@cloudhal/release-verify 0.0.0-stage → 0.10.0

package/dist/src/trust.js

@@ -0,0 +1,248 @@
+/**
+ * The signed key list and yank list (RFC-0046 §9, #226), and how they change what a consumer
+ * trusts: only ever downwards.
+ *
+ * - `verifyKeys`: `keys.json` + `keys.json.sig`, signed by a pinned root, fresh (`issuedAt` ≤
+ *   now < `expires`, at most 13 months apart).
+ * - `verifyYanked`: `yanked.json` + `yanked.json.sig`, signed by a yank-role key that a verified
+ *   `keys.json` lists as active and valid now, fresh (`expires` exactly 30 days after `issuedAt`;
+ *   past it the list is stale, which blocks new installs only), and not rolled back below a
+ *   `serial` the consumer has already seen.
+ * - `mergeTrust`: pinned keys reduced by both: revoke, mark retiring, narrow the validity window.
+ *   A key the lists name but the consumer does not pin is never added.
+ */
+import { sha256Hex, verifyEd25519 } from "./crypto.js";
+import { refuse } from "./errors.js";
+                                                                                             
+                                                                        
+import { validateReleaseKeys, validateReleaseYankList } from "./generated/validators.js";
+import { fromBase64,                                   } from "./keys.js";
+import { checkKeysMemory, checkYankMemory,                 } from "./yank-memory.js";
+
+/** Root keys: they sign only `keys.json`. Pinned at the root ceremony; empty until then. */
+                                                                                
+
+/**
+ * The offline root's public key (docs/security/release-signing-keys.md, kept equal by
+ * test/package.test.ts), pinned at the owner's root ceremony on 2026-11-15. It signs only
+ * `keys.json`; a rotation of the root is a new pinned entry in a reviewed release.
+ */
+export const PINNED_ROOTS           = Object.freeze({
+  "cloudhal-root-2026a": Object.freeze({
+    publicKey: "/rtDvlSlCYV402NiA/7OOFk+ryBv4DIWmkqwRyrVzqw=",
+  }),
+});
+
+export const KEYS_FILE = "keys.json";
+export const YANKED_FILE = "yanked.json";
+/** Where the lists live (RFC-0046 §9); `<file>.sig` next to each. */
+export const TRUST_BASE_URL = "https://cloudhal.dev/.well-known/cloudhal/";
+
+const MAX_KEYS_BYTES = 64 * 1024;
+const MAX_YANKED_BYTES = 256 * 1024;
+/** A list issued a little in the future is a clock skew, not an attack. */
+const SKEW_MS = 5 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+                                  
+                                     
+                                              
+                          
+ 
+
+                                   
+                                     
+                          
+ 
+
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/** The signed JSON document in `bytes` and its signing key id, before its signature is checked. */
+function signedDoc(
+  bytes            ,
+  signature            ,
+  max        ,
+  code                                          ,
+)                                  {
+  const what = code === "key-list-invalid" ? "keys.json" : "yanked.json";
+  if (bytes.length > max) refuse(code, `${what} is above ${max} bytes`);
+  if (signature.length !== 64) refuse(code, `${what}.sig is not 64 bytes`);
+  let doc         ;
+  try {
+    doc = JSON.parse(utf8.decode(bytes));
+  } catch {
+    return refuse(code, `${what} is not UTF-8 JSON`);
+  }
+  const keyId = (doc                                            )?.signing?.keyId;
+  if (typeof keyId !== "string") refuse(code, `${what} names no signing key`);
+  return { doc, keyId: keyId           };
+}
+
+/** `iso` plus `months` calendar months (UTC), clamped to the target month's last day (01-31 + 1 → 02-28/29). */
+export function addMonths(iso        , months        )         {
+  const d = new Date(iso);
+  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();
+}
+
+/** Verifies `keys.json` (see the file comment); throws a `ReleaseVerifyError`. */
+export async function verifyKeys(input   
+                       
+                        
+                   
+             
+                                                                                            
+                      
+ )                           {
+  const now = (input.now ?? new Date()).getTime();
+  const { doc, keyId } = signedDoc(
+    input.document,
+    input.signature,
+    MAX_KEYS_BYTES,
+    "key-list-invalid",
+  );
+  const roots = input.roots ?? PINNED_ROOTS;
+  const root = Object.hasOwn(roots, keyId) ? roots[keyId] : undefined;
+  const raw = root ? fromBase64(root.publicKey) : undefined;
+  if (raw?.length !== 32)
+    refuse("key-list-invalid", `keys.json is signed by ${keyId}, not a pinned root`);
+  if (!(await verifyEd25519(raw              , input.document, input.signature)))
+    refuse("key-list-invalid", `keys.json.sig does not verify with ${keyId}`);
+  if (!validateReleaseKeys(doc)) refuse("key-list-invalid", "keys.json is not a valid key list");
+  const list = doc;
+  const ids = new Set        ();
+  for (const k of list.keys) {
+    if (ids.has(k.keyId)) refuse("key-list-invalid", `keys.json lists ${k.keyId} twice`);
+    ids.add(k.keyId);
+    if (!(Date.parse(k.notBefore) < Date.parse(k.notAfter)))
+      refuse("key-list-invalid", `${k.keyId}: notBefore is not before notAfter`);
+  }
+  // One active yank key at a time: rotation replaces it, so a thief of one key cannot switch to
+  // another to start a fresh memory (yank-memory.ts).
+  const activeYank = list.keys.filter((k) => k.role === "yank" && k.status === "active");
+  if (activeYank.length > 1)
+    refuse(
+      "key-list-invalid",
+      `keys.json lists ${activeYank.length} active yank keys (${activeYank.map((k) => k.keyId).join(", ")}); at most one`,
+    );
+  const issued = Date.parse(list.issuedAt);
+  const expires = Date.parse(list.expires);
+  if (!(issued < expires) || expires > addMonths(list.issuedAt, 13))
+    refuse("key-list-invalid", "keys.json must expire after issuedAt and within 13 months");
+  if (issued > now + SKEW_MS) refuse("key-list-invalid", "keys.json is issued in the future");
+  if (now >= expires) refuse("key-list-expired", `keys.json expired on ${list.expires}`);
+  checkKeysMemory(list, input.memory);
+  return { document: list, sha256: await sha256Hex(input.document) };
+}
+
+/**
+ * Verifies `yanked.json` against a verified key list (see the file comment). A consumer that can
+ * keep state passes its `memory` and stores `rememberYanks(result, keys, memory)` (yank-memory.ts):
+ * a replayed older `keys.json`, a revoked or replaced yank key, a lower serial or a dropped entry
+ * is refused. A stateless consumer (a Worker) cannot detect a replay or an un-yank: for it, a
+ * stolen yank key can un-yank and un-revoke until the root rotates the yank key.
+ */
+export async function verifyYanked(input   
+                       
+                        
+                        
+             
+                      
+ )                            {
+  const now = (input.now ?? new Date()).getTime();
+  const { doc, keyId } = signedDoc(
+    input.document,
+    input.signature,
+    MAX_YANKED_BYTES,
+    "yank-list-invalid",
+  );
+  const signer                        = input.keys.document.keys.find((k) => k.keyId === keyId);
+  if (signer?.role !== "yank" || signer.status !== "active")
+    refuse("yank-list-invalid", `yanked.json is signed by ${keyId}, not an active yank key`);
+  const key = signer             ;
+  if (now < Date.parse(key.notBefore) || now > Date.parse(key.notAfter))
+    refuse("yank-list-invalid", `the yank key ${keyId} is not valid now`);
+  const raw = fromBase64(key.publicKey)              ;
+  if (!(await verifyEd25519(raw, input.document, input.signature)))
+    refuse("yank-list-invalid", `yanked.json.sig does not verify with ${keyId}`);
+  if (!validateReleaseYankList(doc))
+    refuse("yank-list-invalid", "yanked.json is not a valid yank list");
+  const list = doc;
+  const issued = Date.parse(list.issuedAt);
+  if (Date.parse(list.expires) - issued !== 30 * DAY_MS)
+    refuse("yank-list-invalid", "yanked.json must expire exactly 30 days after issuedAt");
+  if (issued > now + SKEW_MS) refuse("yank-list-invalid", "yanked.json is issued in the future");
+  checkYankMemory(list, input.keys.document, input.memory);
+  if (now >= Date.parse(list.expires))
+    refuse(
+      "stale-yank-list",
+      `yanked.json expired on ${list.expires}; new installs wait for a fresh one`,
+    );
+  return { document: list, sha256: await sha256Hex(input.document) };
+}
+
+const RANK                                       = { active: 0, retiring: 1, revoked: 2 };
+const later = (a                    , b        ) =>
+  a === undefined || Date.parse(b) > Date.parse(a) ? b : a;
+const earlier = (a                    , b        ) =>
+  a === undefined || Date.parse(b) < Date.parse(a) ? b : a;
+
+/**
+ * `pinned` reduced by a verified key list and yank list (RFC-0046 §9). For each pinned key: a
+ * listing with another public key or another role revokes it; otherwise the stricter status wins
+ * and the window narrows to the intersection; `listed` records that a fresh list names it. A
+ * revocation in either list revokes it. Keys the lists name but `pinned` lacks are not added.
+ */
+export function mergeTrust(
+  pinned             ,
+  lists                                                        = {},
+)              {
+  const out                             = {};
+  const revokedByYank = new Set(lists.yanked?.document.revokedKeys.map((r) => r.keyId) ?? []);
+  for (const [keyId, key] of Object.entries(pinned)) {
+    let next             = { ...key };
+    const listed = lists.keys?.document.keys.find((k) => k.keyId === keyId);
+    if (listed) {
+      const conflict = listed.publicKey !== key.publicKey || listed.role !== "release";
+      const status                       = conflict
+        ? "revoked"
+        : RANK[listed.status] > RANK[key.status]
+          ? listed.status
+          : key.status;
+      next = {
+        ...next,
+        status,
+        notBefore: later(key.notBefore, listed.notBefore),
+        notAfter: earlier(key.notAfter, listed.notAfter),
+        listed: status !== "revoked",
+      };
+    } else if (next.listed) {
+      // Only a list verified now may confirm a key; a caller's own flag is not trusted.
+      next = { ...next, listed: false };
+    }
+    if (revokedByYank.has(keyId)) next = { ...next, status: "revoked", listed: false };
+    out[keyId] = Object.freeze(next);
+  }
+  return Object.freeze(out);
+}
+
+/** The yank entry for `version`, if the verified list yanks it. */
+export function yankOf(
+  yanked                              ,
+  version        ,
+)                                                   {
+  return yanked?.document.versions.find((v) => v.version === version);
+}

