@classytic/arc 2.6.2 → 2.7.1

package/skills/arc/SKILL.md

@@ -8,11 +8,11 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.6.2
+version: 2.7.1
 license: MIT
 metadata:
   author: Classytic
-  version: "2.6.2"
+  version: "2.7.1"
 tags:
   - fastify
   - rest-api
@@ -126,15 +126,57 @@ auth: false
 
 **Decorates:** `app.authenticate`, `app.optionalAuthenticate`, `app.authorize`
 
+### Better Auth + Mongoose populate bridge (`@classytic/arc/auth/mongoose`)
+
+When BA uses `@better-auth/mongo-adapter`, it writes via the native `mongodb` driver and never registers Mongoose models. arc resources doing `Schema({ userId: { ref: 'user' } })` then throw `MissingSchemaError` on `.populate()`.
+
+```typescript
+import mongoose from 'mongoose';
+import { registerBetterAuthMongooseModels } from '@classytic/arc/auth/mongoose';
+
+// Default: core only (user/session/account/verification). Plugins are opt-in.
+registerBetterAuthMongooseModels(mongoose, {
+  plugins: ['organization', 'organization-teams', 'mcp'],
+  // For separate @better-auth/* packages (passkey, sso, api-key):
+  extraCollections: ['passkey', 'ssoProvider'],
+  // Optional:
+  usePlural: false,                                     // matches mongodbAdapter({ usePlural })
+  modelOverrides: { user: 'profile' },                  // for custom user.modelName configs
+});
+```
+
+**Plugin keys** (core BA only — separate packages use `extraCollections`):
+- `organization` → `organization`, `member`, `invitation`
+- `organization-teams` → `team`, `teamMember`
+- `twoFactor` → `twoFactor`
+- `jwt` → `jwks`
+- `oidcProvider` / `oauthProvider` (alias) → `oauthApplication`, `oauthAccessToken`, `oauthConsent`
+- `mcp` → reuses oidcProvider schema (per BA docs)
+- `deviceAuthorization` → `deviceCode`
+
+**Field-only plugins** (admin, username, phoneNumber, magicLink, emailOtp, anonymous, bearer, multiSession, siwe, lastLoginMethod, genericOAuth) need NO entry — `strict: false` stubs round-trip extra fields automatically.
+
+Lives at a dedicated subpath so non-Mongoose users (Prisma/Drizzle/Kysely) never get Mongoose pulled into their bundle. Idempotent + de-dupes overlapping plugin sets, so `plugins: ['mcp', 'oidcProvider']` won't crash.
+
 ## Permissions
 
-Function-based. A `PermissionCheck` returns `boolean | { granted, reason?, filters? }`:
+Function-based. A `PermissionCheck` returns `boolean | { granted, reason?, filters?, scope? }`:
 
 ```typescript
 import {
+  // Core
   allowPublic, requireAuth, requireRoles, requireOwnership,
+  // Org-bound
   requireOrgMembership, requireOrgRole, requireTeamMembership,
+  // Service / API key (OAuth-style)
+  requireServiceScope,
+  // App-defined scope dimensions (branch, project, region, …)
+  requireScopeContext,
+  // Parent-child org hierarchy
+  requireOrgInScope,
+  // Combinators
   allOf, anyOf, when, denyAll,
+  // Dynamic ACL
   createDynamicPermissionMatrix,
 } from '@classytic/arc';
 
@@ -147,6 +189,173 @@ permissions: {
 }
 ```
 
