@classytic/arc 2.6.3 → 2.7.1

package/dist/types-DPsC0taJ.d.mts

@@ -0,0 +1,178 @@
+import { r as RequestScope } from "./types-CNEbix8T.mjs";
+import { FastifyRequest } from "fastify";
+
+//#region src/permissions/types.d.ts
+/**
+ * User base interface - minimal shape Arc expects
+ * Your actual User can have any additional fields
+ */
+interface UserBase {
+  id?: string;
+  _id?: string;
+  /** User roles — string (comma-separated), string[], or undefined. Matches Better Auth's admin plugin pattern. */
+  role?: string | string[];
+  [key: string]: unknown;
+}
+/**
+ * Extract normalized roles from a user object.
+ *
+ * Reads `user.role` which can be:
+ * - A comma-separated string: `"superadmin,user"` (Better Auth admin plugin)
+ * - A string array: `["admin", "user"]` (JWT / custom auth)
+ * - A single string: `"admin"`
+ */
+/**
+ * Normalize a raw role value (string, comma-separated string, or array) into a string[].
+ * Shared low-level helper used by both getUserRoles() and the Better Auth adapter.
+ */
+declare function normalizeRoles(value: unknown): string[];
+declare function getUserRoles(user: UserBase | null | undefined): string[];
+/**
+ * Context passed to permission check functions
+ */
+interface PermissionContext<TDoc = Record<string, unknown>> {
+  /** Authenticated user or null if unauthenticated */
+  user: UserBase | null;
+  /** Fastify request object */
+  request: FastifyRequest;
+  /** Resource name being accessed */
+  resource: string;
+  /** Action being performed (list, get, create, update, delete, or custom operation name) */
+  action: string;
+  /** Resource ID for single-resource operations (shortcut for params.id) */
+  resourceId?: string;
+  /** All route parameters (slug, parentId, custom params, etc.) */
+  params?: Record<string, string>;
+  /** Request body data */
+  data?: Partial<TDoc> | Record<string, unknown>;
+}
+/**
+ * Result from a permission check.
+ *
+ * Permission checks can do three things:
+ * 1. **Grant or deny** access (`granted`, `reason`)
+ * 2. **Attach row-level filters** (`filters`) — these merge into `_policyFilters`
+ *    and narrow subsequent queries (e.g. `{ userId: ctx.user.id }` for ownership)
+ * 3. **Install the request scope** (`scope`) — when a custom authenticator wants
+ *    to set tenant/identity context directly from the permission layer, without
+ *    relying on a separate auth plugin
+ *
+ * The `scope` field is the clean integration point for custom auth strategies
+ * (API keys, service accounts, gateway headers). When present, Arc writes it to
+ * `request.scope` which then flows through the normal tenant-filtering pipeline
+ * (QueryResolver + AccessControl). This is the idiomatic way to wire non-Better-Auth
+ * identity providers into Arc's multi-tenancy without touching the auth plugin layer.
+ *
+ * @example
+ * ```typescript
+ * // Custom API-key auth — grant access AND install a service scope in one step
+ * 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,
+ *       // Install service scope — Arc writes this to request.scope automatically,
+ *       // and tenantField filtering picks it up via metadata._scope
+ *       scope: {
+ *         kind: 'service',
+ *         clientId: String(client._id),
+ *         organizationId: String(client.companyId),
+ *         scopes: client.allowedScopes,
+ *       },
+ *       // Optional row-level narrowing (e.g. per-project API keys)
+ *       filters: client.projectId ? { projectId: client.projectId } : undefined,
+ *     };
+ *   };
+ * }
+ * ```
+ */
+interface PermissionResult {
+  /** Whether access is granted */
+  granted: boolean;
+  /** Reason for denial (for error messages) */
+  reason?: string;
+  /** Query filters to apply (for ownership / row-level security patterns) */
+  filters?: Record<string, unknown>;
+  /**
+   * Install this scope on `request.scope` when granted. Flows through to
+   * `metadata._scope` and is read by QueryResolver / AccessControl for
+   * tenant-field filtering. Use this to wire custom auth (API keys, service
+   * accounts, gateway headers) into Arc's multi-tenancy without a separate
+   * auth plugin.
+   */
+  scope?: RequestScope;
+}
+/**
+ * Permission Check Function
+ *
+ * THE ONLY way to define permissions in Arc.
+ * Returns boolean, PermissionResult, or Promise of either.
+ *
+ * @example
+ * ```typescript
+ * // Simple boolean return
+ * const isAdmin: PermissionCheck = (ctx) => getUserRoles(ctx.user).includes('admin');
+ *
+ * // With filters for ownership
+ * const ownedByUser: PermissionCheck = (ctx) => ({
+ *   granted: true,
+ *   filters: { userId: ctx.user?.id }
+ * });
+ *
+ * // Async check
+ * const canAccessOrg: PermissionCheck = async (ctx) => {
+ *   const isMember = await checkMembership(ctx.user?.id, ctx.organizationId);
+ *   return { granted: isMember, reason: isMember ? undefined : 'Not a member' };
+ * };
+ * ```
+ */
+type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
+/**
+ * Optional metadata attached to permission check functions.
+ * Used for OpenAPI docs, introspection, and route-level auth decisions.
+ *
+ * Each helper from `permissions/index.ts` writes its own discriminating tag
+ * so downstream tooling (OpenAPI generator, MCP resource builder, route
+ * audit utilities) can read off the requirement without re-parsing the
+ * function body. All fields are optional — only the helpers that emit them
+ * set them.
+ */
+interface PermissionCheckMeta {
+  /** Set by allowPublic() — marks the endpoint as publicly accessible */
+  _isPublic?: boolean;
+  /** Set by requireRoles() — the roles required for access */
+  _roles?: readonly string[];
+  /** Set by requireOrgMembership() — org-level permission type */
+  _orgPermission?: string;
+  /** Set by requireOrgRole() — the org roles required for access */
+  _orgRoles?: readonly string[];
+  /** Set by requireTeamMembership() — team-level permission type */
+  _teamPermission?: string;
+  /**
+   * Set by requireServiceScope() — the OAuth-style scope strings the
+   * caller's `service` identity must hold (any-match logic, parallels
+   * `_orgRoles`).
+   */
+  _serviceScopes?: readonly string[];
+  /**
+   * Set by requireScopeContext() — the app-defined scope dimensions the
+   * caller must satisfy. Map keys are dimension names (`branchId`,
+   * `projectId`, etc.); values are the required string OR `undefined`
+   * for "must be present, any value".
+   */
+  _scopeContext?: Record<string, string | undefined>;
+  /**
+   * Set by requireOrgInScope() — the target organization that must appear
+   * in the caller's org chain (current org or `ancestorOrgIds`). Either
+   * a static org id or a function extracting it from the request context
+   * (e.g. from route params).
+   */
+  _orgInScopeTarget?: string | ((ctx: PermissionContext) => string | undefined);
+}
+//#endregion
+export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };

