settld 0.1.0

package/packages/artifact-verify/src/map-with-concurrency.js

@@ -0,0 +1,32 @@
+function abortError() {
+  const err = new Error("aborted");
+  err.name = "AbortError";
+  return err;
+}
+
+export async function mapWithConcurrency(items, concurrency, mapper, { signal = null } = {}) {
+  if (!Array.isArray(items)) throw new TypeError("items must be an array");
+  if (!Number.isInteger(concurrency) || concurrency < 1) throw new TypeError("concurrency must be a positive integer");
+  if (typeof mapper !== "function") throw new TypeError("mapper must be a function");
+  if (signal !== null && typeof signal !== "object") throw new TypeError("signal must be null or an AbortSignal-like object");
+  if (signal?.aborted) throw abortError();
+
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  const workerCount = Math.min(concurrency, items.length || 1);
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (true) {
+      if (signal?.aborted) throw abortError();
+      const i = nextIndex;
+      nextIndex += 1;
+      if (i >= items.length) return;
+      // eslint-disable-next-line no-await-in-loop
+      results[i] = await mapper(items[i], i);
+    }
+  });
+
+  await Promise.all(workers);
+  return results;
+}
+

package/packages/artifact-verify/src/reconcile.js

@@ -0,0 +1,135 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256HexUtf8 } from "./crypto.js";
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function keyOf({ partyId, accountId }) {
+  return `${partyId}\n${accountId}`;
+}
+
+function addToMap(map, key, delta) {
+  map.set(key, (map.get(key) ?? 0) + delta);
+}
+
+export function reconcileGlBatchAgainstPartyStatements({ glBatch, partyStatements } = {}) {
+  assertPlainObject(glBatch, "glBatch");
+  if (!Array.isArray(partyStatements)) throw new TypeError("partyStatements must be an array");
+
+  const glArtifactType = glBatch?.artifactType ?? glBatch?.schemaVersion ?? null;
+  if (glArtifactType !== "GLBatch.v1") return { ok: false, error: "expected GLBatch.v1", got: glArtifactType };
+  if (glBatch.schemaVersion && glBatch.schemaVersion !== "GLBatch.v1") {
+    return { ok: false, error: "schemaVersion mismatch", expected: "GLBatch.v1", actual: glBatch.schemaVersion };
+  }
+  const glActualHash = glBatch.artifactHash ?? null;
+  if (typeof glActualHash !== "string" || !glActualHash.trim()) return { ok: false, error: "missing glBatch artifactHash" };
+  try {
+    // eslint-disable-next-line no-unused-vars
+    const { artifactHash: _ignored, ...core } = glBatch;
+    const expected = sha256HexUtf8(canonicalJsonStringify(core));
+    if (expected !== glActualHash) return { ok: false, error: "glBatch artifactHash mismatch", expected, actual: glActualHash };
+  } catch (err) {
+    return { ok: false, error: "failed to hash glBatch", detail: err?.message ?? String(err) };
+  }
+
+  const period = String(glBatch.period ?? "");
+  const basis = String(glBatch.basis ?? "");
+  assertNonEmptyString(period, "glBatch.period");
+  assertNonEmptyString(basis, "glBatch.basis");
+
+  const batch = glBatch.batch ?? null;
+  assertPlainObject(batch, "glBatch.batch");
+  const lines = Array.isArray(batch.lines) ? batch.lines : [];
+
+  const glTotals = new Map(); // key(partyId,accountId) -> cents
+  const glEntryIds = new Set();
+  let glNet = 0;
+  for (const l of lines) {
+    if (!l || typeof l !== "object") continue;
+    const partyId = typeof l.partyId === "string" ? l.partyId : null;
+    const accountId = typeof l.accountId === "string" ? l.accountId : null;
+    const entryId = typeof l.entryId === "string" ? l.entryId : null;
+    const amountCents = Number.isSafeInteger(l.amountCents) ? l.amountCents : null;
+    if (!partyId || !accountId || !entryId || amountCents === null) continue;
+    addToMap(glTotals, keyOf({ partyId, accountId }), amountCents);
+    glEntryIds.add(entryId);
+    glNet += amountCents;
+  }
+  if (glNet !== 0) return { ok: false, error: "glBatch does not net to zero", glNet };
+
+  const psTotals = new Map();
+  const psEntryIds = new Set();
+  for (const ps of partyStatements) {
+    if (!ps || typeof ps !== "object") continue;
+
+    const psArtifactType = ps?.artifactType ?? ps?.schemaVersion ?? null;
+    if (psArtifactType !== "PartyStatement.v1") return { ok: false, error: "expected PartyStatement.v1", got: psArtifactType };
+    if (ps.schemaVersion && ps.schemaVersion !== "PartyStatement.v1") {
+      return { ok: false, error: "schemaVersion mismatch", expected: "PartyStatement.v1", actual: ps.schemaVersion };
+    }
+    const psActualHash = ps.artifactHash ?? null;
+    if (typeof psActualHash !== "string" || !psActualHash.trim()) return { ok: false, error: "missing partyStatement artifactHash" };
+    try {
+      // eslint-disable-next-line no-unused-vars
+      const { artifactHash: _ignored, ...core } = ps;
+      const expected = sha256HexUtf8(canonicalJsonStringify(core));
+      if (expected !== psActualHash) return { ok: false, error: "partyStatement artifactHash mismatch", expected, actual: psActualHash };
+    } catch (err) {
+      return { ok: false, error: "failed to hash partyStatement", detail: err?.message ?? String(err) };
+    }
+
+    if (String(ps.period ?? "") !== period) return { ok: false, error: "partyStatement period mismatch", expected: period, got: ps.period ?? null };
+    if (String(ps.basis ?? "") !== basis) return { ok: false, error: "partyStatement basis mismatch", expected: basis, got: ps.basis ?? null };
+
+    assertNonEmptyString(ps.partyId, "partyStatement.partyId");
+    const partyId = String(ps.partyId);
+
+    const totals = ps.statement?.totalsByAccountId ?? ps.totalsByAccountId ?? null;
+    if (!totals || typeof totals !== "object" || Array.isArray(totals)) return { ok: false, error: "partyStatement totalsByAccountId missing" };
+
+    for (const [accountIdRaw, amountRaw] of Object.entries(totals)) {
+      const accountId = String(accountIdRaw);
+      const amountCents = Number(amountRaw);
+      if (!Number.isFinite(amountCents) || !Number.isSafeInteger(amountCents)) {
+        return { ok: false, error: "partyStatement totalsByAccountId contains non-integer", accountId };
+      }
+      addToMap(psTotals, keyOf({ partyId, accountId }), amountCents);
+    }
+
+    const included = ps.statement?.includedEntryIds ?? ps.includedEntryIds ?? [];
+    for (const id of included) {
+      if (typeof id === "string" && id.trim()) psEntryIds.add(id);
+    }
+  }
+
+  const diffs = [];
+  const keys = new Set([...glTotals.keys(), ...psTotals.keys()]);
+  for (const k of keys) {
+    const a = glTotals.get(k) ?? 0;
+    const b = psTotals.get(k) ?? 0;
+    if (a !== b) {
+      const [partyId, accountId] = k.split("\n");
+      diffs.push({ partyId, accountId, glBatchCents: a, partyStatementsCents: b, deltaCents: a - b });
+    }
+  }
+
+  if (diffs.length) return { ok: false, error: "totals mismatch", diffs };
+
+  // Sanity: entry ids match.
+  const glEntryList = Array.from(glEntryIds).sort();
+  const psEntryList = Array.from(psEntryIds).sort();
+  const sameEntries = glEntryList.length === psEntryList.length && glEntryList.every((v, i) => v === psEntryList[i]);
+  if (!sameEntries) {
+    return { ok: false, error: "included entry ids mismatch", glEntryIds: glEntryList, partyStatementEntryIds: psEntryList };
+  }
+
+  return { ok: true, period, basis, totalsKeys: keys.size, entryCount: glEntryIds.size };
+}

