@passkeykit/server 2.0.0

package/dist/esm/stores.js

@@ -0,0 +1,147 @@
+/**
+ * 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 { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { dirname } from 'path';
+// ============================================================
+// In-Memory Stores (good for development and single-process)
+// ============================================================
+export 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;
+    }
+}
+export 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);
+    }
+}
+// ============================================================
+// 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).
+ */
+export class FileChallengeStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        const dir = dirname(filePath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+    }
+    load() {
+        try {
+            return JSON.parse(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];
+        }
+        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;
+    }
+}
+/**
+ * File-based credential store. Credentials stored in a JSON array file.
+ */
+export class FileCredentialStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        const dir = dirname(filePath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+    }
+    load() {
+        try {
+            return JSON.parse(readFileSync(this.filePath, 'utf-8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    persist(data) {
+        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);
+    }
+}

package/dist/esm/types.js

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

package/dist/express-routes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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';
+import { PasskeyServer } from './passkey-server.js';
+import type { UserInfo } from './types.js';
+export interface ExpressRoutesConfig {
+    /**
+     * Resolve a user ID to UserInfo. Called during registration to get
+     * the user's name/displayName for the WebAuthn ceremony.
+     * Return null if user not found.
+     */
+    getUserInfo: (userId: string) => Promise<UserInfo | null>;
+    /**
+     * Called after successful registration. Use this to update your user
+     * record (e.g., mark as activated, store credential reference).
+     */
+    onRegistrationSuccess?: (userId: string, credentialId: string) => Promise<void>;
+    /**
+     * Called after successful authentication. Use this to create a session,
+     * JWT, or whatever your app uses for auth state.
+     * Return an object that will be merged into the response JSON.
+     */
+    onAuthenticationSuccess?: (userId: string, credentialId: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * 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 declare function createExpressRoutes(server: PasskeyServer, config: ExpressRoutesConfig): Router;

package/dist/express-routes.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * 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);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpressRoutes = createExpressRoutes;
+const express_1 = require("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
+ */
+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' });
+                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/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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';
+export type { PasskeyServerConfig, StoredCredential, StoredChallenge, ChallengeStore, CredentialStore, RegistrationResult, AuthenticationResult, UserInfo, } from './types.js';

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileCredentialStore = exports.FileChallengeStore = exports.MemoryCredentialStore = exports.MemoryChallengeStore = exports.openChallengeToken = exports.sealChallengeToken = exports.needsRehash = exports.verifyPassword = exports.hashPassword = exports.PasskeyServer = void 0;
+var passkey_server_js_1 = require("./passkey-server.js");
+Object.defineProperty(exports, "PasskeyServer", { enumerable: true, get: function () { return passkey_server_js_1.PasskeyServer; } });
+var password_js_1 = require("./password.js");
+Object.defineProperty(exports, "hashPassword", { enumerable: true, get: function () { return password_js_1.hashPassword; } });
+Object.defineProperty(exports, "verifyPassword", { enumerable: true, get: function () { return password_js_1.verifyPassword; } });
+Object.defineProperty(exports, "needsRehash", { enumerable: true, get: function () { return password_js_1.needsRehash; } });
+var challenge_token_js_1 = require("./challenge-token.js");
+Object.defineProperty(exports, "sealChallengeToken", { enumerable: true, get: function () { return challenge_token_js_1.sealChallengeToken; } });
+Object.defineProperty(exports, "openChallengeToken", { enumerable: true, get: function () { return challenge_token_js_1.openChallengeToken; } });
+var stores_js_1 = require("./stores.js");
+Object.defineProperty(exports, "MemoryChallengeStore", { enumerable: true, get: function () { return stores_js_1.MemoryChallengeStore; } });
+Object.defineProperty(exports, "MemoryCredentialStore", { enumerable: true, get: function () { return stores_js_1.MemoryCredentialStore; } });
+Object.defineProperty(exports, "FileChallengeStore", { enumerable: true, get: function () { return stores_js_1.FileChallengeStore; } });
+Object.defineProperty(exports, "FileCredentialStore", { enumerable: true, get: function () { return stores_js_1.FileCredentialStore; } });

package/dist/passkey-server.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 type { RegistrationResponseJSON, AuthenticationResponseJSON } from '@simplewebauthn/server';
+import type { PasskeyServerConfig, RegistrationResult, AuthenticationResult, UserInfo } from './types.js';
+export declare class PasskeyServer {
+    private rpName;
+    private rpId;
+    private allowedOrigins;
+    private challengeStore?;
+    private credentialStore;
+    private challengeTTL;
+    private encryptionKey?;
+    constructor(config: PasskeyServerConfig);
+    /**
+     * Step 1 of registration: Generate options for the client.
+     * Returns PublicKeyCredentialCreationOptions (JSON-serializable)
+     * plus a `challengeToken` for stateless verification.
+     */
+    generateRegistrationOptions(user: UserInfo, opts?: {
+        authenticatorAttachment?: 'platform' | 'cross-platform';
+        residentKey?: 'required' | 'preferred' | 'discouraged';
+        userVerification?: 'required' | 'preferred' | 'discouraged';
+    }): Promise<{
+        challengeToken: string | undefined;
+        rp: import("@simplewebauthn/server").PublicKeyCredentialRpEntity;
+        user: import("@simplewebauthn/server").PublicKeyCredentialUserEntityJSON;
+        challenge: import("@simplewebauthn/server").Base64URLString;
+        pubKeyCredParams: import("@simplewebauthn/server").PublicKeyCredentialParameters[];
+        timeout?: number;
+        excludeCredentials?: import("@simplewebauthn/server").PublicKeyCredentialDescriptorJSON[];
+        authenticatorSelection?: import("@simplewebauthn/server").AuthenticatorSelectionCriteria;
+        hints?: import("@simplewebauthn/server").PublicKeyCredentialHint[];
+        attestation?: import("@simplewebauthn/server").AttestationConveyancePreference;
+        attestationFormats?: import("@simplewebauthn/server").AttestationFormat[];
+        extensions?: import("@simplewebauthn/server").AuthenticationExtensionsClientInputs;
+    }>;
+    /**
+     * 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)
+     */
+    verifyRegistration(userId: string, response: RegistrationResponseJSON, credentialName?: string, challengeToken?: string): Promise<RegistrationResult>;
+    /**
+     * 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).
+     */
+    generateAuthenticationOptions(userId?: string, opts?: {
+        userVerification?: 'required' | 'preferred' | 'discouraged';
+    }): Promise<{
+        options: import("@simplewebauthn/server").PublicKeyCredentialRequestOptionsJSON;
+        sessionKey: string;
+        challengeToken: string | undefined;
+    }>;
+    /**
+     * Step 2 of authentication: Verify the client's assertion response.
+     */
+    verifyAuthentication(sessionKey: string, response: AuthenticationResponseJSON): Promise<AuthenticationResult>;
+}