§9 JWT signing-key rotation runbook (todo §9); turned the README's 3-line rotation note into an operational runbook and closed the tooling gap that made its documented steps unrunnable — the old "prepend a key / drop it later" meant hand-editing a JSON file holding a private signing key. Tests-first: new pure rotateJwks(current,{prune}) in gen-jwks.ts — --prepend puts a fresh ES256 key first (Kratos signs with keys[0], the old keys still verify in-flight JWTs) and keeps the rest in order; --prune keeps only the newest (drop superseded post-TTL). CLI reads the existing set from a path arg and writes the new set to stdout (header documents the temp-file redirect so the shell's > can't truncate the input). gen-jwks.test.ts covers prepend (length+1, fresh kid first, old set preserved) + prune (→ 1 key). Runbook documents the two-sided install (Kratos signer env/mount + web JWKS_URL; file:// hot-reloads, base64:// immutable), why it's zero-downtime (sign-with-first + verify-by-kid), the scheduled path (prepend → restart kratos → verify new kid → wait ~12min = 10m TTL + skew → prune; rollback before prune) and the emergency path (replace with a single key → every leaked-key token fails signature → forced re-login; the §9 denylist is moot since the signature is already invalid). Verified the CLI live against the committed dev JWKS (bare→1, --prepend→2 with old kid second, --prune→1); jwks.json untouched. Docs/CLI-only, covered by units (per the §9 precedent, no new browser E2E). README Status + Layout updated. typecheck + 335 units green (333 → 335).

src/gen-jwks.test.ts

@@ -5,7 +5,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { createPrivateKey, sign, type JsonWebKey } from "node:crypto";
-import { generateJwks } from "./gen-jwks.ts";
+import { generateJwks, rotateJwks } from "./gen-jwks.ts";
 import { verifyJws } from "./jwt.ts";
 
 const b64url = (s: string) => Buffer.from(s).toString("base64url");
@@ -30,6 +30,21 @@ test("the committed dev JWKS is a valid ES256 signing key importable by node:cry
   assert.doesNotThrow(() => createPrivateKey({ key: k, format: "jwk" }), "Kratos can load it to sign");
 });
 
+test("rotateJwks prepends a fresh signing key, keeping the old ones for in-flight verification", () => {
+  const old = generateJwks(); // a one-key set, as Kratos signs with the first
+  const rotated = rotateJwks(old);
+  assert.equal(rotated.keys.length, old.keys.length + 1);
+  assert.notEqual(rotated.keys[0]!.kid, old.keys[0]!.kid, "the new key is first (Kratos signs with it) with a fresh kid");
+  assert.deepEqual(rotated.keys.slice(1), old.keys, "old keys are preserved in order so unexpired JWTs still verify");
+  assert.equal(rotated.keys[0]!.alg, "ES256");
+});
+
+test("rotateJwks --prune keeps only the newest (first) key, dropping superseded ones", () => {
+  const twoKeys = rotateJwks(generateJwks()); // prepend → 2 keys
+  const pruned = rotateJwks(twoKeys, { prune: true });
+  assert.deepEqual(pruned.keys, [twoKeys.keys[0]], "only the active signing key remains");
+});
+
 test("a JWS signed with a generated key verifies via our own verifier (§4 reads what Kratos signs)", () => {
   const key = generateJwks().keys[0]!;
   const head = b64url(JSON.stringify({ alg: "ES256", kid: key.kid }));