@theqrl/mldsa87 0.2.0 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 The Quantum Resistant Ledger
+
+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

@@ -1,11 +1,172 @@
-# `@theqrl/mldsa87`
+# @theqrl/mldsa87
 
-> TODO: description
+Post-quantum digital signatures using ML-DSA-87 (FIPS 204).
 
-## Usage
+This package implements the ML-DSA-87 signature scheme at NIST security level 5 (AES-256 equivalent). It follows the [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final) standard and is recommended for new implementations.
 
-``` js
-import { cryptoSign, cryptoSignKeypair, cryptoSignOpen, cryptoSignVerify, cryptoSignSignature } from '@theqrl/mldsa87';
+## Installation
 
-// TODO: DEMONSTRATE API
+```bash
+npm install @theqrl/mldsa87
 ```
+
+## Quick Start
+
+```javascript
+import {
+  cryptoSignKeypair,
+  cryptoSign,
+  cryptoSignOpen,
+  CryptoPublicKeyBytes,
+  CryptoSecretKeyBytes,
+} from '@theqrl/mldsa87';
+
+// Generate keypair
+const pk = new Uint8Array(CryptoPublicKeyBytes);  // 2592 bytes
+const sk = new Uint8Array(CryptoSecretKeyBytes);  // 4896 bytes
+cryptoSignKeypair(null, pk, sk);  // null = random seed
+
+// Sign a message (uses default "ZOND" context)
+const message = new TextEncoder().encode('Hello, quantum world!');
+const signedMessage = cryptoSign(message, sk, false);  // false = deterministic
+
+// Verify and extract
+const extracted = cryptoSignOpen(signedMessage, pk);
+if (extracted === undefined) {
+  throw new Error('Invalid signature');
+}
+console.log(new TextDecoder().decode(extracted));  // "Hello, quantum world!"
+```
+
+## Context Parameter
+
+ML-DSA-87 supports a context parameter for domain separation (FIPS 204 feature). This allows the same keypair to be used safely across different applications.
+
+```javascript
+// With custom context
+const ctx = new TextEncoder().encode('my-app-v1');
+const signed = cryptoSign(message, sk, false, ctx);
+const extracted = cryptoSignOpen(signed, pk, ctx);
+
+// Context must match for verification
+cryptoSignOpen(signed, pk);  // undefined - wrong context (default "ZOND")
+cryptoSignOpen(signed, pk, ctx);  // message - correct context
+```
+
+The default context is `"ZOND"` (for QRL Zond network compatibility). Context can be 0-255 bytes.
+
+## API
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `CryptoPublicKeyBytes` | 2592 | Public key size in bytes |
+| `CryptoSecretKeyBytes` | 4896 | Secret key size in bytes |
+| `CryptoBytes` | 4627 | Signature size in bytes |
+| `SeedBytes` | 32 | Seed size for key generation |
+
+### Functions
+
+#### `cryptoSignKeypair(seed, pk, sk)`
+
+Generate a keypair from a seed.
+
+- `seed`: `Uint8Array(32)` or `null` for random
+- `pk`: `Uint8Array(2592)` - output buffer for public key
+- `sk`: `Uint8Array(4896)` - output buffer for secret key
+- Returns: The seed used (useful when `seed` is `null`)
+
+#### `cryptoSign(message, sk, randomized, context?)`
+
+Sign a message (combined mode: returns signature || message).
+
+- `message`: `Uint8Array` - message to sign
+- `sk`: `Uint8Array(4896)` - secret key
+- `randomized`: `boolean` - `true` for hedged signing, `false` for deterministic
+- `context`: `Uint8Array` (optional) - context string, 0-255 bytes. Default: `"ZOND"`
+- Returns: `Uint8Array` containing signature + message
+
+#### `cryptoSignOpen(signedMessage, pk, context?)`
+
+Verify and extract message from signed message.
+
+- `signedMessage`: `Uint8Array` - output from `cryptoSign()`
+- `pk`: `Uint8Array(2592)` - public key
+- `context`: `Uint8Array` (optional) - must match signing context
+- Returns: Original message if valid, `undefined` if verification fails
+
+#### `cryptoSignSignature(sig, message, sk, randomized, context?)`
+
+Create a detached signature.
+
+- `sig`: `Uint8Array(4627)` - output buffer for signature
+- `message`: `Uint8Array` - message to sign
+- `sk`: `Uint8Array(4896)` - secret key
+- `randomized`: `boolean` - `true` for hedged, `false` for deterministic
+- `context`: `Uint8Array` (optional) - context string, 0-255 bytes
+- Returns: `0` on success
+
+#### `cryptoSignVerify(sig, message, pk, context?)`
+
+Verify a detached signature.
+
+- `sig`: `Uint8Array(4627)` - signature to verify
+- `message`: `Uint8Array` - original message
+- `pk`: `Uint8Array(2592)` - public key
+- `context`: `Uint8Array` (optional) - must match signing context
+- Returns: `true` if valid, `false` otherwise
+
+#### `zeroize(buffer)`
+
+Zero out sensitive data (best-effort, see security notes).
+
+#### `isZero(buffer)`
+
+Check if buffer is all zeros (constant-time).
+
+## Interoperability
+
+Both this library and go-qrllib process ML-DSA-87 seeds identically. Raw seeds produce matching keys:
+
+```javascript
+// Same seed produces same keys in both implementations
+cryptoSignKeypair(seed, pk, sk);
+```
+
+Verified against the [pq-crystals reference implementation](https://github.com/pq-crystals/dilithium).
+
+## ML-DSA-87 vs Dilithium5
+
+| Feature | ML-DSA-87 | Dilithium5 |
+|---------|-----------|------------|
+| Standard | FIPS 204 | CRYSTALS Round 3 |
+| Signature size | 4627 bytes | 4595 bytes |
+| Context parameter | Supported | Not supported |
+| Use case | New implementations | go-qrllib compatibility |
+
+Use [@theqrl/dilithium5](https://www.npmjs.com/package/@theqrl/dilithium5) only if you need compatibility with existing QRL infrastructure.
+
+## Security
+
+See [SECURITY.md](../../SECURITY.md) for important information about:
+
+- JavaScript memory security limitations
+- Constant-time verification
+- Secure key handling recommendations
+
+## Requirements
+
+- Node.js 18+ or modern browsers with ES2020 support
+- Full TypeScript definitions included
+
+## License
+
+MIT
+
+## Links
+
+- [Main documentation](../../README.md)
+- [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final) - ML-DSA specification
+- [go-qrllib](https://github.com/theQRL/go-qrllib) - Go implementation
+- [QRL Website](https://theqrl.org)

package/dist/cjs/mldsa87.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var sha3 = require('@noble/hashes/sha3');
+var sha3_js = require('@noble/hashes/sha3.js');
 var pkg = require('randombytes');
 
 const Shake128Rate = 168;
@@ -87,7 +87,7 @@ class KeccakState {
 // SHAKE-128 functions
 
 function shake128Init(state) {
-  state.hasher = sha3.shake128.create({});
+  state.hasher = sha3_js.shake128.create({});
   state.finalized = false;
 }
 
@@ -109,7 +109,7 @@ function shake128SqueezeBlocks(out, outputOffset, nBlocks, state) {
 // SHAKE-256 functions
 
 function shake256Init(state) {
-  state.hasher = sha3.shake256.create({});
+  state.hasher = sha3_js.shake256.create({});
   state.finalized = false;
 }
 
@@ -1096,7 +1096,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
 
   const outputLength = 2 * SeedBytes + CRHBytes;
   const domainSep = new Uint8Array([K, L]);
-  const seedBuf = sha3.shake256.create({}).update(seed).update(domainSep).xof(outputLength);
+  const seedBuf = sha3_js.shake256.create({}).update(seed).update(domainSep).xof(outputLength);
   const rho = seedBuf.slice(0, SeedBytes);
   const rhoPrime = seedBuf.slice(SeedBytes, SeedBytes + CRHBytes);
   const key = seedBuf.slice(SeedBytes + CRHBytes);
@@ -1125,7 +1125,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
   packPk(pk, rho, t1);
 
   // Compute tr = SHAKE256(pk) (64 bytes) and write secret key
-  const tr = sha3.shake256.create({}).update(pk).xof(TRBytes);
+  const tr = sha3_js.shake256.create({}).update(pk).xof(TRBytes);
   packSk(sk, rho, tr, key, t0, s1, s2);
 
   return seed;
@@ -1189,11 +1189,11 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
   const mBytes = typeof m === 'string' ? hexToBytes(m) : m;
 
   // mu = SHAKE256(tr || pre || m)
-  const mu = sha3.shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
+  const mu = sha3_js.shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
 
   // rhoPrime = SHAKE256(key || rnd || mu)
   const rnd = randomizedSigning ? randomBytes(RNDBytes) : new Uint8Array(RNDBytes);
-  rhoPrime = sha3.shake256.create({}).update(key).update(rnd).update(mu).xof(CRHBytes);
+  rhoPrime = sha3_js.shake256.create({}).update(key).update(rnd).update(mu).xof(CRHBytes);
 
   polyVecMatrixExpand(mat, rho);
   polyVecLNTT(s1);
@@ -1215,7 +1215,7 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning, ctx = DEFAULT_CTX) {
     polyVecKPackW1(sig, w1);
 
     // ctilde = SHAKE256(mu || w1_packed) (64 bytes)
-    const ctilde = sha3.shake256
+    const ctilde = sha3_js.shake256
       .create({})
       .update(mu)
       .update(sig.slice(0, K * PolyW1PackedBytes))
@@ -1341,7 +1341,7 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
   }
 
   /* Compute mu = SHAKE256(tr || pre || m) with tr = SHAKE256(pk) */
-  const tr = sha3.shake256.create({}).update(pk).xof(TRBytes);
+  const tr = sha3_js.shake256.create({}).update(pk).xof(TRBytes);
 
   const pre = new Uint8Array(2 + ctx.length);
   pre[0] = 0;
@@ -1350,7 +1350,7 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
 
   // Convert hex message to bytes
   const mBytes = typeof m === 'string' ? hexToBytes(m) : m;
-  const muFull = sha3.shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
+  const muFull = sha3_js.shake256.create({}).update(tr).update(pre).update(mBytes).xof(CRHBytes);
   mu.set(muFull);
 
   /* Matrix-vector multiplication; compute Az - c2^dt1 */
@@ -1375,7 +1375,7 @@ function cryptoSignVerify(sig, m, pk, ctx = DEFAULT_CTX) {
   polyVecKPackW1(buf, w1);
 
   /* Call random oracle and verify challenge */
-  const c2Hash = sha3.shake256.create({}).update(mu).update(buf).xof(CTILDEBytes);
+  const c2Hash = sha3_js.shake256.create({}).update(mu).update(buf).xof(CTILDEBytes);
   c2.set(c2Hash);
 
   // Constant-time comparison to prevent timing attacks

package/dist/mjs/mldsa87.js

@@ -1,4 +1,4 @@
-import { shake128, shake256 } from '@noble/hashes/sha3';
+import { shake128, shake256 } from '@noble/hashes/sha3.js';
 import pkg from 'randombytes';
 
 const Shake128Rate = 168;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theqrl/mldsa87",
-  "version": "0.2.0",
+  "version": "1.0.4",
   "description": "ML-DSA-87 cryptography",
   "keywords": [
     "ml-dsa",
@@ -10,7 +10,8 @@
   "author": "QRL contributors <info@theqrl.org> (https://theqrl.org)",
   "homepage": "https://github.com/theQRL/qrypto.js#readme",
   "license": "MIT",
-  "main": "src/index.js",
+  "main": "dist/cjs/mldsa87.js",
+  "module": "dist/mjs/mldsa87.js",
   "types": "src/index.d.ts",
   "directories": {
     "lib": "src",
@@ -18,7 +19,9 @@
   },
   "files": [
     "dist",
-    "src/index.d.ts"
+    "src/index.d.ts",
+    "LICENSE",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -45,20 +48,20 @@
   },
   "type": "module",
   "devDependencies": {
-    "c8": "^9.1.0",
-    "chai": "^5.0.0",
-    "codecov": "^3.8.3",
-    "eslint": "^8.56.0",
-    "eslint-config-airbnb": "^19.0.4",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-prettier": "^5.1.3",
-    "mocha": "^10.2.0",
-    "prettier": "^3.2.4",
-    "rollup": "^4.9.5"
+    "@eslint/js": "^9.39.0",
+    "c8": "^10.1.3",
+    "chai": "^6.2.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import-x": "^4.15.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "globals": "^16.2.0",
+    "mocha": "^11.7.5",
+    "prettier": "^3.7.4",
+    "rollup": "^4.55.1"
   },
   "dependencies": {
-    "@noble/hashes": "^1.7.1",
+    "@noble/hashes": "^2.0.1",
     "randombytes": "^2.1.0"
   }
 }

package/src/index.js

@@ -1,11 +0,0 @@
-export * from './const.js';
-export * from './poly.js';
-export * from './polyvec.js';
-export * from './packing.js';
-export * from './reduce.js';
-export * from './rounding.js';
-export * from './symmetric-shake.js';
-export * from './ntt.js';
-export * from './fips202.js';
-export * from './sign.js';
-export * from './utils.js';