raz-encrypt 0.3.0 → 2.1.0

package/dist/crypto/hybrid.d.ts

@@ -7,6 +7,23 @@ declare const ALGORITHMS: {
 export declare class UntrustedPartyError extends Error {
     constructor(alias: string);
 }
+/** 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 declare class DecryptionError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function isValidIsoInstant(value: string): boolean;
 export interface Certificate {
     documentHash: string;
     classicalSignature: string;
@@ -18,6 +35,14 @@ export interface Certificate {
         pqcSignPublicKey: string;
     };
     signedAt: string;
+    /**
+     * Certificate format. 2 (what sign() writes) means the signatures also cover
+     * `signer.alias` and `signedAt`; absent means a legacy certificate whose
+     * signatures cover only the document hash and expiry, so those two fields
+     * are unauthenticated there. A v2 certificate stripped of this field does
+     * not become a valid legacy one: its signatures are over the v2 message.
+     */
+    version?: 2;
     /** Absent = permanent proof, valid indefinitely (the default, unchanged behavior). */
     expiresAt?: string;
 }
@@ -25,7 +50,7 @@ export interface SignOptions {
     /** If set, verify() rejects this certificate as "expired" once this ISO timestamp has passed. */
     expiresAt?: string;
 }
-export type VerifyFailureReason = "untrusted-signer" | "revoked-signer" | "hash-mismatch" | "classical-signature-mismatch" | "pqc-signature-mismatch" | "expired";
+export type VerifyFailureReason = "untrusted-signer" | "revoked-signer" | "hash-mismatch" | "classical-signature-mismatch" | "pqc-signature-mismatch" | "expired" | "malformed-certificate";
 export type VerifyResult = {
     valid: true;
 } | {
@@ -68,50 +93,186 @@ export declare function signCore(identity: Identity, document: unknown, options?
  */
 export declare function verifyCore(identity: Identity, document: unknown, certificate: Certificate, deps: VerifyDeps): Promise<VerifyResult>;
 export interface EncryptedBox {
+    /** Always 2. Version 1 boxes (1.x, unsigned, no context binding) are rejected. */
+    version: 2;
+    /** 16 random bytes, hex. Unique per box; use it to detect replays. */
+    id: string;
+    /** When the sender sealed the box (ISO-8601, covered by the signature). */
+    signedAt: string;
     kemCipherText: string;
     nonce: string;
     ciphertext: string;
+    /** The sender's dual (ECDSA-P384 + ML-DSA-87) signature over everything above and both party fingerprints. */
+    signature: {
+        classicalSignature: string;
+        pqcSignature: string;
+    };
+}
+/** Thrown by decryptFromCore when the caller's `isReplay` hook reports the (otherwise valid) box was already seen. */
+export declare class ReplayedBoxError extends Error {
+    constructor(id: string);
+}
+/** What the replay hook is told about a box that has already passed signature verification. */
+export interface BoxReplayInfo {
+    id: string;
+    signedAt: string;
+    senderFingerprint: string;
+}
+/** decryptFromCore's dependencies: trust, log, and an optional replay check (return true to reject the box). */
+export interface DecryptDeps extends TrustDeps {
+    isReplay?: (info: BoxReplayInfo) => boolean | Promise<boolean>;
 }
 /**
- * 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 declare function encryptForCore(identity: Identity, counterpart: PublicCard, data: unknown, deps: TrustDeps): Promise<EncryptedBox>;
 /**
  * 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 declare function decryptFromCore<T = unknown>(identity: Identity, counterpart: PublicCard, box: EncryptedBox, deps: TrustDeps): Promise<T>;
+export declare function decryptFromCore<T = unknown>(identity: Identity, counterpart: PublicCard, box: EncryptedBox, deps: DecryptDeps): 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);
+}
+/** 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 declare class MalformedHandshakeMessageError extends Error {
+    constructor(message: string);
+}
+/** The four handshake artifacts a confirmation tag is computed over — exactly what both sides hold once the handshake completes. */
+export interface HandshakeTranscript {
+    initiatorCard: PublicCard;
+    responderCard: PublicCard;
+    responderMessage: ResponderHandshakeMessage;
+    initiatorMessage: InitiatorHandshakeMessage;
+}
+export type HandshakeRole = "initiator" | "responder";
+/**
+ * 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 declare function makeKeyConfirmation(confirmationKey: Uint8Array, role: HandshakeRole, transcript: HandshakeTranscript): string;
+/**
+ * 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 declare function verifyKeyConfirmation(confirmationKey: Uint8Array, counterpartRole: HandshakeRole, transcript: HandshakeTranscript, tag: unknown): boolean;
+/**
+ * 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 {};