+**Mixed human + machine routes** — accept both an org admin and an API key:
+
+```typescript
+import { requireServiceScope } from '@classytic/arc';
+
+permissions: {
+  // Human admins OR API keys with the right OAuth scope
+  create: anyOf(
+    requireOrgRole('admin'),
+    requireServiceScope('jobs:write'),
+  ),
+
+  // Org-bound API key with a specific scope (no human path)
+  bulkImport: allOf(
+    requireOrgMembership(),                  // accepts member, service, elevated
+    requireServiceScope('jobs:bulk-write'),  // OAuth-style scope check
+  ),
+}
+```
+
+**Multi-level tenancy** — for app-defined scope dimensions beyond org/team
+(branch, project, region, workspace, department, …):
+
+```typescript
+import { requireScopeContext } from '@classytic/arc';
+import { multiTenantPreset } from '@classytic/arc/presets';
+
+// 1. Populate scope.context in your auth function (from headers, JWT claims,
+//    BA session fields — arc takes no position on the source).
+authFn: async (request) => {
+  const session = await myAuth.getSession(request);
+  request.scope = {
+    kind: 'member',
+    userId: session.userId,
+    userRoles: session.userRoles,
+    organizationId: session.orgId,
+    orgRoles: session.orgRoles,
+    context: {
+      branchId: request.headers['x-branch-id'],
+      projectId: request.headers['x-project-id'],
+    },
+  };
+}
+
+// 2. Gate routes by context dimensions
+permissions: {
+  branchAdmin: allOf(requireOrgRole('admin'), requireScopeContext('branchId')),
+  euOnly:      requireScopeContext('region', 'eu'),
+  projectEdit: requireScopeContext({ projectId: undefined, region: 'eu' }),
+}
+
+// 3. Auto-filter resource queries across all dimensions in lockstep
+defineResource({
+  name: 'job',
+  presets: [
+    multiTenantPreset({
+      tenantFields: [
+        { field: 'organizationId', type: 'org' },
+        { field: 'branchId',       contextKey: 'branchId' },
+        { field: 'projectId',      contextKey: 'projectId' },
+      ],
+    }),
+  ],
+});
+```
+
+Fail-closed: missing dimensions → 403 with the specific missing field name.
+Elevated scopes (platform admins) apply whatever resolves and skip the rest
+(cross-context bypass).
+
+**Parent-child org hierarchy** — for holding companies, MSPs managing
+multiple tenants, white-label parent → child accounts. Arc takes no position
+on the source: your auth function loads the chain from your own org table.
+
+```typescript
+import { requireOrgInScope } from '@classytic/arc';
+
+// 1. Auth function loads ancestorOrgIds from your org table.
+//    Order is closest-first (immediate parent → root).
+authFn: async (request) => {
+  const session = await myAuth.getSession(request);
+  const ancestors = await orgRepo.findAncestors(session.orgId);
+  request.scope = {
+    kind: 'member',
+    userId: session.userId,
+    userRoles: session.userRoles,
+    organizationId: session.orgId,
+    orgRoles: session.orgRoles,
+    ancestorOrgIds: ancestors.map(a => a.id),  // ['acme-eu', 'acme-holding']
+  };
+}
+
+// 2. Gate routes — accepts current org or any ancestor in the chain
+permissions: {
+  // GET /orgs/:orgId/jobs — caller can act on any org in their hierarchy
+  list: requireOrgInScope((ctx) => ctx.request.params.orgId),
+
+  // Static target (rare): one route, one specific org
+  holdingDashboard: requireOrgInScope('acme-holding'),
+
+  // Composed: must be admin AND target must be in hierarchy
+  childAdmin: allOf(
+    requireOrgRole('admin'),
+    requireOrgInScope((ctx) => ctx.request.params.orgId),
+  ),
+}
+```
+
+**No automatic inheritance** — every check is explicit. `multiTenantPreset`
+does NOT auto-include ancestor data (would be a footgun). Sibling
+subsidiaries naturally don't see each other's data because they aren't in
+each other's chain. Elevated bypass still applies on the permission helper.
+
+**Auth source agnostic** — `requireRoles()` checks platform roles
+(`user.role`) AND org roles (`scope.orgRoles`) by default, so it works
+identically with arc JWT, Better Auth user roles, and Better Auth org plugin.
+`requireOrgMembership()` accepts `member`, `service` (API key), and
+`elevated` scopes. `requireOrgRole()` is human-only by design — use
+`anyOf(requireOrgRole(...), requireServiceScope(...))` for mixed routes.
+`scope.context` and `scope.ancestorOrgIds` are populated by your own auth
+function or adapter — arc doesn't bake in any specific dimension or transport.
+
+### RequestScope (quick reference)
+
+Five kinds, all opt-in. Always read via accessors from `@classytic/arc/scope`,
+never via direct property access.
+
+```typescript
+type RequestScope =
+  | { kind: 'public' }
+  | { kind: 'authenticated'; userId?; userRoles? }
+  | { kind: 'member';   userId?; userRoles; organizationId; orgRoles; teamId?; context?; ancestorOrgIds? }
+  | { kind: 'service';  clientId; organizationId; scopes?; context?; ancestorOrgIds? }
+  | { kind: 'elevated'; userId?; organizationId?; elevatedBy; context?; ancestorOrgIds? };
+```
+
+| Kind | Identity | Org context | Set by |
+|---|---|---|---|
+| `public` | none | none | Default for anonymous requests |
+| `authenticated` | userId, userRoles | none | Logged in, no active org |
+| `member` | userId, userRoles | organizationId + orgRoles (+ teamId, context, ancestorOrgIds) | BA org plugin / JWT custom auth |
+| `service` | clientId, scopes | organizationId (required) | API key via `PermissionResult.scope` |
+| `elevated` | userId | organizationId optional | Elevation plugin via `x-arc-scope: platform` header |
+
+| Helper | `member` | `service` | `elevated` |
+|---|---|---|---|
+| `requireOrgMembership()` | ✅ | ✅ | ✅ |
+| `requireOrgRole(roles)` | If role matches | ❌ deny w/ guidance | ✅ bypass |
+| `requireServiceScope(scopes)` | ❌ | If scope matches | ✅ bypass |
+| `requireScopeContext(...)` | If keys match | If keys match | ✅ bypass |
+| `requireTeamMembership()` | If `teamId` set | (n/a) | ✅ bypass |
+| `requireOrgInScope(target)` | If target in chain | If target in chain | ✅ bypass |
+
+```typescript
+import {
+  isMember, isService, isElevated, hasOrgAccess,
+  getOrgId, getUserId, getOrgRoles, getServiceScopes,
+  getScopeContext, getAncestorOrgIds, isOrgInScope,
+} from '@classytic/arc/scope';
+
+if (hasOrgAccess(scope))   // member | service | elevated
+if (isService(scope))      // narrows to API key
+const orgId  = getOrgId(scope);                    // member | service | elevated
+const branch = getScopeContext(scope, 'branchId'); // custom dimension
+isOrgInScope(scope, 'acme-holding');               // pure predicate (no elevated bypass)
+```
+
 **Custom permission:**
 
 ```typescript
@@ -187,15 +396,34 @@ permissions: { list: acl.canAction('product', 'read') }
 | `slugLookup` | GET /slug/:slug | `ISlugLookupController` | `{ slugField }` |
 | `tree` | GET /tree, GET /:parent/children | `ITreeController` | `{ parentField }` |
 | `ownedByUser` | none (middleware) | — | `{ ownerField }` |
-| `multiTenant` | none (middleware) | — | `{ tenantField }` |
+| `multiTenant` | none (middleware) | — | `{ tenantField }` OR `{ tenantFields: TenantFieldSpec[] }` (2.7.1+) |
 | `audited` | none (middleware) | — | — |
 | `bulk` | POST/PATCH/DELETE /bulk | — | `{ operations?, maxCreateItems? }` |
 
 ```typescript