package/dist/utils/index.d.mts

@@ -1,6 +1,6 @@
-import { G as OpenApiSchemas, Q as QueryParserInterface, q as ParsedQuery, u as AnyRecord } from "../interface-DYH8AXGe.mjs";
-import { a as NotFoundError, c as RateLimitError, d as ValidationError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CcVbl1-T.mjs";
-import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-JP2GdJ4b.mjs";
+import { G as OpenApiSchemas, Q as QueryParserInterface, q as ParsedQuery, u as AnyRecord } from "../interface-Dwzqt4mn.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CCSsMpXE.mjs";
+import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-DwxrljLB.mjs";
 import { FastifyInstance } from "fastify";
 
 //#region src/utils/compensation.d.ts

package/dist/utils/index.mjs

@@ -1,7 +1,7 @@
 import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
-import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-BOBOpN2w.mjs";
-import { _ as defineCompensation, a as getListQueryParams, c as listResponse, d as paginateWrapper, f as paginationSchema, g as wrapResponse, h as successResponseSchema, i as getDefaultCrudSchemas, l as messageWrapper, m as responses, n as deleteResponse, o as itemResponse, p as queryParams, r as errorResponseSchema, s as itemWrapper, t as createStateMachine, u as mutationResponse, v as withCompensation } from "../utils-Dc0WhlIl.mjs";
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-NoQKsbAT.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DjzHpFam.mjs";
-import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
+import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-l18oRgL5.mjs";
+import { _ as defineCompensation, a as getListQueryParams, c as listResponse, d as paginateWrapper, f as paginationSchema, g as wrapResponse, h as successResponseSchema, i as getDefaultCrudSchemas, l as messageWrapper, m as responses, n as deleteResponse, o as itemResponse, p as queryParams, r as errorResponseSchema, s as itemWrapper, t as createStateMachine, u as mutationResponse, v as withCompensation } from "../utils-B-l6410F.mjs";
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-Cg58SLNi.mjs";
+import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-0TyONAwM.mjs";
+import { t as hasEvents } from "../typeGuards-CcFZXgU7.mjs";
 export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createError, createQueryParser, createStateMachine, defineCompensation, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, itemWrapper, listResponse, messageWrapper, mutationResponse, paginateWrapper, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.6.3",
+  "version": "2.7.1",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -168,6 +168,10 @@
       "types": "./dist/auth/redis-session.d.mts",
       "default": "./dist/auth/redis-session.mjs"
     },
