@forestrie/receipt-verify 0.6.0 → 0.6.1

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export type { ReceiptVerifyResult, ReceiptVerifyStage, } from "./receipt-verify-
 /** Canonical grant wire type — owned by @forestrie/encoding (FOR-353, ADR-0048). */
 export type { Grant } from "@forestrie/encoding";
 export type { VerifyGrantReceiptOfflineInput } from "./verify-grant-receipt-offline.js";
+export type { VerifyReceiptOfflineInput } from "./verify-grant-receipt-offline.js";
 export { parseReceipt } from "./parse-receipt.js";
 export type { BuildReceiptOfflineInput, ComputedAccumulatorPeak, MassifNodeStore, ParsedCheckpoint, } from "./build-receipt-offline.js";
 export { buildReceiptOffline, computeAccumulatorPeak, openMassifNodeStore, parseCheckpoint, } from "./build-receipt-offline.js";
@@ -12,6 +13,7 @@ export { buildReceiptOffline, computeAccumulatorPeak, openMassifNodeStore, parse
 export { peakMMRIndexes } from "@forestrie/merklelog";
 export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
 export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
+export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
 export { decodeForestrieGrantCose } from "./decode-forestrie-grant-cose.js";
 export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 /** Deterministic receipt construction (plan-2607-12 Phase 2, FOR-353). */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,YAAY,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@ export { buildReceiptOffline, computeAccumulatorPeak, openMassifNodeStore, parse
 export { peakMMRIndexes } from "@forestrie/merklelog";
 export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
 export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
+export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
 export { decodeForestrieGrantCose } from "./decode-forestrie-grant-cose.js";
 export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 /** Deterministic receipt construction (plan-2607-12 Phase 2, FOR-353). */

package/dist/resolve-delegated-verify-key.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Offline delegation-chain resolution (FOR-297). When a checkpoint/receipt was
+ * signed by a DELEGATED key rather than the log's root key, the delegation
+ * certificate travels in the receipt's unprotected header at label 1000
+ * (sealer-embedded). This module verifies that certificate under the genesis
+ * trust root and returns the delegated public key as an additional verify
+ * candidate — the offline port of canopy-api's `resolveReceiptVerifyKey`.
+ *
+ * ES256 (P-256) only: the offline verifier is ES256-only (genesis alg), and
+ * sealer delegate keys are always secp256r1. KS256-rooted delegation is a
+ * server-only concern.
+ *
+ * Note (parity with the server port source): this establishes that the root
+ * authorized the delegated key, but does NOT yet enforce the certificate's MMR
+ * window or expiry-at-issuance against the leaf — that hardening is shared with
+ * the server path and tracked separately (FOR-323).
+ */
+/**
+ * root-only: no delegation cert present — verify against the root keys as-is.
+ * resolved: cert verified under a root key; use `delegatedKey` first.
+ * broken: a cert is present but did not verify under the root, or its delegated
+ *   key could not be parsed — the delegation chain is invalid.
+ */
+export type DelegatedResolution = {
+    kind: "root-only";
+} | {
+    kind: "resolved";
+    delegatedKey: CryptoKey;
+} | {
+    kind: "broken";
+};
+/**
+ * Resolve the delegated verify key from a receipt's delegation certificate.
+ *
+ * @param receiptCbor - the COSE_Sign1 receipt bytes.
+ * @param rootKeys - genesis-derived ES256 root verify keys.
+ */
+export declare function resolveDelegatedVerifyKey(receiptCbor: Uint8Array, rootKeys: CryptoKey[]): Promise<DelegatedResolution>;
+//# sourceMappingURL=resolve-delegated-verify-key.d.ts.map

package/dist/resolve-delegated-verify-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-delegated-verify-key.d.ts","sourceRoot":"","sources":["../src/resolve-delegated-verify-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAuBH;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,SAAS,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAqEvB;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,mBAAmB,CAAC,CA4B9B"}

package/dist/resolve-delegated-verify-key.js

@@ -0,0 +1,122 @@
+/**
+ * Offline delegation-chain resolution (FOR-297). When a checkpoint/receipt was
+ * signed by a DELEGATED key rather than the log's root key, the delegation
+ * certificate travels in the receipt's unprotected header at label 1000
+ * (sealer-embedded). This module verifies that certificate under the genesis
+ * trust root and returns the delegated public key as an additional verify
+ * candidate — the offline port of canopy-api's `resolveReceiptVerifyKey`.
+ *
+ * ES256 (P-256) only: the offline verifier is ES256-only (genesis alg), and
+ * sealer delegate keys are always secp256r1. KS256-rooted delegation is a
+ * server-only concern.
+ *
+ * Note (parity with the server port source): this establishes that the root
+ * authorized the delegated key, but does NOT yet enforce the certificate's MMR
+ * window or expiry-at-issuance against the leaf — that hardening is shared with
+ * the server path and tracked separately (FOR-323).
+ */
+import { coseUnprotectedToMap, decodeCborDeterministic, decodeCoseSign1, verifyCoseSign1WithParsedKey, } from "@forestrie/encoding";
+/** Unprotected header label carrying the delegation certificate. */
+const DELEGATION_CERT_LABEL = 1000;
+/** COSE_Key labels (RFC 9052) and EC2/P-256 constants. */
+const COSE_KEY_KTY = 1;
+const COSE_KEY_CRV = -1;
+const COSE_KEY_X = -2;
+const COSE_KEY_Y = -3;
+const COSE_KTY_EC2 = 2;
+const COSE_CRV_P256 = 1;
+/** Delegation-cert payload label for the delegated COSE_Key. */
+const PAYLOAD_DELEGATED_KEY = 5;
+function extractDelegationCertBytes(unprotected) {
+    const umap = coseUnprotectedToMap(unprotected);
+    const certRaw = umap.get(DELEGATION_CERT_LABEL);
+    return certRaw instanceof Uint8Array && certRaw.length > 0 ? certRaw : null;
+}
+function labelGetter(map) {
+    if (map instanceof Map)
+        return (label) => map.get(label);
+    if (typeof map === "object" && map !== null) {
+        const obj = map;
+        return (label) => obj[label] ?? obj[String(label)];
+    }
+    return null;
+}
+function parseCoseKeyEC2(keyMap) {
+    const get = labelGetter(keyMap);
+    if (!get)
+        return null;
+    const kty = get(COSE_KEY_KTY);
+    if (kty !== COSE_KTY_EC2 && kty !== BigInt(COSE_KTY_EC2))
+        return null;
+    const crv = get(COSE_KEY_CRV);
+    if (crv !== COSE_CRV_P256 && crv !== BigInt(COSE_CRV_P256))
+        return null;
+    const x = get(COSE_KEY_X);
+    const y = get(COSE_KEY_Y);
+    if (!(x instanceof Uint8Array) || x.length !== 32)
+        return null;
+    if (!(y instanceof Uint8Array) || y.length !== 32)
+        return null;
+    return { x, y };
+}
+async function importDelegatedKey(keyMap) {
+    const parsed = parseCoseKeyEC2(keyMap);
+    if (!parsed)
+        return null;
+    const uncompressed = new Uint8Array(65);
+    uncompressed[0] = 0x04;
+    uncompressed.set(parsed.x, 1);
+    uncompressed.set(parsed.y, 33);
+    try {
+        return await crypto.subtle.importKey("raw", uncompressed, { name: "ECDSA", namedCurve: "P-256" }, true, ["verify"]);
+    }
+    catch {
+        return null;
+    }
+}
+function extractDelegatedKeyFromPayload(payloadBytes) {
+    if (!payloadBytes || payloadBytes.length === 0)
+        return null;
+    let payloadMap;
+    try {
+        payloadMap = decodeCborDeterministic(payloadBytes);
+    }
+    catch {
+        return null;
+    }
+    const get = labelGetter(payloadMap);
+    return get ? get(PAYLOAD_DELEGATED_KEY) : null;
+}
+/**
+ * Resolve the delegated verify key from a receipt's delegation certificate.
+ *
+ * @param receiptCbor - the COSE_Sign1 receipt bytes.
+ * @param rootKeys - genesis-derived ES256 root verify keys.
+ */
+export async function resolveDelegatedVerifyKey(receiptCbor, rootKeys) {
+    const decoded = decodeCoseSign1(receiptCbor);
+    if (!decoded)
+        return { kind: "root-only" };
+    const certBytes = extractDelegationCertBytes(decoded.unprotected);
+    if (!certBytes)
+        return { kind: "root-only" };
+    let verified = false;
+    for (const rootKey of rootKeys) {
+        if (await verifyCoseSign1WithParsedKey(certBytes, rootKey, {
+            logPrefix: "delegation-cert-offline",
+        })) {
+            verified = true;
+            break;
+        }
+    }
+    if (!verified)
+        return { kind: "broken" };
+    const certDecoded = decodeCoseSign1(certBytes);
+    if (!certDecoded)
+        return { kind: "broken" };
+    const keyRaw = extractDelegatedKeyFromPayload(certDecoded.payloadBstr);
+    const delegatedKey = keyRaw ? await importDelegatedKey(keyRaw) : null;
+    if (!delegatedKey)
+        return { kind: "broken" };
+    return { kind: "resolved", delegatedKey };
+}

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

@@ -10,4 +10,24 @@ export type VerifyGrantReceiptOfflineInput = {
  * Offline grant receipt verify (layers A–C, ADR-0045). Pure over bytes; no network.
  */
 export declare function verifyGrantReceiptOffline(input: VerifyGrantReceiptOfflineInput): Promise<ReceiptVerifyResult>;
+export type VerifyReceiptOfflineInput = {
+    genesisCbor: Uint8Array;
+    receiptCbor: Uint8Array;
+    /**
+     * The EXACT registered payload bytes whose SHA-256 is the leaf ContentHash.
+     * Kind-agnostic: for a SCITT signed statement this is the statement COSE
+     * bytes; for a forestrie grant leaf it is the grant commitment preimage
+     * (see {@link verifyGrantReceiptOffline}, which derives it).
+     */
+    payload: Uint8Array;
+    idtimestampBe8: Uint8Array;
+};
+/**
+ * Offline verify of a receipt against the EXACT registered payload. The log
+ * leaf commits `SHA-256(idtimestamp ‖ SHA-256(payload))`; this is the standard,
+ * COSE-Receipts-conformant path (a SCITT statement receipt is exactly this with
+ * `payload` = the signed statement). Genesis trust root, FOR-297 delegation
+ * resolution, inclusion, and signature are all standard.
+ */
+export declare function verifyReceiptOffline(input: VerifyReceiptOfflineInput): Promise<ReceiptVerifyResult>;
 //# sourceMappingURL=verify-grant-receipt-offline.d.ts.map

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;AAMjD,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,CA2C9B"}
+{"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;AAOjD,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,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"}

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

@@ -3,6 +3,7 @@ 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 { resolveDelegatedVerifyKey } from "./resolve-delegated-verify-key.js";
 import { univocityLeafHash } from "./leaf-commitment.js";
 import { parseReceipt } from "./parse-receipt.js";
 import { SubtleHasher } from "./subtle-hasher.js";
@@ -58,6 +59,45 @@ async function verifySignatureAndInclusion(opts) {
  * Offline grant receipt verify (layers A–C, ADR-0045). Pure over bytes; no network.
  */
 export async function verifyGrantReceiptOffline(input) {
+    // A GRANT leaf commits the grant commitment hash (register-grant / create-log).
+    let inner;
+    try {
+        inner = await grantCommitmentHashFromGrant(input.grant);
+    }
+    catch {
+        return { ok: false, stage: "binding", reason: "grant_invalid" };
+    }
+    return verifyReceiptOfflineWithLeafInner({
+        genesisCbor: input.genesisCbor,
+        receiptCbor: input.receiptCbor,
+        idtimestampBe8: input.idtimestampBe8,
+        inner,
+    });
+}
+/**
+ * Offline verify of a receipt against the EXACT registered payload. The log
+ * leaf commits `SHA-256(idtimestamp ‖ SHA-256(payload))`; this is the standard,
+ * COSE-Receipts-conformant path (a SCITT statement receipt is exactly this with
+ * `payload` = the signed statement). Genesis trust root, FOR-297 delegation
+ * resolution, inclusion, and signature are all standard.
+ */
+export async function verifyReceiptOffline(input) {
+    const inner = new Uint8Array(await crypto.subtle.digest("SHA-256", input.payload));
+    return verifyReceiptOfflineWithLeafInner({
+        genesisCbor: input.genesisCbor,
+        receiptCbor: input.receiptCbor,
+        idtimestampBe8: input.idtimestampBe8,
+        inner,
+    });
+}
+/**
+ * Shared offline-verify core: reconstruct the leaf as
+ * `univocityLeafHash(idtimestamp, inner)`, resolve the (possibly delegated,
+ * FOR-297) verify key from the genesis trust root, and check signature +
+ * inclusion. `inner` is the leaf ContentHash = `SHA-256(payload)` — the grant
+ * commitment for a grant leaf, or `SHA-256(statement)` for a statement leaf.
+ */
+async function verifyReceiptOfflineWithLeafInner(input) {
     let parsed;
     try {
         parsed = parseReceipt(input.receiptCbor);
@@ -76,13 +116,18 @@ export async function verifyGrantReceiptOffline(input) {
     if (!verifyKeys.length) {
         return { ok: false, stage: "signature", reason: "no_es256_trust_key" };
     }
-    let inner;
-    try {
-        inner = await grantCommitmentHashFromGrant(input.grant);
-    }
-    catch {
-        return { ok: false, stage: "binding", reason: "grant_invalid" };
+    // FOR-297: when the receipt was signed by a DELEGATED key, verify the
+    // label-1000 delegation certificate under the root and try the delegated key
+    // first. A cert present but not chaining to the root is a hard failure — do
+    // not silently fall back to the root key (which cannot verify a
+    // delegated-signed receipt anyway).
+    const delegation = await resolveDelegatedVerifyKey(input.receiptCbor, verifyKeys);
+    if (delegation.kind === "broken") {
+        return { ok: false, stage: "signature", reason: "delegation_invalid" };
     }
+    const allVerifyKeys = delegation.kind === "resolved"
+        ? [delegation.delegatedKey, ...verifyKeys]
+        : verifyKeys;
     let idtimestamp;
     try {
         idtimestamp = readIdtimestampBe8(input.idtimestampBe8);
@@ -90,12 +135,12 @@ export async function verifyGrantReceiptOffline(input) {
     catch {
         return { ok: false, stage: "binding", reason: "idtimestamp_invalid" };
     }
-    const leafHash = await univocityLeafHash(idtimestamp, inner);
+    const leafHash = await univocityLeafHash(idtimestamp, input.inner);
     return verifySignatureAndInclusion({
         receiptCbor: input.receiptCbor,
         explicitPeak: parsed.explicitPeak,
         proof: parsed.proof,
         leafHash,
-        verifyKeys: verifyKeys,
+        verifyKeys: allVerifyKeys,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",

package/src/index.ts

@@ -5,6 +5,7 @@ export type {
 /** Canonical grant wire type — owned by @forestrie/encoding (FOR-353, ADR-0048). */
 export type { Grant } from "@forestrie/encoding";
 export type { VerifyGrantReceiptOfflineInput } from "./verify-grant-receipt-offline.js";
+export type { VerifyReceiptOfflineInput } from "./verify-grant-receipt-offline.js";
 export { parseReceipt } from "./parse-receipt.js";
 export type {
   BuildReceiptOfflineInput,
@@ -25,6 +26,7 @@ export {
 export { peakMMRIndexes } from "@forestrie/merklelog";
 export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
 export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
+export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
 export { decodeForestrieGrantCose } from "./decode-forestrie-grant-cose.js";
 export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 

package/src/resolve-delegated-verify-key.ts

@@ -0,0 +1,155 @@
+/**
+ * Offline delegation-chain resolution (FOR-297). When a checkpoint/receipt was
+ * signed by a DELEGATED key rather than the log's root key, the delegation
+ * certificate travels in the receipt's unprotected header at label 1000
+ * (sealer-embedded). This module verifies that certificate under the genesis
+ * trust root and returns the delegated public key as an additional verify
+ * candidate — the offline port of canopy-api's `resolveReceiptVerifyKey`.
+ *
+ * ES256 (P-256) only: the offline verifier is ES256-only (genesis alg), and
+ * sealer delegate keys are always secp256r1. KS256-rooted delegation is a
+ * server-only concern.
+ *
+ * Note (parity with the server port source): this establishes that the root
+ * authorized the delegated key, but does NOT yet enforce the certificate's MMR
+ * window or expiry-at-issuance against the leaf — that hardening is shared with
+ * the server path and tracked separately (FOR-323).
+ */
+
+import {
+  coseUnprotectedToMap,
+  decodeCborDeterministic,
+  decodeCoseSign1,
+  verifyCoseSign1WithParsedKey,
+} from "@forestrie/encoding";
+
+/** Unprotected header label carrying the delegation certificate. */
+const DELEGATION_CERT_LABEL = 1000;
+
+/** COSE_Key labels (RFC 9052) and EC2/P-256 constants. */
+const COSE_KEY_KTY = 1;
+const COSE_KEY_CRV = -1;
+const COSE_KEY_X = -2;
+const COSE_KEY_Y = -3;
+const COSE_KTY_EC2 = 2;
+const COSE_CRV_P256 = 1;
+
+/** Delegation-cert payload label for the delegated COSE_Key. */
+const PAYLOAD_DELEGATED_KEY = 5;
+
+/**
+ * root-only: no delegation cert present — verify against the root keys as-is.
+ * resolved: cert verified under a root key; use `delegatedKey` first.
+ * broken: a cert is present but did not verify under the root, or its delegated
+ *   key could not be parsed — the delegation chain is invalid.
+ */
+export type DelegatedResolution =
+  | { kind: "root-only" }
+  | { kind: "resolved"; delegatedKey: CryptoKey }
+  | { kind: "broken" };
+
+function extractDelegationCertBytes(unprotected: unknown): Uint8Array | null {
+  const umap = coseUnprotectedToMap(unprotected);
+  const certRaw = umap.get(DELEGATION_CERT_LABEL);
+  return certRaw instanceof Uint8Array && certRaw.length > 0 ? certRaw : null;
+}
+
+function labelGetter(map: unknown): ((label: number) => unknown) | null {
+  if (map instanceof Map) return (label) => map.get(label);
+  if (typeof map === "object" && map !== null) {
+    const obj = map as Record<string | number, unknown>;
+    return (label) => obj[label] ?? obj[String(label)];
+  }
+  return null;
+}
+
+function parseCoseKeyEC2(
+  keyMap: unknown,
+): { x: Uint8Array; y: Uint8Array } | null {
+  const get = labelGetter(keyMap);
+  if (!get) return null;
+
+  const kty = get(COSE_KEY_KTY);
+  if (kty !== COSE_KTY_EC2 && kty !== BigInt(COSE_KTY_EC2)) return null;
+  const crv = get(COSE_KEY_CRV);
+  if (crv !== COSE_CRV_P256 && crv !== BigInt(COSE_CRV_P256)) return null;
+
+  const x = get(COSE_KEY_X);
+  const y = get(COSE_KEY_Y);
+  if (!(x instanceof Uint8Array) || x.length !== 32) return null;
+  if (!(y instanceof Uint8Array) || y.length !== 32) return null;
+  return { x, y };
+}
+
+async function importDelegatedKey(keyMap: unknown): Promise<CryptoKey | null> {
+  const parsed = parseCoseKeyEC2(keyMap);
+  if (!parsed) return null;
+  const uncompressed = new Uint8Array(65);
+  uncompressed[0] = 0x04;
+  uncompressed.set(parsed.x, 1);
+  uncompressed.set(parsed.y, 33);
+  try {
+    return await crypto.subtle.importKey(
+      "raw",
+      uncompressed,
+      { name: "ECDSA", namedCurve: "P-256" },
+      true,
+      ["verify"],
+    );
+  } catch {
+    return null;
+  }
+}
+
+function extractDelegatedKeyFromPayload(
+  payloadBytes: Uint8Array,
+): unknown | null {
+  if (!payloadBytes || payloadBytes.length === 0) return null;
+  let payloadMap: unknown;
+  try {
+    payloadMap = decodeCborDeterministic(payloadBytes);
+  } catch {
+    return null;
+  }
+  const get = labelGetter(payloadMap);
+  return get ? get(PAYLOAD_DELEGATED_KEY) : null;
+}
+
+/**
+ * Resolve the delegated verify key from a receipt's delegation certificate.
+ *
+ * @param receiptCbor - the COSE_Sign1 receipt bytes.
+ * @param rootKeys - genesis-derived ES256 root verify keys.
+ */
+export async function resolveDelegatedVerifyKey(
+  receiptCbor: Uint8Array,
+  rootKeys: CryptoKey[],
+): Promise<DelegatedResolution> {
+  const decoded = decodeCoseSign1(receiptCbor);
+  if (!decoded) return { kind: "root-only" };
+
+  const certBytes = extractDelegationCertBytes(decoded.unprotected);
+  if (!certBytes) return { kind: "root-only" };
+
+  let verified = false;
+  for (const rootKey of rootKeys) {
+    if (
+      await verifyCoseSign1WithParsedKey(certBytes, rootKey, {
+        logPrefix: "delegation-cert-offline",
+      })
+    ) {
+      verified = true;
+      break;
+    }
+  }
+  if (!verified) return { kind: "broken" };
+
+  const certDecoded = decodeCoseSign1(certBytes);
+  if (!certDecoded) return { kind: "broken" };
+
+  const keyRaw = extractDelegatedKeyFromPayload(certDecoded.payloadBstr);
+  const delegatedKey = keyRaw ? await importDelegatedKey(keyRaw) : null;
+  if (!delegatedKey) return { kind: "broken" };
+
+  return { kind: "resolved", delegatedKey };
+}

package/src/verify-grant-receipt-offline.ts

@@ -8,6 +8,7 @@ import type { Grant } from "@forestrie/encoding";
 import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
 import { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
 import { es256ReceiptVerifyKeys } from "./decode-trust-root-cbor.js";
+import { resolveDelegatedVerifyKey } from "./resolve-delegated-verify-key.js";
 import { univocityLeafHash } from "./leaf-commitment.js";
 import { parseReceipt } from "./parse-receipt.js";
 import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
@@ -100,6 +101,71 @@ async function verifySignatureAndInclusion(opts: {
 export async function verifyGrantReceiptOffline(
   input: VerifyGrantReceiptOfflineInput,
 ): Promise<ReceiptVerifyResult> {
+  // A GRANT leaf commits the grant commitment hash (register-grant / create-log).
+  let inner: Uint8Array;
+  try {
+    inner = await grantCommitmentHashFromGrant(input.grant);
+  } catch {
+    return { ok: false, stage: "binding", reason: "grant_invalid" };
+  }
+  return verifyReceiptOfflineWithLeafInner({
+    genesisCbor: input.genesisCbor,
+    receiptCbor: input.receiptCbor,
+    idtimestampBe8: input.idtimestampBe8,
+    inner,
+  });
+}
+
+export type VerifyReceiptOfflineInput = {
+  genesisCbor: Uint8Array;
+  receiptCbor: Uint8Array;
+  /**
+   * The EXACT registered payload bytes whose SHA-256 is the leaf ContentHash.
+   * Kind-agnostic: for a SCITT signed statement this is the statement COSE
+   * bytes; for a forestrie grant leaf it is the grant commitment preimage
+   * (see {@link verifyGrantReceiptOffline}, which derives it).
+   */
+  payload: Uint8Array;
+  idtimestampBe8: Uint8Array;
+};
+
+/**
+ * Offline verify of a receipt against the EXACT registered payload. The log
+ * leaf commits `SHA-256(idtimestamp ‖ SHA-256(payload))`; this is the standard,
+ * COSE-Receipts-conformant path (a SCITT statement receipt is exactly this with
+ * `payload` = the signed statement). Genesis trust root, FOR-297 delegation
+ * resolution, inclusion, and signature are all standard.
+ */
+export async function verifyReceiptOffline(
+  input: VerifyReceiptOfflineInput,
+): Promise<ReceiptVerifyResult> {
+  const inner = new Uint8Array(
+    await crypto.subtle.digest(
+      "SHA-256",
+      input.payload as unknown as BufferSource,
+    ),
+  );
+  return verifyReceiptOfflineWithLeafInner({
+    genesisCbor: input.genesisCbor,
+    receiptCbor: input.receiptCbor,
+    idtimestampBe8: input.idtimestampBe8,
+    inner,
+  });
+}
+
+/**
+ * Shared offline-verify core: reconstruct the leaf as
+ * `univocityLeafHash(idtimestamp, inner)`, resolve the (possibly delegated,
+ * FOR-297) verify key from the genesis trust root, and check signature +
+ * inclusion. `inner` is the leaf ContentHash = `SHA-256(payload)` — the grant
+ * commitment for a grant leaf, or `SHA-256(statement)` for a statement leaf.
+ */
+async function verifyReceiptOfflineWithLeafInner(input: {
+  genesisCbor: Uint8Array;
+  receiptCbor: Uint8Array;
+  idtimestampBe8: Uint8Array;
+  inner: Uint8Array;
+}): Promise<ReceiptVerifyResult> {
   let parsed: ReturnType<typeof parseReceipt>;
   try {
     parsed = parseReceipt(input.receiptCbor);
@@ -114,17 +180,27 @@ export async function verifyGrantReceiptOffline(
     return { ok: false, stage: "parse", reason: "genesis_invalid" };
   }
 
-  const verifyKeys = es256ReceiptVerifyKeys([trustRoot]);
+  const verifyKeys = es256ReceiptVerifyKeys([trustRoot]) as CryptoKey[];
   if (!verifyKeys.length) {
     return { ok: false, stage: "signature", reason: "no_es256_trust_key" };
   }
 
-  let inner: Uint8Array;
-  try {
-    inner = await grantCommitmentHashFromGrant(input.grant);
-  } catch {
-    return { ok: false, stage: "binding", reason: "grant_invalid" };
+  // FOR-297: when the receipt was signed by a DELEGATED key, verify the
+  // label-1000 delegation certificate under the root and try the delegated key
+  // first. A cert present but not chaining to the root is a hard failure — do
+  // not silently fall back to the root key (which cannot verify a
+  // delegated-signed receipt anyway).
+  const delegation = await resolveDelegatedVerifyKey(
+    input.receiptCbor,
+    verifyKeys,
+  );
+  if (delegation.kind === "broken") {
+    return { ok: false, stage: "signature", reason: "delegation_invalid" };
   }
+  const allVerifyKeys =
+    delegation.kind === "resolved"
+      ? [delegation.delegatedKey, ...verifyKeys]
+      : verifyKeys;
 
   let idtimestamp: bigint;
   try {
@@ -133,13 +209,13 @@ export async function verifyGrantReceiptOffline(
     return { ok: false, stage: "binding", reason: "idtimestamp_invalid" };
   }
 
-  const leafHash = await univocityLeafHash(idtimestamp, inner);
+  const leafHash = await univocityLeafHash(idtimestamp, input.inner);
 
   return verifySignatureAndInclusion({
     receiptCbor: input.receiptCbor,
     explicitPeak: parsed.explicitPeak,
     proof: parsed.proof,
     leafHash,
-    verifyKeys: verifyKeys as CryptoKey[],
+    verifyKeys: allVerifyKeys,
   });
 }