@classytic/arc 2.11.3 → 2.13.1

package/skills/arc/references/auth.md

@@ -1,5 +1,19 @@
 # Arc Authentication & Authorization
 
+## Decision tree — which pattern fits your auth provider
+
+Arc deliberately ships **zero per-provider code**. The contract is `request.scope`. Three shapes cover every realistic provider:
+
+| Where does user data live? | Who writes it? | Pattern |
+|---|---|---|
+| Your DB | You | **arc JWT / authenticator** — define your User model normally; no overlay |
+| The provider's cloud | Provider (Clerk, Auth0, Supabase Auth...) | **authenticate callback** — verify provider JWT, map claims to `request.scope`. Optionally webhook-sync to a local user table for joins |
+| Your DB | A library writes it via its own driver (Better Auth) | **kit overlay** — `@classytic/mongokit/better-auth`, sqlite hand-rolled — gives you arc CRUD + queryparser over the library's tables |
+
+**Better Auth is the recommended path** when you want both "users live in my DB" AND "I don't want to hand-roll signup / OAuth / 2FA / orgs". It's the only provider that needs the overlay because it's the only one writing your tables.
+
+For everything else, the canonical primitive is the `authenticate` callback — verify the token, populate `request.scope`. Arc doesn't care which library produced the token.
+
 ## Auth Strategies (Discriminated Union)
 
 Auth config uses `type` field to select strategy:
@@ -41,6 +55,10 @@ const decoded = app.auth.verifyRefreshToken(refreshToken);
 
 ### Better Auth (`type: 'betterAuth'`)
 
