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

package/src/mcp-http.ts

@@ -139,13 +139,18 @@ async function handleMcp(
         content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
-      // Domain errors from the core tools (conflict, missing precondition) get
-      // surfaced as JSON-RPC errors with a structured `data` field so an
-      // agent can key off `data.error_type` and the concurrency tokens.
-      // Everything else falls through to an in-band tool error with
-      // `isError: true` — legible but unstructured.
+      // Domain errors from the core tools (conflict, missing precondition,
+      // path collisions, batch caps, cursor/query validation, tag-field
+      // conflicts, ...) get surfaced as JSON-RPC errors with a structured
+      // `data` field so an agent can key off `data.error_type` and any
+      // error-specific fields (concurrency tokens, violations, candidates,
+      // ...). vault#554: every domain error class is mapped below, either by
+      // a dedicated branch (full field fidelity) or the generic `error_type`
+      // catch-all near the end. Only a TRULY unknown error (no `error_type`
+      // anywhere on it) falls through to the in-band `isError: true` text.
       const message = err instanceof Error ? err.message : "Unknown error";
       const e = err as {
+        name?: string;
         code?: string;
         note_id?: string;
         note_path?: string | null;
@@ -159,6 +164,12 @@ async function handleMcp(
         error_type?: string;
         got?: unknown;
         hint?: string;
+        path?: string;
+        candidates?: unknown;
+        extension?: string;
+        reason?: string;
+        limit?: number;
+        tag?: string;
       };
       // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
       // values that are structurally invalid rather than merely "no
@@ -176,6 +187,19 @@ async function handleMcp(
           hint: e.hint,
         });
       }
+      // Advanced-mode full-text search syntax error (vault#551) — a
+      // raw-passthrough FTS5 query that FTS5 itself rejected. Same shape as
+      // `invalid_query` (field/got/hint) but a DISTINCT `error_type` so a
+      // caller can tell "your search_mode:\"advanced\" syntax is malformed"
+      // apart from "your query PARAMS are malformed."
+      if (e?.error_type === "invalid_search_syntax") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "invalid_search_syntax",
+          field: e.field,
+          got: e.got,
+          hint: e.hint,
+        });
+      }
       if (e?.code === "CONFLICT") {
         throw new McpError(ErrorCode.InvalidRequest, message, {
           error_type: "conflict",
@@ -183,6 +207,7 @@ async function handleMcp(
           your_updated_at: e.expected_updated_at,
           path: e.note_path ?? null,
           note_id: e.note_id,
+          hint: "re-read the note (query-notes) and re-apply your change against its current updated_at, or pass force: true to overwrite",
         });
       }
       // State-transition compare-and-set conflict (vault#299 Part B) — a
@@ -197,6 +222,7 @@ async function handleMcp(
           expected_from: e.expected_from,
           to: e.to,
           current: e.current ?? null,
+          hint: "re-read the note's current value for this field and retry the transition from its actual current state",
         });
       }
       // Strict-schema rejection (vault#299 Part A) — one error carrying ALL
