raz-encrypt 0.3.0 → 1.1.0

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 { decryptFromCore as decryptFrom, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
-export type { Certificate, EncryptedBox, InitiatorSessionResult, LogDeps, SessionKeys, SignOptions, TrustDeps, TrustStatus, VerifyDeps, VerifyFailureReason, VerifyResult, } from "./crypto/hybrid.js";
+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 { 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,4 +20,6 @@ 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 { 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,10 +10,11 @@
  * included, fs-backed versions of the same logic — this module is the
  * un-wired core they're built from, not a separate implementation.
  */
-export { decryptFromCore as decryptFrom, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
+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 { 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 { 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,eAAe,IAAI,WAAW,EAC9B,cAAc,IAAI,UAAU,EAC5B,6BAA6B,IAAI,yBAAyB,EAC1D,6BAA6B,IAAI,yBAAyB,EAC1D,QAAQ,IAAI,IAAI,EAChB,mBAAmB,EACnB,UAAU,IAAI,MAAM,GACrB,MAAM,oBAAoB,CAAC;AAe5B,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"}
+{"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"}

package/dist/crypto/hybrid.d.ts

@@ -87,31 +87,105 @@ export declare function encryptForCore(identity: Identity, counterpart: PublicCa
  */
 export declare function decryptFromCore<T = unknown>(identity: Identity, counterpart: PublicCard, box: EncryptedBox, deps: TrustDeps): Promise<T>;
 export interface SessionKeys {
-    /** AES-256-GCM key for frames sent by the initiator (the side that encapsulated), decrypted by the responder. */
+    /** AES-256-GCM key for frames sent by the initiator, decrypted by the responder. */
     initiatorToResponder: Uint8Array;
-    /** AES-256-GCM key for frames sent by the responder (the side that decapsulated), decrypted by the initiator. */
+    /** AES-256-GCM key for frames sent by the responder, decrypted by the initiator. */
     responderToInitiator: Uint8Array;
 }
-export interface InitiatorSessionResult {
-    /** Send this to the responder — the only message this handshake requires; the ECDH half needs no message since both sides derive it locally from already-exchanged Public Cards. */
+/** The dual classical+PQ signature over a handshake message's own signed ephemeral payload (see `handshakeSignedMessage`). */
+export interface HandshakeSignature {
+    classicalSignature: string;
+    pqcSignature: string;
+}
+/**
+ * The responder's half of the handshake: one fresh ECDH-P384 public key,
+ * one fresh ML-KEM-1024 public key, and a per-handshake nonce, dual-signed
+ * with the responder's long-term classical+PQ signing keys.
+ */
+export interface ResponderHandshakeMessage {
+    ephemeralClassicalPublicKey: string;
+    ephemeralKemPublicKey: string;
+    nonce: string;
+    signature: HandshakeSignature;
+}
+/**
+ * The initiator's reply: its own fresh ECDH-P384 public key and nonce
+ * (dual-signed), plus the ML-KEM ciphertext encapsulated toward the
+ * responder's ephemeral KEM public key (never the responder's long-term
+ * one).
+ */
+export interface InitiatorHandshakeMessage {
+    ephemeralClassicalPublicKey: string;
+    nonce: string;
+    signature: HandshakeSignature;
     kemCipherText: string;
+}
+/**
+ * The responder's ephemeral secrets plus everything needed to reconstruct
+ * its own signed message for the transcript hash later. Returned to the
+ * caller only to be threaded straight into `establishSessionResponderCore`
+ * for THIS handshake attempt — never persisted, logged, or attached to
+ * Identity, and discarded (left for GC) once that call returns.
+ */
+export interface ResponderHandshakeSecrets {
+    ephemeralClassicalSecretKey: Uint8Array;
+    ephemeralKemSecretKey: Uint8Array;
+    message: ResponderHandshakeMessage;
+}
+export interface ResponderHandshakeInit {
+    message: ResponderHandshakeMessage;
+    ephemeral: ResponderHandshakeSecrets;
+}
+export interface InitiatorSessionResult {
+    /** Send this to the responder to complete the handshake. */
+    message: InitiatorHandshakeMessage;
     keys: SessionKeys;
+    /** HKDF output #3 — proves both sides derived the same combined secret before any chat/file-transfer traffic is trusted. Using it (e.g. as a MAC key over the transcript) is the caller's concern. */
+    confirmationKey: Uint8Array;
+    /** HKDF output #4 (additive, issue #29) — seeds a two-party ratchet (see ./ratchet.ts) built on top of this handshake. Not a replacement for `keys`/`confirmationKey`, and never used to encrypt a frame directly. */
+    rootKey: Uint8Array;
 }
+export interface ResponderSessionResult {
+    keys: SessionKeys;
+    confirmationKey: Uint8Array;
+    /** See InitiatorSessionResult.rootKey. */
+    rootKey: Uint8Array;
+}
+export declare class HandshakeVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * First step of the handshake, run by the connection's responder: generates
+ * one fresh, single-use ECDH-P384 keypair and one fresh, single-use
+ * ML-KEM-1024 keypair, a per-handshake nonce, and dual-signs all three with
+ * the responder's long-term classical+PQ signing keys. `message` is sent to
+ * the initiator (it can ride alongside the responder's PublicCard); `ephemeral`
+ * must be held in memory only and passed straight into
+ * `establishSessionResponderCore` once the initiator's reply arrives, then
+ * discarded.
+ */
+export declare function createResponderHandshakeCore(identity: Identity): ResponderHandshakeInit;
 /**
- * Establishes a session as the connection's initiator (the side that
- * created the WebRTC offer, in raz-encrypt-agnostic terms: whichever side
- * owns the single ML-KEM encapsulation this handshake performs). Computes
- * the ECDH-P384 secret with `counterpart` and one ML-KEM-1024 encapsulation
- * toward their KEM public key, then HKDF-splits the combined secret into two
- * directional AES-256-GCM keys. No trust dependency: establishing a session
- * never checks anyone's trust status, same as signCore.
+ * Establishes a session as the connection's initiator, given the
+ * responder's `ResponderHandshakeMessage`. Verifies the responder's dual
+ * signature (throws `HandshakeVerificationError` on failure), generates its
+ * own fresh, single-use ECDH-P384 keypair and nonce, dual-signs them,
+ * encapsulates toward the responder's ephemeral KEM public key, and derives
+ * the Session Keys plus a key-confirmation key from the combined ephemeral
+ * ECDH + KEM + long-term ECDH secret, salted by a hash of the full
+ * handshake transcript. The returned `message` is sent to the responder to
+ * complete the handshake. No trust dependency: establishing a session never
+ * checks anyone's trust status, same as signCore.
  */
-export declare function establishSessionInitiatorCore(identity: Identity, counterpart: PublicCard): InitiatorSessionResult;
+export declare function establishSessionInitiatorCore(identity: Identity, counterpart: PublicCard, responderMessage: ResponderHandshakeMessage): InitiatorSessionResult;
 /**
- * Establishes a session as the connection's responder: computes the same
- * ECDH-P384 secret, decapsulates the initiator's `kemCipherText` with our
- * own KEM secret key, and derives the same two directional keys the
- * initiator derived.
+ * Completes the handshake as the connection's responder, given the
+ * `ephemeral` secrets returned by `createResponderHandshakeCore` and the
+ * initiator's `InitiatorHandshakeMessage`. Verifies the initiator's dual
+ * signature (throws `HandshakeVerificationError` on failure), decapsulates
+ * the KEM ciphertext with the ephemeral KEM secret key, computes the
+ * ephemeral ECDH secret, and derives the same Session Keys and
+ * confirmation key the initiator derived.
  */
-export declare function establishSessionResponderCore(identity: Identity, counterpart: PublicCard, kemCipherText: string): SessionKeys;
+export declare function establishSessionResponderCore(identity: Identity, counterpart: PublicCard, ephemeral: ResponderHandshakeSecrets, initiatorMessage: InitiatorHandshakeMessage): ResponderSessionResult;
 export {};

package/dist/crypto/hybrid.js

@@ -3,8 +3,8 @@ import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha384 } from "@noble/hashes/sha2.js";
 import { bytesToHex, concatBytes, hexToBytes, randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
 import { canonicalize, hashDocument } from "../canonicalJson.js";
-import { classicalSharedSecret, classicalSign, classicalVerify } from "./classical.js";
-import { pqcDecapsulate, pqcEncapsulate, pqcSign, pqcVerify } from "./pqc.js";
+import { classicalSharedSecret, classicalSign, classicalVerify, generateClassicalKeypair } from "./classical.js";
+import { generatePqcKemKeypair, pqcDecapsulate, pqcEncapsulate, pqcSign, pqcVerify } from "./pqc.js";
 // No import of ../store.js or ../trust.js here (only their LogEntry TYPE,
 // which is erased at compile time) — this file must stay resolvable by a
 // browser bundler on its own. The node:fs-backed default wiring for
@@ -139,42 +139,175 @@ export async function decryptFromCore(identity, counterpart, box, deps) {
 //
 // encryptForCore/decryptFromCore above do a full ECDH + ML-KEM encapsulation
 // PER CALL — fine for a one-off document, prohibitively expensive if called
-// once per 16 KiB chunk of a large file transfer. The functions below run
-// that hybrid exchange ONCE per connection and hand back a pair of
-// directional keys the caller reuses (via a separate per-frame cipher, not
-// implemented here) for as many messages as the connection carries.
-const SESSION_INFO_INITIATOR_TO_RESPONDER = utf8ToBytes("raz-encrypt-session-v1|initiator-to-responder");
-const SESSION_INFO_RESPONDER_TO_INITIATOR = utf8ToBytes("raz-encrypt-session-v1|responder-to-initiator");
-function deriveSessionKeys(ecdhSecret, kemSecret) {
-    const ikm = concatBytes(ecdhSecret, kemSecret);
+// once per 16 KiB chunk of a large file transfer. The functions below run a
+// hybrid exchange ONCE per connection and hand back a pair of directional
+// keys the caller reuses (via a separate per-frame cipher, not implemented
+// here) for as many messages as the connection carries.
+//
+// This handshake is ephemeral and authenticated (see docs/adr/0006, which
+// supersedes ADR 0004's single-encapsulation design): each side generates a
+// fresh, single-use ECDH-P384 keypair per session attempt (the responder
+// also a fresh, single-use ML-KEM-1024 keypair), signs its own ephemeral
+// public key(s) plus a per-handshake nonce with its long-term classical and
+// PQ signing keys (the same dual-signature mechanism signCore/verifyCore use
+// for documents), and the counterpart verifies both signatures before
+// trusting the signed ephemeral key(s). The combined secret folds together
+// the fresh ephemeral ECDH secret, the KEM-encapsulated secret, AND the
+// existing long-term (static) ECDH secret (defense-in-depth; forward
+// secrecy itself rests entirely on the ephemeral secrets being discarded).
+// None of the ephemeral secret keys are ever attached to Identity,
+// persisted, or logged — they live only in the return value of
+// createResponderHandshakeCore and the stack of establishSessionInitiatorCore,
+// for the lifetime of one handshake attempt.
+//
+// Wire shape: the responder generates its ephemeral keys first and sends
+// ResponderHandshakeMessage (this can ride alongside the responder's
+// PublicCard, since nothing in it depends on anything from the initiator);
+// the initiator replies with InitiatorHandshakeMessage, which is the only
+// message carrying the KEM ciphertext (the initiator is the one who
+// encapsulates, same initiator/responder asymmetry ADR 0004 already
+// established); the responder completes the handshake from that reply.
+const SESSION_INFO_INITIATOR_TO_RESPONDER = utf8ToBytes("raz-encrypt-session-v2|initiator-to-responder");
+const SESSION_INFO_RESPONDER_TO_INITIATOR = utf8ToBytes("raz-encrypt-session-v2|responder-to-initiator");
+const SESSION_INFO_KEY_CONFIRMATION = utf8ToBytes("raz-encrypt-session-v2|key-confirmation");
+// A fourth, additional HKDF output (issue #29/raz-encrypt #29) from the exact
+// same combined input key material and transcript salt as the three outputs
+// above — NOT a repurposing of any of them. This is the seed for a two-party
+// ratchet (see ./ratchet.ts) built on top of the handshake, never itself used
+// to encrypt a frame directly.
+const SESSION_INFO_ROOT_KEY = utf8ToBytes("raz-encrypt-session-v2|root-key");
+export class HandshakeVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HandshakeVerificationError";
+    }
+}
+/** Reconstructs the counterpart-facing PublicCard shape from an Identity, without importing identity.js (which pulls in node:fs) — keeps this module browser-safe. */
+function publicCardOf(identity) {
     return {
-        initiatorToResponder: hkdf(sha384, ikm, undefined, SESSION_INFO_INITIATOR_TO_RESPONDER, 32),
-        responderToInitiator: hkdf(sha384, ikm, undefined, SESSION_INFO_RESPONDER_TO_INITIATOR, 32),
+        alias: identity.alias,
+        classicalPublicKey: bytesToHex(identity.classical.publicKey),
+        pqcSignPublicKey: bytesToHex(identity.pqcSign.publicKey),
+        pqcKemPublicKey: bytesToHex(identity.pqcKem.publicKey),
+    };
+}
+/** The exact bytes a handshake signature is computed over — mirrors `signedMessage`'s canonicalize-then-sign-directly shape, applied to ephemeral handshake material instead of a document. */
+function handshakeSignedMessage(payload) {
+    return utf8ToBytes(canonicalize(payload));
+}
+function signHandshakePayload(identity, payload) {
+    const message = handshakeSignedMessage(payload);
+    return {
+        classicalSignature: bytesToHex(classicalSign(message, identity.classical.secretKey)),
+        pqcSignature: bytesToHex(pqcSign(message, identity.pqcSign.secretKey)),
+    };
+}
+/** Throws HandshakeVerificationError unless BOTH the classical and PQ signatures check out — mirrors verifyCore's all-or-nothing dual-signature requirement. */
+function verifyHandshakeSignature(signer, payload, signature) {
+    const message = handshakeSignedMessage(payload);
+    const classicalOk = classicalVerify(hexToBytes(signature.classicalSignature), message, hexToBytes(signer.classicalPublicKey));
+    if (!classicalOk)
+        throw new HandshakeVerificationError(`Handshake rejected: classical signature from "${signer.alias}" did not verify.`);
+    const pqcOk = pqcVerify(hexToBytes(signature.pqcSignature), message, hexToBytes(signer.pqcSignPublicKey));
+    if (!pqcOk)
+        throw new HandshakeVerificationError(`Handshake rejected: PQC signature from "${signer.alias}" did not verify.`);
+}
+function handshakeTranscriptSalt(initiatorCard, responderCard, responderMessage, initiatorEphemeral) {
+    return sha384(utf8ToBytes(canonicalize({ initiatorCard, responderCard, responderMessage, initiatorEphemeral })));
+}
+function deriveSessionSecrets(ephemeralEcdhSecret, kemSecret, staticEcdhSecret, transcriptSalt) {
+    const ikm = concatBytes(ephemeralEcdhSecret, kemSecret, staticEcdhSecret);
+    return {
+        keys: {
+            initiatorToResponder: hkdf(sha384, ikm, transcriptSalt, SESSION_INFO_INITIATOR_TO_RESPONDER, 32),
+            responderToInitiator: hkdf(sha384, ikm, transcriptSalt, SESSION_INFO_RESPONDER_TO_INITIATOR, 32),
+        },
+        confirmationKey: hkdf(sha384, ikm, transcriptSalt, SESSION_INFO_KEY_CONFIRMATION, 32),
+        rootKey: hkdf(sha384, ikm, transcriptSalt, SESSION_INFO_ROOT_KEY, 32),
     };
 }
 /**
- * Establishes a session as the connection's initiator (the side that
- * created the WebRTC offer, in raz-encrypt-agnostic terms: whichever side
- * owns the single ML-KEM encapsulation this handshake performs). Computes
- * the ECDH-P384 secret with `counterpart` and one ML-KEM-1024 encapsulation
- * toward their KEM public key, then HKDF-splits the combined secret into two
- * directional AES-256-GCM keys. No trust dependency: establishing a session
- * never checks anyone's trust status, same as signCore.
+ * First step of the handshake, run by the connection's responder: generates
+ * one fresh, single-use ECDH-P384 keypair and one fresh, single-use
+ * ML-KEM-1024 keypair, a per-handshake nonce, and dual-signs all three with
+ * the responder's long-term classical+PQ signing keys. `message` is sent to
+ * the initiator (it can ride alongside the responder's PublicCard); `ephemeral`
+ * must be held in memory only and passed straight into
+ * `establishSessionResponderCore` once the initiator's reply arrives, then
+ * discarded.
  */
-export function establishSessionInitiatorCore(identity, counterpart) {
-    const ecdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
-    const { cipherText, sharedSecret: kemSecret } = pqcEncapsulate(hexToBytes(counterpart.pqcKemPublicKey));
-    return { kemCipherText: bytesToHex(cipherText), keys: deriveSessionKeys(ecdhSecret, kemSecret) };
+export function createResponderHandshakeCore(identity) {
+    const ephemeralClassical = generateClassicalKeypair();
+    const ephemeralKem = generatePqcKemKeypair();
+    const nonce = bytesToHex(randomBytes(32));
+    const payload = {
+        ephemeralClassicalPublicKey: bytesToHex(ephemeralClassical.publicKey),
+        ephemeralKemPublicKey: bytesToHex(ephemeralKem.publicKey),
+        nonce,
+    };
+    const signature = signHandshakePayload(identity, payload);
+    const message = { ...payload, signature };
+    return {
+        message,
+        ephemeral: {
+            ephemeralClassicalSecretKey: ephemeralClassical.secretKey,
+            ephemeralKemSecretKey: ephemeralKem.secretKey,
+            message,
+        },
+    };
 }
 /**
- * Establishes a session as the connection's responder: computes the same
- * ECDH-P384 secret, decapsulates the initiator's `kemCipherText` with our
- * own KEM secret key, and derives the same two directional keys the
- * initiator derived.
+ * Establishes a session as the connection's initiator, given the
+ * responder's `ResponderHandshakeMessage`. Verifies the responder's dual
+ * signature (throws `HandshakeVerificationError` on failure), generates its
+ * own fresh, single-use ECDH-P384 keypair and nonce, dual-signs them,
+ * encapsulates toward the responder's ephemeral KEM public key, and derives
+ * the Session Keys plus a key-confirmation key from the combined ephemeral
+ * ECDH + KEM + long-term ECDH secret, salted by a hash of the full
+ * handshake transcript. The returned `message` is sent to the responder to
+ * complete the handshake. No trust dependency: establishing a session never
+ * checks anyone's trust status, same as signCore.
  */
-export function establishSessionResponderCore(identity, counterpart, kemCipherText) {
-    const ecdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
-    const kemSecret = pqcDecapsulate(hexToBytes(kemCipherText), identity.pqcKem.secretKey);
-    return deriveSessionKeys(ecdhSecret, kemSecret);
+export function establishSessionInitiatorCore(identity, counterpart, responderMessage) {
+    verifyHandshakeSignature(counterpart, {
+        ephemeralClassicalPublicKey: responderMessage.ephemeralClassicalPublicKey,
+        ephemeralKemPublicKey: responderMessage.ephemeralKemPublicKey,
+        nonce: responderMessage.nonce,
+    }, responderMessage.signature);
+    const ephemeralClassical = generateClassicalKeypair();
+    const nonce = bytesToHex(randomBytes(32));
+    const payload = { ephemeralClassicalPublicKey: bytesToHex(ephemeralClassical.publicKey), nonce };
+    const signature = signHandshakePayload(identity, payload);
+    const ephemeralEcdhSecret = classicalSharedSecret(ephemeralClassical.secretKey, hexToBytes(responderMessage.ephemeralClassicalPublicKey));
+    const { cipherText, sharedSecret: kemSecret } = pqcEncapsulate(hexToBytes(responderMessage.ephemeralKemPublicKey));
+    const staticEcdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
+    const transcriptSalt = handshakeTranscriptSalt(publicCardOf(identity), counterpart, responderMessage, payload);
+    const { keys, confirmationKey, rootKey } = deriveSessionSecrets(ephemeralEcdhSecret, kemSecret, staticEcdhSecret, transcriptSalt);
+    return {
+        message: { ...payload, signature, kemCipherText: bytesToHex(cipherText) },
+        keys,
+        confirmationKey,
+        rootKey,
+    };
+}
+/**
+ * Completes the handshake as the connection's responder, given the
+ * `ephemeral` secrets returned by `createResponderHandshakeCore` and the
+ * initiator's `InitiatorHandshakeMessage`. Verifies the initiator's dual
+ * signature (throws `HandshakeVerificationError` on failure), decapsulates
+ * the KEM ciphertext with the ephemeral KEM secret key, computes the
+ * ephemeral ECDH secret, and derives the same Session Keys and
+ * confirmation key the initiator derived.
+ */
+export function establishSessionResponderCore(identity, counterpart, ephemeral, initiatorMessage) {
+    verifyHandshakeSignature(counterpart, { ephemeralClassicalPublicKey: initiatorMessage.ephemeralClassicalPublicKey, nonce: initiatorMessage.nonce }, initiatorMessage.signature);
+    const ephemeralEcdhSecret = classicalSharedSecret(ephemeral.ephemeralClassicalSecretKey, hexToBytes(initiatorMessage.ephemeralClassicalPublicKey));
+    const kemSecret = pqcDecapsulate(hexToBytes(initiatorMessage.kemCipherText), ephemeral.ephemeralKemSecretKey);
+    const staticEcdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
+    const transcriptSalt = handshakeTranscriptSalt(counterpart, publicCardOf(identity), ephemeral.message, {
+        ephemeralClassicalPublicKey: initiatorMessage.ephemeralClassicalPublicKey,
+        nonce: initiatorMessage.nonce,
+    });
+    return deriveSessionSecrets(ephemeralEcdhSecret, kemSecret, staticEcdhSecret, transcriptSalt);
 }
 //# sourceMappingURL=hybrid.js.map

package/dist/crypto/hybrid.js.map

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

package/dist/crypto/ratchet.d.ts

@@ -0,0 +1,68 @@
+import { type ClassicalKeypair } from "./classical.js";
+/** Domain-separation label for `seedChainKey`'s `direction` parameter — mirrors hybrid.ts's SESSION_INFO_* labels, applied to chain keys instead of Session Keys. */
+export declare const CHAIN_INFO_INITIATOR_TO_RESPONDER: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+/** See CHAIN_INFO_INITIATOR_TO_RESPONDER. */
+export declare const CHAIN_INFO_RESPONDER_TO_INITIATOR: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+/**
+ * How many control-type messages (chat/file-lifecycle; file-chunk/binary
+ * traffic is never counted), summed across BOTH directions combined, trigger
+ * one ML-KEM-1024 asymmetric step (see `performKemStep`). Named and exported
+ * so the recovery-speed-vs-overhead trade-off is visible and adjustable in
+ * one place, rather than a magic number buried in `secureConnection.ts`'s
+ * (ticket #30's) triggering logic — which is also where the actual counting
+ * happens; this constant is consumed there, not here.
+ */
+export declare const ML_KEM_STEP_CADENCE = 20;
+/**
+ * Seeds a per-direction chain key from the handshake's `rootKey` output (see
+ * hybrid.ts's InitiatorSessionResult/ResponderSessionResult). Pass one of
+ * CHAIN_INFO_INITIATOR_TO_RESPONDER / CHAIN_INFO_RESPONDER_TO_INITIATOR as
+ * `direction` — the two directions always seed distinct chain keys from the
+ * same root key, mirroring how a Session's two directional keys are split
+ * from one combined secret.
+ */
+export declare function seedChainKey(rootKey: Uint8Array, direction: Uint8Array): Uint8Array;
+/** The result of advancing a chain key by one message: the single-use key for THIS message, and the chain key's new value for the next one. */
+export interface ChainStep {
+    /** Single-use — encrypt/decrypt exactly one frame with this, then discard it. Never reused. */
+    messageKey: Uint8Array;
+    /** Replaces the chain key passed into `ratchetChainKey`. The old chain key must not be kept. */
+    nextChainKey: Uint8Array;
+}
+/**
+ * Derives a single-use message key from `chainKey` AND advances the chain to
+ * its next value, in the same operation — so by the time this call returns,
+ * the OLD chain key is gone (the caller must not retain it) and a fresh
+ * `nextChainKey` stands in its place. Both outputs are one-way functions of
+ * `chainKey` (HKDF-SHA384 with distinct, fixed info labels): holding
+ * `nextChainKey` alone never lets you recover `chainKey` or `messageKey`
+ * (forward secrecy at the symmetric-chain level — see
+ * test/ratchet.test.ts's forward-secrecy suite).
+ */
+export declare function ratchetChainKey(chainKey: Uint8Array): ChainStep;
+/** The result of an asymmetric step (ECDH or ML-KEM): a new root key, and a freshly re-seeded SENDING chain key for the side that performed the step. The other direction's chain is untouched until it performs its own step (Double-Ratchet-style asymmetry). */
+export interface AsymmetricStepResult {
+    rootKey: Uint8Array;
+    sendingChainKey: Uint8Array;
+}
+/**
+ * The ECDH-P384 asymmetric step: mixes a fresh ephemeral ECDH shared secret
+ * into the current root key (producing a new root key) and re-seeds the
+ * stepping side's own sending chain key from it. `ephemeral` is a freshly
+ * generated keypair (reuse `generateClassicalKeypair` from ./classical.js —
+ * this function does not generate keys itself); `counterpartEphemeralPublicKey`
+ * is the counterpart's most recently received ephemeral public key.
+ *
+ * Deciding WHEN to call this ("a reply after receiving") is out of scope —
+ * that is ticket #30's `secureConnection.ts` connection-level state.
+ */
+export declare function performEcdhStep(rootKey: Uint8Array, ephemeral: ClassicalKeypair, counterpartEphemeralPublicKey: Uint8Array, sendingDirection: Uint8Array): AsymmetricStepResult;
+/**
+ * The ML-KEM-1024 asymmetric step: mixes an ML-KEM-encapsulated (sender) or
+ * decapsulated (receiver) shared secret — `kemSecret`, from
+ * `pqcEncapsulate`/`pqcDecapsulate` in ./pqc.js, which this function does not
+ * call itself — into the current root key, and re-seeds the stepping side's
+ * sending chain key from the result. Cadence (how often this fires) is
+ * `ML_KEM_STEP_CADENCE`, counted and triggered by ticket #30, not here.
+ */
+export declare function performKemStep(rootKey: Uint8Array, kemSecret: Uint8Array, sendingDirection: Uint8Array): AsymmetricStepResult;

package/dist/crypto/ratchet.js

@@ -0,0 +1,89 @@
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha384 } from "@noble/hashes/sha2.js";
+import { concatBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { classicalSharedSecret } from "./classical.js";
+// The two-party ratchet (issue #17/#29): built ON TOP OF the handshake in
+// ./hybrid.ts, seeded from its additional `rootKey` output. See docs/adr for
+// the full design and its deliberate, explicit contrast with Signal's Double
+// Ratchet (no skipped-message-key cache, no out-of-order handling, no
+// group/multi-device fan-out — this stays two-party-only and in-order-only,
+// matching this project's always-ordered, always-1:1 transport).
+//
+// Everything here is a PURE function: no "when do I step" logic, no
+// connection-level state, no wire format. The caller (`secureConnection.ts`'s
+// Envelope layer, a later, currently-blocked ticket) drives all of that.
+const CHAIN_INFO_PREFIX = utf8ToBytes("raz-encrypt-ratchet-v1|chain|");
+const MESSAGE_KEY_INFO = utf8ToBytes("raz-encrypt-ratchet-v1|message-key");
+const CHAIN_ADVANCE_INFO = utf8ToBytes("raz-encrypt-ratchet-v1|chain-advance");
+const ROOT_KEY_ECDH_STEP_INFO = utf8ToBytes("raz-encrypt-ratchet-v1|root-key|ecdh-step");
+const ROOT_KEY_KEM_STEP_INFO = utf8ToBytes("raz-encrypt-ratchet-v1|root-key|kem-step");
+/** Domain-separation label for `seedChainKey`'s `direction` parameter — mirrors hybrid.ts's SESSION_INFO_* labels, applied to chain keys instead of Session Keys. */
+export const CHAIN_INFO_INITIATOR_TO_RESPONDER = concatBytes(CHAIN_INFO_PREFIX, utf8ToBytes("initiator-to-responder"));
+/** See CHAIN_INFO_INITIATOR_TO_RESPONDER. */
+export const CHAIN_INFO_RESPONDER_TO_INITIATOR = concatBytes(CHAIN_INFO_PREFIX, utf8ToBytes("responder-to-initiator"));
+/**
+ * How many control-type messages (chat/file-lifecycle; file-chunk/binary
+ * traffic is never counted), summed across BOTH directions combined, trigger
+ * one ML-KEM-1024 asymmetric step (see `performKemStep`). Named and exported
+ * so the recovery-speed-vs-overhead trade-off is visible and adjustable in
+ * one place, rather than a magic number buried in `secureConnection.ts`'s
+ * (ticket #30's) triggering logic — which is also where the actual counting
+ * happens; this constant is consumed there, not here.
+ */
+export const ML_KEM_STEP_CADENCE = 20;
+/**
+ * Seeds a per-direction chain key from the handshake's `rootKey` output (see
+ * hybrid.ts's InitiatorSessionResult/ResponderSessionResult). Pass one of
+ * CHAIN_INFO_INITIATOR_TO_RESPONDER / CHAIN_INFO_RESPONDER_TO_INITIATOR as
+ * `direction` — the two directions always seed distinct chain keys from the
+ * same root key, mirroring how a Session's two directional keys are split
+ * from one combined secret.
+ */
+export function seedChainKey(rootKey, direction) {
+    return hkdf(sha384, rootKey, undefined, direction, 32);
+}
+/**
+ * Derives a single-use message key from `chainKey` AND advances the chain to
+ * its next value, in the same operation — so by the time this call returns,
+ * the OLD chain key is gone (the caller must not retain it) and a fresh
+ * `nextChainKey` stands in its place. Both outputs are one-way functions of
+ * `chainKey` (HKDF-SHA384 with distinct, fixed info labels): holding
+ * `nextChainKey` alone never lets you recover `chainKey` or `messageKey`
+ * (forward secrecy at the symmetric-chain level — see
+ * test/ratchet.test.ts's forward-secrecy suite).
+ */
+export function ratchetChainKey(chainKey) {
+    return {
+        messageKey: hkdf(sha384, chainKey, undefined, MESSAGE_KEY_INFO, 32),
+        nextChainKey: hkdf(sha384, chainKey, undefined, CHAIN_ADVANCE_INFO, 32),
+    };
+}
+/**
+ * The ECDH-P384 asymmetric step: mixes a fresh ephemeral ECDH shared secret
+ * into the current root key (producing a new root key) and re-seeds the
+ * stepping side's own sending chain key from it. `ephemeral` is a freshly
+ * generated keypair (reuse `generateClassicalKeypair` from ./classical.js —
+ * this function does not generate keys itself); `counterpartEphemeralPublicKey`
+ * is the counterpart's most recently received ephemeral public key.
+ *
+ * Deciding WHEN to call this ("a reply after receiving") is out of scope —
+ * that is ticket #30's `secureConnection.ts` connection-level state.
+ */
+export function performEcdhStep(rootKey, ephemeral, counterpartEphemeralPublicKey, sendingDirection) {
+    const sharedSecret = classicalSharedSecret(ephemeral.secretKey, counterpartEphemeralPublicKey);
+    const newRootKey = hkdf(sha384, concatBytes(rootKey, sharedSecret), undefined, ROOT_KEY_ECDH_STEP_INFO, 32);
+    return { rootKey: newRootKey, sendingChainKey: seedChainKey(newRootKey, sendingDirection) };
+}
+/**
+ * The ML-KEM-1024 asymmetric step: mixes an ML-KEM-encapsulated (sender) or
+ * decapsulated (receiver) shared secret — `kemSecret`, from
+ * `pqcEncapsulate`/`pqcDecapsulate` in ./pqc.js, which this function does not
+ * call itself — into the current root key, and re-seeds the stepping side's
+ * sending chain key from the result. Cadence (how often this fires) is
+ * `ML_KEM_STEP_CADENCE`, counted and triggered by ticket #30, not here.
+ */
+export function performKemStep(rootKey, kemSecret, sendingDirection) {
+    const newRootKey = hkdf(sha384, concatBytes(rootKey, kemSecret), undefined, ROOT_KEY_KEM_STEP_INFO, 32);
+    return { rootKey: newRootKey, sendingChainKey: seedChainKey(newRootKey, sendingDirection) };
+}
+//# sourceMappingURL=ratchet.js.map

package/dist/crypto/ratchet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratchet.js","sourceRoot":"","sources":["../../src/crypto/ratchet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAyB,MAAM,gBAAgB,CAAC;AAE9E,0EAA0E;AAC1E,6EAA6E;AAC7E,6EAA6E;AAC7E,sEAAsE;AACtE,4EAA4E;AAC5E,iEAAiE;AACjE,EAAE;AACF,oEAAoE;AACpE,8EAA8E;AAC9E,yEAAyE;AAEzE,MAAM,iBAAiB,GAAG,WAAW,CAAC,+BAA+B,CAAC,CAAC;AACvE,MAAM,gBAAgB,GAAG,WAAW,CAAC,oCAAoC,CAAC,CAAC;AAC3E,MAAM,kBAAkB,GAAG,WAAW,CAAC,sCAAsC,CAAC,CAAC;AAC/E,MAAM,uBAAuB,GAAG,WAAW,CAAC,2CAA2C,CAAC,CAAC;AACzF,MAAM,sBAAsB,GAAG,WAAW,CAAC,0CAA0C,CAAC,CAAC;AAEvF,qKAAqK;AACrK,MAAM,CAAC,MAAM,iCAAiC,GAAG,WAAW,CAAC,iBAAiB,EAAE,WAAW,CAAC,wBAAwB,CAAC,CAAC,CAAC;AACvH,6CAA6C;AAC7C,MAAM,CAAC,MAAM,iCAAiC,GAAG,WAAW,CAAC,iBAAiB,EAAE,WAAW,CAAC,wBAAwB,CAAC,CAAC,CAAC;AAEvH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAmB,EAAE,SAAqB;IACrE,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;AACzD,CAAC;AAUD;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,QAAoB;IAClD,OAAO;QACL,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,EAAE,CAAC;QACnE,YAAY,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,kBAAkB,EAAE,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC;AAQD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAmB,EACnB,SAA2B,EAC3B,6BAAyC,EACzC,gBAA4B;IAE5B,MAAM,YAAY,GAAG,qBAAqB,CAAC,SAAS,CAAC,SAAS,EAAE,6BAA6B,CAAC,CAAC;IAC/F,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,SAAS,EAAE,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC5G,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAAE,CAAC;AAC9F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,OAAmB,EAAE,SAAqB,EAAE,gBAA4B;IACrG,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,sBAAsB,EAAE,EAAE,CAAC,CAAC;IACxG,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAAE,CAAC;AAC9F,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raz-encrypt",
-  "version": "0.3.0",
+  "version": "1.1.0",
   "description": "Local-first, hybrid classical+post-quantum signing and verification for two consenting parties. No server, no database required.",
   "license": "MIT",
   "type": "module",