@lastshotlabs/bunshot 0.0.16 → 0.0.19

package/dist/services/mfa.js

@@ -1,6 +1,6 @@
 import { getAuthAdapter } from "../lib/authAdapter";
 import { HttpError } from "../lib/HttpError";
-import { getMfaIssuer, getMfaAlgorithm, getMfaDigits, getMfaPeriod, getMfaRecoveryCodeCount, getMfaEmailOtpConfig, getMfaEmailOtpCodeLength } from "../lib/appConfig";
+import { getMfaIssuer, getMfaAlgorithm, getMfaDigits, getMfaPeriod, getMfaRecoveryCodeCount, getMfaEmailOtpConfig, getMfaEmailOtpCodeLength, getMfaWebAuthnConfig, getAppName } from "../lib/appConfig";
 import { createMfaChallenge } from "../lib/mfaChallenge";
 // Lazy-load otpauth to keep it as an optional peer dependency
 let _otpauth = null;
@@ -9,11 +9,7 @@ async function getOtpAuth() {
         _otpauth = await import("otpauth");
     return _otpauth;
 }
-function sha256(input) {
-    const hash = new Bun.CryptoHasher("sha256");
-    hash.update(input);
-    return hash.digest("hex");
-}
+import { sha256, timingSafeEqual } from "../lib/crypto";
 function generateRandomCode(length) {
     const chars = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; // no ambiguous chars: I/1/O/0
     let code = "";
@@ -110,7 +106,7 @@ export const verifyRecoveryCode = async (userId, code) => {
         return false;
     const hashedCodes = await adapter.getRecoveryCodes(userId);
     const hashedInput = sha256(code.toUpperCase());
-    const match = hashedCodes.find((h) => h === hashedInput);
+    const match = hashedCodes.find((h) => timingSafeEqual(h, hashedInput));
     if (!match)
         return false;
     await adapter.removeRecoveryCode(userId, match);
@@ -158,7 +154,7 @@ export const generateEmailOtpCode = (length) => {
 };
 /** Verify an email OTP code against a stored hash. */
 export const verifyEmailOtp = (emailOtpHash, code) => {
-    return sha256(code) === emailOtpHash;
+    return timingSafeEqual(sha256(code), emailOtpHash);
 };
 /**
  * Initiate email OTP setup: sends a verification code to the user's email.
@@ -175,7 +171,7 @@ export const initiateEmailOtp = async (userId) => {
     const { code, hash } = generateEmailOtpCode();
     await emailOtpConfig.onSend(user.email, code);
     // Store the hash in a challenge token for verification
-    const setupToken = await createMfaChallenge(userId, hash);
+    const setupToken = await createMfaChallenge(userId, { emailOtpHash: hash });
     return setupToken;
 };
 /**
@@ -274,3 +270,274 @@ export const getMfaMethods = async (userId) => {
         return ["totp"];
     return [];
 };
+// ---------------------------------------------------------------------------
+// WebAuthn / FIDO2
+// ---------------------------------------------------------------------------
+// Lazy-load @simplewebauthn/server to keep it as an optional peer dependency
+let _simplewebauthn = null;
+async function getSimpleWebAuthn() {
+    if (!_simplewebauthn)
+        _simplewebauthn = await import("@simplewebauthn/server");
+    return _simplewebauthn;
+}
+/**
+ * Eager startup check — call at route mount time to fail fast if the peer dependency is missing.
+ */
+export const assertWebAuthnDependency = async () => {
+    try {
+        await import("@simplewebauthn/server");
+    }
+    catch {
+        throw new Error("@simplewebauthn/server is required when mfa.webauthn is configured. Install it: bun add @simplewebauthn/server");
+    }
+};
+/**
+ * Generate WebAuthn authentication options for the login MFA flow.
+ * Called from auth.ts login when the user has "webauthn" in their methods.
+ */
+export const generateWebAuthnAuthenticationOptions = async (userId) => {
+    const config = getMfaWebAuthnConfig();
+    if (!config)
+        return null;
+    const adapter = getAuthAdapter();
+    if (!adapter.getWebAuthnCredentials)
+        return null;
+    const credentials = await adapter.getWebAuthnCredentials(userId);
+    if (credentials.length === 0)
+        return null;
+    const { generateAuthenticationOptions } = await getSimpleWebAuthn();
+    const options = await generateAuthenticationOptions({
+        rpID: config.rpId,
+        allowCredentials: credentials.map((c) => ({
+            id: c.credentialId,
+            transports: c.transports,
+        })),
+        userVerification: config.userVerification ?? "preferred",
+        timeout: config.timeout ?? 60000,
+    });
+    return { challenge: options.challenge, options: options };
+};
+/**
+ * Initiate WebAuthn registration: generates registration options for the client.
+ * Returns options + a registration challenge token.
+ */
+export const initiateWebAuthnRegistration = async (userId) => {
+    const config = getMfaWebAuthnConfig();
+    if (!config)
+        throw new HttpError(501, "WebAuthn is not configured");
+    const adapter = getAuthAdapter();
+    if (!adapter.getWebAuthnCredentials)
+        throw new HttpError(501, "Auth adapter does not support WebAuthn");
+    const user = adapter.getUser ? await adapter.getUser(userId) : null;
+    // Get existing credentials to exclude (prevent re-registration)
+    const existingCreds = await adapter.getWebAuthnCredentials(userId);
+    const { generateRegistrationOptions } = await getSimpleWebAuthn();
+    const options = await generateRegistrationOptions({
+        rpName: config.rpName ?? getAppName(),
+        rpID: config.rpId,
+        userName: user?.email ?? userId,
+        attestationType: config.attestationType ?? "none",
+        excludeCredentials: existingCreds.map((c) => ({
+            id: c.credentialId,
+            transports: c.transports,
+        })),
+        authenticatorSelection: {
+            authenticatorAttachment: config.authenticatorAttachment,
+            userVerification: config.userVerification ?? "preferred",
+            residentKey: "preferred",
+        },
+        timeout: config.timeout ?? 60000,
+    });
+    const { createWebAuthnRegistrationChallenge } = await import("../lib/mfaChallenge");
+    const registrationToken = await createWebAuthnRegistrationChallenge(userId, options.challenge);
+    return { options: options, registrationToken };
+};
+/**
+ * Complete WebAuthn registration: verifies attestation and stores the credential.
+ * Returns recovery codes if this is the first MFA method.
+ */
+export const completeWebAuthnRegistration = async (userId, registrationToken, attestationResponse, name) => {
+    const config = getMfaWebAuthnConfig();
+    if (!config)
+        throw new HttpError(501, "WebAuthn is not configured");
+    const adapter = getAuthAdapter();
+    if (!adapter.addWebAuthnCredential || !adapter.setMfaEnabled || !adapter.setRecoveryCodes) {
+        throw new HttpError(501, "Auth adapter does not support WebAuthn");
+    }
+    const { consumeWebAuthnRegistrationChallenge } = await import("../lib/mfaChallenge");
+    const challenge = await consumeWebAuthnRegistrationChallenge(registrationToken);
+    if (!challenge)
+        throw new HttpError(401, "Invalid or expired registration token");
+    if (challenge.userId !== userId)
+        throw new HttpError(401, "Token does not match user");
+    const { verifyRegistrationResponse } = await getSimpleWebAuthn();
+    const verification = await verifyRegistrationResponse({
+        response: attestationResponse,
+        expectedChallenge: challenge.challenge,
+        expectedOrigin: Array.isArray(config.origin) ? config.origin : [config.origin],
+        expectedRPID: config.rpId,
+    });
+    if (!verification.verified || !verification.registrationInfo) {
+        throw new HttpError(401, "WebAuthn registration verification failed");
+    }
+    const { credential } = verification.registrationInfo;
+    const credentialId = credential.id;
+    // Cross-user uniqueness check
+    if (adapter.findUserByWebAuthnCredentialId) {
+        const existingOwner = await adapter.findUserByWebAuthnCredentialId(credentialId);
+        if (existingOwner && existingOwner !== userId) {
+            throw new HttpError(409, "This security key is already registered to another account");
+        }
+    }
+    const newCredential = {
+        credentialId,
+        publicKey: Buffer.from(credential.publicKey).toString("base64url"),
+        signCount: credential.counter,
+        transports: attestationResponse.response?.transports ?? [],
+        name: name ?? undefined,
+        createdAt: Date.now(),
+    };
+    await adapter.addWebAuthnCredential(userId, newCredential);
+    // Add "webauthn" to methods
+    if (adapter.getMfaMethods && adapter.setMfaMethods) {
+        const methods = await adapter.getMfaMethods(userId);
+        if (!methods.includes("webauthn")) {
+            await adapter.setMfaMethods(userId, [...methods, "webauthn"]);
+        }
+    }
+    // Enable MFA + generate/regenerate recovery codes
+    await adapter.setMfaEnabled(userId, true);
+    const { plainCodes, hashedCodes } = generateRecoveryCodes();
+    await adapter.setRecoveryCodes(userId, hashedCodes);
+    return { credentialId, recoveryCodes: plainCodes };
+};
+/**
+ * Verify a WebAuthn authentication assertion during login MFA.
+ */
+export const verifyWebAuthn = async (userId, assertionResponse, expectedChallenge) => {
+    const config = getMfaWebAuthnConfig();
+    if (!config)
+        return false;
+    const adapter = getAuthAdapter();
+    if (!adapter.getWebAuthnCredentials || !adapter.updateWebAuthnCredentialSignCount)
+        return false;
+    const credentials = await adapter.getWebAuthnCredentials(userId);
+    const credentialId = assertionResponse.id;
+    const matchedCred = credentials.find((c) => c.credentialId === credentialId);
+    if (!matchedCred)
+        return false;
+    const { verifyAuthenticationResponse } = await getSimpleWebAuthn();
+    try {
+        const verification = await verifyAuthenticationResponse({
+            response: assertionResponse,
+            expectedChallenge,
+            expectedOrigin: Array.isArray(config.origin) ? config.origin : [config.origin],
+            expectedRPID: config.rpId,
+            credential: {
+                id: matchedCred.credentialId,
+                publicKey: new Uint8Array(Buffer.from(matchedCred.publicKey, "base64url")),
+                counter: matchedCred.signCount,
+                transports: matchedCred.transports,
+            },
+        });
+        if (!verification.verified)
+            return false;
+        const { authenticationInfo } = verification;
+        // Sign count policy
+        if (authenticationInfo.newCounter < matchedCred.signCount) {
+            if (config.strictSignCount) {
+                console.warn(`[webauthn] Sign count went backward for credential ${credentialId} (user ${userId}) — rejecting (strictSignCount enabled)`);
+                return false;
+            }
+            console.warn(`[webauthn] Sign count went backward for credential ${credentialId} (user ${userId}) — possible cloned authenticator`);
+        }
+        await adapter.updateWebAuthnCredentialSignCount(userId, credentialId, authenticationInfo.newCounter);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Remove a single WebAuthn credential.
+ * Only requires identity verification when removing the last credential of the last MFA method.
+ */
+export const removeWebAuthnCredential = async (userId, credentialId, params) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getWebAuthnCredentials || !adapter.removeWebAuthnCredential) {
+        throw new HttpError(501, "Auth adapter does not support WebAuthn");
+    }
+    const credentials = await adapter.getWebAuthnCredentials(userId);
+    if (!credentials.some((c) => c.credentialId === credentialId)) {
+        throw new HttpError(404, "Credential not found");
+    }
+    const methods = adapter.getMfaMethods ? await adapter.getMfaMethods(userId) : [];
+    const otherMethodsExist = methods.some((m) => m !== "webauthn");
+    const otherCredsExist = credentials.length > 1;
+    // Only require verification when removing the last credential of the last method
+    if (!otherMethodsExist && !otherCredsExist) {
+        await verifyIdentity(userId, params);
+    }
+    await adapter.removeWebAuthnCredential(userId, credentialId);
+    // If that was the last credential, remove "webauthn" from methods
+    if (!otherCredsExist && adapter.setMfaMethods) {
+        const updated = methods.filter((m) => m !== "webauthn");
+        await adapter.setMfaMethods(userId, updated);
+        // If no methods remain, disable MFA entirely
+        if (updated.length === 0 && adapter.setMfaEnabled) {
+            await adapter.setMfaEnabled(userId, false);
+            if (adapter.setRecoveryCodes)
+                await adapter.setRecoveryCodes(userId, []);
+        }
+    }
+};
+/**
+ * Disable WebAuthn entirely: removes all credentials and the method.
+ */
+export const disableWebAuthn = async (userId, params) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getWebAuthnCredentials || !adapter.removeWebAuthnCredential) {
+        throw new HttpError(501, "Auth adapter does not support WebAuthn");
+    }
+    await verifyIdentity(userId, params);
+    const credentials = await adapter.getWebAuthnCredentials(userId);
+    for (const cred of credentials) {
+        await adapter.removeWebAuthnCredential(userId, cred.credentialId);
+    }
+    // Remove "webauthn" from methods
+    if (adapter.getMfaMethods && adapter.setMfaMethods) {
+        const methods = await adapter.getMfaMethods(userId);
+        const updated = methods.filter((m) => m !== "webauthn");
+        await adapter.setMfaMethods(userId, updated);
+        if (updated.length === 0 && adapter.setMfaEnabled) {
+            await adapter.setMfaEnabled(userId, false);
+            if (adapter.setRecoveryCodes)
+                await adapter.setRecoveryCodes(userId, []);
+        }
+    }
+};
+/** Internal: verify identity via TOTP code or password. */
+async function verifyIdentity(userId, params) {
+    const adapter = getAuthAdapter();
+    const methods = adapter.getMfaMethods ? await adapter.getMfaMethods(userId) : [];
+    const hasTotpEnabled = methods.includes("totp");
+    if (hasTotpEnabled) {
+        if (!params.code)
+            throw new HttpError(400, "TOTP code required");
+        const valid = await verifyTotp(userId, params.code);
+        if (!valid)
+            throw new HttpError(401, "Invalid TOTP code");
+    }
+    else {
+        if (!params.password)
+            throw new HttpError(400, "Password required");
+        const user = adapter.findByIdentifier
+            ? await adapter.findByIdentifier((await adapter.getUser?.(userId))?.email ?? "")
+            : await adapter.findByEmail((await adapter.getUser?.(userId))?.email ?? "");
+        if (!user)
+            throw new HttpError(404, "User not found");
+        const valid = await Bun.password.verify(params.password, user.passwordHash);
+        if (!valid)
+            throw new HttpError(401, "Invalid password");
+    }
+}

