@entpoind/verify 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.2.0
+
+Added
+- `verifyLedgerProof(proof, keys, { receipt?, witnessLog? })`: checks a write-once receipt-ledger proof offline. The leaf is
+  rebuilt from your receipt, the path shape and fold are checked against the signed batch root, and the root's signature is
+  verified with the regional key. No network unless you ask for it.
+- The public witness. A verified ledger proof reports `result.witness` (`absent`, `off`, `pending`, `logged` or `malformed`).
+  A `logged` witness is checked offline against the root (hashes, Ed25519ph signature by the root's own key, the copied
+  Rekor entry and its inclusion proof) and, with `witnessLog`, against the log itself. The witness never changes `result.ok`.
+- `verifyEd25519ph` (RFC 8032, SHA-512 prehash), `merkleLeafHash`, `verifyMerkleInclusionFromHash`, `ledgerRootMessage`,
+  `WITNESS_KIND`, `DEFAULT_REKOR_URL`.
+
+Unchanged
+- Receipt, artifact and bundle verification, the `verifyReceiptOnline` default key URL, and the zero-dependency, WebCrypto-only design.
+
+Notes
+- ESM only (`"type": "module"`), Node 20 or later. `require()` works from Node 22.12.
+
+## 0.1.0
+
+First release: `verifyReceipt`, `verifyReceiptOnline`, `verifyArtifact`, `verifyBundle`, `verifyMerkleInclusion`,
+`fetchToolsKeys`, `canonicalJcs`, `ed25519Supported`.

package/README.md

@@ -23,6 +23,8 @@ wrapper the API returns.
 
 ## Where it runs
 
+The package is ESM only (`import`), on Node 20 or later; `require()` works from Node 22.12. See `CHANGELOG.md` for what each version adds.
+
 Any runtime whose WebCrypto verifies Ed25519: Node 20 or later (tested on
 Node 22), Deno, Bun, Cloudflare Workers, and current browsers (Chrome and Edge
 137+, Firefox 129+, Safari 17+). Browsers expose WebCrypto only on secure
@@ -55,13 +57,17 @@ its `keys` to `verifyReceipt`.
 | `verifyArtifact(input, keys)` | Verify a standalone artifact envelope. |
 | `verifyBundle(input, keys)` | Signature, plus Merkle inclusion when anchored. |
 | `verifyMerkleInclusion(leaf, proof, root)` | Fold an inclusion proof locally. |
+| `verifyLedgerProof(proof, keys, { receipt?, witnessLog? })` | Verify a write-once-ledger proof and report its public witness (below). No network unless `witnessLog` is set. |
+| `verifyEd25519ph(publicKey, prehash, signature)` | The raw Ed25519ph (RFC 8032, SHA-512 prehash) check, as a boolean. |
 | `canonicalJcs(value)` | The RFC 8785 canonical string. |
 | `ed25519Supported()` | Whether this runtime can verify Ed25519. |
 | `verifySignature(key, message, signature)` | The raw Ed25519 check, as a boolean. |
 
 The `verify*` functions never throw on hostile input. `fetchToolsKeys` and
 `verifyReceiptOnline` throw when the keys cannot be fetched, so "could not
-check" is never reported as a verdict.
+check" is never reported as a verdict. The witness log check does not throw: an
+unreachable log is reported as `checked: false`, beside a ledger proof that has
+already been judged.
 
 ## Failure reasons
 
@@ -76,6 +82,126 @@ check" is never reported as a verdict.
 A bundle without an anchor verifies with `anchored: false`; that is a valid
 result, not a failure.
 
