@intyga/verify 0.0.0-bootstrap.0 → 1.0.0

package/dist/ledger-leaf.js

@@ -0,0 +1,44 @@
+import { hashLeaf } from "./ledger-merkle.js";
+/**
+ * JCS (RFC 8785) serialization of the `metadata` value — every object key sorted recursively by
+ * UTF-16 code unit. DEWP §4.2 requires the metadata element to be a *canonical* string, so an equal
+ * metadata object hashes identically regardless of the producer's key insertion order or language
+ * (JS/Go/Rust/Python). Do NOT replace with plain JSON.stringify — that reintroduces order dependence.
+ */
+function jcsStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(jcsStringify).join(",")}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${jcsStringify(obj[k])}`).join(",")}}`;
+}
+/** The 18-field ordered array that gets JSON-stringified into the leaf preimage. Keep in lockstep
+ *  with the producer's `leafHash` (packages/db/src/checkpoint.ts). */
+export function canonicalPreimage(row) {
+    return JSON.stringify([
+        row.seq,
+        row.createdAt,
+        row.event,
+        row.outcome,
+        row.detail,
+        jcsStringify(row.metadata ?? null),
+        row.signerDid,
+        row.signerPublicKey,
+        row.signedPayload,
+        row.signature,
+        row.sigAlg,
+        row.isBillable,
+        row.tenantId,
+        row.actorNodeId,
+        row.subjectNodeId,
+        row.edgeId,
+        row.challengeId,
+        row.tenantSeq ?? null,
+    ]);
+}
+/** Domain-separated leaf digest over the full event content. */
+export function leafHash(row) {
+    return hashLeaf(canonicalPreimage(row));
+}

package/dist/ledger-merkle.d.ts

@@ -0,0 +1,46 @@
+export declare function sha256Hex(s: string): string;
+export declare const LEAF_TAG = 0;
+export declare const NODE_TAG = 1;
+export declare const EMPTY_TAG = 2;
+/** Domain-separated leaf digest: sha256(0x00 || UTF8(preimage)). */
+export declare function hashLeaf(data: string): string;
+/** Domain-separated node: sha256(0x01 || rawBytes(left) || rawBytes(right)). Order encodes position — never sort. */
+export declare function hashPair(left: string, right: string): string;
+/** Empty-tree root (DEWP §5.1.1): sha256(0x02). */
+export declare function emptyRoot(): string;
+/** Merkle root over ordered leaves (duplicate-last on odd levels). Empty tree ⇒ sha256(0x02). */
+export declare function merkleRoot(leaves: string[]): string;
+/**
+ * One step on the path from a leaf to the root (DEWP §5.1.6): the SIBLING's hash and the side the
+ * sibling sits on relative to the running node. Ordered leaf → root.
+ */
+export interface ProofStep {
+    siblingHash: string;
+    siblingPosition: "LEFT" | "RIGHT";
+}
+/**
+ * Inclusion proof for the leaf at `index` — the sibling hashes needed to recompute the root.
+ * The producer emits these; the verifier only needs `verifyMerkleProof`. Included here so the same
+ * file can generate test vectors and so auditors can reproduce a proof from raw leaves if they wish.
+ */
+export declare function merkleProof(leaves: string[], index: number): ProofStep[];
+/**
+ * The audit-path length for `index` in a duplicate-last tree of `leafCount` leaves.
+ * One sibling per level, and the tree has ceil(log2(n)) levels above the leaves.
+ */
+export declare function expectedPathLength(leafCount: number): number;
+/**
+ * Position of the leaf a proof is for, and how many leaves its tree had. Supplying these turns an
+ * "is there SOME path from this leaf to this root" check into "is this leaf at this position".
+ *
+ * REQUIRED, per DEWP §3 invariant 3 ("The bounds are REQUIRED, not advisory") and §11.1. This was
+ * an optional parameter, which made the unbounded check reachable by omission from outside this
+ * package — the one place it must not be reachable, since external relying parties are exactly who
+ * this package exists for.
+ */
+export interface ProofBounds {
+    index: number;
+    leafCount: number;
+}
+/** Recompute the root from a leaf + its proof and compare. This is what a third party runs. */
+export declare function verifyMerkleProof(leaf: string, proof: ProofStep[], root: string, bounds: ProofBounds): boolean;

