raz-encrypt 0.3.0 → 2.1.0

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>;

package/dist/identity.js

@@ -1,9 +1,34 @@
 import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { generateClassicalKeypair } from "./crypto/classical.js";
-import { decryptFromFile, encryptToFile } from "./fileCrypto.js";
-import { generatePqcKemKeypair, generatePqcSignKeypair } from "./crypto/pqc.js";
+import { generateClassicalKeypair, isValidClassicalKeypairShape } from "./crypto/classical.js";
+import { signCore } from "./crypto/hybrid.js";
+import { decryptFileWithFormat, DecryptionFailedError, encryptToFile, upgradeLegacyFile } from "./fileCrypto.js";
+import { assertAcceptablePassphrase, MIN_PASSPHRASE_LENGTH, normalizePassphrase } from "./passphrase.js";
+import { generatePqcKemKeypair, generatePqcSignKeypair, isValidPqcKemKeypairShape, isValidPqcSignKeypairShape, } from "./crypto/pqc.js";
+function isHex(value) {
+    return typeof value === "string" && value.length % 2 === 0 && /^[0-9a-f]*$/i.test(value);
+}
+function isValidKeypairShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return isHex(v.publicKey) && isHex(v.secretKey);
+}
+/**
+ * Structural shape check for a decrypted identity file's plaintext. In
+ * normal operation AEAD authentication already guarantees this shape, so a
+ * malformed value here would mean a wrong/corrupted ciphertext slipped past
+ * decryption (practically impossible without the passphrase) — this exists
+ * so that case fails closed with DecryptionFailedError instead of crashing
+ * on a missing/non-hex field (found by fuzzing, issue #42).
+ */
+function isValidSerializedIdentityShape(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const d = data;
+    return typeof d.alias === "string" && isValidKeypairShape(d.classical) && isValidKeypairShape(d.pqcSign) && isValidKeypairShape(d.pqcKem);
+}
 function identityFilePath(storageDir) {
     return join(storageDir, "identity.enc.json");
 }
@@ -42,20 +67,28 @@ function deserialize(storageDir, data) {
         },
     };
 }
-export const MIN_PASSPHRASE_LENGTH = 12;
+export { MIN_PASSPHRASE_LENGTH };
 /**
  * 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 async function createIdentity(options) {
-    if (options.passphrase.length < MIN_PASSPHRASE_LENGTH) {
-        throw new Error(`Passphrase must be at least ${MIN_PASSPHRASE_LENGTH} characters long.`);
-    }
+    const passphrase = normalizePassphrase(options.passphrase);
+    assertAcceptablePassphrase(passphrase);
+    if (options.checkPassphrase)
+        await options.checkPassphrase(passphrase);
     const filePath = identityFilePath(options.storageDir);
     if (!options.overwrite && existsSync(filePath)) {
         throw new Error(`An identity already exists at ${filePath}. Pass { overwrite: true } to replace it.`);
@@ -67,14 +100,67 @@ export async function createIdentity(options) {
         pqcSign: generatePqcSignKeypair(),
         pqcKem: generatePqcKemKeypair(),
     };
-    await encryptToFile(filePath, options.passphrase, serialize(identity));
+    await encryptToFile(filePath, passphrase, serialize(identity));
     return identity;
 }
 /** Loads a previously-created identity back from disk. */
 export async function loadIdentity(options) {
-    const data = await decryptFromFile(identityFilePath(options.storageDir), options.passphrase);
+    const filePath = identityFilePath(options.storageDir);
+    const normalized = normalizePassphrase(options.passphrase);
+    // Normalized form first; the raw form only matters for a file written
+    // before normalization existed under a passphrase NFKC would change.
+    const candidates = normalized === options.passphrase ? [normalized] : [normalized, options.passphrase];
+    const { data, legacy, passphraseIndex } = await decryptFileWithFormat(filePath, candidates);
+    if (!isValidSerializedIdentityShape(data))
+        throw new DecryptionFailedError();
+    if (legacy || passphraseIndex > 0) {
+        // Upgrade a pre-versioned file (and/or re-key one made under an
+        // un-normalized passphrase) to the current format under the normalized
+        // passphrase now that the passphrase is proven correct. Best effort: a
+        // read-only directory or a full disk must not stop the identity from
+        // loading.
+        try {
+            await upgradeLegacyFile(filePath, normalized, data);
+        }
+        catch {
+            // The original file is untouched (see upgradeLegacyFile); try again on the next load.
+        }
+    }
     return deserialize(options.storageDir, data);
 }
