@bevel-software/platform-core-backend 0.1.0

package/src/modules/access/roles-edit.ts

@@ -0,0 +1,248 @@
+/**
+ * Pure parse → edit → re-emit editor for `roles.yaml`.
+ *
+ * WHY re-emit and not a line-splice (cf. `access-splice.ts`): `access-splice.ts`
+ * splices `access.md` line-by-line specifically because those files carry a
+ * markdown BODY below the frontmatter (the repo-root one is a whole README)
+ * that a parse→emit round-trip would silently delete. `roles.yaml` has no body
+ * and no frontmatter fence — it is a plain `roles:` mapping of display-name →
+ * email list — and no real `roles.yaml` in the repo carries comments. So we
+ * parse the file into a model, apply the edit, and re-emit a canonical,
+ * deterministic file. Re-emit is idempotent (re-emitting an unchanged model
+ * yields byte-identical text), so a single edit moves only the lines it
+ * actually changes. The trade-off — hand-written comments are not preserved —
+ * is a documented non-goal.
+ *
+ *   roles:                       (always the top-level key)
+ *     Admin:                     (role display name, indent 2)
+ *       - a@x.eu                 (member email, indent 4)
+ *       - b@x.eu
+ *     Empty Role: []             (the only empty-list form the subset parser
+ *                                  reads back — a bare `Empty Role:` parses to
+ *                                  null and fails parseRolesYaml's list check)
+ *
+ * Every mutation returns `{ text, changed }`; `changed: false` means the edit
+ * was a no-op (e.g. adding a member who already exists) and the caller should
+ * skip the commit. Role ORDER is preserved as parsed; a newly created role is
+ * appended last. Member emails within a role are canonicalised + de-duplicated.
+ *
+ * This module does NOT enforce the Admin-must-exist / no-self-lockout
+ * invariants — those are policy and live in `roles-admin.service.ts`. It only
+ * guarantees the emitted text is structurally well-formed YAML the resolver can
+ * load (the service additionally runs `validateRolesYaml` as a backstop gate).
+ */
+
+import {
+  parseYamlSubset,
+  canonicalRoleName,
+  canonicalEmail,
+  EMAIL_REGEX,
+  RESERVED_ROLE_NAMES,
+} from './access-control.service.js';
+
+/** Bad-input failure when editing roles.yaml (invalid name/email, unknown role). */
+export class RolesEditError extends Error {
+  readonly status: number;
+  constructor(message: string, status = 422) {
+    super(message);
+    this.name = 'RolesEditError';
+    this.status = status;
+  }
+}
+
+/** One role in parse order: display name + its de-duplicated member emails. */
+export interface RoleModel {
+  displayName: string;
+  /** canonicalised, de-duplicated, in first-seen order */
+  members: string[];
+}
+
+export type RolesModel = RoleModel[];
+
+export interface EditResult {
+  text: string;
+  changed: boolean;
+}
+
+/**
+ * Reject role display names whose characters would corrupt the emitted YAML.
+ * `canonicalRoleName` only trims/lowercases/collapses spaces — it does NOT
+ * reject structural characters, so a name like `Sales: West` or `#temp` would
+ * round-trip into a broken file. This guard is the structural complement to the
+ * reserved/duplicate checks the service layer applies.
+ *
+ *   `:`        mis-tokenises as a nested mapping key
+ *   `#`        truncated as a comment by the subset parser's stripComment
+ *   `<` / `>`  collide with the `Name <email>` user-reference shape
+ *   leading -  tokenises as a list item
+ *   \x00-\x1f  control chars / newlines break line structure outright
+ */
+export function assertSafeRoleDisplayName(displayName: string): void {
+  const trimmed = displayName.trim();
+  if (!trimmed) throw new RolesEditError('role name must not be empty');
+  if (/[:#<>]/.test(trimmed)) {
+    throw new RolesEditError(`role name must not contain ':', '#', '<', or '>': ${JSON.stringify(displayName)}`);
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1f]/.test(trimmed)) {
+    throw new RolesEditError(`role name must not contain control characters: ${JSON.stringify(displayName)}`);
+  }
+  if (trimmed.startsWith('-')) {
+    throw new RolesEditError(`role name must not start with '-': ${JSON.stringify(displayName)}`);
+  }
+}
+
+/**
+ * Parse `roles.yaml` text into the ordered model. Tolerant of an empty/missing
+ * file (yields `[]`). Throws RolesEditError on structurally-broken YAML — the
+ * caller reads under the lock, so a broken on-disk file is an operator problem
+ * surfaced as a 422, not a silent reset.
+ */
+export function parseRolesModel(text: string): RolesModel {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  const parsed = parseYamlSubset(text);
+  if (!parsed.ok) throw new RolesEditError(`roles.yaml: ${parsed.error}`);
+  const root = parsed.value;
+  if (root == null || typeof root !== 'object' || Array.isArray(root)) {
+    throw new RolesEditError('roles.yaml: must be a top-level mapping');
+  }
+  const rolesNode = (root as Record<string, unknown>).roles;
+  if (rolesNode == null) return [];
+  if (typeof rolesNode !== 'object' || Array.isArray(rolesNode)) {
+    throw new RolesEditError("roles.yaml: 'roles' must be a mapping");
+  }
+  const model: RolesModel = [];
+  for (const [displayName, value] of Object.entries(rolesNode as Record<string, unknown>)) {
+    const members: string[] = [];
+    // A role value must be a list of emails, an empty list (`[]`), or null
+    // (`Role:` with no members). Any OTHER shape (a scalar string, a nested
+    // mapping) is a malformed file — surface it as the documented 422 rather
+    // than silently coercing it to an empty role (CodeRabbit: a coerce would
+    // let an unrelated edit rewrite a broken roles.yaml).
+    if (value !== null && !Array.isArray(value)) {
+      throw new RolesEditError(`roles.yaml: role '${displayName.trim()}' must be a list of emails`);
+    }
+    if (Array.isArray(value)) {
+      const seen = new Set<string>();
+      for (const raw of value) {
+        // A non-string member entry is malformed — reject, don't drop.
+        if (typeof raw !== 'string') {
+          throw new RolesEditError(`roles.yaml: role '${displayName.trim()}' has a non-string member`);
+        }
+        const email = canonicalEmail(raw);
+        if (!email || seen.has(email)) continue;
+        seen.add(email);
+        members.push(email);
+      }
+    }
+    model.push({ displayName: displayName.trim(), members });
+  }
+  return model;
+}
+
+/**
+ * Re-emit the model as canonical `roles.yaml` text. Deterministic: same model →
+ * same bytes. An empty role is emitted as `Name: []` (round-trippable); a role
+ * with members is emitted as a block list. Always ends with a trailing newline.
+ */
+export function emitRolesModel(model: RolesModel): string {
+  const lines: string[] = ['roles:'];
+  for (const role of model) {
+    if (role.members.length === 0) {
+      lines.push(`  ${role.displayName}: []`);
+    } else {
+      lines.push(`  ${role.displayName}:`);
+      for (const email of role.members) lines.push(`    - ${email}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+function findRole(model: RolesModel, canonical: string): RoleModel | undefined {
+  return model.find((r) => canonicalRoleName(r.displayName) === canonical);
+}
+
+function reemit(original: string, model: RolesModel): EditResult {
+  const text = emitRolesModel(model);
+  // Compare against a re-emit of the ORIGINAL so a pure formatting difference
+  // (e.g. legacy spacing) doesn't masquerade as a content change — `changed`
+  // tracks whether the canonical model moved, which is what the commit cares
+  // about.
+  let originalCanonical: string;
+  try {
+    originalCanonical = emitRolesModel(parseRolesModel(original));
+  } catch {
+    originalCanonical = original;
+  }
+  return { text, changed: text !== originalCanonical };
+}
+
+/** Create a new empty role. 422 on reserved/duplicate/structurally-unsafe name. */
+export function createRole(text: string, displayName: string): EditResult {
+  assertSafeRoleDisplayName(displayName);
+  const canonical = canonicalRoleName(displayName);
+  if (RESERVED_ROLE_NAMES.has(canonical)) {
+    throw new RolesEditError(`'${displayName.trim()}' is a reserved name and cannot be a role`);
+  }
+  const model = parseRolesModel(text);
+  if (findRole(model, canonical)) {
+    throw new RolesEditError(`a role named '${displayName.trim()}' already exists`);
+  }
+  model.push({ displayName: displayName.trim(), members: [] });
+  return reemit(text, model);
+}
+
+/** Delete a role by canonical name. 404 if absent. */
+export function deleteRole(text: string, canonical: string): EditResult {
+  const model = parseRolesModel(text);
+  const idx = model.findIndex((r) => canonicalRoleName(r.displayName) === canonical);
+  if (idx < 0) throw new RolesEditError(`role not found: ${canonical}`, 404);
+  model.splice(idx, 1);
+  return reemit(text, model);
+}
+
+/** Add a member email to a role. Idempotent. 422 bad email; 404 unknown role. */
+export function addMember(text: string, canonical: string, rawEmail: string): EditResult {
+  const email = canonicalEmail(rawEmail);
+  if (!EMAIL_REGEX.test(email)) throw new RolesEditError(`malformed email: ${JSON.stringify(rawEmail)}`);
+  const model = parseRolesModel(text);
+  const role = findRole(model, canonical);
+  if (!role) throw new RolesEditError(`role not found: ${canonical}`, 404);
+  if (role.members.includes(email)) return { text: emitRolesModel(model), changed: false };
+  role.members.push(email);
+  return reemit(text, model);
+}
+
+/** Remove a member email from a role. 404 unknown role; no-op if not a member. */
+export function removeMember(text: string, canonical: string, rawEmail: string): EditResult {
+  const email = canonicalEmail(rawEmail);
+  const model = parseRolesModel(text);
+  const role = findRole(model, canonical);
+  if (!role) throw new RolesEditError(`role not found: ${canonical}`, 404);
+  const idx = role.members.indexOf(email);
+  if (idx < 0) return { text: emitRolesModel(model), changed: false };
+  role.members.splice(idx, 1);
+  return reemit(text, model);
+}
+
+/**
+ * Rename a role's display name. The canonical name MAY change (the service
+ * layer is responsible for the reference rewrite + Admin guard when it does).
+ * 404 unknown source; 422 reserved/duplicate/unsafe target.
+ */
+export function renameRoleDisplay(text: string, canonical: string, newDisplayName: string): EditResult {
+  assertSafeRoleDisplayName(newDisplayName);
+  const newCanonical = canonicalRoleName(newDisplayName);
+  if (RESERVED_ROLE_NAMES.has(newCanonical)) {
+    throw new RolesEditError(`'${newDisplayName.trim()}' is a reserved name and cannot be a role`);
+  }
+  const model = parseRolesModel(text);
+  const role = findRole(model, canonical);
+  if (!role) throw new RolesEditError(`role not found: ${canonical}`, 404);
+  if (newCanonical !== canonical && findRole(model, newCanonical)) {
+    throw new RolesEditError(`a role named '${newDisplayName.trim()}' already exists`);
+  }
+  role.displayName = newDisplayName.trim();
+  return reemit(text, model);
+}

package/src/modules/access/roles-yaml-guard.ts

@@ -0,0 +1,89 @@
+/**
+ * Pre-disk validity gate for `roles.yaml`.
+ *
+ * WHY this exists: `roles.yaml` is the single point of failure for the whole
+ * app. The runtime resolver's `loadModel` HARD-THROWS `AccessConfigError` on a
+ * parse failure, and `isAdmin` swallows that into `false` for EVERYONE — so a
+ * single malformed `roles.yaml` is an app-wide, in-app-unrecoverable admin
+ * lockout. The dedicated Roles & Members service already validates every
+ * candidate before writing (`assertLoadable`), but the two RAW write paths do
+ * not:
+ *   - the human editor save  (`PUT /workspace/:id/file`)
+ *   - the agent's file tools (`LockingFilesystem.writeFile` / `writeFiles`)
+ *
+ * Both of those let an admin (or an admin-driven agent) commit a broken file.
+ * This guard plugs them: it runs the resolver's OWN parser on the candidate
+ * BEFORE a byte hits disk, and refuses the write with a 422 on any error. A
+ * write that passes here is loadable by `loadModel`, so the lockout becomes
+ * structurally unreachable through normal edits.
+ *
+ * The break-glass recovery path (for a file that got broken some OTHER way —
+ * a direct git push, a pre-guard commit) lives in `roles-admin.service.ts`.
+ */
+
+import type { FileContent } from '@mastra/core/workspace';
+import { parseRolesYaml } from './access-control.service.js';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+
+/** Repo-relative basename of the roles file (it lives at the KB repo root). */
+export const ROLES_YAML_BASENAME = 'roles.yaml';
+
+/**
+ * A raw write whose candidate `roles.yaml` would not parse. 422 (bad input) —
+ * the edit is refused and nothing is written. Carries the parser errors so the
+ * editor / agent can show exactly what's wrong.
+ */
+export class RolesYamlInvalidError extends WorkflowDomainError {
+  readonly errors: string[];
+  constructor(errors: string[]) {
+    super(
+      `roles.yaml would be invalid and was not saved: ${errors.join('; ')}`,
+      422,
+      { kind: 'roles-yaml-invalid', rolesYamlErrors: errors },
+    );
+    this.name = 'RolesYamlInvalidError';
+    this.errors = errors;
+  }
+}
+
+/** Normalise a workspace-relative path: backslashes → `/`, strip a leading `./`. */
+function normalizeWsPath(p: string): string {
+  return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/**
+ * True iff `workspaceRelPath` targets the KB's `roles.yaml` (the file at
+ * `<kbDirName>/roles.yaml`). Both the human save route and the agent's
+ * `LockingFilesystem` speak workspace-relative paths, so this is the form we
+ * key on. A bare `roles.yaml` (no KB prefix) is also accepted defensively.
+ */
+export function isRolesYamlPath(workspaceRelPath: string, kbDirName: string): boolean {
+  const norm = normalizeWsPath(workspaceRelPath);
+  return norm === `${kbDirName}/${ROLES_YAML_BASENAME}` || norm === ROLES_YAML_BASENAME;
+}
+
+/**
+ * Throw {@link RolesYamlInvalidError} if `content` does not parse as a valid
+ * `roles.yaml` per the resolver's own parser. No-op on valid content.
+ */
+export function assertRolesYamlParsable(content: string): void {
+  const parsed = parseRolesYaml(content);
+  if (!parsed.ok) throw new RolesYamlInvalidError(parsed.errors);
+}
+
+/**
+ * A `LockingFilesystem` write-validator scoped to a KB dir: refuses a raw write
+ * that would leave `roles.yaml` unparseable. Pass the returned closure as the
+ * filesystem's `validateWrite` hook. Only string writes are checked — every
+ * code path that writes `roles.yaml` writes it as text; a binary write to that
+ * path is nonsensical and left alone.
+ */
+export function makeRolesYamlWriteValidator(
+  kbDirName: string,
+): (path: string, content: FileContent) => void {
+  return (path, content) => {
+    if (typeof content !== 'string') return;
+    if (!isRolesYamlPath(path, kbDirName)) return;
+    assertRolesYamlParsable(content);
+  };
+}

package/src/modules/admin/admin-access.routes.ts

@@ -0,0 +1,29 @@
+import express from 'express';
+import type { IAdminAccessService } from './admin.interface.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+/**
+ * The CORE slice of the admin surface: just the admin-status resolver the
+ * frontend branches on (AdminMenu's "Admin only" section, the roles-recovery
+ * banner). The full admin router (feedback inbox, user administration /
+ * GDPR erasure) is an enterprise extension mounted via
+ * `ServerExtensions.authed`.
+ *
+ * NOTE (core split): in bevel-platform this endpoint lives in the enterprise
+ * `admin.routes.ts`; core serves it itself so a core-only deployment can
+ * resolve admin status. Express keeps first-match-wins, so an enterprise
+ * overlay's own `/admin/access` (mounted later) never shadows this one —
+ * both resolve through the same {@link IAdminAccessService}.
+ */
+export function createAdminAccessRoutes(adminAccess: IAdminAccessService): express.Router {
+  const router = express.Router();
+
+  // Open to any authenticated user — returns `false` for non-admins instead of
+  // 403 so the frontend can branch on the answer without treating a normal
+  // user as an error case.
+  router.get('/admin/access', async (req, res) => {
+    res.json({ isAdmin: await adminAccess.isAdmin(req.userEmail) });
+  });
+
+  return router;
+}

package/src/modules/admin/admin-access.service.ts

@@ -0,0 +1,38 @@
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { type WorkspaceService, workspaceIdForBranch } from '../workspace/workspace.service.js';
+import type { IAdminAccessService } from './admin.interface.js';
+
+/**
+ * Admin = holder of the `Admin` role in `roles.yaml`. We resolve it through the
+ * access model exactly as the rest of the app does — `canWrite('roles.yaml')` is
+ * the existing source of truth for Admin-role membership (only admins may write
+ * `roles.yaml`). Read from the default-branch workspace so admin status doesn't
+ * depend on whichever branch the caller happens to be on.
+ *
+ * There is no env allow-list (`ADMIN_EMAILS` is gone) — `roles.yaml` is the
+ * single source of truth.
+ */
+export class AdminAccessService implements IAdminAccessService {
+  constructor(
+    private readonly accessControl: IAccessControl,
+    private readonly workspaceService: WorkspaceService,
+    /** Branch whose `roles.yaml` defines admins (the authoritative default branch). */
+    private readonly branch: string,
+  ) {}
+
+  async isAdmin(email: string | undefined): Promise<boolean> {
+    if (!email) return false;
+    try {
+      // Ensure the authoritative clone is on disk, then resolve Admin-role
+      // membership via the access model. Any failure (missing/invalid
+      // roles.yaml, clone error) resolves to "not admin" — the safe default.
+      await this.workspaceService.getOrCreateForBranch(this.branch);
+      return await this.accessControl.canWrite(workspaceIdForBranch(this.branch), email, 'roles.yaml');
+    } catch (err) {
+      // Log so an admin lockout caused by a clone / roles.yaml failure is
+      // diagnosable rather than a silent denial.
+      console.warn('[admin] isAdmin resolution failed:', err instanceof Error ? err.message : String(err));
+      return false;
+    }
+  }
+}

package/src/modules/admin/admin.interface.ts

@@ -0,0 +1,10 @@
+/**
+ * Contract for the deployment admin check. A user is an admin iff they hold the
+ * `Admin` role in the KB's `roles.yaml` — the same source of truth the access
+ * model uses for `canWrite('roles.yaml')`. Async because resolving it reads the
+ * access model from the default-branch workspace. Kept as an interface so tests
+ * can swap a static stub without loading the access tree.
+ */
+export interface IAdminAccessService {
+  isAdmin(email: string | undefined): Promise<boolean>;
+}

package/src/modules/auth/account-erasure.service.ts

@@ -0,0 +1,183 @@
+import { randomUUID } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import type { Database } from '../database/connection.js';
+import {
+  changeRequests,
+  externalApiKeys,
+  fileLocks,
+  oauthAuthCodes,
+  oauthTokens,
+  pendingCommits,
+  prComments,
+  prFileApprovals,
+  prMergeLog,
+  users,
+} from '../database/schema.js';
+
+/** A user row as the admin surface needs it (no avatar, no timestamps churn). */
+export interface AdminUserView {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: number;
+}
+
+/** The drizzle client erasure participants receive inside the transaction. */
+export type ErasureTx = Parameters<Parameters<Database['transaction']>[0]>[0];
+
+/** Identity context for one erasure run. */
+export interface ErasureTarget {
+  userId: string;
+  /** The user's (lowercased) email at erasure time — for email-keyed rows. */
+  email: string;
+  /**
+   * Per-erasure placeholder identity for anonymized audit rows. Random per
+   * erasure: no link back to the person, but rows from ONE erasure stay
+   * correlated and email-keyed unique indexes can't collide across erasures.
+   */
+  erasedEmail: string;
+  erasedName: string;
+}
+
+/**
+ * A module-owned slice of account erasure. The core service erases the rows
+ * it owns (tokens, locks, review-trail anonymization, the user row) and runs
+ * every registered participant so each module cleans up its own tables —
+ * chat threads, connector links, routine authorship, … — without the auth
+ * module knowing they exist. Registered at the composition root.
+ *
+ *  - `before` runs OUTSIDE the transaction, first. For idempotent pre-cleanup
+ *    against external stores (e.g. chat-thread message memory) where a failure
+ *    must leave a retryable state, not a half-committed one.
+ *  - `inTransaction` runs INSIDE the erasure transaction, BEFORE the users row
+ *    is deleted (so FKs onto users are still satisfiable and RESTRICT FKs make
+ *    missed rows fail loudly). It may return a callback, which runs after the
+ *    transaction commits — for external-store cleanup of rows captured during
+ *    the transaction.
+ */
+export interface IErasureParticipant {
+  before?(target: ErasureTarget): Promise<void>;
+  inTransaction?(tx: ErasureTx, target: ErasureTarget): Promise<void | (() => Promise<void>)>;
+}
+
+/**
+ * GDPR account erasure (Art. 17). Operator-driven: an admin deletes a user in
+ * response to an erasure request. What it guarantees:
+ *
+ *  - Rows that ARE the user's personal data are hard-deleted: API/OAuth
+ *    tokens, held file locks, the user row itself, and every registered
+ *    participant's module-owned rows (chat threads incl. message memory,
+ *    Microsoft connection, feedback, revalidation requests, upload tokens).
+ *    Deleting the user row cascades whatever FKs onto it with ON DELETE
+ *    CASCADE (account links, watchlist sources/findings, connector configs,
+ *    vault secrets); deleting a connection key cascades its usage metering.
+ *  - Audit rows that must survive for the review trail (approvals, merge log,
+ *    review comments, change requests, queued commits — and, via participants,
+ *    e.g. routine authorship) are kept but ANONYMIZED with the per-erasure
+ *    placeholder identity.
+ *
+ * Out of scope, by firm policy (disclosed in the DPA): git history is never
+ * rewritten. Commit authorship and historical access-file entries stay in the
+ * KB's version history permanently as part of the tamper-evident record;
+ * erasure covers every database/filesystem store plus the CURRENT KB state.
+ *
+ * Note: sign-in is get-or-create by email, so a person who authenticates again
+ * after erasure simply gets a fresh, empty account — that is intended.
+ */
+export interface IAccountErasureService {
+  listUsers(): Promise<AdminUserView[]>;
+  /** Erase `userId`. Returns false when no such user exists. */
+  eraseUser(userId: string): Promise<boolean>;
+}
+
+export class AccountErasureService implements IAccountErasureService {
+  constructor(
+    private readonly db: Database,
+    private readonly participants: IErasureParticipant[] = [],
+  ) {}
+
+  async listUsers(): Promise<AdminUserView[]> {
+    const rows = await this.db
+      .select({ id: users.id, email: users.email, name: users.name, createdAt: users.createdAt })
+      .from(users)
+      .orderBy(users.email);
+    return rows.map((r) => ({ ...r, createdAt: r.createdAt.getTime() }));
+  }
+
+  async eraseUser(userId: string): Promise<boolean> {
+    const [user] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!user) return false;
+
+    const target: ErasureTarget = {
+      userId,
+      email: user.email.toLowerCase(),
+      erasedEmail: `deleted-${randomUUID()}@erased.invalid`,
+      erasedName: 'Deleted user',
+    };
+
+    // Participant pre-passes (e.g. chat threads + their Mastra memory) run
+    // outside the transaction on purpose: external stores are separate
+    // systems, and the pre-passes are idempotent, so a failure here leaves a
+    // retryable state rather than a half-committed one.
+    for (const p of this.participants) {
+      if (p.before) await p.before(target);
+    }
+
+    const postCommit: Array<() => Promise<void>> = [];
+    await this.db.transaction(async (tx) => {
+      // Token-shaped rows (all hashed, but they key to the user). Dependents
+      // like the LLM-usage metering rows cascade at the DB layer.
+      await tx.delete(externalApiKeys).where(eq(externalApiKeys.userId, userId));
+      await tx.delete(oauthAuthCodes).where(eq(oauthAuthCodes.userId, userId));
+      await tx.delete(oauthTokens).where(eq(oauthTokens.userId, userId));
+
+      // Personal-data rows the core owns.
+      await tx.delete(fileLocks).where(eq(fileLocks.holderUserId, userId));
+
+      // Audit rows: anonymize in place (no user FK on these; they key by email).
+      await tx
+        .update(prFileApprovals)
+        .set({ approverEmail: target.erasedEmail, approverName: target.erasedName })
+        .where(eq(prFileApprovals.approverEmail, target.email));
+      await tx
+        .update(prMergeLog)
+        .set({ triggeredByEmail: target.erasedEmail, triggeredByName: target.erasedName })
+        .where(eq(prMergeLog.triggeredByEmail, target.email));
+      await tx
+        .update(prComments)
+        .set({ authorEmail: target.erasedEmail, authorName: target.erasedName })
+        .where(eq(prComments.authorEmail, target.email));
+      await tx
+        .update(changeRequests)
+        .set({ authorEmail: target.erasedEmail, authorName: target.erasedName })
+        .where(eq(changeRequests.authorEmail, target.email));
+      // Queued-but-uncommitted saves: the eventual git commit is authored with
+      // the placeholder instead of the erased identity. The file content still
+      // lands — erasing an account must not lose other people's KB state.
+      await tx
+        .update(pendingCommits)
+        .set({ authorEmail: target.erasedEmail, authorName: target.erasedName })
+        .where(eq(pendingCommits.authorEmail, target.email));
+
+      // Module-owned rows, before the users delete so FKs onto users are
+      // still satisfiable — and so a participant that MISSES rows makes the
+      // users delete below fail on its RESTRICT FK, rolling everything back:
+      // a loud retry, never a silent orphan.
+      for (const p of this.participants) {
+        if (!p.inTransaction) continue;
+        const cb = await p.inTransaction(tx, target);
+        if (cb) postCommit.push(cb);
+      }
+
+      // Finally the user row (plus its ON DELETE CASCADE dependents).
+      await tx.delete(users).where(eq(users.id, userId));
+    });
+
+    // Post-commit callbacks (e.g. Mastra memory cleanup for chat threads
+    // captured inside the transaction).
+    for (const cb of postCommit) await cb();
+
+    console.log(`[account-erasure] erased user id=${userId}`);
+    return true;
+  }
+}

package/src/modules/auth/auth.middleware.ts

@@ -0,0 +1,78 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { AuthService } from './auth.service.js';
+
+// Augment Express Request so userId/userEmail are available after auth middleware
+declare global {
+  namespace Express {
+    interface Request {
+      userId?: string;
+      userEmail?: string;
+    }
+  }
+}
+
+/**
+ * Name of the auth cookie set alongside the Bearer JWT at login. The cookie
+ * exists solely so the SSE route can authenticate — the browser's
+ * `EventSource` API can't set custom headers, so a Bearer token in
+ * `Authorization` can't reach it. All other routes still use the Bearer
+ * header, which the frontend stores in memory and attaches via `authFetch`.
+ *
+ * Same JWT value as the Bearer token. The cookie is `HttpOnly` + `SameSite=Lax`
+ * + `Secure` (in prod) — see `auth.routes.ts` for the issue site.
+ */
+export const AUTH_COOKIE_NAME = 'bevel_token';
+
+/**
+ * Read the auth cookie out of the raw `Cookie` header without pulling in
+ * `cookie-parser`. We only ever look for one cookie, so a tiny parser
+ * beats the dep surface of a middleware. Returns `null` if the cookie
+ * is absent or empty.
+ */
+function readAuthCookie(req: Request): string | null {
+  const header = req.headers.cookie;
+  if (!header) return null;
+  for (const segment of header.split(';')) {
+    const trimmed = segment.trim();
+    if (!trimmed.startsWith(`${AUTH_COOKIE_NAME}=`)) continue;
+    const value = trimmed.slice(AUTH_COOKIE_NAME.length + 1);
+    if (!value) return null;
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+  return null;
+}
+
+export function createAuthMiddleware(authService: AuthService) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Bearer is the primary path — every JSON API call in the frontend
+    // attaches it via `authFetch`. Cookie is the fallback for transports
+    // that can't carry headers (EventSource, image tags), set at login by
+    // `/auth/login` so SSE in particular Just Works after login without
+    // any frontend cooperation.
+    const header = req.headers.authorization;
+    let token: string | null = null;
+    if (header && header.startsWith('Bearer ')) {
+      token = header.slice('Bearer '.length).trim() || null;
+    }
+    if (!token) {
+      token = readAuthCookie(req);
+    }
+    if (!token) {
+      res.status(401).json({ error: 'Missing or invalid Authorization header or auth cookie' });
+      return;
+    }
+
+    try {
+      const { userId, email } = authService.verifyToken(token);
+      req.userId = userId;
+      req.userEmail = email;
+      next();
+    } catch {
+      res.status(401).json({ error: 'Invalid or expired token' });
+    }
+  };
+}