@openparachute/vault 0.4.8 → 0.4.9-rc.11

package/core/src/store.ts

@@ -4,6 +4,12 @@ import { initSchema } from "./schema.js";
 import * as noteOps from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
+import * as indexedFieldOps from "./indexed-fields.js";
+import {
+  pruneOrphanedIndexedFields,
+  reconcileDeclaredIndexes,
+  type PrunedField,
+} from "./indexed-fields.js";
 import { syncWikilinks, resolveUnresolvedWikilinks } from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
 import { HookRegistry } from "./hooks.js";
@@ -217,10 +223,23 @@ export class BunSqliteStore implements Store {
   }
 
   async deleteNote(id: string): Promise<void> {
-    // Read before delete so we can invalidate config caches on the way out.
+    // Read before delete so we can invalidate config caches on the way out
+    // AND so the post-delete hook dispatch carries the minimum payload
+    // ({ id, path }). The full note can't be reconstructed post-delete —
+    // by design, hooks subscribing to "deleted" receive a DeletedNoteRef,
+    // not a Note.
     const existing = noteOps.getNote(this.db, id);
     noteOps.deleteNote(this.db, id);
     if (existing?.path) this.invalidateConfigCachesForPath(existing.path);
+    // Dispatch even when `existing` was null — the caller asked for a
+    // deletion, and downstream consumers (e.g. the mirror) reconcile via
+    // id. Path is undefined in that case; the mirror sweep will catch
+    // any orphans missed by the targeted-removal fast path.
+    this.hooks.dispatch(
+      "deleted",
+      { id, ...(existing?.path ? { path: existing.path } : {}) },
+      this,
+    );
   }
 
   async queryNotes(opts: QueryOpts): Promise<Note[]> {
@@ -340,6 +359,10 @@ export class BunSqliteStore implements Store {
     // and may have declared `fields` powering schema validation.
     this._tagHierarchy = null;
     this._schemaConfig = null;
+    // Fire "deleted" only when SOMETHING happened (the underlying
+    // deleteTag returns `deleted: false` when the tag didn't exist).
+    // The git-mirror reacts to this by sweeping the schema sidecar.
+    if (result.deleted) this.hooks.dispatchTag("deleted", name, this);
     return result;
   }
 
@@ -352,6 +375,16 @@ export class BunSqliteStore implements Store {
     // the schema-config by parent_names + fields content.
     this._tagHierarchy = null;
     this._schemaConfig = null;
+    // Rename = delete-then-upsert from the perspective of any consumer
+    // that keys schema artifacts on the tag name (e.g. the git-mirror's
+    // `.parachute/schemas/<tag>.yaml` sidecar file). Fire both events
+    // so the consumer drops the old artifact and writes the new one.
+    // Only dispatch when the rename actually happened — error returns
+    // ({ error: ... }) shouldn't notify subscribers about phantom moves.
+    if ("renamed" in result) {
+      this.hooks.dispatchTag("deleted", oldName, this);
+      this.hooks.dispatchTag("upserted", newName, this);
+    }
     return result;
   }
 
@@ -365,6 +398,15 @@ export class BunSqliteStore implements Store {
     // bust the schema cache — `fields` declarations follow tag identity.
     this._tagHierarchy = null;
     this._schemaConfig = null;
+    // Each merged source vanishes from the tag set; the target's
+    // schema may have absorbed fields/relationships from the sources.
+    // Fire "deleted" for each source and "upserted" for the target so
+    // the mirror sweeps the source sidecars and rewrites the target.
+    for (const source of sources) {
+      if (source === target) continue;
+      this.hooks.dispatchTag("deleted", source, this);
+    }
+    this.hooks.dispatchTag("upserted", target, this);
     return result;
   }
 
@@ -440,12 +482,26 @@ export class BunSqliteStore implements Store {
     // `fields` drives validation — bust the schema cache so the next
     // create/update sees the new declarations.
     this._schemaConfig = null;
+    // The tag schema sidecar in the mirror needs to track this. Fire
+    // "upserted" regardless of whether the row was created or modified
+    // — the mirror writes the sidecar fresh either way.
+    this.hooks.dispatchTag("upserted", tag, this);
     return result;
   }
 
   async deleteTagSchema(tag: string) {
     const result = tagSchemaOps.deleteTagSchema(this.db, tag);
-    if (result) this._schemaConfig = null;
+    if (result) {
+      this._schemaConfig = null;
+      // Schema-only delete: the tag may still exist as a name in the
+      // hierarchy, but the sidecar lost its content. Mirror reacts by
+      // sweeping the sidecar file. (If the underlying row was reduced
+      // to a bare name with no schema content, hasSchemaContent() in
+      // exportVaultToDir already wouldn't have written it on the next
+      // export pass — the targeted delete is the fast path; the sweep
+      // is the safety net.)
+      this.hooks.dispatchTag("deleted", tag, this);
+    }
     return result;
   }
 
@@ -453,6 +509,37 @@ export class BunSqliteStore implements Store {
     return tagSchemaOps.getTagSchemaMap(this.db);
   }
 
+  // ---- Indexed-field lifecycle (generated columns + indexes) ----
+
+  /**
+   * Prune orphaned `indexed_fields` declarers — declarer tags that no longer
+   * have a `tags` row. Fields with no surviving live declarer are dropped
+   * wholesale (row + generated column + index); co-declared fields keep their
+   * column and just lose the dead declarers. `dryRun` (default true) returns
+   * the plan without mutating. See the gitcoin orphaned-fields bug.
+   */
+  async pruneIndexedFields(opts?: { dryRun?: boolean }): Promise<PrunedField[]> {
+    const plan = pruneOrphanedIndexedFields(this.db, opts);
+    // A drop changes the queryable-field catalog vault-info advertises; bust
+    // the schema cache so the next read reflects it.
+    if (opts?.dryRun === false && plan.length > 0) this._schemaConfig = null;
+    return plan;
+  }
+
+  /**
+   * Replay `declareField` for every `indexed: true` field across all current
+   * tag records, materializing the generated columns + indexes. Idempotent —
+   * used by the portable-md import path so a fresh import ends with the same
+   * backing columns a live vault would have. Returns the count of (tag, field)
+   * declarations replayed.
+   */
+  async reconcileDeclaredIndexes(): Promise<number> {
+    const schemas = await this.listTagRecords();
+    const count = reconcileDeclaredIndexes(this.db, schemas);
+    if (count > 0) this._schemaConfig = null;
+    return count;
+  }
+
   // ---- Tag Records (post-v14: full identity row) ----
 
   async listTagRecords() {
@@ -467,6 +554,18 @@ export class BunSqliteStore implements Store {
    * Partial upsert of the full tag record. Any patch field left undefined
    * is preserved; pass null to clear. Invalidates the tag-hierarchy cache
    * when `parent_names` is touched.
+   *
+   * Indexed-field lifecycle is reconciled HERE — at the single store
+   * chokepoint every caller (MCP update-tag, REST PUT /tags/:name, import)
+   * funnels through — so no caller can persist a `fields` change without the
+   * matching declareField/releaseField. When `patch.fields` is touched
+   * (object or explicit `null`), the prior-vs-next indexed-field set is
+   * diffed: added indexed fields get `declareField`, removed ones get
+   * `releaseField` (which drops the generated column + index only when this
+   * tag is the last live declarer — the co-declaration guard). `patch.fields
+   * === undefined` (no-touch) skips reconciliation entirely. Centralizing
+   * here is the same discipline as moving delete-release into noteOps.deleteTag
+   * — it closes the REST PUT orphaned-column leak. See the gitcoin bug.
    */
   async upsertTagRecord(
     tag: string,
@@ -477,7 +576,43 @@ export class BunSqliteStore implements Store {
       parent_names?: string[] | null;
     },
   ) {
+    // Snapshot the prior indexed-field set BEFORE the write so the diff below
+    // sees what this tag declared going in. Only needed when `fields` changes.
+    const priorRecord =
+      patch.fields !== undefined ? tagSchemaOps.getTagRecord(this.db, tag) : null;
+
     const result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+
+    if (patch.fields !== undefined) {
+      const indexedSet = (fields: Record<string, tagSchemaOps.TagFieldSchema> | null | undefined) =>
+        new Set(
+          Object.entries(fields ?? {})
+            .filter(([, v]) => v.indexed === true)
+            .map(([k]) => k),
+        );
+      const nextFields = patch.fields; // object | null
+      const priorIndexed = indexedSet(priorRecord?.fields);
+      const nextIndexed = indexedSet(nextFields);
+      for (const fieldName of nextIndexed) {
+        const spec = nextFields![fieldName]!;
+        const mapped = indexedFieldOps.mapFieldType(spec.type);
+        // Unmappable type for indexing is a caller error; surface it rather
+        // than silently skipping. MCP/REST validate up-front for a cleaner
+        // message, but this is the backstop at the chokepoint.
+        if (!mapped) {
+          throw new indexedFieldOps.IndexedFieldError(
+            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
+          );
+        }
+        indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
+      }
+      for (const fieldName of priorIndexed) {
+        if (!nextIndexed.has(fieldName)) {
+          indexedFieldOps.releaseField(this.db, fieldName, tag);
+        }
+      }
+    }
+
     if (patch.parent_names !== undefined) {
       // parent_names drives both query expansion (tag hierarchy) AND, post
       // vault#270, schema inheritance — bust both caches.
@@ -494,6 +629,11 @@ export class BunSqliteStore implements Store {
       this._tagHierarchy = null;
       this._schemaConfig = null;
     }
+    // Tag-mutation event for the git-mirror and any other downstream
+    // consumer. Fire "upserted" on every successful tag-record write —
+    // schema/relationship/parent-name mutations all alter the sidecar
+    // contents the mirror persists.
+    this.hooks.dispatchTag("upserted", tag, this);
     return result;
   }
 
@@ -599,6 +739,17 @@ export class BunSqliteStore implements Store {
     const other = this.db.prepare(
       "SELECT 1 FROM attachments WHERE path = ? LIMIT 1",
     ).get(row.path);
+
+    // Post-delete event for downstream consumers (e.g. the git-mirror's
+    // sweep of `.parachute/attachments/<id>/...`). Payload is the
+    // DeletedAttachmentRef — the row is gone, so we pass only id /
+    // note_id / path.
+    this.hooks.dispatchAttachment(
+      "deleted",
+      { id: attachmentId, noteId, path: row.path },
+      this,
+    );
+
     return { deleted: true, path: row.path, orphaned: !other };
   }
 
@@ -621,6 +772,38 @@ export class BunSqliteStore implements Store {
     };
   }
 
+  /**
+   * Reverse-lookup: every attachment row whose `path` column equals the given
+   * vault-internal relative path (`<date>/<filename>`). A single on-disk asset
+   * can be referenced by more than one attachment row (the orphan check in
+   * `deleteAttachment` accounts for that), so this returns an array. Used by
+   * the raw `/api/storage/<date>/<file>` byte-serve path to map a requested
+   * file back to its owning note(s) for tag-scope enforcement — without this,
+   * a tag-scoped token could fetch an out-of-scope note's attachment bytes
+   * directly by path (the path-secrecy-only bypass; see the C0 adversarial
+   * audit finding).
+   */
+  async getAttachmentsByPath(path: string): Promise<Attachment[]> {
+    const rows = this.db.prepare(
+      "SELECT * FROM attachments WHERE path = ? ORDER BY created_at",
+    ).all(path) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string }[];
+
+    return rows.map((r) => {
+      let metadata: Record<string, unknown> | undefined;
+      if (r.metadata && r.metadata !== "{}") {
+        try { metadata = JSON.parse(r.metadata); } catch {}
+      }
+      return {
+        id: r.id,
+        noteId: r.note_id,
+        path: r.path,
+        mimeType: r.mime_type,
+        metadata,
+        createdAt: r.created_at,
+      };
+    });
+  }
+
   /**
    * Replace the attachment's metadata JSON blob. The caller passes the full
    * merged object — this is a set, not a patch, so partial-field updates

package/core/src/types.ts

@@ -1,8 +1,10 @@
 import type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+import type { PrunedField } from "./indexed-fields.js";
 
 // ---- Re-exports ----
 
 export type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+export type { PrunedField } from "./indexed-fields.js";
 
 // ---- Note ----
 
@@ -278,6 +280,24 @@ export interface Store {
   deleteTagSchema(tag: string): Promise<boolean>;
   getTagSchemaMap(): Promise<Record<string, { description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[]; indexed?: boolean }> }>>;
 
+  // Indexed-field lifecycle — generated columns + indexes on `notes` derived
+  // from tag-declared `indexed: true` fields. See core/src/indexed-fields.ts.
+
+  /**
+   * Prune orphaned `indexed_fields` declarers — declarer tags with no `tags`
+   * row. Fields left with no live declarer are dropped wholesale; co-declared
+   * fields keep their column and lose only the dead declarers. `dryRun`
+   * (default true) returns the plan without mutating.
+   */
+  pruneIndexedFields(opts?: { dryRun?: boolean }): Promise<PrunedField[]>;
+  /**
+   * Replay `declareField` for every `indexed: true` field across all current
+   * tag records, materializing the backing columns + indexes. Idempotent —
+   * used by the import path so a fresh import has the same columns a live
+   * vault would. Returns the count of (tag, field) declarations replayed.
+   */
+  reconcileDeclaredIndexes(): Promise<number>;
+
   // Tag records — full v14 identity row (description + fields + typed
   // relationships + parent_names + timestamps). See
   // parachute-patterns/patterns/tag-data-model.md.
@@ -322,6 +342,14 @@ export interface Store {
   addAttachment(noteId: string, path: string, mimeType: string, metadata?: Record<string, unknown>): Promise<Attachment>;
   getAttachments(noteId: string): Promise<Attachment[]>;
   getAttachment(attachmentId: string): Promise<Attachment | null>;
+  /**
+   * Reverse-lookup attachment rows by their vault-internal relative `path`
+   * (`<date>/<filename>`). Returns every row sharing that path (a single
+   * on-disk asset can be referenced by >1 row). Used by the raw
+   * `/api/storage/<date>/<file>` serve path to map a requested file back to
+   * its owning note(s) for tag-scope enforcement.
+   */
+  getAttachmentsByPath(path: string): Promise<Attachment[]>;
   setAttachmentMetadata(attachmentId: string, metadata: Record<string, unknown>): Promise<void>;
   deleteAttachment(noteId: string, attachmentId: string): Promise<{ deleted: boolean; path: string | null; orphaned: boolean }>;
   listAttachmentsByTranscribeStatus(status: "pending" | "failed" | "done", limit?: number): Promise<Attachment[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.8",
+  "version": "0.4.9-rc.11",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@openparachute/scope-guard": "^0.3.0",
+    "@openparachute/scope-guard": "^0.4.0-rc.2",
     "jose": "^6.2.2",
     "otpauth": "^9.5.0",
     "qrcode-terminal": "^0.12.0"

package/src/auth-hub-jwt.test.ts

@@ -105,6 +105,13 @@ interface SignOpts {
    * a hub-minted admin token; provide `["<name>"]` for a non-admin user.
    */
   vaultScope?: string[];
+  /**
+   * `permissions` claim (auth-unification arc, C0). Undefined → omit
+   * entirely (today's hub-JWT shape → unscoped). Provide
+   * `{ scoped_tags: [...] }` for a tag-scoped token, or a deliberately
+   * malformed value to exercise the fail-closed path.
+   */
+  permissions?: unknown;
 }
 
 async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
@@ -115,6 +122,7 @@ async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
     client_id: "test-client",
   };
   if (opts.vaultScope !== undefined) payload.vault_scope = opts.vaultScope;
+  if (opts.permissions !== undefined) payload.permissions = opts.permissions;
   return await new SignJWT(payload)
     .setProtectedHeader({ alg: "RS256", kid: kp.kid })
     .setIssuer(opts.iss)
@@ -518,3 +526,142 @@ describe("authenticateVaultRequest — hub JWT integration", () => {
     }
   });
 });
