/** * The release trust ceremony (RFC-0046 §9, #226; runbook: docs/security/release-signing-keys.md). * Node built-ins, plus `@cloudhal/release-verify` (loaded when signing) to check every signed * document the way consumers do before it is written. No command ever prints a private key. * * node scripts/release-keys.ts root-init --key-id cloudhal-root-2026a --out [--passphrase-file ] * An Ed25519 root: /.key.enc (PKCS#8, AES-256-CBC under PBKDF2-HMAC-SHA256 with * 600,000 iterations of the passphrase) + .pub.json. sign-keys also reads older roots. * node scripts/release-keys.ts yank-init --key-id cloudhal-yank-2026a --out * The yank key: /.pem (mode 0600, for the RELEASE_YANK_KEY secret) + .pub.json. * node scripts/release-keys.ts sign-keys --root-key .key.enc --root-pub .pub.json * [--source security/keys.source.json] [--out security] [--months 12] [--passphrase-file ] * keys.json + keys.json.sig, signed by the root, expiring after --months (at most 13). * node scripts/release-keys.ts sign-yanked --key-id [--key-file ] [--list security/yank-list.json] * [--keys security/keys.json] [--out ] [--published ] [--first-run | --rotate] * [--accept-expired] [--yank= | --revoke=] [--reason=] * yanked.json + yanked.json.sig, expiring in 30 days. The key comes from --key-file or the * RELEASE_YANK_KEY environment variable. It refuses a key that is not the active yank key * of keys.json. The published list (`` and `.sig`) must verify as a consumer * would before anything of it is carried forward. The list signed is every published entry * (append-only), the source, and the emergency `--yank`/`--revoke` entries (comma-separated); * its serial is one above the published one. `--rotate`: the first list of a new yank key, * nothing of the old key's list carried forward, serial 1 (runbook, Rotation). */ import { createPrivateKey, createPublicKey, generateKeyPairSync, type KeyObject, sign, verify, } from "node:crypto"; import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import path from "node:path"; import { createInterface } from "node:readline"; import { fileURLToPath } from "node:url"; import { parseArgs } from "node:util"; import { canonicalJson, sha256 } from "./release-bundle/manifest.ts"; import { encryptPkcs8 } from "./release-keys/pkcs8.ts"; import { checkAppendOnly, mergeYankList, type PublishedPair, readPublished, verifyPublished, type YankExtra, type YankSource, } from "./release-keys/yank-list.ts"; export { type Pbes2Params, ROOT_KDF_ITERATIONS, readPbes2 } from "./release-keys/pkcs8.ts"; export { checkAppendOnly, MAX_EXTRA, mergeYankList, parseExtra, type YankExtra, type YankSource, } from "./release-keys/yank-list.ts"; const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); const SPKI_ED25519 = Buffer.from("302a300506032b6570032100", "hex"); const KEY_ID = /^[a-z0-9][a-z0-9-]{2,63}$/; const DAY_MS = 86_400_000; type Log = (line: string) => void; export interface PublicKeyFile { readonly keyId: string; /** Raw 32-byte Ed25519 public key, base64. */ readonly publicKey: string; } /** The raw 32-byte public key (base64) of a private or public Ed25519 key. */ const rawPublicKey = (key: KeyObject): string => { const pub = key.type === "public" ? key : createPublicKey(key); const der = pub.export({ format: "der", type: "spki" }); return Buffer.from(der.subarray(SPKI_ED25519.length)).toString("base64"); }; const publicKeyOf = (raw: string): KeyObject => createPublicKey({ key: Buffer.concat([SPKI_ED25519, Buffer.from(raw, "base64")]), format: "der", type: "spki", }); /** Whole seconds, `YYYY-MM-DDTHH:MM:SSZ`, as every contract timestamp here. */ const iso = (ms: number) => new Date(Math.floor(ms / 1000) * 1000).toISOString().replace(".000Z", "Z"); function checkKeyId(keyId: string, role: "root" | "yank"): void { if (!KEY_ID.test(keyId)) throw new Error(`not a key id: ${keyId}`); if (!keyId.includes(`-${role}-`)) throw new Error(`a ${role} key id names its role: cloudhal-${role}-`); } function writeNew(file: string, content: string | Uint8Array, mode = 0o644): void { if (existsSync(file)) throw new Error(`${file} exists; refusing to overwrite a key`); writeFileSync(file, content, { mode, flag: "wx" }); } function writePublic(out: string, keyId: string, key: KeyObject, log: Log): PublicKeyFile { const pub: PublicKeyFile = { keyId, publicKey: rawPublicKey(key) }; writeNew(path.join(out, `${keyId}.pub.json`), `${JSON.stringify(pub, null, 2)}\n`); const fingerprint = sha256(Buffer.from(pub.publicKey, "base64")); log(`${keyId}: public key ${pub.publicKey} (SHA-256 of the raw key ${fingerprint})`); return pub; } /** An Ed25519 root, its private key written only encrypted with `passphrase`. */ export function rootInit(o: { keyId: string; out: string; passphrase: string; log: Log; }): PublicKeyFile { checkKeyId(o.keyId, "root"); if (o.passphrase.length < 12) throw new Error("the passphrase must be at least 12 characters"); mkdirSync(o.out, { recursive: true }); const { privateKey, publicKey } = generateKeyPairSync("ed25519"); // Not `privateKey.export({ cipher })`: that is 2,048 PBKDF2 iterations, with no way to ask for more. const enc = encryptPkcs8(privateKey, o.passphrase); writeNew(path.join(o.out, `${o.keyId}.key.enc`), enc, 0o600); o.log(`wrote ${o.keyId}.key.enc (encrypted; seal two copies with the passphrase, apart)`); return writePublic(o.out, o.keyId, publicKey, o.log); } /** The yank key, its PEM written with mode 0600 for the `RELEASE_YANK_KEY` secret. */ export function yankInit(o: { keyId: string; out: string; log: Log }): PublicKeyFile { checkKeyId(o.keyId, "yank"); mkdirSync(o.out, { recursive: true }); const { privateKey, publicKey } = generateKeyPairSync("ed25519"); writeNew( path.join(o.out, `${o.keyId}.pem`), privateKey.export({ format: "pem", type: "pkcs8" }), 0o600, ); o.log( `wrote ${o.keyId}.pem: gh secret set RELEASE_YANK_KEY --env release-yank < ${o.keyId}.pem, then move it offline`, ); return writePublic(o.out, o.keyId, publicKey, o.log); } /** `ms` plus `months` calendar months (UTC), clamped to the target month's last day. */ function addMonths(ms: number, months: number): number { const d = new Date(ms); const target = new Date( Date.UTC( d.getUTCFullYear(), d.getUTCMonth() + months, 1, d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), ), ); const last = new Date( Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0), ).getUTCDate(); target.setUTCDate(Math.min(d.getUTCDate(), last)); return target.getTime(); } /** * The consumer's own verifier, which checks the exact signed bytes before anything is written * (schema, unique key ids, windows, timestamps, sizes). Needs `@cloudhal/release-verify`'s * dependencies installed (the workflow installs that one package, without scripts). */ async function verifier() { try { return await import("../packages/release-verify/src/index.ts"); } catch (e) { throw new Error( `the release verifier is not installed (pnpm install --filter @cloudhal/release-verify): ${(e as Error).message}`, ); } } /** Runs `check`; a refusal names what was about to be signed. */ async function selfCheck(what: string, check: () => Promise): Promise { try { await check(); } catch (e) { throw new Error(`the signed ${what} does not verify, nothing written: ${(e as Error).message}`); } } function signDocument(doc: unknown, key: KeyObject, check: KeyObject) { const bytes = Buffer.from(canonicalJson(doc)); const signature = sign(null, bytes, key); if (signature.length !== 64 || !verify(null, bytes, check, signature)) throw new Error("the signature does not verify with the expected public key"); return { document: new Uint8Array(bytes), signature: new Uint8Array(signature) }; } /** `keys.json` + `keys.json.sig`, signed by the root; the root key must match `rootPub`. */ export async function signKeys(o: { rootKey: string; passphrase: string; rootPub: PublicKeyFile; source: { keys: unknown[] }; out: string; now: number; months?: number; }): Promise<{ document: Uint8Array; signature: Uint8Array }> { const months = o.months ?? 12; if (!(months >= 1 && months <= 13)) throw new Error("keys.json is valid for 1 to 13 months"); checkKeyId(o.rootPub.keyId, "root"); let key: KeyObject; try { key = createPrivateKey({ key: o.rootKey, passphrase: o.passphrase }); } catch { throw new Error("the root key does not open with this passphrase"); } if (rawPublicKey(key) !== o.rootPub.publicKey) throw new Error(`the root key is not ${o.rootPub.keyId}`); if (!Array.isArray(o.source.keys) || o.source.keys.length === 0) throw new Error("the source lists no keys"); const issued = Math.floor(o.now / 1000) * 1000; const doc = { schemaVersion: 1, format: "cloudhal.release-keys@1", issuedAt: iso(issued), expires: iso(addMonths(issued, months)), signing: { keyId: o.rootPub.keyId, algorithm: "Ed25519", signature: "keys.json.sig" }, keys: o.source.keys, }; const signed = signDocument(doc, key, publicKeyOf(o.rootPub.publicKey)); const rv = await verifier(); await selfCheck("key list", () => rv.verifyKeys({ ...signed, roots: { [o.rootPub.keyId]: { publicKey: o.rootPub.publicKey } }, now: new Date(issued), }), ); mkdirSync(o.out, { recursive: true }); writeFileSync(path.join(o.out, "keys.json"), signed.document); writeFileSync(path.join(o.out, "keys.json.sig"), signed.signature); return signed; } /** * `yanked.json` + `yanked.json.sig`, signed by the yank key that `keys` lists as active. The * published list is verified before anything of it is carried forward (release-keys/yank-list.ts). */ export async function signYanked(o: { keyId: string; keyPem: string; /** `keys.json` and its signature, verified here against `roots` (default: the pinned root). */ keyList: { document: Uint8Array; signature: Uint8Array }; roots?: Readonly>; source: YankSource; /** The published `yanked.json` and `.sig` (none for the very first list). */ published: PublishedPair | undefined; /** The first run after a yank-key rotation: the old key's list is not carried forward. */ rotate?: boolean; /** Carry forward a published list that expired during an outage (verified as of its issue). */ acceptExpired?: boolean; extra?: YankExtra; out: string; now: number; }): Promise<{ document: Uint8Array; signature: Uint8Array }> { const rv = await verifier(); const keys = await rv.verifyKeys({ ...o.keyList, ...(o.roots ? { roots: o.roots } : {}), now: new Date(o.now), }); checkKeyId(o.keyId, "yank"); const listed = keys.document.keys.find((k) => k.keyId === o.keyId); if (listed?.role !== "yank" || listed.status !== "active") throw new Error(`keys.json does not list ${o.keyId} as an active yank key`); if (o.now < Date.parse(listed.notBefore) || o.now > Date.parse(listed.notAfter)) throw new Error(`${o.keyId} is outside its window`); let key: KeyObject; try { key = createPrivateKey(o.keyPem); } catch { throw new Error("the yank key is missing or not a PKCS#8 PEM key"); } if (rawPublicKey(key) !== listed.publicKey) throw new Error(`the yank key given is not ${o.keyId} of keys.json`); if (!Array.isArray(o.source.versions) || !Array.isArray(o.source.revokedKeys)) throw new Error("the yank list source needs versions and revokedKeys"); const published = await verifyPublished({ rv, keys, keyId: o.keyId, published: o.published, now: o.now, ...(o.rotate ? { rotate: true } : {}), ...(o.acceptExpired ? { acceptExpired: true } : {}), }); const list = mergeYankList(o.source, published?.list, o.extra ?? {}, o.now); checkAppendOnly(list, published?.list); const issued = Math.floor(o.now / 1000) * 1000; const doc = { schemaVersion: 1, format: "cloudhal.release-yank-list@1", // One more than the published list's, so a consumer that keeps state refuses a rollback. serial: (published?.serial ?? 0) + 1, issuedAt: iso(issued), expires: iso(issued + 30 * DAY_MS), signing: { keyId: o.keyId, algorithm: "Ed25519", signature: "yanked.json.sig" }, versions: list.versions, revokedKeys: list.revokedKeys, }; const signed = signDocument(doc, key, publicKeyOf(listed.publicKey)); // The verified published list is the memory this one must keep, as consumers do. await selfCheck("yank list", () => rv.verifyYanked({ ...signed, keys, now: new Date(issued), ...(published ? { memory: published.memory } : {}), }), ); mkdirSync(o.out, { recursive: true }); writeFileSync(path.join(o.out, "yanked.json"), signed.document); writeFileSync(path.join(o.out, "yanked.json.sig"), signed.signature); return signed; } const readJson = (file: string): T => JSON.parse(readFileSync(file, "utf8")) as T; /** A passphrase from a file, or typed twice on the terminal without echo. */ async function passphrase(file: string | undefined, twice: boolean): Promise { if (file) return readFileSync(file, "utf8").replace(/\r?\n$/, ""); if (!process.stdin.isTTY) throw new Error("no terminal: pass --passphrase-file"); const ask = (prompt: string) => new Promise((resolve) => { const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true }); const out = rl as unknown as { _writeToOutput: (s: string) => void }; out._writeToOutput = (s: string) => { if (s.startsWith(prompt)) process.stdout.write(prompt); }; rl.question(prompt, (answer) => { rl.close(); process.stdout.write("\n"); resolve(answer); }); }); const first = await ask("Root passphrase: "); if (twice && (await ask("Again: ")) !== first) throw new Error("the passphrases differ"); return first; } /** `sign-yanked` from the parsed flags (see the file comment). */ async function signYankedCli( v: Readonly>, keyId: string, log: Log, ): Promise { const str = (name: string) => (typeof v[name] === "string" ? (v[name] as string) : undefined); const security = path.join(ROOT, "security"); const keyPem = str("key-file") ? readFileSync(str("key-file") as string, "utf8") : (process.env.RELEASE_YANK_KEY ?? ""); delete process.env.RELEASE_YANK_KEY; const out = str("out") ?? path.join(ROOT, ".build/yank-list"); const keysFile = str("keys") ?? path.join(security, "keys.json"); await signYanked({ keyId, keyPem, keyList: { document: readFileSync(keysFile), signature: readFileSync(`${keysFile}.sig`) }, // Default: the pinned root. --root-pub only before the root is pinned (or in tests). ...(str("root-pub") ? (() => { const pub = readJson(str("root-pub") as string); return { roots: { [pub.keyId]: { publicKey: pub.publicKey } } }; })() : {}), source: readJson(str("list") ?? path.join(security, "yank-list.json")), published: await readPublished(str("published"), v["first-run"] === true), ...(v.rotate === true ? { rotate: true } : {}), ...(v["accept-expired"] === true ? { acceptExpired: true } : {}), extra: { ...(str("yank") ? { yank: str("yank") as string } : {}), ...(str("revoke") ? { revoke: str("revoke") as string } : {}), ...(str("reason") ? { reason: str("reason") as string } : {}), }, out, now: Date.now(), }); log(`signed ${path.join(out, "yanked.json")} and yanked.json.sig`); } export async function main(argv: readonly string[], log: Log = console.log): Promise { const [command, ...rest] = argv; const { values: v } = parseArgs({ args: rest, options: { "key-id": { type: "string" }, out: { type: "string" }, "passphrase-file": { type: "string" }, "root-key": { type: "string" }, "root-pub": { type: "string" }, source: { type: "string" }, months: { type: "string" }, "key-file": { type: "string" }, list: { type: "string" }, keys: { type: "string" }, published: { type: "string" }, "first-run": { type: "boolean" }, rotate: { type: "boolean" }, "accept-expired": { type: "boolean" }, yank: { type: "string" }, revoke: { type: "string" }, reason: { type: "string" }, }, }); const need = (name: keyof typeof v) => { const value = v[name]; if (typeof value !== "string") throw new Error(`--${name} is required`); return value; }; const security = path.join(ROOT, "security"); if (command === "root-init") { const pass = await passphrase(v["passphrase-file"], true); rootInit({ keyId: need("key-id"), out: need("out"), passphrase: pass, log }); } else if (command === "yank-init") { yankInit({ keyId: need("key-id"), out: need("out"), log }); } else if (command === "sign-keys") { const pass = await passphrase(v["passphrase-file"], false); const out = v.out ?? security; await signKeys({ rootKey: readFileSync(need("root-key"), "utf8"), passphrase: pass, rootPub: readJson(need("root-pub")), source: readJson<{ keys: unknown[] }>(v.source ?? path.join(security, "keys.source.json")), out, now: Date.now(), ...(v.months ? { months: Number(v.months) } : {}), }); log(`signed ${path.join(out, "keys.json")} and keys.json.sig`); } else if (command === "sign-yanked") { await signYankedCli(v, need("key-id"), log); } else { throw new Error( "usage: node scripts/release-keys.ts root-init|yank-init|sign-keys|sign-yanked …", ); } } if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { try { await main(process.argv.slice(2)); } catch (e) { console.error(`release-keys: ${(e as Error).message}`); process.exitCode = 1; } }