@cyberismo/backend 1.1.2 → 1.3.0

package/dist/utils.js

@@ -1,57 +1,32 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2025
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 import path from 'node:path';
-import { createServer } from 'node:net';
+import { serve } from '@hono/node-server';
 /**
  * The relative path to the static frontend directory.
  */
 export const staticFrontendDirRelative = path.relative(process.cwd(), path.resolve(import.meta.dirname, 'public'));
 /**
- * Finds a free port.
- * @param port - The port to start looking for.
- * @param maxAttempts - The maximum number of attempts to find a free port.
- * @returns The free port.
+ * Starts the server, moving to the next port while the current one is taken.
+ * The bind itself is the check, so a port can't be taken between check and use.
+ * @param fetch - Request handler.
+ * @param port - The first port to try.
+ * @param host - The host to bind.
+ * @param maxPort - The last port to try; defaults to `port` (no retry).
+ * @returns The listening server and the port it bound.
  */
-export async function findFreePort(minPort, maxPort) {
-    for (let i = minPort; i < maxPort; i++) {
-        try {
-            await testPort(i);
-            return i;
-        }
-        catch (err) {
-            if (err instanceof Error && err.message.includes('EADDRINUSE')) {
-                console.log(`Port ${i} is already in use, trying next port...`);
+export function listen(fetch, port, host, maxPort = port) {
+    return new Promise((resolve, reject) => {
+        const server = serve({ fetch, port, hostname: host }, (info) => resolve({ server, port: info.port }));
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE' && port < maxPort) {
+                console.log(`Port ${port} is already in use, trying next port...`);
+                resolve(listen(fetch, port + 1, host, maxPort));
             }
             else {
-                throw err;
+                reject(err);
             }
-        }
-    }
-    throw new Error('Failed to find free port');
-}
-function testPort(port) {
-    return new Promise((resolve, reject) => {
-        const server = createServer();
-        server.listen(port, () => {
-            server.close();
-            resolve(true);
-        });
-        server.on('error', (err) => {
-            reject(err);
         });
-        setTimeout(() => {
-            reject(new Error('Timed out waiting for port to be free'));
-        }, 2000);
     });
 }
 export function gitOptionsFromEnv() {

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;EAWE;AACF,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC,QAAQ,CACpD,OAAO,CAAC,GAAG,EAAE,EACb,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAC5C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,OAAe;IAEf,KAAK,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;YAClB,OAAO,CAAC,CAAC;QACX,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC/D,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,yCAAyC,CAAC,CAAC;YAClE,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;YACvB,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACzB,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QACH,UAAU,CAAC,GAAG,EAAE;YACd,MAAM,CAAC,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC,CAAC;QAC7D,CAAC,EAAE,IAAI,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB;IAI/B,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,MAAM;QACvD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM;KACpD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,yCAAyC;AAEzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAmB,MAAM,mBAAmB,CAAC;AAE3D;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC,QAAQ,CACpD,OAAO,CAAC,GAAG,EAAE,EACb,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAC5C,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CACpB,KAA2C,EAC3C,IAAY,EACZ,IAAY,EACZ,UAAkB,IAAI;IAEtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CAC7D,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CACrC,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;YAClD,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,GAAG,OAAO,EAAE,CAAC;gBAChD,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,yCAAyC,CAAC,CAAC;gBACnE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB;IAI/B,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,MAAM;QACvD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM;KACpD,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cyberismo/backend",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Express backend for Cyberismo",
   "main": "dist/index.js",
   "keywords": [],
   "author": "sami.merila@cyberismo.com",
-  "license": "AGPL-3.0",
+  "license": "AGPL-3.0-only",
   "homepage": "https://github.com/CyberismoCom/cyberismo",
   "repository": {
     "type": "git",
@@ -16,20 +16,20 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@asciidoctor/core": "^4.0.6",
-    "@hono/mcp": "^0.3.1",
-    "@hono/node-server": "^2.0.12",
-    "@hono/zod-validator": "^0.9.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@cyberismo/assets": "1.3.0",
+    "@cyberismo/data-handler": "1.3.0",
+    "@cyberismo/mcp": "1.3.0",
+    "@cyberismo/model": "1.2.0",
+    "@hono/mcp": "^0.3.5",
+    "@hono/node-server": "^2.1.5",
+    "@hono/zod-validator": "^0.9.1",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@types/mime-types": "^3.0.1",
-    "dotenv": "^17.3.1",
-    "hono": "^4.12.32",
-    "jose": "^6.2.5",
+    "dotenv": "^18.0.9",
+    "hono": "^4.13.14",
+    "jose": "^6.2.14",
     "mime-types": "^3.0.2",
-    "zod": "^4.3.6",
-    "@cyberismo/assets": "1.1.2",
-    "@cyberismo/data-handler": "1.1.2",
-    "@cyberismo/mcp": "1.1.2"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@cyberismo/app": "0.0.2"

package/src/app.ts

@@ -1,28 +1,22 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2025
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
 import { Hono, type MiddlewareHandler } from 'hono';
-import { gitOptionsFromEnv, staticFrontendDirRelative } from './utils.js';
+import { staticFrontendDirRelative } from './utils.js';
 import { serveStatic } from '@hono/node-server/serve-static';
-import { attachProjectRegistry } from './middleware/commandManager.js';
+import { attachProjectDirectory } from './middleware/commandManager.js';
+import { errorResponse } from './common/errors.js';
 import calculationsRouter from './domain/calculations/index.js';
 import cardsRouter from './domain/cards/index.js';
 import cardTypesRouter from './domain/cardTypes/index.js';
 import connectorsRouter from './domain/connectors/index.js';
+import eventsRouter from './domain/events/index.js';
 import fieldTypesRouter from './domain/fieldTypes/index.js';
 import graphModelsRouter from './domain/graphModels/index.js';
 import graphViewsRouter from './domain/graphViews/index.js';
 import linkTypesRouter from './domain/linkTypes/index.js';
 import reportsRouter from './domain/reports/index.js';
+import skillsRouter from './domain/skills/index.js';
 import templatesRouter from './domain/templates/index.js';
 import treeRouter from './domain/tree/index.js';
 import workflowsRouter from './domain/workflows/index.js';
@@ -38,12 +32,13 @@ import type { AppVars, TreeOptions } from './types.js';
 import treeMiddleware from './middleware/tree.js';
 import projectRouter from './domain/project/index.js';
 import { createMcpRouter } from './domain/mcp/index.js';
+import { writableProjects } from './overlay.js';
 import { createAuthRouter } from './domain/auth/index.js';
 import { createAuthMiddleware } from './middleware/auth.js';
 import type { AuthProvider } from './auth/types.js';
-import { MockAuthProvider, mockRoleCookieMiddleware } from './auth/mock.js';
-import type { ProjectRegistry } from './project-registry.js';
-import { CommandManager, scanForProjects } from '@cyberismo/data-handler';
+import { MockAuthProvider } from './auth/mock.js';
+import type { ProjectDirectory } from '@cyberismo/data-handler';
+import { EventsByProject } from './domain/events/events-by-project.js';
 import { createProjectsRouter } from './domain/projects/index.js';
 import { simpleMcpAuthRouter } from '@hono/mcp';
 
@@ -59,11 +54,13 @@ function createProjectScopedRoutes(
   projectScoped.route('/cards', cardsRouter);
   projectScoped.route('/cardTypes', cardTypesRouter);
   projectScoped.route('/connectors', connectorsRouter);
+  projectScoped.route('/events', eventsRouter);
   projectScoped.route('/fieldTypes', fieldTypesRouter);
   projectScoped.route('/graphModels', graphModelsRouter);
   projectScoped.route('/graphViews', graphViewsRouter);
   projectScoped.route('/linkTypes', linkTypesRouter);
   projectScoped.route('/reports', reportsRouter);
+  projectScoped.route('/skills', skillsRouter);
   projectScoped.route('/templates', templatesRouter);
   projectScoped.route('/tree', treeRouter);
   projectScoped.route('/workflows', workflowsRouter);
@@ -77,16 +74,20 @@ function createProjectScopedRoutes(
 /**
  * Create the Hono app for the backend
  * @param authProvider - Authentication provider
- * @param registry - ProjectRegistry holding all project CommandManagers
+ * @param directory - Directory the projects are opened from
+ * @param exportPrefixes - The projects a static export serves; set only in
+ *   export mode
  */
 export function createApp(
   authProvider: AuthProvider,
-  registry: ProjectRegistry,
+  directory: ProjectDirectory,
   opts?: TreeOptions,
-  exportMode = false,
+  exportPrefixes?: string[],
   multiProjectRoot?: string,
 ) {
   const app = new Hono<{ Variables: AppVars }>();
+  const exportMode = exportPrefixes !== undefined;
+  const events = new EventsByProject(directory);
 
   // Public — no auth middleware (MCP clients call this before they have a token)
   // RFC 9728 resource metadata & OAuth authorization server metadata via @hono/mcp
@@ -109,15 +110,15 @@ export function createApp(
     return c.json({
       staticMode: exportMode,
       logoutUrl: process.env.APP_LOGOUT_URL || '',
-      presenceEnabled: process.env.APP_PRESENCE_ENABLED === 'true',
       defaultProject: process.env.CYBERISMO_DEFAULT_PROJECT || undefined,
+      extensionUrl: process.env.APP_EXTENSION_URL || undefined,
     });
   });
 
-  // Dev-only: let `?role=<reader|editor|admin>` set a persistent mock-role cookie
-  // so role gating can be exercised locally without code changes or a restart.
+  // Mock-auth only: let `?role=` and, with the roster on, `?user=` set persistent
+  // cookies so role gating and identity can be switched locally without a restart.
   if (authProvider instanceof MockAuthProvider) {
-    app.use(mockRoleCookieMiddleware());
+    app.use(authProvider.cookieMiddleware());
   }
 
   // Apply authentication middleware to all API and MCP routes
@@ -125,12 +126,12 @@ export function createApp(
   app.use('/mcp', createAuthMiddleware(authProvider));
   app.use('/mcp/*', createAuthMiddleware(authProvider));
 
-  // Global routes (no project-specific CommandManager needed)
+  // Global routes (no project handle needed)
   app.route('/api/auth', createAuthRouter());
-  app.route('/api/projects', createProjectsRouter(registry, multiProjectRoot));
+  app.route('/api/projects', createProjectsRouter(directory, multiProjectRoot));
 
   // Test-mode reset endpoint: wipes the project dir, restores it from the
-  // golden snapshot, and rebuilds the registry in place. Used by the
+  // golden snapshot, and reopens its projects in place. Used by the
   // Playwright e2e harness to restore the project between spec files.
   // Gated by NODE_ENV so it never ships in production.
   if (process.env.NODE_ENV === 'test') {
@@ -161,9 +162,16 @@ export function createApp(
           400,
         );
       }
-      await fs.rm(resolvedProject, { recursive: true, force: true });
+      // Windows holds transient locks on files the server has just touched,
+      // which surface as EBUSY on the final rmdir. Retry rather than fail the reset.
+      await fs.rm(resolvedProject, {
+        recursive: true,
+        force: true,
+        maxRetries: 5,
+        retryDelay: 100,
+      });
       await fs.cp(goldenPath, resolvedProject, { recursive: true });
-      const projects = await scanForProjects(resolvedProject);
+      const projects = await directory.list();
 
       if (projects.length === 0) {
         return c.json(
@@ -173,13 +181,10 @@ export function createApp(
           500,
         );
       }
-      const entries = [];
       for (const project of projects) {
-        const commands = new CommandManager(project.path, gitOptionsFromEnv());
-        await commands.initialize();
-        entries.push({ prefix: project.prefix, commands });
+        await directory.replace(project.prefix);
+        events.drop(project.prefix);
       }
-      await registry.replace(entries);
       return c.body(null, 204);
     });
   }
@@ -197,23 +202,25 @@ export function createApp(
     }
   });
 
-  if (exportMode) {
+  if (exportPrefixes) {
     // Export mode: mount at each concrete prefix so SSG sees
     // static routes instead of dynamic :prefix patterns it would skip.
-    for (const { prefix } of registry.list()) {
+    for (const prefix of exportPrefixes) {
       const scoped = createProjectScopedRoutes(
-        attachProjectRegistry(registry, prefix),
+        attachProjectDirectory(directory, events, prefix),
       );
       app.route(`/api/projects/${prefix}`, scoped);
     }
   } else {
     // Normal mode: dynamic :prefix param
-    const scoped = createProjectScopedRoutes(attachProjectRegistry(registry));
+    const scoped = createProjectScopedRoutes(
+      attachProjectDirectory(directory, events),
+    );
     app.route('/api/projects/:prefix', scoped);
   }
 
   // MCP endpoint for AI assistant integration
-  app.route('/mcp', createMcpRouter(registry));
+  app.route('/mcp', createMcpRouter(writableProjects(directory)));
 
   app.use(
     '*',
@@ -236,18 +243,13 @@ export function createApp(
     return c.html(file.toString());
   });
   // Error handling
+  // Only server faults are logged; client errors are answered, not logged.
   app.onError((err, c) => {
-    if (!isSSGContext(c)) {
-      if (process.env.NODE_ENV !== 'test') {
-        console.error(err.stack);
-      }
+    const { status, body } = errorResponse(err);
+    if (status >= 500 && !isSSGContext(c) && process.env.NODE_ENV !== 'test') {
+      console.error(err.stack);
     }
-    return c.json(
-      {
-        error: err.message || 'Internal Server Error',
-      },
-      500,
-    );
+    return c.json(body, status);
   });
 
   return app;

package/src/auth/index.ts

@@ -1,17 +1,7 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2026
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation. This program is distributed in the hope that it
-  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
-  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-  See the GNU Affero General Public License for more details.
-  You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 export type { AuthProvider } from './types.js';
-export { MockAuthProvider, mockRoleCookieMiddleware } from './mock.js';
+export { MockAuthProvider } from './mock.js';
 export { KeycloakAuthProvider } from './keycloak.js';
 export type { KeycloakConfig } from './keycloak.js';

package/src/auth/keycloak.ts

@@ -1,21 +1,10 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2026
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation. This program is distributed in the hope that it
-  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
-  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-  See the GNU Affero General Public License for more details.
-  You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 import type { JWTPayload } from 'jose';
 import { UserRole } from '../types.js';
-import type { UserInfo } from '../types.js';
-import type { AuthProvider } from './types.js';
+import type { AuthProvider, AuthResult } from './types.js';
 
 export interface KeycloakConfig {
   issuer: string;
@@ -51,7 +40,7 @@ export class KeycloakAuthProvider implements AuthProvider {
     return this.jwks;
   }
 
-  async authenticate(req: Request): Promise<UserInfo | null> {
+  async authenticate(req: Request): Promise<AuthResult | null> {
     const authHeader = req.headers.get('authorization');
     if (!authHeader) {
       return null;
@@ -78,12 +67,18 @@ export class KeycloakAuthProvider implements AuthProvider {
       if (!claims.email) {
         throw new Error('Missing email');
       }
+      // Optional in RFC 7519, and jwtVerify only checks it when present, so a
+      // token without one would rotate on jitter alone and never clamp.
+      if (!claims.exp) {
+        throw new Error('Missing exp');
+      }
 
       return {
         id: claims.sub,
         email: claims.email,
         name: claims.name ?? claims.preferred_username ?? 'Unknown',
         role,
+        exp: claims.exp,
       };
     } catch {
       // TODO: add proper logging

package/src/auth/mock.ts

@@ -1,40 +1,103 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2026
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation. This program is distributed in the hope that it
-  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
-  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-  See the GNU Affero General Public License for more details.
-  You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
-
-import type { MiddlewareHandler } from 'hono';
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { Context, MiddlewareHandler } from 'hono';
 import { setCookie } from 'hono/cookie';
 import { UserRole } from '../types.js';
 import type { UserInfo } from '../types.js';
-import type { AuthProvider } from './types.js';
+import type { AuthProvider, AuthResult } from './types.js';
 
 export interface MockUserConfig {
   name?: string;
   email?: string;
+  roster?: boolean;
 }
 
 export const MOCK_ROLE_COOKIE = 'mock-role';
-const ROLE_RESET_VALUE = 'default';
+export const MOCK_USER_COOKIE = 'mock-user';
+export const MOCK_EXP_COOKIE = 'mock-exp';
+export const MOCK_AS_PARAM = 'as';
+const RESET_VALUE = 'default';
+const MAX_TTL_SECONDS = 86_400;
+// Mock sessions do not expire. Saying so with a distant deadline rather than
+// no deadline keeps `exp` total for every consumer: it is far beyond the
+// 30-minute stream lifetime, so computeLifetimeMs() min()s it away and
+// rotation still falls to the jitter, exactly as an absent one did.
+const NO_EXPIRY_SECONDS = 100 * 365 * 24 * 60 * 60;
+
+function noExpiry(): number {
+  return Math.floor(Date.now() / 1000) + NO_EXPIRY_SECONDS;
+}
+
+const ROLE_ALIASES = new Map<string, UserRole>([
+  ['reader', UserRole.Reader],
+  ['editor', UserRole.Editor],
+  ['admin', UserRole.Admin],
+  ['connector', UserRole.Connector],
+]);
+
+interface MockUser {
+  id: string;
+  name: string;
+  email: string;
+  role: UserRole;
+}
 
-const ROLE_ALIASES: Record<string, UserRole> = {
-  reader: UserRole.Reader,
-  editor: UserRole.Editor,
-  admin: UserRole.Admin,
-  connector: UserRole.Connector,
-};
+// Opt-in: `cyberismo app` ships mock auth, where a roster identity would forge
+// git commit authorship. Dev and e2e need several users in one backend process.
+const MOCK_USERS = new Map<string, MockUser>([
+  [
+    'alice',
+    {
+      id: 'mock-user-alice',
+      name: 'Alice',
+      email: 'alice@example.com',
+      role: UserRole.Admin,
+    },
+  ],
+  [
+    'bob',
+    {
+      id: 'mock-user-bob',
+      name: 'Bob',
+      email: 'bob@example.com',
+      role: UserRole.Editor,
+    },
+  ],
+  [
+    'carol',
+    {
+      id: 'mock-user-carol',
+      name: 'Carol',
+      email: 'carol@example.com',
+      role: UserRole.Reader,
+    },
+  ],
+]);
 
 function parseRole(value: string | null | undefined): UserRole | null {
   if (!value) return null;
-  return ROLE_ALIASES[value.toLowerCase()] ?? null;
+  return ROLE_ALIASES.get(value.toLowerCase()) ?? null;
+}
+
+function parseUser(value: string | null | undefined): MockUser | null {
+  if (!value) return null;
+  return MOCK_USERS.get(value.toLowerCase()) ?? null;
+}
+
+/** An unreadable deadline is dropped rather than treated as long past, which
+ * would lock the user out with no request left to clear the cookie. */
+function parseExpiry(value: string | null | undefined): number | null {
+  const exp = Number(value);
+  return value && Number.isInteger(exp) && exp > 0 ? exp : null;
+}
+
+/** Seconds from now to the absolute epoch-second deadline to store. */
+function toDeadline(value: string): string | null {
+  const seconds = Number(value);
+  if (!Number.isInteger(seconds) || seconds <= 0) return null;
+  if (seconds > MAX_TTL_SECONDS) return null;
+  return String(Math.floor(Date.now() / 1000) + seconds);
 }
 
 function readCookie(header: string | null, name: string): string | undefined {
@@ -48,6 +111,22 @@ function readCookie(header: string | null, name: string): string | undefined {
   return undefined;
 }
 
+function applyOverride(
+  c: Context,
+  override: string | null,
+  cookieName: string,
+  toCookieValue: (value: string) => string | null,
+): void {
+  if (!override) return;
+  if (override.toLowerCase() === RESET_VALUE) {
+    setCookie(c, cookieName, '', { path: '/', maxAge: 0 });
+    return;
+  }
+  const value = toCookieValue(override);
+  if (value === null) return;
+  setCookie(c, cookieName, value, { path: '/', sameSite: 'Lax' });
+}
+
 export class MockAuthProvider implements AuthProvider {
   private readonly userConfig: MockUserConfig;
 
@@ -55,36 +134,53 @@ export class MockAuthProvider implements AuthProvider {
     this.userConfig = config ?? {};
   }
 
-  async authenticate(req: Request): Promise<UserInfo> {
-    const cookieRole = parseRole(
-      readCookie(req.headers.get('cookie'), MOCK_ROLE_COOKIE),
-    );
-    return {
+  async authenticate(req: Request): Promise<AuthResult | null> {
+    const cookies = req.headers.get('cookie');
+    const cookieRole = parseRole(readCookie(cookies, MOCK_ROLE_COOKIE));
+    if (this.userConfig.roster) {
+      // One-shot: a second identity from inside a tab already signed in as
+      // someone else, so neither the cookie nor the role override applies.
+      const asUser = parseUser(
+        new URL(req.url).searchParams.get(MOCK_AS_PARAM),
+      );
+      if (asUser) return { ...asUser, exp: noExpiry() };
+    }
+    const rosterUser = this.userConfig.roster
+      ? parseUser(readCookie(cookies, MOCK_USER_COOKIE))
+      : null;
+    const expiry = this.userConfig.roster
+      ? parseExpiry(readCookie(cookies, MOCK_EXP_COOKIE))
+      : null;
+    if (expiry !== null && expiry * 1000 <= Date.now()) return null;
+    const exp = expiry ?? noExpiry();
+
+    const identity: UserInfo = rosterUser ?? {
       id: 'mock-user',
       email: this.userConfig.email ?? 'admin@cyberismo.local',
       name: this.userConfig.name ?? 'Local Admin',
-      role: cookieRole ?? UserRole.Admin,
+      role: UserRole.Admin,
     };
+    return { ...identity, role: cookieRole ?? identity.role, exp };
   }
-}
 
-/**
- * Dev-only middleware that turns `?role=<reader|editor|admin>` into a persistent
- * `mock-role` cookie, and clears it on `?role=default`.
- */
-export function mockRoleCookieMiddleware(): MiddlewareHandler {
-  return async (c, next) => {
-    const override = new URL(c.req.url).searchParams.get('role');
-    if (override) {
-      if (override.toLowerCase() === ROLE_RESET_VALUE) {
-        setCookie(c, MOCK_ROLE_COOKIE, '', { path: '/', maxAge: 0 });
-      } else if (parseRole(override)) {
-        setCookie(c, MOCK_ROLE_COOKIE, override.toLowerCase(), {
-          path: '/',
-          sameSite: 'Lax',
-        });
+  /**
+   * Turns ?role= and, with the roster on, ?user= and ?ttl= into cookies;
+   * "default" clears. ?ttl= seconds gives the session an expiry, which is
+   * what drives stream rotation and the 401 that follows it.
+   */
+  cookieMiddleware(): MiddlewareHandler {
+    return async (c, next) => {
+      const params = new URL(c.req.url).searchParams;
+      applyOverride(c, params.get('role'), MOCK_ROLE_COOKIE, (value) =>
+        parseRole(value) ? value.toLowerCase() : null,
+      );
+      if (this.userConfig.roster) {
+        applyOverride(c, params.get('user'), MOCK_USER_COOKIE, (value) =>
+          parseUser(value) ? value.toLowerCase() : null,
+        );
+        applyOverride(c, params.get('ttl'), MOCK_EXP_COOKIE, toDeadline);
       }
-    }
-    await next();
-  };
+      await next();
+    };
+  }
 }