#Token auth

The token strategy of @worker-manager/auth protects the dashboard with one or more static tokens, with no usernames and no identity provider. Scripts send the token in a header; a browser types it once into a small login form and gets an encrypted session cookie. It suits internal boards where a Keycloak realm is overkill and a shared Basic password is not wanted in the browser's credential cache.

npm install @worker-manager/auth

#Options

Use long random tokens (32 characters or more): there is no lockout, so the token's entropy is the only defence against guessing. openssl rand -base64 32 is plenty.

#NestJS

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { WorkerManagerModule } from '@worker-manager/nestjs';
import { BullMQAdapter } from '@worker-manager/api/bullMQAdapter';

@Module({
  imports: [
    WorkerManagerModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        route: '/admin/queues',
        auth: {
          strategy: 'token',
          tokens: [config.getOrThrow('BOARD_TOKEN')],
          header: 'X-Board-Token',
          cookie: { secret: config.getOrThrow('BOARD_SESSION_SECRET') },
        },
      }),
    }),
    WorkerManagerModule.forFeature({ name: 'emails', adapter: BullMQAdapter }),
  ],
})
export class AppModule {}

#Express

import { createAuthMiddleware } from '@worker-manager/auth';

const auth = createAuthMiddleware(
  {
    strategy: 'token',
    tokens: [process.env.BOARD_TOKEN!],
    cookie: { secret: process.env.BOARD_SESSION_SECRET! },
  },
  { basePath: '/queues' }
);

app.use('/queues', auth, serverAdapter.getRouter());

#Fastify

import { createAuthMiddleware, createFastifyAuthPlugin } from '@worker-manager/auth';

const auth = createAuthMiddleware(tokenOptions, { basePath: '/queues' });
app.register(createFastifyAuthPlugin(serverAdapter.registerPlugin(), auth), { prefix: '/queues' });

The plugin registers the POST /auth/login route the form needs inside the board's own scope.

#CLI and Docker

worker-manager --token "$BOARD_TOKEN" --token-header X-Board-Token \
  --session-secret "$BOARD_SESSION_SECRET" --host 0.0.0.0

--token takes a comma separated list. The environment variables are WORKER_MANAGER_TOKENS, WORKER_MANAGER_TOKEN_HEADER and WORKER_MANAGER_SESSION_SECRET, and a config file takes token: { tokens, header, user, cookie }. Without a session secret the CLI encrypts sessions with a random per-process key, so they end on restart.

#What happens to a request

The middleware also serves, under the board's base path, when cookie is set:

• GET /auth/login renders the form: one password field, no scripts, no external assets, a strict Content-Security-Policy and X-Frame-Options: DENY.
• POST /auth/login checks the token and, on success, sets the session cookie and answers 303 to returnTo (same-origin paths only). A wrong token re-renders the form with 401; the token is never echoed back.
• GET /auth/logout clears the cookie and returns to the form.
• GET /auth/me returns { strategy: 'token', user, logoutUrl }, as for the other strategies.

#Security notes

• The session cookie (wm_session by default, wm_session_<name> for a named NestJS board) is HttpOnly, SameSite=Strict, scoped to the base path, Secure on https, and sealed with AES-256-GCM under cookie.secret. It carries the token and an expiry; nothing in it is readable client side, and a tampered or foreign cookie is cleared.
• CSRF on the login form: the POST is only accepted when Origin (or, without it, Referer) is the board's own origin, and a Sec-Fetch-Site other than same-origin is refused, so another site cannot log a browser into a session of its choosing. Together with SameSite=Strict, no cross-site request carries the session either.
• Links from other sites: a SameSite=Strict cookie is withheld from a navigation that starts on another site, such as a link in chat. Such a page load gets a tiny page that reloads itself from the board's origin, which does carry the cookie, so a signed-in user is not asked again.
• No secrets in logs: the middleware logs nothing, and neither tokens nor the session secret appear in any response.

Rate-limit POST ${basePath}/auth/login at your proxy if the board is reachable from the internet.