@lastshotlabs/bunshot 0.0.25 → 0.0.28

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)