@openparachute/vault 0.5.2-rc.5 → 0.5.3-rc.1

package/core/src/core.test.ts

@@ -4,6 +4,7 @@ import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
 import { initSchema } from "./schema.js";
 import { decodeCursor } from "./cursor.js";
+import { traverseLinks } from "./links.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -1894,6 +1895,59 @@ describe("links", async () => {
     const links = await store.getLinks("a");
     expect(links.filter((l) => l.relationship === "mentions")).toHaveLength(1);
   });
+
+  // vault#439 — traverseLinks isTraversable predicate (wall, not sieve).
+  // Topology: a -> b(blocked) -> c. A predicate that blocks `b` must make
+  // `c` unreachable (the BFS can't walk THROUGH b), not merely filtered out.
+  it("traverseLinks: isTraversable predicate is a wall (can't reach past a blocked hop)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    await store.createLink("a", "b", "relates");
+    await store.createLink("b", "c", "relates");
+
+    const blocked = traverseLinks(db, "a", {
+      max_depth: 5,
+      isTraversable: (id) => id !== "b",
+    });
+    const ids = blocked.map((t) => t.noteId);
+    expect(ids).not.toContain("b"); // blocked hop is excluded from results
+    expect(ids).not.toContain("c"); // and unreachable beyond it
+  });
+
+  it("traverseLinks: no predicate walks the full graph (unchanged)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    await store.createLink("a", "b", "relates");
+    await store.createLink("b", "c", "relates");
+
+    const all = traverseLinks(db, "a", { max_depth: 5 });
+    const ids = all.map((t) => t.noteId);
+    expect(ids).toContain("b");
+    expect(ids).toContain("c");
+  });
+
+  it("traverseLinks: an allowed alternate path still reaches the far node", async () => {
+    // a -> b(blocked) -> d ; a -> c(allowed) -> d. d reachable via c.
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    await store.createNote("D", { id: "d" });
+    await store.createLink("a", "b", "relates");
+    await store.createLink("b", "d", "relates");
+    await store.createLink("a", "c", "relates");
+    await store.createLink("c", "d", "relates");
+
+    const res = traverseLinks(db, "a", {
+      max_depth: 5,
+      isTraversable: (id) => id !== "b",
+    });
+    const ids = res.map((t) => t.noteId);
+    expect(ids).not.toContain("b");
+    expect(ids).toContain("c");
+    expect(ids).toContain("d"); // reachable via the allowed c-path
+  });
 });
 
 // ---- Attachments ----

package/core/src/links.ts

