@forestrie/receipt-verify 0.11.0 → 1.0.0

package/dist/index.d.ts

@@ -24,10 +24,25 @@ export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
  */
 export { verifyGrantReceiptOfflineWithKeys, verifyReceiptOfflineWithKeys, } from "./verify-grant-receipt-offline.js";
 export type { VerifyGrantReceiptOfflineWithKeysInput, VerifyReceiptOfflineWithKeysInput, } from "./verify-grant-receipt-offline.js";
-export { checkDelegationConstraints, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+export { checkDelegationConstraints, idtimestampToUnixMs, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
 export type { DelegatedResolution, DelegationConstraints, } 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";
 /** 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,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,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B;;;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;;;;GAIG;AACH,OAAO,EACL,iCAAiC,EACjC,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,sCAAsC,EACtC,iCAAiC,GAClC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mCAAmC,CAAC;AAC3C,yEAAyE;AACzE,OAAO,EAAE,qCAAqC,EAAE,MAAM,6BAA6B,CAAC;AACpF,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;AACzD,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC;AAC/B;;;;;GAKG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,2CAA2C,EAC3C,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -16,9 +16,22 @@ export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
  * See the trust-ladder notes on verifyReceiptOfflineWithKeys.
  */
 export { verifyGrantReceiptOfflineWithKeys, verifyReceiptOfflineWithKeys, } from "./verify-grant-receipt-offline.js";
-export { checkDelegationConstraints, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+export { checkDelegationConstraints, idtimestampToUnixMs, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } 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";
+/**
+ * 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 { 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

@@ -35,6 +35,12 @@
  * earlier "does not yet enforce the window" gap.
  */
 export declare function idtimestampToUnixSeconds(idtimestamp: bigint): number;
+/**
+ * Snowflake idtimestamp → Unix milliseconds: the time component an
+ * ADR-0065 §3 endorsement window is expressed in
+ * (`ms = (id >> TimeShift) + EpochMS(epoch)`).
+ */
+export declare function idtimestampToUnixMs(idtimestamp: bigint): number;
 /**
  * Coverage + validity window a root-signed delegation cert imposes on its
  * delegated key. `mmrStart`/`mmrEnd` are inclusive MMR-index bounds;

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

@@ -1 +1 @@
-{"version":3,"file":"resolve-delegated-verify-key.d.ts","sourceRoot":"","sources":["../src/resolve-delegated-verify-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAqCH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC3C,GACD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAsGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,qBAAqB,EAClC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}
+{"version":3,"file":"resolve-delegated-verify-key.d.ts","sourceRoot":"","sources":["../src/resolve-delegated-verify-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAqCH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC3C,GACD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAsGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,qBAAqB,EAClC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}

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

@@ -60,9 +60,16 @@ const COMMITMENT_EPOCH = 1n;
 const SNOWFLAKE_TIME_SHIFT = 24n;
 const SNOWFLAKE_EPOCH_SPAN_MS = (1n << 40n) - 1n;
 export function idtimestampToUnixSeconds(idtimestamp) {
-    const ms = COMMITMENT_EPOCH * SNOWFLAKE_EPOCH_SPAN_MS +
-        (idtimestamp >> SNOWFLAKE_TIME_SHIFT);
-    return Number(ms / 1000n);
+    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) {
+    return Number(COMMITMENT_EPOCH * SNOWFLAKE_EPOCH_SPAN_MS +
+        (idtimestamp >> SNOWFLAKE_TIME_SHIFT));
 }
 function extractDelegationCertBytes(unprotected) {
     const umap = coseUnprotectedToMap(unprotected);

package/dist/session-key-endorsement.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Passkey session-key endorsement, payload v2 (devdocs ADR-0064 as amended by
+ * ADR-0065 §3; plan-2608-14 1.2).
+ *
+ * A passkey log root signs ceremonies only; the per-turn user-envelope
+ * signer is a separate session key, endorsed by the root via a COSE Sign1 in
+ * the ADR-0063 WebAuthn envelope. This module owns both sides of that
+ * artifact's byte-exact shape:
+ *
+ * - build/assemble: the client constructs the TBS, hashes its Sig_structure
+ *   into the WebAuthn challenge, and attaches the assertion + signature;
+ * - verify: given the passkey root as trust anchor, validate the artifact
+ *   (typed, challenge-bound, fail-closed) and yield the session public key
+ *   and its validity window.
+ *
+ * The endorsement rides INSIDE every endorsed leaf (unprotected label
+ * `COSE_LABEL_SESSION_KEY_ENDORSEMENT`, -65801) and the chain
+ * root → endorsement → session key → leaf → receipt is walked by
+ * {@link verifyEndorsedLeaf} (the single offline rung, ADR-0065 §5) and by
+ * canopy SCRAPI admission (§4).
+ *
+ * Domain separation: the protected content type below names payload v2 and
+ * the payload is EXACTLY `{"sessionKey": bstr .size 64, "notBefore": uint,
+ * "notAfter": uint}` (unix milliseconds, the idtimestamp time domain).
+ * Anything else — including a v1 (window-less) artifact — is a verification
+ * failure, never a fallback (ADR-0065 §3: v1 is rejected, not grandfathered).
+ *
+ * The window itself is NOT checked here: the reference time differs per
+ * verifier (canopy's clock at admission; the receipted idtimestamp offline).
+ * Callers apply {@link checkEndorsementWindow} with the time they hold.
+ */
+import { type ParsedVerifyKey } from "@forestrie/encoding";
+/**
+ * Protected-header content type (label 3) naming the v2 endorsement artifact.
+ * Signed via Sig_structure, so both the artifact's type AND its payload
+ * version are non-malleable.
+ */
+export declare const SESSION_KEY_ENDORSEMENT_CONTENT_TYPE = "application/vnd.forestrie.session-key-endorsement.v2+cbor";
+/**
+ * The retired ADR-0064 v1 content type (payload without a window). Exported
+ * only so verifiers and tests can name what is being REJECTED; no code path
+ * accepts it.
+ */
+export declare const SESSION_KEY_ENDORSEMENT_V1_CONTENT_TYPE = "application/vnd.forestrie.session-key-endorsement+cbor";
+/** Payload map key holding the endorsed session public key (x‖y, 64 bytes). */
+export declare const SESSION_KEY_PAYLOAD_KEY = "sessionKey";
+/** Payload map key: window start, unix milliseconds, inclusive. */
+export declare const NOT_BEFORE_PAYLOAD_KEY = "notBefore";
+/** Payload map key: window end, unix milliseconds, inclusive. */
+export declare const NOT_AFTER_PAYLOAD_KEY = "notAfter";
+/** Default client window length: 7 days (ADR-0065 §3). */
+export declare const DEFAULT_ENDORSEMENT_WINDOW_MS: number;
+/** Validity window of an endorsement, unix milliseconds, both ends inclusive. */
+export interface EndorsementWindow {
+    notBefore: number;
+    notAfter: number;
+}
+/** To-be-signed endorsement halves plus the challenge preimage. */
+export interface SessionKeyEndorsementTbs {
+    /** Protected header map bytes `{1: -65800, 3: cty(v2), 4: root x}`. */
+    protectedBstr: Uint8Array;
+    /** Payload bytes: deterministic CBOR `{sessionKey, notBefore, notAfter}`. */
+    payloadBstr: Uint8Array;
+    /**
+     * `Sig_structure` over the halves. The WebAuthn challenge MUST be
+     * `base64url(sha256(sigStructureBytes))` (ADR-0063 §3).
+     */
+    sigStructureBytes: Uint8Array;
+}
+/**
+ * Build the v2 endorsement TBS. The caller hashes `sigStructureBytes` into
+ * the `navigator.credentials.get` challenge, then assembles with the assertion.
+ *
+ * @param input.rootPublicKeyX - Passkey root x coordinate (kid, 32 bytes)
+ * @param input.sessionPublicKeyXY - Endorsed session public key x‖y (64 bytes)
+ * @param input.notBefore - Window start, unix ms inclusive
+ * @param input.notAfter - Window end, unix ms inclusive; must exceed notBefore
+ */
+export declare function buildSessionKeyEndorsementTbs(input: {
+    rootPublicKeyX: Uint8Array;
+    sessionPublicKeyXY: Uint8Array;
+    notBefore: number;
+    notAfter: number;
+}): SessionKeyEndorsementTbs;
+/**
+ * Assemble the final endorsement COSE Sign1: the assertion rides in the
+ * unprotected header at label -65800 (ADR-0063 §2), the signature is the
+ * assertion's, converted to low-s P1363 r‖s by the caller (see
+ * delegation-cose `derSignatureToP1363` / low-s normalisation).
+ */
+export declare function assembleSessionKeyEndorsement(input: {
+    tbs: SessionKeyEndorsementTbs;
+    authenticatorData: Uint8Array;
+    clientDataJSON: Uint8Array;
+    /** Low-s P1363 r‖s (64 bytes). */
+    signature: Uint8Array;
+}): Uint8Array;
+/** Verification failure reasons; the first check that broke. */
+export type SessionKeyEndorsementFailureReason = "endorsement_malformed" | "wrong_alg" | "wrong_content_type" | "kid_invalid" | "kid_mismatch" | "payload_invalid" | "window_invalid" | "uv_required" | "signature_invalid" | "session_key_import_failed";
+/** Verification outcome; failures name the first check that broke. */
+export type SessionKeyEndorsementVerifyResult = ({
+    ok: true;
+    /** Endorsed session public key, raw x‖y (64 bytes). */
+    sessionPublicKeyXY: Uint8Array;
+    /** The same key imported for ES256 verify of per-turn leaves. */
+    sessionKey: CryptoKey;
+} & EndorsementWindow) | {
+    ok: false;
+    reason: SessionKeyEndorsementFailureReason;
+};
+/** Options for {@link verifySessionKeyEndorsement}. */
+export interface VerifySessionKeyEndorsementOptions {
+    /**
+     * Require the assertion's UV flag. At admission this is the grant's
+     * `GF_REQUIRES_USER_VERIFICATION` (ADR-0065 §4); at DO onboarding, where
+     * no grant exists yet, deployment config (ADR-0064 §3). User presence is
+     * always required regardless.
+     */
+    requireUserVerification?: boolean;
+    /** Emit JSON warning lines on failure paths (no secrets). */
+    logFailures?: boolean;
+    /** Included in JSON log lines. */
+    logPrefix?: string;
+}
+/**
+ * Verify a v2 session-key endorsement under the passkey root and yield the
+ * endorsed session key plus its window. All the ADR-0063 envelope checks
+ * (challenge binding to this artifact's `Sig_structure`, UP flag, ceremony
+ * type, low-s, both fail-closed directions) run inside the shared `-65800`
+ * verify branch; this function adds the ADR-0064/0065 typing rules on top
+ * and reports a missing-UV rejection under its own reason so admission can
+ * name it (`endorsement_uv_required`, ADR-0065 §4).
+ *
+ * @param endorsementCbor - The endorsement COSE Sign1 bytes
+ * @param rootKeys - Passkey root trust anchor(s), tried in order. Raw
+ *   coordinate anchors additionally pin `kid == root x`.
+ * @param opts - UV requirement and failure logging
+ */
+export declare function verifySessionKeyEndorsement(endorsementCbor: Uint8Array, rootKeys: ParsedVerifyKey | ParsedVerifyKey[], opts?: VerifySessionKeyEndorsementOptions): Promise<SessionKeyEndorsementVerifyResult>;
+/** Outcome of {@link checkEndorsementWindow}. */
+export type EndorsementWindowCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "endorsement_not_yet_valid" | "endorsement_expired";
+};
+/**
+ * Is `atMs` inside the endorsement's window? `notBefore ≤ atMs ≤ notAfter`,
+ * both inclusive (ADR-0065 §3). `skewMs` (default 0) tolerates a `notBefore`
+ * slightly in the future of a wall-clock verifier; offline verifiers
+ * comparing against the receipted idtimestamp should leave it at 0 — that
+ * comparison is exact and authoritative.
+ *
+ * Deliberately a pure function of the two numbers so callers can (and must)
+ * run it on every request, structurally outside any verified-endorsement
+ * cache (ADR-0065 §4).
+ */
+export declare function checkEndorsementWindow(window: EndorsementWindow, atMs: number, opts?: {
+    skewMs?: number;
+}): EndorsementWindowCheck;
+//# sourceMappingURL=session-key-endorsement.d.ts.map

package/dist/session-key-endorsement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key-endorsement.d.ts","sourceRoot":"","sources":["../src/session-key-endorsement.ts"],"names":[],"mappings":"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"}

package/dist/session-key-endorsement.js

@@ -0,0 +1,299 @@
+/**
+ * Passkey session-key endorsement, payload v2 (devdocs ADR-0064 as amended by
+ * ADR-0065 §3; plan-2608-14 1.2).
+ *
+ * A passkey log root signs ceremonies only; the per-turn user-envelope
+ * signer is a separate session key, endorsed by the root via a COSE Sign1 in
+ * the ADR-0063 WebAuthn envelope. This module owns both sides of that
+ * artifact's byte-exact shape:
+ *
+ * - build/assemble: the client constructs the TBS, hashes its Sig_structure
+ *   into the WebAuthn challenge, and attaches the assertion + signature;
+ * - verify: given the passkey root as trust anchor, validate the artifact
+ *   (typed, challenge-bound, fail-closed) and yield the session public key
+ *   and its validity window.
+ *
+ * The endorsement rides INSIDE every endorsed leaf (unprotected label
+ * `COSE_LABEL_SESSION_KEY_ENDORSEMENT`, -65801) and the chain
+ * root → endorsement → session key → leaf → receipt is walked by
+ * {@link verifyEndorsedLeaf} (the single offline rung, ADR-0065 §5) and by
+ * canopy SCRAPI admission (§4).
+ *
+ * Domain separation: the protected content type below names payload v2 and
+ * the payload is EXACTLY `{"sessionKey": bstr .size 64, "notBefore": uint,
+ * "notAfter": uint}` (unix milliseconds, the idtimestamp time domain).
+ * Anything else — including a v1 (window-less) artifact — is a verification
+ * failure, never a fallback (ADR-0065 §3: v1 is rejected, not grandfathered).
+ *
+ * The window itself is NOT checked here: the reference time differs per
+ * verifier (canopy's clock at admission; the receipted idtimestamp offline).
+ * Callers apply {@link checkEndorsementWindow} with the time they hold.
+ */
+import { COSE_ALG_ES256_WEBAUTHN, coseUnprotectedToMap, decodeCborDeterministic, decodeCoseSign1, encodeCborDeterministic, encodeCoseSign1Raw, encodeSigStructure, verifyCoseSign1WithParsedKey, WEBAUTHN_ENVELOPE_LABEL, } from "@forestrie/encoding";
+import { importEs256PublicKeyFromGrantDataXy64 } from "./decode-trust-root-cbor.js";
+/**
+ * Protected-header content type (label 3) naming the v2 endorsement artifact.
+ * Signed via Sig_structure, so both the artifact's type AND its payload
+ * version are non-malleable.
+ */
+export const SESSION_KEY_ENDORSEMENT_CONTENT_TYPE = "application/vnd.forestrie.session-key-endorsement.v2+cbor";
+/**
+ * The retired ADR-0064 v1 content type (payload without a window). Exported
+ * only so verifiers and tests can name what is being REJECTED; no code path
+ * accepts it.
+ */
+export const SESSION_KEY_ENDORSEMENT_V1_CONTENT_TYPE = "application/vnd.forestrie.session-key-endorsement+cbor";
+/** Payload map key holding the endorsed session public key (x‖y, 64 bytes). */
+export const SESSION_KEY_PAYLOAD_KEY = "sessionKey";
+/** Payload map key: window start, unix milliseconds, inclusive. */
+export const NOT_BEFORE_PAYLOAD_KEY = "notBefore";
+/** Payload map key: window end, unix milliseconds, inclusive. */
+export const NOT_AFTER_PAYLOAD_KEY = "notAfter";
+/** Default client window length: 7 days (ADR-0065 §3). */
+export const DEFAULT_ENDORSEMENT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** WebAuthn authenticatorData UV flag bit (WebAuthn L2 §6.1). */
+const AUTH_FLAG_UV = 0x04;
+function isUnixMs(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+}
+/**
+ * Structural window check shared by the builder and the verifier: both ends
+ * are unsigned safe integers and the window is non-empty (ADR-0065 §3
+ * "malformed windows are rejected": `notAfter ≤ notBefore`).
+ */
+function windowWellFormed(w) {
+    return (isUnixMs(w.notBefore) && isUnixMs(w.notAfter) && w.notAfter > w.notBefore);
+}
+/**
+ * Build the v2 endorsement TBS. The caller hashes `sigStructureBytes` into
+ * the `navigator.credentials.get` challenge, then assembles with the assertion.
+ *
+ * @param input.rootPublicKeyX - Passkey root x coordinate (kid, 32 bytes)
+ * @param input.sessionPublicKeyXY - Endorsed session public key x‖y (64 bytes)
+ * @param input.notBefore - Window start, unix ms inclusive
+ * @param input.notAfter - Window end, unix ms inclusive; must exceed notBefore
+ */
+export function buildSessionKeyEndorsementTbs(input) {
+    if (input.rootPublicKeyX.length !== 32) {
+        throw new Error("endorsement kid must be the 32-byte root x coordinate");
+    }
+    if (input.sessionPublicKeyXY.length !== 64) {
+        throw new Error("endorsed session key must be 64 bytes (x||y)");
+    }
+    if (!windowWellFormed(input)) {
+        throw new Error("endorsement window must be unsigned safe-integer unix ms with notAfter > notBefore");
+    }
+    const protectedBstr = encodeCborDeterministic(new Map([
+        [1, COSE_ALG_ES256_WEBAUTHN],
+        [3, SESSION_KEY_ENDORSEMENT_CONTENT_TYPE],
+        [4, input.rootPublicKeyX],
+    ]));
+    // Deterministic CBOR sorts the keys (RFC 8949 §4.2.1); insertion order here
+    // is irrelevant to the bytes.
+    const payloadBstr = encodeCborDeterministic(new Map([
+        [SESSION_KEY_PAYLOAD_KEY, input.sessionPublicKeyXY],
+        [NOT_BEFORE_PAYLOAD_KEY, input.notBefore],
+        [NOT_AFTER_PAYLOAD_KEY, input.notAfter],
+    ]));
+    const sigStructureBytes = encodeSigStructure(protectedBstr, new Uint8Array(0), payloadBstr);
+    return { protectedBstr, payloadBstr, sigStructureBytes };
+}
+/**
+ * Assemble the final endorsement COSE Sign1: the assertion rides in the
+ * unprotected header at label -65800 (ADR-0063 §2), the signature is the
+ * assertion's, converted to low-s P1363 r‖s by the caller (see
+ * delegation-cose `derSignatureToP1363` / low-s normalisation).
+ */
+export function assembleSessionKeyEndorsement(input) {
+    if (input.signature.length !== 64) {
+        throw new Error("endorsement signature must be 64-byte P1363 r||s");
+    }
+    const unprotected = new Map([
+        [WEBAUTHN_ENVELOPE_LABEL, [input.authenticatorData, input.clientDataJSON]],
+    ]);
+    return encodeCoseSign1Raw(input.tbs.protectedBstr, unprotected, input.tbs.payloadBstr, input.signature);
+}
+function protectedHeaderEntries(protectedBstr) {
+    let decoded;
+    try {
+        decoded = decodeCborDeterministic(protectedBstr);
+    }
+    catch {
+        return null;
+    }
+    if (decoded instanceof Map) {
+        return { alg: decoded.get(1), cty: decoded.get(3), kid: decoded.get(4) };
+    }
+    if (typeof decoded === "object" && decoded !== null) {
+        const obj = decoded;
+        return {
+            alg: obj[1] ?? obj["1"],
+            cty: obj[3] ?? obj["3"],
+            kid: obj[4] ?? obj["4"],
+        };
+    }
+    return null;
+}
+function toNumberIfInt(v) {
+    // Deterministic decode may surface large ints as bigint; the window is
+    // unix ms (< 2^53) so a safe bigint is folded back to a number.
+    if (typeof v === "bigint" &&
+        v >= 0n &&
+        v <= BigInt(Number.MAX_SAFE_INTEGER)) {
+        return Number(v);
+    }
+    return v;
+}
+function decodePayloadV2(payloadBstr) {
+    let decoded;
+    try {
+        decoded = decodeCborDeterministic(payloadBstr);
+    }
+    catch {
+        return { kind: "payload_invalid" };
+    }
+    // Exactly three entries, exactly the three labels, exactly these shapes
+    // (ADR-0065 §3) — anything else is a failure, never a partial read.
+    let entries;
+    if (decoded instanceof Map) {
+        entries = [...decoded.entries()];
+    }
+    else if (typeof decoded === "object" && decoded !== null) {
+        entries = Object.entries(decoded);
+    }
+    else {
+        return { kind: "payload_invalid" };
+    }
+    if (entries.length !== 3)
+        return { kind: "payload_invalid" };
+    const byKey = new Map(entries);
+    const sessionPublicKeyXY = byKey.get(SESSION_KEY_PAYLOAD_KEY);
+    if (!(sessionPublicKeyXY instanceof Uint8Array) ||
+        sessionPublicKeyXY.length !== 64) {
+        return { kind: "payload_invalid" };
+    }
+    const notBefore = toNumberIfInt(byKey.get(NOT_BEFORE_PAYLOAD_KEY));
+    const notAfter = toNumberIfInt(byKey.get(NOT_AFTER_PAYLOAD_KEY));
+    if (!isUnixMs(notBefore) || !isUnixMs(notAfter)) {
+        return { kind: "payload_invalid" };
+    }
+    const window = { notBefore, notAfter };
+    if (!windowWellFormed(window))
+        return { kind: "window_invalid" };
+    return { kind: "ok", sessionPublicKeyXY, window };
+}
+/** Read the assertion's flags byte from the -65800 envelope, if well-shaped. */
+function envelopeFlags(unprotected) {
+    const envelope = coseUnprotectedToMap(unprotected).get(WEBAUTHN_ENVELOPE_LABEL);
+    if (!Array.isArray(envelope) || envelope.length !== 2)
+        return null;
+    const authenticatorData = envelope[0];
+    if (!(authenticatorData instanceof Uint8Array) ||
+        authenticatorData.length < 37) {
+        return null;
+    }
+    return authenticatorData[32];
+}
+/**
+ * Verify a v2 session-key endorsement under the passkey root and yield the
+ * endorsed session key plus its window. All the ADR-0063 envelope checks
+ * (challenge binding to this artifact's `Sig_structure`, UP flag, ceremony
+ * type, low-s, both fail-closed directions) run inside the shared `-65800`
+ * verify branch; this function adds the ADR-0064/0065 typing rules on top
+ * and reports a missing-UV rejection under its own reason so admission can
+ * name it (`endorsement_uv_required`, ADR-0065 §4).
+ *
+ * @param endorsementCbor - The endorsement COSE Sign1 bytes
+ * @param rootKeys - Passkey root trust anchor(s), tried in order. Raw
+ *   coordinate anchors additionally pin `kid == root x`.
+ * @param opts - UV requirement and failure logging
+ */
+export async function verifySessionKeyEndorsement(endorsementCbor, rootKeys, opts) {
+    const anchors = Array.isArray(rootKeys) ? rootKeys : [rootKeys];
+    const decoded = decodeCoseSign1(endorsementCbor);
+    if (!decoded)
+        return { ok: false, reason: "endorsement_malformed" };
+    const header = protectedHeaderEntries(decoded.protectedBstr);
+    if (!header)
+        return { ok: false, reason: "endorsement_malformed" };
+    const alg = typeof header.alg === "bigint" ? Number(header.alg) : header.alg;
+    if (alg !== COSE_ALG_ES256_WEBAUTHN) {
+        return { ok: false, reason: "wrong_alg" };
+    }
+    if (header.cty !== SESSION_KEY_ENDORSEMENT_CONTENT_TYPE) {
+        return { ok: false, reason: "wrong_content_type" };
+    }
+    if (!(header.kid instanceof Uint8Array) || header.kid.length !== 32) {
+        return { ok: false, reason: "kid_invalid" };
+    }
+    const payload = decodePayloadV2(decoded.payloadBstr);
+    if (payload.kind !== "ok")
+        return { ok: false, reason: payload.kind };
+    if (opts?.requireUserVerification) {
+        const flags = envelopeFlags(decoded.unprotected);
+        // A malformed envelope is left to the shared branch to reject; only a
+        // well-shaped assertion that plainly lacks UV gets the distinct reason.
+        if (flags !== null && (flags & AUTH_FLAG_UV) === 0) {
+            return { ok: false, reason: "uv_required" };
+        }
+    }
+    let kidMismatch = false;
+    for (const anchor of anchors) {
+        // When the anchor exposes raw coordinates, the signed kid must name it —
+        // a valid signature under a root whose x is not the kid is evidence of
+        // artifact confusion, not authorization (ADR-0064 §2 kid = root x).
+        if (!(anchor instanceof CryptoKey)) {
+            const x = anchor.x;
+            if (x.length !== header.kid.length ||
+                !x.every((b, i) => b === header.kid[i])) {
+                kidMismatch = true;
+                continue;
+            }
+        }
+        const sigOk = await verifyCoseSign1WithParsedKey(endorsementCbor, anchor, {
+            requireUserVerification: opts?.requireUserVerification,
+            logFailures: opts?.logFailures,
+            logPrefix: opts?.logPrefix ?? "session-key-endorsement",
+        });
+        if (!sigOk)
+            continue;
+        let sessionKey;
+        try {
+            sessionKey = await importEs256PublicKeyFromGrantDataXy64(payload.sessionPublicKeyXY);
+        }
+        catch {
+            return { ok: false, reason: "session_key_import_failed" };
+        }
+        return {
+            ok: true,
+            sessionPublicKeyXY: payload.sessionPublicKeyXY,
+            sessionKey,
+            ...payload.window,
+        };
+    }
+    return {
+        ok: false,
+        reason: kidMismatch ? "kid_mismatch" : "signature_invalid",
+    };
+}
+/**
+ * Is `atMs` inside the endorsement's window? `notBefore ≤ atMs ≤ notAfter`,
+ * both inclusive (ADR-0065 §3). `skewMs` (default 0) tolerates a `notBefore`
+ * slightly in the future of a wall-clock verifier; offline verifiers
+ * comparing against the receipted idtimestamp should leave it at 0 — that
+ * comparison is exact and authoritative.
+ *
+ * Deliberately a pure function of the two numbers so callers can (and must)
+ * run it on every request, structurally outside any verified-endorsement
+ * cache (ADR-0065 §4).
+ */
+export function checkEndorsementWindow(window, atMs, opts) {
+    const skew = opts?.skewMs ?? 0;
+    if (atMs + skew < window.notBefore) {
+        return { ok: false, reason: "endorsement_not_yet_valid" };
+    }
+    if (atMs > window.notAfter) {
+        return { ok: false, reason: "endorsement_expired" };
+    }
+    return { ok: true };
+}