@theqrl/dilithium5 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,154 @@
-# `@theqrl/dilithium5`
+# @theqrl/dilithium5
 
-> TODO: description
+Post-quantum digital signatures using CRYSTALS-Dilithium Round 3.
 
-## Usage
+This package implements the Dilithium5 signature scheme at NIST security level 5 (AES-256 equivalent). It's designed for compatibility with [go-qrllib](https://github.com/theQRL/go-qrllib) and existing QRL infrastructure.
 
-``` js
-import { cryptoSign, cryptoSignKeypair, cryptoSignOpen, cryptoSignVerify, cryptoSignSignature } from '@theqrl/dilithium5';
+## Installation
 
-// TODO: DEMONSTRATE API
+```bash
+npm install @theqrl/dilithium5
 ```
+
+## Quick Start
+
+```javascript
+import {
+  cryptoSignKeypair,
+  cryptoSign,
+  cryptoSignOpen,
+  CryptoPublicKeyBytes,
+  CryptoSecretKeyBytes,
+} from '@theqrl/dilithium5';
+
+// 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
+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!"
+```
+
+## API
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `CryptoPublicKeyBytes` | 2592 | Public key size in bytes |
+| `CryptoSecretKeyBytes` | 4896 | Secret key size in bytes |
+| `CryptoBytes` | 4595 | 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)`
+
+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
+- Returns: `Uint8Array` containing signature + message
+
+#### `cryptoSignOpen(signedMessage, pk)`
+
+Verify and extract message from signed message.
+
+- `signedMessage`: `Uint8Array` - output from `cryptoSign()`
+- `pk`: `Uint8Array(2592)` - public key
+- Returns: Original message if valid, `undefined` if verification fails
+
+#### `cryptoSignSignature(sig, message, sk, randomized)`
+
+Create a detached signature.
+
+- `sig`: `Uint8Array(4595)` - output buffer for signature
+- `message`: `Uint8Array` - message to sign
+- `sk`: `Uint8Array(4896)` - secret key
+- `randomized`: `boolean` - `true` for hedged, `false` for deterministic
+- Returns: `0` on success
+
+#### `cryptoSignVerify(sig, message, pk)`
+
+Verify a detached signature.
+
+- `sig`: `Uint8Array(4595)` - signature to verify
+- `message`: `Uint8Array` - original message
+- `pk`: `Uint8Array(2592)` - public key
+- 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 with go-qrllib
+
+go-qrllib pre-hashes seeds with SHAKE256 before key generation. To generate matching keys:
+
+```javascript
+import { shake256 } from '@noble/hashes/sha3';
+
+// go-qrllib: hashedSeed = SHAKE256(rawSeed)[:32]
+const hashedSeed = shake256(rawSeed, { dkLen: 32 });
+
+// Use hashedSeed (not rawSeed) with this library
+cryptoSignKeypair(hashedSeed, pk, sk);
+```
+
+## Dilithium5 vs ML-DSA-87
+
+| Feature | Dilithium5 | ML-DSA-87 |
+|---------|------------|-----------|
+| Standard | CRYSTALS Round 3 | FIPS 204 |
+| Signature size | 4595 bytes | 4627 bytes |
+| Context parameter | Not supported | Supported |
+| Use case | go-qrllib compatibility | New implementations |
+
+For new projects, consider using [@theqrl/mldsa87](https://www.npmjs.com/package/@theqrl/mldsa87) which implements the FIPS 204 standard.
+
+## 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)
+- [go-qrllib](https://github.com/theQRL/go-qrllib) - Go implementation
+- [CRYSTALS-Dilithium](https://pq-crystals.org/dilithium/) - Original specification
+- [QRL Website](https://theqrl.org)

package/dist/cjs/dilithium5.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;
@@ -85,7 +85,7 @@ class KeccakState {
 // SHAKE-128 functions
 
 function shake128Init(state) {
-  state.hasher = sha3.shake128.create({});
+  state.hasher = sha3_js.shake128.create({});
   state.finalized = false;
 }
 
@@ -107,7 +107,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;
 }
 
@@ -1081,7 +1081,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
   const seed = passedSeed || randomBytes(SeedBytes);
 
   const outputLength = 2 * SeedBytes + CRHBytes;
-  const seedBuf = sha3.shake256.create({}).update(seed).xof(outputLength);
+  const seedBuf = sha3_js.shake256.create({}).update(seed).xof(outputLength);
   const rho = seedBuf.slice(0, SeedBytes);
   const rhoPrime = seedBuf.slice(SeedBytes, SeedBytes + CRHBytes);
   const key = seedBuf.slice(SeedBytes + CRHBytes);
@@ -1110,7 +1110,7 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
   packPk(pk, rho, t1);
 
   // Compute H(rho, t1) 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;
@@ -1160,12 +1160,12 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
 
   // Convert hex message to bytes
   const mBytes = typeof m === 'string' ? hexToBytes(m) : m;
-  const mu = sha3.shake256.create({}).update(tr).update(mBytes).xof(CRHBytes);
+  const mu = sha3_js.shake256.create({}).update(tr).update(mBytes).xof(CRHBytes);
 
   if (randomizedSigning) {
     rhoPrime = new Uint8Array(randomBytes(CRHBytes));
   } else {
-    rhoPrime = sha3.shake256.create({}).update(key).update(mu).xof(CRHBytes);
+    rhoPrime = sha3_js.shake256.create({}).update(key).update(mu).xof(CRHBytes);
   }
 
   polyVecMatrixExpand(mat, rho);
@@ -1187,7 +1187,7 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
     polyVecKDecompose(w1, w0, w1);
     polyVecKPackW1(sig, w1);
 
-    const cHash = sha3.shake256
+    const cHash = sha3_js.shake256
       .create({})
       .update(mu)
       .update(sig.slice(0, K * PolyW1PackedBytes))
@@ -1308,12 +1308,12 @@ function cryptoSignVerify(sig, m, pk) {
   }
 
   /* Compute CRH(H(rho, t1), msg) */
-  const tr = sha3.shake256.create({}).update(pk).xof(TRBytes);
+  const tr = sha3_js.shake256.create({}).update(pk).xof(TRBytes);
   mu.set(tr);
 
   // Convert hex message to bytes
   const mBytes = typeof m === 'string' ? hexToBytes(m) : m;
-  const muFull = sha3.shake256.create({}).update(mu.slice(0, TRBytes)).update(mBytes).xof(CRHBytes);
+  const muFull = sha3_js.shake256.create({}).update(mu.slice(0, TRBytes)).update(mBytes).xof(CRHBytes);
   mu.set(muFull);
 
   /* Matrix-vector multiplication; compute Az - c2^dt1 */
@@ -1338,7 +1338,7 @@ function cryptoSignVerify(sig, m, pk) {
   polyVecKPackW1(buf, w1);
 
   /* Call random oracle and verify challenge */
-  const c2Hash = sha3.shake256.create({}).update(mu).update(buf).xof(SeedBytes);
+  const c2Hash = sha3_js.shake256.create({}).update(mu).update(buf).xof(SeedBytes);
   c2.set(c2Hash);
 
   // Constant-time comparison to prevent timing attacks

package/dist/mjs/dilithium5.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/dilithium5",
-  "version": "0.2.0",
+  "version": "1.0.4",
   "description": "Dilithium-5 cryptography",
   "keywords": [
     "dilithium",
@@ -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/dilithium5.js",
+  "module": "dist/mjs/dilithium5.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';