package/dist/src/urls.d.ts

@@ -0,0 +1,8 @@
+export declare const RELEASE_REPOSITORY = "cloudhal-dev/cloudhal";
+/** The five assets of `version`, in §1's order (tarball, manifest, statement, signature, Sigstore). */
+export declare function releaseAssetNames(version: string): string[];
+/** `{ name, url }` of each asset of `version` on the GitHub release `v<version>`. */
+export declare function releaseAssetUrls(version: string): {
+    name: string;
+    url: string;
+}[];

package/dist/src/urls.js

@@ -0,0 +1,37 @@
+/**
+ * Where a release's five assets (RFC-0046 §1) are downloaded from. Downloading is discovery only,
+ * never a trust factor: `verifyRelease` decides.
+ */
+import {
+  MANIFEST_FILE,
+  SIGNATURE_FILE,
+  STATEMENT_FILE,
+  sigstoreName,
+  tarballName,
+} from "./limits.js";
+
+export const RELEASE_REPOSITORY = "cloudhal-dev/cloudhal";
+
+/** `CloudhalVersion` of the contracts: anchored, bounded alternatives, no overlapping runs. */
+const VERSION =
+  /^(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})(-[0-9A-Za-z.-]{1,64})?$/;
+
+/** The five assets of `version`, in §1's order (tarball, manifest, statement, signature, Sigstore). */
+export function releaseAssetNames(version        )           {
+  if (!VERSION.test(version)) throw new TypeError(`not a Cloudhal version: ${version}`);
+  return [
+    tarballName(version),
+    MANIFEST_FILE,
+    STATEMENT_FILE,
+    SIGNATURE_FILE,
+    sigstoreName(version),
+  ];
+}
+
+/** `{ name, url }` of each asset of `version` on the GitHub release `v<version>`. */
+export function releaseAssetUrls(version        )                                  {
+  return releaseAssetNames(version).map((name) => ({
+    name,
+    url: `https://github.com/${RELEASE_REPOSITORY}/releases/download/v${version}/${name}`,
+  }));
+}

