@lastshotlabs/bunshot 0.0.27 → 0.0.28

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

@@ -1,117 +0,0 @@
-## Response Caching
-
-Cache GET responses and bust them from mutation endpoints. Supports Redis, MongoDB, SQLite, and memory stores. The cache key is automatically namespaced by `appName` (`cache:{appName}:{key}`), so shared instances across tenant apps never collide.
-
-### Basic usage
-
-```ts
-import { cacheResponse, bustCache } from "@lastshotlabs/bunshot";
-
-// GET — cache the response for 60 seconds in Redis (default)
-router.use("/products", cacheResponse({ ttl: 60, key: "products" }));
-
-// indefinite — cached until busted
-router.use("/config", cacheResponse({ key: "config" }));
-
-router.get("/products", async (c) => {
-  const items = await Product.find();
-  return c.json({ items });
-});
-
-// POST — write data, then bust the shared key (hits all connected stores)
-router.post("/products", userAuth, async (c) => {
-  const body = await c.req.json();
-  await Product.create(body);
-  await bustCache("products");
-  return c.json({ ok: true }, 201);
-});
-```
-
-The `key` string is the shared contract — `cacheResponse` stores under it, `bustCache` deletes it. Responses include an `x-cache: HIT` or `x-cache: MISS` header.
-
-### Choosing a cache store
-
-Pass `store` to select where the response is cached. Defaults to `"redis"`.
-
-```ts
-// Redis (default)
-cacheResponse({ key: "products", ttl: 60 })
-
-// MongoDB — uses appConnection, stores in the `cache_entries` collection
-// TTL is handled natively via a MongoDB expiry index on the expiresAt field
-cacheResponse({ key: "products", ttl: 300, store: "mongo" })
-
-// SQLite — uses the same .db file as sqliteAuthAdapter; requires setSqliteDb or sqliteDb config
-cacheResponse({ key: "products", ttl: 60, store: "sqlite" })
-
-// Memory — in-process Map, ephemeral (cleared on restart), no external dependencies
-cacheResponse({ key: "products", ttl: 60, store: "memory" })
-```
-
-Use SQLite when running without Redis or MongoDB. Use MongoDB when you want cache entries co-located with your app data. Use Redis for lower-latency hot caches. Use Memory for tests or single-process apps where persistence isn't needed.
-
-**Connection requirements:** The chosen store must be initialized when the route is first hit. If `store: "sqlite"` is used but `setSqliteDb` has not been called (e.g. `sqliteDb` was not passed to `createServer`), the middleware throws a clear error on the first request. The same applies to the other stores.
-
-### Busting cached entries
-
-`bustCache` always attempts all four stores (Redis, Mongo, SQLite, Memory), skipping any that aren't connected. This means it works correctly regardless of which `store` option your routes use, and is safe to call in apps that don't use all stores:
-
-```ts
-await bustCache("products"); // hits whichever stores are connected
-```
-
-### Per-user caching
-
-The `key` function receives the full Hono context, so you can scope cache entries to the authenticated user:
-
-```ts
-router.use("/feed", userAuth, cacheResponse({
-  ttl: 60,
-  key: (c) => `feed:${c.get("authUserId")}`,
-}));
-```
-
-`authUserId` is populated by `identify`, which always runs before route middleware, so it's safe to use here.
-
-### Per-resource caching
-
-For routes with dynamic segments, use the function form of `key`. Produce the same string in `bustCache`:
-
-```ts
-// GET /products/:id
-router.use("/products/:id", cacheResponse({
-  ttl: 60,
-  key: (c) => `product:${c.req.param("id")}`,
-}));
-
-router.get("/products/:id", async (c) => {
-  const item = await Product.findById(c.req.param("id"));
-  return c.json(item);
-});
-
-// PUT /products/:id
-router.put("/products/:id", userAuth, async (c) => {
-  const id = c.req.param("id");
-  await Product.findByIdAndUpdate(id, await c.req.json());
-  await bustCache(`product:${id}`);
-  return c.json({ ok: true });
-});
-```
-
-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:
-
-```ts
-import { bustCachePattern } from "@lastshotlabs/bunshot";
-
-// key includes query params: `balance:${userId}:${from}:${to}:${groupBy}`
-// bust all balance entries for this user regardless of params
-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.

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

@@ -1,13 +0,0 @@
-## Response Caching
-
-Cache GET responses with `cacheResponse({ ttl, key })` and bust them with `bustCache(key)`. Supports Redis, MongoDB, SQLite, and memory stores. Cache keys are auto-namespaced by app name and tenant (when multi-tenancy is active).
-
-```ts
-import { cacheResponse, bustCache } from "@lastshotlabs/bunshot";
-
-router.use("/products", cacheResponse({ ttl: 60, key: "products" }));
-// ...
-await bustCache("products"); // hits all connected stores
-```
-
-Supports per-user caching via `key: (c) => ...`, per-resource caching, and wildcard invalidation via `bustCachePattern("products:*")`.

package/docs/sections/roles/full.md

@@ -1,225 +0,0 @@
-### Roles
-
-#### Setup
-
-Declare the valid roles for your app in `createServer` / `createApp`:
-
-```ts
-await createServer({
-  auth: {
-    roles: ["admin", "editor", "user"],
-    defaultRole: "user",  // automatically assigned on /auth/register
-  },
-  // ...
-});
-```
-
-`roles` makes the list available anywhere via `getAppRoles()`. `defaultRole` is assigned to every new user that registers via `POST /auth/register` — no extra code needed.
-
-#### Assigning roles to a user
-
-Three helpers are available depending on what you need:
-
-| Helper | Behaviour |
-|---|---|
-| `setUserRoles(userId, roles)` | Replace all roles — pass the full desired set |
-| `addUserRole(userId, role)` | Add a single role, leaving others unchanged |
-| `removeUserRole(userId, role)` | Remove a single role, leaving others unchanged |
-
-```ts
-import { setUserRoles, addUserRole, removeUserRole, userAuth, requireRole } from "@lastshotlabs/bunshot";
-
-// promote a user to admin
-router.post("/admin/users/:id/promote", userAuth, requireRole("admin"), async (c) => {
-  await addUserRole(c.req.param("id"), "admin");
-  return c.json({ ok: true });
-});
-
-// revoke a role
-router.post("/admin/users/:id/demote", userAuth, requireRole("admin"), async (c) => {
-  await removeUserRole(c.req.param("id"), "admin");
-  return c.json({ ok: true });
-});
-
-// replace all roles at once
-router.put("/admin/users/:id/roles", userAuth, requireRole("admin"), async (c) => {
-  const { roles } = await c.req.json();
-  await setUserRoles(c.req.param("id"), roles);
-  return c.json({ ok: true });
-});
-```
-
-#### Protecting routes by role
-
-`requireRole` is a middleware factory. It lazy-fetches roles on the first role-checked request and caches them on the Hono context, so multiple `requireRole` calls in a middleware chain only hit the DB once.
-
-```ts
-import { userAuth, requireRole } from "@lastshotlabs/bunshot";
-
-router.use("/admin", userAuth, requireRole("admin"));
-router.use("/content", userAuth, requireRole("admin", "editor")); // allow either role
-```
-
-| Scenario | Response |
-|---|---|
-| No session | `401 Unauthorized` |
-| Authenticated, wrong role | `403 Forbidden` |
-| Authenticated, correct role | passes through |
-
-#### Custom adapter with roles
-
-If you're using a custom `authAdapter`, implement the role methods to back role operations with your own store:
-
-| Method | Required for |
-|---|---|
-| `getRoles(userId)` | `requireRole` middleware |
-| `setRoles(userId, roles)` | `defaultRole` assignment on registration, full replace |
-| `addRole(userId, role)` | Granular role addition |
-| `removeRole(userId, role)` | Granular role removal |
-
-All are optional — only implement what your app uses. `setRoles` is **required** if you configure `defaultRole` (the app will throw at startup if this combination is misconfigured). The exported helpers `setUserRoles`, `addUserRole`, and `removeUserRole` route through your adapter, so they work regardless of which store you use.
-
-```ts
-const myAdapter: AuthAdapter = {
-  findByEmail: ...,
-  create: ...,
-  async getRoles(userId) {
-    const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
-    return user?.roles ?? [];
-  },
-  async setRoles(userId, roles) {
-    await db.update(users).set({ roles }).where(eq(users.id, userId));
-  },
-  async addRole(userId, role) {
-    const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
-    if (user && !user.roles.includes(role)) {
-      await db.update(users).set({ roles: [...user.roles, role] }).where(eq(users.id, userId));
-    }
-  },
-  async removeRole(userId, role) {
-    const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
-    if (user) {
-      await db.update(users).set({ roles: user.roles.filter((r: string) => r !== role) }).where(eq(users.id, userId));
-    }
-  },
-};
-```
-
-#### Tenant-scoped roles
-
-When multi-tenancy is enabled (see below), `requireRole` automatically checks **tenant-scoped roles** instead of app-wide roles when a `tenantId` is present in the request context.
-
-```ts
-// Assign a tenant-scoped role
-import { addTenantRole, setTenantRoles, removeTenantRole, getTenantRoles } from "@lastshotlabs/bunshot";
-
-await addTenantRole(userId, "acme", "admin");
-await setTenantRoles(userId, "acme", ["admin", "editor"]);
-await removeTenantRole(userId, "acme", "editor");
-const roles = await getTenantRoles(userId, "acme"); // ["admin"]
-```
-
-`requireRole("admin")` checks tenant-scoped roles when `tenantId` is in context, and falls back to app-wide roles when there is no tenant context. Use `requireRole.global("superadmin")` to always check app-wide roles regardless of tenant.
-
-```ts
-router.use("/tenant-admin", userAuth, requireRole("admin"));           // checks tenant roles when in tenant context
-router.use("/super-admin", userAuth, requireRole.global("superadmin")); // always checks app-wide roles
-```
-
-If you're using a custom `authAdapter`, implement the tenant role methods:
-
-| Method | Purpose |
-|---|---|
-| `getTenantRoles(userId, tenantId)` | Required for tenant-scoped `requireRole` |
-| `setTenantRoles(userId, tenantId, roles)` | Full replace |
-| `addTenantRole(userId, tenantId, role)` | Granular addition |
-| `removeTenantRole(userId, tenantId, role)` | Granular removal |
-
-#### Groups
-
-Groups are named collections of users that grant roles additively. They sit on top of direct role assignments — effective roles are always `directRoles ∪ groupBaselineRoles ∪ membershipRoles` (deduplicated).
-
-**Role model:** Each group carries a `roles[]` array that all members inherit. Each `GroupMembership` also carries its own `roles[]` for per-member extras on top of the group baseline.
-
-```ts
-import {
-  createGroup, deleteGroup, getGroup, listGroups, updateGroup,
-  addGroupMember, updateGroupMembership, removeGroupMember,
-  getGroupMembers, getUserGroups, getEffectiveRoles,
-} from "@lastshotlabs/bunshot";
-
-// Create a group (app-wide; tenantId: null)
-const { id } = await createGroup({ name: "editors", roles: ["editor"], tenantId: null });
-
-// Add a member with optional per-membership extras
-await addGroupMember(id, userId, ["editor-lead"]); // throws 409 if already a member
-
-// Effective roles = direct + group baseline + per-membership (deduplicated)
-const roles = await getEffectiveRoles(userId, null); // ["editor", "editor-lead"]
-```
-
-**Scope:** Groups are either app-wide (`tenantId: null`) or tenant-scoped (`tenantId: string`). Tenant-scoped group roles only count when `requireRole` runs in that tenant's context — they never satisfy `requireRole.global`.
-
-```ts
-// tenant-scoped group: roles only visible within that tenant's context
-await createGroup({ name: "tenant-admins", roles: ["admin"], tenantId: "acme" });
-await addGroupMember(groupId, userId);
-
-// Within acme's request context → requireRole("admin") passes
-// requireRole.global("admin") → NEVER satisfied by a tenant-scoped group
-```
-
-**`tenantId` is immutable** after creation. To move a group to a different scope, delete it and recreate it.
-
-##### Management routes
-
-Enable built-in REST endpoints for managing groups:
-
-```ts
-await createServer({
-  groups: {
-    managementRoutes: true, // default guard: requireRole.global("admin")
-  },
-});
-```
-
-| Option | Type | Description |
-|---|---|---|
-| `managementRoutes` | `true \| { adminRole?, middleware? }` | Enable management routes |
-| `adminRole` | `string` | Role required (default: `"admin"`); uses `requireRole.global` |
-| `middleware` | `MiddlewareHandler[]` | Fully replaces the default `[userAuth, requireRole.global(adminRole)]` stack |
-
-Routes mounted at the root:
-
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/groups` | List groups (tenant-scoped if `tenantId` in context, else app-wide) |
-| `POST` | `/groups` | Create group (`name` must match `/^[a-z0-9_-]+$/`) |
-| `GET` | `/groups/:groupId` | Get group |
-| `PATCH` | `/groups/:groupId` | Update name / displayName / description / roles |
-| `DELETE` | `/groups/:groupId` | Delete group (cascades memberships) |
-| `GET` | `/groups/:groupId/members` | List members with per-membership roles |
-| `POST` | `/groups/:groupId/members` | Add member `{ userId, roles? }` |
-| `PATCH` | `/groups/:groupId/members/:userId` | Update member's per-membership roles |
-| `DELETE` | `/groups/:groupId/members/:userId` | Remove member |
-| `GET` | `/users/:userId/groups` | List user's groups with `membershipRoles` |
-
-All list endpoints are paginated (`?limit=&offset=`).
-
-##### Custom adapter
-
-Implement these methods on your `AuthAdapter` to back groups with your own store:
-
-| Method | Purpose |
-|---|---|
-| `createGroup(group)` | Create group; throw `HttpError(409, ...)` on duplicate name in scope |
-| `deleteGroup(groupId)` | Delete group + cascade memberships |
-| `getGroup(groupId)` | Fetch by ID |
-| `listGroups(tenantId, opts?)` | Paginated list scoped to `tenantId` |
-| `updateGroup(groupId, updates)` | Update name/displayName/description/roles |
-| `addGroupMember(groupId, userId, roles?)` | Add member; **must throw 409** if already a member |
-| `updateGroupMembership(groupId, userId, roles)` | Update per-membership roles in-place |
-| `removeGroupMember(groupId, userId)` | Remove member |
-| `getGroupMembers(groupId, opts?)` | Paginated member list |
-| `getUserGroups(userId, tenantId)` | All groups for a user in a scope |
-| `getEffectiveRoles(userId, tenantId)` | Compute effective roles (required — no fallback) |

