raz-encrypt 0.1.0 → 0.3.0

package/README.md

@@ -145,19 +145,6 @@ const combinedResult = await verify(
 
 **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                                                                                                                                                                                                      |
@@ -191,11 +178,11 @@ If one layer is ever broken — classical by a quantum computer, or the newer po
 
 **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.
+**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 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)

package/dist/crypto/frameCipher.d.ts

@@ -13,11 +13,20 @@ export interface EncryptedFrame {
  * `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.
+ *
+ * `aad` is optional Associated Authenticated Data: extra context (e.g.
+ * direction, frame/message type) bound into the AEAD tag but not encrypted.
+ * It is never transmitted as part of EncryptedFrame — the receiver must
+ * reconstruct the identical bytes out of band (from the frame's own
+ * metadata, e.g. its direction and type) and pass them to decryptFrame.
+ * Omitting it behaves exactly as before this parameter existed.
  */
-export declare function encryptFrame(key: Uint8Array, counter: number, plaintext: Uint8Array): EncryptedFrame;
+export declare function encryptFrame(key: Uint8Array, counter: number, plaintext: Uint8Array, aad?: 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.
+ * FrameDecryptionError — on a tampered ciphertext, a mismatched counter, the
+ * wrong directional key, or an `aad` that doesn't match what the sender used
+ * (including one side supplying `aad` and the other omitting it), rather
+ * than ever returning corrupted plaintext.
  */
-export declare function decryptFrame(key: Uint8Array, frame: EncryptedFrame): Uint8Array;
+export declare function decryptFrame(key: Uint8Array, frame: EncryptedFrame, aad?: Uint8Array): Uint8Array;

package/dist/crypto/frameCipher.js

@@ -37,19 +37,28 @@ function counterToNonce(counter) {
  * `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.
+ *
+ * `aad` is optional Associated Authenticated Data: extra context (e.g.
+ * direction, frame/message type) bound into the AEAD tag but not encrypted.
+ * It is never transmitted as part of EncryptedFrame — the receiver must
+ * reconstruct the identical bytes out of band (from the frame's own
+ * metadata, e.g. its direction and type) and pass them to decryptFrame.
+ * Omitting it behaves exactly as before this parameter existed.
  */
-export function encryptFrame(key, counter, plaintext) {
-    const ciphertext = gcm(key, counterToNonce(counter)).encrypt(plaintext);
+export function encryptFrame(key, counter, plaintext, aad) {
+    const ciphertext = gcm(key, counterToNonce(counter), aad).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.
+ * FrameDecryptionError — on a tampered ciphertext, a mismatched counter, the
+ * wrong directional key, or an `aad` that doesn't match what the sender used
+ * (including one side supplying `aad` and the other omitting it), rather
+ * than ever returning corrupted plaintext.
  */
-export function decryptFrame(key, frame) {
+export function decryptFrame(key, frame, aad) {
     try {
-        return gcm(key, counterToNonce(frame.counter)).decrypt(hexToBytes(frame.ciphertext));
+        return gcm(key, counterToNonce(frame.counter), aad).decrypt(hexToBytes(frame.ciphertext));
     }
     catch {
         throw new FrameDecryptionError();

package/dist/crypto/frameCipher.js.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,OAAe,EAAE,SAAqB,EAAE,GAAgB;IACpG,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAe,EAAE,KAAqB,EAAE,GAAgB;IACnF,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5F,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,oBAAoB,EAAE,CAAC;IACnC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raz-encrypt",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Local-first, hybrid classical+post-quantum signing and verification for two consenting parties. No server, no database required.",
   "license": "MIT",
   "type": "module",