@classytic/arc 2.6.3 → 2.7.3

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.3
 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.
@@ -520,14 +748,26 @@ Connect Claude CLI: `claude mcp add --transport http my-api http://localhost:300
 **Auth** — three modes, user chooses: `false` | `getAuth()` (Better Auth OAuth 2.1) | custom function:
 
 ```typescript
+// Human user auth
 auth: async (headers) => {
   if (headers['x-api-key'] !== process.env.MCP_KEY) return null;
   return { userId: 'bot', organizationId: 'org-1', roles: ['admin'] };
 },
+
+// Service account / machine-to-machine (produces kind: "service" scope)
+auth: async (headers) => ({
+  clientId: 'ingestion-pipeline',
+  organizationId: 'org-1',
+  scopes: ['read:products', 'write:events'],
+}),
 ```
 
+`auth: false` → `ctx.user` is `null`, `scope.kind` is `"public"`. Permission guards like `!!ctx.user` correctly block anonymous callers.
+
 **Guards** for custom tools: `guard(requireAuth, requireOrg, requireRole('admin'), handler)`
 
+**Service scope**: When `clientId` is set in auth result, MCP produces `kind: "service"` RequestScope — works with `requireServiceScope()`, `getClientId()`, `getServiceScopes()`. No synthetic userId needed for machine principals.
+
 **Multi-tenancy**: `organizationId` from auth flows into BaseController org-scoping automatically.
 
 **Permission filters**: `PermissionResult.filters` from resource permissions flow into MCP tools — same as REST. Define once, works everywhere:
@@ -653,6 +893,55 @@ additionalRoutes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${
 additionalRoutes: [{ streamResponse: true, handler: async (req, reply) => reply.send(stream) }]
 ```
 
+## DX Helpers (v2.7.3)
+
+**Reply helpers** — consistent response envelopes (opt-in via `createApp({ replyHelpers: true })`):
+
+```typescript
+return reply.ok({ name: 'MacBook' });              // → 200 { success: true, data: {...} }
+return reply.ok(product, 201);                      // → 201 { success: true, data: {...} }
+return reply.fail('Not found', 404);                // → 404 { success: false, error: '...' }
+return reply.fail(['err1', 'err2'], 422);           // → 422 { success: false, errors: [...] }
+return reply.paginated({ docs, total, page, limit });
+return reply.stream(csvReadable, { contentType: 'text/csv', filename: 'export.csv' });
+```
+
+**Error mappers** — class-based domain error → HTTP response (in `errorHandler` options):
+
+```typescript
+const app = await createApp({
+  errorHandler: {
+    errorMappers: [{
+      type: AccountingError,
+      toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
+    }],
+  },
+});
+// Handlers just throw — Arc catches and maps automatically
+```
+
+**BigInt serialization** — opt-in via `createApp({ serializeBigInt: true })`. Converts BigInt → Number in all JSON responses.
+
+**Multipart body middleware** — opt-in file upload for CRUD routes:
+
+```typescript
+import { multipartBody } from '@classytic/arc/middleware';
+
+defineResource({
+  name: 'product',
+  adapter,
+  middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png', 'image/jpeg'], maxFileSize: 5 * 1024 * 1024 })] },
+  hooks: {
+    'before:create': async (data) => {
+      if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
+      return data;
+    },
+  },
+});
+```
+
+`multipartBody()` is a no-op for JSON requests — safe to always add.
+
 ## Subpath Imports
 
 ```typescript
@@ -660,6 +949,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';
@@ -676,7 +969,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';
@@ -684,7 +991,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)
@@ -693,5 +1000,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/integrations.md

@@ -297,7 +297,7 @@ All optional, gracefully degrade:
 import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
 ```
 
-Fastify plugin that auto-dispatches Arc events to customer webhook endpoints with HMAC-SHA256 signing, delivery logging, and pluggable persistence.
+Fastify plugin that auto-dispatches Arc events to customer webhook endpoints with HMAC-SHA256 signing, delivery logging, bounded concurrency, and pluggable persistence.
 
 ### Setup
 
@@ -309,6 +309,7 @@ await fastify.register(webhookPlugin, {
   store: myMongoWebhookStore,  // implements WebhookStore { getAll, save, remove }
   timeout: 5000,               // delivery timeout (default: 10000ms)
   maxLogEntries: 500,          // ring buffer cap (default: 1000)
+  concurrency: 10,             // max parallel deliveries per event (default: 5)
 });
 ```
 
@@ -338,21 +339,45 @@ await app.events.publish('order.created', { orderId: '123' });
 //   Body: { type, payload, meta }
 ```
 
-### HMAC Signing
+Deliveries run with bounded concurrency (default: 5) — one slow endpoint won't block the rest. Set `concurrency: 1` for sequential delivery.
 
