@forestrie/receipt-verify 3.0.1 → 3.2.0

package/dist/select-ks256-attestation.js

@@ -0,0 +1,119 @@
+/**
+ * Choosing an ERC-1271 attestation from several (owner ruling D8,
+ * 2026-10-19). A contract KS256 root (a Safe) that rotated its delegate
+ * signs one certificate per delegate, and each certificate needs its own
+ * attestation; a caller holding a checkpoint chain or several receipts
+ * supplies them as a list. Each certificate takes the attestation whose
+ * `digest` AND `signatureHash` are that certificate's: keccak256 of its
+ * Sig_structure and keccak256 of its signature bytes.
+ *
+ * Selection never makes an attestation acceptable on its own:
+ * `verifyKs256DelegationCert` still checks address, digest, signature hash,
+ * genesis chain id and magic.
+ */
+import { keccak_256 } from "@noble/hashes/sha3";
+import { resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+import { extractKs256DelegationDigest } from "./verify-ks256-delegation.js";
+/**
+ * The attestation in `attestations` made for this certificate: the first
+ * whose `digest` equals the certificate digest and whose `signatureHash`
+ * equals keccak256 of the certificate signature.
+ *
+ * @param cert - From `extractKs256CertificateDigest` (delegation-cose) or
+ *   {@link extractKs256DelegationDigest}.
+ * @returns The first matching attestation, or `undefined` when none
+ *   matches. The verifiers go further: they try EVERY match in order and
+ *   keep the first that passes its own checks.
+ */
+export function selectKs256Attestation(cert, attestations) {
+    const i = selectKs256AttestationIndex(cert, attestations);
+    return i === undefined ? undefined : attestations[i];
+}
+function selectKs256AttestationIndex(cert, attestations) {
+    return matchingIndexes(cert, attestations)[0];
+}
+/**
+ * Resolve a COSE_Sign1's label-1000 certificate (a receipt or a checkpoint)
+ * under `rootKeys`, trying the supplied attestations made for it.
+ *
+ * Every attestation whose digest and signature hash match the certificate
+ * is tried in list order, and the first that resolves wins: a stale or
+ * wrong-chain copy listed before a good one must not mask it. When none
+ * resolves, the first failure is returned. When none matches at all, a
+ * DIAGNOSTIC stand-in (one with the right digest if any, else the first) is
+ * passed so a contract root fails with the precise
+ * `ks256_attestation_*_mismatch` reason rather than a bare
+ * `ks256_root_not_recovered`; a stand-in can never verify, because
+ * `verifyKs256DelegationCert` checks digest and signature hash. With one
+ * attestation supplied this is exactly the 3.1.0 behaviour of the singular
+ * `ks256Attestation` input.
+ *
+ * @returns The resolution; `selected`, the index of the attestation it was
+ *   resolved with (whether or not ecrecover made it unnecessary); and
+ *   `rejected`, the matching attestations tried that failed their own
+ *   checks (address, chain id, magic).
+ * @internal
+ */
+export async function resolveWithKs256Attestations(coseSign1Bytes, rootKeys, attestations, forestChainId) {
+    if (attestations.length === 0) {
+        return {
+            resolution: await resolveDelegatedVerifyKey(coseSign1Bytes, rootKeys),
+            rejected: [],
+        };
+    }
+    let cert = null;
+    try {
+        cert = extractKs256DelegationDigest(coseSign1Bytes);
+    }
+    catch {
+        // Not a KS256 certificate (or not a COSE_Sign1): no attestation can be
+        // made for it; the stand-in below is never consulted by an ES256 root.
+        cert = null;
+    }
+    const candidates = cert === null ? [] : matchingIndexes(cert, attestations);
+    const rejected = [];
+    let firstFailure;
+    for (const i of candidates) {
+        const resolution = await resolveDelegatedVerifyKey(coseSign1Bytes, rootKeys, { attestation: attestations[i], forestChainId });
+        if (resolution.kind !== "broken") {
+            return { resolution, selected: i, rejected };
+        }
+        firstFailure ??= resolution;
+        // Only an attestation's own checks make it "rejected"; any other
+        // failure is the certificate's and no other copy can change it.
+        if (!resolution.reason?.startsWith("ks256_attestation_"))
+            break;
+        rejected.push(i);
+    }
+    if (firstFailure !== undefined)
+        return { resolution: firstFailure, rejected };
+    const standIn = (cert !== null &&
+        attestations.find((a) => bytesEqual(a.digest, cert.digest))) ||
+        attestations[0];
+    return {
+        resolution: await resolveDelegatedVerifyKey(coseSign1Bytes, rootKeys, {
+            attestation: standIn,
+            forestChainId,
+        }),
+        rejected,
+    };
+}
+function matchingIndexes(cert, attestations) {
+    const signatureHash = keccak_256(cert.signature);
+    const out = [];
+    attestations.forEach((a, i) => {
+        if (bytesEqual(a.digest, cert.digest) &&
+            bytesEqual(a.signatureHash, signatureHash)) {
+            out.push(i);
+        }
+    });
+    return out;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let x = 0;
+    for (let i = 0; i < a.length; i++)
+        x |= a[i] ^ b[i];
+    return x === 0;
+}

package/dist/verify-grant-receipt-offline.d.ts

@@ -1,19 +1,22 @@
 import type { Grant } from "@forestrie/encoding";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import { type RootVerifyKey } from "./root-verify-key.js";
 import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
 export type VerifyGrantReceiptOfflineInput = {
     genesisCbor: Uint8Array;
     receiptCbor: Uint8Array;
     grant: Grant;
     idtimestampBe8: Uint8Array;
+    /** See {@link VerifyReceiptOfflineInput.ks256Attestation}. */
+    ks256Attestation?: Ks256Attestation;
+    /** See {@link VerifyReceiptOfflineInput.ks256Attestations}. */
+    ks256Attestations?: readonly Ks256Attestation[];
 };
 /**
  * Offline grant receipt verify (layers A–C, ADR-0045). Pure over bytes; no network.
  */
 export declare function verifyGrantReceiptOffline(input: VerifyGrantReceiptOfflineInput): Promise<ReceiptVerifyResult>;
-export type VerifyGrantReceiptOfflineWithKeysInput = Omit<VerifyGrantReceiptOfflineInput, "genesisCbor"> & {
-    /** Caller-known ES256 trust keys — see {@link VerifyReceiptOfflineWithKeysInput}. */
-    trustKeys: CryptoKey[];
-};
+export type VerifyGrantReceiptOfflineWithKeysInput = Omit<VerifyGrantReceiptOfflineInput, "genesisCbor"> & Pick<VerifyReceiptOfflineWithKeysInput, "trustKeys" | "forestGenesisCbor">;
 /**
  * {@link verifyGrantReceiptOffline} under caller-supplied trust keys instead of
  * the genesis trust root — see {@link verifyReceiptOfflineWithKeys} for the
@@ -31,6 +34,21 @@ export type VerifyReceiptOfflineInput = {
      */
     payload: Uint8Array;
     idtimestampBe8: Uint8Array;
+    /**
+     * ERC-1271 attestation for a KS256 contract root (plan-2610-03 D4). Used
+     * only when ecrecover doesn't match the root, and accepted only when it
+     * binds the root address, the certificate digest and the genesis chain id.
+     */
+    ks256Attestation?: Ks256Attestation;
+    /**
+     * Several attestations (owner ruling D8): the one whose digest and
+     * signature hash match the receipt's certificate is used
+     * ({@link selectKs256Attestation}). Combined with
+     * {@link ks256Attestation} when both are given. When none matches, one
+     * still reaches the KS256 check only to name the mismatch: it can never
+     * verify the certificate.
+     */
+    ks256Attestations?: readonly Ks256Attestation[];
 };
 /**
  * Offline verify of a receipt against the EXACT registered payload. The log
@@ -42,12 +60,19 @@ export type VerifyReceiptOfflineInput = {
 export declare function verifyReceiptOffline(input: VerifyReceiptOfflineInput): Promise<ReceiptVerifyResult>;
 export type VerifyReceiptOfflineWithKeysInput = Omit<VerifyReceiptOfflineInput, "genesisCbor"> & {
     /**
-     * Caller-known ES256 trust keys, tried in order. For a child-log receipt
+     * Caller-known trust keys, tried in order: ES256 `CryptoKey`s or KS256
+     * 20-byte addresses ({@link knownLogKeyFromBytes}). For a child-log receipt
      * this is the log OWNER's key (the delegation-cert issuer), NOT the sealer
      * key — the label-1000 cert is verified under these keys and the delegated
      * sealer key is extracted from it, so the anchor survives sealer rotation.
      */
