@lastshotlabs/bunshot 0.0.16 → 0.0.18

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) |

package/docs/sections/exports/full.md

@@ -27,7 +27,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)
@@ -51,6 +52,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
@@ -69,7 +78,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/docs/sections/multi-tenancy/full.md

@@ -31,6 +31,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
@@ -59,4 +63,4 @@ await deleteTenant("acme");                  // soft-delete + invalidates resolu
 When tenant context is present, rate limits and cache keys are automatically namespaced per-tenant — no code changes needed. Each tenant gets independent rate limit buckets and cache entries.
 
 - Rate limit keys: `t:${tenantId}:ip:${ip}` (instead of `ip:${ip}`)
-- Cache keys: `cache:${appName}:${tenantId}:${key}` (instead of `cache:${appName}:${key}`)
+- Cache keys: `cache:${appName}:${tenantId}:${key}` (instead of `cache:${appName}:${key}`)

package/docs/sections/oauth/full.md

@@ -1,6 +1,6 @@
 ## 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({
@@ -22,6 +22,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",
+        },
       },
     },
   },
@@ -34,22 +45,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`:
 
@@ -66,11 +132,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:
@@ -96,10 +164,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`.
@@ -116,4 +186,4 @@ const myAdapter: AuthAdapter = {
     await db.update(users).set({ providerIds: filtered }).where(eq(users.id, userId));
   },
 };
-```
+```

package/docs/sections/oauth/overview.md

@@ -1,6 +1,6 @@
 ## Social Login (OAuth)
 
-Pass `auth.oauth.providers` to enable Google and/or Apple sign-in. Routes are mounted automatically for each configured provider.
+Pass `auth.oauth.providers` to enable Google, Apple, Microsoft, and/or GitHub sign-in. Routes are mounted automatically for each configured provider.
 
 ```ts
 auth: {
@@ -13,4 +13,4 @@ auth: {
 }
 ```
 
-Auto-mounted routes per provider: initiate (`GET /auth/{provider}`), callback, link to existing account (`GET /auth/{provider}/link`), and unlink (`DELETE /auth/{provider}/link`). Supports custom adapters via `findOrCreateByProvider`, `linkProvider`, and `unlinkProvider`.
+Auto-mounted routes per provider: initiate (`GET /auth/{provider}`), callback, link to existing account (`GET /auth/{provider}/link`), and unlink (`DELETE /auth/{provider}/link`). After OAuth redirect, the client exchanges a one-time authorization code via `POST /auth/oauth/exchange` to receive the session token (the JWT is never exposed in the redirect URL). Supports custom adapters via `findOrCreateByProvider`, `linkProvider`, and `unlinkProvider`. Optionally restrict redirect URLs with `allowedRedirectUrls`.

package/docs/sections/peer-dependencies/full.md

@@ -31,6 +31,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 |
@@ -38,6 +41,7 @@ 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.
+If you're running fully on SQLite or memory (no Redis, no MongoDB), none of the optional peers are needed.

package/docs/sections/response-caching/full.md

@@ -100,6 +100,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:
@@ -112,4 +114,4 @@ import { bustCachePattern } from "@lastshotlabs/bunshot";
 await bustCachePattern(`balance:${userId}:*`);
 ```
 
-The `*` wildcard is translated to a Redis glob, a Mongo/Memory regex, and a SQLite LIKE pattern automatically. Like `bustCache`, it silently skips any store that isn't connected, so it's safe to call in apps that only use one store.
+The `*` wildcard is translated to a Redis glob, a Mongo/Memory regex, and a SQLite LIKE pattern automatically. Like `bustCache`, it silently skips any store that isn't connected, so it's safe to call in apps that only use one store.

package/docs/sections/websocket/full.md

@@ -8,8 +8,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`)
 
@@ -56,7 +57,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({
@@ -97,4 +98,4 @@ await createServer({
     },
   },
 });
-```
+```

package/docs/sections/websocket/overview.md

@@ -1,5 +1,5 @@
 ## WebSocket
 
-The `/ws` endpoint is mounted automatically by `createServer`. Default behavior: cookie-JWT auth on upgrade, room action handling, and echo for other messages.
+The `/ws` endpoint is mounted automatically by `createServer`. Default behavior: cookie-JWT auth on upgrade, room action handling, message size enforcement (64 KB default). Non-room messages are dropped unless a custom handler is provided.
 
 `SocketData` carries `id`, `userId`, and `rooms` per connection. Pass a type parameter to `createServer<T>` to extend with custom fields. Override `ws.handler` (open/message/close) and `ws.upgradeHandler` for custom behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastshotlabs/bunshot",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Batteries-included Bun + Hono API framework — auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box",
   "repository": {
     "type": "git",
@@ -51,7 +51,14 @@
     "dev": "bun --watch src/index.ts",
     "start": "bun src/index.ts",
     "readme": "bun docs/build-readme.ts",
-    "readme:npm": "bun docs/build-readme.ts npm"
+    "readme:npm": "bun docs/build-readme.ts npm",
+    "test": "bun test tests/unit tests/integration",
+    "test:coverage": "bun test --coverage tests/unit tests/integration",
+    "test:docker:up": "docker compose -f docker-compose.test.yml up -d --wait",
+    "test:docker:down": "docker compose -f docker-compose.test.yml down",
+    "test:docker": "bun test --config bunfig.docker.toml tests/docker/",
+    "test:all": "bun test tests/unit tests/integration && bun run test:docker",
+    "test:coverage:full": "bun run test:docker:up && bun test --coverage --config bunfig.ci.toml tests/unit tests/integration tests/docker; bun run test:docker:down"
   },
   "dependencies": {
     "@hono/zod-openapi": "1.2.2",
@@ -65,7 +72,8 @@
     "mongoose": ">=9.0 <10",
     "ioredis": ">=5.0 <6",
     "bullmq": ">=5.0 <6",
-    "otpauth": ">=9.0 <10"
+    "otpauth": ">=9.0 <10",
+    "@simplewebauthn/server": ">=10.0.0"
   },
   "peerDependenciesMeta": {
     "mongoose": {
@@ -79,6 +87,9 @@
     },
     "otpauth": {
       "optional": true
+    },
+    "@simplewebauthn/server": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -90,7 +101,8 @@
     "otpauth": "^9.5.0",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.9.3",
-    "zod": ">=4.0"
+    "zod": ">=4.0",
+    "@simplewebauthn/server": "^13.1.1"
   },
   "publishConfig": {
     "access": "public"