raz-encrypt 2.3.0 → 2.4.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" | "fingerprint-mismatch";
 export type VerifyResult = {
     valid: true;
 } | {
@@ -68,24 +93,57 @@ 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, decrypted by the responder. */
     initiatorToResponder: Uint8Array;
@@ -154,6 +212,35 @@ export interface ResponderSessionResult {
 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