@bevel-software/platform-core-backend 0.9.1 → 0.11.0

package/src/modules/access/synced-groups-writer.ts

@@ -0,0 +1,303 @@
+import {
+  EMAIL_REGEX,
+  GROUP_REF_PREFIX,
+  canonicalEmail,
+  canonicalRoleName,
+  RESERVED_ROLE_NAMES,
+} from './access-control.service.js';
+import { unsafeNameReason } from './group-files.js';
+
+/**
+ * Locale-independent code-unit comparator. `localeCompare` would make the
+ * "deterministic render" depend on the process's ambient locale/ICU build —
+ * two deployments could then disagree on byte order and ping-pong no-op
+ * detection.
+ */
+function codeUnitCompare(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Materializes an external directory's groups into `synced-groups.yaml` — the
+ * MACHINE-OWNED group file the access resolver reads in IdP mode.
+ *
+ * Why a file and not the DB: access resolution is file-based and evaluated at
+ * git refs (the merge/push gates depend on it), so group membership must live
+ * in the KB repo. Wholesale regeneration (never editing) is what makes the
+ * file conflict-free, and git history doubles as the membership audit log.
+ *
+ * The DIRECTORY ITSELF is not core's business: groups arrive through a
+ * {@link SyncedGroupsSource} an overlay provides (e.g. a SCIM mirror fed by
+ * Entra/Okta provisioning). Core owns the file format, the rendering rules,
+ * and the commit pipeline — the same module that parses the file on the read
+ * side (`group-files.ts`) governs what gets written into it.
+ *
+ * The renderer is a PURE function so its determinism is trivially testable;
+ * the writer wraps it with debounce (a provisioning cycle is a burst of many
+ * directory pushes — one commit per burst, not per mutation) and no-op
+ * detection (unchanged content never commits).
+ */
+
+const FILE_HEADER = `# MACHINE-GENERATED from the identity provider's directory — do not edit.
+# Membership is managed in the IdP; this file is regenerated wholesale on every
+# provisioning push. Manual groups live in groups.yaml (ignored while this file
+# exists — its presence IS what puts the deployment in IdP mode).
+`;
+
+/** A member of an externally-synced group, as the materializer needs it. */
+export interface SyncedGroupMember {
+  /** Lowercased primary email — the identity join key; null when the IdP sent none. */
+  email: string | null;
+  /** Deactivated members stay mirrored upstream but are not materialized. */
+  active: boolean;
+}
+
+/** A group from the external directory, as the materializer needs it. */
+export interface SyncedGroupRecord {
+  /** The IdP's own identifier, if it sent one — only used to break sort ties. */
+  externalId: string | null;
+  displayName: string;
+  members: SyncedGroupMember[];
+}
+
+/**
+ * The seam an overlay implements to feed the materializer: "the current
+ * groups in the external directory." Core never learns HOW they got there
+ * (SCIM push, API poll, …).
+ */
+export interface SyncedGroupsSource {
+  listGroups(): Promise<SyncedGroupRecord[]>;
+}
+
+// Name safety is the SHARED predicate in `group-files.ts` (`unsafeNameReason`)
+// — the same rules the manual group editor asserts, including the reserved
+// `role/` prefix. Here the name arrives from the IdP, so an unsafe group is
+// SKIPPED with a warning instead of erroring (fail-closed: an unrepresentable
+// group grants nothing).
+
+export interface RenderedSyncedGroups {
+  text: string;
+  /** Groups/members that could not be materialized, human-readable. */
+  warnings: string[];
+  /** Groups actually emitted (post-skip). */
+  groupCount: number;
+}
+
+/**
+ * Deterministic render: same directory state → byte-identical file. Groups
+ * sort by canonical name (ties by externalId), member emails sort lexically.
+ * Excluded from materialization (each with a warning): groups with
+ * YAML-unsafe or reserved names, canonical-name duplicates (first wins), and
+ * members that are inactive or carry no email (email is the identity join
+ * key — a member without one cannot be granted anything).
+ */
+export function renderSyncedGroupsYaml(groups: SyncedGroupRecord[]): RenderedSyncedGroups {
+  const warnings: string[] = [];
+  const byCanonical = new Map<string, SyncedGroupRecord>();
+
+  const sorted = [...groups].sort((a, b) => {
+    const byName = codeUnitCompare(canonicalRoleName(a.displayName), canonicalRoleName(b.displayName));
+    if (byName !== 0) return byName;
+    const byExternalId = codeUnitCompare(a.externalId ?? '', b.externalId ?? '');
+    if (byExternalId !== 0) return byExternalId;
+    // Full-key duplicates: break the tie on membership, then on the RAW
+    // display name (same canonical can differ in case/spacing, and the winner
+    // of the first-wins dedup below decides the emitted name) — so the bytes
+    // never depend on source array order. The membership key is JSON — a
+    // plain delimiter join could collide (an email may legally contain the
+    // delimiter characters), and a collision between DIFFERENT member sets
+    // would push the tie-break back onto input order.
+    const memberKey = (members: SyncedGroupMember[]): string =>
+      JSON.stringify(
+        members.map((m) => `${JSON.stringify(m.email ?? '')}:${m.active}`).sort(codeUnitCompare),
+      );
+    const byMembers = codeUnitCompare(memberKey(a.members), memberKey(b.members));
+    if (byMembers !== 0) return byMembers;
+    return codeUnitCompare(a.displayName, b.displayName);
+  });
+
+  // Group names are UNTRUSTED IdP input and flow into warnings that land in
+  // logs — JSON.stringify them so a name carrying control characters (ANSI
+  // escapes, newlines) is rendered escaped instead of verbatim into the log
+  // stream (a newline-bearing name could otherwise forge whole log lines).
+  // JSON.stringify only escapes C0 controls (U+0000–U+001F) plus quote and
+  // backslash: C1 controls (U+007F–U+009F — including U+009B, the one-byte
+  // CSI that starts ANSI sequences on its own) and the JS line separators
+  // U+2028/U+2029 pass through raw, so escape those ourselves.
+  const printable = (name: string): string =>
+    JSON.stringify(name).replace(
+      /[\u007F-\u009F\u2028\u2029]/g,
+      (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`,
+    );
+  for (const group of sorted) {
+    const reason = unsafeNameReason(group.displayName);
+    if (reason) {
+      warnings.push(`group ${printable(group.displayName)} skipped: ${reason} — rename it in the IdP`);
+      continue;
+    }
+    const canonical = canonicalRoleName(group.displayName);
+    if (RESERVED_ROLE_NAMES.has(canonical)) {
+      warnings.push(
+        `group ${printable(group.displayName)} skipped: '${canonical}' is a reserved name — rename it in the IdP`,
+      );
+      continue;
+    }
+    const existing = byCanonical.get(canonical);
+    if (existing) {
+      warnings.push(
+        `group ${printable(group.displayName)} skipped: name collides with ${printable(existing.displayName)} — rename one in the IdP`,
+      );
+      continue;
+    }
+    byCanonical.set(canonical, group);
+  }
+
+  const lines: string[] = [FILE_HEADER.trimEnd(), 'groups:'];
+  for (const [, group] of byCanonical) {
+    const emails = new Set<string>();
+    let skippedMembers = 0;
+    let malformedMembers = 0;
+    for (const member of group.members) {
+      if (!member.active || !member.email) {
+        skippedMembers++;
+        continue;
+      }
+      // The directory is UNTRUSTED input: a "email" carrying a newline or
+      // entry-grammar characters would corrupt the emitted YAML or inject
+      // memberships. Canonicalize and validate before it may become a line.
+      // A leading '#' passes the regex but the emitted `- #…` reads back as a
+      // comment (stripComment) — the member would silently vanish on the next
+      // resolver read, so refuse it here where it at least gets a warning.
+      // The reserved `group:` prefix passes EMAIL_REGEX (`group:lee@x.io`)
+      // but the read-side parser skips it as a group reference — refuse it
+      // here so the file never carries an entry its own parser warns on.
+      const email = canonicalEmail(member.email);
+      if (!EMAIL_REGEX.test(email) || email.startsWith('#') || email.startsWith(GROUP_REF_PREFIX)) {
+        malformedMembers++;
+        continue;
+      }
+      emails.add(email);
+    }
+    if (skippedMembers > 0) {
+      warnings.push(
+        `group ${printable(group.displayName)}: ${skippedMembers} member${skippedMembers === 1 ? '' : 's'} not materialized (inactive or no email)`,
+      );
+    }
+    if (malformedMembers > 0) {
+      warnings.push(
+        `group ${printable(group.displayName)}: ${malformedMembers} member${malformedMembers === 1 ? '' : 's'} not materialized (malformed email)`,
+      );
+    }
+    const name = group.displayName.trim();
+    if (emails.size === 0) {
+      lines.push(`  ${name}: []`);
+    } else {
+      lines.push(`  ${name}:`);
+      for (const email of [...emails].sort(codeUnitCompare)) lines.push(`    - ${email}`);
+    }
+  }
+
+  return { text: lines.join('\n') + '\n', warnings, groupCount: byCanonical.size };
+}
+
+export interface SyncedGroupsWriteResult {
+  /** False when the rendered content matched what is already committed. */
+  changed: boolean;
+  groupCount: number;
+  warnings: string[];
+}
+
+export interface SyncedGroupsWriterDeps {
+  source: SyncedGroupsSource;
+  /** Current committed file content, or null when it does not exist yet. */
+  readCurrent: () => Promise<string | null>;
+  /** Write + commit the new content (the composition root owns the git plumbing). */
+  persist: (content: string) => Promise<void>;
+  /** Post-commit hook: cache invalidation + change events. */
+  onWritten?: (result: SyncedGroupsWriteResult) => void;
+  /** Trailing-edge debounce for provisioning bursts. */
+  debounceMs?: number;
+  log?: (message: string) => void;
+}
+
+const DEFAULT_DEBOUNCE_MS = 10_000;
+
+export class SyncedGroupsWriter {
+  private timer: NodeJS.Timeout | null = null;
+  /** Serializes writes: a mutation landing mid-write queues one follow-up. */
+  private inflight: Promise<SyncedGroupsWriteResult> | null = null;
+  private rerunWanted = false;
+
+  constructor(private readonly deps: SyncedGroupsWriterDeps) {}
+
+  /**
+   * Note a directory mutation; (re)arm the debounce timer. Called on every
+   * successful ingress/degress, so a provisioning burst keeps pushing the
+   * timer and the write lands once, after the burst goes quiet.
+   */
+  notifyMutation(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.writeNow().catch((err) => {
+        this.deps.log?.(
+          `[directory-sync] deferred synced-groups write failed: ${err instanceof Error ? err.message : err}`,
+        );
+      });
+    }, this.deps.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+    // Never hold the process open for a pending materialization.
+    this.timer.unref?.();
+  }
+
+  /** Render + commit immediately, skipping the debounce. Today only the
+      debounce timer calls this; it is public so a future manual "sync now"
+      surface can reuse it without changing the writer. */
+  async writeNow(): Promise<SyncedGroupsWriteResult> {
+    if (this.inflight) {
+      // A write is running against a snapshot that may predate this call —
+      // ask for one follow-up run and share ITS eventual result semantics by
+      // awaiting the current one first (callers only need "a write covering
+      // my mutation happened"; the follow-up covers it).
+      this.rerunWanted = true;
+      await this.inflight.catch(() => undefined);
+      if (this.inflight) return this.inflight;
+    }
+    this.inflight = this.runOnce();
+    try {
+      let result = await this.inflight;
+      while (this.rerunWanted) {
+        this.rerunWanted = false;
+        this.inflight = this.runOnce();
+        result = await this.inflight;
+      }
+      return result;
+    } finally {
+      this.inflight = null;
+    }
+  }
+
+  private async runOnce(): Promise<SyncedGroupsWriteResult> {
+    const groups = await this.deps.source.listGroups();
+    const rendered = renderSyncedGroupsYaml(groups);
+    for (const w of rendered.warnings) this.deps.log?.(`[directory-sync] ${w}`);
+
+    const current = await this.deps.readCurrent();
+    if (current === rendered.text) {
+      return { changed: false, groupCount: rendered.groupCount, warnings: rendered.warnings };
+    }
+    await this.deps.persist(rendered.text);
+    const result: SyncedGroupsWriteResult = {
+      changed: true,
+      groupCount: rendered.groupCount,
+      warnings: rendered.warnings,
+    };
+    this.deps.onWritten?.(result);
+    return result;
+  }
+
+  /** Cancel any pending debounce (shutdown/tests). */
+  dispose(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+}

package/src/modules/database/core-schema.ts

@@ -211,6 +211,14 @@ export const fileLocks = pgTable('file_locks', {
   path: text('path').notNull(),
   holderUserId: uuid('holder_user_id').notNull().references(() => users.id),
   holderName: text('holder_name').notNull(),
+  // How the lock was acquired. 'edit' (the default) is a normal write hold —
+  // the holder is editing and the release publishes their bytes.
+  // 'coordination' is a pure-mutex hold (see IWorkflowService.acquireLock)
+  // that grants NO write authority. Persisted on the row — not inferred at
+  // release time — so the write/checkpoint/commit-enqueue paths can refuse
+  // to treat a coordination hold as write possession for as long as the row
+  // lives, across process restarts included.
+  mode: text('mode').notNull().default('edit'),
   acquiredAt: timestamp('acquired_at').defaultNow().notNull(),
   lastHeartbeatAt: timestamp('last_heartbeat_at').defaultNow().notNull(),
   expiresAt: timestamp('expires_at').notNull(),
@@ -220,6 +228,7 @@ export const fileLocks = pgTable('file_locks', {
   // table scan once the lock count grows.
   byExpiry: index('file_locks_by_expiry').on(t.expiresAt),
   byHolder: index('file_locks_by_holder').on(t.holderUserId),
+  modeCheck: check('file_locks_mode', sql`${t.mode} IN ('edit', 'coordination')`),
 }));
 
 /**

package/src/modules/mcp/__tests__/mcp-auth.middleware.test.ts

@@ -4,6 +4,7 @@ import { createMcpAuthMiddleware } from '../mcp-auth.middleware.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
 import type { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
 
 const RESOURCE_METADATA_URL = 'https://bevel.example/.well-known/oauth-protected-resource/api/mcp';
 
@@ -64,6 +65,7 @@ function makeMw(
     auth?: AuthService;
     keys?: IExternalApiKeyService;
     oauth?: BevelOAuthProvider;
+    internal?: InternalTokenService;
   } = {},
 ) {
   return createMcpAuthMiddleware(
@@ -71,6 +73,7 @@ function makeMw(
     overrides.keys ?? makeExternalApiKeyService(),
     overrides.oauth ?? makeOAuthProvider(),
     RESOURCE_METADATA_URL,
+    overrides.internal ?? new InternalTokenService({ secret: 'test-secret-32-bytes-long-enough!!' }),
   );
 }
 
@@ -246,4 +249,117 @@ describe('createMcpAuthMiddleware', () => {
     expect(status).toHaveBeenCalledWith(401);
     expect(next).not.toHaveBeenCalled();
   });
+
+
+  /**
+   * The internal-token branch: server-minted only (createSession's loopback
+   * bearer, the /mcp/local-token exchange). hexis-mcp's OAuth mode sends one
+   * here when it registers this endpoint as its remote manual — the exact hop
+   * that failed while this surface refused the shape.
+   */
+  describe('internal tokens', () => {
+    const internal = new InternalTokenService({ secret: 'test-secret-32-bytes-long-enough!!' });
+
+    it('accepts a live internal token and resolves the user', async () => {
+      const token = internal.mint({ userId: 'user-7', externalProxy: true }, 60_000);
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      const mw = makeMw({ internal, auth });
+      const { req, res, next } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).toHaveBeenCalled();
+      expect(req.userId).toBe('user-7');
+      expect(req.userEmail).toBe('seven@example.com');
+    });
+
+    it('401s an expired internal token', async () => {
+      const past = new InternalTokenService({
+        secret: 'test-secret-32-bytes-long-enough!!',
+        now: () => Date.now() - 120_000,
+      });
+      const token = past.mint({ userId: 'user-7', externalProxy: true }, 60_000);
+      const mw = makeMw({ internal });
+      const { req, res, next, status } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).not.toHaveBeenCalled();
+      expect(status).toHaveBeenCalledWith(401);
+    });
+
+    it('401s an internal token whose user no longer exists', async () => {
+      const token = internal.mint({ userId: 'ghost', externalProxy: true }, 60_000);
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => null);
+      const mw = makeMw({ internal, auth });
+      const { req, res, next, status } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).not.toHaveBeenCalled();
+      expect(status).toHaveBeenCalledWith(401);
+    });
+
+    /**
+     * Only the externalProxy shape may be an MCP caller. A plain in-process
+     * internal token — the per-run credential the agent factory mints for its
+     * own code-mode client — is a loopback-surface credential, and admitting
+     * it here would let it open an MCP session (createSession would even mint
+     * it a fresh externalProxy bearer, upgrading it).
+     */
+    it('401s a VALID internal token that lacks the externalProxy claim', async () => {
+      const token = internal.mint({ userId: 'user-7' }, 60_000);
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      const mw = makeMw({ internal, auth });
+      const { req, res, next, status } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).not.toHaveBeenCalled();
+      expect(status).toHaveBeenCalledWith(401);
+      // Rejected before any user lookup — the shape alone disqualifies it.
+      expect(auth.getUserById).not.toHaveBeenCalled();
+    });
+
+    /**
+     * `verify` answers null for the invalid cases it can see coming, but a
+     * malformed token of plausible shape can still THROW from inside it
+     * (e.g. `timingSafeEqual` on same-length strings whose byte lengths
+     * differ). That is the caller's bad token — a clean 401, never a 500 or
+     * an unhandled throw.
+     */
+    it('401s — not 500s — when verify throws on a malformed token', async () => {
+      const throwing = {
+        looksLikeInternalToken: (t: string) => t.startsWith('bevel-int_'),
+        verify: () => {
+          throw new RangeError('Input buffers must have the same byte length');
+        },
+      } as unknown as InternalTokenService;
+      const mw = makeMw({ internal: throwing });
+      const { req, res, next, status } = makeReqRes('Bearer bevel-int_bödy.sïg');
+      await mw(req, res, next);
+      expect(next).not.toHaveBeenCalled();
+      expect(status).toHaveBeenCalledWith(401);
+    });
+
+    /**
+     * The real-token spelling of the throw above: a signature of the SAME
+     * string length whose non-ASCII characters change its BYTE length makes
+     * `timingSafeEqual` throw inside the real `verify` — proof the guard is
+     * needed against the genuine service, not only a mock.
+     */
+    it('401s a real token whose forged signature makes verify throw', async () => {
+      const token = internal.mint({ userId: 'user-7', externalProxy: true }, 60_000);
+      const dot = token.lastIndexOf('.');
+      const sig = token.slice(dot + 1);
+      // Same string LENGTH, different byte length: 'é' is two UTF-8 bytes.
+      const forged = `${token.slice(0, dot + 1)}é${sig.slice(1)}`;
+      const mw = makeMw({ internal });
+      const { req, res, next, status } = makeReqRes(`Bearer ${forged}`);
+      await mw(req, res, next);
+      expect(next).not.toHaveBeenCalled();
+      expect(status).toHaveBeenCalledWith(401);
+    });
+  });
 });

