@openparachute/vault 0.3.1 → 0.4.0

package/src/config.test.ts

@@ -180,6 +180,50 @@ describe("config", () => {
     writeGlobalConfig({ port: 1940, discovery: "disabled" });
     expect(readGlobalConfig().discovery).toBe("disabled");
   });
+
+  test("global api_keys round-trip scope: read|write and default missing scope to write", () => {
+    // Regression for the silent privilege-escalation bug: the global YAML
+    // parser used to drop the `scope` field, leaving `globalKey.scope`
+    // undefined. Auth then resolved any non-"read" value to "full", so a
+    // user-authored `scope: read` global key would silently get full access.
+    writeGlobalConfig({
+      port: 1940,
+      api_keys: [
+        { id: "k_r", label: "reader", scope: "read", key_hash: "sha256:r", created_at: "2026-01-01T00:00:00.000Z" },
+        { id: "k_w", label: "writer", scope: "write", key_hash: "sha256:w", created_at: "2026-01-01T00:00:00.000Z" },
+      ],
+    });
+    const loaded = readGlobalConfig();
+    expect(loaded.api_keys?.find((k) => k.id === "k_r")?.scope).toBe("read");
+    expect(loaded.api_keys?.find((k) => k.id === "k_w")?.scope).toBe("write");
+
+    // Missing-scope branch: a hand-edited config.yaml entry without a
+    // `scope:` line must default to "write" (matches vault-level parser
+    // and the historical behavior the writer round-trips).
+    const fs = require("fs");
+    const path = `${process.env.PARACHUTE_HOME}/vault/config.yaml`;
+    fs.writeFileSync(
+      path,
+      `port: 1940\napi_keys:\n  - id: k_legacy\n    label: legacy\n    key_hash: sha256:legacy\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const reloaded = readGlobalConfig();
+    expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
+  });
+
+  test("round-trips autostart: true|false (#113)", () => {
+    // Default: absent means autostart-on (init registers the daemon).
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().autostart).toBeUndefined();
+
+    // Explicit true (e.g., user re-enabled after disabling).
+    writeGlobalConfig({ port: 1940, autostart: true });
+    expect(readGlobalConfig().autostart).toBe(true);
+
+    // Explicit false — the opt-out signal init writes when --no-autostart is
+    // passed. Daemon registration is then skipped on this and future inits.
+    writeGlobalConfig({ port: 1940, autostart: false });
+    expect(readGlobalConfig().autostart).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -86,6 +86,14 @@ export const ERR_PATH = join(LOGS_DIR, "vault.err");
 export const DEFAULT_PORT = 1940;
 export const ASSETS_DIR = join(VAULT_HOME, "assets");
 
+// Filesystem sentinel for graceful shutdown. `parachute-vault stop` writes
+// this file; the running server polls for it and exits cleanly when it
+// appears. Resolved per-call so PARACHUTE_HOME overrides (tests, Docker)
+// match between writer and reader.
+export function stopSignalPath(): string {
+  return join(vaultHomePath(), "stop.signal");
+}
+
 export function vaultDir(name: string): string {
   return join(dataDirPath(), name);
 }
@@ -243,6 +251,16 @@ export interface GlobalConfig {
    *   callers.
    */
   discovery?: "enabled" | "disabled";
+  /**
+   * Whether `parachute-vault init` registers the daemon with launchd / systemd
+   * (which then auto-starts on boot AND auto-restarts on crash). Defaults to
+   * `true` (preserve historical behavior). When `false`, init skips daemon
+   * registration AND removes any prior registration — for CI, dev sandboxes,
+   * Docker/K8s setups, or environments where another supervisor manages the
+   * process. The user is expected to run `parachute-vault serve` manually or
+   * point their own supervisor at it.
+   */
+  autostart?: boolean;
   /** Backup configuration: schedule, retention, destinations. */
   backup?: BackupConfig;
 }
@@ -403,13 +421,13 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   };
 
   const nameMatch = yaml.match(/^name:\s*(.+)/m);
-  if (nameMatch) config.name = nameMatch[1].trim();
+  if (nameMatch) config.name = nameMatch[1]!.trim();
 
   const createdMatch = yaml.match(/^created_at:\s*"?([^"\n]+)"?/m);
-  if (createdMatch) config.created_at = createdMatch[1];
+  if (createdMatch) config.created_at = createdMatch[1]!;
 
   const pubTagMatch = yaml.match(/^published_tag:\s*(\S+)/m);
-  if (pubTagMatch) config.published_tag = pubTagMatch[1];
+  if (pubTagMatch) config.published_tag = pubTagMatch[1]!;
 
   const retentionMatch = yaml.match(/^audio_retention:\s*(\S+)/m);
   if (retentionMatch) {
@@ -420,14 +438,14 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   // Parse description (block scalar)
   const descMatch = yaml.match(/^description:\s*\|\s*\n((?:\s{2}.+\n?)+)/m);
   if (descMatch) {
-    config.description = descMatch[1]
+    config.description = descMatch[1]!
       .split("\n")
       .map((l) => l.replace(/^\s{2}/, ""))
       .join("\n")
       .trim();
   } else {
     const descSimple = yaml.match(/^description:\s*(.+)/m);
-    if (descSimple) config.description = descSimple[1].trim().replace(/^"(.*)"$/, "$1");
+    if (descSimple) config.description = descSimple[1]!.trim().replace(/^"(.*)"$/, "$1");
   }
 
   // Parse api_keys
@@ -442,10 +460,10 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
 
     if (idMatch && hashMatch) {
       config.api_keys.push({
-        id: idMatch[1],
+        id: idMatch[1]!,
         label: (labelMatch?.[1] ?? "default").trim(),
         scope: (scopeMatch?.[1] as KeyScope) ?? "write",
-        key_hash: hashMatch[1],
+        key_hash: hashMatch[1]!,
         created_at: createdAtMatch?.[1] ?? new Date().toISOString(),
         last_used_at: lastUsedMatch?.[1],
       });
@@ -499,12 +517,12 @@ function parseTranscriptionContext(yaml: string): TriggerIncludeContext[] | unde
     if (itemStart) {
       pushCurrent();
       current = { tag: "" };
-      applyContextField(current, itemStart[1], itemStart[2]);
+      applyContextField(current, itemStart[1]!, itemStart[2]!);
       continue;
     }
     const fieldMatch = trimmed.match(/^(\w+):\s*(.*)$/);
     if (fieldMatch && current) {
-      applyContextField(current, fieldMatch[1], fieldMatch[2]);
+      applyContextField(current, fieldMatch[1]!, fieldMatch[2]!);
       continue;
     }
   }
@@ -533,50 +551,52 @@ function parseTagSchemas(yaml: string): Record<string, TagSchema> | undefined {
     if (line.match(/^\S/) && line.trim().length > 0) break;
     if (line.trim().length === 0) continue;
 
-    const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
+    const indent = line.match(/^(\s*)/)?.[1]?.length ?? 0;
 
     if (indent === 2) {
       // Tag name (e.g., "  person:")
       const tagMatch = line.match(/^\s{2}(\S+):\s*$/);
       if (tagMatch) {
-        currentTag = tagMatch[1];
+        currentTag = tagMatch[1]!;
         currentField = null;
         schemas[currentTag] = {};
       }
     } else if (indent === 4 && currentTag) {
       // Tag-level property (description, fields:)
+      const schema = schemas[currentTag]!;
       const descMatch = line.match(/^\s{4}description:\s*"?([^"]*)"?\s*$/);
       if (descMatch) {
-        schemas[currentTag].description = descMatch[1];
+        schema.description = descMatch[1]!;
         continue;
       }
       const fieldsMatch = line.match(/^\s{4}fields:\s*$/);
       if (fieldsMatch) {
-        schemas[currentTag].fields = schemas[currentTag].fields ?? {};
+        schema.fields = schema.fields ?? {};
         currentField = null;
       }
-    } else if (indent === 6 && currentTag && schemas[currentTag].fields !== undefined) {
+    } else if (indent === 6 && currentTag && schemas[currentTag]?.fields !== undefined) {
       // Field name (e.g., "      first_appeared:")
       const fieldMatch = line.match(/^\s{6}(\S+):\s*$/);
       if (fieldMatch) {
-        currentField = fieldMatch[1];
-        schemas[currentTag].fields![currentField] = { type: "string" };
+        currentField = fieldMatch[1]!;
+        schemas[currentTag]!.fields![currentField] = { type: "string" };
       }
-    } else if (indent === 8 && currentTag && currentField && schemas[currentTag].fields) {
+    } else if (indent === 8 && currentTag && currentField && schemas[currentTag]?.fields) {
       // Field property (type, description, enum)
+      const field = schemas[currentTag]!.fields![currentField]!;
       const typeMatch = line.match(/^\s{8}type:\s*(\S+)/);
       if (typeMatch) {
-        schemas[currentTag].fields![currentField].type = typeMatch[1];
+        field.type = typeMatch[1]!;
         continue;
       }
       const fdescMatch = line.match(/^\s{8}description:\s*"?([^"]*)"?\s*$/);
       if (fdescMatch) {
-        schemas[currentTag].fields![currentField].description = fdescMatch[1];
+        field.description = fdescMatch[1]!;
         continue;
       }
       const enumMatch = line.match(/^\s{8}enum:\s*\[([^\]]*)\]/);
       if (enumMatch) {
-        schemas[currentTag].fields![currentField].enum = enumMatch[1]
+        field.enum = enumMatch[1]!
           .split(",")
           .map((s) => s.trim().replace(/^"(.*)"$/, "$1"));
       }
@@ -610,7 +630,7 @@ function applyContextField(
   if (key === "exclude_tag") { item.exclude_tag = value.replace(/^"(.*)"$/, "$1"); return; }
   if (key === "include_metadata") {
     const listMatch = value.match(/^\[([^\]]*)\]/);
-    if (listMatch) item.include_metadata = parseYamlList(listMatch[1]);
+    if (listMatch) item.include_metadata = parseYamlList(listMatch[1]!);
     return;
   }
 }
@@ -655,7 +675,7 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
           console.warn(`[config] trigger "${current.name}" has no webhook URL — skipping`);
         }
       }
-      current = { name: nameMatch[1].trim(), when: {}, action: undefined as unknown as TriggerAction };
+      current = { name: nameMatch[1]!.trim(), when: {}, action: undefined as unknown as TriggerAction };
       section = "top";
       continue;
     }
@@ -677,37 +697,37 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
     // Top-level trigger field
     const eventsMatch = trimmed.match(/^events:\s*\[([^\]]*)\]/);
     if (eventsMatch) {
-      current.events = parseYamlList(eventsMatch[1]) as Array<"created" | "updated">;
+      current.events = parseYamlList(eventsMatch[1]!) as Array<"created" | "updated">;
       continue;
     }
 
     // When fields
     if (section === "when") {
       const tagsMatch = trimmed.match(/^tags:\s*\[([^\]]*)\]/);
-      if (tagsMatch) { current.when!.tags = parseYamlList(tagsMatch[1]); continue; }
+      if (tagsMatch) { current.when!.tags = parseYamlList(tagsMatch[1]!); continue; }
       const hasContentMatch = trimmed.match(/^has_content:\s*(true|false)/);
       if (hasContentMatch) { current.when!.has_content = hasContentMatch[1] === "true"; continue; }
       const missingMetaMatch = trimmed.match(/^missing_metadata:\s*\[([^\]]*)\]/);
-      if (missingMetaMatch) { current.when!.missing_metadata = parseYamlList(missingMetaMatch[1]); continue; }
+      if (missingMetaMatch) { current.when!.missing_metadata = parseYamlList(missingMetaMatch[1]!); continue; }
       const hasMetaMatch = trimmed.match(/^has_metadata:\s*\[([^\]]*)\]/);
-      if (hasMetaMatch) { current.when!.has_metadata = parseYamlList(hasMetaMatch[1]); continue; }
+      if (hasMetaMatch) { current.when!.has_metadata = parseYamlList(hasMetaMatch[1]!); continue; }
     }
 
     // Action fields
     if (section === "action") {
       const webhookMatch = trimmed.match(/^webhook:\s*(.+)/);
       if (webhookMatch) {
-        current.action = { ...(current.action ?? {}), webhook: webhookMatch[1].trim() } as TriggerAction;
+        current.action = { ...(current.action ?? {}), webhook: webhookMatch[1]!.trim() } as TriggerAction;
         continue;
       }
       const timeoutMatch = trimmed.match(/^timeout:\s*(\d+)/);
       if (timeoutMatch && current.action) {
-        current.action.timeout = parseInt(timeoutMatch[1], 10);
+        current.action.timeout = parseInt(timeoutMatch[1]!, 10);
         continue;
       }
       const sendMatch = trimmed.match(/^send:\s*(\S+)/);
       if (sendMatch && current.action) {
-        current.action.send = sendMatch[1] as TriggerAction["send"];
+        current.action.send = sendMatch[1]! as TriggerAction["send"];
         continue;
       }
     }
@@ -719,12 +739,12 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
       if (itemStart) {
         pushContextItem();
         currentContext = { tag: "" };
-        applyContextField(currentContext, itemStart[1], itemStart[2]);
+        applyContextField(currentContext, itemStart[1]!, itemStart[2]!);
         continue;
       }
       const fieldMatch = trimmed.match(/^(\w+):\s*(.*)$/);
       if (fieldMatch && currentContext) {
-        applyContextField(currentContext, fieldMatch[1], fieldMatch[2]);
+        applyContextField(currentContext, fieldMatch[1]!, fieldMatch[2]!);
         continue;
       }
     }
@@ -843,7 +863,7 @@ function parseBackup(yaml: string): BackupConfig | undefined {
       const tierMatch = trimmed.match(/^(daily|weekly|monthly|yearly):\s*(\S+)/);
       if (tierMatch) {
         const tier = tierMatch[1] as keyof RetentionPolicy;
-        const raw = tierMatch[2].trim();
+        const raw = tierMatch[2]!.trim();
         // "null" / "~" / "unbounded" all mean "keep every year" for the
         // yearly tier. For the other tiers they'd be meaningless; we
         // silently treat them as disabled (0) rather than erroring.
@@ -867,13 +887,13 @@ function parseBackup(yaml: string): BackupConfig | undefined {
         pushDest();
         hasDest = true;
         currentDest = {};
-        (currentDest as Record<string, string>)[itemMatch[1]] = itemMatch[2].trim();
+        (currentDest as Record<string, string>)[itemMatch[1]!] = itemMatch[2]!.trim();
         continue;
       }
       // Continuation line inside the current list item.
       const fieldMatch = trimmed.match(/^(\w+):\s*(.*)$/);
       if (fieldMatch && hasDest) {
-        (currentDest as Record<string, string>)[fieldMatch[1]] = fieldMatch[2].trim();
+        (currentDest as Record<string, string>)[fieldMatch[1]!] = fieldMatch[2]!.trim();
         continue;
       }
     }
@@ -1106,14 +1126,18 @@ export function readGlobalConfig(): GlobalConfig {
       const passwordHashMatch = yaml.match(/^owner_password_hash:\s*"([^"]+)"/m);
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
+      const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
       const config: GlobalConfig = {
-        port: portMatch ? parseInt(portMatch[1], 10) : DEFAULT_PORT,
+        port: portMatch ? parseInt(portMatch[1]!, 10) : DEFAULT_PORT,
         default_vault: defaultVaultMatch?.[1],
         owner_password_hash: passwordHashMatch?.[1],
         totp_secret: totpSecretMatch?.[1],
       };
       if (discoveryMatch) {
-        config.discovery = discoveryMatch[1] as "enabled" | "disabled";
+        config.discovery = discoveryMatch[1]! as "enabled" | "disabled";
+      }
+      if (autostartMatch) {
+        config.autostart = autostartMatch[1]! === "true";
       }
 
       // Parse backup_codes: a YAML list of quoted bcrypt hashes under
@@ -1128,7 +1152,7 @@ export function readGlobalConfig(): GlobalConfig {
         for (const line of lines) {
           if (line.match(/^\S/) && line.trim().length > 0) break; // next top-level key
           const m = line.match(/^\s+-\s+"([^"]+)"/);
-          if (m) codes.push(m[1]);
+          if (m) codes.push(m[1]!);
         }
         if (codes.length > 0) config.backup_codes = codes;
       }
@@ -1140,14 +1164,16 @@ export function readGlobalConfig(): GlobalConfig {
         for (const block of keyBlocks) {
           const idMatch = block.match(/^(\S+)/);
           const labelMatch = block.match(/label:\s*(.+)/);
+          const scopeMatch = block.match(/scope:\s*(\S+)/);
           const hashMatch = block.match(/key_hash:\s*(\S+)/);
           const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
           const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
           if (idMatch && hashMatch) {
             config.api_keys.push({
-              id: idMatch[1],
+              id: idMatch[1]!,
               label: (labelMatch?.[1] ?? "default").trim(),
-              key_hash: hashMatch[1],
+              scope: (scopeMatch?.[1] as KeyScope) ?? "write",
+              key_hash: hashMatch[1]!,
               created_at: createdAtMatch?.[1] ?? new Date().toISOString(),
               last_used_at: lastUsedMatch?.[1],
             });
@@ -1172,6 +1198,7 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   const lines = [`port: ${config.port}`];
   if (config.default_vault) lines.push(`default_vault: ${config.default_vault}`);
   if (config.discovery) lines.push(`discovery: ${config.discovery}`);
+  if (config.autostart !== undefined) lines.push(`autostart: ${config.autostart}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);
   }
@@ -1190,6 +1217,7 @@ export function writeGlobalConfig(config: GlobalConfig): void {
     for (const key of config.api_keys) {
       lines.push(`  - id: ${key.id}`);
       lines.push(`    label: ${key.label}`);
+      lines.push(`    scope: ${key.scope ?? "write"}`);
       lines.push(`    key_hash: ${key.key_hash}`);
       lines.push(`    created_at: "${key.created_at}"`);
       if (key.last_used_at) {
@@ -1420,7 +1448,7 @@ export function resolveDefaultVault(): string | null {
     return globalConfig.default_vault;
   }
   if (vaults.length === 1) {
-    return vaults[0];
+    return vaults[0]!;
   }
   return null;
 }

package/src/hub-jwt.test.ts

@@ -0,0 +1,296 @@
+/**
+ * Hub-issued JWT validation — vault as resource server.
+ *
+ * Spins up a fake JWKS endpoint (Bun.serve) with a known RSA keypair, signs
+ * JWTs locally with `jose.SignJWT`, and asserts `validateHubJwt` accepts the
+ * good ones and rejects every failure mode the spec cares about: bad
+ * signature, wrong issuer, expired, missing kid, unknown kid, JWKS
+ * unreachable. Audience permissiveness is exercised — both `aud="operator"`
+ * and `aud="<client_id>"` shapes pass.
+ *
+ * Each test resets the JWKS cache so the origin/keys can change between
+ * cases. The cache is module-scoped; without `resetJwksCache()` we'd reuse
+ * the previous origin's getter and miss test rotations.
+ */
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from "bun:test";
+import { generateKeyPair, exportJWK, SignJWT } from "jose";
+import { resetJwksCache, validateHubJwt, looksLikeJwt } from "./hub-jwt.ts";
+
+interface Keypair {
+  privateKey: CryptoKey;
+  publicJwk: { kty: string; n: string; e: string; kid: string; alg: string; use: string };
+  kid: string;
+}
+
+async function makeKeypair(kid: string): Promise<Keypair> {
+  const { privateKey, publicKey } = await generateKeyPair("RS256", { extractable: true });
+  const jwk = await exportJWK(publicKey);
+  return {
+    privateKey,
+    publicJwk: {
+      kty: "RSA",
+      n: jwk.n!,
+      e: jwk.e!,
+      kid,
+      alg: "RS256",
+      use: "sig",
+    },
+    kid,
+  };
+}
+
+interface JwksFixture {
+  origin: string;
+  stop: () => void;
+  setKeys: (keys: Keypair[]) => void;
+  setUnreachable: (down: boolean) => void;
+}
+
+function startJwksFixture(): JwksFixture {
+  let keys: Keypair[] = [];
+  let down = false;
+  const server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname !== "/.well-known/jwks.json") {
+        return new Response("not found", { status: 404 });
+      }
+      if (down) return new Response("upstream down", { status: 503 });
+      return Response.json({ keys: keys.map((k) => k.publicJwk) });
+    },
+  });
+  return {
+    origin: `http://127.0.0.1:${server.port}`,
+    stop: () => server.stop(true),
+    setKeys: (next) => { keys = next; },
+    setUnreachable: (v) => { down = v; },
+  };
+}
+
+interface SignOpts {
+  iss?: string;
+  aud?: string | string[];
+  sub?: string;
+  scope?: string;
+  jti?: string;
+  clientId?: string;
+  ttlSeconds?: number;
+  expiresAtSeconds?: number;
+  omitKid?: boolean;
+  kid?: string;
+}
+
+async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
+  const iat = Math.floor(Date.now() / 1000);
+  const exp = opts.expiresAtSeconds ?? iat + (opts.ttlSeconds ?? 60);
+  const builder = new SignJWT({
+    scope: opts.scope ?? "vault:read vault:write",
+    client_id: opts.clientId ?? "test-client",
+  })
+    .setProtectedHeader(opts.omitKid ? { alg: "RS256" } : { alg: "RS256", kid: opts.kid ?? kp.kid })
+    .setIssuer(opts.iss ?? "http://issuer.invalid")
+    .setSubject(opts.sub ?? "user-1")
+    .setAudience(opts.aud ?? "operator")
+    .setIssuedAt(iat)
+    .setExpirationTime(exp)
+    .setJti(opts.jti ?? "jti-1");
+  return await builder.sign(kp.privateKey);
+}
+
+let fixture: JwksFixture;
+let kp: Keypair;
+let prevHubOrigin: string | undefined;
+
+beforeAll(async () => {
+  fixture = startJwksFixture();
+  kp = await makeKeypair("k1");
+  fixture.setKeys([kp]);
+});
+
+afterAll(() => {
+  fixture.stop();
+  if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+  else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+});
+
+beforeEach(() => {
+  // Each test sets its own origin for clarity.
+  prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  fixture.setUnreachable(false);
+  fixture.setKeys([kp]);
+  resetJwksCache();
+});
+
+describe("looksLikeJwt", () => {
+  test("`eyJ` prefix → true", () => {
+    expect(looksLikeJwt("eyJhbGciOiJSUzI1NiJ9.x.y")).toBe(true);
+  });
+
+  test("pvt_ token → false", () => {
+    expect(looksLikeJwt("pvt_abcdef0123456789")).toBe(false);
+  });
+
+  test("empty / random → false", () => {
+    expect(looksLikeJwt("")).toBe(false);
+    expect(looksLikeJwt("hello-world")).toBe(false);
+  });
+});
+
+describe("validateHubJwt — happy path", () => {
+  test("valid JWT with correct iss → claims surface", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, scope: "vault:work:read vault:work:write" });
+    const claims = await validateHubJwt(token);
+    expect(claims.sub).toBe("user-1");
+    expect(claims.scopes).toEqual(["vault:work:read", "vault:work:write"]);
+    expect(claims.aud).toBe("operator");
+    expect(claims.jti).toBe("jti-1");
+    expect(claims.clientId).toBe("test-client");
+  });
+
+  test("aud=operator accepted when expectedAudience not set", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, aud: "operator" });
+    const claims = await validateHubJwt(token);
+    expect(claims.aud).toBe("operator");
+  });
+
+  test("aud=<client_id> accepted when expectedAudience not set", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "did:plc:randomclientid",
+      clientId: "did:plc:randomclientid",
+    });
+    const claims = await validateHubJwt(token);
+    expect(claims.aud).toBe("did:plc:randomclientid");
+  });
+
+  test("empty scope claim → empty scopes array", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, scope: "" });
+    const claims = await validateHubJwt(token);
+    expect(claims.scopes).toEqual([]);
+  });
+
+  test("audience strict-check passes when expected matches", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, aud: "vault.work" });
+    const claims = await validateHubJwt(token, { expectedAudience: "vault.work" });
+    expect(claims.aud).toBe("vault.work");
+  });
+});
+
+describe("validateHubJwt — audience strict-check", () => {
+  test("mismatched audience throws with the expected vs got values", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, aud: "vault.personal" });
+    await expect(
+      validateHubJwt(token, { expectedAudience: "vault.work" }),
+    ).rejects.toThrow(/audience mismatch.*vault\.work.*vault\.personal/);
+  });
+
+  test("missing audience claim throws when expected is set", async () => {
+    // jose's SignJWT requires .setAudience() — provide an unrelated value to
+    // exercise "not the expected one" rather than a literal missing claim.
+    const token = await signJwt(kp, { iss: fixture.origin, aud: "operator" });
+    await expect(
+      validateHubJwt(token, { expectedAudience: "vault.work" }),
+    ).rejects.toThrow(/audience mismatch/);
+  });
+
+  test("expectedAudience: null skips the check (cross-vault path)", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, aud: "vault.anything" });
+    const claims = await validateHubJwt(token, { expectedAudience: null });
+    expect(claims.aud).toBe("vault.anything");
+  });
+
+  test("array aud: passes when expected is one of the entries", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: ["vault.work", "vault.personal", "operator"],
+    });
+    const claims = await validateHubJwt(token, { expectedAudience: "vault.personal" });
+    expect(claims.aud).toBe("vault.personal");
+  });
+
+  test("array aud: rejects when expected is not in the entries", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: ["vault.work", "operator"],
+    });
+    await expect(
+      validateHubJwt(token, { expectedAudience: "vault.personal" }),
+    ).rejects.toThrow(/audience mismatch.*vault\.personal.*vault\.work.*operator/);
+  });
+
+  test("array aud: surfaces the first entry when no expectation is set", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: ["vault.first", "vault.second"],
+    });
+    const claims = await validateHubJwt(token, { expectedAudience: null });
+    expect(claims.aud).toBe("vault.first");
+  });
+});
+
+describe("validateHubJwt — failure modes", () => {
+  test("wrong issuer → throws", async () => {
+    const token = await signJwt(kp, { iss: "http://attacker.example" });
+    await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+  });
+
+  test("expired token → throws", async () => {
+    const past = Math.floor(Date.now() / 1000) - 10;
+    const token = await signJwt(kp, { iss: fixture.origin, expiresAtSeconds: past });
+    await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+  });
+
+  test("bad signature (token signed by an unpublished key) → throws", async () => {
+    const otherKp = await makeKeypair("k1"); // same kid, different key
+    const token = await signJwt(otherKp, { iss: fixture.origin });
+    await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+  });
+
+  test("unknown kid → throws", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, kid: "does-not-exist" });
+    await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+  });
+
+  test("missing kid header → throws when JWKS has multiple keys", async () => {
+    // jose's createRemoteJWKSet falls back to the only key when JWKS has just
+    // one — so to exercise the "no kid" failure path we need ≥2 keys.
+    const kp2 = await makeKeypair("k2");
+    fixture.setKeys([kp, kp2]);
+    resetJwksCache();
+    const token = await signJwt(kp, { iss: fixture.origin, omitKid: true });
+    await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+  });
+
+  test("JWKS endpoint unreachable → throws (fail closed)", async () => {
+    fixture.setUnreachable(true);
+    const token = await signJwt(kp, { iss: fixture.origin });
+    await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+  });
+
+  test("missing `sub` claim → throws", async () => {
+    // SignJWT requires .setSubject; build the token manually-ish: pass empty sub.
+    const iat = Math.floor(Date.now() / 1000);
+    const token = await new SignJWT({ scope: "vault:read" })
+      .setProtectedHeader({ alg: "RS256", kid: kp.kid })
+      .setIssuer(fixture.origin)
+      .setAudience("operator")
+      .setIssuedAt(iat)
+      .setExpirationTime(iat + 60)
+      .setJti("jti-no-sub")
+      .sign(kp.privateKey);
+    await expect(validateHubJwt(token)).rejects.toThrow(/missing required `sub`/);
+  });
+});
+
+describe("validateHubJwt — JWKS rotation", () => {
+  test("rotated key (new kid published) verifies after cache reset", async () => {
+    const kp2 = await makeKeypair("k2");
+    fixture.setKeys([kp, kp2]);
+    resetJwksCache();
+    const token = await signJwt(kp2, { iss: fixture.origin });
+    const claims = await validateHubJwt(token);
+    expect(claims.sub).toBe("user-1");
+  });
+});