@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/docs/sections/signing/full.md

@@ -0,0 +1,203 @@
+## Unified HMAC Signing (`security.signing`)
+
+A single `security.signing` config block enables six HMAC-based security features. All features are opt-in — disable the whole block or any individual feature to keep existing behavior.
+
+### Configuration
+
+```ts
+createApp({
+  security: {
+    signing: {
+      // HMAC secret. Defaults to JWT_SECRET_DEV/PROD env var if omitted.
+      // Pass string[] for key rotation — first element signs, all elements verify.
+      secret: process.env.HMAC_SECRET,
+
+      cookies: true,          // Sign/verify cookies set via signCookieValue()
+      cursors: true,          // HMAC-sign pagination cursors
+      presignedUrls: {        // Stateless HMAC presigned download URLs
+        defaultExpiry: 3600,  // seconds, default 3600
+      },
+      requestSigning: {       // Require clients to HMAC-sign requests
+        tolerance: 300_000,   // ms, default 5 min
+        header: "x-signature",
+        timestampHeader: "x-timestamp",
+      },
+      idempotencyKeys: true,  // HMAC-hash idempotency keys before storage
+      sessionBinding: {       // Bind sessions to client fingerprint
+        fields: ["ip", "ua"], // default: ["ip", "ua"]
+        onMismatch: "reject", // "unauthenticate" | "reject" | "log-only"
+      },
+    },
+  },
+});
+```
+
+### Secret & Key Rotation
+
+Secret resolution order: `signing.secret` → `JWT_SECRET_DEV/PROD` env var (same as CSRF and JWT).
+
+To rotate keys without breaking in-flight tokens, pass an array — **newest key first**:
+
+```ts
+secret: [process.env.HMAC_SECRET_NEW!, process.env.HMAC_SECRET_OLD!]
+```
+
+All verification attempts try each key in order; signing always uses the first.
+
+---
+
+### Feature 1: Signed Cookie Values
+
+```ts
+import { signCookieValue, verifyCookieValue } from "@lastshotlabs/bunshot";
+
+// Sign before setting a cookie
+const signed = signCookieValue(userId, secret);   // "b64value.hmac"
+setCookie(c, "session_hint", signed);
+
+// Verify when reading
+const raw = verifyCookieValue(getCookie(c, "session_hint") ?? "", secret);
+// null if tampered or missing
+```
+
+When `signing.cookies: false`, the helpers are still exported — they pass through values without signing (with a console warning).
+
+---
+
+### Feature 2: Request Signing (`requireSignedRequest`)
+
+Requires clients to HMAC-sign a canonical string of the request:
+
+```
+METHOD\nPATH\nCANONICAL_QUERY\nTIMESTAMP\nBODY
+```
+
+Query params are sorted and percent-encoding normalized (`%20` and `+` both become `%20`) before signing.
+
+```ts
+import { requireSignedRequest } from "@lastshotlabs/bunshot";
+
+// Mount on specific routes that need signing
+router.use("/webhooks/internal", requireSignedRequest());
+
+// Or override defaults per-route
+router.use("/admin/*", requireSignedRequest({ tolerance: 60_000 }));
+```
+
+Returns `401 { code: "INVALID_SIGNATURE" | "EXPIRED_TIMESTAMP" }` on failure.
+
+When `signing.requestSigning: false`, the middleware is a no-op.
+
+---
+
+### Feature 3: Idempotency (`idempotent`)
+
+Deduplicates requests using the `Idempotency-Key` header. The second identical request returns the cached first response without re-executing the handler.
+
+```ts
+import { idempotent } from "@lastshotlabs/bunshot";
+
+router.use("/payments", idempotent({ ttl: 86400 }));
+router.post("/payments", async (c) => {
+  // Safe to retry — second call returns cached 201
+  const result = await processPayment(c.req.valid("json"));
+  return c.json(result, 201);
+});
+```
+
+Store key: `userId:key` (authenticated) or `anon:key` (unauthenticated). When `signing.idempotencyKeys: true`, keys are HMAC'd before storage to prevent enumeration.
+
+**Race condition handling**: Two concurrent identical requests both miss the cache. The second writer detects the collision (Redis `SET NX`, Mongo duplicate key, SQLite `INSERT OR IGNORE`) and falls back to the first-stored result — never a 500.
+
+Configure the store via `setIdempotencyStore("redis" | "mongo" | "sqlite" | "memory")`. Default: `"redis"`.
+
+---
+
+### Feature 4: Signed Cursors
+
+When `signing.cursors: true`, `parseCursorParams()` verifies cursor signatures and `maybeSignCursor()` signs outgoing cursors. Tampered cursors are rejected with an invalid cursor flag.
+
+```ts
+import { parseCursorParams, maybeSignCursor } from "@lastshotlabs/bunshot";
+
+const { limit, cursor, invalidCursor } = parseCursorParams(c.req.query());
+if (invalidCursor) return c.json({ error: "Invalid cursor" }, 400);
+
+const items = await fetchPage({ limit, cursor });
+const nextCursor = maybeSignCursor(items.length === limit ? items.at(-1)!.id : null);
+return c.json({ items, nextCursor, hasMore: items.length === limit });
+```
+
+When off, cursors pass through unsigned (current behavior).
+
+---
+
+### Feature 5: Presigned URLs
+
+Stateless HMAC-signed download URLs — no database lookup required.
+
+```ts
+import { createPresignedUrl, verifyPresignedUrl } from "@lastshotlabs/bunshot";
+
+// Generate (e.g. in a GET /uploads/presign/:key route)
+const url = createPresignedUrl(
+  "https://api.example.com/uploads/download/",
+  "avatars/user123.jpg",
+  { method: "GET", expiry: 3600 },
+  secret
+);
+// → "https://api.example.com/uploads/download/?key=avatars%2F...&exp=...&method=GET&sig=..."
+
+// Verify (e.g. in the download handler)
+const result = verifyPresignedUrl(url, "GET", secret);
+// null if expired, tampered, or wrong method
+```
+
+The built-in upload router (`presignedUrls: true`) automatically serves HMAC presigned URLs at `GET /uploads/presign/:key` when `signing.presignedUrls` is enabled. Falls back to `adapter.presignGet()` (S3) otherwise.
+
+---
+
+### Feature 6: Session Binding
+
+Binds sessions to the client's HTTP fingerprint (IP + User-Agent by default). Mismatches indicate session hijacking or IP change.
+
+```ts
+sessionBinding: {
+  fields: ["ip", "ua"],      // fingerprint components
+  onMismatch: "reject",      // strict — 401 on mismatch
+}
+```
+
+| `onMismatch` | Behavior |
+|---|---|
+| `"unauthenticate"` (default) | Treat as logged-out; continue request unauthenticated |
+| `"reject"` | Return `401 { code: "FINGERPRINT_MISMATCH" }` |
+| `"log-only"` | Allow through but log the mismatch (useful during rollout) |
+
+The fingerprint is stored lazily on the first authenticated request after login. Subsequent requests compare the current fingerprint to the stored one.
+
+---
+
+### "HMAC off" behavior per feature
+
+| Feature | HMAC on | HMAC off |
+|---|---|---|
+| Signed cookies | `signCookieValue` / `verifyCookieValue` sign/verify | Pass-through (identity functions with warning) |
+| Request signing | `requireSignedRequest` validates HMAC | Middleware is a no-op |
+| Idempotency keys | Key is HMAC'd before storage | Raw key stored (slight enumeration risk) |
+| Signed cursors | `parseCursorParams` rejects invalid sigs | Cursors pass through unsigned |
+| Presigned URLs | Stateless HMAC-signed URL | Falls back to `adapter.presignGet()` or 501 |
+| Session binding | Fingerprint verified on each request | No fingerprint check |
+
+---
+
+### Low-level primitives
+
+```ts
+import { hmacSign, hmacVerify } from "@lastshotlabs/bunshot";
+
+const sig = hmacSign("data", secret);
+const ok  = hmacVerify("data", sig, secret); // uses timingSafeEqual internally
+```
+
+`hmacVerify` always uses `timingSafeEqual` — never `===` — to prevent timing side-channel attacks.