package/dist/ledger-merkle.js

@@ -0,0 +1,183 @@
+import crypto from "node:crypto";
+// Pure Merkle primitives — zero dependencies beyond node:crypto. This file is the trust root of the
+// verifier: an auditor should be able to read it end to end and be convinced. It is a byte-for-byte
+// port of the tree construction used to build Intyga's two-tier witness anchor
+// (per-event leaves → block roots → daily root). If this and the producer ever disagree, proofs fail
+// closed (verification returns false), never open.
+export function sha256Hex(s) {
+    return crypto.createHash("sha256").update(s).digest("hex");
+}
+// DEWP domain separation (docs/DEWP.md §4.4): leaves, interior nodes, and the empty root are hashed
+// under DISTINCT one-byte prefixes so an interior-node hash can never be reinterpreted as a leaf
+// (blocks second-preimage / proof malleability where a subtree root is passed off as a leaf).
+// 0x00 = leaf, 0x01 = node, 0x02 = empty root. Node children are HEX-DECODED to their raw 32 bytes
+// before hashing (NOT concatenated as hex text). Must stay byte-identical to the @intyga/db producer.
+export const LEAF_TAG = 0x00;
+export const NODE_TAG = 0x01;
+export const EMPTY_TAG = 0x02;
+/** Domain-separated leaf digest: sha256(0x00 || UTF8(preimage)). */
+export function hashLeaf(data) {
+    return crypto
+        .createHash("sha256")
+        .update(Buffer.from([LEAF_TAG]))
+        .update(Buffer.from(data, "utf8"))
+        .digest("hex");
+}
+/**
+ * Exactly 64 LOWERCASE hex characters (DEWP §4.4). Verification inputs must pass this before they
+ * reach `hashPair`, because `Buffer.from(s, "hex")` is lenient in two ways that both break the
+ * proof: it accepts uppercase, and it silently stops at the first non-hex character instead of
+ * failing. So distinct proof strings collapse onto the same bytes.
+ *
+ * That is not cosmetic — it defeats the padding check in `verifyMerkleProof`. That check rejects a
+ * step whose sibling equals the running node anywhere but the unpaired end of an odd level, which is
+ * what makes a path to a never-existent index fail. The comparison is on the STRING, so uppercasing
+ * a sibling makes `selfPaired` false while `hashPair` still decodes it to the identical 32 bytes:
+ * the padding forgery recomputes the genuine root and verifies. Reproduced against the real 3-leaf
+ * tree before this gate existed. The Go, Rust, Python and Java ports already gate on this; the
+ * reference implementation did not, so it was the only port accepting the forgery.
+ */
+function isHash64(s) {
+    if (typeof s !== "string" || s.length !== 64)
+        return false;
+    for (let i = 0; i < 64; i++) {
+        const c = s.charCodeAt(i);
+        const isDigit = c >= 0x30 && c <= 0x39;
+        const isLowerAf = c >= 0x61 && c <= 0x66;
+        if (!isDigit && !isLowerAf)
+            return false;
+    }
+    return true;
+}
+// Checked indexed read. The loops below keep indices in range by construction; if that invariant
+// ever breaks, throwing beats fabricating a hash — a wrong tree must never verify.
+function at(level, i) {
+    const v = level[i];
+    if (v === undefined)
+        throw new Error("merkle: index out of range");
+    return v;
+}
+/** Domain-separated node: sha256(0x01 || rawBytes(left) || rawBytes(right)). Order encodes position — never sort. */
+export function hashPair(left, right) {
+    return crypto
+        .createHash("sha256")
+        .update(Buffer.from([NODE_TAG]))
+        .update(Buffer.from(left, "hex"))
+        .update(Buffer.from(right, "hex"))
+        .digest("hex");
+}
+/** Empty-tree root (DEWP §5.1.1): sha256(0x02). */
+export function emptyRoot() {
+    return crypto
+        .createHash("sha256")
+        .update(Buffer.from([EMPTY_TAG]))
+        .digest("hex");
+}
+/** Merkle root over ordered leaves (duplicate-last on odd levels). Empty tree ⇒ sha256(0x02). */
+export function merkleRoot(leaves) {
+    if (leaves.length === 0)
+        return emptyRoot();
+    let level = leaves;
+    while (level.length > 1) {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2) {
+            const left = at(level, i);
+            next.push(hashPair(left, level[i + 1] ?? left));
+        }
+        level = next;
+    }
+    return at(level, 0);
+}
+/**
+ * Inclusion proof for the leaf at `index` — the sibling hashes needed to recompute the root.
+ * The producer emits these; the verifier only needs `verifyMerkleProof`. Included here so the same
+ * file can generate test vectors and so auditors can reproduce a proof from raw leaves if they wish.
+ */
+export function merkleProof(leaves, index) {
+    if (index < 0 || index >= leaves.length)
+        throw new Error("merkleProof: index out of range");
+    const proof = [];
+    let level = leaves;
+    let idx = index;
+    while (level.length > 1) {
+        const isRightChild = idx % 2 === 1;
+        const siblingIdx = isRightChild ? idx - 1 : idx + 1;
+        // duplicate-last: an unpaired right node is hashed against itself.
+        const sibling = level[siblingIdx] ?? at(level, idx);
+        // If the running node is the RIGHT child, its sibling sits on the LEFT, and vice versa.
+        proof.push({ siblingHash: sibling, siblingPosition: isRightChild ? "LEFT" : "RIGHT" });
+        const next = [];
+        for (let i = 0; i < level.length; i += 2) {
+            const left = at(level, i);
+            next.push(hashPair(left, level[i + 1] ?? left));
+        }
+        level = next;
+        idx = Math.floor(idx / 2);
+    }
+    return proof;
+}
+/**
+ * The audit-path length for `index` in a duplicate-last tree of `leafCount` leaves.
+ * One sibling per level, and the tree has ceil(log2(n)) levels above the leaves.
+ */
+export function expectedPathLength(leafCount) {
+    return leafCount <= 1 ? 0 : Math.ceil(Math.log2(leafCount));
+}
+/** Recompute the root from a leaf + its proof and compare. This is what a third party runs. */
+export function verifyMerkleProof(leaf, proof, root, bounds) {
+    // Bounds are what make this a proof of membership rather than a proof that A path exists.
+    //
+    // This tree pads an unpaired trailing node by hashing it against ITSELF (DEWP §5.1.1 rule 3), so
+    // merkleRoot([a,b,c]) === merkleRoot([a,b,c,c]) and a path for the nonexistent index 3 recomputes
+    // the 3-leaf root exactly. Without a length and index there is nothing to reject it with, which
+    // falsifies DEWP §17.1's claim that forging an inclusion path needs a SHA-256 second preimage.
+    // DEWP §11.1 states outright that an implementation stopping at root recomputation is
+    // non-conformant, so this is a rejection, never a skipped check.
+    //
+    // `bounds` is required for every TS caller, but this package is the dependency-free, plain-JS-
+    // callable trust anchor (see packages/verify/README.md) — nothing enforces that for a legacy
+    // 3-argument call from an untyped consumer. Refusing here keeps this a boolean predicate for that
+    // caller instead of a thrown TypeError.
+    if (!bounds)
+        return false;
+    // Canonical hex FIRST: the self-pairing check below compares sibling to node as STRINGS, so an
+    // uppercased sibling slips past it while hashing to the identical bytes (see `isHash64`). Every
+    // hash that reaches `hashPair` is gated here and at each step.
+    if (!isHash64(leaf) || !isHash64(root))
+        return false;
+    const { index, leafCount } = bounds;
+    if (!Number.isInteger(index) || !Number.isInteger(leafCount))
+        return false;
+    if (leafCount < 1 || index < 0 || index >= leafCount)
+        return false;
+    if (proof.length !== expectedPathLength(leafCount))
+        return false;
+    // Each sibling's side follows from the index; letting the prover choose it freely would hand
+    // back the flexibility the length check just removed.
+    //
+    // The self-pairing check is what actually closes the padding forgery. `leafCount` comes from the
+    // proof, so a prover can simply inflate it: claiming leafCount 4 on a 3-leaf tree makes index 3
+    // "in range" and the path length correct, and the duplicate-last root is identical — so range
+    // and length alone still accept it (verified). But padding is observable: a node hashed against
+    // ITSELF only legitimately occurs at the unpaired END of an odd level. A step whose sibling
+    // equals the running node anywhere else is the signature of an index pointing into padding.
+    let idx = index;
+    let levelSize = leafCount;
+    let node = leaf;
+    for (const step of proof) {
+        if (!isHash64(step.siblingHash))
+            return false;
+        const expectedSide = idx % 2 === 1 ? "LEFT" : "RIGHT";
+        if (step.siblingPosition !== expectedSide)
+            return false;
+        const selfPaired = step.siblingHash === node;
+        const legitimatelyUnpaired = idx === levelSize - 1 && levelSize % 2 === 1;
+        if (selfPaired && !legitimatelyUnpaired)
+            return false;
+        node =
+            step.siblingPosition === "LEFT" ? hashPair(step.siblingHash, node) : hashPair(node, step.siblingHash);
+        idx = Math.floor(idx / 2);
+        levelSize = Math.ceil(levelSize / 2);
+    }
+    return node === root;
+}

