@cyberismo/backend 1.1.2 → 1.3.0

package/src/main.ts

@@ -1,22 +1,13 @@
-/**
-  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/>.
-*/
-import { scanForProjects } from '@cyberismo/data-handler';
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { localFolder } from '@cyberismo/data-handler';
 import { startServer } from './index.js';
 import { exportSite } from './export.js';
 import { MockAuthProvider } from './auth/mock.js';
 import { KeycloakAuthProvider } from './auth/keycloak.js';
 import type { AuthProvider } from './auth/types.js';
-import { ProjectRegistry } from './project-registry.js';
+import { formatProjectErrors } from '@cyberismo/model';
 import { gitOptionsFromEnv } from './utils.js';
 import { parseArgs } from 'node:util';
 import dotenv from 'dotenv';
@@ -35,7 +26,7 @@ function createAuthProvider(): AuthProvider {
   }
 
   if (authMode === 'mock') {
-    return new MockAuthProvider();
+    return new MockAuthProvider({ roster: true });
   }
 
   if (authMode === 'idp') {
@@ -59,9 +50,21 @@ function createAuthProvider(): AuthProvider {
 }
 
 const projectPath = process.env.npm_config_project_path || process.cwd();
-let projects;
+
+const { values: args } = parseArgs({
+  options: {
+    export: { type: 'boolean', default: false },
+    'default-project': { type: 'string' },
+  },
+  strict: false,
+});
+
+let opened;
 try {
-  projects = await scanForProjects(projectPath);
+  opened = await localFolder(
+    projectPath,
+    args.export ? undefined : gitOptionsFromEnv(),
+  );
 } catch (error) {
   console.error(
     error instanceof Error
@@ -70,32 +73,37 @@ try {
   );
   process.exit(1);
 }
-
-const { values: args } = parseArgs({
-  options: {
-    export: { type: 'boolean', default: false },
-    'default-project': { type: 'string' },
-  },
-  strict: false,
-});
+const { directory, failed } = opened;
 
 if (args.export) {
-  if (projects.length === 0) {
+  const projects = await directory.list();
+  if (projects.length === 0 && failed.length === 0) {
     console.error('No projects found to export.');
     process.exit(1);
   }
-  const registry = await ProjectRegistry.fromScannedProjects(projects);
-  await exportSite(registry, undefined, {
-    defaultProject:
-      typeof args['default-project'] === 'string'
-        ? args['default-project']
-        : undefined,
+  const defaultProject =
+    typeof args['default-project'] === 'string'
+      ? args['default-project']
+      : undefined;
+  if (
+    projects.length === 0 ||
+    failed.some((f) => f.prefix === defaultProject)
+  ) {
+    console.error(formatProjectErrors(failed));
+    process.exit(1);
+  }
+  const { errors: exportErrors } = await exportSite(directory, undefined, {
+    defaultProject,
   });
+  const errors = [...failed, ...exportErrors];
+  if (errors.length > 0) {
+    console.error(formatProjectErrors(errors));
+    process.exit(1);
+  }
 } else {
-  const registry = await ProjectRegistry.fromScannedProjects(
-    projects,
-    gitOptionsFromEnv(),
-  );
+  if (failed.length > 0) {
+    console.error(formatProjectErrors(failed));
+  }
   const authProvider = createAuthProvider();
-  await startServer(authProvider, registry, true, projectPath);
+  await startServer(authProvider, directory, true, projectPath);
 }

package/src/middleware/auth.ts

@@ -1,25 +1,17 @@
-/**
-  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 type { Context, MiddlewareHandler } from 'hono';
 import type { UserInfo } from '../types.js';
 import { UserRole } from '../types.js';
 import type { AuthProvider } from '../auth/types.js';
+import { isReadOnly } from '../overlay.js';
 
 // Extend Hono Context type to include our custom properties
 declare module 'hono' {
   interface ContextVariableMap {
     user: UserInfo;
+    tokenExp: number;
   }
 }
 
@@ -30,6 +22,14 @@ const roleLevel: Record<UserRole, number> = {
   [UserRole.Admin]: 2,
 };
 
+/** Everyone below administrator is a reader; lifting read-only is their job. */
+function applyReadOnly(user: UserInfo): UserInfo {
+  if (user.role === UserRole.Admin) {
+    return user;
+  }
+  return { ...user, role: UserRole.Reader };
+}
+
 /**
  * Create authentication middleware from an AuthProvider.
  * Validates the user and attaches user info to the context.
@@ -38,10 +38,12 @@ export function createAuthMiddleware(
   provider: AuthProvider,
 ): MiddlewareHandler {
   return async (c, next) => {
-    const user = await provider.authenticate(c.req.raw);
+    const result = await provider.authenticate(c.req.raw);
 
-    if (user) {
-      c.set('user', user);
+    if (result) {
+      const { exp, ...user } = result;
+      c.set('user', isReadOnly(c.req.path) ? applyReadOnly(user) : user);
+      c.set('tokenExp', exp);
     } else {
       // RFC 9728 §5.1: include resource_metadata in WWW-Authenticate
       // only for MCP routes, where the metadata document applies.
@@ -60,6 +62,13 @@ export function createAuthMiddleware(
   };
 }
 
+/**
+ * Check if a role meets or exceeds a minimum role in the hierarchy.
+ */
+export function isAtLeastRole(role: UserRole, minimumRole: UserRole): boolean {
+  return roleLevel[role] >= roleLevel[minimumRole];
+}
+
 /**
  * Check if the current user has at least the required role
  */
@@ -69,7 +78,7 @@ export function hasRole(c: Context, minimumRole: UserRole): boolean {
     return false;
   }
 
-  return roleLevel[user.role] >= roleLevel[minimumRole];
+  return isAtLeastRole(user.role, minimumRole);
 }
 
 /**

package/src/middleware/commandManager.ts

@@ -1,78 +1,66 @@
-/**
-    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 type { Context, MiddlewareHandler } from 'hono';
-import type { CommandManager } from '@cyberismo/data-handler';
+import type { ActorRef } from '@cyberismo/model';
+import type { ProjectDirectory, Workspace } from '@cyberismo/data-handler';
 import { getCurrentUser } from './auth.js';
-import type { ProjectRegistry } from '../project-registry.js';
+import { UserRole, type UserInfo } from '../types.js';
+import type { ProjectEvents } from '../domain/events/project-events.js';
+import type { EventsByProject } from '../domain/events/events-by-project.js';
 
 // Extend Hono Context type to include our custom properties
 declare module 'hono' {
   interface ContextVariableMap {
-    commands: CommandManager;
+    ws: Workspace;
+    events: ProjectEvents;
     projectPath: string;
-    registry: ProjectRegistry;
+    directory: ProjectDirectory;
+    eventsByProject: EventsByProject;
   }
 }
 
-/**
- * Set CommandManager on context and run the next handler as the authenticated user.
- */
-async function runWithCommands(
-  c: Context,
-  commands: CommandManager,
-  next: () => Promise<void>,
-) {
-  const user = getCurrentUser(c);
-  if (!user) {
-    throw new Error('CommandManager expects a user');
-  }
-  c.set('commands', commands);
-  c.set('projectPath', commands.project.basePath);
-  await commands.runAsAuthor({ name: user.name, email: user.email }, () =>
-    next(),
-  );
+/** The actor a user acts as. */
+export function actorOf(user: UserInfo): ActorRef {
+  return {
+    kind: user.role === UserRole.Connector ? 'connector' : 'user',
+    id: user.id,
+    name: user.name,
+  };
 }
 
-// TODO: Remove once MCP is made project-scoped via attachProjectRegistry
-export const attachCommandManager = (
-  commands: CommandManager,
-): MiddlewareHandler => {
-  return (c, next) => runWithCommands(c, commands, next);
-};
-
 /**
- * Middleware that resolves the project from the registry and sets the
- * CommandManager on context.
+ * Middleware that opens the authenticated user's handle over the project
+ * and puts it, with the project's events and the directory, on the context.
+ * An unknown project is refused with ProjectNotFoundError (404).
  *
- * @param registry - Project registry to look up projects.
+ * @param directory - Directory the project is opened from.
+ * @param events - Events of the directory's projects.
  * @param fixedPrefix - When provided, used instead of the `:prefix` route
  *   param. This is needed in export/SSG mode where routes are mounted at
  *   concrete paths (e.g. `/api/projects/decision/...`) with no dynamic param.
  */
-export const attachProjectRegistry = (
-  registry: ProjectRegistry,
+export const attachProjectDirectory = (
+  directory: ProjectDirectory,
+  events: EventsByProject,
   fixedPrefix?: string,
 ): MiddlewareHandler => {
   return async (c: Context, next) => {
-    c.set('registry', registry);
     const prefix = c.req.param('prefix') ?? fixedPrefix;
     if (!prefix) {
       return c.json({ error: 'Project prefix is required' }, 400);
     }
-    const commands = registry.get(prefix);
-    if (!commands) {
-      return c.json({ error: `Project '${prefix}' not found` }, 404);
+    const user = getCurrentUser(c);
+    if (!user) {
+      throw new Error('A project handle expects a user');
     }
-    return runWithCommands(c, commands, next);
+    const identity = { name: user.name, email: user.email };
+    const ws = await directory.open(prefix, actorOf(user), identity);
+    c.set('directory', directory);
+    c.set('eventsByProject', events);
+    c.set('events', await events.for(prefix));
+    c.set('ws', ws);
+    c.set('projectPath', ws.path);
+    await next();
   };
 };

package/src/middleware/tree.ts

@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
 import type { Next } from 'hono';
 import type { AppContext, TreeOptions } from '../types.js';
 

package/src/middleware/zvalidator.ts

@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
 import { zValidator as zv } from '@hono/zod-validator';
 import type { ZodType } from 'zod';
 import type { ValidationTargets } from 'hono';

package/src/overlay.ts

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Which projects, or the whole instance, are read-only.
+ *
+ * Polled on a timer so no request waits for it, and permissive on every
+ * uncertain path: a freeze arriving late beats an outage. Unset
+ * CYBERISMO_OVERLAY_URL means no policy, which is the standalone default.
+ */
+
+import { z } from 'zod';
+import {
+  ProjectNotFoundError,
+  type ProjectDirectory,
+} from '@cyberismo/data-handler';
+
+const POLL_INTERVAL_MS = 10_000;
+const FETCH_TIMEOUT_MS = 2_000;
+
+const policySchema = z
+  .object({
+    readOnly: z.boolean().catch(false),
+    projects: z
+      .record(z.string(), z.object({ readOnly: z.boolean().catch(false) }))
+      .catch({}),
+  })
+  .catch(() => EMPTY);
+
+export type Policy = z.infer<typeof policySchema>;
+
+const EMPTY: Policy = { readOnly: false, projects: {} };
+
+let current: Policy = EMPTY;
+
+export function getPolicy(): Policy {
+  return current;
+}
+
+export function setPolicy(policy: Policy): void {
+  current = policy;
+}
+
+export function isProjectReadOnly(prefix: string): boolean {
+  return current.readOnly || current.projects[prefix]?.readOnly === true;
+}
+
+/** `/api/projects/<prefix>/…` is the only request shape naming a project. */
+export function isReadOnly(path: string): boolean {
+  if (current.readOnly) return true;
+  const match = /^\/api\/projects\/([^/?#]+)/.exec(path);
+  if (!match) return false;
+  let prefix: string;
+  try {
+    prefix = decodeURIComponent(match[1]);
+  } catch {
+    prefix = match[1];
+  }
+  return isProjectReadOnly(prefix);
+}
+
+/**
+ * Temporary: the app is the source of truth for which projects exist, so it
+ * tells overlay. That inverts once projects are created in overlay's admin
+ * views, after which overlay reports them and this goes away.
+ */
+async function reportProjects(
+  base: string,
+  token: string | undefined,
+  projects: { prefix: string }[],
+): Promise<void> {
+  const response = await fetch(`${base.replace(/\/$/, '')}/projects`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { 'X-Overlay-Token': token } : {}),
+    },
+    body: JSON.stringify({ projects }),
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    throw new Error(`responded ${response.status}`);
+  }
+}
+
+export function startPolicyPolling(
+  projects: () => Promise<{ prefix: string }[]> = async () => [],
+): void {
+  const base = process.env.CYBERISMO_OVERLAY_URL;
+  if (!base) return;
+  const token = process.env.CYBERISMO_OVERLAY_TOKEN;
+  const url = `${base.replace(/\/$/, '')}/tenant`;
+
+  let lastFailure: string | undefined;
+
+  const poll = async () => {
+    try {
+      const response = await fetch(url, {
+        headers: token ? { 'X-Overlay-Token': token } : {},
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      });
+      if (!response.ok) {
+        throw new Error(`responded ${response.status}`);
+      }
+      setPolicy(policySchema.parse(await response.json()));
+      if (lastFailure) {
+        console.error(`overlay: ${url} is reachable again`);
+        lastFailure = undefined;
+      }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      if (reason !== lastFailure) {
+        lastFailure = reason;
+        console.error(`overlay: ${url} ${reason}, keeping the previous policy`);
+      }
+    }
+  };
+
+  // Reported every tick from a fresh list, so a project created after start-up
+  // is registered within one interval.
+  let lastReportFailure: string | undefined;
+  const report = async () => {
+    const current = await projects();
+    if (current.length === 0) return;
+    try {
+      await reportProjects(base, token, current);
+      lastReportFailure = undefined;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      if (reason !== lastReportFailure) {
+        lastReportFailure = reason;
+        console.error(`overlay: could not report projects, ${reason}`);
+      }
+    }
+  };
+
+  // setInterval does not wait for the previous run, so skip a tick rather than
+  // letting two overlap.
+  let running = false;
+  const tick = async () => {
+    if (running) return;
+    running = true;
+    try {
+      await poll();
+      await report();
+    } finally {
+      running = false;
+    }
+  };
+
+  void tick();
+  setInterval(() => void tick(), POLL_INTERVAL_MS).unref();
+}
+
+/**
+ * Hide read-only projects from MCP.
+ *
+ * MCP takes the project as an argument rather than in the path, so the role cap
+ * cannot see which one a call touches. Making a frozen project unresolvable
+ * fails closed, at the cost of hiding it from reads and from administrators too.
+ */
+export function writableProjects(
+  directory: ProjectDirectory,
+): ProjectDirectory {
+  return {
+    open: async (prefix, actor, identity) => {
+      if (isProjectReadOnly(prefix)) {
+        throw new ProjectNotFoundError(prefix);
+      }
+      return directory.open(prefix, actor, identity);
+    },
+    list: async () =>
+      (await directory.list()).filter((p) => !isProjectReadOnly(p.prefix)),
+    create: (params, actor, identity) =>
+      directory.create(params, actor, identity),
+    clone: (url) => directory.clone(url),
+    rename: async (prefix, newPrefix, actor, identity, options) => {
+      if (isProjectReadOnly(prefix)) {
+        throw new ProjectNotFoundError(prefix);
+      }
+      return directory.rename(prefix, newPrefix, actor, identity, options);
+    },
+    replace: (prefix) => directory.replace(prefix),
+  };
+}

package/src/types.ts

@@ -1,15 +1,5 @@
-/**
-  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 type { Context } from 'hono';
 

package/src/utils.ts

@@ -1,17 +1,8 @@
-/**
-  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, type ServerType } from '@hono/node-server';
 
 /**
  * The relative path to the static frontend directory.
@@ -22,43 +13,32 @@ export const staticFrontendDirRelative = path.relative(
 );
 
 /**
- * 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: number,
-  maxPort: number,
-): Promise<number> {
-  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: Parameters<typeof serve>[0]['fetch'],
+  port: number,
+  host: string,
+  maxPort: number = port,
+): Promise<{ server: ServerType; port: number }> {
+  return new Promise((resolve, reject) => {
+    const server = serve({ fetch, port, hostname: host }, (info) =>
+      resolve({ server, port: info.port }),
+    );
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      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: number) {
-  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);
   });
 }
 

package/dist/domain/cards/presence.d.ts

@@ -1,50 +0,0 @@
-/**
-  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 { UserInfo } from '../../types.js';
-import type { SSEMessage } from 'hono/streaming';
-export interface PresenceEntry {
-    userId: string;
-    userName: string;
-    mode: 'viewing' | 'editing';
-}
-/**
- * In-memory presence tracker for card editing/viewing.
- * Tracks which users are currently looking at or editing each card,
- * and notifies all connected clients via SSE when presence changes.
- */
-declare class PresenceStore {
-    private connections;
-    private nextId;
-    /**
-     * Add a user connection for a card. Returns a connection ID for later removal.
-     */
-    add(cardKey: string, user: UserInfo, mode: 'viewing' | 'editing', send: (message: SSEMessage) => void): string;
-    /**
-     * Remove a connection and broadcast updated presence.
-     */
-    remove(cardKey: string, connId: string): void;
-    /**
-     * Get current presence list for a card.
-     */
-    getPresence(cardKey: string): PresenceEntry[];
-    /**
-     * Broadcast current presence to all connected clients for a card.
-     */
-    private broadcast;
-    /**
-     * Remove all connections. Intended for test cleanup.
-     */
-    removeAll(): void;
-}
-export declare const presenceStore: PresenceStore;
-export {};