@passkeykit/server 2.0.0

package/dist/challenge-token.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Stateless challenge token using AES-256-GCM + HMAC-SHA256.
+ *
+ * @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.
+ *
+ * Token format: base64url(iv + ciphertext + authTag)
+ * Payload: JSON { challenge, userId?, type, exp }
+ *
+ * Security properties:
+ * - AES-256-GCM provides authenticated encryption (confidentiality + integrity)
+ * - 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)
+ */
+export interface ChallengeTokenPayload {
+    /** The WebAuthn challenge string (base64url from @simplewebauthn) */
+    challenge: string;
+    /** User ID (present during registration, optional during auth) */
+    userId?: string;
+    /** 'registration' or 'authentication' */
+    type: 'registration' | 'authentication';
+    /** Expiry timestamp (ms since epoch) */
+    exp: number;
+}
+/**
+ * Encrypt a challenge payload into an opaque base64url token.
+ */
+export declare function sealChallengeToken(payload: ChallengeTokenPayload, secret: string): string;
+/**
+ * Decrypt and verify a challenge token. Returns null if invalid/expired.
+ */
+export declare function openChallengeToken(token: string, secret: string): ChallengeTokenPayload | null;

package/dist/challenge-token.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Stateless challenge token using AES-256-GCM + HMAC-SHA256.
+ *
+ * @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.
+ *
+ * Token format: base64url(iv + ciphertext + authTag)
+ * Payload: JSON { challenge, userId?, type, exp }
+ *
+ * Security properties:
+ * - AES-256-GCM provides authenticated encryption (confidentiality + integrity)
+ * - 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)
+ */
+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;
+/**
+ * Derive a 32-byte encryption key from a secret string.
+ * Uses HMAC-SHA256 with a fixed context label (domain separation).
+ */
+function deriveKey(secret) {
+    return (0, crypto_1.createHmac)('sha256', 'passkey-kit-challenge-key')
+        .update(secret)
+        .digest();
+}
+/**
+ * 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');
+}
+/**
+ * Decrypt and verify a challenge token. Returns null if invalid/expired.
+ */
+function openChallengeToken(token, 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
+        if (Date.now() > payload.exp)
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/esm/challenge-token.js

@@ -0,0 +1,70 @@
+/**
+ * Stateless challenge token using AES-256-GCM + HMAC-SHA256.
+ *
+ * @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.
+ *
+ * Token format: base64url(iv + ciphertext + authTag)
+ * Payload: JSON { challenge, userId?, type, exp }
+ *
+ * Security properties:
+ * - AES-256-GCM provides authenticated encryption (confidentiality + integrity)
+ * - 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)
+ */
+import { createCipheriv, createDecipheriv, randomBytes, createHmac } from 'crypto';
+const ALG = 'aes-256-gcm';
+const IV_LEN = 12;
+const TAG_LEN = 16;
+/**
+ * Derive a 32-byte encryption key from a secret string.
+ * Uses HMAC-SHA256 with a fixed context label (domain separation).
+ */
+function deriveKey(secret) {
+    return createHmac('sha256', 'passkey-kit-challenge-key')
+        .update(secret)
+        .digest();
+}
+/**
+ * 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');
+}
+/**
+ * Decrypt and verify a challenge token. Returns null if invalid/expired.
+ */
+export function openChallengeToken(token, 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
+        if (Date.now() > payload.exp)
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/esm/express-routes.js

@@ -0,0 +1,127 @@
+/**
+ * Ready-made Express routes for passkey registration and authentication.
+ *
+ * @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.
+ *
+ * Usage:
+ *   const routes = createExpressRoutes(passkeyServer, { getUserInfo });
+ *   app.use('/api/auth/passkey', routes);
+ */
+import { Router } from 'express';
+/**
+ * Create Express router with passkey registration and authentication routes.
+ *
+ * Routes:
+ *   POST /register/options   — Get registration challenge options
+ *   POST /register/verify    — Verify registration response
+ *   POST /authenticate/options — Get authentication challenge options
+ *   POST /authenticate/verify  — Verify authentication response
+ */
+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' });
+                return;
+            }
+            const user = await config.getUserInfo(userId);
+            if (!user) {
+                res.status(404).json({ error: 'User not found' });
+                return;
+            }
+            const options = await server.generateRegistrationOptions(user, {
+                authenticatorAttachment,
+                residentKey,
+                userVerification,
+            });
+            res.json(options);
+        }
+        catch (err) {
+            console.error('[passkey-kit] Registration options error:', err);
+            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' });
+                return;
+            }
+            const result = await server.verifyRegistration(userId, response, credentialName, challengeToken);
+            if (config.onRegistrationSuccess) {
+                await config.onRegistrationSuccess(userId, result.credential.credentialId);
+            }
+            res.json({
+                verified: result.verified,
+                credentialId: result.credential.credentialId,
+                credentialName: result.credential.name,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Verification failed';
+            console.error('[passkey-kit] Registration verify error:', err);
+            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 { options, sessionKey, challengeToken } = await server.generateAuthenticationOptions(userId, { userVerification });
+            res.json({ options, sessionKey, challengeToken });
+        }
+        catch (err) {
+            console.error('[passkey-kit] Authentication options error:', err);
+            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' });
+                return;
+            }
+            const result = await server.verifyAuthentication(sessionKey, response);
+            let extra = {};
+            if (config.onAuthenticationSuccess) {
+                extra = await config.onAuthenticationSuccess(result.userId, result.credentialId);
+            }
+            res.json({
+                verified: result.verified,
+                userId: result.userId,
+                credentialId: result.credentialId,
+                ...extra,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Verification failed';
+            console.error('[passkey-kit] Authentication verify error:', err);
+            res.status(400).json({ error: message });
+        }
+    });
+    return router;
+}

