raz-encrypt 2.3.0 → 2.4.0

package/dist/canonicalJson.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Canonical JSON per RFC 8785 (JCS): no whitespace, object keys sorted by
+ * UTF-16 code unit, ECMAScript number and string serialization — so the same
+ * logical document always hashes to the same value regardless of key order
+ * on the wire.
+ *
+ * Unlike a bare `JSON.stringify`, this rejects (with a `TypeError` naming the
+ * offending path) every value that JSON cannot represent faithfully, rather
+ * than silently collapsing it into something else. Two different in-memory
+ * documents must never canonicalize to the same bytes (ADR 0012):
+ * `undefined`, `NaN`, `±Infinity`, `BigInt`, functions, symbols, sparse
+ * arrays, circular references, lone surrogates, and anything that is not a
+ * plain object / array / string / finite number / boolean / null (`Map`,
+ * `Set`, `Date`, typed arrays, class instances, ...).
+ */
 export declare function canonicalize(value: unknown): string;
 /** The document hash every signature is made over. */
 export declare function hashDocument(value: unknown): string;

package/dist/canonicalJson.js

@@ -1,22 +1,82 @@
 import { sha512 } from "@noble/hashes/sha2.js";
 import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
 /**
- * Deterministic JSON serialization (object keys sorted recursively) so the
- * same logical document always hashes to the same value regardless of key
- * order on the wire.
+ * Canonical JSON per RFC 8785 (JCS): no whitespace, object keys sorted by
+ * UTF-16 code unit, ECMAScript number and string serialization — so the same
+ * logical document always hashes to the same value regardless of key order
+ * on the wire.
+ *
+ * Unlike a bare `JSON.stringify`, this rejects (with a `TypeError` naming the
+ * offending path) every value that JSON cannot represent faithfully, rather
+ * than silently collapsing it into something else. Two different in-memory
+ * documents must never canonicalize to the same bytes (ADR 0012):
+ * `undefined`, `NaN`, `±Infinity`, `BigInt`, functions, symbols, sparse
+ * arrays, circular references, lone surrogates, and anything that is not a
+ * plain object / array / string / finite number / boolean / null (`Map`,
+ * `Set`, `Date`, typed arrays, class instances, ...).
  */
-function sortKeysDeep(value) {
-    if (Array.isArray(value))
-        return value.map(sortKeysDeep);
-    if (value !== null && typeof value === "object") {
-        return Object.fromEntries(Object.keys(value)
-            .sort()
-            .map((key) => [key, sortKeysDeep(value[key])]));
+export function canonicalize(value) {
+    return serialize(value, "$", new Set());
+}
+function fail(path, what) {
+    throw new TypeError(`canonicalize: ${what} at ${path} cannot be represented as canonical JSON`);
+}
+function serialize(value, path, ancestors) {
+    switch (typeof value) {
+        case "string":
+            return serializeString(value, path);
+        case "number":
+            if (!Number.isFinite(value))
+                fail(path, `non-finite number (${String(value)})`);
+            // ECMAScript Number::toString is exactly what RFC 8785 §3.2.2.3 mandates
+            // (including "-0" -> "0").
+            return JSON.stringify(value);
+        case "boolean":
+            return value ? "true" : "false";
+        case "object":
+            break;
+        default:
+            return fail(path, typeof value === "undefined" ? "undefined" : `${typeof value}`);
+    }
+    if (value === null)
+        return "null";
+    const obj = value;
+    if (ancestors.has(obj))
+        fail(path, "circular reference");
+    ancestors.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            const parts = [];
+            for (let i = 0; i < obj.length; i++) {
+                if (!(i in obj))
+                    fail(`${path}[${i}]`, "hole in sparse array");
+                parts.push(serialize(obj[i], `${path}[${i}]`, ancestors));
+            }
+            return `[${parts.join(",")}]`;
+        }
+        const proto = Object.getPrototypeOf(obj);
+        if (proto !== Object.prototype && proto !== null) {
+            fail(path, `non-plain object (${proto.constructor?.name ?? "unknown"})`);
+        }
+        const record = obj;
+        // Default sort() compares UTF-16 code units, which is the RFC 8785 order.
+        const keys = Object.keys(record).sort();
+        const parts = keys.map((key) => `${serializeString(key, `${path}.${key}`)}:${serialize(record[key], `${path}.${key}`, ancestors)}`);
+        return `{${parts.join(",")}}`;
+    }
+    finally {
+        ancestors.delete(obj);
     }
-    return value;
 }