@@ -205,6 +231,7 @@ async function handleMcp(
         throw new McpError(ErrorCode.InvalidParams, message, {
           error_type: "schema_validation",
           violations: e.violations ?? [],
+          hint: "fix every field listed in violations and retry — none of this write was applied",
         });
       }
       if (e?.code === "PRECONDITION_REQUIRED") {
@@ -212,6 +239,96 @@ async function handleMcp(
           error_type: "precondition_required",
           note_id: e.note_id,
           path: e.note_path ?? null,
+          hint: "re-read the note, pass its updated_at as if_updated_at, or pass force: true to skip the check",
+        });
+      }
+      // Any other QueryError (vault#554) — FIELD_NOT_INDEXED, UNKNOWN_OPERATOR,
+      // INVALID_OPERATOR_VALUE, and the various cursor/near/search
+      // incompatibility throws that predate the vault#550/#551 `error_type`
+      // convention (which is why they weren't caught by the two branches
+      // above). Falls back to `error_type: "invalid_query"` — the umbrella
+      // REST already uses for this whole error class — so these no longer
+      // fall through to the unstructured `isError: true` text.
+      if (e?.name === "QueryError") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: e.error_type ?? "invalid_query",
+          code: e.code,
+          field: e.field,
+          got: e.got,
+          hint: e.hint,
+        });
+      }
+      // Malformed / stale opaque cursor (vault#313, vault#554) — was
+      // entirely unmapped here before (REST already returns `{error, code}`
+      // — no `error_type` either; both surfaces get one now). `code` is
+      // already the exact `error_type` vocabulary: "cursor_invalid" or
+      // "cursor_query_mismatch".
+      if (e?.name === "CursorError" && typeof e.code === "string") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: e.code,
+        });
+      }
+      // Path-rename/create collision (vault#126, vault#554) — schema's
+      // UNIQUE(path) tripped. Mirrors REST's 409 `path_conflict` shape.
+      if (e?.code === "PATH_CONFLICT") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "path_conflict",
+          path: e.path,
+        });
+      }
+      // A path lookup matched more than one note (vault#330 S1, vault#554) —
+      // mirrors REST's 409 `ambiguous_path` shape (candidates = the
+      // disambiguating extensions).
+      if (e?.code === "AMBIGUOUS_PATH") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "ambiguous_path",
+          path: e.path,
+          candidates: e.candidates,
+        });
+      }
+      // Bad `extension` value (vault#328, vault#554) — mirrors REST's 400
+      // `invalid_extension` shape.
+      if (e?.code === "INVALID_EXTENSION") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "invalid_extension",
+          extension: e.extension,
+          reason: e.reason,
+        });
+      }
+      // Batch cap exceeded (#213, vault#554) — mirrors REST's 413
+      // `batch_too_large` shape.
+      if (e?.code === "BATCH_TOO_LARGE") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "batch_too_large",
+          limit: e.limit,
+          got: e.got,
+        });
+      }
+      // update-tag cross-tag field conflicts (vault#553/#554) — carries
+      // EVERY violation in one response (see `TagFieldConflictError`).
+      if (e?.code === "TAG_FIELD_CONFLICT") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "tag_field_conflict",
+          tag: e.tag,
+          violations: e.violations ?? [],
+        });
+      }
+      // Generic catch-all (vault#554): any remaining error that carries a
+      // stable `error_type` — either a domain error class that stamps it as
+      // an instance property (IndexedFieldError, and the classes handled by
+      // dedicated branches above as defense-in-depth) or a validation leaf
+      // built with `structuredError()` in core/src/mcp.ts (mutually_exclusive,
+      // invalid_content_edit, content_edit_not_found, content_edit_ambiguous,
+      // invalid_state_transition, invalid_parent_names, invalid_relationships,
+      // not_found, ...). This is the backstop that makes "nothing falls
+      // through to the unstructured isError text except a TRULY unknown
+      // error" true by construction: only errors nobody tagged with
+      // `error_type` still hit the fallback below.
+      if (typeof e?.error_type === "string") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: e.error_type,
+          field: e.field,
+          hint: e.hint,
         });
       }
       return {

package/src/mcp-list-tags-scope.test.ts

@@ -151,4 +151,40 @@ describe("MCP list-tags single-tag path — tag-scope enforcement (vault#550 fol
     expect(names).toContain("health");
     expect(names).not.toContain("work");
   });
+
+  // vault#554 carry-forward: the wrapper's SECOND scrub branch (the one
+  // AFTER the early out-of-scope short-circuit above) fires when the queried
+  // tag itself IS in the allowlist but core still reports tag_not_found —
+  // the hollow-tag case (vault#550: no identity row, no notes directly
+  // carrying it) reached ONLY via a child's `parent_names`. Core computes
+  // `did_you_mean` vault-wide (scope-unaware by architecture), so it can
+  // name an out-of-scope tag; the wrapper must strip that suggestion even
+  // though the queried tag itself passed the allowlist gate. This branch was
+  // execution-verified in a prior review; this test commits it.
+  test("scoped token + in-scope HOLLOW tag (reachable only via a child's parent_names) scrubs an out-of-scope did_you_mean", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    // "health" itself has NO identity row and NO note directly carrying it —
+    // it's in the allowlist expansion ONLY because "kale" declares it as a
+    // parent. "kale" is deliberately NOT lexically close to "health" (the
+    // mission's "non-close child") so it can't win did_you_mean and mask
+    // the bug this test targets.
+    await store.upsertTagRecord("kale", { parent_names: ["health"] });
+    await store.createNote("k", { tags: ["kale"] });
+
+    // Out-of-scope decoy, lexically close to "health" (prefix match) — this
+    // is what core's vault-wide suggestSimilarTag would pick if nothing
+    // scrubbed it.
+    await store.createNote("hy", { tags: ["healthy"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({ tag: "health" })) as any;
+
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("health");
+    // The scrub: did_you_mean must NOT leak the out-of-scope "healthy",
+    // even though "health" (the query) itself passed the allowlist gate.
+    expect(result.did_you_mean).toBeUndefined();
+  });
 });

