@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/src/modules/access/__tests__/access.routes.group-grant.test.ts

@@ -4,6 +4,7 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 
 import type { IAccessControl } from '../access-control.interface.js';
+import { AccessControlService } from '../access-control.service.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { WorkflowService } from '../../workflow/workflow.service.js';
@@ -31,6 +32,10 @@ async function makeHarness(opts: {
   files?: Record<string, string>;
   roles?: string[];
   groups?: string[];
+  /** Whether the caller is an admin, who is offered every group. Defaults to true. */
+  admin?: boolean;
+  /** The groups the caller is a member of — all a non-admin is offered, or may grant to. */
+  memberOf?: string[];
 }): Promise<{ server: Server; baseUrl: string; files: Map<string, string> }> {
   const files = new Map<string, string>(Object.entries(opts.files ?? {}));
 
@@ -46,6 +51,12 @@ async function makeHarness(opts: {
       groups: opts.groups ?? [],
       people: [],
     })),
+    holdsAdminRootWrite: vi.fn(async () => opts.admin ?? true),
+    groupsOfUser: vi.fn(async () => opts.memberOf ?? []),
+    // The real policy over the two stubs above: who sees which group is the
+    // resolver's one answer, not something a route (or this double) decides.
+    visibleGroups: (wsId: string, email: string, groups: readonly string[]) =>
+      AccessControlService.prototype.visibleGroups.call(accessControl, wsId, email, groups),
     eligibleWriters: vi.fn(async () => ({ roles: [], users: [] })),
     eligibleReaders: vi.fn(async () => ({ restricted: true, roles: [], users: [] })),
     eligibleOwners: vi.fn(async () => ({ roles: [], users: [] })),
@@ -213,6 +224,61 @@ describe('group principals on the share surface', () => {
     expect(body.plugins).toEqual(body.roles);
   });
 