+// Single-field (default, backwards compatible)
 presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
+
+// Multi-field — org + branch + project in lockstep (2.7.1+)
+presets: [
+  multiTenantPreset({
+    tenantFields: [
+      { field: 'organizationId', type: 'org' },                // → getOrgId(scope)
+      { field: 'teamId',         type: 'team' },               // → getTeamId(scope)
+      { field: 'branchId',       contextKey: 'branchId' },     // → scope.context.branchId
+      { field: 'projectId',      contextKey: 'projectId' },
+    ],
+  }),
+]
+
 // Bulk: presets: ['bulk'] or bulkPreset({ operations: ['createMany', 'updateMany'] })
 ```
 
+`multiTenant` recognizes `member`, `service` (API key), and `elevated`
+scopes uniformly via `hasOrgAccess()`. Multi-field uses fail-closed
+semantics: missing dimensions → 403 with the specific missing field name.
+Elevated scopes apply whatever resolves and skip the rest.
+
 ### tenantField — When to Use and When to Disable
 
 Arc defaults `tenantField` to `'organizationId'` on BaseController. This silently adds `{ organizationId: scope.organizationId }` to every query when the user has an org context. Correct for per-org resources, wrong for company-wide resources.
@@ -220,6 +448,31 @@ When to use `tenantField: false`:
 - Cross-org reports or analytics
 - Single-tenant apps where org scoping isn't needed
 
+### idField — Custom Primary Key
+
+Default is `'_id'`. Override for resources keyed by a business identifier (UUID, slug, `ORD-2026-0001`, `job-5219f346-a4d`, etc.).
+
+```typescript
+defineResource({
+  name: 'job',
+  adapter: createMongooseAdapter(JobModel, jobRepository),
+  idField: 'jobId',     // ← one line
+});
+
+// GET /jobs/job-5219f346-a4d  → controller runs { jobId: 'job-5219f346-a4d' }
+// GET /jobs/<uuid>             → accepted (no ObjectId pattern enforcement)
+```
+
+Changes all three layers:
+- **Fastify AJV** — strips any ObjectId pattern from `params.id` so custom formats aren't pre-rejected
+- **BaseController** — `get`/`update`/`delete` query by `{ [idField]: id }` (merged with tenant + policy filters)
+- **OpenAPI docs** — `spec.paths['/jobs/{id}']` emits a plain string `id` with description
+- **MCP tools** — auto-generated CRUD tools use `idField` transparently
+
+URL path segment stays `:id` (not `:jobId`) — clients send the ID value, Arc maps it server-side. User-provided `openApiSchemas.params` still overrides everything.
+
+For custom adapters, honor the new `AdapterSchemaContext` passed to `generateSchemas(options, context?)` to emit the right `params.id` pattern from the start. Legacy adapters still work — Arc's safety net strips mismatched ObjectId patterns automatically.
+
 ## QueryCache
 
 TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
@@ -635,6 +888,10 @@ import { defineResource, BaseController, allowPublic } from '@classytic/arc';
 import { createApp } from '@classytic/arc/factory';
 import { MemoryCacheStore, RedisCacheStore, QueryCache } from '@classytic/arc/cache';
 import { createBetterAuthAdapter, extractBetterAuthOpenApi } from '@classytic/arc/auth';
+// 2.7.1+: optional Mongoose stub-models bridge for `populate()` against
+// Better Auth collections — only loaded if you import it (subpath gate
+// keeps Mongoose out of Prisma/Drizzle/Kysely bundles).
+import { registerBetterAuthMongooseModels } from '@classytic/arc/auth/mongoose';
 import type { ExternalOpenApiPaths } from '@classytic/arc/docs';
 import { eventPlugin } from '@classytic/arc/events';
 import { RedisEventTransport } from '@classytic/arc/events/redis';
@@ -651,7 +908,21 @@ import { createTestApp } from '@classytic/arc/testing';
 import { Type, ArcListResponse } from '@classytic/arc/schemas';
 import { createStateMachine, CircuitBreaker, withCompensation, defineCompensation } from '@classytic/arc/utils';
 import { defineMigration } from '@classytic/arc/migrations';
-import { isMember, isElevated, getOrgId, getUserId, getUserRoles } from '@classytic/arc/scope';
+// Scope accessors — full surface as of 2.7.1
+import {
+  // Type guards
+  isMember, isService, isElevated, isAuthenticated, hasOrgAccess,
+  // Identity / org accessors
+  getUserId, getUserRoles, getOrgId, getOrgRoles, getTeamId, getClientId,
+  // Service scopes (OAuth-style strings on API keys)
+  getServiceScopes,
+  // App-defined scope dimensions (branch, project, region, …)
+  getScopeContext, getScopeContextMap,
+  // Parent-child org hierarchy
+  getAncestorOrgIds, isOrgInScope,
+  // Generic request-side helper
+  getRequestScope,
+} from '@classytic/arc/scope';
 import { createTenantKeyGenerator } from '@classytic/arc/scope';
 import { createRoleHierarchy } from '@classytic/arc/permissions';
 import { createServiceClient } from '@classytic/arc/rpc';
@@ -659,7 +930,7 @@ import { metricsPlugin, versioningPlugin } from '@classytic/arc/plugins';
 import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
 import { mcpPlugin, createMcpServer, defineTool, definePrompt, fieldRulesToZod, resourceToTools } from '@classytic/arc/mcp';
 import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
-import { bulkPreset } from '@classytic/arc/presets';
+import { bulkPreset, multiTenantPreset, type TenantFieldSpec } from '@classytic/arc/presets';
 ```
 
 ## References (Progressive Disclosure)