package/dist/src/verify.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `verifyRelease` (RFC-0046 §2, §11a): the six steps of §2 in order, with no soft-fail anywhere.
+ *
+ *   1. sizes: the statement at most 4096 bytes, the signature exactly 64;
+ *   2. Ed25519 over the exact statement bytes with a trusted key for `signing.keyId`, valid at
+ *      the statement's `createdAt` and still trusted now (§9), and the version not yanked;
+ *   3. the statement is for the requested version and channel (invariant 7);
+ *   4. the statement's schema and invariants 1, 2, 3 and 6;
+ *   5. the manifest: size and SHA-256 equal the statement's, schema, invariants 4 and 5, the
+ *      signature form, `planVersion`, and every listing (paths, §7 limits);
+ *   6. the tarball, read once: size and SHA-256 equal the statement's.
+ *
+ * `entries()` then reads the tarball a second time and yields each entry only after its path is
+ * safe and its size and SHA-256 equal its listing; it throws on an unlisted entry, on anything
+ * outside §7's tar format and, at the end, on a listed entry that never came. A consumer may upload
+ * entries while it iterates; it must not activate a deployment until the iteration has finished.
+ */
+import { type ListedPart, type Worker } from "./documents.js";
+import type { ReleaseManifest } from "./generated/release-manifest.js";
+import type { ReleaseStatement } from "./generated/release-statement.js";
+import { type ReleaseKeys } from "./keys.js";
+import { type ByteSource } from "./tar.js";
+import { type VerifiedYankList } from "./trust.js";
+export interface VerifyReleaseInput {
+    /** What the consumer asked for; `channel` defaults to the one the version implies. */
+    readonly request: {
+        readonly version: string;
+        readonly channel?: "stable" | "next";
+    };
+    /** The exact downloaded bytes; nothing is re-serialised. */
+    readonly statement: Uint8Array;
+    readonly signature: Uint8Array;
+    readonly manifest: Uint8Array;
+    /** Opens the tarball; called twice (the digest pass, then `entries()`). */
+    readonly tarball: () => ByteSource | Promise<ByteSource>;
+    /** The highest `planVersion` the caller supports. */
+    readonly planVersion: number;
+    /** The trusted keys (default `PINNED_KEYS`); see keys.ts. */
+    readonly keys?: ReleaseKeys;
+    /** Key ids to distrust on top of `keys` (reduce-only). */
+    readonly revoked?: readonly string[];
+    /** A verified yank list (`verifyYanked`): a yanked version is refused. Pass `keys` through `mergeTrust` to apply its revocations too. */
+    readonly yanked?: VerifiedYankList;
+    /** The time keys are checked against (default: now). */
+    readonly now?: Date;
+}
+export interface VerifiedEntry {
+    readonly worker: Worker | null;
+    readonly kind: "module" | "asset" | "starter";
+    /** The module path, the asset path (`/x`), or `starter/<file>`. */
+    readonly path: string;
+    /** The tar path (`site/modules/x.mjs`). */
+    readonly tarPath: string;
+    /** A module's type from the manifest (`esm`, `cjs`, `wasm`, `text`, `data`). */
+    readonly type?: string;
+    readonly bytes: Uint8Array;
+}
+export interface VerifiedRelease {
+    readonly statement: ReleaseStatement;
+    readonly manifest: ReleaseManifest;
+    entries(): AsyncGenerator<VerifiedEntry>;
+}
+export declare function verifyRelease(input: VerifyReleaseInput): Promise<VerifiedRelease>;
+/**
+ * The second pass (step 6's entries), exported for the producer's self-check
+ * (scripts/release-bundle/verify.ts); not part of the package's public exports.
+ */
+export declare function verifiedEntries(open: VerifyReleaseInput["tarball"], listed: ReadonlyMap<string, ListedPart>, mtime: number): AsyncGenerator<VerifiedEntry>;

