quantum-resistant-rustykey 0.7.8 → 0.8.0

package/README.md

@@ -14,12 +14,10 @@ npm i quantum-resistant-rustykey
 
 - ***Recommendation***: Await v1.0.0 (following security audit) for production/regulated deployment.
 - includes NIST approved as well as riskier NIST 'on-ramp' variants eg SQISign
-- *signature algorithms:*
-  - *FN-DSA (Falcon-512, Falcon-1024)*
-  - *ML-DSA (Dilithium variants)*
-  - *SQISign*
-- module-lattice-based key-encapsulation mechanism
-  - **ML-KEM-512**, **ML-KEM-768**, and **ML-KEM-1024** using the same stack: [mlkem-native](https://github.com/pq-code-package/mlkem-native) built with **Emscripten**.
+- **ML-DSA** (ML-DSA-65, ML-DSA-87)
+- **FN-DSA** (FN-DSA-512, FN-DSA-1024)
+- **SQIsign** (Level 1)
+- **ML-KEM** (512, 768, 1024) using [mlkem-native](https://github.com/pq-code-package/mlkem-native).
 
 ### NOTE: Why we support SQISign when it is 'NIST-on-ramp' only
 *TLDR; to help hurdle the "silent" barrier to post-quantum adoption: 1024-byte buffer limit in many existing FIDO2/WebAuthn implementations*
@@ -249,16 +247,41 @@ pnpm build
 
 - Run `pnpm test` for ML-KEM-512 / 768 / 1024 round-trips.
 
-## Browser example (local)
+### Digital Signatures (Node.js & Frontend)
 
-A Vite app under `examples/browser-demo` links this package from the workspace. From the repo root:
+All signature algorithms (**FN-DSA**, **ML-DSA**, and **SQIsign**) share a common interface.
 
-```bash
-pnpm build
-pnpm example:browser
+```typescript
+import { 
+  loadFnDsa512, 
+  loadMlDsa3, 
+  loadSqisignLvl1 
+} from "quantum-resistant-rustykey";
+
+async function main() {
+  // 1. Load the algorithm (e.g., FN-DSA-512)
+  const fnDsa = await loadFnDsa512();
+
+  // 2. Generate a keypair
+  const kp = fnDsa.keypair();
+  const publicKey = await kp.get("public_key");
+  const privateKey = await kp.get("private_key");
+
+  // 3. Sign a message
+  const message = "Authored by RustyKey";
+  const signature = await fnDsa.sign(message, privateKey);
+  console.log("Signature (hex):", fnDsa.buffer_to_string(signature));
+
+  // 4. Verify the signature
+  const isValid = await fnDsa.verify(signature, message, publicKey);
+  console.log("Is signature valid?", isValid);
+}
 ```
 
-See `examples/browser-demo/README.md` for details.
+> [!NOTE]
+> **SQIsign Performance**: Level 1 signing is extremely CPU-intensive (can take seconds to minutes depending on hardware). It is recommended for "sign-once, verify-many" scenarios like certificates or firmware updates.
+
+## Browser example (local)
 
 ## Project Structure
 
@@ -279,6 +302,42 @@ This implementation includes patches to withstand side-channel attacks. For more
 
 ISC
 
+
+## Performance Metrics
+
+Measured on a standard development environment (Node.js/WASM). Individual results may vary based on hardware and runtime overhead.
+
+| Algorithm | KeyGen (ms) | Sign (ms) | Verify (ms) |
+| :--- | :---: | :---: | :---: |
+| **FN-DSA-512** | 8.13 | 0.74 | 0.78 |
+| **FN-DSA-1024** | 25.62 | 1.25 | 0.24 |
+| **ML-DSA-3 (Level 3)** | 0.22 | 0.45 | 0.25 |
+| **ML-DSA-5 (Level 5)** | 0.33 | 0.63 | 0.34 |
+| **SQIsign L1** | 99.95 | 534.41 | 15.35 |
+
+---
+
+## Known Answer Tests (KAT)
+
+To ensure implementation correctness, our WASM build is verified against official NIST and reference test vectors.
+
+### ML-DSA-3 (Level 3 / Dilithium-3)
+*   **Msg**: `6dbbc4375136df3b07f7c70e639e223e`
+*   **PK**: `e50d03fff3b3a70961abbb92a390008dec1283f603f50cdbaaa3d00bd659bc767c3f...`
+*   **Sig**: `a0c1af32f9ba4e4beea3016b96d1c780e8b5e020bb07c24478dbdd0ec875666b5a...`
+
+### ML-DSA-5 (Level 5 / Dilithium-5)
+*   **Msg**: `6dbbc4375136df3b07f7c70e639e223e`
+*   **PK**: `bc89b367d4288f47c71a74679d0fcffbe041de41b5da2f5fc66d8e28c589949404...`
+*   **Sig**: `47dc5764266841c1af3073fcead6a13d372979e6cca0b2952b349915f54ef66312...`
+
+### SQIsign Level 1
+*   **Msg**: `d81c4d8d734fcbfbeade3d3f8a039faa2a2c9957e835ad55b22e75bf57bb556ac8`
+*   **PK**: `07CCD21425136F6E865E497D2D4D208F0054AD81372066E817480787AAF7B2029...`
+*   **Sig**: `84228651f271b0f39f2f19f2e8718f31ed3365ac9e5cb303afe663d0cfc11f0455...`
+
+*Full byte-perfect vectors are included in the `src/*.test.ts` files.*
+
 ## Funding
 
 This project was generously supported by:
@@ -303,3 +362,18 @@ This project was generously supported by:
 - people have differences of opinion, usually every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer.
 - go light on unstructured critique, encourage others!
 - if you feel you have been or are being harassed or made uncomfortable by a community member, contact BuzzyBee® our friendly multi-LLM on the chat widget on our testbed site
+
+## Appendix (WIP) testbed 'coming soon' features
+
+Below our some examples of stats and interactivity we plan to add to the testbed depending on user-interest that will help users understand the trade-offs between lattice-based (ML-KEM/DSA) and isogeny-based (SQISign) crypto:
+
+- Memory Peak (Heap Usage): WASM runs in a linear memory space. Tracking performance.memory.usedJSHeapSize (in supported browsers) or monitoring the WASM instance’s memory growth is vital, especially for ML-DSA (Dilithium), which can be memory-intensive.
+
+- Serialized Payload Size: Explicitly display the "Over-the-wire" size for public keys and signatures. Seeing a 204-byte SQISign signature next to a 2,420-byte Dilithium-2 signature makes the WebAuthn buffer issue immediately obvious.
+
+- WASM Instantiation Time: Measure how long it takes to compile and initialize the module. This is a "hidden" latency cost in web apps that users often overlook.
+
+- Interactive "Live Insight" Buttons
+  - "Simulate CTAP2 Limit": A toggle that "clips" the buffer at 1024 bytes. If the user tries to run Dilithium, it throws a visual error, while SQISign passes—demonstrating that "silent barrier" they mentioned
+  - "Throttle CPU": An option to simulate mobile/embedded performance (standard in Chrome DevTools, but great as a one-click button). This highlights how SQISign is great for size but potentially slower on verification time compared to Falcon or Dilithium.
+  - "Batch Verification Run": A button to run 100 signatures in a loop. This generates a jitter chart to show if the Montgomery constant-time implementation stays flat or fluctuates under load

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantum-resistant-rustykey",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "description": "WebAssembly post-quantum-resistant tools for web",
   "author": "Antony R Mott <a@auditcanary.com> (https://rustykey.app)",
   "license": "ISC",