feat(multiuser): phase 2, multi-user auth pipeline

Adds a parallel multi-user auth branch (the single-user Basic-auth path is
left byte-identical). Off unless CODEMAN_MULTIUSER/--multiuser.

- middleware/auth.ts: mode-selecting registerAuthMiddleware. New async
  multi-user hook verifies username:password against the user store (scrypt),
  mints identity-carrying cookies, decorates req.authUser, enforces a per-IP
  AND per-username failure bucket, and the mustChangePassword lockbox. The
  hook-secret loopback bypass is now a single shared helper used by both
  branches. FastifyRequest.authUser module augmentation.
- ports/auth-port.ts: AuthSessionRecord gains username/role/mustChangePassword.
- user-store.ts: verifyPassword (timing-equalized against user enumeration).
- route-helpers.ts: getAuthUser (synthetic admin fallback), canAccessOwned,
  requireAdmin, revokeUserSessions; findSessionOrFail gains an optional req for
  a NOT_FOUND owner check (dormant until phase 3 wires callers).
- routes/me-routes.ts: GET /api/me (synthetic admin in single-user) and
  POST /api/me/password (verify current, min 8, clear mustChangePassword,
  revoke other sessions).
- QR: QrTokenRecord + AuthSessionRecord carry a username; tunnel-manager
  mintUserToken / consumeTokenWithIdentity / getQrSvgForCode; /q/:code binds
  the cookie to the token's user (rejects identity-less tokens in multi-user);
  GET /api/tunnel/qr mints a per-user token. Single-user keeps the rotating token.
- server.ts: bootstrap the initial admin from CODEMAN_USERNAME/PASSWORD on first
  boot (refuse to start with no users); multi-user with >= 1 user satisfies the
  non-loopback auth requirement and the tunnel-enable guard; userFailures bucket
  disposal.
- types/api.ts: FORBIDDEN, PASSWORD_CHANGE_REQUIRED, USER_EXISTS, USER_NOT_FOUND,
  LAST_ADMIN error codes (message + status wired).
- Session.owner field + getter/setter, SessionState.owner, MuxSession.owner,
  CreateSessionOptions.owner (foundation for phase 3 ownership threading).

Tests: test/multiuser-auth.test.ts (10, live server on 3170/3171). Existing auth
suite (auth-security, qr-auth, cod54-hook-event, network-auth-policy) unchanged
and green; full test:ci sweep passes (3519 tests).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/web/middleware/auth.ts

@@ -8,7 +8,7 @@
  * - CORS (localhost only)
  */
 
-import type { FastifyInstance, FastifyReply } from 'fastify';
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { StaleExpirationMap } from '../../utils/index.js';
 import type { AuthSessionRecord } from '../ports/auth-port.js';
@@ -20,6 +20,17 @@ import {
   AUTH_FAILURE_WINDOW_MS,
 } from '../../config/auth-config.js';
 import { getHookSecret, HOOK_SECRET_HEADER } from '../../config/hook-secret.js';
+import { isMultiUserMode } from '../../config/multiuser.js';
+import { setPassword, touchLastLogin, verifyPassword } from '../../user-store.js';
+import { ApiErrorCode, createErrorResponse, type AuthUser } from '../../types.js';
+
+// Request-scoped identity (multi-user). Single-user leaves it undefined and the
+// ownership helpers default to a synthetic admin (see route-helpers).
+declare module 'fastify' {
+  interface FastifyRequest {
+    authUser?: AuthUser;
+  }
+}
 
 // Auth session cookie name
 export const AUTH_COOKIE_NAME = 'codeman_session';
