@kirkelliott/kdfts 1.1.1 → 2.0.1

package/README.md

@@ -3,9 +3,9 @@
 [![CI](https://github.com/dmvjs/kdfts/actions/workflows/ci.yml/badge.svg)](https://github.com/dmvjs/kdfts/actions/workflows/ci.yml)
 [![license](https://img.shields.io/github/license/dmvjs/kdfts)](LICENSE)
 
-If you're storing passwords or deriving secrets that must survive a server compromise, the salt is what attackers try to precompute. A stolen PRNG seed, a weak entropy source, or a future algorithm break can reconstruct every salt you've ever generated. `kdfts` removes that attack surface by sourcing salt from the [ANU Quantum Random Number Generator](https://quantumnumbers.anu.edu.au) — photon shot noise at a beam splitter. Those bytes were never produced by an algorithm. There is no state to steal.
+Argon2id KDF with optional quantum-backed salt provenance. Salt is sourced from the [ANU Quantum Random Number Generator](https://quantumnumbers.anu.edu.au) (photon shot noise at a beam splitter) when available, with `strict` mode for deployments where that provenance is required. Falls back to `crypto.getRandomValues()` otherwise.
 
-Falls back silently to `crypto.getRandomValues()` when the ANU API is unavailable.
+Standard CSPRNGs already satisfy OWASP's salt requirements. The ANU source adds auditable entropy provenance — useful for compliance workflows or systems that need to document their randomness chain, not a substitute for strong KDF parameters.
 
 ## Install
 
@@ -26,13 +26,12 @@ export ANU_API_KEY=your-key-here
 ```ts
 import { derive, formatCert } from '@kirkelliott/kdfts'
 
-const { key, salt, certificate } = await derive('my-password', {
+const { hash, certificate } = await derive('my-password', {
   context: 'myapp:user42:session',  // domain separation — optional but recommended
 })
 
-// Persist these — both are needed to verify later
-const persistedSalt = salt.toString('hex')
-const persistedKey  = key.toString('hex')
+// Persist this single string — it contains everything needed to verify later
+await db.users.update({ passwordHash: hash })
 
 console.log(formatCert(certificate))
 // ════════════════════════════════════════════════════
@@ -40,8 +39,8 @@ console.log(formatCert(certificate))
 // ════════════════════════════════════════════════════
 //   Source:        ANU Quantum Vacuum (photon shot noise)
 //   Timestamp:     2026-03-07T04:00:00.000Z
-//   KDF:           scrypt
-//   N / r / p:     16384 / 8 / 1
+//   KDF:           argon2id
+//   t / m / p:     3 / 65536 / 4
 //   Key length:    32 bytes (256 bits)
 //   Salt bytes:    32 bytes (256 bits)
 //   Context:       myapp:user42:session
@@ -56,12 +55,8 @@ console.log(formatCert(certificate))
 ```ts
 import { verify } from '@kirkelliott/kdfts'
 
-const salt = Buffer.from(persistedSalt, 'hex')
-const key  = Buffer.from(persistedKey, 'hex')
-
-const valid = await verify('my-password', salt, key, {
-  context: 'myapp:user42:session',
-})
+const valid = await verify('my-password', storedHash)
+// Parameters, salt, and context are all read from the hash string.
 ```
 
 **Reuse a source across multiple derivations** (saves one ANU round-trip):
@@ -82,18 +77,19 @@ const [keyA, keyB] = await Promise.all([
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `context` | `string` | — | Domain separation string. Mixed in as `password \|\| 0x00 \|\| context`. |
+| `context` | `string` | — | Domain separation string, passed as Argon2id `associatedData`. Embedded in the hash — no need to pass to `verify()`. |
 | `saltBytes` | `number` | `32` | Bytes of quantum entropy to fetch. |
 | `keyLength` | `number` | `32` | Output key length in bytes. |
-| `cost` | `{ N, r, p }` | `{ N: 16384, r: 8, p: 1 }` | scrypt parameters. Increase `N` for higher-value keys. |
+| `cost` | `{ timeCost, memoryCost, parallelism }` | `{ timeCost: 3, memoryCost: 65536, parallelism: 4 }` | Argon2id parameters. `memoryCost` is in KiB. Embedded in the hash — no need to track separately. |
+| `strict` | `boolean` | `false` | Throw if the ANU source is unavailable instead of falling back to `crypto.getRandomValues()`. |
 | `source` | `QuantumSource` | — | Pre-created source for reuse or testing. |
 
 ## Security notes
 
 - Salt is fetched fresh for every `derive` call — never reused
-- Context is domain-separated with a null byte: `password || 0x00 || context`
+- Context is passed as Argon2id `associatedData` and embedded in the hash — `verify()` reads it automatically
 - Verification uses `crypto.timingSafeEqual` — no timing oracle on key comparison
-- scrypt defaults (`N=16384, r=8, p=1`) follow [OWASP recommendations](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+- Argon2id defaults (`timeCost=3, memoryCost=65536, parallelism=4`) exceed [OWASP minimum recommendations](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
 - The certificate records only SHA-256 hashes of the salt and key, never the raw values
 - Every claim in this README is validated by the [test suite](https://github.com/dmvjs/kdfts/actions/workflows/ci.yml)
 

package/dist/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QuantumSource = exports.verify = exports.formatCert = exports.derive = void 0;
+exports.QuantumSource = exports.verify = exports.formatCert = exports.derive = exports.needsRehash = void 0;
+var argon2_1 = require("argon2");
+Object.defineProperty(exports, "needsRehash", { enumerable: true, get: function () { return argon2_1.needsRehash; } });
 var kdf_1 = require("./kdf");
 Object.defineProperty(exports, "derive", { enumerable: true, get: function () { return kdf_1.derive; } });
 Object.defineProperty(exports, "formatCert", { enumerable: true, get: function () { return kdf_1.formatCert; } });

package/dist/kdf.js

@@ -4,68 +4,58 @@ exports.derive = derive;
 exports.verify = verify;
 exports.formatCert = formatCert;
 const node_crypto_1 = require("node:crypto");
+const argon2_1 = require("argon2");
 const qrng_1 = require("./qrng");
-const scryptAsync = (password, salt, keyLen, opts) => new Promise((resolve, reject) => (0, node_crypto_1.scrypt)(password, salt, keyLen, opts, (err, key) => err ? reject(err) : resolve(key)));
 /**
- * Derive a cryptographic key from a password using scrypt with a
+ * Derive a cryptographic key from a password using Argon2id with a
  * quantum-random salt sourced from ANU vacuum fluctuations.
+ *
+ * Returns a self-describing PHC hash string. Persist it as-is.
  */
 async function derive(password, options = {}) {
     const saltBytes = options.saltBytes ?? 32;
     const keyLength = options.keyLength ?? 32;
     const context = options.context ?? null;
-    const N = options.cost?.N ?? 16384;
-    const r = options.cost?.r ?? 8;
-    const p = options.cost?.p ?? 1;
-    const qs = options.source ?? (await qrng_1.QuantumSource.create());
+    const timeCost = options.cost?.timeCost ?? 3;
+    const memoryCost = options.cost?.memoryCost ?? 65536;
+    const parallelism = options.cost?.parallelism ?? 4;
+    const qs = options.source ??
+        (await qrng_1.QuantumSource.create(undefined, { strict: options.strict }));
     const salt = await qs.bytes(saltBytes);
-    const ikm = context
-        ? Buffer.concat([
-            Buffer.from(password),
-            Buffer.from('\x00'),
-            Buffer.from(context),
-        ])
-        : Buffer.from(password);
-    const key = await scryptAsync(ikm, salt, keyLength, {
-        N,
-        r,
-        p,
-        maxmem: 128 * N * r * 2,
+    const encoded = await (0, argon2_1.hash)(Buffer.from(password), {
+        type: argon2_1.argon2id,
+        salt,
+        timeCost,
+        memoryCost,
+        parallelism,
+        hashLength: keyLength,
+        ...(context !== null && { associatedData: Buffer.from(context) }),
     });
+    // Extract hash bytes from the last segment of the PHC string for the certificate.
+    // Format: $argon2id$v=19$m=...,t=...,p=...[,data=...]$<salt_b64>$<hash_b64>
+    const parts = encoded.split('$');
+    const hashBytes = Buffer.from(parts[parts.length - 1], 'base64');
     const certificate = {
         source: qs.source,
         timestamp: new Date().toISOString(),
         saltHash: sha256(salt),
-        keyHash: sha256(key),
-        params: { N, r, p, keyLength, saltBytes },
+        keyHash: sha256(hashBytes),
+        params: { timeCost, memoryCost, parallelism, keyLength, saltBytes },
         context,
     };
-    return { key, salt, certificate };
+    return { hash: encoded, certificate };
 }
 /**
- * Re-derive from password + salt and check against the expected key.
- * Uses constant-time comparison.
+ * Verify a password against a stored PHC hash string.
+ * All parameters — including context (associatedData) — are read from the hash.
  */
-async function verify(password, salt, key, options = {}) {
-    const keyLength = options.keyLength ?? key.length;
-    const N = options.cost?.N ?? 16384;
-    const r = options.cost?.r ?? 8;
-    const p = options.cost?.p ?? 1;
-    const context = options.context ?? null;
-    const ikm = context
-        ? Buffer.concat([
-            Buffer.from(password),
-            Buffer.from('\x00'),
-            Buffer.from(context),
-        ])
-        : Buffer.from(password);
-    const derived = await scryptAsync(ikm, salt, keyLength, {
-        N,
-        r,
-        p,
-        maxmem: 128 * N * r * 2,
-    });
-    return derived.length === key.length && (0, node_crypto_1.timingSafeEqual)(derived, key);
+async function verify(password, hash) {
+    try {
+        return await (0, argon2_1.verify)(hash, Buffer.from(password));
+    }
+    catch {
+        return false;
+    }
 }
 /** Format a certificate as a human-readable block. */
 function formatCert(cert) {
@@ -81,8 +71,8 @@ function formatCert(cert) {
         line,
         row('Source:', sourceLabel),
         row('Timestamp:', cert.timestamp),
-        row('KDF:', 'scrypt'),
-        row('N / r / p:', `${cert.params.N} / ${cert.params.r} / ${cert.params.p}`),
+        row('KDF:', 'argon2id'),
+        row('t / m / p:', `${cert.params.timeCost} / ${cert.params.memoryCost} / ${cert.params.parallelism}`),
         row('Key length:', `${cert.params.keyLength} bytes (${cert.params.keyLength * 8} bits)`),
         row('Salt bytes:', `${cert.params.saltBytes} bytes (${cert.params.saltBytes * 8} bits)`),
         cert.context ? row('Context:', cert.context) : null,

package/dist/qrng.js

@@ -3,7 +3,8 @@
  * Quantum Random Number Generator
  *
  * Probes ANU (Australian National University) quantum vacuum fluctuations API.
- * Falls back silently to crypto.getRandomValues() if ANU is unavailable.
+ * Falls back silently to crypto.getRandomValues() if ANU is unavailable,
+ * unless strict mode is enabled.
  *
  * API:  https://api.quantumnumbers.anu.edu.au
  * Keys: https://quantumnumbers.anu.edu.au
@@ -20,19 +21,30 @@ class QuantumSource {
         this.#source = source;
         this.#apiKey = apiKey;
     }
-    /** Create a QuantumSource. Probes ANU first; falls back to crypto silently. */
-    static async create(apiKey) {
+    /**
+     * Create a QuantumSource. Probes ANU first.
+     * Without strict mode, falls back to crypto.getRandomValues() silently if ANU is unavailable.
+     * With strict mode, throws if ANU is unavailable or no API key is configured.
+     */
+    static async create(apiKey, options) {
         const key = apiKey ?? process.env.ANU_API_KEY;
+        const strict = options?.strict ?? false;
         if (key) {
             try {
                 const qs = new QuantumSource('anu', key);
                 await qs.bytes(1); // probe
                 return qs;
             }
-            catch {
+            catch (err) {
+                if (strict) {
+                    throw new Error(`ANU QRNG unavailable (strict mode): ${err instanceof Error ? err.message : String(err)}`);
+                }
                 // fall through to crypto
             }
         }
+        else if (strict) {
+            throw new Error('ANU QRNG strict mode requires an API key — set ANU_API_KEY or pass apiKey');
+        }
         return new QuantumSource('crypto');
     }
     /** Which entropy source is active. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kirkelliott/kdfts",
-  "version": "1.1.1",
-  "description": "Quantum-seeded KDF — scrypt with salt from ANU vacuum fluctuations",
+  "version": "2.0.1",
+  "description": "Quantum-seeded KDF — Argon2id with salt from ANU vacuum fluctuations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -27,5 +27,8 @@
     "dist",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "dependencies": {
+    "argon2": "^0.44.0"
+  }
 }