raz-encrypt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 razmans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# 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.
+
+## Hands-on demo
+
+The `demo/` folder is a runnable version of the quickstart above, playing Alice and Bob as two separate local identities:
+
+```bash
+npm run demo:setup   # creates both identities, swaps public cards, records trust
+npm run demo:sign    # Alice signs demo/sample-document.json
+npm run demo:verify  # Bob verifies it -> { valid: true }
+npm run demo:tamper  # Bob verifies a modified copy -> { valid: false, reason: "hash-mismatch" }
+npm run demo:verify  # run again fresh -> proves identity/trust really persisted to disk, not just in memory
+npm run demo:clean   # removes the generated local stores/cards so you can start over
+```
+
+## 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
+```

package/dist/canonicalJson.d.ts

@@ -0,0 +1,3 @@
+export declare function canonicalize(value: unknown): string;
+/** The document hash every signature is made over. */
+export declare function hashDocument(value: unknown): string;

package/dist/canonicalJson.js

@@ -0,0 +1,25 @@
+import { sha512 } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+/**
+ * Deterministic JSON serialization (object keys sorted recursively) so the
+ * same logical document always hashes to the same value regardless of key
+ * order on the wire.
+ */
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, sortKeysDeep(value[key])]));
+    }
+    return value;
+}
+export function canonicalize(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+/** The document hash every signature is made over. */
+export function hashDocument(value) {
+    return bytesToHex(sha512(utf8ToBytes(canonicalize(value))));
+}
+//# sourceMappingURL=canonicalJson.js.map

package/dist/canonicalJson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalJson.js","sourceRoot":"","sources":["../src/canonicalJson.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC;aAC1C,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser-safe crypto surface: everything from the hybrid classical+PQC
+ * layer, with zero `node:fs` dependency — nothing here touches
+ * identity.enc.json, trust.json, or log.jsonl.
+ *
+ * The four crypto operations take an explicit trust/log dependency instead
+ * of a persisted identity/trust store, so any caller (a browser, a
+ * different storage backend, tests) can supply its own. The top-level `"."`
+ * export's `sign`/`verify`/`encryptFor`/`decryptFrom` remain the batteries-
+ * included, fs-backed versions of the same logic — this module is the
+ * un-wired core they're built from, not a separate implementation.
+ */
+export { decryptFromCore as decryptFrom, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
+export type { Certificate, EncryptedBox, InitiatorSessionResult, LogDeps, SessionKeys, SignOptions, TrustDeps, TrustStatus, VerifyDeps, VerifyFailureReason, VerifyResult, } from "./crypto/hybrid.js";
+export { generateClassicalKeypair, classicalSharedSecret, classicalSign, classicalVerify } from "./crypto/classical.js";
+export type { ClassicalKeypair } from "./crypto/classical.js";
+export { generatePqcKemKeypair, generatePqcSignKeypair, pqcDecapsulate, pqcEncapsulate, pqcSign, pqcVerify, } from "./crypto/pqc.js";
+export type { PqcKemKeypair, PqcSignKeypair } from "./crypto/pqc.js";
+export { canonicalize, hashDocument } from "./canonicalJson.js";
+export { fingerprint } from "./fingerprint.js";
+export { decryptFrame, encryptFrame, FrameDecryptionError } from "./crypto/frameCipher.js";
+export type { EncryptedFrame } from "./crypto/frameCipher.js";
+export type { Identity, PublicCard } from "./identity.js";

package/dist/core.js

@@ -0,0 +1,19 @@
+/**
+ * Browser-safe crypto surface: everything from the hybrid classical+PQC
+ * layer, with zero `node:fs` dependency — nothing here touches
+ * identity.enc.json, trust.json, or log.jsonl.
+ *
+ * The four crypto operations take an explicit trust/log dependency instead
+ * of a persisted identity/trust store, so any caller (a browser, a
+ * different storage backend, tests) can supply its own. The top-level `"."`
+ * export's `sign`/`verify`/`encryptFor`/`decryptFrom` remain the batteries-
+ * included, fs-backed versions of the same logic — this module is the
+ * un-wired core they're built from, not a separate implementation.
+ */
+export { decryptFromCore as decryptFrom, encryptForCore as encryptFor, establishSessionInitiatorCore as establishSessionInitiator, establishSessionResponderCore as establishSessionResponder, signCore as sign, UntrustedPartyError, verifyCore as verify, } from "./crypto/hybrid.js";
+export { generateClassicalKeypair, classicalSharedSecret, classicalSign, classicalVerify } from "./crypto/classical.js";
+export { generatePqcKemKeypair, generatePqcSignKeypair, pqcDecapsulate, pqcEncapsulate, pqcSign, pqcVerify, } from "./crypto/pqc.js";
+export { canonicalize, hashDocument } from "./canonicalJson.js";
+export { fingerprint } from "./fingerprint.js";
+export { decryptFrame, encryptFrame, FrameDecryptionError } from "./crypto/frameCipher.js";
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,eAAe,IAAI,WAAW,EAC9B,cAAc,IAAI,UAAU,EAC5B,6BAA6B,IAAI,yBAAyB,EAC1D,6BAA6B,IAAI,yBAAyB,EAC1D,QAAQ,IAAI,IAAI,EAChB,mBAAmB,EACnB,UAAU,IAAI,MAAM,GACrB,MAAM,oBAAoB,CAAC;AAe5B,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,OAAO,EACP,SAAS,GACV,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/crypto/classical.d.ts

@@ -0,0 +1,10 @@
+export interface ClassicalKeypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/** ECDSA/ECDH on NIST P-384 — the classical, CNSA-1.0-eligible layer. */
+export declare function generateClassicalKeypair(): ClassicalKeypair;
+export declare function classicalSign(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+export declare function classicalVerify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+/** ECDH shared secret between our secret key and their public key. */
+export declare function classicalSharedSecret(secretKey: Uint8Array, theirPublicKey: Uint8Array): Uint8Array;

package/dist/crypto/classical.js

@@ -0,0 +1,21 @@
+import { p384 } from "@noble/curves/nist.js";
+/** ECDSA/ECDH on NIST P-384 — the classical, CNSA-1.0-eligible layer. */
+export function generateClassicalKeypair() {
+    return p384.keygen();
+}
+export function classicalSign(message, secretKey) {
+    return p384.sign(message, secretKey);
+}
+export function classicalVerify(signature, message, publicKey) {
+    try {
+        return p384.verify(signature, message, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/** ECDH shared secret between our secret key and their public key. */
+export function classicalSharedSecret(secretKey, theirPublicKey) {
+    return p384.getSharedSecret(secretKey, theirPublicKey);
+}
+//# sourceMappingURL=classical.js.map

package/dist/crypto/classical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classical.js","sourceRoot":"","sources":["../../src/crypto/classical.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAO7C,yEAAyE;AACzE,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAmB,EAAE,SAAqB;IACtE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,SAAqB,EAAE,OAAmB,EAAE,SAAqB;IAC/F,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,qBAAqB,CAAC,SAAqB,EAAE,cAA0B;IACrF,OAAO,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AACzD,CAAC"}

package/dist/crypto/frameCipher.d.ts

@@ -0,0 +1,23 @@
+export declare class FrameDecryptionError extends Error {
+    constructor();
+}
+export interface EncryptedFrame {
+    /** The nonce input, transmitted alongside the ciphertext — see Q9 in the session design: explicit, not implicit. */
+    counter: number;
+    /** Hex-encoded AES-256-GCM output (ciphertext with the auth tag appended). */
+    ciphertext: string;
+}
+/**
+ * Encrypts one frame of `plaintext` under `key` (one of the two directional
+ * keys from establishSessionInitiatorCore/establishSessionResponderCore) at
+ * `counter`. The caller owns counter bookkeeping: increment it once per
+ * frame sent under this key, one counter sequence per direction, and never
+ * reuse a value.
+ */
+export declare function encryptFrame(key: Uint8Array, counter: number, plaintext: Uint8Array): EncryptedFrame;
+/**
+ * Decrypts a frame produced by encryptFrame. Fails closed — throws
+ * FrameDecryptionError — on a tampered ciphertext, a mismatched counter, or
+ * the wrong directional key, rather than ever returning corrupted plaintext.
+ */
+export declare function decryptFrame(key: Uint8Array, frame: EncryptedFrame): Uint8Array;

package/dist/crypto/frameCipher.js

@@ -0,0 +1,58 @@
+import { gcm } from "@noble/ciphers/aes.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+// The per-frame AEAD used to wrap every message sent under a session key
+// established by establishSessionInitiatorCore/establishSessionResponderCore
+// (see hybrid.ts) — one directional key, reused across many frames, so the
+// nonce can never repeat under that key or AES-GCM's security fails. Nonces
+// here are the caller-supplied `counter`, never random and never derived
+// implicitly from delivery order: the caller (one per direction) increments
+// it once per frame and MUST NEVER reuse a counter value under the same key
+// — reusing one is a silent security failure, not something this module can
+// detect, since a stateless encrypt call has no memory of counters it's
+// already used.
+const NONCE_LENGTH = 12;
+const COUNTER_BYTES = 8;
+export class FrameDecryptionError extends Error {
+    constructor() {
+        super("Failed to decrypt frame: wrong key, wrong counter, or the frame was tampered with in transit.");
+        this.name = "FrameDecryptionError";
+    }
+}
+/** Encodes `counter` as a 96-bit nonce: 4 zero bytes + an 8-byte big-endian counter (2^64 frames is far beyond any realistic session). */
+function counterToNonce(counter) {
+    if (!Number.isInteger(counter) || counter < 0) {
+        throw new Error(`Frame counter must be a non-negative integer, got ${counter}.`);
+    }
+    const nonce = new Uint8Array(NONCE_LENGTH);
+    let value = BigInt(counter);
+    for (let i = NONCE_LENGTH - 1; i >= NONCE_LENGTH - COUNTER_BYTES; i--) {
+        nonce[i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    return nonce;
+}
+/**
+ * Encrypts one frame of `plaintext` under `key` (one of the two directional
+ * keys from establishSessionInitiatorCore/establishSessionResponderCore) at
+ * `counter`. The caller owns counter bookkeeping: increment it once per
+ * frame sent under this key, one counter sequence per direction, and never
+ * reuse a value.
+ */
+export function encryptFrame(key, counter, plaintext) {
+    const ciphertext = gcm(key, counterToNonce(counter)).encrypt(plaintext);
+    return { counter, ciphertext: bytesToHex(ciphertext) };
+}
+/**
+ * Decrypts a frame produced by encryptFrame. Fails closed — throws
+ * FrameDecryptionError — on a tampered ciphertext, a mismatched counter, or
+ * the wrong directional key, rather than ever returning corrupted plaintext.
+ */
+export function decryptFrame(key, frame) {
+    try {
+        return gcm(key, counterToNonce(frame.counter)).decrypt(hexToBytes(frame.ciphertext));
+    }
+    catch {
+        throw new FrameDecryptionError();
+    }
+}
+//# sourceMappingURL=frameCipher.js.map

package/dist/crypto/frameCipher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frameCipher.js","sourceRoot":"","sources":["../../src/crypto/frameCipher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEhE,yEAAyE;AACzE,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,wEAAwE;AACxE,gBAAgB;AAEhB,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;QACE,KAAK,CAAC,+FAA+F,CAAC,CAAC;QACvG,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AASD,0IAA0I;AAC1I,SAAS,cAAc,CAAC,OAAe;IACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,qDAAqD,OAAO,GAAG,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC,IAAI,YAAY,GAAG,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;QACtE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;QACjC,KAAK,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,OAAe,EAAE,SAAqB;IAClF,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,KAAqB;IACjE,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,oBAAoB,EAAE,CAAC;IACnC,CAAC;AACH,CAAC"}

package/dist/crypto/hybrid.d.ts

@@ -0,0 +1,117 @@
+import type { Identity, PublicCard } from "../identity.js";
+import type { LogEntry } from "../store.js";
+declare const ALGORITHMS: {
+    readonly classical: "ECDSA-P384";
+    readonly pqc: "ML-DSA-87";
+};
+export declare class UntrustedPartyError extends Error {
+    constructor(alias: string);
+}
+export interface Certificate {
+    documentHash: string;
+    classicalSignature: string;
+    pqcSignature: string;
+    algorithms: typeof ALGORITHMS;
+    signer: {
+        alias: string;
+        classicalPublicKey: string;
+        pqcSignPublicKey: string;
+    };
+    signedAt: string;
+    /** Absent = permanent proof, valid indefinitely (the default, unchanged behavior). */
+    expiresAt?: string;
+}
+export interface SignOptions {
+    /** If set, verify() rejects this certificate as "expired" once this ISO timestamp has passed. */
+    expiresAt?: string;
+}
+export type VerifyFailureReason = "untrusted-signer" | "revoked-signer" | "hash-mismatch" | "classical-signature-mismatch" | "pqc-signature-mismatch" | "expired";
+export type VerifyResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: VerifyFailureReason;
+};
+export type TrustStatus = "trusted" | "revoked" | "untrusted";
+/** Injectable audit-log hook, shared by every *Core function. Omit to log nothing. */
+export interface LogDeps {
+    onLog?: (entry: Omit<LogEntry, "at">) => void | Promise<void>;
+}
+/**
+ * verifyCore's trust dependency. Matches only the fields a Certificate's
+ * signer actually carries (no KEM key — signing never uses it), same as
+ * verify()'s own matching always did.
+ */
+export interface VerifyDeps extends LogDeps {
+    checkTrust: (signer: {
+        alias: string;
+        classicalPublicKey: string;
+        pqcSignPublicKey: string;
+    }) => Promise<TrustStatus>;
+}
+/** encryptForCore/decryptFromCore's trust dependency — matches the full PublicCard, KEM key included. */
+export interface TrustDeps extends LogDeps {
+    checkTrust: (card: PublicCard) => Promise<TrustStatus>;
+}
+/**
+ * Signs `document` with both the classical (ECDSA-P384) and post-quantum
+ * (ML-DSA-87) keys. Permanent by default; pass `options.expiresAt` to make
+ * verify() reject it once that time has passed. Takes no trust dependency —
+ * signing never checks anyone else's trust status, only your own keys.
+ */
+export declare function signCore(identity: Identity, document: unknown, options?: SignOptions, deps?: LogDeps): Promise<Certificate>;
+/**
+ * Verifies `certificate` over `document` using an injected trust check
+ * (`deps.checkTrust`) instead of a hard-wired trust store. Requires BOTH the
+ * classical and post-quantum signatures to check out — either one failing
+ * fails the whole verification.
+ */
+export declare function verifyCore(identity: Identity, document: unknown, certificate: Certificate, deps: VerifyDeps): Promise<VerifyResult>;
+export interface EncryptedBox {
+    kemCipherText: string;
+    nonce: string;
+    ciphertext: string;
+}
+/**
+ * Encrypts `data` for `counterpart` using a symmetric key derived from BOTH
+ * an ECDH-P384 exchange and an ML-KEM-1024 encapsulation (HKDF-SHA384
+ * combines the two secrets), then AES-256-GCM. Throws UntrustedPartyError
+ * unless `deps.checkTrust(counterpart)` reports "trusted".
+ */
+export declare function encryptForCore(identity: Identity, counterpart: PublicCard, data: unknown, deps: TrustDeps): Promise<EncryptedBox>;
+/**
+ * Decrypts a box produced by `encryptFor`. `counterpart` is the sender's
+ * public card. Throws UntrustedPartyError unless `deps.checkTrust(counterpart)`
+ * reports "trusted" — this stops a caller from accidentally decrypting "as
+ * if" a message came from someone they never actually trusted.
+ */
+export declare function decryptFromCore<T = unknown>(identity: Identity, counterpart: PublicCard, box: EncryptedBox, deps: TrustDeps): Promise<T>;
+export interface SessionKeys {
+    /** AES-256-GCM key for frames sent by the initiator (the side that encapsulated), decrypted by the responder. */
+    initiatorToResponder: Uint8Array;
+    /** AES-256-GCM key for frames sent by the responder (the side that decapsulated), decrypted by the initiator. */
+    responderToInitiator: Uint8Array;
+}
+export interface InitiatorSessionResult {
+    /** Send this to the responder — the only message this handshake requires; the ECDH half needs no message since both sides derive it locally from already-exchanged Public Cards. */
+    kemCipherText: string;
+    keys: SessionKeys;
+}
+/**
+ * Establishes a session as the connection's initiator (the side that
+ * created the WebRTC offer, in raz-encrypt-agnostic terms: whichever side
+ * owns the single ML-KEM encapsulation this handshake performs). Computes
+ * the ECDH-P384 secret with `counterpart` and one ML-KEM-1024 encapsulation
+ * toward their KEM public key, then HKDF-splits the combined secret into two
+ * directional AES-256-GCM keys. No trust dependency: establishing a session
+ * never checks anyone's trust status, same as signCore.
+ */
+export declare function establishSessionInitiatorCore(identity: Identity, counterpart: PublicCard): InitiatorSessionResult;
+/**
+ * Establishes a session as the connection's responder: computes the same
+ * ECDH-P384 secret, decapsulates the initiator's `kemCipherText` with our
+ * own KEM secret key, and derives the same two directional keys the
+ * initiator derived.
+ */
+export declare function establishSessionResponderCore(identity: Identity, counterpart: PublicCard, kemCipherText: string): SessionKeys;
+export {};