package/src/mcp-query-notes-search-scope.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Combined tag-scope × full-text-search enforcement (vault#554 carry-forward
+ * — "auth-561" review traced the code clean; this commits the self-verifying
+ * test the review promised).
+ *
+ * `applyTagScopeWrappers`'s `query-notes` wrapper (`src/mcp-tools.ts`) runs
+ * the ENTIRE search — content matching, `search_mode` escaping, `sort` — via
+ * core (scope-unaware by architecture), then filters the returned notes
+ * against the token's allowlist as a post-hoc array `.filter()`
+ * (`noteWithinTagScope`, `src/tag-scope.ts`). Because the filter is applied
+ * uniformly AFTER core returns, in principle no single (mode, sort)
+ * combination is special — but a regression in one code path (e.g. a search
+ * branch that bypasses the wrapper, or a shape the filter doesn't recognize)
+ * could still slip an out-of-scope note through for SOME combination. This
+ * test exercises the full `search_mode × sort` matrix and asserts the
+ * out-of-scope note never appears in any of them.
+ *
+ * Fixture: two notes both match the search term "widget" in punctuation-
+ * bearing content (so literal-mode escaping and advanced-mode raw FTS5 both
+ * still match it) — one tagged in-scope (`health`), one out-of-scope
+ * (`work`). A tag-scoped session ["health"] must see only the in-scope note
+ * across every (search_mode, sort) pairing.
+ */
+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 type { AuthResult } from "./auth.ts";
+import { SEARCH_MODES } from "../core/src/search-query.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-search-scope-${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): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  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",
+  };
+}
+
+async function queryNotesTool(vaultName: string, scopedTags: string[] | null) {
+  const tools = generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags));
+  return tools.find((t) => t.name === "query-notes")!;
+}
+
+// Normalize the tool's response (bare array, or {notes, next_cursor?,
+// warnings?} in cursor/warnings mode) down to the note-id list actually
+// returned — search is never cursor mode, but stays defensive to shape.
+function idsOf(result: unknown): string[] {
+  if (Array.isArray(result)) return result.map((n: any) => n.id);
+  const notes = (result as any)?.notes;
+  return Array.isArray(notes) ? notes.map((n: any) => n.id) : [];
+}
+
+describe("MCP query-notes search × tag-scope — combined enforcement (vault#554 carry-forward)", () => {
+  test("out-of-scope notes never appear across every search_mode × sort combination", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    // Punctuation-bearing content so literal-mode's escaping and
+    // advanced-mode's raw FTS5 passthrough both still match "widget"
+    // cleanly (advanced mode has no operator characters to trip on here).
+    const inScope = await store.createNote("didn't fix the widget yet", { tags: ["health"] });
+    const outOfScope = await store.createNote("ordered a replacement widget", { tags: ["work"] });
+
+    const tool = await queryNotesTool("journal", ["health"]);
+
+    const sorts: (undefined | "asc" | "desc")[] = [undefined, "asc", "desc"];
+    const modes: (undefined | (typeof SEARCH_MODES)[number])[] = [undefined, ...SEARCH_MODES];
+
+    for (const search_mode of modes) {
+      for (const sort of sorts) {
+        const params: Record<string, unknown> = { search: "widget" };
+        if (search_mode !== undefined) params.search_mode = search_mode;
+        if (sort !== undefined) params.sort = sort;
+
+        const result = await tool.execute(params);
+        const ids = idsOf(result);
+
+        expect(ids).toContain(inScope.id);
+        expect(ids).not.toContain(outOfScope.id);
+      }
+    }
+  });
+
+  test("unscoped session sees both notes across the same matrix (control)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    const a = await store.createNote("didn't fix the widget yet", { tags: ["health"] });
+    const b = await store.createNote("ordered a replacement widget", { tags: ["work"] });
+
+    const tool = await queryNotesTool("journal", null);
+
+    for (const search_mode of [undefined, ...SEARCH_MODES]) {
+      for (const sort of [undefined, "asc", "desc"] as const) {
+        const params: Record<string, unknown> = { search: "widget" };
+        if (search_mode !== undefined) params.search_mode = search_mode;
+        if (sort !== undefined) params.sort = sort;
+
+        const ids = idsOf(await tool.execute(params));
+        expect(ids).toContain(a.id);
+        expect(ids).toContain(b.id);
+      }
+    }
+  });
+});

package/src/mcp-tools.ts