package/dist/ledger-proof.d.ts

@@ -0,0 +1,40 @@
+import { type ProofStep } from "./ledger-merkle.js";
+export interface InclusionProof {
+    seq: string;
+    leaf: string;
+    blockIndex: string;
+    blockRoot: string;
+    blockProof: ProofStep[];
+    /** Position of this event's leaf within its block, and how many leaves that block had. */
+    leafIndex: number;
+    blockLeafCount: number;
+    checkpointId: string | null;
+    checkpointRoot: string | null;
+    checkpointProof: ProofStep[];
+    /** Position of the block root within the daily tree, and that tree's leaf count. */
+    checkpointLeafIndex: number;
+    checkpointLeafCount: number;
+    anchorRef: string | null;
+    /** Producer claim: a self publication receipt exists. Commitment only — NOT independence. */
+    anchored: boolean;
+    /**
+     * Producer claim: the producer says a §5.3 external anchor quorum (distinct INDEPENDENT issuers >=
+     * its configured requirement) exists for this checkpoint. Absent on bundles exported before the
+     * field shipped. Display/triage only — independence is established by THIS verifier's own anchor
+     * quorum evaluation (`anchorVerified`), never by trusting the flag.
+     */
+    externallyAnchored?: boolean;
+    /**
+     * The quorum size the producer evaluated that claim against. Absent on bundles exported before it
+     * shipped. Without it the boolean cannot be read: a 1-of-1 deployment and a 2-of-N deployment both
+     * publish `true`. Still a producer claim — it says what the producer required, not what happened.
+     */
+    externallyAnchoredRequired?: number;
+}
+/**
+ * Verify a two-hop inclusion proof against a KNOWN daily root (event → block → day).
+ * Pass a daily root you obtained independently — recorded earlier, or from the published roots file —
+ * NOT proof.checkpointRoot: trusting the root shipped inside the proof would let a forged bundle vouch
+ * for itself. (An external anchor cannot supply the root; it holds only a digest committing to it.)
+ */
+export declare function verifyInclusionProof(proof: InclusionProof, dailyRoot: string): boolean;