package/packages/artifact-verify/src/release/release-index-lib.js

@@ -0,0 +1,190 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+
+import { canonicalJsonStringify } from "../canonical-json.js";
+
+export function sha256Hex(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+export function keyIdFromPublicKeyPem(publicKeyPem) {
+  return `key_${sha256Hex(String(publicKeyPem)).slice(0, 24)}`;
+}
+
+export async function sha256FileHex(fp) {
+  const h = crypto.createHash("sha256");
+  const f = await fs.open(fp, "r");
+  try {
+    const buf = Buffer.alloc(1024 * 1024);
+    while (true) {
+      // eslint-disable-next-line no-await-in-loop
+      const { bytesRead } = await f.read(buf, 0, buf.length, null);
+      if (bytesRead === 0) break;
+      h.update(buf.subarray(0, bytesRead));
+    }
+  } finally {
+    await f.close();
+  }
+  return h.digest("hex");
+}
+
+export function canonicalIndexBytes(indexJson) {
+  const canonical = canonicalJsonStringify(indexJson);
+  return Buffer.from(canonical, "utf8");
+}
+
+export function indexMessageSha256Hex(indexJson) {
+  return sha256Hex(canonicalIndexBytes(indexJson));
+}
+
+export function signIndex({ indexJson, privateKeyPem }) {
+  const messageSha256 = indexMessageSha256Hex(indexJson);
+  const messageBytes = Buffer.from(messageSha256, "hex");
+  const sig = crypto.sign(null, messageBytes, privateKeyPem).toString("base64");
+
+  const pub = crypto.createPublicKey(crypto.createPrivateKey(privateKeyPem)).export({ type: "spki", format: "pem" });
+  const publicKeyPem = String(pub);
+  const keyId = keyIdFromPublicKeyPem(publicKeyPem);
+
+  return {
+    schemaVersion: "ReleaseIndexSignature.v1",
+    algorithm: "ed25519-sha256",
+    keyId,
+    messageSha256,
+    publicKeyPem,
+    signatureBase64: sig
+  };
+}
+
+export function wrapSignaturesV1(signatures) {
+  const list = Array.isArray(signatures) ? signatures.filter(Boolean) : [];
+  return {
+    schemaVersion: "ReleaseIndexSignatures.v1",
+    signatures: list
+  };
+}
+
+export function unwrapSignaturesV1(sigJson) {
+  if (sigJson && typeof sigJson === "object" && !Array.isArray(sigJson)) {
+    if (sigJson.schemaVersion === "ReleaseIndexSignature.v1") return [sigJson];
+    if (sigJson.schemaVersion === "ReleaseIndexSignatures.v1") {
+      const arr = Array.isArray(sigJson.signatures) ? sigJson.signatures : [];
+      return arr.filter(Boolean);
+    }
+  }
+  return [];
+}
+
+export function verifyIndexSignature({ indexJson, signatureJson, trustedPublicKeyPem }) {
+  const errors = [];
+  const messageSha256 = indexMessageSha256Hex(indexJson);
+
+  if (!signatureJson || typeof signatureJson !== "object") {
+    errors.push({ code: "SIGNATURE_INVALID", message: "signature JSON missing/invalid", path: null });
+    return { ok: false, messageSha256, errors };
+  }
+  if (signatureJson.schemaVersion !== "ReleaseIndexSignature.v1") {
+    errors.push({ code: "SIGNATURE_INVALID", message: "unexpected signature schemaVersion", path: null });
+    return { ok: false, messageSha256, errors };
+  }
+  if (signatureJson.algorithm !== "ed25519-sha256") {
+    errors.push({ code: "SIGNATURE_UNSUPPORTED_ALGORITHM", message: "unsupported signature algorithm", path: null });
+    return { ok: false, messageSha256, errors };
+  }
+  if (typeof signatureJson.signatureBase64 !== "string" || !signatureJson.signatureBase64.trim()) {
+    errors.push({ code: "SIGNATURE_INVALID", message: "signatureBase64 missing", path: null });
+    return { ok: false, messageSha256, errors };
+  }
+
+  const publicKeyPem = String(trustedPublicKeyPem ?? "");
+  if (!publicKeyPem.trim()) {
+    errors.push({ code: "SIGNATURE_INVALID", message: "trusted public key missing", path: null });
+    return { ok: false, messageSha256, errors };
+  }
+
+  if (typeof signatureJson.messageSha256 === "string" && signatureJson.messageSha256.toLowerCase() !== messageSha256) {
+    errors.push({ code: "SIGNATURE_MISMATCH", message: "messageSha256 mismatch", path: null });
+    return { ok: false, messageSha256, errors };
+  }
+
+  try {
+    const ok = crypto.verify(
+      null,
+      Buffer.from(messageSha256, "hex"),
+      publicKeyPem,
+      Buffer.from(String(signatureJson.signatureBase64), "base64")
+    );
+    if (!ok) errors.push({ code: "SIGNATURE_INVALID", message: "signature verification failed", path: null });
+  } catch (e) {
+    errors.push({ code: "SIGNATURE_INVALID", message: `signature verification error: ${e?.message ?? String(e)}`, path: null });
+  }
+
+  return { ok: errors.length === 0, messageSha256, errors };
+}
+
+export function normalizeReleaseTrust(trustJson) {
+  if (!trustJson || typeof trustJson !== "object" || Array.isArray(trustJson)) {
+    throw new Error("release trust JSON missing/invalid");
+  }
+
+  if (trustJson.schemaVersion === "ReleaseTrust.v1") {
+    const roots = trustJson.releaseRoots ?? null;
+    if (!roots || typeof roots !== "object" || Array.isArray(roots)) throw new Error("ReleaseTrust.v1.releaseRoots missing/invalid");
+    const keys = [];
+    for (const [keyId, publicKeyPem] of Object.entries(roots)) {
+      if (typeof keyId !== "string" || !keyId.trim()) continue;
+      if (typeof publicKeyPem !== "string" || !publicKeyPem.trim()) continue;
+      keys.push({ keyId, publicKeyPem, notBeforeEpochSeconds: null, notAfterEpochSeconds: null, revokedAtEpochSeconds: null, comment: null });
+    }
+    keys.sort((a, b) => cmpString(a.keyId, b.keyId));
+    return { schemaVersion: "ReleaseTrust.v1", policy: { minSignatures: 1, requiredKeyIds: null }, keys };
+  }
+
+  if (trustJson.schemaVersion === "ReleaseTrust.v2") {
+    const policy = trustJson.policy ?? null;
+    if (!policy || typeof policy !== "object" || Array.isArray(policy)) throw new Error("ReleaseTrust.v2.policy missing/invalid");
+    const minSignatures = policy.minSignatures;
+    if (!Number.isInteger(minSignatures) || minSignatures < 1) throw new Error("ReleaseTrust.v2.policy.minSignatures missing/invalid");
+    const requiredKeyIds = Array.isArray(policy.requiredKeyIds)
+      ? policy.requiredKeyIds.filter((v) => typeof v === "string" && v.trim())
+      : null;
+
+    const arr = Array.isArray(trustJson.keys) ? trustJson.keys : null;
+    if (!arr) throw new Error("ReleaseTrust.v2.keys missing/invalid");
+    const keys = [];
+    for (const item of arr) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+      const keyId = typeof item.keyId === "string" && item.keyId.trim() ? item.keyId.trim() : null;
+      const publicKeyPem = typeof item.publicKeyPem === "string" && item.publicKeyPem.trim() ? item.publicKeyPem : null;
+      if (!keyId || !publicKeyPem) continue;
+
+      const derived = keyIdFromPublicKeyPem(publicKeyPem);
+      if (derived !== keyId) throw new Error(`ReleaseTrust.v2 keyId mismatch: declared=${keyId} derived=${derived}`);
+
+      const notBeforeEpochSeconds = Number.isInteger(item.notBeforeEpochSeconds) && item.notBeforeEpochSeconds >= 0 ? item.notBeforeEpochSeconds : null;
+      const notAfterEpochSeconds = Number.isInteger(item.notAfterEpochSeconds) && item.notAfterEpochSeconds >= 0 ? item.notAfterEpochSeconds : null;
+      const revokedAtEpochSeconds = Number.isInteger(item.revokedAtEpochSeconds) && item.revokedAtEpochSeconds >= 0 ? item.revokedAtEpochSeconds : null;
+      const comment = typeof item.comment === "string" && item.comment.trim() ? item.comment : null;
+
+      keys.push({ keyId, publicKeyPem, notBeforeEpochSeconds, notAfterEpochSeconds, revokedAtEpochSeconds, comment });
+    }
+    keys.sort((a, b) => cmpString(a.keyId, b.keyId));
+    return { schemaVersion: "ReleaseTrust.v2", policy: { minSignatures, requiredKeyIds }, keys };
+  }
+
+  throw new Error("release trust schemaVersion must be ReleaseTrust.v1 or ReleaseTrust.v2");
+}
+
+export async function loadReleaseTrust({ trustPath }) {
+  const raw = await fs.readFile(trustPath, "utf8");
+  return normalizeReleaseTrust(JSON.parse(raw));
+}
+
+export function cmpString(a, b) {
+  const aa = String(a ?? "");
+  const bb = String(b ?? "");
+  if (aa < bb) return -1;
+  if (aa > bb) return 1;
+  return 0;
+}
+