+
+describe("authenticateVaultRequest — hub JWT tag-scoping (auth-unification C0)", () => {
+  // Helper: pull a successful AuthResult out of authenticateVaultRequest,
+  // failing the test loudly if auth returned an error Response.
+  async function authOk(
+    token: string,
+    vaultName: string,
+  ): Promise<import("./auth.ts").AuthResult> {
+    const config = readVaultConfig(vaultName)!;
+    const store = getVaultStore(vaultName);
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    if ("error" in result) {
+      const body = await result.error.json();
+      throw new Error(`expected AuthResult, got ${result.error.status}: ${JSON.stringify(body)}`);
+    }
+    return result;
+  }
+
+  test("permissions.scoped_tags:[health] → AuthResult.scoped_tags=[health]; query-notes enforces (health visible, work hidden)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // Seed two notes: one tagged health, one tagged work.
+    await store.createNote("blood pressure log", { path: "h1", tags: ["health"] });
+    await store.createNote("quarterly OKRs", { path: "w1", tags: ["work"] });
+
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+      permissions: { scoped_tags: ["health"] },
+    });
+
+    const auth = await authOk(token, "journal");
+    // The READ side: the allowlist is lifted off the validated token.
+    expect(auth.scoped_tags).toEqual(["health"]);
+
+    // End-to-end enforcement: the tag-scope-wrapped query-notes tool must
+    // hide the `work` note and surface the `health` note.
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const tools = generateScopedMcpTools("journal", auth);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({})) as any;
+    const notes = Array.isArray(result) ? result : result.notes;
+    const paths = notes.map((n: any) => n.path).sort();
+    expect(paths).toEqual(["h1"]);
+    expect(paths).not.toContain("w1");
+  });
+
+  test("no permissions claim → scoped_tags=null (unscoped, full vault — regression: unchanged)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("a", { path: "h1", tags: ["health"] });
+    await store.createNote("b", { path: "w1", tags: ["work"] });
+
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+      // permissions intentionally omitted — today's hub-JWT shape
+    });
+
+    const auth = await authOk(token, "journal");
+    expect(auth.scoped_tags).toBeNull();
+
+    const { generateScopedMcpTools } = await import("./mcp-tools.ts");
+    const tools = generateScopedMcpTools("journal", auth);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({})) as any;
+    const notes = Array.isArray(result) ? result : result.notes;
+    const paths = notes.map((n: any) => n.path).sort();
+    // Unscoped: BOTH notes visible.
+    expect(paths).toEqual(["h1", "w1"]);
+  });
+
+  test("permissions present but scoped_tags absent → scoped_tags=null (unscoped)", async () => {
+    seedVault("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+      permissions: { some_other_perm: true },
+    });
+    const auth = await authOk(token, "journal");
+    expect(auth.scoped_tags).toBeNull();
+  });
+
+  test("permissions.scoped_tags:null → scoped_tags=null (explicit unscoped)", async () => {
+    seedVault("journal");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+      permissions: { scoped_tags: null },
+    });
+    const auth = await authOk(token, "journal");
+    expect(auth.scoped_tags).toBeNull();
+  });
+
+  // ---- Fail-closed cases: present-but-malformed scoped_tags MUST 401, ----
+  // ---- never silently widen to full-vault. ----
+  for (const [label, badValue] of [
+    ["a string", "health"],
+    ["a number", 42],
+    ["an object", { health: true }],
+    ["an array with a non-string", ["health", 5]],
+    ["an array with an empty string", ["health", ""]],
+    ["an empty array", []],
+  ] as Array<[string, unknown]>) {
+    test(`malformed scoped_tags (${label}) → 401 fail-closed (does NOT widen to full vault)`, async () => {
+      seedVault("journal");
+      const token = await signJwt(kp, {
+        iss: fixture.origin,
+        aud: "vault.journal",
+        scope: "vault:journal:read",
+        permissions: { scoped_tags: badValue },
+      });
+      const config = readVaultConfig("journal")!;
+      const store = getVaultStore("journal");
+
+      const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const result = await authenticateVaultRequest(bearer(token), config, store.db);
+        // The whole request is rejected — NOT served with scoped_tags=null
+        // (full vault) or scoped_tags=[] (also full vault on the MCP path).
+        expect("error" in result).toBe(true);
+        if ("error" in result) {
+          expect(result.error.status).toBe(401);
+          const body = (await result.error.json()) as { error: string; message: string };
+          expect(body.error).toBe("Unauthorized");
+          expect(body.message).toContain("malformed tag-scope");
+        }
+        // Audit log carries the diagnostic.
+        expect(warnSpy).toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+  }
+});