-Every delivery is signed with the subscription's secret using HMAC-SHA256:
+### HMAC Signing & Verification
+
+**Outbound** — every delivery is signed with the subscription's secret:
 
 ```
 x-webhook-signature: sha256=a1b2c3...
 ```
 
-Verify on the receiving end:
+**Inbound** — verify with `verifySignature()` (timing-safe, never throws):
+
+```typescript
+import { verifySignature } from '@classytic/arc/integrations/webhooks';
+
+fastify.post('/webhooks/incoming', async (req, reply) => {
+  const sig = req.headers['x-webhook-signature'] as string;
+  if (!verifySignature(req.rawBody, secret, sig)) {
+    return reply.status(401).send({ error: 'Invalid signature' });
+  }
+  // handle event via req.headers['x-webhook-event']
+});
+```
+
+Accepts `string | Buffer` body, `string | undefined` signature. Configurable for non-Arc senders:
+
 ```typescript
-import { createHmac } from 'node:crypto';
-const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
-if (expected !== req.headers['x-webhook-signature']) throw new Error('Invalid signature');
+// GitHub (same prefix, same algorithm — works with defaults)
+verifySignature(body, secret, req.headers['x-hub-signature-256']);
+
+// Custom algorithm / bare hex
+verifySignature(body, secret, req.headers['x-custom-sig'], {
+  prefix: '',           // bare hex, no prefix
+  algorithm: 'sha512',  // non-default algorithm
+});
 ```
 
+**Note:** `req.rawBody` requires `fastify-raw-body` — JSON re-serialization breaks HMAC since field ordering differs.
+
 ### Delivery Log
 
 ```typescript

package/skills/arc/references/mcp.md

@@ -139,7 +139,7 @@ Arc doesn't enforce an auth strategy. You choose what fits.
 await app.register(mcpPlugin, { resources, auth: false });
 ```
 
-All tools open. Every request gets `{ userId: 'anonymous' }`.
+All tools open. `ctx.user` is `null`, `scope.kind` is `"public"`. Permission guards like `!!ctx.user` correctly block — anonymous callers cannot bypass auth checks.
 
 ### 2. Better Auth OAuth 2.1 (production SaaS)
 
@@ -175,13 +175,27 @@ type McpAuthResolver = (headers: Record<string, string | undefined>) =>
   Promise<McpAuthResult | null> | McpAuthResult | null;
 ```
 
-Return `{ userId, organizationId? }` to allow. Return `null` to reject (401).
+Return `McpAuthResult` to allow. Return `null` to reject (401).
+
+**`McpAuthResult` fields:**
+- `userId?` — human user ID (optional for machine principals)
+- `organizationId?` — org scope
+- `roles?` / `orgRoles?` — user roles
+- `clientId?` — set this to produce `kind: "service"` scope (machine-to-machine)
+- `scopes?` — OAuth scopes for service accounts
 
 ```typescript
-// API key
+// Human user — API key
 auth: async (headers) => {
   if (headers['x-api-key'] !== process.env.MCP_API_KEY) return null;
-  return { userId: 'service', organizationId: 'org-123' };
+  return { userId: 'alice', organizationId: 'org-123', roles: ['admin'] };
+},
+
+// Machine principal — service account (no userId needed)
+auth: async (headers) => {
+  const key = headers['x-service-key'];
+  if (key !== process.env.SVC_KEY) return null;
+  return { clientId: 'ingestion-pipeline', organizationId: 'org-123', scopes: ['write:events'] };
 },
 
 // Gateway-validated JWT (token already verified upstream)
@@ -191,9 +205,6 @@ auth: async (headers) => {
   return userId ? { userId, organizationId: orgId } : null;
 },
 
-// Static org (trusted internal network)
-auth: async () => ({ userId: 'internal', organizationId: 'org-main' }),
-
 // Bearer token with custom validation
 auth: async (headers) => {
   const token = headers['authorization']?.replace('Bearer ', '');
@@ -203,6 +214,19 @@ auth: async (headers) => {
 },
 ```
 
+### Service Scope (machine-to-machine)
+
+When `clientId` is present in the auth result, Arc produces `kind: "service"` RequestScope:
+
+```
+auth resolver returns { clientId: 'pipeline-v2', organizationId: 'org-a', scopes: ['read:all'] }
+  → buildRequestContext sets _scope: { kind: 'service', clientId: 'pipeline-v2', organizationId: 'org-a', scopes: ['read:all'] }
+  → ctx.user is null (machine principals don't masquerade as users)
+  → isService(scope), getClientId(scope), getServiceScopes(scope) all work
+```
+
+When `userId` is present (without `clientId`), Arc produces `kind: "member"` or `kind: "authenticated"` as before.
+
 ### Multi-Tenancy
 
 The `organizationId` from auth flows into BaseController's org-scoping automatically: