@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/access-model/access-template.ts

@@ -0,0 +1,44 @@
+/**
+ * The shape of an `access.md` the platform writes on its own — THE one
+ * explanation of how the file works, carried inside every file it generates
+ * so a person (or an agent) reading it in place learns the rules from the
+ * file itself, rather than from a document they have not opened.
+ *
+ * Two blocks, two scopes: the frontmatter governs the FILE, the body governs
+ * the FOLDER. The wording here is what a fresh folder `access.md` carries
+ * (`spliceGrant` on an empty file with `target: 'folder'`); the plugin and
+ * personal-space templates in the provisioning service say the same thing in
+ * their own words, tailored to what those folders are.
+ */
+
+/** The frontmatter block of a fresh access.md — comments only, no verbs. */
+export const ACCESS_MD_FRONTMATTER_NOTE: readonly string[] = [
+  '# THIS BLOCK (the frontmatter) governs this access.md FILE only: who may see',
+  '# and change these rules. Left empty, the file follows the folder rules below.',
+];
+
+/** The comment block that opens a fresh access.md body, before its verbs. */
+export const ACCESS_MD_BODY_NOTE: readonly string[] = [
+  '# THIS BLOCK (the body) governs the FOLDER this file sits in, and everything',
+  '# beneath it until a nearer access.md says otherwise. Verbs: read, write,',
+  '# download, owner (owner implies the rest; write and download each imply read).',
+  '# An entry is a role from roles.yaml, a group from groups.yaml, a person as',
+  '# `Name <email>`, or `everyone` — every signed-in person, the whole organisation.',
+  '# `deny X` takes away that verb ALONE: grants imply the lower verbs, denials',
+  '# never do — `deny download` says nothing about read, and leaves a separate',
+  '# read grant standing. Keep this block pure YAML; explanations go in `#` lines.',
+];
+
+/**
+ * A fresh access.md around `bodyYaml` (the folder's verbs, already rendered)
+ * — the two blocks, each opened by its note.
+ */
+export function freshAccessMd(bodyYaml: string, eol = '\n'): string {
+  return [
+    '---',
+    ...ACCESS_MD_FRONTMATTER_NOTE,
+    '---',
+    ...ACCESS_MD_BODY_NOTE,
+    bodyYaml,
+  ].join(eol) + eol;
+}

package/src/modules/access-model/change-gate.ts

@@ -0,0 +1,80 @@
+/**
+ * The contract of the READ-BEFORE-WRITE gate: nothing is created, changed or
+ * removed at a place its author cannot read. The service that answers
+ * (filesystem stats, access checks) is `modules/access/change-read-gate.ts`;
+ * this file carries only the types, so the workflow, kb-fs and tool modules
+ * depend on the contract and never on the access module.
+ *
+ * Why `read`, when every write already needs `write`: on a draft branch no
+ * write grant is needed at all — anyone may propose anything, and the change
+ * request is where the real boundary lives. Without this gate a proposal
+ * could land in a folder its author cannot see, where it would vanish from
+ * them the moment it was added. And a write grant only IMPLIES read; a
+ * nearer `deny read` can take the read away while the write stands. The gate
+ * makes the one rule hold everywhere: you can only change what you can see.
+ *
+ * The one exception is a NEW FOLDER directly under one of the three roots
+ * (knowledge, skills, plugins — `creatableRootDirNames`). Those roots grant
+ * read to nobody by default, and a person's own space or a new plugin or
+ * skill has to start somewhere. The new folder carries its creator's own
+ * grant in its `access.md` (see `ICreatorAccess`), so what they create there
+ * is visible to them from the first byte. A loose FILE directly at a root
+ * cannot carry such a grant, so it is not excepted.
+ */
+
+/**
+ * Where a change is asked about. `'file'` is what every lock acquire is (the
+ * path being written, moved, or deleted — a `.gitkeep` included); `'dir'` is
+ * for a caller asking about a folder itself before it fills it, such as the
+ * destination of an archive extraction.
+ */
+export type ChangeTargetKind = 'file' | 'dir';
+
+export type ChangeReadVerdict =
+  | {
+      allowed: true;
+      via:
+        /** The caller reads the path (or, for a new path, where it lands). */
+        | 'readable'
+        /** A new folder directly under one of the three roots — the exception. */
+        | 'new-top-level-folder'
+        /** Outside the knowledge-base repository: no read rules apply. */
+        | 'outside-kb'
+        /** A machine-owned file whose writer the write rule already names. */
+        | 'machine-owned'
+        /** An admin on a file directly in the repository root — the rescue path. */
+        | 'admin-rescue'
+        /**
+         * No `roles.yaml` on this tree at all — a repository before its first
+         * one: nothing to decide against. A `roles.yaml` that is THERE but
+         * unusable is not this: a broken rule set is an error, never an open
+         * door.
+         */
+        | 'no-rules';
+    }
+  | {
+      allowed: false;
+      /**
+       * The repo-relative path the caller cannot read: the target itself when
+       * it exists, otherwise the folder it would land in (`''` = the root).
+       */
+      unreadable: string;
+    };
+
+export interface IChangeReadGate {
+  /** The verdict for `wsPath` (workspace-relative), with why it holds. */
+  judge(
+    workspaceId: string,
+    userEmail: string,
+    wsPath: string,
+    kind: ChangeTargetKind,
+  ): Promise<ChangeReadVerdict>;
+
+  /** `judge`, throwing `AccessDeniedError` (with `unreadable` set) on a refusal. */
+  assertMayChange(
+    workspaceId: string,
+    userEmail: string,
+    wsPath: string,
+    kind: ChangeTargetKind,
+  ): Promise<void>;
+}

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

@@ -10,22 +10,25 @@
 import type { Principal } from './access-splice.js';
 
 /**
- * How a pending creation gets its creator read grant.
- *   - `seed-access-md`: merge the grant into `wsRelPath` (a new directory's
- *     own `access.md`, workspace-relative) — BEFORE or alongside the creation,
- *     via the caller's own lock+commit machinery. The caller MUST re-read the
- *     file's CURRENT text under its lock and write `apply(current)` ('' when
- *     absent), never a precomputed fresh file: two concurrent creators can
- *     both plan a seed for the same new directory, and a blind overwrite
- *     would silently revoke whichever grant landed first. Skip the write when
- *     `apply` returns the input unchanged, and call `noteAccessFileWritten`
- *     after a write so the resolver cache drops.
- *   - `frontmatter`: run the new file's content through `apply` before
- *     writing it, so the grant lands atomically inside the created file.
+ * How a pending creation gets its creator read grant — there is one way:
+ * `seed-access-md` merges the grant into `wsRelPath` (the new top-level
+ * folder's own `access.md`, workspace-relative) BEFORE or alongside the
+ * creation, via the caller's own lock+commit machinery. The caller MUST
+ * re-read the file's CURRENT text under its lock and write `apply(current)`
+ * ('' when absent), never a precomputed fresh file: two concurrent creators
+ * can both plan a seed for the same new directory, and a blind overwrite
+ * would silently revoke whichever grant landed first. Skip the write when
+ * `apply` returns the input unchanged, and call `noteAccessFileWritten`
+ * after a write so the resolver cache drops.
+ *
+ * Kept a union of one so a second plan kind can return without touching the
+ * consumers' `plan?.kind === 'seed-access-md'` reads.
  */
-export type CreationGrantPlan =
-  | { kind: 'seed-access-md'; wsRelPath: string; apply: (current: string) => string }
-  | { kind: 'frontmatter'; apply: (content: string) => string };
+export type CreationGrantPlan = {
+  kind: 'seed-access-md';
+  wsRelPath: string;
+  apply: (current: string) => string;
+};
 
 /** The creator identity a grant is written for. */
 export interface Creator {
@@ -46,12 +49,6 @@ export interface ICreatorAccess {
     kind: 'file' | 'dir',
   ): Promise<CreationGrantPlan | null>;
 
-  grantInExtractedFile(
-    workspaceId: string,
-    creator: Creator,
-    wsRelPath: string,
-  ): Promise<string | null>;
-
   noteAccessFileWritten(workspaceId: string): void;
 }
 

package/src/modules/access-model/frontmatter-lines.ts

