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

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

@@ -66,19 +66,30 @@ import {
   DIRECTORY_SYNC_BOT_NAME,
 } from './directory-sync-bot.js';
 
+/**
+ * What one spec of a batched read came back as: a blob's text, nothing at
+ * that path, or an object that is not a file (a directory, say). The last
+ * two are told apart on purpose: for the model at a commit, a path that is
+ * there but is not a file is not "absent", it is config the model cannot be
+ * read from.
+ */
+type CatFileOutcome =
+  | { kind: 'blob'; text: string }
+  | { kind: 'missing' }
+  | { kind: 'non-blob'; type: string };
+
 /**
  * Read many objects from a git repo in ONE `git cat-file --batch` process.
  * `specs` are `<ref>:<path>` lines; the result array is index-aligned with
- * them — the blob's text, or null when the spec is missing/ambiguous at the
- * ref or resolves to a non-blob (e.g. a directory). Output protocol per
- * request: `<oid> <type> <size>\n<size bytes>\n`, or `<spec> missing\n`
- * (the spec may itself contain spaces, hence the endsWith checks).
+ * them. Output protocol per request: `<oid> <type> <size>\n<size bytes>\n`,
+ * or `<spec> missing\n` (the spec may itself contain spaces, hence the
+ * endsWith checks).
  */