package/dist/src/verify.js

@@ -0,0 +1,171 @@
+/**
+ * `verifyRelease` (RFC-0046 §2, §11a): the six steps of §2 in order, with no soft-fail anywhere.
+ *
+ *   1. sizes: the statement at most 4096 bytes, the signature exactly 64;
+ *   2. Ed25519 over the exact statement bytes with a trusted key for `signing.keyId`, valid at
+ *      the statement's `createdAt` and still trusted now (§9), and the version not yanked;
+ *   3. the statement is for the requested version and channel (invariant 7);
+ *   4. the statement's schema and invariants 1, 2, 3 and 6;
+ *   5. the manifest: size and SHA-256 equal the statement's, schema, invariants 4 and 5, the
+ *      signature form, `planVersion`, and every listing (paths, §7 limits);
+ *   6. the tarball, read once: size and SHA-256 equal the statement's.
+ *
+ * `entries()` then reads the tarball a second time and yields each entry only after its path is
+ * safe and its size and SHA-256 equal its listing; it throws on an unlisted entry, on anything
+ * outside §7's tar format and, at the end, on a listed entry that never came. A consumer may upload
+ * entries while it iterates; it must not activate a deployment until the iteration has finished.
+ */
+
+import { incrementalSha256, sha256Hex, verifyEd25519 } from "./crypto.js";
+import {
+  checkManifestDoc,
+  checkRequested,
+  checkStatementDoc,
+                  
+  listedParts,
+  parseJson,
+              
+} from "./documents.js";
+import { refuse } from "./errors.js";
+                                                                       
+                                                                         
+import { checkKeyWindow, PINNED_KEYS,                   trustedKey } from "./keys.js";
+import { LIMITS } from "./limits.js";
+import { checkPath } from "./paths.js";
+import {                  chunksOf, gunzip, readTar } from "./tar.js";
+import {                        yankOf } from "./trust.js";
+
+                                     
+                                                                                        
+                                                                                       
+                                                              
+                                 
+                                 
+                                
+                                                                             
+                                                           
+                                                       
+                               
+                                                               
+                              
+                                                            
+                                       
+                                                                                                                                           
+                                     
+                                                          
+                      
+ 
+
+                                
+                                 
+                                                
+                                                                     
+                        
+                                             
+                           
+                                                                                  
+                         
+                             
+ 
+
+                                  
+                                       
+                                     
+                                           
+ 
+
+export async function verifyRelease(input                    )                           {
+  // 1.
+  if (input.statement.length > LIMITS.statementBytes)
+    refuse("statement-too-large", `the statement is above ${LIMITS.statementBytes} bytes`);
+  if (input.signature.length !== 64)
+    refuse("signature-size", `the signature is ${input.signature.length} bytes, not 64`);
+  // 2.
+  const doc = parseJson(input.statement, "statement-invalid");
+  const keyId = (doc                                            )?.signing?.keyId;
+  if (typeof keyId !== "string") refuse("statement-invalid", "the statement names no key");
+  const { raw, key } = trustedKey(input.keys ?? PINNED_KEYS, input.revoked ?? [], keyId);
+  if (!(await verifyEd25519(raw, input.statement, input.signature)))
+    refuse("signature-invalid", `the signature does not verify with ${keyId}`);
+  // 3. and 4.
+  checkRequested(doc, input.request.version, input.request.channel);
+  const statement = checkStatementDoc(doc, input.statement.length);
+  // §9: the key was valid when the statement was created, and is still trusted now.
+  checkKeyWindow(keyId, key, statement.createdAt, input.now ?? new Date());
+  const yank = yankOf(input.yanked, statement.version);
+  if (yank) refuse("yanked", `${statement.version} is yanked: ${yank.reason}`);
+  // 5.
+  if (
+    input.manifest.length !== statement.manifest.bytes ||
+    (await sha256Hex(input.manifest)) !== statement.manifest.sha256
+  )
+    refuse("manifest-mismatch", "manifest.json is not the file the statement pins");
+  const manifest = checkManifestDoc(
+    parseJson(input.manifest, "manifest-invalid"),
+    statement,
+    input.planVersion,
+  );
+  // 6.
+  await checkTarballDigest(await input.tarball(), statement.tarball);
+  const listed = listedParts(manifest);
+  const mtime = Date.parse(statement.createdAt) / 1000;
+  return {
+    statement,
+    manifest,
+    entries: () => verifiedEntries(input.tarball, listed, mtime),
+  };
+}
+
+async function checkTarballDigest(
+  source            ,
+  want                                                     ,
+)                {
+  const h = incrementalSha256();
+  let bytes = 0;
+  for await (const chunk of chunksOf(source)) {
+    bytes += chunk.length;
+    if (bytes > want.bytes) refuse("tarball-mismatch", "the tarball is larger than its statement");
+    await h.update(chunk);
+  }
+  if (bytes !== want.bytes || (await h.digest()) !== want.sha256)
+    refuse("tarball-mismatch", "the tarball is not the file the statement pins");
+}
+
+/**
+ * The second pass (step 6's entries), exported for the producer's self-check
+ * (scripts/release-bundle/verify.ts); not part of the package's public exports.
+ */
+export async function* verifiedEntries(
+  open                               ,
+  listed                                 ,
+  mtime        ,
+)                                {
+  const left = new Map(listed);
+  let previous = "";
+  const admit = (tarPath        , size        ) => {
+    checkPath(tarPath, "entry", "tar entry");
+    if (tarPath <= previous)
+      refuse("tar-format", `${tarPath}: tar entries are not sorted and unique`);
+    previous = tarPath;
+    const part = left.get(tarPath);
+    if (!part) refuse("entry-unlisted", `${tarPath} is in the tarball but not in the manifest`);
+    if (size !== part.bytes)
+      refuse("entry-mismatch", `${tarPath} is not the size its listing says`);
+  };
+  for await (const e of readTar(gunzip(await open()), mtime, admit)) {
+    const part = left.get(e.path)              ;
+    if ((await sha256Hex(e.bytes)) !== part.sha256)
+      refuse("entry-mismatch", `${e.path} does not match the manifest's SHA-256`);
+    left.delete(e.path);
+    yield {
+      worker: part.worker,
+      kind: part.kind,
+      path: part.path,
+      tarPath: e.path,
+      ...(part.type !== undefined ? { type: part.type } : {}),
+      bytes: e.bytes,
+    };
+  }
+  const missing = left.keys().next();
+  if (!missing.done) refuse("entry-missing", `${missing.value} is listed but not in the tarball`);
+}

