@passkeykit/server 2.0.0

package/dist/passkey-server.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PasskeyServer = void 0;
+const server_1 = require("@simplewebauthn/server");
+const helpers_1 = require("@simplewebauthn/server/helpers");
+const challenge_token_js_1 = require("./challenge-token.js");
+const DEFAULT_CHALLENGE_TTL = 5 * 60 * 1000; // 5 minutes
+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 (0, server_1.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 = (0, challenge_token_js_1.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 = (0, challenge_token_js_1.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 (0, server_1.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: helpers_1.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 (0, server_1.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 = (0, challenge_token_js_1.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 = (0, challenge_token_js_1.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 (0, server_1.verifyAuthenticationResponse)({
+            response,
+            expectedChallenge,
+            expectedOrigin: this.allowedOrigins,
+            expectedRPID: this.rpId,
+            credential: {
+                id: credential.credentialId,
+                publicKey: helpers_1.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,
+        };
+    }
+}
+exports.PasskeyServer = PasskeyServer;

package/dist/password-argon2.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export declare function hashPassword(password: string, options?: {
+    memoryCost?: number;
+    timeCost?: number;
+    parallelism?: number;
+}): Promise<string>;
+export declare function verifyPassword(storedHash: string, password: string): Promise<boolean>;
+export declare function needsRehash(storedHash: string, options?: {
+    memoryCost?: number;
+    timeCost?: number;
+    parallelism?: number;
+}): boolean;

package/dist/password-argon2.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashPassword = hashPassword;
+exports.verifyPassword = verifyPassword;
+exports.needsRehash = needsRehash;
+const argon2_1 = __importDefault(require("argon2"));
+async function hashPassword(password, options) {
+    return argon2_1.default.hash(password, {
+        type: argon2_1.default.argon2id,
+        memoryCost: options?.memoryCost ?? 65536,
+        timeCost: options?.timeCost ?? 3,
+        parallelism: options?.parallelism ?? 4,
+    });
+}
+async function verifyPassword(storedHash, password) {
+    return argon2_1.default.verify(storedHash, password);
+}
+function needsRehash(storedHash, options) {
+    return argon2_1.default.needsRehash(storedHash, {
+        memoryCost: options?.memoryCost ?? 65536,
+        timeCost: options?.timeCost ?? 3,
+        parallelism: options?.parallelism ?? 4,
+    });
+}

package/dist/password.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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>
+ */
+export interface ScryptOptions {
+    /** CPU/memory cost parameter (power of 2). Default: 2^17 */
+    N?: number;
+    /** Block size. Default: 8 */
+    r?: number;
+    /** Parallelism. Default: 1 */
+    p?: number;
+}
+/**
+ * Hash a password using scrypt.
+ * Returns a PHC-format string: $scrypt$ln=<log2N>,r=<r>,p=<p>$<salt>$<hash>
+ */
+export declare function hashPassword(password: string, options?: ScryptOptions): Promise<string>;
+/**
+ * Verify a password against a stored scrypt hash.
+ */
+export declare function verifyPassword(storedHash: string, password: string): Promise<boolean>;
+/**
+ * Check if a hash needs rehashing (params differ from current defaults).
+ */
+export declare function needsRehash(storedHash: string, options?: ScryptOptions): boolean;

package/dist/password.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * 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>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+    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>
+ */
+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 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');
+    return `$scrypt$ln=${ln},r=${r},p=${p}$${saltB64}$${hashB64}`;
+}
+/**
+ * Verify a password against a stored scrypt hash.
+ */
+async function verifyPassword(storedHash, password) {
+    const parsed = parsePhc(storedHash);
+    if (!parsed)
+        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);
+}
+/**
+ * Check if a hash needs rehashing (params differ from current defaults).
+ */
+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);
+}

package/dist/stores.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+import type { ChallengeStore, CredentialStore, StoredChallenge, StoredCredential } from './types.js';
+export declare class MemoryChallengeStore implements ChallengeStore {
+    private challenges;
+    save(key: string, challenge: StoredChallenge): Promise<void>;
+    consume(key: string): Promise<StoredChallenge | null>;
+}
+export declare class MemoryCredentialStore implements CredentialStore {
+    private credentials;
+    save(credential: StoredCredential): Promise<void>;
+    getByUserId(userId: string): Promise<StoredCredential[]>;
+    getByCredentialId(credentialId: string): Promise<StoredCredential | null>;
+    updateCounter(credentialId: string, newCounter: number): Promise<void>;
+    delete(credentialId: string): Promise<void>;
+}
+/**
+ * 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 {
+    private filePath;
+    constructor(filePath: string);
+    private load;
+    private persist;
+    save(key: string, challenge: StoredChallenge): Promise<void>;
+    consume(key: string): Promise<StoredChallenge | null>;
+}
+/**
+ * File-based credential store. Credentials stored in a JSON array file.
+ */
+export declare class FileCredentialStore implements CredentialStore {
+    private filePath;
+    constructor(filePath: string);
+    private load;
+    private persist;
+    save(credential: StoredCredential): Promise<void>;
+    getByUserId(userId: string): Promise<StoredCredential[]>;
+    getByCredentialId(credentialId: string): Promise<StoredCredential | null>;
+    updateCounter(credentialId: string, newCounter: number): Promise<void>;
+    delete(credentialId: string): Promise<void>;
+}

package/dist/stores.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileCredentialStore = exports.FileChallengeStore = exports.MemoryCredentialStore = exports.MemoryChallengeStore = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// ============================================================
+// In-Memory Stores (good for development and single-process)
+// ============================================================
+class MemoryChallengeStore {
+    challenges = new Map();
+    async save(key, challenge) {
+        this.challenges.set(key, challenge);
+        // Auto-cleanup expired challenges
+        setTimeout(() => this.challenges.delete(key), challenge.expiresAt - Date.now());
+    }
+    async consume(key) {
+        const challenge = this.challenges.get(key);
+        if (!challenge)
+            return null;
+        this.challenges.delete(key);
+        if (Date.now() > challenge.expiresAt)
+            return null;
+        return challenge;
+    }
+}
+exports.MemoryChallengeStore = MemoryChallengeStore;
+class MemoryCredentialStore {
+    credentials = [];
+    async save(credential) {
+        this.credentials.push(credential);
+    }
+    async getByUserId(userId) {
+        return this.credentials.filter(c => c.userId === userId);
+    }
+    async getByCredentialId(credentialId) {
+        return this.credentials.find(c => c.credentialId === credentialId) ?? null;
+    }
+    async updateCounter(credentialId, newCounter) {
+        const cred = this.credentials.find(c => c.credentialId === credentialId);
+        if (cred)
+            cred.counter = newCounter;
+    }
+    async delete(credentialId) {
+        this.credentials = this.credentials.filter(c => c.credentialId !== credentialId);
+    }
+}
+exports.MemoryCredentialStore = MemoryCredentialStore;
+// ============================================================
+// File-Based Stores (good for single-server, persistent)
+// ============================================================
+/**
+ * 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 {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        const dir = (0, path_1.dirname)(filePath);
+        if (!(0, fs_1.existsSync)(dir))
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    load() {
+        try {
+            return JSON.parse((0, fs_1.readFileSync)(this.filePath, 'utf-8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    persist(data) {
+        // Clean expired
+        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));
+    }
+    async save(key, challenge) {
+        const data = this.load();
+        data[key] = challenge;
+        this.persist(data);
+    }
+    async consume(key) {
+        const data = this.load();
+        const challenge = data[key];
+        if (!challenge)
+            return null;
+        delete data[key];
+        this.persist(data);
+        if (Date.now() > challenge.expiresAt)
+            return null;
+        return challenge;
+    }
+}
+exports.FileChallengeStore = FileChallengeStore;
+/**
+ * File-based credential store. Credentials stored in a JSON array file.
+ */
+class FileCredentialStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        const dir = (0, path_1.dirname)(filePath);
+        if (!(0, fs_1.existsSync)(dir))
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    load() {
+        try {
+            return JSON.parse((0, fs_1.readFileSync)(this.filePath, 'utf-8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    persist(data) {
+        (0, fs_1.writeFileSync)(this.filePath, JSON.stringify(data, null, 2));
+    }
+    async save(credential) {
+        const data = this.load();
+        data.push(credential);
+        this.persist(data);
+    }
+    async getByUserId(userId) {
+        return this.load().filter(c => c.userId === userId);
+    }
+    async getByCredentialId(credentialId) {
+        return this.load().find(c => c.credentialId === credentialId) ?? null;
+    }
+    async updateCounter(credentialId, newCounter) {
+        const data = this.load();
+        const cred = data.find(c => c.credentialId === credentialId);
+        if (cred) {
+            cred.counter = newCounter;
+            this.persist(data);
+        }
+    }
+    async delete(credentialId) {
+        const data = this.load().filter(c => c.credentialId !== credentialId);
+        this.persist(data);
+    }
+}
+exports.FileCredentialStore = FileCredentialStore;