package/docs/sections/roles/overview.md

@@ -1,14 +0,0 @@
-### Roles
-
-Declare roles in `createServer({ auth: { roles: ["admin", "editor", "user"], defaultRole: "user" } })`. The default role is auto-assigned on registration.
-
-```ts
-import { userAuth, requireRole, addUserRole } from "@lastshotlabs/bunshot";
-
-router.use("/admin", userAuth, requireRole("admin"));
-await addUserRole(userId, "admin"); // also: setUserRoles, removeUserRole
-```
-
-Tenant-scoped roles are supported when multi-tenancy is enabled — `requireRole` checks tenant roles when `tenantId` is in context, falls back to app-wide roles otherwise. Use `requireRole.global("superadmin")` to always check app-wide roles.
-
-**Groups** are named user collections that grant roles additively. Effective roles = `directRoles ∪ groupBaselineRoles ∪ membershipRoles`. Groups are either app-wide (`tenantId: null`) or tenant-scoped — tenant group roles never satisfy `requireRole.global`. Enable managed REST endpoints via `groups: { managementRoutes: true }` in config.

package/docs/sections/running-without-redis/full.md

@@ -1,16 +0,0 @@
-## Running without Redis
-
-Set `db.redis: false` and `db.sessions: "mongo"` to run the entire auth flow on MongoDB only. Sessions, OAuth state, and response caching (when `store: "mongo"`) all work without Redis. The only feature that still requires Redis is BullMQ queues.
-
-```ts
-await createServer({
-  db: {
-    mongo: "single",
-    redis: false,
-    sessions: "mongo",   // sessions + OAuth state → MongoDB
-    cache: "mongo",      // or omit cacheResponse entirely if not using it
-  },
-});
-```
-
-Redis key namespacing: when Redis is used, all keys are prefixed with `appName` (`session:{appName}:{sessionId}`, `usersessions:{appName}:{userId}`, `oauth:{appName}:state:{state}`, `cache:{appName}:{key}`) so multiple apps sharing one Redis instance never collide.

