@openparachute/vault 0.7.9-rc.1 → 0.7.9-rc.2

package/core/src/mcp-manifest.ts

@@ -171,8 +171,8 @@ Response shape (vault#550 — three variants, pick by what you passed):
           },
           created_by: { type: "string", description: "Write-attribution filter (vault#298): only notes whose FIRST write was attributed to this principal (a JWT subject, or an operator/token label). Exact match; indexed. Legacy/unattributed notes (NULL) never match." },
           last_updated_by: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write was attributed to this principal. Exact match; indexed." },
-          created_via: { type: "string", description: "Write-attribution filter (vault#298): only notes FIRST written through this interface/channel — e.g. `mcp`, `surface:<name>`, `agent:<id>`, `operator`, `api`. Exact match; indexed." },
-          last_updated_via: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write came through this interface/channel. Exact match; indexed." },
+          created_via: { type: "string", description: "Write-attribution filter (vault#298): only notes FIRST written through this interface/channel — e.g. `mcp`, `surface:<name>`, `agent:<id>`, `nostr:<64-hex-pubkey>`, `operator`, `api`. `nostr:<pubkey>` (vault#698) is the Nostr key that SIGNED the request, and is the axis that tells two agents apart when they share one hub user (`created_by`). Emitted by BOTH doors — self-hosted hub (parachute-hub#937) and cloud (parachute-cloud#277). Exact match; indexed." },
+          last_updated_via: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write came through this interface/channel — same vocabulary as `created_via`, including `nostr:<64-hex-pubkey>` for the signing key. Exact match; indexed." },
           order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. Two special values need no declaration: `link_count` sorts by link DEGREE (both-directions raw row count), matching the `include_link_count` field for every note; `updated_at` (vault#585) sorts on the integer `updated_at_ms` mirror column — correct on non-canonical/imported timestamps — with `id` as the tiebreaker. Direction is taken from `sort` (default 'asc'); for other fields `created_at` is appended as a stable tiebreaker." },
           date_from: { type: "string", description: "Start date (ISO, inclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', from }`." },
           date_to: { type: "string", description: "End date (ISO, exclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', to }`." },
@@ -341,7 +341,7 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
 - \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`, \`displayTitle\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present. \`displayTitle\` is the note's first non-empty content line (heading markers stripped, ~120 chars max), \`null\` when content is empty — never stored, computed fresh from content already in hand.
 
-Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\` (the principal + interface of the first write) and \`lastUpdatedBy\`/\`lastUpdatedVia\` (the most recent write). NULL on notes written before attribution existed. Filter on them with \`created_by\`/\`last_updated_by\`/\`created_via\`/\`last_updated_via\`.`,
+Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\` (the principal + interface of the first write) and \`lastUpdatedBy\`/\`lastUpdatedVia\` (the most recent write). NULL on notes written before attribution existed. Filter on them with \`created_by\`/\`last_updated_by\`/\`created_via\`/\`last_updated_via\`. When the write was signed with a Nostr key (the hub's NIP-98 door), the \`*Via\` value is \`nostr:<64-hex-pubkey>\` — \`createdBy\` stays the hub USER, so the pubkey is what distinguishes two agents sharing that user.`,
       inputSchema: {
         type: "object",
         properties: {

package/core/src/notes.ts

@@ -41,8 +41,12 @@ import { generateUlid } from "./ulid.js";
  *           `created_by` on the first write and `last_updated_by` on every
  *           write.
  *   via   — VIA WHAT: the interface/channel the write arrived through
- *           (`mcp`, `surface:<name>`, `agent:<id>`, `operator`/`cli`, `api`).
- *           Lands in `created_via` / `last_updated_via` symmetrically.
+ *           (`mcp`, `surface:<name>`, `agent:<id>`, `nostr:<pubkey>`,
+ *           `operator`/`cli`, `api`). `nostr:<pubkey>` (vault#698) is the
+ *           Nostr key that SIGNED the request — more specific than the
+ *           channel, and the only axis distinguishing two agents that share
+ *           one hub user. Lands in `created_via` / `last_updated_via`
+ *           symmetrically.
  *
  * Both are independently optional — an internal/import write may carry
  * neither, and a non-JWT operator write carries an `actor`/`via` pair without

package/core/src/schema.ts

@@ -1282,7 +1282,7 @@ function migrateToV22(db: Database): void {
  *
  * `*_by` is the JWT `sub` (or an operator / `token:<id>` label for non-JWT
  * auth); `*_via` is the channel (`mcp`, `surface:<name>`, `agent:<id>`,
- * `operator`/`cli`, `api`). All four NULL on legacy rows — we deliberately do
+ * `nostr:<pubkey>`, `operator`/`cli`, `api`). All four NULL on legacy rows — we deliberately do
  * NOT backfill an author for writes that predate attribution; NULL reads as
  * "unknown / pre-attribution," distinct from any real principal.
  *

package/core/src/types.ts

@@ -45,7 +45,9 @@ export interface Note {
    * Write-attribution (vault#298) — two axes of provenance, both nullable.
    * `*By` is the principal (a JWT `sub`, or an operator / `token:<id>` label);
    * `*Via` is the interface the write arrived through (`mcp`, `surface:<name>`,
-   * `agent:<id>`, `operator`/`cli`, `api`). The `created*` pair is set once at
+   * `agent:<id>`, `nostr:<pubkey>`, `operator`/`cli`, `api`). `nostr:<pubkey>`
+   * (vault#698) is the Nostr key that SIGNED the request — the axis that tells
+   * two agents apart when they share one hub user. The `created*` pair is set once at
    * create; the `lastUpdated*` pair tracks the most recent mutating write. NULL
    * = unknown / written before attribution existed (legacy rows) or by a path
    * that carried no context — distinct from any real principal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.9-rc.1",
+  "version": "0.7.9-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/attribution-threading.test.ts

@@ -6,7 +6,8 @@
  *   - 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 env-var bearer; `nostr:<pubkey>` when the hub stamped a NIP-98
+ *     signing key (vault#698); refined to `mcp` by the MCP handler otherwise.
  *
  * The store-layer column behavior + query filters live in
  * core/src/attribution.test.ts. This file pins the AUTH → AuthResult mapping
@@ -27,10 +28,10 @@ import {
   hashKey,
 } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
-import { authenticateVaultRequest } from "./auth.ts";
+import { authenticateVaultRequest, refineMcpVia } from "./auth.ts";
 import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
 import { generateScopedMcpTools } from "./mcp-tools.ts";
-import { parseNotesQueryOpts } from "./routes.ts";
+import { handleNotes, parseNotesQueryOpts } from "./routes.ts";
 import type { AuthResult } from "./auth.ts";
 
 // ---------------------------------------------------------------------------
@@ -68,10 +69,21 @@ function startHubFixture(keys: Keypair[]): { origin: string; stop: () => void }
 }
 async function signJwt(
   kp: Keypair,
-  opts: { iss: string; aud: string; scope: string; sub?: string },
+  opts: {
+    iss: string;
+    aud: string;
+    scope: string;
+    sub?: string;
+    /** Raw `permissions` claim — vault#698 carries `principal_pubkey` here. */
+    permissions?: unknown;
+  },
 ): Promise<string> {
   const iat = Math.floor(Date.now() / 1000);
-  return await new SignJWT({ scope: opts.scope, client_id: "test-client" })
+  return await new SignJWT({
+    scope: opts.scope,
+    client_id: "test-client",
+    ...(opts.permissions !== undefined ? { permissions: opts.permissions } : {}),
+  })
     .setProtectedHeader({ alg: "RS256", kid: kp.kid })
     .setIssuer(opts.iss)
     .setSubject(opts.sub ?? "user-1")
@@ -348,3 +360,281 @@ describe("attribution threading — REST query filters (symmetric with MCP)", ()
     expect(queryOpts?.lastUpdatedVia).toBeUndefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// vault#698 — Nostr principal attribution
+//
+// The hub's NIP-98 `/mcp` door mints the vault hop token with
+// `permissions.principal_pubkey = <64-hex>`. `created_by` stays the hub USER
+// id (two agents linked to one user share it), so `created_via` /
+// `last_updated_via` are the ONLY axis that tells them apart.
+// ---------------------------------------------------------------------------
+
+const PUBKEY_A = "a".repeat(64);
+const PUBKEY_B = "e6619493" + "b".repeat(56);
+
+describe("attribution threading — nostr principal (vault#698)", () => {
+  test("hub JWT with permissions.principal_pubkey → via = 'nostr:<pubkey>', actor unchanged", async () => {
+    seedVaultNoKey("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      sub: "e6619493-hub-user",
+      permissions: { principal_pubkey: PUBKEY_A },
+    });
+    const result = await authenticateVaultRequest(bearer(token), readVaultConfig("journal")!);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      // `created_by` axis is untouched — still the hub user.
+      expect(result.actor).toBe("e6619493-hub-user");
+      expect(result.via).toBe(`nostr:${PUBKEY_A}`);
+    }
+  });
+
+  test("a malformed principal_pubkey degrades to 'api' — never 401, never stored", async () => {
+    seedVaultNoKey("journal");
+    // Uppercase hex, wrong length, non-hex, non-string, and an npub — each must
+    // fail SOFT (attribution is a label, not an access decision).
+    const bad: unknown[] = [
+      "A".repeat(64),
+      "ab".repeat(20),
+      `${"z".repeat(64)}`,
+      12345,
+      { hex: PUBKEY_A },
+      "npub1qqqqq",
+      null,
+    ];
+    for (const value of bad) {
+      const token = await signJwt(kp, {
+        iss: fixture.origin,
+        aud: "vault.journal",
+        scope: "vault:journal:write",
+        sub: "hub-user",
+        permissions: { principal_pubkey: value },
+      });
+      const result = await authenticateVaultRequest(bearer(token), readVaultConfig("journal")!);
+      expect("error" in result).toBe(false);
+      if (!("error" in result)) expect(result.via).toBe("api");
+    }
+  });
+
+  test("principal_pubkey coexists with scoped_tags in the same permissions claim", async () => {
+    seedVaultNoKey("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      sub: "hub-user",
+      permissions: { principal_pubkey: PUBKEY_A, scoped_tags: ["daily"] },
+    });
+    const result = await authenticateVaultRequest(bearer(token), readVaultConfig("journal")!);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.via).toBe(`nostr:${PUBKEY_A}`);
+      expect(result.scoped_tags).toEqual(["daily"]);
+    }
+  });
+
+  test("ORDERING GUARANTEE: a permissions claim with ONLY principal_pubkey is ignorable — scoped_tags stays unscoped", async () => {
+    // This is the "vault ships first" safety argument, pinned as a test: the
+    // ONLY pre-existing reader of `permissions` is
+    // `parseScopedTagsFromPermissions`, and it returns null (unscoped) when
+    // `scoped_tags` is absent. So a hub that emits the new claim against an
+    // OLD vault changes nothing.
+    seedVaultNoKey("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      sub: "hub-user",
+      permissions: { principal_pubkey: PUBKEY_A },
+    });
+    const result = await authenticateVaultRequest(bearer(token), readVaultConfig("journal")!);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) expect(result.scoped_tags).toBeNull();
+  });
+
+  test("refineMcpVia keeps a nostr signer, refines the generic classes, keeps operator", () => {
+    expect(refineMcpVia(`nostr:${PUBKEY_A}`)).toBe(`nostr:${PUBKEY_A}`);
+    expect(refineMcpVia("operator")).toBe("operator");
+    expect(refineMcpVia("api")).toBe("mcp");
+    expect(refineMcpVia("token:abc123")).toBe("mcp");
+    expect(refineMcpVia(null)).toBe("mcp");
+  });
+});
+
+describe("attribution threading — nostr signer lands on every MCP write path", () => {
+  function nostrAuth(hubUserId: string, vaultName: string, pubkey: string): AuthResult {
+    return {
+      permission: "full",
+      scopes: [`vault:${vaultName}:write`, `vault:${vaultName}:read`],
+      legacyDerived: false,
+      scoped_tags: null,
+      vault_name: null,
+      caller_jti: null,
+      actor: hubUserId,
+      via: `nostr:${pubkey}`,
+    };
+  }
+
+  test("create-note: both *_via columns carry the signer, created_by stays the hub user", async () => {
+    seedVaultNoKey("journal");
+    const tools = generateScopedMcpTools(
+      "journal",
+      nostrAuth("e6619493-hub-user", "journal", PUBKEY_A),
+      null,
+    );
+    const create = tools.find((t) => t.name === "create-note")!;
+    const created = (await create.execute({ content: "signed by A" })) as { id: string };
+
+    const store = getVaultStore("journal");
+    const row = store.db
+      .prepare(
+        "SELECT created_by, created_via, last_updated_by, last_updated_via FROM notes WHERE id = ?",
+      )
+      .get(created.id) as Record<string, string | null>;
+    expect(row.created_by).toBe("e6619493-hub-user");
+    expect(row.last_updated_by).toBe("e6619493-hub-user");
+    expect(row.created_via).toBe(`nostr:${PUBKEY_A}`);
+    expect(row.last_updated_via).toBe(`nostr:${PUBKEY_A}`);
+  });
+
+  test("create-note BATCH: every item in the batch carries the signer", async () => {
+    seedVaultNoKey("journal");
+    const tools = generateScopedMcpTools("journal", nostrAuth("hub-user", "journal", PUBKEY_A), null);
+    const create = tools.find((t) => t.name === "create-note")!;
+    await create.execute({
+      notes: [
+        { content: "one", path: "Batch/One" },
+        { content: "two", path: "Batch/Two" },
+      ],
+    });
+    const store = getVaultStore("journal");
+    const rows = store.db
+      .prepare("SELECT created_via, last_updated_via FROM notes WHERE path LIKE 'Batch/%'")
+      .all() as Array<Record<string, string | null>>;
+    expect(rows.length).toBe(2);
+    for (const row of rows) {
+      expect(row.created_via).toBe(`nostr:${PUBKEY_A}`);
+      expect(row.last_updated_via).toBe(`nostr:${PUBKEY_A}`);
+    }
+  });
+
+  test("THE REPORTED BUG: agent B appending to agent A's note is distinguishable", async () => {
+    // Observed 2026-09-02: GrokJi's append showed lastUpdatedBy = e6619493-…,
+    // byte-identical to ClaudeJi's, because both link to the same hub user and
+    // both writes stamped via="mcp".
+    seedVaultNoKey("journal");
+    const HUB_USER = "e6619493-shared-hub-user";
+    const store = getVaultStore("journal");
+
+    const toolsA = generateScopedMcpTools("journal", nostrAuth(HUB_USER, "journal", PUBKEY_A), null);
+    const created = (await toolsA.find((t) => t.name === "create-note")!.execute({
+      content: "written by A",
+      path: "Shared/Note",
+    })) as { id: string };
+
+    const toolsB = generateScopedMcpTools("journal", nostrAuth(HUB_USER, "journal", PUBKEY_B), null);
+    await toolsB
+      .find((t) => t.name === "update-note")!
+      .execute({ id: created.id, append: "\n\nappended by B" });
+
+    const after = await store.getNote(created.id);
+    // Same hub user on both axes — that is correct and unchanged.
+    expect(after?.createdBy).toBe(HUB_USER);
+    expect(after?.lastUpdatedBy).toBe(HUB_USER);
+    // …but the two agents are now distinguishable.
+    expect(after?.createdVia).toBe(`nostr:${PUBKEY_A}`);
+    expect(after?.lastUpdatedVia).toBe(`nostr:${PUBKEY_B}`);
+    expect(after?.content).toContain("appended by B");
+  });
+
+  test("update-note (full replace) bumps last_updated_via to the new signer", async () => {
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+    const seed = await store.createNote("seed", { actor: "hub-user", via: `nostr:${PUBKEY_A}` });
+    const toolsB = generateScopedMcpTools("journal", nostrAuth("hub-user", "journal", PUBKEY_B), null);
+    await toolsB
+      .find((t) => t.name === "update-note")!
+      .execute({ id: seed.id, content: "replaced by B", force: true });
+    const after = await store.getNote(seed.id);
+    expect(after?.createdVia).toBe(`nostr:${PUBKEY_A}`); // set-once
+    expect(after?.lastUpdatedVia).toBe(`nostr:${PUBKEY_B}`);
+  });
+
+  test("update-note if_missing:'create' (upsert-create) stamps the signer on both pairs", async () => {
+    seedVaultNoKey("journal");
+    const tools = generateScopedMcpTools("journal", nostrAuth("hub-user", "journal", PUBKEY_B), null);
+    const created = (await tools.find((t) => t.name === "update-note")!.execute({
+      id: "Upsert/Born",
+      content: "born via upsert",
+      if_missing: "create",
+    })) as { id: string };
+    const store = getVaultStore("journal");
+    const row = store.db
+      .prepare("SELECT created_via, last_updated_via FROM notes WHERE id = ?")
+      .get(created.id) as Record<string, string | null>;
+    expect(row.created_via).toBe(`nostr:${PUBKEY_B}`);
+    expect(row.last_updated_via).toBe(`nostr:${PUBKEY_B}`);
+  });
+
+  test("REST DOOR PARITY: a REST write carries the signer too (routing.ts passes auth.via unrefined)", async () => {
+    // The MCP door refines via `refineMcpVia`; the REST door threads the BASE
+    // `auth.via` straight into WriteCtx (routing.ts ~L1145). Since the base
+    // value is already `nostr:<pubkey>`, REST gets signer attribution for free
+    // — but nothing pinned it, so a future "normalize REST via to api" change
+    // would silently drop it on that door only.
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+    const res = await handleNotes(
+      new Request("http://localhost/api/notes", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ content: "written over REST", path: "Rest/Signed" }),
+      }),
+      store,
+      "",
+      "journal",
+      { allowed: null, raw: null },
+      { actor: "e6619493-hub-user", via: `nostr:${PUBKEY_A}` },
+    );
+    expect(res.status).toBe(201);
+    const row = store.db
+      .prepare(
+        "SELECT created_by, created_via, last_updated_via FROM notes WHERE path = 'Rest/Signed'",
+      )
+      .get() as Record<string, string | null>;
+    expect(row.created_by).toBe("e6619493-hub-user");
+    expect(row.created_via).toBe(`nostr:${PUBKEY_A}`);
+    expect(row.last_updated_via).toBe(`nostr:${PUBKEY_A}`);
+  });
+
+  test("the signer is FILTERABLE via created_via / last_updated_via", async () => {
+    seedVaultNoKey("journal");
+    const store = getVaultStore("journal");
+    const toolsA = generateScopedMcpTools("journal", nostrAuth("hub-user", "journal", PUBKEY_A), null);
+    const toolsB = generateScopedMcpTools("journal", nostrAuth("hub-user", "journal", PUBKEY_B), null);
+    const byA = (await toolsA.find((t) => t.name === "create-note")!.execute({
+      content: "A wrote this",
+      path: "Filter/A",
+    })) as { id: string };
+    await toolsB.find((t) => t.name === "create-note")!.execute({
+      content: "B wrote this",
+      path: "Filter/B",
+    });
+    // B then edits A's note — created_via stays A, last_updated_via becomes B.
+    await toolsB
+      .find((t) => t.name === "update-note")!
+      .execute({ id: byA.id, append: " (edited)" });
+
+    const createdByA = await store.queryNotes({ createdVia: `nostr:${PUBKEY_A}` });
+    expect(createdByA.map((n) => n.path)).toEqual(["Filter/A"]);
+
+    const touchedByB = await store.queryNotes({ lastUpdatedVia: `nostr:${PUBKEY_B}` });
+    expect(touchedByB.map((n) => n.path).sort()).toEqual(["Filter/A", "Filter/B"]);
+
+    // And the old flat label matches nothing now that the signer is recorded.
+    expect(await store.queryNotes({ createdVia: "mcp" })).toEqual([]);
+  });
+});

