@openparachute/vault 0.7.9-rc.2 → 0.7.9-rc.4

package/src/tag-scope-query-tag.test.ts

@@ -0,0 +1,374 @@
+/**
+ * vault#675 — a scoped caller must not be able to PROBE for an out-of-scope
+ * tag by naming it in a query and reading hit/miss.
+ *
+ * #568/#674 stopped scoped reads from DISCLOSING an out-of-scope co-tag's
+ * name. The oracle left behind: the caller names it itself. A note tagged
+ * `["mine","project-manhattan"]` is admitted to a `mine`-scoped token via
+ * `mine`, so `?tag=project-manhattan` came back with a row — confirming the
+ * guessed name — while `?tag=some-tag-that-does-not-exist` came back empty.
+ * No name leaked; membership did. Same on all three doors (REST `?tag=`,
+ * MCP `query-notes { tag }`, live subscriptions).
+ *
+ * The fix (`scopeQueryTags` / `scopeQueryTagParam`, src/tag-scope.ts)
+ * rewrites an out-of-scope query tag to a name no note can carry, so an
+ * out-of-scope tag behaves EXACTLY as a tag that does not exist. Every test
+ * below is written as that comparison — the assertion is not "empty", it is
+ * "byte-identical to the nonexistent-tag control" — because equality with
+ * the control is the actual security property. `NONEXISTENT` is itself out
+ * of scope (every unknown name is), so the two requests differ in exactly
+ * one way: whether the named tag exists in the vault.
+ *
+ * The live-subscription door is covered in `ws-subscribe.test.ts` (it needs
+ * a real socket).
+ *
+ * Fixture + naming follow `tag-scope-note-tags.test.ts`: `mine` is in scope,
+ * `project-manhattan` is the out-of-scope tag being probed for. Every test
+ * carries an UNSCOPED control — the fix must be invisible to unscoped
+ * tokens, which still query the co-tag normally.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { handleNotes, type TagScopeCtx } from "./routes.ts";
+import { expandTokenTagScope, OUT_OF_SCOPE_QUERY_TAG } from "./tag-scope.ts";
+import { stripTagHash } from "../core/src/tag-hierarchy.ts";
+import type { AuthResult } from "./auth.ts";
+import type { Store } from "../core/src/types.ts";
+
+const OUT_OF_SCOPE = "project-manhattan";
+/** The control: a name that is equally out of scope, but does NOT exist. */
+const NONEXISTENT = "tag-that-does-not-exist";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-675-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): Store {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  return getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null): AuthResult {
+  return {
+    permission: "full",
+    scopes: [`vault:${vaultName}:read`, `vault:${vaultName}:write`],
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  } as AuthResult;
+}
+
+async function restScope(store: Store, scopedTags: string[] | null): Promise<TagScopeCtx> {
+  return { allowed: await expandTokenTagScope(store, scopedTags), raw: scopedTags };
+}
+
+async function rest(store: Store, scope: TagScopeCtx, query: string): Promise<any> {
+  const req = new Request(`http://localhost/vault/v/api/notes${query}`, { method: "GET" });
+  const res = await handleNotes(req, store, "", "v", scope);
+  return { status: res.status, body: await res.json() };
+}
+
+/**
+ * The corpus every test probes:
+ *   - `CoTagged`  — `["mine", OUT_OF_SCOPE]`: visible via `mine`. THE oracle
+ *     — it is the row a probe for `OUT_OF_SCOPE` used to return.
+ *   - `MineOnly`  — `["mine"]`: the in-scope baseline.
+ *   - `HiddenOnly` — `[OUT_OF_SCOPE]`: already invisible pre-fix.
+ */
+async function seedCorpus(store: Store): Promise<void> {
+  await store.createNote("co-tagged body", { path: "CoTagged", tags: ["mine", OUT_OF_SCOPE] });
+  await store.createNote("mine only", { path: "MineOnly", tags: ["mine"] });
+  await store.createNote("hidden", { path: "HiddenOnly", tags: [OUT_OF_SCOPE] });
+}
+
+const paths = (body: any): string[] =>
+  (Array.isArray(body) ? body : (body?.notes ?? [])).map((n: any) => n.path).sort();
+
+describe("vault#675 — the substituted tag itself", () => {
+  /**
+   * The whole fix rests on two properties of `OUT_OF_SCOPE_QUERY_TAG`, and
+   * both fail SILENTLY and CATASTROPHICALLY if someone edits the constant to
+   * something more readable. Pinned here rather than trusted:
+   *
+   *  1. It survives tag normalization. `SqliteStore.normalizeQueryTags` maps
+   *     `stripTagHash` over query tags and DROPS the empties; if the
+   *     substitute normalized away, `tags` would collapse to `[]`, the tag
+   *     filter would be skipped entirely, and an out-of-scope probe would
+   *     return the caller's WHOLE visible set instead of nothing.
+   *  2. Even a note DELIBERATELY tagged with it can't widen what a scoped
+   *     caller sees. The substitution changes which notes the query matches;
+   *     it does not touch the result-side scope filter, so a planted decoy is
+   *     dropped exactly like any other out-of-scope note.
+   */
+  test("survives stripTagHash — a tag filter naming it is never normalized away", () => {
+    expect(stripTagHash(OUT_OF_SCOPE_QUERY_TAG)).toBe(OUT_OF_SCOPE_QUERY_TAG);
+    expect(OUT_OF_SCOPE_QUERY_TAG).not.toBe("");
+  });
+
+  test("a note deliberately tagged with it is still invisible to a scoped probe", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    // Storage does not forbid the name (nothing in a real tagging workflow —
+    // YAML front-matter, a JSON `tags` array — can produce a NUL, but the
+    // store doesn't police it). This is the residual case, and it is inert:
+    // the note carries no in-scope tag, so the unchanged result-side filter
+    // drops it.
+    await store.createNote("decoy", { path: "Decoy", tags: [OUT_OF_SCOPE_QUERY_TAG] });
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?tag=${OUT_OF_SCOPE}`);
+    const control = await rest(store, scope, `?tag=${NONEXISTENT}`);
+    expect(probe.body).toEqual(control.body);
+    expect(probe.body).toEqual([]);
+  });
+});
+
+describe("vault#675 — REST door: an out-of-scope query tag matches nothing", () => {
+  test("?tag=<out-of-scope> — byte-identical to the same query naming a NONEXISTENT tag", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?tag=${OUT_OF_SCOPE}`);
+    const control = await rest(store, scope, `?tag=${NONEXISTENT}`);
+
+    expect(probe.status).toBe(control.status);
+    expect(probe.body).toEqual(control.body);
+    expect(probe.body).toEqual([]);
+    expect(JSON.stringify(probe.body)).not.toContain(OUT_OF_SCOPE);
+  });
+
+  test("?tag=<out-of-scope> UNSCOPED control — the co-tagged note still comes back in full", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, null);
+
+    const probe = await rest(store, scope, `?tag=${OUT_OF_SCOPE}`);
+    expect(paths(probe.body)).toEqual(["CoTagged", "HiddenOnly"]);
+  });
+
+  test("tag_match=all — an out-of-scope tag ANDed with an in-scope one still matches nothing", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?tag=mine&tag=${OUT_OF_SCOPE}&tag_match=all`);
+    const control = await rest(store, scope, `?tag=mine&tag=${NONEXISTENT}&tag_match=all`);
+
+    expect(probe.body).toEqual(control.body);
+    expect(probe.body).toEqual([]);
+  });
+
+  test("tag_match=any — the out-of-scope member contributes nothing, the in-scope member is unaffected", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    // A SECOND in-scope root is what makes `any` an oracle: `OpsCoTagged`
+    // is visible via `ops`, so pre-fix the out-of-scope union member pulled
+    // it into an answer to a question about `mine`.
+    await store.createNote("ops co-tagged", { path: "OpsCoTagged", tags: ["ops", OUT_OF_SCOPE] });
+    const scope = await restScope(store, ["mine", "ops"]);
+
+    const probe = await rest(store, scope, `?tag=mine&tag=${OUT_OF_SCOPE}&tag_match=any`);
+    const control = await rest(store, scope, `?tag=mine&tag=${NONEXISTENT}&tag_match=any`);
+
+    expect(probe.body).toEqual(control.body);
+    expect(paths(probe.body)).toEqual(["CoTagged", "MineOnly"]);
+  });
+
+  test("exclude_tag=<out-of-scope> — excludes nothing, exactly as excluding a nonexistent tag does", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?exclude_tag=${OUT_OF_SCOPE}`);
+    const control = await rest(store, scope, `?exclude_tag=${NONEXISTENT}`);
+
+    // Pre-fix this SHRANK the visible set (CoTagged dropped out) — a
+    // difference-of-counts oracle on the same tag name.
+    expect(probe.body).toEqual(control.body);
+    expect(paths(probe.body)).toEqual(["CoTagged", "MineOnly"]);
+  });
+
+  test("?search= composes the same way — the FTS branch lowers the same query tags", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?search=body&tag=${OUT_OF_SCOPE}`);
+    const control = await rest(store, scope, `?search=body&tag=${NONEXISTENT}`);
+
+    expect(probe.body).toEqual(control.body);
+    expect(paths(probe.body)).toEqual([]);
+  });
+
+  test("?format=graph — the graph projection is the same query, so nodes[] is empty too", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?format=graph&tag=${OUT_OF_SCOPE}`);
+    const control = await rest(store, scope, `?format=graph&tag=${NONEXISTENT}`);
+
+    expect(probe.body).toEqual(control.body);
+    expect(probe.body.nodes).toEqual([]);
+  });
+
+  test("?aggregate[op]=count — the rollup can't be used as a counting oracle either", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?aggregate[op]=count&tag=${OUT_OF_SCOPE}`);
+    const control = await rest(store, scope, `?aggregate[op]=count&tag=${NONEXISTENT}`);
+
+    expect(probe.body).toEqual(control.body);
+    expect(probe.body).toEqual([{ group: null, value: 0 }]);
+  });
+
+  test("cursor envelope — same shape as the nonexistent-tag control (opaque cursor aside)", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const scope = await restScope(store, ["mine"]);
+
+    const probe = await rest(store, scope, `?tag=${OUT_OF_SCOPE}&cursor=`);
+    const control = await rest(store, scope, `?tag=${NONEXISTENT}&cursor=`);
+
+    expect(Object.keys(probe.body).sort()).toEqual(Object.keys(control.body).sort());
+    expect(probe.body.notes).toEqual([]);
+    // The cursor is opaque and derived from the caller's OWN query string —
+    // it carries no vault state. What matters is that it is the watermark of
+    // a genuinely empty page, which it is because the query really did match
+    // nothing rather than being emptied afterwards.
+    expect(typeof probe.body.next_cursor).toBe("string");
+  });
+
+  test("an IN-SCOPE query tag is untouched — including the `#`-prefixed form the engine strips", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    await store.createNote("sub", { path: "Sub", tags: ["mine/sub"] });
+    const scope = await restScope(store, ["mine"]);
+
+    expect(paths((await rest(store, scope, "?tag=mine")).body)).toEqual(["CoTagged", "MineOnly"]);
+    expect(paths((await rest(store, scope, "?tag=%23mine")).body)).toEqual(["CoTagged", "MineOnly"]);
+    expect(paths((await rest(store, scope, "?tag=mine/sub")).body)).toEqual(["Sub"]);
+  });
+});
+
+describe("vault#675 — MCP door: identical semantics (one contract, two doors)", () => {
+  function toolset(vaultName: string, scopedTags: string[] | null) {
+    const tools = generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags) as any);
+    return (name: string) => tools.find((t) => t.name === name)!;
+  }
+
+  test("query-notes { tag } — byte-identical to naming a NONEXISTENT tag", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const queryNotes = toolset("v", ["mine"])("query-notes");
+
+    const probe: any = await queryNotes.execute({ tag: OUT_OF_SCOPE });
+    const control: any = await queryNotes.execute({ tag: NONEXISTENT });
+
+    expect(probe).toEqual(control);
+    expect(paths(probe)).toEqual([]);
+    expect(JSON.stringify(probe)).not.toContain(OUT_OF_SCOPE);
+  });
+
+  test("query-notes { tag } UNSCOPED control — the co-tagged note still comes back", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+
+    const probe: any = await toolset("v", null)("query-notes").execute({ tag: OUT_OF_SCOPE });
+    expect(paths(probe)).toEqual(["CoTagged", "HiddenOnly"]);
+  });
+
+  test("query-notes { tag: [in, out], tag_match: all } — matches nothing", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const queryNotes = toolset("v", ["mine"])("query-notes");
+
+    const probe: any = await queryNotes.execute({ tag: ["mine", OUT_OF_SCOPE], tag_match: "all" });
+    const control: any = await queryNotes.execute({ tag: ["mine", NONEXISTENT], tag_match: "all" });
+
+    expect(probe).toEqual(control);
+    expect(paths(probe)).toEqual([]);
+  });
+
+  test("query-notes { tag: [in, out], tag_match: any } — the in-scope member is unaffected", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    await store.createNote("ops co-tagged", { path: "OpsCoTagged", tags: ["ops", OUT_OF_SCOPE] });
+    const queryNotes = toolset("v", ["mine", "ops"])("query-notes");
+
+    const probe: any = await queryNotes.execute({ tag: ["mine", OUT_OF_SCOPE], tag_match: "any" });
+    const control: any = await queryNotes.execute({ tag: ["mine", NONEXISTENT], tag_match: "any" });
+
+    expect(probe).toEqual(control);
+    expect(paths(probe)).toEqual(["CoTagged", "MineOnly"]);
+  });
+
+  test("query-notes { exclude_tags } — excludes nothing", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const queryNotes = toolset("v", ["mine"])("query-notes");
+
+    const probe: any = await queryNotes.execute({ exclude_tags: OUT_OF_SCOPE });
+    const control: any = await queryNotes.execute({ exclude_tags: NONEXISTENT });
+
+    expect(probe).toEqual(control);
+    expect(paths(probe)).toEqual(["CoTagged", "MineOnly"]);
+  });
+
+  test("query-notes aggregate rollup — no counting oracle on this door either", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const queryNotes = toolset("v", ["mine"])("query-notes");
+
+    const probe: any = await queryNotes.execute({ tag: OUT_OF_SCOPE, aggregate: { op: "count" } });
+    const control: any = await queryNotes.execute({ tag: NONEXISTENT, aggregate: { op: "count" } });
+
+    expect(probe).toEqual(control);
+    expect(probe).toEqual([{ group: null, value: 0 }]);
+  });
+
+  test("an IN-SCOPE query tag is untouched on this door too", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+    const queryNotes = toolset("v", ["mine"])("query-notes");
+
+    expect(paths(await queryNotes.execute({ tag: "mine" }))).toEqual(["CoTagged", "MineOnly"]);
+    expect(paths(await queryNotes.execute({ tag: "#mine" }))).toEqual(["CoTagged", "MineOnly"]);
+  });
+
+  test("BOTH-DOOR PARITY — REST and MCP answer an out-of-scope query tag the same way", async () => {
+    const store = seedVault("v");
+    await seedCorpus(store);
+
+    const restBody = (await rest(store, await restScope(store, ["mine"]), `?tag=${OUT_OF_SCOPE}`)).body;
+    const mcpBody: any = await toolset("v", ["mine"])("query-notes").execute({ tag: OUT_OF_SCOPE });
+
+    expect(paths(mcpBody)).toEqual(paths(restBody));
+    expect(paths(restBody)).toEqual([]);
+  });
+});