package/dist/esm/index.js

@@ -0,0 +1,18 @@
+/**
+ * passkey-kit-server
+ *
+ * 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).
+ */
+export { PasskeyServer } from './passkey-server.js';
+export { hashPassword, verifyPassword, needsRehash } from './password.js';
+export { sealChallengeToken, openChallengeToken } from './challenge-token.js';
+export { MemoryChallengeStore, MemoryCredentialStore, FileChallengeStore, FileCredentialStore, } from './stores.js';

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/passkey-server.js

@@ -0,0 +1,241 @@
+/**
+ * PasskeyServer — core WebAuthn server-side logic.
+ *
+ * @ai_context All challenge generation and attestation/assertion verification
+ * happens here. The client NEVER generates challenges — that's the key security
+ * fix over the old insecure pattern.
+ *
+ * Supports two challenge persistence modes:
+ * 1. **Stateless** (default): Challenge is encrypted into a signed token returned
+ *    to the client. No server-side state required — works on Vercel, Cloudflare, etc.
+ * 2. **Stateful**: Challenge is stored in a ChallengeStore (memory, file, Redis, etc).
+ *    Use this when you need server-side challenge revocation.
+ *
+ * The mode is selected automatically: if `challengeStore` is provided in config,
+ * stateful mode is used. Otherwise, `encryptionKey` must be provided for stateless.
+ *
+ * Flow:
+ *   Registration: generateRegistrationOptions → client signs → verifyRegistration
+ *   Authentication: generateAuthenticationOptions → client signs → verifyAuthentication
+ */
+import { generateRegistrationOptions, verifyRegistrationResponse, generateAuthenticationOptions, verifyAuthenticationResponse, } from '@simplewebauthn/server';
+import { isoBase64URL } from '@simplewebauthn/server/helpers';
+import { sealChallengeToken, openChallengeToken } from './challenge-token.js';
+const DEFAULT_CHALLENGE_TTL = 5 * 60 * 1000; // 5 minutes
+export class PasskeyServer {
+    rpName;
+    rpId;
+    allowedOrigins;
+    challengeStore;
+    credentialStore;
+    challengeTTL;
+    encryptionKey;
+    constructor(config) {
+        this.rpName = config.rpName;
+        this.rpId = config.rpId;
+        this.allowedOrigins = config.allowedOrigins;
+        this.challengeStore = config.challengeStore;
+        this.credentialStore = config.credentialStore;
+        this.challengeTTL = config.challengeTTL ?? DEFAULT_CHALLENGE_TTL;
+        this.encryptionKey = config.encryptionKey;
+        if (!this.challengeStore && !this.encryptionKey) {
+            throw new Error('passkey-kit: Provide either `challengeStore` (stateful) or `encryptionKey` (stateless). ' +
+                'For serverless, set encryptionKey to a random 32+ character secret.');
+        }
+    }
+    /**
+     * Step 1 of registration: Generate options for the client.
+     * Returns PublicKeyCredentialCreationOptions (JSON-serializable)
+     * plus a `challengeToken` for stateless verification.
+     */
+    async generateRegistrationOptions(user, opts) {
+        const existingCredentials = await this.credentialStore.getByUserId(user.id);
+        const options = await generateRegistrationOptions({
+            rpName: this.rpName,
+            rpID: this.rpId,
+            userName: user.name,
+            userDisplayName: user.displayName ?? user.name,
+            userID: new TextEncoder().encode(user.id),
+            attestationType: 'none',
+            excludeCredentials: existingCredentials.map(c => ({
+                id: c.credentialId,
+                transports: c.transports,
+            })),
+            authenticatorSelection: {
+                authenticatorAttachment: opts?.authenticatorAttachment,
+                residentKey: opts?.residentKey ?? 'preferred',
+                userVerification: opts?.userVerification ?? 'preferred',
+            },
+        });
+        let challengeToken;
+        if (this.challengeStore) {
+            // Stateful: persist challenge in store
+            await this.challengeStore.save(user.id, {
+                challenge: options.challenge,
+                userId: user.id,
+                expiresAt: Date.now() + this.challengeTTL,
+                type: 'registration',
+            });
+        }
+        else {
+            // Stateless: encrypt challenge into token
+            challengeToken = sealChallengeToken({
+                challenge: options.challenge,
+                userId: user.id,
+                type: 'registration',
+                exp: Date.now() + this.challengeTTL,
+            }, this.encryptionKey);
+        }
+        return { ...options, challengeToken };
+    }
+    /**
+     * Step 2 of registration: Verify the client's attestation response.
+     *
+     * @param userId - User ID
+     * @param response - WebAuthn attestation response from the browser
+     * @param credentialName - Human-readable name for this credential
+     * @param challengeToken - The opaque token from step 1 (stateless mode)
+     */
+    async verifyRegistration(userId, response, credentialName, challengeToken) {
+        let expectedChallenge;
+        if (this.challengeStore) {
+            const storedChallenge = await this.challengeStore.consume(userId);
+            if (!storedChallenge)
+                throw new Error('Challenge not found or expired');
+            if (storedChallenge.type !== 'registration')
+                throw new Error('Challenge type mismatch');
+            if (Date.now() > storedChallenge.expiresAt)
+                throw new Error('Challenge expired');
+            expectedChallenge = storedChallenge.challenge;
+        }
+        else {
+            if (!challengeToken)
+                throw new Error('challengeToken is required in stateless mode');
+            const payload = openChallengeToken(challengeToken, this.encryptionKey);
+            if (!payload)
+                throw new Error('Invalid or expired challenge token');
+            if (payload.type !== 'registration')
+                throw new Error('Challenge type mismatch');
+            if (payload.userId !== userId)
+                throw new Error('Challenge userId mismatch');
+            expectedChallenge = payload.challenge;
+        }
+        const verification = await verifyRegistrationResponse({
+            response,
+            expectedChallenge,
+            expectedOrigin: this.allowedOrigins,
+            expectedRPID: this.rpId,
+        });
+        if (!verification.verified || !verification.registrationInfo) {
+            throw new Error('Registration verification failed');
+        }
+        const { credential } = verification.registrationInfo;
+        const storedCredential = {
+            credentialId: credential.id,
+            publicKey: isoBase64URL.fromBuffer(credential.publicKey),
+            counter: credential.counter,
+            transports: response.response.transports ?? [],
+            name: credentialName ?? 'Passkey',
+            registeredAt: new Date().toISOString(),
+            userId,
+        };
+        await this.credentialStore.save(storedCredential);
+        return { credential: storedCredential, verified: true };
+    }
+    /**
+     * Step 1 of authentication: Generate options for the client.
+     * If userId is provided, only that user's credentials are allowed.
+     * If not provided, uses discoverable credentials (resident keys).
+     */
+    async generateAuthenticationOptions(userId, opts) {
+        let allowCredentials;
+        if (userId) {
+            const credentials = await this.credentialStore.getByUserId(userId);
+            allowCredentials = credentials.map(c => ({
+                id: c.credentialId,
+                transports: c.transports,
+            }));
+        }
+        const options = await generateAuthenticationOptions({
+            rpID: this.rpId,
+            allowCredentials,
+            userVerification: opts?.userVerification ?? 'preferred',
+        });
+        let sessionKey;
+        let challengeToken;
+        if (this.challengeStore) {
+            // Stateful: persist challenge
+            sessionKey = userId ?? `auth:${options.challenge}`;
+            await this.challengeStore.save(sessionKey, {
+                challenge: options.challenge,
+                userId,
+                expiresAt: Date.now() + this.challengeTTL,
+                type: 'authentication',
+            });
+        }
+        else {
+            // Stateless: encrypt into token (sessionKey IS the token)
+            challengeToken = sealChallengeToken({
+                challenge: options.challenge,
+                userId,
+                type: 'authentication',
+                exp: Date.now() + this.challengeTTL,
+            }, this.encryptionKey);
+            sessionKey = challengeToken;
+        }
+        return { options, sessionKey, challengeToken };
+    }
+    /**
+     * Step 2 of authentication: Verify the client's assertion response.
+     */
+    async verifyAuthentication(sessionKey, response) {
+        let expectedChallenge;
+        if (this.challengeStore) {
+            const storedChallenge = await this.challengeStore.consume(sessionKey);
+            if (!storedChallenge)
+                throw new Error('Challenge not found or expired');
+            if (storedChallenge.type !== 'authentication')
+                throw new Error('Challenge type mismatch');
+            if (Date.now() > storedChallenge.expiresAt)
+                throw new Error('Challenge expired');
+            expectedChallenge = storedChallenge.challenge;
+        }
+        else {
+            // In stateless mode, sessionKey IS the challengeToken
+            const payload = openChallengeToken(sessionKey, this.encryptionKey);
+            if (!payload)
+                throw new Error('Invalid or expired challenge token');
+            if (payload.type !== 'authentication')
+                throw new Error('Challenge type mismatch');
+            expectedChallenge = payload.challenge;
+        }
+        const credentialId = response.id;
+        const credential = await this.credentialStore.getByCredentialId(credentialId);
+        if (!credential) {
+            throw new Error('Credential not found');
+        }
+        const verification = await verifyAuthenticationResponse({
+            response,
+            expectedChallenge,
+            expectedOrigin: this.allowedOrigins,
+            expectedRPID: this.rpId,
+            credential: {
+                id: credential.credentialId,
+                publicKey: isoBase64URL.toBuffer(credential.publicKey),
+                counter: credential.counter,
+                transports: credential.transports,
+            },
+        });
+        if (!verification.verified) {
+            throw new Error('Authentication verification failed');
+        }
+        const newCounter = verification.authenticationInfo.newCounter;
+        await this.credentialStore.updateCounter(credentialId, newCounter);
+        return {
+            credentialId,
+            userId: credential.userId,
+            verified: true,
+            newCounter,
+        };
+    }
+}