package/dist/ledger-proof.js

@@ -0,0 +1,29 @@
+import { hashLeaf, verifyMerkleProof } from "./ledger-merkle.js";
+/**
+ * Verify a two-hop inclusion proof against a KNOWN daily root (event → block → day).
+ * Pass a daily root you obtained independently — recorded earlier, or from the published roots file —
+ * NOT proof.checkpointRoot: trusting the root shipped inside the proof would let a forged bundle vouch
+ * for itself. (An external anchor cannot supply the root; it holds only a digest committing to it.)
+ */
+export function verifyInclusionProof(proof, dailyRoot) {
+    // Position is REQUIRED, and its absence is a rejection rather than a skipped check. This tree pads
+    // an unpaired trailing node against itself, so without an index and a leaf count a path to a leaf
+    // that was never in the tree recomputes the real root (verified: a proof for index 3 verifies
+    // against a 3-leaf root). A proof that cannot say where its leaf sits does not establish inclusion.
+    if (!Number.isInteger(proof.leafIndex) ||
+        !Number.isInteger(proof.blockLeafCount) ||
+        !Number.isInteger(proof.checkpointLeafIndex) ||
+        !Number.isInteger(proof.checkpointLeafCount)) {
+        return false;
+    }
+    if (!verifyMerkleProof(proof.leaf, proof.blockProof, proof.blockRoot, {
+        index: proof.leafIndex,
+        leafCount: proof.blockLeafCount,
+    })) {
+        return false;
+    }
+    return verifyMerkleProof(hashLeaf(proof.blockRoot), proof.checkpointProof, dailyRoot, {
+        index: proof.checkpointLeafIndex,
+        leafCount: proof.checkpointLeafCount,
+    });
+}

