@openparachute/vault 0.7.0-rc.3 → 0.7.0-rc.5

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

@@ -0,0 +1,97 @@
+/**
+ * Tag-scope scrub on the two vault#552 taxonomy-integrity guards:
+ * `tag_referenced_as_parent` (delete-tag's referential-integrity refusal)
+ * and `parent_cycle` (upsertTagRecord's write-time cycle guard). Same "in
+ * doubt, scrub" posture as `tag_field_conflict` (see
+ * tag-field-conflict-scope.test.ts) — the write stays rejected regardless
+ * of scope, but an out-of-scope tag name must never appear in the response.
+ *
+ * Reachability note: for BOTH guards, the offending tag(s) the scrub would
+ * redact are, by construction, always descendants of the tag the caller is
+ * already scoped to (deleteTag's `referencing_tags` are children of the
+ * doomed tag; `findParentCycle`'s conflicting parent + path are members of
+ * `getTagDescendants(hierarchy, tag)`, the SAME computation
+ * `expandTokenTagScope` uses to build the caller's allowlist for that same
+ * `tag`). So under the CURRENT hierarchy-based tag-scope model, a live
+ * end-to-end request can't actually construct an out-of-scope referrer —
+ * the scrub is defense-in-depth for a future change to either guard (e.g. if
+ * `deleteTag`'s search ever widens past direct parent_names children). These
+ * tests exercise the scrub functions directly against a synthetic
+ * out-of-scope input to pin the CONTRACT ("an out-of-scope name never
+ * survives"), independent of today's reachability.
+ */
+import { describe, test, expect } from "bun:test";
+import { scrubReferencingTagsByScope, scrubParentCycleError } from "./tag-scope.ts";
+import { ParentCycleError } from "../core/src/tag-schemas.ts";
+
+describe("scrubReferencingTagsByScope (vault#552)", () => {
+  test("unscoped caller (allowed === null): passthrough, no redaction", () => {
+    const result = scrubReferencingTagsByScope(["child-a", "secret-child"], null);
+    expect(result).toEqual(["child-a", "secret-child"]);
+  });
+
+  test("scoped caller: in-scope names kept, out-of-scope names redacted to a generic label — never the real name", () => {
+    const allowed = new Set(["child-a"]);
+    const result = scrubReferencingTagsByScope(["child-a", "secret-child"], allowed);
+    expect(result[0]).toBe("child-a");
+    expect(result[1]).not.toBe("secret-child");
+    expect(result.join(" ")).not.toContain("secret-child");
+    expect(result[1]).toContain("outside your token's tag scope");
+  });
+
+  test("every referencing tag out of scope: every entry redacted, count preserved", () => {
+    const allowed = new Set<string>(["unrelated"]);
+    const result = scrubReferencingTagsByScope(["secret-1", "secret-2"], allowed);
+    expect(result).toHaveLength(2);
+    for (const r of result) {
+      expect(r).not.toBe("secret-1");
+      expect(r).not.toBe("secret-2");
+    }
+  });
+
+  test("empty referencing list stays empty", () => {
+    expect(scrubReferencingTagsByScope([], new Set())).toEqual([]);
+  });
+});
+
+describe("scrubParentCycleError (vault#552)", () => {
+  test("unscoped caller (allowed === null): passthrough, same instance semantics (message/tag/cycle unchanged)", () => {
+    const err = new ParentCycleError("mine", ["mine", "secret-hop", "mine"]);
+    const scrubbed = scrubParentCycleError(err, null);
+    expect(scrubbed).toBe(err);
+  });
+
+  test("every hop in scope: passthrough, original error returned untouched", () => {
+    const err = new ParentCycleError("mine", ["mine", "child", "mine"]);
+    const allowed = new Set(["mine", "child"]);
+    const scrubbed = scrubParentCycleError(err, allowed);
+    expect(scrubbed).toBe(err);
+    expect(scrubbed.cycle).toEqual(["mine", "child", "mine"]);
+  });
+
+  test("an out-of-scope hop is generalized: the caller's own tag stays named, the out-of-scope hop does not, and the write is still reported rejected", () => {
+    const err = new ParentCycleError("mine", ["mine", "secret-hop", "mine"]);
+    const allowed = new Set(["mine"]); // "secret-hop" deliberately excluded
+    const scrubbed = scrubParentCycleError(err, allowed);
+
+    expect(scrubbed).not.toBe(err); // a REPLACEMENT error, not the original
+    expect(scrubbed.error_type).toBe("parent_cycle");
+    expect(scrubbed.tag).toBe("mine"); // the caller's own tag — always in-scope, never redacted
+    expect(scrubbed.cycle[0]).toBe("mine");
+    expect(scrubbed.cycle[2]).toBe("mine");
+    expect(scrubbed.cycle[1]).not.toBe("secret-hop");
+    expect(scrubbed.cycle.join(" ")).not.toContain("secret-hop");
+    expect(scrubbed.message).not.toContain("secret-hop");
+    expect(scrubbed.message).toContain("cycle");
+  });
+
+  test("multiple out-of-scope hops in a longer chain are each redacted independently", () => {
+    const err = new ParentCycleError("mine", ["mine", "secret-1", "secret-2", "mine"]);
+    const allowed = new Set(["mine"]);
+    const scrubbed = scrubParentCycleError(err, allowed);
+    expect(scrubbed.cycle[1]).not.toBe("secret-1");
+    expect(scrubbed.cycle[2]).not.toBe("secret-2");
+    expect(scrubbed.cycle.join(" ")).not.toContain("secret-1");
+    expect(scrubbed.cycle.join(" ")).not.toContain("secret-2");
+  });
+});

