burnledger 0.9.0 → 0.10.0

package/dist/esm/audit-pack.js

@@ -0,0 +1,858 @@
+/** Audit pack verification (docs/audit-pack.md).
+ *
+ * A port of core/auditpack.go and core/auditpack_footer.go, verdict for
+ * verdict and reason string for reason string. Every record inside a pack is
+ * verified exactly as `burnledger check --cert` verifies one, through the same
+ * verifyCertificateWithStatus and verifyTransparency. What this file adds is
+ * the framing — header, footer, digest, cursor chain — that lets a reader tell
+ * a whole page from a subset and a whole set of pages from a partial one, and
+ * the footer's signed statement, which is the issuer's word on the count and
+ * digest rather than the host's.
+ *
+ * The single-record verifier reports a refusal by THROWING a VerificationError
+ * whose message is prose, where Go returns a named verdict. A pack result is
+ * read beside the Go one — testdata/audit_pack/index.json pins the two to the
+ * same strings — so the throw is mapped back to Go's name here rather than
+ * leaking one SDK's wording into a cross-language contract.
+ */
+import { CERTIFICATE_REVOKED, UNSUPPORTED_ALGORITHM, UNSUPPORTED_FORMAT_VERSION, VerificationError, } from "./errors.js";
+import { buildTreeHeadPayload, bytesToHex, canonicalJson, decodeFixed, evaluateKey, formatTimestamp, formatUuid, hexToBytes, keyIsUsable, parseUuid, publicKeyFromHex, signatureCoversRunId, transparencyVerdictName, verifyCertificateWithStatus, verifyTransparency, } from "./verify.js";
+import { parseRunRecordDocument, verifyRunRecord, verifyRunRecordInclusion, } from "./run-record.js";
+export const AUDIT_PACK_FORMAT = "burnledger.audit_pack.v1";
+/** Mirrors core.auditPackMaxLine: a record is a few kilobytes, and a line past
+ * sixteen megabytes is not one this reader should buffer. */
+const MAX_LINE_BYTES = 16 << 20;
+const NOT_AUDIT_PACK = "not an audit pack: the first line is not an audit pack header";
+export const PAYLOAD_TYPE_AUDIT_PACK_FOOTER = "burnledger.audit_pack_footer.v1";
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+// ---------------------------------------------------------------------------
+// Go verdict names for this SDK's refusals
+// ---------------------------------------------------------------------------
+/** VerificationError message prefixes → core.VerificationResult, in the order
+ * verifyCertificate and verifyStatusStatement raise them. A message none of
+ * these match came from a field this SDK could not READ (decodeFixed,
+ * requireUint, formatTimestamp, objectAt), which is where Go's json.Unmarshal
+ * refuses the document before any verdict — so it is reported the way Go
+ * reports that, as an unreadable certificate document. */
+const OFFLINE_VERDICTS = [
+    ["unknown issuer key:", "UNKNOWN_KEY"],
+    ["issuer key is compromised:", "KEY_COMPROMISED"],
+    ["issuer key was not valid when it signed:", "KEY_OUTSIDE_VALIDITY"],
+    ["issuer key has an unusable status", "UNKNOWN_KEY"],
+    ["certificate signature is invalid", "INVALID_CERTIFICATE_SIGNATURE"],
+    ["attestation signature is invalid", "INVALID_ATTESTATION_SIGNATURE"],
+    ["certificate attests no systems", "INCOMPLETE_VERIFICATION"],
+    ["malformed systems:", "MALFORMED_SYSTEMS"],
+    ["data still present:", "DATA_STILL_PRESENT"],
+    ["incomplete verification:", "INCOMPLETE_VERIFICATION"],
+    ["status statement signed by unknown key:", "UNKNOWN_KEY"],
+    ["status statement key is compromised:", "KEY_COMPROMISED"],
+    ["status statement key was not valid when it signed:", "KEY_OUTSIDE_VALIDITY"],
+    ["status statement key has an unusable status", "UNKNOWN_KEY"],
+    ["status statement signature is invalid", "INVALID_STATUS_SIGNATURE"],
+    ["status statement is about a different certificate", "STATUS_STATEMENT_MISMATCH"],
+    // Go's buildCertificateStatusPayload failing is INVALID_STATUS_SIGNATURE;
+    // here the same fields are refused by decodeFixed under a "status." path.
+    ["status.", "INVALID_STATUS_SIGNATURE"],
+];
+const OFFLINE_CODES = new Map([
+    [CERTIFICATE_REVOKED, "REVOKED"],
+    [UNSUPPORTED_FORMAT_VERSION, "UNKNOWN_FORMAT_VERSION"],
+    [UNSUPPORTED_ALGORITHM, "UNSUPPORTED_ALGORITHM"],
+]);
+function offlineVerdict(e) {
+    const coded = e.code === undefined ? undefined : OFFLINE_CODES.get(e.code);
+    if (coded !== undefined)
+        return coded;
+    for (const [prefix, verdict] of OFFLINE_VERDICTS) {
+        if (e.message.startsWith(prefix))
+            return verdict;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Framing: the strict line scanner (core.ScanAuditPack)
+// ---------------------------------------------------------------------------
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/** Trailing "\r" and "\n" stripped, as bytes.TrimRight(line, "\r\n") does. */
+function trimLineEnd(line) {
+    let end = line.length;
+    while (end > 0 && (line[end - 1] === 0x0a || line[end - 1] === 0x0d))
+        end--;
+    return line.subarray(0, end);
+}
+function isBlank(line) {
+    for (const b of line) {
+        if (b !== 0x20 && b !== 0x09 && b !== 0x0a && b !== 0x0d && b !== 0x0b && b !== 0x0c)
+            return false;
+    }
+    return true;
+}
+function stringOrNull(v, field) {
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v !== "string")
+        throw new Error(`${field} is not a string`);
+    return v;
+}
+function optionalString(v, field) {
+    if (v === null || v === undefined)
+        return undefined;
+    if (typeof v !== "string")
+        throw new Error(`${field} is not a string`);
+    return v;
+}
+function requireInt(v, field) {
+    // Go's int and uint64 refuse a fraction or, for uint64, a negative.
+    if (typeof v !== "number" || !Number.isSafeInteger(v))
+        throw new Error(`${field} is not an integer`);
+    return v;
+}
+/** The type checks encoding/json applies unmarshalling core.AuditPackHeader.
+ * Anything it would refuse is refused here with the same outcome: the whole
+ * page is UNREADABLE. Value checks (hex lengths, the format string) come after,
+ * as they do in Go. */
+function parseHeader(doc) {
+    const format = optionalString(doc.format, "format") ?? "";
+    // time.Time refuses anything that is not RFC 3339, and reads null or an
+    // absent key as the zero time.
+    const generatedAt = formatTimestamp(optionalString(doc.generated_at, "generated_at"), "generated_at");
+    const rawFilters = doc.filters;
+    const filters = { status: null, issuedAfter: null, issuedBefore: null, runId: null };
+    if (rawFilters !== undefined && rawFilters !== null) {
+        if (!isObject(rawFilters))
+            throw new Error("filters is not an object");
+        filters.status = stringOrNull(rawFilters.status, "filters.status");
+        filters.issuedAfter = stringOrNull(rawFilters.issued_after, "filters.issued_after");
+        filters.issuedBefore = stringOrNull(rawFilters.issued_before, "filters.issued_before");
+        filters.runId = stringOrNull(rawFilters.run_id, "filters.run_id");
+    }
+    const cursor = stringOrNull(doc.cursor, "cursor");
+    let issuerKeys = [];
+    const rawKeys = doc.issuer_keys;
+    if (rawKeys !== undefined && rawKeys !== null) {
+        if (!isObject(rawKeys))
+            throw new Error("issuer_keys is not an object");
+        if (rawKeys.keys !== undefined && rawKeys.keys !== null) {
+            if (!Array.isArray(rawKeys.keys))
+                throw new Error("issuer_keys.keys is not an array");
+            issuerKeys = rawKeys.keys.map((k, i) => {
+                if (!isObject(k))
+                    throw new Error(`issuer_keys.keys[${i}] is not an object`);
+                return k;
+            });
+        }
+    }
+    const header = {
+        format,
+        generatedAt,
+        filters,
+        cursor,
+        issuerKeys,
+    };
+    const rawHead = doc.log_head;
+    if (rawHead !== undefined && rawHead !== null) {
+        if (!isObject(rawHead))
+            throw new Error("log_head is not an object");
+        const head = {
+            tree_size: requireInt(rawHead.tree_size ?? 0, "log_head.tree_size"),
+            root_hash: optionalString(rawHead.root_hash, "log_head.root_hash") ?? "",
+            timestamp: optionalString(rawHead.timestamp, "log_head.timestamp") ?? "",
+            signature: optionalString(rawHead.signature, "log_head.signature") ?? "",
+        };
+        if (head.tree_size < 0)
+            throw new Error("log_head.tree_size is negative");
+        const logId = optionalString(rawHead.log_id, "log_head.log_id");
+        if (logId !== undefined)
+            head.log_id = logId;
+        header.logHead = head;
+    }
+    // Kept as it arrived, as Go's json.RawMessage does; the verifier parses it.
+    // A present key that is not an object — null included — is refused as
+    // core.ParseRunRecordDocument refuses it.
+    const rawRun = doc.run_record;
+    if (rawRun !== undefined) {
+        if (!isObject(rawRun))
+            throw new Error("run_record: run record: not a JSON object");
+        header.runRecord = rawRun;
+    }
+    return header;
+}
+/** The type checks encoding/json applies unmarshalling core.AuditPackFooter,
+ * `signed` included: a null or absent `signed` is an unsigned footer, and a
+ * field of the wrong JSON type makes the page UNREADABLE. Whether the hex and
+ * the timestamp READ is the statement rebuild's question, as in Go. */
+function parseFooter(doc) {
+    const footer = {
+        recordCount: requireInt(doc.record_count ?? 0, "record_count"),
+        nextCursor: stringOrNull(doc.next_cursor, "next_cursor"),
+        recordsSha256: optionalString(doc.records_sha256, "records_sha256") ?? "",
+    };
+    const raw = doc.signed;
+    if (raw === undefined || raw === null)
+        return footer;
+    if (!isObject(raw))
+        throw new Error("signed is not an object");
+    const signed = {
+        statement_issued_at: optionalString(raw.statement_issued_at, "signed.statement_issued_at") ?? "",
+        sth_tree_size: requireInt(raw.sth_tree_size ?? 0, "signed.sth_tree_size"),
+        sth_root_hash: optionalString(raw.sth_root_hash, "signed.sth_root_hash") ?? "",
+        signature: optionalString(raw.signature, "signed.signature") ?? "",
+        key_id: optionalString(raw.key_id, "signed.key_id") ?? "",
+    };
+    if (signed.sth_tree_size < 0)
+        throw new Error("signed.sth_tree_size is negative");
+    footer.signed = signed;
+    return footer;
+}
+/** Reads one page. The rules are strict because the file is evidence: the
+ * header is the first non-empty line, the footer when present is the last, a
+ * second header is refused (two pages concatenated as bytes are not one page),
+ * and any line after a footer is refused. Throws an Error whose message is the
+ * pack's UNREADABLE reason. */
+async function scanAuditPack(crypto, source, cb) {
+    let header = null;
+    let footer = null;
+    let records = 0;
+    const digested = [];
+    let at = 0;
+    while (at < source.length) {
+        const nl = source.indexOf(0x0a, at);
+        const end = nl < 0 ? source.length : nl + 1;
+        const line = source.subarray(at, end);
+        at = end;
+        if (line.length > MAX_LINE_BYTES)
+            throw new Error(`audit pack: a line exceeds ${MAX_LINE_BYTES} bytes`);
+        const trimmed = trimLineEnd(line);
+        if (isBlank(trimmed))
+            continue;
+        if (footer !== null)
+            throw new Error("audit pack: a line follows the footer; the footer must be last");
+        // encoding/json unmarshals `null` into a struct as a no-op, so a bare null
+        // line is a record with nothing in it rather than a line that is not JSON.
+        let parsed;
+        try {
+            parsed = JSON.parse(decoder.decode(trimmed));
+        }
+        catch {
+            parsed = undefined;
+        }
+        const readable = parsed === null ||
+            (isObject(parsed) && isMarker(parsed._audit_pack_header) && isMarker(parsed._audit_pack_footer));
+        if (!readable) {
+            if (header === null)
+                throw new Error(NOT_AUDIT_PACK);
+            throw new Error(`audit pack: record ${records + 1} is not a JSON object`);
+        }
+        const doc = parsed === null ? {} : parsed;
+        if (header === null) {
+            if (doc._audit_pack_header !== true)
+                throw new Error(NOT_AUDIT_PACK);
+            try {
+                header = parseHeader(doc);
+            }
+            catch (e) {
+                throw new Error(`audit pack: header: ${message(e)}`);
+            }
+            if (header.format !== AUDIT_PACK_FORMAT) {
+                throw new Error(`audit pack: format ${JSON.stringify(header.format)} is not ${AUDIT_PACK_FORMAT}`);
+            }
+            await cb.onHeader(header);
+            continue;
+        }
+        if (doc._audit_pack_header === true) {
+            throw new Error("audit pack: a second header; concatenate pages by their records, not their bytes");
+        }
+        if (doc._audit_pack_footer === true) {
+            try {
+                footer = parseFooter(doc);
+            }
+            catch (e) {
+                throw new Error(`audit pack: footer: ${message(e)}`);
+            }
+            continue;
+        }
+        digested.push(trimmed);
+        records++;
+        await cb.onRecord(records, trimmed);
+    }
+    if (header === null)
+        throw new Error(NOT_AUDIT_PACK);
+    return { header, footer, records, digest: await auditPackDigest(crypto, digested) };
+}
+/** A marker is a bool or absent; anything else fails Go's probe unmarshal. */
+function isMarker(v) {
+    return v === undefined || typeof v === "boolean";
+}
+/** The one definition of the footer's records_sha256: SHA-256 over every
+ * record line followed by a newline, in file order, with a trailing carriage
+ * return stripped. Mirrors core.AuditPackDigest. */
+export async function auditPackDigest(crypto, lines) {
+    let total = 0;
+    const trimmed = lines.map((l) => {
+        const t = trimLineEnd(l);
+        total += t.length + 1;
+        return t;
+    });
+    const joined = new Uint8Array(total);
+    let at = 0;
+    for (const t of trimmed) {
+        joined.set(t, at);
+        at += t.length;
+        joined[at++] = 0x0a;
+    }
+    return bytesToHex(await crypto.sha256(joined));
+}
+// ---------------------------------------------------------------------------
+// Verification (core.VerifyAuditPackWith)
+// ---------------------------------------------------------------------------
+/** The pack's own issuer_keys as a key set, under the checks cli.ts loadKeys
+ * applies to a --keys file: the key parses, a declared key_id is
+ * sha256(public_key), a compromised key names its date, and a duplicate does
+ * not contradict itself. The map is keyed on the DERIVED id so a lying key_id
+ * cannot shadow a genuine one. Throws where Go's KeyListDocument.PublicKeys
+ * returns an error. */
+async function keysFromEntries(crypto, entries) {
+    const map = new Map();
+    for (const e of entries) {
+        if (e.key_status === "compromised" && (e.compromised_from === undefined || e.compromised_from === null)) {
+            throw new Error(`key ${e.key_id ?? "?"}: key_status is compromised but compromised_from is absent`);
+        }
+        let pki;
+        try {
+            pki = await publicKeyFromHex(crypto, e.public_key, {
+                keyStatus: e.key_status,
+                notBefore: e.not_before,
+                notAfter: e.not_after ?? undefined,
+                compromisedFrom: e.compromised_from ?? undefined,
+            });
+        }
+        catch (err) {
+            throw new Error(`key ${e.key_id ?? "?"}: invalid public_key: ${message(err)}`);
+        }
+        if (e.key_id !== undefined && e.key_id !== pki.keyId) {
+            throw new Error(`key_id ${e.key_id} does not match sha256(public_key) (${pki.keyId})`);
+        }
+        const existing = map.get(pki.keyId);
+        if (existing !== undefined && existing.keyStatus !== pki.keyStatus) {
+            throw new Error(`conflicting key_status for duplicate key ${pki.keyId}`);
+        }
+        map.set(pki.keyId, pki);
+    }
+    return map;
+}
+const HEX_32 = /^[0-9a-fA-F]{64}$/;
+const HEX_64 = /^[0-9a-fA-F]{128}$/;
+/** Mirrors core.verifyAuditPackLogHead. A head names no key id, so every key
+ * usable at the head's own timestamp is tried; the one that verifies is
+ * reported so the reader knows which authority the head rests on. Returns
+ * UNREADABLE where Go's SignedTreeHeadDocument.SignedTreeHead refuses the
+ * document: a short or long hex value, or a timestamp that is not RFC 3339. */
+async function verifyLogHead(crypto, head, keys) {
+    if (!HEX_32.test(head.root_hash) || !HEX_64.test(head.signature)) {
+        return { result: "UNREADABLE", keyId: "" };
+    }
+    let anchor;
+    let payload;
+    try {
+        anchor = Math.floor(Date.parse(formatTimestamp(head.timestamp, "log_head.timestamp")) / 1000);
+        payload = buildTreeHeadPayload({ ...head });
+    }
+    catch (e) {
+        if (e instanceof VerificationError)
+            return { result: "UNREADABLE", keyId: "" };
+        throw e;
+    }
+    const signature = hexToBytes(head.signature);
+    for (const [id, key] of keys) {
+        if (!keyIsUsable(evaluateKey(key, anchor)))
+            continue;
+        if (await crypto.ed25519Verify(key.keyBytes, payload, signature))
+            return { result: "VALID", keyId: id };
+    }
+    return { result: "INVALID_SIGNATURE", keyId: "" };
+}
+/** The rule a record must meet to count as verified — the one cli.ts's exit
+ * code applies to a single record. The two soft key verdicts are refused here
+ * as there: a pack an auditor relies on is exactly the place a "needs a human"
+ * verdict must not pass as a number. */
+function recordAccepted(offline, transparency) {
+    if (offline !== "VALID" && offline !== "VALID_REVOCATION_UNKNOWN")
+        return false;
+    return transparency === "VALID" || transparency === "NOT_INCLUDED";
+}
+/** Verify one page offline, exactly as core.VerifyAuditPackWith does.
+ *
+ * `keys` null means the pack's own issuer_keys are used and the result says so
+ * (trust on first use). A supplied map — even an empty one — outranks them.
+ * `now` is the reader's clock, used to read a status statement's window.
+ */
+export async function verifyAuditPack(crypto, source, keys, now, opts = {}) {
+    const res = {
+        verdict: "UNREADABLE",
+        reason: "",
+        header: null,
+        footer: null,
+        records: 0,
+        revoked: 0,
+        notIncluded: 0,
+        failed: [],
+        logHead: "ABSENT",
+        logHeadKeyId: "",
+        keysFromPack: false,
+        digest: "",
+        statusChecked: 0,
+        statusRevoked: 0,
+        revokedIds: [],
+        footerStatement: "UNSIGNED",
+        footerKeyId: "",
+        run: null,
+        runResult: "",
+        runInclusion: "",
+        runSubjects: [],
+        runRecordIds: [],
+        runMislabelled: 0,
+    };
+    let keySet = keys;
+    let headSize = null;
+    const bytes = typeof source === "string" ? encoder.encode(source) : source;
+    let scan;
+    try {
+        scan = await scanAuditPack(crypto, bytes, {
+            async onHeader(h) {
+                if (keySet === null) {
+                    if (h.issuerKeys.length === 0) {
+                        throw new Error("audit pack: the pack carries no issuer keys and none were supplied");
+                    }
+                    try {
+                        keySet = await keysFromEntries(crypto, h.issuerKeys);
+                    }
+                    catch (e) {
+                        throw new Error(`audit pack: issuer_keys: ${message(e)}`);
+                    }
+                    res.keysFromPack = true;
+                }
+                if (h.logHead !== undefined) {
+                    const { result, keyId } = await verifyLogHead(crypto, h.logHead, keySet);
+                    res.logHead = result;
+                    res.logHeadKeyId = keyId;
+                    if (result === "VALID")
+                        headSize = h.logHead.tree_size;
+                }
+                if (h.runRecord !== undefined) {
+                    let rec;
+                    try {
+                        rec = parseRunRecordDocument(h.runRecord);
+                    }
+                    catch (e) {
+                        if (!(e instanceof VerificationError))
+                            throw e;
+                        throw new Error(`audit pack: run_record: ${e.message}`);
+                    }
+                    res.run = rec;
+                    res.runResult = await verifyRunRecord(crypto, rec, keySet);
+                    res.runInclusion = "NOT_INCLUDED";
+                    const key = keySet.get(rec.issuer.keyId);
+                    if (key !== undefined)
+                        res.runInclusion = await verifyRunRecordInclusion(crypto, rec, key);
+                }
+            },
+            async onRecord(index, line) {
+                // The scanner delivers the header before any record, and onHeader
+                // either resolved a key set or threw.
+                if (keySet === null)
+                    throw new Error("audit pack: record before header");
+                res.records = index;
+                const f = await verifyRecord(crypto, index, line, keySet, headSize, now, opts, res);
+                if (f !== null)
+                    res.failed.push(f);
+            },
+        });
+    }
+    catch (e) {
+        res.verdict = "UNREADABLE";
+        res.reason = message(e);
+        return res;
+    }
+    res.header = scan.header;
+    res.footer = scan.footer;
+    res.digest = scan.digest;
+    const findings = [];
+    if (res.failed.length > 0)
+        findings.push(`${res.failed.length} of ${res.records} records refused`);
+    if (res.run !== null) {
+        if (res.runResult !== "VALID") {
+            findings.push(`the run record does not verify: ${res.runResult}`);
+        }
+        else if (res.runInclusion !== "VALID" && res.runInclusion !== "NOT_INCLUDED") {
+            findings.push(`the run record's inclusion proof does not verify: ${res.runInclusion}`);
+        }
+        const filtered = scan.header.filters.runId;
+        if (filtered !== null && filtered !== res.run.runId) {
+            findings.push(`the run record is for run ${res.run.runId}, not the run the pack was filtered by`);
+        }
+    }
+    if (res.logHead === "INVALID_SIGNATURE") {
+        findings.push("the log head's signature does not verify under any supplied key");
+    }
+    else if (res.logHead === "UNREADABLE") {
+        findings.push("the log head cannot be read");
+    }
+    let invalid = findings.length > 0;
+    const incomplete = [];
+    if (scan.footer === null) {
+        incomplete.push("no footer: the page is truncated");
+    }
+    else if (scan.footer.recordCount !== scan.records) {
+        incomplete.push(`the footer says ${scan.footer.recordCount} records and the file carries ${scan.records}`);
+    }
+    else if (scan.footer.recordsSha256 !== scan.digest) {
+        incomplete.push("the record lines do not reproduce the footer's records_sha256");
+    }
+    // The footer's own statement, checked whether or not the lines agree with
+    // it: a signed footer the lines contradict is still evidence of what the
+    // issuer attested, and a reader is told both things.
+    if (scan.footer?.signed !== undefined) {
+        // onHeader resolved a key set or threw, and the scanner delivered the
+        // header before the footer.
+        const { result, keyId } = await verifyFooter(crypto, scan.header, scan.footer, keySet);
+        res.footerStatement = result;
+        res.footerKeyId = keyId;
+        if (result !== "VALID") {
+            findings.push(`the footer's signature does not verify: ${result}`);
+            invalid = true;
+        }
+    }
+    findings.push(...incomplete);
+    res.verdict = invalid ? "INVALID" : findings.length > 0 ? "INCOMPLETE" : "VERIFIED";
+    res.reason = findings.join("; ");
+    return res;
+}
+// ---------------------------------------------------------------------------
+// The signed footer (core/auditpack_footer.go)
+// ---------------------------------------------------------------------------
+/** The canonical signing payload of a footer statement. Optional fields are
+ * omitted rather than encoded as null, as in every other statement: a page
+ * with no filter must sign the same bytes a verifier rebuilds from it. Mirrors
+ * core.BuildAuditPackFooterPayload. */
+export function buildAuditPackFooterPayload(s) {
+    const payload = { payload_type: PAYLOAD_TYPE_AUDIT_PACK_FOOTER };
+    if (s.cursor !== null)
+        payload.cursor = s.cursor;
+    if (s.filters.issuedAfter !== null)
+        payload.issued_after = s.filters.issuedAfter;
+    if (s.filters.issuedBefore !== null)
+        payload.issued_before = s.filters.issuedBefore;
+    if (s.nextCursor !== null)
+        payload.next_cursor = s.nextCursor;
+    payload.record_count = s.recordCount;
+    payload.records_sha256 = bytesToHex(s.recordsSha256);
+    if (s.filters.runId !== null)
+        payload.run_id = s.filters.runId;
+    payload.statement_issued_at = formatTimestamp(s.statementIssuedAt, "statement_issued_at");
+    if (s.filters.status !== null)
+        payload.status = s.filters.status;
+    payload.sth_root_hash = bytesToHex(s.sthRootHash);
+    payload.sth_tree_size = s.sthTreeSize;
+    return canonicalJson(payload);
+}
+/** Checks a footer statement against the reader's keys, in the order every
+ * other verifier uses: the key's authority first, then the signature. Mirrors
+ * core.VerifyAuditPackFooter. A statement whose payload cannot be built is
+ * INVALID_SIGNATURE, as there. */
+export async function verifyAuditPackFooter(crypto, s, keys) {
+    const key = keys.get(s.keyId);
+    if (key === undefined)
+        return "UNKNOWN_KEY";
+    let anchor;
+    let payload;
+    try {
+        anchor = Math.floor(Date.parse(formatTimestamp(s.statementIssuedAt, "statement_issued_at")) / 1000);
+        payload = buildAuditPackFooterPayload(s);
+    }
+    catch (e) {
+        if (e instanceof VerificationError)
+            return "INVALID_SIGNATURE";
+        throw e;
+    }
+    if (!keyIsUsable(evaluateKey(key, anchor)))
+        return "KEY_UNUSABLE";
+    if (!(await crypto.ed25519Verify(key.keyBytes, payload, s.signature)))
+        return "INVALID_SIGNATURE";
+    return "VALID";
+}
+/** Rebuilds the signed statement from a page's header and footer, as
+ * core.AuditPackFooter.Statement does. Throws for an unsigned footer, and for
+ * signed fields that do not parse, rather than returning a statement that
+ * would verify against nothing. */
+export function auditPackFooterStatement(header, footer) {
+    const signed = footer.signed;
+    if (signed === undefined)
+        throw new Error("audit pack: the footer carries no signed statement");
+    if (!HEX_32.test(footer.recordsSha256))
+        throw new Error("audit pack: footer: records_sha256 is not 32 bytes of hex");
+    if (!HEX_32.test(signed.sth_root_hash))
+        throw new Error("audit pack: footer: sth_root_hash is not 32 bytes of hex");
+    if (!HEX_64.test(signed.signature))
+        throw new Error("audit pack: footer: signature is not 64 bytes of hex");
+    return {
+        filters: header.filters,
+        cursor: header.cursor,
+        nextCursor: footer.nextCursor,
+        recordCount: footer.recordCount,
+        recordsSha256: hexToBytes(footer.recordsSha256),
+        sthTreeSize: signed.sth_tree_size,
+        sthRootHash: hexToBytes(signed.sth_root_hash),
+        statementIssuedAt: formatTimestamp(signed.statement_issued_at, "statement_issued_at"),
+        signature: hexToBytes(signed.signature),
+        keyId: signed.key_id,
+    };
+}
+/** Mirrors core.verifyAuditPackFooter. Signed fields that do not parse are
+ * INVALID_SIGNATURE: the issuer wrote something a reader cannot check, which
+ * is a refusal, not an absence. After a VALID signature the signed anchor must
+ * be the header's own log head, when the header has a readable one: a footer
+ * signed against a different head is a footer for a different page. */
+async function verifyFooter(crypto, header, footer, keys) {
+    let stmt;
+    try {
+        stmt = auditPackFooterStatement(header, footer);
+    }
+    catch (e) {
+        if (e instanceof Error)
+            return { result: "INVALID_SIGNATURE", keyId: "" };
+        throw e;
+    }
+    const result = await verifyAuditPackFooter(crypto, stmt, keys);
+    if (result !== "VALID")
+        return { result, keyId: "" };
+    const head = header.logHead;
+    if (head !== undefined && logHeadReadable(head)) {
+        if (head.tree_size !== stmt.sthTreeSize || head.root_hash.toLowerCase() !== bytesToHex(stmt.sthRootHash)) {
+            return { result: "INVALID_SIGNATURE", keyId: "" };
+        }
+    }
+    return { result: "VALID", keyId: stmt.keyId };
+}
+/** Whether Go's SignedTreeHeadDocument.SignedTreeHead would parse the head:
+ * the hex lengths and an RFC 3339 timestamp. An unreadable head cannot anchor
+ * anything, so the footer is not compared with it. */
+function logHeadReadable(head) {
+    if (!HEX_32.test(head.root_hash) || !HEX_64.test(head.signature))
+        return false;
+    try {
+        formatTimestamp(head.timestamp, "log_head.timestamp");
+        return true;
+    }
+    catch (e) {
+        if (e instanceof VerificationError)
+            return false;
+        throw e;
+    }
+}
+/** One record through the single-record verifier; why it was refused, or null.
+ * Mirrors core.verifyAuditPackRecord, including what is counted before a
+ * refusal: the REVOKED label, a statement obtained, a proof absent. */
+async function verifyRecord(crypto, index, line, keys, headSize, now, opts, res) {
+    const refused = (certificateId, offline, transparency, reason) => ({ index, certificateId, offline, transparency, reason });
+    // The scanner already parsed this line once, to classify it; parsing again
+    // here keeps the verifier's reading of the envelope beside the checks that
+    // use it, as Go's does. The line is what the scanner accepted, so this
+    // cannot fail on shape — only a null line yields an empty envelope.
+    const rec = (JSON.parse(decoder.decode(line)) ?? {});
+    const envelopeId = typeof rec.id === "string" ? rec.id : "";
+    if (rec.status === "REVOKED")
+        res.revoked++;
+    if (rec.certificate === undefined || rec.certificate === null) {
+        return refused(envelopeId, "", "", "the record carries no certificate document");
+    }
+    if (!isObject(rec.certificate)) {
+        return refused(envelopeId, "", "", "unreadable certificate document: certificate is not a JSON object");
+    }
+    const cert = rec.certificate;
+    const id = typeof cert.certificate_id === "string" ? cert.certificate_id : envelopeId;
+    if (res.run !== null) {
+        // What this page contributes to the run's roots, taken before the record
+        // is judged: a refused record was still presented as the run's, and the
+        // roots are what say whether it belongs. Go reads these fields at parse,
+        // so a record they cannot be read from is unreadable there too.
+        let subjectHash;
+        let canonicalId;
+        let runId;
+        try {
+            const subject = cert.subject;
+            if (!isObject(subject))
+                throw new VerificationError("subject is not an object");
+            subjectHash = decodeFixed(subject.identifier_hash, "subject.identifier_hash", 32);
+            canonicalId = formatUuid(parseUuid(id));
+            if (cert.run_id != null) {
+                if (typeof cert.run_id !== "string")
+                    throw new VerificationError("run_id is not a string");
+                runId = formatUuid(parseUuid(cert.run_id));
+            }
+        }
+        catch (e) {
+            if (!(e instanceof VerificationError) && !(e instanceof TypeError))
+                throw e;
+            return refused(id, "", "", `unreadable certificate document: ${e.message}`);
+        }
+        res.runSubjects.push(subjectHash);
+        res.runRecordIds.push(canonicalId);
+        const version = typeof cert.certificate_format_version === "string" ? cert.certificate_format_version : "";
+        const mislabelled = (runId !== undefined && runId !== res.run.runId) ||
+            (runId === undefined && signatureCoversRunId(version));
+        if (mislabelled) {
+            res.runMislabelled++;
+            return refused(id, "", "", "the record's signed run_id does not name the pack's run");
+        }
+    }
+    let status = null;
+    if (opts.status !== undefined) {
+        status = await opts.status(id);
+        if (status !== null)
+            res.statusChecked++;
+    }
+    let offline;
+    try {
+        offline = await offlineVerdictOf(crypto, cert, keys, status, now);
+    }
+    catch (e) {
+        if (!(e instanceof VerificationError))
+            throw e;
+        return refused(id, "", "", `unreadable certificate document: ${e.message}`);
+    }
+    if (offline === "REVOKED" && status !== null) {
+        // Evidenced revocation: a fresh statement, verified under the reader's
+        // keys, said so. Recorded, and the record otherwise stands on the verdict
+        // it would have had without the statement.
+        res.statusRevoked++;
+        res.revokedIds.push(id);
+        try {
+            offline = await offlineVerdictOf(crypto, cert, keys, null, now);
+        }
+        catch (e) {
+            if (!(e instanceof VerificationError))
+                throw e;
+            return refused(id, "", "", `unreadable certificate document: ${e.message}`);
+        }
+    }
+    const issuer = cert.issuer;
+    const issuerKeyId = isObject(issuer) && typeof issuer.key_id === "string" ? issuer.key_id : "";
+    let transparency = "NOT_INCLUDED";
+    if (keys.has(issuerKeyId)) {
+        try {
+            const t = await verifyTransparency(crypto, cert, keys);
+            transparency = t === "INCLUDED" ? "VALID" : "NOT_INCLUDED";
+        }
+        catch (e) {
+            if (!(e instanceof VerificationError))
+                throw e;
+            transparency = transparencyVerdictName(e);
+        }
+    }
+    if (transparency === "NOT_INCLUDED")
+        res.notIncluded++;
+    if (!recordAccepted(offline, transparency)) {
+        return refused(id, offline, transparency, `${offline} / transparency ${transparency}`);
+    }
+    const includedAt = treeSizeOf(cert);
+    if (headSize !== null && includedAt !== null && includedAt > headSize) {
+        return refused(id, offline, transparency, `included at tree size ${includedAt}, past the pack's log head at ${headSize}`);
+    }
+    return null;
+}
+/** The single-record verdict under Go's name. Throws the VerificationError
+ * back when it is not one Go has a verdict for — a document this SDK could
+ * not read. */
+async function offlineVerdictOf(crypto, cert, keys, status, now) {
+    try {
+        return await verifyCertificateWithStatus(crypto, cert, keys, status, now);
+    }
+    catch (e) {
+        if (!(e instanceof VerificationError))
+            throw e;
+        const verdict = offlineVerdict(e);
+        if (verdict === null)
+            throw e;
+        return verdict;
+    }
+}
+/** The signed tree size the record's proof sits at; null when it carries no
+ * proof. By the time this is read the proof has verified, so the field is the
+ * one the signature covers. */
+function treeSizeOf(cert) {
+    const t = cert.transparency;
+    if (!isObject(t))
+        return null;
+    const sth = t.signed_tree_head;
+    if (!isObject(sth) || typeof sth.tree_size !== "number")
+        return null;
+    return sth.tree_size;
+}
+/** Orders a set of pages by their cursors and says whether they are one
+ * complete answer: exactly one first page, each next_cursor met by a page that
+ * resumes from it, every file used, and a last page with no next cursor. The
+ * returned order is as far as the chain could be followed. */
+export function chainAuditPackPages(pages) {
+    const byCursor = new Map();
+    const firsts = [];
+    for (const p of pages) {
+        if (p.cursor === null) {
+            firsts.push(p);
+            continue;
+        }
+        const list = byCursor.get(p.cursor);
+        if (list === undefined)
+            byCursor.set(p.cursor, [p]);
+        else
+            list.push(p);
+    }
+    if (firsts.length === 0) {
+        return { order: [], complete: false, reason: "no first page: every file resumes from a cursor" };
+    }
+    if (firsts.length > 1) {
+        return {
+            order: [],
+            complete: false,
+            reason: `${firsts.length} files are first pages (${firsts[0].name} and ${firsts[1].name}); a query has one`,
+        };
+    }
+    const order = [];
+    const used = new Set();
+    let cur = firsts[0];
+    for (;;) {
+        order.push(cur);
+        used.add(cur.name);
+        if (cur.nextCursor === null)
+            break;
+        const next = byCursor.get(cur.nextCursor) ?? [];
+        if (next.length === 0) {
+            return {
+                order, complete: false,
+                reason: `${cur.name} says more pages follow and no file resumes from its cursor`,
+            };
+        }
+        if (next.length > 1) {
+            return {
+                order, complete: false,
+                reason: `${next.length} files resume from the same cursor (${next[0].name} and ${next[1].name})`,
+            };
+        }
+        if (used.has(next[0].name)) {
+            return { order, complete: false, reason: `the cursors loop back to ${next[0].name}` };
+        }
+        cur = next[0];
+    }
+    for (const p of pages) {
+        if (!used.has(p.name))
+            return { order, complete: false, reason: `${p.name} is not part of the chain` };
+    }
+    return { order, complete: true, reason: "" };
+}
+//# sourceMappingURL=audit-pack.js.map