@cyberismo/backend 1.1.1 → 1.2.0

package/src/auth/mock.ts

@@ -11,30 +11,103 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import type { MiddlewareHandler } from 'hono';
+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;
 
-const ROLE_ALIASES: Record<string, UserRole> = {
-  reader: UserRole.Reader,
-  editor: UserRole.Editor,
-  admin: UserRole.Admin,
-  connector: UserRole.Connector,
-};
+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;
+}
+
+// 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 +121,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 +144,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();
+    };
+  }
 }

package/src/auth/types.ts

@@ -13,6 +13,13 @@
 
 import type { UserInfo } from '../types.js';
 
+export interface AuthResult extends UserInfo {
+  /** Credential deadline (epoch seconds). Always present: a provider whose
+   * sessions do not expire says so with a deadline far enough out to be
+   * inert, rather than leaving every consumer to handle its absence. */
+  exp: number;
+}
+
 export interface AuthProvider {
-  authenticate(req: Request): Promise<UserInfo | null>;
+  authenticate(req: Request): Promise<AuthResult | null>;
 }

package/src/domain/cards/index.ts

@@ -13,13 +13,11 @@
 
 import { type Context, Hono } from 'hono';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
-import { streamSSE } from 'hono/streaming';
 import { getCardDetails } from './lib.js';
 import * as cardService from './service.js';
 import { isSSGContext, ssgParams } from 'hono/ssg';
 import type { AppContext } from '../../types.js';
 import { UserRole } from '../../types.js';
