raz-encrypt 1.1.0 → 2.1.0

package/dist/crypto/nodeHybrid.d.ts

@@ -10,9 +10,9 @@
  * resolvable by a browser bundler with no node:fs in its module graph.
  */
 import type { Identity, PublicCard } from "../identity.js";
-import { type Certificate, type EncryptedBox, type SignOptions, type VerifyResult } from "./hybrid.js";
-export { UntrustedPartyError } from "./hybrid.js";
-export type { Certificate, EncryptedBox, SignOptions, VerifyFailureReason, VerifyResult } from "./hybrid.js";
+import { type DecryptDeps, type Certificate, type EncryptedBox, type SignOptions, type VerifyResult } from "./hybrid.js";
+export { DecryptionError, ReplayedBoxError, UntrustedPartyError } from "./hybrid.js";
+export type { BoxReplayInfo, Certificate, EncryptedBox, SignOptions, VerifyFailureReason, VerifyResult } from "./hybrid.js";
 /**
  * Signs `document` with both the classical (ECDSA-P384) and post-quantum
  * (ML-DSA-87) keys. Permanent by default; pass `options.expiresAt` to make
@@ -39,4 +39,6 @@ export declare function encryptFor(identity: Identity, counterpart: PublicCard,
  * in `identity`'s local trust list — this stops a caller from accidentally
  * decrypting "as if" a message came from someone they never actually trusted.
  */
-export declare function decryptFrom<T = unknown>(identity: Identity, counterpart: PublicCard, box: EncryptedBox): Promise<T>;
+export declare function decryptFrom<T = unknown>(identity: Identity, counterpart: PublicCard, box: EncryptedBox, options?: {
+    isReplay?: DecryptDeps["isReplay"];
+}): Promise<T>;

package/dist/crypto/nodeHybrid.js

@@ -1,7 +1,7 @@
 import { appendLogEntry } from "../store.js";
 import { getTrustRecordsByAlias, getTrustedPartiesByAlias } from "../trust.js";
 import { decryptFromCore, encryptForCore, signCore, verifyCore, } from "./hybrid.js";