package/src/tag-scope.ts

@@ -20,6 +20,12 @@
  */
 
 import type { Store, Note, HydratedLink, NoteSummary } from "../core/src/types.ts";
+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";
+
+/** 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)";
 
 /**
  * Build the effective tag-allowlist for a token: union of `{root} ∪
@@ -167,6 +173,109 @@ export function filterHydratedLinksByTagScope(
   );
 }
 
+/**
+ * Scrub `tag_field_conflict` violations for a tag-scoped caller
+ * (vault#554 auth-and-scope review fold). Core's cross-tag field
+ * validation (`collectCrossTagFieldViolations` / `collectTagFieldViolations`
+ * in core/src/tag-schemas.ts) scans EVERY tag's schema — scope-unaware by
+ * architecture — so a scoped caller updating its own in-scope tag can
+ * receive a violation whose `message` names an OUT-OF-SCOPE tag and
+ * reveals its declared type/indexed flag (proven live on both MCP and
+ * REST). Policy: the write is STILL rejected (schema integrity is
+ * scope-independent — do not weaken the check), but the violation entry
+ * for an out-of-scope conflicting declarer is generalized: no tag name,
+ * no declared type/flag, `other_tag` dropped. In-scope conflicting
+ * declarers keep full detail; solo own-field violations (no `other_tag`)
+ * pass through untouched; unscoped callers (`allowed === null`) keep full
+ * detail everywhere.
+ *
+ * Membership is `allowed.has(other_tag)` — the same convention the
+ * `did_you_mean` scrub and the update-tag/delete-tag wrappers use in
+ * src/mcp-tools.ts (no string-form root fallback: when in doubt, scrub —
+ * the fail-closed direction only costs detail, never correctness).
+ */
+export function scrubTagFieldViolationsByScope(
+  violations: TagFieldViolation[],
+  allowed: Set<string> | null,
+): TagFieldViolation[] {
+  if (allowed === null) return violations;
+  return violations.map((v) => {
+    if (v.other_tag === undefined || allowed.has(v.other_tag)) return v;
+    const generalized =
+      v.reason === "type_conflict"
+        ? `field "${v.field}" type conflict: another tag (outside your token's tag scope) declares this field with a different type. Types must agree across all declarers.`
+        : `field "${v.field}" indexed-flag conflict: another tag (outside your token's tag scope) declares this field with a different indexed flag. Must match across all declarers.`;
+    const { other_tag: _dropped, ...rest } = v;
+    return { ...rest, message: generalized };
+  });
+}
+
+/**
+ * Companion scrub for the OTHER door the same information can leak
+ * through (vault#554 auth-and-scope × wire-review interaction): a
+ * both-indexed cross-tag type conflict deliberately bypasses the
+ * `tag_field_conflict` pre-check (preserving its pre-existing
+ * `declareField` → 400 `invalid_indexed_field` contract — see
+ * `collectCrossTagFieldViolations`'s doc comment), and declareField's
+ * message names the other declarer tag(s) plus their sqlite type. For a
+ * tag-scoped caller with any out-of-scope declarer, return a REPLACEMENT
+ * `IndexedFieldError` with a generalized message (no tag names, no
+ * existing type) — same rejection, same 400 status, same `error_type`,
+ * just no leak. If every declarer is in scope (or the error carries no
+ * `declarer_tags` — the solo own-field throws), or the caller is unscoped
+ * (`allowed === null`), the original error is returned untouched.
+ */
+export function scrubIndexedFieldConflictError(
+  err: IndexedFieldError & { field?: string; declarer_tags?: string[] },
+  allowed: Set<string> | null,
+): IndexedFieldError {
+  if (allowed === null) return err;
+  if (!Array.isArray(err.declarer_tags) || err.declarer_tags.length === 0) return err;
+  if (err.declarer_tags.every((t) => allowed.has(t))) return err;
+  return new IndexedFieldError(
+    `field "${err.field ?? "?"}" is already indexed by another tag (outside your token's tag scope) with a conflicting type. Types must agree across all declarers.`,
+  );
+}
+
+/**
+ * Scrub the `referencing_tags` list on a `tag_referenced_as_parent` refusal
+ * (vault#552 — deleteTag's referential-integrity guard) for a tag-scoped
+ * caller. The delete is refused regardless of scope (referential integrity
+ * is scope-independent, same posture as `tag_field_conflict`), but a
+ * referencing tag OUTSIDE the caller's allowlist must not be named — same
+ * "in doubt, scrub" convention `scrubTagFieldViolationsByScope` uses.
+ * No-op for unscoped callers (`allowed === null`).
+ */
+export function scrubReferencingTagsByScope(
+  referencing: string[],
+  allowed: Set<string> | null,
+): string[] {
+  if (allowed === null) return referencing;
+  return referencing.map((t) => (allowed.has(t) ? t : OUT_OF_SCOPE_LABEL));
+}
+
+/**
+ * Scrub a `ParentCycleError`'s `cycle` path (vault#552 — the `parent_names`
+ * cycle guard) for a tag-scoped caller. The write is still rejected — a
+ * cycle is a structural problem independent of who's asking — but the
+ * cycle path can walk through tags OUTSIDE the caller's allowlist (the
+ * hierarchy `upsertTagRecord` validates against is vault-wide, scope-unaware
+ * by architecture, same as the cross-tag field checks). Returns a
+ * REPLACEMENT error with out-of-scope hops in `cycle` generalized; the
+ * caller's own tag (`err.tag`) is always in-scope by the time this runs (the
+ * update-tag wrapper already gates on it) so it's never redacted. No-op for
+ * unscoped callers or a cycle with no out-of-scope hop.
+ */
+export function scrubParentCycleError(
+  err: ParentCycleError,
+  allowed: Set<string> | null,
+): ParentCycleError {
+  if (allowed === null) return err;
+  if (err.cycle.every((t) => allowed.has(t))) return err;
+  const scrubbedCycle = err.cycle.map((t) => (allowed.has(t) ? t : OUT_OF_SCOPE_LABEL));
+  return new ParentCycleError(err.tag, scrubbedCycle);
+}
+
 /**
  * Standard 403 response shape for tag-scope rejections. Mirrors the
  * `insufficient_scope` 403 shape used elsewhere in the API so clients

package/src/vault.test.ts

@@ -484,7 +484,7 @@ describe("deeper link queries", async () => {
 describe("MCP tools", async () => {
   test("generates the consolidated tool set", () => {
     const tools = generateMcpTools(store);
-    expect(tools.length).toBe(10);
+    expect(tools.length).toBe(13);
 
     const names = tools.map((t) => t.name);
     expect(names).toContain("query-notes");
@@ -498,6 +498,12 @@ describe("MCP tools", async () => {
     expect(names).toContain("vault-info");
     // prune-schema (admin) — drops orphaned indexed-field columns.
     expect(names).toContain("prune-schema");
+    // rename-tag / merge-tags (vault#552) — MCP parity with the pre-existing
+    // REST engine.
+    expect(names).toContain("rename-tag");
+    expect(names).toContain("merge-tags");
+    // doctor (admin, vault#552) — read-only taxonomy/metadata integrity scan.
+    expect(names).toContain("doctor");
     // Six note-schema MCP tools (list/update/delete-note-schema +
     // list/set/delete-schema-mapping) retired in v17 — vault#267.
     expect(names).not.toContain("list-note-schemas");
@@ -5414,8 +5420,11 @@ describe("stateless MCP transport", async () => {
     expect(toolNames).not.toContain("delete-note");
     expect(toolNames).not.toContain("update-tag");
     expect(toolNames).not.toContain("delete-tag");
+    expect(toolNames).not.toContain("rename-tag");
+    expect(toolNames).not.toContain("merge-tags");
     // Admin tools (vault#376) are hidden too
     expect(toolNames).not.toContain("manage-token");
+    expect(toolNames).not.toContain("doctor");
     // Read tier is exactly 4 tools.
     expect(toolNames.length).toBe(4);
 
@@ -5658,7 +5667,7 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     expect(names.length).toBe(4);
   });
 
-  test("vault:read + vault:write sees the 9 read+write tools", async () => {
+  test("vault:read + vault:write sees the 11 read+write tools", async () => {
     const names = await listToolNames(["vault:read", "vault:write"]);
     expect(new Set(names)).toEqual(
       new Set([
@@ -5671,24 +5680,31 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
         "delete-note",
         "update-tag",
         "delete-tag",
+        // vault#552: MCP parity with the pre-existing REST rename/merge engine.
+        "rename-tag",
+        "merge-tags",
       ]),
     );
-    expect(names.length).toBe(9);
+    expect(names.length).toBe(11);
     expect(names).not.toContain("manage-token");
+    expect(names).not.toContain("doctor");
     // Aaron 2026-05-27: delete-* are write-tier (same destructive verb as
-    // update). Only manage-token is admin-gated.
+    // update). Only manage-token/prune-schema/doctor are admin-gated.
     expect(names).toContain("delete-note");
     expect(names).toContain("delete-tag");
   });
 
-  test("vault:admin sees all 11 tools including manage-token + prune-schema", async () => {
+  test("vault:admin sees all 14 tools including manage-token + prune-schema + doctor", async () => {
     const names = await listToolNames(["vault:read", "vault:write", "vault:admin"]);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
-    expect(names.length).toBe(11);
+    expect(names).toContain("doctor");
+    expect(names).toContain("rename-tag");
+    expect(names).toContain("merge-tags");
+    expect(names.length).toBe(14);
   });
 
-  test("legacy-derived full token sees all 11 tools (back-compat)", async () => {
+  test("legacy-derived full token sees all 14 tools (back-compat)", async () => {
     const { handleScopedMcp } = await import("./mcp-http.ts");
     const { writeVaultConfig } = await import("./config.ts");
     const { closeAllStores } = await import("./vault-store.ts");
@@ -5721,9 +5737,10 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     } as any);
     const body = await res.json() as any;
     const names: string[] = body.result.tools.map((t: any) => t.name);
-    expect(names.length).toBe(11);
+    expect(names.length).toBe(14);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
+    expect(names).toContain("doctor");
     closeAllStores();
   });