@passkeykit/server 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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).
+ */
+import type { AuthenticatorTransportFuture } from '@simplewebauthn/server';
+/** Configuration for PasskeyServer */
+export interface PasskeyServerConfig {
+    /** Relying Party name shown to users (e.g. "MovieBox", "SafeHarbor") */
+    rpName: string;
+    /** Relying Party ID — must be a valid domain (e.g. "movies.danieltech.dev") */
+    rpId: string;
+    /** Allowed origins for WebAuthn (e.g. ["https://movies.danieltech.dev"]) */
+    allowedOrigins: string[];
+    /**
+     * Challenge store implementation (stateful mode).
+     * If omitted, stateless mode is used instead (requires `encryptionKey`).
+     */
+    challengeStore?: ChallengeStore;
+    /** Credential store implementation */
+    credentialStore: CredentialStore;
+    /** Challenge TTL in ms (default: 5 minutes) */
+    challengeTTL?: number;
+    /**
+     * Secret key for stateless challenge tokens (AES-256-GCM).
+     * Required when `challengeStore` is not provided.
+     * Must be at least 32 characters. Derive from env: process.env.PASSKEY_SECRET
+     */
+    encryptionKey?: string;
+}
+/** A stored WebAuthn credential (persisted per-user) */
+export interface StoredCredential {
+    /** Base64URL-encoded credential ID */
+    credentialId: string;
+    /** Base64URL-encoded public key */
+    publicKey: string;
+    /** Signature counter for replay protection */
+    counter: number;
+    /** Credential transports (for allowCredentials hints) */
+    transports?: AuthenticatorTransportFuture[];
+    /** Human-readable name for this credential */
+    name?: string;
+    /** ISO timestamp of registration */
+    registeredAt: string;
+    /** User ID this credential belongs to */
+    userId: string;
+}
+/** A stored challenge (short-lived, for verification) */
+export interface StoredChallenge {
+    /** The challenge string */
+    challenge: string;
+    /** User ID (if applicable, e.g. during registration) */
+    userId?: string;
+    /** Expiry timestamp (ms since epoch) */
+    expiresAt: number;
+    /** 'registration' or 'authentication' */
+    type: 'registration' | 'authentication';
+}
+/** User info passed during registration */
+export interface UserInfo {
+    id: string;
+    name: string;
+    displayName?: string;
+}
+/** Result of successful registration */
+export interface RegistrationResult {
+    credential: StoredCredential;
+    verified: boolean;
+}
+/** Result of successful authentication */
+export interface AuthenticationResult {
+    credentialId: string;
+    userId: string;
+    verified: boolean;
+    newCounter: number;
+}
+/**
+ * Challenge store abstraction — apps implement this for their storage backend.
+ * Challenges are short-lived (5 min default) and must be cleaned up.
+ */
+export interface ChallengeStore {
+    /** Save a challenge. Key can be any unique string (userId or random token). */
+    save(key: string, challenge: StoredChallenge): Promise<void>;
+    /** Retrieve and delete a challenge (one-time use). Returns null if expired/missing. */
+    consume(key: string): Promise<StoredChallenge | null>;
+}
+/**
+ * Credential store abstraction — apps implement this for their storage backend.
+ */
+export interface CredentialStore {
+    /** Save a new credential */
+    save(credential: StoredCredential): Promise<void>;
+    /** Get all credentials for a user */
+    getByUserId(userId: string): Promise<StoredCredential[]>;
+    /** Get a credential by its ID */
+    getByCredentialId(credentialId: string): Promise<StoredCredential | null>;
+    /** Update counter after successful authentication */
+    updateCounter(credentialId: string, newCounter: number): Promise<void>;
+    /** Delete a credential */
+    delete(credentialId: string): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@passkeykit/server",
+  "version": "2.0.0",
+  "description": "Server-side WebAuthn passkey verification \u2014 stateless or stateful, pure JS, works on serverless",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./express": {
+      "import": "./dist/esm/express-routes.js",
+      "require": "./dist/express-routes.js",
+      "types": "./dist/express-routes.d.ts"
+    },
+    "./argon2": {
+      "import": "./dist/esm/password-argon2.js",
+      "require": "./dist/password-argon2.js",
+      "types": "./dist/password-argon2.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.esm.json && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "webauthn",
+    "passkey",
+    "fido2",
+    "authentication",
+    "serverless",
+    "scrypt"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@simplewebauthn/server": "^13.1.1",
+    "@noble/hashes": "^1.7.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0",
+    "argon2": "^0.41.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "argon2": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}