+  it("suggest offers someone who is not an admin only the groups they are in, never another group's name", async () => {
+    h = await makeHarness({ roles: ['Everyone'], groups: ['GTM Team', 'Product'], admin: false, memberOf: ['Product'] });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access/suggest?q=`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { roles: string[]; groups: string[] };
+    expect(body.groups).toEqual(['Product']);
+    expect(body.roles).toEqual(['Everyone']); // roles are not withheld
+  });
+
+  it('suggest offers someone in no group, who is not an admin, no groups at all', async () => {
+    h = await makeHarness({ groups: ['GTM Team', 'Product'], admin: false });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access/suggest?q=`);
+    const body = (await res.json()) as { groups: string[] };
+    expect(body.groups).toEqual([]);
+  });
+
+  it('a non-admin grants to a group they are in', async () => {
+    h = await makeHarness({ groups: ['GTM Team', 'Product'], admin: false, memberOf: ['Product'] });
+    const res = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'Product' },
+    });
+    expect(res.status).toBe(200);
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- Product');
+  });
+
+  it('a non-admin granting to a group they are not in is refused exactly like an unknown group', async () => {
+    h = await makeHarness({ groups: ['GTM Team', 'Product'], admin: false, memberOf: ['Product'] });
+    const res = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'GTM Team' },
+    });
+    // Same status, same body as a group that does not exist — the WHOLE
+    // answer, message included, with only the name asked about differing —
+    // so the grant route confirms no group name the picker would not have
+    // offered.
+    const ghost = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'Ghost Team' },
+    });
+    expect(res.status).toBe(404);
+    expect(ghost.status).toBe(404);
+    const hiddenBody = (await res.json()) as Record<string, unknown>;
+    const ghostBody = (await ghost.json()) as Record<string, unknown>;
+    expect(hiddenBody).toMatchObject({ kind: 'unknown-group', group: 'GTM Team' });
+    expect(JSON.stringify(hiddenBody).replaceAll('GTM Team', 'Ghost Team')).toBe(JSON.stringify(ghostBody));
+    expect(h.files.has(`${KB}/Sales/access.md`)).toBe(false);
+  });
+
   it('revokes with a group principal (name-based, no existence check)', async () => {
     h = await makeHarness({
       groups: ['GTM Team'],

package/src/modules/access/__tests__/access.routes.unknown-email.test.ts

@@ -55,6 +55,8 @@ async function makeHarness(opts: {
     grantSources: vi.fn(async () => ({ read: [{ kind: 'direct' }] })),
     invalidate: vi.fn(),
     kbPrincipals: vi.fn(async () => ({ roles: [], groups: [], people: opts.kbPeople ?? [] })),
+    // No groups in this source, so the answer is the empty list the service gives for one.
+    visibleGroups: vi.fn(async (_w: string, _e: string, groups: readonly string[]) => [...groups]),
     eligibleWriters: vi.fn(async () => ({ roles: [], users: granted })),
     eligibleReaders: vi.fn(async () => ({ restricted: true, roles: [], users: granted })),
     eligibleOwners: vi.fn(async () => ({ roles: [], users: [] })),

package/src/modules/access/access-control.interface.ts

@@ -234,6 +234,28 @@ export interface IAccessControl {
    */
   canReadAsEveryoneBatch(workspaceId: string, relativePaths: string[]): Promise<Map<string, boolean>>;
 
+  /**
+   * The display names of the groups `userEmail` is a member of, in the
+   * active group source (`groups.yaml`, or the IdP-synced file), spelled as
+   * `kbPrincipals` spells them. Direct membership only: a role that lists a
+   * group does not make its holders members of it. Empty when the person is
+   * in no group.
+   */
+  groupsOfUser(workspaceId: string, userEmail: string): Promise<string[]>;
+
+  /**
+   * Which of `groups` (names from the active group source) `userEmail` may
+   * SEE: every one for an admin, who manages them all, and only the groups
+   * they are a member of ({@link groupsOfUser}) for anyone else. A group's
+   * name is information — on a deployment that gives each client, author or
+   * customer a group of its own, the list of groups is the client list — so
+   * this ONE answer is what the Library's Groups tab lists, what the share
+   * dialog offers as a grantee, and what a grant may name; a group outside it
+   * is treated as one that does not exist. Order and spelling of `groups` are
+   * kept.
+   */
+  visibleGroups(workspaceId: string, userEmail: string, groups: readonly string[]): Promise<string[]>;
+
   /**
    * Batched canWrite for PR diffs and commit-time gating. Returns a map keyed
    * by the input paths, with `true` / `false` for each. Reuses one config

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

@@ -5,9 +5,10 @@ import { logger } from '../../shared/logging.js';
 const log = logger('access');
 
 import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.contract.js';
-import { assertOneSpecPerLine, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
+import { assertOneSpecPerLine, isCommitSha, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
 import { hashEmail } from '../../shared/email-identity.js';
 import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { readRevSha } from '../kb-fs/index.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type {
   IAccessControl,
@@ -1370,7 +1371,13 @@ function ineligibleNamedEmailsResolved(
  * was built from (not the ref name that led there), so the per-file
  * own-entries reads that follow a gate resolve against exactly that tree.
  */
-type AtRefModel = { model: AccessModel; resolvedRef: string };
+/**
+ * A model built at a commit, with the commit it was built at and, when the
+ * tree is not too large to hold, every path the commit carries: what the
+ * own-entries reads need to tell a path that is absent at the commit (a
+ * fact, remembered) from a blob the batch could not read (never remembered).
+ */
+type AtRefModel = { model: AccessModel; resolvedRef: string; tree: ReadonlySet<string> | null };
 /**
  * One build's outcome: a model, no roles.yaml at the commit, or one that
  * doesn't parse. A git read failure is none of these: it throws
@@ -1440,6 +1447,25 @@ export class AccessControlService implements IAccessControl {
   private readonly atRefInFlight = new Map<string, Promise<AtRefBuild>>();
   private static readonly AT_REF_CACHE_MAX = 512;
 
+  /**
+   * A path's own access entries AT A COMMIT, keyed by commit + path. A blob
+   * at a commit never changes, so neither does what it declares for itself:
+   * no TTL, no invalidation, and no workspace in the key (every clone holds
+   * the same objects). This is the read every at-ref gate makes after the
+   * model: one `cat-file --batch` per call for the paths asked, which a
+   * change-request listing made once per ref per listing for the same paths
+   * at the same commits. Bounded FIFO; the bound only caps memory.
+   */
+  private readonly ownEntriesAtCommit = new Map<string, OwnEntries | null>();
+  private static readonly OWN_ENTRIES_AT_COMMIT_MAX = 16_384;
+  /** Paths a cached model keeps of its commit's tree, at most; a larger tree is not kept. */
+  private static readonly TREE_INDEX_MAX_PATHS = 20_000;
+  /** Paths held across every cached model's tree, at most; past it the oldest models let their tree go. */
+  private static readonly TREE_INDEX_BUDGET = 500_000;
+  private readonly treeIndexMaxPaths: number;
+  private readonly treeIndexBudget: number;
+  private treePathsHeld = 0;
+
   /**
    * Canonicalised deployment-owner emails (see `AccessModel.deploymentOwners`).
    * Held on the service rather than read per-model because it comes from the
@@ -1473,10 +1499,19 @@ export class AccessControlService implements IAccessControl {
      * run on the default layout.
      */
     private readonly kb: Pick<KbContext, 'layout'> = { layout: DEFAULT_KB_LAYOUT },
+    /**
+     * How much of the commits' trees the at-ref models may hold (see
+     * `TREE_INDEX_MAX_PATHS`, `TREE_INDEX_BUDGET`). The defaults are the
+     * deployment's; a suite lowers them to reach the bounds with a small
+     * repository.
+     */
+    limits: { treeIndexMaxPaths?: number; treeIndexBudget?: number } = {},
   ) {
     this.deploymentOwners = new Set(
       deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)),
     );
+    this.treeIndexMaxPaths = limits.treeIndexMaxPaths ?? AccessControlService.TREE_INDEX_MAX_PATHS;
+    this.treeIndexBudget = limits.treeIndexBudget ?? AccessControlService.TREE_INDEX_BUDGET;
   }
 
   /**
@@ -1618,6 +1653,23 @@ export class AccessControlService implements IAccessControl {
     return result;
   }
 
+  async groupsOfUser(workspaceId: string, userEmail: string): Promise<string[]> {
+    const model = await this.loadModel(workspaceId);
+    const email = canonicalEmail(userEmail);
+    const names: string[] = [];
+    for (const principal of model.roles.byCanonical.values()) {
+      if (principal.kind === 'group' && principal.emails.has(email)) names.push(principal.displayName);
+    }
+    return names;
+  }
+
+  async visibleGroups(workspaceId: string, userEmail: string, groups: readonly string[]): Promise<string[]> {
+    if (groups.length === 0) return [];
+    if (await this.holdsAdminRootWrite(workspaceId, userEmail)) return [...groups];
+    const mine = new Set(await this.groupsOfUser(workspaceId, userEmail));
+    return groups.filter((g) => mine.has(g));
+  }
+
   async canWriteBatch(
     workspaceId: string,
     userEmail: string,
@@ -2135,7 +2187,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return hasPermissionResolved(loaded.model, 'write', userEmail, relativePath, own);
   }
 
@@ -2148,7 +2200,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return canReadResolved(loaded.model, userEmail, relativePath, own);
   }
 
@@ -2171,7 +2223,7 @@ export class AccessControlService implements IAccessControl {
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole path set — a per-path `git
     // show` spawn made CR owner-routing take minutes on large change sets.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     const result = new Map<string, boolean>();
     for (const p of relativePaths) {
       const machineOwned = machineAnswers.get(p);
@@ -2196,7 +2248,7 @@ export class AccessControlService implements IAccessControl {
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole set — see canWriteBatchAtRef.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     const result = new Map<string, boolean>();
     for (const p of relativePaths) {
       result.set(p, canReadResolved(loaded.model, userEmail, p, owns.get(p) ?? null));
@@ -2219,7 +2271,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return eligibleHoldersResolved(loaded.model, 'write', relativePath, own);
   }
 
@@ -2333,7 +2385,7 @@ export class AccessControlService implements IAccessControl {
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole path set — see canWriteBatchAtRef.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     for (const p of relativePaths) {
       if (result.has(p)) continue;
       const own = owns.get(p) ?? null;
@@ -2551,8 +2603,14 @@ export class AccessControlService implements IAccessControl {
     repoDir: string,
     ref: string,
     relativePath: string,
+    tree: ReadonlySet<string> | null = null,
   ): Promise<OwnEntries | null> {
     if (relativePath === 'roles.yaml') return null;
+    // At a commit (what every gate passes: `resolvedRef`), the batched read
+    // and its memo answer; a single `git show` stays for a symbolic ref.
+    if (isCommitSha(ref)) {
+      return (await this.readOwnEntriesAtRefBatch(repoDir, ref, [relativePath], tree)).get(relativePath) ?? null;
+    }
     const text = await this.showAtRef(repoDir, ref, relativePath);
     if (text === null) return null;
     if (isAccessMdPath(relativePath)) return accessMdSelfEntries(text);
@@ -2571,23 +2629,60 @@ export class AccessControlService implements IAccessControl {
     repoDir: string,
     ref: string,
     relativePaths: string[],
+    tree: ReadonlySet<string> | null = null,
   ): Promise<Map<string, OwnEntries | null>> {
     const result = new Map<string, OwnEntries | null>();
     const wanted: string[] = [];
+    const memo = isCommitSha(ref) ? this.ownEntriesAtCommit : null;
     for (const p of relativePaths) {
-      if (p === 'roles.yaml') result.set(p, null);
-      else if (!wanted.includes(p)) wanted.push(p);
+      if (p === 'roles.yaml') {
+        result.set(p, null);
+        continue;
+      }
+      const key = `${ref}\0${p}`;
+      if (memo?.has(key)) {
+        result.set(p, memo.get(key) ?? null);
+        continue;
+      }
+      // A path the commit's tree does not carry has no own entries, as a
+      // fact about the commit: remembered, and not read. (A change request
+      // that adds a file asks about it at the base, where it does not exist
+      // yet; one that deletes a file asks at the head.)
+      if (tree && !tree.has(p)) {
+        result.set(p, null);
+        if (memo) this.rememberOwnEntriesAtCommit(key, null);
+        continue;
+      }
+      if (!wanted.includes(p)) wanted.push(p);
     }
     if (wanted.length === 0) return result;
     const texts = await catFileBatch(this.gitRunner, repoDir, wanted.map((p) => `${ref}:${p}`));
     wanted.forEach((p, i) => {
       const text = texts[i];
-      if (text === null) result.set(p, null);
-      else result.set(p, isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text));
+      if (text === null) {
+        // Absent at the commit (when no tree was there to say so first), or
+        // a blob git could not read: the batch says "missing" for both, and
+        // only the first is a fact about the commit. Answered as no own
+        // entries, as before, but never remembered.
+        result.set(p, null);
+        return;
+      }
+      const own = isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text);
+      result.set(p, own);
+      // What a blob declares for itself — including nothing — is a fact about the commit.
+      if (memo) this.rememberOwnEntriesAtCommit(`${ref}\0${p}`, own);
     });
     return result;
   }
 
+  private rememberOwnEntriesAtCommit(key: string, value: OwnEntries | null): void {
+    this.ownEntriesAtCommit.set(key, value);
+    if (this.ownEntriesAtCommit.size > AccessControlService.OWN_ENTRIES_AT_COMMIT_MAX) {
+      const oldest = this.ownEntriesAtCommit.keys().next().value;
+      if (oldest !== undefined) this.ownEntriesAtCommit.delete(oldest);
+    }
+  }
+
   /**
    * Resolve a candidate ref to one git accepts. Falls back to `origin/<ref>`
    * for short branch names, matching the heuristic in
@@ -2649,11 +2744,12 @@ export class AccessControlService implements IAccessControl {
   private async listAccessFilesAtRef(
     repoDir: string,
     ref: string,
-  ): Promise<{ accessFiles: string[]; pluginDirs: string[]; named: Set<string> } | 'error'> {
+  ): Promise<{ accessFiles: string[]; pluginDirs: string[]; named: Set<string>; all: string[] } | 'error'> {
     try {
       const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '-z', '--name-only', ref]);
       const out: string[] = [];
       const pluginDirs: string[] = [];
+      const all: string[] = [];
       // The fixed-name sources the tree carries (roles.yaml, the groups
       // files): a read of one of these that comes back empty is "absent"
       // only when the tree does not name it.
@@ -2661,13 +2757,15 @@ export class AccessControlService implements IAccessControl {
       const { pluginsDir } = this.kb.layout;
       for (const p of stdout.split('\0')) {
         if (!p) continue;
+        // One past the cap is enough to know the tree is not kept.
+        if (all.length <= this.treeIndexMaxPaths) all.push(p);
         if (p === 'access.md' || p.endsWith('/access.md')) out.push(p);
         else if (p === 'roles.yaml' || p === SYNCED_GROUPS_YAML || p === GROUPS_YAML) named.add(p);
         else if (p.startsWith(`${pluginsDir}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
           pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
         }
       }
-      return { accessFiles: out, pluginDirs, named };
+      return { accessFiles: out, pluginDirs, named, all };
     } catch {
       return 'error';
     }
@@ -2742,6 +2840,14 @@ export class AccessControlService implements IAccessControl {
   /** The commit `ref` points at in this clone, or null when it doesn't resolve. */
   private async revParseCommit(repoDir: string, ref: string): Promise<string | null> {
     if (!ref || ref.startsWith('-')) return null;
+    // The ref files first (`readRevSha`): the names git would try, in git's
+    // order, read without a process. "Missing" from the files is what
+    // rev-parse answers nothing for; "unreadable" — a spelling the reader
+    // does not resolve, a tag it cannot peel, a file it could not read — is
+    // git's to decide, as the authority.
+    const fromFiles = await readRevSha(repoDir, ref);
+    if (fromFiles === 'missing') return null;
+    if (fromFiles !== 'unreadable') return fromFiles.sha;
     try {
       const { stdout } = await this.gitRunner.run(repoDir, [
         'rev-parse',
@@ -2762,9 +2868,22 @@ export class AccessControlService implements IAccessControl {
 
   private rememberAtRef(key: string, value: AtRefModel): void {
     this.atRefCache.set(key, value);
+    this.treePathsHeld += value.tree?.size ?? 0;
     if (this.atRefCache.size > AccessControlService.AT_REF_CACHE_MAX) {
       const oldest = this.atRefCache.keys().next().value;
-      if (oldest !== undefined) this.atRefCache.delete(oldest);
+      if (oldest !== undefined) {
+        this.treePathsHeld -= this.atRefCache.get(oldest)?.tree?.size ?? 0;
+        this.atRefCache.delete(oldest);
+      }
+    }
+    // The trees are a budget of their own, across every held model: past
+    // it, the oldest models keep their model and let their tree go — the
+    // gate still answers, absence is just no longer remembered for them.
+    for (const held of this.atRefCache.values()) {
+      if (this.treePathsHeld <= this.treeIndexBudget) break;
+      if (!held.tree) continue;
+      this.treePathsHeld -= held.tree.size;
+      held.tree = null;
     }
   }
 
@@ -2940,6 +3059,10 @@ export class AccessControlService implements IAccessControl {
         deploymentOwners: this.deploymentOwners,
       },
       resolvedRef: commit,
+      // The listing already named every path; held so an own-entries read
+      // can tell absence from a lost blob, unless the tree is too large to
+      // hold for every cached commit (then absence is simply not remembered).
+      tree: listed.all.length <= this.treeIndexMaxPaths ? new Set(listed.all) : null,
     };
   }
 }

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

@@ -128,6 +128,18 @@ export function createAccessRoutes(
     return { roles, groups, plugins: plugins ?? [] };
   };
 
+  /**
+   * The groups `email` may be offered as a grantee, or name in a grant: the
+   * resolver's ONE answer to who sees which group (`visibleGroups`: every
+   * group for an admin, only their own for anyone else), the same the
+   * Library's Groups tab lists. Read on the default branch, where the active
+   * group source lives. The picker never names a group the caller has no
+   * part in, and the grant route refuses one with the same words as a group
+   * that does not exist.
+   */
+  const visibleGroups = (email: string, groups: string[]): Promise<string[]> =>
+    accessControl.visibleGroups(kb.defaultWorkspaceId(), email, groups);
+
   /**
    * The plugins `email` may DISCOVER — read the folder's access.md, the same
    * verdict the plugin index lists on. Both the suggest list and the grant
@@ -491,8 +503,9 @@ export function createAccessRoutes(
    * names — resolved from the DEFAULT branch, the authoritative source),
    * groups (the ACTIVE group source, same authority), and people (branch-local
    * to `:id`). Roles/groups come from the resolver's CACHED model — no fresh
-   * file reads per keystroke. Roles + groups are small + non-sensitive so they
-   * always show; PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query
+   * file reads per keystroke. Roles are small + non-sensitive so they always
+   * show; GROUPS are the caller's own unless they are an admin (see
+   * `visibleGroups`); PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query
    * can't dump the whole directory (email-harvesting guard). People are the
    * union of the KB-canonical set (roles.yaml + access.md grants) and the
    * `users` table (logged-in users). Results are capped. Each person carries
@@ -527,7 +540,7 @@ export function createAccessRoutes(
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
-      const matchedGroups = groups
+      const matchedGroups = (await visibleGroups(user.email, groups))
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
@@ -934,9 +947,12 @@ export function createAccessRoutes(
       } else if (principal.kind === 'group') {
         // A group grant must name a group in the ACTIVE source (IdP-synced or
         // manual) on the default branch — same authority the suggest list
-        // uses. No role-collision refusal: bare tokens resolve GROUP-FIRST,
-        // so the written bare name IS the group.
-        const { groups } = await defaultBranchPrincipals();
+        // uses — and one the caller may see (`visibleGroups`): a group hidden
+        // from the picker is refused here with the same words as one that
+        // does not exist, so the grant route is no oracle for group names.
+        // No role-collision refusal: bare tokens resolve GROUP-FIRST, so the
+        // written bare name IS the group.
+        const groups = await visibleGroups(user.email, (await defaultBranchPrincipals()).groups);
         const canonical = canonicalRoleName(principal.group);
         if (!groups.some((g) => canonicalRoleName(g) === canonical)) {
           throw new AccessMutationError(

package/src/modules/agent-guide/__tests__/agent-guide.test.ts

@@ -358,7 +358,7 @@ describe('the HTML views section', () => {
     expect(ids.indexOf('html-views')).toBe(ids.indexOf('tool-manuals') + 1);
   });
 
-  it('describes the frame, the two members core puts on window.bevel, and a fragment that scrolls the page', async () => {
+  it('describes the frame, the members core puts on window.bevel, and a fragment that scrolls the page', async () => {
     const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
     expect(text).toContain('**No network.**');
     expect(text).toContain('**Inline scripts and styles only.**');
@@ -374,6 +374,27 @@ describe('the HTML views section', () => {
     expect(docs).toContain('/workspace/main/Docs/Alice.md');
   });
 
+  it('documents window.bevel.tools: its four functions, the null check, the consent rule and requireTools with its card', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
+    for (const member of [
+      '`window.bevel.tools.searchTools(query)`',
+      '`window.bevel.tools.toolsInfo(names)`',
+      '`window.bevel.tools.callTool(name, args)`',
+      '`window.bevel.tools.callToolChain(code)`',
+      '`window.bevel.requireTools()`',
+    ]) {
+      expect(text).toContain(member);
+    }
+    expect(text).toContain('`window.bevel.tools` is `null` wherever tools are not available');
+    expect(text).toContain('Check it before every use');
+    expect(text).toContain('**Reading runs at once; writing asks first.**');
+    expect(text).toContain('"<page name> wants to write to the knowledge base"');
+    expect(text).toContain('Allow while open and Deny');
+    expect(text).toContain('rejects the call with `denied`');
+    expect(text).toContain('"<page name> uses tools that are only available in the platform"');
+    expect(text).toContain('Continue without tools and Open in the platform');
+  });
+
   it('lets a distribution replace the section or drop it', async () => {
     const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
       sections.map((s) => (s.id === 'html-views' ? { id: s.id, body: '## HTML views\n\nOurs, graph-aware.\n' } : s)),

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -3,7 +3,7 @@
  *
  * They used to be appended, in full, to every tool description that they
  * covered: the content rule rode on all twelve file tools, the agent-guide
- * reminder on all of them plus the shell, the write-mode and escape-sequence
+ * reminder on all of them, the write-mode and escape-sequence
  * paragraphs on two or three apiece. A description then ran to two or three
  * thousand characters, most of it text the agent had already read on the tool
  * above — and clients cut long descriptions from the END, which is where the

package/src/modules/audit/__tests__/agent-audit.service.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it, vi } from 'vitest';
 import type { SQL } from 'drizzle-orm';
 import { PgDialect } from 'drizzle-orm/pg-core';
 import { AgentAuditService, retentionDaysFrom } from '../agent-audit.service.js';
-import { AuditPrincipalNotFoundError, InvalidCursorError } from '../audit.contract.js';
+import { AuditPrincipalNotFoundError, InvalidCursorError, pagePrincipalId, parsePagePrincipalId } from '../audit.contract.js';
 import type { Database } from '../../database/connection.js';
 import { agentConnections, oauthTokens } from '../../database/schema.js';
 import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
@@ -217,6 +217,8 @@ describe('AgentAuditService.listPrincipals', () => {
           { keyId: 'k-1', connectionId: null, n: 7 },
           { keyId: null, connectionId: 'c-1', n: 3 },
         ],
+        // pages
+        [],
       ],
       { listForUser: vi.fn(async () => [key({ lastUsedAt: NOW - 2 * DAY })]) },
     );
@@ -235,6 +237,7 @@ describe('AgentAuditService.listPrincipals', () => {
       [
         [{ connection: connection({ id: 'c-bob', userId: BOB.id }), user: BOB }],
         [],
+        [],
       ],
       { listForDeployment: vi.fn(async () => [{ ...key({}), user: ALICE }]) },
     );
@@ -247,6 +250,80 @@ describe('AgentAuditService.listPrincipals', () => {
   });
 });
 
+describe('AgentAuditService — a page as a principal', () => {
+  const ALICE_ID = '11111111-1111-4111-8111-111111111111';
+  const PAGE = 'Dashboards/Roadmap.html';
+
+  it("records a page's call under its path, with neither a key nor a connection", async () => {
+    const { service, captured } = makeService([undefined]);
+    service.record({
+      userId: ALICE_ID,
+      principal: { kind: 'page', path: PAGE },
+      kind: 'capability',
+      manual: null,
+      name: 'edit_file',
+      outcome: 'refused',
+      durationMs: null,
+    });
+    await flush();
+    expect(captured.values[0]).toMatchObject({
+      userId: ALICE_ID,
+      keyId: null,
+      connectionId: null,
+      pagePath: PAGE,
+      name: 'edit_file',
+      outcome: 'refused',
+    });
+  });
+
+  it('lists each page a person opened as a row of its own, labelled by its path, never revocable', async () => {
+    const { service } = makeService([
+      [{ ...ALICE, id: ALICE_ID }],
+      [],
+      [],
+      [
+        {
+          userId: ALICE_ID,
+          pagePath: PAGE,
+          n: 4,
+          first: new Date(NOW - DAY),
+          last: new Date(NOW - 60_000),
+          user: { ...ALICE, id: ALICE_ID },
+        },
+      ],
+    ]);
+    const rows = await service.listPrincipals({ userId: ALICE_ID });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      kind: 'page',
+      id: pagePrincipalId(ALICE_ID, PAGE),
+      label: PAGE,
+      eventCount: 4,
+      createdAt: NOW - DAY,
+      lastUsedAt: NOW - 60_000,
+      revokedAt: null,
+    });
+  });
+
+  it("reads a page's events by its person and path, and owns it by that person", async () => {
+    const id = pagePrincipalId(ALICE_ID, PAGE);
+    expect(parsePagePrincipalId(id)).toEqual({ userId: ALICE_ID, path: PAGE });
+
+    const events = makeService([[], [{ total: 0 }]]);
+    await events.service.listEvents({ kind: 'page', id }, { limit: 10 });
+    expect(render(events.captured.where[0]).params).toEqual([ALICE_ID, PAGE]);
+
+    const owned = makeService([[{ id: 'e-1' }]]);
+    await expect(owned.service.ownerOf({ kind: 'page', id })).resolves.toBe(ALICE_ID);
+    const never = makeService([[]]);
+    await expect(never.service.ownerOf({ kind: 'page', id })).resolves.toBeNull();
+    // An id that names no person and path is no page, without asking the database.
+    const bogus = makeService([]);
+    await expect(bogus.service.ownerOf({ kind: 'page', id: 'not-a-page' })).resolves.toBeNull();
+    expect(bogus.counts.select).toBe(0);
+  });
+});
+
 describe('AgentAuditService.listEvents', () => {
   const eventId = (i: number) => `00000000-0000-4000-8000-00000000000${i}`;
   const eventRow = (i: number) => ({