@entpoind/verify 0.1.0 → 0.2.0

package/dist/witness.js

@@ -0,0 +1,523 @@
+/**
+ * @entpoind/verify — the receipt ledger's public witness: a batch root's entry in the Sigstore Rekor log.
+ *
+ * What the ledger logs (runtime/shared/rekor-witness.ts, by the hourly cron job):
+ *
+ *   rootMessage   the canonical JSON the batch's `rootSignature` is over (ledgerRootMessage)
+ *   A             SHA-512(UTF-8 rootMessage)            `witness.artifactSha512`
+ *   data.hash     SHA-512(A)                            `witness.rekorSha512`, the hash in the `hashedrekord` entry
+ *   signature     Ed25519ph by the region's receipt key, the SAME key (`kid`) as the root's, with A as the message,
+ *                 so its prehash is SHA-512(A) = data.hash
+ *
+ * Offline (always): the witness's hashes are recomputed from the root message, the witness is by the root's key, its
+ * Ed25519ph signature verifies over the recomputed hash with that key, and the copy of the log's answer the proof carries
+ * (`body`, `entryUuid`, `inclusionProof`) is that entry and hangs together. That copy came from Entpoind, so it shows the
+ * witness is consistent, not that the log holds it.
+ *
+ * Online (opt-in): the entry is fetched from the log itself and checked again, with the log's own inclusion proof,
+ * signed checkpoint and signed entry timestamp verified against the log's public key (ECDSA P-256, as rekor.sigstore.dev
+ * uses). The key is pinned by the caller, or fetched from the log, which is then trust on first use; the result says which.
+ *
+ * Nothing here can fail the receipt or the ledger proof: a witness that is absent, off, pending, inconsistent or
+ * unreachable is reported as exactly that, next to a ledger proof that verified on its own. `off` means the receipt's
+ * workspace had turned the public witness off before the receipt was batched: the batch's root was never submitted, by
+ * the workspace's choice. It is not a failure.
+ */
+import { canonicalJcs } from "./canonical-json.js";
+import { verifyEd25519ph } from "./ed25519ph.js";
+export const WITNESS_KIND = "rekor.hashedrekord.v0.0.1";
+export const DEFAULT_REKOR_URL = "https://rekor.sigstore.dev";
+export const WITNESS_LOG_TIMEOUT_MS = 10_000;
+// ─── bytes ────────────────────────────────────────────────────────────
+const ENC = new TextEncoder();
+const HEX64 = /^[0-9a-f]{64}$/;
+const UUID = /^(?:[0-9a-f]{16})?[0-9a-f]{64}$/;
+const SPKI_ED25519_PREFIX = [0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00];
+function hexOf(b) {
+    let s = "";
+    for (const x of b)
+        s += x.toString(16).padStart(2, "0");
+    return s;
+}
+function bytesOfHex(h) {
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+/** base64 or base64url, padded or not. Throws on anything else. */
+function fromBase64(s) {
+    const t = s.replace(/\s+/g, "").replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(t + "=".repeat((4 - (t.length % 4)) % 4));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+const eq = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+async function digest(alg, b) {
+    return new Uint8Array(await crypto.subtle.digest(alg, b));
+}
+function derOfPem(pem) {
+    const m = /-----BEGIN PUBLIC KEY-----([\s\S]*?)-----END PUBLIC KEY-----/.exec(pem);
+    if (!m)
+        return null;
+    try {
+        return fromBase64(m[1]);
+    }
+    catch {
+        return null;
+    }
+}
+/** The raw 32-byte key of an Ed25519 SubjectPublicKeyInfo, or null. */
+function ed25519OfSpki(der) {
+    if (der.length !== 44 || !SPKI_ED25519_PREFIX.every((x, i) => der[i] === x))
+        return null;
+    return der.slice(12);
+}
+// ─── the log's Merkle tree (RFC 6962) ─────────────────────────────────
+/** RFC 9162 §2.1.3.2: does `leaf` at `index` fold up `path` to `root` in a tree of `size` leaves? */
+async function verifyRfc6962Inclusion(leaf, index, size, path, root) {
+    if (!Number.isSafeInteger(index) || !Number.isSafeInteger(size) || index < 0 || index >= size)
+        return false;
+    let fn = index;
+    let sn = size - 1;
+    let r = leaf;
+    for (const p of path) {
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            r = await digest("SHA-256", concat(Uint8Array.of(1), p, r));
+            if (fn % 2 === 0) {
+                while (fn % 2 === 0 && fn !== 0) {
+                    fn = Math.floor(fn / 2);
+                    sn = Math.floor(sn / 2);
+                }
+            }
+        }
+        else {
+            r = await digest("SHA-256", concat(Uint8Array.of(1), r, p));
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && eq(r, root);
+}
+function isInclusionProof(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const p = x;
+    return (Number.isSafeInteger(p.logIndex) &&
+        Number.isSafeInteger(p.treeSize) &&
+        typeof p.rootHash === "string" &&
+        HEX64.test(p.rootHash) &&
+        Array.isArray(p.hashes) &&
+        p.hashes.every((h) => typeof h === "string" && HEX64.test(h)) &&
+        typeof p.checkpoint === "string");
+}
+async function inclusionHolds(leaf, p) {
+    return verifyRfc6962Inclusion(leaf, p.logIndex, p.treeSize, p.hashes.map(bytesOfHex), bytesOfHex(p.rootHash));
+}
+/**
+ * The checks on a stored `hashedrekord` body (base64), against what the root gives: the hash is the recomputed one, the
+ * key is the root's, and the signature in it verifies. Returns the problems, the signature it carries and the leaf hash.
+ */
+async function checkEntryBody(bodyB64, want) {
+    let bytes;
+    let body;
+    try {
+        bytes = fromBase64(bodyB64);
+    }
+    catch {
+        return { problems: ["entry_body_malformed"], signature: null, leaf: null };
+    }
+    // The leaf is the stored bytes, whatever they hold: the UUID and the inclusion proof are over them.
+    const leaf = await digest("SHA-256", concat(Uint8Array.of(0), bytes));
+    try {
+        body = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return { problems: ["entry_body_malformed"], signature: null, leaf };
+    }
+    const sp = body?.spec;
+    if (!body || body.kind !== "hashedrekord" || body.apiVersion !== "0.0.1" || typeof sp?.signature?.content !== "string" || typeof sp?.signature?.publicKey?.content !== "string") {
+        return { problems: ["entry_body_malformed"], signature: null, leaf };
+    }
+    const problems = [];
+    if (sp.data?.hash?.algorithm !== "sha512" || sp.data?.hash?.value !== hexOf(want.rekorSha512))
+        problems.push("entry_hash_mismatch");
+    let signature = null;
+    let key = null;
+    try {
+        signature = fromBase64(sp.signature.content);
+        const der = derOfPem(new TextDecoder().decode(fromBase64(sp.signature.publicKey.content)));
+        key = der ? ed25519OfSpki(der) : null;
+    }
+    catch {
+        return { problems: ["entry_body_malformed"], signature: null, leaf };
+    }
+    if (!key || !eq(key, want.publicKey))
+        problems.push("entry_key_mismatch");
+    else if (!(await verifyEd25519ph(key, want.rekorSha512, signature)))
+        problems.push("bad_witness_signature");
+    return { problems, signature, leaf };
+}
+/** Never throws: anything the witness holds that cannot be checked is a problem, reported. */
+export async function checkLedgerWitness(witness, ctx, log) {
+    if (witness === null || witness === undefined)
+        return { status: "absent" };
+    if (typeof witness !== "object" || Array.isArray(witness))
+        return { status: "malformed" };
+    const w = witness;
+    const str = (k) => (typeof w[k] === "string" ? w[k] : null);
+    const int = (k) => (Number.isSafeInteger(w[k]) ? w[k] : null);
+    if (w.status === "off")
+        return { status: "off" };
+    if (w.status === "pending")
+        return { status: "pending", since: str("since"), attempts: int("attempts"), lastError: str("lastError"), nextAttemptAt: str("nextAttemptAt") };
+    if (w.status !== "logged")
+        return { status: "malformed" };
+    const report = {
+        status: "logged",
+        consistent: false,
+        problems: [],
+        log: str("log"),
+        logIndex: int("logIndex"),
+        entryUuid: str("entryUuid"),
+        integratedAt: str("integratedAt"),
+        searchUrl: str("searchUrl"),
+    };
+    const problems = new Set();
+    try {
+        const a = await digest("SHA-512", ENC.encode(ctx.rootMessage));
+        const rekor = await digest("SHA-512", a);
+        const publicKey = fromBase64(ctx.publicKeyX);
+        // 1. the hashes are the root's
+        if (str("kind") !== WITNESS_KIND)
+            problems.add("unknown_witness_kind");
+        if (str("artifactSha512") !== hexOf(a))
+            problems.add("artifact_hash_mismatch");
+        if (str("rekorSha512") !== hexOf(rekor))
+            problems.add("rekor_hash_mismatch");
+        // 2. by the root's key, and its signature verifies over the RECOMPUTED hash
+        if (str("signatureKeyId") !== ctx.signatureKeyId)
+            problems.add("not_the_root_key");
+        const sig = str("signature");
+        let sigBytes = null;
+        try {
+            sigBytes = sig === null ? null : fromBase64(sig);
+        }
+        catch {
+            sigBytes = null;
+        }
+        if (sigBytes === null)
+            problems.add("malformed_witness");
+        else if (!(await verifyEd25519ph(publicKey, rekor, sigBytes)))
+            problems.add("bad_witness_signature");
+        // 3. the copy of the log's answer is that entry
+        const body = str("body");
+        const uuid = str("entryUuid");
+        const integratedTime = int("integratedTime");
+        if (body === null || uuid === null || !UUID.test(uuid) || integratedTime === null || report.logIndex === null)
+            problems.add("malformed_witness");
+        if (body !== null) {
+            const entry = await checkEntryBody(body, { rekorSha512: rekor, publicKey });
+            for (const p of entry.problems)
+                problems.add(p);
+            if (entry.signature && sigBytes && !eq(entry.signature, sigBytes))
+                problems.add("entry_signature_mismatch");
+            if (entry.leaf && uuid !== null && uuid.slice(-64) !== hexOf(entry.leaf))
+                problems.add("entry_uuid_mismatch");
+            const ip = w.inclusionProof;
+            if (ip !== null && ip !== undefined) {
+                if (!isInclusionProof(ip))
+                    problems.add("malformed_witness");
+                else if (!entry.leaf || !(await inclusionHolds(entry.leaf, ip)))
+                    problems.add("inclusion_proof_invalid");
+            }
+        }
+        if (integratedTime !== null && report.integratedAt !== null && new Date(integratedTime * 1000).toISOString() !== report.integratedAt)
+            problems.add("integrated_at_mismatch");
+    }
+    catch {
+        problems.add("malformed_witness");
+    }
+    report.problems = [...problems];
+    report.consistent = report.problems.length === 0;
+    if (log)
+        report.logCheck = await checkWitnessLog(w, ctx, log);
+    return report;
+}
+// ─── online: ask the log ──────────────────────────────────────────────
+async function timedFetch(f, url, init, timeoutMs) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+        // A redirect could leave https or the log's origin; the Rekor API does not redirect.
+        return await f(url, { ...init, redirect: "error", signal: ctl.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** An ECDSA signature as DER (what Rekor emits) to the r ‖ s form WebCrypto verifies. Null if it is not one. */
+function p1363OfDer(der, n = 32) {
+    let i = 0;
+    if (der[i++] !== 0x30)
+        return null;
+    let len = der[i++];
+    if (len & 0x80) {
+        if (len !== 0x81)
+            return null;
+        len = der[i++];
+    }
+    if (i + len !== der.length)
+        return null;
+    const out = new Uint8Array(2 * n);
+    for (let part = 0; part < 2; part++) {
+        if (der[i++] !== 0x02)
+            return null;
+        const l = der[i++];
+        if (l === undefined || l < 1 || i + l > der.length)
+            return null;
+        let v = der.slice(i, i + l);
+        i += l;
+        while (v.length > 1 && v[0] === 0)
+            v = v.slice(1);
+        if (v.length > n)
+            return null;
+        out.set(v, part * n + (n - v.length));
+    }
+    return i === der.length ? out : null;
+}
+async function ecdsaVerify(key, derSig, message) {
+    const sig = p1363OfDer(derSig);
+    if (!sig)
+        return false;
+    try {
+        return await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key, sig, message);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A Rekor checkpoint (a signed note): the body lines `<origin>\n<tree size>\n<base64 root hash>\n[…]\n`, a blank line,
+ * then signature lines `— <name> <base64(4-byte key hint ‖ DER signature)>`. The signature is over the body, its last
+ * newline included; the key hint is the first four bytes of the log's `logID` (SHA-256 of its key).
+ */
+async function checkCheckpoint(note, ip, logId, key) {
+    const cut = note.indexOf("\n\n");
+    if (cut < 0)
+        return "checkpoint_malformed";
+    const signed = note.slice(0, cut + 1);
+    const lines = signed.split("\n");
+    if (lines.length < 4 || !/^[0-9]+$/.test(lines[1]))
+        return "checkpoint_malformed";
+    let root;
+    try {
+        root = fromBase64(lines[2]);
+    }
+    catch {
+        return "checkpoint_malformed";
+    }
+    if (Number(lines[1]) !== ip.treeSize || hexOf(root) !== ip.rootHash)
+        return "checkpoint_mismatch";
+    const sigLines = note.slice(cut + 2).split("\n").filter((l) => l.length > 0);
+    for (const l of sigLines) {
+        const m = /^— (\S+) (\S+)$/.exec(l);
+        if (!m)
+            continue;
+        let raw;
+        try {
+            raw = fromBase64(m[2]);
+        }
+        catch {
+            continue;
+        }
+        if (raw.length < 5 || !eq(raw.slice(0, 4), logId.slice(0, 4)))
+            continue;
+        if (await ecdsaVerify(key, raw.slice(4), ENC.encode(signed)))
+            return "ok";
+    }
+    return "bad_checkpoint_signature";
+}
+async function checkWitnessLog(w, ctx, o) {
+    const f = o.fetch ?? fetch;
+    const timeoutMs = o.timeoutMs ?? WITNESS_LOG_TIMEOUT_MS;
+    const raw = o.logUrl ?? (typeof w.log === "string" && w.log ? w.log : DEFAULT_REKOR_URL);
+    const logUrl = raw.replace(/\/+$/, "");
+    try {
+        if (new URL(logUrl).protocol !== "https:")
+            return { checked: false, logUrl, reason: "log_url_not_https" };
+    }
+    catch {
+        return { checked: false, logUrl, reason: "log_url_not_https" };
+    }
+    const uuid = typeof w.entryUuid === "string" ? w.entryUuid.toLowerCase() : "";
+    if (!UUID.test(uuid))
+        return { checked: false, logUrl, reason: "no_entry_uuid" };
+    let res;
+    try {
+        res = await timedFetch(f, `${logUrl}/api/v1/log/entries/${uuid}`, { headers: { accept: "application/json" } }, timeoutMs);
+    }
+    catch {
+        return { checked: false, logUrl, reason: "log_unreachable" };
+    }
+    const out = {
+        checked: true,
+        logUrl,
+        ok: false,
+        problems: [],
+        logKey: "unavailable",
+        integratedTime: null,
+        inclusionProof: "not_checked",
+        checkpoint: "not_checked",
+        signedEntryTimestamp: "not_checked",
+    };
+    const problems = new Set();
+    const done = () => {
+        out.problems = [...problems];
+        out.ok = out.problems.length === 0 && out.inclusionProof === "verified" && out.checkpoint === "verified" && out.signedEntryTimestamp === "verified";
+        return out;
+    };
+    if (res.status === 404) {
+        await res.body?.cancel().catch(() => { });
+        problems.add("entry_not_in_log");
+        return done();
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        return { checked: false, logUrl, reason: "log_error", status: res.status };
+    }
+    // The answer: { "<uuid>": { body, integratedTime, logID, logIndex, verification: { inclusionProof, signedEntryTimestamp } } }
+    let v = null;
+    try {
+        const json = (await res.json());
+        const keys = json && typeof json === "object" && !Array.isArray(json) ? Object.keys(json) : [];
+        if (keys.length === 1) {
+            if (keys[0].toLowerCase().slice(-64) !== uuid.slice(-64))
+                problems.add("entry_uuid_mismatch");
+            v = json[keys[0]];
+        }
+    }
+    catch {
+        v = null;
+    }
+    const verification = v?.verification;
+    if (!v ||
+        typeof v !== "object" ||
+        typeof v.body !== "string" ||
+        !Number.isSafeInteger(v.logIndex) ||
+        !Number.isSafeInteger(v.integratedTime) ||
+        typeof v.logID !== "string" ||
+        !HEX64.test(v.logID) ||
+        !verification ||
+        typeof verification !== "object") {
+        problems.add("bad_log_response");
+        return done();
+    }
+    const body = v.body;
+    const logIndex = v.logIndex;
+    const integratedTime = v.integratedTime;
+    const logId = v.logID;
+    out.integratedTime = integratedTime;
+    // The entry the log holds: the root's hash, the root's key, a signature that verifies.
+    const a = await digest("SHA-512", ENC.encode(ctx.rootMessage));
+    const rekor = await digest("SHA-512", a);
+    const entry = await checkEntryBody(body, { rekorSha512: rekor, publicKey: fromBase64(ctx.publicKeyX) });
+    for (const p of entry.problems)
+        problems.add(p);
+    if (!entry.leaf || uuid.slice(-64) !== hexOf(entry.leaf))
+        problems.add("entry_uuid_mismatch");
+    if (logIndex !== w.logIndex)
+        problems.add("log_index_mismatch");
+    if (integratedTime !== w.integratedTime)
+        problems.add("integrated_time_mismatch");
+    // Its inclusion in the log's tree needs no key.
+    const ip = verification.inclusionProof;
+    if (ip === undefined || ip === null) {
+        problems.add("no_inclusion_proof");
+    }
+    else if (!isInclusionProof(ip)) {
+        problems.add("bad_log_response");
+    }
+    else if (entry.leaf && (await inclusionHolds(entry.leaf, ip))) {
+        out.inclusionProof = "verified";
+    }
+    else {
+        out.inclusionProof = "failed";
+        problems.add("inclusion_proof_invalid");
+    }
+    // The log's key: pinned, or the log's own (for the entry's shard, named by the UUID's 16-hex tree id).
+    let der = null;
+    if (o.logPublicKey !== undefined) {
+        der = derOfPem(o.logPublicKey);
+        if (der)
+            out.logKey = "pinned";
+    }
+    else {
+        const tree = uuid.length === 80 ? `?treeID=${BigInt(`0x${uuid.slice(0, 16)}`).toString()}` : "";
+        try {
+            const kr = await timedFetch(f, `${logUrl}/api/v1/log/publicKey${tree}`, { headers: { accept: "application/x-pem-file, text/plain" } }, timeoutMs);
+            if (kr.ok) {
+                der = derOfPem(await kr.text());
+                if (der)
+                    out.logKey = "fetched";
+            }
+            else {
+                await kr.body?.cancel().catch(() => { });
+            }
+        }
+        catch {
+            der = null;
+        }
+    }
+    if (!der) {
+        problems.add("log_key_unavailable");
+        return done();
+    }
+    if (hexOf(await digest("SHA-256", der)) !== logId) {
+        problems.add("log_key_not_log_id");
+        return done();
+    }
+    let key;
+    try {
+        key = await crypto.subtle.importKey("spki", der, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+    }
+    catch {
+        problems.add("log_key_unsupported");
+        return done();
+    }
+    // The signed entry timestamp: the log's signature over { body, integratedTime, logID, logIndex } (RFC 8785).
+    const set = verification.signedEntryTimestamp;
+    let setOk = false;
+    if (typeof set === "string") {
+        try {
+            setOk = await ecdsaVerify(key, fromBase64(set), ENC.encode(canonicalJcs({ body, integratedTime, logID: logId, logIndex })));
+        }
+        catch {
+            setOk = false;
+        }
+    }
+    out.signedEntryTimestamp = setOk ? "verified" : "failed";
+    if (!setOk)
+        problems.add("bad_signed_entry_timestamp");
+    // The checkpoint the inclusion proof ends in, signed by the log.
+    if (isInclusionProof(ip)) {
+        const c = await checkCheckpoint(ip.checkpoint, ip, bytesOfHex(logId), key);
+        out.checkpoint = c === "ok" ? "verified" : "failed";
+        if (c !== "ok")
+            problems.add(c);
+    }
+    return done();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entpoind/verify",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Offline verification of Entpoind Tools receipts and VerifiableArtifact bundles — Ed25519 over RFC 8785 canonical JSON, plus Merkle inclusion proofs. Zero dependencies.",
   "license": "MIT",
   "author": "Avonao, Inc.",
@@ -15,7 +15,7 @@
     },
     "./package.json": "./package.json"
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
   "sideEffects": false,
   "engines": {
     "node": ">=20"