@bevel-software/platform-core-backend 0.4.0 → 0.5.0

package/src/modules/access/access-declarations.ts

@@ -0,0 +1,251 @@
+import type { FileTreeEntry, IWorkspaceService } from '@bevel-software/platform-shared';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { accessMdPathForFolder } from './access-mutation.service.js';
+import {
+  EVERYONE_CANONICAL,
+  KNOWN_VERBS,
+  parseAccessFile,
+  parseOwnAccessEntries,
+  type ParsedEntry,
+  type Verb,
+} from './access-control.service.js';
+
+/**
+ * WHERE access rules are DECLARED inside a folder — a read-only inventory, not
+ * a second resolver.
+ *
+ * A group's `access.md` is never the whole story: resolution is closeness-first,
+ * so a rule written on a single skill or `.tool` inside the folder overrides the
+ * folder's rule for the principals it names. An admin looking at a group's share
+ * list and seeing "GTM Team can read" would otherwise have no way to know that
+ * one battlecard underneath says `deny read: everyone`.
+ *
+ * So this module answers exactly one question — *which files declare access
+ * rules under here, and what do they say* — and it answers it with the SAME
+ * parsers the resolver builds its model from (`parseAccessFile` for `access.md`,
+ * `parseOwnAccessEntries` for node frontmatter). Nothing here decides whether
+ * anybody can do anything; it reports declarations verbatim. That is the whole
+ * reason it can exist without touching `IAccessControl`, which enterprise
+ * implements: a display of the stored rules cannot drift from the rules that
+ * are enforced, because it is reading the same bytes through the same parse.
+ */
+
+/** A principal named by a declaration, in wire form. */
+export type DeclarationPrincipal =
+  | { kind: 'role'; role: string }
+  | { kind: 'user'; email: string; name: string }
+  | { kind: 'everyone' };
+
+/** One `verb: principal` line of a declaration, deny-prefix preserved. */
+export interface DeclarationEntry {
+  verb: Verb;
+  /** True when the line carried the literal `deny ` prefix. */
+  deny: boolean;
+  principal: DeclarationPrincipal;
+}
+
+export interface AccessDeclaration {
+  /** Repo-relative path of the file that DECLARES the rules. */
+  path: string;
+  /**
+   * Repo-relative path the rules GOVERN: the containing directory for an
+   * `access.md`, the file itself for node frontmatter. Distinct from `path`
+   * because that is what a reader needs to recognise ("the battlecards
+   * folder"), and what the caller read-filters rows on.
+   */
+  governs: string;
+  source: 'access-md' | 'frontmatter';
+  entries: DeclarationEntry[];
+  /**
+   * Set (with `entries: []`) when an `access.md` failed to parse. Surfaced
+   * rather than swallowed: a broken rule file is exactly the thing somebody
+   * managing access has to be told about, and the resolver's forgiveness makes
+   * it invisible everywhere else.
+   */
+  parseError?: string;
+}
+
+/**
+ * How many files one scan will read. A group folder is small by construction;
+ * this cap exists so a pathological folder (a whole ontology moved under
+ * `Groups/`) degrades into an honest partial answer instead of pinning the
+ * event loop. Callers surface `truncated` to the user.
+ */
+export const DECLARATION_SCAN_FILE_CAP = 400;
+
+/** 400 for a target that is not a folder. */
+export class AccessDeclarationsError extends WorkflowDomainError {
+  constructor(message: string, status = 400) {
+    super(message, status);
+    this.name = 'AccessDeclarationsError';
+  }
+}
+
+/** Node files whose own frontmatter may declare verbs. */
+function isNodeCandidate(name: string): boolean {
+  return name.endsWith('.md') || name.endsWith('.tool');
+}
+
+/** Walk a workspace-relative path down the file tree; null when absent. */
+function findNode(root: FileTreeEntry, wsRelPath: string): FileTreeEntry | null {
+  if (wsRelPath === '') return root;
+  let node: FileTreeEntry = root;
+  for (const segment of wsRelPath.split('/').filter(Boolean)) {
+    const next = node.children?.find((c) => c.name === segment);
+    if (!next) return null;
+    node = next;
+  }
+  return node;
+}
+
+interface Candidate {
+  /** Repo-relative path of the declaring file. */
+  repoRel: string;
+  /** Workspace-relative path, i.e. what `readFile` takes. */
+  wsPath: string;
+  isAccessMd: boolean;
+}
+
+function collectCandidates(node: FileTreeEntry, kbPrefix: string, out: Candidate[]): void {
+  for (const child of node.children ?? []) {
+    if (child.type === 'directory') {
+      collectCandidates(child, kbPrefix, out);
+      continue;
+    }
+    const isAccessMd = child.name === 'access.md';
+    if (!isAccessMd && !isNodeCandidate(child.name)) continue;
+    if (!child.relativePath.startsWith(kbPrefix)) continue;
+    out.push({
+      repoRel: child.relativePath.slice(kbPrefix.length),
+      wsPath: child.relativePath,
+      isAccessMd,
+    });
+  }
+}
+
+/** The directory a `<dir>/access.md` governs (`''` for the repo root's own). */
+function dirOf(repoRelPath: string): string {
+  const slash = repoRelPath.lastIndexOf('/');
+  return slash === -1 ? '' : repoRelPath.slice(0, slash);
+}
+
+/**
+ * `ParsedEntry` → wire principal. The canonical built-in `everyone` role
+ * becomes its own kind rather than a role named "everyone": it is not a
+ * roles.yaml role, it has no members to look up, and the UI says "Everyone"
+ * about it — collapsing it here keeps that decision out of three renderers.
+ */
+function toPrincipal(entry: ParsedEntry): DeclarationPrincipal {
+  if (entry.kind === 'user') {
+    return { kind: 'user', email: entry.email, name: entry.displayName };
+  }
+  if (entry.role === EVERYONE_CANONICAL) return { kind: 'everyone' };
+  return { kind: 'role', role: entry.displayRole };
+}
+
+/** Flatten a per-verb entry map into wire entries, verb order then file order. */
+function toEntries(byVerb: Record<Verb, ParsedEntry[]>): DeclarationEntry[] {
+  const out: DeclarationEntry[] = [];
+  for (const verb of KNOWN_VERBS) {
+    for (const entry of byVerb[verb] ?? []) {
+      out.push({ verb, deny: entry.deny, principal: toPrincipal(entry) });
+    }
+  }
+  return out;
+}
+
+/**
+ * Every access declaration living INSIDE `folderRepoRel`.
+ *
+ * The folder's own `access.md` is deliberately excluded — that file is the
+ * folder's summary, already shown as the main share list, and repeating it in a
+ * list headed "item-specific rules" would read as a contradiction of itself.
+ *
+ * Failure modes are asymmetric on purpose, matching the resolver: a node whose
+ * frontmatter is malformed is skipped silently (a typo in a skill's `owner:`
+ * must not make the group's access page unreadable), while a malformed
+ * `access.md` is REPORTED with its `parseError` (that file was written to
+ * control access and currently controls nothing).
+ *
+ * Throws `AccessDeclarationsError` (400) when the target is a file. A target
+ * that does not exist in the clone yields an empty result — an unmigrated or
+ * not-yet-created folder is a normal state, not an error.
+ */
+export async function listAccessDeclarationsUnder(
+  workspaceService: IWorkspaceService,
+  workspaceId: string,
+  kbDirName: string,
+  folderRepoRel: string,
+): Promise<{ overrides: AccessDeclaration[]; truncated: boolean }> {
+  const tree = await workspaceService.listFiles(workspaceId);
+  const kbPrefix = `${kbDirName}/`;
+  const wsFolderPath = folderRepoRel ? `${kbPrefix}${folderRepoRel}` : kbDirName;
+
+  const node = findNode(tree, wsFolderPath);
+  if (!node) return { overrides: [], truncated: false };
+  if (node.type !== 'directory') {
+    throw new AccessDeclarationsError('path must be a folder');
+  }
+
+  const ownAccessMd = accessMdPathForFolder(folderRepoRel);
+  const candidates: Candidate[] = [];
+  collectCandidates(node, kbPrefix, candidates);
+
+  const scannable = candidates
+    .filter((c) => c.repoRel !== ownAccessMd)
+    .sort((a, b) => (a.repoRel < b.repoRel ? -1 : a.repoRel > b.repoRel ? 1 : 0));
+  const truncated = scannable.length > DECLARATION_SCAN_FILE_CAP;
+  const scanned = truncated ? scannable.slice(0, DECLARATION_SCAN_FILE_CAP) : scannable;
+
+  const rows = await Promise.all(
+    scanned.map(async (candidate): Promise<AccessDeclaration | null> => {
+      let text: string;
+      try {
+        text = await workspaceService.readFile(workspaceId, candidate.wsPath);
+      } catch {
+        // The tree said it was there and the disk disagrees (a concurrent
+        // delete, a broken symlink). Nothing to declare — drop the row rather
+        // than fail the whole scan for one file.
+        return null;
+      }
+
+      if (candidate.isAccessMd) {
+        const parsed = parseAccessFile(text, candidate.repoRel);
+        if (!parsed.ok) {
+          return {
+            path: candidate.repoRel,
+            governs: dirOf(candidate.repoRel),
+            source: 'access-md',
+            entries: [],
+            parseError: parsed.errors.join('; '),
+          };
+        }
+        // An `access.md` that parses to nothing (empty, or only unknown keys)
+        // declares nothing: closeness-first resolution yields no verdict at that
+        // scope, so the parent's rules apply unchanged. Listing it under
+        // "item-specific rules" would announce an override that does not exist.
+        const entries = toEntries(parsed.file.entries);
+        if (entries.length === 0) return null;
+        return {
+          path: candidate.repoRel,
+          governs: dirOf(candidate.repoRel),
+          source: 'access-md',
+          entries,
+        };
+      }
+
+      const own = parseOwnAccessEntries(text);
+      if (!own) return null;
+      const entries = toEntries(own);
+      if (entries.length === 0) return null;
+      return {
+        path: candidate.repoRel,
+        governs: candidate.repoRel,
+        source: 'frontmatter',
+        entries,
+      };
+    }),
+  );
+
+  return { overrides: rows.filter((r): r is AccessDeclaration => r !== null), truncated };
+}

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