-export function canonicalize(value) {
-    return JSON.stringify(sortKeysDeep(value));
+// High surrogate not followed by a low one, or a low surrogate not preceded by a high one.
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+function serializeString(value, path) {
+    // RFC 8785 requires I-JSON: strings must be well-formed UTF-16. A lone
+    // surrogate has no UTF-8 encoding, so two distinct strings would otherwise
+    // both turn into U+FFFD when hashed.
+    if (LONE_SURROGATE.test(value))
+        fail(path, "string with a lone surrogate");
+    return JSON.stringify(value);
 }
 /** The document hash every signature is made over. */
 export function hashDocument(value) {

package/dist/canonicalJson.js.map

@@ -1 +1 @@
-{"version":3,"file":"canonicalJson.js","sourceRoot":"","sources":["../src/canonicalJson.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC;aAC1C,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"canonicalJson.js","sourceRoot":"","sources":["../src/canonicalJson.ts"],"names":[],"mappings":"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"}

package/dist/core.d.ts

@@ -10,8 +10,8 @@
  * included, fs-backed versions of the same logic — this module is the
  * un-wired core they're built from, not a separate implementation.
  */
-export { createResponderHandshakeCore as createResponderHandshake, decryptFromCore as decryptFrom, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, HandshakeVerificationError, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
-export type { Certificate, EncryptedBox, HandshakeSignature, InitiatorHandshakeMessage, InitiatorSessionResult, LogDeps, ResponderHandshakeInit, ResponderHandshakeMessage, ResponderHandshakeSecrets, ResponderSessionResult, SessionKeys, SignOptions, TrustDeps, TrustStatus, VerifyDeps, VerifyFailureReason, VerifyResult, } from "./crypto/hybrid.js";
+export { createResponderHandshakeCore as createResponderHandshake, decryptFromCore as decryptFrom, DecryptionError, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, HandshakeVerificationError, makeKeyConfirmation, verifyKeyConfirmation, MalformedHandshakeMessageError, ReplayedBoxError, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
+export type { BoxReplayInfo, Certificate, DecryptDeps, EncryptedBox, HandshakeRole, HandshakeSignature, HandshakeTranscript, InitiatorHandshakeMessage, InitiatorSessionResult, LogDeps, ResponderHandshakeInit, ResponderHandshakeMessage, ResponderHandshakeSecrets, ResponderSessionResult, SessionKeys, SignOptions, TrustDeps, TrustStatus, VerifyDeps, VerifyFailureReason, VerifyResult, } from "./crypto/hybrid.js";
 export { generateClassicalKeypair, classicalSharedSecret, classicalSign, classicalVerify } from "./crypto/classical.js";
 export type { ClassicalKeypair } from "./crypto/classical.js";
 export { generatePqcKemKeypair, generatePqcSignKeypair, pqcDecapsulate, pqcEncapsulate, pqcSign, pqcVerify, } from "./crypto/pqc.js";
@@ -20,6 +20,8 @@ export { canonicalize, hashDocument } from "./canonicalJson.js";
 export { fingerprint } from "./fingerprint.js";
 export { decryptFrame, encryptFrame, FrameDecryptionError } from "./crypto/frameCipher.js";
 export type { EncryptedFrame } from "./crypto/frameCipher.js";
+export { createFrameChannels, FrameCounterError, FrameReceiver, FrameSender } from "./crypto/frameSession.js";
+export { ConfirmedSession, UnconfirmedSessionError } from "./crypto/confirmedSession.js";
 export { CHAIN_INFO_INITIATOR_TO_RESPONDER, CHAIN_INFO_RESPONDER_TO_INITIATOR, ML_KEM_STEP_CADENCE, performEcdhStep, performKemStep, ratchetChainKey, seedChainKey, } from "./crypto/ratchet.js";
 export type { AsymmetricStepResult, ChainStep } from "./crypto/ratchet.js";
 export type { Identity, PublicCard } from "./identity.js";

package/dist/core.js

@@ -10,11 +10,13 @@
  * included, fs-backed versions of the same logic — this module is the
  * un-wired core they're built from, not a separate implementation.
  */
-export { createResponderHandshakeCore as createResponderHandshake, decryptFromCore as decryptFrom, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, HandshakeVerificationError, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
+export { createResponderHandshakeCore as createResponderHandshake, decryptFromCore as decryptFrom, DecryptionError, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, HandshakeVerificationError, makeKeyConfirmation, verifyKeyConfirmation, MalformedHandshakeMessageError, ReplayedBoxError, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
 export { generateClassicalKeypair, classicalSharedSecret, classicalSign, classicalVerify } from "./crypto/classical.js";
 export { generatePqcKemKeypair, generatePqcSignKeypair, pqcDecapsulate, pqcEncapsulate, pqcSign, pqcVerify, } from "./crypto/pqc.js";
 export { canonicalize, hashDocument } from "./canonicalJson.js";
 export { fingerprint } from "./fingerprint.js";
 export { decryptFrame, encryptFrame, FrameDecryptionError } from "./crypto/frameCipher.js";
+export { createFrameChannels, FrameCounterError, FrameReceiver, FrameSender } from "./crypto/frameSession.js";
+export { ConfirmedSession, UnconfirmedSessionError } from "./crypto/confirmedSession.js";
 export { CHAIN_INFO_INITIATOR_TO_RESPONDER, CHAIN_INFO_RESPONDER_TO_INITIATOR, ML_KEM_STEP_CADENCE, performEcdhStep, performKemStep, ratchetChainKey, seedChainKey, } from "./crypto/ratchet.js";
 //# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -1 +1 @@
-{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,4BAA4B,IAAI,wBAAwB,EACxD,eAAe,IAAI,WAAW,EAC9B,cAAc,IAAI,UAAU,EAC5B,6BAA6B,IAAI,yBAAyB,EAC1D,6BAA6B,IAAI,yBAAyB,EAC1D,0BAA0B,EAC1B,QAAQ,IAAI,IAAI,EAChB,mBAAmB,EACnB,UAAU,IAAI,MAAM,GACrB,MAAM,oBAAoB,CAAC;AAqB5B,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,OAAO,EACP,SAAS,GACV,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAG3F,OAAO,EACL,iCAAiC,EACjC,iCAAiC,EACjC,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,GACb,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,4BAA4B,IAAI,wBAAwB,EACxD,eAAe,IAAI,WAAW,EAC9B,eAAe,EACf,cAAc,IAAI,UAAU,EAC5B,6BAA6B,IAAI,yBAAyB,EAC1D,6BAA6B,IAAI,yBAAyB,EAC1D,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,8BAA8B,EAC9B,gBAAgB,EAChB,QAAQ,IAAI,IAAI,EAChB,mBAAmB,EACnB,UAAU,IAAI,MAAM,GACrB,MAAM,oBAAoB,CAAC;AAyB5B,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,OAAO,EACP,SAAS,GACV,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE3F,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC9G,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEzF,OAAO,EACL,iCAAiC,EACjC,iCAAiC,EACjC,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,GACb,MAAM,qBAAqB,CAAC"}

package/dist/crypto/classical.d.ts

@@ -8,3 +8,5 @@ export declare function classicalSign(message: Uint8Array, secretKey: Uint8Array
 export declare function classicalVerify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
 /** ECDH shared secret between our secret key and their public key. */
 export declare function classicalSharedSecret(secretKey: Uint8Array, theirPublicKey: Uint8Array): Uint8Array;
+/** True iff `keypair`'s two fields are the exact byte lengths p384's own keygen produces — a cheap sanity check for key material sourced from somewhere this library doesn't control (e.g. a caller-supplied KeyStore, issue #38). */
+export declare function isValidClassicalKeypairShape(keypair: ClassicalKeypair): boolean;

package/dist/crypto/classical.js

@@ -18,4 +18,8 @@ export function classicalVerify(signature, message, publicKey) {
 export function classicalSharedSecret(secretKey, theirPublicKey) {
     return p384.getSharedSecret(secretKey, theirPublicKey);
 }
+/** True iff `keypair`'s two fields are the exact byte lengths p384's own keygen produces — a cheap sanity check for key material sourced from somewhere this library doesn't control (e.g. a caller-supplied KeyStore, issue #38). */
+export function isValidClassicalKeypairShape(keypair) {
+    return keypair.secretKey.length === p384.lengths.secretKey && keypair.publicKey.length === p384.lengths.publicKey;
+}
 //# sourceMappingURL=classical.js.map

package/dist/crypto/classical.js.map

@@ -1 +1 @@
-{"version":3,"file":"classical.js","sourceRoot":"","sources":["../../src/crypto/classical.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAO7C,yEAAyE;AACzE,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAmB,EAAE,SAAqB;IACtE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,SAAqB,EAAE,OAAmB,EAAE,SAAqB;IAC/F,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,qBAAqB,CAAC,SAAqB,EAAE,cAA0B;IACrF,OAAO,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"classical.js","sourceRoot":"","sources":["../../src/crypto/classical.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAO7C,yEAAyE;AACzE,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAmB,EAAE,SAAqB;IACtE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,SAAqB,EAAE,OAAmB,EAAE,SAAqB;IAC/F,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,qBAAqB,CAAC,SAAqB,EAAE,cAA0B;IACrF,OAAO,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AACzD,CAAC;AAED,sOAAsO;AACtO,MAAM,UAAU,4BAA4B,CAAC,OAAyB;IACpE,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;AACpH,CAAC"}

package/dist/crypto/confirmedSession.d.ts

@@ -0,0 +1,47 @@
+import type { EncryptedFrame } from "./frameCipher.js";
+import { type HandshakeRole, type HandshakeTranscript, type InitiatorSessionResult, type ResponderSessionResult } from "./hybrid.js";
+/**
+ * ConfirmedSession (issue #40/ADR 0025): a high-level gate in front of
+ * FrameSender/FrameReceiver that makes it hard to skip key confirmation by
+ * accident. `createFrameChannels` already builds a ready-to-use
+ * sender/receiver pair straight from SessionKeys with no confirmation gate
+ * at all — a caller could start sending and receiving the instant the
+ * handshake returns, with nothing to signal that confirmation (issue #8's
+ * makeKeyConfirmation/verifyKeyConfirmation) was skipped entirely.
+ *
+ * This class adds exactly one thing, no new crypto: a gate. It performs NO
+ * network I/O — the caller still transports the handshake messages and the
+ * confirmation tags over whatever channel they already use, exactly as for
+ * the low-level functions, which are completely unchanged and remain the
+ * supported API for advanced use.
+ */
+export declare class UnconfirmedSessionError extends Error {
+    constructor(operation: "seal" | "open");
+}
+export declare class ConfirmedSession {
+    private readonly role;
+    private readonly counterpartRole;
+    private readonly confirmationKey;
+    private readonly transcript;
+    private readonly sender;
+    private readonly receiver;
+    private confirmed;
+    /** The tag to send the counterpart — computed eagerly, send it as soon as you have a channel to send it over. */
+    readonly ownConfirmationTag: string;
+    constructor(role: HandshakeRole, result: InitiatorSessionResult | ResponderSessionResult, transcript: HandshakeTranscript);
+    /** Whether `confirmPeer` has already succeeded. `seal`/`open` are only usable once this is true. */
+    get isConfirmed(): boolean;
+    /**
+     * Verifies the tag received from the counterpart. Returns `false` for a
+     * wrong or malformed tag — never throws, matching `verifyKeyConfirmation`'s
+     * own contract — so you decide what to do (retry, abort, log). Once this
+     * returns `true`, the gate opens permanently; nothing closes it again.
+     */
+    confirmPeer(peerTag: unknown): boolean;
+    /** Encrypts `plaintext` at the next counter. Throws UnconfirmedSessionError until `confirmPeer` has succeeded. */
+    seal(plaintext: Uint8Array, aad?: Uint8Array): EncryptedFrame;
+    /** Opens a received frame. Throws UnconfirmedSessionError until `confirmPeer` has succeeded — reading content from an unconfirmed counterpart is exactly the mistake key confirmation exists to prevent. */
+    open(frame: EncryptedFrame, aad?: Uint8Array): Uint8Array;
+    /** Wipes the wrapped sender/receiver's key copies and this object's own copy of the confirmation key. Unusable afterwards. */
+    destroy(): void;
+}

package/dist/crypto/confirmedSession.js

@@ -0,0 +1,84 @@
+import { createFrameChannels } from "./frameSession.js";
+import { makeKeyConfirmation, verifyKeyConfirmation, } from "./hybrid.js";
+/**
+ * ConfirmedSession (issue #40/ADR 0025): a high-level gate in front of
+ * FrameSender/FrameReceiver that makes it hard to skip key confirmation by
+ * accident. `createFrameChannels` already builds a ready-to-use
+ * sender/receiver pair straight from SessionKeys with no confirmation gate
+ * at all — a caller could start sending and receiving the instant the
+ * handshake returns, with nothing to signal that confirmation (issue #8's
+ * makeKeyConfirmation/verifyKeyConfirmation) was skipped entirely.
+ *
+ * This class adds exactly one thing, no new crypto: a gate. It performs NO
+ * network I/O — the caller still transports the handshake messages and the
+ * confirmation tags over whatever channel they already use, exactly as for
+ * the low-level functions, which are completely unchanged and remain the
+ * supported API for advanced use.
+ */
+export class UnconfirmedSessionError extends Error {
+    constructor(operation) {
+        super(`Cannot ${operation}: key confirmation has not succeeded yet. Call confirmPeer(peerTag) with the tag received from the counterpart first.`);
+        this.name = "UnconfirmedSessionError";
+    }
+}
+export class ConfirmedSession {
+    role;
+    counterpartRole;
+    confirmationKey;
+    transcript;
+    sender;
+    receiver;
+    confirmed = false;
+    /** The tag to send the counterpart — computed eagerly, send it as soon as you have a channel to send it over. */
+    ownConfirmationTag;
+    constructor(role, result, transcript) {
+        this.role = role;
+        this.counterpartRole = role === "initiator" ? "responder" : "initiator";
+        // A private copy, same reason FrameSender/FrameReceiver copy their keys
+        // (./frameSession.js): destroy() must never reach back and mutate the
+        // caller's own handshake-result object.
+        this.confirmationKey = result.confirmationKey.slice();
+        this.transcript = transcript;
+        this.ownConfirmationTag = makeKeyConfirmation(result.confirmationKey, role, transcript);
+        const { sender, receiver } = createFrameChannels(result.keys, role);
+        this.sender = sender;
+        this.receiver = receiver;
+    }
+    /** Whether `confirmPeer` has already succeeded. `seal`/`open` are only usable once this is true. */
+    get isConfirmed() {
+        return this.confirmed;
+    }
+    /**
+     * Verifies the tag received from the counterpart. Returns `false` for a
+     * wrong or malformed tag — never throws, matching `verifyKeyConfirmation`'s
+     * own contract — so you decide what to do (retry, abort, log). Once this
+     * returns `true`, the gate opens permanently; nothing closes it again.
+     */
+    confirmPeer(peerTag) {
+        if (this.confirmed)
+            return true;
+        if (verifyKeyConfirmation(this.confirmationKey, this.counterpartRole, this.transcript, peerTag)) {
+            this.confirmed = true;
+        }
+        return this.confirmed;
+    }
+    /** Encrypts `plaintext` at the next counter. Throws UnconfirmedSessionError until `confirmPeer` has succeeded. */
+    seal(plaintext, aad) {
+        if (!this.confirmed)
+            throw new UnconfirmedSessionError("seal");
+        return this.sender.seal(plaintext, aad);
+    }
+    /** Opens a received frame. Throws UnconfirmedSessionError until `confirmPeer` has succeeded — reading content from an unconfirmed counterpart is exactly the mistake key confirmation exists to prevent. */
+    open(frame, aad) {
+        if (!this.confirmed)
+            throw new UnconfirmedSessionError("open");
+        return this.receiver.open(frame, aad);
+    }
+    /** Wipes the wrapped sender/receiver's key copies and this object's own copy of the confirmation key. Unusable afterwards. */
+    destroy() {
+        this.sender.destroy();
+        this.receiver.destroy();
+        this.confirmationKey.fill(0);
+    }
+}
+//# sourceMappingURL=confirmedSession.js.map

package/dist/crypto/confirmedSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmedSession.js","sourceRoot":"","sources":["../../src/crypto/confirmedSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAA8B,MAAM,mBAAmB,CAAC;AAEpF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GAKtB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,SAA0B;QACpC,KAAK,CAAC,UAAU,SAAS,uHAAuH,CAAC,CAAC;QAClJ,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,gBAAgB;IACV,IAAI,CAAgB;IACpB,eAAe,CAAgB;IAC/B,eAAe,CAAa;IAC5B,UAAU,CAAsB;IAChC,MAAM,CAAc;IACpB,QAAQ,CAAgB;IACjC,SAAS,GAAG,KAAK,CAAC;IAE1B,iHAAiH;IACxG,kBAAkB,CAAS;IAEpC,YAAY,IAAmB,EAAE,MAAuD,EAAE,UAA+B;QACvH,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,eAAe,GAAG,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC;QACxE,wEAAwE;QACxE,sEAAsE;QACtE,wCAAwC;QACxC,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QACtD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,kBAAkB,GAAG,mBAAmB,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QACxF,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,oGAAoG;IACpG,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,OAAgB;QAC1B,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,qBAAqB,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC;YAChG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,kHAAkH;IAClH,IAAI,CAAC,SAAqB,EAAE,GAAgB;QAC1C,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,4MAA4M;IAC5M,IAAI,CAAC,KAAqB,EAAE,GAAgB;QAC1C,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,8HAA8H;IAC9H,OAAO;QACL,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/crypto/frameCipher.js

@@ -1,5 +1,9 @@
 import { gcm } from "@noble/ciphers/aes.js";
 import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+// Prefer FrameSender/FrameReceiver (./frameSession.ts), which own the counter so
+// it cannot be reused by mistake; use these raw functions only if you must manage
+// counters yourself.
+//
 // The per-frame AEAD used to wrap every message sent under a session key
 // established by establishSessionInitiatorCore/establishSessionResponderCore
 // (see hybrid.ts) — one directional key, reused across many frames, so the
@@ -20,8 +24,10 @@ export class FrameDecryptionError extends Error {
 }
 /** Encodes `counter` as a 96-bit nonce: 4 zero bytes + an 8-byte big-endian counter (2^64 frames is far beyond any realistic session). */
 function counterToNonce(counter) {
-    if (!Number.isInteger(counter) || counter < 0) {
-        throw new Error(`Frame counter must be a non-negative integer, got ${counter}.`);
+    // isSafeInteger, not isInteger: above 2^53 distinct counters can round to
+    // the same double, which would silently reuse a nonce.
+    if (!Number.isSafeInteger(counter) || counter < 0) {
+        throw new Error(`Frame counter must be a non-negative safe integer (0 to 2^53-1), got ${counter}.`);
     }
     const nonce = new Uint8Array(NONCE_LENGTH);
     let value = BigInt(counter);

package/dist/crypto/frameCipher.js.map

@@ -1 +1 @@
-{"version":3,"file":"frameCipher.js","sourceRoot":"","sources":["../../src/crypto/frameCipher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEhE,yEAAyE;AACzE,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,wEAAwE;AACxE,gBAAgB;AAEhB,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;QACE,KAAK,CAAC,+FAA+F,CAAC,CAAC;QACvG,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AASD,0IAA0I;AAC1I,SAAS,cAAc,CAAC,OAAe;IACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,qDAAqD,OAAO,GAAG,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC,IAAI,YAAY,GAAG,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;QACtE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;QACjC,KAAK,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,OAAe,EAAE,SAAqB,EAAE,GAAgB;IACpG,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,KAAqB,EAAE,GAAgB;IACnF,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5F,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,oBAAoB,EAAE,CAAC;IACnC,CAAC;AACH,CAAC"}
+{"version":3,"file":"frameCipher.js","sourceRoot":"","sources":["../../src/crypto/frameCipher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEhE,iFAAiF;AACjF,kFAAkF;AAClF,qBAAqB;AACrB,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,wEAAwE;AACxE,gBAAgB;AAEhB,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;QACE,KAAK,CAAC,+FAA+F,CAAC,CAAC;QACvG,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AASD,0IAA0I;AAC1I,SAAS,cAAc,CAAC,OAAe;IACrC,0EAA0E;IAC1E,uDAAuD;IACvD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,wEAAwE,OAAO,GAAG,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC,IAAI,YAAY,GAAG,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;QACtE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;QACjC,KAAK,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,OAAe,EAAE,SAAqB,EAAE,GAAgB;IACpG,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,KAAqB,EAAE,GAAgB;IACnF,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5F,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,oBAAoB,EAAE,CAAC;IACnC,CAAC;AACH,CAAC"}

package/dist/crypto/frameSession.d.ts

@@ -0,0 +1,40 @@
+import { type EncryptedFrame } from "./frameCipher.js";
+import type { SessionKeys } from "./hybrid.js";
+/** Thrown for counter misuse: exhausted space, a replayed or out-of-order counter, a malformed counter, or use after destroy(). */
+export declare class FrameCounterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Seals frames under one directional key, owning the counter. Use exactly one
+ * sender per key, and never create a second sender for a key that has already
+ * been used: a new sender starts again at counter 0.
+ */
+export declare class FrameSender {
+    private key;
+    private next;
+    private exhausted;
+    constructor(key: Uint8Array);
+    /** Encrypts `plaintext` at the next counter. The counter is spent before encrypting, so a failure can never lead to reuse. `aad` has the same meaning as in encryptFrame. */
+    seal(plaintext: Uint8Array, aad?: Uint8Array): EncryptedFrame;
+    /** Wipes this sender's private copy of the key. The array you passed in is not touched. */
+    destroy(): void;
+}
+/**
+ * Opens frames under one directional key and rejects any counter that is not
+ * higher than the last frame it opened. Gaps are allowed (a dropped frame is
+ * not an attack); repeats and reordering are not. State only moves after a
+ * frame authenticates, so forged frames cannot advance it.
+ */
+export declare class FrameReceiver {
+    private key;
+    private last;
+    constructor(key: Uint8Array);
+    open(frame: EncryptedFrame, aad?: Uint8Array): Uint8Array;
+    /** Wipes this receiver's private copy of the key. The array you passed in is not touched. */
+    destroy(): void;
+}
+/** Pairs the right directional keys for your role so a sender can never be given the receiving key by mistake. */
+export declare function createFrameChannels(keys: SessionKeys, role: "initiator" | "responder"): {
+    sender: FrameSender;
+    receiver: FrameReceiver;
+};

package/dist/crypto/frameSession.js

@@ -0,0 +1,96 @@
+import { decryptFrame, encryptFrame } from "./frameCipher.js";
+// Stateful wrappers around encryptFrame/decryptFrame (ADR 0020, issue #35).
+//
+// AES-GCM breaks badly if a (key, nonce) pair is ever used twice, and the
+// low-level functions take the counter from the caller, so a stray retry, a
+// restored snapshot or a second code path sharing a key can reuse one without
+// anyone noticing. These classes own the counter instead: the sender can only
+// move forward and never repeats, the receiver only accepts a counter higher
+// than the last one it successfully opened.
+const KEY_LENGTH = 32;
+/** Thrown for counter misuse: exhausted space, a replayed or out-of-order counter, a malformed counter, or use after destroy(). */
+export class FrameCounterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FrameCounterError";
+    }
+}
+function copyKey(key) {
+    if (!(key instanceof Uint8Array) || key.length !== KEY_LENGTH) {
+        throw new TypeError(`Frame key must be a ${KEY_LENGTH}-byte Uint8Array.`);
+    }
+    return key.slice();
+}
+/**
+ * Seals frames under one directional key, owning the counter. Use exactly one
+ * sender per key, and never create a second sender for a key that has already
+ * been used: a new sender starts again at counter 0.
+ */
+export class FrameSender {
+    key;
+    next = 0;
+    exhausted = false;
+    constructor(key) {
+        this.key = copyKey(key);
+    }
+    /** Encrypts `plaintext` at the next counter. The counter is spent before encrypting, so a failure can never lead to reuse. `aad` has the same meaning as in encryptFrame. */
+    seal(plaintext, aad) {
+        if (!this.key)
+            throw new FrameCounterError("This FrameSender was destroyed.");
+        if (this.exhausted)
+            throw new FrameCounterError("Frame counter space is exhausted for this key; establish a new session.");
+        const counter = this.next;
+        if (counter === Number.MAX_SAFE_INTEGER)
+            this.exhausted = true;
+        else
+            this.next = counter + 1;
+        return encryptFrame(this.key, counter, plaintext, aad);
+    }
+    /** Wipes this sender's private copy of the key. The array you passed in is not touched. */
+    destroy() {
+        this.key?.fill(0);
+        this.key = null;
+    }
+}
+/**
+ * Opens frames under one directional key and rejects any counter that is not
+ * higher than the last frame it opened. Gaps are allowed (a dropped frame is
+ * not an attack); repeats and reordering are not. State only moves after a
+ * frame authenticates, so forged frames cannot advance it.
+ */
+export class FrameReceiver {
+    key;
+    last = -1;
+    constructor(key) {
+        this.key = copyKey(key);
+    }
+    open(frame, aad) {
+        if (!this.key)
+            throw new FrameCounterError("This FrameReceiver was destroyed.");
+        const counter = frame?.counter;
+        if (typeof counter !== "number" || !Number.isSafeInteger(counter) || counter < 0) {
+            throw new FrameCounterError("Frame counter must be a non-negative safe integer.");
+        }
+        if (counter <= this.last)
+            throw new FrameCounterError(`Frame counter ${counter} was already used or is out of order (last accepted: ${this.last}).`);
+        const plaintext = decryptFrame(this.key, frame, aad);
+        this.last = counter;
+        return plaintext;
+    }
+    /** Wipes this receiver's private copy of the key. The array you passed in is not touched. */
+    destroy() {
+        this.key?.fill(0);
+        this.key = null;
+    }
+}
+/** Pairs the right directional keys for your role so a sender can never be given the receiving key by mistake. */
+export function createFrameChannels(keys, role) {
+    if (role === "initiator") {
+        return { sender: new FrameSender(keys.initiatorToResponder), receiver: new FrameReceiver(keys.responderToInitiator) };
+    }
+    if (role === "responder") {
+        return { sender: new FrameSender(keys.responderToInitiator), receiver: new FrameReceiver(keys.initiatorToResponder) };
+    }
+    throw new TypeError(`Unknown role "${String(role)}": expected "initiator" or "responder".`);
+}
+//# sourceMappingURL=frameSession.js.map

package/dist/crypto/frameSession.js.map

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