@openparachute/vault 0.7.3-rc.8 → 0.7.3

package/core/src/notes.ts

@@ -2778,6 +2778,22 @@ export const DISPLAY_TITLE_MAX_LEN = 120;
  */
 const FRONTMATTER_SCAN_LINES = 100;
 
+/**
+ * Shared by `computeDisplayTitle` and `computeLede`: given `content` already
+ * split into `lines`, return the index of the first line that counts as the
+ * start of the DOCUMENT body — after a leading closed frontmatter block, if
+ * `content` opens with one (see `computeDisplayTitle`'s frontmatter-skip
+ * doc for the full rationale). `0` when there's no leading frontmatter.
+ */
+function skipLeadingFrontmatter(lines: string[]): number {
+  if (lines[0]?.trim() !== "---") return 0;
+  const scanLimit = Math.min(lines.length, FRONTMATTER_SCAN_LINES);
+  for (let i = 1; i < scanLimit; i++) {
+    if (lines[i]?.trim() === "---") return i + 1;
+  }
+  return 0;
+}
+
 /**
  * Derive a note's display title: the first non-empty line of `content`,
  * with a leading markdown heading marker (`#` through `######`) and its
@@ -2807,16 +2823,7 @@ const FRONTMATTER_SCAN_LINES = 100;
 export function computeDisplayTitle(content: string | null | undefined): string | null {
   if (!content) return null;
   const lines = content.split("\n");
-  let startIndex = 0;
-  if (lines[0]?.trim() === "---") {
-    const scanLimit = Math.min(lines.length, FRONTMATTER_SCAN_LINES);
-    for (let i = 1; i < scanLimit; i++) {
-      if (lines[i]?.trim() === "---") {
-        startIndex = i + 1;
-        break;
-      }
-    }
-  }
+  const startIndex = skipLeadingFrontmatter(lines);
   for (let i = startIndex; i < lines.length; i++) {
     const stripped = lines[i]!.replace(/^#{1,6}\s*/, "").trim();
     if (stripped === "") continue;
@@ -2829,6 +2836,58 @@ export function computeDisplayTitle(content: string | null | undefined): string
   return null;
 }
 