@@ -22,8 +22,12 @@ import {
   expandTokenTagScope,
   filterHydratedLinksByTagScope,
   noteWithinTagScope,
+  scrubIndexedFieldConflictError,
+  scrubTagFieldViolationsByScope,
   tagsWithinScope,
 } from "./tag-scope.ts";
+import { TagFieldConflictError } from "../core/src/tag-schemas.ts";
+import { IndexedFieldError } from "../core/src/indexed-fields.ts";
 import {
   findTokensReferencingTag,
   recordMcpMintLedger,
@@ -344,7 +348,7 @@ function applyTagScopeWrappers(
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
       return noteWithinTagScope(result as any, allowed, rawTags)
         ? scrubNoteLinks(result)
-        : { error: "Note not found", id: (result as any).id };
+        : { error: "Note not found", error_type: "not_found", id: (result as any).id };
     }
     return result;
   });
@@ -470,7 +474,7 @@ function applyTagScopeWrappers(
       if (!id) continue;
       const existing = await store.getNote(id as string);
       if (!existing || !noteWithinTagScope(existing, allowed, rawTags)) {
-        return { error: "Note not found", id };
+        return { error: "Note not found", error_type: "not_found", id };
       }
       const removed = new Set<string>((item as any).tags?.remove ?? []);
       const projected = new Set<string>((existing.tags ?? []).filter((t) => !removed.has(t)));
@@ -489,7 +493,7 @@ function applyTagScopeWrappers(
     if (id) {
       const existing = await store.getNote(id as string);
       if (!existing || !noteWithinTagScope(existing, allowed, rawTags)) {
-        return { error: "Note not found", id };
+        return { error: "Note not found", error_type: "not_found", id };
       }
     }
     return await orig(params);
@@ -502,7 +506,37 @@ function applyTagScopeWrappers(
     if (typeof tag === "string" && !allowed.has(tag)) {
       return forbidden(`update-tag: tag "${tag}" is outside the token's allowlist`);
     }
-    return await orig(params);
+    try {
+      return await orig(params);
+    } catch (err: any) {
+      // Tag-scope scrub for cross-tag field conflicts (vault#554
+      // auth-and-scope fold). Core's validation scans EVERY tag's schema
+      // (scope-unaware by architecture), so its TagFieldConflictError can
+      // name an OUT-OF-SCOPE tag and reveal its declared type/flag in both
+      // the violation entries and the error message. The write stays
+      // rejected — schema integrity is scope-independent — but re-throw
+      // with scrubbed violations (out-of-scope declarers generalized, no
+      // tag name / declared type, `other_tag` dropped; in-scope declarers
+      // keep full detail). Rebuilding via the constructor also rebuilds
+      // the top-level message from the scrubbed entries. Same pattern as
+      // the list-tags `did_you_mean` scrub above.
+      if (err && err.code === "TAG_FIELD_CONFLICT" && Array.isArray(err.violations)) {
+        throw new TagFieldConflictError(
+          err.tag ?? (tag as string),
+          scrubTagFieldViolationsByScope(err.violations, allowed),
+        );
+      }
+      // Same leak through the OTHER door (wire-review interaction): a
+      // both-indexed cross-tag type conflict deliberately bypasses the
+      // pre-check (preserving its declareField → invalid_indexed_field
+      // contract), and declareField's IndexedFieldError message names the
+      // other declarer tag(s). Generalize for scoped callers; solo
+      // own-field IndexedFieldErrors (no declarer_tags) pass untouched.
+      if (err instanceof IndexedFieldError) {
+        throw scrubIndexedFieldConflictError(err, allowed);
+      }
+      throw err;
+    }
   });
 
   wrapReadTool(tools, "delete-tag", async (orig, params) => {
@@ -542,6 +576,16 @@ function overrideVaultInfo(
   if (!vaultInfo) return;
 
   vaultInfo.execute = async (params) => {
+    // NOTE (vault#554): these two throws are deliberately left as plain,
+    // unstructured `Error`s — NOT given `error_type` — even though the rest
+    // of this file's sweep attaches one everywhere else. Attaching one here
+    // routes the throw through mcp-http.ts's structured-error mapping, which
+    // surfaces it as a JSON-RPC protocol-level error (`response.error`)
+    // instead of the in-band tool result the existing contract test asserts
+    // (`response.result.isError === true`, `response.result.content[0].text`
+    // containing the scope name) — see "tools/call of vault-info with
+    // description arg and vault:read scope is refused" in src/vault.test.ts.
+    // Changing that transport shape is out of scope for this wave.
     const config = readVaultConfig(vaultName);
     if (!config) throw new Error(`Vault "${vaultName}" not found`);