@@ -0,0 +1,98 @@
+/**
+ * THE line-based scan of a `---` frontmatter block, for the access model.
+ *
+ * The access model deliberately does NOT use the two-string splitter in
+ * `@bevel-software/platform-shared`: a splice has to put bytes back exactly
+ * as it found them — comments, blank lines, the file's own line endings —
+ * and that needs the LINES, not two captured strings. Two readers here
+ * scanned for the fences separately (the grammar's `extractFrontmatter` and
+ * `bodyAfterFrontmatter`, and the splice's `splitFrontmatter`), each with its
+ * own copy of the same loop. This is that loop, once.
+ *
+ * What it decides, and what it leaves to the caller:
+ *
+ *   - THE FENCE RULE is NOT decided here: it is `isFrontmatterFence` from the
+ *     shared package, the same function the splitter asks, so the access
+ *     model and the catalog can never again disagree about whether a file
+ *     has frontmatter (`frontmatter-fences.test.ts` asserts they agree).
+ *   - WHAT AN UNTERMINATED BLOCK MEANS is the caller's: the grammar reads it
+ *     as a parse error, the body reader as no body, the splice as a refusal.
+ *     One scan, three answers, none of them re-deriving the fences.
+ */
+import { isFrontmatterFence } from '@bevel-software/platform-shared';
+
+/** An opening fence with no closing one — the caller decides what that means. */
+export interface UnterminatedFrontmatter {
+  kind: 'unterminated';
+}
+
+/** No opening fence: the whole text is body. */
+export interface NoFrontmatter {
+  kind: 'none';
+  /** Every line of the text, so a splice can put it back untouched. */
+  lines: string[];
+  eol: string;
+}
+
+/** A closed `---` block. */
+export interface ScannedFrontmatter {
+  kind: 'frontmatter';
+  /** The opening fence line, on its own — a splice writes it back verbatim. */
+  open: string[];
+  /** The lines BETWEEN the fences. */
+  fm: string[];
+  /** The closing fence line and everything after it. */
+  post: string[];
+  /** The text's own line ending, so a rewrite does not dirty every line. */
+  eol: string;
+}
+
+export type FrontmatterScan = ScannedFrontmatter | NoFrontmatter | UnterminatedFrontmatter;
+
+/** Whether a line IS a fence — the platform's one rule, shared with the catalog's splitter. */
+const isFence = isFrontmatterFence;
+
+/**
+ * The line ending a rewrite of `text` should use: the one MOST of its lines
+ * already use.
+ *
+ * A splice re-joins the whole file with a single separator — the frontmatter
+ * array is edited by index, so there is no surviving per-line ending to put
+ * back — which makes "which ending?" purely a question of whose lines get
+ * rewritten. The majority answers it with the fewest: a consistent file (all
+ * LF, or all CRLF, which is every file git checks out) comes back byte for
+ * byte, and a MIXED file is normalised towards whatever it mostly already is.
+ *
+ * The rule this replaces was "CRLF if the text contains one anywhere", which
+ * let a single stray CRLF — in the body, in a comment — rewrite every line of
+ * a knowledge base's access rules as churn in somebody's change request. Ties
+ * (and a file with no line breaks at all) go to the file's FIRST ending, so
+ * the answer is always the file's own.
+ */
+function dominantEol(text: string): string {
+  let crlf = 0;
+  let lf = 0;
+  let firstIsCrlf = false;
+  for (let i = text.indexOf('\n'); i !== -1; i = text.indexOf('\n', i + 1)) {
+    const isCrlf = i > 0 && text[i - 1] === '\r';
+    if (crlf + lf === 0) firstIsCrlf = isCrlf;
+    if (isCrlf) crlf++;
+    else lf++;
+  }
+  if (crlf > lf) return '\r\n';
+  if (lf > crlf) return '\n';
+  return firstIsCrlf ? '\r\n' : '\n';
+}
+
+/** Scan `text` for a leading `---` block. Decides nothing beyond the fences. */
+export function scanFrontmatter(text: string): FrontmatterScan {
+  const eol = dominantEol(text);
+  const lines = text.split(/\r?\n/);
+  if (!isFence(lines[0])) return { kind: 'none', lines, eol };
+  for (let i = 1; i < lines.length; i++) {
+    if (isFence(lines[i])) {
+      return { kind: 'frontmatter', open: lines.slice(0, 1), fm: lines.slice(1, i), post: lines.slice(i), eol };
+    }
+  }
+  return { kind: 'unterminated' };
+}

package/src/modules/access-model/plugin-principals.ts

