@forestrie/receipt-verify 0.11.0 → 1.0.0

package/dist/verify-endorsed-leaf.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The single offline rung for a passkey-rooted log (devdocs ADR-0065 §5,
+ * plan-2608-14 1.2). From public artifacts only — the log root (on-chain
+ * `logRootKey` == the grant's `grantData`), the exact registered leaf bytes,
+ * the receipt and its idtimestamp — reconstruct:
+ *
+ *   root → endorsement (-65801 inside the leaf; -65800 verify under the
+ *   root, UV per the grant flag, window from the payload)
+ *     → session key
+ *       → leaf: kid == session x, ES256 signature under the session key
+ *         → receipt: leaf bytes hash to the receipted index (inclusion),
+ *           receipted idtimestamp ∈ [notBefore, notAfter]
+ *
+ * There is exactly one route and no fallback: a leaf without an endorsement
+ * is not verified under the root here (that is the plain
+ * `verifyReceiptOffline*` path for root-signed logs), and the ADR-0064
+ * export-fed rung (`resolveEndorsedSessionKey` over a `/receipts` export)
+ * is gone — the endorsement an auditor needs is inside the committed leaf.
+ *
+ * Tampering closes both ways (ADR-0065 §5): editing the endorsement changes
+ * `contentHash`, so inclusion fails; substituting a different valid
+ * endorsement changes the session key, so the leaf signature fails.
+ */
+import { type SessionKeyEndorsementFailureReason } from "./session-key-endorsement.js";
+export interface VerifyEndorsedLeafInput {
+    /**
+     * The log root as raw P-256 x‖y (64 bytes): the grant's `grantData`, the
+     * value univocity binds as `logRootKey`. The endorsement's trust anchor;
+     * its kid is pinned to this x.
+     */
+    rootPublicKeyXY: Uint8Array;
+    /** The EXACT registered leaf bytes (COSE Sign1 carrying -65801). */
+    statementCbor: Uint8Array;
+    /** The receipt over that leaf. */
+    receiptCbor: Uint8Array;
+    /** The receipted idtimestamp (8 bytes, big-endian). */
+    idtimestampBe8: Uint8Array;
+    /**
+     * Receipt trust anchors (the sealer or, for a delegated seal, the
+     * delegation-cert issuer — for a user log that is the root itself, which
+     * signs the sealing delegation with a passkey gesture). Defaults to the
+     * root. See `verifyReceiptOfflineWithKeys` for the trust model.
+     */
+    trustKeys?: CryptoKey[];
+}
+export interface VerifyEndorsedLeafOptions {
+    /**
+     * The grant's `GF_REQUIRES_USER_VERIFICATION` (ADR-0063 §4): when set the
+     * endorsement's assertion must carry UV. User presence is always required.
+     */
+    requireUserVerification?: boolean;
+    /** Emit JSON warning lines on failure paths (no secrets). */
+    logFailures?: boolean;
+    logPrefix?: string;
+}
+export type VerifyEndorsedLeafStage = "endorsement" | "leaf" | "window" | "receipt";
+export type VerifyEndorsedLeafResult = {
+    ok: true;
+    /** The endorsed session public key, raw x‖y (64 bytes). */
+    sessionPublicKeyXY: Uint8Array;
+    /** The endorsement window, unix ms inclusive. */
+    notBefore: number;
+    notAfter: number;
+    /** The receipted idtimestamp's time component, unix ms. */
+    leafIdtimestampMs: number;
+} | {
+    ok: false;
+    stage: VerifyEndorsedLeafStage;
+    reason: string;
+};
+/** ADR-0065 §4 reason vocabulary, shared with canopy admission. */
+export type EndorsementAdmissionReason = "endorsement_missing" | "endorsement_invalid" | "endorsement_root_mismatch" | "endorsement_uv_required" | "endorsement_expired" | "endorsement_not_yet_valid";
+/**
+ * Fold the endorsement verifier's fine-grained reasons into the ADR-0065 §4
+ * admission vocabulary. `signature_invalid` under a coordinate anchor means
+ * "a well-formed endorsement that does not chain to THIS root" — the
+ * `endorsement_root_mismatch` case; a malformed window is
+ * `endorsement_expired` (§4: "window, both directions, and malformed
+ * windows" — no instant is inside it); everything else structural is
+ * `endorsement_invalid`.
+ */
+export declare function endorsementAdmissionReason(reason: SessionKeyEndorsementFailureReason): EndorsementAdmissionReason;
+/**
+ * Read the endorsement bytes from a leaf's unprotected header.
+ * `missing` when there is no -65801 entry; `invalid` when the entry is not
+ * a byte string (present-but-unusable is never "absent").
+ */
+export declare function extractLeafEndorsement(statementCbor: Uint8Array): {
+    kind: "ok";
+    endorsement: Uint8Array;
+    kid: Uint8Array | null;
+} | {
+    kind: "missing";
+} | {
+    kind: "invalid";
+};
+/**
+ * Verify an endorsed leaf and its receipt from public artifacts only.
+ * Pure over bytes; no network (rules-of-the-road C1).
+ */
+export declare function verifyEndorsedLeaf(input: VerifyEndorsedLeafInput, opts?: VerifyEndorsedLeafOptions): Promise<VerifyEndorsedLeafResult>;
+//# sourceMappingURL=verify-endorsed-leaf.d.ts.map

package/dist/verify-endorsed-leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-endorsed-leaf.d.ts","sourceRoot":"","sources":["../src/verify-endorsed-leaf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,EAGL,KAAK,kCAAkC,EACxC,MAAM,8BAA8B,CAAC;AAMtC,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,eAAe,EAAE,UAAU,CAAC;IAC5B,oEAAoE;IACpE,aAAa,EAAE,UAAU,CAAC;IAC1B,kCAAkC;IAClC,WAAW,EAAE,UAAU,CAAC;IACxB,uDAAuD;IACvD,cAAc,EAAE,UAAU,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,uBAAuB,GAC/B,aAAa,GACb,MAAM,GACN,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,wBAAwB,GAChC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,2DAA2D;IAC3D,kBAAkB,EAAE,UAAU,CAAC;IAC/B,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,mEAAmE;AACnE,MAAM,MAAM,0BAA0B,GAClC,qBAAqB,GACrB,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,qBAAqB,GACrB,2BAA2B,CAAC;AAEhC;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,kCAAkC,GACzC,0BAA0B,CAY5B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,UAAU,GAEvB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAsBtB;AAoBD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,IAAI,CAAC,EAAE,yBAAyB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAkGnC"}

package/dist/verify-endorsed-leaf.js

@@ -0,0 +1,189 @@
+/**
+ * The single offline rung for a passkey-rooted log (devdocs ADR-0065 §5,
+ * plan-2608-14 1.2). From public artifacts only — the log root (on-chain
+ * `logRootKey` == the grant's `grantData`), the exact registered leaf bytes,
+ * the receipt and its idtimestamp — reconstruct:
+ *
+ *   root → endorsement (-65801 inside the leaf; -65800 verify under the
+ *   root, UV per the grant flag, window from the payload)
+ *     → session key
+ *       → leaf: kid == session x, ES256 signature under the session key
+ *         → receipt: leaf bytes hash to the receipted index (inclusion),
+ *           receipted idtimestamp ∈ [notBefore, notAfter]
+ *
+ * There is exactly one route and no fallback: a leaf without an endorsement
+ * is not verified under the root here (that is the plain
+ * `verifyReceiptOffline*` path for root-signed logs), and the ADR-0064
+ * export-fed rung (`resolveEndorsedSessionKey` over a `/receipts` export)
+ * is gone — the endorsement an auditor needs is inside the committed leaf.
+ *
+ * Tampering closes both ways (ADR-0065 §5): editing the endorsement changes
+ * `contentHash`, so inclusion fails; substituting a different valid
+ * endorsement changes the session key, so the leaf signature fails.
+ */
+import { COSE_LABEL_SESSION_KEY_ENDORSEMENT, coseUnprotectedToMap, decodeCborDeterministic, decodeCoseSign1, verifyCoseSign1WithParsedKey, } from "@forestrie/encoding";
+import { importEs256PublicKeyFromGrantDataXy64 } from "./decode-trust-root-cbor.js";
+import { idtimestampToUnixMs } from "./resolve-delegated-verify-key.js";
+import { checkEndorsementWindow, verifySessionKeyEndorsement, } from "./session-key-endorsement.js";
+import { verifyReceiptOfflineWithKeys } from "./verify-grant-receipt-offline.js";
+/** COSE header label for key id (kid). */
+const COSE_KID = 4;
+/**
+ * Fold the endorsement verifier's fine-grained reasons into the ADR-0065 §4
+ * admission vocabulary. `signature_invalid` under a coordinate anchor means
+ * "a well-formed endorsement that does not chain to THIS root" — the
+ * `endorsement_root_mismatch` case; a malformed window is
+ * `endorsement_expired` (§4: "window, both directions, and malformed
+ * windows" — no instant is inside it); everything else structural is
+ * `endorsement_invalid`.
+ */
+export function endorsementAdmissionReason(reason) {
+    switch (reason) {
+        case "kid_mismatch":
+        case "signature_invalid":
+            return "endorsement_root_mismatch";
+        case "uv_required":
+            return "endorsement_uv_required";
+        case "window_invalid":
+            return "endorsement_expired";
+        default:
+            return "endorsement_invalid";
+    }
+}
+/**
+ * Read the endorsement bytes from a leaf's unprotected header.
+ * `missing` when there is no -65801 entry; `invalid` when the entry is not
+ * a byte string (present-but-unusable is never "absent").
+ */
+export function extractLeafEndorsement(statementCbor) {
+    const decoded = decodeCoseSign1(statementCbor);
+    if (!decoded)
+        return { kind: "invalid" };
+    const entry = coseUnprotectedToMap(decoded.unprotected).get(COSE_LABEL_SESSION_KEY_ENDORSEMENT);
+    if (entry === undefined)
+        return { kind: "missing" };
+    if (!(entry instanceof Uint8Array) || entry.length === 0) {
+        return { kind: "invalid" };
+    }
+    let kid = null;
+    try {
+        const protectedMap = decodeCborDeterministic(decoded.protectedBstr);
+        const raw = protectedMap instanceof Map
+            ? protectedMap.get(COSE_KID)
+            : protectedMap?.[COSE_KID];
+        if (raw instanceof Uint8Array)
+            kid = raw;
+    }
+    catch {
+        kid = null;
+    }
+    return { kind: "ok", endorsement: entry, kid };
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+function readIdtimestampBe8(bytes) {
+    if (!bytes || bytes.length < 8) {
+        throw new Error("idtimestamp required (8 bytes)");
+    }
+    const view = bytes.length === 8
+        ? new DataView(bytes.buffer, bytes.byteOffset, 8)
+        : new DataView(bytes.buffer, bytes.byteOffset + bytes.length - 8, 8);
+    return view.getBigUint64(0, false);
+}
+/**
+ * Verify an endorsed leaf and its receipt from public artifacts only.
+ * Pure over bytes; no network (rules-of-the-road C1).
+ */
+export async function verifyEndorsedLeaf(input, opts) {
+    if (input.rootPublicKeyXY.length !== 64) {
+        return { ok: false, stage: "endorsement", reason: "root_invalid" };
+    }
+    const logPrefix = opts?.logPrefix ?? "verify-endorsed-leaf";
+    // 1. The endorsement, from the leaf itself.
+    const extracted = extractLeafEndorsement(input.statementCbor);
+    if (extracted.kind === "missing") {
+        return { ok: false, stage: "endorsement", reason: "endorsement_missing" };
+    }
+    if (extracted.kind === "invalid") {
+        return { ok: false, stage: "endorsement", reason: "endorsement_invalid" };
+    }
+    // 2. Under the root (kid pinned to root x by the coordinate anchor).
+    const endorsed = await verifySessionKeyEndorsement(extracted.endorsement, {
+        x: input.rootPublicKeyXY.subarray(0, 32),
+        y: input.rootPublicKeyXY.subarray(32, 64),
+        curve: "P-256",
+    }, {
+        requireUserVerification: opts?.requireUserVerification,
+        logFailures: opts?.logFailures,
+        logPrefix,
+    });
+    if (!endorsed.ok) {
+        return {
+            ok: false,
+            stage: "endorsement",
+            reason: endorsementAdmissionReason(endorsed.reason),
+        };
+    }
+    // 3. The leaf: kid == session x, signature under the session key. The
+    // shared verify branch rejects a -65800 entry on a plain-ES256 leaf.
+    const sessionX = endorsed.sessionPublicKeyXY.subarray(0, 32);
+    if (!extracted.kid || !bytesEqual(extracted.kid, sessionX)) {
+        return { ok: false, stage: "leaf", reason: "signer_mismatch" };
+    }
+    const leafOk = await verifyCoseSign1WithParsedKey(input.statementCbor, endorsed.sessionKey, { logFailures: opts?.logFailures, logPrefix: `${logPrefix}:leaf` });
+    if (!leafOk) {
+        return { ok: false, stage: "leaf", reason: "leaf_signature_invalid" };
+    }
+    // 4. The window, against the receipted idtimestamp (never wall-clock —
+    // a valid receipt verifies forever). Exact: no skew.
+    let idtimestamp;
+    try {
+        idtimestamp = readIdtimestampBe8(input.idtimestampBe8);
+    }
+    catch {
+        return { ok: false, stage: "window", reason: "idtimestamp_invalid" };
+    }
+    const leafIdtimestampMs = idtimestampToUnixMs(idtimestamp);
+    const window = checkEndorsementWindow(endorsed, leafIdtimestampMs);
+    if (!window.ok) {
+        return { ok: false, stage: "window", reason: window.reason };
+    }
+    // 5. Inclusion of the EXACT leaf bytes (the endorsement is inside them).
+    let trustKeys = input.trustKeys;
+    if (!trustKeys) {
+        try {
+            trustKeys = [
+                await importEs256PublicKeyFromGrantDataXy64(input.rootPublicKeyXY),
+            ];
+        }
+        catch {
+            return { ok: false, stage: "receipt", reason: "root_invalid" };
+        }
+    }
+    const receipt = await verifyReceiptOfflineWithKeys({
+        receiptCbor: input.receiptCbor,
+        payload: input.statementCbor,
+        idtimestampBe8: input.idtimestampBe8,
+        trustKeys,
+    });
+    if (!receipt.ok) {
+        return {
+            ok: false,
+            stage: "receipt",
+            reason: receipt.reason ?? "receipt_invalid",
+        };
+    }
+    return {
+        ok: true,
+        sessionPublicKeyXY: endorsed.sessionPublicKeyXY,
+        notBefore: endorsed.notBefore,
+        notAfter: endorsed.notAfter,
+        leafIdtimestampMs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -28,8 +28,8 @@
   ],
   "dependencies": {
     "@noble/hashes": "^1.7.1",
-    "@forestrie/encoding": "0.6.0",
     "@forestrie/chain-rpc": "0.2.0",
+    "@forestrie/encoding": "0.7.0",
     "@forestrie/merklelog": "0.3.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -49,6 +49,7 @@ export type {
 } from "./verify-grant-receipt-offline.js";
 export {
   checkDelegationConstraints,
+  idtimestampToUnixMs,
   idtimestampToUnixSeconds,
   resolveDelegatedVerifyKey,
 } from "./resolve-delegated-verify-key.js";
@@ -58,6 +59,49 @@ export type {
 } from "./resolve-delegated-verify-key.js";
 /** Import a raw 64-byte x||y P-256 public key as an ES256 verify key. */
 export { importEs256PublicKeyFromGrantDataXy64 } from "./decode-trust-root-cbor.js";
+/**
+ * Passkey session-key endorsement v2 (ADR-0064 as amended by ADR-0065):
+ * build, assemble, and verify the artifact chaining a passkey log root to the
+ * plain-ES256 per-turn session key for a validity window. The endorsement
+ * rides inside every endorsed leaf at unprotected label -65801
+ * (`COSE_LABEL_SESSION_KEY_ENDORSEMENT`, @forestrie/encoding).
+ */
+export {
+  assembleSessionKeyEndorsement,
+  buildSessionKeyEndorsementTbs,
+  checkEndorsementWindow,
+  DEFAULT_ENDORSEMENT_WINDOW_MS,
+  NOT_AFTER_PAYLOAD_KEY,
+  NOT_BEFORE_PAYLOAD_KEY,
+  SESSION_KEY_ENDORSEMENT_CONTENT_TYPE,
+  SESSION_KEY_ENDORSEMENT_V1_CONTENT_TYPE,
+  SESSION_KEY_PAYLOAD_KEY,
+  verifySessionKeyEndorsement,
+} from "./session-key-endorsement.js";
+export type {
+  EndorsementWindow,
+  EndorsementWindowCheck,
+  SessionKeyEndorsementFailureReason,
+  SessionKeyEndorsementTbs,
+  SessionKeyEndorsementVerifyResult,
+  VerifySessionKeyEndorsementOptions,
+} from "./session-key-endorsement.js";
+/**
+ * The single offline rung for a passkey-rooted log (ADR-0065 §5): root →
+ * endorsement (inside the leaf) → session key → leaf → receipt + window.
+ */
+export {
+  endorsementAdmissionReason,
+  extractLeafEndorsement,
+  verifyEndorsedLeaf,
+} from "./verify-endorsed-leaf.js";
+export type {
+  EndorsementAdmissionReason,
+  VerifyEndorsedLeafInput,
+  VerifyEndorsedLeafOptions,
+  VerifyEndorsedLeafResult,
+  VerifyEndorsedLeafStage,
+} from "./verify-endorsed-leaf.js";
 export { decodeForestrieGrantCose } from "./decode-forestrie-grant-cose.js";
 export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 

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

@@ -71,10 +71,19 @@ const SNOWFLAKE_TIME_SHIFT = 24n;
 const SNOWFLAKE_EPOCH_SPAN_MS = (1n << 40n) - 1n;
 
 export function idtimestampToUnixSeconds(idtimestamp: bigint): number {
-  const ms =
+  return Math.floor(idtimestampToUnixMs(idtimestamp) / 1000);
+}
+
+/**
+ * Snowflake idtimestamp → Unix milliseconds: the time component an
+ * ADR-0065 §3 endorsement window is expressed in
+ * (`ms = (id >> TimeShift) + EpochMS(epoch)`).
+ */
+export function idtimestampToUnixMs(idtimestamp: bigint): number {
+  return Number(
     COMMITMENT_EPOCH * SNOWFLAKE_EPOCH_SPAN_MS +
-    (idtimestamp >> SNOWFLAKE_TIME_SHIFT);
-  return Number(ms / 1000n);
+      (idtimestamp >> SNOWFLAKE_TIME_SHIFT),
+  );
 }
 
 /**