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

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;
   };
 }