package/docs/sections/running-without-redis-or-mongodb/full.md

@@ -1,60 +0,0 @@
-## Running without Redis or MongoDB
-
-Two lightweight options for local dev, tests, or small projects with no external services:
-
-### SQLite — persisted to disk
-
-Uses `bun:sqlite` (built into Bun, zero npm deps). A single `.db` file holds all users, sessions, OAuth state, and cache.
-
-```ts
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  app: { name: "My App", version: "1.0.0" },
-  db: {
-    auth: "sqlite",
-    sqlite: import.meta.dir + "/../data.db",  // created automatically on first run
-    mongo: false,
-    redis: false,
-    sessions: "sqlite",
-    cache: "sqlite",
-  },
-});
-```
-
-#### Optional: periodic cleanup of expired rows
-
-Expired rows are filtered out lazily on read. For long-running servers, sweep them periodically:
-
-```ts
-import { startSqliteCleanup } from "@lastshotlabs/bunshot";
-
-startSqliteCleanup();           // default: every hour
-startSqliteCleanup(5 * 60_000); // custom interval (ms)
-```
-
-### Memory — ephemeral, great for tests
-
-Pure in-memory Maps. No files, no external services. All state is lost on process restart.
-
-```ts
-import { createServer, clearMemoryStore } from "@lastshotlabs/bunshot";
-
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  app: { name: "My App", version: "1.0.0" },
-  db: {
-    auth: "memory",
-    mongo: false,
-    redis: false,
-    sessions: "memory",
-    cache: "memory",
-  },
-});
-
-// In tests — reset all state between test cases:
-clearMemoryStore();
-```
-
-### Limitations (both sqlite and memory)
-
-- BullMQ queues still require Redis

package/docs/sections/signing/full.md

@@ -1,203 +0,0 @@
-## 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/stack/full.md

@@ -1,10 +0,0 @@
-## Stack
-
-- **Runtime**: [Bun](https://bun.sh)
-- **Framework**: [Hono](https://hono.dev) + [@hono/zod-openapi](https://github.com/honojs/middleware/tree/main/packages/zod-openapi)
-- **Docs UI**: [Scalar](https://scalar.com)
-- **Data / Auth**: MongoDB, SQLite, or in-memory — configurable via `db.auth` (default: MongoDB via [Mongoose](https://mongoosejs.com))
-- **Cache / Sessions**: Redis, MongoDB, SQLite, or in-memory — configurable via `db.sessions` / `db.cache` (default: Redis via [ioredis](https://github.com/redis/ioredis))
-- **Auth**: JWT via [jose](https://github.com/panva/jose), HttpOnly cookies + `x-user-token` header
-- **Queues**: [BullMQ](https://docs.bullmq.io) (requires Redis with `noeviction` policy)
-- **Validation**: [Zod v4](https://zod.dev)