@lastshotlabs/bunshot 0.0.16 → 0.0.19

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.19",
   "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"