@lastshotlabs/bunshot 0.0.21 → 0.0.27

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/passkey-login/full.md

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

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

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

package/docs/sections/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.