package/dist/esm/password-argon2.js

@@ -0,0 +1,30 @@
+/**
+ * Password hashing using argon2id (native C++ bindings).
+ *
+ * @ai_context This is an OPTIONAL subpath export for users who:
+ * 1. Run on a platform with native module support (Node.js, not serverless edge)
+ * 2. Want the absolute strongest password hash (argon2id > scrypt)
+ *
+ * Import: import { hashPassword, verifyPassword } from 'passkey-kit-server/argon2'
+ *
+ * Most users should use the default scrypt export which works everywhere.
+ */
+import argon2 from 'argon2';
+export async function hashPassword(password, options) {
+    return argon2.hash(password, {
+        type: argon2.argon2id,
+        memoryCost: options?.memoryCost ?? 65536,
+        timeCost: options?.timeCost ?? 3,
+        parallelism: options?.parallelism ?? 4,
+    });
+}
+export async function verifyPassword(storedHash, password) {
+    return argon2.verify(storedHash, password);
+}
+export function needsRehash(storedHash, options) {
+    return argon2.needsRehash(storedHash, {
+        memoryCost: options?.memoryCost ?? 65536,
+        timeCost: options?.timeCost ?? 3,
+        parallelism: options?.parallelism ?? 4,
+    });
+}

package/dist/esm/password.js