package/docs/sections/uploads/full.md

@@ -0,0 +1,208 @@
+## File Uploads
+
+Bunshot provides opt-in file upload handling with pluggable storage adapters (memory, local filesystem, S3/R2), server-side multipart parsing, and optional presigned URL generation for direct client-to-storage uploads.
+
+### Configuration
+
+Enable uploads by passing `upload` to `createApp` or `createServer`:
+
+```typescript
+import { createServer, memoryStorage } from "@lastshotlabs/bunshot";
+
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  upload: {
+    storage: memoryStorage(),       // swap for localStorage() or s3Storage()
+    maxFileSize: 5 * 1024 * 1024,  // 5 MB per file
+    maxFiles: 3,
+    allowedMimeTypes: ["image/*", "application/pdf"],
+    keyPrefix: "uploads/",
+    tenantScopedKeys: false,
+    presignedUrls: true,            // mounts POST /uploads/presign and DELETE /uploads/:key
+  },
+});
+```
+
+**`UploadConfig` fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `storage` | `StorageAdapter` | required | Storage backend instance |
+| `maxFileSize` | `number` | `10485760` (10 MB) | Max bytes per file |
+| `maxFiles` | `number` | `10` | Max files per request |
+| `allowedMimeTypes` | `string[]` | all allowed | Permitted MIME types (supports wildcards like `image/*`) |
+| `keyPrefix` | `string` | `"uploads/"` | Path prefix prepended to generated keys |
+| `generateKey` | `(file, ctx) => string` | UUID-based | Custom key generation function |
+| `tenantScopedKeys` | `boolean` | `false` | Prepend `tenantId/` to generated keys |
+| `presignedUrls` | `boolean \| PresignedUrlConfig` | `false` | Mount presigned URL routes |
+
+### Storage Adapters
+
+#### Memory (testing)
+
+```typescript
+import { memoryStorage, clearMemoryUploadStore } from "@lastshotlabs/bunshot";
+
+const storage = memoryStorage();
+// clearMemoryUploadStore() is called automatically by clearMemoryStore() in tests
+```
+
+Does not implement `presignPut` / `presignGet`. The presigned URL route returns `501` when this adapter is used.
+
+#### Local Filesystem
+
+```typescript
+import { localStorage } from "@lastshotlabs/bunshot";
+
+const storage = localStorage({
+  directory: import.meta.dir + "/uploads",
+  baseUrl: "https://example.com/files",   // optional — appended to key for public URL
+});
+```
+
+#### S3 / R2 / MinIO
+
+Requires `@aws-sdk/client-s3`. Presigned URLs additionally require `@aws-sdk/s3-request-presigner`.
+
+```typescript
+import { s3Storage } from "@lastshotlabs/bunshot";
+
+const storage = s3Storage({
+  bucket: "my-bucket",
+  region: "us-east-1",
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+  publicUrl: "https://cdn.example.com",  // optional — used to build the returned URL
+  // For Cloudflare R2 or MinIO:
+  // endpoint: "https://<account>.r2.cloudflarestorage.com",
+  // forcePathStyle: true,
+});
+```
+
+### Server-Side Upload (Middleware)
+
+Use `handleUpload` middleware in your route handler. It parses the multipart body, validates files, stores them, and sets `uploadResults` on the context.
+
+```typescript
+import { createRoute, handleUpload } from "@lastshotlabs/bunshot";
+import { createRouter } from "@lastshotlabs/bunshot";
+
+export const router = createRouter();
+
+const uploadRoute = createRoute({
+  method: "post",
+  path: "/photos",
+  summary: "Upload photos",
+  responses: {
+    200: { description: "Uploaded", content: { "application/json": { schema: z.object({ keys: z.array(z.string()) }) } } },
+  },
+});
+
+router.openapi(uploadRoute, handleUpload({ field: "photo", allowedMimeTypes: ["image/*"] }), async (c) => {
+  const results = c.get("uploadResults") ?? [];
+  return c.json({ keys: results.map((r) => r.key) });
+});
+```
+
+**`UploadResult` fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | Storage key |
+| `originalName` | `string` | Original filename from the browser |
+| `mimeType` | `string` | Detected MIME type |
+| `size` | `number` | File size in bytes |
+| `url` | `string \| undefined` | Public URL (when adapter returns one) |
+
+### Presigned URL Flow (Client-Side Upload)
+
+When `presignedUrls` is set, two routes are mounted (default base path `/uploads`, requires authentication):
+
+- `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, 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, maxBytes: 5 * 1024 * 1024 }),
+}).then(r => r.json());
+
+// 2. Client uploads directly to storage (no server bandwidth used)
+await fetch(url, { method: "PUT", body: file, headers: { "Content-Type": "image/jpeg" } });
+
+// 3. Store the key in your database
+await savePhotoRecord({ key, userId: currentUser.id });
+```
+
+Configure the base path and default expiry:
+
+```typescript
+presignedUrls: {
+  path: "/media",         // mounts POST /media/presign and DELETE /media/:key
+  expirySeconds: 600,     // default 10-minute expiry
+}
+```
+
+If the configured storage adapter does not support `presignPut` (e.g., memory or local filesystem), the endpoint returns `501 { error: "Presigned URLs not supported by the configured storage adapter" }`.
+
+### Dynamic Bucket Selection
+
+Set `c.set("uploadBucket", "tenant-bucket-name")` before calling `handleUpload` (or `parseUpload`) to override the default bucket on a per-request basis. Supported by `s3Storage` — `meta.bucket` takes priority over `config.bucket`.
+
+```typescript
+router.use("/uploads/*", async (c, next) => {
+  const tenant = c.get("tenantId");
+  if (tenant) c.set("uploadBucket", `tenant-${tenant}`);
+  await next();
+});
+```
+
+### MIME Type Wildcards
+
+`allowedMimeTypes` supports exact matches and `type/*` wildcards:
+
+```typescript
+allowedMimeTypes: ["image/*", "video/mp4", "application/pdf"]
+```
+
+### Tenant-Scoped Keys
+
+When `tenantScopedKeys: true`, generated keys are prefixed with the request's `tenantId`:
+
+```
+uploads/tenant-abc/550e8400-e29b-41d4-a716-446655440000.jpg
+```
+
+### Context Variables
+
+| Variable | Type | Set by |
+|----------|------|--------|
+| `uploadResults` | `UploadResult[] \| null` | `handleUpload` middleware |
+| `uploadBucket` | `string \| undefined` | Application code (per-request bucket override) |
+
+### `parseUpload` (lower-level)
+
+`parseUpload(c, opts?)` is the underlying function used by `handleUpload`. It returns `UploadResult[]` directly without touching `c.set("uploadResults", ...)`. Use it when you need more control over the response or want to handle results inline:
+
+```typescript
+import { parseUpload } from "@lastshotlabs/bunshot";
+
+router.post("/avatar", async (c) => {
+  const [result] = await parseUpload(c, { field: "avatar", maxFiles: 1, allowedMimeTypes: ["image/*"] });
+  await db.users.update({ id: c.get("authUserId")! }, { avatar: result.key });
+  return c.json({ key: result.key });
+});
+```