package/dist/ledger-rekor.d.ts

@@ -0,0 +1,49 @@
+import { type AnchorInput } from "./ledger-anchor.js";
+/** The parts of a Rekor log entry we need. Mirrors what packages/db persists as `evidence`. */
+export interface RekorEvidence {
+    uuid?: string;
+    /** Base64 of the canonicalized entry Rekor stored. The SET signs this — without it, nothing. */
+    body?: string;
+    logID?: string;
+    logIndex?: number;
+    integratedTime?: number;
+    verification?: {
+        signedEntryTimestamp?: string;
+        inclusionProof?: {
+            logIndex?: number;
+            rootHash?: string;
+            treeSize?: number;
+            hashes?: string[];
+            checkpoint?: string;
+        };
+    };
+}
+export interface RekorVerification {
+    ok: boolean;
+    reason?: string;
+    /** Rekor's log index for this entry — where a third party can retrieve it themselves. */
+    logIndex?: number;
+    logID?: string;
+    integratedTime?: number;
+}
+/**
+ * The hash Rekor was asked to bind the anchor signature to.
+ *
+ * MUST match the producer (packages/db/src/anchors/rekor.ts): `signAnchorDigest` signs the RAW
+ * 32-byte anchor digest, and the signature scheme applies SHA-256 to those bytes itself — so the
+ * value Rekor holds is SHA-256 OF the anchor digest, not the digest.
+ */
+export declare function rekorPayloadHashFor(anchor: AnchorInput): string;
+/**
+ * Verify a Rekor anchor: Rekor's signature over the entry, AND that the entry is about this root.
+ *
+ * `rekorPublicKey` is PEM or base64 SPKI for the log's key, supplied by the CALLER from its own
+ * configuration — never from the bundle, for the same reason approver keys are not read from a
+ * receipt. Sigstore publishes it via TUF; pin it at deploy time.
+ */
+export declare function verifyRekorAnchor(evidence: RekorEvidence, anchor: AnchorInput, rekorPublicKey: string, opts?: {
+    /** The producer's pinned Rekor submission key(s); see ExternalAnchorKeys.rekorSubmitterKeys. */
+    submitterKeys?: string[];
+}): RekorVerification;
+/** Parse a stored base64 evidence blob into a RekorEvidence, or null if it is not one. */
+export declare function parseRekorEvidence(evidenceB64: string | null | undefined): RekorEvidence | null;

package/dist/ledger-rekor.js