-export { UntrustedPartyError } from "./hybrid.js";
+export { DecryptionError, ReplayedBoxError, UntrustedPartyError } from "./hybrid.js";
 async function trustStatusForSigner(identity, signer) {
     const allRecords = await getTrustRecordsByAlias(identity, signer.alias);
     const matchingRecord = allRecords.find((r) => r.card.classicalPublicKey === signer.classicalPublicKey && r.card.pqcSignPublicKey === signer.pqcSignPublicKey);
@@ -56,8 +56,9 @@ export async function encryptFor(identity, counterpart, data) {
  * in `identity`'s local trust list — this stops a caller from accidentally
  * decrypting "as if" a message came from someone they never actually trusted.
  */
-export async function decryptFrom(identity, counterpart, box) {
+export async function decryptFrom(identity, counterpart, box, options = {}) {
     return decryptFromCore(identity, counterpart, box, {
+        isReplay: options.isReplay,
         checkTrust: (card) => trustStatusForCard(identity, card),
         onLog: (entry) => appendLogEntry(identity, entry),
     });

package/dist/crypto/nodeHybrid.js.map

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

package/dist/crypto/pqc.d.ts

@@ -8,8 +8,9 @@ export interface PqcKemKeypair {
 }
 /** ML-DSA-87 (FIPS 204, category-5 parameter set) — the post-quantum signing layer. */
 export declare function generatePqcSignKeypair(): PqcSignKeypair;
-export declare function pqcSign(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
-export declare function pqcVerify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+/** `context` provides domain separation (FIPS 204 §5.4): omit it for document signing (unchanged), pass it for the session handshake so a handshake signature can't be reinterpreted in a different context. */
+export declare function pqcSign(message: Uint8Array, secretKey: Uint8Array, context?: Uint8Array): Uint8Array;
+export declare function pqcVerify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array, context?: Uint8Array): boolean;
 /** ML-KEM-1024 (FIPS 203, category-5 parameter set) — the post-quantum key-exchange layer. */
 export declare function generatePqcKemKeypair(): PqcKemKeypair;
 export declare function pqcEncapsulate(theirPublicKey: Uint8Array): {
@@ -17,3 +18,7 @@ export declare function pqcEncapsulate(theirPublicKey: Uint8Array): {
     sharedSecret: Uint8Array;
 };
 export declare function pqcDecapsulate(cipherText: Uint8Array, secretKey: Uint8Array): Uint8Array;
+/** True iff `keypair`'s two fields are the exact byte lengths ml_dsa87's own keygen produces — a cheap sanity check for key material sourced from somewhere this library doesn't control (e.g. a caller-supplied KeyStore, issue #38). */
+export declare function isValidPqcSignKeypairShape(keypair: PqcSignKeypair): boolean;
+/** Same as isValidPqcSignKeypairShape, for ML-KEM-1024. */
+export declare function isValidPqcKemKeypairShape(keypair: PqcKemKeypair): boolean;

package/dist/crypto/pqc.js

@@ -4,12 +4,13 @@ import { ml_kem1024 } from "@noble/post-quantum/ml-kem.js";
 export function generatePqcSignKeypair() {
     return ml_dsa87.keygen();
 }
-export function pqcSign(message, secretKey) {
-    return ml_dsa87.sign(message, secretKey);
+/** `context` provides domain separation (FIPS 204 §5.4): omit it for document signing (unchanged), pass it for the session handshake so a handshake signature can't be reinterpreted in a different context. */
+export function pqcSign(message, secretKey, context) {
+    return ml_dsa87.sign(message, secretKey, context ? { context } : undefined);
 }
-export function pqcVerify(signature, message, publicKey) {
+export function pqcVerify(signature, message, publicKey, context) {
     try {
-        return ml_dsa87.verify(signature, message, publicKey);
+        return ml_dsa87.verify(signature, message, publicKey, context ? { context } : undefined);
     }
     catch {
         return false;
@@ -25,4 +26,12 @@ export function pqcEncapsulate(theirPublicKey) {
 export function pqcDecapsulate(cipherText, secretKey) {
     return ml_kem1024.decapsulate(cipherText, secretKey);
 }
+/** True iff `keypair`'s two fields are the exact byte lengths ml_dsa87's own keygen produces — a cheap sanity check for key material sourced from somewhere this library doesn't control (e.g. a caller-supplied KeyStore, issue #38). */
+export function isValidPqcSignKeypairShape(keypair) {
+    return keypair.secretKey.length === ml_dsa87.lengths.secretKey && keypair.publicKey.length === ml_dsa87.lengths.publicKey;
+}
+/** Same as isValidPqcSignKeypairShape, for ML-KEM-1024. */
+export function isValidPqcKemKeypairShape(keypair) {
+    return keypair.secretKey.length === ml_kem1024.lengths.secretKey && keypair.publicKey.length === ml_kem1024.lengths.publicKey;
+}
 //# sourceMappingURL=pqc.js.map

package/dist/crypto/pqc.js.map

@@ -1 +1 @@
-{"version":3,"file":"pqc.js","sourceRoot":"","sources":["../../src/crypto/pqc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAY3D,uFAAuF;AACvF,MAAM,UAAU,sBAAsB;IACpC,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAmB,EAAE,SAAqB;IAChE,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,SAAqB,EAAE,OAAmB,EAAE,SAAqB;IACzF,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,qBAAqB;IACnC,OAAO,UAAU,CAAC,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,cAA0B;IACvD,OAAO,UAAU,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,UAAsB,EAAE,SAAqB;IAC1E,OAAO,UAAU,CAAC,WAAW,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"pqc.js","sourceRoot":"","sources":["../../src/crypto/pqc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAY3D,uFAAuF;AACvF,MAAM,UAAU,sBAAsB;IACpC,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED,gNAAgN;AAChN,MAAM,UAAU,OAAO,CAAC,OAAmB,EAAE,SAAqB,EAAE,OAAoB;IACtF,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,SAAqB,EAAE,OAAmB,EAAE,SAAqB,EAAE,OAAoB;IAC/G,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,qBAAqB;IACnC,OAAO,UAAU,CAAC,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,cAA0B;IACvD,OAAO,UAAU,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,UAAsB,EAAE,SAAqB;IAC1E,OAAO,UAAU,CAAC,WAAW,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,0OAA0O;AAC1O,MAAM,UAAU,0BAA0B,CAAC,OAAuB;IAChE,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;AAC5H,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,yBAAyB,CAAC,OAAsB;IAC9D,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC;AAChI,CAAC"}

package/dist/crypto/ratchet.js

@@ -9,6 +9,11 @@ import { classicalSharedSecret } from "./classical.js";
 // group/multi-device fan-out — this stays two-party-only and in-order-only,
 // matching this project's always-ordered, always-1:1 transport).
 //
+// Callers should hold ONE ROOT PER DIRECTION (a send root advanced only by
+// their own steps, a receive root advanced only by mirroring the peer's) and
+// say explicitly on the wire when a step happened and which peer key it used.
+// A single shared root diverges when both sides step at once — see ADR 0013.
+//
 // 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.

package/dist/crypto/ratchet.js.map

@@ -1 +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"}
+{"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,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAC9E,6EAA6E;AAC7E,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/dist/fileCrypto.d.ts

@@ -1,6 +1,48 @@
-/** Encrypts `data` (any JSON-serializable value) at rest under a passphrase-derived AES-256-GCM key. */
-export declare function encryptToFile(filePath: string, passphrase: string, data: unknown): Promise<void>;
+/** Cost used for newly written files. Stored in each file, so it can be raised without a migration. */
+export declare const DEFAULT_KDF: {
+    readonly name: "scrypt";
+    readonly N: number;
+    readonly r: 8;
+    readonly p: 1;
+};
 export declare class DecryptionFailedError extends Error {
     constructor();
 }
+/** The file was written by a newer raz-encrypt than this one understands. */
+export declare class UnsupportedFileVersionError extends Error {
+    constructor(version: unknown);
+}
+/**
+ * Atomically replaces `filePath` with `contents` (mode 0o600): write a temp
+ * file in the same directory, fsync it, rename it over the target, then
+ * best-effort fsync the directory. A crash at any point leaves either the
+ * complete old file or the complete new file — never a partial one.
+ */
+export declare function writeFileAtomic(filePath: string, contents: string, beforeRename?: () => Promise<void>): Promise<void>;
+/** Encrypts `data` (any JSON-serializable value) at rest under a passphrase-derived AES-256-GCM key, in the current (v2) format, atomically. */
+export declare function encryptToFile(filePath: string, passphrase: string, data: unknown): Promise<void>;
+export interface DecryptedFile<T> {
+    data: T;
+    /** True if the file on disk is the legacy v1 format (a caller may upgrade it with `upgradeLegacyFile`). */
+    legacy: boolean;
+    /** Index into the candidate passphrases that actually unlocked the file (0 = the first/preferred one). */
+    passphraseIndex: number;
+}
+/**
+ * Decrypts a file of any supported version and reports whether it was the
+ * legacy format and which candidate passphrase worked. `passphrases` are tried
+ * in order (callers pass the normalized form first, then the raw form for
+ * files written before normalization existed). A missing file rejects with
+ * the filesystem's ENOENT error.
+ */
+export declare function decryptFileWithFormat<T>(filePath: string, passphrases: string | string[]): Promise<DecryptedFile<T>>;
 export declare function decryptFromFile<T>(filePath: string, passphrase: string): Promise<T>;
+/**
+ * Rewrites a file in the current format, under `passphrase` (used for a
+ * legacy v1 file, or one unlocked by a pre-normalization passphrase). Safe by construction:
+ * the new file is written to a temp path, re-read and decrypted with the same
+ * passphrase to prove it round-trips to `data`, and only then renamed over
+ * the original — so the old file stays intact until the instant the verified
+ * replacement atomically takes its place.
+ */
+export declare function upgradeLegacyFile(filePath: string, passphrase: string, data: unknown): Promise<void>;

package/dist/fileCrypto.js

@@ -1,45 +1,214 @@
 import { gcm } from "@noble/ciphers/aes.js";
-import { scrypt } from "@noble/hashes/scrypt.js";
+import { scryptAsync } from "@noble/hashes/scrypt.js";
 import { bytesToHex, hexToBytes, randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
 import { dirname } from "node:path";
-const SCRYPT_PARAMS = { N: 2 ** 17, r: 8, p: 1, dkLen: 32 };
-function deriveKey(passphrase, salt) {
-    return scrypt(utf8ToBytes(passphrase), salt, SCRYPT_PARAMS);
-}
-/** Encrypts `data` (any JSON-serializable value) at rest under a passphrase-derived AES-256-GCM key. */
-export async function encryptToFile(filePath, passphrase, data) {
-    const salt = randomBytes(16);
-    const nonce = randomBytes(12);
-    const key = deriveKey(passphrase, salt);
-    const plaintext = utf8ToBytes(JSON.stringify(data));
-    const ciphertext = gcm(key, nonce).encrypt(plaintext);
-    const payload = {
-        salt: bytesToHex(salt),
-        nonce: bytesToHex(nonce),
-        ciphertext: bytesToHex(ciphertext),
-    };
-    await mkdir(dirname(filePath), { recursive: true });
-    await writeFile(filePath, JSON.stringify(payload), { mode: 0o600 });
-}
+import { canonicalize } from "./canonicalJson.js";
+// Encrypted-at-rest file format (ADR 0016).
+//
+// v2 (current): { version: 2, kdf: { name: "scrypt", N, r, p }, salt, nonce, ciphertext }
+//   - the KDF parameters live in the file, so the cost can be raised later
+//     without breaking files written today;
+//   - the header (version, kdf, salt, nonce) is authenticated as AES-GCM AAD;
+//   - written atomically (temp file + fsync + rename).
+// v1 (legacy, read-only): { salt, nonce, ciphertext } with fixed scrypt
+//   N=2^17 r=8 p=1 and no AAD. Still readable forever; callers may upgrade it.
+/** Cost used for newly written files. Stored in each file, so it can be raised without a migration. */
+export const DEFAULT_KDF = { name: "scrypt", N: 2 ** 17, r: 8, p: 1 };
+const DK_LEN = 32;
+/** The only parameters v1 files could ever have used. */
+const LEGACY_KDF = { name: "scrypt", N: 2 ** 17, r: 8, p: 1 };
+// A file we are asked to open must not be able to make us allocate unbounded
+// memory (scrypt needs ~128*N*r bytes) or burn unbounded CPU.
+const MIN_N = 2 ** 14;
+const MAX_N = 2 ** 20;
+const MAX_N_TIMES_R = 2 ** 23; // ~1 GiB of scrypt memory
+const MAX_R = 16;
+const MAX_P = 4;
 export class DecryptionFailedError extends Error {
     constructor() {
         super("Failed to decrypt local store: wrong passphrase or corrupted/tampered file.");
         this.name = "DecryptionFailedError";
     }
 }
-export async function decryptFromFile(filePath, passphrase) {
+/** The file was written by a newer raz-encrypt than this one understands. */
+export class UnsupportedFileVersionError extends Error {
+    constructor(version) {
+        super(`Local store has format version ${String(version)}, which this version of raz-encrypt does not understand. Upgrade raz-encrypt.`);
+        this.name = "UnsupportedFileVersionError";
+    }
+}
+function isPowerOfTwo(n) {
+    return Number.isInteger(n) && n > 0 && (n & (n - 1)) === 0;
+}
+/** Rejects KDF parameters outside the range this library would ever write, before spending any memory or CPU on them. */
+function validateKdf(kdf) {
+    const k = kdf;
+    const ok = typeof k === "object" &&
+        k !== null &&
+        k.name === "scrypt" &&
+        isPowerOfTwo(k.N) &&
+        k.N >= MIN_N &&
+        k.N <= MAX_N &&
+        Number.isInteger(k.r) &&
+        k.r >= 1 &&
+        k.r <= MAX_R &&
+        Number.isInteger(k.p) &&
+        k.p >= 1 &&
+        k.p <= MAX_P &&
+        k.N * k.r <= MAX_N_TIMES_R;
+    if (!ok)
+        throw new DecryptionFailedError();
+}
+async function deriveKey(passphrase, salt, kdf) {
+    return scryptAsync(utf8ToBytes(passphrase), salt, { N: kdf.N, r: kdf.r, p: kdf.p, dkLen: DK_LEN });
+}
+/** The authenticated header bytes: everything in the file except the ciphertext itself. */
+function headerAad(file) {
+    return utf8ToBytes(canonicalize({ version: file.version, kdf: file.kdf, salt: file.salt, nonce: file.nonce }));
+}
+async function encryptToString(passphrase, data) {
+    const salt = randomBytes(16);
+    const nonce = randomBytes(12);
+    const kdf = { ...DEFAULT_KDF };
+    const key = await deriveKey(passphrase, salt, kdf);
+    const header = { version: 2, kdf, salt: bytesToHex(salt), nonce: bytesToHex(nonce) };
+    const ciphertext = gcm(key, nonce, headerAad(header)).encrypt(utf8ToBytes(JSON.stringify(data)));
+    const file = { ...header, ciphertext: bytesToHex(ciphertext) };
+    return JSON.stringify(file);
+}
+/**
+ * Atomically replaces `filePath` with `contents` (mode 0o600): write a temp
+ * file in the same directory, fsync it, rename it over the target, then
+ * best-effort fsync the directory. A crash at any point leaves either the
+ * complete old file or the complete new file — never a partial one.
+ */
+export async function writeFileAtomic(filePath, contents, beforeRename) {
+    const dir = dirname(filePath);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        const handle = await open(tmpPath, "w", 0o600);
+        try {
+            await handle.writeFile(contents, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (beforeRename)
+            await beforeRename();
+        await rename(tmpPath, filePath);
+    }
+    catch (err) {
+        await rm(tmpPath, { force: true });
+        throw err;
+    }
+    try {
+        const dirHandle = await open(dir, "r");
+        try {
+            await dirHandle.sync();
+        }
+        finally {
+            await dirHandle.close();
+        }
+    }
+    catch {
+        // Directory fsync is best-effort (unsupported on some platforms/filesystems).
+    }
+}
+/** Encrypts `data` (any JSON-serializable value) at rest under a passphrase-derived AES-256-GCM key, in the current (v2) format, atomically. */
+export async function encryptToFile(filePath, passphrase, data) {
+    await writeFileAtomic(filePath, await encryptToString(passphrase, data));
+}
+async function decryptParsed(payload, passphrases) {
+    if (typeof payload !== "object" || payload === null)
+        throw new DecryptionFailedError();
+    const version = payload.version;
+    let salt;
+    let nonce;
+    let ciphertext;
+    let kdf;
+    let aad;
+    let legacy;
+    try {
+        if (version === undefined) {
+            const v1 = payload;
+            salt = hexToBytes(v1.salt);
+            nonce = hexToBytes(v1.nonce);
+            ciphertext = hexToBytes(v1.ciphertext);
+            kdf = { ...LEGACY_KDF };
+            aad = undefined;
+            legacy = true;
+        }
+        else if (version === 2) {
+            const v2 = payload;
+            validateKdf(v2.kdf);
+            salt = hexToBytes(v2.salt);
+            nonce = hexToBytes(v2.nonce);
+            ciphertext = hexToBytes(v2.ciphertext);
+            kdf = v2.kdf;
+            aad = headerAad(v2);
+            legacy = false;
+        }
+        else {
+            throw new UnsupportedFileVersionError(version);
+        }
+    }
+    catch (err) {
+        if (err instanceof UnsupportedFileVersionError)
+            throw err;
+        throw new DecryptionFailedError();
+    }
+    for (let passphraseIndex = 0; passphraseIndex < passphrases.length; passphraseIndex++) {
+        const key = await deriveKey(passphrases[passphraseIndex], salt, kdf);
+        try {
+            const plaintext = gcm(key, nonce, aad).decrypt(ciphertext);
+            return { data: JSON.parse(new TextDecoder().decode(plaintext)), legacy, passphraseIndex };
+        }
+        catch {
+            // Try the next candidate passphrase, if any.
+        }
+    }
+    throw new DecryptionFailedError();
+}
+/**
+ * Decrypts a file of any supported version and reports whether it was the
+ * legacy format and which candidate passphrase worked. `passphrases` are tried
+ * in order (callers pass the normalized form first, then the raw form for
+ * files written before normalization existed). A missing file rejects with
+ * the filesystem's ENOENT error.
+ */
+export async function decryptFileWithFormat(filePath, passphrases) {
     const raw = await readFile(filePath, "utf8");
-    const payload = JSON.parse(raw);
-    const salt = hexToBytes(payload.salt);
-    const nonce = hexToBytes(payload.nonce);
-    const key = deriveKey(passphrase, salt);
+    let payload;
     try {
-        const plaintext = gcm(key, nonce).decrypt(hexToBytes(payload.ciphertext));
-        return JSON.parse(new TextDecoder().decode(plaintext));
+        payload = JSON.parse(raw);
     }
     catch {
         throw new DecryptionFailedError();
     }
+    return (await decryptParsed(payload, Array.isArray(passphrases) ? passphrases : [passphrases]));
+}
+export async function decryptFromFile(filePath, passphrase) {
+    return (await decryptFileWithFormat(filePath, passphrase)).data;
+}
+/**
+ * Rewrites a file in the current format, under `passphrase` (used for a
+ * legacy v1 file, or one unlocked by a pre-normalization passphrase). Safe by construction:
+ * the new file is written to a temp path, re-read and decrypted with the same
+ * passphrase to prove it round-trips to `data`, and only then renamed over
+ * the original — so the old file stays intact until the instant the verified
+ * replacement atomically takes its place.
+ */
+export async function upgradeLegacyFile(filePath, passphrase, data) {
+    const contents = await encryptToString(passphrase, data);
+    const expected = JSON.stringify(data);
+    await writeFileAtomic(filePath, contents, async () => {
+        // Verify the exact bytes we are about to publish, with the real passphrase.
+        const check = await decryptParsed(JSON.parse(contents), [passphrase]);
+        if (JSON.stringify(check.data) !== expected)
+            throw new Error("Upgraded identity file failed its round-trip check; leaving the original untouched.");
+    });
 }
 //# sourceMappingURL=fileCrypto.js.map

package/dist/fileCrypto.js.map

@@ -1 +1 @@
-{"version":3,"file":"fileCrypto.js","sourceRoot":"","sources":["../src/fileCrypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,aAAa,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAQ5D,SAAS,SAAS,CAAC,UAAkB,EAAE,IAAgB;IACrD,OAAO,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;AAC9D,CAAC;AAED,wGAAwG;AACxG,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,UAAkB,EAAE,IAAa;IACrF,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtD,MAAM,OAAO,GAAkB;QAC7B,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC;QACtB,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC;QACxB,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC;KACnC,CAAC;IAEF,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C;QACE,KAAK,CAAC,6EAA6E,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAI,QAAgB,EAAE,UAAkB;IAC3E,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAkB,CAAC;IACjD,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAExC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAM,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,qBAAqB,EAAE,CAAC;IACpC,CAAC;AACH,CAAC"}
+{"version":3,"file":"fileCrypto.js","sourceRoot":"","sources":["../src/fileCrypto.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -1,4 +1,6 @@
 import { type ClassicalKeypair } from "./crypto/classical.js";
+import { type Certificate, type SignOptions } from "./crypto/hybrid.js";
+import { MIN_PASSPHRASE_LENGTH, type PassphraseChecker } from "./passphrase.js";
 import { type PqcKemKeypair, type PqcSignKeypair } from "./crypto/pqc.js";
 export interface Identity {
     alias: string;
@@ -14,22 +16,31 @@ export interface PublicCard {
     pqcSignPublicKey: string;
     pqcKemPublicKey: string;
 }
-export declare const MIN_PASSPHRASE_LENGTH = 12;
+export { MIN_PASSPHRASE_LENGTH };
 export interface CreateIdentityOptions {
     storageDir: string;
     passphrase: string;
     alias: string;
     /** Overwrite an existing identity at this storageDir. Defaults to false. */
     overwrite?: boolean;
+    /** Optional, runs after the built-in checks below. See PassphraseChecker (ADR 0021). */
+    checkPassphrase?: PassphraseChecker;
 }
 /**
  * Generates a new hybrid classical+post-quantum identity (one ECDSA/ECDH-P384
  * keypair, one ML-DSA-87 signing keypair, one ML-KEM-1024 key-exchange
  * keypair) and persists it encrypted-at-rest under `storageDir`.
  *
- * Requires a passphrase of at least MIN_PASSPHRASE_LENGTH characters — this
- * check only applies here, not to loadIdentity, so an identity created
- * before this check existed can still be loaded with its original passphrase.
+ * The passphrase is normalized to Unicode NFKC, must be at least
+ * MIN_PASSPHRASE_LENGTH characters (counted as code points after
+ * normalization), must not be a single repeated character, and must not be
+ * on a small blocklist of very common passphrases (ADR 0017). These checks
+ * only apply here, not to loadIdentity, so an identity created before they
+ * existed can still be loaded with its original passphrase.
+ *
+ * `options.checkPassphrase`, if supplied, runs after all of the above pass
+ * (ADR 0021) — this is where real breach-corpus checking belongs, not in
+ * this library's own, deliberately small, blocklist.
  */
 export declare function createIdentity(options: CreateIdentityOptions): Promise<Identity>;
 export interface LoadIdentityOptions {
@@ -38,5 +49,59 @@ export interface LoadIdentityOptions {
 }
 /** Loads a previously-created identity back from disk. */
 export declare function loadIdentity(options: LoadIdentityOptions): Promise<Identity>;
+/**
+ * Supplies an Identity's secret-key material from somewhere other than
+ * `identity.enc.json` — an OS keychain, a TPM, an HSM, anything (issue
+ * #38/ADR 0024). Scoped to key SOURCING, not operation delegation: once
+ * `load()` returns, this library operates on the returned Uint8Arrays
+ * directly in its own process memory exactly as it does for a file-loaded
+ * Identity. There is no way to make classicalSign/pqcSign/etc. forward the
+ * actual signing operation to the device instead — see ADR 0024 for why
+ * that's out of scope (and, for the post-quantum half, not achievable with
+ * any hardware that exists today regardless).
+ */
+export interface KeyStore {
+    load(): Promise<{
+        classical: ClassicalKeypair;
+        pqcSign: PqcSignKeypair;
+        pqcKem: PqcKemKeypair;
+    }>;
+}
+export interface LoadIdentityFromKeyStoreOptions {
+    alias: string;
+    storageDir: string;
+    keyStore: KeyStore;
+}
+/**
+ * Builds an Identity from a caller-supplied KeyStore instead of a
+ * passphrase-encrypted file — `identity.enc.json` and a passphrase are
+ * never part of the picture. The returned key material's shape (byte
+ * lengths) is validated before trusting it, so a buggy KeyStore fails
+ * clearly here rather than with a cryptic error the first time a signing
+ * call happens to touch the bad bytes. `storageDir` is still required: the
+ * trust store and audit log are a separate concern from where secret keys
+ * live, unaffected by this function.
+ */
+export declare function loadIdentityFromKeyStore(options: LoadIdentityFromKeyStoreOptions): Promise<Identity>;
+/**
+ * Best-effort wipe of the secret key bytes held by `identity`: overwrites
+ * them with zeros so they do not linger in this process's memory after you
+ * are done. The identity is unusable afterwards. Limits: JavaScript gives no
+ * guarantee about copies the engine or GC already made, and the hex strings
+ * produced while saving or loading an identity are immutable and cannot be
+ * wiped. This narrows the exposure window; it is not a secure-erase.
+ */
+export declare function zeroizeIdentity(identity: Identity): void;
 /** The shareable public half of an identity — hand this to the other party out of band. */
 export declare function exportPublicIdentity(identity: Identity): PublicCard;
+/**
+ * A self-signed, optionally time-limited version of `exportPublicIdentity`'s
+ * card (ADR 0023/issue #37): the identity signs its own card, so a peer can
+ * verify it wasn't tampered with and — if `options.expiresAt` was set —
+ * reject it once expired, enforcing a cryptoperiod the bare card has no way
+ * to carry (it has no signature at all). `exportPublicIdentity` itself is
+ * unchanged; this is a separate, opt-in function precisely so every
+ * existing caller of the bare card is unaffected. Verify and trust a
+ * received one with `trustSignedCard`, not `trustParty`.
+ */
+export declare function exportSignedCard(identity: Identity, options?: SignOptions): Promise<Certificate>;