@openparachute/vault 0.3.3 → 0.4.3

package/src/services-manifest.test.ts

@@ -123,6 +123,26 @@ describe("services-manifest", () => {
     }
   });
 
+  test("preserves hub-stamped fields on the row (e.g. installDir from parachute-hub#84)", () => {
+    const { path, cleanup } = tempPath();
+    try {
+      // Pre-existing row carries `installDir` — a field the hub stamps onto
+      // the entry post-install. Vault's self-registration pass must not drop
+      // it, even though `installDir` isn't part of the typed ServiceEntry.
+      const stamped = { ...vault, installDir: "/Users/test/.parachute/vault" };
+      writeFileSync(path, `${JSON.stringify({ services: [stamped] }, null, 2)}\n`);
+      const updated = { ...vault, version: "0.4.0" };
+      upsertService(updated, path);
+      const m = readManifest(path);
+      expect(m.services).toHaveLength(1);
+      const row = m.services[0] as ServiceEntry & { installDir?: string };
+      expect(row.version).toBe("0.4.0"); // vault's field wins
+      expect(row.installDir).toBe("/Users/test/.parachute/vault"); // hub's field survives
+    } finally {
+      cleanup();
+    }
+  });
+
   test("default path honors PARACHUTE_HOME set at runtime", () => {
     const dir = mkdtempSync(join(tmpdir(), "pvault-home-"));
     const prior = process.env.PARACHUTE_HOME;

package/src/services-manifest.ts

@@ -46,7 +46,10 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (typeof version !== "string") {
     throw new ServicesManifestError(`${where}: "version" must be a string`);
   }
-  return { name, port, paths: paths as string[], health, version };
+  // Spread the raw object first so hub-stamped fields (e.g. `installDir` from
+  // parachute-hub#84) ride through the read. The strict fields below pin the
+  // typed shape we promise callers; anything extra survives untouched.
+  return { ...e, name, port, paths: paths as string[], health, version } as ServiceEntry;
 }
 
 function validateManifest(raw: unknown, where: string): ServicesManifest {
@@ -90,7 +93,11 @@ export function upsertService(
   const current = readManifest(path);
   const idx = current.services.findIndex((s) => s.name === entry.name);
   if (idx >= 0) {
-    current.services[idx] = entry;
+    // Merge rather than replace so fields the hub stamps onto the row
+    // (`installDir` from parachute-hub#84, etc.) survive a self-registration
+    // pass. Vault still wins for the fields it owns — port, paths, version,
+    // health — because `entry` spreads last.
+    current.services[idx] = { ...current.services[idx], ...entry };
   } else {
     current.services.push(entry);
   }

package/src/stop-signal.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Integration test for `parachute-vault stop` — exercises the filesystem
+ * sentinel handshake end-to-end: spawn server → write sentinel → confirm
+ * the server exits cleanly. Closes #100.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync, existsSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
+import { stopSignalPath } from "./config.ts";
+import { waitForHealthy, checkHealth } from "./health.ts";
+
+const SERVER_PATH = resolve(import.meta.dir, "server.ts");
+
+// Pick a port unlikely to clash with the developer's running daemon (1940)
+// or the typical hub/scribe range.
+const TEST_PORT = 19_404;
+
+let tmpHome: string;
+let originalHome: string | undefined;
+
+beforeAll(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), "vault-stop-test-"));
+  mkdirSync(join(tmpHome, "vault"), { recursive: true });
+  originalHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+});
+
+afterAll(() => {
+  if (originalHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = originalHome;
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
+describe("graceful shutdown via stop.signal (#100)", () => {
+  test("stopSignalPath resolves under PARACHUTE_HOME", () => {
+    expect(stopSignalPath()).toBe(join(tmpHome, "vault", "stop.signal"));
+  });
+
+  test("server clears a stale sentinel at startup, then exits when one is written", async () => {
+    // Pre-populate a stale sentinel — the server should clear it on boot
+    // rather than treating it as a fresh shutdown request.
+    writeFileSync(stopSignalPath(), "stale\n");
+    expect(existsSync(stopSignalPath())).toBe(true);
+
+    const proc = Bun.spawn({
+      cmd: ["bun", SERVER_PATH],
+      env: {
+        ...process.env,
+        PARACHUTE_HOME: tmpHome,
+        PORT: String(TEST_PORT),
+        // Avoid the transcription worker spinning up + adding shutdown latency.
+        SCRIBE_URL: "",
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    try {
+      const health = await waitForHealthy(TEST_PORT, { totalMs: 10_000 });
+      expect(health.status).toBe("healthy");
+      expect(existsSync(stopSignalPath())).toBe(false); // stale cleared
+
+      writeFileSync(stopSignalPath(), `${new Date().toISOString()}\n`);
+
+      const exitCode = await Promise.race([
+        proc.exited,
+        new Promise<number>((_, reject) =>
+          setTimeout(() => reject(new Error("server did not exit within 5s")), 5_000),
+        ),
+      ]);
+      expect(exitCode).toBe(0);
+
+      // Server should also have removed the sentinel as it processed it.
+      expect(existsSync(stopSignalPath())).toBe(false);
+
+      // And the port is no longer accepting connections.
+      const after = await checkHealth(TEST_PORT);
+      expect(["not-listening", "error"]).toContain(after.status);
+    } finally {
+      if (!proc.killed) proc.kill();
+    }
+  }, 20_000);
+});

package/src/storage.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Storage upload allowlist tests (issue #127).
+ *
+ * The allowlist guards `POST /api/storage/upload` against turning user
+ * uploads into XSS vectors when the asset is later served back from
+ * `/storage/`. We pin both the accepted set and the deliberate exclusions
+ * so a future widening doesn't quietly let SVG/HTML in.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { rmSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const testDir = join(
+  tmpdir(),
+  `vault-storage-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+);
+process.env.PARACHUTE_HOME = testDir;
+process.env.ASSETS_DIR = join(testDir, "assets");
+
+const { handleStorage } = await import("./routes.ts");
+
+function uploadRequest(filename: string, mimeType: string): Request {
+  const form = new FormData();
+  const file = new File([new Uint8Array([0x00, 0x01, 0x02])], filename, {
+    type: mimeType,
+  });
+  form.set("file", file);
+  return new Request("http://localhost:1940/storage/upload", {
+    method: "POST",
+    body: form,
+  });
+}
+
+beforeAll(() => {
+  mkdirSync(testDir, { recursive: true });
+  mkdirSync(join(testDir, "assets"), { recursive: true });
+});
+
+afterAll(() => {
+  if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
+});
+
+describe("storage upload allowlist", () => {
+  test("accepts .pdf — knowledge-vault content (#127)", async () => {
+    const res = await handleStorage(uploadRequest("paper.pdf", "application/pdf"), "/upload", "default");
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as { mimeType: string; path: string };
+    expect(body.mimeType).toBe("application/pdf");
+    expect(body.path).toMatch(/\.pdf$/);
+  });
+
+  test("accepts .mp4 — mobile capture default (#127)", async () => {
+    const res = await handleStorage(uploadRequest("clip.mp4", "video/mp4"), "/upload", "default");
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as { mimeType: string };
+    expect(body.mimeType).toBe("video/mp4");
+  });
+
+  test("still accepts the existing audio + image set", async () => {
+    for (const [name, mime] of [
+      ["clip.wav", "audio/wav"],
+      ["clip.mp3", "audio/mpeg"],
+      ["photo.png", "image/png"],
+      ["photo.jpg", "image/jpeg"],
+      ["clip.webm", "audio/webm"],
+    ] as const) {
+      const res = await handleStorage(uploadRequest(name, mime), "/upload", "default");
+      expect(res.status).toBe(201);
+    }
+  });
+
+  test("rejects .svg — XSS vector via inline <script> (#127)", async () => {
+    const res = await handleStorage(uploadRequest("evil.svg", "image/svg+xml"), "/upload", "default");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain(".svg");
+  });
+
+  test("rejects .html — same XSS surface as SVG (#127)", async () => {
+    const res = await handleStorage(uploadRequest("evil.html", "text/html"), "/upload", "default");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain(".html");
+  });
+
+  test("rejects unknown extensions (default-deny)", async () => {
+    const res = await handleStorage(uploadRequest("payload.exe", "application/octet-stream"), "/upload", "default");
+    expect(res.status).toBe(400);
+  });
+});

package/src/tag-scope.ts

@@ -0,0 +1,118 @@
+/**
+ * Tag-scope enforcement for tag-scoped tokens (patterns/tag-scoped-tokens.md).
+ *
+ * A token's `scoped_tags` allowlist narrows its effective access to notes
+ * carrying one of the allowlisted tags or a sub-tag thereof. The expansion
+ * to descendants happens via the per-vault `_tags/<name>` config-note
+ * hierarchy (see core/src/tag-hierarchy.ts).
+ *
+ * Auth check pseudocode (from patterns/tag-scoped-tokens.md):
+ *
+ *   if (!hasScope(token, ...)) return forbidden();
+ *   if (token.scoped_tags === null) return ok();   // unscoped
+ *   const noteTags = note.tags;                     // hierarchy-aware
+ *   if (noteTags.some(t => allowlist.includes(rootOf(t)))) return ok();
+ *   return forbidden();
+ *
+ * This module returns the *expanded* allowlist (root + descendants), so
+ * call-sites just intersect with the note's actual tag set — no per-tag
+ * `rootOf` walk is needed at the boundary.
+ */
+
+import type { Store, Note } from "../core/src/types.ts";
+
+/**
+ * Build the effective tag-allowlist for a token: union of `{root} ∪
+ * descendants(root)` for each root in `scoped_tags`. Returns null when the
+ * token is unscoped (no enforcement needed). An empty array also returns
+ * null — defensive parity with the token-store parser, which collapses
+ * `[]` to null.
+ */
+export async function expandTokenTagScope(
+  store: Store,
+  scoped_tags: string[] | null,
+): Promise<Set<string> | null> {
+  if (!scoped_tags || scoped_tags.length === 0) return null;
+  return await store.expandTagsWithDescendants(scoped_tags);
+}
+
+/**
+ * Return true iff the note's tag set intersects the expanded allowlist OR
+ * — fail-open per patterns/tag-scoped-tokens.md §Storage — any of the
+ * note's tags has a string-form root inside `rawRoots`. The string-form
+ * fallback covers the orphan-sub-tag case: a token allowlisted for
+ * `health` should still see `#health/food` even when no `_tags/health/food`
+ * schema declares the hierarchy. The raw `rawRoots` array is the canonical
+ * allowlist source; `allowed` is just a precomputed expansion for the
+ * common (declared-hierarchy) case.
+ *
+ * Pass `null` for both when the token is unscoped (always permitted).
+ */
+export function noteWithinTagScope(
+  note: Note,
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): boolean {
+  if (rawRoots === null) return true;
+  if (!note.tags || note.tags.length === 0) return false;
+  for (const t of note.tags) {
+    if (allowed && allowed.has(t)) return true;
+    const root = t.split("/")[0];
+    if (root && rawRoots.includes(root)) return true;
+  }
+  return false;
+}
+
+/**
+ * Filter an array of notes to those within the token's tag scope.
+ * No-op when `rawRoots` is null. See `noteWithinTagScope` for the
+ * string-form fallback semantics.
+ */
+export function filterNotesByTagScope<T extends Note>(
+  notes: T[],
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): T[] {
+  if (rawRoots === null) return notes;
+  return notes.filter((n) => noteWithinTagScope(n, allowed, rawRoots));
+}
+
+/**
+ * For write paths: a note being created/updated must end up carrying at
+ * least one tag inside the allowlist. `tags` is the post-write tag set
+ * (already including any tag updates). The string-form fallback in
+ * `rawRoots` mirrors the read-path semantics — a token allowlisted for
+ * `health` can write `#health/food` even when the sub-tag has no
+ * declared schema. Returns true iff write is permitted.
+ */
+export function tagsWithinScope(
+  tags: string[] | undefined,
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): boolean {
+  if (rawRoots === null) return true;
+  if (!tags || tags.length === 0) return false;
+  for (const t of tags) {
+    if (allowed && allowed.has(t)) return true;
+    const root = t.split("/")[0];
+    if (root && rawRoots.includes(root)) return true;
+  }
+  return false;
+}
+
+/**
+ * Standard 403 response shape for tag-scope rejections. Mirrors the
+ * `insufficient_scope` 403 shape used elsewhere in the API so clients
+ * get a consistent error envelope.
+ */
+export function tagScopeForbidden(scoped_tags: string[]): Response {
+  return Response.json(
+    {
+      error: "Forbidden",
+      error_type: "tag_scope_violation",
+      message: `This token is restricted to tags: ${scoped_tags.join(", ")}. The note (or write) is outside that scope.`,
+      scoped_tags,
+    },
+    { status: 403 },
+  );
+}

package/src/token-store.test.ts

@@ -157,6 +157,53 @@ describe("token CRUD", () => {
   });
 });
 
+describe("per-vault binding (v16)", () => {
+  test("createToken without vault_name leaves the column NULL (legacy / server-wide)", () => {
+    const { fullToken } = generateToken();
+    createToken(db, fullToken, { label: "legacy" });
+
+    const resolved = resolveToken(db, fullToken);
+    expect(resolved!.vault_name).toBeNull();
+
+    const [row] = listTokens(db);
+    expect(row!.vault_name).toBeNull();
+  });
+
+  test("createToken with vault_name binds the token to that vault", () => {
+    const { fullToken } = generateToken();
+    createToken(db, fullToken, { label: "boulder-bound", vault_name: "boulder" });
+
+    const resolved = resolveToken(db, fullToken);
+    expect(resolved!.vault_name).toBe("boulder");
+
+    const [row] = listTokens(db);
+    expect(row!.vault_name).toBe("boulder");
+  });
+
+  test("listTokens with vaultName filter returns matching + legacy NULL tokens", () => {
+    // Per the contract: per-vault listings show tokens bound to THIS vault
+    // plus any server-wide (NULL) tokens. The latter authenticate cross-vault
+    // by design, so the operator should be able to see + revoke them in any
+    // vault's admin UI. Tokens bound to OTHER vaults are excluded.
+    const { fullToken: tA } = generateToken();
+    const { fullToken: tB } = generateToken();
+    const { fullToken: tLegacy } = generateToken();
+    createToken(db, tA, { label: "boulder", vault_name: "boulder" });
+    createToken(db, tB, { label: "default-vault", vault_name: "default" });
+    createToken(db, tLegacy, { label: "server-wide" });
+
+    const boulderTokens = listTokens(db, { vaultName: "boulder" });
+    expect(boulderTokens.map((t) => t.label).sort()).toEqual(["boulder", "server-wide"]);
+
+    const defaultTokens = listTokens(db, { vaultName: "default" });
+    expect(defaultTokens.map((t) => t.label).sort()).toEqual(["default-vault", "server-wide"]);
+
+    // No filter → everything.
+    const all = listTokens(db);
+    expect(all.length).toBe(3);
+  });
+});
+
 describe("token generation", () => {
   test("generated tokens have pvt_ prefix", () => {
     const { fullToken, tokenHash } = generateToken();

package/src/token-store.ts

@@ -45,6 +45,21 @@ export interface Token {
   scope_tag: string | null;
   /** @deprecated Scope columns exist in DB but are not enforced at runtime. */
   scope_path_prefix: string | null;
+  /**
+   * Tag-allowlist (root tag names). When non-null, the token's effective
+   * access is the intersection of `scopes` and notes carrying one of these
+   * tags or a sub-tag thereof (hierarchy expansion via getTagDescendants).
+   * NULL = unscoped, full vault access per `scopes`. See
+   * patterns/tag-scoped-tokens.md.
+   */
+  scoped_tags: string[] | null;
+  /**
+   * Per-vault binding (v16). Non-null = token can only authenticate against
+   * this vault; cross-vault presentation rejects in
+   * `authenticateVaultRequest`. NULL = legacy / server-wide token, accepted
+   * for any vault. See vault#257.
+   */
+  vault_name: string | null;
   expires_at: string | null;
   created_at: string;
   last_used_at: string | null;
@@ -61,6 +76,36 @@ export interface ResolvedToken {
   scopes: string[];
   /** True iff `scopes` was derived from the legacy `permission` column. */
   legacyDerived: boolean;
+  /**
+   * Tag-allowlist for tag-scoped tokens (root tag names). NULL = unscoped.
+   * See `Token.scoped_tags`.
+   */
+  scoped_tags: string[] | null;
+  /**
+   * Per-vault binding (v16). Non-null = token is bound to this vault;
+   * `authenticateVaultRequest` rejects when the bound vault doesn't match
+   * the request's vault. NULL = legacy / server-wide, accepted for any
+   * vault. See vault#257.
+   */
+  vault_name: string | null;
+}
+
+/**
+ * Parse the JSON-encoded `scoped_tags` column. Returns null for NULL/empty
+ * input. Defensive: malformed JSON or non-array shapes degrade to null
+ * (treat as unscoped) rather than throwing — a corrupt column value
+ * shouldn't take down auth; it just means the token loses its tag scope.
+ */
+export function parseScopedTags(raw: string | null): string[] | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return null;
+    const tags = parsed.filter((t): t is string => typeof t === "string" && t.length > 0);
+    return tags.length === 0 ? null : tags;
+  } catch {
+    return null;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -89,6 +134,20 @@ export function createToken(
     scope_tag?: string | null;
     /** @deprecated Written to DB but not enforced at runtime. */
     scope_path_prefix?: string | null;
+    /**
+     * Tag-allowlist (root tag names). null/undefined → unscoped (full vault
+     * access per `scopes`). When provided, must be already-validated root tag
+     * names per patterns/tag-scoped-tokens.md (no path separators); the mint
+     * endpoint validates against existing tags before passing through.
+     */
+    scoped_tags?: string[] | null;
+    /**
+     * Per-vault binding (v16). Non-null = token can only authenticate
+     * against this vault. NULL = legacy / server-wide; auth accepts the
+     * token for any vault. New mints via per-vault routes set this; the
+     * legacy YAML-import path leaves it NULL. See vault#257.
+     */
+    vault_name?: string | null;
     expires_at?: string | null;
   },
 ): Token {
@@ -97,19 +156,24 @@ export function createToken(
   const permission = opts.permission ?? "full";
   const scopes = opts.scopes ?? legacyPermissionToScopes(permission);
   const scopesStr = serializeScopes(scopes);
+  const scopedTags = opts.scoped_tags && opts.scoped_tags.length > 0 ? opts.scoped_tags : null;
+  const scopedTagsStr = scopedTags ? JSON.stringify(scopedTags) : null;
+  const vaultName = opts.vault_name ?? null;
 
   db.prepare(`
-    INSERT INTO tokens (token_hash, label, permission, scopes, scope_tag, scope_path_prefix, expires_at, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO tokens (token_hash, label, permission, scopes, scoped_tags, scope_tag, scope_path_prefix, expires_at, created_at, vault_name)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     tokenHash,
     opts.label,
     permission,
     scopesStr,
+    scopedTagsStr,
     opts.scope_tag ?? null,
     opts.scope_path_prefix ?? null,
     opts.expires_at ?? null,
     now,
+    vaultName,
   );
 
   return {
@@ -118,6 +182,8 @@ export function createToken(
     permission,
     scope_tag: opts.scope_tag ?? null,
     scope_path_prefix: opts.scope_path_prefix ?? null,
+    scoped_tags: scopedTags,
+    vault_name: vaultName,
     expires_at: opts.expires_at ?? null,
     created_at: now,
     last_used_at: null,
@@ -135,13 +201,15 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   const candidateHash = hashKey(providedToken);
 
   const row = db.prepare(`
-    SELECT token_hash, permission, scopes, expires_at
+    SELECT token_hash, permission, scopes, scoped_tags, expires_at, vault_name
     FROM tokens WHERE token_hash = ?
   `).get(candidateHash) as {
     token_hash: string;
     permission: string;
     scopes: string | null;
+    scoped_tags: string | null;
     expires_at: string | null;
+    vault_name: string | null;
   } | null;
 
   if (!row) return null;
@@ -160,29 +228,74 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   const hasVaultScope = parsed.some((s) => s.startsWith("vault:"));
   const scopes = hasVaultScope ? parsed : legacyPermissionToScopes(permission);
   const legacyDerived = !hasVaultScope;
+  const scoped_tags = parseScopedTags(row.scoped_tags);
 
-  return { permission, scopes, legacyDerived };
+  return { permission, scopes, legacyDerived, scoped_tags, vault_name: row.vault_name };
 }
 
 /**
- * List all tokens (for CLI display). Never exposes the hash directly —
- * shows a truncated prefix for identification.
+ * List tokens (for CLI display + admin SPA). Never exposes the hash
+ * directly — shows a truncated prefix for identification.
+ *
+ * Filtering (v16): pass `{ vaultName }` to scope the result to tokens
+ * bound to that vault. The filter is `vault_name = $vaultName OR
+ * vault_name IS NULL` — legacy server-wide tokens (NULL) remain visible
+ * inside every per-vault listing, since they authenticate cross-vault
+ * by design and the operator should see them in any vault's admin UI
+ * to revoke. Pass no filter (or `vaultName: null`) to list everything.
  */
-export function listTokens(db: Database): (Token & { id: string })[] {
+export function listTokens(
+  db: Database,
+  opts: { vaultName?: string | null } = {},
+): (Token & { id: string })[] {
+  const where = opts.vaultName ? "WHERE vault_name = ? OR vault_name IS NULL" : "";
+  const params = opts.vaultName ? [opts.vaultName] : [];
   const rows = db.prepare(`
     SELECT token_hash, label, permission, scope_tag, scope_path_prefix,
-           expires_at, created_at, last_used_at
-    FROM tokens ORDER BY created_at DESC
-  `).all() as Token[];
+           scoped_tags, vault_name, expires_at, created_at, last_used_at
+    FROM tokens ${where}
+    ORDER BY created_at DESC
+  `).all(...params) as (Omit<Token, "scoped_tags"> & { scoped_tags: string | null })[];
 
   return rows.map((r) => ({
     ...r,
     permission: normalizePermission(r.permission),
+    scoped_tags: parseScopedTags(r.scoped_tags),
     // Derive a short display ID from the hash (first 12 chars after "sha256:")
     id: `t_${r.token_hash.slice(7, 19)}`,
   }));
 }
 
+/**
+ * Find tokens whose `scoped_tags` allowlist references the given root tag.
+ * Used by tag-delete and tag-merge to fail-closed (409) when removing a
+ * tag would silently orphan a tag-scoped token's allowlist entry.
+ *
+ * Returns display ID + label pairs (no token-hash exposure) so error
+ * envelopes can name the offending tokens for the operator. The match is
+ * exact on the root name — `scoped_tags` only ever stores roots per
+ * patterns/tag-scoped-tokens.md.
+ */
+export function findTokensReferencingTag(
+  db: Database,
+  tag: string,
+): { id: string; label: string }[] {
+  const rows = db.prepare(`
+    SELECT token_hash, label, scoped_tags
+    FROM tokens
+    WHERE scoped_tags IS NOT NULL
+  `).all() as { token_hash: string; label: string; scoped_tags: string | null }[];
+
+  const matches: { id: string; label: string }[] = [];
+  for (const row of rows) {
+    const tags = parseScopedTags(row.scoped_tags);
+    if (tags && tags.includes(tag)) {
+      matches.push({ id: `t_${row.token_hash.slice(7, 19)}`, label: row.label });
+    }
+  }
+  return matches;
+}
+
 /**
  * Revoke (delete) a token by its display ID or full hash.
  * Returns true if exactly one token was deleted.
@@ -196,7 +309,7 @@ export function revokeToken(db: Database, idOrHash: string): boolean {
       "SELECT token_hash FROM tokens WHERE token_hash LIKE ?"
     ).all(`sha256:${hashPrefix}%`) as { token_hash: string }[];
     if (rows.length === 1) {
-      db.prepare("DELETE FROM tokens WHERE token_hash = ?").run(rows[0].token_hash);
+      db.prepare("DELETE FROM tokens WHERE token_hash = ?").run(rows[0]!.token_hash);
       return true;
     }
     if (rows.length > 1) {
@@ -206,8 +319,10 @@ export function revokeToken(db: Database, idOrHash: string): boolean {
   }
 
   // Try matching by full hash
-  const result = db.prepare("DELETE FROM tokens WHERE token_hash = ?").run(idOrHash);
-  return result.changes > 0;
+  const deleted = db.prepare(
+    "DELETE FROM tokens WHERE token_hash = ? RETURNING token_hash",
+  ).get(idOrHash) as { token_hash: string } | null;
+  return deleted !== null;
 }
 
 // ---------------------------------------------------------------------------