package/dist/src/yank-memory.d.ts

@@ -0,0 +1,22 @@
+import type { ReleaseKeys as KeyListDocument } from "./generated/release-keys.js";
+import type { ReleaseYankList } from "./generated/release-yank-list.js";
+export interface YankMemory {
+    readonly keyId: string;
+    readonly serial: number;
+    readonly versions: readonly string[];
+    readonly revokedKeys: readonly string[];
+    /** `issuedAt` of the newest `keys.json` seen. */
+    readonly keysIssuedAt: string;
+    /** Yank keys a root list has revoked, or that a newer yank key replaced: never accepted again. */
+    readonly retiredYankKeys: readonly string[];
+}
+/** The memory after accepting `yanked` with `keys` (see the file comment). */
+export declare function rememberYanks(yanked: {
+    readonly document: ReleaseYankList;
+}, keys: {
+    readonly document: KeyListDocument;
+}, previous?: YankMemory): YankMemory;
+/** Refuses a `keys.json` older than the newest one `memory` has seen (a replayed list). */
+export declare function checkKeysMemory(keys: KeyListDocument, memory: YankMemory | undefined): void;
+/** Refuses a yank list (with the key list it verified against) that goes back on `memory`. */
+export declare function checkYankMemory(list: ReleaseYankList, keys: KeyListDocument, memory: YankMemory | undefined): void;