package/packages/artifact-verify/src/release/verify-release.js

@@ -0,0 +1,187 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  sha256FileHex,
+  unwrapSignaturesV1,
+  verifyIndexSignature,
+  loadReleaseTrust,
+  cmpString
+} from "./release-index-lib.js";
+
+function addError(list, code, message, p = null) {
+  list.push({ code, message, path: p });
+}
+
+function signatureTimeFromIndex(indexJson) {
+  const n = indexJson?.toolchain?.buildEpochSeconds;
+  return Number.isInteger(n) && n >= 0 ? n : null;
+}
+
+function keyIsUsableAtTime(key, signatureTime) {
+  if (signatureTime === null) return true;
+  const nb = key.notBeforeEpochSeconds;
+  const na = key.notAfterEpochSeconds;
+  const rv = key.revokedAtEpochSeconds;
+  if (Number.isInteger(nb) && signatureTime < nb) return false;
+  if (Number.isInteger(na) && signatureTime > na) return false;
+  if (Number.isInteger(rv) && signatureTime >= rv) return false;
+  return true;
+}
+
+export async function verifyReleaseDir({ dir, trustPath }) {
+  const errors = [];
+  const warnings = [];
+
+  const indexPath = path.join(dir, "release_index_v1.json");
+  const sigPath = path.join(dir, "release_index_v1.sig");
+
+  let indexJson = null;
+  let sigJsonRaw = null;
+  try {
+    indexJson = JSON.parse(await fs.readFile(indexPath, "utf8"));
+  } catch (e) {
+    addError(errors, "RELEASE_INDEX_INVALID", e?.message ?? String(e), "release_index_v1.json");
+  }
+  try {
+    sigJsonRaw = JSON.parse(await fs.readFile(sigPath, "utf8"));
+  } catch (e) {
+    addError(errors, "RELEASE_SIGNATURE_INVALID", e?.message ?? String(e), "release_index_v1.sig");
+  }
+
+  const tag = String(indexJson?.release?.tag ?? "");
+  const version = String(indexJson?.release?.version ?? "");
+  const commit = indexJson?.toolchain?.commit ?? null;
+
+  if (!trustPath) addError(errors, "RELEASE_TRUST_MISSING", "missing release trust file (pass --trust-file)", null);
+
+  let trust = null;
+  if (trustPath) {
+    try {
+      trust = await loadReleaseTrust({ trustPath });
+    } catch (e) {
+      addError(errors, "RELEASE_TRUST_INVALID", e?.message ?? String(e), null);
+    }
+  }
+
+  const signatureTime = signatureTimeFromIndex(indexJson);
+  const trustRequiresTime = trust?.schemaVersion === "ReleaseTrust.v2" && trust.keys.some((k) => k.notBeforeEpochSeconds !== null || k.notAfterEpochSeconds !== null || k.revokedAtEpochSeconds !== null);
+  if (trustRequiresTime && signatureTime === null) {
+    addError(errors, "RELEASE_INDEX_INVALID", "ReleaseIndex.v1.toolchain.buildEpochSeconds required for time-based release trust", null);
+  }
+
+  const sigList = unwrapSignaturesV1(sigJsonRaw);
+  const validSigners = new Set();
+  let signatureOk = false;
+
+  if (trust && !sigList.length && sigJsonRaw && indexJson) {
+    addError(errors, "RELEASE_SIGNATURE_INVALID", "signature file missing/invalid", "release_index_v1.sig");
+  }
+
+  if (trust && sigList.length && indexJson) {
+    for (const sigJson of sigList) {
+      const keyId = typeof sigJson?.keyId === "string" && sigJson.keyId.trim() ? sigJson.keyId.trim() : null;
+      if (!keyId) {
+        addError(errors, "RELEASE_SIGNATURE_INVALID", "signature missing keyId", null);
+        continue;
+      }
+
+      const trustKey = trust.keys.find((k) => k.keyId === keyId) ?? null;
+      if (!trustKey) {
+        addError(errors, "RELEASE_SIGNER_UNAUTHORIZED", "signer keyId not in release trust", null);
+        continue;
+      }
+
+      if (trust?.schemaVersion === "ReleaseTrust.v2" && signatureTime !== null) {
+        const rv = trustKey.revokedAtEpochSeconds;
+        if (Number.isInteger(rv) && signatureTime >= rv) {
+          addError(errors, "RELEASE_SIGNER_REVOKED", "signer keyId revoked for this release time", null);
+          continue;
+        }
+        if (!keyIsUsableAtTime(trustKey, signatureTime)) {
+          addError(errors, "RELEASE_SIGNER_UNAUTHORIZED", "signer keyId not valid for this release time", null);
+          continue;
+        }
+      }
+
+      const sigCheck = verifyIndexSignature({ indexJson, signatureJson: sigJson, trustedPublicKeyPem: trustKey.publicKeyPem });
+      for (const e of sigCheck.errors) {
+        const mapped =
+          e.code === "SIGNATURE_UNSUPPORTED_ALGORITHM"
+            ? "RELEASE_SIGNATURE_UNSUPPORTED_ALGORITHM"
+            : "RELEASE_SIGNATURE_INVALID";
+        addError(errors, mapped, e.message, e.path ?? null);
+      }
+      if (sigCheck.ok) validSigners.add(keyId);
+    }
+
+    const minSignatures = trust.policy?.minSignatures ?? 1;
+    const requiredKeyIds = Array.isArray(trust.policy?.requiredKeyIds) ? trust.policy.requiredKeyIds : null;
+    const countOk = validSigners.size >= minSignatures;
+    const requiredOk = !requiredKeyIds || requiredKeyIds.every((kid) => validSigners.has(kid));
+    signatureOk = countOk && requiredOk;
+    if (!signatureOk) {
+      addError(errors, "RELEASE_SIGNATURE_QUORUM_NOT_SATISFIED", "release signature quorum not satisfied", null);
+    }
+  }
+
+  const artifacts = Array.isArray(indexJson?.artifacts) ? indexJson.artifacts : [];
+
+  // Duplicate paths
+  try {
+    const seen = new Set();
+    for (const a of artifacts) {
+      const rel = String(a?.path ?? "");
+      if (!rel) continue;
+      if (seen.has(rel)) throw new Error(`duplicate artifact path: ${rel}`);
+      seen.add(rel);
+    }
+  } catch (e) {
+    addError(errors, "RELEASE_ARTIFACTS_DUPLICATE_PATH", e?.message ?? String(e), null);
+  }
+
+  let artifactsOk = true;
+  for (const a of artifacts) {
+    const rel = typeof a?.path === "string" ? a.path : "";
+    const expected = typeof a?.sha256 === "string" ? a.sha256 : "";
+    const expectedSize = typeof a?.sizeBytes === "number" ? a.sizeBytes : null;
+    if (!rel || !expected) {
+      artifactsOk = false;
+      addError(errors, "RELEASE_ASSET_ENTRY_INVALID", "artifact entry missing required fields", rel || null);
+      continue;
+    }
+    const fp = path.join(dir, rel);
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const st = await fs.stat(fp);
+      if (!st.isFile()) throw new Error("not a file");
+      if (expectedSize !== null && st.size !== expectedSize) {
+        artifactsOk = false;
+        addError(errors, "RELEASE_ASSET_SIZE_MISMATCH", `size mismatch expected=${expectedSize} actual=${st.size}`, rel);
+      }
+      // eslint-disable-next-line no-await-in-loop
+      const actual = await sha256FileHex(fp);
+      if (String(actual) !== String(expected).toLowerCase()) {
+        artifactsOk = false;
+        addError(errors, "RELEASE_ASSET_HASH_MISMATCH", `sha256 mismatch expected=${expected} actual=${actual}`, rel);
+      }
+    } catch (e) {
+      artifactsOk = false;
+      addError(errors, "RELEASE_ASSET_MISSING", e?.message ?? String(e), rel);
+    }
+  }
+
+  const ok = signatureOk && artifactsOk && errors.length === 0;
+
+  errors.sort((a, b) => cmpString(a.path ?? "", b.path ?? "") || cmpString(a.code ?? "", b.code ?? ""));
+
+  return {
+    schemaVersion: "VerifyReleaseOutput.v1",
+    ok,
+    release: { tag, version, commit },
+    signatureOk,
+    artifactsOk,
+    errors,
+    warnings
+  };
+}