package/src/auth.ts

@@ -91,6 +91,12 @@ function tryServerWideAuth(
     legacyDerived: false,
     scoped_tags: null,
     vault_name: null,
+    // No stable session id for the env-var operator token — every request
+    // is the operator-bearer, not a minted session. manage-token's session
+    // pin is a no-op for this caller (it'd still mint, but list/revoke
+    // would see no other operator mints; that's fine — env-var-bearer is
+    // explicitly the operator-channel, not a user surface).
+    caller_jti: null,
   };
 }
 
@@ -120,6 +126,15 @@ export interface AuthResult {
    * legacy / server-wide / hub JWT — no per-vault binding. See vault#257.
    */
   vault_name: string | null;
+  /**
+   * Session identifier (v19). For `pvt_*` tokens this is the display id
+   * (`t_<hashprefix>`) of the presented token. For hub JWTs it's the
+   * `jti` claim, when present. NULL for legacy YAML keys / server-wide
+   * env-var tokens / hub JWTs without a `jti`. Used by the manage-token
+   * MCP tool to stamp child tokens with `parent_jti` so list/revoke can
+   * scope to this session's mints. See vault#376.
+   */
+  caller_jti: string | null;
 }
 
 /**
@@ -134,6 +149,7 @@ function legacyAuthResult(permission: TokenPermission): AuthResult {
     legacyDerived: true,
     scoped_tags: null,
     vault_name: null,
+    caller_jti: null,
   };
 }
 
@@ -285,6 +301,7 @@ export async function authenticateVaultRequest(
           legacyDerived: resolved.legacyDerived,
           scoped_tags: resolved.scoped_tags,
           vault_name: resolved.vault_name,
+          caller_jti: resolved.jti,
         };
       }
     } catch {
@@ -314,6 +331,75 @@ export async function authenticateVaultRequest(
   return { error: Response.json({ error: "Unauthorized", message: "Invalid API key" }, { status: 401 }) };
 }
 
+/**
+ * Sentinel thrown when a hub JWT carries a `permissions.scoped_tags` claim
+ * that is present but malformed (not an array of non-empty strings). See
+ * `parseScopedTagsFromPermissions` for why this MUST fail closed.
+ */
+class MalformedScopedTagsError extends Error {}
+
+/**
+ * Map a validated hub JWT's `permissions` claim into the `scoped_tags`
+ * allowlist for `AuthResult` (auth-unification arc, C0 — the READ side).
+ *
+ * Wire contract (the shape the SPA + manage-token mint sides target):
+ *
+ *   permissions: { scoped_tags: string[] }   // root tag names
+ *
+ * Same semantics as the deprecated `pvt_*` `scoped_tags` DB column: each
+ * entry is a ROOT tag name; the token sees notes carrying that tag or a
+ * sub-tag thereof (hierarchy expansion happens in tag-scope.ts).
+ *
+ * Three outcomes, chosen for a strict FAIL-CLOSED invariant — tag-scoping is
+ * always a RESTRICTION, so a misread must NEVER widen access:
+ *
+ *   1. Claim absent (no `permissions`, or no `scoped_tags` key) → returns
+ *      `null` = UNSCOPED = full vault. This is legitimate and is today's
+ *      behavior for every hub JWT. Absence genuinely means "not tag-scoped".
+ *
+ *   2. `scoped_tags` is a non-empty array of non-empty strings → returns
+ *      that array. The token is tag-scoped; the allowlist is enforced.
+ *
+ *   3. `scoped_tags` is present but MALFORMED — a string, a number, an
+ *      object, an array containing a non-string / empty-string, or an empty
+ *      array `[]` — throws `MalformedScopedTagsError`. The caller REJECTS
+ *      the request (401). We do NOT coerce to `null` or `[]`:
+ *
+ *      - Coercing to `null` would WIDEN a token that was MEANT to be scoped
+ *        up to full-vault — a privilege leak. Forbidden.
+ *      - Coercing to `[]` is NOT reliably fail-closed across enforcement
+ *        paths. The MCP read-tool wrappers fast-path out on
+ *        `scoped_tags.length === 0` (mcp-tools.ts ~L178) and the REST path
+ *        collapses `[]` → null inside `expandTokenTagScope` (tag-scope.ts
+ *        ~L35) — both treat `[]` as UNSCOPED = full vault. So `[]` would
+ *        ALSO widen. (Note: `filterNotesByTagScope`/`noteWithinTagScope`
+ *        would treat a raw `[]` as "matches nothing", but the call sites
+ *        never reach them with `[]` because of the upstream short-circuits —
+ *        the two enforcement paths disagree on `[]`, which is exactly why we
+ *        refuse to manufacture it here.)
+ *
+ *      The only correct fail-closed action for a present-but-unreadable
+ *      scope is to reject the whole request — never serve it wide.
+ */
+function parseScopedTagsFromPermissions(
+  permissions: Record<string, unknown> | undefined,
+): string[] | null {
+  if (!permissions || !("scoped_tags" in permissions)) return null;
+  const raw = permissions.scoped_tags;
+  if (raw === null || raw === undefined) return null; // explicit "unscoped"
+  if (
+    Array.isArray(raw) &&
+    raw.length > 0 &&
+    raw.every((t) => typeof t === "string" && t.length > 0)
+  ) {
+    return raw as string[];
+  }
+  // Present but malformed (incl. `[]`): fail closed — never widen.
+  throw new MalformedScopedTagsError(
+    "hub JWT permissions.scoped_tags is present but not a non-empty array of tag names",
+  );
+}
+
 /**
  * Validate a JWT-shaped bearer and convert the result into an `AuthResult`.
  * The token's scope claim becomes the granted scopes; permission is derived
@@ -336,6 +422,12 @@ export async function authenticateVaultRequest(
  * unchanged. The 403 (not 401) signals "your credential is valid but
  * doesn't grant access to this vault" — distinct from authentication
  * failures upstream. See hub#283 + scope-guard 0.3.0 for the mint side.
+ *
+ * Tag-scoping (auth-unification arc, C0): the token's `permissions.scoped_tags`
+ * claim (when present and well-formed) maps into `AuthResult.scoped_tags`,
+ * restricting which notes the token sees. A present-but-malformed claim FAILS
+ * CLOSED with a 401 rather than widening to full-vault — see
+ * `parseScopedTagsFromPermissions`.
  */
 async function authenticateHubJwt(
   token: string,
@@ -396,8 +488,35 @@ async function authenticateHubJwt(
       hasScope(claims.scopes, SCOPE_WRITE) || hasScope(claims.scopes, SCOPE_ADMIN)
         ? "full"
         : "read";
-    return { permission, scopes: claims.scopes, legacyDerived: false, scoped_tags: null, vault_name: null };
+    // C0: read tag-scoping from the validated token's `permissions` claim.
+    // 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);
+    return {
+      permission,
+      scopes: claims.scopes,
+      legacyDerived: false,
+      scoped_tags,
+      vault_name: null,
+      // claims.jti is `undefined` when the issuer didn't stamp one. Pass it
+      // 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,
+    };
   } catch (err) {
+    if (err instanceof MalformedScopedTagsError) {
+      // Fail-closed (C0): a present-but-malformed `permissions.scoped_tags`
+      // means the token wanted to be tag-scoped but we can't read the
+      // allowlist. Reject rather than widen to full-vault. The audit log
+      // carries the diagnostic; the client gets a generic 401.
+      console.warn(`[auth] hub JWT rejected: ${err.message}`);
+      return {
+        error: Response.json(
+          { error: "Unauthorized", message: "token has a malformed tag-scope claim" },
+          { status: 401 },
+        ),
+      };
+    }
     if (err instanceof HubJwtError) {
       // Revocation-related codes get sanitized client messages: server-side
       // audit log carries the full diagnostic (jti for `revoked`,
@@ -511,6 +630,7 @@ export async function authenticateGlobalRequest(
           legacyDerived: resolved.legacyDerived,
           scoped_tags: resolved.scoped_tags,
           vault_name: resolved.vault_name,
+          caller_jti: resolved.jti,
         };
       }
     } catch {