@lastshotlabs/bunshot 0.0.16 → 0.0.19

package/README.md

@@ -155,6 +155,24 @@ const auth: AuthConfig = {
         clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
         redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/google/callback`,
       },
+      apple: {
+        clientId: process.env.APPLE_CLIENT_ID!,
+        teamId: process.env.APPLE_TEAM_ID!,
+        keyId: process.env.APPLE_KEY_ID!,
+        privateKey: process.env.APPLE_PRIVATE_KEY!,
+        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/apple/callback`,
+      },
+      microsoft: {
+        tenantId: process.env.MICROSOFT_TENANT_ID!,
+        clientId: process.env.MICROSOFT_CLIENT_ID!,
+        clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
+        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/microsoft/callback`,
+      },
+      github: {
+        clientId: process.env.GITHUB_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/github/callback`,
+      },
     },
   },
 };
@@ -721,8 +739,9 @@ The `/ws` endpoint is mounted automatically by `createServer`. No extra setup ne
 |---|---|
 | Upgrade / auth | Reads `auth-token` cookie → verifies JWT → checks session → sets `ws.data.userId` |
 | `open` | Logs connection, sends `{ event: "connected", id }` |
-| `message` | Handles room actions (see below), echoes everything else |
+| `message` | Checks message size (closes with 1009 if exceeds `maxMessageSize`), handles room actions (see below), drops non-room messages unless custom handler provided |
 | `close` | Clears `ws.data.rooms`, logs disconnection |
+| `maxMessageSize` | 65 536 bytes (64 KB) — configurable via `ws.maxMessageSize` |
 
 ### Socket data (`SocketData`)
 
@@ -769,7 +788,7 @@ With no type parameter, `SocketData` defaults to `{ id, userId, rooms }` — the
 
 ### Overriding the message handler
 
-Pass `ws.handler` to `createServer` to replace the default echo. Room action handling always runs first — your handler only receives non-room messages:
+Pass `ws.handler` to `createServer` to add custom message handling. Room action handling always runs first — your handler only receives non-room messages:
 
 ```ts
 await createServer({
@@ -1054,6 +1073,8 @@ router.put("/products/:id", userAuth, async (c) => {
 
 Only 2xx responses are cached. Non-2xx responses pass through uncached. Omit `ttl` to cache indefinitely — the entry will persist until explicitly busted with `bustCache`.
 
+**Header sanitization:** Security-sensitive response headers (`set-cookie`, `www-authenticate`, `authorization`, `x-csrf-token`, `proxy-authenticate`) are automatically stripped before caching to prevent session fixation or auth bypass via cached responses.
+
 ### Busting by pattern
 
 When cache keys include variable parts (e.g. query params), use `bustCachePattern` to invalidate an entire logical group at once. It runs against all four stores — Redis (via SCAN), Mongo (via regex), SQLite (via LIKE), and Memory (via regex) — in parallel:
@@ -1177,6 +1198,8 @@ await createServer({
       resendVerification: { windowMs: 60 * 60 * 1000, max: 3  }, // default: 3 attempts / hour (per user)
       forgotPassword:     { windowMs: 15 * 60 * 1000, max: 5  }, // default: 5 attempts / 15 min (per IP)
       resetPassword:      { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
+      mfaVerify:          { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
+      mfaResend:          { windowMs: 60 * 1000,      max: 5  }, // default: 5 attempts / minute (per IP)
       store: "redis",                       // default: "redis" when Redis is enabled, else "memory"
     },
     sessionPolicy: {                        // optional — session concurrency and metadata
@@ -1185,9 +1208,16 @@ await createServer({
       includeInactiveSessions: false,       // default: false — include expired/deleted sessions in GET /auth/sessions
       trackLastActive: false,               // default: false — update lastActiveAt on every auth'd request (adds one DB write)
     },
+    passwordPolicy: {                        // optional — password complexity rules (applies to register + reset, not login)
+      minLength: 8,                         // default: 8
+      requireLetter: true,                  // default: true — at least one a–z or A–Z
+      requireDigit: true,                   // default: true — at least one 0–9
+      requireSpecial: false,                // default: false — at least one non-alphanumeric character
+    },
     oauth: {
       providers: { google: { ... }, apple: { ... } }, // omit a provider to disable it
       postRedirect: "/dashboard",           // default: "/"
+      allowedRedirectUrls: ["https://myapp.com"], // optional — validate postRedirect against allowlist at startup
     },
     refreshTokens: {                        // optional — short-lived access + long-lived refresh tokens
       accessTokenExpiry: 900,               // default: 900 (15 min)
@@ -1238,6 +1268,16 @@ await createServer({
       fingerprintRateLimit: true,           // rate-limit by HTTP fingerprint (IP-rotation resistant). default: false
       blockList: ["198.51.100.0/24"],       // IPv4 CIDRs or exact IPs to block with 403. default: []
     },
+    headers: {                              // optional — additional security headers via Hono secureHeaders
+      contentSecurityPolicy: "default-src 'self'",  // CSP header value
+      permissionsPolicy: "camera=(), microphone=()", // Permissions-Policy header value
+    },
+    trustProxy: 1,                          // default: false — see "Trusted Proxy" section below
+    csrf: {                                 // opt-in CSRF protection for cookie-based auth
+      enabled: true,                        // default: false
+      exemptPaths: ["/webhooks/*"],         // additional exempt paths (OAuth callbacks auto-exempt)
+      checkOrigin: true,                    // validate Origin header against CORS origins (default: true)
+    },
   },
 
   // Extra middleware injected after identify, before route matching
@@ -1264,6 +1304,7 @@ await createServer({
     handler: { ... },                                  // override open/message/close/drain handlers
     upgradeHandler: async (req, server) => { ... },    // replace default cookie-JWT upgrade logic
     onRoomSubscribe(ws, room) { return true; },        // gate room subscriptions; can be async
+    maxMessageSize: 65_536,                            // default: 65536 (64 KB) — close connection on oversized messages
   },
 });
 ```