package/packages/artifact-verify/src/revocation-list.js

@@ -0,0 +1,119 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256HexUtf8, verifyHashHexEd25519 } from "./crypto.js";
+
+export const REVOCATION_LIST_SCHEMA_V1 = "RevocationList.v1";
+
+function stripRevocationListSig(list) {
+  const { listHash: _h, signature: _sig, ...rest } = list ?? {};
+  return rest;
+}
+
+function normalizeIsoOrNull(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const s = value.trim();
+  const t = Date.parse(s);
+  return Number.isFinite(t) ? s : null;
+}
+
+export function parseRevocationListV1(listJson) {
+  if (!listJson || typeof listJson !== "object" || Array.isArray(listJson)) return { ok: false, error: "revocation list must be an object" };
+  if (String(listJson.schemaVersion ?? "") !== REVOCATION_LIST_SCHEMA_V1) {
+    return { ok: false, error: "unsupported revocation list schemaVersion", schemaVersion: listJson.schemaVersion ?? null };
+  }
+  const listId = typeof listJson.listId === "string" && listJson.listId.trim() ? listJson.listId.trim() : null;
+  const generatedAt = normalizeIsoOrNull(listJson.generatedAt ?? null) ?? (typeof listJson.generatedAt === "string" ? listJson.generatedAt : null);
+  if (!listId) return { ok: false, error: "revocation list listId missing" };
+  if (!generatedAt) return { ok: false, error: "revocation list generatedAt missing" };
+
+  const rotations = Array.isArray(listJson.rotations) ? listJson.rotations : null;
+  const revocations = Array.isArray(listJson.revocations) ? listJson.revocations : null;
+  if (!rotations) return { ok: false, error: "revocation list rotations must be an array" };
+  if (!revocations) return { ok: false, error: "revocation list revocations must be an array" };
+
+  const parsedRotations = [];
+  for (const r of rotations) {
+    const oldKeyId = typeof r?.oldKeyId === "string" && r.oldKeyId.trim() ? r.oldKeyId.trim() : null;
+    const newKeyId = typeof r?.newKeyId === "string" && r.newKeyId.trim() ? r.newKeyId.trim() : null;
+    const rotatedAt = normalizeIsoOrNull(r?.rotatedAt ?? null) ?? (typeof r?.rotatedAt === "string" ? r.rotatedAt : null);
+    if (!oldKeyId || !newKeyId || !rotatedAt) continue;
+    parsedRotations.push({ oldKeyId, newKeyId, rotatedAt, reason: r?.reason ?? null, scope: r?.scope ?? null });
+  }
+
+  const parsedRevocations = [];
+  for (const r of revocations) {
+    const keyId = typeof r?.keyId === "string" && r.keyId.trim() ? r.keyId.trim() : null;
+    const revokedAt = normalizeIsoOrNull(r?.revokedAt ?? null) ?? (typeof r?.revokedAt === "string" ? r.revokedAt : null);
+    if (!keyId || !revokedAt) continue;
+    parsedRevocations.push({ keyId, revokedAt, reason: r?.reason ?? null, scope: r?.scope ?? null });
+  }
+
+  const signerKeyId = typeof listJson.signerKeyId === "string" && listJson.signerKeyId.trim() ? listJson.signerKeyId.trim() : null;
+  const signedAt = typeof listJson.signedAt === "string" && listJson.signedAt.trim() ? listJson.signedAt.trim() : null;
+  const listHash = typeof listJson.listHash === "string" && listJson.listHash.trim() ? listJson.listHash.trim() : null;
+  const signature = typeof listJson.signature === "string" && listJson.signature.trim() ? listJson.signature.trim() : null;
+
+  return {
+    ok: true,
+    list: {
+      schemaVersion: REVOCATION_LIST_SCHEMA_V1,
+      listId,
+      generatedAt,
+      rotations: parsedRotations,
+      revocations: parsedRevocations,
+      signerKeyId,
+      signedAt,
+      listHash,
+      signature
+    }
+  };
+}
+
+export function verifyRevocationListV1Signature({ list, trustedGovernanceRootPublicKeyByKeyId } = {}) {
+  if (!list || typeof list !== "object" || Array.isArray(list)) return { ok: false, error: "list must be an object" };
+  if (String(list.schemaVersion ?? "") !== REVOCATION_LIST_SCHEMA_V1) return { ok: false, error: "unsupported revocation list schemaVersion" };
+  if (!(trustedGovernanceRootPublicKeyByKeyId instanceof Map)) return { ok: false, error: "trustedGovernanceRootPublicKeyByKeyId must be a Map" };
+  const signerKeyId = typeof list.signerKeyId === "string" && list.signerKeyId.trim() ? list.signerKeyId.trim() : null;
+  const signature = typeof list.signature === "string" && list.signature.trim() ? list.signature.trim() : null;
+  const declaredHash = typeof list.listHash === "string" && list.listHash.trim() ? list.listHash.trim() : null;
+  if (!signerKeyId || !signature || !declaredHash) return { ok: false, error: "revocation list missing signature fields" };
+  const publicKeyPem = trustedGovernanceRootPublicKeyByKeyId.get(signerKeyId) ?? null;
+  if (!publicKeyPem) return { ok: false, error: "revocation list signerKeyId not trusted", signerKeyId };
+
+  const core = stripRevocationListSig(list);
+  const expectedHash = sha256HexUtf8(canonicalJsonStringify(core));
+  if (expectedHash !== declaredHash) return { ok: false, error: "revocation listHash mismatch", expected: expectedHash, actual: declaredHash };
+
+  const okSig = verifyHashHexEd25519({ hashHex: expectedHash, signatureBase64: signature, publicKeyPem });
+  if (!okSig) return { ok: false, error: "revocation list signature invalid", signerKeyId };
+  return { ok: true, listHash: expectedHash, signerKeyId };
+}
+
+export function deriveKeyTimelineFromRevocationList(list) {
+  const timeline = new Map(); // keyId -> { rotatedAt, revokedAt, validFrom }
+  for (const rot of Array.isArray(list?.rotations) ? list.rotations : []) {
+    const rotatedAt = typeof rot?.rotatedAt === "string" && rot.rotatedAt.trim() ? rot.rotatedAt.trim() : null;
+    const oldKeyId = typeof rot?.oldKeyId === "string" && rot.oldKeyId.trim() ? rot.oldKeyId.trim() : null;
+    const newKeyId = typeof rot?.newKeyId === "string" && rot.newKeyId.trim() ? rot.newKeyId.trim() : null;
+    if (!rotatedAt || !oldKeyId || !newKeyId) continue;
+
+    const oldRow = timeline.get(oldKeyId) ?? {};
+    if (!oldRow.rotatedAt || Date.parse(rotatedAt) < Date.parse(oldRow.rotatedAt)) oldRow.rotatedAt = rotatedAt;
+    timeline.set(oldKeyId, oldRow);
+
+    const newRow = timeline.get(newKeyId) ?? {};
+    if (!newRow.validFrom || Date.parse(rotatedAt) < Date.parse(newRow.validFrom)) newRow.validFrom = rotatedAt;
+    timeline.set(newKeyId, newRow);
+  }
+
+  for (const rev of Array.isArray(list?.revocations) ? list.revocations : []) {
+    const revokedAt = typeof rev?.revokedAt === "string" && rev.revokedAt.trim() ? rev.revokedAt.trim() : null;
+    const keyId = typeof rev?.keyId === "string" && rev.keyId.trim() ? rev.keyId.trim() : null;
+    if (!revokedAt || !keyId) continue;
+    const row = timeline.get(keyId) ?? {};
+    if (!row.revokedAt || Date.parse(revokedAt) < Date.parse(row.revokedAt)) row.revokedAt = revokedAt;
+    timeline.set(keyId, row);
+  }
+
+  return timeline;
+}
+