package/docs/sections/versioning/full.md

@@ -0,0 +1,85 @@
+## API Versioning
+
+Mount multiple API versions with isolated OpenAPI specs and Scalar docs pages.
+
+### Directory Structure
+
+```
+routes/
+├── v1/
+│   └── users.ts          # v1-specific routes
+├── v2/
+│   └── users.ts          # v2-specific routes (breaking changes)
+└── shared/
+    └── health.ts         # appears in all versions, unprefixed schemas
+```
+
+### Configuration
+
+```typescript
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  versioning: {
+    versions: ["v1", "v2"],   // subdirectories under routesDir
+    defaultVersion: "v2",     // which version /docs and /openapi.json redirect to (default: last)
+    sharedDir: "shared",      // shared routes dir (default: "shared", set false to disable)
+  },
+});
+```
+
+**What gets mounted:**
+
+| Path | Description |
+|------|-------------|
+| `/v1/users`, `/v2/users` | Version-specific route handlers |
+| `/v1/openapi.json`, `/v2/openapi.json` | Isolated OpenAPI specs |
+| `/v1/docs`, `/v2/docs` | Scalar docs per version |
+| `/docs` | Version selector page (links to each version's docs) |
+| `/openapi.json` | 302 redirect to `/{defaultVersion}/openapi.json` (no merged spec) |
+
+### Route Files
+
+Route files are unchanged — use `createRouter()` and `createRoute()` as normal:
+
+```typescript
+// routes/v2/users.ts
+import { createRouter, createRoute } from "@lastshotlabs/bunshot";
+import { z } from "zod";
+
+export const router = createRouter();
+
+const ListUsersRoute = createRoute({
+  method: "get",
+  path: "/users",
+  responses: {
+    200: {
+      description: "Users",
+      content: { "application/json": { schema: z.object({ users: z.array(UserSchema) }) } },
+    },
+  },
+});
+
+router.openapi(ListUsersRoute, (c) => c.json({ users: [] }));
+```
+
+Schema names are automatically prefixed with the version: `GET /users` in v1 → `V1GetUsersResponse`, in v2 → `V2GetUsersResponse`. This prevents phantom types in generated TypeScript clients when both specs share a registry.
+
+### Shared Routes
+
+Routes in the `shared/` directory are mounted on every versioned app. Their schemas receive **no version prefix** since they are version-agnostic. Shared route files must be stateless — Hono mounts a reference (not a clone), so the same router instance is shared across all versioned apps. Standard `createRouter()` routers are stateless by design.
+
+### Unreferenced Schema Stripping
+
+Each version's spec is post-processed to remove `components/schemas` entries not referenced by that version's routes. This prevents schema bleed from the global OpenAPI registry into specs that don't use them.
+
+`stripUnreferencedSchemas` is also exported from the package for apps that serve OpenAPI specs via custom handlers.
+
+### No Merged Spec
+
+There is no combined spec at `/openapi.json`. Root `/openapi.json` returns a `302` redirect to the default version's spec. This is intentional — merging specs from multiple versions produces ambiguous schema names and defeats the isolation benefit.
+
+### Notes
+
+- **Avoid unbounded top-level `await` in route files.** The framework sets the version prefix module-level before importing each version's route files. A route file whose `createRoute()` calls run synchronously (the normal pattern) works correctly. If `createRoute()` is called after an unbounded top-level `await` (e.g., an unresolved DB call), the prefix may have changed. The framework throws a clear startup error if this is detected.
+- **Non-versioned behavior is unchanged.** If `versioning` is not set, routes are discovered at `routesDir/**/*.ts` and mounted at root exactly as before.
+- **Priority ordering works per-version.** Export `export const priority = <number>` from a versioned route file to control load order within that version.

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

@@ -0,0 +1,100 @@
+## Webhook Authentication
+
+`webhookAuth` is a middleware that verifies HMAC signatures on incoming webhook requests. It supports GitHub-style signing, multiple algorithms, replay protection, and per-request dynamic secrets.
+
+```ts
+import { webhookAuth } from "@lastshotlabs/bunshot";
+```
+
+### Basic usage
+
+```ts
+// routes/webhooks.ts
+import { webhookAuth } from "@lastshotlabs/bunshot";
+import { createRouter } from "@lastshotlabs/bunshot";
+
+export const router = createRouter();
+
+router.post(
+  "/webhooks/stripe",
+  webhookAuth({ secret: process.env.STRIPE_WEBHOOK_SECRET! }),
+  async (c) => {
+    const event = await c.req.json();
+    // body is still readable — Hono caches it after webhookAuth reads it
+    return c.json({ received: true });
+  }
+);
+```
+
+### GitHub-style (prefix + sha256)
+
+GitHub sends `X-Hub-Signature-256: sha256=<hex>`. Use `prefix` to strip the `sha256=` before comparing:
+
+```ts
+router.post(
+  "/webhooks/github",
+  webhookAuth({
+    secret: process.env.GITHUB_WEBHOOK_SECRET!,
+    header: "x-hub-signature-256",
+    prefix: "sha256=",
+    algorithm: "sha256",
+  }),
+  async (c) => c.json({ ok: true })
+);
+```
+
+If the header value does **not** start with the configured prefix, the full value is compared as-is — the prefix is stripped when present, not required.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `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"` | `"sha256"` | HMAC algorithm. |
+| `prefix` | `string` | — | Strip this prefix before comparing (e.g. `"sha256="` for GitHub). |
+| `timestamp` | `{ header, tolerance }` | — | Opt-in replay protection (see below). |
+
+### Replay protection
+
+Pass `timestamp` to reject requests with a stale timestamp header:
+
+```ts
+webhookAuth({
+  secret: process.env.WEBHOOK_SECRET!,
+  timestamp: {
+    header: "x-webhook-timestamp",  // header name carrying the Unix timestamp
+    tolerance: 300_000,             // 5 minutes in ms
+  },
+})
+```
+
+- Values `< 1e10` in the header are treated as Unix **seconds** and auto-converted to ms
+- Missing or non-numeric timestamps → `401 EXPIRED_TIMESTAMP`
+- Timestamp outside `tolerance` → `401 EXPIRED_TIMESTAMP`
+- Signature check runs after the timestamp check passes
+
+### Dynamic secrets (multi-tenant)
+
+Pass a function to resolve the secret per request — useful when each tenant has its own webhook secret:
+
+```ts
+webhookAuth({
+  secret: async (c) => {
+    const tenantId = c.req.header("x-tenant-id");
+    const tenant = await getTenantWebhookSecret(tenantId);
+    if (!tenant) throw new Error("unknown tenant");
+    return tenant.webhookSecret;
+  },
+})
+```
+
+If the function throws, the request receives `500 { code: "WEBHOOK_SECRET_ERROR" }`.
+
+### Error responses
+
+| Condition | Status | `code` |
+|-----------|--------|--------|
+| Missing or invalid signature | `401` | `INVALID_SIGNATURE` |
+| Missing, non-numeric, or expired timestamp | `401` | `EXPIRED_TIMESTAMP` |
+| Secret function threw | `500` | `WEBHOOK_SECRET_ERROR` |