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

package/src/attribution-threading.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Write-attribution threading (vault#298) — the server-side half: how the
+ * authenticated request resolves the two provenance axes onto `AuthResult`,
+ * and how the MCP layer refines the `via` channel.
+ *
+ *   - WHO  (`actor`): JWT `sub` on the hub path; `operator` for the env-var
+ *     bearer; `token:<id>` for legacy YAML keys.
+ *   - VIA  (`via`):  `api` (credential class) on the REST path; `operator` for
+ *     the env-var bearer; refined to `mcp` by the MCP handler.
+ *
+ * The store-layer column behavior + query filters live in
+ * core/src/attribution.test.ts. This file pins the AUTH → AuthResult mapping
+ * and the MCP via-refinement end-to-end (an MCP create lands attribution in
+ * the row).
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { generateKeyPair, exportJWK, SignJWT } from "jose";
+import {
+  writeVaultConfig,
+  writeGlobalConfig,
+  readVaultConfig,
+  readGlobalConfig,
+  generateApiKey,
+  hashKey,
+} from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { authenticateVaultRequest } from "./auth.ts";
+import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { parseNotesQueryOpts } from "./routes.ts";
+import type { AuthResult } from "./auth.ts";
+
+// ---------------------------------------------------------------------------
+// Hub-JWT fixture (mirrors auth-hub-jwt.test.ts)
+// ---------------------------------------------------------------------------
+interface Keypair {
+  privateKey: CryptoKey;
+  publicJwk: { kty: string; n: string; e: string; kid: string; alg: string; use: string };
+  kid: string;
+}
+async function makeKeypair(kid: string): Promise<Keypair> {
+  const { privateKey, publicKey } = await generateKeyPair("RS256", { extractable: true });
+  const jwk = await exportJWK(publicKey);
+  return {
+    privateKey,
+    publicJwk: { kty: "RSA", n: jwk.n!, e: jwk.e!, kid, alg: "RS256", use: "sig" },
+    kid,
+  };
+}
+function startHubFixture(keys: Keypair[]): { origin: string; stop: () => void } {
+  const server = Bun.serve({
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/.well-known/jwks.json") {
+        return Response.json({ keys: keys.map((k) => k.publicJwk) });
+      }
+      if (url.pathname === "/.well-known/parachute-revocation.json") {
+        return Response.json({ generated_at: new Date().toISOString(), jtis: [] });
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+  return { origin: `http://127.0.0.1:${server.port}`, stop: () => server.stop(true) };
+}
+async function signJwt(
+  kp: Keypair,
+  opts: { iss: string; aud: string; scope: string; sub?: string },
+): Promise<string> {
+  const iat = Math.floor(Date.now() / 1000);
+  return await new SignJWT({ scope: opts.scope, client_id: "test-client" })
+    .setProtectedHeader({ alg: "RS256", kid: kp.kid })
+    .setIssuer(opts.iss)
+    .setSubject(opts.sub ?? "user-1")
+    .setAudience(opts.aud)
+    .setIssuedAt(iat)
+    .setExpirationTime(iat + 60)
+    .setJti(`jti-${Math.random().toString(36).slice(2)}`)
+    .sign(kp.privateKey);
+}
+function bearer(token: string): Request {
+  return new Request("https://vault.test/x", { headers: { Authorization: `Bearer ${token}` } });
+}
+
+let tmpHome: string;
+let prevHome: string | undefined;
+let prevHubOrigin: string | undefined;
+let prevJwksOrigin: string | undefined;
+let prevAuthToken: string | undefined;
+let fixture: { origin: string; stop: () => void };
+let kp: Keypair;
+
+beforeEach(async () => {
+  tmpHome = join(tmpdir(), `vault-attr-thread-${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();
+
+  kp = await makeKeypair("k1");
+  fixture = startHubFixture([kp]);
+  prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  prevJwksOrigin = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  prevAuthToken = process.env.VAULT_AUTH_TOKEN;
+  process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = fixture.origin;
+  delete process.env.VAULT_AUTH_TOKEN;
+  resetJwksCache();
+  resetRevocationCache();
+});
+
+afterEach(() => {
+  fixture.stop();
+  clearVaultStoreCache();
+  const restore = (k: string, v: string | undefined) => {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  };
+  restore("PARACHUTE_HOME", prevHome);
+  restore("PARACHUTE_HUB_ORIGIN", prevHubOrigin);
+  restore("PARACHUTE_HUB_JWKS_ORIGIN", prevJwksOrigin);
+  restore("VAULT_AUTH_TOKEN", prevAuthToken);
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVaultWithKey(name: string): string {
+  const { fullKey, keyId } = generateApiKey();
+  writeVaultConfig({
+    name,
+    api_keys: [
+      {
+        id: keyId,
+        label: "bootstrap",
+        scope: "write",
+        key_hash: hashKey(fullKey),
+        created_at: new Date().toISOString(),
+      },
+    ],
+    created_at: new Date().toISOString(),
+  });
+  getVaultStore(name);
+  return fullKey;
+}
+
+function seedVaultNoKey(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+describe("attribution threading — AuthResult actor/via derivation", () => {
+  test("hub JWT → actor = sub, via = 'api' (the REST credential class)", async () => {
+    seedVaultNoKey("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      sub: "mathilda",
+    });
+    const result = await authenticateVaultRequest(bearer(token), readVaultConfig("journal")!);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.actor).toBe("mathilda");
+      expect(result.via).toBe("api");
+    }
+  });
+
+  test("VAULT_AUTH_TOKEN operator bearer → actor = via = 'operator'", async () => {
+    seedVaultNoKey("journal");
+    process.env.VAULT_AUTH_TOKEN = "super-secret-operator-bearer";
+    const result = await authenticateVaultRequest(
+      bearer("super-secret-operator-bearer"),
+      readVaultConfig("journal")!,
+    );
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.actor).toBe("operator");
+      expect(result.via).toBe("operator");
+    }
+  });
+
+  test("legacy YAML api_key → actor = 'token:<id>', via = 'api' (never crashes)", async () => {
+    const fullKey = seedVaultWithKey("journal");
+    const result = await authenticateVaultRequest(bearer(fullKey), readVaultConfig("journal")!);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.actor).toMatch(/^token:[0-9a-f]{1,}$/i);
+      expect(result.via).toBe("api");
+      expect(result.legacyDerived).toBe(true);
+    }
+  });
+});
+
+describe("attribution threading — MCP refines via to 'mcp' and stamps the write", () => {
+  function authFor(sub: string, vaultName: string): AuthResult {
+    return {
+      permission: "full",
+      scopes: [`vault:${vaultName}:write`, `vault:${vaultName}:read`],
+      legacyDerived: false,
+      scoped_tags: null,
+      vault_name: null,
+      caller_jti: null,
+      actor: sub,
+      via: "api", // base class from auth; the MCP layer should refine to "mcp"
+    };
+  }
+
+  test("a create-note through the MCP tools lands actor=sub + via='mcp'", async () => {
+    seedVaultNoKey("journal");
+    const auth = authFor("aaron", "journal");
+    const tools = generateScopedMcpTools("journal", auth, null);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const created = (await create.execute({ content: "via mcp" })) as {
+      id: string;
+      createdBy?: string | null;
+      createdVia?: string | null;
+      lastUpdatedVia?: string | null;
+    };
+    expect(created.createdBy).toBe("aaron");
+    expect(created.createdVia).toBe("mcp");
+    expect(created.lastUpdatedVia).toBe("mcp");
+
+    // Confirm it persisted to the row, not just the response shape.
+    const store = getVaultStore("journal");
+    const row = store.db
+      .prepare("SELECT created_by, created_via FROM notes WHERE id = ?")
+      .get(created.id) as { created_by: string | null; created_via: string | null };
+    expect(row.created_by).toBe("aaron");
+    expect(row.created_via).toBe("mcp");
+  });
+
+  test("an update-note through the MCP tools bumps last_updated_via='mcp'", async () => {
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+    const seed = await store.createNote("seed", { actor: "aaron", via: "api" });
+
+    const auth = authFor("aaron", "journal");
+    const tools = generateScopedMcpTools("journal", auth, null);
+    const update = tools.find((t) => t.name === "update-note")!;
+    // `force: true` waives the optimistic-concurrency precondition (we don't
+    // echo updated_at in this focused test).
+    await update.execute({ id: seed.id, content: "edited via mcp", force: true });
+
+    const after = await store.getNote(seed.id);
+    expect(after?.createdVia).toBe("api"); // set-once original channel
+    expect(after?.lastUpdatedBy).toBe("aaron");
+    expect(after?.lastUpdatedVia).toBe("mcp"); // refined channel of the latest edit
+  });
+
+  test("update-note with if_missing:'create' on a MISSING note attributes the created row", async () => {
+    // Regression: the upsert-create branch built createOpts without actor/via,
+    // so an MCP-driven upsert that CREATES a note wrote NULL attribution while
+    // create-note + REST upsert-create did it right. (vault#298 review.)
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+
+    const tools = generateScopedMcpTools("journal", authFor("aaron", "journal"), null);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const created = (await update.execute({
+      id: "Projects/Brand New",
+      content: "born via upsert",
+      if_missing: "create",
+    })) as { id: string; createdBy?: string | null; createdVia?: string | null };
+
+    // The note did not exist → this is a create; attribution must be set.
+    expect(created.createdBy).toBe("aaron");
+    expect(created.createdVia).toBe("mcp"); // refined channel, not NULL
+
+    // Confirm it persisted to the row, not just the echoed shape.
+    const row = store.db
+      .prepare(
+        "SELECT created_by, created_via, last_updated_by, last_updated_via FROM notes WHERE id = ?",
+      )
+      .get(created.id) as {
+      created_by: string | null;
+      created_via: string | null;
+      last_updated_by: string | null;
+      last_updated_via: string | null;
+    };
+    expect(row.created_by).toBe("aaron");
+    expect(row.created_via).toBe("mcp");
+    // First write IS the latest write — the last_updated_* pair mirrors it.
+    expect(row.last_updated_by).toBe("aaron");
+    expect(row.last_updated_via).toBe("mcp");
+  });
+
+  test("the operator bearer keeps via='operator' even on the MCP channel", async () => {
+    seedVaultNoKey("journal");
+    const auth: AuthResult = {
+      permission: "full",
+      scopes: ["vault:admin", "vault:write", "vault:read"],
+      legacyDerived: false,
+      scoped_tags: null,
+      vault_name: null,
+      caller_jti: null,
+      actor: "operator",
+      via: "operator",
+    };
+    const tools = generateScopedMcpTools("journal", auth, null);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const created = (await create.execute({ content: "op write" })) as {
+      createdVia?: string | null;
+    };
+    expect(created.createdVia).toBe("operator");
+  });
+
+  test("content_edit (surgical find-and-replace) also attributes the latest edit", async () => {
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+    const seed = await store.createNote("hello WORLD", { actor: "aaron", via: "api" });
+
+    const tools = generateScopedMcpTools("journal", authFor("mathilda", "journal"), null);
+    const update = tools.find((t) => t.name === "update-note")!;
+    await update.execute({
+      id: seed.id,
+      content_edit: { old_text: "WORLD", new_text: "there" },
+      force: true,
+    });
+
+    const after = await store.getNote(seed.id);
+    expect(after?.content).toBe("hello there");
+    expect(after?.createdBy).toBe("aaron"); // set-once
+    expect(after?.lastUpdatedBy).toBe("mathilda"); // content_edit flows through updateNote
+    expect(after?.lastUpdatedVia).toBe("mcp");
+  });
+});
+
+describe("attribution threading — REST query filters (symmetric with MCP)", () => {
+  test("parseNotesQueryOpts wires the four attribution filter params", () => {
+    const url = new URL(
+      "http://localhost:1940/vault/journal/api/notes" +
+        "?created_by=aaron&last_updated_by=agent:nightly" +
+        "&created_via=surface:meeting-ingest&last_updated_via=mcp",
+    );
+    const { queryOpts } = parseNotesQueryOpts(url);
+    expect(queryOpts?.createdBy).toBe("aaron");
+    expect(queryOpts?.lastUpdatedBy).toBe("agent:nightly");
+    expect(queryOpts?.createdVia).toBe("surface:meeting-ingest");
+    expect(queryOpts?.lastUpdatedVia).toBe("mcp");
+  });
+
+  test("absent attribution params leave the filters undefined (no spurious filtering)", () => {
+    const url = new URL("http://localhost:1940/vault/journal/api/notes?tag=daily");
+    const { queryOpts } = parseNotesQueryOpts(url);
+    expect(queryOpts?.createdBy).toBeUndefined();
+    expect(queryOpts?.lastUpdatedVia).toBeUndefined();
+  });
+});

package/src/auth.ts

@@ -100,6 +100,11 @@ function tryServerWideAuth(
     // would see no other operator mints; that's fine — env-var-bearer is
     // explicitly the operator-channel, not a user surface).
     caller_jti: null,
+    // Write-attribution (vault#298): the env-var bearer IS the operator
+    // channel. `actor: "operator"` + `via: "operator"` — a stable, honest
+    // label for cross-container hub→vault and CLI operator writes.
+    actor: "operator",
+    via: "operator",
   };
 }
 
@@ -137,14 +142,52 @@ export interface AuthResult {
    * mints. See vault#376.
    */
   caller_jti: string | null;
+  /**
+   * Write-attribution axis 1 — WHO (vault#298). The principal a write is
+   * attributed to:
+   *   - Hub JWT  → the validated `sub` claim (the human or the identity an
+   *     agent runs as).
+   *   - VAULT_AUTH_TOKEN operator bearer → `"operator"`.
+   *   - Legacy YAML api_keys → `"token:<keyhash-prefix>"` so legacy writes
+   *     still attribute to *something* stable, never crash.
+   * NULL only when no principal could be resolved (shouldn't happen on a
+   * successful auth, but kept nullable so a future credential class that
+   * lacks a subject degrades gracefully rather than throwing).
+   */
+  actor: string | null;
+  /**
+   * Write-attribution axis 2 — VIA WHAT (vault#298). The interface/channel a
+   * write arrived through, derived PRAGMATICALLY from the credential class
+   * here, then REFINED by the request path at the call site (the MCP handler
+   * stamps `mcp`; the REST router keeps the credential-class default). Values:
+   * `mcp` · `surface:<name>` · `agent:<id>` · `operator` · `api`. This is the
+   * BASE value from auth — the credential class:
+   *   - Hub JWT  → `"api"` (the generic class; refined to `mcp` etc. downstream
+   *     once the channel is known).
+   *   - operator bearer → `"operator"`.
+   *   - legacy YAML key → `"api"` (a REST credential; the `token:<id>` actor
+   *     already carries the legacy-key identity).
+   * Never blocks the `actor` work — if the channel can't be cleanly
+   * determined the class (or `api`) stands.
+   */
+  via: string | null;
 }
 
 /**
  * Convert a legacy "read" | "full" permission into scopes + the legacyDerived
  * flag. Used for legacy YAML key authentication paths and for tokens whose
  * `scopes` column is still NULL.
+ *
+ * `actorLabel` (vault#298) is the write-attribution principal for this legacy
+ * credential — `token:<keyhash-prefix>` so a legacy-YAML-keyed write still
+ * attributes to a stable identity. Defaults to `"operator"` for the rare
+ * call site without a key in hand. `via` is the generic `api` class (legacy
+ * keys are a REST credential); the MCP handler refines it to `mcp` downstream.
  */
-function legacyAuthResult(permission: TokenPermission): AuthResult {
+function legacyAuthResult(
+  permission: TokenPermission,
+  actorLabel: string = "operator",
+): AuthResult {
   return {
     permission,
     scopes: legacyPermissionToScopes(permission),
@@ -152,9 +195,23 @@ function legacyAuthResult(permission: TokenPermission): AuthResult {
     scoped_tags: null,
     vault_name: null,
     caller_jti: null,
+    actor: actorLabel,
+    via: "api",
   };
 }
 
+/**
+ * Stable short label for a legacy YAML api_key, derived from its stored hash.
+ * `token:<first-12-of-hash>` — enough to distinguish keys for attribution
+ * without putting a full secret-derived hash into note rows. The hash is
+ * already a one-way digest of the key (see config.ts `verifyKey`), so a prefix
+ * leaks nothing usable.
+ */
+function legacyKeyActorLabel(keyHash: string): string {
+  const clean = keyHash.replace(/^[^:]*:/, ""); // drop any `algo:` prefix
+  return `token:${clean.slice(0, 12)}`;
+}
+
 // One-shot deprecation warning tracker, keyed by token hash / legacy label so
 // we don't spam the log on every request.
 const warnedLegacyTokens = new Set<string>();
@@ -303,7 +360,10 @@ export async function authenticateVaultRequest(
   if (vaultKey) {
     try { writeVaultConfig(vaultConfig); } catch {}
     warnLegacyOnce(`yaml-vault:${vaultKey.key_hash}`, "vault.yaml api_keys");
-    return legacyAuthResult(vaultKey.scope === "read" ? "read" : "full");
+    return legacyAuthResult(
+      vaultKey.scope === "read" ? "read" : "full",
+      legacyKeyActorLabel(vaultKey.key_hash),
+    );
   }
 
   // Legacy: check global keys from config.yaml
@@ -313,7 +373,10 @@ export async function authenticateVaultRequest(
     if (globalKey) {
       try { writeGlobalConfig(globalConfig); } catch {}
       warnLegacyOnce(`yaml-global:${globalKey.key_hash}`, "config.yaml api_keys");
-      return legacyAuthResult(globalKey.scope === "read" ? "read" : "full");
+      return legacyAuthResult(
+        globalKey.scope === "read" ? "read" : "full",
+        legacyKeyActorLabel(globalKey.key_hash),
+      );
     }
   }
 
@@ -515,6 +578,18 @@ async function authenticateHubJwt(
       // through verbatim — manage-token's session-pin will be null in that
       // case, and list/revoke from that session sees no mints.
       caller_jti: claims.jti ?? null,
+      // Write-attribution (vault#298). WHO = the validated JWT subject (the
+      // human, or the identity an agent runs as — note agent-grant tokens are
+      // minted with `sub = <user-on-whose-behalf>`, so today an agent's writes
+      // attribute to that human; a delegation-chain `via` is the deferred v2 in
+      // the issue). VIA = `api` here, the generic credential class; the request
+      // path refines it (the MCP handler stamps `mcp`). The JWT carries no
+      // clean surface-name / agent-definition-id claim — `clientId` is an
+      // opaque DCR id and `aud` is just `vault.<name>` — so per the issue's
+      // pragmatic constraint we DON'T manufacture a more specific class; the
+      // channel comes from the path instead.
+      actor: claims.sub && claims.sub.length > 0 ? claims.sub : null,
+      via: "api",
     };
   } catch (err) {
     if (err instanceof MalformedScopedTagsError) {
@@ -619,7 +694,10 @@ export async function authenticateGlobalRequest(
     if (matched) {
       try { writeGlobalConfig(globalConfig); } catch {}
       warnLegacyOnce(`yaml-global:${matched.key_hash}`, "config.yaml api_keys");
-      return legacyAuthResult(matched.scope === "read" ? "read" : "full");
+      return legacyAuthResult(
+        matched.scope === "read" ? "read" : "full",
+        legacyKeyActorLabel(matched.key_hash),
+      );
     }
   }
 

package/src/config.ts

@@ -215,6 +215,17 @@ export interface TriggerWhen {
   missing_metadata?: string[];
   /** Note.metadata must have ALL of these keys set (non-null). */
   has_metadata?: string[];
+  /**
+   * Value-matched metadata predicate (vault#299 Part B). A map of
+   * field → operator-object, evaluated against the note's live metadata with
+   * the SAME operators as `query-notes` (eq/ne/gt/gte/lt/lte/in/not_in/exists)
+   * via the shared `matchesOperator` engine. ALL entries must match (AND).
+   * Lets a trigger fire only on a specific transition — e.g.
+   * `metadata: { state: { eq: "published" } }` fires when a note reaches
+   * `published`, not on every edit. Combines with the presence/tag/content
+   * filters above (all must hold).
+   */
+  metadata?: Record<string, Record<string, unknown>>;
 }
 
 /**

package/src/mcp-http.ts

@@ -151,6 +151,11 @@ async function handleMcp(
         note_path?: string | null;
         current_updated_at?: string | null;
         expected_updated_at?: string;
+        field?: string;
+        expected_from?: unknown;
+        to?: unknown;
+        current?: unknown;
+        violations?: unknown;
       };
       if (e?.code === "CONFLICT") {
         throw new McpError(ErrorCode.InvalidRequest, message, {
@@ -161,6 +166,28 @@ async function handleMcp(
           note_id: e.note_id,
         });
       }
+      // State-transition compare-and-set conflict (vault#299 Part B) — a
+      // DISTINCT vocabulary from `conflict` (settled lead #3): the value
+      // didn't match, not the updated_at token.
+      if (e?.code === "TRANSITION_CONFLICT") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "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,
+        });
+      }
+      // Strict-schema rejection (vault#299 Part A) — one error carrying ALL
+      // per-field violations (settled lead #1).
+      if (e?.code === "SCHEMA_VALIDATION") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "schema_validation",
+          violations: e.violations ?? [],
+        });
+      }
       if (e?.code === "PRECONDITION_REQUIRED") {
         throw new McpError(ErrorCode.InvalidParams, message, {
           error_type: "precondition_required",

package/src/mcp-tools.ts

@@ -6,7 +6,7 @@
  */
 
 import { generateMcpTools } from "../core/src/mcp.ts";
-import type { McpToolDef } from "../core/src/mcp.ts";
+import type { McpToolDef, GenerateMcpToolsOpts } from "../core/src/mcp.ts";
 import { getNoteTags } from "../core/src/notes.ts";
 import type { Note } from "../core/src/types.ts";
 import {
@@ -16,7 +16,7 @@ import {
 } from "../core/src/vault-projection.ts";
 import { readVaultConfig, writeVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { hasScopeForVault, parseScopes, validateMintedScopes } from "./scopes.ts";
+import { hasScopeForVault, hasMigrateScopeForVault, parseScopes, validateMintedScopes, logStrictBypass } from "./scopes.ts";
 import type { AuthResult } from "./auth.ts";
 import {
   expandTokenTagScope,
@@ -166,10 +166,37 @@ export function generateScopedMcpTools(
         )
     : undefined;
 
+  // Write-attribution (vault#298). Every write through an MCP session arrives
+  // on the `mcp` channel — so we REFINE the auth's base `via` (the generic
+  // credential class) to `mcp` here, where the path/channel is known. The
+  // operator bearer keeps `operator` (its credential class IS its channel and
+  // is more informative than `mcp` for cross-container hub→vault writes); any
+  // other credential's via becomes `mcp`. `actor` (the principal) passes
+  // through unchanged.
+  const writeContext = auth
+    ? { actor: auth.actor, via: auth.via === "operator" ? "operator" : "mcp" }
+    : undefined;
+
+  // Migration-bypass (vault#299): a `vault:migrate`-scoped MCP session skips
+  // strict-schema enforcement and logs every bypassed write. Orthogonal to
+  // read/write/admin — an admin token does NOT bypass unless it also holds
+  // `migrate`. `onStrictBypass` writes the same structured log line the REST
+  // path uses (the audit-log table, #300, is deferred).
+  const strictBypass = auth ? hasMigrateScopeForVault(auth.scopes, vaultName) : false;
+  const onStrictBypass: GenerateMcpToolsOpts["onStrictBypass"] = strictBypass
+    ? (info) => logStrictBypass(info)
+    : undefined;
+
   const tools = generateMcpTools(
     store,
-    expandVisibility || nearTraversable
-      ? { ...(expandVisibility ? { expandVisibility } : {}), ...(nearTraversable ? { nearTraversable } : {}) }
+    expandVisibility || nearTraversable || writeContext || strictBypass
+      ? {
+          ...(expandVisibility ? { expandVisibility } : {}),
+          ...(nearTraversable ? { nearTraversable } : {}),
+          ...(writeContext ? { writeContext } : {}),
+          ...(strictBypass ? { strictBypass } : {}),
+          ...(onStrictBypass ? { onStrictBypass } : {}),
+        }
       : undefined,
   );