raz-encrypt 0.3.0 → 2.1.0

package/dist/crypto/hybrid.js

@@ -1,16 +1,25 @@
 import { gcm } from "@noble/ciphers/aes.js";
+import { equalBytes } from "@noble/ciphers/utils.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
+import { hmac } from "@noble/hashes/hmac.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 { fingerprint } from "../fingerprint.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
 // sign/verify/encryptFor/decryptFrom lives in ./nodeHybrid.ts instead,
 // which is what "." (not "./core") re-exports.
-const HYBRID_INFO = utf8ToBytes("raz-encrypt-hybrid-v1");
+// Box v2 (ADR 0018): the key is derived under this label with a salt that binds
+// both parties and every public value in the box; the sender dual-signs the
+// box under this domain tag (also passed as the ML-DSA context).
+const BOX_VERSION = 2;
+const BOX_KEY_INFO = utf8ToBytes("raz-encrypt-box-v2|key");
+const BOX_DOMAIN_TAG = "raz-encrypt-box-v2|sign";
+const BOX_CONTEXT = utf8ToBytes(BOX_DOMAIN_TAG);
 const ALGORITHMS = { classical: "ECDSA-P384", pqc: "ML-DSA-87" };
 export class UntrustedPartyError extends Error {
     constructor(alias) {
@@ -18,6 +27,89 @@ export class UntrustedPartyError extends Error {
         this.name = "UntrustedPartyError";
     }
 }
+/** Thrown by decryptFromCore for a structurally-malformed EncryptedBox or a failed AEAD decryption — both mean "this box is unusable", so one error class covers both causes. */
+export class DecryptionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DecryptionError";
+    }
+}
+/** True for a non-empty, even-length string of hex digits only — what every hex-encoded field in this module expects. */
+function isHex(value) {
+    return typeof value === "string" && value.length > 0 && value.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(value);
+}
+/**
+ * True only for the exact canonical format `new Date().toISOString()` itself
+ * produces — the one format this codebase ever actually writes. A round-trip
+ * check (not a regex, not bare `Date.parse`) catches wrong formats, non-ISO
+ * strings `Date.parse` would otherwise accept (implementation-defined beyond
+ * strict ISO-8601), AND calendar-overflow values some engines silently roll
+ * forward (e.g. a Feb 30th) — all in one comparison: any mismatch, whatever
+ * the cause, fails the round-trip (ADR 0010). Exported so other modules that
+ * define their own timestamp fields (e.g. trust.ts's rotation/revocation
+ * documents) can hold them to the same strict standard instead of each
+ * re-deriving their own looser check.
+ */
+export function isValidIsoInstant(value) {
+    const date = new Date(value);
+    return !Number.isNaN(date.getTime()) && date.toISOString() === value;
+}
+/**
+ * Structural shape check only — right fields, right primitive types, hex
+ * fields actually parse as hex, and (issue #4) a present `expiresAt` must be
+ * a valid ISO instant, not just a string. Runs before any
+ * hexToBytes/checkTrust call so a malformed certificate can't crash
+ * verifyCore instead of just failing it.
+ */
+function isValidCertificateShape(certificate) {
+    if (typeof certificate !== "object" || certificate === null)
+        return false;
+    const c = certificate;
+    if (typeof c.documentHash !== "string")
+        return false;
+    if (!isHex(c.classicalSignature))
+        return false;
+    if (!isHex(c.pqcSignature))
+        return false;
+    if (typeof c.algorithms !== "object" || c.algorithms === null)
+        return false;
+    if (typeof c.signedAt !== "string")
+        return false;
+    if (c.version !== undefined && c.version !== 2)
+        return false;
+    if (c.version === 2 && !isValidIsoInstant(c.signedAt))
+        return false;
+    if (c.expiresAt !== undefined && (typeof c.expiresAt !== "string" || !isValidIsoInstant(c.expiresAt)))
+        return false;
+    if (typeof c.signer !== "object" || c.signer === null)
+        return false;
+    const signer = c.signer;
+    if (typeof signer.alias !== "string")
+        return false;
+    if (!isHex(signer.classicalPublicKey))
+        return false;
+    if (!isHex(signer.pqcSignPublicKey))
+        return false;
+    return true;
+}
+/** Same structural-shape treatment as isValidCertificateShape, for the box encryptFor/decryptFrom exchange instead of a Certificate. Version is checked separately so a v1 box gets a clear error. */
+function isValidEncryptedBoxShape(box) {
+    if (typeof box !== "object" || box === null)
+        return false;
+    const b = box;
+    const sig = b.signature;
+    return (isHex(b.id) &&
+        b.id.length === 32 &&
+        typeof b.signedAt === "string" &&
+        isValidIsoInstant(b.signedAt) &&
+        isHex(b.kemCipherText) &&
+        isHex(b.nonce) &&
+        isHex(b.ciphertext) &&
+        typeof sig === "object" &&
+        sig !== null &&
+        isHex(sig.classicalSignature) &&
+        isHex(sig.pqcSignature));
+}
 /**
  * The exact bytes both signatures are computed over. Binds `expiresAt` into
  * the signed payload (not just `documentHash`) so a certificate's expiry
@@ -29,6 +121,17 @@ export class UntrustedPartyError extends Error {
 function signedMessage(documentHash, expiresAt) {
     return utf8ToBytes(canonicalize({ documentHash, expiresAt: expiresAt ?? null }));
 }
+const CERTIFICATE_V2_DOMAIN = "raz-encrypt/certificate/v2";
+/** v2 signed payload: also binds the signer's alias and signedAt, under a domain-separation tag (ADR 0017). */
+function signedMessageV2(documentHash, expiresAt, alias, signedAt) {
+    return utf8ToBytes(canonicalize({ domain: CERTIFICATE_V2_DOMAIN, documentHash, expiresAt: expiresAt ?? null, alias, signedAt }));
+}
+/** The exact bytes `certificate`'s signatures are over, by its format version. */
+function certificateMessage(certificate) {
+    return certificate.version === 2
+        ? signedMessageV2(certificate.documentHash, certificate.expiresAt, certificate.signer.alias, certificate.signedAt)
+        : signedMessage(certificate.documentHash, certificate.expiresAt);
+}
 async function requireTrusted(checkTrust, counterpart) {
     const status = await checkTrust(counterpart);
     if (status !== "trusted")
@@ -45,9 +148,14 @@ async function log(onLog, entry) {
  * signing never checks anyone else's trust status, only your own keys.
  */
 export async function signCore(identity, document, options = {}, deps = {}) {
+    if (options.expiresAt !== undefined && !isValidIsoInstant(options.expiresAt)) {
+        throw new Error(`options.expiresAt must be a valid ISO-8601 instant in the exact format new Date().toISOString() produces (e.g. "2024-01-01T00:00:00.000Z"); got ${JSON.stringify(options.expiresAt)}.`);
+    }
     const documentHash = hashDocument(document);
-    const message = signedMessage(documentHash, options.expiresAt);
+    const signedAt = new Date().toISOString();
+    const message = signedMessageV2(documentHash, options.expiresAt, identity.alias, signedAt);
     const certificate = {
+        version: 2,
         documentHash,
         classicalSignature: bytesToHex(classicalSign(message, identity.classical.secretKey)),
         pqcSignature: bytesToHex(pqcSign(message, identity.pqcSign.secretKey)),
@@ -57,7 +165,7 @@ export async function signCore(identity, document, options = {}, deps = {}) {
             classicalPublicKey: bytesToHex(identity.classical.publicKey),
             pqcSignPublicKey: bytesToHex(identity.pqcSign.publicKey),
         },
-        signedAt: new Date().toISOString(),
+        signedAt,
         ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
     };
     await log(deps.onLog, { action: "sign", documentHash });
@@ -70,8 +178,18 @@ export async function signCore(identity, document, options = {}, deps = {}) {
  * fails the whole verification.
  */
 export async function verifyCore(identity, document, certificate, deps) {
-    const record = (result) => {
-        void log(deps.onLog, {
+    if (!isValidCertificateShape(certificate)) {
+        const result = { valid: false, reason: "malformed-certificate" };
+        // No real signer to name — certificate.signer may not even exist. The
+        // audit log still gets an entry so a verify attempt that happened isn't
+        // silently uncounted just because the input was garbage. Awaited, same
+        // as every log() call below — a failed write propagates to the caller
+        // instead of becoming an unhandled rejection (issue #5).
+        await log(deps.onLog, { action: "verify", result: result.reason });
+        return result;
+    }
+    const record = async (result) => {
+        await log(deps.onLog, {
             action: "verify",
             documentHash: certificate.documentHash,
             counterpartAlias: certificate.signer.alias,
@@ -92,7 +210,7 @@ export async function verifyCore(identity, document, certificate, deps) {
     if (certificate.expiresAt && Date.now() >= Date.parse(certificate.expiresAt)) {
         return record({ valid: false, reason: "expired" });
     }
-    const message = signedMessage(certificate.documentHash, certificate.expiresAt);
+    const message = certificateMessage(certificate);
     const classicalOk = classicalVerify(hexToBytes(certificate.classicalSignature), message, hexToBytes(certificate.signer.classicalPublicKey));
     if (!classicalOk)
         return record({ valid: false, reason: "classical-signature-mismatch" });
@@ -101,80 +219,420 @@ export async function verifyCore(identity, document, certificate, deps) {
         return record({ valid: false, reason: "pqc-signature-mismatch" });
     return record({ valid: true });
 }
-function deriveHybridKey(ecdhSecret, kemSecret) {
-    return hkdf(sha384, concatBytes(ecdhSecret, kemSecret), undefined, HYBRID_INFO, 32);
+/** Thrown by decryptFromCore when the caller's `isReplay` hook reports the (otherwise valid) box was already seen. */
+export class ReplayedBoxError extends Error {
+    constructor(id) {
+        super(`Box ${id} has already been seen and was rejected as a replay.`);
+        this.name = "ReplayedBoxError";
+    }
+}
+/** Everything both sides know about a box before decryption: the parties and every public value in it. */
+function boxContext(sender, recipient, box) {
+    return {
+        version: BOX_VERSION,
+        sender: { fingerprint: fingerprint(sender), classicalPublicKey: sender.classicalPublicKey },
+        recipient: {
+            fingerprint: fingerprint(recipient),
+            classicalPublicKey: recipient.classicalPublicKey,
+            pqcKemPublicKey: recipient.pqcKemPublicKey,
+        },
+        id: box.id,
+        signedAt: box.signedAt,
+        kemCipherText: box.kemCipherText,
+        nonce: box.nonce,
+    };
+}
+function deriveBoxKey(ecdhSecret, kemSecret, context) {
+    const salt = sha384(utf8ToBytes(canonicalize(context)));
+    return hkdf(sha384, concatBytes(ecdhSecret, kemSecret), salt, BOX_KEY_INFO, 32);
+}
+function boxAad(context) {
+    return utf8ToBytes(canonicalize(context));
+}
+function boxSignedMessage(context, ciphertext) {
+    return utf8ToBytes(canonicalize({ tag: BOX_DOMAIN_TAG, context, ciphertextHash: bytesToHex(sha384(hexToBytes(ciphertext))) }));
 }
 /**
- * Encrypts `data` for `counterpart` using a symmetric key derived from BOTH
- * an ECDH-P384 exchange and an ML-KEM-1024 encapsulation (HKDF-SHA384
- * combines the two secrets), then AES-256-GCM. Throws UntrustedPartyError
- * unless `deps.checkTrust(counterpart)` reports "trusted".
+ * Encrypts `data` for `counterpart` (box v2, ADR 0018). The key comes from
+ * ECDH-P384 and an ML-KEM-1024 encapsulation, combined by HKDF-SHA384 with a
+ * salt that binds both parties and every public value in the box. AES-256-GCM
+ * authenticates the same context as AAD, and the sender dual-signs the box so
+ * it cannot be forged by the recipient or anyone else. Throws
+ * UntrustedPartyError unless `deps.checkTrust(counterpart)` reports "trusted".
+ *
+ * There is still NO forward secrecy: the ECDH half uses long-term keys. Use a
+ * session handshake for anything that needs it.
  */
 export async function encryptForCore(identity, counterpart, data, deps) {
     await requireTrusted(deps.checkTrust, counterpart);
+    const sender = publicCardOf(identity);
     const ecdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
-    const { cipherText: kemCipherText, sharedSecret: kemSecret } = pqcEncapsulate(hexToBytes(counterpart.pqcKemPublicKey));
-    const key = deriveHybridKey(ecdhSecret, kemSecret);
+    const { cipherText, sharedSecret: kemSecret } = pqcEncapsulate(hexToBytes(counterpart.pqcKemPublicKey));
     const nonce = randomBytes(12);
-    const ciphertext = gcm(key, nonce).encrypt(utf8ToBytes(canonicalize(data)));
+    const head = {
+        id: bytesToHex(randomBytes(16)),
+        signedAt: new Date().toISOString(),
+        kemCipherText: bytesToHex(cipherText),
+        nonce: bytesToHex(nonce),
+    };
+    const context = boxContext(sender, counterpart, head);
+    const key = deriveBoxKey(ecdhSecret, kemSecret, context);
+    const ciphertext = bytesToHex(gcm(key, nonce, boxAad(context)).encrypt(utf8ToBytes(canonicalize(data))));
+    const message = boxSignedMessage(context, ciphertext);
+    const signature = {
+        classicalSignature: bytesToHex(classicalSign(message, identity.classical.secretKey)),
+        pqcSignature: bytesToHex(pqcSign(message, identity.pqcSign.secretKey, BOX_CONTEXT)),
+    };
     await log(deps.onLog, { action: "encrypt", counterpartAlias: counterpart.alias });
-    return { kemCipherText: bytesToHex(kemCipherText), nonce: bytesToHex(nonce), ciphertext: bytesToHex(ciphertext) };
+    return { version: BOX_VERSION, ...head, ciphertext, signature };
 }
 /**
  * Decrypts a box produced by `encryptFor`. `counterpart` is the sender's
  * public card. Throws UntrustedPartyError unless `deps.checkTrust(counterpart)`
- * reports "trusted" — this stops a caller from accidentally decrypting "as
- * if" a message came from someone they never actually trusted.
+ * reports "trusted". The sender's signature and the recipient binding are
+ * verified BEFORE any decapsulation or decryption; a v1 box, a box sealed for
+ * someone else, or a box not signed by `counterpart` is a DecryptionError. If
+ * `deps.isReplay` is given it is consulted only after the signature checks
+ * out, and a true result throws ReplayedBoxError.
  */
 export async function decryptFromCore(identity, counterpart, box, deps) {
     await requireTrusted(deps.checkTrust, counterpart);
-    const ecdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
-    const kemSecret = pqcDecapsulate(hexToBytes(box.kemCipherText), identity.pqcKem.secretKey);
-    const key = deriveHybridKey(ecdhSecret, kemSecret);
-    const plaintext = gcm(key, hexToBytes(box.nonce)).decrypt(hexToBytes(box.ciphertext));
+    if (typeof box !== "object" || box === null || box.version !== BOX_VERSION) {
+        throw new DecryptionError("Unsupported box version: only version 2 boxes are accepted (1.x boxes are rejected, see ADR 0018).");
+    }
+    if (!isValidEncryptedBoxShape(box)) {
+        throw new DecryptionError("Malformed EncryptedBox: id/signedAt/kemCipherText/nonce/ciphertext/signature are not all valid.");
+    }
+    const recipient = publicCardOf(identity);
+    const context = boxContext(counterpart, recipient, box);
+    // Verify before touching the KEM or the cipher.
+    const message = boxSignedMessage(context, box.ciphertext);
+    const classicalOk = classicalVerify(hexToBytes(box.signature.classicalSignature), message, hexToBytes(counterpart.classicalPublicKey));
+    const pqcOk = pqcVerify(hexToBytes(box.signature.pqcSignature), message, hexToBytes(counterpart.pqcSignPublicKey), BOX_CONTEXT);
+    if (!classicalOk || !pqcOk) {
+        throw new DecryptionError(`Box from "${counterpart.alias}" was rejected: its signature does not match this sender and recipient.`);
+    }
+    if (deps.isReplay && (await deps.isReplay({ id: box.id, signedAt: box.signedAt, senderFingerprint: fingerprint(counterpart) }))) {
+        throw new ReplayedBoxError(box.id);
+    }
+    let plaintext;
+    try {
+        const ecdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
+        const kemSecret = pqcDecapsulate(hexToBytes(box.kemCipherText), identity.pqcKem.secretKey);
+        const key = deriveBoxKey(ecdhSecret, kemSecret, context);
+        plaintext = gcm(key, hexToBytes(box.nonce), boxAad(context)).decrypt(hexToBytes(box.ciphertext));
+    }
+    catch (err) {
+        throw new DecryptionError(`Failed to decrypt box from "${counterpart.alias}": ${err instanceof Error ? err.message : String(err)}`);
+    }
     await log(deps.onLog, { action: "decrypt", counterpartAlias: counterpart.alias });
-    return JSON.parse(new TextDecoder().decode(plaintext));
+    try {
+        return JSON.parse(new TextDecoder().decode(plaintext));
+    }
+    catch (err) {
+        // Decryption succeeded (so the sender really did send these exact
+        // bytes), but they aren't valid JSON — a malicious or buggy sender, not
+        // a tampering attacker. Fail closed with the same error type as every
+        // other rejection here, instead of crashing the caller on a raw
+        // SyntaxError (found by fuzzing, issue #42).
+        throw new DecryptionError(`Box from "${counterpart.alias}" decrypted, but its plaintext is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 // --- Session handshake ------------------------------------------------
 //
 // 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-v3|initiator-to-responder");
+const SESSION_INFO_RESPONDER_TO_INITIATOR = utf8ToBytes("raz-encrypt-session-v3|responder-to-initiator");
+const SESSION_INFO_KEY_CONFIRMATION = utf8ToBytes("raz-encrypt-session-v3|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-v3|root-key");
+// Domain-separation tag for handshake signatures (ADR 0008, raz-encrypt
+// #2/issue #2): embedded as a `tag` field inside each handshake message's
+// signed payload AND passed as ML-DSA's native `context` option (FIPS 204
+// §5.4) — belt-and-suspenders, not redundant: the payload field survives
+// even if a caller signs with a different PQC primitive later, the `context`
+// option is enforced by the algorithm itself. One version counter shared
+// with the SESSION_INFO_* labels above, not a separately-tracked one.
+const HANDSHAKE_DOMAIN_TAG = "raz-encrypt-session-v3|handshake";
+const HANDSHAKE_CONTEXT = utf8ToBytes(HANDSHAKE_DOMAIN_TAG);
+export class HandshakeVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HandshakeVerificationError";
+    }
+}
+/** Thrown for a structurally-malformed handshake message (non-hex fields) — distinct from HandshakeVerificationError, which means the shape was fine but the signature didn't check out. */
+export class MalformedHandshakeMessageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MalformedHandshakeMessageError";
+    }
+}
+function isValidHandshakeSignatureShape(signature) {
+    if (typeof signature !== "object" || signature === null)
+        return false;
+    const s = signature;
+    return isHex(s.classicalSignature) && isHex(s.pqcSignature);
+}
+function isValidResponderHandshakeMessageShape(message) {
+    if (typeof message !== "object" || message === null)
+        return false;
+    const m = message;
+    return isHex(m.ephemeralClassicalPublicKey) && isHex(m.ephemeralKemPublicKey) && isHex(m.nonce) && isValidHandshakeSignatureShape(m.signature);
+}
+function isValidInitiatorHandshakeMessageShape(message) {
+    if (typeof message !== "object" || message === null)
+        return false;
+    const m = message;
+    return isHex(m.ephemeralClassicalPublicKey) && isHex(m.nonce) && isHex(m.kemCipherText) && isValidHandshakeSignatureShape(m.signature);
+}
+/** 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, HANDSHAKE_CONTEXT)),
+    };
+}
+/** 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), HANDSHAKE_CONTEXT);
+    if (!pqcOk)
+        throw new HandshakeVerificationError(`Handshake rejected: PQC signature from "${signer.alias}" did not verify.`);
+}
+const KEY_CONFIRMATION_DOMAIN = "raz-encrypt/key-confirmation/v1";
+function keyConfirmationBytes(role, transcript) {
+    if (role !== "initiator" && role !== "responder")
+        throw new TypeError(`Unknown handshake role: ${String(role)}`);
+    return utf8ToBytes(canonicalize({ domain: KEY_CONFIRMATION_DOMAIN, role, ...transcript }));
+}
 /**
- * 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.
+ * The tag to send the counterpart as proof you derived the same secrets:
+ * HMAC-SHA384, keyed by the handshake's `confirmationKey`, over the full
+ * transcript and YOUR role (hex, 96 characters). Folding the role in means
+ * your own tag can never be replayed back to you as the counterpart's.
+ * Send it only after the handshake call returned, and treat the connection
+ * as unauthenticated until `verifyKeyConfirmation` succeeds on the tag you
+ * receive.
  */
-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 makeKeyConfirmation(confirmationKey, role, transcript) {
+    if (confirmationKey.length !== 32)
+        throw new TypeError("confirmationKey must be 32 bytes");
+    return bytesToHex(hmac(sha384, confirmationKey, keyConfirmationBytes(role, transcript)));
 }
 /**
- * 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.
+ * Checks the tag received from the counterpart. Pass the COUNTERPART's role
+ * (an initiator verifies "responder"). Returns false — never throws — for a
+ * wrong tag, a malformed one (any non-string, odd length, non-hex, wrong
+ * length, uppercase) or an unusable key/role, and compares in constant time.
  */
-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 verifyKeyConfirmation(confirmationKey, counterpartRole, transcript, tag) {
+    if (typeof tag !== "string" || !/^[0-9a-f]{96}$/.test(tag))
+        return false;
+    let expected;
+    try {
+        expected = makeKeyConfirmation(confirmationKey, counterpartRole, transcript);
+    }
+    catch {
+        return false;
+    }
+    return equalBytes(hexToBytes(tag), hexToBytes(expected));
+}
+/**
+ * Hashes the FULL transcript — both messages in their entirety, including
+ * each one's own signature and (for the initiator's message) the KEM
+ * ciphertext — not just the stripped ephemeral-key/nonce subset. Binding the
+ * signatures and kemCipherText into the salt means the derived Session Keys
+ * depend on the complete handshake as actually exchanged, not a partial
+ * view of it.
+ */
+function handshakeTranscriptSalt(initiatorCard, responderCard, responderMessage, initiatorMessage) {
+    return sha384(utf8ToBytes(canonicalize({ initiatorCard, responderCard, responderMessage, initiatorMessage })));
+}
+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),
+    };
+}
+/**
+ * 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 createResponderHandshakeCore(identity) {
+    const ephemeralClassical = generateClassicalKeypair();
+    const ephemeralKem = generatePqcKemKeypair();
+    const nonce = bytesToHex(randomBytes(32));
+    // No `counterpart` parameter here: the responder speaks first, before it
+    // knows who it's talking to, so its own signed payload can only bind what
+    // it already knows — tag, role, its own fingerprint, its own ephemeral
+    // keys and nonce. See ADR 0008 for why this asymmetry (vs. the
+    // initiator's reply, which CAN bind the peer) is accepted, not closed.
+    const signedPayload = {
+        tag: HANDSHAKE_DOMAIN_TAG,
+        role: "responder",
+        ownFingerprint: fingerprint(publicCardOf(identity)),
+        ephemeralClassicalPublicKey: bytesToHex(ephemeralClassical.publicKey),
+        ephemeralKemPublicKey: bytesToHex(ephemeralKem.publicKey),
+        nonce,
+    };
+    const signature = signHandshakePayload(identity, signedPayload);
+    const message = {
+        ephemeralClassicalPublicKey: signedPayload.ephemeralClassicalPublicKey,
+        ephemeralKemPublicKey: signedPayload.ephemeralKemPublicKey,
+        nonce,
+        signature,
+    };
+    return {
+        message,
+        ephemeral: {
+            ephemeralClassicalSecretKey: ephemeralClassical.secretKey,
+            ephemeralKemSecretKey: ephemeralKem.secretKey,
+            message,
+        },
+    };
+}
+/**
+ * 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 establishSessionInitiatorCore(identity, counterpart, responderMessage) {
+    if (!isValidResponderHandshakeMessageShape(responderMessage)) {
+        throw new MalformedHandshakeMessageError("Malformed ResponderHandshakeMessage: ephemeral keys/nonce/signature must all be hex strings.");
+    }
+    verifyHandshakeSignature(counterpart, {
+        tag: HANDSHAKE_DOMAIN_TAG,
+        role: "responder",
+        ownFingerprint: fingerprint(counterpart),
+        ephemeralClassicalPublicKey: responderMessage.ephemeralClassicalPublicKey,
+        ephemeralKemPublicKey: responderMessage.ephemeralKemPublicKey,
+        nonce: responderMessage.nonce,
+    }, responderMessage.signature);
+    const ephemeralClassical = generateClassicalKeypair();
+    const nonce = bytesToHex(randomBytes(32));
+    const { cipherText, sharedSecret: kemSecret } = pqcEncapsulate(hexToBytes(responderMessage.ephemeralKemPublicKey));
+    // Unlike the responder, the initiator already knows exactly who it's
+    // talking to and has the responder's message in hand — so its signed
+    // payload binds everything issue #2 asks for: both fingerprints, both
+    // nonces, and the KEM ciphertext this message carries.
+    const signedPayload = {
+        tag: HANDSHAKE_DOMAIN_TAG,
+        role: "initiator",
+        ownFingerprint: fingerprint(publicCardOf(identity)),
+        peerFingerprint: fingerprint(counterpart),
+        ephemeralClassicalPublicKey: bytesToHex(ephemeralClassical.publicKey),
+        nonce,
+        peerNonce: responderMessage.nonce,
+        kemCipherText: bytesToHex(cipherText),
+    };
+    const signature = signHandshakePayload(identity, signedPayload);
+    const message = {
+        ephemeralClassicalPublicKey: signedPayload.ephemeralClassicalPublicKey,
+        nonce,
+        signature,
+        kemCipherText: signedPayload.kemCipherText,
+    };
+    const ephemeralEcdhSecret = classicalSharedSecret(ephemeralClassical.secretKey, hexToBytes(responderMessage.ephemeralClassicalPublicKey));
+    const staticEcdhSecret = classicalSharedSecret(identity.classical.secretKey, hexToBytes(counterpart.classicalPublicKey));
+    const transcriptSalt = handshakeTranscriptSalt(publicCardOf(identity), counterpart, responderMessage, message);
+    const { keys, confirmationKey, rootKey } = deriveSessionSecrets(ephemeralEcdhSecret, kemSecret, staticEcdhSecret, transcriptSalt);
+    return { message, 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) {
+    if (!isValidInitiatorHandshakeMessageShape(initiatorMessage)) {
+        throw new MalformedHandshakeMessageError("Malformed InitiatorHandshakeMessage: ephemeral key/nonce/signature/kemCipherText must all be hex strings.");
+    }
+    verifyHandshakeSignature(counterpart, {
+        tag: HANDSHAKE_DOMAIN_TAG,
+        role: "initiator",
+        ownFingerprint: fingerprint(counterpart),
+        peerFingerprint: fingerprint(publicCardOf(identity)),
+        ephemeralClassicalPublicKey: initiatorMessage.ephemeralClassicalPublicKey,
+        nonce: initiatorMessage.nonce,
+        peerNonce: ephemeral.message.nonce,
+        kemCipherText: initiatorMessage.kemCipherText,
+    }, 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, initiatorMessage);
+    return deriveSessionSecrets(ephemeralEcdhSecret, kemSecret, staticEcdhSecret, transcriptSalt);
 }
 //# sourceMappingURL=hybrid.js.map