@@ -30,6 +41,80 @@ interface AuthState {
   authFailures: StaleExpirationMap<string, number> | null;
   qrAuthFailures: StaleExpirationMap<string, number> | null;
   hookSecretFailures: StaleExpirationMap<string, number> | null;
+  /** Per-username Basic-auth failure bucket (multi-user only). */
+  userFailures: StaleExpirationMap<string, number> | null;
+}
+
+/** Rate-limit response for a client that exceeded the failure cap. */
+function sendAuthRateLimit(reply: FastifyReply, failures: StaleExpirationMap<string, number>, key: string): void {
+  const remainingMs = failures.getRemainingTtl(key) ?? AUTH_FAILURE_WINDOW_MS;
+  const retryAfterSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
+  reply.header('Retry-After', String(retryAfterSeconds));
+  reply.code(429).send('Too Many Requests — try again later');
+}
+
+/** Parse a `Basic base64(user:pass)` header into its parts, or null if malformed. */
+function parseBasicAuth(header?: string): { username: string; password: string } | null {
+  if (!header || !header.startsWith('Basic ')) return null;
+  try {
+    const decoded = Buffer.from(header.slice(6), 'base64').toString('utf-8');
+    const idx = decoded.indexOf(':');
+    if (idx < 0) return null;
+    return { username: decoded.slice(0, idx), password: decoded.slice(idx + 1) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `/api/hook-event` + `/api/status-telemetry` localhost bypass, shared by the
+ * single-user and multi-user auth hooks so the security-critical logic has ONE
+ * source of truth. Returns:
+ *  - 'bypass'   : loopback + valid hook secret; the caller should allow the request
+ *  - 'rejected' : a reply was already sent (wrong secret rate-limited / 401)
+ *  - 'continue' : not a hook request (or non-loopback); fall through to normal auth
+ *
+ * COD-91: the shared hook secret is required UNCONDITIONALLY on the loopback bypass
+ * (a user's own loopback reverse proxy is indistinguishable from a real local hook).
+ */
+function checkHookSecretBypass(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  hookSecretFailures: StaleExpirationMap<string, number>
+): 'bypass' | 'rejected' | 'continue' {
+  if ((req.url === '/api/hook-event' || req.url === '/api/status-telemetry') && req.method === 'POST') {
+    const ip = req.ip;
+    const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+    if (isLoopback) {
+      const presented = Buffer.from(req.headers[HOOK_SECRET_HEADER.toLowerCase()]?.toString() ?? '');
+      const expected = Buffer.from(getHookSecret());
+      if (presented.length === expected.length && timingSafeEqual(presented, expected)) {
+        return 'bypass';
+      }
+      const hookIp = req.ip;
+      const hookFailures = hookSecretFailures.get(hookIp) ?? 0;
+      if (hookFailures >= AUTH_FAILURE_MAX) {
+        sendAuthRateLimit(reply, hookSecretFailures, hookIp);
+        return 'rejected';
+      }
+      hookSecretFailures.set(hookIp, hookFailures + 1);
+      reply.code(401).send('Unauthorized: hook secret required');
+      return 'rejected';
+    }
+    // Non-localhost hook requests fall through to normal auth
+  }
+  return 'continue';
+}
+
+/**
+ * Requests that a `mustChangePassword` user may still reach: the identity probe,
+ * the password-change endpoint, and any non-API path (static assets / index.html,
+ * so the browser can load the app and render the change-password modal).
+ */
+function isPasswordChangeExempt(req: FastifyRequest): boolean {
+  const url = (req.url ?? '').split('?')[0];
+  if (url === '/api/me' || url === '/api/me/password') return true;
+  return !url.startsWith('/api/');
 }
 
 /**
@@ -47,13 +132,20 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
     authFailures: null,
     qrAuthFailures: null,
     hookSecretFailures: null,
+    userFailures: null,
   };
 
-  const authPassword = process.env.CODEMAN_PASSWORD;
-  if (!authPassword) return state;
+  // Always declare req.authUser so downstream reads are safe (single-user leaves it
+  // undefined; the ownership helpers then default to a synthetic admin).
+  if (!app.hasRequestDecorator('authUser')) app.decorateRequest('authUser', undefined);
 
-  const authUsername = process.env.CODEMAN_USERNAME || 'admin';
-  const expectedHeader = 'Basic ' + Buffer.from(`${authUsername}:${authPassword}`).toString('base64');
+  const multiUser = isMultiUserMode();
+  const authPassword = process.env.CODEMAN_PASSWORD;
+
+  // No auth at all: single-user with no password (byte-identical to legacy). In
+  // multi-user mode auth is ALWAYS active (users authenticate individually), even
+  // without CODEMAN_PASSWORD.
+  if (!multiUser && !authPassword) return state;
 
   // Session token store — active sessions extend TTL on access
   state.authSessions = new StaleExpirationMap<string, AuthSessionRecord>({
@@ -87,57 +179,28 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
   const authFailures = state.authFailures;
   const hookSecretFailures = state.hookSecretFailures;
 
-  function sendAuthRateLimit(
-    reply: FastifyReply,
-    clientIp: string,
-    failures: StaleExpirationMap<string, number> = authFailures
-  ): void {
-    const remainingMs = failures.getRemainingTtl(clientIp) ?? AUTH_FAILURE_WINDOW_MS;
-    const retryAfterSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
-    reply.header('Retry-After', String(retryAfterSeconds));
-    reply.code(429).send('Too Many Requests — try again later');
+  if (multiUser) {
+    // Per-username failure bucket: a botnet can't brute-force one account across
+    // many IPs, and one user behind a NAT can't lock out everyone else.
+    state.userFailures = new StaleExpirationMap<string, number>({
+      ttlMs: AUTH_FAILURE_WINDOW_MS,
+      refreshOnGet: false,
+    });
+    registerMultiUserAuthHook(app, https, authSessions, authFailures, hookSecretFailures, state.userFailures);
+    return state;
   }
 
+  // ── Single-user Basic Auth (unchanged behavior; CODEMAN_PASSWORD required) ──
+  const authUsername = process.env.CODEMAN_USERNAME || 'admin';
+  const expectedHeader = 'Basic ' + Buffer.from(`${authUsername}:${authPassword}`).toString('base64');
+
   app.addHook('onRequest', (req, reply, done) => {
-    // Hook events + statusline telemetry come from local Claude Code (curl from
-    // localhost) — no Basic-Auth credentials available. Validated downstream by
-    // HookEventSchema / StatusTelemetrySchema. Same loopback+hook-secret gate.
-    //
-    // COD-54: the bare localhost bypass is unsafe while a tunnel is running, because
-    // `cloudflared --url http://127.0.0.1:port` proxies internet traffic INTO the
-    // loopback origin, so a tunneled request arrives with req.ip === 127.0.0.1 and
-    // would pass. COD-91: require the shared hook secret on the loopback bypass
-    // UNCONDITIONALLY (not just while the managed tunnel is up). Codeman can't detect
-    // a user's own loopback reverse proxy (their own `cloudflared --url`, `tailscale
-    // serve`, nginx → 127.0.0.1), so tunnel-gating left that path with the unsafe plain
-    // bypass. Managed-session hooks always present the secret (X-Codeman-Hook-Secret,
-    // from $CODEMAN_HOOK_SECRET_FILE — generated for every instance), so requiring it
-    // always closes the gap without breaking the legitimate hook channel.
-    if ((req.url === '/api/hook-event' || req.url === '/api/status-telemetry') && req.method === 'POST') {
-      const ip = req.ip;
-      const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
-      if (isLoopback) {
-        // Always require the shared secret (constant-time compare).
-        const presented = Buffer.from(req.headers[HOOK_SECRET_HEADER.toLowerCase()]?.toString() ?? '');
-        const expected = Buffer.from(getHookSecret());
-        if (presented.length === expected.length && timingSafeEqual(presented, expected)) {
-          done();
-          return;
-        }
-        // Wrong/absent secret — rate-limit per IP in the DEDICATED hook bucket
-        // (never authFailures, which would lock out the login path).
-        const hookIp = req.ip;
-        const hookFailures = hookSecretFailures.get(hookIp) ?? 0;
-        if (hookFailures >= AUTH_FAILURE_MAX) {
-          sendAuthRateLimit(reply, hookIp, hookSecretFailures);
-          return;
-        }
-        hookSecretFailures.set(hookIp, hookFailures + 1);
-        reply.code(401).send('Unauthorized: hook secret required');
-        return;
-      }
-      // Non-localhost hook requests fall through to normal auth
+    const bypass = checkHookSecretBypass(req, reply, hookSecretFailures);
+    if (bypass === 'bypass') {
+      done();
+      return;
     }
+    if (bypass === 'rejected') return;
 
     // QR auth path — handled by the route itself (token validation + rate limiting)
     if (req.url?.startsWith('/q/')) {
@@ -153,10 +216,6 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
     if (sessionToken && authSessions.get(sessionToken) !== undefined) {
       // Sliding cookie: re-issue on every authenticated request so the browser
       // cookie lifetime tracks the server-side sliding TTL (refreshOnGet above).
-      // Without this the cookie has a fixed lifetime from login; the browser
-      // drops it mid-use, the next request arrives cookie-less and falls through
-      // to Basic Auth — popping the native username/password dialog, which reads
-      // as a random logout while actively working.
       reply.setCookie(AUTH_COOKIE_NAME, sessionToken, {
         httpOnly: true,
         secure: https,
@@ -206,7 +265,7 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
     // Rate limit only requests that failed to authenticate on this attempt.
     const failures = authFailures.get(clientIp) ?? 0;
     if (failures >= AUTH_FAILURE_MAX) {
-      sendAuthRateLimit(reply, clientIp);
+      sendAuthRateLimit(reply, authFailures, clientIp);
       return;
     }
 
@@ -220,6 +279,124 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
   return state;
 }
 
+/**
+ * Multi-user auth hook (async, because password verification runs scrypt). Verifies
+ * `username:password` against the user store, mints an identity-carrying cookie,
+ * decorates `req.authUser`, enforces the per-IP + per-username rate limits, and the
+ * `mustChangePassword` lockbox. The single-user hook above is left untouched.
+ */
+function registerMultiUserAuthHook(
+  app: FastifyInstance,
+  https: boolean,
+  authSessions: StaleExpirationMap<string, AuthSessionRecord>,
+  authFailures: StaleExpirationMap<string, number>,
+  hookSecretFailures: StaleExpirationMap<string, number>,
+  userFailures: StaleExpirationMap<string, number>
+): void {
+  const setSessionCookie = (reply: FastifyReply, token: string) =>
+    reply.setCookie(AUTH_COOKIE_NAME, token, {
+      httpOnly: true,
+      secure: https,
+      sameSite: 'lax',
+      maxAge: AUTH_SESSION_TTL_MS / 1000,
+      path: '/',
+    });
+
+  // Evict the oldest cookie session of the SAME user first (so one user logging in
+  // 100 times cannot flush everyone else's sessions), falling back to global-oldest.
+  const evictForCapacity = (username: string) => {
+    let userKey: string | undefined;
+    let userTs = Infinity;
+    let globalKey: string | undefined;
+    let globalTs = Infinity;
+    for (const [k, v] of authSessions) {
+      if (v.createdAt < globalTs) {
+        globalTs = v.createdAt;
+        globalKey = k;
+      }
+      if (v.username === username && v.createdAt < userTs) {
+        userTs = v.createdAt;
+        userKey = k;
+      }
+    }
+    const key = userKey ?? globalKey;
+    if (key !== undefined) authSessions.delete(key);
+  };
+
+  const enforcePasswordChange = (req: FastifyRequest, reply: FastifyReply, mustChange: boolean): boolean => {
+    if (mustChange && !isPasswordChangeExempt(req)) {
+      reply.code(403).send(createErrorResponse(ApiErrorCode.PASSWORD_CHANGE_REQUIRED));
+      return true;
+    }
+    return false;
+  };
+
+  app.addHook('onRequest', async (req, reply) => {
+    const bypass = checkHookSecretBypass(req, reply, hookSecretFailures);
+    if (bypass === 'bypass' || bypass === 'rejected') return;
+
+    // QR redemption path — handled by the route itself.
+    if (req.url?.startsWith('/q/')) return;
+
+    const clientIp = req.ip;
+
+    // 1. Cookie session (carries identity + mustChangePassword snapshot).
+    const sessionToken = req.cookies[AUTH_COOKIE_NAME];
+    const record = sessionToken ? authSessions.get(sessionToken) : undefined;
+    if (record && record.username) {
+      req.authUser = { username: record.username, role: record.role ?? 'user' };
+      setSessionCookie(reply, sessionToken!); // sliding re-issue
+      enforcePasswordChange(req, reply, !!record.mustChangePassword);
+      return;
+    }
+
+    // 2. Basic Auth against the user store (scrypt verify).
+    const ipFail = authFailures.get(clientIp) ?? 0;
+    if (ipFail >= AUTH_FAILURE_MAX) {
+      sendAuthRateLimit(reply, authFailures, clientIp);
+      return;
+    }
+    const creds = parseBasicAuth(req.headers.authorization);
+    if (creds) {
+      const normUser = creds.username.trim().toLowerCase();
+      const uFail = userFailures.get(normUser) ?? 0;
+      if (uFail >= AUTH_FAILURE_MAX) {
+        sendAuthRateLimit(reply, userFailures, normUser);
+        return;
+      }
+      const result = await verifyPassword(creds.username, creds.password);
+      if (result) {
+        const { user, needsRehash: rehash } = result;
+        if (rehash) void setPassword(user.username, creds.password).catch(() => {});
+        void touchLastLogin(user.username).catch(() => {});
+        authFailures.delete(clientIp);
+        userFailures.delete(normUser);
+
+        const token = randomBytes(32).toString('hex');
+        if (authSessions.size >= MAX_AUTH_SESSIONS) evictForCapacity(user.username);
+        authSessions.set(token, {
+          ip: clientIp,
+          ua: req.headers['user-agent'] ?? '',
+          createdAt: Date.now(),
+          method: 'basic',
+          username: user.username,
+          role: user.role,
+          mustChangePassword: !!user.mustChangePassword,
+        });
+        req.authUser = { username: user.username, role: user.role };
+        setSessionCookie(reply, token);
+        enforcePasswordChange(req, reply, !!user.mustChangePassword);
+        return;
+      }
+      userFailures.set(normUser, uFail + 1);
+    }
+
+    authFailures.set(clientIp, ipFail + 1);
+    reply.header('WWW-Authenticate', 'Basic realm="Codeman"');
+    reply.code(401).send('Unauthorized');
+  });
+}
+
 /** Methods that don't change server state and so skip the cross-site Origin check. */
 const SAFE_HTTP_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 

src/web/ports/auth-port.ts

@@ -11,6 +11,16 @@ export interface AuthSessionRecord {
   ua: string;
   createdAt: number;
   method: 'qr' | 'basic';
+  /**
+   * Multi-user identity carried by the cookie (single-user leaves these unset).
+   * Snapshotted at mint time; state transitions that would change them (password
+   * reset, disable, delete) revoke the user's sessions so a stale snapshot can't
+   * outlive the change. See docs/multi-user-plan.md section 5.
+   */
+  username?: string;
+  role?: 'admin' | 'user';
+  /** Whether this user must change their password before other actions are allowed. */
+  mustChangePassword?: boolean;
 }
 
 export interface AuthPort {

src/web/route-helpers.ts

@@ -10,13 +10,18 @@ import { realpathSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import { homedir } from 'node:os';
 import type { z } from 'zod';
+import type { FastifyReply, FastifyRequest } from 'fastify';
 import { Session } from '../session.js';
-import { ApiErrorCode, createErrorResponse } from '../types.js';
+import { ApiErrorCode, createErrorResponse, type AuthUser } from '../types.js';
 import { parseRalphLoopConfig, extractCompletionPhrase } from '../ralph-config.js';
 import { SseEvent } from './sse-events.js';
 import type { SessionPort } from './ports/session-port.js';
 import type { EventPort } from './ports/event-port.js';
+import type { AuthSessionRecord } from './ports/auth-port.js';
+import type { StaleExpirationMap } from '../utils/index.js';
 import { dataPath } from '../config/instance.js';
+import { isMultiUserMode } from '../config/multiuser.js';
+import { SYNTHETIC_ADMIN } from '../user-store.js';
 
 // Shared path constants used across route modules. CASES_DIR (project folders)
 // stays shared across instances; SETTINGS_PATH is per-instance runtime state.
@@ -79,13 +84,69 @@ export function validateSessionFilePath(
 // Maximum hook data size (prevents oversized SSE broadcasts)
 const MAX_HOOK_DATA_SIZE = 8 * 1024;
 
+/**
+ * Effective identity for a request. In multi-user mode this is the auth-decorated
+ * user; in single-user mode (or when unset) it defaults to a synthetic admin so
+ * downstream ownership checks are no-ops and there is ONE code path.
+ */
+export function getAuthUser(req: FastifyRequest): AuthUser {
+  return req.authUser ?? SYNTHETIC_ADMIN;
+}
+
+/**
+ * Whether an identity may see/act on a resource with the given owner. Always true
+ * in single-user mode; in multi-user, admins see everything and regular users only
+ * their own (an absent owner is legacy/unassigned = admin-only).
+ */
+export function canAccessOwned(user: AuthUser, owner: string | undefined): boolean {
+  if (!isMultiUserMode()) return true;
+  if (user.role === 'admin') return true;
+  return !!owner && owner === user.username;
+}
+
+/**
+ * First line of admin-only handlers: 403 FORBIDDEN + returns false when the caller
+ * is not an admin. Always true in single-user mode (the sole user is the admin).
+ */
+export function requireAdmin(req: FastifyRequest, reply: FastifyReply): boolean {
+  if (!isMultiUserMode()) return true;
+  if (getAuthUser(req).role === 'admin') return true;
+  reply.code(403).send(createErrorResponse(ApiErrorCode.FORBIDDEN));
+  return false;
+}
+
+/**
+ * Revoke every cookie session belonging to a user (optionally keeping one token,
+ * e.g. the caller's own during a self-service password change). Returns the count.
+ */
+export function revokeUserSessions(
+  authSessions: StaleExpirationMap<string, AuthSessionRecord> | null,
+  username: string,
+  exceptToken?: string
+): number {
+  if (!authSessions) return 0;
+  const norm = username.trim().toLowerCase();
+  let removed = 0;
+  for (const [token, record] of authSessions) {
+    if (record.username === norm && token !== exceptToken) {
+      authSessions.delete(token);
+      removed++;
+    }
+  }
+  return removed;
+}
+
 /**
  * Look up a session by ID or throw a structured error.
  * Replaces the pattern: `const session = sessions.get(id); if (!session) return createErrorResponse(...)`.
+ *
+ * When `req` is passed in multi-user mode, a session the caller does not own is
+ * reported as NOT_FOUND (never 403), so existence of other users' sessions is not
+ * leaked. Single-user / admin callers are unaffected.
  */
-export function findSessionOrFail(ctx: SessionPort, sessionId: string): Session {
+export function findSessionOrFail(ctx: SessionPort, sessionId: string, req?: FastifyRequest): Session {
   const session = ctx.sessions.get(sessionId);
-  if (!session) {
+  if (!session || (req && !canAccessOwned(getAuthUser(req), session.owner))) {
     throw Object.assign(new Error(`Session ${sessionId} not found`), {
       statusCode: 404,
       body: createErrorResponse(ApiErrorCode.NOT_FOUND, `Session ${sessionId} not found`),

src/web/routes/index.ts

@@ -19,4 +19,5 @@ export { registerPlanRoutes } from './plan-routes.js';
 export { registerOrchestratorRoutes } from './orchestrator-routes.js';
 export { registerClipboardRoutes } from './clipboard-routes.js';
 export { registerSearchRoutes } from './search-routes.js';
+export { registerMeRoutes } from './me-routes.js';
 export { registerWsRoutes } from './ws-routes.js';

src/web/routes/me-routes.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Self-service identity routes (multi-user + single-user).
+ *
+ * - GET  /api/me            : who am I ({ username, role, mustChangePassword }).
+ *                             Works in single-user mode too, returning the synthetic
+ *                             admin so the frontend has one "am I admin" code path.
+ * - POST /api/me/password   : change my own password (verifies the current one,
+ *                             clears mustChangePassword, revokes my OTHER sessions).
+ *
+ * These are the two endpoints a `mustChangePassword` user may still reach (the auth
+ * middleware's lockbox exempts them). See docs/multi-user-plan.md sections 5, 8.
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import { ApiErrorCode, createErrorResponse } from '../../types.js';
+import { isMultiUserMode } from '../../config/multiuser.js';
+import { findUser, setPassword, verifyPassword } from '../../user-store.js';
+import { getAuthUser, revokeUserSessions } from '../route-helpers.js';
+import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
+import type { AuthPort } from '../ports/auth-port.js';
+
+const PasswordChangeSchema = z.object({
+  currentPassword: z.string().min(1).max(1024),
+  newPassword: z.string().min(8).max(1024),
+});
+
+export function registerMeRoutes(app: FastifyInstance, ctx: AuthPort): void {
+  // GET /api/me — identity probe. Synthetic admin in single-user mode.
+  app.get('/api/me', async (req) => {
+    if (!isMultiUserMode()) {
+      return { success: true, data: { username: 'admin', role: 'admin', mustChangePassword: false } };
+    }
+    const user = getAuthUser(req);
+    const record = await findUser(user.username);
+    return {
+      success: true,
+      data: {
+        username: user.username,
+        role: user.role,
+        mustChangePassword: !!record?.mustChangePassword,
+      },
+    };
+  });
+
+  // POST /api/me/password — self-service password change.
+  app.post('/api/me/password', async (req, reply) => {
+    if (!isMultiUserMode()) {
+      reply.code(404);
+      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Multi-user mode is not enabled');
+    }
+    const parsed = PasswordChangeSchema.safeParse(req.body);
+    if (!parsed.success) {
+      reply.code(400);
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        parsed.error.issues[0]?.message ?? 'New password must be at least 8 characters'
+      );
+    }
+    const { username } = getAuthUser(req);
+    const verified = await verifyPassword(username, parsed.data.currentPassword);
+    if (!verified) {
+      reply.code(403);
+      return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Current password is incorrect');
+    }
+    await setPassword(username, parsed.data.newPassword, { mustChangePassword: false });
+
+    // Revoke this user's OTHER cookie sessions; keep the caller's own session alive
+    // and clear its mustChangePassword snapshot so they aren't re-locked immediately.
+    const currentToken = req.cookies[AUTH_COOKIE_NAME];
+    revokeUserSessions(ctx.authSessions, username, currentToken);
+    if (currentToken) {
+      const rec = ctx.authSessions?.get(currentToken);
+      if (rec) rec.mustChangePassword = false;
+    }
+    return { success: true };
+  });
+}

src/web/routes/system-routes.ts

@@ -15,6 +15,9 @@ import { randomBytes } from 'node:crypto';
 import { dataPath } from '../../config/instance.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, type NiceConfig } from '../../types.js';
 import { isUnauthenticatedNetworkAcknowledged } from '../network-auth-policy.js';
+import { isMultiUserMode } from '../../config/multiuser.js';
+import { findUser } from '../../user-store.js';
+import { getAuthUser } from '../route-helpers.js';
 import {
   ConfigUpdateSchema,
   SettingsUpdateSchema,
@@ -159,12 +162,19 @@ export function registerSystemRoutes(
     };
   });
 
-  app.get('/api/tunnel/qr', async (_req, reply) => {
+  app.get('/api/tunnel/qr', async (req, reply) => {
     const url = ctx.tunnelManager.getUrl();
     if (!url) {
       return reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Tunnel not running'));
     }
     try {
+      if (isMultiUserMode()) {
+        // A rotating global token cannot carry identity — mint a single-use token
+        // bound to the requesting user so the scanned code logs THEM in.
+        const shortCode = ctx.tunnelManager.mintUserToken(getAuthUser(req).username);
+        const svg = await ctx.tunnelManager.getQrSvgForCode(url, shortCode);
+        return { svg, authEnabled: true };
+      }
       const authPassword = process.env.CODEMAN_PASSWORD;
       if (authPassword) {
         // Auth enabled — use cached SVG with embedded short code
@@ -188,10 +198,11 @@ export function registerSystemRoutes(
 
   app.get('/q/:code', async (req, reply) => {
     const shortCode = (req.params as { code: string }).code;
+    const multiUser = isMultiUserMode();
     const authPassword = process.env.CODEMAN_PASSWORD;
 
-    // No point if auth isn't enabled — just redirect
-    if (!authPassword) {
+    // No point if auth isn't enabled — just redirect. Multi-user is always "enabled".
+    if (!multiUser && !authPassword) {
       return reply.redirect('/');
     }
 
@@ -203,12 +214,26 @@ export function registerSystemRoutes(
       return reply.code(429).send('Too Many Requests');
     }
 
-    // Validate and atomically consume the token
-    if (!shortCode || !ctx.tunnelManager.consumeToken(shortCode)) {
+    // Validate and atomically consume the token (with any bound identity).
+    const consumed = shortCode ? ctx.tunnelManager.consumeTokenWithIdentity(shortCode) : { ok: false };
+    // In multi-user mode a token MUST carry an identity (an identity-less rotating
+    // token can't create a scoped session), so reject those too.
+    if (!consumed.ok || (multiUser && !consumed.username)) {
       ctx.qrAuthFailures?.set(clientIp, qrFailures + 1);
       return reply.code(401).send('Invalid or expired QR code');
     }
 
+    // Resolve the role for the bound user (disabled/deleted users fail closed).
+    let identity: { username: string; role: 'admin' | 'user' } | undefined;
+    if (multiUser && consumed.username) {
+      const user = await findUser(consumed.username);
+      if (!user || user.disabled) {
+        ctx.qrAuthFailures?.set(clientIp, qrFailures + 1);
+        return reply.code(401).send('Invalid or expired QR code');
+      }
+      identity = { username: user.username, role: user.role };
+    }
+
     // Issue session cookie (same pattern as Basic Auth success path)
     const sessionToken = randomBytes(32).toString('hex');
     const clientUA = req.headers['user-agent'] ?? '';
@@ -217,6 +242,9 @@ export function registerSystemRoutes(
       ua: clientUA,
       createdAt: Date.now(),
       method: 'qr',
+      username: identity?.username,
+      role: identity?.role,
+      mustChangePassword: false,
     });
     ctx.qrAuthFailures?.delete(clientIp);
 
@@ -585,7 +613,10 @@ export function registerSystemRoutes(
     // letting an operator opt in from the browser without setting the env var.
     // Guard runs BEFORE persisting so a refused tunnelEnabled:true is not saved.
     if (settings.tunnelEnabled === true && !ctx.tunnelManager.isRunning()) {
-      const acknowledged = isUnauthenticatedNetworkAcknowledged() || settings.acknowledgeUnauthTunnel === true;
+      // Multi-user mode makes the tunnel authenticated (every person has their own
+      // credential), so it satisfies the same requirement as CODEMAN_PASSWORD.
+      const acknowledged =
+        isMultiUserMode() || isUnauthenticatedNetworkAcknowledged() || settings.acknowledgeUnauthTunnel === true;
       if (!acknowledged) {
         const msg =
           'Refusing to start the Cloudflare tunnel without authentication: it would publish ' +

src/web/server.ts

@@ -135,6 +135,8 @@ import { SseEvent } from './sse-events.js';
 import { getLatestPlanUsage } from './plan-usage-latest.js';
 import type { ScheduledRun } from './ports/index.js';
 import { registerAuthMiddleware, registerSecurityHeaders, registerHostGuard } from './middleware/auth.js';
+import { isMultiUserMode } from '../config/multiuser.js';
+import { bootstrapInitialAdmin, hasUsers } from '../user-store.js';
 import { installRouteErrorHandler } from './route-error-handler.js';
 import { isExplicitlyEnabled, isLoopbackBindHost, buildHostPolicy, type HostPolicy } from './network-auth-policy.js';
 import {
@@ -155,6 +157,7 @@ import {
   registerSearchRoutes,
   registerOrchestratorRoutes,
   registerCronRoutes,
+  registerMeRoutes,
   registerWsRoutes,
 } from './routes/index.js';
 import { CronService } from '../cron/cron-service.js';
@@ -279,6 +282,7 @@ export class WebServer extends EventEmitter {
   private authFailures: StaleExpirationMap<string, number> | null = null;
   private qrAuthFailures: StaleExpirationMap<string, number> | null = null;
   private hookSecretFailures: StaleExpirationMap<string, number> | null = null;
+  private userFailures: StaleExpirationMap<string, number> | null = null;
   private pushStore: PushSubscriptionStore = new PushSubscriptionStore();
   private teamWatcher: TeamWatcher = new TeamWatcher();
   private _orchestratorLoop: import('../orchestrator-loop.js').OrchestratorLoop | null = null;
@@ -680,6 +684,7 @@ export class WebServer extends EventEmitter {
       this.authFailures = authState.authFailures;
       this.qrAuthFailures = authState.qrAuthFailures;
       this.hookSecretFailures = authState.hookSecretFailures;
+      this.userFailures = authState.userFailures;
     }
 
     // WebSocket support (terminal I/O — low-latency bidirectional channel)
@@ -899,6 +904,7 @@ export class WebServer extends EventEmitter {
     registerPlanRoutes(this.app, ctx);
     registerClipboardRoutes(this.app, ctx);
     registerSearchRoutes(this.app, ctx);
+    registerMeRoutes(this.app, ctx);
     registerOrchestratorRoutes(this.app, ctx);
 
     // Cron: build the service from the same context, recompute
@@ -1930,6 +1936,24 @@ export class WebServer extends EventEmitter {
   }
 
   async start(): Promise<void> {
+    // Multi-user first boot: create the initial admin from CODEMAN_USERNAME/PASSWORD
+    // if there are no users yet, else refuse to start (there would be no way in).
+    if (isMultiUserMode() && !this.testMode) {
+      const boot = await bootstrapInitialAdmin();
+      if (boot.status === 'missing-env') {
+        throw new Error(
+          'Multi-user mode is enabled but users.json has no users. Create the first admin with ' +
+            '`codeman users add <name> --admin` (or set CODEMAN_USERNAME/CODEMAN_PASSWORD for one-time bootstrap).'
+        );
+      }
+      if (boot.status === 'created') {
+        console.log(
+          `✓ Multi-user: bootstrapped initial admin "${boot.username}" from CODEMAN_USERNAME/CODEMAN_PASSWORD`
+        );
+      }
+      console.log('✓ Multi-user mode active (per-user accounts in users.json; CODEMAN_PASSWORD is ignored for login)');
+    }
+
     await this.setupRoutes();
 
     const lifecycleLog = getLifecycleLog();
@@ -2006,7 +2030,10 @@ export class WebServer extends EventEmitter {
     // "just worked" before. Instead we start and warn loudly, pointing at the ways
     // to secure it. --allow-unauthenticated-network just acknowledges the risk (a
     // terser note). See docs/security-architecture.md.
-    if (!isLoopbackBindHost(this.host) && !process.env.CODEMAN_PASSWORD) {
+    // Multi-user mode with >= 1 enabled user satisfies the auth requirement even
+    // without CODEMAN_PASSWORD (every person has their own credential).
+    const authActive = !!process.env.CODEMAN_PASSWORD || (isMultiUserMode() && (await hasUsers()));
+    if (!isLoopbackBindHost(this.host) && !authActive) {
       if (this.allowUnauthenticatedNetwork) {
         console.warn(
           `\n⚠  Codeman is reachable WITHOUT a password on ${displayHost}:${this.port} ` +
@@ -2637,6 +2664,10 @@ export class WebServer extends EventEmitter {
       this.hookSecretFailures.dispose();
       this.hookSecretFailures = null;
     }
+    if (this.userFailures) {
+      this.userFailures.dispose();
+      this.userFailures = null;
+    }
     this.activePlanOrchestrators.clear();
     this.cleaningUp.clear();