raz-encrypt 0.3.0 → 2.1.0

package/README.md

@@ -1,212 +1,442 @@
-# RAZ Encrypt
-
-A local-first npm library for **two consenting parties** to sign documents, verify each other's signatures, and privately encrypt data for each other — with no server, no database, and no third-party account. Each party keeps their own identity and audit log in a small encrypted file on their own machine.
-
-Built around a **hybrid classical + post-quantum** cryptography design (see "Security posture" below) rather than any single algorithm.
-
-## How it works (the short version)
-
-1. Alice and Bob each call `createIdentity()` once. This generates their keys and stores them, encrypted, in a local folder.
-2. They exchange their **public cards** — just public keys, safe to send over email/Slack/whatever — and call `trustParty()` to record each other as trusted.
-3. From then on: Alice can `sign()` a document; Bob can `verify()` it against the certificate. Either of them can `encryptFor()` the other and `decryptFrom()` what they receive.
-
-Nothing here requires the two parties' computers to ever talk to each other directly — everything is exchanged "by hand" (file, email, chat), and each side's storage is entirely local and private to them.
-
-## Install
-
-```bash
-npm install raz-encrypt
-```
-
-## Quickstart
-
-```ts
-import {
-  createIdentity,
-  exportPublicIdentity,
-  trustParty,
-  sign,
-  verify,
-} from "raz-encrypt";
-
-// --- Alice, once ---
-const alice = await createIdentity({
-  storageDir: "./alice-store",
-  passphrase: "alice's secret passphrase",
-  alias: "alice",
-});
-const aliceCard = exportPublicIdentity(alice); // send this to Bob
-
-// --- Bob, once ---
-const bob = await createIdentity({
-  storageDir: "./bob-store",
-  passphrase: "bob's secret passphrase",
-  alias: "bob",
-});
-const bobCard = exportPublicIdentity(bob); // send this to Alice
-
-// --- Before trusting, compare fingerprints over a side channel (phone call, in person) ---
-// This is what catches a spoofed or intercepted card — email/chat alone can't prove
-// a card really came from the person you think it did.
-import { fingerprint } from "raz-encrypt";
-console.log("Alice reads this aloud:", fingerprint(aliceCard));
-console.log("Bob confirms it matches what he sees:", fingerprint(bobCard));
-
-// --- Both sides trust each other (after swapping cards AND confirming fingerprints) ---
-await trustParty(alice, bobCard);
-await trustParty(bob, aliceCard);
-
-// --- Alice signs a document ---
-const document = { invoiceId: "INV-1", amount: 15000 };
-const certificate = await sign(alice, document);
-
-// --- Bob verifies it (send him `document` + `certificate`) ---
-const result = await verify(bob, document, certificate);
-// => { valid: true }
-```
-
-If the document is changed even slightly, or the certificate is corrupted, or the signer was never trusted, `verify()` returns `{ valid: false, reason: "..." }` instead of throwing — so a caller always gets a clear, structured answer.
-
-### Private data between the two parties
-
-```ts
-import { encryptFor, decryptFrom } from "raz-encrypt";
-
-const box = await encryptFor(alice, bobCard, {
-  secretPayload: "only Bob should read this",
-});
-const opened = await decryptFrom(bob, aliceCard, box);
-```
-
-## Two important things people ask when actually wiring this up
-
-**1. `sign`/`verify` and `encryptFor`/`decryptFrom` are two separate, independent tools — not a pipeline.**
-
-- `sign` + `verify` prove **authenticity**: "this exact document really came from Alice and wasn't altered." The document itself travels in the clear.
-- `encryptFor` + `decryptFrom` provide **confidentiality**: "nobody but Bob can read this." It says nothing about who sent it.
-
-You use whichever one (or both) fits what you're protecting against. You do **not** need to call `verify()` before you can call `decryptFrom()`, or vice versa — neither depends on the other. If you want both (a document that's both proven-authentic _and_ private), sign it, then encrypt the `{ document, certificate }` pair together — see the worked example below.
-
-**2. A "card" (from `exportPublicIdentity`) is just a JSON object.** However Alice actually gets it to Bob — email attachment, Slack message, QR code, USB stick — Bob ends up with the same plain JSON on disk. Loading it back is nothing more than reading that file and `JSON.parse`-ing it; there's no special "import" step.
-
-## Full example: Bob receives something from Alice
-
-Assume Bob has already run `createIdentity()` once (so he has his own `storageDir` + passphrase) and already has `alice-card.json` — the file Alice sent him after she ran `exportPublicIdentity()` on her side.
-
-```ts
-import { readFile } from "node:fs/promises";
-import {
-  loadIdentity,
-  decryptFrom,
-  verify,
-  type PublicCard,
-  type Certificate,
-} from "raz-encrypt";
-
-// Step 1 — Bob loads his own identity (needs his own passphrase, not Alice's).
-const bob = await loadIdentity({
-  storageDir: "./bob-store",
-  passphrase: "bob's secret passphrase",
-});
-
-// Step 2 — Bob loads Alice's card. It's just JSON — read whatever file/message it arrived in.
-const aliceCard: PublicCard = JSON.parse(
-  await readFile("./alice-card.json", "utf8"),
-);
-// (One-time only: before the first exchange, Bob must also have called
-//  trustParty(bob, aliceCard) once — otherwise decryptFrom/verify will refuse Alice's card.)
-
-// --- If what Alice sent was ENCRYPTED (confidential) ---
-const box = JSON.parse(await readFile("./received-box.json", "utf8"));
-const opened = await decryptFrom(bob, aliceCard, box);
-
-// --- If what Alice sent was SIGNED (a document + a certificate, sent in the clear) ---
-const { document, certificate } = JSON.parse(
-  await readFile("./signed-doc.json", "utf8"),
-) as {
-  document: unknown;
-  certificate: Certificate;
-};
-const result = await verify(bob, document, certificate);
-// => { valid: true } or { valid: false, reason: "..." }
-
-// --- If Alice sent something both signed AND encrypted ---
-// She encrypted { document, certificate } as one payload with encryptFor(); Bob does:
-const openedSignedPayload = await decryptFrom<{
-  document: unknown;
-  certificate: Certificate;
-}>(bob, aliceCard, box);
-const combinedResult = await verify(
-  bob,
-  openedSignedPayload.document,
-  openedSignedPayload.certificate,
-);
-```
-
-**So, to directly answer "do I need to run verify first?"** — no. `verify()` is only relevant when Alice actually signed something; `decryptFrom()` is only relevant when Alice actually encrypted something. Run whichever one matches what you received, in either order, or both if she did both.
-
-## API
-
-| Function                                                                                      | What it does                                                                                                                                                                                                      |
-| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `createIdentity({ storageDir, passphrase, alias, overwrite? })`                               | Generates a new identity (see "Security posture") and persists it encrypted at `storageDir`. Requires a passphrase of at least `MIN_PASSPHRASE_LENGTH` (12) characters.                                           |
-| `loadIdentity({ storageDir, passphrase })`                                                    | Loads a previously-created identity back from disk.                                                                                                                                                               |
-| `exportPublicIdentity(identity)`                                                              | Returns the shareable public card `{ alias, classicalPublicKey, pqcSignPublicKey, pqcKemPublicKey }`.                                                                                                             |
-| `fingerprint(card)`                                                                           | Short, human-comparable fingerprint of a public card (grouped hex). Compare this over a side channel before trusting a card you received over email/chat.                                                         |
-| `trustParty(identity, card)`                                                                  | Records another party's public card as trusted, locally. Re-trusting a previously revoked card reinstates it.                                                                                                     |
-| `untrustParty(identity, alias)`                                                               | Revokes every currently-trusted card under `alias` (e.g. after a suspected key compromise). Tombstoned, not deleted — `verify()` reports `"revoked-signer"` distinctly from `"untrusted-signer"` (never trusted). |
-| `listTrustedParties(identity)` / `getTrustedParty(identity, alias)`                           | Read back your local trust list (revoked cards excluded).                                                                                                                                                         |
-| `getTrustedPartiesByAlias(identity, alias)` / `getTrustRecordsByAlias(identity, alias)`       | Since alias isn't unique, these return _every_ card under an alias — the latter includes revoked ones, with their `revokedAt`.                                                                                    |
-| `listTrustRecords(identity)`                                                                  | Full trust history, revoked included — for audit purposes.                                                                                                                                                        |
-| `sign(identity, document, options?)`                                                          | Canonicalizes and hashes `document`, signs it with both keys, returns a `Certificate`. Pass `{ expiresAt }` (ISO timestamp) to make it expire; omit it for a permanent proof (the default).                       |
-| `verify(identity, document, certificate)`                                                     | Checks the certificate's signer is trusted (and not revoked), the document hasn't changed, it hasn't expired, and both signatures check out.                                                                      |
-| `encryptFor(identity, counterpartCard, data)` / `decryptFrom(identity, counterpartCard, box)` | Encrypt/decrypt data meant only for one specific counterpart. Both throw `UntrustedPartyError` unless that counterpart is already in your local trust list (`trustParty`).                                        |
-| `readLog(identity)`                                                                           | Reads the local, append-only audit log of everything this identity has signed/verified/encrypted/decrypted.                                                                                                       |
-| `verifyLogIntegrity(identity)`                                                                | Walks the log's hash chain and reports `{ intact: true }` or `{ intact: false, brokenAtIndex }` — detects an edited or deleted entry.                                                                             |
-| `canonicalize(value)` / `hashDocument(value)`                                                 | The deterministic JSON hashing used internally — exposed in case you want to compute a document hash yourself.                                                                                                    |
-
-## Security posture
-
-**Is this "military grade"?** It uses the same algorithms — ECDSA/ECDH on curve P-384, AES-256 — that banks, governments, and CNSA-1.0-compliant systems use. The math is the real thing, not a toy. What it is **not** is FIPS 140-2/3 (CMVP) validated: that's a certification of one specific software build/deployment, done by an accredited lab, and it takes years — no realistic npm library ships with that certification. Not being certified doesn't mean it's unsafe: it's the difference between a home-cooked meal made with the exact same top-shelf ingredients a certified restaurant uses, versus the restaurant's official health-inspection paperwork. The ingredients and technique are what make it safe; the certificate just proves it to a third party who requires that paperwork (e.g. a specific government/defense procurement rule). If your use case legally _requires_ FIPS-validated modules, this library's logic needs to run inside a validated HSM/crypto boundary — that's a deployment decision outside what any library's code can provide on its own.
-
-**Is this quantum-safe?** Half of the design is built specifically for that. **ML-KEM-1024** (key exchange) and **ML-DSA-87** (signatures) are NIST's official post-quantum standards (FIPS 203 / FIPS 204, finalized 2024), chosen because classical ECC and RSA can eventually be broken by a large enough quantum computer via Shor's algorithm. We don't rely on the post-quantum algorithms _alone_, though — they're only a few years old, with far less real-world cryptanalysis behind them than P-384. So every signature and every shared secret in this library requires **both** the classical layer and the post-quantum layer to hold:
-
-- **Signing**: every document is signed twice — once with ECDSA-P384, once with ML-DSA-87. `verify()` only returns `valid: true` if **both** signatures check out.
-- **Encryption**: the AES-256-GCM key is derived (via HKDF-SHA384) from **both** an ECDH-P384 exchange and an ML-KEM-1024 encapsulation.
-
-If one layer is ever broken — classical by a quantum computer, or the newer post-quantum standard by an as-yet-undiscovered flaw — the other still protects you.
-
-**Bottom line:** this is genuinely strong, real-world-grade cryptography built from carefully audited, widely used components (the [`@noble/*`](https://github.com/paulmillr/noble-post-quantum) libraries) — not a marketing label. It just isn't a government-certified module, and true safety also depends on this specific implementation being built and tested carefully, which is exactly what the test suite's "try to break it" cases (tampered documents, corrupted individual signatures) are for.
-
-**What `sign`/`verify` guarantees, precisely.** Every field that affects a verification outcome — the document hash _and_ the optional `expiresAt` — is part of the signed payload, not just `documentHash` alone. That matters because certificates travel over the exact same untrusted channels (email, chat) this library assumes for everything else: without that, an intermediary with no secret key at all could delete or rewrite `expiresAt` in transit and flip a `verify()` result, which would quietly defeat the whole point of setting an expiry.
-
-**Two honest limitations, so you can decide if they matter for your use case:**
-
-- **No forward secrecy.** `encryptFor`/`decryptFrom` derive their key from _long-term_ keys on both sides: a static ECDH-P384 exchange (deterministic for a given pair of identities) combined with an ML-KEM-1024 encapsulation whose secret still requires the recipient's long-term KEM secret key to decapsulate. Both of those secret keys live in the same `identity.enc.json`. This means that if someone ever recovers your passphrase and that file, they can decrypt **every box anyone ever sent you**, not just future ones — there's no per-message ephemeral key rotation (the kind Signal-style ratcheting provides). Rotate identities (new `storageDir`, `trustParty()` again) if you need to bound the blast radius of a future key compromise.
-- **No replay protection.** An `EncryptedBox` decrypts identically no matter how many times, or how much later, it's replayed to the same recipient — there's no session id, counter, or timestamp binding it to a single delivery. Fine for "send this document once"; if your use case cares about replay (e.g. treating receipt of a box as a one-time authorization), add your own nonce/timestamp inside the encrypted payload and check it on the receiving end.
-
-## What this library deliberately does _not_ do (v1)
-
-- No server, no HTTP API, no database — everything is local files.
-- No live network sync between the two parties' machines — public cards, documents, and certificates are exchanged "by hand" (file/email/etc.), not automatically.
-- No multi-party or hierarchical signing (buyers/vendors/approval-levels/etc.) — this is a generic building block for exactly two parties trusting each other directly.
-- **Node.js only, not a browser library.** The underlying `@noble/*` crypto libraries are isomorphic and would run fine in a browser, but the storage layer (`identity.enc.json`, `trust.json`, `log.jsonl`) is built on `node:fs`, which browsers don't have. There's no IndexedDB (or similar) storage adapter — if you need this in a browser, that adapter would need to be built.
-
-## Local storage layout
-
-Each identity's `storageDir` contains:
-
-```
-identity.enc.json   # your keys, encrypted at rest under your passphrase (AES-256-GCM, scrypt-derived key)
-trust.json          # fingerprint-keyed public cards of parties you've trusted (or revoked) — not secret, just public keys
-log.jsonl           # hash-chained, append-only audit log: what you've signed/verified/encrypted/decrypted, and when
-```
-
-## Development
-
-```bash
-npm install
-npm run typecheck
-npm test
-npm run build
-```
+# RAZ Encrypt
+
+A local-first npm library for **two consenting parties** to sign documents, verify each other's signatures, and privately encrypt data for each other — with no server, no database, and no third-party account. Each party keeps their own identity and audit log in a small encrypted file on their own machine.
+
+Built around a **hybrid classical + post-quantum** cryptography design (see "Security posture" below) rather than any single algorithm.
+
+## How it works (the short version)
+
+1. Alice and Bob each call `createIdentity()` once. This generates their keys and stores them, encrypted, in a local folder.
+2. They exchange their **public cards** — just public keys, safe to send over email/Slack/whatever — and call `trustParty()` to record each other as trusted.
+3. From then on: Alice can `sign()` a document; Bob can `verify()` it against the certificate. Either of them can `encryptFor()` the other and `decryptFrom()` what they receive.
+
+Nothing here requires the two parties' computers to ever talk to each other directly — everything is exchanged "by hand" (file, email, chat), and each side's storage is entirely local and private to them.
+
+## Install
+
+```bash
+npm install raz-encrypt
+```
+
+## Upgrading from 1.x to 2.0
+
+2.0 closes every High and Medium finding from a security audit of 1.1.0. Most of it is invisible, but these changes need action from existing users:
+
+| Change | What you need to do |
+| --- | --- |
+| `trust.json` is now authenticated (HMAC) and an old one is **not read implicitly** | The first trust-list read throws `TrustStoreIntegrityError`. Check the file's entries are yours, then call `migrateLegacyTrustStore(identity)` once. |
+| The audit log is now MAC-chained with a key derived from your identity | An old `log.jsonl` fails `verifyLogIntegrity`. Move it aside (keep it as an archive); a new log starts clean. Deleting the most recent entries is now detected too, using a new `log.head.json`. |
+| `sign()` writes version-2 certificates (alias and `signedAt` are now signed) | Old certificates still verify. A v2 certificate does **not** verify on 1.x, so upgrade verifiers before signers. |
+| The live-session handshake (`raz-encrypt/core`) signs role, peer identities and a domain tag, and its key labels moved to `v3` | A 2.0 peer cannot complete a handshake with a 1.x peer, and there is no fallback. Upgrade both ends together. (Only matters if you use the session handshake and ratchet.) |
+| `encryptFor` boxes are now **version 2**: the key is bound to both parties and every public value, and the sender dual-signs the box. **1.x boxes are rejected.** | Decrypt anything you still need with 1.x first and re-encrypt it with 2.0. 2.0 and 1.x cannot read each other's boxes. Boxes now carry `id`, `signedAt` and `signature` and are about 9 KB larger. |
+| `identity.enc.json` moves to a versioned, authenticated format | Nothing: it upgrades itself on the first successful `loadIdentity`. Once upgraded, 1.x can't read it, so back the file up first if you may roll back. |
+
+Smaller behavior changes:
+
+- `canonicalize`/`hashDocument` are strict RFC 8785: values JSON can't represent (`undefined`, `NaN`, `Infinity`, `BigInt`, `Map`, `Set`, `Date`, typed arrays, class instances, lone surrogates, cycles) now throw `TypeError` instead of silently colliding. Convert them first (omit the key, or `date.toISOString()`). Output for valid documents is unchanged.
+- `verify()` returns `{ valid: false, reason: "malformed-certificate" }` for malformed certificates instead of throwing, and an invalid `expiresAt` is rejected by `sign()` and fails closed in `verify()`.
+- New identities need a passphrase that is normalized (Unicode NFKC), at least 12 characters, not one repeated character, and not a very common one. Existing passphrases keep working.
+- Storage directories created by the library are mode `0700`.
+
+New in 2.0: key-confirmation helpers (`makeKeyConfirmation`/`verifyKeyConfirmation`), role- and peer-bound handshake signatures, `untrustFingerprint`, `zeroizeIdentity`, a ratchet-caller guide (ADR 0013), CI, npm provenance releases and a [security policy](https://github.com/razmans/raz-encrypt/blob/main/SECURITY.md).
+
+## Quickstart
+
+```ts
+import {
+  createIdentity,
+  exportPublicIdentity,
+  trustParty,
+  sign,
+  verify,
+} from "raz-encrypt";
+
+// --- Alice, once ---
+const alice = await createIdentity({
+  storageDir: "./alice-store",
+  passphrase: "alice's secret passphrase",
+  alias: "alice",
+});
+const aliceCard = exportPublicIdentity(alice); // send this to Bob
+
+// --- Bob, once ---
+const bob = await createIdentity({
+  storageDir: "./bob-store",
+  passphrase: "bob's secret passphrase",
+  alias: "bob",
+});
+const bobCard = exportPublicIdentity(bob); // send this to Alice
+
+// --- Before trusting, compare fingerprints over a side channel (phone call, in person) ---
+// This is what catches a spoofed or intercepted card — email/chat alone can't prove
+// a card really came from the person you think it did.
+import { fingerprint } from "raz-encrypt";
+console.log("Alice reads this aloud:", fingerprint(aliceCard));
+console.log("Bob confirms it matches what he sees:", fingerprint(bobCard));
+
+// --- Both sides trust each other (after swapping cards AND confirming fingerprints) ---
+await trustParty(alice, bobCard);
+await trustParty(bob, aliceCard);
+
+// --- Alice signs a document ---
+const document = { invoiceId: "INV-1", amount: 15000 };
+const certificate = await sign(alice, document);
+
+// --- Bob verifies it (send him `document` + `certificate`) ---
+const result = await verify(bob, document, certificate);
+// => { valid: true }
+```
+
+If the document is changed even slightly, or the certificate is corrupted, or the signer was never trusted, `verify()` returns `{ valid: false, reason: "..." }` instead of throwing — so a caller always gets a clear, structured answer.
+
+### Private data between the two parties
+
+```ts
+import { encryptFor, decryptFrom } from "raz-encrypt";
+
+const box = await encryptFor(alice, bobCard, {
+  secretPayload: "only Bob should read this",
+});
+const opened = await decryptFrom(bob, aliceCard, box);
+```
+
+## Two important things people ask when actually wiring this up
+
+**1. `sign`/`verify` and `encryptFor`/`decryptFrom` are two separate, independent tools — not a pipeline.**
+
+- `sign` + `verify` prove **authenticity**: "this exact document really came from Alice and wasn't altered." The document itself travels in the clear.
+- `encryptFor` + `decryptFrom` provide **confidentiality**: "nobody but Bob can read this." Since 2.0 the box is also signed by the sender and bound to both parties, so Bob knows it came from Alice and was meant for him. That signature covers the box, not a separate document: use `sign`/`verify` when the document itself must be provable to a third party.
+
+You use whichever one (or both) fits what you're protecting against. You do **not** need to call `verify()` before you can call `decryptFrom()`, or vice versa — neither depends on the other. If you want both (a document that's both proven-authentic _and_ private), sign it, then encrypt the `{ document, certificate }` pair together — see the worked example below.
+
+**2. A "card" (from `exportPublicIdentity`) is just a JSON object.** However Alice actually gets it to Bob — email attachment, Slack message, QR code, USB stick — Bob ends up with the same plain JSON on disk. Loading it back is nothing more than reading that file and `JSON.parse`-ing it; there's no special "import" step.
+
+## Full example: Bob receives something from Alice
+
+Assume Bob has already run `createIdentity()` once (so he has his own `storageDir` + passphrase) and already has `alice-card.json` — the file Alice sent him after she ran `exportPublicIdentity()` on her side.
+
+```ts
+import { readFile } from "node:fs/promises";
+import {
+  loadIdentity,
+  decryptFrom,
+  verify,
+  type PublicCard,
+  type Certificate,
+} from "raz-encrypt";
+
+// Step 1 — Bob loads his own identity (needs his own passphrase, not Alice's).
+const bob = await loadIdentity({
+  storageDir: "./bob-store",
+  passphrase: "bob's secret passphrase",
+});
+
+// Step 2 — Bob loads Alice's card. It's just JSON — read whatever file/message it arrived in.
+const aliceCard: PublicCard = JSON.parse(
+  await readFile("./alice-card.json", "utf8"),
+);
+// (One-time only: before the first exchange, Bob must also have called
+//  trustParty(bob, aliceCard) once — otherwise decryptFrom/verify will refuse Alice's card.)
+
+// --- If what Alice sent was ENCRYPTED (confidential) ---
+const box = JSON.parse(await readFile("./received-box.json", "utf8"));
+const opened = await decryptFrom(bob, aliceCard, box);
+
+// --- If what Alice sent was SIGNED (a document + a certificate, sent in the clear) ---
+const { document, certificate } = JSON.parse(
+  await readFile("./signed-doc.json", "utf8"),
+) as {
+  document: unknown;
+  certificate: Certificate;
+};
+const result = await verify(bob, document, certificate);
+// => { valid: true } or { valid: false, reason: "..." }
+
+// --- If Alice sent something both signed AND encrypted ---
+// She encrypted { document, certificate } as one payload with encryptFor(); Bob does:
+const openedSignedPayload = await decryptFrom<{
+  document: unknown;
+  certificate: Certificate;
+}>(bob, aliceCard, box);
+const combinedResult = await verify(
+  bob,
+  openedSignedPayload.document,
+  openedSignedPayload.certificate,
+);
+```
+
+**So, to directly answer "do I need to run verify first?"** — no. `verify()` is only relevant when Alice actually signed something; `decryptFrom()` is only relevant when Alice actually encrypted something. Run whichever one matches what you received, in either order, or both if she did both.
+
+## Example scenarios
+
+A few concrete situations this library is built for, beyond the single-document walkthrough above.
+
+**1. Signing a legal document that must expire.** A contract, a power of attorney, anything with a validity window:
+
+```ts
+const certificate = await sign(alice, contractDocument, {
+  expiresAt: new Date("2027-01-01T00:00:00.000Z").toISOString(),
+});
+// ... time passes ...
+const result = await verify(bob, contractDocument, certificate);
+// => { valid: false, reason: "expired" } once 2027-01-01 has passed
+```
+
+**2. Private, authenticated messaging between two known parties.** Encrypt and sign together so the recipient knows both "only I can read this" and "this provably came from Alice":
+
+```ts
+const certificate = await sign(alice, { message: "Transfer approved" });
+const box = await encryptFor(alice, bobCard, { document: { message: "Transfer approved" }, certificate });
+const opened = await decryptFrom<{ document: unknown; certificate: Certificate }>(bob, aliceCard, box);
+const result = await verify(bob, opened.document, opened.certificate);
+```
+
+**3. A compliance-driven deployment that needs confidentiality at rest, not just tamper-evidence.** Call both migration functions once, right after `createIdentity` (or at any later point — see "Encrypting the trust store and audit log" below), before anything sensitive accumulates:
+
+```ts
+const alice = await createIdentity({ storageDir, passphrase, alias: "alice" });
+await migrateTrustStoreToEncrypted(alice);
+await migrateAuditLogToEncrypted(alice);
+// From here on, trust.json and every new log entry are encrypted, not just authenticated.
+```
+
+**4. Auditing an identity's history after the fact (encrypted or not).** `readLog`/`verifyLogIntegrity` work identically either way — the caller never needs to know which format is on disk:
+
+```ts
+const entries = await readLog(alice); // transparently decrypts if migrateAuditLogToEncrypted was called
+const integrity = await verifyLogIntegrity(alice);
+if (!integrity.intact) {
+  console.error("Audit log was tampered with or truncated:", integrity);
+}
+```
+
+**5. Revoking trust after a suspected compromise, then telling everyone.** Combine `untrustFingerprint` (stop trusting a specific card locally) with a portable revocation notice (tell every peer who ever trusted you, independent of this library's local state):
+
+```ts
+await untrustFingerprint(bob, fingerprint(compromisedCard));
+const notice = await createRevocationNotice(alice, { reason: "Suspected device compromise" });
+// Send `notice` to everyone who has ever trusted alice's card — each of them runs:
+await applyRevocationNotice(someoneElse, notice);
+```
+
+**6. Rotating to a new key pair without losing existing peers' trust.** A dual-signed handoff — both the old and new key must agree — so a compromised old key alone can't redirect anyone's trust:
+
+```ts
+const newAlice = await createIdentity({ storageDir: "./alice-store-v2", passphrase, alias: "alice" });
+const draft = await beginRotation(alice, exportPublicIdentity(newAlice));
+const statement = await completeRotation(newAlice, draft);
+// Send `statement` to every peer who trusts the old card; each runs:
+await applyRotation(bob, statement);
+```
+
+**7. An ephemeral, confirmed live session instead of one-shot documents/boxes** (chat, a real-time channel) — see "Live sessions" below for the full `ConfirmedSession` walkthrough.
+
+## API
+
+| Function                                                                                      | What it does                                                                                                                                                                                                      |
+| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createIdentity({ storageDir, passphrase, alias, overwrite?, checkPassphrase? })`             | Generates a new identity (see "Security posture") and persists it encrypted at `storageDir`. Passphrase is normalized (Unicode NFKC), must be at least `MIN_PASSPHRASE_LENGTH` (12) characters, not one repeated character, and not a very common passphrase. Optional `checkPassphrase(normalized)` runs after those checks — see below. |
+| `loadIdentity({ storageDir, passphrase })`                                                    | Loads a previously-created identity back from disk.                                                                                                                                                               |
+| `loadIdentityFromKeyStore({ alias, storageDir, keyStore })`                                   | Builds an identity from a caller-supplied `KeyStore` (`{ load() }`) instead of `identity.enc.json`/a passphrase. Key sourcing only — see "Security posture" and ADR 0024 for what this does and doesn't mean.    |
+| `zeroizeIdentity(identity)`                                                                   | Best-effort wipe of the identity's secret key bytes in memory when you're done with it (the identity is unusable afterwards).                                                                                      |
+| `exportPublicIdentity(identity)`                                                              | Returns the shareable public card `{ alias, classicalPublicKey, pqcSignPublicKey, pqcKemPublicKey }`.                                                                                                             |
+| `fingerprint(card)`                                                                           | Short, human-comparable fingerprint of a public card (grouped hex). Compare this over a side channel before trusting a card you received over email/chat.                                                         |
+| `trustParty(identity, card)`                                                                  | Records another party's public card as trusted, locally. Re-trusting a previously revoked card reinstates it.                                                                                                     |
+| `untrustParty(identity, alias)`                                                               | Revokes every currently-trusted card under `alias` (e.g. after a suspected key compromise). Tombstoned, not deleted — `verify()` reports `"revoked-signer"` distinctly from `"untrusted-signer"` (never trusted). |
+| `listTrustedParties(identity)` / `getTrustedParty(identity, alias)`                           | Read back your local trust list (revoked cards excluded).                                                                                                                                                         |
+| `getTrustedPartiesByAlias(identity, alias)` / `getTrustRecordsByAlias(identity, alias)`       | Since alias isn't unique, these return _every_ card under an alias — the latter includes revoked ones, with their `revokedAt`.                                                                                    |
+| `listTrustRecords(identity)`                                                                  | Full trust history, revoked included — for audit purposes.                                                                                                                                                        |
+| `sign(identity, document, options?)`                                                          | Canonicalizes and hashes `document`, signs it with both keys, returns a `Certificate`. Pass `{ expiresAt }` (ISO timestamp) to make it expire; omit it for a permanent proof (the default).                       |
+| `verify(identity, document, certificate)`                                                     | Checks the certificate's signer is trusted (and not revoked), the document hasn't changed, it hasn't expired, and both signatures check out.                                                                      |
+| `encryptFor(identity, counterpartCard, data)` / `decryptFrom(identity, counterpartCard, box)` | Encrypt/decrypt data meant only for one specific counterpart. Both throw `UntrustedPartyError` unless that counterpart is already in your local trust list (`trustParty`).                                        |
+| `untrustFingerprint(identity, fingerprint)`                                                   | Revokes exactly one card by its `fingerprint(card)` string (case/spacing ignored); other cards sharing the alias stay trusted. Returns `false` if no such trusted card exists.                                    |
+| `migrateLegacyTrustStore(identity)`                                                           | One-time adoption of an unauthenticated `trust.json` from an earlier version. Review the file first; returns how many records were adopted. See "Upgrading the trust store" below.                                |
+| `migrateTrustStoreToEncrypted(identity)`                                                      | One-time, explicit opt-in that encrypts `trust.json`'s entries (not just authenticates them). No-op if already encrypted. See "Encrypting the trust store and audit log" below.                                   |
+| `migrateAuditLogToEncrypted(identity)`                                                        | One-time, explicit opt-in that encrypts every audit-log entry's content (not just authenticates it); every `appendLogEntry` call afterwards encrypts only the new entry. No-op if already encrypted.               |
+| `exportSignedCard(identity, options?)` / `trustSignedCard(identity, card, certificate)`       | A self-signed, optionally-expiring version of your card (`{ expiresAt? }`), and verifying/trusting one you received. Enforces a cryptoperiod a bare card has no way to carry. See ADR 0023.                       |
+| `beginRotation(oldIdentity, newCard)` / `completeRotation(newIdentity, draft)` / `applyRotation(identity, statement)` | A dual-signed statement handing trust from an old card to a new one — both parties must sign, so a compromised old key alone can't redirect trust. Applying a valid statement moves trust automatically; no-ops for a card you never trusted. |
+| `createRevocationNotice(identity, options?)` / `applyRevocationNotice(identity, notice)`      | A self-signed, portable revocation notice any peer can verify independently — generate one right after `createIdentity` and store it separately for recovery if the identity later becomes inaccessible. No-ops for a card you never trusted. |
+| `readLog(identity)`                                                                           | Reads the local, append-only audit log of everything this identity has signed/verified/encrypted/decrypted.                                                                                                       |
+| `verifyLogIntegrity(identity)`                                                                | Walks the log's keyed (HMAC) chain and reports `{ intact: true }` or `{ intact: false, brokenAtIndex, reason? }` — detects an edited or deleted entry, and removal of the newest entries (`reason: "truncated"`), including by someone with file access but not your keys. Cannot detect both files being rolled back together, or deleted outright; keep an off-box copy of `log.head.json` if that matters. |
+| `canonicalize(value)` / `hashDocument(value)`                                                 | RFC 8785 (JCS) canonical JSON and its SHA-512 hash, used internally. Throws `TypeError` for anything JSON can't represent faithfully (`undefined`, `NaN`/`Infinity`, `BigInt`, `Map`/`Set`/`Date`/typed arrays/class instances, lone surrogates, cycles) instead of silently collapsing it.                                                                                                    |
+
+### Checking a passphrase against a real breach corpus
+
+`createIdentity`'s own blocklist is deliberately small — "a floor, not a strength meter," per its own comment. NIST SP 800-63B expects checking against a *large* corpus of known-compromised passphrases, which this library doesn't ship (and doesn't make network calls to check, either — see ADR 0021). Plug in a real checker yourself via `checkPassphrase`, which runs after the built-in checks and gets the already-normalized passphrase:
+
+```ts
+import zxcvbn from "zxcvbn"; // or an offline top-N list, or your own HIBP k-anonymity call
+
+await createIdentity({
+  storageDir,
+  passphrase,
+  alias: "alice",
+  checkPassphrase: (normalized) => {
+    if (zxcvbn(normalized).score < 3) {
+      throw new Error("Passphrase is too weak — choose something harder to guess.");
+    }
+  },
+});
+```
+
+Throw to reject the passphrase with your own message; return normally to accept it. An async function (returning a `Promise`) works too — `createIdentity` awaits it.
+
+### Live sessions (`raz-encrypt/core`) — key confirmation is a required step
+
+`createResponderHandshake`, `establishSessionInitiator` and `establishSessionResponder` return a `confirmationKey` alongside the session keys. A completed handshake is **not** proof the peer derived the same secrets until you confirm it — and nothing stops you from skipping that step entirely if you build on the low-level pieces directly. `ConfirmedSession` closes that gap: it won't let you `seal` or `open` anything until confirmation has actually succeeded in both directions.
+
+```ts
+const session = new ConfirmedSession("initiator", result, transcript); // or "responder"
+// ...send session.ownConfirmationTag to the peer, receive `theirTag` back...
+if (!session.confirmPeer(theirTag)) {
+  /* close the connection: the peer didn't prove it derived the same secrets */
+}
+const frame = session.seal(bytes, aad?);   // throws UnconfirmedSessionError before confirmPeer succeeds
+const plain = session.open(frame, aad?);   // same — both directions are gated
+session.destroy();                         // wipe the copied keys when the session ends
+```
+
+`transcript` is `{ initiatorCard, responderCard, responderMessage, initiatorMessage }`. `ConfirmedSession` performs no network I/O itself — you still transport `ownConfirmationTag` (and the handshake messages before it) however you already do; it only decides when `seal`/`open` are allowed to run. See ADR 0025.
+
+**Advanced use: the low-level pieces, if you need to skip the gate.** `makeKeyConfirmation(confirmationKey, role, transcript)` / `verifyKeyConfirmation(confirmationKey, counterpartRole, transcript, tag)` are role-bound (your own tag can't be reflected back at you), compare in constant time, and `verifyKeyConfirmation` returns `false` instead of throwing for malformed input. `createFrameChannels(result.keys, role)` returns the underlying `{ sender, receiver }` pair directly — `sender.seal`/`receiver.open` own the AES-GCM counter so a (key, counter) pair is never reused (AES-GCM is catastrophically weak if one ever is): create one sender per key, never a second for the same key; the receiver only advances after a frame authenticates, so forged frames can't move it; counter problems throw `FrameCounterError`, bad ciphertext throws `FrameDecryptionError`. `ConfirmedSession` is built from exactly these two functions — reach for them directly only if you specifically need to manage confirmation yourself.
+
+### Upgrading the trust store (`trust.json`)
+
+`trust.json` now carries an HMAC keyed from your identity's secret keys, so an edited, truncated or copied file is detected: everything that reads the trust list (`verify`, `encryptFor`, `decryptFrom`, `listTrustedParties`, ...) throws `TrustStoreIntegrityError` instead of using it.
+
+A `trust.json` written by an earlier version has no MAC, so it is **not** read implicitly (an attacker could otherwise plant one). The first call throws an error pointing at `migrateLegacyTrustStore(identity)`. Check the file's entries are yours, then call it once; it keeps your records (and revocations) and rewrites the file authenticated. A fresh identity needs nothing.
+
+### Encrypting the trust store and audit log
+
+By default, `trust.json` and `log.jsonl` are **authenticated but not encrypted** — an edit is detected, but anyone with filesystem read access (no passphrase, no knowledge of your identity's secrets) can still read who you trust and what you've done. If that confidentiality matters for your deployment (shared hosting, a backed-up disk image, a compliance requirement), opt in once per store:
+
+```ts
+import { loadIdentity, migrateTrustStoreToEncrypted, migrateAuditLogToEncrypted } from "raz-encrypt";
+
+const alice = await loadIdentity({ storageDir: "./alice-store", passphrase: "alice's secret passphrase" });
+
+// One-time opt-in, per store. Safe to call on a brand-new identity (nothing
+// to migrate yet) or an established one (every existing record/entry is
+// re-encrypted in that one call).
+await migrateTrustStoreToEncrypted(alice);
+await migrateAuditLogToEncrypted(alice);
+
+// Everything else is unchanged — trustParty, sign, verify, encryptFor,
+// decryptFrom, readLog, verifyLogIntegrity all keep working exactly as
+// before; trust.json and new log entries are now written encrypted.
+```
+
+Both encryption keys are derived from your identity's own secret keys (the same HKDF approach already used for the existing integrity MACs) — never from your passphrase, since these calls never receive one. The existing tamper/deletion detection (the MAC chain and `log.head.json`'s head record) keeps working exactly as before; encryption only adds confidentiality on top of it, it doesn't replace it. Calling either migration function a second time is a safe no-op. See ADR 0027 and [docs/adr/0027-encrypted-trust-store-and-audit-log.md](docs/adr/0027-encrypted-trust-store-and-audit-log.md).
+
+## Security posture
+
+**Is this "military grade"?** It uses the same algorithms — ECDSA/ECDH on curve P-384, AES-256 — that banks, governments, and CNSA-1.0-compliant systems use. The math is the real thing, not a toy. What it is **not** is FIPS 140-2/3 (CMVP) validated: that's a certification of one specific software build/deployment, done by an accredited lab, and it takes years — no realistic npm library ships with that certification. Not being certified doesn't mean it's unsafe: it's the difference between a home-cooked meal made with the exact same top-shelf ingredients a certified restaurant uses, versus the restaurant's official health-inspection paperwork. The ingredients and technique are what make it safe; the certificate just proves it to a third party who requires that paperwork (e.g. a specific government/defense procurement rule). If your use case legally _requires_ FIPS-validated modules, this library's logic needs to run inside a validated HSM/crypto boundary — that's a deployment decision outside what any library's code can provide on its own. The test suite includes known-answer vectors proving this library's own wiring of each primitive matches the standard (ADR 0022) — conformance evidence, not a substitute for that certification.
+
+One specific gap worth naming: the identity file's passphrase-derived key uses **scrypt**, which is not the KDF NIST SP 800-132 names (that's PBKDF2). Scrypt was kept anyway because it's memory-hard — a real defense against GPU/ASIC password-cracking that PBKDF2 doesn't have — but if your use case specifically requires an SP 800-132-compliant KDF, this library doesn't offer one yet.
+
+**Is this quantum-safe?** Half of the design is built specifically for that. **ML-KEM-1024** (key exchange) and **ML-DSA-87** (signatures) are NIST's official post-quantum standards (FIPS 203 / FIPS 204, finalized 2024), chosen because classical ECC and RSA can eventually be broken by a large enough quantum computer via Shor's algorithm. We don't rely on the post-quantum algorithms _alone_, though — they're only a few years old, with far less real-world cryptanalysis behind them than P-384. So every signature and every shared secret in this library requires **both** the classical layer and the post-quantum layer to hold:
+
+- **Signing**: every document is signed twice — once with ECDSA-P384, once with ML-DSA-87. `verify()` only returns `valid: true` if **both** signatures check out.
+- **Encryption**: the AES-256-GCM key is derived (via HKDF-SHA384) from **both** an ECDH-P384 exchange and an ML-KEM-1024 encapsulation.
+
+If one layer is ever broken — classical by a quantum computer, or the newer post-quantum standard by an as-yet-undiscovered flaw — the other still protects you.
+
+**Bottom line:** this is genuinely strong, real-world-grade cryptography built from carefully audited, widely used components (the [`@noble/*`](https://github.com/paulmillr/noble-post-quantum) libraries) — not a marketing label. It just isn't a government-certified module, and true safety also depends on this specific implementation being built and tested carefully, which is exactly what the test suite's "try to break it" cases (tampered documents, corrupted individual signatures) are for.
+
+**What `sign`/`verify` guarantees, precisely.** Every field that affects a verification outcome — the document hash _and_ the optional `expiresAt` — is part of the signed payload, not just `documentHash` alone. That matters because certificates travel over the exact same untrusted channels (email, chat) this library assumes for everything else: without that, an intermediary with no secret key at all could delete or rewrite `expiresAt` in transit and flip a `verify()` result, which would quietly defeat the whole point of setting an expiry.
+
+**Two honest limitations, so you can decide if they matter for your use case:**
+
+- **No forward secrecy.** `encryptFor`/`decryptFrom` derive their key from _long-term_ keys on both sides: a static ECDH-P384 exchange (deterministic for a given pair of identities) combined with an ML-KEM-1024 encapsulation whose secret still requires the recipient's long-term KEM secret key to decapsulate. Both of those secret keys live in the same `identity.enc.json`. This means that if someone ever recovers your passphrase and that file, they can decrypt **every box anyone ever sent you**, not just future ones — there's no per-message ephemeral key rotation (the kind Signal-style ratcheting provides). Rotate identities (new `storageDir`, `trustParty()` again) if you need to bound the blast radius of a future key compromise.
+- **Replay protection is opt-in.** Every box has a unique `id` and a signed `signedAt`. The library does not remember boxes, so pass `decryptFrom(bob, aliceCard, box, { isReplay })` with a function that returns `true` for an `id` you have already seen (it is called only after the signature verifies, and a `true` throws `ReplayedBoxError`). Without it, a valid box decrypts every time it is replayed.
+
+**Backup and recovery.** There is no password-reset flow: losing your passphrase or `identity.enc.json` loses the identity, permanently. Two things actually help:
+
+- **Back up `identity.enc.json` itself** (encrypted, so a copied file alone is not enough to compromise you) somewhere separate from the machine it lives on — and back up the passphrase separately from the file, the same way you'd handle any other secret.
+- **Generate a revocation notice immediately after `createIdentity`, before you ever share your card with anyone, and store it separately from the identity** — `createRevocationNotice(identity)`. It's a self-signed, portable statement any peer can verify independently (`applyRevocationNotice`), and it works exactly the same whether you use it the day you made it or years later. This is the only thing that gives you a way out if the identity itself later becomes completely inaccessible: you can't "recover" a lost identity, but you can tell everyone who ever trusted it to stop. See `exportSignedCard`/`trustSignedCard` (self-signed, optionally expiring cards) and `beginRotation`/`completeRotation`/`applyRotation` (a dual-signed handoff from an old card to a new one, so peers' trust moves automatically) for the rest of the key-lifecycle API — see ADR 0023.
+
+**`KeyStore`: where your keys come from, not how operations are performed.** `loadIdentityFromKeyStore` lets you source secret-key material from an OS keychain or similar instead of `identity.enc.json`/a passphrase — but once loaded, this library still operates on the raw key bytes directly in its own process memory, exactly like a file-loaded identity. There is no way to make this library forward a signing or key-exchange operation *to* a device so the private key never leaves it — that's a different, much larger feature (every crypto call site would need to become a pluggable remote operation), and it's only partially possible today regardless: no commodity HSM or TPM implements ML-DSA-87 or ML-KEM-1024 yet, so even a "real" hardware-backed identity could only ever cover the classical half. A `KeyStore` backed by an OS keychain that hands back raw bytes to your authorized process is a reasonable, honest use of this interface; wrapping an actual HSM in one, where the whole point is that the key *can't* be extracted, isn't — see ADR 0024.
+
+## Standards this library aims to align with
+
+**None of the following is a certification or an independent audit finding.** This section lists the public standards and specifications whose guidance this library's design and a standards-alignment self-review were checked against — all effort has gone into aligning with them, but nothing here has been independently verified by an accredited lab, a formal certification body, or a third-party review. Treat it as "built with these in mind," not "certified to these."
+
+| Area | Standard / reference | How this library relates to it |
+| --- | --- | --- |
+| Post-quantum signatures | NIST FIPS 204 (ML-DSA) | Every document/certificate is signed with ML-DSA-87 alongside the classical signature; `verify()` requires both. |
+| Post-quantum key exchange | NIST FIPS 203 (ML-KEM) | Every session/box key derivation includes an ML-KEM-1024 encapsulation alongside the classical ECDH exchange. |
+| Key establishment | NIST SP 800-56A | The hybrid (classical + post-quantum) handshake's key-derivation structure follows this family's conventions for authenticated key establishment. |
+| Key derivation / domain separation | NIST SP 800-56C | Every HKDF-derived key in this library (MAC keys, head-MAC keys, and the new encryption keys from issue #43/ADR 0027) uses its own dedicated info label, so independent uses of the same base secret never share derived key material. |
+| Memorized secret (passphrase) guidance | NIST SP 800-63B | `createIdentity`'s passphrase policy (minimum length, rejecting trivial/common values) follows this standard's spirit; `checkPassphrase` lets a caller plug in a real breach-corpus check, which this library doesn't ship itself (ADR 0021). |
+| Password-based key derivation | NIST SP 800-132 | `identity.enc.json` is encrypted under a passphrase-derived key via **scrypt** rather than the PBKDF2 this standard names — a deliberate, documented deviation for scrypt's memory-hardness (see "Security posture" above). |
+| Key management / mutual authentication | ISO/IEC 11770-3 | The session handshake's key-confirmation step (`ConfirmedSession`, `makeKeyConfirmation`/`verifyKeyConfirmation`) follows this standard's model for proving both sides derived the same key before trusting a channel. |
+| Non-invasive attack resistance (timing) | ISO/IEC 17825, FIPS 140-3 (non-invasive attacks) | Every MAC/tag comparison in this library (trust store, audit log, key confirmation) uses a constant-time compare; `test/timingSafety.test.ts` fuzzes and statistically checks this (issue #42/ADR 0026). JavaScript cannot guarantee constant time the way a lower-level language can — this is evidence of due diligence, not a hard guarantee. |
+| Use of cryptography | ISO/IEC 27002:2022, control 8.24 | The optional encryption for `trust.json` and the audit log (issue #43/ADR 0027) exists specifically to close the gap this control calls out: authenticated is not the same as confidential. |
+| Data classification | OWASP ASVS V6.1 | Same gap as above — "who you trust" and "what you did" are classified as confidential, not just integrity-protected, data. |
+| Stored cryptography | OWASP ASVS V6 | `identity.enc.json`, `trust.json`, and the audit log are all encrypted-at-rest options built from reviewed primitives (the `@noble/*` libraries), never a custom cipher. |
+| Input validation / fuzzing | OWASP ASVS V5 | Every parser that touches externally-controlled or persisted input (canonical-JSON, handshake-message shape validators, the trust-store and audit-log parsers, identity-file deserialization) is fuzz-tested with `fast-check` to prove it fails closed on malformed input instead of crashing (issue #42/ADR 0026). |
+| Canonical JSON | RFC 8785 (JSON Canonicalization Scheme) | `canonicalize()`/`hashDocument()` implement JCS exactly, strictly rejecting anything JSON cannot represent faithfully rather than silently colliding two different documents onto the same hash. |
+| National algorithm suite | CNSA 1.0 | The classical layer (ECDSA/ECDH on P-384, AES-256) uses the same algorithm choices CNSA-1.0-compliant systems use (see "Security posture"). |
+| Conformance evidence | NIST/ISO known-answer test vectors | The test suite includes known-answer vectors cross-checked against the standards, proving this library's own wiring of each primitive matches the specification (ADR 0022) — conformance evidence, not a substitute for FIPS 140-2/3 (CMVP) module validation, which this library does not have. |
+
+For the honest limits of all of the above — no independent cryptographic review of the custom handshake/ratchet, no forward secrecy for `encryptFor`/`decryptFrom`, no FIPS-validated module — see "Security posture", "Independent review status", and "Threat model and non-goals" below.
+
+## Independent review status
+
+The session handshake and ratchet are custom compositions of well-known primitives. **They have not been independently reviewed or formally modelled.** Do not rely on them for high-stakes use until they have been. [docs/security-review-brief.md](docs/security-review-brief.md) sets out the protocol, the claims, the assumptions and the known limits for a reviewer. Also note that `encryptFor`/`decryptFrom` have no forward secrecy.
+
+## Threat model and non-goals
+
+**What it defends against**
+
+- A passive or active network attacker who can read, replay, reorder, drop or modify handshake and session traffic: both parties are authenticated with dual (classical + post-quantum) signatures, session keys are ephemeral, and frames are authenticated with strict counters.
+- "Harvest now, decrypt later": every secret needs both the classical and the post-quantum layer to be broken.
+- Someone who steals your files but not your passphrase: `identity.enc.json` is encrypted (scrypt + AES-256-GCM), `trust.json` and the audit log are authenticated with keys derived from your identity, so edits are detected.
+- A counterpart you never added to your trust list: `verify`, `encryptFor` and `decryptFrom` refuse them.
+
+**What it does not defend against**
+
+- Malware or an attacker running as you on an unlocked machine: if they have your decrypted identity, they are you. `zeroizeIdentity` shortens the window; it is not a secure-erase.
+- A wrong card: the library cannot tell that a card you were handed belongs to the person you think it does. Compare `fingerprint(card)` over a separate channel before `trustParty`.
+- A weak passphrase: the policy is a floor (length, no trivial or very common values). An offline attacker with your `identity.enc.json` can guess against it at scrypt speed.
+- Traffic analysis, endpoint compromise, side channels (timing, cache, power) beyond what the underlying `@noble/*` libraries provide, and denial of service by someone who can corrupt your storage directory.
+- Forward secrecy for `encryptFor`/`decryptFrom` (see above); use the session handshake and ratchet for live traffic.
+
+**Status of the cryptography**
+
+The primitives are standard (NIST P-384, ML-DSA-87, ML-KEM-1024, AES-256-GCM, HKDF-SHA384, scrypt) and come from the `@noble/*` libraries, which are pinned to exact versions here. `@noble/post-quantum` is still 0.x. The handshake and ratchet are custom compositions of those primitives and have **not** had an independent cryptographic review or formal analysis; weigh that before relying on them for high-stakes use. Report problems privately, see [SECURITY.md](https://github.com/razmans/raz-encrypt/blob/main/SECURITY.md).
+
+## What this library deliberately does _not_ do
+
+- No server, no HTTP API, no database — everything is local files.
+- No live network sync between the two parties' machines — public cards, documents, and certificates are exchanged "by hand" (file/email/etc.), not automatically.
+- No multi-party or hierarchical signing (buyers/vendors/approval-levels/etc.) — this is a generic building block for exactly two parties trusting each other directly.
+- **Node.js only, not a browser library.** The underlying `@noble/*` crypto libraries are isomorphic and would run fine in a browser, but the storage layer (`identity.enc.json`, `trust.json`, `log.jsonl`) is built on `node:fs`, which browsers don't have. There's no IndexedDB (or similar) storage adapter — if you need this in a browser, that adapter would need to be built.
+
+## Local storage layout
+
+Each identity's `storageDir` contains:
+
+```
+identity.enc.json   # your keys, encrypted at rest under your passphrase (AES-256-GCM, scrypt-derived key; versioned, KDF cost stored in the file, written atomically)
+trust.json          # fingerprint-keyed public cards of parties you've trusted (or revoked), with an integrity MAC — always authenticated; encrypted too once you call migrateTrustStoreToEncrypted
+log.jsonl           # append-only audit log, MAC-chained with a key derived from your identity: what you've signed/verified/encrypted/decrypted, and when — encrypted per entry once you call migrateAuditLogToEncrypted
+log.head.json       # authenticated entry count and last MAC, so deleting the newest log entries is detected
+```
+
+Identity files written by earlier versions (no `version` field) still load with the same passphrase, and are upgraded to the current format automatically on the first successful `loadIdentity`. If that upgrade can't be written (read-only directory, full disk) the identity still loads and the original file is left untouched. A file from a *newer* raz-encrypt rejects with `UnsupportedFileVersionError`.
+
+New storage directories are created with mode `0700` (an existing directory's mode is never changed). `sign()` now writes version-2 certificates whose signatures also cover `signer.alias` and `signedAt`; certificates from earlier releases (no `version`) still verify, but a v2 certificate is not verifiable by an older release.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## Keywords
+
+Post-quantum cryptography, hybrid classical and post-quantum encryption, ML-KEM-1024, ML-DSA-87, FIPS 203, FIPS 204, CRYSTALS-Kyber, CRYSTALS-Dilithium, ECDSA P-384, ECDH P-384, AES-256-GCM, HKDF-SHA384, scrypt key derivation, quantum-safe digital signatures, quantum-resistant key exchange, harvest-now-decrypt-later defense, local-first identity library, Node.js cryptography library, document signing and verification, end-to-end encrypted messaging between two parties, encrypted audit log, encrypted trust store, tamper-evident MAC chain, constant-time comparison, timing side-channel resistance, ISO/IEC 17825, FIPS 140-3 non-invasive attacks, NIST SP 800-56A key establishment, NIST SP 800-56C key derivation, NIST SP 800-63B passphrase policy, NIST SP 800-132 password-based key derivation, ISO/IEC 11770-3 key management, ISO/IEC 27002 8.24 use of cryptography, OWASP ASVS V5 input validation, OWASP ASVS V6 stored cryptography, OWASP ASVS V6.1 data classification, RFC 8785 JSON Canonicalization Scheme, CNSA 1.0, known-answer test vectors, fuzz testing with fast-check, property-based testing, key confirmation, forward secrecy limitations, key rotation and revocation, self-signed card expiry, no server no database npm package.