package/dist/ws/index.js

@@ -25,8 +25,9 @@ export const websocket = {
         console.log(`[ws] connected: ${ws.data.id}`);
         ws.send(JSON.stringify({ event: "connected", id: ws.data.id }));
     },
-    message(ws, message) {
-        ws.send(message);
+    message(_ws, _message) {
+        // No-op: room actions are handled by server.ts via handleRoomActions.
+        // Override ws.handler.message in WsConfig for custom message handling.
     },
     close(ws) {
         console.log(`[ws] disconnected: ${ws.data.id}`);

package/docs/sections/auth-flow/full.md

@@ -157,6 +157,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:
@@ -193,6 +256,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
@@ -297,6 +379,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.
 
@@ -338,14 +423,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 })) {
@@ -428,6 +513,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`:
@@ -454,3 +582,53 @@ 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)
+```

package/docs/sections/configuration/full.md

@@ -43,6 +43,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
@@ -51,9 +53,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)
@@ -104,6 +113,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
@@ -130,6 +149,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
   },
 });
 ```

package/docs/sections/configuration/overview.md

@@ -8,7 +8,7 @@
 | `app` | App name and version (shown in docs) |
 | `auth` | Roles, OAuth, email verification, MFA, refresh tokens, rate limiting, account deletion |
 | `db` | Connection and store routing — mongo, redis, sqlite, sessions, cache, auth adapter |
-| `security` | CORS, bearer auth, rate limiting, bot protection |
+| `security` | CORS, bearer auth, rate limiting, bot protection, CSRF |
 | `tenancy` | Multi-tenant resolution (header/subdomain/path) |
 | `jobs` | Job status REST endpoint config |
 | `ws` | WebSocket handler and upgrade overrides |

package/docs/sections/configuration-example/full.md

@@ -48,6 +48,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`,
+      },
     },
   },
 };
@@ -96,4 +114,4 @@ Every field above is optional except `routesDir`. See the [Configuration](#confi
 | `GET /health` | Health check |
 | `GET /docs` | Scalar API docs UI |
 | `GET /openapi.json` | OpenAPI spec |
-| `WS /ws` | WebSocket endpoint (cookie-JWT auth) |
+| `WS /ws` | WebSocket endpoint (cookie-JWT auth) |