@lastshotlabs/bunshot 0.0.25 → 0.0.27

package/docs/sections/auth-security-examples/full.md

@@ -363,3 +363,26 @@ await createServer({
 - `auth: "memory"` and `sessions: "memory"` use in-memory Maps. Import `clearMemoryStore()` from the package in your tests to reset state between test runs.
 - Rate limits are set to 10 000 per minute rather than disabled entirely so the rate-limit code path is exercised (avoiding "works in dev, breaks in prod" surprises). The limit is just high enough that it never triggers during normal use.
 - If you want to test email flows locally without a real provider, the commented-out block shows how to log the token to the console — paste it into the browser or a `curl` call directly.
+
+---
+
+## JWT Claims (iss, aud, iat)
+
+By default Bunshot tokens include `sub`, `sid`, and `exp`. Enable standard JWT claims for multi-service deployments or compliance requirements:
+
+```ts
+createApp({
+  auth: {
+    jwt: {
+      issuer: "https://auth.yourapp.com",   // iss claim — who issued the token
+      audience: "your-api",                 // aud claim — who the token is for
+    },
+  },
+});
+```
+
+When configured:
+- **`iss`** and **`aud`** are included in every token and validated on every verification. Tokens from a different issuer or intended for a different audience are rejected.
+- **`iat`** (issued-at) is always included once JWT config is set. Use it to detect token reuse or implement absolute expiry windows.
+
+This is recommended for fintech and multi-tenant deployments where tokens from one service should not be accepted by another.

package/docs/sections/metrics/full.md

@@ -94,12 +94,16 @@ This counter is always present when metrics are enabled so you can alert on scra
 
 ### Security
 
-Auth defaults to `"none"` for easy adoption. A production warning is logged when metrics are enabled without auth. **Recommended:** Lock down `/metrics` in production since it exposes operational details (error rates, queue depths, tenant activity patterns).
+Auth defaults to `"none"` for easy adoption. A production warning is logged when metrics are enabled without auth.
+
+**In production, `/metrics` returns `403` when `auth` is `"none"`** — the endpoint is hard-blocked to prevent accidental exposure of operational details (error rates, queue depths, tenant activity patterns). Configure `metrics.auth` before deploying:
 
 ```ts
 metrics: {
   enabled: true,
-  auth: [userAuth, requireRole("admin")], // custom middleware stack
+  auth: "userAuth",                        // require a logged-in user
+  // or:
+  auth: [userAuth, requireRole("admin")],  // custom middleware stack
 }
 ```
 

package/docs/sections/passkey-login/full.md

@@ -0,0 +1,90 @@
+#### Passkey Login (Passwordless)
+
+Passkeys (Windows Hello, Face ID, Touch ID) can be used as a **first-factor** passwordless login — no password required. The user authenticates directly with their biometric or device PIN.
+
+This is separate from [WebAuthn as an MFA method](#webauthn--security-keys) (which requires password first). When both are configured, passkey login and WebAuthn MFA coexist independently.
+
+> **Prerequisites:** Credentials must be registered with `residentKey: "required"` and `userVerification: "required"` to work as passkeys. bunshot sets both automatically on all WebAuthn registrations — credentials registered with an older version of the library will continue to work as MFA-only second factors but won't be usable for passwordless login.
+
+##### Enable passkey login
+
+Add `allowPasswordlessLogin: true` to the `mfa.webauthn` config:
+
+```ts
+await createServer({
+  auth: {
+    mfa: {
+      webauthn: {
+        rpId: "example.com",
+        origin: "https://example.com",
+        allowPasswordlessLogin: true,   // mounts /auth/passkey/* routes
+        passkeyMfaBypass: true,         // default — passkey satisfies both factors
+      },
+    },
+  },
+});
+```
+
+When `allowPasswordlessLogin` is `false` (the default), the `/auth/passkey/*` routes are not mounted at all — callers receive a `404`.
+
+##### Endpoints
+
+| Endpoint | Auth | Rate limit | Purpose |
+|---|---|---|---|
+| `POST /auth/passkey/login-options` | None | 5 / min per IP | Get WebAuthn challenge options |
+| `POST /auth/passkey/login` | None | 10 / 15 min per IP | Verify assertion, issue session |
+
+##### Login flow
+
+1. `POST /auth/passkey/login-options` with optional `{ email? }` → `{ options, passkeyToken }`
+2. Client passes `options` to `startAuthentication(options)` from `@simplewebauthn/browser` — OS shows biometric / PIN prompt
+3. `POST /auth/passkey/login` with `{ passkeyToken, assertionResponse }` → `{ token, userId, ... }`
+
+```ts
+import { startAuthentication } from '@simplewebauthn/browser'
+
+// Step 1 — get challenge
+const { options, passkeyToken } = await fetch('/auth/passkey/login-options', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ email }),  // optional hint
+}).then(r => r.json())
+
+// Step 2 — browser OS prompt
+const assertionResponse = await startAuthentication(options)
+
+// Step 3 — verify & get session
+const result = await fetch('/auth/passkey/login', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ passkeyToken, assertionResponse }),
+}).then(r => r.json())
+// result: { token, userId, email? } or { mfaRequired, mfaToken, mfaMethods } when passkeyMfaBypass: false
+```
+
+##### MFA bypass
+
+By default (`passkeyMfaBypass: true`), a passkey login that passes `userVerification: "required"` satisfies **both factors** — no subsequent TOTP or email OTP prompt, even if the user has MFA enabled. Biometric + device possession is equivalent to password + TOTP.
+
+Set `passkeyMfaBypass: false` to require MFA after a passkey login — for apps with strict compliance requirements:
+
+```ts
+mfa: {
+  webauthn: {
+    // ...
+    allowPasswordlessLogin: true,
+    passkeyMfaBypass: false,  // require TOTP/OTP after passkey
+  },
+}
+```
+
+##### Enumeration prevention
+
+`POST /auth/passkey/login-options` always returns a valid-looking challenge regardless of whether the email exists or has registered credentials. It never returns a `404` or a distinguishable error — the shape and timing are identical for known and unknown emails.
+
+##### Security
+
+- `userVerification` defaults to `"required"` for passkey login — a bare hardware key tap without biometric or PIN is rejected. Set `mfa.webauthn.userVerification: "preferred"` to allow touch-only hardware keys (same tradeoff as "remember this device": proves possession, not identity)
+- The `passkeyToken` is a 120-second single-use challenge token — it is consumed on the first verification attempt, so replay is not possible even within the TTL window
+- Sign count is validated and updated on every successful assertion. A backward sign count logs a warning; set `strictSignCount: true` to reject it (possible cloned authenticator signal)
+- Sessions created via passkey login are independent of the credential — revoking or deleting a credential does not invalidate existing sessions. Use explicit session revocation for that

package/docs/sections/passkey-login/overview.md

@@ -0,0 +1 @@
+Passkeys (Windows Hello, Face ID, Touch ID) as a **passwordless first-factor** — no password required. Enable with `mfa.webauthn.allowPasswordlessLogin: true`. Mounts `POST /auth/passkey/login-options` and `POST /auth/passkey/login`. By default a verified passkey satisfies both factors (`passkeyMfaBypass: true`). Enumeration-safe: login-options always returns valid-looking challenge data.

package/docs/sections/uploads/full.md

@@ -123,12 +123,21 @@ When `presignedUrls` is set, two routes are mounted (default base path `/uploads
 - `POST /uploads/presign` — returns a time-limited PUT URL
 - `DELETE /uploads/:key` — deletes a stored file
 
+**`POST /uploads/presign` request fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | Storage key for the upload |
+| `mimeType` | `string` (optional) | MIME type of the file. Certain dangerous types are rejected with `400 { error: "File type not allowed." }`: `application/x-executable`, `application/x-sh`, `application/x-msdownload`, `text/html`, `application/x-httpd-php`, `application/javascript`, `text/javascript` |
+| `expirySeconds` | `number` (optional) | URL expiry in seconds |
+| `maxBytes` | `number` (optional) | Maximum allowed file size in bytes (client-enforced via Content-Length). Defaults to 10MB. Maximum: 100MB. Returned in the response so clients can enforce the limit before uploading. |
+
 ```typescript
 // 1. Client requests a presigned URL from your API
-const { url, key } = await fetch("/uploads/presign", {
+const { url, key, maxBytes } = await fetch("/uploads/presign", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ key: "photos/my-image.jpg", mimeType: "image/jpeg", expirySeconds: 300 }),
+  body: JSON.stringify({ key: "photos/my-image.jpg", mimeType: "image/jpeg", expirySeconds: 300, maxBytes: 5 * 1024 * 1024 }),
 }).then(r => r.json());
 
 // 2. Client uploads directly to storage (no server bandwidth used)

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

@@ -51,7 +51,7 @@ If the header value does **not** start with the configured prefix, the full valu
 |--------|------|---------|-------------|
 | `secret` | `string \| (c) => string \| Promise<string>` | — | Shared HMAC secret. Pass a function for dynamic resolution (e.g. per-tenant lookup). |
 | `header` | `string` | `"x-webhook-signature"` | Header that carries the signature. |
-| `algorithm` | `"sha256" \| "sha512" \| "sha1"` | `"sha256"` | HMAC algorithm. |
+| `algorithm` | `"sha256" \| "sha512"` | `"sha256"` | HMAC algorithm. |
 | `prefix` | `string` | — | Strip this prefix before comparing (e.g. `"sha256="` for GitHub). |
 | `timestamp` | `{ header, tolerance }` | — | Opt-in replay protection (see below). |
 

package/docs/sections/websocket/full.md

@@ -164,6 +164,18 @@ const older = await getMessageHistory("chat:general", { limit: 50, before: histo
 
 Messages for non-configured rooms are silently ignored. Store errors are caught and logged (non-blocking) — message delivery is never interrupted by a persistence failure.
 
+### Room Name Validation
+
+Room names sent by clients via `subscribe` and `unsubscribe` actions are validated before any action is taken. Invalid room names are silently dropped — no error is sent to the client.
+
+**Valid room name rules:**
+- Characters: `a–z`, `A–Z`, `0–9`, `_`, `:`, `.`, `/`, `-`
+- Length: 1–128 characters
+
+Examples of valid names: `chat:general`, `user:123`, `tenant/room-1`, `notifications`
+
+Room names containing characters outside this set (e.g. spaces, `@`, `#`, or Unicode) are silently ignored. This prevents injection of arbitrary pub/sub topic names from untrusted client input.
+
 ### Overriding the upgrade / auth handler
 
 Replace the default cookie-JWT handshake entirely via `ws.upgradeHandler`. You must call `server.upgrade()` yourself and include `rooms: new Set()` in data:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastshotlabs/bunshot",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Batteries-included Bun + Hono API framework — auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box",
   "repository": {
     "type": "git",
@@ -66,7 +66,8 @@
     "@hono/zod-openapi": "1.2.2",
     "@scalar/hono-api-reference": "0.10.0",
     "arctic": "^3.7.0",
-    "jose": "6.2.0"
+    "jose": "6.2.0",
+    "samlify": "^2.8"
   },
   "peerDependencies": {
     "hono": ">=4.12 <5",