package/src/auth.ts

@@ -161,8 +161,12 @@ export interface AuthResult {
    * 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:
+   * `mcp` · `surface:<name>` · `agent:<id>` · `nostr:<pubkey>` · `operator` ·
+   * `api`. This is the BASE value from auth — the credential class:
+   *   - Hub JWT with a `permissions.principal_pubkey` claim → `nostr:<pubkey>`
+   *     (vault#698). The signer is MORE specific than the channel, and unlike
+   *     every other class it distinguishes two agents that share one hub user,
+   *     so downstream does NOT refine it away — see `mcp-tools.ts`.
    *   - Hub JWT  → `"api"` (the generic class; refined to `mcp` etc. downstream
    *     once the channel is known).
    *   - operator bearer → `"operator"`.
@@ -464,6 +468,97 @@ class MalformedScopedTagsError extends Error {}
  *      The only correct fail-closed action for a present-but-unreadable
  *      scope is to reject the whole request — never serve it wide.
  */
+/**
+ * Nostr pubkey shape: 32 bytes, lowercase hex. NIP-01 canonical form.
+ */
+const NOSTR_PUBKEY_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * Write-attribution `via` label for a NIP-98-signed principal.
+ *
+ * `nostr:<64-hex>` joins the existing open-ended `via` vocabulary
+ * (`mcp` · `surface:<name>` · `agent:<id>` · `operator` · `api`) — same
+ * `<class>:<id>` shape as `agent:<id>`, so `created_via` / `last_updated_via`
+ * stay plain exact-match strings and every existing filter keeps working.
+ */
+export function nostrVia(pubkey: string): string {
+  return `nostr:${pubkey}`;
+}
+
+/**
+ * Refine the credential-class `via` from `AuthResult` for a write that arrived
+ * on the MCP channel.
+ *
+ * `mcp` wins over the generic classes (`api`, a legacy `token:` REST key) —
+ * the channel is the more specific fact. It does NOT win over a class that
+ * already names a *principal or channel of its own*:
+ *
+ *   - `operator` — the env-var bearer (vault#298).
+ *   - `nostr:<pubkey>` — the NIP-98 signer (vault#698). Every hub `/mcp`
+ *     caller is on the `mcp` channel, so `mcp` cannot distinguish two agents
+ *     sharing a hub user; the key can.
+ */
+export function refineMcpVia(via: string | null | undefined): string {
+  // `undefined` is accepted alongside `null` on purpose: `AuthResult` declares
+  // `via: string | null`, but several in-repo call sites build the object
+  // without the key (attachment tools, test harnesses). The expression this
+  // replaced (`auth.via === "operator" ? … : "mcp"`) tolerated that silently,
+  // so a `string`-only signature here would turn a missing key into a
+  // TypeError at write time. Narrow on `typeof`, not on `!== null`.
+  if (via === "operator") return "operator";
+  if (typeof via === "string" && via.startsWith("nostr:")) return via;
+  return "mcp";
+}
+
+/**
+ * Read the signing pubkey out of a validated hub JWT's `permissions` claim
+ * (vault#698 / hub#937 — Nostr principal attribution).
+ *
+ * Wire contract: `permissions: { principal_pubkey: "<64 lowercase hex>" }`.
+ * The hub stamps it ONLY on tokens minted for a NIP-98-authenticated caller;
+ * password / OAuth / Bearer sessions never carry it.
+ *
+ * Why it rides inside `permissions` rather than a top-level claim:
+ * `@openparachute/scope-guard` returns a FIXED claim surface
+ * (`sub`, `scopes`, `aud`, `jti`, `clientId`, `vaultScope`, `permissions`) and
+ * drops everything else, and `permissions` is its documented verbatim
+ * passthrough. A new top-level claim would be invisible here without a
+ * scope-guard release.
+ *
+ * FAIL-SOFT, deliberately the opposite of `parseScopedTagsFromPermissions`:
+ * this claim only *labels* a write, it never widens or narrows access. A
+ * missing / malformed / wrong-case / non-hex value returns `null` and the
+ * caller falls back to the generic credential class, rather than storing junk
+ * in an attribution column or 401-ing a legitimate write.
+ */
+export function parsePrincipalPubkey(
+  permissions: Record<string, unknown> | undefined,
+): string | null {
+  if (!permissions) return null;
+  if (!("principal_pubkey" in permissions)) return null;
+  const raw = permissions.principal_pubkey;
+  if (typeof raw === "string" && NOSTR_PUBKEY_RE.test(raw)) return raw;
+  // PRESENT but unreadable. Fail soft (see above) — but never SILENTLY: the
+  // symptom of a dropped claim (`created_via` back to `mcp`) is byte-identical
+  // to the symptom of the hub not having shipped the claim at all, which is
+  // exactly the bug this feature exists to fix. One warn per distinct bad
+  // value makes the two distinguishable in the daemon log. A pubkey is public
+  // by construction, so logging the value leaks nothing.
+  const seen = typeof raw === "string" ? raw : `<${typeof raw}>`;
+  if (!warnedBadPubkeys.has(seen)) {
+    warnedBadPubkeys.add(seen);
+    console.warn(
+      "[attribution] hub JWT permissions.principal_pubkey present but not 64 lowercase hex — " +
+        `ignoring, falling back to the generic credential class (saw: ${JSON.stringify(seen)})`,
+    );
+  }
+  return null;
+}
+
+/** Dedupe key set for the warn above — unbounded growth is bounded in practice
+ *  by the number of DISTINCT malformed values a misconfigured hub emits (one). */
+const warnedBadPubkeys = new Set<string>();
+
 function parseScopedTagsFromPermissions(
   permissions: Record<string, unknown> | undefined,
 ): string[] | null {
@@ -575,6 +670,9 @@ async function authenticateHubJwt(
     // Throws MalformedScopedTagsError (caught below → 401) on a present-but-
     // malformed claim so we never widen access on a misread.
     const scoped_tags = parseScopedTagsFromPermissions(claims.permissions);
+    // Write-attribution axis 2 (vault#698): the NIP-98 signing pubkey, when
+    // the hub stamped one. Fail-soft — see `parsePrincipalPubkey`.
+    const principalPubkey = parsePrincipalPubkey(claims.permissions);
     return {
       permission,
       scopes: claims.scopes,
@@ -596,7 +694,13 @@ async function authenticateHubJwt(
       // 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",
+      // VIA: `nostr:<pubkey>` when the hub tells us which key signed the
+      // request that produced this token (vault#698 — the NIP-98 `/mcp` door),
+      // otherwise the generic `api` credential class the request path refines.
+      // `actor` is untouched on purpose: it stays the hub USER id, so two
+      // agents sharing a hub user keep one `created_by` and are told apart by
+      // `created_via` / `last_updated_via`.
+      via: principalPubkey !== null ? nostrVia(principalPubkey) : "api",
     };
   } catch (err) {
     if (err instanceof MalformedScopedTagsError) {

package/src/mcp-tools.ts

@@ -18,6 +18,7 @@ import { readVaultConfig, writeVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { hasScopeForVault, hasMigrateScopeForVault, parseScopes, validateMintedScopes, logStrictBypass } from "./scopes.ts";
 import type { AuthResult } from "./auth.ts";
+import { refineMcpVia } from "./auth.ts";
 import {
   expandTokenTagScope,
   filterHydratedLinksByTagScope,
@@ -226,14 +227,19 @@ export function generateScopedMcpTools(
 
   // 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;
+  // credential class) to `mcp` here, where the path/channel is known. `actor`
+  // (the principal) passes through unchanged.
+  //
+  // Two classes are kept INSTEAD of `mcp`, because each is strictly more
+  // informative than the channel:
+  //   - `operator` — the env-var bearer's credential class IS its channel, and
+  //     it names cross-container hub→vault writes (vault#298).
+  //   - `nostr:<pubkey>` — the NIP-98 signer (vault#698). Every agent coming
+  //     through the hub's `/mcp` door arrives on the `mcp` channel, so `mcp`
+  //     cannot tell two agents apart; the signing key can. `created_by` is
+  //     still the shared hub user, so this is the ONLY attribution axis that
+  //     distinguishes them — flattening it here would reintroduce the bug.
+  const writeContext = auth ? { actor: auth.actor, via: refineMcpVia(auth.via) } : undefined;
 
   // Migration-bypass (vault#299): a `vault:migrate`-scoped MCP session skips
   // strict-schema enforcement and logs every bypassed write. Orthogonal to

package/src/release-plan.test.ts

@@ -0,0 +1,302 @@
+/**
+ * The publish-on-merge decision.
+ *
+ * Release logic that can double-publish or silently drop a release is exactly
+ * the kind that should not live untested in a YAML `run:` block. Every case
+ * here is one where a wrong answer costs something real. Ported from
+ * parachute-app's `scripts/release-plan.test.ts` onto bun:test (this repo's
+ * `bun test ./src/` surface).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  compareVersions,
+  decidePublish,
+  distTagFor,
+  readRegistry,
+  unpublishedDrift,
+} from "../scripts/release-plan.ts";
+
+describe("distTagFor", () => {
+  test("prerelease → rc, release → latest", () => {
+    expect(distTagFor("0.7.9-rc.2")).toBe("rc");
+    expect(distTagFor("0.7.9")).toBe("latest");
+  });
+});
+
+describe("compareVersions", () => {
+  test("orders patch versions", () => {
+    expect(compareVersions("0.7.5", "0.7.4")).toBeGreaterThan(0);
+    expect(compareVersions("0.7.4", "0.7.5")).toBeLessThan(0);
+    expect(compareVersions("0.7.5", "0.7.5")).toBe(0);
+  });
+
+  test("orders rc chains numerically, not lexically", () => {
+    // The lexical trap: "rc.10" < "rc.9" as strings.
+    expect(compareVersions("0.7.5-rc.10", "0.7.5-rc.9")).toBeGreaterThan(0);
+    expect(compareVersions("0.7.5-rc.5", "0.7.5-rc.6")).toBeLessThan(0);
+  });
+
+  test("a release sorts above its own prereleases", () => {
+    expect(compareVersions("0.7.5", "0.7.5-rc.99")).toBeGreaterThan(0);
+  });
+
+  test("major/minor dominate the prerelease suffix", () => {
+    expect(compareVersions("0.8.0-rc.1", "0.7.9")).toBeGreaterThan(0);
+  });
+});
+
+describe("decidePublish", () => {
+  test("a fresh version publishes", () => {
+    const d = decidePublish("0.7.9-rc.2", {
+      versionExists: false,
+      currentDistTagVersion: "0.7.9-rc.1",
+    });
+    expect(d).toMatchObject({ publish: true });
+  });
+
+  test("an already-published version is skipped — the idempotency guarantee", () => {
+    const d = decidePublish("0.7.9-rc.1", { versionExists: true });
+    expect(d).toMatchObject({ publish: false });
+  });
+
+  test("a never-published package SKIPS on a branch push — a first publish is deliberate", () => {
+    // surface#220 / hub#930 / app#189: a 404 package used to read "0.1.0 is
+    // not on npm" → should_publish=true, and the OIDC publish 404'd. Vault's
+    // inline shell had the same hole: curling /vault/$VERSION 404s for both
+    // "version missing" and "package missing".
+    const d = decidePublish(
+      "0.1.0",
+      { versionExists: false, publishedVersions: [] },
+      { branch: "main" },
+    );
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/first publish is a deliberate act/);
+    expect("reason" in d && d.reason).toMatch(/cannot create a package/);
+  });
+
+  test("an rc of a never-published package skips too — it's the package, not the channel", () => {
+    const d = decidePublish(
+      "0.1.0-rc.1",
+      { versionExists: false, publishedVersions: [] },
+      { branch: "next" },
+    );
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/nothing is published under this name yet/);
+  });
+
+  test("omitted publishedVersions with no dist-tag reads as never-published — skip, don't publish", () => {
+    const d = decidePublish("0.1.0-rc.1", { versionExists: false });
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/nothing is published under this name yet/);
+  });
+
+  test("a never-published package on an rc TAG PUSH still tries — a human said release this", () => {
+    const d = decidePublish(
+      "0.1.0-rc.1",
+      { versionExists: false, publishedVersions: [] },
+      { isTagPush: true },
+    );
+    expect(d).toMatchObject({ publish: true });
+    expect("reason" in d && d.reason).toMatch(/explicit tag push/);
+  });
+
+  test("a never-published STABLE on a tag push is still refused by the from-main gate", () => {
+    const d = decidePublish(
+      "0.1.0",
+      { versionExists: false, publishedVersions: [] },
+      { isTagPush: true },
+    );
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/from main only/);
+  });
+
+  test("an existing package is unaffected — one published version is enough", () => {
+    const d = decidePublish(
+      "0.7.9-rc.2",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.7.9-rc.1",
+        publishedVersions: ["0.7.9-rc.1"],
+      },
+      { branch: "next" },
+    );
+    expect(d).toMatchObject({ publish: true });
+    expect("reason" in d && d.reason).toMatch(/is not on npm/);
+  });
+
+  test("an unreadable registry is still a REFUSAL, not a never-published skip", () => {
+    const ambiguous = decidePublish("0.7.9-rc.1", { ambiguous: true }, { branch: "next" });
+    expect(ambiguous).toMatchObject({ refuse: true });
+    expect("refuse" in ambiguous && ambiguous.reason).toMatch(/refusing to guess/);
+  });
+
+  test("REFUSES to move a dist-tag backwards — the parallel-merge hazard", () => {
+    const d = decidePublish("0.7.5-rc.5", {
+      versionExists: false,
+      currentDistTagVersion: "0.7.5-rc.6",
+    });
+    expect(d).toMatchObject({ refuse: true });
+    expect("refuse" in d && d.reason).toMatch(/OLDER than the current rc/);
+    expect("refuse" in d && d.reason).toMatch(/merged out of version order/);
+  });
+
+  test("rc and latest are tracked independently", () => {
+    const d = decidePublish("0.8.0-rc.1", {
+      versionExists: false,
+      currentDistTagVersion: "0.7.9-rc.5",
+    });
+    expect(d).toMatchObject({ publish: true });
+  });
+
+  test("an ambiguous registry REFUSES rather than guessing", () => {
+    const d = decidePublish("0.7.9", { ambiguous: true }, { branch: "main" });
+    expect(d).toMatchObject({ refuse: true });
+    expect("refuse" in d && d.reason).toMatch(/refusing to guess/);
+  });
+
+  test("an explicit rc tag push overrides the registry checks — a human said release this rc", () => {
+    const d = decidePublish(
+      "0.7.0-rc.1",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.8.0",
+      },
+      { isTagPush: true },
+    );
+    expect(d).toMatchObject({ publish: true });
+  });
+
+  test("an rc tag push even overrides ambiguity", () => {
+    const d = decidePublish("0.7.9-rc.1", { ambiguous: true }, { isTagPush: true });
+    expect(d).toMatchObject({ publish: true });
+  });
+
+  test("next skips a stable version — stables publish from main only", () => {
+    const d = decidePublish("0.7.9", { versionExists: false }, { branch: "next" });
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/stable promotions publish from main only/);
+  });
+
+  test("next still publishes an rc", () => {
+    const d = decidePublish(
+      "0.7.9-rc.1",
+      { versionExists: false, currentDistTagVersion: "0.7.8-rc.5" },
+      { branch: "next" },
+    );
+    expect(d).toMatchObject({ publish: true });
+  });
+
+  test("main is unaffected — stable publishes as before", () => {
+    const d = decidePublish(
+      "0.7.9",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.7.8",
+        publishedVersions: ["0.7.8"],
+      },
+      { branch: "main" },
+    );
+    expect(d).toMatchObject({ publish: true });
+  });
+
+  test("a tag push of a stable does NOT override the main-only gate", () => {
+    const d = decidePublish(
+      "0.7.9",
+      { versionExists: false },
+      { branch: "next", isTagPush: true },
+    );
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/from main only/);
+  });
+
+  test("a stable with no branch is refused — fail closed, don't guess the trigger", () => {
+    const d = decidePublish("0.7.9", { versionExists: false });
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/from main only/);
+  });
+});
+
+describe("readRegistry", () => {
+  const json = (body: unknown, status = 200) =>
+    Promise.resolve(new Response(JSON.stringify(body), { status }));
+
+  test("reads existence + the relevant dist-tag", async () => {
+    const v = await readRegistry("@openparachute/vault", "0.7.9-rc.2", (() =>
+      json({
+        versions: { "0.7.9-rc.1": {}, "0.7.9-rc.2": {} },
+        "dist-tags": { rc: "0.7.9-rc.2", latest: "0.7.8" },
+      })) as unknown as typeof fetch);
+    expect(v).toMatchObject({ versionExists: true, currentDistTagVersion: "0.7.9-rc.2" });
+  });
+
+  test("picks the dist-tag matching the version's channel", async () => {
+    const v = await readRegistry("@openparachute/vault", "0.7.9", (() =>
+      json({
+        versions: {},
+        "dist-tags": { rc: "0.7.9-rc.2", latest: "0.7.8" },
+      })) as unknown as typeof fetch);
+    expect(v).toMatchObject({ currentDistTagVersion: "0.7.8" });
+  });
+
+  test("a never-published package is not ambiguous — a 404 is knowledge", async () => {
+    const v = await readRegistry("@openparachute/new", "0.1.0", (() =>
+      json({}, 404)) as unknown as typeof fetch);
+    expect(v).toMatchObject({ versionExists: false, publishedVersions: [] });
+  });
+
+  test("the 404 view composes into a skip — the two halves of surface#220 line up", async () => {
+    const v = await readRegistry("@openparachute/new", "0.1.0", (() =>
+      json({}, 404)) as unknown as typeof fetch);
+    expect("ambiguous" in v).toBe(false);
+    if ("ambiguous" in v) return;
+    const d = decidePublish("0.1.0", v, { branch: "main" });
+    expect(d).toMatchObject({ publish: false });
+    expect("reason" in d && d.reason).toMatch(/first publish is a deliberate act/);
+  });
+
+  test("a populated registry returns publishedVersions", async () => {
+    const v = await readRegistry("@openparachute/vault", "0.7.9-rc.3", (() =>
+      json({
+        versions: { "0.7.9-rc.1": {}, "0.7.9-rc.2": {} },
+        "dist-tags": { rc: "0.7.9-rc.2", latest: "0.7.8" },
+      })) as unknown as typeof fetch);
+    expect(v).toMatchObject({
+      versionExists: false,
+      currentDistTagVersion: "0.7.9-rc.2",
+      publishedVersions: ["0.7.9-rc.1", "0.7.9-rc.2"],
+    });
+  });
+
+  test("a 5xx is ambiguous", async () => {
+    const v = await readRegistry("@openparachute/vault", "1.0.0", (() =>
+      json({}, 503)) as unknown as typeof fetch);
+    expect(v).toMatchObject({ ambiguous: true });
+  });
+
+  test("a network throw is ambiguous, not a crash", async () => {
+    const v = await readRegistry("@openparachute/vault", "1.0.0", (() =>
+      Promise.reject(new Error("ECONNRESET"))) as unknown as typeof fetch);
+    expect(v).toMatchObject({ ambiguous: true });
+  });
+});
+
+describe("unpublishedDrift", () => {
+  test("no commits → not drifted", () => {
+    expect(unpublishedDrift([]).drifted).toBe(false);
+    expect(unpublishedDrift(["", "  "]).drifted).toBe(false);
+  });
+
+  test("commits → drifted, counted, and LISTED", () => {
+    const d = unpublishedDrift(["abc feat: one", "def fix: two"]);
+    expect(d.drifted).toBe(true);
+    expect(d.count).toBe(2);
+    expect(d.summary).toContain("feat: one");
+    expect(d.summary).toContain("fix: two");
+    expect(d.summary).toMatch(/release PR/i);
+  });
+
+  test("blank lines from git's trailing newline don't inflate the count", () => {
+    expect(unpublishedDrift(["abc one", ""]).count).toBe(1);
+  });
+});

package/src/routing.ts

@@ -1135,9 +1135,14 @@ export async function route(
 
   // 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.
+  // `operator` for the env-var bearer, `nostr:<pubkey>` when the hub stamped a
+  // NIP-98 signing key — vault#698). 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`, via `refineMcpVia`). That gives the REST door
+  // signer attribution for free and symmetric with MCP: `nostr:<pubkey>` is
+  // already the base value, so it lands in `created_via`/`last_updated_via`
+  // unchanged. Pinned by src/attribution-threading.test.ts. 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