-import { presenceStore } from './presence.js';
 import { requireRole } from '../../middleware/auth.js';
 import { zValidator } from '../../middleware/zvalidator.js';
 import {
@@ -32,6 +30,10 @@ import {
 
 const router = new Hono();
 
+function notifyCardsUpdated(c: Context, keys: string[]) {
+  c.get('events').cardsUpdated(keys, c.get('user'));
+}
+
 /**
  * @swagger
  * /api/cards:
@@ -240,7 +242,9 @@ router.patch('/:key', requireRole(UserRole.Editor), async (c) => {
   const body = await c.req.json();
 
   try {
-    await cardService.updateCard(commands, key, body);
+    if (await cardService.updateCard(commands, key, body)) {
+      notifyCardsUpdated(c, [key]);
+    }
     const result = await getCardDetails(
       c.get('commands'),
       key,
@@ -400,6 +404,7 @@ router.post('/:key/attachments', requireRole(UserRole.Editor), async (c) => {
       key,
       files as File[],
     );
+    notifyCardsUpdated(c, [key]);
     return c.json(result);
   } catch (error) {
     return c.json(
@@ -451,6 +456,7 @@ router.delete(
         key,
         filename,
       );
+      notifyCardsUpdated(c, [key]);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -466,54 +472,6 @@ router.delete(
   },
 );
 
-/**
- * @swagger
- * /api/cards/{key}/attachments/{filename}/open:
- *   post:
- *     summary: Open an attachment using the system's default application
- *     parameters:
- *       - name: key
- *         in: path
- *         required: true
- *         schema:
- *           type: string
- *       - name: filename
- *         in: path
- *         required: true
- *         schema:
- *           type: string
- *     responses:
- *       200:
- *         description: Attachment opened successfully
- *       400:
- *         description: Invalid request
- *       500:
- *         description: Server error
- */
-router.post(
-  '/:key/attachments/:filename/open',
-  requireRole(UserRole.Reader),
-  async (c) => {
-    const commands = c.get('commands');
-    const { key, filename } = c.req.param();
-
-    try {
-      const result = await cardService.openAttachment(commands, key, filename);
-      return c.json(result);
-    } catch (error) {
-      return c.json(
-        {
-          error:
-            error instanceof Error
-              ? error.message
-              : 'Failed to open attachment',
-        },
-        500,
-      );
-    }
-  },
-);
-
 /**
  * @swagger
  * /api/cards/{key}/parse:
@@ -613,6 +571,7 @@ router.post(
         direction,
         description,
       );
+      notifyCardsUpdated(c, [key, toCard]);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -675,6 +634,7 @@ router.delete(
         direction,
         description,
       );
+      notifyCardsUpdated(c, [key, toCard]);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -761,6 +721,7 @@ router.put(
         description,
         previousDescription,
       );
+      notifyCardsUpdated(c, [key, toCard, previousToCard]);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -843,55 +804,4 @@ router.get(
     }
   },
 );
-/**
- * @swagger
- * /api/cards/{key}/presence:
- *   get:
- *     summary: SSE stream of users currently viewing or editing this card
- *     parameters:
- *       - name: key
- *         in: path
- *         required: true
- *         description: Card key (string)
- *       - name: mode
- *         in: query
- *         required: false
- *         schema:
- *           type: string
- *           enum: [viewing, editing]
- *         description: Whether the user is viewing or editing (default: viewing)
- *     responses:
- *       200:
- *         description: SSE stream with presence events
- */
-router.get('/:key/presence', requireRole(UserRole.Reader), (c) => {
-  const key = c.req.param('key');
-  const mode = c.req.query('mode') === 'editing' ? 'editing' : 'viewing';
-  const user = c.get('user');
-
-  if (!key) {
-    return c.text('No card key', 400);
-  }
-
-  return streamSSE(c, async (stream) => {
-    const connId = presenceStore.add(
-      key,
-      user,
-      mode,
-      (data) => void stream.writeSSE(data),
-    );
-
-    let aborted = false;
-    stream.onAbort(() => {
-      aborted = true;
-      presenceStore.remove(key, connId);
-    });
-
-    // Keep connection alive with periodic heartbeat
-    while (!aborted) {
-      await stream.write(': hb\n\n');
-      await stream.sleep(30000);
-    }
-  });
-});
 export default router;

package/src/domain/cards/lib.ts

@@ -11,7 +11,6 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { convert } from '@asciidoctor/core';
 import type { Card } from '@cyberismo/data-handler/interfaces/project-interfaces';
 import { type CommandManager, evaluateMacros } from '@cyberismo/data-handler';
 import { preprocessMermaidBlocksForHtml } from '@cyberismo/data-handler/utils/mermaid-renderer';
@@ -70,17 +69,6 @@ export async function getCardDetails(
       staticMode ? 'staticSite' : 'inject',
     );
 
-    const projectPrefix = commands.project.projectPrefix;
-    const htmlContent = (
-      await convert(asciidocContent, {
-        safe: 'safe',
-        attributes: {
-          imagesdir: `/api/projects/${projectPrefix}/cards/${key}/a`,
-          icons: 'font',
-        },
-      })
-    ).toString();
-
     if (raw) {
       if (!cardDetailsResponse.metadata) {
         throw new Error('Card has no metadata');
@@ -143,7 +131,7 @@ export async function getCardDetails(
             editContent: [],
           },
           rawContent: cardDetailsResponse.content || '',
-          parsedContent: htmlContent,
+          adocContent: asciidocContent,
           attachments: cardDetailsResponse.attachments,
           path: cardDetailsResponse.path,
         },
@@ -165,7 +153,7 @@ export async function getCardDetails(
       data: {
         ...card[0],
         rawContent: cardDetailsResponse.content || '',
-        parsedContent: htmlContent,
+        adocContent: asciidocContent,
         attachments: cardDetailsResponse.attachments,
         path: cardDetailsResponse.path,
       },

package/src/domain/cards/schema.ts

@@ -39,12 +39,20 @@ export const updateLinkSchema = z.object({
   previousDirection: linkDirection,
   previousDescription: z.string().optional(),
 });
+
+// Interpolated into the exported document's AsciiDoc header, where a line break
+// starts a new attribute entry.
+const headerValue = z
+  .string()
+  .min(1)
+  .regex(/^[^\r\n]*$/, 'must not contain line breaks');
+
 export const exportCardPdfSchema = z.object({
-  title: z.string().min(1),
-  name: z.string().min(1),
+  title: headerValue,
+  name: headerValue,
   cardKey: z.string(),
   exportChildCards: z.boolean(),
-  version: z.string().min(1).optional(),
+  version: headerValue.optional(),
 });
 
 export type ExportCardPdfRequestBody = z.infer<typeof exportCardPdfSchema>;

package/src/domain/cards/service.ts

@@ -11,7 +11,6 @@
   License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { convert } from '@asciidoctor/core';
 import type {
   ExportPdfOptions,
   MetadataContent,
@@ -51,13 +50,16 @@ export async function updateCard(
   key: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   body: any,
-) {
+): Promise<boolean> {
+  let written = false;
   await commands.atomic(async () => {
     if (body.state) {
       await commands.transitionCmd.cardTransition(key, body.state);
+      written = true;
     }
     if (body.content != null) {
       await commands.editCmd.editCardContent(key, body.content);
+      written = true;
     }
     if (body.metadata) {
       for (const [metadataKey, metadataValue] of Object.entries(
@@ -68,15 +70,19 @@ export async function updateCard(
           metadataKey,
           metadataValue as MetadataContent,
         );
+        written = true;
       }
     }
     if (body.parent) {
       await commands.moveCmd.moveCard(key, body.parent);
+      written = true;
     }
     if (body.index != null) {
       await commands.moveCmd.rankByIndex(key, body.index);
+      written = true;
     }
   }, `Update card ${key}`);
+  return written;
 }
 
 export async function deleteCard(commands: CommandManager, key: string) {
@@ -142,16 +148,6 @@ export async function removeAttachment(
   return { message: 'Attachment removed successfully' };
 }
 
-export async function openAttachment(
-  commands: CommandManager,
-  key: string,
-  filename: string,
-) {
-  validateAttachmentFileName(filename);
-  await commands.showCmd.openAttachment(key, filename);
-  return { message: 'Attachment opened successfully' };
-}
-
 export async function parseContent(
   commands: CommandManager,
   key: string,
@@ -181,18 +177,7 @@ export async function parseContent(
       'inject',
     );
 
-    const projectPrefix = commands.project.projectPrefix;
-    const parsedContent = (
-      await convert(asciidocContent, {
-        safe: 'safe',
-        attributes: {
-          imagesdir: `/api/projects/${projectPrefix}/cards/${key}/a`,
-          icons: 'font',
-        },
-      })
-    ).toString();
-
-    return { parsedContent };
+    return { adocContent: asciidocContent };
   });
 }
 

package/src/domain/events/index.ts

@@ -0,0 +1,112 @@
+/**
+  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 { Hono } from 'hono';
+import { disableSSG } from 'hono/ssg';
+import { streamSSE, type SSEMessage } from 'hono/streaming';
+import { isAtLeastRole, requireRole } from '../../middleware/auth.js';
+import { zValidator } from '../../middleware/zvalidator.js';
+import { UserRole } from '../../types.js';
+import { computeLifetimeMs } from './lifetime.js';
+import { presenceSchema } from './schema.js';
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+const router = new Hono();
+
+router.get('/', disableSSG(), requireRole(UserRole.Reader), (c) => {
+  const events = c.get('events');
+  const user = c.get('user');
+  const capabilities = {
+    canSeeIdentity: isAtLeastRole(user.role, UserRole.Editor),
+    canDeclareEditing: isAtLeastRole(user.role, UserRole.Editor),
+    canSeePresence: isAtLeastRole(user.role, UserRole.Editor),
+  };
+  return streamSSE(c, async (stream) => {
+    if (stream.aborted) return;
+    let finish: () => void = () => {};
+    const closed = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    let stopped = false;
+    let release = () => {};
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
+      release();
+      finish();
+    };
+    // Ends the stream after one last message. Deliberately does not call
+    // `release()`: a rotating connection has been retired, and disconnecting
+    // it would drop the presence entry that bridges the client's reconnect.
+    const terminate = (message: SSEMessage) => {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(heartbeat);
+      clearTimeout(rotate);
+      void stream.writeSSE(message).then(finish);
+    };
+    // Hono swallows stream write errors; `onAbort` is the only teardown signal.
+    stream.onAbort(stop);
+    const connectionId = events.connect(user, capabilities, {
+      send: (message) => void stream.writeSSE(message),
+      close: stop,
+      terminate,
+    });
+    release = () => events.disconnect(connectionId);
+    const heartbeat = setInterval(
+      () => void stream.writeSSE({ event: 'hb', data: '' }),
+      HEARTBEAT_INTERVAL_MS,
+    );
+    const rotate = setTimeout(
+      () => {
+        events.retire(connectionId);
+        terminate({ event: 'rotating', data: '' });
+      },
+      computeLifetimeMs(c.get('tokenExp')),
+    );
+    try {
+      await closed;
+    } finally {
+      clearInterval(heartbeat);
+      clearTimeout(rotate);
+      stop();
+    }
+  });
+});
+
+router.put(
+  '/presence',
+  requireRole(UserRole.Reader),
+  zValidator('json', presenceSchema),
+  (c) => {
+    const { connectionId, sequence, cardKey, mode } = c.req.valid('json');
+    if (cardKey && !c.get('commands').project.hasCard(cardKey)) {
+      return c.json({ error: 'Card not found' }, 404);
+    }
+    const events = c.get('events');
+    const known = events.update(
+      connectionId,
+      c.get('user').id,
+      sequence,
+      cardKey,
+      mode,
+    );
+    if (!known) {
+      return c.json({ error: 'Presence connection not found' }, 404);
+    }
+    return c.body(null, 204);
+  },
+);
+
+export default router;