+    "./auth/mongoose": {
+      "types": "./dist/auth/mongoose.d.mts",
+      "default": "./dist/auth/mongoose.mjs"
+    },
     "./plugins/response-cache": {
       "types": "./dist/plugins/response-cache.d.mts",
       "default": "./dist/plugins/response-cache.mjs"
@@ -220,7 +224,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.5.0",
+    "@classytic/mongokit": ">=3.5.5",
     "@classytic/streamline": ">=2.0.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -238,13 +242,13 @@
     "@opentelemetry/instrumentation-mongodb": ">=0.40.0",
     "@opentelemetry/sdk-node": ">=0.50.0",
     "@sinclair/typebox": ">=0.34.0",
-    "better-auth": ">=1.5.5",
+    "better-auth": ">=1.6.0",
     "bullmq": ">=5.0.0",
     "fastify": ">=5.0.0",
     "fastify-raw-body": ">=5.0.0",
     "ioredis": ">=5.0.0",
     "mongodb": ">=6.0.0",
-    "mongoose": ">=9.0.0",
+    "mongoose": ">=9.4.1",
     "pino-pretty": ">=13.0.0",
     "zod": ">=4.0.0"
   },
@@ -337,22 +341,30 @@
     "secure-json-parse": "^4.1.0"
   },
   "devDependencies": {
+    "@better-auth/mongo-adapter": "^1.6.0",
     "@biomejs/biome": "^2.4.10",
-    "@classytic/mongokit": "^3.5.2",
+    "@classytic/mongokit": "^3.5.5",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",
     "@fastify/multipart": "^9.0.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/sensible": "^6.0.4",
     "@fastify/type-provider-typebox": "^6.0.0",
+    "@fastify/under-pressure": "^9.0.3",
     "@fastify/websocket": "^11.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sinclair/typebox": "^0.34.0",
     "@types/node": "^22.10.0",
     "@types/qs": "^6.14.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "better-auth": "^1.6.0",
     "fastify-raw-body": "^5.0.0",
     "jsonwebtoken": "^9.0.0",
     "knip": "^6.3.0",
     "mongodb": "^7.1.0",
     "mongodb-memory-server": "^11.0.1",
+    "mongoose": "^9.4.1",
     "tsdown": "^0.21.7",
     "typescript": "^6.0.2",
     "vitest": "^3.0.0",

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.
@@ -660,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';
@@ -676,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';
@@ -684,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)
@@ -693,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