+Two pieces — the **request-side bridge** (catch-all `/api/auth/*` route + scope adapter) and the **table-side overlay** (so arc resources can read BA's collections with full pagination / queryparser / OpenAPI).
+
+#### Request-side bridge
+
 ```typescript
 import { createBetterAuthAdapter } from '@classytic/arc/auth';
 
@@ -56,30 +74,316 @@ const app = await createApp({
 ```
 
 **Org context flow** (when `orgContext: true`):
-1. Gets session via Better Auth
+1. Gets session via `auth.api.getSession()` (in-process, no HTTP round-trip)
 2. Reads `session.activeOrganizationId`, or falls back to `x-organization-id` header (needed for API key auth where synthetic sessions have no org context)
-3. Looks up org membership via `getActiveMemberRole` (with explicit `organizationId` param for header-based resolution)
+3. Looks up org membership via `auth.api.getActiveMember` (or `getActiveMemberRole` with explicit `organizationId` for header-based resolution)
 4. Splits roles: `"admin,recruiter"` → `['admin', 'recruiter']`
 5. Sets `request.scope`: `{ kind: 'member', organizationId, orgRoles: string[], teamId? }`
 
+> **Arc 2.13+ requires `auth.api.*`** — pass a real `betterAuth()` instance. The pre-2.13 HTTP fallback for org/team lookups was retired.
+
+#### Table-side overlay — read BA's tables as arc resources
+
+Better Auth writes its own tables (`user`, `organization`, `member`, `invitation`, ...) via its own driver. To expose them as arc resources with pagination, queryparser, OpenAPI, audit, permissions, and multi-tenant scope, use the kit-side overlay:
+
+##### Mongoose / mongokit (Tier 2 — convenience factory)
+
+```typescript
+import { betterAuth } from 'better-auth';
+import { mongodbAdapter } from '@better-auth/mongo-adapter';
+import { organization } from 'better-auth/plugins';
+import mongoose from 'mongoose';
+import {
+  createBetterAuthOverlay,
+  registerBetterAuthStubs,
+} from '@classytic/mongokit/better-auth';
+
+const auth = betterAuth({
+  database: mongodbAdapter(mongoose.connection.getClient().db()),
+  plugins: [organization()],
+  // ...
+});
+
+// Bulk-register stubs so `populate('user')` works app-wide.
+registerBetterAuthStubs(mongoose, { plugins: ['organization'] });
+
+// Per-resource overlay — ready to plug into defineResource.
+const orgAdapter = createBetterAuthOverlay({
+  mongoose,
+  collection: 'organization',
+});
+
+defineResource({
+  name: 'organization',
+  adapter: orgAdapter,
+  tenantField: false,                // platform-wide, not tenant-scoped
+  permissions: { list: requireAuth(), get: requireAuth() },
+});
+```
+
+##### Mongoose / mongokit (Tier 1 — hand-rolled, full control)
+
+When you need custom validators, `toJSON` transforms (e.g., strip `password`), domain methods on the Repository, or special indexes — drop the factory and hand-roll:
+
+```typescript
+const userSchema = new mongoose.Schema(
+  {
+    name: String,
+    email: String,
+    role: { type: [String], enum: SYSTEM_ROLES, default: ['user'] },
+    isActive: { type: Boolean, default: true },
+    // BA owns these via strict:false overlay; only declare what you need typed
+  },
+  { strict: false, timestamps: false, collection: 'user' },
+);
+userSchema.set('toJSON', { transform: (_, ret) => { delete ret.password; return ret; } });
+const User = mongoose.model('User', userSchema);
+
+class UserRepository extends Repository<IUser> {
+  async getByRole(role: string) { return this.getAll({ filters: { role, isActive: true } }); }
+}
+
+defineResource({
+  name: 'user',
+  adapter: createMongooseAdapter(User, new UserRepository(User)),
+  tenantField: false,
+  fields: { password: fields.hidden() },     // belt-and-braces
+  permissions: { list: requireRoles(['admin']) },
+});
+```
+
+##### sqlite / sqlitekit (Tier 2 — convenience factory)
+
+Same parallel structure as mongokit. The factory derives the Drizzle table dynamically from BA's resolved schema (`auth.$context.tables`) — `additionalFields`, `modelName` overrides, and plugin schema additions all flow through automatically.
+
+```typescript
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { betterAuth } from 'better-auth';
+import { organization } from 'better-auth/plugins';
+import { createBetterAuthOverlay } from '@classytic/sqlitekit/better-auth';
+
+const sqlite = new Database('app.db');
+const auth = betterAuth({ database: sqlite, plugins: [organization()] });
+const db = drizzle(sqlite);
+
+// Async because we await BA's resolved schema. Resolves once at boot.
+const orgAdapter = await createBetterAuthOverlay({ auth, db, collection: 'organization' });
+
+defineResource({ name: 'organization', adapter: orgAdapter, idField: 'id', tenantField: false });
+```
+
+Need a column BA doesn't declare (host-side audit, custom JSON column, etc.)? Pass `additionalColumns`:
+
+```typescript
+import { integer, text } from 'drizzle-orm/sqlite-core';
+
+const orgAdapter = await createBetterAuthOverlay({
+  auth, db, collection: 'organization',
+  additionalColumns: {
+    syncedAt: integer('syncedAt'),
+    branchType: text('branchType'),       // matches your BA additionalFields entry
+  },
+});
+```
+
+##### sqlite / sqlitekit (Tier 1 — hand-roll for full control)
+
+When you need a custom `SqliteRepository` subclass with domain methods, custom Drizzle column modes (`integer({ mode: 'timestamp_ms' })` for typed Date), or table-level extensions the factory can't express — drop the factory:
+
+```typescript
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { SqliteRepository } from '@classytic/sqlitekit/repository';
+import { createDrizzleAdapter } from '@classytic/sqlitekit/adapter';
+
+export const organizationTable = sqliteTable('organization', {
+  id: text('id').primaryKey().notNull(),
+  name: text('name').notNull(),
+  slug: text('slug'),
+  logo: text('logo'),
+  createdAt: integer('createdAt', { mode: 'timestamp_ms' }).notNull(),  // typed Date
+  metadata: text('metadata'),
+});
+
+class OrgRepository extends SqliteRepository<{ id: string; name: string }> {
+  async getActive() { return this.getAll({ filters: { /* ... */ } }); }
+}
+
+const db = drizzle(sqliteDatabase);
+const repo = new OrgRepository({ db, table: organizationTable, idField: 'id' });
+const orgAdapter = createDrizzleAdapter({ table: organizationTable, repository: repo });
+```
+
+Reference playgrounds: [`playground/better-auth/mongo/`](../../../playground/better-auth/mongo/) · [`playground/better-auth/sqlite/`](../../../playground/better-auth/sqlite/). Both pass identical 17-scenario smoke suites — same `defineResource` host code, only the kit import differs.
+
+> **Removed in arc 2.13** — `@classytic/arc/auth/mongoose` (the old `registerBetterAuthMongooseModels`). The helper moved to `@classytic/mongokit/better-auth` as `registerBetterAuthStubs`. Same behavior, kit-owned location.
+
+### Better Auth plugin integration matrix
+
+The `auth.api.*` direct in-process API map and `auth.$context.tables` schema introspection let arc and the kit overlays be **plugin-agnostic** — wire any combination of BA plugins, the overlay reads what's there. No per-plugin code in arc/mongokit/sqlitekit.
+
+| BA plugin | Adds tables | Tested in | What you need on the arc side |
+|---|---|---|---|
+| (core) — `emailAndPassword`, OAuth providers | `user`, `session`, `account`, `verification` | both kits + playground | Nothing extra. Optionally overlay `user` as a resource. |
+| `organization()` (built-in) | `organization`, `member`, `invitation` | both kits + playground | `createBetterAuthAdapter({ orgContext: true })`; overlay `organization` / `member` as resources. |
+| `organization({ teams: true })` | + `team`, `teamMember` | mongokit | `requireTeamMembership()` works on `scope.teamId`. |
+| `twoFactor()` (built-in) | `twoFactor` | both kits | Picked up automatically by overlay; expose `twoFactor` as a resource if needed. |
+| `admin()` (built-in) | (field-only, augments `user`) | both kits | `requireRoles(['admin'])` reads the platform role; no extra plumbing. |
+| `bearer()` (built-in) | (none — header strategy) | CLI scaffold | Token comes via `Authorization: Bearer <session>` instead of cookie — same `auth.api.getSession()` path. Use for SPA / mobile clients. |
+| `apiKey()` from **`@better-auth/api-key`** (separate npm package) | `apikey` | both kits | Arc auto-resolves API key sessions via `enableSessionForAPIKeys: true`; falls back to `x-organization-id` header for org context. See "API Key Auth" below. |
+| `magicLink()`, `username()`, `passkey()`, `oidcProvider()`, `mcp()`, `deviceAuthorization()` | varies (passkey: `passkey`; oidc: `oauthApplication`/`oauthAccessToken`; deviceAuth: `deviceCode`) | not in kit tests | Overlay reads them automatically — pass plugin name to `registerBetterAuthStubs` or list under `extraCollections`. |
+
+#### Multi-plugin recipe — combine without overlay code changes
+
+```typescript
+import { betterAuth } from 'better-auth';
+import { mongodbAdapter } from '@better-auth/mongo-adapter';
+import { admin, organization, twoFactor, bearer } from 'better-auth/plugins';
+import { apiKey } from '@better-auth/api-key';
+import { createBetterAuthOverlay, registerBetterAuthStubs } from '@classytic/mongokit/better-auth';
+
+const auth = betterAuth({
+  database: mongodbAdapter(mongoose.connection.getClient().db()),
+  emailAndPassword: { enabled: true },
+  plugins: [
+    organization(),       // adds organization, member, invitation
+    twoFactor(),          // adds twoFactor
+    admin(),              // augments user with role/banned/banReason
+    bearer(),             // header-based session for SPA/mobile
+    apiKey({ enableSessionForAPIKeys: true }),   // adds apikey
+  ],
+});
+
+// One stub-registration call covers the populate('user') / ref:'organization' surface
+// for every plugin you've enabled. apikey isn't ref'd by populate so it goes into extras.
+registerBetterAuthStubs(mongoose, {
+  plugins: ['organization'],
+  extraCollections: ['apikey'],
+});
+
+// Overlay any of the resulting tables — picks modelName + additionalFields up
+// automatically from auth.$context.tables. Tested combinations: organization,
+// member, invitation, apikey, twoFactor, user.
+const orgAdapter    = await createBetterAuthOverlay({ auth, mongoose, collection: 'organization' });
+const memberAdapter = await createBetterAuthOverlay({ auth, mongoose, collection: 'member' });
+const apiKeyAdapter = await createBetterAuthOverlay({ auth, mongoose, collection: 'apikey' });
+```
+
+Sqlitekit is symmetric — replace `{ mongoose }` with `{ db }` (a Drizzle binding), use `additionalColumns` instead of `additionalFields`, and skip the stub registration step (no `populate()` in Drizzle).
+
+#### Multi-role members — `role: "admin,recruiter,viewer"`
+
+BA's organization plugin stores multiple roles in a single comma-separated `member.role` string (be-prod canonical). The overlay round-trips this unchanged; arc's `requireRoles()` and `requireOrgRole()` split on comma when reading `scope.orgRoles`:
+
+```typescript
+// BA writes:                                    arc reads:
+// member.role = "admin,recruiter,viewer"   →   scope.orgRoles = ['admin', 'recruiter', 'viewer']
+
+defineResource({
+  name: 'invoice',
+  permissions: {
+    create: requireOrgRole('admin'),         // matches — admin is in the list
+    delete: requireOrgRole('owner'),         // does NOT match — string-equality on each role
+  },
+});
+```
+
+Filtering `member` by exact role string with `?role=admin` will NOT match a multi-role member — the column is opaque text, not an array. Filter with `role[like]=admin` (case-sensitive substring) or model membership server-side.
+
+#### `registerBetterAuthStubs(mongoose, opts?)` — full options (mongokit only)
+
+Bulk-registers `strict: false` Mongoose stubs so `populate('user')` / `ref: 'organization'` work app-wide without per-collection schemas. Idempotent — calling twice returns `[]` the second time.
+
+```typescript
+registerBetterAuthStubs(mongoose, {
+  plugins: ['organization', 'organization-teams', 'mcp', 'oidcProvider', 'deviceAuthorization'],
+  extraCollections: ['passkey', 'ssoProvider', 'apikey'],   // anything not in the plugin map
+  modelOverrides: { organization: 'OrgRoot' },              // BA modelName → Mongoose model name
+  usePlural: true,                                          // register 'organizations' alongside 'organization'
+});
+```
+
+Plugin keys recognized by the registry: `organization`, `organization-teams`, `twoFactor`, `jwt`, `oidcProvider`, `mcp`, `deviceAuthorization`. Field-only plugins (`admin`, `username`, `magicLink`, `bearer`, `apiKey` field augmentations) need no entry.
+
+**Gotcha — stub already registered + `additionalFields` requested:** `createBetterAuthOverlay` throws when the host called `registerBetterAuthStubs` for the same collection AND now passes `additionalFields` to the overlay. The stub model is already locked to `strict: false` with no extra paths; adding fields after the fact would silently no-op. Call order: register stubs OR overlay-with-additional-fields, not both for the same collection.
+
 ### API Key Auth (Better Auth `apiKey()` plugin)
 
-When the `apiKey()` plugin is enabled in Better Auth, Arc's adapter automatically:
-- Resolves API key sessions via `enableSessionForAPIKeys: true`
-- Falls back to `x-organization-id` header for org context (API key sessions have no `activeOrganizationId`)
-- Generates OpenAPI security schemes dynamically — `apiKeyAuth` only appears in the spec when the plugin is active
+`apiKey` ships as a **separate npm package**: `@better-auth/api-key`. It is NOT exported from `better-auth/plugins` like `organization` / `twoFactor` / `bearer`. Common mistake.
+
+```typescript
+import { apiKey } from '@better-auth/api-key';      // ✓ separate package
+// import { apiKey } from 'better-auth/plugins';    // ✗ does not exist
+
+const auth = betterAuth({
+  // ...
+  plugins: [apiKey({ enableSessionForAPIKeys: true })],
+});
+```
+
+When enabled, Arc's adapter automatically:
+- Resolves API key sessions via `enableSessionForAPIKeys: true` (the plugin's option, not arc's).
+- Falls back to `x-organization-id` header for org context — API key sessions have no `activeOrganizationId`, so without the header `scope.kind` is `'authenticated'`, not `'member'`.
+- Generates OpenAPI security schemes dynamically — `apiKeyAuth` only appears in the spec when the plugin is active.
 
 ```
 x-api-key: ak_live_...           # Authentication
 x-organization-id: org_abc123    # Org context (required for org-scoped resources)
 ```
 
-**OpenAPI security semantics:**
+**OpenAPI security semantics** (auto-derived; no manual schema):
 - Resource paths: `security: [{ bearerAuth: [] }, { apiKeyAuth: [], orgHeader: [] }]`
   - Meaning: bearer token alone **OR** (API key **AND** org header together)
 - Auth endpoints: `security: [{ cookieAuth: [] }, { bearerAuth: [] }, { apiKeyAuth: [] }]`
   - No org header required for auth management endpoints
 
+**Overlay the `apikey` table as an arc resource** (admin-only, for issuing/revoking keys via REST):
+
+```typescript
+const apiKeyAdapter = await createBetterAuthOverlay({ auth, mongoose, collection: 'apikey' });
+// or sqlitekit: { auth, db, collection: 'apikey' }
+
+defineResource({
+  name: 'apikey',
+  adapter: apiKeyAdapter,
+  tenantField: false,                                 // platform-managed, not tenant-scoped
+  permissions: {
+    list: requireRoles(['admin']),
+    get: requireRoles(['admin']),
+    create: denyAll('use POST /api/auth/api-key/create'),   // BA owns the issuance path
+    delete: requireRoles(['admin']),
+  },
+  fields: {
+    key: fields.hidden(),                             // never expose the raw key after creation
+  },
+});
+```
+
+The plugin also adds a required `configId` field on `apikey` rows and uses `referenceId` (not `userId`) — note when seeding test fixtures.
+
+### Bearer plugin — SPA / mobile clients
+
+For non-cookie clients (React Native, native mobile, headless SPA), enable `bearer()` so sessions travel as `Authorization: Bearer <session-token>` instead of cookies. Same `auth.api.getSession()` path, just a different transport.
+
+```typescript
+import { bearer } from 'better-auth/plugins';
+const auth = betterAuth({ plugins: [bearer(), organization()] });
+```
+
+Arc's adapter handles both transports identically — you don't switch arc config based on which is enabled. Enable both `cookie` (default) + `bearer` for hybrid web + mobile apps.
+
+### CLI scaffolding for Better Auth
+
+`arc init my-api --better-auth --mongokit --ts` prompts for session strategy and api-key:
+
+```
+Session strategy [1=Cookie (web app, default), 2=Bearer token (mobile/SPA), 3=Both]: 3
+Enable API key plugin (machine-to-machine auth via @better-auth/api-key)? [y/N]: y
+```
+
+The scaffold wires `registerBetterAuthStubs(mongoose, { plugins: [...], extraCollections: ['apikey'] })`, conditional plugin imports, and the matching peer dep entries (`@better-auth/api-key` only if you opted in).
+
 ### Custom Plugin (`type: 'custom'`)
 
 ```typescript
@@ -100,6 +404,49 @@ auth: {
 }
 ```
 
+### Clerk / Auth0 / Supabase Auth / any cloud SaaS
+
+User data lives in the provider's cloud, not your DB. No tables to overlay — just verify the provider's JWT and map claims to `request.scope`. The same shape works for any cloud auth provider; only the verifier function differs.
+
+```typescript
+import { verifyToken } from '@clerk/backend';
+
+await createApp({
+  auth: {
+    type: 'jwt',                              // arc's plugin handles plumbing
+    jwt: { secret: 'unused' },                // overridden by authenticate
+    authenticate: async (request) => {
+      const token = request.headers.authorization?.slice(7);
+      if (!token) return null;
+      const claims = await verifyToken(token, { secretKey: process.env.CLERK_SECRET_KEY! });
+
+      // Map provider claims → arc scope (same shape BA produces)
+      if (claims.org_id) {
+        request.scope = {
+          kind: 'member',
+          userId: claims.sub,
+          organizationId: claims.org_id,
+          orgRoles: [claims.org_role],
+          userRoles: claims.org_role ? [claims.org_role] : [],
+        };
+      }
+      return { id: claims.sub, email: claims.email };
+    },
+  },
+});
+```
+
+**Optional: local user table for joins.** If your resources reference users (`Order.userId → populate`), webhook-sync from Clerk into a local `users` collection and treat it as a normal arc resource — no overlay needed because *you* write it.
+
+```typescript
+// POST /webhooks/clerk
+fastify.post('/webhooks/clerk', { config: { rawBody: true } }, async (req, reply) => {
+  // Verify Clerk webhook signature, then upsert into your User collection.
+  await User.findOneAndUpdate({ _id: payload.data.id }, payload.data, { upsert: true });
+  return { ok: true };
+});
+```
+
 ### Disabled
 
 ```typescript

package/skills/arc/references/enterprise-auth.md

@@ -0,0 +1,94 @@
+# Enterprise Auth — what's in the box
+
+Arc 2.13 closes the enterprise-auth gaps without forcing a parallel infrastructure. Sessions / refresh / OAuth flows stay in Better Auth's hands; arc adds the three things arc actually owns: provisioning, agent-mandate gating, and audit chain.
+
+## In-box (2.13)
+
+| Capability | Surface | Notes |
+|---|---|---|
+| **SCIM 2.0 provisioning** | `@classytic/arc/scim` | Auto-derived `/scim/v2/Users` + `/scim/v2/Groups` from existing resources. Filter, PATCH, discovery endpoints. Bearer or `verify` callback. → [scim.md](scim.md) |
+| **Agent capability mandates** | `requireAgentScope`, `requireMandate`, `requireDPoP` from `@classytic/arc/permissions` | AP2 / Stripe x402 / MCP authorization. `RequestScope.service.mandate` + `.dpopJkt` are first-class. → [agent-auth.md](agent-auth.md) |
+| **Auth-event audit chain** | `wireBetterAuthAudit` from `@classytic/arc/auth/audit` | BA's `databaseHooks` + endpoint hooks routed through existing `auditPlugin`. One canonical row shape for resource AND auth events. |
+| **Sessions / refresh / OAuth / MFA / SSO providers** | Better Auth | Configure via BA's `secondaryStorage`, `plugins: [twoFactor(), bearer(), apiKey(), ...]`. Arc reads BA tables via the kit overlays. → [auth.md](auth.md) |
+| **Multi-role / multi-tenant / parent-child orgs** | `RequestScope` + presets | Pre-2.13. → [multi-tenancy.md](multi-tenancy.md) |
+| **Field-level redaction + dynamic ACL + role hierarchy** | `@classytic/arc/permissions` | Pre-2.13. |
+| **Resource-op audit + retention + per-resource opt-in** | `@classytic/arc/audit` | Pre-2.13. |
+| **API-key admin REST** | BA `apiKey()` plugin + arc overlay | Recipe in [auth.md](auth.md). |
+
+## Out-of-box (deliberate)
+
+| Capability | Why arc doesn't ship it | What to use instead |
+|---|---|---|
+| **First-party SAML** | BA SAML plugin is the canonical path; arc can't compete with IdP edge cases | Better Auth SAML plugin (community, maturing) or `@node-saml/passport-saml` wrapped in arc's `authenticate` callback |
+| **Session storage / Redis sessions** | BA's `secondaryStorage` covers this — duplicating fragments truth | Configure BA's `secondaryStorage: { get, set, delete }` with `ioredis` directly |
+| **Refresh-token rotation** | BA owns the session model; arc would have to parallel-implement to add it | BA handles rotation in its session model; for JWT auth, use the existing `isRevoked` hook |
+| **DPoP cryptographic proof verification** | One `jose.dpop.verify()` call in your authenticate function — arc would force peer-dep `jose` | `jose` (already a peer of most apps using OAuth/JWT) |
+| **Mandate JWT/VC parsing** | Format varies per IdP/issuer; arc validates *what's verified*, not how it's verified | `jose` for JWTs, `did-jwt-vc` for Verifiable Credentials |
+| **Device trust / risk scoring** | Out of framework scope; vendor-specific | Castle, Stytch, Auth0 Risk, Persona |
+| **SOC2/HIPAA attestations** | Arc gives you the controls; certification is per-deployment | [`docs/compliance/soc2.md`](../../../docs/compliance/soc2.md) maps controls to arc primitives |
+| **First-party SSO discovery** (`/.well-known/openid-configuration` aggregation) | No real demand; BA exposes its own well-known paths | BA's `openAPI()` + `mcp()` plugins emit RFC 9728 metadata |
+
+## Sequencing — how the three new pieces compose
+
+```
+        IdP (Okta / Azure AD)
+              │
+              │  SCIM provisioning  ──→  /scim/v2/Users  ──→  arc user resource
+              │
+              │  SAML / OIDC SSO    ──→  Better Auth      ──→  scope.kind = 'member'
+              │                                                       │
+              ▼                                                       │
+        end-user signs in                                             │
+              │                                                       │
+              │  → BA databaseHooks.session.create.after              │
+              │  → wireBetterAuthAudit dispatches                     │
+              │  → audit row: { resource:'auth', action:'session.create' }
+              ▼
+        end-user delegates to AI agent
+              │
+              │  user authorizes mandate (cap, audience, ttl)
+              │  IdP / your token endpoint mints mandate JWT
+              ▼
+        AI agent calls protected route
+              │
+              │  Authorization: Mandate <jwt>
+              │  DPoP: <proof>
+              │
+              ▼
+        arc authenticate fn:
+          - jose.jwtVerify(mandate, JWKS)
+          - jose.dpop.verify(proof)
+          - sets scope = { kind:'service', mandate, dpopJkt, ... }
+              │
+              ▼
+        requireAgentScope({ capability, audience, validateAmount, requireDPoP })
+              │
+              ├─ ✓ auditPlugin.custom('invoice','INV-7','pay', { mandate.id, dpopJkt })
+              │   ↳ same store as session.create row above
+              │
+              └─ executes handler
+```
+
+## Threat model — what each layer prevents
+
+| Threat | Mitigation |
+|---|---|
+| Stale offboarded user keeps access | SCIM `DELETE /Users/:id` → resource soft-delete on connector trigger |
+| Stolen bearer token replay | `requireDPoP()` — token is bound to agent's keypair |
+| Agent overspends user authorization | `requireMandate({ validateAmount, cap })` — per-call ceiling |
+| Agent uses payment mandate against wrong invoice | `requireMandate({ audience: ctx => 'invoice:'+ctx.params.id })` |
+| Mandate replay after revocation | `expiresAt` (short TTL) + your IdP's revocation endpoint |
+| Untraceable agent action | Audit bridge stamps `mandate.id`, `dpopJkt`, `clientId` on every row |
+| Org admin abuses elevated scope | `noElevatedBypass: true` on regulated mandates; `arc.scope.elevated` audit event |
+| Failed sign-in / MFA flooding | `wireBetterAuthAudit` captures `mfa.failed` events; rate-limit on `clientId` |
+
+## Compliance
+
+See [`docs/compliance/soc2.md`](../../../docs/compliance/soc2.md) and [`docs/compliance/hipaa.md`](../../../docs/compliance/hipaa.md) for the control matrix mapping each requirement (CC6.1 access provisioning, CC7.2 logging, §164.308 admin safeguards) to the specific arc primitive that satisfies it.
+
+## See also
+
+- [scim.md](scim.md) — provisioning surface deep-dive
+- [agent-auth.md](agent-auth.md) — DPoP + mandate semantics
+- [auth.md](auth.md) — Better Auth + multi-plugin matrix
+- [`playground/enterprise-auth/`](../../../playground/enterprise-auth/) — full runnable smoke

package/skills/arc/references/events.md

@@ -116,7 +116,9 @@ const unsub = await fastify.events.subscribe('order.created', handler);
 unsub();
 ```
 
-## Event Structure (v2.9)
+## Event Structure
+
+Event types live in `@classytic/primitives/events` (canonical source). Arc re-exports the runtime `MemoryEventTransport` only — every type below is imported from primitives.
 
 ```typescript
 interface EventMeta {
@@ -142,7 +144,7 @@ interface DomainEvent<T> {
 }
 ```
 
-**Arc is source of truth** — `@classytic/primitives/events` mirrors these shapes. Downstream packages import from primitives; arc owns evolution.
+**`@classytic/primitives/events` is source of truth** — `EventMeta`, `DomainEvent`, `EventHandler`, `EventLogger`, `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`, `createChildEvent`, `matchEventPattern` all live there. Arc consumes them and re-exports the runtime `MemoryEventTransport`.
 
 ### DDD aggregate narrowing
 
@@ -162,7 +164,7 @@ Unlike `correlationId` / `causationId`, `aggregate` is **not inherited** by `cre
 ### Causation chains
 
 ```typescript
-import { createEvent, createChildEvent } from '@classytic/arc/events';
+import { createEvent, createChildEvent } from '@classytic/primitives/events';
 
 const placed = createEvent('order.placed', { orderId: 'o1' }, {
   correlationId: req.id, userId: user.id,
@@ -177,7 +179,7 @@ const reserved = createChildEvent(placed, 'inventory.reserved', { sku: 'a' });
 ### Dead-letter contract
 
 ```typescript
-import type { DeadLetteredEvent, EventTransport } from '@classytic/arc/events';
+import type { DeadLetteredEvent, EventTransport } from '@classytic/primitives/events';
 
 class KafkaTransport implements EventTransport {
   async deadLetter(dlq: DeadLetteredEvent) {
@@ -191,7 +193,7 @@ class KafkaTransport implements EventTransport {
 Implement `EventTransport` for RabbitMQ, Kafka, etc.:
 
 ```typescript
-import type { EventTransport, DomainEvent } from '@classytic/arc/events';
+import type { EventTransport, DomainEvent } from '@classytic/primitives/events';
 
 class KafkaTransport implements EventTransport {
   readonly name = 'kafka';
@@ -253,7 +255,7 @@ For a pure cache DB (no queues, no idempotency), `allkeys-lru` is correct and wh
 All transports and retry accept a `logger` option — defaults to `console`, compatible with pino/fastify.log:
 
 ```typescript
-import type { EventLogger } from '@classytic/arc/events';
+import type { EventLogger } from '@classytic/primitives/events';
 
 // Interface: { warn(msg, ...args): void; error(msg, ...args): void }
 

package/skills/arc/references/mcp.md

@@ -557,9 +557,9 @@ import { envelope } from '@classytic/arc';
 handler: async (req, reply) => {
   const data = await service.getResults();
   return reply.send(envelope(data));
-  // → { success: true, data }
+  // → { data }
   return reply.send(envelope(data, { total: 100, page: 1 }));
-  // → { success: true, data, total: 100, page: 1 }
+  // → { data, total: 100, page: 1 }
 }
 ```
 

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

@@ -130,9 +130,12 @@ export function requireApiKey(): PermissionCheck {
 Then wire it into the resource:
 
 ```ts
+// import { createMongooseAdapter } from '@classytic/mongokit/adapter';
+// import { buildCrudSchemasFromModel } from '@classytic/mongokit';
+
 defineResource({
   name: 'job',
-  adapter: createMongooseAdapter({ model: Job, repository: jobRepo }),
+  adapter: createMongooseAdapter({ model: Job, repository: jobRepo, schemaGenerator: buildCrudSchemasFromModel }),
   controller: new BaseController(jobRepo, { tenantField: 'companyId' }),
   permissions: {
     list: requireApiKey(),
@@ -174,7 +177,7 @@ Arc does NOT auto-derive scope from `request.user.organizationId` — that's a f
 
 ## 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)`.
+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)`. **Auto-inference (2.12):** when the Mongoose model has no `organizationId` path AND no other tenant field is configured, arc auto-infers `tenantField: false` rather than emitting queries against a non-existent column.
 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.
@@ -240,6 +243,12 @@ import {
   getServiceScopes, // service only (OAuth-style scope strings)
   getTeamId,       // member with teamId set
 
+  // Throwing accessors — return the value or throw a 403 ArcError
+  requireUserId,
+  requireOrgId,
+  requireClientId,
+  requireTeamId,
+
   // Canonical request extractor
   getOrgContext,
 

package/skills/arc/references/production.md

@@ -299,16 +299,14 @@ const app = await createApp({
 
 Mappers are checked via `instanceof` before all other error classification. Multiple mappers supported — first match wins.
 
-## Reply Helpers (v2.7.3)
+## Reply Helpers
 
-Opt-in response envelope decorators: `createApp({ replyHelpers: true })`
+Opt-in `sendList` + `stream` decorators: `createApp({ replyHelpers: true })`. Arc emits raw data on success — no `{ success, data }` envelope; HTTP status discriminates — so single-doc handlers just `return doc` (or `reply.send(doc)`) and errors throw `ArcError` (the global handler serialises to `ErrorContract`). The two decorators below cover the cases that DO need framework support:
 
 ```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 });
+// List response — any kit-shaped paginated result OR a bare array → canonical wire shape
+return reply.sendList({ method: 'offset', data, total, page, limit, pages, hasNext, hasPrev });
+return reply.sendList(rows);                                  // bare array endpoints
 ```
 
 ### Streaming Responses
@@ -545,9 +543,12 @@ const relayed = await outbox.relay();  // publishes pending → transport
 Adds bulk CRUD routes — repository must provide `createMany`, `updateMany`, `deleteMany`:
 
 ```typescript
+import { createMongooseAdapter } from '@classytic/mongokit/adapter';
+import { buildCrudSchemasFromModel } from '@classytic/mongokit';
+
 defineResource({
   name: 'product',
-  adapter: createMongooseAdapter({ model, repository }),
+  adapter: createMongooseAdapter({ model, repository, schemaGenerator: buildCrudSchemasFromModel }),
   presets: ['bulk'],  // adds POST/PATCH/DELETE /{resource}/bulk
 });
 
@@ -642,7 +643,7 @@ defineResource({
     handler: async (request, reply) => {
       const result = await withCompensation('checkout', steps, { orderId: request.params.id });
       if (!result.success) return reply.code(422).send({ error: result.error });
-      return reply.send({ success: true, data: result.results });
+      return reply.send({ data: result.results });
     },
   }],
 });