+/**
+ * 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 async function loadIdentityFromKeyStore(options) {
+    const { classical, pqcSign, pqcKem } = await options.keyStore.load();
+    if (!isValidClassicalKeypairShape(classical))
+        throw new Error("KeyStore returned a classical keypair with the wrong byte length(s) for P-384.");
+    if (!isValidPqcSignKeypairShape(pqcSign))
+        throw new Error("KeyStore returned a pqcSign keypair with the wrong byte length(s) for ML-DSA-87.");
+    if (!isValidPqcKemKeypairShape(pqcKem))
+        throw new Error("KeyStore returned a pqcKem keypair with the wrong byte length(s) for ML-KEM-1024.");
+    return { alias: options.alias, storageDir: options.storageDir, classical, pqcSign, pqcKem };
+}
+/**
+ * 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 function zeroizeIdentity(identity) {
+    identity.classical.secretKey.fill(0);
+    identity.pqcSign.secretKey.fill(0);
+    identity.pqcKem.secretKey.fill(0);
+}
 /** The shareable public half of an identity — hand this to the other party out of band. */
 export function exportPublicIdentity(identity) {
     return {
@@ -84,4 +170,17 @@ export function exportPublicIdentity(identity) {
         pqcKemPublicKey: bytesToHex(identity.pqcKem.publicKey),
     };
 }
+/**
+ * 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 async function exportSignedCard(identity, options = {}) {
+    return signCore(identity, exportPublicIdentity(identity), options);
+}
 //# sourceMappingURL=identity.js.map

package/dist/identity.js.map

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

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { canonicalize, hashDocument } from "./canonicalJson.js";
 export { fingerprint } from "./fingerprint.js";
-export { decryptFrom, encryptFor, sign, UntrustedPartyError, verify } from "./crypto/nodeHybrid.js";
-export type { Certificate, EncryptedBox, VerifyFailureReason, VerifyResult } from "./crypto/nodeHybrid.js";
-export { createIdentity, exportPublicIdentity, loadIdentity, MIN_PASSPHRASE_LENGTH } from "./identity.js";
-export type { CreateIdentityOptions, Identity, LoadIdentityOptions, PublicCard } from "./identity.js";
-export { readLog, verifyLogIntegrity } from "./store.js";
+export { decryptFrom, DecryptionError, encryptFor, ReplayedBoxError, sign, UntrustedPartyError, verify } from "./crypto/nodeHybrid.js";
+export type { BoxReplayInfo, Certificate, EncryptedBox, VerifyFailureReason, VerifyResult } from "./crypto/nodeHybrid.js";
+export { createIdentity, exportPublicIdentity, exportSignedCard, loadIdentity, loadIdentityFromKeyStore, MIN_PASSPHRASE_LENGTH, zeroizeIdentity, } from "./identity.js";
+export type { CreateIdentityOptions, Identity, KeyStore, LoadIdentityFromKeyStoreOptions, LoadIdentityOptions, PublicCard } from "./identity.js";
+export type { PassphraseChecker } from "./passphrase.js";
+export { migrateAuditLogToEncrypted, readLog, verifyLogIntegrity } from "./store.js";
 export type { LogEntry, LogIntegrityResult } from "./store.js";
-export { getTrustedParty, getTrustedPartiesByAlias, getTrustRecordsByAlias, listTrustedParties, listTrustRecords, trustParty, untrustParty, } from "./trust.js";
-export type { TrustRecord } from "./trust.js";
+export { applyRevocationNotice, applyRotation, beginRotation, completeRotation, createRevocationNotice, getTrustedParty, getTrustedPartiesByAlias, getTrustRecordsByAlias, listTrustedParties, listTrustRecords, migrateLegacyTrustStore, migrateTrustStoreToEncrypted, TrustStoreIntegrityError, trustParty, trustSignedCard, untrustFingerprint, untrustParty, } from "./trust.js";
+export type { RevocationDocument, RevocationNotice, RotationDocument, RotationStatement, TrustRecord } from "./trust.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { canonicalize, hashDocument } from "./canonicalJson.js";
 export { fingerprint } from "./fingerprint.js";
-export { decryptFrom, encryptFor, sign, UntrustedPartyError, verify } from "./crypto/nodeHybrid.js";
-export { createIdentity, exportPublicIdentity, loadIdentity, MIN_PASSPHRASE_LENGTH } from "./identity.js";
-export { readLog, verifyLogIntegrity } from "./store.js";
-export { getTrustedParty, getTrustedPartiesByAlias, getTrustRecordsByAlias, listTrustedParties, listTrustRecords, trustParty, untrustParty, } from "./trust.js";
+export { decryptFrom, DecryptionError, encryptFor, ReplayedBoxError, sign, UntrustedPartyError, verify } from "./crypto/nodeHybrid.js";
+export { createIdentity, exportPublicIdentity, exportSignedCard, loadIdentity, loadIdentityFromKeyStore, MIN_PASSPHRASE_LENGTH, zeroizeIdentity, } from "./identity.js";
+export { migrateAuditLogToEncrypted, readLog, verifyLogIntegrity } from "./store.js";
+export { applyRevocationNotice, applyRotation, beginRotation, completeRotation, createRevocationNotice, getTrustedParty, getTrustedPartiesByAlias, getTrustRecordsByAlias, listTrustedParties, listTrustRecords, migrateLegacyTrustStore, migrateTrustStoreToEncrypted, TrustStoreIntegrityError, trustParty, trustSignedCard, untrustFingerprint, untrustParty, } from "./trust.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEpG,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE1G,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEvI,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,GAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,0BAA0B,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErF,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/passphrase.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Passphrase handling shared by every place a passphrase becomes key
+ * material (ADR 0017).
+ *
+ * Normalization: the same visible passphrase can be encoded as different
+ * Unicode code point sequences (composed vs decomposed accents, full-width
+ * digits, ...) depending on the keyboard, OS or app that typed it, which
+ * would derive different keys. Passphrases are normalized to NFKC before
+ * the KDF so what the user sees is what unlocks. For pure-ASCII passphrases
+ * NFKC is the identity, so nothing changes for them.
+ */
+export declare function normalizePassphrase(passphrase: string): string;
+export declare const MIN_PASSPHRASE_LENGTH = 12;
+/**
+ * A caller-supplied passphrase check, run by createIdentity AFTER the
+ * built-in checks (length, repeated-character, the small blocklist above)
+ * pass. Receives the already-normalized passphrase. Throw (synchronously or
+ * via a rejected promise) to reject it with your own message — e.g. because
+ * it's found in a real breach corpus, or scores poorly under a strength
+ * estimator. This is the actual fix for NIST SP 800-63B's breach-check
+ * expectation (ADR 0021): the built-in blocklist above is deliberately not
+ * grown to try to meet that bar itself, and this library adds no built-in
+ * network-calling checker (e.g. an HIBP lookup) of its own.
+ */
+export type PassphraseChecker = (normalized: string) => void | Promise<void>;
+/** Throws if `passphrase` (already normalized) is unacceptable for a NEW identity. Loading an existing identity never calls this. */
+export declare function assertAcceptablePassphrase(normalized: string): void;