package/src/tag-scope.ts

@@ -23,6 +23,7 @@ import type { Store, Note, HydratedLink, NoteSummary } from "../core/src/types.t
 import type { TagFieldViolation } from "../core/src/tag-schemas.ts";
 import { ParentCycleError } from "../core/src/tag-schemas.ts";
 import { IndexedFieldError } from "../core/src/indexed-fields.ts";
+import { stripTagHash } from "../core/src/tag-hierarchy.ts";
 
 /** Generic replacement for a redacted out-of-scope tag name — never the real name. */
 const OUT_OF_SCOPE_LABEL = "(outside your token's tag scope)";
@@ -246,6 +247,121 @@ export function scrubNotesTagsByScope<T extends { tags?: string[] }>(
   return notes.map((n) => scrubNoteTagsByScope(n, allowed, rawRoots));
 }
 
+/**
+ * The stand-in an out-of-scope QUERY tag is rewritten to (vault#675) — a
+ * name no real tagging workflow can produce, so a filter naming it matches
+ * nothing. See `scopeQueryTags` for why that is the whole fix.
+ *
+ * Two properties are load-bearing, both pinned by
+ * `tag-scope-query-tag.test.ts`:
+ *
+ *  1. **It survives `stripTagHash`.** `SqliteStore.normalizeQueryTags` maps
+ *     `stripTagHash` over query tags and drops the empties — a substitute
+ *     that normalized away would collapse `tags` to `[]`, skip the tag
+ *     filter entirely, and hand an out-of-scope probe the caller's WHOLE
+ *     visible set. Hence the NUL rather than a leading `#`/space.
+ *  2. **A collision is inert.** Storage does not police tag bytes, so a
+ *     note CAN be written carrying this name (nothing that reads YAML
+ *     front-matter or a JSON `tags` array will do so by accident). It buys
+ *     an attacker nothing: this rewrite only changes which notes the query
+ *     matches, and every read path still applies the unchanged result-side
+ *     `filterNotesByTagScope` — so a planted decoy can only ever surface to
+ *     a caller who could already read it.
+ */
+export const OUT_OF_SCOPE_QUERY_TAG = "\u0000out-of-scope";
+
+/**
+ * Rewrite an out-of-scope tag NAMED IN A QUERY to `OUT_OF_SCOPE_QUERY_TAG`
+ * (vault#675 — the existence-oracle class left open after #568/#674).
+ *
+ * #568 stopped scoped reads from DISCLOSING an out-of-scope co-tag's name.
+ * A scoped caller could still name one itself — `?tag=project-manhattan`,
+ * `query-notes { tag }`, a live subscription — and read the answer off
+ * hit/miss: a note tagged `["mine","project-manhattan"]` passes
+ * `noteWithinTagScope` via `mine`, so the co-tagged filter came back with a
+ * row and confirmed the guessed name. No name leaked; membership did.
+ *
+ * Policy: **an out-of-scope tag behaves exactly as a tag that does not
+ * exist** — the same equivalence the rest of this contract already runs on
+ * (an out-of-scope note 404s like a missing one; `list-tags { tag }` /
+ * `GET /api/tags?tag=` return `tag_not_found` for an out-of-scope name
+ * "whether the tag exists or not"). In the FILTER position a nonexistent tag
+ * is not an error — it is a filter that matches nothing — so this is a
+ * rewrite, not a rejection: the query still runs and still returns 200, it
+ * just can't match. Rewriting (rather than short-circuiting per door) is
+ * what makes the response byte-identical to the nonexistent-tag control on
+ * every door and in every shape — list, cursor envelope, `format=graph`,
+ * aggregate rollup, live snapshot — because it IS the nonexistent-tag code
+ * path, not a reconstruction of it.
+ *
+ * Composition falls out of that, no special cases:
+ *   - `tag=X` (out of scope) → matches nothing → `[]`.
+ *   - `tag=mine&tag=X&tag_match=all` → the `X` membership clause matches
+ *     nothing → `[]` (dropping `X` instead would have WIDENED the answer).
+ *   - `tag=mine&tag=X&tag_match=any` → the union is just `mine`'s notes.
+ *   - `exclude_tag=X` → core skips an exclude clause that can't match,
+ *     so it excludes nothing — again exactly a nonexistent tag.
+ *
+ * Visibility uses the same `tagVisibleInScope` rule that admits a note and
+ * scrubs `.tags`, applied to the BARE form (`stripTagHash`) because the
+ * query engine strips `#` before matching — otherwise `?tag=%23mine` would
+ * be neutralised for a `mine`-scoped caller.
+ *
+ * Non-mutating, and a no-op for unscoped tokens (`rawRoots === null`) and
+ * for queries whose tags are all in scope — the input object is returned by
+ * reference in both cases.
+ */
+export function scopeQueryTags<T extends { tags?: string[]; excludeTags?: string[] }>(
+  opts: T,
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): T {
+  if (rawRoots === null || !opts) return opts;
+  const tags = scopeQueryTagList(opts.tags, allowed, rawRoots);
+  const excludeTags = scopeQueryTagList(opts.excludeTags, allowed, rawRoots);
+  if (tags === opts.tags && excludeTags === opts.excludeTags) return opts;
+  const next: T = { ...opts };
+  if (tags !== opts.tags) next.tags = tags;
+  if (excludeTags !== opts.excludeTags) next.excludeTags = excludeTags;
+  return next;
+}
+
+/** `scopeQueryTags` for one array of query tags. Same array back if unchanged. */
+function scopeQueryTagList(
+  tags: string[] | undefined,
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): string[] | undefined {
+  if (!tags || tags.length === 0) return tags;
+  let changed = false;
+  const out = tags.map((t) => {
+    if (typeof t !== "string" || tagVisibleInScope(stripTagHash(t), allowed, rawRoots)) return t;
+    changed = true;
+    return OUT_OF_SCOPE_QUERY_TAG;
+  });
+  return changed ? out : tags;
+}
+
+/**
+ * `scopeQueryTags` for an MCP tool param, which is `string | string[]`
+ * (`normalizeTags` accepts either). Shape-preserving — a string stays a
+ * string — so the rewritten params lower to the same `QueryOpts` the
+ * original would have. Same reference back when nothing is rewritten.
+ */
+export function scopeQueryTagParam<V>(value: V, allowed: Set<string> | null, rawRoots: string[] | null): V {
+  if (rawRoots === null || value === undefined || value === null) return value;
+  if (typeof value === "string") {
+    return (tagVisibleInScope(stripTagHash(value), allowed, rawRoots)
+      ? value
+      : OUT_OF_SCOPE_QUERY_TAG) as unknown as V;
+  }
+  if (Array.isArray(value)) {
+    const scoped = scopeQueryTagList(value as string[], allowed, rawRoots);
+    return (scoped === (value as unknown as string[]) ? value : scoped) as unknown as V;
+  }
+  return value;
+}
+
 /**
  * Treat a hydrated link's endpoint summary as a scope-checkable note. The
  * summary carries `id` + `tags`, which is all `noteWithinTagScope` needs.

package/src/test-support/vault-714-find-path.json

@@ -0,0 +1,58 @@
+{
+  "MCP": {
+    "path": [
+      "work-src",
+      "hidden-dup"
+    ],
+    "relationships": [
+      "wikilink"
+    ],
+    "nodes": [
+      {
+        "id": "work-src",
+        "path": "work-src"
+      },
+      {
+        "id": "hidden-dup",
+        "path": "p1/Dup"
+      }
+    ],
+    "edges": [
+      {
+        "source": "work-src",
+        "target": "hidden-dup",
+        "relationship": "wikilink",
+        "sourcePath": "work-src",
+        "targetPath": "p1/Dup"
+      }
+    ]
+  },
+  "REST": {
+    "path": [
+      "work-src",
+      "hidden-dup"
+    ],
+    "relationships": [
+      "wikilink"
+    ],
+    "nodes": [
+      {
+        "id": "work-src",
+        "path": "work-src"
+      },
+      {
+        "id": "hidden-dup",
+        "path": "p1/Dup"
+      }
+    ],
+    "edges": [
+      {
+        "source": "work-src",
+        "target": "hidden-dup",
+        "relationship": "wikilink",
+        "sourcePath": "work-src",
+        "targetPath": "p1/Dup"
+      }
+    ]
+  }
+}

package/src/test-support/vault-714-graph.json

@@ -0,0 +1,27 @@
+{
+  "REST": {
+    "nodes": [
+      {
+        "id": "hidden-dup",
+        "path": "p1/Dup",
+        "tags": [
+          "personal"
+        ]
+      },
+      {
+        "id": "work-src",
+        "path": "work-src",
+        "tags": [
+          "work"
+        ]
+      }
+    ],
+    "edges": [
+      {
+        "source": "work-src",
+        "target": "hidden-dup",
+        "relationship": "wikilink"
+      }
+    ]
+  }
+}

package/src/test-support/vault-714-has_links.json

@@ -0,0 +1,96 @@
+{
+  "MCP": [
+    [
+      {
+        "id": "hidden-dup",
+        "path": "p1/Dup",
+        "extension": "md",
+        "createdAt": "2026-01-01T00:00:00.000Z",
+        "updatedAt": "2026-01-01T00:00:00.000Z",
+        "createdBy": null,
+        "createdVia": null,
+        "lastUpdatedBy": null,
+        "lastUpdatedVia": null,
+        "tags": [
+          "personal"
+        ],
+        "metadata": {},
+        "byteSize": 12,
+        "preview": "personal dup",
+        "displayTitle": "personal dup"
+      },
+      {
+        "id": "work-src",
+        "path": "work-src",
+        "extension": "md",
+        "createdAt": "2026-01-01T00:00:00.000Z",
+        "updatedAt": "2026-01-01T00:00:00.000Z",
+        "createdBy": null,
+        "createdVia": null,
+        "lastUpdatedBy": null,
+        "lastUpdatedVia": null,
+        "tags": [
+          "work"
+        ],
+        "metadata": {},
+        "byteSize": 11,
+        "preview": "src [[Dup]]",
+        "displayTitle": "src [[Dup]]"
+      }
+    ],
+    [],
+    [
+      {
+        "group": null,
+        "value": 2
+      }
+    ]
+  ],
+  "REST": [
+    [
+      {
+        "id": "hidden-dup",
+        "path": "p1/Dup",
+        "extension": "md",
+        "createdAt": "2026-01-01T00:00:00.000Z",
+        "updatedAt": "2026-01-01T00:00:00.000Z",
+        "createdBy": null,
+        "createdVia": null,
+        "lastUpdatedBy": null,
+        "lastUpdatedVia": null,
+        "tags": [
+          "personal"
+        ],
+        "metadata": {},
+        "byteSize": 12,
+        "preview": "personal dup",
+        "displayTitle": "personal dup"
+      },
+      {
+        "id": "work-src",
+        "path": "work-src",
+        "extension": "md",
+        "createdAt": "2026-01-01T00:00:00.000Z",
+        "updatedAt": "2026-01-01T00:00:00.000Z",
+        "createdBy": null,
+        "createdVia": null,
+        "lastUpdatedBy": null,
+        "lastUpdatedVia": null,
+        "tags": [
+          "work"
+        ],
+        "metadata": {},
+        "byteSize": 11,
+        "preview": "src [[Dup]]",
+        "displayTitle": "src [[Dup]]"
+      }
+    ],
+    [],
+    [
+      {
+        "group": null,
+        "value": 2
+      }
+    ]
+  ]
+}