package/dist/src/yank-memory.js

@@ -0,0 +1,106 @@
+/**
+ * What a consumer that keeps state remembers of the trust lists it has accepted (RFC-0046 §9), so
+ * that neither a stolen yank key nor a replayed older list can take back a yank or a revocation.
+ *
+ * - The newest `keys.json` seen (`keysIssuedAt`): an older one is refused, so a list from before a
+ *   revocation cannot bring a revoked yank key back.
+ * - Every yank key a root list has revoked or replaced (`retiredYankKeys`): refused forever.
+ * - The yank key of the last accepted list (`keyId`), its serial and every yanked version and
+ *   revoked key: a later list from the same key may not go back in serial or drop an entry.
+ * - A list from another yank key starts a new memory (rotation, and how the list is pruned) only
+ *   when a `keys.json` newer than the remembered one lists that key and no longer lists the old
+ *   one as active. `verifyKeys` allows at most one active yank key, so two cannot alternate.
+ *
+ * Store `rememberYanks(yanked, keys, memory)` after every accepted pair.
+ */
+import { refuse } from "./errors.js";
+                                                                                  
+                                                                        
+
+                             
+                         
+                          
+                                       
+                                          
+                                                   
+                                
+                                                                                                    
+                                              
+ 
+
+const union = (...lists                                ) => [...new Set(lists.flat())].sort();
+
+/** The memory after accepting `yanked` with `keys` (see the file comment). */
+export function rememberYanks(
+  yanked                                        ,
+  keys                                        ,
+  previous             ,
+)             {
+  const d = yanked.document;
+  const revokedByRoot = keys.document.keys
+    .filter((k) => k.role === "yank" && k.status === "revoked")
+    .map((k) => k.keyId);
+  const replaced = previous && previous.keyId !== d.signing.keyId ? [previous.keyId] : [];
+  const newerKeys =
+    previous && Date.parse(previous.keysIssuedAt) > Date.parse(keys.document.issuedAt)
+      ? previous.keysIssuedAt
+      : keys.document.issuedAt;
+  return {
+    keyId: d.signing.keyId,
+    serial: d.serial,
+    versions: d.versions.map((v) => v.version),
+    revokedKeys: d.revokedKeys.map((k) => k.keyId),
+    keysIssuedAt: newerKeys,
+    retiredYankKeys: union(previous?.retiredYankKeys ?? [], revokedByRoot, replaced),
+  };
+}
+
+/** Refuses a `keys.json` older than the newest one `memory` has seen (a replayed list). */
+export function checkKeysMemory(keys                 , memory                        )       {
+  if (memory && Date.parse(keys.issuedAt) < Date.parse(memory.keysIssuedAt))
+    refuse(
+      "key-list-invalid",
+      `keys.json was issued ${keys.issuedAt}, before ${memory.keysIssuedAt} seen before: a replayed key list`,
+    );
+}
+
+/** Refuses a yank list (with the key list it verified against) that goes back on `memory`. */
+export function checkYankMemory(
+  list                 ,
+  keys                 ,
+  memory                        ,
+)       {
+  if (!memory) return;
+  checkKeysMemory(keys, memory);
+  const signer = list.signing.keyId;
+  if (memory.retiredYankKeys.includes(signer))
+    refuse(
+      "yank-list-invalid",
+      `yanked.json is signed by ${signer}, a revoked or replaced yank key`,
+    );
+  if (memory.keyId !== signer) {
+    const old = keys.keys.find((k) => k.keyId === memory.keyId);
+    if (!(Date.parse(keys.issuedAt) > Date.parse(memory.keysIssuedAt)) || old?.status === "active")
+      refuse(
+        "stale-yank-list",
+        `yanked.json is signed by ${signer}, not ${memory.keyId}: a new yank key needs a newer keys.json that replaces ${memory.keyId}`,
+      );
+    return;
+  }
+  if (list.serial < memory.serial)
+    refuse(
+      "stale-yank-list",
+      `yanked.json has serial ${list.serial}, below ${memory.serial} seen before: a rolled-back list`,
+    );
+  const versions = new Set(list.versions.map((v) => v.version));
+  const revoked = new Set(list.revokedKeys.map((k) => k.keyId));
+  const dropped = [
+    ...memory.versions.filter((v) => !versions.has(v)),
+    ...memory.revokedKeys.filter((k) => !revoked.has(k)),
+  ];
+  if (dropped.length)
+    refuse(
+      "stale-yank-list",
+      `yanked.json drops ${dropped.join(", ")}, seen before: a yank or revocation is never undone`,
+    );
+}