@lastshotlabs/bunshot 0.0.21 → 0.0.25

package/docs/sections/pagination/full.md

@@ -0,0 +1,93 @@
+## Pagination Helpers
+
+Shared Zod schema factories and parse utilities for offset and cursor pagination. Both patterns produce named OpenAPI components and eliminate repeated `parseInt`/clamping boilerplate in route files.
+
+### Offset pagination
+
+```ts
+import {
+  offsetParams, parseOffsetParams, paginatedResponse,
+} from "@lastshotlabs/bunshot";
+
+const ItemSchema = z.object({ id: z.string(), name: z.string() });
+
+// Schema factories — call once at module scope
+const querySchema = offsetParams({ limit: 20, maxLimit: 100 });
+const responseSchema = paginatedResponse(ItemSchema, "PaginatedItems");
+
+router.openapi(
+  createRoute({
+    method: "get",
+    path: "/items",
+    request: { query: querySchema },
+    responses: { 200: { content: { "application/json": { schema: responseSchema } }, description: "ok" } },
+  }),
+  async (c) => {
+    const { limit, offset } = parseOffsetParams(c.req.query(), { maxLimit: 100 });
+    const [items, total] = await Promise.all([
+      Item.find().skip(offset).limit(limit),
+      Item.countDocuments(),
+    ]);
+    return c.json({ items, total, limit, offset });
+  }
+);
+```
+
+`paginatedResponse(itemSchema, name)` wraps the item schema in `{ items: T[], total: number, limit: number, offset: number }` and registers the result as a named OpenAPI component. Calling it with the same name and schema instance is idempotent; calling it with the same name but a different schema throws at startup.
+
+`parseOffsetParams` clamps `limit` to `[1, maxLimit]` and `offset` to `[0, ∞)`. Non-numeric values fall back to defaults. Floats are truncated via `parseInt`.
+
+### Cursor pagination
+
+```ts
+import {
+  cursorParams, parseCursorParams, cursorResponse,
+  type CursorResult,
+} from "@lastshotlabs/bunshot";
+
+const postQuerySchema = cursorParams({ limit: 25 });
+const postResponseSchema = cursorResponse(PostSchema, "PostsPage");
+
+router.openapi(
+  createRoute({
+    method: "get",
+    path: "/posts",
+    request: { query: postQuerySchema },
+    responses: { 200: { content: { "application/json": { schema: postResponseSchema } }, description: "ok" } },
+  }),
+  async (c) => {
+    const { limit, cursor } = parseCursorParams(c.req.query(), { limit: 25 });
+    const filter = cursor ? { _id: { $lt: cursor } } : {};
+    const items = await Post.find(filter).sort({ _id: -1 }).limit(limit + 1);
+    const hasMore = items.length > limit;
+    const page = hasMore ? items.slice(0, limit) : items;
+    return c.json({
+      items: page,
+      nextCursor: hasMore ? page[page.length - 1].id : null,
+      hasMore,
+    });
+  }
+);
+```
+
+`cursorResponse(itemSchema, name)` wraps the item schema in `{ items: T[], nextCursor: string | null, hasMore: boolean }`. The `cursor` field is opaque — the service layer decides encoding (ID, timestamp, base64 composite key). An empty cursor string is normalized to `undefined` by `parseCursorParams`.
+
+### TypeScript result type
+
+Use `CursorResult<T>` to type the return value of cursor-paginated service functions:
+
+```ts
+import type { CursorResult } from "@lastshotlabs/bunshot";
+
+async function listPosts(limit: number, cursor?: string): Promise<CursorResult<Post>> {
+  // ...
+}
+```
+
+### Defaults reference
+
+| Parameter | Default | Notes |
+|-----------|---------|-------|
+| `limit` | `50` | Override via `defaults.limit` |
+| `maxLimit` | `200` | Limit clamped to this ceiling |
+| `offset` | `0` | Offset pagination only |

package/docs/sections/roles/full.md

@@ -1,136 +1,225 @@
-## 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 |
+### 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,4 +1,4 @@
-## Roles
+### Roles
 
 Declare roles in `createServer({ auth: { roles: ["admin", "editor", "user"], defaultRole: "user" } })`. The default role is auto-assigned on registration.
 
@@ -10,3 +10,5 @@ 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/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.