@@ -4,10 +4,10 @@ import {
   PLUGIN_TOKEN_PREFIX,
   PLUGIN_TOKEN_VERBS,
   pluginPrincipalKey,
+  sourceVerbsFor,
   type AccessFile,
   type PluginTokenVerb,
   type RolesIndex,
-  type Verb,
 } from './access-grammar.js';
 
 /**
@@ -18,10 +18,12 @@ import {
  *
  * WHAT A PLUGIN'S ROSTER IS: the folder-governing rules of
  * `Plugins/<Name>/access.md` — the file provisioning seeds and the join flow
- * edits. Three principals per plugin, following the resolver's own superset
- * convention (write implies read, owner implies both):
+ * edits. Three principals per plugin, folded by the resolver's own
+ * `sourceVerbsFor` table — the ONE place the nesting is written down, so a
+ * roster can never drift from what resolution itself grants (`write` and
+ * `download` each imply `read`; `owner` implies all three):
  *
- *   plugin/<slug>/read    everyone under read, write or owner
+ *   plugin/<slug>/read    everyone under read, write, download or owner
  *   plugin/<slug>/write   everyone under write or owner
  *   plugin/<slug>/owner   everyone under owner
  *
@@ -72,7 +74,7 @@ export function synthesizePluginPrincipals(
     const file = accessFiles.get(dir);
     if (!file) continue; // a plugin without rules has no roster
     for (const verb of PLUGIN_TOKEN_VERBS) {
-      const { emails, everyone } = holdersOf(index, file, verb);
+      const { emails, everyone, sourceKeys } = holdersOf(index, file, verb);
       const key = pluginPrincipalKey(slug, verb);
       index.byCanonical.set(key, {
         displayName: key,
@@ -80,6 +82,7 @@ export function synthesizePluginPrincipals(
         kind: 'plugin',
         pluginName: slug,
         pluginDir: dir,
+        sourceKeys,
       });
       for (const email of emails) {
         let set = index.byEmail.get(email);
@@ -97,24 +100,13 @@ export function synthesizePluginPrincipals(
   }
 }
 
-/** The verbs whose grants confer `verb` on the plugin (the superset fold). */
-function sourceVerbsFor(verb: PluginTokenVerb): Verb[] {
-  switch (verb) {
-    case 'read':
-      return ['read', 'write', 'owner'];
-    case 'write':
-      return ['write', 'owner'];
-    case 'owner':
-      return ['owner'];
-  }
-}
-
 function holdersOf(
   index: RolesIndex,
   file: AccessFile,
   verb: PluginTokenVerb,
-): { emails: Set<string>; everyone: boolean } {
+): { emails: Set<string>; everyone: boolean; sourceKeys: Set<string> } {
   const emails = new Set<string>();
+  const sourceKeys = new Set<string>();
   let everyone = false;
   for (const source of sourceVerbsFor(verb)) {
     for (const entry of file.entries[source]) {
@@ -130,8 +122,9 @@ function holdersOf(
       if (entry.role.startsWith(PLUGIN_TOKEN_PREFIX)) continue; // no recursion
       const record = index.byCanonical.get(entry.role);
       if (!record) continue; // an unknown role contributes nothing (loadModel warns separately)
+      sourceKeys.add(entry.role);
       for (const email of record.emails) emails.add(email);
     }
   }
-  return { emails, everyone };
+  return { emails, everyone, sourceKeys };
 }

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

@@ -5,7 +5,7 @@
  * 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
+ * lockout. The dedicated App roles service already validates every
  * candidate before writing (`assertLoadable`), but the two RAW write paths do
  * not:
  *   - the human editor save  (`PUT /workspace/:id/file`)
@@ -22,8 +22,10 @@
  */
 
 import type { FileContent } from '@mastra/core/workspace';
-import { parseRolesYaml } from './access-grammar.js';
+import { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } from './access-grammar.js';
+import type { GroupsIndex } from './group-files.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { WriteValidator } from '../kb-fs/locking-filesystem.js';
 
 /** Repo-relative basename of the roles file (it lives at the KB repo root). */
 export const ROLES_YAML_BASENAME = 'roles.yaml';
@@ -80,10 +82,186 @@ export function assertRolesYamlParsable(content: string): void {
  */
 export function makeRolesYamlWriteValidator(
   kbDirName: string,
-): (path: string, content: FileContent) => void {
-  return (path, content) => {
+): WriteValidator & ((path: string, content: FileContent) => void) {
+  const validate: WriteValidator & ((path: string, content: FileContent) => void) = (path, content) => {
     if (typeof content !== 'string') return;
     if (!isRolesYamlPath(path, kbDirName)) return;
     assertRolesYamlParsable(content);
   };
+  validate.appliesTo = (path) => isRolesYamlPath(path, kbDirName);
+  return validate;
+}
+
+/** What an agent is told to do instead of creating a role. */
+export const NEW_ROLE_GUIDANCE =
+  'App roles are pre-set — add people to existing roles, and use a GROUP for a task- or team-scoped set of people.';
+
+/**
+ * An AGENT write whose candidate `roles.yaml` declares a role the current file
+ * does not. Same 422 shape as {@link RolesYamlInvalidError}; the message is
+ * self-contained because a tool error reaches the agent as its message alone,
+ * and the agent relays it to its user.
+ */
+export class RolesYamlNewRoleError extends WorkflowDomainError {
+  readonly roleNames: string[];
+  constructor(roleNames: string[]) {
+    const quoted = roleNames.map((n) => `'${n}'`).join(', ');
+    super(
+      `roles.yaml was not saved: agents never create app roles, and ${quoted} ` +
+        `${roleNames.length === 1 ? 'is not an existing role' : 'are not existing roles'}. ${NEW_ROLE_GUIDANCE}`,
+      422,
+      { kind: 'roles-yaml-new-role', roleNames },
+    );
+    this.name = 'RolesYamlNewRoleError';
+    this.roleNames = roleNames;
+  }
+}
+
+/**
+ * The role names `text` declares, canonical → display spelling. Lenient on
+ * purpose: a current file with a bad email still vouches for its role names.
+ * Text that is absent or not a `roles:` mapping declares none.
+ */
+function declaredRoleNames(text: string | null): Map<string, string> {
+  const names = new Map<string, string>();
+  if (text === null) return names;
+  const parsed = parseYamlSubset(text);
+  if (!parsed.ok) return names;
+  const roles = (parsed.value as Record<string, unknown> | null)?.roles;
+  if (roles == null || typeof roles !== 'object' || Array.isArray(roles)) return names;
+  for (const display of Object.keys(roles)) {
+    const canonical = canonicalRoleName(display);
+    if (canonical && !names.has(canonical)) names.set(canonical, display.trim());
+  }
+  return names;
+}
+
+/**
+ * Throw {@link RolesYamlNewRoleError} if `candidate` declares a role name
+ * (compared canonically, so a respelling is not new) absent from `current`.
+ * A rename is a delete plus a create, so it is refused for the created name.
+ */
+export function assertNoNewRoles(current: string | null, candidate: string): void {
+  const existing = declaredRoleNames(current);
+  const created = [...declaredRoleNames(candidate)]
+    .filter(([canonical]) => !existing.has(canonical))
+    .map(([, display]) => display);
+  if (created.length > 0) throw new RolesYamlNewRoleError(created);
+}
+
+/**
+ * The active group source an agent write is checked against: its groups and
+ * the file they came from (`groups.yaml`, or `synced-groups.yaml` in IdP mode).
+ * `null` when the source exists but could not be read — group entries are then
+ * left unchecked rather than every one refused.
+ */
+export type ActiveGroupsForValidation = { groups: GroupsIndex; sourceFile: string } | null;
+
+/** One `- group:<Name>` member entry: the role it sits under and the entry as written. */
+interface GroupEntry {
+  role: string;
+  roleCanonical: string;
+  entry: string;
+  group: string;
+}
+
+/**
+ * An AGENT write whose candidate `roles.yaml` adds a `- group:<Name>` entry
+ * naming no group in the active group source. The resolver ignores such an
+ * entry with only a log warning — the role silently reaches nobody — so it is
+ * refused up front, naming each entry, in the same 422 shape as the others.
+ */
+export class RolesYamlUnknownGroupError extends WorkflowDomainError {
+  readonly entries: { role: string; entry: string }[];
+  constructor(entries: { role: string; entry: string }[], sourceFile: string) {
+    const listed = entries.map((e) => `'- ${e.entry}' under role '${e.role}'`).join(', ');
+    super(
+      `roles.yaml was not saved: ${listed} ${entries.length === 1 ? 'names a group' : 'name groups'} ` +
+        `that ${sourceFile} does not declare. Group names are matched case- and whitespace-insensitively; ` +
+        'use an existing group, or create the group first.',
+      422,
+      { kind: 'roles-yaml-unknown-group', entries, sourceFile },
+    );
+    this.name = 'RolesYamlUnknownGroupError';
+    this.entries = entries;
+  }
+}
+
+/** Every `- group:<Name>` entry `text` declares, in file order. Lenient, like {@link declaredRoleNames}. */
+function groupEntries(text: string | null): GroupEntry[] {
+  const out: GroupEntry[] = [];
+  if (text === null) return out;
+  const parsed = parseYamlSubset(text);
+  if (!parsed.ok) return out;
+  const roles = (parsed.value as Record<string, unknown> | null)?.roles;
+  if (roles == null || typeof roles !== 'object' || Array.isArray(roles)) return out;
+  for (const [display, members] of Object.entries(roles)) {
+    if (!Array.isArray(members)) continue;
+    for (const member of members) {
+      if (typeof member !== 'string') continue;
+      const entry = member.trim();
+      if (!entry.toLowerCase().startsWith(GROUP_REF_PREFIX)) continue;
+      out.push({
+        role: display.trim(),
+        roleCanonical: canonicalRoleName(display),
+        entry,
+        group: canonicalRoleName(entry.slice(GROUP_REF_PREFIX.length)),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Throw {@link RolesYamlUnknownGroupError} if `candidate` adds a group entry
+ * whose name (compared canonically) the active group source does not declare.
+ * Only ADDED entries are checked: an entry already in `current` whose group
+ * has since been retired is left alone, so it cannot block an unrelated
+ * membership edit.
+ */
+export function assertKnownGroups(
+  current: string | null,
+  candidate: string,
+  active: ActiveGroupsForValidation,
+): void {
+  if (active === null) return;
+  const key = (e: GroupEntry) => `${e.roleCanonical}\n${e.group}`;
+  const existing = new Set(groupEntries(current).map(key));
+  const unknown = groupEntries(candidate)
+    .filter((e) => !existing.has(key(e)) && !active.groups.has(e.group))
+    .map(({ role, entry }) => ({ role, entry }));
+  if (unknown.length > 0) throw new RolesYamlUnknownGroupError(unknown, active.sourceFile);
+}
+
+/**
+ * The agent's `roles.yaml` gate: everything {@link makeRolesYamlWriteValidator}
+ * refuses, plus any role the current file does not declare and — when
+ * `loadGroups` is given — any added `- group:<Name>` entry naming a group the
+ * active group source does not declare. Agents manage
+ * membership only; the human editor and the App roles service keep the plain
+ * validator. `readCurrent` returns the file's current text, null when absent.
+ * Content of any type is checked — decoded as UTF-8 — so bytes cannot slip past.
+ *
+ * `readCurrent` is read afresh on every call, never cached: `LockingFilesystem`
+ * calls this validator before taking the lock (a cheap early refusal) and again
+ * once the `roles.yaml` lock is held, on the bytes that land. That second call
+ * is the decisive one — it compares against the file as the other roles.yaml
+ * writers, which coordinate on the same lock, left it — so a role deleted while
+ * the write waited cannot be reinstated, and one added meanwhile is not refused.
+ */
+export function makeAgentRolesYamlWriteValidator(
+  kbDirName: string,
+  readCurrent: () => Promise<string | null>,
+  loadGroups?: () => Promise<ActiveGroupsForValidation>,
+): WriteValidator {
+  const validate: WriteValidator = async (path, content) => {
+    if (!isRolesYamlPath(path, kbDirName)) return;
+    const text = typeof content === 'string' ? content : Buffer.from(content).toString('utf-8');
+    assertRolesYamlParsable(text);
+    const current = await readCurrent();
+    assertNoNewRoles(current, text);
+    if (loadGroups) assertKnownGroups(current, text, await loadGroups());
+  };
+  validate.appliesTo = (path) => isRolesYamlPath(path, kbDirName);
+  return validate;
 }

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

@@ -1,6 +1,10 @@
 import type { IAccessControl } from '../access/access-control.interface.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('admin');
 import { type WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import type { IAdminAccessService } from './admin.interface.js';
 
 /**
@@ -31,7 +35,7 @@ export class AdminAccessService implements IAdminAccessService {
 
   async isAdmin(email: string | undefined): Promise<boolean> {
     if (!email) return false;
-    const normalized = email.trim().toLowerCase();
+    const normalized = canonicalEmail(email);
     if (this.alwaysAdminEmails.includes(normalized)) return true;
     try {
       // Ensure the authoritative clone is on disk, then resolve Admin-role
@@ -43,7 +47,7 @@ export class AdminAccessService implements IAdminAccessService {
     } 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));
+      log.warn('isAdmin resolution failed:', { err });
       return false;
     }
   }