@passkeykit/server 2.0.2 → 3.0.0

package/README.md

@@ -10,9 +10,19 @@ Handles challenge generation, attestation/assertion verification, and includes s
 ## Install
 
 ```bash
-npm install @passkeykit/server
+npm install @passkeykit/server @simplewebauthn/server
 ```
 
+> `@simplewebauthn/server` is a **peer dependency** — you control the version. This keeps the package itself lightweight while giving you full WebAuthn verification.
+>
+> **Password-only?** If you only need `hashPassword` / `verifyPassword`, import from the subpath — no WebAuthn dependency required:
+> ```bash
+> npm install @passkeykit/server
+> ```
+> ```typescript
+> import { hashPassword, verifyPassword } from '@passkeykit/server/password';
+> ```
+
 ## Quick Start
 
 ### Stateless (Serverless / Vercel / Cloudflare)
@@ -205,7 +215,7 @@ interface PasskeyServerConfig {
   credentialStore: CredentialStore;
 
   // Stateless mode (default — pick one):
-  encryptionKey?: string;   // 32+ char secret for AES-256-GCM challenge tokens
+  encryptionKey?: string | string[];   // AES-256-GCM secret(s) — see Key Rotation below
 
   // Stateful mode (alternative):
   challengeStore?: ChallengeStore;
@@ -215,13 +225,44 @@ interface PasskeyServerConfig {
 }
 ```
 
+## Key Rotation
+
+Pass an array of keys to rotate secrets without breaking in-flight ceremonies:
+
+```typescript
+const server = new PasskeyServer({
+  // ...
+  encryptionKey: [
+    process.env.PASSKEY_SECRET_NEW!, // Current — used for encryption
+    process.env.PASSKEY_SECRET_OLD!, // Previous — still accepted for decryption
+  ],
+});
+```
+
+- **Encryption** always uses the **first** key.
+- **Decryption** tries each key in order until one succeeds.
+- Once all in-flight tokens have expired (default: 5 minutes), remove the old key.
+
+## Runtime Compatibility
+
+v3.0 uses the **Web Crypto API** (`crypto.subtle`) instead of `node:crypto`. This means the library runs natively on:
+
+- ✅ Node.js 18+
+- ✅ Deno
+- ✅ Bun
+- ✅ Cloudflare Workers
+- ✅ Vercel Edge Runtime
+
+> **Breaking change in v3.0:** `sealChallengeToken` and `openChallengeToken` are now **async** (return `Promise`). If you use PasskeyServer directly, this is handled internally. If you imported these functions directly, add `await`.
+
 ## Exports
 
-| Import Path | Contents |
-|-------------|----------|
-| `@passkeykit/server` | `PasskeyServer`, stores, password hashing, types |
-| `@passkeykit/server/express` | `createExpressRoutes()` — ready-made Express router |
-| `@passkeykit/server/argon2` | `hashPassword()`, `verifyPassword()` — native argon2id |
+| Import Path | Contents | Requires |
+|-------------|----------|----------|
+| `@passkeykit/server` | `PasskeyServer`, stores, password hashing, types | `@simplewebauthn/server` |
+| `@passkeykit/server/password` | `hashPassword()`, `verifyPassword()`, `needsRehash()` — scrypt | None (pure JS) |
+| `@passkeykit/server/express` | `createExpressRoutes()` — ready-made Express router | `express` |
+| `@passkeykit/server/argon2` | `hashPassword()`, `verifyPassword()` — native argon2id | `argon2` |
 
 ## Client Pairing
 

package/dist/challenge-token.d.ts

@@ -1,20 +1,26 @@
 /**
- * Stateless challenge token using AES-256-GCM + HMAC-SHA256.
+ * Stateless challenge token using AES-256-GCM (Web Crypto API).
  *
  * @ai_context This is the core innovation for serverless deployments.
  * Instead of storing challenges in a database/memory, we encrypt the
  * challenge payload into an opaque token. The server can verify it later
  * without any state — just the secret key.
  *
+ * Uses the standard Web Crypto API (`crypto.subtle`) so it runs natively
+ * in Node 18+, Deno, Bun, Cloudflare Workers, and Vercel Edge Runtime.
+ *
  * Token format: base64url(iv + ciphertext + authTag)
  * Payload: JSON { challenge, userId?, type, exp }
  *
  * Security properties:
  * - AES-256-GCM provides authenticated encryption (confidentiality + integrity)
+ * - HKDF-SHA256 derives the encryption key from the secret (domain separation)
  * - The challenge value is hidden from the client (they only see the opaque token)
  * - Expiry is baked into the token — no cleanup needed
  * - Each token has a unique IV — replay is prevented by single-use consumption
- *   (the WebAuthn spec itself prevents replays via the challenge binding)
+ *
+ * Key rotation: accepts multiple keys. Always encrypts with the first key.
+ * Decryption tries each key in order until one succeeds.
  */
 export interface ChallengeTokenPayload {
     /** The WebAuthn challenge string (base64url from @simplewebauthn) */
@@ -29,8 +35,10 @@ export interface ChallengeTokenPayload {
 /**
  * Encrypt a challenge payload into an opaque base64url token.
  */
-export declare function sealChallengeToken(payload: ChallengeTokenPayload, secret: string): string;
+export declare function sealChallengeToken(payload: ChallengeTokenPayload, secret: string): Promise<string>;
 /**
- * Decrypt and verify a challenge token. Returns null if invalid/expired.
+ * Decrypt and verify a challenge token. Supports key rotation —
+ * if `secret` is an array, tries each key in order until one works.
+ * Returns null if all keys fail or the token is expired.
  */
-export declare function openChallengeToken(token: string, secret: string): ChallengeTokenPayload | null;
+export declare function openChallengeToken(token: string, secret: string | string[]): Promise<ChallengeTokenPayload | null>;

package/dist/challenge-token.js

@@ -1,69 +1,77 @@
 "use strict";
 /**
- * Stateless challenge token using AES-256-GCM + HMAC-SHA256.
+ * Stateless challenge token using AES-256-GCM (Web Crypto API).
  *
  * @ai_context This is the core innovation for serverless deployments.
  * Instead of storing challenges in a database/memory, we encrypt the
  * challenge payload into an opaque token. The server can verify it later
  * without any state — just the secret key.
  *
+ * Uses the standard Web Crypto API (`crypto.subtle`) so it runs natively
+ * in Node 18+, Deno, Bun, Cloudflare Workers, and Vercel Edge Runtime.
+ *
  * Token format: base64url(iv + ciphertext + authTag)
  * Payload: JSON { challenge, userId?, type, exp }
  *
  * Security properties:
  * - AES-256-GCM provides authenticated encryption (confidentiality + integrity)
+ * - HKDF-SHA256 derives the encryption key from the secret (domain separation)
  * - The challenge value is hidden from the client (they only see the opaque token)
  * - Expiry is baked into the token — no cleanup needed
  * - Each token has a unique IV — replay is prevented by single-use consumption
- *   (the WebAuthn spec itself prevents replays via the challenge binding)
+ *
+ * Key rotation: accepts multiple keys. Always encrypts with the first key.
+ * Decryption tries each key in order until one succeeds.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sealChallengeToken = sealChallengeToken;
 exports.openChallengeToken = openChallengeToken;
-const crypto_1 = require("crypto");
-const ALG = 'aes-256-gcm';
 const IV_LEN = 12;
-const TAG_LEN = 16;
+const HKDF_INFO = new TextEncoder().encode('passkey-kit-challenge-key');
 /**
- * Derive a 32-byte encryption key from a secret string.
- * Uses HMAC-SHA256 with a fixed context label (domain separation).
+ * Derive a 256-bit AES-GCM CryptoKey from a secret string using HKDF.
  */
-function deriveKey(secret) {
-    return (0, crypto_1.createHmac)('sha256', 'passkey-kit-challenge-key')
-        .update(secret)
-        .digest();
+async function deriveKey(secret) {
+    const rawKey = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), 'HKDF', false, ['deriveKey']);
+    return crypto.subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), info: HKDF_INFO }, rawKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+// --- Base64url helpers (no Buffer dependency) ---
+function toBase64Url(buf) {
+    const binStr = Array.from(buf, b => String.fromCharCode(b)).join('');
+    return btoa(binStr).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(str) {
+    const padded = str.replace(/-/g, '+').replace(/_/g, '/') +
+        '='.repeat((4 - (str.length % 4)) % 4);
+    const binStr = atob(padded);
+    return Uint8Array.from(binStr, c => c.charCodeAt(0));
 }
 /**
  * Encrypt a challenge payload into an opaque base64url token.
  */
-function sealChallengeToken(payload, secret) {
-    const key = deriveKey(secret);
-    const iv = (0, crypto_1.randomBytes)(IV_LEN);
-    const cipher = (0, crypto_1.createCipheriv)(ALG, key, iv);
-    const json = JSON.stringify(payload);
-    const encrypted = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()]);
-    const tag = cipher.getAuthTag();
-    // iv (12) + ciphertext (variable) + tag (16)
-    const combined = Buffer.concat([iv, encrypted, tag]);
-    return combined.toString('base64url');
+async function sealChallengeToken(payload, secret) {
+    const key = await deriveKey(secret);
+    const iv = crypto.getRandomValues(new Uint8Array(IV_LEN));
+    const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+    // AES-GCM encrypt (returns ciphertext + 16-byte auth tag appended)
+    const encrypted = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext));
+    // Combine: iv (12) + ciphertext+tag (variable)
+    const combined = new Uint8Array(IV_LEN + encrypted.length);
+    combined.set(iv, 0);
+    combined.set(encrypted, IV_LEN);
+    return toBase64Url(combined);
 }
 /**
- * Decrypt and verify a challenge token. Returns null if invalid/expired.
+ * Decrypt and verify a challenge token with a single key.
+ * Returns null if invalid/expired.
  */
-function openChallengeToken(token, secret) {
+async function openWithKey(buf, secret) {
     try {
-        const key = deriveKey(secret);
-        const buf = Buffer.from(token, 'base64url');
-        if (buf.length < IV_LEN + TAG_LEN + 1)
-            return null;
-        const iv = buf.subarray(0, IV_LEN);
-        const tag = buf.subarray(buf.length - TAG_LEN);
-        const ciphertext = buf.subarray(IV_LEN, buf.length - TAG_LEN);
-        const decipher = (0, crypto_1.createDecipheriv)(ALG, key, iv);
-        decipher.setAuthTag(tag);
-        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-        const payload = JSON.parse(decrypted.toString('utf8'));
-        // Check expiry
+        const key = await deriveKey(secret);
+        const iv = buf.slice(0, IV_LEN);
+        const ciphertextWithTag = buf.slice(IV_LEN);
+        const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertextWithTag);
+        const payload = JSON.parse(new TextDecoder().decode(decrypted));
         if (Date.now() > payload.exp)
             return null;
         return payload;
@@ -72,3 +80,26 @@ function openChallengeToken(token, secret) {
         return null;
     }
 }
+/**
+ * Decrypt and verify a challenge token. Supports key rotation —
+ * if `secret` is an array, tries each key in order until one works.
+ * Returns null if all keys fail or the token is expired.
+ */
+async function openChallengeToken(token, secret) {
+    try {
+        const buf = fromBase64Url(token);
+        // AES-GCM tag is 16 bytes, so minimum length is IV + 1 byte ciphertext + 16 tag
+        if (buf.length < IV_LEN + 17)
+            return null;
+        const secrets = Array.isArray(secret) ? secret : [secret];
+        for (const s of secrets) {
+            const result = await openWithKey(buf, s);
+            if (result)
+                return result;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/esm/challenge-token.js

@@ -1,65 +1,73 @@
 /**
- * Stateless challenge token using AES-256-GCM + HMAC-SHA256.
+ * Stateless challenge token using AES-256-GCM (Web Crypto API).
  *
  * @ai_context This is the core innovation for serverless deployments.
  * Instead of storing challenges in a database/memory, we encrypt the
  * challenge payload into an opaque token. The server can verify it later
  * without any state — just the secret key.
  *
+ * Uses the standard Web Crypto API (`crypto.subtle`) so it runs natively
+ * in Node 18+, Deno, Bun, Cloudflare Workers, and Vercel Edge Runtime.
+ *
  * Token format: base64url(iv + ciphertext + authTag)
  * Payload: JSON { challenge, userId?, type, exp }
  *
  * Security properties:
  * - AES-256-GCM provides authenticated encryption (confidentiality + integrity)
+ * - HKDF-SHA256 derives the encryption key from the secret (domain separation)
  * - The challenge value is hidden from the client (they only see the opaque token)
  * - Expiry is baked into the token — no cleanup needed
  * - Each token has a unique IV — replay is prevented by single-use consumption
- *   (the WebAuthn spec itself prevents replays via the challenge binding)
+ *
+ * Key rotation: accepts multiple keys. Always encrypts with the first key.
+ * Decryption tries each key in order until one succeeds.
  */
-import { createCipheriv, createDecipheriv, randomBytes, createHmac } from 'crypto';
-const ALG = 'aes-256-gcm';
 const IV_LEN = 12;
-const TAG_LEN = 16;
+const HKDF_INFO = new TextEncoder().encode('passkey-kit-challenge-key');
 /**
- * Derive a 32-byte encryption key from a secret string.
- * Uses HMAC-SHA256 with a fixed context label (domain separation).
+ * Derive a 256-bit AES-GCM CryptoKey from a secret string using HKDF.
  */
-function deriveKey(secret) {
-    return createHmac('sha256', 'passkey-kit-challenge-key')
-        .update(secret)
-        .digest();
+async function deriveKey(secret) {
+    const rawKey = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), 'HKDF', false, ['deriveKey']);
+    return crypto.subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), info: HKDF_INFO }, rawKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+// --- Base64url helpers (no Buffer dependency) ---
+function toBase64Url(buf) {
+    const binStr = Array.from(buf, b => String.fromCharCode(b)).join('');
+    return btoa(binStr).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(str) {
+    const padded = str.replace(/-/g, '+').replace(/_/g, '/') +
+        '='.repeat((4 - (str.length % 4)) % 4);
+    const binStr = atob(padded);
+    return Uint8Array.from(binStr, c => c.charCodeAt(0));
 }
 /**
  * Encrypt a challenge payload into an opaque base64url token.
  */
-export function sealChallengeToken(payload, secret) {
-    const key = deriveKey(secret);
-    const iv = randomBytes(IV_LEN);
-    const cipher = createCipheriv(ALG, key, iv);
-    const json = JSON.stringify(payload);
-    const encrypted = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()]);
-    const tag = cipher.getAuthTag();
-    // iv (12) + ciphertext (variable) + tag (16)
-    const combined = Buffer.concat([iv, encrypted, tag]);
-    return combined.toString('base64url');
+export async function sealChallengeToken(payload, secret) {
+    const key = await deriveKey(secret);
+    const iv = crypto.getRandomValues(new Uint8Array(IV_LEN));
+    const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+    // AES-GCM encrypt (returns ciphertext + 16-byte auth tag appended)
+    const encrypted = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext));
+    // Combine: iv (12) + ciphertext+tag (variable)
+    const combined = new Uint8Array(IV_LEN + encrypted.length);
+    combined.set(iv, 0);
+    combined.set(encrypted, IV_LEN);
+    return toBase64Url(combined);
 }
 /**
- * Decrypt and verify a challenge token. Returns null if invalid/expired.
+ * Decrypt and verify a challenge token with a single key.
+ * Returns null if invalid/expired.
  */
-export function openChallengeToken(token, secret) {
+async function openWithKey(buf, secret) {
     try {
-        const key = deriveKey(secret);
-        const buf = Buffer.from(token, 'base64url');
-        if (buf.length < IV_LEN + TAG_LEN + 1)
-            return null;
-        const iv = buf.subarray(0, IV_LEN);
-        const tag = buf.subarray(buf.length - TAG_LEN);
-        const ciphertext = buf.subarray(IV_LEN, buf.length - TAG_LEN);
-        const decipher = createDecipheriv(ALG, key, iv);
-        decipher.setAuthTag(tag);
-        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-        const payload = JSON.parse(decrypted.toString('utf8'));
-        // Check expiry
+        const key = await deriveKey(secret);
+        const iv = buf.slice(0, IV_LEN);
+        const ciphertextWithTag = buf.slice(IV_LEN);
+        const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertextWithTag);
+        const payload = JSON.parse(new TextDecoder().decode(decrypted));
         if (Date.now() > payload.exp)
             return null;
         return payload;
@@ -68,3 +76,26 @@ export function openChallengeToken(token, secret) {
         return null;
     }
 }
+/**
+ * Decrypt and verify a challenge token. Supports key rotation —
+ * if `secret` is an array, tries each key in order until one works.
+ * Returns null if all keys fail or the token is expired.
+ */
+export async function openChallengeToken(token, secret) {
+    try {
+        const buf = fromBase64Url(token);
+        // AES-GCM tag is 16 bytes, so minimum length is IV + 1 byte ciphertext + 16 tag
+        if (buf.length < IV_LEN + 17)
+            return null;
+        const secrets = Array.isArray(secret) ? secret : [secret];
+        for (const s of secrets) {
+            const result = await openWithKey(buf, s);
+            if (result)
+                return result;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/esm/index.js

@@ -4,10 +4,6 @@
  * Server-side WebAuthn passkey verification with challenge-response pattern
  * and scrypt password hashing (pure JS, works everywhere).
  *
- * @ai_context This is the core auth library used across all dnldev apps.
- * Challenge generation and verification MUST happen server-side.
- * Client never sees raw challenges — only attestation/assertion responses.
- *
  * Two modes:
  * - **Stateless** (default): No server-side state. Set `encryptionKey` in config.
  * - **Stateful**: Provide a `challengeStore` (memory, file, Redis, etc).

package/dist/esm/passkey-server.js

@@ -78,13 +78,14 @@ export class PasskeyServer {
             });
         }
         else {
-            // Stateless: encrypt challenge into token
-            challengeToken = sealChallengeToken({
+            // Stateless: encrypt challenge into token (use first key for encryption)
+            const primaryKey = Array.isArray(this.encryptionKey) ? this.encryptionKey[0] : this.encryptionKey;
+            challengeToken = await sealChallengeToken({
                 challenge: options.challenge,
                 userId: user.id,
                 type: 'registration',
                 exp: Date.now() + this.challengeTTL,
-            }, this.encryptionKey);
+            }, primaryKey);
         }
         return { ...options, challengeToken };
     }
@@ -111,7 +112,7 @@ export class PasskeyServer {
         else {
             if (!challengeToken)
                 throw new Error('challengeToken is required in stateless mode');
-            const payload = openChallengeToken(challengeToken, this.encryptionKey);
+            const payload = await openChallengeToken(challengeToken, this.encryptionKey);
             if (!payload)
                 throw new Error('Invalid or expired challenge token');
             if (payload.type !== 'registration')
@@ -175,12 +176,13 @@ export class PasskeyServer {
         }
         else {
             // Stateless: encrypt into token (sessionKey IS the token)
-            challengeToken = sealChallengeToken({
+            const primaryKey = Array.isArray(this.encryptionKey) ? this.encryptionKey[0] : this.encryptionKey;
+            challengeToken = await sealChallengeToken({
                 challenge: options.challenge,
                 userId,
                 type: 'authentication',
                 exp: Date.now() + this.challengeTTL,
-            }, this.encryptionKey);
+            }, primaryKey);
             sessionKey = challengeToken;
         }
         return { options, sessionKey, challengeToken };
@@ -202,7 +204,7 @@ export class PasskeyServer {
         }
         else {
             // In stateless mode, sessionKey IS the challengeToken
-            const payload = openChallengeToken(sessionKey, this.encryptionKey);
+            const payload = await openChallengeToken(sessionKey, this.encryptionKey);
             if (!payload)
                 throw new Error('Invalid or expired challenge token');
             if (payload.type !== 'authentication')

package/dist/esm/password.js

@@ -5,6 +5,8 @@
  * @noble/hashes is audited by Trail of Bits and works on every runtime:
  * Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge, browser.
  *
+ * Uses Web Crypto API for random salt generation — no node:crypto dependency.
+ *
  * For users who want argon2id (requires native bindings), see the
  * `@passkeykit/server/argon2` subpath export.
  *
@@ -12,7 +14,6 @@
  *   $scrypt$ln=17,r=8,p=1$<base64salt>$<base64hash>
  */
 import { scrypt as scryptSync } from '@noble/hashes/scrypt';
-import { randomBytes, timingSafeEqual as tse } from 'crypto';
 /** Default scrypt parameters (OWASP recommendations for interactive login) */
 const DEFAULTS = {
     N: 2 ** 17, // 131072 — CPU/memory cost
@@ -21,6 +22,28 @@ const DEFAULTS = {
     dkLen: 32, // Output key length
     saltLen: 16, // Salt length
 };
+// --- Base64 helpers (no Buffer dependency) ---
+function uint8ToBase64(buf) {
+    const binStr = Array.from(buf, b => String.fromCharCode(b)).join('');
+    return btoa(binStr);
+}
+function base64ToUint8(str) {
+    const binStr = atob(str);
+    return Uint8Array.from(binStr, c => c.charCodeAt(0));
+}
+/**
+ * Constant-time comparison — prevents timing attacks on hash verification.
+ * Works on all runtimes (no node:crypto dependency).
+ */
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a[i] ^ b[i];
+    }
+    return result === 0;
+}
 /**
  * Hash a password using scrypt.
  * Returns a PHC-format string: $scrypt$ln=<log2N>,r=<r>,p=<p>$<salt>$<hash>
@@ -29,11 +52,11 @@ export async function hashPassword(password, options) {
     const N = options?.N ?? DEFAULTS.N;
     const r = options?.r ?? DEFAULTS.r;
     const p = options?.p ?? DEFAULTS.p;
-    const salt = randomBytes(DEFAULTS.saltLen);
+    const salt = crypto.getRandomValues(new Uint8Array(DEFAULTS.saltLen));
     const hash = scryptSync(password, salt, { N, r, p, dkLen: DEFAULTS.dkLen });
     const ln = Math.log2(N);
-    const saltB64 = Buffer.from(salt).toString('base64');
-    const hashB64 = Buffer.from(hash).toString('base64');
+    const saltB64 = uint8ToBase64(salt);
+    const hashB64 = uint8ToBase64(hash);
     return `$scrypt$ln=${ln},r=${r},p=${p}$${saltB64}$${hashB64}`;
 }
 /**
@@ -45,7 +68,7 @@ export async function verifyPassword(storedHash, password) {
         return false;
     const { N, r, p, salt, hash } = parsed;
     const derived = scryptSync(password, salt, { N, r, p, dkLen: hash.length });
-    return timingSafeEqual(Buffer.from(derived), hash);
+    return constantTimeEqual(new Uint8Array(derived), hash);
 }
 /**
  * Check if a hash needs rehashing (params differ from current defaults).
@@ -69,12 +92,7 @@ function parsePhc(phc) {
         N: 2 ** parseInt(match[1], 10),
         r: parseInt(match[2], 10),
         p: parseInt(match[3], 10),
-        salt: Buffer.from(match[4], 'base64'),
-        hash: Buffer.from(match[5], 'base64'),
+        salt: base64ToUint8(match[4]),
+        hash: base64ToUint8(match[5]),
     };
 }
-function timingSafeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    return tse(a, b);
-}

package/dist/esm/stores.js

@@ -1,9 +1,8 @@
 /**
  * Built-in store implementations for common backends.
  *
- * @ai_context These are convenience implementations. For production with
- * multiple server instances, use a shared store (Redis, database, Firestore).
- * For single-server apps (like MovieBox, MediaBox), FileStore works great.
+ * For production with multiple server instances, implement the ChallengeStore
+ * and CredentialStore interfaces with a shared backend (Redis, database, etc).
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { dirname } from 'path';
@@ -54,7 +53,6 @@ export class MemoryCredentialStore {
  * File-based challenge store. Challenges are stored in a JSON file.
  * Auto-cleans expired challenges on every operation.
  *
- * @ai_context Used by MovieBox/MediaBox which store auth in auth.json.
  * Not suitable for multi-process servers (race conditions on file writes).
  */
 export class FileChallengeStore {

package/dist/esm/types.js

@@ -1,8 +1,8 @@
 /**
  * Type definitions for @passkeykit/server
  *
- * @ai_context These types define the storage interface abstraction.
+ * These types define the storage interface abstraction.
  * Apps provide their own ChallengeStore and CredentialStore implementations
- * so the library works with any backend (Firestore, file JSON, SQLite, etc).
+ * so the library works with any backend (Firestore, file JSON, SQLite, Redis, etc).
  */
 export {};

package/dist/index.d.ts

@@ -4,10 +4,6 @@
  * Server-side WebAuthn passkey verification with challenge-response pattern
  * and scrypt password hashing (pure JS, works everywhere).
  *
- * @ai_context This is the core auth library used across all dnldev apps.
- * Challenge generation and verification MUST happen server-side.
- * Client never sees raw challenges — only attestation/assertion responses.
- *
  * Two modes:
  * - **Stateless** (default): No server-side state. Set `encryptionKey` in config.
  * - **Stateful**: Provide a `challengeStore` (memory, file, Redis, etc).

package/dist/index.js

@@ -5,10 +5,6 @@
  * Server-side WebAuthn passkey verification with challenge-response pattern
  * and scrypt password hashing (pure JS, works everywhere).
  *
- * @ai_context This is the core auth library used across all dnldev apps.
- * Challenge generation and verification MUST happen server-side.
- * Client never sees raw challenges — only attestation/assertion responses.
- *
  * Two modes:
  * - **Stateless** (default): No server-side state. Set `encryptionKey` in config.
  * - **Stateful**: Provide a `challengeStore` (memory, file, Redis, etc).

package/dist/passkey-server.js

@@ -81,13 +81,14 @@ class PasskeyServer {
             });
         }
         else {
-            // Stateless: encrypt challenge into token
-            challengeToken = (0, challenge_token_js_1.sealChallengeToken)({
+            // Stateless: encrypt challenge into token (use first key for encryption)
+            const primaryKey = Array.isArray(this.encryptionKey) ? this.encryptionKey[0] : this.encryptionKey;
+            challengeToken = await (0, challenge_token_js_1.sealChallengeToken)({
                 challenge: options.challenge,
                 userId: user.id,
                 type: 'registration',
                 exp: Date.now() + this.challengeTTL,
-            }, this.encryptionKey);
+            }, primaryKey);
         }
         return { ...options, challengeToken };
     }
@@ -114,7 +115,7 @@ class PasskeyServer {
         else {
             if (!challengeToken)
                 throw new Error('challengeToken is required in stateless mode');
-            const payload = (0, challenge_token_js_1.openChallengeToken)(challengeToken, this.encryptionKey);
+            const payload = await (0, challenge_token_js_1.openChallengeToken)(challengeToken, this.encryptionKey);
             if (!payload)
                 throw new Error('Invalid or expired challenge token');
             if (payload.type !== 'registration')
@@ -178,12 +179,13 @@ class PasskeyServer {
         }
         else {
             // Stateless: encrypt into token (sessionKey IS the token)
-            challengeToken = (0, challenge_token_js_1.sealChallengeToken)({
+            const primaryKey = Array.isArray(this.encryptionKey) ? this.encryptionKey[0] : this.encryptionKey;
+            challengeToken = await (0, challenge_token_js_1.sealChallengeToken)({
                 challenge: options.challenge,
                 userId,
                 type: 'authentication',
                 exp: Date.now() + this.challengeTTL,
-            }, this.encryptionKey);
+            }, primaryKey);
             sessionKey = challengeToken;
         }
         return { options, sessionKey, challengeToken };
@@ -205,7 +207,7 @@ class PasskeyServer {
         }
         else {
             // In stateless mode, sessionKey IS the challengeToken
-            const payload = (0, challenge_token_js_1.openChallengeToken)(sessionKey, this.encryptionKey);
+            const payload = await (0, challenge_token_js_1.openChallengeToken)(sessionKey, this.encryptionKey);
             if (!payload)
                 throw new Error('Invalid or expired challenge token');
             if (payload.type !== 'authentication')

package/dist/password.d.ts

@@ -5,6 +5,8 @@
  * @noble/hashes is audited by Trail of Bits and works on every runtime:
  * Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge, browser.
  *
+ * Uses Web Crypto API for random salt generation — no node:crypto dependency.
+ *
  * For users who want argon2id (requires native bindings), see the
  * `@passkeykit/server/argon2` subpath export.
  *

package/dist/password.js

@@ -6,6 +6,8 @@
  * @noble/hashes is audited by Trail of Bits and works on every runtime:
  * Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge, browser.
  *
+ * Uses Web Crypto API for random salt generation — no node:crypto dependency.
+ *
  * For users who want argon2id (requires native bindings), see the
  * `@passkeykit/server/argon2` subpath export.
  *
@@ -17,7 +19,6 @@ exports.hashPassword = hashPassword;
 exports.verifyPassword = verifyPassword;
 exports.needsRehash = needsRehash;
 const scrypt_1 = require("@noble/hashes/scrypt");
-const crypto_1 = require("crypto");
 /** Default scrypt parameters (OWASP recommendations for interactive login) */
 const DEFAULTS = {
     N: 2 ** 17, // 131072 — CPU/memory cost
@@ -26,6 +27,28 @@ const DEFAULTS = {
     dkLen: 32, // Output key length
     saltLen: 16, // Salt length
 };
+// --- Base64 helpers (no Buffer dependency) ---
+function uint8ToBase64(buf) {
+    const binStr = Array.from(buf, b => String.fromCharCode(b)).join('');
+    return btoa(binStr);
+}
+function base64ToUint8(str) {
+    const binStr = atob(str);
+    return Uint8Array.from(binStr, c => c.charCodeAt(0));
+}
+/**
+ * Constant-time comparison — prevents timing attacks on hash verification.
+ * Works on all runtimes (no node:crypto dependency).
+ */
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a[i] ^ b[i];
+    }
+    return result === 0;
+}
 /**
  * Hash a password using scrypt.
  * Returns a PHC-format string: $scrypt$ln=<log2N>,r=<r>,p=<p>$<salt>$<hash>
@@ -34,11 +57,11 @@ async function hashPassword(password, options) {
     const N = options?.N ?? DEFAULTS.N;
     const r = options?.r ?? DEFAULTS.r;
     const p = options?.p ?? DEFAULTS.p;
-    const salt = (0, crypto_1.randomBytes)(DEFAULTS.saltLen);
+    const salt = crypto.getRandomValues(new Uint8Array(DEFAULTS.saltLen));
     const hash = (0, scrypt_1.scrypt)(password, salt, { N, r, p, dkLen: DEFAULTS.dkLen });
     const ln = Math.log2(N);
-    const saltB64 = Buffer.from(salt).toString('base64');
-    const hashB64 = Buffer.from(hash).toString('base64');
+    const saltB64 = uint8ToBase64(salt);
+    const hashB64 = uint8ToBase64(hash);
     return `$scrypt$ln=${ln},r=${r},p=${p}$${saltB64}$${hashB64}`;
 }
 /**
@@ -50,7 +73,7 @@ async function verifyPassword(storedHash, password) {
         return false;
     const { N, r, p, salt, hash } = parsed;
     const derived = (0, scrypt_1.scrypt)(password, salt, { N, r, p, dkLen: hash.length });
-    return timingSafeEqual(Buffer.from(derived), hash);
+    return constantTimeEqual(new Uint8Array(derived), hash);
 }
 /**
  * Check if a hash needs rehashing (params differ from current defaults).
@@ -74,12 +97,7 @@ function parsePhc(phc) {
         N: 2 ** parseInt(match[1], 10),
         r: parseInt(match[2], 10),
         p: parseInt(match[3], 10),
-        salt: Buffer.from(match[4], 'base64'),
-        hash: Buffer.from(match[5], 'base64'),
+        salt: base64ToUint8(match[4]),
+        hash: base64ToUint8(match[5]),
     };
 }
-function timingSafeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    return (0, crypto_1.timingSafeEqual)(a, b);
-}

package/dist/stores.d.ts

@@ -1,9 +1,8 @@
 /**
  * Built-in store implementations for common backends.
  *
- * @ai_context These are convenience implementations. For production with
- * multiple server instances, use a shared store (Redis, database, Firestore).
- * For single-server apps (like MovieBox, MediaBox), FileStore works great.
+ * For production with multiple server instances, implement the ChallengeStore
+ * and CredentialStore interfaces with a shared backend (Redis, database, etc).
  */
 import type { ChallengeStore, CredentialStore, StoredChallenge, StoredCredential } from './types.js';
 export declare class MemoryChallengeStore implements ChallengeStore {
@@ -23,7 +22,6 @@ export declare class MemoryCredentialStore implements CredentialStore {
  * File-based challenge store. Challenges are stored in a JSON file.
  * Auto-cleans expired challenges on every operation.
  *
- * @ai_context Used by MovieBox/MediaBox which store auth in auth.json.
  * Not suitable for multi-process servers (race conditions on file writes).
  */
 export declare class FileChallengeStore implements ChallengeStore {

package/dist/stores.js

@@ -2,9 +2,8 @@
 /**
  * Built-in store implementations for common backends.
  *
- * @ai_context These are convenience implementations. For production with
- * multiple server instances, use a shared store (Redis, database, Firestore).
- * For single-server apps (like MovieBox, MediaBox), FileStore works great.
+ * For production with multiple server instances, implement the ChallengeStore
+ * and CredentialStore interfaces with a shared backend (Redis, database, etc).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileCredentialStore = exports.FileChallengeStore = exports.MemoryCredentialStore = exports.MemoryChallengeStore = void 0;
@@ -59,7 +58,6 @@ exports.MemoryCredentialStore = MemoryCredentialStore;
  * File-based challenge store. Challenges are stored in a JSON file.
  * Auto-cleans expired challenges on every operation.
  *
- * @ai_context Used by MovieBox/MediaBox which store auth in auth.json.
  * Not suitable for multi-process servers (race conditions on file writes).
  */
 class FileChallengeStore {

package/dist/types.d.ts

@@ -1,18 +1,18 @@
 /**
  * Type definitions for @passkeykit/server
  *
- * @ai_context These types define the storage interface abstraction.
+ * These types define the storage interface abstraction.
  * Apps provide their own ChallengeStore and CredentialStore implementations
- * so the library works with any backend (Firestore, file JSON, SQLite, etc).
+ * so the library works with any backend (Firestore, file JSON, SQLite, Redis, etc).
  */
 import type { AuthenticatorTransportFuture } from '@simplewebauthn/server';
 /** Configuration for PasskeyServer */
 export interface PasskeyServerConfig {
-    /** Relying Party name shown to users (e.g. "MovieBox", "SafeHarbor") */
+    /** Relying Party name shown to users (e.g. "My App") */
     rpName: string;
-    /** Relying Party ID — must be a valid domain (e.g. "movies.danieltech.dev") */
+    /** Relying Party ID — must be a valid domain (e.g. "auth.example.com") */
     rpId: string;
-    /** Allowed origins for WebAuthn (e.g. ["https://movies.danieltech.dev"]) */
+    /** Allowed origins for WebAuthn (e.g. ["https://example.com"]) */
     allowedOrigins: string[];
     /**
      * Challenge store implementation (stateful mode).
@@ -24,11 +24,16 @@ export interface PasskeyServerConfig {
     /** Challenge TTL in ms (default: 5 minutes) */
     challengeTTL?: number;
     /**
-     * Secret key for stateless challenge tokens (AES-256-GCM).
+     * Secret key(s) for stateless challenge tokens (AES-256-GCM).
      * Required when `challengeStore` is not provided.
+     *
+     * **Key rotation:** Pass an array of secrets. The first key is used to encrypt
+     * new tokens. All keys are tried when decrypting, so you can rotate secrets
+     * without breaking in-flight registration/authentication flows.
+     *
      * Must be at least 32 characters. Derive from env: process.env.PASSKEY_SECRET
      */
-    encryptionKey?: string;
+    encryptionKey?: string | string[];
 }
 /** A stored WebAuthn credential (persisted per-user) */
 export interface StoredCredential {

package/dist/types.js

@@ -2,8 +2,8 @@
 /**
  * Type definitions for @passkeykit/server
  *
- * @ai_context These types define the storage interface abstraction.
+ * These types define the storage interface abstraction.
  * Apps provide their own ChallengeStore and CredentialStore implementations
- * so the library works with any backend (Firestore, file JSON, SQLite, etc).
+ * so the library works with any backend (Firestore, file JSON, SQLite, Redis, etc).
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passkeykit/server",
-  "version": "2.0.2",
+  "version": "3.0.0",
   "description": "Server-side WebAuthn passkey verification — stateless or stateful, pure JS, works on serverless",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -11,6 +11,11 @@
       "require": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./password": {
+      "import": "./dist/esm/password.js",
+      "require": "./dist/password.js",
+      "types": "./dist/password.d.ts"
+    },
     "./express": {
       "import": "./dist/esm/express-routes.js",
       "require": "./dist/express-routes.js",
@@ -49,14 +54,17 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@simplewebauthn/server": "^13.1.1",
     "@noble/hashes": "^1.7.0"
   },
   "peerDependencies": {
+    "@simplewebauthn/server": "^13.0.0",
     "express": "^4.0.0 || ^5.0.0",
     "argon2": "^0.41.0"
   },
   "peerDependenciesMeta": {
+    "@simplewebauthn/server": {
+      "optional": false
+    },
     "express": {
       "optional": true
     },