@@ -255,14 +255,26 @@ export interface TraversalNode {
 /**
  * Traverse the link graph from a starting note up to `maxDepth` hops.
  * Returns all reachable notes with their depth and how they were reached.
+ *
+ * `isTraversable` (vault#439) is an OPTIONAL per-note predicate. When
+ * provided, a neighbor that fails the predicate is treated as a WALL: it is
+ * neither added to the results nor pushed onto the frontier, so the BFS
+ * cannot reach further notes THROUGH it. This makes a tag-scoped traversal
+ * symmetric with `find-path` (which guards every hop) — scope acts as a wall,
+ * not a sieve. Omitted (every unscoped / internal caller) → the full graph is
+ * walked exactly as before. Core stays scope-unaware: it receives a plain
+ * `(noteId) => boolean` closure and never imports the server's tag-scope
+ * module. The anchor `noteId` is never passed through the predicate — the
+ * caller is responsible for confirming the anchor is in scope before calling.
  */
 export function traverseLinks(
   db: Database,
   noteId: string,
-  opts?: { max_depth?: number; relationship?: string },
+  opts?: { max_depth?: number; relationship?: string; isTraversable?: (noteId: string) => boolean },
 ): TraversalNode[] {
   const maxDepth = opts?.max_depth ?? 2;
   const relFilter = opts?.relationship;
+  const isTraversable = opts?.isTraversable;
   const visited = new Set<string>([noteId]);
   const results: TraversalNode[] = [];
   let frontier = [noteId];
@@ -286,6 +298,10 @@ export function traverseLinks(
       for (const row of outbound) {
         if (!visited.has(row.target_id)) {
           visited.add(row.target_id);
+          // Wall (vault#439): an out-of-scope neighbor is marked visited (so
+          // it isn't re-evaluated) but is NOT added to the frontier or the
+          // results — the BFS can't traverse THROUGH it to reach notes beyond.
+          if (isTraversable && !isTraversable(row.target_id)) continue;
           nextFrontier.push(row.target_id);
           results.push({
             noteId: row.target_id,
@@ -311,6 +327,8 @@ export function traverseLinks(
       for (const row of inbound) {
         if (!visited.has(row.source_id)) {
           visited.add(row.source_id);
+          // Wall (vault#439): see the outbound branch above.
+          if (isTraversable && !isTraversable(row.source_id)) continue;
           nextFrontier.push(row.source_id);
           results.push({
             noteId: row.source_id,

package/core/src/mcp.ts

@@ -114,6 +114,15 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
  */
 export interface GenerateMcpToolsOpts {
   expandVisibility?: (note: Note) => boolean;
+  /**
+   * `nearTraversable` (vault#439) is an OPTIONAL per-note predicate threaded
+   * into the `near[]` graph BFS. When provided, the traversal refuses to walk
+   * THROUGH any note that fails the predicate — making a tag-scoped `near[]`
+   * query symmetric with `find-path` (scope is a wall, not a sieve). Core
+   * stays scope-unaware: it receives a plain `(noteId) => boolean` closure.
+   * Omitted (unscoped / internal callers) → the full graph is walked.
+   */
+  nearTraversable?: (noteId: string) => boolean;
 }
 
 /**
@@ -124,6 +133,7 @@ export interface GenerateMcpToolsOpts {
 export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
   const db: Database = (store as any).db;
   const expandVisibility = opts?.expandVisibility;
+  const nearTraversable = opts?.nearTraversable;
 
   return [
 
@@ -305,15 +315,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // --- Build near-scope (graph-filtered set of allowed IDs) ---
         //
-        // Tag-scope policy for `near[]` (output-filter, not hop-guard): core
-        // is scope-unaware, so this BFS walks the FULL graph from the anchor —
-        // including out-of-scope intermediate hops. For a tag-scoped session
-        // the server's `applyTagScopeWrappers` (mcp-tools.ts) tag-filters the
-        // RESULT list AFTER execute, so out-of-scope notes never survive into
-        // the response — no content/ids leak. This is ASYMMETRIC with
-        // `find-path`, which guards every hop (it returns the path itself, so
-        // an out-of-scope intermediary would be a leak there). The asymmetry is
-        // deliberate; tracked at vault#439.
+        // Tag-scope policy for `near[]` (vault#439 — hop-guard, symmetric with
+        // find-path): when the session is tag-scoped the server injects a
+        // `nearTraversable` predicate (mcp-tools.ts), and the BFS refuses to
+        // walk THROUGH out-of-scope notes — scope is a wall, not a sieve. So a
+        // token scoped to ["work"] can't reach an in-scope note at depth 2 via
+        // a #personal intermediary at depth 1. Core stays scope-unaware: it
+        // only invokes the injected closure. Unscoped sessions pass no
+        // predicate → the FULL graph is walked exactly as before. The
+        // `applyTagScopeWrappers` result-filter still runs afterward (defense
+        // in depth), but the wall makes it redundant for `near[]`.
         let nearScope: Set<string> | null = null;
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
@@ -323,6 +334,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           const traversed = linkOps.traverseLinks(db, anchor.id, {
             max_depth: depth,
             relationship: near.relationship,
+            isTraversable: nearTraversable,
           });
           nearScope = new Set([anchor.id, ...traversed.map((t) => t.noteId)]);
         }

package/package.json

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

package/src/config.test.ts

@@ -213,6 +213,72 @@ describe("config", () => {
     expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
   });
 
+  // ----- vault#234: anchored api_keys field regexes ----------------------
+  // The api_keys field regexes (label/scope/key_hash/created_at/last_used_at)
+  // used to be unanchored, so a COMMENTED `# scope: read` line matched, and a
+  // value-less `scope: ` (trailing space) captured the NEXT field's token
+  // (`key_hash`). The writer never emits either shape — only hand-editing
+  // reaches these branches — but a malformed scope could silently mis-scope a
+  // key. The regexes are now line-anchored + horizontal-whitespace-bounded.
+
+  test("vault#234: commented `# scope:` line is ignored, scope falls back to default", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234"), { recursive: true });
+    // The only `scope:` line is commented out; the parser must NOT pick it up.
+    fs.writeFileSync(
+      path,
+      `name: mv234\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_cmt\n    label: commented\n    # scope: read\n    key_hash: sha256:cmt\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234");
+    const key = loaded!.api_keys.find((k) => k.id === "k_cmt");
+    expect(key).toBeDefined();
+    // Commented scope ignored → default "write", NOT "read".
+    expect(key!.scope).toBe("write");
+    expect(key!.key_hash).toBe("sha256:cmt");
+  });
+
+  test("vault#234: value-less `scope: ` (trailing space) does NOT capture the next field", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b"), { recursive: true });
+    // `scope: ` has a trailing space and no value; the OLD regex skipped the
+    // newline and captured `sha256:trailing` (the key_hash) as the scope.
+    fs.writeFileSync(
+      path,
+      `name: mv234b\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_trail\n    label: trailing\n    scope: \n    key_hash: sha256:trailing\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234b");
+    const key = loaded!.api_keys.find((k) => k.id === "k_trail");
+    expect(key).toBeDefined();
+    // The hash must NOT have been borrowed as the scope.
+    expect(key!.scope).not.toBe("sha256:trailing");
+    expect(key!.scope).toBe("write"); // default
+    // And the real key_hash is still parsed correctly.
+    expect(key!.key_hash).toBe("sha256:trailing");
+  });
+
+  test("vault#234: a valid `scope: read` still parses (positive control, both parsers)", () => {
+    const fs = require("fs");
+    // Vault-level parser.
+    const vpath = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c"), { recursive: true });
+    fs.writeFileSync(
+      vpath,
+      `name: mv234c\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_v\n    label: reader\n    scope: read\n    key_hash: sha256:v\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    expect(readVaultConfig("mv234c")!.api_keys.find((k) => k.id === "k_v")?.scope).toBe("read");
+
+    // Global parser, same grammar.
+    const gpath = join(process.env.PARACHUTE_HOME!, "vault", "config.yaml");
+    fs.writeFileSync(
+      gpath,
+      `port: 1940\napi_keys:\n  - id: k_g\n    label: reader\n    # scope: write\n    scope: read\n    key_hash: sha256:g\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    // The commented `# scope: write` is skipped; the real `scope: read` wins.
+    expect(readGlobalConfig().api_keys?.find((k) => k.id === "k_g")?.scope).toBe("read");
+  });
+
   test("writeEnvFile writes .env at 0600 (SCRIBE_AUTH_TOKEN secrecy)", () => {
     // Regression for vault#354 reviewer finding: the .env holds
     // SCRIBE_AUTH_TOKEN (the vault↔scribe loopback bearer). On a

package/src/config.ts

@@ -518,14 +518,32 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   }
 
   // Parse api_keys
+  //
+  // Accepted grammar (vault#234): each `id:` block is the writer's output —
+  // one field per line, indented two spaces under the `- id:` list item:
+  //
+  //     - id: <id>
+  //       label: <label>            # free text to end of line
+  //       scope: <scope>            # single token (read|write|admin|…)
+  //       key_hash: <hash>          # single token
+  //       created_at: "<iso>"       # quoted or bare, no embedded newline
+  //       last_used_at: "<iso>"
+  //
+  // Each field regex is line-anchored (`^...`, `m` flag) so a COMMENTED line
+  // (`# scope: read`) never matches — the line must begin with optional
+  // leading whitespace then the bare key. The value matcher uses horizontal
+  // whitespace only (`[^\S\r\n]*`, never `\s*`) after the colon so a
+  // value-less field (`scope: ` with a trailing space) can't skip the newline
+  // and capture the NEXT field's value. A missing optional field falls back to
+  // its default rather than borrowing a neighbor's token.
   const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
   for (const block of keyBlocks) {
     const idMatch = block.match(/^(\S+)/);
-    const labelMatch = block.match(/label:\s*(.+)/);
-    const scopeMatch = block.match(/scope:\s*(\S+)/);
-    const hashMatch = block.match(/key_hash:\s*(\S+)/);
-    const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-    const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+    const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+    const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+    const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+    const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+    const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
 
     if (idMatch && hashMatch) {
       config.api_keys.push({
@@ -1250,16 +1268,19 @@ export function readGlobalConfig(): GlobalConfig {
       }
 
       // Parse global api_keys
+      // Same line-anchored grammar as the vault-level parser above (vault#234)
+      // — commented lines don't match; a value-less field can't capture the
+      // next field's token across the newline.
       const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
       if (keyBlocks.length > 0) {
         config.api_keys = [];
         for (const block of keyBlocks) {
           const idMatch = block.match(/^(\S+)/);
-          const labelMatch = block.match(/label:\s*(.+)/);
-          const scopeMatch = block.match(/scope:\s*(\S+)/);
-          const hashMatch = block.match(/key_hash:\s*(\S+)/);
-          const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-          const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+          const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+          const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+          const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+          const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+          const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
           if (idMatch && hashMatch) {
             config.api_keys.push({
               id: idMatch[1]!,

package/src/mcp-tools.ts

@@ -7,6 +7,7 @@
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
+import { getNoteTags } from "../core/src/notes.ts";
 import type { Note } from "../core/src/types.ts";
 import {
   buildVaultProjection,
@@ -135,9 +136,27 @@ export function generateScopedMcpTools(
     ? (note: Note) => noteWithinTagScope(note, allowedHolder.value, rawTags)
     : undefined;
 
+  // Tag-scope hop-guard for `near[]` (vault#439): a per-note predicate the
+  // core BFS consults so it refuses to traverse THROUGH out-of-scope notes —
+  // symmetric with find-path. Reads from the SAME shared `allowedHolder` the
+  // result-filter populates; the query-notes wrapper `await getAllowed()`s
+  // (which fills the holder) before core's execute runs the BFS, so the
+  // allowlist is ready by the time this fires. Looks up each candidate note's
+  // tags by id (sync, core-native). Unscoped sessions install no predicate.
+  const nearTraversable = scoped
+    ? (noteId: string) =>
+        noteWithinTagScope(
+          { id: noteId, tags: getNoteTags(store.db, noteId) } as Note,
+          allowedHolder.value,
+          rawTags,
+        )
+    : undefined;
+
   const tools = generateMcpTools(
     store,
-    expandVisibility ? { expandVisibility } : undefined,
+    expandVisibility || nearTraversable
+      ? { ...(expandVisibility ? { expandVisibility } : {}), ...(nearTraversable ? { nearTraversable } : {}) }
+      : undefined,
   );
 
   overrideVaultInfo(tools, vaultName, auth);

package/src/routes.ts

@@ -13,7 +13,7 @@
 
 import type { Store, Note } from "../core/src/types.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { getNote, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import { getNote, getNoteTags, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import { attachValidationStatus } from "../core/src/mcp.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
@@ -817,16 +817,24 @@ async function handleNotesInner(
         }
         const depth = Math.min(parseInt10(parseQuery(url, "near[depth]")) ?? 2, 5);
         const relationship = parseQuery(url, "near[relationship]") ?? undefined;
-        // Tag-scope policy for `near[]` (output-filter, not hop-guard): the
-        // BFS walks the FULL graph from the anchor, including out-of-scope
-        // intermediate hops, then the RESULT set is tag-scope-filtered below
-        // (`filterNotesByTagScope`). No out-of-scope content or ids leak —
-        // out-of-scope notes never survive into the response. This is
-        // ASYMMETRIC with `find-path`, which guards every hop (it returns the
-        // path itself, so an out-of-scope intermediary would be a leak there).
-        // The asymmetry is deliberate; tracked at vault#439 should we ever want
-        // `near[]` to also constrain traversal hops.
-        const traversed = linkOps.traverseLinks(db, anchor.id, { max_depth: depth, relationship });
+        // Tag-scope policy for `near[]` (vault#439 — hop-guard, symmetric with
+        // find-path): for a tag-scoped token the BFS refuses to traverse
+        // THROUGH out-of-scope notes — scope is a wall, not a sieve. So a token
+        // scoped to ["work"] can't reach an in-scope note at depth 2 via a
+        // #personal intermediary at depth 1; that note is simply unreachable.
+        // The `filterNotesByTagScope` pass below still runs (defense in depth),
+        // but the wall makes it redundant for the `near[]` result set.
+        // Unscoped tokens (`tagScope.raw === null`) install no predicate → the
+        // FULL graph is walked exactly as before, behavior unchanged.
+        const isTraversable = tagScope.raw
+          ? (id: string) =>
+              noteWithinTagScope(
+                { id, tags: getNoteTags(db, id) } as Note,
+                tagScope.allowed,
+                tagScope.raw,
+              )
+          : undefined;
+        const traversed = linkOps.traverseLinks(db, anchor.id, { max_depth: depth, relationship, isTraversable });
         const nearScope = new Set([anchor.id, ...traversed.map((t) => t.noteId)]);
         results = results.filter((n) => nearScope.has(n.id));
       }

package/src/routing.test.ts

@@ -30,7 +30,7 @@ const testDir = join(
 process.env.PARACHUTE_HOME = testDir;
 
 // Dynamic import after env override so modules pick up the tmp dir.
-const { route } = await import("./routing.ts");
+const { route, filterVaultListForBinding } = await import("./routing.ts");
 const {
   readGlobalConfig,
   writeGlobalConfig,
@@ -318,6 +318,56 @@ describe("GET /vaults/list (public discovery)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// GET /vaults — authenticated metadata listing, filtered by vault binding
+// (vault#259). Operator / admin-channel callers (vault_name === null) see the
+// full list; a vault-bound caller sees only its own vault.
+// ---------------------------------------------------------------------------
+
+describe("GET /vaults (binding filter — vault#259)", () => {
+  // Pure policy helper — drives the filtering decision independent of the
+  // auth path (no current credential yields a non-null vault_name HERE, since
+  // authenticateGlobalRequest 401s hub JWTs; the helper pins the correct
+  // shape for any future vault-bound credential on this surface).
+  test("filterVaultListForBinding: null binding (operator) keeps the full list", () => {
+    const names = ["work", "boulder", "default"];
+    expect(filterVaultListForBinding(names, null)).toEqual(names);
+  });
+
+  test("filterVaultListForBinding: a vault-bound caller sees only its own vault", () => {
+    const names = ["work", "boulder", "default"];
+    expect(filterVaultListForBinding(names, "work")).toEqual(["work"]);
+    // No cross-vault info-leak: boulder/default are not disclosed.
+    expect(filterVaultListForBinding(names, "work")).not.toContain("boulder");
+    expect(filterVaultListForBinding(names, "work")).not.toContain("default");
+  });
+
+  test("filterVaultListForBinding: binding to a vault absent from the list yields empty", () => {
+    expect(filterVaultListForBinding(["work", "default"], "ghost")).toEqual([]);
+  });
+
+  test("operator token (VAULT_AUTH_TOKEN) gets the UNFILTERED full listing", async () => {
+    createVault("work");
+    createVault("boulder");
+    createVault("default");
+    const prev = process.env.VAULT_AUTH_TOKEN;
+    process.env.VAULT_AUTH_TOKEN = "op-secret-token-259";
+    try {
+      const req = new Request("http://localhost:1940/vaults", {
+        headers: { authorization: "Bearer op-secret-token-259" },
+      });
+      const res = await route(req, "/vaults");
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { vaults: { name: string }[] };
+      const names = body.vaults.map((v) => v.name);
+      expect(new Set(names)).toEqual(new Set(["work", "boulder", "default"]));
+    } finally {
+      if (prev === undefined) delete process.env.VAULT_AUTH_TOKEN;
+      else process.env.VAULT_AUTH_TOKEN = prev;
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // /vault/<name>/admin/* — admin SPA static-file mount. Detailed tests live
 // in admin-spa.test.ts (with a tmp dist dir); these pin the dispatch — i.e.
@@ -1640,6 +1690,147 @@ describe("scope enforcement on /api/*", () => {
     expect(res.status).toBe(201);
   });
 
+  // ----- vault#439: near[] BFS is a WALL, not a sieve --------------------
+  // For a tag-scoped token the graph traversal must refuse to walk THROUGH
+  // an out-of-scope note. So an in-scope note reachable ONLY via an
+  // out-of-scope intermediary is unreachable — symmetric with find-path.
+  // Topology: A(#work) --link--> P(#personal) --link--> B(#work).
+  // A token scoped to ["work"] anchored at A, depth 2:
+  //   - sieve (old): B survives (reached via P, then output-filtered to keep B)
+  //   - wall (new):  P is the wall; B is never reached.
+
+  test("vault#439: tag-scoped near[] cannot reach an in-scope note through an out-of-scope hop", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const a = await store.createNote("anchor-work", { tags: ["work"] });
+    const p = await store.createNote("bridge-personal", { tags: ["personal"] });
+    const b = await store.createNote("far-work", { tags: ["work"] });
+    await store.createLink(a.id, p.id, "relates");
+    await store.createLink(p.id, b.id, "relates");
+    const token = await mintTagScopedToken("journal", ["vault:read"], ["work"]);
+
+    // `route`'s second arg is the pathname only; the query rides on req.url.
+    const pathname = "/vault/journal/api/notes";
+    const full = `${pathname}?near[note_id]=${a.id}&near[depth]=2`;
+    const res = await route(authed(token, "GET", full), pathname);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(body) ? body : (body.notes ?? []);
+    const ids = list.map((n) => n.id);
+    // B is in-scope (#work) but only reachable via the out-of-scope #personal
+    // bridge — the wall makes it unreachable.
+    expect(ids).not.toContain(b.id);
+    // P itself never leaks (it's out of scope).
+    expect(ids).not.toContain(p.id);
+  });
+
+  test("vault#439: tag-scoped near[] still reaches in-scope notes via in-scope hops", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const a = await store.createNote("anchor-work", { tags: ["work"] });
+    const mid = await store.createNote("mid-work", { tags: ["work"] });
+    const far = await store.createNote("far-work", { tags: ["work"] });
+    await store.createLink(a.id, mid.id, "relates");
+    await store.createLink(mid.id, far.id, "relates");
+    const token = await mintTagScopedToken("journal", ["vault:read"], ["work"]);
+
+    const pathname = "/vault/journal/api/notes";
+    const full = `${pathname}?near[note_id]=${a.id}&near[depth]=2`;
+    const res = await route(authed(token, "GET", full), pathname);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(body) ? body : (body.notes ?? []);
+    const ids = list.map((n) => n.id);
+    // All-in-scope path: both mid (depth 1) and far (depth 2) are reachable.
+    expect(ids).toContain(mid.id);
+    expect(ids).toContain(far.id);
+  });
+
+  test("vault#439: UNSCOPED token near[] still walks the full graph (behavior unchanged)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const a = await store.createNote("anchor-work", { tags: ["work"] });
+    const p = await store.createNote("bridge-personal", { tags: ["personal"] });
+    const b = await store.createNote("far-work", { tags: ["work"] });
+    await store.createLink(a.id, p.id, "relates");
+    await store.createLink(p.id, b.id, "relates");
+    // No scopedTags → unscoped admin token; no wall installed.
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:admin"] });
+
+    const pathname = "/vault/journal/api/notes";
+    const full = `${pathname}?near[note_id]=${a.id}&near[depth]=2`;
+    const res = await route(authed(token, "GET", full), pathname);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(body) ? body : (body.notes ?? []);
+    const ids = list.map((n) => n.id);
+    // Unscoped: the full neighborhood is visible, including the #personal
+    // bridge and the note beyond it.
+    expect(ids).toContain(p.id);
+    expect(ids).toContain(b.id);
+  });
+
+  // ----- vault#404: REST-path hub-JWT tag-scoping enforcement (C0) --------
+  // The MCP path's tag-scope enforcement is covered end-to-end; pin that a
+  // tag-scoped HUB JWT (allowlist carried in the `permissions.scoped_tags`
+  // claim, NOT a vestigial DB row) hitting the REST surface enforces the
+  // same allowlist on both read and write. `mintTagScopedToken` mints a real
+  // hub JWT, so these tests exercise the hub-JWT-sourced `scoped_tags` path.
+
+  test("vault#404: hub-JWT tag-scoped READ via REST enforces the allowlist (list + single)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const inScope = await store.createNote("h", { tags: ["health"] });
+    const outOfScope = await store.createNote("w", { tags: ["work"] });
+    const token = await mintTagScopedToken("journal", ["vault:read"], ["health"]);
+
+    // List: only in-scope notes.
+    const listPath = "/vault/journal/api/notes";
+    const listRes = await route(authed(token, "GET", listPath), listPath);
+    expect(listRes.status).toBe(200);
+    const listBody = (await listRes.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(listBody) ? listBody : (listBody.notes ?? []);
+    const ids = list.map((n) => n.id);
+    expect(ids).toContain(inScope.id);
+    expect(ids).not.toContain(outOfScope.id);
+
+    // Single in-scope → 200; single out-of-scope → 404 (no existence leak).
+    const okPath = `/vault/journal/api/notes/${inScope.id}`;
+    expect((await route(authed(token, "GET", okPath), okPath)).status).toBe(200);
+    const denyPath = `/vault/journal/api/notes/${outOfScope.id}`;
+    expect((await route(authed(token, "GET", denyPath), denyPath)).status).toBe(404);
+  });
+
+  test("vault#404: hub-JWT tag-scoped WRITE via REST enforces the allowlist", async () => {
+    createVault("journal");
+    const token = await mintTagScopedToken("journal", ["vault:read", "vault:write"], ["health"]);
+
+    // In-scope write → 201.
+    const path = "/vault/journal/api/notes";
+    const okRes = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ content: "ok", tags: ["health"] }),
+      }),
+      path,
+    );
+    expect(okRes.status).toBe(201);
+
+    // Out-of-scope write → 403 tag_scope_violation.
+    const denyRes = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ content: "denied", tags: ["work"] }),
+      }),
+      path,
+    );
+    expect(denyRes.status).toBe(403);
+    const denyBody = (await denyRes.json()) as { error_type?: string };
+    expect(denyBody.error_type).toBe("tag_scope_violation");
+  });
+
   // ----- Q5: tag-delete dependency check ---------------------------------
   // Deleting a tag referenced by any token's scoped_tags would silently
   // orphan the token's allowlist; fail closed with 409 + referenced_by.

package/src/routing.ts

@@ -180,6 +180,23 @@ function handleParachuteIcon(): Response {
   });
 }
 
+/**
+ * Filter a server-wide vault-name list for a caller's per-vault binding
+ * (vault#259). `vaultName === null` is the operator / admin-channel caller
+ * (server-wide VAULT_AUTH_TOKEN or legacy cross-vault config.yaml key) — they
+ * keep the FULL list. A non-null binding reduces the list to just that vault
+ * (empty if the bound vault isn't in the listing). Pure + exported so the
+ * policy is unit-testable independent of the auth path. See the `/vaults`
+ * handler for the full rationale.
+ */
+export function filterVaultListForBinding(
+  names: string[],
+  vaultName: string | null,
+): string[] {
+  if (vaultName === null) return names;
+  return names.filter((name) => name === vaultName);
+}
+
 export async function route(
   req: Request,
   path: string,
@@ -286,10 +303,24 @@ export async function route(
   }
 
   // Authenticated vault metadata list.
+  //
+  // Vault-binding filter (vault#259, info-leak follow-up): `/vaults` is a
+  // cross-vault DISCOVERY endpoint, not a single-vault operational one (unlike
+  // /mcp, which legitimately routes a vault-bound token back into its own
+  // vault). A caller bound to one vault shouldn't learn that OTHER vaults exist
+  // on this server. So when the authenticated caller carries a per-vault
+  // binding (`auth.vault_name !== null`), the listing is reduced to just that
+  // vault. Operator / admin-channel callers — the server-wide VAULT_AUTH_TOKEN
+  // and legacy cross-vault config.yaml keys — have `vault_name === null` and
+  // keep the full listing (they're explicitly the cross-vault management
+  // channel). `authenticateGlobalRequest` already 401s hub JWTs here, so the
+  // only callers that reach this point today are operator-channel
+  // (`vault_name === null`); this filter is the security-correct shape for any
+  // future vault-bound credential that becomes accepted on this surface.
   if (path === "/vaults" && req.method === "GET") {
     const auth = await authenticateGlobalRequest(req);
     if ("error" in auth) return auth.error;
-    const names = listVaults();
+    const names = filterVaultListForBinding(listVaults(), auth.vault_name);
     const vaults = names.map((name) => {
       const config = readVaultConfig(name);
       return {