@@ -0,0 +1,187 @@
+// Sigstore Rekor transparency-log anchor verification.
+//
+// This is what turns an external anchor from "Intyga stored a blob it says came from Rekor" into
+// evidence. Before it existed, `anchorCheckpoints` recorded REKOR anchors with an EMPTY DEWP
+// signature and the export dropped their evidence entirely — so a REKOR anchor could not contribute
+// to a §5.3 quorum, and `AUDIT_ANCHOR_REQUIRED=2` was satisfiable only by anchors signed with
+// Intyga's own key. The independence guarantee never reached the verifier.
+//
+// Two things must hold, and BOTH matter:
+//
+//   1. Rekor really signed this entry — its Signed Entry Timestamp (SET) verifies under Rekor's
+//      public key, which the caller supplies from its own trust configuration.
+//   2. The entry is about THIS checkpoint — the logged hashedrekord binds the payload hash to
+//      SHA-256(anchorDigest) for the root being verified.
+//
+// Without (2) any valid Rekor entry — there are millions, all public — would "verify". That is the
+// same self-referential trap as verifying a receipt against the key inside it.
+import crypto from "node:crypto";
+import { anchorDigest } from "./ledger-anchor.js";
+/**
+ * RFC 8785 JCS over the SET payload.
+ *
+ * Rekor signs the canonicalized JSON of {body, integratedTime, logID, logIndex} — keys sorted, no
+ * whitespace. Reusing the ledger's own JCS habit rather than JSON.stringify with a hand-written key
+ * order, because the order IS the contract and hand-ordering is exactly how these drift.
+ */
+function setPayload(e) {
+    return JSON.stringify({
+        body: e.body,
+        integratedTime: e.integratedTime,
+        logID: e.logID,
+        logIndex: e.logIndex,
+    });
+}
+/** Decode the base64 `body` into a hashedrekord, or null if it is not one. */
+function decodeHashedRekord(bodyB64) {
+    try {
+        const decoded = JSON.parse(Buffer.from(bodyB64, "base64").toString("utf-8"));
+        return decoded && decoded.kind === "hashedrekord" ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The payload hash a hashedrekord attests to, lowercased, or null. */
+function hashedRekordPayloadHash(decoded) {
+    const hash = decoded.spec?.data?.hash;
+    if (hash?.algorithm !== "sha256" || typeof hash.value !== "string")
+        return null;
+    return hash.value.toLowerCase();
+}
+/** DER SPKI bytes of a PEM or base64 key, or null. */
+function spkiDer(key) {
+    try {
+        const obj = key.includes("BEGIN")
+            ? crypto.createPublicKey(key)
+            : crypto.createPublicKey({ key: Buffer.from(key, "base64"), format: "der", type: "spki" });
+        return obj.export({ format: "der", type: "spki" });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Was this entry submitted by a key the caller pinned, and does that key's signature cover the
+ * anchor digest? Rekor itself checks the signature at submission, but it accepts ANY key — so without
+ * this, anyone who can compute an anchor digest (it is built from public fields) can get it logged
+ * under a throwaway key. `publicKey.content` is base64 of the PEM, as hashedrekord requires.
+ */
+function submittedByPinnedKey(decoded, anchor, pinned) {
+    const content = decoded.spec?.signature?.publicKey?.content;
+    const sig = decoded.spec?.signature?.content;
+    if (typeof content !== "string" || typeof sig !== "string")
+        return false;
+    const submitted = spkiDer(Buffer.from(content, "base64").toString("utf-8"));
+    if (!submitted)
+        return false;
+    if (!pinned.some((k) => spkiDer(k)?.equals(submitted) === true))
+        return false;
+    try {
+        const key = crypto.createPublicKey({ key: submitted, format: "der", type: "spki" });
+        if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1")
+            return false;
+        const digest = anchorDigest(anchor);
+        const signature = Buffer.from(sig, "base64");
+        const verify = (dsaEncoding) => {
+            try {
+                return crypto.verify("sha256", digest, { key, dsaEncoding }, signature);
+            }
+            catch {
+                return false;
+            }
+        };
+        return (signature.length === 64 && verify("ieee-p1363")) || verify("der");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The hash Rekor was asked to bind the anchor signature to.
+ *
+ * MUST match the producer (packages/db/src/anchors/rekor.ts): `signAnchorDigest` signs the RAW
+ * 32-byte anchor digest, and the signature scheme applies SHA-256 to those bytes itself — so the
+ * value Rekor holds is SHA-256 OF the anchor digest, not the digest.
+ */
+export function rekorPayloadHashFor(anchor) {
+    return crypto.createHash("sha256").update(anchorDigest(anchor)).digest("hex");
+}
+/**
+ * Verify a Rekor anchor: Rekor's signature over the entry, AND that the entry is about this root.
+ *
+ * `rekorPublicKey` is PEM or base64 SPKI for the log's key, supplied by the CALLER from its own
+ * configuration — never from the bundle, for the same reason approver keys are not read from a
+ * receipt. Sigstore publishes it via TUF; pin it at deploy time.
+ */
+export function verifyRekorAnchor(evidence, anchor, rekorPublicKey, opts = {}) {
+    if (!evidence.body)
+        return { ok: false, reason: "rekor evidence carries no entry body" };
+    const set = evidence.verification?.signedEntryTimestamp;
+    if (!set)
+        return { ok: false, reason: "rekor evidence carries no signedEntryTimestamp (SET)" };
+    if (typeof evidence.logIndex !== "number" || typeof evidence.integratedTime !== "number") {
+        return { ok: false, reason: "rekor evidence is missing logIndex/integratedTime" };
+    }
+    // (2) first — cheap, and it is the check that stops an unrelated (but perfectly valid) public
+    // Rekor entry from being presented as evidence for this checkpoint.
+    const decoded = decodeHashedRekord(evidence.body);
+    const logged = decoded ? hashedRekordPayloadHash(decoded) : null;
+    if (!decoded || !logged)
+        return { ok: false, reason: "rekor entry body is not a readable hashedrekord" };
+    const expected = rekorPayloadHashFor(anchor);
+    if (logged !== expected) {
+        return {
+            ok: false,
+            reason: `rekor entry attests a different payload (logged ${logged.slice(0, 16)}…, expected ${expected.slice(0, 16)}…) — this entry is not about this checkpoint`,
+        };
+    }
+    // (2b) Who submitted it — only when the caller pinned the producer's key.
+    if (opts.submitterKeys &&
+        opts.submitterKeys.length > 0 &&
+        !submittedByPinnedKey(decoded, anchor, opts.submitterKeys)) {
+        return {
+            ok: false,
+            reason: "rekor entry was not submitted under a pinned producer key with a valid signature over this anchor",
+        };
+    }
+    // (1) Rekor's own signature over the entry.
+    try {
+        const keyObject = rekorPublicKey.includes("BEGIN")
+            ? crypto.createPublicKey(rekorPublicKey)
+            : crypto.createPublicKey({
+                key: Buffer.from(rekorPublicKey, "base64"),
+                format: "der",
+                type: "spki",
+            });
+        // Rekor's log key is ECDSA P-256; pin it rather than letting the key material choose the
+        // algorithm, exactly as verifyEcdsaP256 does for approver keys.
+        if (keyObject.asymmetricKeyType !== "ec" || keyObject.asymmetricKeyDetails?.namedCurve !== "prime256v1") {
+            return { ok: false, reason: "rekor public key is not an EC P-256 key" };
+        }
+        const verified = crypto.verify("sha256", Buffer.from(setPayload(evidence), "utf-8"), { key: keyObject, dsaEncoding: "der" }, Buffer.from(set, "base64"));
+        if (!verified)
+            return { ok: false, reason: "rekor SET does not verify under the supplied log key" };
+    }
+    catch (err) {
+        return { ok: false, reason: `rekor SET verification failed: ${err.message}` };
+    }
+    return {
+        ok: true,
+        logIndex: evidence.logIndex,
+        logID: evidence.logID,
+        integratedTime: evidence.integratedTime,
+    };
+}
+/** Parse a stored base64 evidence blob into a RekorEvidence, or null if it is not one. */
+export function parseRekorEvidence(evidenceB64) {
+    if (!evidenceB64)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(evidenceB64, "base64").toString("utf-8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/ledger-rfc3161.d.ts

@@ -0,0 +1,25 @@
+import { type SignedAnchor } from "./ledger-anchor.js";
+/** Caller-owned TSA trust. Never populate this from an evidence bundle. Requires OpenSSL 3. */
+export interface Rfc3161Trust {
+    caPem: string;
+    /** SHA-256 of the DER signer certificate, pinned specifically to this issuer. */
+    signerCertificateSha256: string;
+    /** Explicit choice: check caller-supplied offline CRLs, or make no revocation assertion. */
+    revocation: "crl" | "unchecked";
+    crlPem?: string;
+    untrustedPem?: string;
+    /** Certificate/CRL evaluation time, Unix seconds. Defaults to current time rounded up to the next second. */
+    verificationTime?: number;
+    opensslPath?: string;
+}
+export interface Rfc3161Verification {
+    ok: boolean;
+    reason?: string;
+    /** Authenticated TSA time, Unix seconds (fractional seconds are discarded). */
+    genTime?: number;
+}
+/** Offline RFC 3161 verification. No shell, downloads, OS trust store, or implicit TSA trust. */
+export declare function verifyRfc3161Anchor(anchor: SignedAnchor, trust: Rfc3161Trust): Rfc3161Verification;
+export declare function verifyRfc3161Timestamp(evidence: string | null | undefined, digest: Uint8Array, trust: Rfc3161Trust, request?: Uint8Array): Rfc3161Verification;
+/** Asynchronous producer equivalent: identical checks without blocking the gateway event loop. */
+export declare function verifyRfc3161TimestampAsync(evidence: string | null | undefined, digest: Uint8Array, trust: Rfc3161Trust, request?: Uint8Array): Promise<Rfc3161Verification>;