+/** Max code points in a computed `lede` (summaries-as-content, 2026-07-17 dialogue). */
+export const LEDE_MAX_LEN = 400;
+
+/**
+ * Derive a note's "lede": the first non-empty PARAGRAPH after the title
+ * line (a run of consecutive non-blank lines, whitespace-collapsed to one
+ * line, truncated to `LEDE_MAX_LEN` code points). `null` when there's no
+ * paragraph after the title — a title-only note has no lede to report, and
+ * callers must not fall back to repeating the title itself.
+ *
+ * This is the machinery half of a soft convention (2026-07-17 dialogue):
+ * summaries work better as visible CONTENT — a note's opening paragraph —
+ * than as hidden metadata, because visible text gets corrected by the notes
+ * that reference it while hidden metadata rots unnoticed. Nothing validates
+ * that a note actually opens with a title + lede; this function just reports
+ * what it finds, honestly, using the SAME title-line rule as
+ * `computeDisplayTitle` (including its frontmatter skip) so a caller that
+ * shows both title and lede sees them agree on where the title ends.
+ */
+export function computeLede(content: string | null | undefined): string | null {
+  if (!content) return null;
+  const lines = content.split("\n");
+  const bodyStart = skipLeadingFrontmatter(lines);
+
+  let titleLine = -1;
+  for (let i = bodyStart; i < lines.length; i++) {
+    if (lines[i]!.replace(/^#{1,6}\s*/, "").trim() !== "") {
+      titleLine = i;
+      break;
+    }
+  }
+  if (titleLine === -1) return null; // no title at all — nothing to find a lede after
+
+  let i = titleLine + 1;
+  while (i < lines.length && lines[i]!.trim() === "") i++; // skip blank lines after the title
+
+  const paragraphLines: string[] = [];
+  while (i < lines.length && lines[i]!.trim() !== "") {
+    paragraphLines.push(lines[i]!);
+    i++;
+  }
+  if (paragraphLines.length === 0) return null; // title-only note
+
+  const paragraph = paragraphLines.join(" ").replace(/\s+/g, " ").trim();
+  if (paragraph === "") return null;
+
+  const codePoints = Array.from(paragraph);
+  return codePoints.length > LEDE_MAX_LEN
+    ? codePoints.slice(0, LEDE_MAX_LEN).join("")
+    : paragraph;
+}
+
 /**
  * Convert a full Note into its lean index shape:
  * drops `content`, adds `byteSize`, a whitespace-collapsed `preview`, and a

package/core/src/vault-projection.ts

@@ -283,27 +283,34 @@ function sqliteToUserType(t: string): string {
  * its own context on them (bytes never ride MCP either way).
  *
  * `ticketsEnabled` reflects whether THIS door has wired an
- * `AttachmentTicketProvider` (bun: always, as of this PR; cloud: not yet
- * — its mirror is a separate PR). An unwired door omits BOTH the ticket
- * tools from `tools/list` (see `generateMcpTools`'s `attachmentTickets`
- * opt) AND the ticket-tool sentences here — the brief never dangles a
- * pointer at a tool the agent can't actually call.
+ * `AttachmentTicketProvider` (bun: always, as of the Wave 1 PR; cloud: not
+ * yet — its mirror is a separate PR). `readEnabled` reflects whether it's
+ * wired an `AttachmentBytesProvider` (bun: always, as of this PR — Wave 2).
+ * An unwired seam omits BOTH its tool(s) from `tools/list` (see
+ * `generateMcpTools`'s `attachmentTickets` / `attachmentBytes` opts) AND
+ * its sentence here — the brief never dangles a pointer at a tool the
+ * agent can't actually call.
  *
  * Kept as a single dense paragraph (not its own multi-line list) to stay
  * inside the connect-time brief's token budget — see
  * `projectionToMarkdown`'s doc comment.
  */
-export function attachmentsInstructionBlock(opts: { ticketsEnabled: boolean }): string {
+export function attachmentsInstructionBlock(opts: { ticketsEnabled: boolean; readEnabled?: boolean }): string {
   const sentences: string[] = [
-    "Notes can carry file attachments (`include_attachments: true` on `query-notes` returns their rows; bytes don't ride MCP).",
+    "Notes can carry file attachments (`include_attachments: true` on `query-notes` returns their rows; bytes don't ride MCP tool RESULTS unless you ask for them).",
   ];
   if (opts.ticketsEnabled) {
     sentences.push(
-      "To move bytes, call `request-attachment-upload` / `request-attachment-download` — each mints a short-lived, single-use URL (with a ready-to-run `curl_example`) your shell spends directly; no MCP session credential is needed to spend it.",
+      "To move bytes without spending your own context, call `request-attachment-upload` / `request-attachment-download` — each mints a short-lived, single-use URL (with a ready-to-run `curl_example`) your shell spends directly; no MCP session credential is needed to spend it.",
+    );
+  }
+  if (opts.readEnabled) {
+    sentences.push(
+      "To read an attachment directly into this conversation, call `read-attachment` — text comes back as a paginated `content` slice, images as a real image you can see, audio/video as a transcript pointer (never raw bytes), and PDF/other binary formats point you at a download ticket instead.",
     );
   }
   sentences.push(
-    "If your runtime holds this vault's own API token, REST works too: upload = `POST {base}/storage/upload` (multipart `file`, ≤100 MB) then `POST {base}/notes/{id}/attachments` `{path, mimeType, transcribe?}`; download = `GET {base}/storage/{path}` with the same `Authorization: Bearer`. Audio attached with `transcribe: true` is transcribed automatically.",
+    "If your runtime holds this vault's own API token, REST works too: upload = `POST {base}/storage/upload` (multipart `file`, ≤100 MB) then `POST {base}/notes/{id}/attachments` `{path, mimeType, transcribe?}`; download = `GET {base}/storage/{path}` with the same `Authorization: Bearer` (honors a `Range: bytes=a-b` header for partial reads). Audio attached with `transcribe: true` is transcribed automatically.",
   );
   return sentences.join(" ");
 }
@@ -344,7 +351,7 @@ export function projectionToMarkdown(args: {
    * that hasn't wired ticket support yet (or a test fixture) never
    * accidentally advertises tools it can't back.
    */
-  attachments?: { ticketsEnabled: boolean };
+  attachments?: { ticketsEnabled: boolean; readEnabled?: boolean };
 }): string {
   const { vaultName, description, projection, coordinates } = args;
   const stats = projection.stats;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.3-rc.8",
+  "version": "0.7.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/attachment-bytes.ts

@@ -0,0 +1,68 @@
+/**
+ * Attachment bytes — bun's filesystem implementation of the model-lane
+ * (Wave 2) `AttachmentBytesProvider` seam (`core/src/attachment/bytes-provider.ts`).
+ *
+ * Stateless by design (unlike the ticket provider, there's no in-memory
+ * state to share across requests) — a fresh instance per MCP session is
+ * cheap, so `createFsAttachmentBytesProvider` is a plain factory, not a
+ * shared singleton.
+ *
+ * `readRange` uses `Bun.file(path).slice(start, end)` — a bounded,
+ * positional read (Bun resolves the slice lazily via `pread` under the
+ * hood), never the whole-file `readFileSync` this design explicitly moves
+ * away from (see `handleStorage`'s REST `Range` support in `src/routes.ts`
+ * for the sibling fix on the byte-serve side).
+ */
+
+import { existsSync, statSync } from "fs";
+import { join, normalize } from "path";
+import type { Attachment } from "../core/src/types.ts";
+import type { AttachmentBytesProvider } from "../core/src/attachment/bytes-provider.ts";
+import { assetsDir } from "./config.ts";
+import { transcriptPathFor } from "./transcript-note.ts";
+import { getVaultStore } from "./vault-store.ts";
+
+/**
+ * Resolve + confine an attachment's on-disk path under this vault's assets
+ * dir. Same guard as the ticket download spend route (`src/attachment-tickets.ts`)
+ * and the REST byte-serve route (`src/routes.ts`): normalize, then require
+ * the result to still start with the (normalized) assets root — a stored
+ * `path` can never resolve outside it, but a defense-in-depth check costs
+ * nothing. Returns `null` on a traversal attempt (treated identically to
+ * "file doesn't exist" by every caller here).
+ */
+function resolveConfinedPath(vaultName: string, attachment: Attachment): string | null {
+  const assets = assetsDir(vaultName);
+  const filePath = normalize(join(assets, attachment.path));
+  if (!filePath.startsWith(normalize(assets))) return null;
+  return filePath;
+}
+
+class FsAttachmentBytesProvider implements AttachmentBytesProvider {
+  constructor(private readonly vaultName: string) {}
+
+  async stat(attachment: Attachment): Promise<{ size: number } | null> {
+    const filePath = resolveConfinedPath(this.vaultName, attachment);
+    if (!filePath || !existsSync(filePath)) return null;
+    return { size: statSync(filePath).size };
+  }
+
+  async readRange(attachment: Attachment, start: number, end: number): Promise<Uint8Array> {
+    const filePath = resolveConfinedPath(this.vaultName, attachment);
+    if (!filePath) return new Uint8Array(0);
+    const slice = Bun.file(filePath).slice(start, end);
+    return new Uint8Array(await slice.arrayBuffer());
+  }
+
+  async resolveTranscriptNote(attachment: Attachment): Promise<{ id: string; path: string } | null> {
+    const store = getVaultStore(this.vaultName);
+    const note = await store.getNoteByPath(transcriptPathFor(attachment.path));
+    if (!note) return null;
+    return { id: note.id, path: note.path ?? transcriptPathFor(attachment.path) };
+  }
+}
+
+/** Build a fresh `AttachmentBytesProvider` scoped to one vault. Cheap — safe to call per-request. */
+export function createFsAttachmentBytesProvider(vaultName: string): AttachmentBytesProvider {
+  return new FsAttachmentBytesProvider(vaultName);
+}

package/src/attachment-tickets.test.ts

@@ -29,7 +29,15 @@ const { handleScopedMcp } = await import("./mcp-http.ts");
 const { getServerInstruction } = await import("./mcp-tools.ts");
 const { writeVaultConfig } = await import("./config.ts");
 const { getVaultStore } = await import("./vault-store.ts");
-const { getSharedAttachmentTicketProvider } = await import("./attachment-tickets.ts");
+const {
+  getSharedAttachmentTicketProvider,
+  InProcessAttachmentTicketProvider,
+  sweepExpiredAttachmentTickets,
+  startAttachmentTicketSweep,
+  stopAttachmentTicketSweep,
+} = await import("./attachment-tickets.ts");
+const { generateTicketId } = await import("../core/src/attachment/tickets.ts");
+import type { AttachmentTicket } from "../core/src/attachment/tickets.ts";
 const { attachmentsInstructionBlock } = await import("../core/src/vault-projection.ts");
 
 /** `route()` takes the pathname as a separate arg (server.ts derives it from `req.url`) — this wrapper matches that call shape everywhere below. */
@@ -347,4 +355,121 @@ describe("attachment tickets — discoverability", () => {
     expect(md).toContain("## Attachments");
     expect(md).toContain("request-attachment-upload");
   });
+
+  test("attachmentsInstructionBlock teaches read-attachment when readEnabled, and omits it when not", () => {
+    const enabled = attachmentsInstructionBlock({ ticketsEnabled: true, readEnabled: true });
+    expect(enabled).toContain("read-attachment");
+
+    const disabled = attachmentsInstructionBlock({ ticketsEnabled: true, readEnabled: false });
+    expect(disabled).not.toContain("read-attachment");
+  });
+
+  test("bun's connect-time getServerInstruction teaches read-attachment too", async () => {
+    const vaultName = freshVault("tickets-instructions-read");
+    const md = await getServerInstruction(vaultName);
+    expect(md).toContain("read-attachment");
+  });
+});
+
+describe("attachment ticket sweep (vault#612)", () => {
+  // Isolated instance — no risk of touching the one process-wide provider
+  // every OTHER test in this file (and every other test FILE, via
+  // getSharedAttachmentTicketProvider) also shares.
+  function ticketExpiringAt(id: string, expiresAt: number): AttachmentTicket {
+    return {
+      id,
+      kind: "download",
+      vaultName: "sweep-unit-test",
+      createdAt: expiresAt - 60_000,
+      expiresAt,
+      attachmentId: "att-1",
+    };
+  }
+
+  test("sweepExpired drops only expired-unspent tickets and returns the count dropped", async () => {
+    const provider = new InProcessAttachmentTicketProvider();
+    const now = Date.now();
+    await provider.put(ticketExpiringAt("expired-1", now - 5000));
+    await provider.put(ticketExpiringAt("expired-2", now - 1));
+    await provider.put(ticketExpiringAt("fresh-1", now + 60_000));
+    expect(provider.size()).toBe(3);
+
+    const dropped = provider.sweepExpired(now);
+    expect(dropped).toBe(2);
+    expect(provider.size()).toBe(1);
+
+    // Dropped tickets are gone — take() returns null, same as "never existed".
+    expect(await provider.take("expired-1")).toBeNull();
+    expect(await provider.take("expired-2")).toBeNull();
+    // The unexpired ticket survived the sweep and is still spendable.
+    const fresh = await provider.take("fresh-1");
+    expect(fresh?.id).toBe("fresh-1");
+  });
+
+  test("a ticket expiring exactly `now` counts as expired (< comparison, not <=)", async () => {
+    const provider = new InProcessAttachmentTicketProvider();
+    const now = Date.now();
+    await provider.put(ticketExpiringAt("boundary", now));
+    expect(provider.sweepExpired(now)).toBe(0); // expiresAt === now is NOT yet expired
+    expect(provider.sweepExpired(now + 1)).toBe(1); // one ms later, it is
+  });
+
+  test("a no-op sweep (nothing expired) drops nothing", () => {
+    const provider = new InProcessAttachmentTicketProvider();
+    expect(provider.sweepExpired(Date.now())).toBe(0);
+    expect(provider.size()).toBe(0);
+  });
+
+  test("sweepExpiredAttachmentTickets delegates to the shared provider (unique ids — safe alongside concurrent tests)", async () => {
+    const provider = getSharedAttachmentTicketProvider();
+    const now = Date.now();
+    const expiredId = generateTicketId();
+    const freshId = generateTicketId();
+    await provider.put(ticketExpiringAt(expiredId, now - 1));
+    await provider.put(ticketExpiringAt(freshId, now + 60_000));
+
+    sweepExpiredAttachmentTickets(now);
+
+    expect(await provider.take(expiredId)).toBeNull();
+    const fresh = await provider.take(freshId);
+    expect(fresh?.id).toBe(freshId);
+  });
+
+  test("sweepExpiredAttachmentTickets always returns a number (the `?? 0` fallback path never throws)", () => {
+    // By this point in the suite the shared provider already exists (other
+    // tests above created it) — this doesn't re-prove the true
+    // never-created case in isolation, but pins the return type/no-throw
+    // contract the periodic sweep timer depends on every tick.
+    expect(typeof sweepExpiredAttachmentTickets()).toBe("number");
+  });
+
+  test("start/stop the periodic sweep: idempotent start, a short-interval real timer actually drops an expired ticket, clean stop", async () => {
+    // Poll via `size()`, NOT `take(id)` — `take()` deletes unconditionally
+    // on any lookup (expired or not; see its own doc comment), so polling
+    // with it would consume the ticket itself on the FIRST poll — before
+    // the timer ever fires — and the test would pass for the wrong reason.
+    const provider = getSharedAttachmentTicketProvider() as InstanceType<typeof InProcessAttachmentTicketProvider>;
+    const now = Date.now();
+    const id = generateTicketId();
+    await provider.put(ticketExpiringAt(id, now - 1)); // already expired
+    const baseline = provider.size();
+
+    startAttachmentTicketSweep(15); // 15ms — short enough to observe within the test timeout
+    startAttachmentTicketSweep(15); // idempotent — no-op, doesn't create a second timer
+
+    // Poll briefly rather than a single fixed sleep — bounded by the test
+    // runner's own timeout.
+    let sizeDropped = false;
+    for (let i = 0; i < 20 && !sizeDropped; i++) {
+      await new Promise((r) => setTimeout(r, 15));
+      if (provider.size() < baseline) sizeDropped = true;
+    }
+    stopAttachmentTicketSweep();
+    stopAttachmentTicketSweep(); // idempotent — no-op on an already-stopped sweep
+
+    expect(sizeDropped).toBe(true);
+    // Confirm it was genuinely OUR ticket the sweep dropped, not a
+    // coincidental size change from something else.
+    expect(await provider.take(id)).toBeNull();
+  });
 });

package/src/attachment-tickets.ts

@@ -37,7 +37,11 @@ function json(data: unknown, status = 200): Response {
  * `take` returns, collapsing "expired" into the same null as "spent" /
  * "unknown" so the HTTP layer can give a uniform 404 (no oracle).
  */
-class InProcessAttachmentTicketProvider implements AttachmentTicketProvider {
+// Exported (alongside the shared-singleton accessors below) so
+// vault#612's sweep logic can be unit-tested against an ISOLATED instance
+// — no risk of a test's reset touching the one process-wide provider every
+// OTHER test file's ticket mint/spend flow also shares.
+export class InProcessAttachmentTicketProvider implements AttachmentTicketProvider {
   private readonly tickets = new Map<string, AttachmentTicket>();
 
   async put(ticket: AttachmentTicket): Promise<void> {
@@ -50,6 +54,30 @@ class InProcessAttachmentTicketProvider implements AttachmentTicketProvider {
     this.tickets.delete(id);
     return ticket;
   }
+
+  /**
+   * Drop every unspent ticket whose TTL has elapsed (vault#612). `take()`
+   * already enforces expiry AT SPEND TIME — a caller can never successfully
+   * spend a stale ticket — so this is purely a memory-hygiene backstop: an
+   * agent that mints and then abandons the flow (network drop, a curl that
+   * never runs) would otherwise leave its ticket in this Map forever. Returns
+   * the count dropped, for test assertions / logging.
+   */
+  sweepExpired(now: number = Date.now()): number {
+    let dropped = 0;
+    for (const [id, ticket] of this.tickets) {
+      if (ticket.expiresAt < now) {
+        this.tickets.delete(id);
+        dropped++;
+      }
+    }
+    return dropped;
+  }
+
+  /** Test-only visibility into how many tickets are currently held. */
+  size(): number {
+    return this.tickets.size;
+  }
 }
 
 let sharedProvider: InProcessAttachmentTicketProvider | undefined;
@@ -65,6 +93,54 @@ export function resetSharedAttachmentTicketProviderForTests(): void {
   sharedProvider = undefined;
 }
 
+/** Test-only: how many tickets the shared provider currently holds (0 if never created). */
+export function sharedAttachmentTicketCountForTests(): number {
+  return sharedProvider?.size() ?? 0;
+}
+
+/**
+ * Drop every expired-unspent ticket from the shared provider (vault#612). A
+ * no-op (returns 0) before the shared provider has ever been created — the
+ * periodic sweep below calls this unconditionally, so this must tolerate
+ * running before the first mint.
+ */
+export function sweepExpiredAttachmentTickets(now: number = Date.now()): number {
+  return sharedProvider?.sweepExpired(now) ?? 0;
+}
+
+/**
+ * Sweep cadence (vault#612) — same cadence family as `EmbeddingWorker`'s
+ * default sweep interval (`src/embedding-worker.ts`'s `DEFAULT_SWEEP_MS`).
+ * Tickets are short-TTL (10-30 min, `computeTicketTtlMs`) and low-volume, so
+ * a 30s sweep is comfortably frequent without being wasteful.
+ */
+const TICKET_SWEEP_INTERVAL_MS = 30_000;
+
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Start the periodic expired-ticket sweep. No-op if already started. Mirrors
+ * `EmbeddingWorker.start()`'s shape (`.unref()` so the timer never keeps the
+ * process alive on its own — `server.ts`'s graceful-shutdown path still
+ * calls `stopAttachmentTicketSweep()` explicitly for a clean stop, same as
+ * `embeddingWorker.stop()`).
+ */
+export function startAttachmentTicketSweep(intervalMs: number = TICKET_SWEEP_INTERVAL_MS): void {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => {
+    sweepExpiredAttachmentTickets();
+  }, intervalMs);
+  sweepTimer.unref?.();
+}
+
+/** Stop the periodic expired-ticket sweep. */
+export function stopAttachmentTicketSweep(): void {
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+}
+
 /**
  * Take + validate a ticket against the URL's vault name and the spend
  * route's expected kind (a GET must not spend an upload ticket, etc.).

package/src/auth-hub-jwt.test.ts

@@ -28,7 +28,7 @@ import { tmpdir } from "os";
 import { generateKeyPair, exportJWK, SignJWT } from "jose";
 import { writeVaultConfig, readVaultConfig } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
-import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
+import { authenticateVaultRequest, authenticateGlobalRequest, deriveVaultFromToken } from "./auth.ts";
 import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
 
 interface Keypair {
@@ -705,3 +705,120 @@ describe("pvt_* DROP (vault#282 Stage 2 — unvalidatable)", () => {
     expect("error" in result).toBe(false);
   });
 });
+
+// ---------------------------------------------------------------------------
+// deriveVaultFromToken — the derivation precedence for the canonical root
+// `/mcp` endpoint (U1). This function READS a validated token's claims to name
+// the target vault; it never authorizes (the router re-dispatches through the
+// full per-vault machinery). These cases isolate the three naming sources —
+// narrowed scope / `aud=vault.<name>` / single-element `vault_scope` — and the
+// fail-closed rules (agree → one name; disagree or none → `not_derivable`).
+// The end-to-end routing.test.ts covers the wired behavior; this pins the
+// precedence logic directly.
+// ---------------------------------------------------------------------------
+describe("deriveVaultFromToken — root /mcp vault derivation (U1)", () => {
+  test("all three sources agree → that vault", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      vaultScope: ["journal"],
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("narrowed scope alone names the vault (non-vault aud, no vault_scope)", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:journal:read",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("aud=vault.<name> alone names the vault (broad scope names nothing)", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:read",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("single-element vault_scope alone names the vault", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:read",
+      vaultScope: ["journal"],
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("multi-element vault_scope is NOT a single name → not_derivable (nothing else names)", async () => {
+    // Phase-2 multi-vault shape: a multi-element vault_scope doesn't name ONE
+    // vault, so at the single-vault root it can't be the sole source.
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:read",
+      vaultScope: ["journal", "work"],
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("sources disagree (scope vs aud) → not_derivable, never a guess", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.work",
+      scope: "vault:journal:write",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("no source names a vault → not_derivable", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:read",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("no bearer → no_bearer", async () => {
+    const req = new Request("https://vault.test/mcp");
+    expect(await deriveVaultFromToken(req)).toEqual({ error: "no_bearer" });
+  });
+
+  test("non-JWT bearer (operator / legacy shape) names no vault → not_derivable", async () => {
+    // The operator VAULT_AUTH_TOKEN and legacy YAML keys are vault-agnostic —
+    // they can't route the token-derived root endpoint (they keep working at
+    // the per-vault URL).
+    expect(await deriveVaultFromToken(bearer("opaque-operator-secret"))).toEqual({
+      error: "not_derivable",
+    });
+  });
+
+  test("expired JWT → not_derivable (validated with the full trust kernel)", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      ttlSeconds: -10, // already expired
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("revoked JWT → not_derivable (revocation runs in derivation too)", async () => {
+    const jti = "u1-derive-revoked";
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      jti,
+    });
+    fixture.setRevoked([jti]);
+    resetRevocationCache();
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+});

package/src/auth.ts

@@ -30,6 +30,7 @@ import {
   hasScope,
   hasScopeForVault,
   legacyPermissionToScopes,
+  narrowedVaultNames,
   SCOPE_ADMIN,
   SCOPE_READ,
   SCOPE_WRITE,
@@ -712,3 +713,66 @@ export async function authenticateGlobalRequest(
   }
   return { error: Response.json({ error: "Unauthorized", message: "Invalid API key" }, { status: 401 }) };
 }
+
+/**
+ * Outcome of deriving a target vault from a request's bearer at the canonical
+ * root `/mcp` endpoint (U1). `vaultName` on success; a coarse failure `error`
+ * otherwise. Both failure reasons map to the SAME 401 + root-PRM challenge at
+ * the router — the distinction exists for logging/tests, never leaks to the
+ * client. `no_bearer` = no credential presented; `not_derivable` = a credential
+ * that names no single vault (non-JWT operator/legacy bearer, invalid /
+ * expired / revoked JWT, or a JWT whose scope / `aud` / `vault_scope` sources
+ * name zero or conflicting vaults).
+ */
+export type VaultDerivation =
+  | { vaultName: string }
+  | { error: "no_bearer" | "not_derivable" };
+
+/**
+ * Derive the target vault from a request's bearer token WITHOUT authorizing the
+ * request. The caller re-dispatches the derived name through the full per-vault
+ * auth machinery (`authenticateVaultRequest`), which re-validates the token
+ * WITH the audience pin — derive-then-redispatch, so a bad derivation FAILS the
+ * inner check rather than bypassing it (defense in depth). This function only
+ * reads the claims well enough to name the vault; it is never the authorization
+ * gate.
+ *
+ * Only hub-issued JWTs name a vault. The operator `VAULT_AUTH_TOKEN` and legacy
+ * YAML keys are vault-agnostic (they name no resource — see scopes.ts), so they
+ * return `not_derivable` here and keep working at the URL-addressed
+ * `/vault/<name>/*` surface. The JWT is validated with the SAME scope-guard
+ * trust kernel the per-vault path uses (signature, `iss` pin, `jti` +
+ * revocation, expiry) but WITHOUT `expectedAudience` — at the root we don't yet
+ * know which audience to expect; that pin is re-applied by the re-dispatch.
+ *
+ * From the validated claims, three independent sources can name a vault:
+ *   1. a narrowed `vault:<name>:<verb>` scope,
+ *   2. an `aud` of the form `vault.<name>`,
+ *   3. a single-element `vault_scope` claim.
+ * On a hub-minted token these AGREE. We collect every name any source provides
+ * and require EXACTLY ONE distinct name: zero (nothing named a vault) and
+ * two-or-more (the sources disagree) both fail closed with `not_derivable`. We
+ * never pick a winner from a precedence order — an ambiguous or unnamed token
+ * gets the discovery challenge, not a silent guess.
+ */
+export async function deriveVaultFromToken(req: Request): Promise<VaultDerivation> {
+  const key = extractApiKey(req);
+  if (!key) return { error: "no_bearer" };
+  if (!looksLikeJwt(key)) return { error: "not_derivable" };
+  let claims;
+  try {
+    // No `expectedAudience`: the per-vault trust kernel minus the aud pin
+    // (which the re-dispatch re-applies). A bad signature / iss / expiry /
+    // revoked jti throws here → not_derivable → the standard 401 challenge.
+    claims = await validateHubJwt(key, {});
+  } catch {
+    return { error: "not_derivable" };
+  }
+  const named = new Set<string>();
+  for (const name of narrowedVaultNames(claims.scopes)) named.add(name);
+  const audMatch = claims.aud?.match(/^vault\.(.+)$/);
+  if (audMatch) named.add(audMatch[1]!);
+  if (claims.vaultScope.length === 1) named.add(claims.vaultScope[0]!);
+  if (named.size !== 1) return { error: "not_derivable" };
+  return { vaultName: [...named][0]! };
+}