+## Ledger proofs
+
+A receipt that has been copied to the write-once ledger has a proof at
+`GET /api/v1/tools/receipts/{receiptId}/ledger` (404 `not_anchored_yet` until the
+copy is made). `verifyLedgerProof(proof, keys, { receipt })` checks, offline:
+
+1. **the leaf**: the envelope that was locked is recomputed from your saved receipt
+   (the SHA-256 of its canonical form, with its signature and key id) and must be
+   the leaf the proof starts from (`receiptBound: true`). Without `receipt` the
+   envelope in the proof, or just its leaf hash, is used;
+2. **the path**: it has the shape its leaf index and tree size require, and folds,
+   leaf to root;
+3. **the root**: it carries a valid signature by the region's receipt key (the same
+   published keys that verify your receipts) over a message that names the batch,
+   the tree size and the date the lock lapses.
+
+This proves the copy was filed under that signed root. That the stored object is
+still locked is checked at the storage service, with read access to the bucket,
+using `s3.key` and `s3.versionId` from the proof.
+
+| `reason` | Meaning |
+|---|---|
+| `malformed_proof` | Not a complete ledger proof. |
+| `not_this_receipt` | The proof is for another receipt id. |
+| `receipt_not_in_batch` | Your receipt does not hash to the leaf that was locked (it was altered, or the proof is for different bytes). |
+| `proof_shape_mismatch` | The path does not fit the claimed leaf index and tree size. |
+| `not_in_root` | The path does not reach the root. |
+| `unknown_key` / `bad_root_signature` | The root's signing key is not in the set, or its signature does not verify. |
+
+### The public witness
+
+A proof may carry `witness`: the batch root's entry in Sigstore's public Rekor log
+(`hashedrekord` v0.0.1). The batch's root message is hashed, `A = SHA-512(message)`,
+and `A` is signed in Ed25519ph mode by the **same** regional key that signed the root,
+so the log records `data.hash = SHA-512(A)` (`witness.rekorSha512`).
+
+A verified ledger proof always reports the witness in `result.witness`. The witness
+never changes `result.ok`: the ledger proof stands or falls on its own.
+
+| `witness.status` | Meaning |
+|---|---|
+| `absent` | The proof has no witness: the batch has not been submitted yet, or the witness is not switched on. |
+| `off` | Not witnessed, by the workspace's choice: an owner or admin had turned the public witness off (it is on by default) before the receipt was batched, so the batch root was never submitted. Not a failure; the log is never asked. |
+| `pending` | Submitted, not in the log yet; `since`, `attempts`, `lastError` and `nextAttemptAt` as the proof states them. |
+| `logged` | `consistent: true` with `problems: []`, or `consistent: false` with the exact `problems` (below). |
+| `malformed` | A `witness` whose status is none of `off`, `pending` and `logged`. |
+
+**Offline (always).** No network. Checked against the root message rebuilt from the
+proof and the root's published key:
+
+- `artifactSha512` is SHA-512 of the root message, and `rekorSha512` is SHA-512 of
+  that (`artifact_hash_mismatch`, `rekor_hash_mismatch`); `kind` is
+  `rekor.hashedrekord.v0.0.1` (`unknown_witness_kind`);
+- `signatureKeyId` is the root's key id (`not_the_root_key`), and `signature`
+  verifies as Ed25519ph with the root's key over the **recomputed** hash
+  (`bad_witness_signature`);
+- the copy of the log's answer in the proof is that entry: `body` is a `hashedrekord`
+  with `data.hash = { sha512, <recomputed hash> }`, the root's public key and the same
+  signature (`entry_body_malformed`, `entry_hash_mismatch`, `entry_key_mismatch`,
+  `entry_signature_mismatch`); `entryUuid` ends in the RFC 6962 leaf hash of `body`
+  (`entry_uuid_mismatch`); the copied `inclusionProof`, when present, folds that leaf
+  to the root hash it names (`inclusion_proof_invalid`); `integratedAt` is the instant
+  `integratedTime` names (`integrated_at_mismatch`). A missing field is
+  `malformed_witness`.
+
+That copy came from Entpoind, so the offline check shows the witness is consistent
+with the root, not that the log holds it.
+
+**Online (opt-in).** Pass `witnessLog: true`, or options:
+
+```ts
+const r = await verifyLedgerProof(proof, keys, {
+  receipt,
+  witnessLog: { logPublicKey: rekorPem }, // or `true`; also logUrl, fetch, timeoutMs
+});
+if (r.ok && r.witness.status === "logged") console.log(r.witness.consistent, r.witness.logCheck);
+```
+
+The entry is fetched from the log itself, `GET {log}/api/v1/log/entries/{entryUuid}`,
+where `{log}` is `logUrl`, else the proof's `witness.log`, else
+`https://rekor.sigstore.dev`. Only `https:` is used, and redirects are refused. On the
+log's answer it checks:
+
+- the entry holds the recomputed hash and the root's key, and its signature verifies
+  as Ed25519ph with that key; the UUID is the entry's leaf hash; its `logIndex` and
+  `integratedTime` are the ones the proof states;
+- its **inclusion proof** folds the entry to the tree root it names (RFC 6962);
+- its **checkpoint** (the signed note the inclusion proof ends in) names that tree size
+  and root, and is signed by the log;
+- its **signed entry timestamp** is the log's signature over
+  `{ body, integratedTime, logID, logIndex }` (RFC 8785).
+
+The log's signatures are checked with its public key: `logPublicKey` (SPKI PEM) if you
+pin it (`logKey: "pinned"`), otherwise the key fetched from the same log at
+`/api/v1/log/publicKey?treeID=…` (`logKey: "fetched"`). Either way the key must hash
+(SHA-256) to the entry's `logID`. A fetched key is trust on first use: a log that is not
+Sigstore's could serve its own key. Pin Sigstore's key (from its trust root, for example
+the TUF repository the Sigstore clients use) for the strongest check.
+
+`witness.logCheck` is `{ checked: false, reason }` when nothing was judged
+(`log_url_not_https`, `no_entry_uuid`, `log_unreachable`, `log_error` with `status`),
+or `{ checked: true, ok, problems, logKey, integratedTime, inclusionProof, checkpoint,
+signedEntryTimestamp }`, each part `verified`, `failed` or `not_checked`. `ok` is true
+only when all three parts are `verified` and there is no problem. A 404 from the log is
+the finding `entry_not_in_log`.
+
+**What is not checked.**
+
+- Log keys other than ECDSA P-256 (`log_key_unsupported`). rekor.sigstore.dev uses
+  P-256.
+- That the log is consistent over time: no consistency proof between checkpoints, no
+  checkpoint gossip or witness cosignatures. A log that showed different trees to
+  different people would need that to be caught; Sigstore's monitors do it.
+- The copy's `signedEntryTimestamp` and checkpoint offline: they are checked only on
+  the log's fresh answer.
+- Rekor v2 (tile-based) logs: this speaks the v1 API that the ledger submits to.
+- What the witness cannot prove at all: that every receipt was put in a batch, or that
+  what a receipt says is true. It shows the root existed, signed by our key, no later
+  than the log's `integratedTime`.
+
 ## Documentation
 
 Receipt format, verification procedure and key rotation:

package/dist/canonical-json.js

@@ -16,17 +16,17 @@ export class NonCanonicalizableError extends Error {
         this.name = "NonCanonicalizableError";
     }
 }
-function canonicalizeValue(value, path) {
+function serializeValue(value, path) {
     if (value === null)
-        return null;
+        return "null";
     const t = typeof value;
     if (t === "boolean" || t === "string")
-        return value;
+        return JSON.stringify(value);
     if (t === "number") {
         if (!Number.isFinite(value)) {
             throw new NonCanonicalizableError(`non-finite number (${String(value)}) is not valid JSON`, path);
         }
-        return value;
+        return JSON.stringify(value);
     }
     if (t === "bigint") {
         throw new NonCanonicalizableError("bigint cannot be canonicalized (no JSON representation)", path);
@@ -35,23 +35,24 @@ function canonicalizeValue(value, path) {
         throw new NonCanonicalizableError(`${t} cannot be canonicalized`, path);
     }
     if (Array.isArray(value)) {
-        return value.map((v, i) => canonicalizeValue(v, `${path}[${i}]`));
+        return `[${value.map((v, i) => serializeValue(v, `${path}[${i}]`)).join(",")}]`;
     }
     const proto = Object.getPrototypeOf(value);
     if (proto !== Object.prototype && proto !== null) {
         throw new NonCanonicalizableError(`non-plain object (${value.constructor?.name ?? "unknown"}) cannot be canonicalized; pass plain JSON`, path);
     }
     const obj = value;
-    const out = {};
+    // Written as text: an object would reorder integer-like keys and swallow a `__proto__` key.
+    const members = [];
     for (const key of Object.keys(obj).sort()) {
         const child = obj[key];
         if (child === undefined)
             continue;
-        out[key] = canonicalizeValue(child, path ? `${path}.${key}` : key);
+        members.push(`${JSON.stringify(key)}:${serializeValue(child, path ? `${path}.${key}` : key)}`);
     }
-    return out;
+    return `{${members.join(",")}}`;
 }
 /** The RFC 8785 canonical string for `value` — the bytes a signature covers. */
 export function canonicalJcs(value) {
-    return JSON.stringify(canonicalizeValue(value, ""));
+    return serializeValue(value, "");
 }

package/dist/ed25519ph.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @entpoind/verify — Ed25519ph (RFC 8032 §5.1, "HashEdDSA" with SHA-512) signature verification.
+ *
+ * Needed for one thing: the receipt ledger's public witness. Rekor accepts an Ed25519 key in a `hashedrekord` entry only as
+ * Ed25519ph, so the witness signature is Ed25519ph by the region's receipt key, and WebCrypto has no Ed25519ph. This is
+ * the RFC's verification procedure (§5.1.7) in BigInt arithmetic, with WebCrypto supplying SHA-512 and nothing else:
+ *
+ *   k = SHA-512( dom2(1, "") ‖ R ‖ A ‖ PH(M) )  mod L,     and accept iff  encode([S]B − [k]A) == R
+ *
+ * the cofactorless check, with S < L and A and R decoded strictly (§5.1.3), as Go's crypto/ed25519 does. Tested against
+ * the RFC 8032 §7.3 vector and against signatures made by Go's crypto/ed25519.
+ *
+ * Verification only touches public values, so the arithmetic need not be constant-time. `ed25519phSign` exists for test
+ * fixtures; it is not exported from the package and must never see a real key.
+ */
+/**
+ * Ed25519ph verification over an already computed prehash `ph` = SHA-512(M) (64 bytes), as Rekor and Go's
+ * `ed25519.VerifyWithOptions(pub, ph, sig, &ed25519.Options{Hash: crypto.SHA512})` take it. Never throws.
+ */
+export declare function verifyEd25519ph(publicKey: Uint8Array, ph: Uint8Array, signature: Uint8Array): Promise<boolean>;
+/** TEST FIXTURES ONLY: an Ed25519ph signature (RFC 8032 §5.1.6) by the 32-byte `seed` over the prehash `ph`. */
+export declare function ed25519phSign(seed: Uint8Array, ph: Uint8Array): Promise<{
+    publicKey: Uint8Array;
+    signature: Uint8Array;
+}>;

package/dist/ed25519ph.js

@@ -0,0 +1,171 @@
+/**
+ * @entpoind/verify — Ed25519ph (RFC 8032 §5.1, "HashEdDSA" with SHA-512) signature verification.
+ *
+ * Needed for one thing: the receipt ledger's public witness. Rekor accepts an Ed25519 key in a `hashedrekord` entry only as
+ * Ed25519ph, so the witness signature is Ed25519ph by the region's receipt key, and WebCrypto has no Ed25519ph. This is
+ * the RFC's verification procedure (§5.1.7) in BigInt arithmetic, with WebCrypto supplying SHA-512 and nothing else:
+ *
+ *   k = SHA-512( dom2(1, "") ‖ R ‖ A ‖ PH(M) )  mod L,     and accept iff  encode([S]B − [k]A) == R
+ *
+ * the cofactorless check, with S < L and A and R decoded strictly (§5.1.3), as Go's crypto/ed25519 does. Tested against
+ * the RFC 8032 §7.3 vector and against signatures made by Go's crypto/ed25519.
+ *
+ * Verification only touches public values, so the arithmetic need not be constant-time. `ed25519phSign` exists for test
+ * fixtures; it is not exported from the package and must never see a real key.
+ */
+const P = 2n ** 255n - 19n;
+const L = 2n ** 252n + 27742317777372353535851937790883648493n;
+const D = mod(-121665n * inv(121666n));
+const SQRT_M1 = pow(2n, (P - 1n) / 4n);
+const BASE = (() => {
+    const y = mod(4n * inv(5n));
+    const x = 15112221349535400772501151409588531511454012693041857206046113283949847762202n;
+    return { x, y, z: 1n, t: mod(x * y) };
+})();
+const IDENTITY = { x: 0n, y: 1n, z: 1n, t: 0n };
+/** dom2(phflag = 1, context = ""), RFC 8032 §2. */
+const DOM2_PH = new Uint8Array([...new TextEncoder().encode("SigEd25519 no Ed25519 collisions"), 1, 0]);
+function mod(a, m = P) {
+    const r = a % m;
+    return r >= 0n ? r : r + m;
+}
+function pow(b, e) {
+    let r = 1n;
+    let x = mod(b);
+    while (e > 0n) {
+        if (e & 1n)
+            r = mod(r * x);
+        x = mod(x * x);
+        e >>= 1n;
+    }
+    return r;
+}
+function inv(a) {
+    return pow(a, P - 2n);
+}
+// RFC 8032 §5.1.4, extended coordinates; the addition is complete, so it doubles too.
+function add(p, q) {
+    const a = mod((p.y - p.x) * (q.y - q.x));
+    const b = mod((p.y + p.x) * (q.y + q.x));
+    const c = mod(2n * D * p.t * q.t);
+    const d = mod(2n * p.z * q.z);
+    const e = b - a;
+    const f = d - c;
+    const g = d + c;
+    const h = b + a;
+    return { x: mod(e * f), y: mod(g * h), z: mod(f * g), t: mod(e * h) };
+}
+function mul(p, n) {
+    let r = IDENTITY;
+    let q = p;
+    while (n > 0n) {
+        if (n & 1n)
+            r = add(r, q);
+        q = add(q, q);
+        n >>= 1n;
+    }
+    return r;
+}
+function negate(p) {
+    return { x: mod(-p.x), y: p.y, z: p.z, t: mod(-p.t) };
+}
+function leInt(b) {
+    let n = 0n;
+    for (let i = b.length - 1; i >= 0; i--)
+        n = (n << 8n) | BigInt(b[i]);
+    return n;
+}
+function leBytes(n, len) {
+    const out = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        out[i] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+    return out;
+}
+function encode(p) {
+    const zi = inv(p.z);
+    const x = mod(p.x * zi);
+    const y = mod(p.y * zi);
+    const out = leBytes(y, 32);
+    if (x & 1n)
+        out[31] = out[31] | 0x80;
+    return out;
+}
+/** RFC 8032 §5.1.3. Null for anything that is not the canonical encoding of a curve point. */
+function decode(b) {
+    if (b.length !== 32)
+        return null;
+    const x0 = (b[31] & 0x80) !== 0;
+    const yb = b.slice();
+    yb[31] = yb[31] & 0x7f;
+    const y = leInt(yb);
+    if (y >= P)
+        return null;
+    const u = mod(y * y - 1n);
+    const v = mod(D * y * y + 1n);
+    let x = mod(u * pow(v, 3n) * pow(u * pow(v, 7n), (P - 5n) / 8n));
+    const vx2 = mod(v * x * x);
+    if (vx2 === u) {
+        /* x is a root */
+    }
+    else if (vx2 === mod(-u)) {
+        x = mod(x * SQRT_M1);
+    }
+    else {
+        return null;
+    }
+    if (x === 0n && x0)
+        return null;
+    if ((x & 1n) !== (x0 ? 1n : 0n))
+        x = mod(-x);
+    return { x, y, z: 1n, t: mod(x * y) };
+}
+async function sha512(...parts) {
+    const all = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let off = 0;
+    for (const p of parts) {
+        all.set(p, off);
+        off += p.length;
+    }
+    return new Uint8Array(await crypto.subtle.digest("SHA-512", all));
+}
+const eq = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+/**
+ * Ed25519ph verification over an already computed prehash `ph` = SHA-512(M) (64 bytes), as Rekor and Go's
+ * `ed25519.VerifyWithOptions(pub, ph, sig, &ed25519.Options{Hash: crypto.SHA512})` take it. Never throws.
+ */
+export async function verifyEd25519ph(publicKey, ph, signature) {
+    try {
+        if (publicKey.length !== 32 || ph.length !== 64 || signature.length !== 64)
+            return false;
+        const a = decode(publicKey);
+        if (!a)
+            return false;
+        const rBytes = signature.slice(0, 32);
+        const s = leInt(signature.slice(32));
+        if (s >= L)
+            return false;
+        const k = mod(leInt(await sha512(DOM2_PH, rBytes, publicKey, ph)), L);
+        return eq(encode(add(mul(BASE, s), mul(negate(a), k))), rBytes);
+    }
+    catch {
+        return false;
+    }
+}
+/** TEST FIXTURES ONLY: an Ed25519ph signature (RFC 8032 §5.1.6) by the 32-byte `seed` over the prehash `ph`. */
+export async function ed25519phSign(seed, ph) {
+    const h = await sha512(seed);
+    const sb = h.slice(0, 32);
+    sb[0] = sb[0] & 248;
+    sb[31] = (sb[31] & 127) | 64;
+    const s = leInt(sb);
+    const publicKey = encode(mul(BASE, s));
+    const r = mod(leInt(await sha512(DOM2_PH, h.slice(32), ph)), L);
+    const rBytes = encode(mul(BASE, r));
+    const k = mod(leInt(await sha512(DOM2_PH, rBytes, publicKey, ph)), L);
+    const signature = new Uint8Array(64);
+    signature.set(rBytes, 0);
+    signature.set(leBytes(mod(r + k * s, L), 32), 32);
+    return { publicKey, signature };
+}

package/dist/index.d.ts

@@ -15,8 +15,11 @@
  * Deno, Bun, and Cloudflare Workers.
  */
 import { type MerkleProofStep } from "./merkle.js";
+import { type LedgerWitness, type WitnessLogOptions, type WitnessReport } from "./witness.js";
 export { canonicalJcs, NonCanonicalizableError, type JsonValue } from "./canonical-json.js";
-export { merkleLeafHash, verifyMerkleInclusion, type MerkleProofStep } from "./merkle.js";
+export { merkleLeafHash, verifyMerkleInclusion, verifyMerkleInclusionFromHash, type MerkleProofStep } from "./merkle.js";
+export { verifyEd25519ph } from "./ed25519ph.js";
+export { DEFAULT_REKOR_URL, WITNESS_KIND, type LedgerWitness, type WitnessLogCheck, type WitnessLogOptions, type WitnessLogProblem, type WitnessPart, type WitnessProblem, type WitnessReport, } from "./witness.js";
 /** A public verification key as published in the Tools JWK Set. */
 export type PublishedKey = {
     kid: string;
@@ -129,3 +132,91 @@ export declare function verifyBundle(input: unknown, publicKeys: ReadonlyArray<P
  * check" never reads as a verdict on the receipt.
  */
 export declare function verifyReceiptOnline(input: unknown, keysUrl?: string): Promise<ReceiptVerification>;
+/** The envelope a ledger batch locks for one receipt: hashes and the signature, never the body. */
+export type LedgerEnvelope = {
+    v: 1;
+    receipt_id: string;
+    kind: string;
+    receipt_hash: string;
+    signature: string;
+    signature_key_id: string;
+    issued_at: string;
+    region: string;
+    retain_until: string;
+};
+/** What `GET /api/v1/tools/receipts/{id}/ledger` answers (the 200 body). */
+export type LedgerProof = {
+    kind: "entpoind.tools.receipt-ledger.proof";
+    v: 1;
+    receiptId: string;
+    batchId: string;
+    leafIndex: number;
+    treeSize: number;
+    leafHash: string;
+    /** The envelope that leaf hashes; null for a redacted receipt. */
+    envelope: LedgerEnvelope | null;
+    proof: MerkleProofStep[];
+    root: string;
+    rootSignature: string;
+    signatureKeyId: string;
+    region: string;
+    retentionClass: string;
+    bucketHour: string;
+    retainUntil: string;
+    anchoredAt: string;
+    s3: {
+        bucket: string | null;
+        key: string;
+        versionId: string | null;
+    };
+    /**
+     * The batch root's entry in the public Sigstore Rekor log; null (or absent, before LED-5) until it has been submitted;
+     * `{ status: "off" }` when the workspace had turned the public witness off before the receipt was batched.
+     */
+    witness?: LedgerWitness | null;
+};
+export type LedgerFailureReason = "malformed_proof" | "malformed_envelope" | "not_this_receipt" | "receipt_not_in_batch" | "proof_shape_mismatch" | "not_in_root" | "unknown_key" | "bad_root_signature" | "unsupported_runtime";
+export type LedgerVerification = {
+    ok: true;
+    /** True when the proof was tied to the receipt you supplied (or its envelope was recomputed from it). False when only the leaf hash was folded. */
+    receiptBound: boolean;
+    batchId: string;
+    leafIndex: number;
+    treeSize: number;
+    root: string;
+    signatureKeyId: string;
+    /** When the compliance lock on the stored copy lapses. */
+    retainUntil: string;
+    /**
+     * The public witness, judged on its own: `absent` / `off` / `pending` / `malformed`, or `logged` with `consistent` and the exact
+     * `problems`. It never changes `ok`: the ledger proof above stands or falls without it.
+     */
+    witness: WitnessReport;
+} | {
+    ok: false;
+    reason: LedgerFailureReason;
+};
+/** The bytes the region's receipt key signed over a batch root. */
+export declare function ledgerRootMessage(p: Pick<LedgerProof, "region" | "batchId" | "retentionClass" | "bucketHour" | "treeSize" | "root" | "retainUntil">): string;
+/**
+ * Verify a receipt-ledger proof offline. Pure public-key crypto: no account, no network, and no S3 access.
+ *
+ *   1. (with `receipt`) the envelope the ledger locked is RECOMPUTED from your saved receipt (its canonical form,
+ *      hashed, with its signature and key id) and must be the leaf the proof starts from. Without a receipt the leaf is
+ *      the envelope the proof carries, or just the leaf hash; `receiptBound` says which.
+ *   2. the sibling path has exactly the shape its leaf index and tree size require, and folds, leaf to root;
+ *   3. the root carries a valid signature by the region's receipt key (the key set that verifies your receipts), over a
+ *      message that also names the batch, the tree size and the date the lock lapses.
+ *
+ * It proves the copy was FILED, under that root, by that key. That the object is still locked at S3 is S3's guarantee,
+ * checked there (GET object-retention on `s3.key` / `s3.versionId`) by someone holding read access to the bucket.
+ *
+ * Once the root verifies, the proof's `witness` (the root's entry in the public Rekor log) is checked too and reported in
+ * `witness` (see witness.ts): offline, that its hashes are the root message's, that it is by the root's key and its
+ * Ed25519ph signature verifies, and that the copy of the log's answer is that entry. With `witnessLog` (opt-in, the only
+ * network call here) the entry is also fetched from the log and checked there, with the log's own signatures.
+ */
+export declare function verifyLedgerProof(input: unknown, publicKeys: ReadonlyArray<PublishedKey>, options?: {
+    receipt?: unknown;
+    witnessLog?: boolean | WitnessLogOptions;
+}): Promise<LedgerVerification>;