@@ -668,5 +939,6 @@ import { bulkPreset } from '@classytic/arc/presets';
 - **[events](references/events.md)** — Domain events, transports, retry, outbox pattern, auto-emission
 - **[integrations](references/integrations.md)** — BullMQ jobs, WebSocket, EventGateway, Streamline, Webhooks
 - **[mcp](references/mcp.md)** — MCP tools for AI agents, auto-generation from resources, custom tools, Better Auth OAuth 2.1
+- **[multi-tenancy](references/multi-tenancy.md)** — Scope ladder, `tenantField` read sites, `PermissionResult.scope`, API key auth without a separate auth plugin
 - **[production](references/production.md)** — Health, audit, idempotency, tracing, metrics, versioning, SSE, QueryCache, bulk ops, saga, RPC schema versioning, tenant rate limiting
 - **[testing](references/testing.md)** — Test app, mocks, data factories, in-memory MongoDB

package/skills/arc/references/multi-tenancy.md

@@ -0,0 +1,208 @@
+---
+name: Multi-Tenancy Playbook
+description: Where `tenantField` takes effect, how it composes with `_policyFilters`, and how to install scope from custom auth (API keys, service accounts, gateway headers)
+---
+
+# Multi-Tenancy Playbook
+
+Arc's multi-tenancy has exactly **one source of truth**: `request.scope`. This document shows where it's read, how filters compose, and how to wire custom authentication strategies (API keys, service accounts) without fighting the framework.
+
+## Mental model
+
+Every request goes through this ladder — if any step is missed, tenant isolation silently breaks:
+
+```
+1. Authenticator populates request.scope   (member | service | elevated | ...)
+                  ↓
+2. Permission check validates access        (allowPublic | requireAuth | requireApiKey | ...)
+                  ↓                          may ALSO set request.scope via PermissionResult.scope
+3. fastifyAdapter snapshots scope into metadata._scope
+                  ↓
+4. QueryResolver / AccessControl read metadata._scope
+                  ↓
+5. If tenantField is set AND getOrgId(scope) returns an orgId,
+   the org filter is ALWAYS prepended to the query
+```
+
+## The 5 scope kinds
+
+| Kind            | Use case                            | Has `userId` | Has `organizationId` | Helper                   |
+|-----------------|-------------------------------------|:------------:|:--------------------:|--------------------------|
+| `public`        | No authentication                   | ❌           | ❌                    | `PUBLIC_SCOPE`           |
+| `authenticated` | Logged-in user, no org context      | ✅           | ❌                    | `getUserId()`            |
+| `member`        | User in an org with specific roles  | ✅           | ✅                    | `isMember()` + `getOrgId()` |
+| `service`       | Machine-to-machine (API keys, bots) | ❌ (`clientId` instead) | ✅          | `isService()` + `getClientId()` |
+| `elevated`      | Platform admin, explicit elevation  | ✅           | Optional             | `isElevated()`           |
+
+**Why `service` is distinct from `member`:** a service account is not a human. It has no user record, no global roles, and should be auditable as a machine actor. Faking it as a `member` with `userId: client._id` pollutes audit logs, confuses rate-limit keys, and makes future per-service-scope authorization (OAuth scopes) harder.
+
+## Where `tenantField` is read
+
+Every resource defines `tenantField` (default: `'organizationId'`, or `false` to disable). It is read in **exactly three places** and ALL of them derive the org ID from `metadata._scope` via `getOrgId()`:
+
+| File                           | Method                  | Purpose                                        |
+|--------------------------------|-------------------------|------------------------------------------------|
+| `src/core/QueryResolver.ts`    | `resolve()`             | `list` — prepends `{ [tenantField]: orgId }` to the filter |
+| `src/core/AccessControl.ts`    | `buildIdFilter()`       | `get`, `update`, `delete` by ID — compound filter so cross-tenant IDs 404 |
+| `src/core/BaseController.ts`   | `buildBulkFilter()`     | `bulkUpdate`, `bulkDelete` — narrows bulk ops to the caller's org |
+
+**Everything else** (`BodySanitizer`, `MongoKit QueryParser`, presets) already composes cleanly with these three read points. If `getOrgId(scope)` returns the right value, you have tenant isolation — end of story.
+
+## Filter composition
+
+`_policyFilters` and `tenantField` are different and both apply:
+
+```ts
+// The final filter passed to the database is:
+{
+  ...parsedUserFilters,      // from the incoming query string
+  ..._policyFilters,         // from permission checks (ownership, project scoping, etc.)
+  [tenantField]: orgId,      // from metadata._scope (if tenantField is set and scope has orgId)
+}
+```
+
+**Priority rules:**
+- `_policyFilters` overrides user-supplied filters (the user can't bypass them)
+- `tenantField` only gets injected if `_policyFilters` does not already set it (so a more specific policy filter wins)
+- `elevated` scope with no `organizationId` means the filter is skipped entirely (admin sees everything)
+
+## Four ways to install scope
+
+### 1. Better Auth (recommended for human users)
+
+The `betterAuth` adapter reads the session cookie and installs `kind: 'member'` automatically. Nothing to wire.
+
+```ts
+await createApp({
+  auth: getAuth(),  // Better Auth instance
+  // ... scope is set by the adapter, zero code
+});
+```
+
+### 2. Custom Fastify authenticator (JWT, headers, whatever)
+
+Arc's `authPlugin.ts` auto-derives scope from `request.user` after your authenticator returns. If your user has `organizationId`, you get a `member` scope for free:
+
+```ts
+await createApp({
+  auth: {
+    type: 'authenticator',
+    authenticate: async (request) => {
+      const user = await verifyJwt(request.headers.authorization);
+      return user; // Must have `organizationId` for member scope
+    },
+  },
+});
+```
+
+### 3. `PermissionResult.scope` (NEW — best for API keys, service accounts, custom headers)
+
+Return the scope directly from your permission check. This is the cleanest integration point for machine-to-machine auth — no separate auth plugin, no scope-derivation-from-user magic. It's explicit, typed, and auditable.
+
+```ts
+// src/permissions/apiKey.ts
+import type { PermissionCheck } from '@classytic/arc/permissions';
+import { ClientModel } from '../models/Client.js';
+
+export function requireApiKey(): PermissionCheck {
+  return async ({ request }) => {
+    const apiKey = request.headers['x-api-key'] as string | undefined;
+    if (!apiKey) return { granted: false, reason: 'Missing API key' };
+
+    const client = await ClientModel.findOne({ apiKey });
+    if (!client) return { granted: false, reason: 'Invalid API key' };
+
+    return {
+      granted: true,
+      scope: {
+        kind: 'service',
+        clientId: String(client._id),
+        organizationId: String(client.companyId),
+        scopes: client.allowedScopes,  // optional OAuth-style scope strings
+      },
+      // Optional additional row-level narrowing
+      filters: client.projectId ? { projectId: client.projectId } : undefined,
+    };
+  };
+}
+```
+
+Then wire it into the resource:
+
+```ts
+defineResource({
+  name: 'job',
+  adapter: createMongooseAdapter({ model: Job, repository: jobRepo }),
+  controller: new BaseController(jobRepo, { tenantField: 'companyId' }),
+  permissions: {
+    list: requireApiKey(),
+    get: requireApiKey(),
+    create: requireApiKey(),
+    update: requireApiKey(),
+    delete: requireApiKey(),
+  },
+});
+```
+
+**That's the whole setup.** No auth plugin, no scope-resolution hook, no separate tenant-filter middleware. One file, one function, full tenant isolation — verified against cross-tenant `get`, `list`, `update`, and `delete` in [tests/e2e/permission-scope-wire.test.ts](../../../tests/e2e/permission-scope-wire.test.ts).
+
+**Override safety:** `PermissionResult.scope` only writes to `request.scope` when the current scope is still `public`. An already-authenticated request (from Better Auth, JWT, etc.) is never downgraded or overwritten.
+
+### 4. Custom Fastify hook (advanced)
+
+For exotic cases (mTLS, downstream RPC calls), write an `onRequest` hook that sets `request.scope` directly. Arc reads from `request.scope` — it doesn't care how you got there.
+
+## Decision table
+
+| Your auth source                  | Where to set scope                                  |
+|-----------------------------------|------------------------------------------------------|
+| Better Auth session cookie        | Nothing — `betterAuth` adapter handles it            |
+| JWT with `organizationId` claim   | Return it from `authenticate()` — auth plugin derives scope |
+| API key → DB lookup               | **`PermissionResult.scope`** ← the clean path        |
+| Gateway-injected headers          | `PermissionResult.scope` or a custom `onRequest` hook |
+| Service account OAuth token       | `PermissionResult.scope` with `kind: 'service'`      |
+| Platform admin elevation          | `elevationPlugin` — sets `kind: 'elevated'`          |
+
+## What happens when scope is missing
+
+If `tenantField` is set but `getOrgId(scope)` returns `undefined`:
+
+- **`list` / `get` / `update` / `delete`** — the filter is NOT narrowed. A caller with `public` scope would see ALL rows across ALL tenants. **This is why you must always pair `tenantField` with a permission check that installs a scope with `organizationId`.**
+- **`bulkUpdate` / `bulkDelete`** — `buildBulkFilter()` returns `null` and the bulk operation is rejected. This is a safety net, but don't rely on it for `list`.
+
+Arc does NOT auto-derive scope from `request.user.organizationId` — that's a footgun (silent tenant leak if you set the user but forget the scope). If you want this behavior, either use the JWT/custom authenticator path (which does derive automatically) or return `scope` explicitly from your permission check.
+
+## Gotchas
+
+1. **`tenantField` is per-resource, not per-app.** Different resources can use different tenant field names (`companyId`, `workspaceId`, `tenantId`). The org ID always comes from `getOrgId(scope)`.
+2. **`elevated` with no `organizationId` bypasses tenant filtering.** This is intentional (admin sees everything), but it means you can't use `kind: 'elevated'` for normal per-org access.
+3. **`systemManaged` is your seatbelt for create/update.** Mark tenant fields (`companyId`, `organizationId`) as `systemManaged` in `fieldRules` so `BodySanitizer` strips any client-supplied value. The tenant field is then injected from the scope at write time — not from the request body.
+4. **Rate-limit keys respect all 5 scope kinds.** The built-in `createTenantKeyGenerator` uses `organizationId` for member/service/elevated and falls back to `userId`/IP for authenticated/public.
+
+## Helpers reference
+
+All exported from `@classytic/arc/scope`:
+
+```ts
+import {
+  // Type guards
+  isMember, isService, isElevated, isAuthenticated, hasOrgAccess,
+
+  // Accessors (return undefined when not applicable — no throws)
+  getUserId,       // authenticated | member | elevated
+  getClientId,     // service only
+  getOrgId,        // member | service | elevated
+  getUserRoles,    // authenticated | member
+  getOrgRoles,     // member only
+  getServiceScopes, // service only (OAuth-style scope strings)
+  getTeamId,       // member with teamId set
+
+  // Canonical request extractor
+  getOrgContext,
+
+  // Constants
+  PUBLIC_SCOPE, AUTHENTICATED_SCOPE,
+
+  type RequestScope,
+} from '@classytic/arc/scope';
+```