@openparachute/hub 0.5.7 → 0.5.10-rc.2

package/src/__tests__/hub.test.ts

@@ -13,10 +13,9 @@ describe("renderHub", () => {
     expect(html).toContain("<script>");
   });
 
-  test("fetches /.well-known/parachute.json and reads services[] + vaults[]", () => {
+  test("fetches /.well-known/parachute.json for the Use section", () => {
     expect(html).toContain("/.well-known/parachute.json");
     expect(html).toContain("doc.services");
-    expect(html).toContain("doc.vaults");
   });
 
   test("uses parachute.computer sage palette and serif/sans fonts", () => {
@@ -30,79 +29,133 @@ describe("renderHub", () => {
     expect(html).toContain("prefers-color-scheme: dark");
   });
 
-  test("falls back to a generic icon for module tiles", () => {
-    expect(html).toContain("fallbackIcon");
+  test("renders two sections: Services and Admin, each with its own heading + grid", () => {
+    expect(html).toContain('id="services-section"');
+    expect(html).toContain('id="admin-section"');
+    expect(html).toContain('id="services-grid"');
+    expect(html).toContain('id="admin-grid"');
+    expect(html).toContain("<h2>Services</h2>");
+    expect(html).toContain("<h2>Admin</h2>");
   });
 
-  test("renders one tile per module type, not per service instance", () => {
-    expect(html).toContain("aggregate(services, vaults)");
-    expect(html).toContain("renderTile");
-    expect(html).toContain("MODULE_ORDER");
+  test("Services section sub-text frames the section as service-owned surfaces", () => {
+    // Services-vs-Admin axis is OWNERSHIP (services own their UIs vs
+    // hub owns host admin), not function. The sub-text reflects that —
+    // earlier "Browse, transcribe, and run" framing put it on the
+    // function axis, which broke down once you noticed services have
+    // UIs that mix use / config / admin.
+    expect(html).toContain("Surfaces provided by services");
   });
 
-  test("known module display order is vault → scribe → notes → agent", () => {
-    expect(html).toContain("['vault', 'scribe', 'notes', 'agent']");
+  test("Services tiles are data-driven from each service's uiUrl + displayName", () => {
+    // Phase D consumer-side: SERVICE_LABELS / SERVICE_ORDER hardcoding
+    // retired. Each well-known services[] row carries displayName + uiUrl
+    // (sourced from module.json via hub-server's loadServiceUiMetadata);
+    // tiles render directly from those.
+    expect(html).toContain("svc.uiUrl");
+    expect(html).toContain("svc.displayName");
+    // No more hardcoded short→label map.
+    expect(html).not.toContain("'Notes', desc:");
+    expect(html).not.toContain("['notes', 'scribe', 'agent']");
   });
 
-  test("vault tile counts vaults[] (per instance) and links to /vault", () => {
-    // Vault count is the length of doc.vaults — one entry per /vault/<name>
-    // mount, so a single ServiceEntry with paths=[a,b,c] still shows "3
-    // registered". The manage link is the hub's vault SPA at /vault
-    // (renamed from /hub/vaults in the realignment), never an individual
-    // vault backend.
-    expect(html).toContain("vaults.length");
-    expect(html).toContain("'/vault'");
+  test("Services skip rule emerges from data, not name-checks (vault has no uiUrl)", () => {
+    // The previous `isVaultName` hardcoded skip is gone — vault doesn't
+    // declare uiUrl, so it naturally doesn't render. Other API-only
+    // modules (current or future) get the same treatment for free.
+    expect(html).toContain("if (!svc || !svc.uiUrl) continue;");
+    // The function definition is gone (the comment may still mention the
+    // name as historical context — we only care about the active code).
+    expect(html).not.toContain("function isVaultName");
   });
 
-  test("non-vault tiles take their manageUrl from the service's path", () => {
-    // shortName('parachute-scribe') = 'scribe' → tile links to svc.path,
-    // which is whatever the module declared (e.g. /scribe, /notes, /agent).
-    // Hardcoding the link would silently break on a custom mount.
-    expect(html).toContain("manageUrl: svc.path");
+  test("Services tiles sort alphabetically by displayName", () => {
+    // Per the module-json-extensibility pattern doc — default ordering
+    // until a `displayOrder` field surfaces. localeCompare keeps the
+    // ordering stable across locales for ASCII labels.
+    expect(html).toContain("a.title.localeCompare(b.title)");
   });
 
-  test("tiles for module types with zero instances are hidden", () => {
-    // Aggregate only inserts a group when the type has at least one entry;
-    // tilesInOrder iterates the map. No "0 registered" surface.
-    expect(html).not.toContain("0 registered");
-    expect(html).toContain("count === 1 ? '1 registered'");
+  test("Admin section is hardcoded (always visible) with three entries", () => {
+    expect(html).toContain("ADMIN_ENTRIES");
+    expect(html).toContain("/admin/vaults");
+    expect(html).toContain("/admin/permissions");
+    expect(html).toContain("/admin/tokens");
   });
 
-  test("module labels are humanized (Vault / Scribe / Notes / Agent)", () => {
-    expect(html).toContain("vault: 'Vault'");
-    expect(html).toContain("scribe: 'Scribe'");
-    expect(html).toContain("notes: 'Notes'");
-    expect(html).toContain("agent: 'Agent'");
+  test("Admin section renders synchronously (does not depend on the well-known fetch)", () => {
+    // Even if the fetch is slow or fails, the operator should see Admin
+    // surfaces — they may be the reason the operator landed on /.
+    expect(html).toContain("renderAdmin();");
+    expect(html).toContain("Admin section is static");
   });
 
-  test("vault-name detection covers parachute-vault and parachute-vault-<name>", () => {
-    // Phase-1 multi-vault keeps a single ServiceEntry with multiple paths
-    // (parachute-vault), but the door is open for per-instance entries
-    // (parachute-vault-techne). isVaultName has to accept both.
-    expect(html).toContain("isVaultName");
-    expect(html).toContain("'parachute-vault'");
-    expect(html).toContain("'parachute-vault-'");
+  test("Services section empty state guides operators to declare uiUrl", () => {
+    // Empty state under Phase D means "no installed service has declared
+    // uiUrl yet" — different shape from pre-D ("none installed at all").
+    // Hint points at the pattern doc since the fix is in module.json,
+    // not at install time.
+    expect(html).toContain("No services with a UI declared yet");
+    expect(html).toContain("module-json-extensibility");
   });
 
-  test("empty state when no modules are registered", () => {
-    expect(html).toContain("No modules installed yet");
-    expect(html).toContain("parachute install vault");
+  test("Use section error state surfaces the underlying message", () => {
+    expect(html).toContain("Could not load services");
   });
 
-  test("error state surfaces the underlying message", () => {
-    expect(html).toContain("Could not load modules");
-  });
-
-  test("does not retain the per-service interactive-card / config-form code", () => {
-    // The home page is now a directory of modules — per-instance config
-    // forms and detail panels live behind the Manage links (vault SPA at
-    // /vault, the running module's own UI elsewhere). Keeping the
-    // dead code around is a maintenance trap.
+  test("does not retain the old aggregate-by-module-type code", () => {
+    // The Vault collapse + per-module aggregation pattern is gone — Use
+    // entries are direct service-path → label lookups; Admin is hardcoded.
+    expect(html).not.toContain("aggregate(services, vaults)");
+    expect(html).not.toContain("MODULE_LABELS");
     expect(html).not.toContain("renderConfigField");
-    expect(html).not.toContain("fetchConfig");
     expect(html).not.toContain("kind-badge");
-    expect(html).not.toContain("info.mcpUrl");
-    expect(html).not.toContain("info.openInNotesUrl");
+  });
+
+  test("default render (no session) emits the 'Sign in' affordance", () => {
+    expect(html).toContain('class="auth-indicator"');
+    expect(html).toContain("Sign in");
+    expect(html).toContain('href="/login?next=/"');
+    // No POST form, no CSRF input — those only appear when signed in.
+    expect(html).not.toContain('action="/logout"');
+    expect(html).not.toContain("__csrf");
+  });
+});
+
+describe("renderHub — signed-in indicator (rc.13)", () => {
+  test("session user → 'Signed in as <name>' + inline POST form with CSRF", () => {
+    const html = renderHub({
+      session: { displayName: "aaron", csrfToken: "csrf-token-xyz" },
+    });
+    expect(html).toContain('class="auth-indicator"');
+    expect(html).toContain("Signed in as");
+    expect(html).toContain("aaron");
+    // Inline POST form for sign-out — CSRF token embedded as the
+    // existing `__csrf` field name (matches /logout's expectations).
+    expect(html).toContain('method="POST" action="/logout"');
+    expect(html).toContain('name="__csrf"');
+    expect(html).toContain('value="csrf-token-xyz"');
+    expect(html).toContain("Sign out");
+    // No "Sign in" affordance when signed in.
+    expect(html).not.toContain('href="/login?next=/"');
+  });
+
+  test("displayName with HTML special chars is escaped", () => {
+    // Username field allows alphanumerics historically, but the
+    // displayName field on the wire is forward-compatible with profile
+    // names that may contain &, <, >. Escape at render time.
+    const html = renderHub({
+      session: { displayName: "<aaron>&friends", csrfToken: "tok" },
+    });
+    expect(html).toContain("&lt;aaron&gt;&amp;friends");
+    expect(html).not.toContain("<aaron>&friends");
+  });
+
+  test("CSRF token with HTML special chars is escaped in the value attribute", () => {
+    const html = renderHub({
+      session: { displayName: "aaron", csrfToken: 'token"with"quotes' },
+    });
+    expect(html).toContain('value="token&quot;with&quot;quotes"');
   });
 });
 

package/src/__tests__/install-source.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type DetectInstallSourceDeps,
+  detectHubInstallSource,
+  detectInstallSource,
+  formatInstallSourceLabel,
+  isStale,
+} from "../install-source.ts";
+
+/**
+ * Stub helpers for the detect path. Production reads the operator's bun
+ * globals + real package.jsons; here we wire everything from a virtual
+ * filesystem so each kind (npm / bun-linked / unknown / stale) has a
+ * deterministic shape.
+ */
+function makeDeps(opts: {
+  prefixes?: readonly string[];
+  packageVersions?: Record<string, string>;
+  bunGlobalLinks?: Record<string, string>;
+  gitHeads?: Record<string, string>;
+}): DetectInstallSourceDeps {
+  const prefixes = opts.prefixes ?? ["/home/test/.bun/install/global/node_modules"];
+  return {
+    bunGlobalPrefixes: () => prefixes,
+    resolveBunGlobal: (pkg) => opts.bunGlobalLinks?.[pkg] ?? null,
+    readJson: (path) => {
+      // Path looks like `<pkgDir>/package.json` — strip suffix.
+      const pkgDirRaw = path.replace(/\/package\.json$/, "");
+      const v = opts.packageVersions?.[pkgDirRaw];
+      if (v === undefined) throw new Error(`no package.json at ${pkgDirRaw}`);
+      return { name: "@stub/pkg", version: v };
+    },
+    readGitHead: (path) => opts.gitHeads?.[path],
+  };
+}
+
+describe("detectInstallSource", () => {
+  test("classifies a bun-linked checkout (installDir outside bun globals)", () => {
+    const deps = makeDeps({
+      packageVersions: { "/Users/me/code/parachute-notes": "0.3.15-rc.1" },
+      gitHeads: { "/Users/me/code/parachute-notes": "051c404" },
+    });
+    const source = detectInstallSource(
+      { entryName: "parachute-notes", installDir: "/Users/me/code/parachute-notes" },
+      deps,
+    );
+    expect(source.kind).toBe("bun-linked");
+    expect(source.path).toBe("/Users/me/code/parachute-notes");
+    expect(source.gitHead).toBe("051c404");
+    expect(source.livePackageVersion).toBe("0.3.15-rc.1");
+  });
+
+  test("classifies an npm install (installDir under bun globals)", () => {
+    const deps = makeDeps({
+      prefixes: ["/home/test/.bun/install/global/node_modules"],
+      packageVersions: {
+        "/home/test/.bun/install/global/node_modules/@openparachute/scribe": "0.4.2-rc.1",
+      },
+    });
+    const source = detectInstallSource(
+      {
+        entryName: "parachute-scribe",
+        installDir: "/home/test/.bun/install/global/node_modules/@openparachute/scribe",
+      },
+      deps,
+    );
+    expect(source.kind).toBe("npm");
+    expect(source.livePackageVersion).toBe("0.4.2-rc.1");
+    expect(source.gitHead).toBeUndefined();
+  });
+
+  test("falls back to bun-global symlink lookup when installDir is absent", () => {
+    const deps = makeDeps({
+      bunGlobalLinks: { "@openparachute/vault": "/Users/me/code/parachute-vault" },
+      packageVersions: { "/Users/me/code/parachute-vault": "0.4.4-rc.3" },
+      gitHeads: { "/Users/me/code/parachute-vault": "8aa167b" },
+    });
+    const source = detectInstallSource({ entryName: "parachute-vault" }, deps);
+    expect(source.kind).toBe("bun-linked");
+    expect(source.path).toBe("/Users/me/code/parachute-vault");
+    expect(source.gitHead).toBe("8aa167b");
+  });
+
+  test("returns unknown when nothing resolves (no installDir, no first-party mapping)", () => {
+    const deps = makeDeps({});
+    const source = detectInstallSource({ entryName: "agent" }, deps);
+    expect(source.kind).toBe("unknown");
+    expect(source.path).toBeUndefined();
+    expect(source.gitHead).toBeUndefined();
+  });
+
+  test("omits gitHead when the bun-linked path isn't a git repo", () => {
+    const deps = makeDeps({
+      packageVersions: { "/tmp/no-git/pkg": "1.0.0" },
+      // gitHeads intentionally missing → readGitHead returns undefined.
+    });
+    const source = detectInstallSource(
+      { entryName: "third-party", installDir: "/tmp/no-git/pkg" },
+      deps,
+    );
+    expect(source.kind).toBe("bun-linked");
+    expect(source.gitHead).toBeUndefined();
+    expect(source.livePackageVersion).toBe("1.0.0");
+  });
+
+  test("omits livePackageVersion when package.json is unreadable", () => {
+    const deps = makeDeps({
+      packageVersions: {}, // every read throws
+    });
+    const source = detectInstallSource(
+      { entryName: "third-party", installDir: "/tmp/no-pkg" },
+      deps,
+    );
+    expect(source.kind).toBe("bun-linked");
+    expect(source.livePackageVersion).toBeUndefined();
+  });
+
+  test("trailing-slash prefix doesn't false-match a sibling directory", () => {
+    // Subtle: `/home/test/.bun/install/global/node_modules-other` shouldn't
+    // be classified as "under" `/home/test/.bun/install/global/node_modules`.
+    // The prefix join in `isUnderBunGlobals` adds a trailing slash precisely
+    // to avoid this — pin the behavior.
+    const deps = makeDeps({
+      prefixes: ["/home/test/.bun/install/global/node_modules"],
+      packageVersions: {
+        "/home/test/.bun/install/global/node_modules-other/pkg": "1.0.0",
+      },
+    });
+    const source = detectInstallSource(
+      {
+        entryName: "third-party",
+        installDir: "/home/test/.bun/install/global/node_modules-other/pkg",
+      },
+      deps,
+    );
+    expect(source.kind).toBe("bun-linked");
+  });
+});
+
+describe("isStale", () => {
+  test("flags drift between cached entry version and live package.json", () => {
+    expect(
+      isStale("0.3.11-rc.1", {
+        kind: "bun-linked",
+        path: "/Users/me/code/parachute-notes",
+        livePackageVersion: "0.3.15-rc.1",
+      }),
+    ).toBe(true);
+  });
+
+  test("does not flag a matching version", () => {
+    expect(
+      isStale("0.3.15-rc.1", {
+        kind: "bun-linked",
+        path: "/Users/me/code/parachute-notes",
+        livePackageVersion: "0.3.15-rc.1",
+      }),
+    ).toBe(false);
+  });
+
+  test("does not flag npm-installed services (cached version IS the source)", () => {
+    expect(
+      isStale("0.4.2-rc.1", {
+        kind: "npm",
+        path: "/path/to/global",
+        livePackageVersion: "0.4.2-rc.1",
+      }),
+    ).toBe(false);
+  });
+
+  test("does not flag when live version is unavailable", () => {
+    expect(
+      isStale("0.3.11-rc.1", {
+        kind: "bun-linked",
+        path: "/Users/me/code/parachute-notes",
+        // livePackageVersion absent — can't compute drift, don't false-flag.
+      }),
+    ).toBe(false);
+  });
+
+  test("does not flag unknown sources", () => {
+    expect(isStale("1.0.0", { kind: "unknown" })).toBe(false);
+  });
+});
+
+describe("formatInstallSourceLabel", () => {
+  test("bun-linked → basename + short SHA", () => {
+    expect(
+      formatInstallSourceLabel({
+        kind: "bun-linked",
+        path: "/Users/me/code/parachute-notes",
+        gitHead: "051c404",
+      }),
+    ).toBe("bun-linked → parachute-notes @ 051c404");
+  });
+
+  test("bun-linked without gitHead drops the @ <sha> suffix", () => {
+    expect(
+      formatInstallSourceLabel({
+        kind: "bun-linked",
+        path: "/Users/me/code/parachute-notes",
+      }),
+    ).toBe("bun-linked → parachute-notes");
+  });
+
+  test("npm with version", () => {
+    expect(
+      formatInstallSourceLabel({
+        kind: "npm",
+        path: "/some/global/dir",
+        livePackageVersion: "0.4.2-rc.1",
+      }),
+    ).toBe("npm (0.4.2-rc.1)");
+  });
+
+  test("npm without version", () => {
+    expect(formatInstallSourceLabel({ kind: "npm" })).toBe("npm");
+  });
+
+  test("unknown sources render as 'unknown'", () => {
+    expect(formatInstallSourceLabel({ kind: "unknown" })).toBe("unknown");
+  });
+});
+
+describe("detectHubInstallSource", () => {
+  test("classifies the hub based on its source location", () => {
+    // Exercise the happy path via the real hub's `src/` dir. The result
+    // depends on the test environment (CI vs. bun-linked checkout), so we
+    // only assert the kind is one of the known classifications — not the
+    // exact value. `readGitHead` is stubbed so the test never forks a real
+    // git process; the contract under test is "climb to package.json,
+    // classify by location against bun globals" — git is incidental.
+    const source = detectHubInstallSource(import.meta.dir, {
+      readGitHead: () => "deadbeef",
+    });
+    expect(["bun-linked", "npm", "unknown"]).toContain(source.kind);
+  });
+
+  test("returns unknown when no package.json exists above srcDir", () => {
+    // `/private` exists on macOS but has no package.json up the chain;
+    // injected readJson always throws so the walk hits the climb-cap.
+    const source = detectHubInstallSource("/private/var/empty", {
+      readJson: () => {
+        throw new Error("no package.json");
+      },
+    });
+    expect(source.kind).toBe("unknown");
+  });
+});

package/src/__tests__/jwt-sign.test.ts

@@ -9,8 +9,13 @@ import {
   REFRESH_TOKEN_TTL_MS,
   RefreshTokenInsertError,
   findRefreshToken,
+  findTokenRowByJti,
+  listActiveRevocations,
+  recordTokenMint,
+  revokeTokenByJti,
   signAccessToken,
   signRefreshToken,
+  tokenRowIdentity,
   validateAccessToken,
 } from "../jwt-sign.ts";
 import { getActiveSigningKey, rotateSigningKey } from "../signing-keys.ts";
@@ -359,3 +364,203 @@ describe("validateAccessToken", () => {
     }
   });
 });
+
+// closes #212 Phase 1 — unified token registry helpers (recordTokenMint,
+// revokeTokenByJti, listActiveRevocations) and the v6 schema shape.
+describe("token registry (hub#212 Phase 1)", () => {
+  test("v6 schema: tokens has user_id NULLABLE + permissions/created_via/subject", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      // SQLite PRAGMA table_info reports column nullability + defaults; the
+      // bun:sqlite driver maps the row shape onto our type. The columns are
+      // (cid, name, type, notnull, dflt_value, pk) per SQLite docs.
+      type ColInfo = {
+        cid: number;
+        name: string;
+        type: string;
+        notnull: number;
+        dflt_value: string | null;
+        pk: number;
+      };
+      const cols = db.query<ColInfo, []>("PRAGMA table_info(tokens)").all();
+      const byName = new Map(cols.map((c) => [c.name, c]));
+      // Pre-v6: user_id NOT NULL. Post-v6: user_id NULLABLE.
+      expect(byName.get("user_id")?.notnull).toBe(0);
+      // New columns.
+      expect(byName.has("permissions")).toBe(true);
+      expect(byName.has("created_via")).toBe(true);
+      expect(byName.has("subject")).toBe(true);
+      // created_via has the back-compat default for pre-v6 rows.
+      expect(byName.get("created_via")?.dflt_value).toMatch(/oauth_refresh/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("recordTokenMint inserts a registry row matching the inputs", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const expiresAt = new Date(Date.now() + 86400_000).toISOString();
+      recordTokenMint(db, {
+        jti: "jti-cli-1",
+        createdVia: "cli_mint",
+        subject: "operator",
+        clientId: "parachute-hub",
+        scopes: ["vault:read", "scribe:transcribe"],
+        expiresAt,
+        permissions: '{"vault":{"default":{"read_tags":["public"]}}}',
+      });
+      const row = findTokenRowByJti(db, "jti-cli-1");
+      expect(row).not.toBeNull();
+      expect(row?.userId).toBeNull();
+      expect(row?.subject).toBe("operator");
+      expect(row?.createdVia).toBe("cli_mint");
+      expect(row?.scopes).toEqual(["vault:read", "scribe:transcribe"]);
+      expect(row?.expiresAt).toBe(expiresAt);
+      expect(row?.permissions).toBe('{"vault":{"default":{"read_tags":["public"]}}}');
+      expect(row?.revokedAt).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("recordTokenMint with a duplicate jti throws RefreshTokenInsertError", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const expiresAt = new Date(Date.now() + 86400_000).toISOString();
+      recordTokenMint(db, {
+        jti: "jti-dup",
+        createdVia: "operator_mint",
+        subject: "operator",
+        clientId: "parachute-hub",
+        scopes: ["hub:admin"],
+        expiresAt,
+      });
+      expect(() =>
+        recordTokenMint(db, {
+          jti: "jti-dup",
+          createdVia: "cli_mint",
+          subject: "operator",
+          clientId: "parachute-hub",
+          scopes: ["vault:read"],
+          expiresAt,
+        }),
+      ).toThrow(RefreshTokenInsertError);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("revokeTokenByJti flips revoked_at; second call returns false (idempotent)", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const expiresAt = new Date(Date.now() + 86400_000).toISOString();
+      recordTokenMint(db, {
+        jti: "jti-rev",
+        createdVia: "cli_mint",
+        subject: "operator",
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        expiresAt,
+      });
+      const now = new Date();
+      expect(revokeTokenByJti(db, "jti-rev", now)).toBe(true);
+      expect(revokeTokenByJti(db, "jti-rev", now)).toBe(false);
+      const row = findTokenRowByJti(db, "jti-rev");
+      expect(row?.revokedAt).toBe(now.toISOString());
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("listActiveRevocations filters by revoked_at AND expires_at>now", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const past = new Date(Date.now() - 86400_000).toISOString();
+      const future = new Date(Date.now() + 86400_000).toISOString();
+      // Two revoked rows: one expired, one active.
+      recordTokenMint(db, {
+        jti: "jti-revoked-expired",
+        createdVia: "cli_mint",
+        subject: "operator",
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        expiresAt: past,
+      });
+      recordTokenMint(db, {
+        jti: "jti-revoked-active",
+        createdVia: "cli_mint",
+        subject: "operator",
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        expiresAt: future,
+      });
+      // One non-revoked active row (control — must NOT appear).
+      recordTokenMint(db, {
+        jti: "jti-not-revoked",
+        createdVia: "cli_mint",
+        subject: "operator",
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        expiresAt: future,
+      });
+      const now = new Date();
+      revokeTokenByJti(db, "jti-revoked-expired", now);
+      revokeTokenByJti(db, "jti-revoked-active", now);
+      const list = listActiveRevocations(db, now);
+      expect(list).toEqual(["jti-revoked-active"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("tokenRowIdentity returns userId when present, else subject", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      // OAuth refresh row: userId set, subject NULL.
+      const refresh = signRefreshToken(db, {
+        jti: "jti-oauth",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+      });
+      expect(refresh.familyId).toBeDefined();
+      const oauthRow = findTokenRowByJti(db, "jti-oauth")!;
+      expect(tokenRowIdentity(oauthRow)).toBe(u.id);
+
+      // CLI mint row: userId NULL, subject set.
+      recordTokenMint(db, {
+        jti: "jti-cli",
+        createdVia: "cli_mint",
+        subject: "operator",
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        expiresAt: new Date(Date.now() + 86400_000).toISOString(),
+      });
+      const cliRow = findTokenRowByJti(db, "jti-cli")!;
+      expect(tokenRowIdentity(cliRow)).toBe("operator");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("signRefreshToken explicitly stamps created_via='oauth_refresh'", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      signRefreshToken(db, {
+        jti: "jti-oauth-stamped",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+      });
+      const row = findTokenRowByJti(db, "jti-oauth-stamped");
+      expect(row?.createdVia).toBe("oauth_refresh");
+    } finally {
+      cleanup();
+    }
+  });
+});