-    trustKeys: CryptoKey[];
+    trustKeys: RootVerifyKey[];
+    /**
+     * The forest's genesis, read only for the chain id a `ks256Attestation`
+     * must match (D6); it supplies no trust keys. Without it an attestation is
+     * refused with `ks256_attestation_chain_unbound`.
+     */
+    forestGenesisCbor?: Uint8Array;
 };
 /**
  * {@link verifyReceiptOffline} under caller-supplied trust keys instead of the

package/dist/verify-grant-receipt-offline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-grant-receipt-offline.d.ts","sourceRoot":"","sources":["../src/verify-grant-receipt-offline.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAUjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,UAAU,CAAC;CAC5B,CAAC;AA4EF;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,MAAM,MAAM,sCAAsC,GAAG,IAAI,CACvD,8BAA8B,EAC9B,aAAa,CACd,GAAG;IACF,qFAAqF;IACrF,SAAS,EAAE,SAAS,EAAE,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,sCAAsC,GAC5C,OAAO,CAAC,mBAAmB,CAAC,CAa9B;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB;;;;;OAKG;IACH,OAAO,EAAE,UAAU,CAAC;IACpB,cAAc,EAAE,UAAU,CAAC;CAC5B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAa9B;AAED,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAClD,yBAAyB,EACzB,aAAa,CACd,GAAG;IACF;;;;;OAKG;IACH,SAAS,EAAE,SAAS,EAAE,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,mBAAmB,CAAC,CAa9B"}
+{"version":3,"file":"verify-grant-receipt-offline.d.ts","sourceRoot":"","sources":["../src/verify-grant-receipt-offline.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAIjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAOhF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,UAAU,CAAC;IAC3B,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD,CAAC;AA4EF;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAe9B;AAED,MAAM,MAAM,sCAAsC,GAAG,IAAI,CACvD,8BAA8B,EAC9B,aAAa,CACd,GACC,IAAI,CAAC,iCAAiC,EAAE,WAAW,GAAG,mBAAmB,CAAC,CAAC;AAE7E;;;;GAIG;AACH,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,sCAAsC,GAC5C,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB;;;;;OAKG;IACH,OAAO,EAAE,UAAU,CAAC;IACpB,cAAc,EAAE,UAAU,CAAC;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAClD,yBAAyB,EACzB,aAAa,CACd,GAAG;IACF;;;;;;OAMG;IACH,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,mBAAmB,CAAC,CAiB9B"}

package/dist/verify-grant-receipt-offline.js

@@ -2,11 +2,13 @@ import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
 import { calculateRoot, verifyInclusion, } from "@forestrie/merklelog";
 import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
 import { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
-import { es256ReceiptVerifyKeys } from "./decode-trust-root-cbor.js";
-import { checkDelegationConstraints, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+import { isParsedKs256RootKey } from "./root-verify-key.js";
+import { checkDelegationConstraints, } from "./resolve-delegated-verify-key.js";
 import { univocityLeafHash } from "./leaf-commitment.js";
 import { parseReceipt } from "./parse-receipt.js";
 import { SubtleHasher } from "./subtle-hasher.js";
+import { resolveWithKs256Attestations } from "./select-ks256-attestation.js";
 function readIdtimestampBe8(bytes) {
     if (!bytes || bytes.length < 8) {
         throw new Error("idtimestamp required for receipt verification (8 bytes)");
@@ -72,6 +74,7 @@ export async function verifyGrantReceiptOffline(input) {
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner,
+        ks256Attestations: attestationCandidates(input),
     });
 }
 /**
@@ -92,6 +95,10 @@ export async function verifyGrantReceiptOfflineWithKeys(input) {
         idtimestampBe8: input.idtimestampBe8,
         inner,
         trustKeys: input.trustKeys,
+        ks256Attestations: attestationCandidates(input),
+        forestChainId: input.forestGenesisCbor
+            ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+            : undefined,
     });
 }
 /**
@@ -108,6 +115,7 @@ export async function verifyReceiptOffline(input) {
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner,
+        ks256Attestations: attestationCandidates(input),
     });
 }
 /**
@@ -134,8 +142,34 @@ export async function verifyReceiptOfflineWithKeys(input) {
         idtimestampBe8: input.idtimestampBe8,
         inner,
         trustKeys: input.trustKeys,
+        ks256Attestations: attestationCandidates(input),
+        forestChainId: input.forestGenesisCbor
+            ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+            : undefined,
     });
 }
+/**
+ * Every attestation the caller supplied: the list, then the singular field
+ * (kept for 3.1.0 callers).
+ */
+function attestationCandidates(input) {
+    return [
+        ...(input.ks256Attestations ?? []),
+        ...(input.ks256Attestation ? [input.ks256Attestation] : []),
+    ];
+}
+/**
+ * The forest's chain id from its genesis chain binding, or `undefined` when
+ * the genesis carries none (an attestation then can't be bound, D6).
+ */
+function genesisChainIdOrUndefined(genesisCbor) {
+    try {
+        return BigInt(decodeChainBindingFromGenesis(genesisCbor).chainId);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Shared offline-verify core: reconstruct the leaf as
  * `univocityLeafHash(idtimestamp, inner)`, resolve the (possibly delegated,
@@ -151,21 +185,21 @@ async function verifyReceiptOfflineWithLeafInner(input) {
     catch {
         return { ok: false, stage: "parse", reason: "genesis_invalid" };
     }
-    const verifyKeys = es256ReceiptVerifyKeys([trustRoot]);
-    if (!verifyKeys.length) {
-        return { ok: false, stage: "signature", reason: "no_es256_trust_key" };
-    }
     return verifyReceiptOfflineWithLeafInnerKeys({
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner: input.inner,
-        trustKeys: verifyKeys,
+        trustKeys: [trustRoot],
+        ks256Attestations: input.ks256Attestations,
+        forestChainId: genesisChainIdOrUndefined(input.genesisCbor),
     });
 }
 /**
  * Trust-key-parameterised offline-verify core. Identical to the genesis path
  * once the trust keys are in hand: resolve the (possibly delegated, FOR-297)
- * verify key against `trustKeys`, then check signature + inclusion.
+ * verify key against `trustKeys`, then check signature + inclusion. Receipts
+ * are always ES256, so a KS256 trust key only ever verifies the delegation
+ * certificate; only ES256 trust keys are tried on the receipt itself.
  */
 async function verifyReceiptOfflineWithLeafInnerKeys(input) {
     let parsed;
@@ -183,13 +217,30 @@ async function verifyReceiptOfflineWithLeafInnerKeys(input) {
     // delegated key first. A cert present but not chaining to a trust key is a
     // hard failure — do not silently fall back to the trust key (which cannot
     // verify a delegated-signed receipt anyway).
-    const delegation = await resolveDelegatedVerifyKey(input.receiptCbor, input.trustKeys);
+    // D8: the attestations made for THIS receipt's certificate (digest and
+    // signature hash), tried in order; none matching, a stand-in only names
+    // the mismatch.
+    const { resolution: delegation } = await resolveWithKs256Attestations(input.receiptCbor, input.trustKeys, input.ks256Attestations, input.forestChainId);
     if (delegation.kind === "broken") {
-        return { ok: false, stage: "signature", reason: "delegation_invalid" };
+        return {
+            ok: false,
+            stage: "signature",
+            reason: delegation.reason ?? "delegation_invalid",
+        };
+    }
+    const es256TrustKeys = input.trustKeys.filter((k) => !isParsedKs256RootKey(k));
+    if (delegation.kind === "root-only" && !es256TrustKeys.length) {
+        // A KS256 root never signs a receipt; without a certificate there is no
+        // ES256 key to check it with.
+        return {
+            ok: false,
+            stage: "signature",
+            reason: "ks256_root_requires_delegation",
+        };
     }
     const allVerifyKeys = delegation.kind === "resolved"
-        ? [delegation.delegatedKey, ...input.trustKeys]
-        : input.trustKeys;
+        ? [delegation.delegatedKey, ...es256TrustKeys]
+        : es256TrustKeys;
     let idtimestamp;
     try {
         idtimestamp = readIdtimestampBe8(input.idtimestampBe8);

package/dist/verify-ks256-delegation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Offline KS256 root → delegation certificate check (plan-2610-03 D4, D5;
+ * protocol ADR-0045 amendment 2026-10-18). Receipts are always ES256, signed
+ * by a sealer's P-256 delegated key; what a KS256 root changes is how the
+ * label-1000 delegation certificate is checked against it.
+ *
+ * - An EOA root verifies by ecrecover through `@forestrie/delegation-cose`'s
+ *   `verifyDelegationCertificateKs256` with no hooks: pure, the same guarantee
+ *   as an ES256 root. delegation-cose also enforces the KS256 alg binding.
+ * - Anything ecrecover doesn't match (a contract root such as a Safe, or a
+ *   wrong signer: offline you can't tell which) fails with
+ *   `ks256_root_not_recovered`, unless the caller supplies an ERC-1271
+ *   attestation (ks256-attestation.ts) bound to this root, this digest, this
+ *   signature and the forest's genesis chain.
+ *
+ * No network and no injected callback: the chain read is a separate helper's
+ * job (forestrie-cli, mcp-resolve), as for the known accumulator.
+ */
+import { type Ks256CertificateDigest } from "@forestrie/delegation-cose";
+import { type Ks256Attestation } from "./ks256-attestation.js";
+/**
+ * Chain evidence a caller may supply for a KS256 contract root. `forestChainId`
+ * is read from the forest's genesis, never from the attestation or a
+ * coordinator; an attestation without it is refused.
+ */
+export type Ks256DelegationEvidence = {
+    attestation?: Ks256Attestation | undefined;
+    forestChainId?: bigint | undefined;
+};
+/**
+ * Check a delegation certificate against a KS256 root address.
+ *
+ * @param certBytes - The receipt's label-1000 COSE_Sign1 certificate.
+ * @param rootAddress - 20-byte root from genesis or a caller-known log key.
+ * @param evidence - Optional ERC-1271 attestation and the genesis chain id.
+ * @returns `ok`, or a stable reason: `delegation_not_ks256` (wrong alg,
+ *   WebAuthn envelope or malformed), `ks256_root_not_recovered`, or a
+ *   `ks256_attestation_*` mismatch.
+ */
+export declare function verifyKs256DelegationCert(certBytes: Uint8Array, rootAddress: Uint8Array, evidence: Ks256DelegationEvidence): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Extract the KS256 delegation certificate's root address, digest and
+ * signature from a receipt: what an ERC-1271 attestation helper calls
+ * `isValidSignature` with. Does not verify anything.
+ *
+ * @param receiptCbor - COSE_Sign1 receipt bytes.
+ * @returns `null` when the receipt carries no label-1000 certificate.
+ * @throws When the certificate is not a KS256 certificate.
+ */
+export declare function extractKs256DelegationDigest(receiptCbor: Uint8Array): Ks256CertificateDigest | null;
+//# sourceMappingURL=verify-ks256-delegation.d.ts.map

package/dist/verify-ks256-delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-ks256-delegation.d.ts","sourceRoot":"","sources":["../src/verify-ks256-delegation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAKhC;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAiCvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,UAAU,GACtB,sBAAsB,GAAG,IAAI,CAQ/B"}

package/dist/verify-ks256-delegation.js

@@ -0,0 +1,95 @@
+/**
+ * Offline KS256 root → delegation certificate check (plan-2610-03 D4, D5;
+ * protocol ADR-0045 amendment 2026-10-18). Receipts are always ES256, signed
+ * by a sealer's P-256 delegated key; what a KS256 root changes is how the
+ * label-1000 delegation certificate is checked against it.
+ *
+ * - An EOA root verifies by ecrecover through `@forestrie/delegation-cose`'s
+ *   `verifyDelegationCertificateKs256` with no hooks: pure, the same guarantee
+ *   as an ES256 root. delegation-cose also enforces the KS256 alg binding.
+ * - Anything ecrecover doesn't match (a contract root such as a Safe, or a
+ *   wrong signer: offline you can't tell which) fails with
+ *   `ks256_root_not_recovered`, unless the caller supplies an ERC-1271
+ *   attestation (ks256-attestation.ts) bound to this root, this digest, this
+ *   signature and the forest's genesis chain.
+ *
+ * No network and no injected callback: the chain read is a separate helper's
+ * job (forestrie-cli, mcp-resolve), as for the known accumulator.
+ */
+import { coseUnprotectedToMap, decodeCoseSign1 } from "@forestrie/encoding";
+import { extractKs256CertificateDigest, verifyDelegationCertificateKs256, } from "@forestrie/delegation-cose";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { ERC1271_MAGIC_VALUE, } from "./ks256-attestation.js";
+/** Unprotected header label carrying the delegation certificate. */
+const DELEGATION_CERT_LABEL = 1000;
+/**
+ * Check a delegation certificate against a KS256 root address.
+ *
+ * @param certBytes - The receipt's label-1000 COSE_Sign1 certificate.
+ * @param rootAddress - 20-byte root from genesis or a caller-known log key.
+ * @param evidence - Optional ERC-1271 attestation and the genesis chain id.
+ * @returns `ok`, or a stable reason: `delegation_not_ks256` (wrong alg,
+ *   WebAuthn envelope or malformed), `ks256_root_not_recovered`, or a
+ *   `ks256_attestation_*` mismatch.
+ */
+export async function verifyKs256DelegationCert(certBytes, rootAddress, evidence) {
+    let parts;
+    try {
+        parts = extractKs256CertificateDigest(certBytes);
+    }
+    catch {
+        return { ok: false, reason: "delegation_not_ks256" };
+    }
+    if (await verifyDelegationCertificateKs256(certBytes, rootAddress)) {
+        return { ok: true };
+    }
+    const { attestation, forestChainId } = evidence;
+    if (!attestation) {
+        return { ok: false, reason: "ks256_root_not_recovered" };
+    }
+    if (!bytesEqual(attestation.address, rootAddress)) {
+        return { ok: false, reason: "ks256_attestation_address_mismatch" };
+    }
+    if (!bytesEqual(attestation.digest, parts.digest)) {
+        return { ok: false, reason: "ks256_attestation_digest_mismatch" };
+    }
+    if (!bytesEqual(attestation.signatureHash, keccak_256(parts.signature))) {
+        return { ok: false, reason: "ks256_attestation_signature_mismatch" };
+    }
+    if (forestChainId === undefined) {
+        return { ok: false, reason: "ks256_attestation_chain_unbound" };
+    }
+    if (attestation.chainId !== forestChainId) {
+        return { ok: false, reason: "ks256_attestation_chain_mismatch" };
+    }
+    if (!bytesEqual(attestation.magic, ERC1271_MAGIC_VALUE)) {
+        return { ok: false, reason: "ks256_attestation_magic_invalid" };
+    }
+    return { ok: true };
+}
+/**
+ * Extract the KS256 delegation certificate's root address, digest and
+ * signature from a receipt: what an ERC-1271 attestation helper calls
+ * `isValidSignature` with. Does not verify anything.
+ *
+ * @param receiptCbor - COSE_Sign1 receipt bytes.
+ * @returns `null` when the receipt carries no label-1000 certificate.
+ * @throws When the certificate is not a KS256 certificate.
+ */
+export function extractKs256DelegationDigest(receiptCbor) {
+    const decoded = decodeCoseSign1(receiptCbor);
+    if (!decoded)
+        throw new Error("receipt is not a COSE_Sign1");
+    const certRaw = coseUnprotectedToMap(decoded.unprotected).get(DELEGATION_CERT_LABEL);
+    if (!(certRaw instanceof Uint8Array) || certRaw.length === 0)
+        return null;
+    return extractKs256CertificateDigest(certRaw);
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let x = 0;
+    for (let i = 0; i < a.length; i++)
+        x |= a[i] ^ b[i];
+    return x === 0;
+}

package/dist/verify-receipt-against-checkpoint-chain.d.ts

@@ -0,0 +1,42 @@
+import type { CheckpointChainReceiptOutcome } from "./checkpoint-chain-receipt-outcome.js";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import type { RootVerifyKey } from "./root-verify-key.js";
+/** Input to {@link verifyReceiptAgainstCheckpointChain}. */
+export type VerifyReceiptAgainstCheckpointChainInput = {
+    receiptCbor: Uint8Array;
+    /** The leaf's idtimestamp; the last 8 bytes are used (big-endian). */
+    idtimestampBe8: Uint8Array;
+    /** Leaf ContentHash: SHA-256(payload), or the grant commitment hash. */
+    inner: Uint8Array;
+    /** Retained checkpoints in fold (ascending size) order. */
+    checkpoints: readonly Uint8Array[];
+    /** ES256 keys and KS256 addresses, from genesis or caller-known keys. */
+    rootKeys: readonly RootVerifyKey[];
+    /** ERC-1271 attestations, one per contract-root certificate. */
+    attestations?: readonly Ks256Attestation[] | undefined;
+    /**
+     * The forest genesis, read only for its chain id (attestations must
+     * match it). Give this or {@link forestChainId}; both must agree.
+     */
+    forestGenesisCbor?: Uint8Array | undefined;
+    forestChainId?: bigint | undefined;
+    /** Trusted base for a suffix chain; see `verifyCheckpointChain`. */
+    trustedBase?: {
+        size: bigint;
+        accumulator: Uint8Array[];
+    } | undefined;
+};
+/**
+ * Verify a receipt against a retained checkpoint chain.
+ *
+ * The receipt's own signature is not checked: the authenticated chain is
+ * the authority, and the peak is ALWAYS recomputed from the leaf
+ * (`idtimestamp ‖ inner`) and the inclusion path, never taken from an
+ * attached payload. A match binds the leaf's idtimestamp (through the leaf
+ * hash) and its mmrIndex (through the matched peak's POSITION, which must be
+ * the node the inclusion walk reaches: the leaf hash alone does not commit
+ * its position, and an empty path commits none).
+ * Links are searched newest first; the newest cover is reported.
+ */
+export declare function verifyReceiptAgainstCheckpointChain(input: VerifyReceiptAgainstCheckpointChainInput): Promise<CheckpointChainReceiptOutcome>;
+//# sourceMappingURL=verify-receipt-against-checkpoint-chain.d.ts.map

package/dist/verify-receipt-against-checkpoint-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-receipt-against-checkpoint-chain.d.ts","sourceRoot":"","sources":["../src/verify-receipt-against-checkpoint-chain.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,uCAAuC,CAAC;AAM3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,4DAA4D;AAC5D,MAAM,MAAM,wCAAwC,GAAG;IACrD,WAAW,EAAE,UAAU,CAAC;IACxB,sEAAsE;IACtE,cAAc,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IACnC,yEAAyE;IACzE,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,gEAAgE;IAChE,YAAY,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAAC;IACvD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,oEAAoE;IACpE,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,UAAU,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACvE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,mCAAmC,CACvD,KAAK,EAAE,wCAAwC,GAC9C,OAAO,CAAC,6BAA6B,CAAC,CA0KxC"}