@@ -1511,6 +1552,69 @@ This two-step flow ensures the `onSend` callback actually delivers emails before
 - If email OTP is the only method: requires the account password in the `password` field
 - Disabling the last MFA method turns off MFA entirely
 
+### WebAuthn / Security Keys
+
+Hardware security keys (YubiKey, etc.) and platform authenticators (Touch ID, Windows Hello) via the WebAuthn/FIDO2 standard. Users can register multiple keys and use them as an MFA method alongside TOTP and email OTP.
+
+```ts
+await createServer({
+  auth: {
+    mfa: {
+      webauthn: {
+        rpId: "example.com",              // Relying Party ID — your domain
+        origin: "https://example.com",    // Expected origin(s)
+        rpName: "My App",                 // Display name (default: app name)
+        userVerification: "preferred",    // "required" | "preferred" | "discouraged"
+        timeout: 60000,                   // Ceremony timeout in ms (default: 60000)
+        strictSignCount: false,           // Reject when sign count goes backward (default: false — warn only)
+      },
+    },
+  },
+});
+```
+
+Requires `@simplewebauthn/server` peer dependency:
+
+```bash
+bun add @simplewebauthn/server
+```
+
+If `mfa.webauthn` is configured but the dependency is missing, the server fails fast at startup with a clear error message.
+
+#### Endpoints
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `POST /auth/mfa/webauthn/register-options` | userAuth | Generate registration options for `navigator.credentials.create()` |
+| `POST /auth/mfa/webauthn/register` | userAuth | Verify attestation and store credential |
+| `GET /auth/mfa/webauthn/credentials` | userAuth | List registered security keys |
+| `DELETE /auth/mfa/webauthn/credentials/:credentialId` | userAuth | Remove a single key |
+| `DELETE /auth/mfa/webauthn` | userAuth | Disable WebAuthn entirely |
+
+#### Registration flow
+
+1. `POST /auth/mfa/webauthn/register-options` → returns `{ options, registrationToken }`
+2. Client passes `options` to `navigator.credentials.create()` — browser prompts user to tap/scan key
+3. `POST /auth/mfa/webauthn/register` with `{ registrationToken, attestationResponse, name? }` → stores credential → returns recovery codes
+
+#### Login flow with WebAuthn
+
+1. `POST /auth/login` → `{ mfaRequired: true, mfaToken, mfaMethods: ["webauthn"], webauthnOptions: {...} }`
+2. Client passes `webauthnOptions` to `navigator.credentials.get()` — browser prompts for key
+3. `POST /auth/mfa/verify` with `{ mfaToken, webauthnResponse: {...} }` → creates session
+
+The `webauthnOptions` object follows the WebAuthn spec — pass it directly to `navigator.credentials.get()`. The `webauthnResponse` is the full result from the browser API.
+
+#### Credential removal
+
+- Removing a spare key (other keys or MFA methods still active): no extra verification needed
+- Removing the last credential of the last MFA method: requires TOTP code or password
+- `DELETE /auth/mfa/webauthn` (disable all): always requires verification
+
+#### Sign count validation
+
+WebAuthn authenticators increment a sign count on each use to detect cloned keys. By default, a backward count logs a warning but allows authentication. Set `strictSignCount: true` to reject authentication when the count goes backward.
+
 ### Account Deletion
 
 Enable `DELETE /auth/me` for user-initiated account deletion:
@@ -1547,6 +1651,25 @@ await createServer({
 
 When `queued: true`, deletion is enqueued as a BullMQ job instead of running synchronously. The endpoint returns `202 Accepted` immediately. With `gracePeriod > 0`, the user can cancel via `POST /auth/cancel-deletion`.
 
+### Password Policy
+
+Configure password complexity requirements via `auth.passwordPolicy`. The policy applies to registration and password reset — login uses `min(1)` intentionally to avoid locking out users registered under older/weaker policies.
+
+```ts
+await createServer({
+  auth: {
+    passwordPolicy: {
+      minLength: 10,          // default: 8
+      requireLetter: true,    // default: true — at least one a–z or A–Z
+      requireDigit: true,     // default: true — at least one 0–9
+      requireSpecial: true,   // default: false — at least one non-alphanumeric character
+    },
+  },
+});
+```
+
+When not configured, the default policy requires 8+ characters with at least one letter and one digit.
+
 ### Protecting routes
 
 ```ts
@@ -1651,6 +1774,9 @@ All built-in auth endpoints are rate-limited out of the box with sensible defaul
 | `POST /auth/resend-verification` | Identifier (email/username/phone) | Every attempt | 3 / hour |
 | `POST /auth/forgot-password` | IP address | Every attempt | 5 / 15 min |
 | `POST /auth/reset-password` | IP address | Every attempt | 10 / 15 min |
+| `POST /auth/refresh` | IP address | Every attempt | 30 / min |
+| `POST /auth/mfa/verify` | IP address | Every attempt | 10 / 15 min |
+| `POST /auth/mfa/resend` | IP address | Every attempt | 5 / min |
 
 Login is keyed by the **identifier being targeted** — an attacker rotating IPs to brute-force `alice@example.com` is blocked regardless of source IP. A successful login resets the counter so legitimate users aren't locked out.
 
@@ -1692,14 +1818,14 @@ Key formats: `login:{identifier}`, `register:{ip}`, `verify:{ip}`, `resend:{user
 `trackAttempt` and `isLimited` are exported so you can apply the same Redis-backed rate limiting to any route in your app. They use the same store configured via `auth.rateLimit.store`.
 
 ```ts
-import { trackAttempt, isLimited, bustAuthLimit } from "@lastshotlabs/bunshot";
+import { trackAttempt, isLimited, bustAuthLimit, getClientIp } from "@lastshotlabs/bunshot";
 
 // trackAttempt — increments the counter and returns true if now over the limit
 // isLimited    — checks without incrementing (read-only)
 // bustAuthLimit — resets a key (e.g. on success or admin unlock)
 
 router.post("/api/submit", async (c) => {
-  const ip = c.req.header("x-forwarded-for") ?? "unknown";
+  const ip = getClientIp(c);
   const key = `submit:${ip}`;
 
   if (await trackAttempt(key, { windowMs: 60 * 1000, max: 5 })) {
@@ -1782,6 +1908,49 @@ router.use("/api/submit", botProtection({ blockList: ["198.51.100.0/24"] }));
 
 ---
 
+### Trusted Proxy
+
+By default, Bunshot uses the socket-level IP address for all rate limiting and session metadata — the `X-Forwarded-For` header is **ignored entirely**. This prevents attackers from spoofing IPs to bypass rate limits.
+
+If your app runs behind a reverse proxy (nginx, Cloudflare, AWS ALB), configure `security.trustProxy` so the framework reads the real client IP from the `X-Forwarded-For` chain:
+
+```ts
+await createServer({
+  security: {
+    trustProxy: 1,   // trust 1 proxy hop — use the second-to-last IP in X-Forwarded-For
+    // trustProxy: 2, // behind 2 proxies (e.g. Cloudflare → ALB → app)
+    // trustProxy: false, // default — use socket IP, ignore XFF entirely
+  },
+});
+```
+
+The number represents how many trusted proxy hops sit between your app and the internet. With `trustProxy: N`, the framework takes the Nth-from-right entry in the `X-Forwarded-For` chain, skipping the N trusted proxies.
+
+All rate limiting (auth, general, bot protection) and session metadata (IP in `GET /auth/sessions`) use the centralized `getClientIp(c)` utility, which respects this setting. It's also exported for use in your own routes:
+
+```ts
+import { getClientIp } from "@lastshotlabs/bunshot";
+
+router.post("/api/action", async (c) => {
+  const ip = getClientIp(c); // respects trustProxy setting
+  // ...
+});
+```
+
+### JWT Secret Validation
+
+JWT secrets are validated on first use. The framework throws a clear error if:
+- The environment variable (`JWT_SECRET_DEV` or `JWT_SECRET_PROD`) is missing
+- The secret is shorter than 32 characters
+
+Generate a strong secret:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
+```
+
+---
+
 ### Setting a password after social login
 
 If a user signed up via Google or Apple and later wants to add a password, send an authenticated request to `POST /auth/set-password`:
@@ -1809,6 +1978,56 @@ const myAdapter: AuthAdapter = {
 };
 ```
 
+### CSRF Protection
+
+Opt-in via `security.csrf` — protects cookie-authenticated browser clients against cross-site request forgery attacks. Mobile apps and SPAs using header-based auth (`x-user-token`) are not affected and do not need CSRF.
+
+```ts
+await createServer({
+  security: {
+    csrf: {
+      enabled: true,
+      // exemptPaths: ["/webhooks/*"],  // additional exempt paths
+      // checkOrigin: true,             // validate Origin header (default: true)
+    },
+  },
+});
+```
+
+**How it works:**
+
+1. The first GET request sets a `csrf_token` cookie (non-HttpOnly, readable by JS)
+2. The token is HMAC-SHA256 signed with the JWT secret to prevent forgery
+3. For state-changing requests (POST/PUT/PATCH/DELETE), the client must send the cookie value back in the `x-csrf-token` header
+4. The middleware validates the signature and compares the header to the cookie using timing-safe comparison
+5. Requests without an auth cookie (`token`) skip validation — they are not vulnerable to CSRF
+
+The CSRF cookie is refreshed on login, register, MFA verify, and OAuth exchange. It is cleared on logout.
+
+**Client-side integration:**
+
+```js
+function getCsrfToken() {
+  return document.cookie
+    .split("; ")
+    .find(row => row.startsWith("csrf_token="))
+    ?.split("=")[1];
+}
+
+// Include on all state-changing requests
+fetch("/api/resource", {
+  method: "POST",
+  credentials: "include",
+  headers: {
+    "Content-Type": "application/json",
+    "X-CSRF-Token": getCsrfToken(),
+  },
+  body: JSON.stringify(data),
+});
+
+// After login, read the NEW csrf_token value (it's refreshed on auth state changes)
+```
+
 ---
 
 ## Roles
@@ -1983,6 +2202,10 @@ await createServer({
 
 These paths skip tenant resolution by default: `/health`, `/docs`, `/openapi.json`, `/auth/` (auth is global — all tenants share a user pool). Add more via `exemptPaths`.
 
+### `onResolve` is required in production
+
+When `tenancy` is configured without an `onResolve` callback, tenant IDs from headers/subdomains/paths are trusted without validation — a cross-tenant access risk. **In production (`NODE_ENV=production`), the server will refuse to start** if `onResolve` is missing. In development, a warning is logged instead.
+
 ### Accessing tenant in routes
 
 ```ts
@@ -2017,7 +2240,7 @@ When tenant context is present, rate limits and cache keys are automatically nam
 
 ## Social Login (OAuth)
 
-Pass `auth.oauth.providers` to `createServer` to enable Google and/or Apple sign-in. Routes are mounted automatically for each configured provider.
+Pass `auth.oauth.providers` to `createServer` to enable Google, Apple, Microsoft, and/or GitHub sign-in. Routes are mounted automatically for each configured provider.
 
 ```ts
 await createServer({
@@ -2039,6 +2262,17 @@ await createServer({
           privateKey: process.env.APPLE_PRIVATE_KEY!,   // PEM string
           redirectUri: "https://myapp.com/auth/apple/callback",
         },
+        microsoft: {
+          tenantId: process.env.MICROSOFT_TENANT_ID!,   // "common", "organizations", "consumers", or tenant GUID
+          clientId: process.env.MICROSOFT_CLIENT_ID!,
+          clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/microsoft/callback",
+        },
+        github: {
+          clientId: process.env.GITHUB_CLIENT_ID!,
+          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/github/callback",
+        },
       },
     },
   },
@@ -2051,22 +2285,77 @@ await createServer({
 |---|---|---|---|---|
 | Google | `GET /auth/google` | `GET /auth/google/callback` | `GET /auth/google/link` | `DELETE /auth/google/link` |
 | Apple | `GET /auth/apple` | `POST /auth/apple/callback` | `GET /auth/apple/link` | — |
+| Microsoft | `GET /auth/microsoft` | `GET /auth/microsoft/callback` | `GET /auth/microsoft/link` | `DELETE /auth/microsoft/link` |
+| GitHub | `GET /auth/github` | `GET /auth/github/callback` | `GET /auth/github/link` | `DELETE /auth/github/link` |
 
 > Apple sends its callback as a **POST** with form data. Your server must be publicly reachable and the redirect URI must be registered in the Apple developer console.
 
+> **Microsoft `tenantId` options:** `"common"` accepts any Microsoft account (personal + work/school), `"organizations"` accepts work/school accounts only, `"consumers"` accepts personal accounts only, or pass a specific tenant GUID to restrict to a single Azure AD tenant (recommended for company SSO).
+
+> **GitHub:** Create an OAuth App (not a GitHub App) at [github.com/settings/developers](https://github.com/settings/developers). The `user:email` scope is requested to retrieve the user's verified email address, since the primary `/user` endpoint may not return it for users with private email settings.
+
+Additionally, a shared code exchange endpoint is always mounted:
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /auth/oauth/exchange` | Exchange one-time authorization code for session token |
+
 ### Flow
 
-1. Client navigates to `GET /auth/google` (or `/auth/apple`)
+1. Client navigates to `GET /auth/google` (or `/auth/apple`, `/auth/microsoft`, `/auth/github`)
 2. Package redirects to the provider's OAuth page
 3. Provider redirects (or POSTs) back to the callback URL
 4. Package exchanges the code, fetches the user profile, and calls `authAdapter.findOrCreateByProvider`
-5. A session is created, the `auth-token` cookie is set, and the user is redirected to `auth.oauth.postRedirect`
+5. A session is created and a **one-time authorization code** is generated
+6. User is redirected to `auth.oauth.postRedirect?code=<one-time-code>`
+7. Client exchanges the code for a session token via `POST /auth/oauth/exchange`
+
+> **Security:** The JWT is never exposed in the redirect URL. The one-time code expires after 60 seconds and can only be used once, preventing token leakage via browser history, server logs, or referrer headers.
+
+#### Code exchange
+
+After the OAuth redirect, the client must exchange the one-time code for a session token:
+
+```ts
+// Client-side
+const res = await fetch("/auth/oauth/exchange", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ code: new URLSearchParams(location.search).get("code") }),
+});
+const { token, userId, email, refreshToken } = await res.json();
+```
+
+The exchange endpoint sets session cookies automatically for browser clients. Mobile/SPA clients can use the JSON response directly. Rate limited to 20 requests per minute per IP.
+
+| Field | Description |
+|---|---|
+| `token` | Session JWT |
+| `userId` | Authenticated user ID |
+| `email` | User email (if available) |
+| `refreshToken` | Refresh token (only when `auth.refreshTokens` is configured) |
+
+### Redirect URL validation
+
+Pass `auth.oauth.allowedRedirectUrls` to restrict where OAuth callbacks can redirect:
+
+```ts
+auth: {
+  oauth: {
+    postRedirect: "/dashboard",
+    allowedRedirectUrls: ["https://myapp.com", "https://staging.myapp.com"],
+    providers: { ... },
+  },
+}
+```
+
+When configured, the `postRedirect` value is validated against the allowlist at startup. If omitted, any redirect URL is accepted (not recommended for production).
 
 ### User storage
 
 The default `mongoAuthAdapter` stores social users in `AuthUser` with a `providerIds` field (e.g. `["google:1234567890"]`). If no existing provider key is found, a new account is created — emails are never auto-linked. To connect a social identity to an existing credential account the user must explicitly use the link flow below.
 
-**Email conflict handling:** If a user attempts to sign in via Google (or Apple) and the email returned by the provider already belongs to a credential-based account, `findOrCreateByProvider` throws `HttpError(409, ...)`. The OAuth callback catches this and redirects to `auth.oauth.postRedirect?error=<message>` so the client can display a helpful prompt (e.g. "An account with this email already exists — sign in with your password, then link Google from your account settings.").
+**Email conflict handling:** If a user attempts to sign in via Google (or Apple/Microsoft/GitHub) and the email returned by the provider already belongs to a credential-based account, `findOrCreateByProvider` throws `HttpError(409, ...)`. The OAuth callback catches this and redirects to `auth.oauth.postRedirect?error=<message>` so the client can display a helpful prompt (e.g. "An account with this email already exists — sign in with your password, then link Google from your account settings.").
 
 To support social login with a custom adapter, implement `findOrCreateByProvider`:
 
@@ -2083,11 +2372,13 @@ const myAdapter: AuthAdapter = {
 
 ### Linking a provider to an existing account
 
-A logged-in user can link their account to a Google or Apple identity by navigating to the link route. This is the only way to associate a social login with an existing credential account — email matching is intentionally not done automatically.
+A logged-in user can link their account to a Google, Apple, Microsoft, or GitHub identity by navigating to the link route. This is the only way to associate a social login with an existing credential account — email matching is intentionally not done automatically.
 
 ```
-GET /auth/google/link   (requires active session via cookie)
-GET /auth/apple/link    (requires active session via cookie)
+GET /auth/google/link      (requires active session via cookie)
+GET /auth/apple/link       (requires active session via cookie)
+GET /auth/microsoft/link   (requires active session via cookie)
+GET /auth/github/link      (requires active session via cookie)
 ```
 
 The link flow:
@@ -2113,10 +2404,12 @@ const myAdapter: AuthAdapter = {
 
 ### Unlinking a provider
 
-A logged-in user can remove a linked Google identity via:
+A logged-in user can remove a linked Google, Microsoft, or GitHub identity via:
 
 ```
-DELETE /auth/google/link   (requires active session via cookie)
+DELETE /auth/google/link      (requires active session via cookie)
+DELETE /auth/microsoft/link   (requires active session via cookie)
+DELETE /auth/github/link      (requires active session via cookie)
 ```
 
 Returns `204 No Content` on success. All `google:*` entries are removed from the user's `providerIds`.
@@ -2170,6 +2463,9 @@ bun add bullmq
 
 # MFA / TOTP
 bun add otpauth
+
+# MFA / WebAuthn (security keys, Touch ID, Windows Hello)
+bun add @simplewebauthn/server
 ```
 
 | Package | Required version | When you need it |
@@ -2177,7 +2473,8 @@ bun add otpauth
 | `mongoose` | `>=9.0 <10` | `db.auth: "mongo"`, `db.sessions: "mongo"`, or `db.cache: "mongo"` |
 | `ioredis` | `>=5.0 <6` | `db.redis: true` (the default), or any store set to `"redis"` |
 | `bullmq` | `>=5.0 <6` | Workers / queues |
-| `otpauth` | `>=9.0 <10` | `auth.mfa` configuration |
+| `otpauth` | `>=9.0 <10` | `auth.mfa` configuration (TOTP) |
+| `@simplewebauthn/server` | `>=10.0.0` | `auth.mfa.webauthn` configuration |
 
 If you're running fully on SQLite or memory (no Redis, no MongoDB), none of the optional peers are needed.
 
@@ -2454,7 +2751,8 @@ import {
   createVerificationToken, getVerificationToken, deleteVerificationToken,  // email verification tokens
   createResetToken, consumeResetToken, setPasswordResetStore,              // password reset tokens
   createMfaChallenge, consumeMfaChallenge, replaceMfaChallengeOtp, setMfaChallengeStore, // MFA challenge tokens
-  bustAuthLimit, trackAttempt, isLimited,          // auth rate limiting — use in custom routes or admin unlocks
+  storeOAuthCode, consumeOAuthCode, setOAuthCodeStore,               // OAuth one-time authorization codes
+  bustAuthLimit, trackAttempt, isLimited, clearMemoryRateLimitStore, // auth rate limiting — use in custom routes or admin unlocks
   buildFingerprint,                                // HTTP fingerprint hash (IP-independent) — use in custom bot detection logic
   sqliteAuthAdapter, setSqliteDb, startSqliteCleanup,  // SQLite backend (persisted)
   memoryAuthAdapter, clearMemoryStore,                 // in-memory backend (ephemeral)
@@ -2478,6 +2776,14 @@ import {
   requireVerifiedEmail,                           // blocks unverified email addresses
   cacheResponse, bustCache, bustCachePattern, setCacheStore,  // response caching (tenant-namespaced)
 
+  // Crypto utilities
+  timingSafeEqual,                                  // constant-time string comparison for secrets/hashes
+  sha256,                                           // SHA-256 hash helper
+
+  // IP / proxy utilities
+  getClientIp,                                      // centralized IP extraction — respects security.trustProxy setting
+  setTrustProxy,                                    // configure trust level (called automatically by createApp)
+
   // Utilities
   HttpError, log, validate, createRouter, createRoute,
   registerSchema, registerSchemas,                // named OpenAPI schema registration
@@ -2496,7 +2802,7 @@ import {
   type DbConfig, type AppMeta, type AuthConfig, type OAuthConfig, type SecurityConfig,
   type PrimaryField, type EmailVerificationConfig, type PasswordResetConfig,
   type RefreshTokenConfig, type MfaConfig, type MfaEmailOtpConfig, type JobsConfig,
-  type AccountDeletionConfig,
+  type AccountDeletionConfig, type PasswordPolicyConfig, type OAuthCodePayload,
   type SocketData, type WsConfig,
 } from "@lastshotlabs/bunshot";
 

package/dist/adapters/memoryAuth.d.ts

@@ -34,3 +34,6 @@ export declare const memoryConsumeResetToken: (hash: string) => {
     userId: string;
     email: string;
 } | null;
+import type { OAuthCodePayload } from "../lib/oauthCode";
+export declare const memoryStoreOAuthCode: (hash: string, payload: OAuthCodePayload, ttlSeconds: number) => void;
+export declare const memoryConsumeOAuthCode: (hash: string) => OAuthCodePayload | null;

package/dist/adapters/memoryAuth.js

@@ -1,5 +1,7 @@
 import { HttpError } from "../lib/HttpError";
 import { getPersistSessionMetadata, getIncludeInactiveSessions } from "../lib/appConfig";
+import { clearMemoryRateLimitStore } from "../lib/authRateLimit";
+import { clearMemoryMfaChallenges } from "../lib/mfaChallenge";
 const _users = new Map();
 const _byEmail = new Map();
 const _sessions = new Map(); // sessionId → session
@@ -9,6 +11,7 @@ const _oauthStates = new Map();
 const _cache = new Map();
 const _verificationTokens = new Map();
 const _resetTokens = new Map();
+const _oauthCodes = new Map();
 const _tenantRoles = new Map(); // "userId:tenantId" → roles
 /** Reset all in-memory state. Useful for test isolation. */
 export const clearMemoryStore = () => {
@@ -19,9 +22,12 @@ export const clearMemoryStore = () => {
     _refreshTokenIndex.clear();
     _tenantRoles.clear();
     _oauthStates.clear();
+    _oauthCodes.clear();
     _cache.clear();
     _verificationTokens.clear();
     _resetTokens.clear();
+    clearMemoryRateLimitStore();
+    clearMemoryMfaChallenges();
 };
 // ---------------------------------------------------------------------------
 // Auth adapter
@@ -41,7 +47,7 @@ export const memoryAuthAdapter = {
         if (_byEmail.has(normalised))
             throw new HttpError(409, "Email already registered");
         const id = crypto.randomUUID();
-        const user = { id, email: normalised, passwordHash, providerIds: [], roles: [], emailVerified: false, mfaSecret: null, mfaEnabled: false, recoveryCodes: [], mfaMethods: [] };
+        const user = { id, email: normalised, passwordHash, providerIds: [], roles: [], emailVerified: false, mfaSecret: null, mfaEnabled: false, recoveryCodes: [], mfaMethods: [], webauthnCredentials: [] };
         _users.set(id, user);
         _byEmail.set(normalised, id);
         return { id };
@@ -67,7 +73,7 @@ export const memoryAuthAdapter = {
         }
         const id = crypto.randomUUID();
         const email = profile.email ? profile.email.toLowerCase() : null;
-        const user = { id, email, passwordHash: null, providerIds: [key], roles: [], emailVerified: false, mfaSecret: null, mfaEnabled: false, recoveryCodes: [], mfaMethods: [] };
+        const user = { id, email, passwordHash: null, providerIds: [key], roles: [], emailVerified: false, mfaSecret: null, mfaEnabled: false, recoveryCodes: [], mfaMethods: [], webauthnCredentials: [] };
         _users.set(id, user);
         if (email)
             _byEmail.set(email, id);
@@ -188,6 +194,34 @@ export const memoryAuthAdapter = {
         if (user)
             user.mfaMethods = [...methods];
     },
+    async getWebAuthnCredentials(userId) {
+        return [...(_users.get(userId)?.webauthnCredentials ?? [])];
+    },
+    async addWebAuthnCredential(userId, credential) {
+        const user = _users.get(userId);
+        if (user)
+            user.webauthnCredentials.push({ ...credential });
+    },
+    async removeWebAuthnCredential(userId, credentialId) {
+        const user = _users.get(userId);
+        if (user)
+            user.webauthnCredentials = user.webauthnCredentials.filter((c) => c.credentialId !== credentialId);
+    },
+    async updateWebAuthnCredentialSignCount(userId, credentialId, signCount) {
+        const user = _users.get(userId);
+        if (!user)
+            return;
+        const cred = user.webauthnCredentials.find((c) => c.credentialId === credentialId);
+        if (cred)
+            cred.signCount = signCount;
+    },
+    async findUserByWebAuthnCredentialId(credentialId) {
+        for (const user of _users.values()) {
+            if (user.webauthnCredentials.some((c) => c.credentialId === credentialId))
+                return user.id;
+        }
+        return null;
+    },
     async getTenantRoles(userId, tenantId) {
         return _tenantRoles.get(`${userId}:${tenantId}`) ?? [];
     },
@@ -442,3 +476,15 @@ export const memoryConsumeResetToken = (hash) => {
     _resetTokens.delete(hash);
     return { userId: entry.userId, email: entry.email };
 };
+export const memoryStoreOAuthCode = (hash, payload, ttlSeconds) => {
+    _oauthCodes.set(hash, { ...payload, expiresAt: Date.now() + ttlSeconds * 1000 });
+};
+export const memoryConsumeOAuthCode = (hash) => {
+    const entry = _oauthCodes.get(hash);
+    if (!entry || entry.expiresAt <= Date.now()) {
+        _oauthCodes.delete(hash);
+        return null;
+    }
+    _oauthCodes.delete(hash);
+    return { token: entry.token, userId: entry.userId, email: entry.email, refreshToken: entry.refreshToken };
+};