@passkeykit/server 2.1.0 → 3.1.0

package/README.md

@@ -215,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;
@@ -225,6 +225,36 @@ 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 | Requires |

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/express-routes.js

@@ -3,13 +3,50 @@
  *
  * @ai_context This is a convenience wrapper. Apps that don't use Express
  * can use PasskeyServer directly. These routes implement the standard
- * challenge-response pattern with proper error handling.
+ * challenge-response pattern with proper error handling and Zod validation.
  *
  * Usage:
  *   const routes = createExpressRoutes(passkeyServer, { getUserInfo });
  *   app.use('/api/auth/passkey', routes);
  */
 import { Router } from 'express';
+import { z } from 'zod';
+// ============================================================
+// Zod Schemas — strict input validation for every route
+// ============================================================
+const registerOptionsSchema = z.object({
+    userId: z.string().min(1),
+    authenticatorAttachment: z.enum(['platform', 'cross-platform']).optional(),
+    residentKey: z.enum(['required', 'preferred', 'discouraged']).optional(),
+    userVerification: z.enum(['required', 'preferred', 'discouraged']).optional(),
+}).strict();
+const registerVerifySchema = z.object({
+    userId: z.string().min(1),
+    response: z.object({
+        id: z.string(),
+        rawId: z.string(),
+        type: z.literal('public-key'),
+        response: z.record(z.string(), z.unknown()),
+        clientExtensionResults: z.record(z.string(), z.unknown()),
+        authenticatorAttachment: z.string().optional(),
+    }).passthrough(),
+    credentialName: z.string().optional(),
+    challengeToken: z.string().optional(),
+}).strict();
+const authenticateOptionsSchema = z.object({
+    userId: z.string().min(1).optional(),
+    userVerification: z.enum(['required', 'preferred', 'discouraged']).optional(),
+}).strict();
+const authenticateVerifySchema = z.object({
+    sessionKey: z.string().min(1),
+    response: z.object({
+        id: z.string(),
+        rawId: z.string(),
+        type: z.literal('public-key'),
+        response: z.record(z.string(), z.unknown()),
+        clientExtensionResults: z.record(z.string(), z.unknown()),
+    }).passthrough(),
+}).strict();
 /**
  * Create Express router with passkey registration and authentication routes.
  *
@@ -21,18 +58,14 @@ import { Router } from 'express';
  */
 export function createExpressRoutes(server, config) {
     const router = Router();
-    /**
-     * POST /register/options
-     * Body: { userId: string, authenticatorAttachment?: 'platform' | 'cross-platform' }
-     * Response includes `challengeToken` in stateless mode.
-     */
     router.post('/register/options', async (req, res) => {
         try {
-            const { userId, authenticatorAttachment, residentKey, userVerification } = req.body;
-            if (!userId) {
-                res.status(400).json({ error: 'userId is required' });
+            const parsed = registerOptionsSchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
                 return;
             }
+            const { userId, authenticatorAttachment, residentKey, userVerification } = parsed.data;
             const user = await config.getUserInfo(userId);
             if (!user) {
                 res.status(404).json({ error: 'User not found' });
@@ -50,18 +83,14 @@ export function createExpressRoutes(server, config) {
             res.status(500).json({ error: 'Failed to generate registration options' });
         }
     });
-    /**
-     * POST /register/verify
-     * Body: { userId: string, response: RegistrationResponseJSON, credentialName?: string, challengeToken?: string }
-     * `challengeToken` is required in stateless mode.
-     */
     router.post('/register/verify', async (req, res) => {
         try {
-            const { userId, response, credentialName, challengeToken } = req.body;
-            if (!userId || !response) {
-                res.status(400).json({ error: 'userId and response are required' });
+            const parsed = registerVerifySchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
                 return;
             }
+            const { userId, response, credentialName, challengeToken } = parsed.data;
             const result = await server.verifyRegistration(userId, response, credentialName, challengeToken);
             if (config.onRegistrationSuccess) {
                 await config.onRegistrationSuccess(userId, result.credential.credentialId);
@@ -78,14 +107,14 @@ export function createExpressRoutes(server, config) {
             res.status(400).json({ error: message });
         }
     });
-    /**
-     * POST /authenticate/options
-     * Body: { userId?: string }
-     * Response includes `sessionKey` (which IS the challengeToken in stateless mode).
-     */
     router.post('/authenticate/options', async (req, res) => {
         try {
-            const { userId, userVerification } = req.body;
+            const parsed = authenticateOptionsSchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
+                return;
+            }
+            const { userId, userVerification } = parsed.data;
             const { options, sessionKey, challengeToken } = await server.generateAuthenticationOptions(userId, { userVerification });
             res.json({ options, sessionKey, challengeToken });
         }
@@ -94,17 +123,14 @@ export function createExpressRoutes(server, config) {
             res.status(500).json({ error: 'Failed to generate authentication options' });
         }
     });
-    /**
-     * POST /authenticate/verify
-     * Body: { sessionKey: string, response: AuthenticationResponseJSON }
-     */
     router.post('/authenticate/verify', async (req, res) => {
         try {
-            const { sessionKey, response } = req.body;
-            if (!sessionKey || !response) {
-                res.status(400).json({ error: 'sessionKey and response are required' });
+            const parsed = authenticateVerifySchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
                 return;
             }
+            const { sessionKey, response } = parsed.data;
             const result = await server.verifyAuthentication(sessionKey, response);
             let extra = {};
             if (config.onAuthenticationSuccess) {

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

@@ -4,7 +4,8 @@
  * 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 { readFile, writeFile } from 'fs/promises';
+import { mkdirSync, existsSync } from 'fs';
 import { dirname } from 'path';
 // ============================================================
 // In-Memory Stores (good for development and single-process)
@@ -63,35 +64,39 @@ export class FileChallengeStore {
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
     }
-    load() {
+    async load() {
         try {
-            return JSON.parse(readFileSync(this.filePath, 'utf-8'));
+            const raw = await readFile(this.filePath, 'utf-8');
+            return JSON.parse(raw);
         }
-        catch {
-            return {};
+        catch (err) {
+            // File not yet created — valid initial state
+            if (err?.code === 'ENOENT')
+                return {};
+            // Anything else (permission denied, corrupted JSON) must surface
+            throw err;
         }
     }
-    persist(data) {
-        // Clean expired
+    async persist(data) {
         const now = Date.now();
         for (const [key, val] of Object.entries(data)) {
             if (now > val.expiresAt)
                 delete data[key];
         }
-        writeFileSync(this.filePath, JSON.stringify(data, null, 2));
+        await writeFile(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(key, challenge) {
-        const data = this.load();
+        const data = await this.load();
         data[key] = challenge;
-        this.persist(data);
+        await this.persist(data);
     }
     async consume(key) {
-        const data = this.load();
+        const data = await this.load();
         const challenge = data[key];
         if (!challenge)
             return null;
         delete data[key];
-        this.persist(data);
+        await this.persist(data);
         if (Date.now() > challenge.expiresAt)
             return null;
         return challenge;
@@ -108,38 +113,41 @@ export class FileCredentialStore {
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
     }
-    load() {
+    async load() {
         try {
-            return JSON.parse(readFileSync(this.filePath, 'utf-8'));
+            const raw = await readFile(this.filePath, 'utf-8');
+            return JSON.parse(raw);
         }
-        catch {
-            return [];
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return [];
+            throw err;
         }
     }
-    persist(data) {
-        writeFileSync(this.filePath, JSON.stringify(data, null, 2));
+    async persist(data) {
+        await writeFile(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(credential) {
-        const data = this.load();
+        const data = await this.load();
         data.push(credential);
-        this.persist(data);
+        await this.persist(data);
     }
     async getByUserId(userId) {
-        return this.load().filter(c => c.userId === userId);
+        return (await this.load()).filter(c => c.userId === userId);
     }
     async getByCredentialId(credentialId) {
-        return this.load().find(c => c.credentialId === credentialId) ?? null;
+        return (await this.load()).find(c => c.credentialId === credentialId) ?? null;
     }
     async updateCounter(credentialId, newCounter) {
-        const data = this.load();
+        const data = await this.load();
         const cred = data.find(c => c.credentialId === credentialId);
         if (cred) {
             cred.counter = newCounter;
-            this.persist(data);
+            await this.persist(data);
         }
     }
     async delete(credentialId) {
-        const data = this.load().filter(c => c.credentialId !== credentialId);
-        this.persist(data);
+        const data = (await this.load()).filter(c => c.credentialId !== credentialId);
+        await this.persist(data);
     }
 }

package/dist/express-routes.d.ts

@@ -3,7 +3,7 @@
  *
  * @ai_context This is a convenience wrapper. Apps that don't use Express
  * can use PasskeyServer directly. These routes implement the standard
- * challenge-response pattern with proper error handling.
+ * challenge-response pattern with proper error handling and Zod validation.
  *
  * Usage:
  *   const routes = createExpressRoutes(passkeyServer, { getUserInfo });

package/dist/express-routes.js

@@ -4,7 +4,7 @@
  *
  * @ai_context This is a convenience wrapper. Apps that don't use Express
  * can use PasskeyServer directly. These routes implement the standard
- * challenge-response pattern with proper error handling.
+ * challenge-response pattern with proper error handling and Zod validation.
  *
  * Usage:
  *   const routes = createExpressRoutes(passkeyServer, { getUserInfo });
@@ -13,6 +13,43 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createExpressRoutes = createExpressRoutes;
 const express_1 = require("express");
+const zod_1 = require("zod");
+// ============================================================
+// Zod Schemas — strict input validation for every route
+// ============================================================
+const registerOptionsSchema = zod_1.z.object({
+    userId: zod_1.z.string().min(1),
+    authenticatorAttachment: zod_1.z.enum(['platform', 'cross-platform']).optional(),
+    residentKey: zod_1.z.enum(['required', 'preferred', 'discouraged']).optional(),
+    userVerification: zod_1.z.enum(['required', 'preferred', 'discouraged']).optional(),
+}).strict();
+const registerVerifySchema = zod_1.z.object({
+    userId: zod_1.z.string().min(1),
+    response: zod_1.z.object({
+        id: zod_1.z.string(),
+        rawId: zod_1.z.string(),
+        type: zod_1.z.literal('public-key'),
+        response: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+        clientExtensionResults: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+        authenticatorAttachment: zod_1.z.string().optional(),
+    }).passthrough(),
+    credentialName: zod_1.z.string().optional(),
+    challengeToken: zod_1.z.string().optional(),
+}).strict();
+const authenticateOptionsSchema = zod_1.z.object({
+    userId: zod_1.z.string().min(1).optional(),
+    userVerification: zod_1.z.enum(['required', 'preferred', 'discouraged']).optional(),
+}).strict();
+const authenticateVerifySchema = zod_1.z.object({
+    sessionKey: zod_1.z.string().min(1),
+    response: zod_1.z.object({
+        id: zod_1.z.string(),
+        rawId: zod_1.z.string(),
+        type: zod_1.z.literal('public-key'),
+        response: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+        clientExtensionResults: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    }).passthrough(),
+}).strict();
 /**
  * Create Express router with passkey registration and authentication routes.
  *
@@ -24,18 +61,14 @@ const express_1 = require("express");
  */
 function createExpressRoutes(server, config) {
     const router = (0, express_1.Router)();
-    /**
-     * POST /register/options
-     * Body: { userId: string, authenticatorAttachment?: 'platform' | 'cross-platform' }
-     * Response includes `challengeToken` in stateless mode.
-     */
     router.post('/register/options', async (req, res) => {
         try {
-            const { userId, authenticatorAttachment, residentKey, userVerification } = req.body;
-            if (!userId) {
-                res.status(400).json({ error: 'userId is required' });
+            const parsed = registerOptionsSchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
                 return;
             }
+            const { userId, authenticatorAttachment, residentKey, userVerification } = parsed.data;
             const user = await config.getUserInfo(userId);
             if (!user) {
                 res.status(404).json({ error: 'User not found' });
@@ -53,18 +86,14 @@ function createExpressRoutes(server, config) {
             res.status(500).json({ error: 'Failed to generate registration options' });
         }
     });
-    /**
-     * POST /register/verify
-     * Body: { userId: string, response: RegistrationResponseJSON, credentialName?: string, challengeToken?: string }
-     * `challengeToken` is required in stateless mode.
-     */
     router.post('/register/verify', async (req, res) => {
         try {
-            const { userId, response, credentialName, challengeToken } = req.body;
-            if (!userId || !response) {
-                res.status(400).json({ error: 'userId and response are required' });
+            const parsed = registerVerifySchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
                 return;
             }
+            const { userId, response, credentialName, challengeToken } = parsed.data;
             const result = await server.verifyRegistration(userId, response, credentialName, challengeToken);
             if (config.onRegistrationSuccess) {
                 await config.onRegistrationSuccess(userId, result.credential.credentialId);
@@ -81,14 +110,14 @@ function createExpressRoutes(server, config) {
             res.status(400).json({ error: message });
         }
     });
-    /**
-     * POST /authenticate/options
-     * Body: { userId?: string }
-     * Response includes `sessionKey` (which IS the challengeToken in stateless mode).
-     */
     router.post('/authenticate/options', async (req, res) => {
         try {
-            const { userId, userVerification } = req.body;
+            const parsed = authenticateOptionsSchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
+                return;
+            }
+            const { userId, userVerification } = parsed.data;
             const { options, sessionKey, challengeToken } = await server.generateAuthenticationOptions(userId, { userVerification });
             res.json({ options, sessionKey, challengeToken });
         }
@@ -97,17 +126,14 @@ function createExpressRoutes(server, config) {
             res.status(500).json({ error: 'Failed to generate authentication options' });
         }
     });
-    /**
-     * POST /authenticate/verify
-     * Body: { sessionKey: string, response: AuthenticationResponseJSON }
-     */
     router.post('/authenticate/verify', async (req, res) => {
         try {
-            const { sessionKey, response } = req.body;
-            if (!sessionKey || !response) {
-                res.status(400).json({ error: 'sessionKey and response are required' });
+            const parsed = authenticateVerifySchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'Invalid request body', details: parsed.error.flatten().fieldErrors });
                 return;
             }
+            const { sessionKey, response } = parsed.data;
             const result = await server.verifyAuthentication(sessionKey, response);
             let extra = {};
             if (config.onAuthenticationSuccess) {

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.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileCredentialStore = exports.FileChallengeStore = exports.MemoryCredentialStore = exports.MemoryChallengeStore = void 0;
+const promises_1 = require("fs/promises");
 const fs_1 = require("fs");
 const path_1 = require("path");
 // ============================================================
@@ -68,35 +69,39 @@ class FileChallengeStore {
         if (!(0, fs_1.existsSync)(dir))
             (0, fs_1.mkdirSync)(dir, { recursive: true });
     }
-    load() {
+    async load() {
         try {
-            return JSON.parse((0, fs_1.readFileSync)(this.filePath, 'utf-8'));
+            const raw = await (0, promises_1.readFile)(this.filePath, 'utf-8');
+            return JSON.parse(raw);
         }
-        catch {
-            return {};
+        catch (err) {
+            // File not yet created — valid initial state
+            if (err?.code === 'ENOENT')
+                return {};
+            // Anything else (permission denied, corrupted JSON) must surface
+            throw err;
         }
     }
-    persist(data) {
-        // Clean expired
+    async persist(data) {
         const now = Date.now();
         for (const [key, val] of Object.entries(data)) {
             if (now > val.expiresAt)
                 delete data[key];
         }
-        (0, fs_1.writeFileSync)(this.filePath, JSON.stringify(data, null, 2));
+        await (0, promises_1.writeFile)(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(key, challenge) {
-        const data = this.load();
+        const data = await this.load();
         data[key] = challenge;
-        this.persist(data);
+        await this.persist(data);
     }
     async consume(key) {
-        const data = this.load();
+        const data = await this.load();
         const challenge = data[key];
         if (!challenge)
             return null;
         delete data[key];
-        this.persist(data);
+        await this.persist(data);
         if (Date.now() > challenge.expiresAt)
             return null;
         return challenge;
@@ -114,39 +119,42 @@ class FileCredentialStore {
         if (!(0, fs_1.existsSync)(dir))
             (0, fs_1.mkdirSync)(dir, { recursive: true });
     }
-    load() {
+    async load() {
         try {
-            return JSON.parse((0, fs_1.readFileSync)(this.filePath, 'utf-8'));
+            const raw = await (0, promises_1.readFile)(this.filePath, 'utf-8');
+            return JSON.parse(raw);
         }
-        catch {
-            return [];
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return [];
+            throw err;
         }
     }
-    persist(data) {
-        (0, fs_1.writeFileSync)(this.filePath, JSON.stringify(data, null, 2));
+    async persist(data) {
+        await (0, promises_1.writeFile)(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(credential) {
-        const data = this.load();
+        const data = await this.load();
         data.push(credential);
-        this.persist(data);
+        await this.persist(data);
     }
     async getByUserId(userId) {
-        return this.load().filter(c => c.userId === userId);
+        return (await this.load()).filter(c => c.userId === userId);
     }
     async getByCredentialId(credentialId) {
-        return this.load().find(c => c.credentialId === credentialId) ?? null;
+        return (await this.load()).find(c => c.credentialId === credentialId) ?? null;
     }
     async updateCounter(credentialId, newCounter) {
-        const data = this.load();
+        const data = await this.load();
         const cred = data.find(c => c.credentialId === credentialId);
         if (cred) {
             cred.counter = newCounter;
-            this.persist(data);
+            await this.persist(data);
         }
     }
     async delete(credentialId) {
-        const data = this.load().filter(c => c.credentialId !== credentialId);
-        this.persist(data);
+        const data = (await this.load()).filter(c => c.credentialId !== credentialId);
+        await this.persist(data);
     }
 }
 exports.FileCredentialStore = FileCredentialStore;

package/dist/types.d.ts

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passkeykit/server",
-  "version": "2.1.0",
+  "version": "3.1.0",
   "description": "Server-side WebAuthn passkey verification — stateless or stateful, pure JS, works on serverless",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -54,12 +54,13 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@noble/hashes": "^1.7.0"
+    "@noble/hashes": "^1.7.0",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@simplewebauthn/server": "^13.0.0",
-    "express": "^4.0.0 || ^5.0.0",
-    "argon2": "^0.41.0"
+    "argon2": "^0.41.0",
+    "express": "^4.0.0 || ^5.0.0"
   },
   "peerDependenciesMeta": {
     "@simplewebauthn/server": {