package/src/modules/mcp/__tests__/mcp.e2e.test.ts

@@ -82,7 +82,9 @@ async function connectClient(): Promise<Client> {
     publicFrontendUrl: 'http://localhost:5173',
   });
   const stub = {} as never;
-  app.use('/api', createMcpRoutes(mcpService, stub, fakeAuth, fakeAuth, stub));
+  // local-token deps (internal tokens / OAuth provider / metadata URL) are only
+  // dereferenced by that route's handler — stubs suffice here.
+  app.use('/api', createMcpRoutes(mcpService, stub, fakeAuth, fakeAuth, stub, stub, stub, ''));
   app.use('/api', createManualRoutes(registry, fakeAuth));
 
   const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/api/mcp`), {

package/src/modules/mcp/__tests__/mcp.routes.delete.test.ts

@@ -41,7 +41,12 @@ async function mountWithRemove(
 
   const app = express();
   app.use(express.json());
-  app.use('/api', createMcpRoutes(mcpService, externalApiKeyService, fakeAuth, fakeAuth, stub));
+  // local-token deps (internal tokens / OAuth provider / metadata URL) are only
+  // dereferenced by that route's handler — stubs suffice here.
+  app.use(
+    '/api',
+    createMcpRoutes(mcpService, externalApiKeyService, fakeAuth, fakeAuth, stub, stub, stub, ''),
+  );
 
   httpServer = await new Promise<HttpServer>((resolve) => {
     const s = app.listen(0, () => resolve(s));