@entpoind/verify 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+/**
+ * @entpoind/verify — offline verification of Entpoind Tools receipts and
+ * VerifiableArtifact bundles.
+ *
+ * What a customer pastes into this library was signed by the Tools worker's
+ * per-jurisdiction Ed25519 key; the matching public keys are published as a
+ * JWK Set at `/.well-known/tools-keys.json` (CORS-open on purpose — this
+ * library is meant to run from the customer's own page or backend).
+ *
+ * No trust in us is required beyond the published key set: the signature is
+ * verified locally over the RFC 8785 canonical form of the envelope, and an
+ * artifact bundle's Merkle inclusion proof is folded locally too.
+ *
+ * Zero dependencies. WebCrypto only — runs in every modern browser, Node ≥ 20,
+ * 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, 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;
+    kty: string;
+    crv: string;
+    x: string;
+    alg?: string;
+    use?: string;
+};
+/** The `/.well-known/tools-keys.json` document shape. */
+export type ToolsKeySet = {
+    keys: PublishedKey[];
+};
+/**
+ * Where the production key set is published. The same document is mirrored on
+ * the Tools marketing domain; either origin serves it CORS-open.
+ */
+export declare const DEFAULT_KEYS_URL = "https://entpoind.com/.well-known/tools-keys.json";
+/**
+ * Fetch the published key set. `keysUrl` is absolute — e.g.
+ * `https://entpoind.com/.well-known/tools-keys.json` or the `keysUrl` field a
+ * runtime embeds in its receipts.
+ *
+ * Throws on transport failure — callers that distinguish "couldn't fetch keys"
+ * from "bad signature" should catch and report that separately.
+ */
+export declare function fetchToolsKeys(keysUrl: string): Promise<PublishedKey[]>;
+/** Whether this runtime's WebCrypto can verify Ed25519 signatures. Cached after the first call. */
+export declare function ed25519Supported(): Promise<boolean>;
+/**
+ * Verify a base64url Ed25519 signature. Never throws on hostile input. Returns
+ * false both for a wrong signature and for a runtime without Ed25519; use
+ * `ed25519Supported()` to tell those apart, or the `verify*` functions, which
+ * report `unsupported_runtime`.
+ */
+export declare function verifySignature(publicKey: {
+    kty: string;
+    crv: string;
+    x: string;
+}, message: string, signatureB64Url: string): Promise<boolean>;
+/** Why a verification failed. `unsupported_runtime` means the check could not run, not that the document is bad. */
+export type FailureReason = "bad_signature" | "unknown_key" | "malformed_envelope" | "unsupported_runtime";
+export type ReceiptVerification = {
+    ok: true;
+    signedAt: string;
+    signatureKeyId: string;
+} | {
+    ok: false;
+    reason: FailureReason;
+};
+/** The canonical bytes a receipt's signature covers: JCS(envelope − signature). */
+export declare function canonicalReceiptString(envelope: Record<string, unknown>): string;
+/** Runtime shape guard for an untrusted receipt envelope. */
+export declare function isReceiptEnvelope(x: unknown): x is Record<string, unknown>;
+/**
+ * Verify a Tools receipt against the published public keys. Accepts the parsed
+ * envelope, its JSON text, or the `{ receipt }` wrapper the API returns. Pure
+ * public-key crypto — no account, no network.
+ */
+export declare function verifyReceipt(input: unknown, publicKeys: ReadonlyArray<PublishedKey>): Promise<ReceiptVerification>;
+export type ArtifactVerification = {
+    ok: true;
+    signedAt: string;
+    signatureKeyId: string;
+    kind: string;
+} | {
+    ok: false;
+    reason: FailureReason;
+};
+/** The canonical bytes an artifact's signature covers: JCS(envelope − signature). */
+export declare function canonicalArtifactString(envelope: Record<string, unknown>): string;
+/** Runtime shape guard for an untrusted artifact envelope. */
+export declare function isArtifactEnvelope(x: unknown): x is Record<string, unknown>;
+/** Verify a standalone VerifiableArtifact against the published public keys. */
+export declare function verifyArtifact(input: unknown, publicKeys: ReadonlyArray<PublishedKey>): Promise<ArtifactVerification>;
+/** A self-contained artifact bundle: the signed artifact, its index id, and —
+ *  once the batch is anchored — the Merkle proof + anchored root. `leafHash` is
+ *  the plain SHA-256 of the leaf string, an index id; verification does not use it. */
+export type ArtifactBundle = {
+    artifact: Record<string, unknown>;
+    leafHash: string;
+    anchor?: {
+        merkleRoot: string;
+        proof: MerkleProofStep[];
+        topsRef?: string;
+    };
+};
+export type BundleVerification = {
+    ok: true;
+    anchored: boolean;
+    signedAt: string;
+    kind: string;
+} | {
+    ok: false;
+    anchored: boolean;
+    reason: FailureReason | "not_in_anchored_root";
+};
+/**
+ * Verify a bundle offline: the artifact's Ed25519 signature, then — when an
+ * anchor is present — that JCS(signed artifact) is included under the anchored
+ * Merkle root. `anchored:false` on a pre-anchor bundle is a valid result, not a
+ * failure.
+ */
+export declare function verifyBundle(input: unknown, publicKeys: ReadonlyArray<PublishedKey>): Promise<BundleVerification>;
+/**
+ * One-shot receipt verification against the published key set — fetch keys,
+ * resolve `signatureKeyId`, verify. `keysUrl` defaults to the production
+ * well-known document; pass an override for staging / self-hosted runtimes.
+ * Throws (like `fetchToolsKeys`) when the keys cannot be fetched, so "could not
+ * 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>;

package/dist/index.js

@@ -0,0 +1,350 @@
+/**
+ * @entpoind/verify — offline verification of Entpoind Tools receipts and
+ * VerifiableArtifact bundles.
+ *
+ * What a customer pastes into this library was signed by the Tools worker's
+ * per-jurisdiction Ed25519 key; the matching public keys are published as a
+ * JWK Set at `/.well-known/tools-keys.json` (CORS-open on purpose — this
+ * library is meant to run from the customer's own page or backend).
+ *
+ * No trust in us is required beyond the published key set: the signature is
+ * verified locally over the RFC 8785 canonical form of the envelope, and an
+ * artifact bundle's Merkle inclusion proof is folded locally too.
+ *
+ * Zero dependencies. WebCrypto only — runs in every modern browser, Node ≥ 20,
+ * Deno, Bun, and Cloudflare Workers.
+ */
+import { canonicalJcs } from "./canonical-json.js";
+import { merkleLeafHash, sha256Hex, verifyMerkleInclusion, verifyMerkleInclusionFromHash } from "./merkle.js";
+import { checkLedgerWitness } from "./witness.js";
+export { canonicalJcs, NonCanonicalizableError } from "./canonical-json.js";
+export { merkleLeafHash, verifyMerkleInclusion, verifyMerkleInclusionFromHash } from "./merkle.js";
+export { verifyEd25519ph } from "./ed25519ph.js";
+export { DEFAULT_REKOR_URL, WITNESS_KIND, } from "./witness.js";
+/**
+ * Where the production key set is published. The same document is mirrored on
+ * the Tools marketing domain; either origin serves it CORS-open.
+ */
+export const DEFAULT_KEYS_URL = "https://entpoind.com/.well-known/tools-keys.json";
+/**
+ * Fetch the published key set. `keysUrl` is absolute — e.g.
+ * `https://entpoind.com/.well-known/tools-keys.json` or the `keysUrl` field a
+ * runtime embeds in its receipts.
+ *
+ * Throws on transport failure — callers that distinguish "couldn't fetch keys"
+ * from "bad signature" should catch and report that separately.
+ */
+export async function fetchToolsKeys(keysUrl) {
+    const res = await fetch(keysUrl, { headers: { accept: "application/jwk-set+json, application/json" } });
+    if (!res.ok)
+        throw new Error(`tools keys: HTTP ${res.status} from ${keysUrl}`);
+    const doc = (await res.json());
+    if (!doc || !Array.isArray(doc.keys))
+        throw new Error("tools keys: response is not a JWK Set");
+    return doc.keys.filter((k) => k && typeof k.kid === "string" && k.kty === "OKP" && k.crv === "Ed25519" && typeof k.x === "string");
+}
+// ─── Ed25519 ──────────────────────────────────────────────────────────
+function bytesFromBase64Url(s) {
+    const pad = (4 - (s.length % 4)) % 4;
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat(pad);
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+// RFC 8032 §7.1 test 1 public key: importing it fails only where WebCrypto has no Ed25519.
+const PROBE_KEY = { kty: "OKP", crv: "Ed25519", x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo", ext: true };
+let ed25519Probe;
+/** Whether this runtime's WebCrypto can verify Ed25519 signatures. Cached after the first call. */
+export function ed25519Supported() {
+    ed25519Probe ??= (async () => {
+        try {
+            await crypto.subtle.importKey("jwk", PROBE_KEY, { name: "Ed25519" }, false, ["verify"]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return ed25519Probe;
+}
+async function checkSignature(publicKey, message, signatureB64Url) {
+    let key;
+    try {
+        key = await crypto.subtle.importKey("jwk", { kty: publicKey.kty, crv: publicKey.crv, x: publicKey.x, ext: true }, { name: "Ed25519" }, false, ["verify"]);
+    }
+    catch {
+        // A key that will not import is a bad key, unless the runtime cannot do Ed25519 at all.
+        return (await ed25519Supported()) ? "invalid" : "unsupported";
+    }
+    try {
+        const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, bytesFromBase64Url(signatureB64Url), new TextEncoder().encode(message));
+        return ok ? "valid" : "invalid";
+    }
+    catch {
+        return "invalid";
+    }
+}
+/**
+ * Verify a base64url Ed25519 signature. Never throws on hostile input. Returns
+ * false both for a wrong signature and for a runtime without Ed25519; use
+ * `ed25519Supported()` to tell those apart, or the `verify*` functions, which
+ * report `unsupported_runtime`.
+ */
+export async function verifySignature(publicKey, message, signatureB64Url) {
+    return (await checkSignature(publicKey, message, signatureB64Url)) === "valid";
+}
+/** The canonical bytes a receipt's signature covers: JCS(envelope − signature). */
+export function canonicalReceiptString(envelope) {
+    const rest = { ...envelope };
+    delete rest.signature;
+    return canonicalJcs(rest);
+}
+/** Runtime shape guard for an untrusted receipt envelope. */
+export function isReceiptEnvelope(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const e = x;
+    return (e.version === "1" &&
+        typeof e.receiptId === "string" &&
+        typeof e.issuedAt === "string" &&
+        typeof e.type === "string" &&
+        typeof e.signatureKeyId === "string" &&
+        typeof e.signature === "string" &&
+        !!e.body &&
+        typeof e.body === "object" &&
+        e.body.type === e.type);
+}
+/**
+ * Verify a Tools receipt against the published public keys. Accepts the parsed
+ * envelope, its JSON text, or the `{ receipt }` wrapper the API returns. Pure
+ * public-key crypto — no account, no network.
+ */
+export async function verifyReceipt(input, publicKeys) {
+    let envelope = typeof input === "string" ? safeParse(input) : input;
+    if (!isReceiptEnvelope(envelope) && envelope && typeof envelope === "object") {
+        envelope = envelope.receipt;
+    }
+    if (!isReceiptEnvelope(envelope))
+        return { ok: false, reason: "malformed_envelope" };
+    const key = findKey(publicKeys, envelope.signatureKeyId);
+    if (!key)
+        return { ok: false, reason: "unknown_key" };
+    const check = await checkSignature(key, canonicalReceiptString(envelope), envelope.signature);
+    if (check === "unsupported")
+        return { ok: false, reason: "unsupported_runtime" };
+    if (check === "invalid")
+        return { ok: false, reason: "bad_signature" };
+    return { ok: true, signedAt: envelope.issuedAt, signatureKeyId: envelope.signatureKeyId };
+}
+/** The canonical bytes an artifact's signature covers: JCS(envelope − signature). */
+export function canonicalArtifactString(envelope) {
+    const rest = { ...envelope };
+    delete rest.signature;
+    return canonicalJcs(rest);
+}
+/** Runtime shape guard for an untrusted artifact envelope. */
+export function isArtifactEnvelope(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const e = x;
+    return (e.version === "1" &&
+        typeof e.artifactId === "string" &&
+        typeof e.issuedAt === "string" &&
+        typeof e.kind === "string" &&
+        typeof e.signatureKeyId === "string" &&
+        typeof e.signature === "string" &&
+        "subject" in e &&
+        "claims" in e);
+}
+/** Verify a standalone VerifiableArtifact against the published public keys. */
+export async function verifyArtifact(input, publicKeys) {
+    const envelope = typeof input === "string" ? safeParse(input) : input;
+    if (!isArtifactEnvelope(envelope))
+        return { ok: false, reason: "malformed_envelope" };
+    const key = findKey(publicKeys, envelope.signatureKeyId);
+    if (!key)
+        return { ok: false, reason: "unknown_key" };
+    const check = await checkSignature(key, canonicalArtifactString(envelope), envelope.signature);
+    if (check === "unsupported")
+        return { ok: false, reason: "unsupported_runtime" };
+    if (check === "invalid")
+        return { ok: false, reason: "bad_signature" };
+    return {
+        ok: true,
+        signedAt: envelope.issuedAt,
+        signatureKeyId: envelope.signatureKeyId,
+        kind: envelope.kind,
+    };
+}
+/**
+ * Verify a bundle offline: the artifact's Ed25519 signature, then — when an
+ * anchor is present — that JCS(signed artifact) is included under the anchored
+ * Merkle root. `anchored:false` on a pre-anchor bundle is a valid result, not a
+ * failure.
+ */
+export async function verifyBundle(input, publicKeys) {
+    const bundle = (typeof input === "string" ? safeParse(input) : input);
+    if (!bundle || typeof bundle !== "object" || !isArtifactEnvelope(bundle.artifact)) {
+        return { ok: false, anchored: false, reason: "malformed_envelope" };
+    }
+    const sig = await verifyArtifact(bundle.artifact, publicKeys);
+    if (!sig.ok)
+        return { ok: false, anchored: false, reason: sig.reason };
+    if (!bundle.anchor)
+        return { ok: true, anchored: false, signedAt: sig.signedAt, kind: sig.kind };
+    const leaf = canonicalJcs(bundle.artifact);
+    const included = await verifyMerkleInclusion(leaf, bundle.anchor.proof ?? [], bundle.anchor.merkleRoot);
+    if (!included)
+        return { ok: false, anchored: true, reason: "not_in_anchored_root" };
+    return { ok: true, anchored: true, signedAt: sig.signedAt, kind: sig.kind };
+}
+/**
+ * One-shot receipt verification against the published key set — fetch keys,
+ * resolve `signatureKeyId`, verify. `keysUrl` defaults to the production
+ * well-known document; pass an override for staging / self-hosted runtimes.
+ * Throws (like `fetchToolsKeys`) when the keys cannot be fetched, so "could not
+ * check" never reads as a verdict on the receipt.
+ */
+export async function verifyReceiptOnline(input, keysUrl = DEFAULT_KEYS_URL) {
+    return verifyReceipt(input, await fetchToolsKeys(keysUrl));
+}
+const LEDGER_ROOT_KIND = "entpoind.tools.receipt-ledger.root";
+const HEX64 = /^[0-9a-f]{64}$/;
+function isLedgerProof(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const p = x;
+    const str = (k) => typeof p[k] === "string" && p[k].length > 0;
+    if (p.kind !== "entpoind.tools.receipt-ledger.proof" || p.v !== 1)
+        return false;
+    for (const k of ["receiptId", "batchId", "rootSignature", "signatureKeyId", "region", "retentionClass", "bucketHour", "retainUntil"])
+        if (!str(k))
+            return false;
+    if (typeof p.root !== "string" || !HEX64.test(p.root) || typeof p.leafHash !== "string" || !HEX64.test(p.leafHash))
+        return false;
+    if (!Number.isInteger(p.leafIndex) || !Number.isInteger(p.treeSize) || p.treeSize < 1 || p.leafIndex < 0 || p.leafIndex >= p.treeSize)
+        return false;
+    if (!Array.isArray(p.proof))
+        return false;
+    return true;
+}
+/**
+ * The positions (`left`/`right` of the sibling) a proof for leaf `index` in a tree of `size` leaves must have, from the
+ * leaf up. An odd node at a level is carried up and contributes no step. Checking the served path against this binds the
+ * claimed leaf index and tree size to the proof: a path for a different place cannot be passed off as this one's.
+ */
+function expectedPositions(index, size) {
+    const out = [];
+    let idx = index;
+    let n = size;
+    while (n > 1) {
+        const sibling = idx % 2 === 0 ? idx + 1 : idx - 1;
+        if (sibling < n)
+            out.push(idx % 2 === 0 ? "right" : "left");
+        idx = Math.floor(idx / 2);
+        n = Math.ceil(n / 2);
+    }
+    return out;
+}
+/** The bytes the region's receipt key signed over a batch root. */
+export function ledgerRootMessage(p) {
+    return canonicalJcs({
+        kind: LEDGER_ROOT_KIND,
+        v: 1,
+        region: p.region,
+        batchId: p.batchId,
+        retentionClass: p.retentionClass,
+        bucketHour: p.bucketHour,
+        treeSize: p.treeSize,
+        root: p.root,
+        retainUntil: p.retainUntil,
+    });
+}
+/**
+ * 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 async function verifyLedgerProof(input, publicKeys, options = {}) {
+    const proof = typeof input === "string" ? safeParse(input) : input;
+    if (!isLedgerProof(proof))
+        return { ok: false, reason: "malformed_proof" };
+    // 1. the leaf
+    let receiptBound = false;
+    let leaf = null;
+    let receipt = typeof options.receipt === "string" ? safeParse(options.receipt) : options.receipt;
+    if (options.receipt !== undefined) {
+        if (!isReceiptEnvelope(receipt) && receipt && typeof receipt === "object")
+            receipt = receipt.receipt;
+        if (!isReceiptEnvelope(receipt))
+            return { ok: false, reason: "malformed_envelope" };
+        if (receipt.receiptId !== proof.receiptId)
+            return { ok: false, reason: "not_this_receipt" };
+    }
+    if (isReceiptEnvelope(receipt) && receipt.redacted !== true) {
+        const envelope = {
+            v: 1,
+            receipt_id: receipt.receiptId,
+            kind: receipt.type,
+            receipt_hash: await sha256Hex(canonicalReceiptString(receipt)),
+            signature: receipt.signature,
+            signature_key_id: receipt.signatureKeyId,
+            issued_at: receipt.issuedAt,
+            region: proof.region,
+            retain_until: proof.retainUntil,
+        };
+        leaf = canonicalJcs(envelope);
+        receiptBound = true;
+    }
+    else if (proof.envelope) {
+        leaf = canonicalJcs(proof.envelope);
+    }
+    if (leaf !== null && (await merkleLeafHash(leaf)) !== proof.leafHash)
+        return { ok: false, reason: "receipt_not_in_batch" };
+    // 2. the path
+    const want = expectedPositions(proof.leafIndex, proof.treeSize);
+    if (proof.proof.length !== want.length || proof.proof.some((s, i) => !s || s.position !== want[i]))
+        return { ok: false, reason: "proof_shape_mismatch" };
+    if (!(await verifyMerkleInclusionFromHash(proof.leafHash, proof.proof, proof.root)))
+        return { ok: false, reason: "not_in_root" };
+    // 3. the signed root
+    const key = findKey(publicKeys, proof.signatureKeyId);
+    if (!key)
+        return { ok: false, reason: "unknown_key" };
+    const check = await checkSignature(key, ledgerRootMessage(proof), proof.rootSignature);
+    if (check === "unsupported")
+        return { ok: false, reason: "unsupported_runtime" };
+    if (check === "invalid")
+        return { ok: false, reason: "bad_root_signature" };
+    // 4. the public witness: reported, never a verdict on the proof
+    const witnessLog = options.witnessLog === true ? {} : options.witnessLog || undefined;
+    const witness = await checkLedgerWitness(proof.witness, { rootMessage: ledgerRootMessage(proof), signatureKeyId: proof.signatureKeyId, publicKeyX: key.x }, witnessLog);
+    return { ok: true, receiptBound, batchId: proof.batchId, leafIndex: proof.leafIndex, treeSize: proof.treeSize, root: proof.root, signatureKeyId: proof.signatureKeyId, retainUntil: proof.retainUntil, witness };
+}
+// Only a well-formed Ed25519 public key is ever used, whatever the caller's key list holds.
+function findKey(keys, kid) {
+    return keys.find((k) => !!k && k.kid === kid && k.kty === "OKP" && k.crv === "Ed25519" && typeof k.x === "string");
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/merkle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @entpoind/verify — domain-separated Merkle inclusion proofs.
+ *
+ * Byte-identical port of runtime/shared/merkle.ts's verify path:
+ *   leaf hash  = SHA-256( 0x00 ‖ utf8(leaf) )
+ *   node hash  = SHA-256( 0x01 ‖ leftBytes ‖ rightBytes )
+ *   odd nodes are carried up unchanged (never duplicated).
+ */
+export declare function sha256Hex(input: string | Uint8Array): Promise<string>;
+export declare function merkleLeafHash(leaf: string): Promise<string>;
+export type MerkleProofStep = {
+    sibling: string;
+    position: "left" | "right";
+};
+/**
+ * Verify that `leaf` (the original leaf STRING — the canonical signed envelope)
+ * folds along `proof` into `root`. Never throws on a malformed proof.
+ */
+export declare function verifyMerkleInclusion(leaf: string, proof: ReadonlyArray<MerkleProofStep>, root: string): Promise<boolean>;
+/**
+ * The same fold, starting from a leaf HASH (hex) rather than the leaf string — for a proof whose leaf string is not
+ * available (a ledger proof for a redacted receipt). Never throws on a malformed proof.
+ */
+export declare function verifyMerkleInclusionFromHash(leafHash: string, proof: ReadonlyArray<MerkleProofStep>, root: string): Promise<boolean>;

package/dist/merkle.js

@@ -0,0 +1,76 @@
+/**
+ * @entpoind/verify — domain-separated Merkle inclusion proofs.
+ *
+ * Byte-identical port of runtime/shared/merkle.ts's verify path:
+ *   leaf hash  = SHA-256( 0x00 ‖ utf8(leaf) )
+ *   node hash  = SHA-256( 0x01 ‖ leftBytes ‖ rightBytes )
+ *   odd nodes are carried up unchanged (never duplicated).
+ */
+const ENC = new TextEncoder();
+export async function sha256Hex(input) {
+    const bytes = typeof input === "string" ? ENC.encode(input) : input;
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+function hexBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+export async function merkleLeafHash(leaf) {
+    return sha256Hex(concat(Uint8Array.of(0x00), ENC.encode(leaf)));
+}
+async function merkleNodeHash(leftHex, rightHex) {
+    return sha256Hex(concat(Uint8Array.of(0x01), hexBytes(leftHex), hexBytes(rightHex)));
+}
+/**
+ * Verify that `leaf` (the original leaf STRING — the canonical signed envelope)
+ * folds along `proof` into `root`. Never throws on a malformed proof.
+ */
+export async function verifyMerkleInclusion(leaf, proof, root) {
+    try {
+        if (typeof leaf !== "string")
+            return false;
+        return await verifyMerkleInclusionFromHash(await merkleLeafHash(leaf), proof, root);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The same fold, starting from a leaf HASH (hex) rather than the leaf string — for a proof whose leaf string is not
+ * available (a ledger proof for a redacted receipt). Never throws on a malformed proof.
+ */
+export async function verifyMerkleInclusionFromHash(leafHash, proof, root) {
+    try {
+        if (typeof leafHash !== "string" || typeof root !== "string" || !Array.isArray(proof))
+            return false;
+        const want = root.toLowerCase();
+        if (!SHA256_HEX.test(want) || !SHA256_HEX.test(leafHash.toLowerCase()))
+            return false;
+        let h = leafHash.toLowerCase();
+        for (const step of proof) {
+            if (!step || (step.position !== "left" && step.position !== "right"))
+                return false;
+            if (typeof step.sibling !== "string" || !SHA256_HEX.test(step.sibling.toLowerCase()))
+                return false;
+            const sibling = step.sibling.toLowerCase();
+            h = step.position === "left" ? await merkleNodeHash(sibling, h) : await merkleNodeHash(h, sibling);
+        }
+        return h === want;
+    }
+    catch {
+        return false;
+    }
+}