@@ -144,7 +144,7 @@ export class AccessMutationService {
     const current = await this.readOrEmpty(workspaceId, editPath, kind === 'folder');
     let result;
     try {
-      result = spliceGrant(current, verb, principal, { allowScalar });
+      result = spliceGrant(current, verb, principal, { allowScalar, target: kind === 'folder' ? 'folder' : 'node' });
     } catch (err) {
       throw this.toMutationError(err);
     }
@@ -196,7 +196,7 @@ export class AccessMutationService {
     try {
       const verbsToRevoke = verb ? [verb] : KNOWN_VERBS;
       for (const v of verbsToRevoke) {
-        const r = spliceRevoke(next, v, principal);
+        const r = spliceRevoke(next, v, principal, { target: kind === 'folder' ? 'folder' : 'node' });
         next = r.text;
         changed = changed || r.changed;
       }
@@ -259,9 +259,9 @@ export class AccessMutationService {
       for (const v of verbsToDeny) {
         // (1) Strip any same-scope GRANT for this principal so grant-beats-deny
         // can't silently swallow the deny we're about to add.
-        next = spliceRevoke(next, v, principal).text;
+        next = spliceRevoke(next, v, principal, { target: kind === 'folder' ? 'folder' : 'node' }).text;
         // (2) Add the deny under the same verb.
-        next = spliceGrant(next, v, principal, { allowScalar, deny: true }).text;
+        next = spliceGrant(next, v, principal, { allowScalar, deny: true, target: kind === 'folder' ? 'folder' : 'node' }).text;
       }
     } catch (err) {
       throw this.toMutationError(err);

package/src/modules/access/access-splice.ts

@@ -32,8 +32,22 @@ import {
   parseAccessEntry,
   canonicalEmail,
   canonicalRoleName,
+  accessMdDeclaresBodyRules,
 } from './access-control.service.js';
 
+/**
+ * Which rule block a mutation edits.
+ *
+ *  - `'node'` (default): the file's YAML frontmatter — node files, and every
+ *    call that predates the two-format `access.md` story.
+ *  - `'folder'`: the block that governs the CONTAINING FOLDER of an
+ *    `access.md` — the body when the file is in the new (body-governed)
+ *    format, the frontmatter otherwise. Callers mutating folder rules pass
+ *    this so a grant can never land in a new-format file's frontmatter
+ *    (which governs the FILE itself, not the folder).
+ */
+export type SpliceTarget = 'node' | 'folder';
+
 /** A principal to grant/revoke, in the resolver's canonical terms. */
 export type Principal =
   | { kind: 'user'; email: string; displayName: string }
@@ -181,6 +195,28 @@ function joinFrontmatter(f: Frontmatter): string {
   return [...f.pre, ...f.fm, ...f.post].join(f.eol);
 }
 
+/**
+ * The line region a mutation edits, per {@link SpliceTarget}. `lines` aliases
+ * the region's array (edited in place, like `f.fm` always was); `join()`
+ * reassembles the whole file around it.
+ */
+function pickRegion(
+  text: string,
+  f: Frontmatter & { hasFrontmatter: boolean },
+  target: SpliceTarget,
+): { lines: string[]; join(): string } {
+  if (target === 'folder' && f.hasFrontmatter && accessMdDeclaresBodyRules(text)) {
+    // New format: post = [closing '---', ...body]. Edit the body lines.
+    const closing = f.post[0];
+    const body = f.post.slice(1);
+    return {
+      lines: body,
+      join: () => [...f.pre, ...f.fm, closing, ...body].join(f.eol),
+    };
+  }
+  return { lines: f.fm, join: () => joinFrontmatter(f) };
+}
+
 /** Leading-space count of a line. */
 function indentOf(line: string): number {
   const m = line.match(/^( *)/);
@@ -311,7 +347,7 @@ export function spliceGrant(
   text: string,
   verb: Verb,
   rawPrincipal: Principal,
-  opts: { allowScalar?: boolean; deny?: boolean } = {},
+  opts: { allowScalar?: boolean; deny?: boolean; target?: SpliceTarget } = {},
 ): SpliceResult {
   const principal = validatePrincipal(rawPrincipal);
   const deny = opts.deny ?? false;
@@ -329,8 +365,9 @@ export function spliceGrant(
     return { text: text2, changed: true };
   }
 
-  const block = findVerbBlock(f.fm, verb);
-  const existing = blockEntries(f.fm, block);
+  const region = pickRegion(text, f, opts.target ?? 'node');
+  const block = findVerbBlock(region.lines, verb);
+  const existing = blockEntries(region.lines, block);
 
   // Idempotency: an entry for this principal with the same deny-ness is already
   // present (a grant when granting, a deny when denying).
@@ -341,17 +378,17 @@ export function spliceGrant(
   const itemValue = renderEntry(principal, deny);
 
   if (block.keyLine === -1) {
-    // Verb key absent — append a new block at the end of the frontmatter.
+    // Verb key absent — append a new block at the end of the region.
     const lines = opts.allowScalar ? [`${verb}: ${itemValue}`] : [`${verb}:`, `  - ${itemValue}`];
-    f.fm.push(...lines);
-    return { text: joinFrontmatter(f), changed: true };
+    region.lines.push(...lines);
+    return { text: region.join(), changed: true };
   }
 
   if (block.inlineScalarValue !== null) {
     // Scalar form — promote to a block list with both the old and new entry.
     const old = block.inlineScalarValue;
-    f.fm.splice(block.keyLine, 1, `${verb}:`, `  - ${old}`, `  - ${itemValue}`);
-    return { text: joinFrontmatter(f), changed: true };
+    region.lines.splice(block.keyLine, 1, `${verb}:`, `  - ${old}`, `  - ${itemValue}`);
+    return { text: region.join(), changed: true };
   }
 
   // Block-list (possibly inline `[]`). Insert after the last existing item, or
@@ -360,14 +397,14 @@ export function spliceGrant(
   const newLine = `${indent}- ${itemValue}`;
   if (block.inlineEmpty) {
     // `verb: []` -> `verb:` + one item.
-    f.fm[block.keyLine] = `${' '.repeat(block.keyIndent)}${verb}:`;
-    f.fm.splice(block.keyLine + 1, 0, newLine);
-    return { text: joinFrontmatter(f), changed: true };
+    region.lines[block.keyLine] = `${' '.repeat(block.keyIndent)}${verb}:`;
+    region.lines.splice(block.keyLine + 1, 0, newLine);
+    return { text: region.join(), changed: true };
   }
   const insertAt =
     block.itemLines.length > 0 ? block.itemLines[block.itemLines.length - 1] + 1 : block.keyLine + 1;
-  f.fm.splice(insertAt, 0, newLine);
-  return { text: joinFrontmatter(f), changed: true };
+  region.lines.splice(insertAt, 0, newLine);
+  return { text: region.join(), changed: true };
 }
 
 /**
@@ -377,37 +414,43 @@ export function spliceGrant(
  * file still parses cleanly (the resolver reads `[]` as an empty list).
  * Preserves everything else.
  */
-export function spliceRevoke(text: string, verb: Verb, rawPrincipal: Principal): SpliceResult {
+export function spliceRevoke(
+  text: string,
+  verb: Verb,
+  rawPrincipal: Principal,
+  opts: { target?: SpliceTarget } = {},
+): SpliceResult {
   const principal = validatePrincipal(rawPrincipal);
   const f = splitFrontmatter(text);
   if (!f.hasFrontmatter) return { text, changed: false };
 
-  const block = findVerbBlock(f.fm, verb);
+  const region = pickRegion(text, f, opts.target ?? 'node');
+  const block = findVerbBlock(region.lines, verb);
   if (block.keyLine === -1) return { text, changed: false };
 
   if (block.inlineScalarValue !== null) {
     const r = parseAccessEntry(block.inlineScalarValue);
     if (r.ok && entryMatches(r.entry, principal)) {
       // Lone scalar entry removed -> collapse to empty list.
-      f.fm[block.keyLine] = `${' '.repeat(block.keyIndent)}${verb}: []`;
-      return { text: joinFrontmatter(f), changed: true };
+      region.lines[block.keyLine] = `${' '.repeat(block.keyIndent)}${verb}: []`;
+      return { text: region.join(), changed: true };
     }
     return { text, changed: false };
   }
 
-  const entries = blockEntries(f.fm, block);
+  const entries = blockEntries(region.lines, block);
   const victims = entries.filter((e) => entryMatches(e.entry, principal)).map((e) => e.line);
   if (victims.length === 0) return { text, changed: false };
 
   // Delete from the bottom up so earlier indices stay valid.
   const remaining = block.itemLines.filter((l) => !victims.includes(l));
-  for (const line of [...victims].sort((a, b) => b - a)) f.fm.splice(line, 1);
+  for (const line of [...victims].sort((a, b) => b - a)) region.lines.splice(line, 1);
 
   if (remaining.length === 0) {
     // Verb block is now empty — collapse `verb:` to `verb: []`. The key line
     // index is unchanged because we only removed lines that came after it.
-    f.fm[block.keyLine] = `${' '.repeat(block.keyIndent)}${verb}: []`;
+    region.lines[block.keyLine] = `${' '.repeat(block.keyIndent)}${verb}: []`;
   }
-  return { text: joinFrontmatter(f), changed: true };
+  return { text: region.join(), changed: true };
 }
 

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

@@ -20,6 +20,7 @@ import {
   type TargetKind,
 } from './access-mutation.service.js';
 import { canonicalRoleName, EVERYONE_CANONICAL, type Verb } from './access-control.service.js';
+import { listAccessDeclarationsUnder } from './access-declarations.js';
 import { RolesAdminService, RolesAdminError } from './roles-admin.service.js';
 import type { Principal } from './access-splice.js';
 import type { Database } from '../database/connection.js';
@@ -171,6 +172,66 @@ export function createAccessRoutes(
     }
   });
 
+  /**
+   * GET /api/workspace/:id/access/overrides?path=<folder>
+   *
+   * Every access declaration living INSIDE a folder — the descendant
+   * `access.md` files and the node frontmatter that override the folder's own
+   * rules for the principals they name. Display-only: the group access surface
+   * shows it so nobody reads a folder's share list as the whole story.
+   *
+   * Gating is stricter than the sibling `GET /access`, which hands its eligible
+   * lists to any authenticated caller: here the caller must RESOLVE read on the
+   * folder (403 otherwise), and every returned row is additionally filtered by
+   * `canReadBatch` on what it governs. So the endpoint can only ever tell you
+   * about rules on things you can already see. It writes nothing and resolves
+   * nothing — it reports declarations through the resolver's own parsers.
+   */
+  router.get('/workspace/:id/access/overrides', async (req, res) => {
+    const user = await requireUser(req, res);
+    if (!user) return;
+
+    const rawPath = req.query.path;
+    if (typeof rawPath !== 'string' || !rawPath) {
+      res.status(400).json({ error: 'path query parameter is required' });
+      return;
+    }
+
+    try {
+      const folder = toRepoRelative(rawPath);
+      assertRepoRelativeTarget(folder, 'folder');
+
+      if (!(await accessControl.canRead(req.params.id, user.email, folder))) {
+        res.status(403).json({ error: 'You do not have access to this folder.' });
+        return;
+      }
+
+      const { overrides, truncated } = await listAccessDeclarationsUnder(
+        workspaceService,
+        req.params.id,
+        kbDirName,
+        folder,
+      );
+
+      // Read-filter per ROW. Folder read does not imply read on everything
+      // underneath — a `deny read` on one skill is precisely the kind of rule
+      // this endpoint lists, and echoing that skill's name back to the person
+      // it was denied to would leak the thing the rule exists to hide.
+      const governs = [...new Set(overrides.map((o) => o.governs))];
+      const readable = governs.length
+        ? await accessControl.canReadBatch(req.params.id, user.email, governs)
+        : new Map<string, boolean>();
+
+      res.json({
+        overrides: overrides.filter((o) => readable.get(o.governs) === true),
+        truncated,
+      });
+    } catch (err) {
+      const { status, body } = toHttpError(err);
+      res.status(status).json(body);
+    }
+  });
+
   /**
    * POST /api/workspace/:id/access/batch
    * Body: `{ paths: string[] }`. Returns `{ results: { [path]: boolean } }`.

package/src/modules/access/creator-access.ts

@@ -87,6 +87,16 @@ export interface ICreatorAccess {
   noteAccessFileWritten(workspaceId: string): void;
 }
 
+/**
+ * The splice-safe principal for a creator — exported because group
+ * provisioning (`GroupProvisionService`) writes the same `Name <email>`
+ * entries into the access.md files it seeds, and two spellings of the same
+ * person would read as two people.
+ */
+export function creatorPrincipal(creator: Creator): Principal {
+  return { kind: 'user', email: creator.email, displayName: safeDisplayName(creator) };
+}
+
 /**
  * `Name <email>`-safe display name: `validatePrincipal` rejects control
  * chars, `<`, `>`, and `#`, so strip those from the user's name and fall
@@ -159,6 +169,11 @@ export class CreatorAccessService implements ICreatorAccess {
           warnSkipped(rel, err);
           return null;
         }
+        // NOTE: a direct group folder (`Groups/<Name>`) is no longer special
+        // here. Groups — and personal folders — are made by the dedicated
+        // provisioning endpoint (`GroupProvisionService`), which writes the
+        // full ownership template itself; this generic read-grant only covers
+        // ad-hoc folder creation elsewhere in the tree.
         return {
           kind: 'seed-access-md',
           wsRelPath: `${this.kbDirName}/${acc}/access.md`,
@@ -166,7 +181,12 @@ export class CreatorAccessService implements ICreatorAccess {
             try {
               // Idempotent merge into whatever is on disk by write time — a
               // concurrent creator's grant survives; ours lands next to it.
-              return spliceGrant(current, 'read', principal, { allowScalar: false }).text;
+              // `target: 'folder'` so a new-format access.md (body-governed)
+              // gets the grant in its FOLDER rules, never its self-frontmatter.
+              return spliceGrant(current, 'read', principal, {
+                allowScalar: false,
+                target: 'folder',
+              }).text;
             } catch (err) {
               warnSkipped(rel, err);
               return current;
@@ -249,7 +269,7 @@ export class CreatorAccessService implements ICreatorAccess {
   }
 
   private principalFor(creator: Creator): Principal {
-    return { kind: 'user', email: creator.email, displayName: safeDisplayName(creator) };
+    return creatorPrincipal(creator);
   }
 }
 

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

@@ -17,7 +17,7 @@ export class AdminAccessService implements IAdminAccessService {
     private readonly accessControl: IAccessControl,
     private readonly workspaceService: WorkspaceService,
     /** Branch whose `roles.yaml` defines admins (the authoritative default branch). */
-    private readonly branch: string,
+    private readonly branch: string | (() => string),
     /**
      * Emails treated as admin WITHOUT consulting `roles.yaml` — the env
      * bootstrap admin (`ADMIN_EMAIL`). A fresh deployment's KB may not list
@@ -36,8 +36,9 @@ export class AdminAccessService implements IAdminAccessService {
       // 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');
+      const branch = typeof this.branch === 'function' ? this.branch() : this.branch;
+      await this.workspaceService.getOrCreateForBranch(branch);
+      return await this.accessControl.canWrite(workspaceIdForBranch(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.

package/src/modules/auth/__tests__/auth.service.test.ts

@@ -215,3 +215,60 @@ describe('AuthService.listAccounts', () => {
     expect(JSON.stringify(accounts)).not.toContain('scrypt:');
   });
 });
+
+/**
+ * `ALLOWED_EMAIL_DOMAINS` is the SSO allow-list, and only that.
+ *
+ * It exists because SSO AUTO-PROVISIONS — `loginWithSso` upserts the account
+ * the first time the issuer authenticates someone, with nobody approving it.
+ * Against a multi-tenant issuer (Google, the Entra `common` endpoint) it is the
+ * only thing between "has an account somewhere" and "has an account here.
+ *
+ * The other two entry points do not have that property, which is why the guard
+ * was taken off them: an admin-created account is vetted by the act of creating
+ * it, and password login can only reach an account that already exists. The
+ * check gated nothing there — while being able to lock out a bootstrap admin
+ * whose own address sits outside the list, which the last test pins.
+ */
+describe('AuthService — the SSO domain allow-list', () => {
+  const config = makeConfig({ allowedEmailDomains: ['bevel.software'] });
+
+  it('refuses an SSO sign-in from outside the allow-list', async () => {
+    const { db } = makeFakeDb([[]]);
+    await expect(
+      new AuthService(db, config).loginWithSso('someone@gmail.com', 'Someone'),
+    ).rejects.toThrow(/domain is not allowed/i);
+  });
+
+  it('admits a subdomain of an allowed domain', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: 'eu@eu.bevel.software', name: 'EU' }]]);
+    const out = await new AuthService(db, config).loginWithSso('eu@eu.bevel.software', 'EU');
+    expect(out.user.email).toBe('eu@eu.bevel.software');
+  });
+
+  it('does NOT gate an account an admin creates', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: 'contractor@gmail.com', name: 'Contractor' }]]);
+    const account = await new AuthService(db, config).createAccount(
+      'contractor@gmail.com',
+      'Contractor',
+      'pw-longer-than-8',
+    );
+    expect(account.email).toBe('contractor@gmail.com');
+  });
+
+  it('does NOT lock the bootstrap admin out of their own deployment', async () => {
+    // The owner's address need not sit inside the SSO allow-list — the list is
+    // about who may provision themselves, not about who owns the deployment.
+    const outsideConfig = makeConfig({
+      allowedEmailDomains: ['bevel.software'],
+      adminEmail: 'root@gmail.com',
+      adminPassword: 'sup3r-secret',
+    });
+    const { db } = makeFakeDb([[{ ...ROW, email: 'root@gmail.com', name: 'root' }]]);
+    const out = await new AuthService(db, outsideConfig).loginWithPassword(
+      'root@gmail.com',
+      'sup3r-secret',
+    );
+    expect(out.user.email).toBe('root@gmail.com');
+  });
+});