@openparachute/vault 0.6.3 → 0.6.4-rc.2

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/mcp-tools.ts

@@ -166,10 +166,25 @@ 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;
+
   const tools = generateMcpTools(
     store,
-    expandVisibility || nearTraversable
-      ? { ...(expandVisibility ? { expandVisibility } : {}), ...(nearTraversable ? { nearTraversable } : {}) }
+    expandVisibility || nearTraversable || writeContext
+      ? {
+          ...(expandVisibility ? { expandVisibility } : {}),
+          ...(nearTraversable ? { nearTraversable } : {}),
+          ...(writeContext ? { writeContext } : {}),
+        }
       : undefined,
   );
 

package/src/mirror-credentials.test.ts

@@ -104,6 +104,53 @@ describe("serialize + parse round-trip", () => {
     expect(out).toEqual(creds);
   });
 
+  test("github_oauth with persisted owner/name round-trips through the bytes (vault#401)", () => {
+    // owner/name are persisted at repo-select time so the selection survives a
+    // cleared git origin + restart. They must serialize and parse back
+    // byte-faithfully.
+    const creds: MirrorCredentials = {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "gho_abc123def456ghi789",
+        scope: "repo",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 12345,
+        owner: "aaron",
+        name: "backup-repo",
+      },
+      pat: null,
+    };
+    const out = parseCredentials(serializeCredentials(creds));
+    expect(out).toEqual(creds);
+    expect(out.github_oauth?.owner).toBe("aaron");
+    expect(out.github_oauth?.name).toBe("backup-repo");
+  });
+
+  test("github_oauth WITHOUT owner/name stays byte-stable (back-compat)", () => {
+    // Credentials written before a repo is picked (or before vault#401) carry
+    // no owner/name. Serialize must NOT emit empty owner/name lines, and the
+    // round-trip must leave the fields absent (not "").
+    const creds: MirrorCredentials = {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "gho_abc123def456ghi789",
+        scope: "repo",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 12345,
+      },
+      pat: null,
+    };
+    const serialized = serializeCredentials(creds);
+    expect(serialized).not.toContain("owner:");
+    expect(serialized).not.toContain("name:");
+    const out = parseCredentials(serialized);
+    expect(out).toEqual(creds);
+    expect(out.github_oauth?.owner).toBeUndefined();
+    expect(out.github_oauth?.name).toBeUndefined();
+  });
+
   test("github_oauth with empty scope round-trips (GitHub App tokens)", () => {
     // Tokens from the shared Parachute GitHub App carry scope: "" (GitHub
     // Apps use fine-grained permissions, not scopes). The empty string must

package/src/mirror-credentials.ts

@@ -86,6 +86,18 @@ export interface GitHubOAuthCredential {
   user_login: string;
   /** GitHub numeric user id — stable across login renames. */
   user_id: number;
+  /**
+   * The selected repo's owner — persisted at repo-select time (vault#401).
+   * Optional: absent before the operator picks a repo, and absent in
+   * credentials files written before this field existed (back-compat). When
+   * present, `applyCredentialsToRemote` reconstructs the authed remote URL
+   * from `owner`/`name` directly rather than regex-parsing the current git
+   * origin — so the selection survives the origin being cleared (e.g.
+   * `DELETE /auth` then re-OAuth) and a server restart.
+   */
+  owner?: string;
+  /** The selected repo's name — persisted alongside `owner` (vault#401). */
+  name?: string;
 }
 
 /**
@@ -138,6 +150,10 @@ export interface MirrorCredentialsPublic {
     scope: string;
     authorized_at: string;
     token_preview: string;
+    /** Selected repo owner, when a repo has been picked (vault#401). */
+    owner?: string;
+    /** Selected repo name, when a repo has been picked (vault#401). */
+    name?: string;
   } | null;
   pat: {
     label: string;
@@ -233,6 +249,15 @@ export function serializeCredentials(creds: MirrorCredentials): string {
     lines.push(`  authorized_at: ${quoteIfNeeded(creds.github_oauth.authorized_at)}`);
     lines.push(`  user_login: ${quoteIfNeeded(creds.github_oauth.user_login)}`);
     lines.push(`  user_id: ${creds.github_oauth.user_id}`);
+    // owner/name persisted at repo-select time (vault#401). Emitted only when
+    // present so credentials written before a repo is picked (or before this
+    // field existed) stay byte-stable.
+    if (creds.github_oauth.owner !== undefined) {
+      lines.push(`  owner: ${quoteIfNeeded(creds.github_oauth.owner)}`);
+    }
+    if (creds.github_oauth.name !== undefined) {
+      lines.push(`  name: ${quoteIfNeeded(creds.github_oauth.name)}`);
+    }
   } else {
     lines.push("github_oauth: null");
   }
@@ -356,6 +381,8 @@ export function parseCredentials(yaml: string): MirrorCredentials {
       else if (key === "scope") oauth.scope = parseScalar(rawVal!);
       else if (key === "authorized_at") oauth.authorized_at = parseScalar(rawVal!);
       else if (key === "user_login") oauth.user_login = parseScalar(rawVal!);
+      else if (key === "owner") oauth.owner = parseScalar(rawVal!);
+      else if (key === "name") oauth.name = parseScalar(rawVal!);
       else if (key === "user_id") {
         const n = Number(parseScalar(rawVal!));
         if (Number.isFinite(n)) oauth.user_id = n;
@@ -571,6 +598,12 @@ export function sanitizeCredentials(
           scope: creds.github_oauth.scope,
           authorized_at: creds.github_oauth.authorized_at,
           token_preview: previewToken(creds.github_oauth.access_token),
+          ...(creds.github_oauth.owner !== undefined
+            ? { owner: creds.github_oauth.owner }
+            : {}),
+          ...(creds.github_oauth.name !== undefined
+            ? { name: creds.github_oauth.name }
+            : {}),
         }
       : null,
     pat: creds.pat

package/src/mirror-manager.ts

@@ -1073,33 +1073,49 @@ export class MirrorManager {
         return;
       }
       // github_oauth: the active token is set, but a repo may not yet be
-      // picked. The select-repo route handler writes the URL; on a
-      // subsequent restart we can't reconstruct the URL without the
-      // owner/repo. Best-effort: if `origin` already points at a github.com
-      // URL, rewrite it with the stored token in case the token rotated.
+      // picked. The select-repo route handler writes the URL onto origin AND
+      // (vault#401) persists owner/name into the credentials struct.
       if (creds.active_method === "github_oauth" && creds.github_oauth) {
-        const current = await readCurrentOrigin(repoDir);
-        if (current && current.includes("github.com")) {
-          // Parse owner/repo out of the current URL.
-          const match = current.match(
-            /github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?$/,
-          );
-          if (match) {
-            const [, owner, repo] = match;
-            const { githubAuthedRemoteUrl } = await import("./mirror-credentials.ts");
-            const authed = githubAuthedRemoteUrl(
-              creds.github_oauth.access_token,
-              owner!,
-              repo!,
+        // vault#401: prefer the persisted owner/name. Reconstructing the
+        // remote from credentials alone means the selection survives the
+        // origin being cleared (DELETE /auth then re-OAuth) across a restart —
+        // the bug class where regex-parsing the origin silently lost the repo.
+        const persistedOwner = creds.github_oauth.owner;
+        const persistedName = creds.github_oauth.name;
+        let owner: string | undefined;
+        let repo: string | undefined;
+        if (persistedOwner && persistedName) {
+          owner = persistedOwner;
+          repo = persistedName;
+        } else {
+          // Back-compat fallback: credentials written before #401 don't carry
+          // owner/name. Parse them out of the current github.com origin (the
+          // pre-#401 behavior) when origin is still present.
+          const current = await readCurrentOrigin(repoDir);
+          if (current && current.includes("github.com")) {
+            const match = current.match(
+              /github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?$/,
             );
-            const result = await applyToGitRemote(repoDir, authed);
-            if (!result.ok) {
-              console.warn(
-                `[mirror] could not refresh github_oauth remote URL (non-fatal): ${result.error}`,
-              );
+            if (match) {
+              owner = match[1];
+              repo = match[2];
             }
           }
         }
+        if (owner && repo) {
+          const { githubAuthedRemoteUrl } = await import("./mirror-credentials.ts");
+          const authed = githubAuthedRemoteUrl(
+            creds.github_oauth.access_token,
+            owner,
+            repo,
+          );
+          const result = await applyToGitRemote(repoDir, authed);
+          if (!result.ok) {
+            console.warn(
+              `[mirror] could not refresh github_oauth remote URL (non-fatal): ${result.error}`,
+            );
+          }
+        }
       }
     } catch (err) {
       console.warn(

package/src/mirror-routes.test.ts

@@ -912,6 +912,84 @@ describe("auth credential routes — credential-save side-effects (Cuts 3 + 6)",
     await manager.stop();
   }, 30_000);
 
+  test("vault#401: owner/name survive a cleared origin + restart (persisted in creds, not just the git remote)", async () => {
+    // The bug: pre-#401, select-repo wrote owner/name ONLY into the git
+    // origin URL. On restart, applyCredentialsToRemote regex-parsed them back
+    // out of the origin — so clearing the origin (DELETE /auth → re-OAuth
+    // without re-selecting) silently lost the repo even with a valid token.
+    // Now select-repo persists owner/name into the credentials struct, and
+    // applyCredentialsToRemote prefers the persisted values. With the origin
+    // cleared, a restart still reconstructs the github.com remote.
+    home = tmp("mirror-selectrepo-persist-");
+    const { manager, deps } = makeManager(home);
+    const cfg = {
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal" as const,
+      sync_mode: "manual" as const,
+      auto_commit: false,
+      auto_push: false,
+    };
+    // The manager reads config via deps.readMirrorConfig (in-memory); the
+    // route's history-on-link keys off the real per-vault file's existence.
+    // Seed both, same as the autopush test above.
+    deps.writeMirrorConfig(cfg);
+    writeMirrorConfigForVault("default", cfg);
+    await manager.start();
+    const mirrorPath = manager.getStatus().mirror_path;
+    expect(mirrorPath).toBeTruthy();
+
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "gho_persisttoken12345",
+        scope: "repo",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+
+    const res = await handleAuthGithubSelectRepo(
+      new Request("http://x/select", {
+        method: "POST",
+        body: JSON.stringify({ owner: "aaron", name: "backup-repo" }),
+      }),
+      manager,
+    );
+    expect(res.status).toBe(200);
+
+    // The fix: owner/name persisted into the credentials struct (not just origin).
+    const persisted = readCredentials("default");
+    expect(persisted?.github_oauth?.owner).toBe("aaron");
+    expect(persisted?.github_oauth?.name).toBe("backup-repo");
+
+    // Simulate the DELETE /auth + re-OAuth-without-reselect path: the OAuth
+    // token survives, but the git origin gets cleared.
+    Bun.spawnSync(["git", "remote", "remove", "origin"], { cwd: mirrorPath! });
+    const afterClear = Bun.spawnSync(["git", "remote", "get-url", "origin"], {
+      cwd: mirrorPath!,
+    });
+    expect(afterClear.exitCode).not.toBe(0); // origin is gone
+
+    // Restart — applyCredentialsToRemote runs again. Pre-#401 it would find no
+    // origin to parse and leave the remote unset; post-#401 it rebuilds from
+    // the persisted owner/name.
+    await manager.stop();
+    await manager.start();
+
+    const reapplied = Bun.spawnSync(["git", "remote", "get-url", "origin"], {
+      cwd: mirrorPath!,
+    });
+    expect(reapplied.exitCode).toBe(0);
+    const reappliedUrl = reapplied.stdout.toString().trim();
+    // The remote was reconstructed from persisted owner/name (token embedded,
+    // not asserted here). Without persistence this would be empty.
+    expect(reappliedUrl).toContain("github.com/aaron/backup-repo");
+    await manager.stop();
+  }, 30_000);
+
   test("select-repo is a no-op for auto_push when mirror is disabled", async () => {
     // Operator wiring credentials before flipping the mirror on — don't
     // mutate auto_push behind their back.

package/src/mirror-routes.ts

@@ -1200,6 +1200,19 @@ export async function handleAuthGithubSelectRepo(
     }
   }
 
+  // vault#401: persist the selected owner/name INTO the credentials struct,
+  // not only into the git origin URL. Pre-#401 the selection lived solely in
+  // the origin URL; `applyCredentialsToRemote` regex-parsed it back out on
+  // restart, so clearing the origin (e.g. `DELETE /auth` then re-OAuth without
+  // re-selecting) silently lost the repo even with a still-valid token. Saving
+  // it here lets the restart path reconstruct the remote from credentials
+  // alone. Write before the remote-apply so the persisted selection survives
+  // even if the apply later fails.
+  writeCredentials(manager.getVaultName(), {
+    ...creds,
+    github_oauth: { ...creds.github_oauth, owner, name },
+  });
+
   // Reach into mirror-credentials.ts for the authed URL builder.
   const { githubAuthedRemoteUrl } = await import("./mirror-credentials.ts");
   const authedUrl = githubAuthedRemoteUrl(

package/src/routes.ts

@@ -44,6 +44,16 @@ 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 };
+
+const NO_WRITE_CTX: WriteCtx = { actor: null, via: null };
 import {
   expandContent,
   DEFAULT_EXPAND_DEPTH,
@@ -567,6 +577,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 +721,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 +738,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;
@@ -1109,6 +1128,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
@@ -1383,6 +1405,9 @@ 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) ?? "";
           const created = await store.createNote(content, createOpts);
@@ -1568,6 +1593,10 @@ async function handleNotesInner(
       }
 
       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);
       }
 

package/src/routing.ts

@@ -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,14 @@ 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.
+  const writeCtx: WriteCtx = { actor: auth.actor, via: auth.via };
+
+  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.