@entpoind/verify 0.1.0 → 0.2.0

package/dist/index.js

@@ -15,9 +15,12 @@
  * Deno, Bun, and Cloudflare Workers.
  */
 import { canonicalJcs } from "./canonical-json.js";
-import { verifyMerkleInclusion } from "./merkle.js";
+import { merkleLeafHash, sha256Hex, verifyMerkleInclusion, verifyMerkleInclusionFromHash } from "./merkle.js";
+import { checkLedgerWitness } from "./witness.js";
 export { canonicalJcs, NonCanonicalizableError } from "./canonical-json.js";
-export { merkleLeafHash, verifyMerkleInclusion } from "./merkle.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.
@@ -207,6 +210,132 @@ export async function verifyBundle(input, publicKeys) {
 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");

package/dist/merkle.d.ts

@@ -6,6 +6,7 @@
  *   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;
@@ -16,3 +17,8 @@ export type MerkleProofStep = {
  * 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

@@ -7,7 +7,7 @@
  *   odd nodes are carried up unchanged (never duplicated).
  */
 const ENC = new TextEncoder();
-async function sha256Hex(input) {
+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("");
@@ -40,12 +40,26 @@ async function merkleNodeHash(leftHex, rightHex) {
  */
 export async function verifyMerkleInclusion(leaf, proof, root) {
     try {
-        if (typeof leaf !== "string" || typeof root !== "string" || !Array.isArray(proof))
+        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))
+        if (!SHA256_HEX.test(want) || !SHA256_HEX.test(leafHash.toLowerCase()))
             return false;
-        let h = await merkleLeafHash(leaf);
+        let h = leafHash.toLowerCase();
         for (const step of proof) {
             if (!step || (step.position !== "left" && step.position !== "right"))
                 return false;

package/dist/witness.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @entpoind/verify — the receipt ledger's public witness: a batch root's entry in the Sigstore Rekor log.
+ *
+ * What the ledger logs (runtime/shared/rekor-witness.ts, by the hourly cron job):
+ *
+ *   rootMessage   the canonical JSON the batch's `rootSignature` is over (ledgerRootMessage)
+ *   A             SHA-512(UTF-8 rootMessage)            `witness.artifactSha512`
+ *   data.hash     SHA-512(A)                            `witness.rekorSha512`, the hash in the `hashedrekord` entry
+ *   signature     Ed25519ph by the region's receipt key, the SAME key (`kid`) as the root's, with A as the message,
+ *                 so its prehash is SHA-512(A) = data.hash
+ *
+ * Offline (always): the witness's hashes are recomputed from the root message, the witness is by the root's key, its
+ * Ed25519ph signature verifies over the recomputed hash with that key, and the copy of the log's answer the proof carries
+ * (`body`, `entryUuid`, `inclusionProof`) is that entry and hangs together. That copy came from Entpoind, so it shows the
+ * witness is consistent, not that the log holds it.
+ *
+ * Online (opt-in): the entry is fetched from the log itself and checked again, with the log's own inclusion proof,
+ * signed checkpoint and signed entry timestamp verified against the log's public key (ECDSA P-256, as rekor.sigstore.dev
+ * uses). The key is pinned by the caller, or fetched from the log, which is then trust on first use; the result says which.
+ *
+ * Nothing here can fail the receipt or the ledger proof: a witness that is absent, off, pending, inconsistent or
+ * unreachable is reported as exactly that, next to a ledger proof that verified on its own. `off` means the receipt's
+ * workspace had turned the public witness off before the receipt was batched: the batch's root was never submitted, by
+ * the workspace's choice. It is not a failure.
+ */
+export declare const WITNESS_KIND = "rekor.hashedrekord.v0.0.1";
+export declare const DEFAULT_REKOR_URL = "https://rekor.sigstore.dev";
+export declare const WITNESS_LOG_TIMEOUT_MS = 10000;
+/** `witness` in the ledger proof, as the Tools Worker serves it. */
+export type LedgerWitness = 
+/** The workspace had turned the public witness off when the batch was built; its root is never submitted. */
+{
+    status: "off";
+} | {
+    status: "pending";
+    since: string;
+    attempts: number;
+    lastError: string | null;
+    nextAttemptAt: string | null;
+} | {
+    status: "logged";
+    kind: string;
+    log: string;
+    logIndex: number;
+    entryUuid: string;
+    integratedTime: number;
+    integratedAt: string;
+    searchUrl: string;
+    entryUrl: string;
+    artifactSha512: string;
+    rekorSha512: string;
+    signature: string;
+    signatureKeyId: string;
+    logId: string;
+    body: string;
+    inclusionProof: {
+        logIndex: number;
+        rootHash: string;
+        treeSize: number;
+        hashes: string[];
+        checkpoint: string;
+    } | null;
+    signedEntryTimestamp: string;
+};
+/** Why a logged witness is not consistent with the ledger proof. Each is exact: several can be reported at once. */
+export type WitnessProblem = 
+/** A field the check needs is missing or of the wrong type. */
+"malformed_witness" | "unknown_witness_kind"
+/** `artifactSha512` is not SHA-512 of the root message. */
+ | "artifact_hash_mismatch"
+/** `rekorSha512` is not SHA-512 of the artifact: not the hash the root message gives. */
+ | "rekor_hash_mismatch"
+/** `signatureKeyId` is not the key that signed the root. */
+ | "not_the_root_key"
+/** The Ed25519ph signature does not verify over the recomputed hash with the root's key. */
+ | "bad_witness_signature"
+/** The log entry (`body`) is not a decodable `hashedrekord`. */
+ | "entry_body_malformed"
+/** The entry's `data.hash` is not `{ sha512, <the recomputed hash> }`. */
+ | "entry_hash_mismatch"
+/** The entry's public key is not the root's key. */
+ | "entry_key_mismatch"
+/** The entry's signature is not the witness signature. */
+ | "entry_signature_mismatch"
+/** `entryUuid` does not end in the RFC 6962 leaf hash of the entry. */
+ | "entry_uuid_mismatch"
+/** The copied inclusion proof does not fold the entry to the root hash it names. */
+ | "inclusion_proof_invalid"
+/** `integratedAt` is not the instant `integratedTime` names. */
+ | "integrated_at_mismatch";
+/** What the log itself said, when it was asked (`witnessLog`). */
+export type WitnessLogProblem = 
+/** The log has no entry with that UUID (404). */
+"entry_not_in_log" | "bad_log_response" | "entry_uuid_mismatch" | "entry_body_malformed" | "entry_hash_mismatch" | "entry_key_mismatch" | "bad_witness_signature"
+/** The log's `logIndex` / `integratedTime` are not the ones the proof states. */
+ | "log_index_mismatch" | "integrated_time_mismatch"
+/** The log's public key could not be fetched, is not ECDSA P-256, or does not hash to the entry's `logID`. */
+ | "log_key_unavailable" | "log_key_unsupported" | "log_key_not_log_id" | "bad_signed_entry_timestamp" | "no_inclusion_proof" | "inclusion_proof_invalid" | "checkpoint_malformed"
+/** The checkpoint names another tree size or root hash than the inclusion proof. */
+ | "checkpoint_mismatch" | "bad_checkpoint_signature";
+export type WitnessPart = "verified" | "failed" | "not_checked";
+export type WitnessLogCheck = 
+/** The log was not asked, or did not answer: nothing about the witness was judged. */
+{
+    checked: false;
+    logUrl: string;
+    reason: "log_url_not_https" | "no_entry_uuid" | "log_unreachable" | "log_error";
+    status?: number;
+} | {
+    checked: true;
+    logUrl: string;
+    /** True only when every part below is `verified` and there is no problem. */
+    ok: boolean;
+    problems: WitnessLogProblem[];
+    /** `pinned`: the caller's `logPublicKey`. `fetched`: from the log's own /api/v1/log/publicKey, trust on first use. */
+    logKey: "pinned" | "fetched" | "unavailable";
+    /** The log's time for the entry (Unix seconds), as the log answered. */
+    integratedTime: number | null;
+    inclusionProof: WitnessPart;
+    checkpoint: WitnessPart;
+    signedEntryTimestamp: WitnessPart;
+};
+export type WitnessReport = 
+/** The proof carries no witness: the batch has not been submitted yet, or the witness is not switched on. */
+{
+    status: "absent";
+}
+/**
+ * Not witnessed, by the workspace's choice: its owner or admin had turned the public witness off before this receipt was
+ * batched, so the batch's root was never submitted to the log. Not a failure, and nothing to retry.
+ */
+ | {
+    status: "off";
+}
+/** Tried, not in the log yet. The batch itself is complete. */
+ | {
+    status: "pending";
+    since: string | null;
+    attempts: number | null;
+    lastError: string | null;
+    nextAttemptAt: string | null;
+}
+/** A `witness` whose status is none of the three the API defines (`off`, `pending`, `logged`). */
+ | {
+    status: "malformed";
+} | {
+    status: "logged";
+    /** The witness is the root's: its hashes, key and signature, and the copy of the log's answer, all check out. */
+    consistent: boolean;
+    problems: WitnessProblem[];
+    log: string | null;
+    logIndex: number | null;
+    entryUuid: string | null;
+    integratedAt: string | null;
+    searchUrl: string | null;
+    /** Present only when the log was asked (`witnessLog`). */
+    logCheck?: WitnessLogCheck;
+};
+export type WitnessLogOptions = {
+    /** Overrides the proof's `witness.log`. Must be https. Default: the proof's, else https://rekor.sigstore.dev. */
+    logUrl?: string;
+    /** The log's public key (SubjectPublicKeyInfo PEM) to verify its signatures with. Without it, the key is fetched from the log. */
+    logPublicKey?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+export type WitnessContext = {
+    /** The message the root signature is over, rebuilt from the proof. */
+    rootMessage: string;
+    /** The root's key id, and its key from the published set (already used to verify the root). */
+    signatureKeyId: string;
+    publicKeyX: string;
+};
+/** Never throws: anything the witness holds that cannot be checked is a problem, reported. */
+export declare function checkLedgerWitness(witness: unknown, ctx: WitnessContext, log?: WitnessLogOptions): Promise<WitnessReport>;