@openparachute/vault 0.6.4-rc.1 → 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/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.