@openparachute/vault 0.6.4-rc.1 → 0.6.4-rc.3

package/src/routes.ts

@@ -21,7 +21,9 @@ import {
   contentRangeRequiresContent,
   type ContentRange,
 } from "../core/src/content-range.ts";
-import { attachValidationStatus } from "../core/src/mcp.ts";
+import { attachValidationStatus, enforceStrictWrite } from "../core/src/mcp.ts";
+import type { ValidationWarning } from "../core/src/schema-defaults.ts";
+import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import {
@@ -44,6 +46,52 @@ import { findTokensReferencingTag } from "./token-store.ts";
 export type TagScopeCtx = { allowed: Set<string> | null; raw: string[] | null };
 
 const NO_TAG_SCOPE: TagScopeCtx = { allowed: null, raw: null };
+
+/**
+ * Write-attribution context (vault#298) for REST writes — the principal
+ * (`actor`) and interface (`via`) threaded from the authenticated request into
+ * `store.createNote` / `store.updateNote`. Both null for paths without an auth
+ * context (the no-op default). See `WriteContext` in core/src/notes.ts.
+ */
+export type WriteCtx = {
+  actor: string | null;
+  via: string | null;
+  /**
+   * Migration-bypass (vault#299). True when the caller holds `vault:migrate`
+   * — strict-schema enforcement is skipped and the bypass is logged. Defaults
+   * to false (full enforcement) for every normal write.
+   */
+  bypassStrict?: boolean;
+};
+
+const NO_WRITE_CTX: WriteCtx = { actor: null, via: null };
+
+/**
+ * Run the shared strict-schema gate for a REST write (vault#299). Mirrors the
+ * MCP path's `enforceStrict` closure: enforce unless the caller holds the
+ * migration-bypass scope, and log every bypassed write to the daemon's
+ * structured log (the audit-log table, #300, is deferred). Throws
+ * `SchemaValidationError` (caught by the route's catch → 422) when not bypassed.
+ */
+function gateStrictWrite(
+  store: Store,
+  writeCtx: WriteCtx,
+  shape: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
+): void {
+  enforceStrictWrite(store, shape, {
+    bypass: writeCtx.bypassStrict === true,
+    onBypass: (violations: ValidationWarning[]) => {
+      logStrictBypass({
+        actor: writeCtx.actor,
+        via: writeCtx.via,
+        path: shape.path ?? null,
+        tags: shape.tags,
+        violations,
+      });
+    },
+  });
+}
+
 import {
   expandContent,
   DEFAULT_EXPAND_DEPTH,
@@ -567,6 +615,13 @@ export function parseNotesQueryOpts(url: URL): {
     pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
     extension: parseExtensionFilter(url),
     metadata: bracket.metadata ?? metadataAlias.metadata,
+    // Write-attribution filters (vault#298) — symmetric with the MCP
+    // query-notes tool so a REST caller can ask "what did Mathilda write" /
+    // "what came in via the meeting-ingest surface" the same way.
+    createdBy: parseQuery(url, "created_by") ?? undefined,
+    lastUpdatedBy: parseQuery(url, "last_updated_by") ?? undefined,
+    createdVia: parseQuery(url, "created_via") ?? undefined,
+    lastUpdatedVia: parseQuery(url, "last_updated_via") ?? undefined,
     ...(bracket.dateFilter
       ? { dateFilter: bracket.dateFilter }
       : parseQuery(url, "date_field")
@@ -704,9 +759,10 @@ export async function handleNotes(
   subpath: string,
   vault?: string,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+  writeCtx: WriteCtx = NO_WRITE_CTX,
 ): Promise<Response> {
   try {
-    return await handleNotesInner(req, store, subpath, vault, tagScope);
+    return await handleNotesInner(req, store, subpath, vault, tagScope, writeCtx);
   } catch (e: any) {
     const ambig = ambiguousPathResponse(e);
     if (ambig) return ambig;
@@ -720,6 +776,7 @@ async function handleNotesInner(
   subpath: string,
   vault?: string,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+  writeCtx: WriteCtx = NO_WRITE_CTX,
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
@@ -1102,6 +1159,13 @@ async function handleNotesInner(
           const extension = item.extension !== undefined
             ? validateExtension(item.extension)
             : undefined;
+          // Strict-schema gate (vault#299) — reject before any write so a
+          // mid-batch violation rolls back via the outer BEGIN/ROLLBACK.
+          gateStrictWrite(store, writeCtx, {
+            path: item.path,
+            tags: item.tags,
+            metadata: item.metadata,
+          });
           const note = await store.createNote(item.content ?? "", {
             id: item.id,
             path: item.path,
@@ -1109,6 +1173,9 @@ async function handleNotesInner(
             metadata: item.metadata,
             created_at: item.createdAt ?? item.created_at,
             ...(extension !== undefined ? { extension } : {}),
+            // Write-attribution (vault#298) — REST batch create.
+            actor: writeCtx.actor,
+            via: writeCtx.via,
           });
 
           // Create explicit links
@@ -1131,6 +1198,13 @@ async function handleNotesInner(
             409,
           );
         }
+        // Strict-schema rejection (vault#299 Part A) on create — 422.
+        if (e && e.code === "SCHEMA_VALIDATION") {
+          return json(
+            { error_type: "schema_validation", error: "schema_validation", violations: e.violations ?? [], message: e.message },
+            422,
+          );
+        }
         if (e && e.code === "INVALID_EXTENSION") {
           return json(
             { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
@@ -1383,8 +1457,17 @@ async function handleNotesInner(
             ...(body.created_at !== undefined ? { created_at: body.created_at as string } : {}),
             ...(body.createdAt !== undefined ? { created_at: body.createdAt as string } : {}),
             ...(createExt !== undefined ? { extension: createExt } : {}),
+            // Write-attribution (vault#298) — REST upsert-create branch.
+            actor: writeCtx.actor,
+            via: writeCtx.via,
           };
           const content = (body.content as string | undefined) ?? "";
+          // Strict-schema gate (vault#299) — if_missing:"create" is a create.
+          gateStrictWrite(store, writeCtx, {
+            path: createOpts.path ?? undefined,
+            tags: createOpts.tags,
+            metadata: createOpts.metadata,
+          });
           const created = await store.createNote(content, createOpts);
           if (tagsArr.length > 0) {
             await applySchemaDefaults(store, db, [created.id], tagsArr);
@@ -1474,7 +1557,19 @@ async function handleNotesInner(
         && body.createdAt === undefined
         && body.tags === undefined
         && body.links === undefined;
-      if (!isAppendOnly && body.if_updated_at === undefined && body.force !== true) {
+      // A state_transition is itself a compare-and-set precondition (vault#299
+      // Part B) — a transition-only PATCH needs no if_updated_at/force.
+      const isTransitionOnly = body.state_transition !== undefined
+        && !hasContent
+        && !hasAppendPrepend
+        && !hasContentEdit
+        && body.path === undefined
+        && body.metadata === undefined
+        && body.created_at === undefined
+        && body.createdAt === undefined
+        && body.tags === undefined
+        && body.links === undefined;
+      if (!isAppendOnly && !isTransitionOnly && body.if_updated_at === undefined && body.force !== true) {
         return json(
           {
             error_type: "precondition_required",
@@ -1566,8 +1661,39 @@ async function handleNotesInner(
       if (body.if_updated_at !== undefined) {
         updates.if_updated_at = body.if_updated_at;
       }
+      // Compare-and-set state transition (vault#299 Part B). Combinable with
+      // other field updates; folds into the same atomic UPDATE.
+      const stBody = body.state_transition as { field?: unknown; from?: unknown; to?: unknown } | undefined;
+      if (stBody !== undefined) {
+        if (typeof stBody.field !== "string" || stBody.field.length === 0) {
+          return json(
+            { error: "bad_request", message: "`state_transition.field` must be a non-empty string." },
+            400,
+          );
+        }
+        updates.state_transition = { field: stBody.field, from: stBody.from, to: stBody.to };
+      }
+
+      // --- Strict-schema gate (vault#299 Part A) ---
+      // Validate the PROSPECTIVE shape (final tags + merged metadata, incl. a
+      // state_transition's `to`) before the write so a rejection leaves the
+      // note untouched. Throws SchemaValidationError → 422 in the catch.
+      {
+        const removeSet = new Set<string>((body.tags?.remove as string[] | undefined) ?? []);
+        const projectedTags = new Set<string>((note.tags ?? []).filter((t) => !removeSet.has(t)));
+        for (const t of (body.tags?.add as string[] | undefined) ?? []) projectedTags.add(t);
+        const baseMeta = updates.metadata ?? ((note.metadata as Record<string, unknown>) ?? {});
+        const projectedMeta = stBody !== undefined
+          ? { ...baseMeta, [stBody.field as string]: stBody.to }
+          : baseMeta;
+        gateStrictWrite(store, writeCtx, { path: note.path, tags: [...projectedTags], metadata: projectedMeta });
+      }
 
       if (Object.keys(updates).length > 0) {
+        // Write-attribution (vault#298) — REST update. Stamp the most-recent-
+        // write columns on the same UPDATE that bumps updated_at.
+        updates.actor = writeCtx.actor;
+        updates.via = writeCtx.via;
         await store.updateNote(note.id, updates);
       }
 
@@ -1661,6 +1787,39 @@ async function handleNotesInner(
           409,
         );
       }
+      // State-transition compare-and-set conflict (vault#299 Part B). A
+      // DISTINCT error vocabulary from `conflict` (settled lead #3): the
+      // field VALUE didn't match `from`, not the updated_at token. 409.
+      if (e && e.code === "TRANSITION_CONFLICT") {
+        return json(
+          {
+            error_type: "transition_conflict",
+            error: "transition_conflict",
+            note_id: e.note_id,
+            path: e.note_path ?? null,
+            field: e.field,
+            expected_from: e.expected_from,
+            to: e.to,
+            current: e.current ?? null,
+            message: e.message,
+          },
+          409,
+        );
+      }
+      // Strict-schema rejection (vault#299 Part A). One error carrying ALL
+      // per-field violations (settled lead #1). 422 Unprocessable Entity —
+      // the note exists / request is well-formed but violates the contract.
+      if (e && e.code === "SCHEMA_VALIDATION") {
+        return json(
+          {
+            error_type: "schema_validation",
+            error: "schema_validation",
+            violations: e.violations ?? [],
+            message: e.message,
+          },
+          422,
+        );
+      }
       // Path-rename collision — schema's UNIQUE(path) tripped. Issue #126.
       if (e && e.code === "PATH_CONFLICT") {
         return json(

package/src/routing.ts

@@ -52,7 +52,7 @@ import {
   authenticateGlobalRequest,
   extractApiKey,
 } from "./auth.ts";
-import { hasScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
+import { hasScopeForVault, hasMigrateScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { handleScopedMcp } from "./mcp-http.ts";
 import {
@@ -71,6 +71,7 @@ import {
   handleStorage,
   handleViewNote,
   type TagScopeCtx,
+  type WriteCtx,
 } from "./routes.ts";
 import { handleSubscribe } from "./subscribe.ts";
 import { handleTriggers } from "./triggers-api.ts";
@@ -812,7 +813,22 @@ export async function route(
     raw: auth.scoped_tags,
   };
 
-  if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope);
+  // Write-attribution context (vault#298). `auth.actor` is the principal;
+  // `auth.via` is the credential class (`api` for hub JWTs + legacy keys,
+  // `operator` for the env-var bearer). The REST surface IS the `api` channel,
+  // so no refinement is needed here — the base via stands (the MCP handler is
+  // the one that refines to `mcp`). Threaded only into the write handler.
+  // Migration-bypass (vault#299): a `vault:migrate`-scoped caller may write
+  // notes that violate `strict:true` field constraints (for backfill /
+  // migration). Every bypassed write is logged. Orthogonal to read/write/admin
+  // — an admin token does NOT bypass unless it also holds `migrate`.
+  const writeCtx: WriteCtx = {
+    actor: auth.actor,
+    via: auth.via,
+    bypassStrict: hasMigrateScopeForVault(auth.scopes, vaultName),
+  };
+
+  if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope, writeCtx);
   // Live-query SSE subscription (design 2026-06-08). Snapshot + scoped live
   // upsert/remove events over text/event-stream. Auth + tag-scope already
   // resolved above and threaded through, mirroring the /notes branch.

package/src/scopes.test.ts

@@ -9,10 +9,12 @@ import {
   SCOPE_READ,
   SCOPE_WRITE,
   SCOPE_ADMIN,
+  SCOPE_MIGRATE,
   parseScopes,
   parseScopeFlags,
   hasScope,
   hasScopeForVault,
+  hasMigrateScopeForVault,
   findBroadVaultScopes,
   scopeForMethod,
   verbForMethod,
@@ -20,6 +22,28 @@ import {
   serializeScopes,
 } from "./scopes.ts";
 
+describe("hasMigrateScopeForVault — migration-bypass capability (vault#299)", () => {
+  test("broad vault:migrate satisfies any vault", () => {
+    expect(hasMigrateScopeForVault([SCOPE_MIGRATE], "default")).toBe(true);
+    expect(hasMigrateScopeForVault([SCOPE_MIGRATE], "anything")).toBe(true);
+  });
+
+  test("narrowed vault:<name>:migrate satisfies only that vault", () => {
+    expect(hasMigrateScopeForVault(["vault:gitcoin:migrate"], "gitcoin")).toBe(true);
+    expect(hasMigrateScopeForVault(["vault:gitcoin:migrate"], "default")).toBe(false);
+  });
+
+  test("admin does NOT imply migrate — orthogonal axis", () => {
+    expect(hasMigrateScopeForVault([SCOPE_ADMIN], "default")).toBe(false);
+    expect(hasMigrateScopeForVault(["vault:default:admin"], "default")).toBe(false);
+  });
+
+  test("no migrate scope → false", () => {
+    expect(hasMigrateScopeForVault([SCOPE_WRITE, SCOPE_READ], "default")).toBe(false);
+    expect(hasMigrateScopeForVault([], "default")).toBe(false);
+  });
+});
+
 describe("parseScopes", () => {
   test("returns [] for null or empty input", () => {
     expect(parseScopes(null)).toEqual([]);

package/src/scopes.ts

@@ -28,6 +28,19 @@ export const SCOPE_READ = "vault:read" as const;
 export const SCOPE_WRITE = "vault:write" as const;
 export const SCOPE_ADMIN = "vault:admin" as const;
 
+/**
+ * Migration-bypass scope (vault#299). A SEPARATE capability axis — NOT part
+ * of the read ⊇ write ⊇ admin inheritance chain. A token holding
+ * `vault:migrate` (broad) or `vault:<name>:migrate` (narrowed) may skip
+ * `strict:true` schema enforcement so existing non-conforming notes can be
+ * migrated/backfilled. It is deliberately orthogonal: an `admin` token does
+ * NOT auto-bypass strict validation — bypass must be an explicit, audited
+ * grant. A bypass write still needs `write` to actually mutate (migrate is an
+ * ADD-ON flag, not a write grant on its own). Every bypassed write is logged
+ * (see the write path) since #300 (the audit-log table) is deferred.
+ */
+export const SCOPE_MIGRATE = "vault:migrate" as const;
+
 /** All first-class vault scopes in inheritance order (lowest → highest). */
 export const VAULT_SCOPES = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN] as const;
 export type VaultScope = (typeof VAULT_SCOPES)[number];
@@ -137,6 +150,56 @@ export function hasScopeForVault(
   return false;
 }
 
+/**
+ * Migration-bypass check (vault#299): does `granted` hold the `migrate`
+ * capability for `vaultName`? Accepts broad `vault:migrate` (any vault) or
+ * narrowed `vault:<name>:migrate` (this vault only). Orthogonal to the
+ * read/write/admin verbs — a plain admin token returns `false` here, by
+ * design. The migrate scope does NOT live in `decomposeVaultScope` (it isn't a
+ * read/write/admin verb), so it's matched by exact shape here.
+ */
+export function hasMigrateScopeForVault(granted: string[], vaultName: string): boolean {
+  for (const s of granted) {
+    if (s === SCOPE_MIGRATE) return true; // broad — any vault
+    if (s === `vault:${vaultName}:migrate`) return true; // narrowed — this vault
+  }
+  return false;
+}
+
+/**
+ * Structured log line for a migration-bypassed write (vault#299 settled lead
+ * #2). Records WHO bypassed (actor/via from MW1 attribution), WHAT note, and
+ * WHICH strict violations were waived — enough to reconstruct the bypass for
+ * later audit without the #300 audit-log table (deferred). One JSON line so
+ * it's grep/jq-able in the daemon log. Lives here (next to the migrate-scope
+ * check) so both write transports — REST (routes.ts) and MCP (mcp-tools.ts) —
+ * emit the identical line without importing each other.
+ */
+export function logStrictBypass(info: {
+  actor: string | null;
+  via: string | null;
+  path?: string | null;
+  tags?: string[];
+  violations: { field: string; reason: string; schema: string }[];
+}): void {
+  console.warn(
+    "[schema-bypass] " +
+      JSON.stringify({
+        event: "strict_schema_bypass",
+        actor: info.actor,
+        via: info.via,
+        path: info.path ?? null,
+        tags: info.tags ?? [],
+        violations: info.violations.map((v) => ({
+          field: v.field,
+          reason: v.reason,
+          schema: v.schema,
+        })),
+        at: new Date().toISOString(),
+      }),
+  );
+}
+
 /**
  * Pick the required scope for a given API request.
  *   - GET/HEAD/OPTIONS → read

package/src/triggers-api.ts

@@ -30,6 +30,7 @@ import {
   type TriggerInput,
 } from "../core/src/triggers-store.ts";
 import { registerVaultTrigger } from "./triggers.ts";
+import { SUPPORTED_OPS } from "../core/src/query-operators.ts";
 import { hasScopeForVault, SCOPE_ADMIN } from "./scopes.ts";
 import type { AuthResult } from "./auth.ts";
 
@@ -135,6 +136,29 @@ function validateInput(body: unknown):
   if (typeof b.when !== "object" || b.when === null || Array.isArray(b.when)) {
     return { ok: false, message: "`when` is required and must be an object" };
   }
+  // Value-matched metadata predicate (vault#299 Part B): when present, each
+  // field must map to an operator-object whose keys are all supported
+  // operators. Fail at registration so a typo'd operator (`{ state: { equals:
+  // ... } }`) is a 400, not a silently-never-firing trigger.
+  const whenMeta = (b.when as Record<string, unknown>).metadata;
+  if (whenMeta !== undefined) {
+    if (typeof whenMeta !== "object" || whenMeta === null || Array.isArray(whenMeta)) {
+      return { ok: false, message: "`when.metadata` must be an object mapping field → operator-object" };
+    }
+    for (const [field, opObj] of Object.entries(whenMeta as Record<string, unknown>)) {
+      if (typeof opObj !== "object" || opObj === null || Array.isArray(opObj)) {
+        return { ok: false, message: `\`when.metadata.${field}\` must be an operator-object, e.g. { eq: "published" }` };
+      }
+      for (const op of Object.keys(opObj as Record<string, unknown>)) {
+        if (!SUPPORTED_OPS.includes(op as (typeof SUPPORTED_OPS)[number])) {
+          return {
+            ok: false,
+            message: `\`when.metadata.${field}\` has unknown operator "${op}". Supported: ${SUPPORTED_OPS.join(", ")}.`,
+          };
+        }
+      }
+    }
+  }
 
   if (typeof b.action !== "object" || b.action === null || Array.isArray(b.action)) {
     return { ok: false, message: "`action` is required and must be an object" };

package/src/triggers.test.ts

@@ -95,6 +95,39 @@ describe("buildPredicate", () => {
     expect(pred(makeNote({ tags: ["reader"] }))).toBe(false);
     expect(pred(makeNote({ tags: ["reader", "important"] }))).toBe(true);
   });
+
+  // Value-matched metadata grammar (vault#299 Part B).
+  it("metadata eq: fires only when the field equals the value", () => {
+    const pred = buildPredicate({ metadata: { state: { eq: "published" } } }, "publish_hook");
+    expect(pred(makeNote({ metadata: { state: "published" } }))).toBe(true);
+    expect(pred(makeNote({ metadata: { state: "drafted" } }))).toBe(false);
+    expect(pred(makeNote({ metadata: {} }))).toBe(false); // absent → no fire
+  });
+
+  it("metadata in: fires on membership", () => {
+    const pred = buildPredicate({ metadata: { state: { in: ["produced", "published"] } } }, "h");
+    expect(pred(makeNote({ metadata: { state: "produced" } }))).toBe(true);
+    expect(pred(makeNote({ metadata: { state: "idea" } }))).toBe(false);
+  });
+
+  it("metadata combines with tag + presence filters (all must hold)", () => {
+    const pred = buildPredicate(
+      { tags: ["piece"], metadata: { state: { eq: "published" } }, missing_metadata: ["notified_at"] },
+      "h",
+    );
+    expect(pred(makeNote({ tags: ["piece"], metadata: { state: "published" } }))).toBe(true);
+    // right state, wrong tag.
+    expect(pred(makeNote({ tags: ["other"], metadata: { state: "published" } }))).toBe(false);
+    // right tag + state but already notified.
+    expect(
+      pred(makeNote({ tags: ["piece"], metadata: { state: "published", notified_at: "x" } })),
+    ).toBe(false);
+  });
+
+  it("a malformed operator never throws from the predicate (treated as no-match)", () => {
+    const pred = buildPredicate({ metadata: { state: { bogus: "x" } as any } }, "h");
+    expect(pred(makeNote({ metadata: { state: "published" } }))).toBe(false);
+  });
 });
 
 describe("registerTriggers — dispatch modes", async () => {

package/src/triggers.ts

@@ -30,6 +30,7 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
 import crypto from "node:crypto";
 import type { Note, Store, Attachment } from "../core/src/types.ts";
 import type { HookRegistry, HookEvent, NoteHookPayload } from "../core/src/hooks.ts";
+import { matchesOperator } from "../core/src/query-operators.ts";
 import type { TriggerConfig, TriggerWhen } from "./config.ts";
 import type { StoredTrigger } from "../core/src/triggers-store.ts";
 import { getVaultNameForStore } from "./vault-store.ts";
@@ -106,6 +107,22 @@ export function buildPredicate(when: TriggerWhen, triggerName: string): (note: N
       }
     }
 
+    // Value-matched metadata filter (vault#299 Part B). Each field's
+    // operator-object is evaluated against the note's live metadata with the
+    // SAME engine query-notes uses. ALL fields must match (AND). A malformed
+    // operator throws at registration-time validation, not here — by the time
+    // the predicate runs the shape is known-good, but we guard defensively so
+    // a bad config can never crash the hook dispatch loop (treat as no-match).
+    if (when.metadata) {
+      for (const [field, opObj] of Object.entries(when.metadata)) {
+        try {
+          if (!matchesOperator(field, meta?.[field], opObj)) return false;
+        } catch {
+          return false;
+        }
+      }
+    }
+
     return true;
   };
 }