-async function catFileBatch(
+async function catFileBatchOutcomes(
   runner: IGitRunner,
   repoDir: string,
   specs: string[],
-): Promise<(string | null)[]> {
+): Promise<CatFileOutcome[]> {
   // Bytes, not text: every `<size>` in the header counts bytes, and the walk
   // below has to step by that count through content that is not all ASCII.
   // One spec per LINE is the protocol, and this walk depends on getting back
@@ -91,7 +102,7 @@ async function catFileBatch(
     input: `${specs.join('\n')}\n`,
     encoding: 'buffer',
   });
-  const results: (string | null)[] = [];
+  const results: CatFileOutcome[] = [];
   let off = 0;
   for (let i = 0; i < specs.length; i++) {
     const nl = out.indexOf(0x0a, off);
@@ -99,7 +110,7 @@ async function catFileBatch(
     const header = out.subarray(off, nl).toString('utf-8');
     off = nl + 1;
     if (header.endsWith(' missing') || header.endsWith(' ambiguous')) {
-      results.push(null);
+      results.push({ kind: 'missing' });
       continue;
     }
     const parts = header.split(' ');
@@ -107,14 +118,33 @@ async function catFileBatch(
     if (parts.length !== 3 || !Number.isInteger(size) || size < 0) {
       throw new Error(`unexpected git cat-file header: ${header}`);
     }
-    // Non-blob (a directory path resolves to a tree) → null, but the
-    // payload still has to be skipped to stay aligned.
-    results.push(parts[1] === 'blob' ? out.subarray(off, off + size).toString('utf-8') : null);
+    // A non-blob (a directory path resolves to a tree) is reported as such,
+    // and its payload still has to be skipped to stay aligned.
+    results.push(
+      parts[1] === 'blob'
+        ? { kind: 'blob', text: out.subarray(off, off + size).toString('utf-8') }
+        : { kind: 'non-blob', type: parts[1]! },
+    );
     off += size + 1; // payload + trailing LF
   }
   return results;
 }
 
+/**
+ * {@link catFileBatchOutcomes} for callers that want text or nothing: the
+ * blob's text, or null when the spec is missing at the ref or resolves to a
+ * non-blob — the own-entries reads, where a directory where a file was
+ * named simply carries no entries.
+ */
+async function catFileBatch(
+  runner: IGitRunner,
+  repoDir: string,
+  specs: string[],
+): Promise<(string | null)[]> {
+  const outcomes = await catFileBatchOutcomes(runner, repoDir, specs);
+  return outcomes.map((o) => (o.kind === 'blob' ? o.text : null));
+}
+
 
 interface AccessModel {
   roles: RolesIndex;
@@ -1384,22 +1414,31 @@ export class AccessControlService implements IAccessControl {
    *
    * This is what makes the change-request gates affordable. One detail read
    * plus one approval click runs six at-ref gates, and before this cache
-   * every one of them rebuilt the model from git: an `ls-tree -r` plus a
-   * `git show` per `access.md`, ~270ms each on a real knowledge base. Six
-   * builds per click was the lag behind the approve checkmark.
+   * every one of them rebuilt the model from git. A build is two git calls
+   * (`buildModelAtCommit`: one `ls-tree`, one `cat-file --batch` for every
+   * file the model reads), and each call forks the server process, which
+   * costs tens of milliseconds on a server holding a large heap.
    *
-   * Bounded FIFO, so a long-lived server holds the last few tips rather than
-   * one model per commit it ever gated against. A build that found no usable
-   * roles.yaml is deliberately NOT cached, and a build that saw any git read
-   * fail never becomes a model at all: it throws AccessUnreadableError and the
-   * gate fails closed for that call. Both are what a transient failure looks
-   * like, and pinning either to a commit would turn one hiccup into a wrong
-   * verdict, denying or granting, until the base branch moved. Concurrent
-   * misses on the same commit share one build via `atRefInFlight`.
+   * Bounded FIFO. The bound is sized for a listing that resolves access at
+   * every open change request's two refs: one commit per open request plus
+   * the targets, and a knowledge base with a hundred open requests was
+   * evicting in a cycle under the old bound of 64, rebuilding every model on
+   * every listing — thousands of forks, minutes of the main thread, and
+   * every other request waiting behind them. A commit's tree never changes,
+   * so a model is good for as long as it is held; the bound only caps memory.
+   *
+   * A commit with no roles.yaml is remembered too (`atRefNoRoles`): the batch
+   * read answers "missing" for it from git itself, which is as final as the
+   * commit. What is never cached is a build that saw a git read FAIL: it
+   * throws AccessUnreadableError and the gate fails closed for that call, and
+   * pinning that to a commit would turn one hiccup into a wrong verdict until
+   * the branch moved. Concurrent misses on the same commit share one build
+   * via `atRefInFlight`.
    */
   private readonly atRefCache = new Map<string, AtRefModel>();
+  private readonly atRefNoRoles = new Set<string>();
   private readonly atRefInFlight = new Map<string, Promise<AtRefBuild>>();
-  private static readonly AT_REF_CACHE_MAX = 64;
+  private static readonly AT_REF_CACHE_MAX = 512;
 
   /**
    * Canonicalised deployment-owner emails (see `AccessModel.deploymentOwners`).
@@ -2600,28 +2639,35 @@ export class AccessControlService implements IAccessControl {
   /**
    * List every `access.md` path that exists at any depth as of `ref`.
    * The access tree is structure-agnostic: any `access.md` participates
-   * regardless of where it sits. Uses `git ls-tree -r --name-only`.
-   * `'error'` when git failed: a model built without its access files is
-   * not the model, and the caller must not cache it as one.
+   * regardless of where it sits. Uses `git ls-tree -r -z --name-only`: `-z`
+   * puts a NUL between paths and prints them as they are, where the default
+   * output C-quotes a path with a non-ASCII or special character, which would
+   * then name nothing when read back. `'error'` when git failed: a model
+   * built without its access files is not the model, and the caller must not
+   * cache it as one.
    */
   private async listAccessFilesAtRef(
     repoDir: string,
     ref: string,
-  ): Promise<{ accessFiles: string[]; pluginDirs: string[] } | 'error'> {
+  ): Promise<{ accessFiles: string[]; pluginDirs: string[]; named: Set<string> } | 'error'> {
     try {
-      const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '--name-only', ref]);
+      const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '-z', '--name-only', ref]);
       const out: string[] = [];
       const pluginDirs: 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.
+      const named = new Set<string>();
       const { pluginsDir } = this.kb.layout;
-      for (const line of stdout.split('\n')) {
-        const p = line.trim();
+      for (const p of stdout.split('\0')) {
         if (!p) continue;
         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 };
+      return { accessFiles: out, pluginDirs, named };
     } catch {
       return 'error';
     }
@@ -2666,6 +2712,9 @@ export class AccessControlService implements IAccessControl {
       const key = `${workspaceId}\0${commit}`;
       const hit = this.atRefCache.get(key);
       if (hit) return hit;
+      // A commit known to carry no roles.yaml: the next candidate, without a
+      // build (see `atRefNoRoles`).
+      if (this.atRefNoRoles.has(key)) continue;
       // Registered BEFORE the first await on the build path, so concurrent
       // misses on one commit share a single build instead of all racing past
       // an empty in-flight check together.
@@ -2674,6 +2723,7 @@ export class AccessControlService implements IAccessControl {
         pending = this.buildModelAtCommit(repoDir, commit, candidate)
           .then((built) => {
             if (typeof built !== 'string') this.rememberAtRef(key, built);
+            else if (built === 'no-roles') this.rememberNoRolesAtRef(key);
             return built;
           })
           .finally(() => {
@@ -2718,6 +2768,14 @@ export class AccessControlService implements IAccessControl {
     }
   }
 
+  private rememberNoRolesAtRef(key: string): void {
+    this.atRefNoRoles.add(key);
+    if (this.atRefNoRoles.size > AccessControlService.AT_REF_CACHE_MAX) {
+      const oldest = this.atRefNoRoles.values().next().value;
+      if (oldest !== undefined) this.atRefNoRoles.delete(oldest);
+    }
+  }
+
   /**
    * The uncached build behind `loadModelAtRef`: the whole access tree read
    * at `commit`. `label` is the candidate ref the commit came from, kept for
@@ -2725,6 +2783,15 @@ export class AccessControlService implements IAccessControl {
    * means the commit carries no roles.yaml (the caller tries its next
    * candidate); `'malformed'` means it does but it doesn't parse (the caller
    * answers null, as it always has).
+   *
+   * TWO git calls, whatever the tree holds: one `ls-tree` to learn which
+   * files the model is made of, then one `cat-file --batch` that reads all of
+   * them — roles.yaml, the groups sources, every access.md and every plugin
+   * manifest. It used to be one `git show` per file, and each git call forks
+   * the server process, which on a server holding a large heap costs tens of
+   * milliseconds of the main thread per call: a knowledge base with a few
+   * dozen access files paid a second or more per commit, times every ref a
+   * listing resolves.
    */
   private async buildModelAtCommit(
     repoDir: string,
@@ -2737,20 +2804,74 @@ export class AccessControlService implements IAccessControl {
     // and the caller fails closed (AccessUnreadableError, a 503) until a
     // retry reads the tree in full.
     const tag = `${label}@${commit.slice(0, 7)}`;
+
+    const listed = await this.listAccessFilesAtRef(repoDir, commit);
+    if (listed === 'error') {
+      logger(`access@${tag}`).warn('listing access.md files failed; refusing to decide from a partial tree');
+      throw new AccessUnreadableError(label, 'access.md (ls-tree)');
+    }
+    const wanted = [
+      'roles.yaml',
+      SYNCED_GROUPS_YAML,
+      GROUPS_YAML,
+      ...listed.accessFiles,
+      ...listed.pluginDirs.map((dir) => `${dir}/${PLUGIN_MANIFEST_FILE}`),
+    ];
+    let outcomes: CatFileOutcome[];
+    try {
+      outcomes = await catFileBatchOutcomes(this.gitRunner, repoDir, wanted.map((p) => `${commit}:${p}`));
+    } catch (err) {
+      // The operational signal: one line per failed build, naming the commit,
+      // so a run of these is visible in the logs.
+      logger(`access@${tag}`).warn(
+        `git read of the access tree failed; refusing to decide from a partial tree: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      throw new AccessUnreadableError(label, 'access tree (cat-file)');
+    }
+    const fetched = new Map<string, CatFileOutcome>();
+    wanted.forEach((p, i) => fetched.set(p, outcomes[i] ?? { kind: 'missing' }));
+    const refuse = (relativePath: string, why: string): never => {
+      logger(`access@${tag}`).warn(`${relativePath} ${why}; refusing to decide from a partial tree`);
+      throw new AccessUnreadableError(label, relativePath);
+    };
+    // What the build reads. "Missing" from the batch is "absent" only for a
+    // groups source the tree does not name. A path the tree names — an
+    // access.md, a plugin manifest, or a groups file the listing carried —
+    // that comes back missing has a blob git could not read (a lost object),
+    // and one that is not a file is a tree the model cannot be read from:
+    // either way the build fails closed rather than drop what that file
+    // would deny. A path the build did not prefetch (none today) is read on
+    // its own, told apart from a git failure as before.
+    const inTree = (relativePath: string) =>
+      listed.named.has(relativePath) || !(relativePath === SYNCED_GROUPS_YAML || relativePath === GROUPS_YAML);
     const read = async (relativePath: string): Promise<string | null> => {
-      const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
-      if (outcome.kind === 'error') {
-        // The operational signal: one line per failed read, naming the commit
-        // and the path, so a run of these is visible in the logs.
-        logger(`access@${tag}`).warn(`git read of ${relativePath} failed; refusing to decide from a partial tree`);
-        throw new AccessUnreadableError(label, relativePath);
+      const got = fetched.get(relativePath);
+      if (got === undefined) {
+        const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
+        if (outcome.kind === 'error') refuse(relativePath, 'could not be read');
+        return outcome.kind === 'text' ? outcome.text : null;
       }
-      return outcome.kind === 'text' ? outcome.text : null;
+      if (got.kind === 'blob') return got.text;
+      if (got.kind === 'non-blob') return refuse(relativePath, `is a ${got.type}, not a file`);
+      if (!inTree(relativePath)) return null;
+      return refuse(relativePath, 'is in the tree but its blob could not be read');
     };
 
-    const rolesYaml = await read('roles.yaml');
-    if (rolesYaml === null) return 'no-roles';
-    const rolesParsed = parseRolesYaml(rolesYaml);
+    // roles.yaml decides the build's outcome, so its states are read
+    // directly. Absent from the tree is "no roles here" (the caller tries
+    // its next candidate ref). In the tree but unreadable refuses the build:
+    // answering "no roles" for it would be remembered for the commit and
+    // would send a short ref through to origin, which may grant. A directory
+    // of that name is as malformed as a file that does not parse (the caller
+    // answers null, and never falls through to a ref that might grant what
+    // this one does not).
+    const roles = fetched.get('roles.yaml') ?? { kind: 'missing' as const };
+    if (roles.kind === 'missing') {
+      if (listed.named.has('roles.yaml')) refuse('roles.yaml', 'is in the tree but its blob could not be read');
+      return 'no-roles';
+    }
+    if (roles.kind === 'non-blob') return 'malformed';
+    const rolesParsed = parseRolesYaml(roles.text);
     if (!rolesParsed.ok) return 'malformed';
 
     // Same group loading as the working-tree model, read AT THE COMMIT — the
@@ -2775,11 +2896,6 @@ export class AccessControlService implements IAccessControl {
     for (const w of mergeWarnings) logger(`access@${tag}`).warn(w);
 
     const accessFiles = new Map<string, AccessFile>();
-    const listed = await this.listAccessFilesAtRef(repoDir, commit);
-    if (listed === 'error') {
-      logger(`access@${tag}`).warn('listing access.md files failed; refusing to decide from a partial tree');
-      throw new AccessUnreadableError(label, 'access.md (ls-tree)');
-    }
     for (const p of listed.accessFiles) {
       const text = await read(p);
       if (text === null) continue;

package/src/modules/auth/index.ts

@@ -0,0 +1,29 @@
+/**
+ * The entry other modules reach auth through: its admission contract, and
+ * the two things a module checking a credential or refusing a switched-off
+ * account needs to agree with auth on. The composition root wires the rest.
+ *
+ * The embed reaches auth here. Modules written before this entry existed
+ * still import auth's files directly (`auth.service.ts`, the middleware's
+ * request augmentation, `account-admission.ts`); each moves here as it is
+ * touched, and what it needs is added here then — this file holds what is
+ * offered, not everything auth has.
+ */
+export {
+  ACCOUNT_DEACTIVATED_MESSAGE,
+  AccountAdmissionRefusedError,
+  AccountChangeRefusedError,
+  AccountDeactivatedError,
+  AuthBackendError,
+  admitEveryone,
+  type AccountAdmissionVerdict,
+  type AccountProvisionReason,
+  type IAccountAdmission,
+} from './account-admission.js';
+// A constant-time comparison for a secret arriving on a request, so a
+// shared-secret check elsewhere cannot leak the secret's length or prefix by
+// timing — one implementation, auth's.
+export { timingSafeStringEqual } from './password-hash.js';
+// The Express `Request` augmentation (`req.userId`, …): a module whose routes
+// read it imports this entry, never the middleware file.
+import './auth.middleware.js';

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

@@ -168,15 +168,51 @@ describe('EmbedService: minting', () => {
   /**
    * The token rides in the tool result and so in the chat transcript;
    * whoever holds it acts on that one file as its user until it expires.
-   * One hour (Razvan, 2026-10-09), down from the two the embed used before.
+   * Five minutes (Razvan, 2026-10-09): the chat view renews it through its
+   * host when a call is refused, so a short life costs the reader nothing.
    */
-  it('mints a token that lives one hour', async () => {
+  it('mints an open_page token that lives five minutes', async () => {
     const { service } = build();
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     const { iat, exp } = claimsOf(token) as { iat: number; exp: number };
+    expect(exp - iat).toBe(5 * 60);
+  });
+
+  /** The connector frames `/embed` and has no host to renew through: its hour stands. */
+  it('mints a connector token that keeps its one-hour lifetime', async () => {
+    const { service } = build();
+    const { token } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    const { iat, exp } = claimsOf(token) as { iat: number; exp: number };
     expect(exp - iat).toBe(60 * 60);
   });
 
+  /**
+   * Both kinds are read by the same verification: each loads while it lives
+   * and is refused as a token once it has run out — the user's after five
+   * minutes, the connector's only after the hour.
+   */
+  it('reads both kinds while they live and refuses each once its own lifetime is over', async () => {
+    vi.useFakeTimers({ toFake: ['Date'] });
+    try {
+      vi.setSystemTime(new Date('2026-10-09T10:00:00Z'));
+      const { service } = build();
+      const user = await service.mintForUser({ userId: USER.id, reference: REPO });
+      const connector = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T10:04:50Z'));
+      await expect(service.loadFile(user.token)).resolves.toMatchObject({ repoRelative: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T10:05:01Z'));
+      await expect(service.loadFile(user.token)).rejects.toThrow(EmbedTokenError);
+      await expect(service.loadFile(connector.token)).resolves.toMatchObject({ repoRelative: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T11:00:01Z'));
+      await expect(service.loadFile(connector.token)).rejects.toThrow(EmbedTokenError);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('mints for an outside account — the connector path, unchanged', async () => {
     const { service } = build();
     const { token } = await service.mintToken({
@@ -189,7 +225,9 @@ describe('EmbedService: minting', () => {
 
   it('keeps the token PSEUDONYMOUS — no address, no name', async () => {
     const { service } = build();
-    const { token } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    const { token, embedUrl } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    // The connector's host sizes its frame to the content: its view is told so.
+    expect(embedUrl).toBe(`https://hexis.example/embed?token=${encodeURIComponent(token)}&sizing=content`);
     expect(JSON.stringify(claimsOf(token))).not.toContain(USER.email);
     expect(JSON.stringify(claimsOf(token))).not.toContain(USER.name);
   });
@@ -711,6 +749,41 @@ describe('EmbedService: a switched-off account', () => {
   });
 });
 
+/**
+ * A distribution's own token-authed route beside the embed (a graph for a
+ * dashboard) asks who is looking before it serves anything, and must judge
+ * the viewer exactly as the embed does.
+ */
+describe('EmbedService: who is looking through a token', () => {
+  it('answers the linked user, their verdicts on the file, and the file', async () => {
+    const { service } = build({ canWrite: false });
+    const { token } = await service.mintForUser({ userId: USER.id, reference: `${REPO}#intro` });
+    expect(await service.viewerOf(token)).toEqual({
+      linked: true,
+      user: expect.objectContaining({ id: USER.id, email: USER.email }),
+      canRead: true,
+      canWrite: false,
+      repoRelative: REPO,
+    });
+  });
+
+  it('answers nobody for an unlinked outside account, and refuses a switched-off one as the embed does', async () => {
+    const unlinked = build({ linkedUserId: null });
+    const outside = await unlinked.service.mintToken({ accountId: 'acc-1', reference: REPO });
+    expect(await unlinked.service.viewerOf(outside.token)).toEqual({
+      linked: false,
+      user: null,
+      canRead: false,
+      canWrite: false,
+      repoRelative: REPO,
+    });
+    const off = build({ active: false });
+    const { token } = await off.service.mintForUser({ userId: USER.id, reference: REPO });
+    await expect(off.service.viewerOf(token)).rejects.toThrow(ACCOUNT_DEACTIVATED_MESSAGE);
+    await expect(off.service.viewerOf('not-a-token')).rejects.toThrow(EmbedTokenError);
+  });
+});
+
 describe('EmbedService: the roles.yaml write gate', () => {
   const ROLES = `${KB}/roles.yaml`;
   const VALID = 'roles:\n  Admin:\n    - a@x.eu\n';

package/src/modules/embed/__tests__/embed.tools.test.ts

@@ -2,6 +2,7 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import { checkFor } from '@bevel-software/platform-mcp-core';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
@@ -122,6 +123,21 @@ describe('open_page: the listing', () => {
     expect(internal).not.toContain(OPEN_PAGE_TOOL);
   });
 
+  /**
+   * The chat view renews its token by having its host call this tool with
+   * `{ body: { path, heading } }` (see `mcp-app/page.html`). The listing's
+   * own check decides what `/api/mcp` accepts: that shape passes it, and the
+   * flat one the view once sent is refused, so no token ever came back.
+   */
+  it("accepts the chat view's renewal arguments under body, and refuses them flat", async () => {
+    const { registry } = await serve();
+    const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
+    const compiled = checkFor(def.inputs);
+    if (!compiled.checkable) throw new Error(`open_page's schema is not checkable: ${compiled.reason}`);
+    expect(compiled.check({ body: { path: 'Data/Thing.md', heading: 'what-it-is' } })).toEqual([]);
+    expect(compiled.check({ path: 'Data/Thing.md', heading: 'what-it-is' })).not.toEqual([]);
+  });
+
   it('takes a path and an optional heading, and no branch at all', async () => {
     const { registry } = await serve();
     const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
@@ -197,6 +213,19 @@ describe('open_page: the answer', () => {
     expect(body.appUrl).toContain('#what-it-is');
   });
 
+  /**
+   * The view renews its token by calling this tool again with the arguments
+   * it was opened with, and the result is all it is told — so the heading
+   * comes back beside the path, and is absent when none was named.
+   */
+  it('echoes the heading beside the path, for the view to call again with', async () => {
+    const { call } = await serve();
+    const { body } = await call({ path: 'Data/Thing.md', heading: 'what-it-is' });
+    expect(body).toMatchObject({ path: 'Data/Thing.md', heading: 'what-it-is' });
+    const plain = await call({ path: 'Data/Thing.md' });
+    expect(plain.body).not.toHaveProperty('heading');
+  });
+
   it('accepts a path with or without the knowledge-base prefix, as read_file documents', async () => {
     const { call, mints } = await serve();
     await call({ path: 'Data/Thing.md' });

package/src/modules/embed/embed.interface.ts

@@ -103,6 +103,19 @@ export interface EmbedLinkedAccount {
  */
 export type EmbedNodeIdResolver = (nodeId: string) => Promise<string | null>;
 
+/** The viewer behind a token, as {@link IEmbedService.viewerOf} answers it. */
+export interface EmbedViewer {
+  /** Whether the token's identity resolved to a user at all. */
+  linked: boolean;
+  /** The linked user; null when unlinked. */
+  user: AuthUser | null;
+  /** Read access on the token's file — always false when unlinked. */
+  canRead: boolean;
+  canWrite: boolean;
+  /** The token's file, repository-relative. */
+  repoRelative: string;
+}
+
 /**
  * What the embed service needs of the workspace: the clone of a branch, and
  * four verbs on one file of it. A port rather than the workspace service
@@ -165,6 +178,17 @@ export interface IEmbedService {
   /** Load the file the token is scoped to, with the viewer's read/write status. */
   loadFile(token: string): Promise<EmbedFileView>;
 
+  /**
+   * Who is looking through `token`, and at what: the resolved viewer (the
+   * linked user, or none), their read and write verdicts on the token's
+   * file, and the file. The one answer a distribution's own token-authed
+   * route beside this surface (a graph for a dashboard, say) asks before it
+   * serves anything, so it judges the viewer exactly as the embed does — the
+   * same token check, the same account link, the same switched-off refusal.
+   * Throws as `loadFile` throws for a token that is invalid or expired.
+   */
+  viewerOf(token: string): Promise<EmbedViewer>;
+
   /**
    * The raw bytes of the embedded file, or of one asset `path` beside it (an
    * image a markdown page shows — a file no reader edits as text, or an SVG,