@@ -0,0 +1,81 @@
+/**
+ * Password hashing using scrypt (pure JavaScript via @noble/hashes).
+ *
+ * @ai_context Replaces the native argon2 module as the default.
+ * @noble/hashes is audited by Trail of Bits and works on every runtime:
+ * Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge, browser.
+ *
+ * For users who want argon2id (requires native bindings), see the
+ * `passkey-kit-server/argon2` subpath export.
+ *
+ * Output format is PHC-like:
+ *   $scrypt$ln=17,r=8,p=1$<base64salt>$<base64hash>
+ */
+import { scrypt as scryptSync } from '@noble/hashes/scrypt';
+import { randomBytes } from 'crypto';
+/** Default scrypt parameters (OWASP recommendations for interactive login) */
+const DEFAULTS = {
+    N: 2 ** 17, // 131072 — CPU/memory cost
+    r: 8, // Block size
+    p: 1, // Parallelism
+    dkLen: 32, // Output key length
+    saltLen: 16, // Salt length
+};
+/**
+ * Hash a password using scrypt.
+ * Returns a PHC-format string: $scrypt$ln=<log2N>,r=<r>,p=<p>$<salt>$<hash>
+ */
+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 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');
+    return `$scrypt$ln=${ln},r=${r},p=${p}$${saltB64}$${hashB64}`;
+}
+/**
+ * Verify a password against a stored scrypt hash.
+ */
+export async function verifyPassword(storedHash, password) {
+    const parsed = parsePhc(storedHash);
+    if (!parsed)
+        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);
+}
+/**
+ * Check if a hash needs rehashing (params differ from current defaults).
+ */
+export function needsRehash(storedHash, options) {
+    const parsed = parsePhc(storedHash);
+    if (!parsed)
+        return true;
+    const N = options?.N ?? DEFAULTS.N;
+    const r = options?.r ?? DEFAULTS.r;
+    const p = options?.p ?? DEFAULTS.p;
+    return parsed.N !== N || parsed.r !== r || parsed.p !== p;
+}
+// --- Internal helpers ---
+function parsePhc(phc) {
+    // $scrypt$ln=17,r=8,p=1$<salt>$<hash>
+    const match = phc.match(/^\$scrypt\$ln=(\d+),r=(\d+),p=(\d+)\$([A-Za-z0-9+/=]+)\$([A-Za-z0-9+/=]+)$/);
+    if (!match)
+        return null;
+    return {
+        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'),
+    };
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const { timingSafeEqual: tse } = require('crypto');
+    return tse(a, b);
+}