@classytic/arc 2.28.0 → 2.31.0

package/dist/utils/index.mjs

@@ -1,10 +1,11 @@
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, 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-DkO8Nk6-.mjs";
-import { n as requireSingleHeaderValue, t as getHeader } from "../headers-BvlQSDMB.mjs";
-import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-Cg_y3fBz.mjs";
-import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-Cg05HPsn.mjs";
-import { A as createCircuitBreakerRegistry, C as defineCompensation, D as CircuitBreakerRegistry, E as CircuitBreakerError, O as CircuitState, S as defineErrorMapper, T as CircuitBreaker, _ as createQueryParser, a as deleteResponse, b as NEUTRAL_DIALECT, c as getDefaultCrudSchemas, d as listResponse, f as offsetListResponse, g as ArcQueryParser, h as responses, i as bareListResponse, k as createCircuitBreaker, l as getListQueryParams, m as queryParams, n as scheduleBackground, o as errorContractSchema, p as paginationSchema, r as aggregateListResponse, s as errorDetailSchema, t as createStateMachine, u as keysetListResponse, v as handleRaw, w as withCompensation, x as defineGuard, y as MONGO_DIALECT } from "../utils-taUVD4p3.mjs";
-import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DJvodiHj.mjs";
-import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-BQcW6_Kq.mjs";
-import { t as openSseStream } from "../sseStream-BQ7Qaynp.mjs";
-import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, 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-Cj42AntO.mjs";
+import { n as requireSingleHeaderValue, t as getHeader } from "../headers-3zvE0rM3.mjs";
+import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-ChYJ6CdK.mjs";
+import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-DjQJ7FKA.mjs";
+import { A as createCircuitBreakerRegistry, C as defineCompensation, D as CircuitBreakerRegistry, E as CircuitBreakerError, O as CircuitState, S as defineErrorMapper, T as CircuitBreaker, _ as createQueryParser, a as deleteResponse, b as NEUTRAL_DIALECT, c as getDefaultCrudSchemas, d as listResponse, f as offsetListResponse, g as ArcQueryParser, h as responses, i as bareListResponse, k as createCircuitBreaker, l as getListQueryParams, m as queryParams, n as scheduleBackground, o as errorContractSchema, p as paginationSchema, r as aggregateListResponse, s as errorDetailSchema, t as createStateMachine, u as keysetListResponse, v as handleRaw, w as withCompensation, x as defineGuard, y as MONGO_DIALECT } from "../utils-vL8BrDE2.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-D--wdJM-.mjs";
+import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-PSZwi8JV.mjs";
+import { t as openSseStream } from "../sseStream-B_5XcVVd.mjs";
+import { t as hasEvents } from "../typeGuards-B0ryPo3I.mjs";
 export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };

package/dist/{utils-taUVD4p3.mjs → utils-vL8BrDE2.mjs}

@@ -1,6 +1,7 @@
-import { m as RESERVED_QUERY_PARAMS } from "./constants-DNre0wRg.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { m as RESERVED_QUERY_PARAMS } from "./constants-D3Dv4LAV.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
+import { t as ArcError } from "./errors-Cj42AntO.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
 import { scheduleBackground } from "@classytic/repo-core/cache";
 //#region src/utils/circuitBreaker.ts

package/dist/{validate-Bk44F2yT.mjs → validate-_KbifpHF.mjs}

@@ -1,4 +1,5 @@
-import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
 //#region src/core/aggregation/normalize.ts
 /**
 * Framework cap on URL-driven aggregation limits when the host opts

package/dist/{versioning-gKWyryT3.mjs → versioning-CHDTor3P.mjs}

@@ -1,5 +1,6 @@
-import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
-import { d as createDomainError } from "./errors-DkO8Nk6-.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
+import { d as createDomainError } from "./errors-Cj42AntO.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/versioning.ts
 var versioning_exports = /* @__PURE__ */ __exportAll({

package/dist/{versioning-DXgY5BUm.d.mts → versioning-D_rhHfZm.d.mts}

@@ -1,4 +1,5 @@
-import { n as DomainEvent } from "./EventTransport-QmY7A258.mjs";
+
+import { n as DomainEvent } from "./EventTransport-2uVV34WU.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/plugins/caching.d.ts
 interface CachingRule {
@@ -85,7 +86,9 @@ interface RealtimeOptions {
    * the feed when the auth token's `exp` passes (forcing reconnect +
    * re-authorization with fresh filters) — this option adds a cap for
    * session/cookie auth that carries no `exp`, or to tighten below the
-   * token TTL. Omit for token-exp-only bounding.
+   * token TTL. **Defaults to 30 min** ({@link DEFAULT_MAX_CONNECTION_MS}) so a
+   * feed is NEVER unbounded by omission; set a large explicit value (up to
+   * ~24.8 days) for a deliberately long-lived feed.
    */
   maxConnectionMs?: number;
 }

package/dist/{websocket-_Pd0CgR0.d.mts → websocket-BOXVggMf.d.mts}

@@ -1,4 +1,5 @@
-import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-BbcnpNTm.mjs";
+
+import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-Dov9l4qE.mjs";
 import { FastifyBaseLogger, FastifyPluginAsync } from "fastify";
 //#region src/integrations/websocket/adapter.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.28.0",
+  "version": "2.31.0",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -297,7 +297,8 @@
     "dist",
     "bin",
     "skills",
-    "llms.txt"
+    "llms.txt",
+    "TRADEMARK.md"
   ],
   "scripts": {
     "build": "tsdown",
@@ -336,13 +337,14 @@
     "check:peer-skew": "node scripts/check-peer-skew.mjs",
     "check:docs-drift": "node scripts/check-docs-drift.mjs",
     "check:boundaries": "node scripts/check-boundaries.mjs",
-    "prepublishOnly": "npm run check:peer-skew && npm run check:docs-drift && npm run check:boundaries && npm run typecheck && npm run lint && npm run build && npm run check:api-surface && npm run check:package && npm run test:ci && npm run smoke:consumer"
+    "prepublishOnly": "npm run check:peer-skew && npm run check:docs-drift && npm run check:route-api && npm run check:boundaries && npm run typecheck && npm run lint && npm run build && npm run check:api-surface && npm run check:package && npm run test:ci && npm run smoke:consumer",
+    "check:route-api": "node scripts/check-removed-route-api.mjs"
   },
   "engines": {
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/primitives": ">=0.15.0",
+    "@classytic/primitives": ">=0.18.0",
     "@classytic/repo-core": ">=0.17.0",
     "@classytic/streamline": ">=2.8.0",
     "@fastify/cors": ">=11.0.0",
@@ -363,14 +365,15 @@
     "@opentelemetry/sdk-node": ">=0.50.0",
     "better-auth": ">=1.6.2",
     "bullmq": ">=5.0.0",
-    "fastify": "^5.8.5",
+    "fastify": ">=5.8.5",
     "fastify-raw-body": ">=5.0.0",
     "h3-js": ">=4.0.0",
     "ioredis": ">=5.0.0",
     "jose": ">=5.0.0",
     "pino-pretty": ">=13.0.0",
     "typebox": ">=1.0.0",
-    "zod": ">=4.0.0"
+    "zod": ">=4.4.0",
+    "@fastify/static": ">=8.0.0"
   },
   "peerDependenciesMeta": {
     "better-auth": {
@@ -450,6 +453,9 @@
     },
     "@modelcontextprotocol/sdk": {
       "optional": true
+    },
+    "@fastify/static": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -466,7 +472,7 @@
     "@classytic/gitkit": ">=0.1.0",
     "@classytic/mongokit": "^3.28.0",
     "@classytic/pgkit": "^0.1.0",
-    "@classytic/primitives": "^0.15.0",
+    "@classytic/primitives": "^0.18.0",
     "@classytic/repo-core": "^0.17.0",
     "@classytic/sqlitekit": "^0.6.0",
     "@classytic/streamline": "^2.8.2",
@@ -477,6 +483,7 @@
     "@fastify/multipart": "^10.0.0",
     "@fastify/rate-limit": "^11.0.0",
     "@fastify/sensible": "^6.0.4",
+    "@fastify/static": "^10.1.2",
     "@fastify/type-provider-typebox": "^6.1.0",
     "@fastify/under-pressure": "^9.0.3",
     "@fastify/websocket": "^11.2.0",
@@ -534,6 +541,7 @@
   ],
   "author": "Classytic",
   "license": "MIT",
+  "homepage": "https://classytic.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/classytic/arc.git"

package/skills/arc/SKILL.md

@@ -123,7 +123,7 @@ export default defineResource({
 
   routes: [
     { method: 'GET',  path: '/featured', handler: 'getFeatured', permissions: allowPublic() },
-    { method: 'POST', path: '/webhook',  handler: webhookFn, raw: true, permissions: requireAuth() },
+    { method: 'POST', path: '/webhook',  rawHandler: webhookFn, permissions: requireAuth() },
   ],
   actions: {
     approve: { handler: approveOrder, permissions: requireRoles(['admin']) },
@@ -133,6 +133,20 @@ export default defineResource({
 
 **Auto-generated:** `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`. Presets add their own routes (see table below).
 
+### Custom routes: `handler` vs `rawHandler`
+
+A route declares its execution model by WHICH FIELD it fills — there is no `raw` flag (removed in 2.31).
+
+| Field | Signature | Behaviour |
+|---|---|---|
+| `handler` | `(ctx: IRequestContext)` or a controller-method name | Arc pipeline: envelope shaping, field-write permissions, MCP tool by default |
+| `rawHandler` | `(request, reply)` or a controller-method name | Fastify-native: owns the response, no pipeline, no MCP unless `mcpHandler` is set |
+| `controllerMethod` | `(c: MyController) => c.method` | Typed ref for the pipeline — TS catches typos |
+
+Declaring both `handler` and `rawHandler` throws at boot. `streamResponse: true` requires `rawHandler` (the handler is invoked with `(request, reply)` and owns the socket).
+
+Inline `rawHandler` parameters infer — no `req: FastifyRequest` annotation — and typed generics (`FastifyRequest<{ Body: CreateBody }>`) assign without a cast.
+
 **Resource shorthands:**
 
 ```typescript
@@ -317,8 +331,8 @@ defineResource({
   name: 'procurement',
   routeGuards: [tenantGuard.preHandler],
   routes: [{
-    method: 'GET', path: '/summary', raw: true, permissions: requireAuth(),
-    handler: async (req, reply) => {
+    method: 'GET', path: '/summary', permissions: requireAuth(),
+    rawHandler: async (req, reply) => {
       const { orgId } = tenantGuard.from(req);
       reply.send({ orgId });
     },
@@ -570,9 +584,9 @@ defineResource({
   name: 'chat',
   customRoutesOnly: true,
   routes: [{
-    method: 'POST', path: '/', streamResponse: true, raw: true,
+    method: 'POST', path: '/', streamResponse: true,
     permissions: requireAuth(),
-    handler: async (req) => {
+    rawHandler: async (req) => {
       const result = streamText({ model, messages: req.body.messages });
       return result.toUIMessageStream();  // arc pipes it for you
     },
@@ -692,7 +706,7 @@ import { envelope } from '@classytic/arc';
 import { multipartBody } from '@classytic/arc/middleware';
 
 // Typed request — no `(req as any).user`
-handler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
+rawHandler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
 
 // File upload — no-op for JSON requests, safe to always add
 defineResource({
@@ -706,10 +720,10 @@ defineResource({
   },
 });
 
-// SSE — preAuth runs before auth (EventSource can't set headers); raw: true streams the response
+// SSE — preAuth runs before auth (EventSource can't set headers); rawHandler streams the response
 routes: [
   { preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] },
-  { method: 'GET', path: '/stream', raw: true, handler: async (req, reply) => reply.send(stream) },
+  { method: 'GET', path: '/stream', rawHandler: async (req, reply) => reply.send(stream) },
 ]
 
 // Per-route rate limit (2.20) — overrides the resource/app default for ONE endpoint.

package/skills/arc/references/api-reference.md

@@ -60,6 +60,10 @@ import {
   allowPublic, requireAuth, requireRoles, requireOwnership,
   requireOrgMembership, requireOrgRole, requireTeamMembership,
   requireServiceScope, requireScopeContext, requireOrgInScope,
+  // Platform-only role gate — an ORG role can never satisfy it. Required by
+  // globally-scoped surfaces (jobsPlugin managementRoutes) that cannot filter by tenant.
+  requirePlatformRole,
+
   // Agent-auth (2.13) — DPoP + capability mandates (AP2 / x402 / MCP)
   requireAgentScope, requireMandate, requireDPoP,
   type RequireAgentScopeOptions, type RequireMandateOptions,

package/skills/arc/references/auth.md

@@ -484,6 +484,9 @@ auth: false
 import {
   allowPublic, requireAuth, requireRoles, requireOwnership,
   requireOrgMembership, requireOrgRole, requireTeamMembership,
+  // Platform-only role gate — an ORG role can never satisfy it. Required by
+  // globally-scoped surfaces (jobsPlugin managementRoutes) that cannot filter by tenant.
+  requirePlatformRole,
   allOf, anyOf, when, denyAll,
 } from '@classytic/arc';
 ```

package/skills/arc/references/integrations.md

@@ -71,11 +71,44 @@ await fastify.jobs.dispatch('process-image', { url: '...', width: 800 }, {
   removeOnComplete: true,
 });
 
+// dispatch returns a JobHandle — the queue is part of the identity because
+// BullMQ ids are queue-LOCAL (two queues can both hold "123").
+const { queue, jobId } = await fastify.jobs.dispatch('send-email', { to: 'a@b.com' });
+const status = await fastify.jobs.getStatus(queue, jobId);
+
 // Get stats
 const stats = await fastify.jobs.getStats();
 // { 'send-email': { waiting: 5, active: 2, completed: 100, failed: 3, delayed: 0 } }
 ```
 
+### Management routes (off by default)
+
+`GET /jobs/stats` and `GET /jobs/:queue/:id/status` are NOT mounted unless you
+ask for them. A status carries `returnValue` and `failedReason` — your handler's
+own output and error text — so an unauthenticated route turns a job id into a
+read primitive over other tenants' work.
+
+```typescript
+jobsPlugin({
+  connection,
+  jobs,
+  managementRoutes: {
+    // Must be PLATFORM-only, verified at boot. These routes are global: /stats
+    // spans every queue and a job carries no tenant identity, so an org-role
+    // gate would let org A's manager read org B's job.
+    operatorPermission: requirePlatformRole('platform-ops'),
+    exposeResult: false,        // default — opt in knowing what your handlers return
+    exposeFailureReason: false, // default
+  },
+});
+```
+
+`requireOrgRole('manager')` and the default `requireRoles(['platform-ops'])` are
+REFUSED at boot: both grant on an organization role and return no policy, so
+nothing at request time can tell them apart from a real operator gate. Use
+`requirePlatformRole`, or `allowUnverifiedOperatorPermission: true` for a custom
+check you have verified yourself.
+
 ### Timeout & DLQ
 
 Job timeout via `Promise.race` (timer always cleaned up). DLQ queues tracked and closed on shutdown:

package/skills/arc/references/mcp.md

@@ -568,12 +568,12 @@ Use to verify the MCP server is alive before configuring Claude CLI.
 
 ### ArcRequest — Typed Fastify Request
 
-For `raw: true` routes, use `ArcRequest` instead of `(req as any).user`:
+For `rawHandler` routes, use `ArcRequest` instead of `(req as any).user`:
 
 ```typescript
 import type { ArcRequest } from '@classytic/arc';
 
-handler: async (req: ArcRequest, reply) => {
+rawHandler: async (req: ArcRequest, reply) => {
   req.user?.id;                    // typed
   req.scope.organizationId;        // typed (when member)
   req.signal;                      // AbortSignal (Fastify 5 built-in)
@@ -585,7 +585,7 @@ handler: async (req: ArcRequest, reply) => {
 ```typescript
 import { envelope } from '@classytic/arc';
 
-handler: async (req, reply) => {
+rawHandler: async (req, reply) => {
   const data = await service.getResults();
   return reply.send(envelope(data));
   // → { data }
@@ -601,7 +601,7 @@ Eliminates duplicated `req.user.organizationId || req.headers['x-organization-id
 ```typescript
 import { getOrgContext } from '@classytic/arc/scope';
 
-handler: async (req, reply) => {
+rawHandler: async (req, reply) => {
   const { userId, organizationId, roles, orgRoles } = getOrgContext(req);
   // Works regardless of auth type (JWT, Better Auth, custom)
 }
@@ -628,13 +628,12 @@ Run before auth middleware. Use for promoting `?token=` to `Authorization` heade
 routes: [{
   method: 'GET',
   path: '/stream',
-  raw: true,
   permissions: requireAuth(),
   preAuth: [(req) => {
     const token = req.query?.token;
     if (token) req.headers.authorization = `Bearer ${token}`;
   }],
-  handler: sseHandler,
+  rawHandler: sseHandler,
 }]
 ```
 
@@ -648,7 +647,7 @@ routes: [{
   path: '/stream',
   streamResponse: true,        // SSE headers + no { success, data } wrapper
   permissions: requireAuth(),
-  handler: async (request, reply) => {
+  rawHandler: async (request, reply) => {
     const { stream } = await generateStream({ abortSignal: request.signal });
     return reply.send(stream);
   },

package/skills/arc/references/production.md

@@ -696,8 +696,7 @@ defineResource({
     method: 'POST',
     path: '/:id/checkout',
     permissions: requireAuth(),
-    raw: true,
-    handler: async (request, reply) => {
+    rawHandler: 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({ data: result.results });
@@ -709,26 +708,26 @@ defineResource({
 **Compensation errors**: collected in `result.compensationErrors[]` without stopping rollback. **Context**: mutable `Record<string, unknown>` shared across all steps.
 
 **Scope**: In-process primitive. Process crash = no compensation. For durable distributed workflows, use Temporal, Inngest, or `@classytic/streamline`.
-
-## Multi-Domain Deployment
-
-Arc supports multi-domain applications through COMPOSITION — it deliberately owns no domain routing, domain databases, certificate provisioning, or wildcard-domain management. The deployment shape:
-
-```
-api.example.com       → arc API
-auth.example.com      → Better Auth (or auth module)
-events.example.com    → SSE/WebSocket edge tier
-admin.example.com     → frontend
-customer-domain.com   → gateway/domain resolver → tenant context
-```
-
-The primitives are already there: CORS allowlists, Better Auth trusted origins, tenant scope, request context, `trustProxy` configuration, resource/module prefixes.
-
-**Custom tenant domains**: resolve the domain at a gateway or an early host plugin, then convert it into a trusted `RequestScope` — a small host-provided resolver is enough:
-
-```typescript
-// onRequest, before auth: map host → tenant hint
-const tenant = await resolveTenantDomain(request.hostname); // → { organizationId } | null
-```
-
-Then validate membership or service scope through the NORMAL permission path. **Never treat raw `Host` / `X-Forwarded-Host` as tenant authorization by itself** — behind a misconfigured proxy those are attacker-controlled (see the `trustProxy` boot warning). The header selects the tenant *candidate*; membership resolution authorizes it — same rule `resolveOrgFromHeader` follows for `x-organization-id`.
+
+## Multi-Domain Deployment
+
+Arc supports multi-domain applications through COMPOSITION — it deliberately owns no domain routing, domain databases, certificate provisioning, or wildcard-domain management. The deployment shape:
+
+```
+api.example.com       → arc API
+auth.example.com      → Better Auth (or auth module)
+events.example.com    → SSE/WebSocket edge tier
+admin.example.com     → frontend
+customer-domain.com   → gateway/domain resolver → tenant context
+```
+
+The primitives are already there: CORS allowlists, Better Auth trusted origins, tenant scope, request context, `trustProxy` configuration, resource/module prefixes.
+
+**Custom tenant domains**: resolve the domain at a gateway or an early host plugin, then convert it into a trusted `RequestScope` — a small host-provided resolver is enough:
+
+```typescript
+// onRequest, before auth: map host → tenant hint
+const tenant = await resolveTenantDomain(request.hostname); // → { organizationId } | null
+```
+
+Then validate membership or service scope through the NORMAL permission path. **Never treat raw `Host` / `X-Forwarded-Host` as tenant authorization by itself** — behind a misconfigured proxy those are attacker-controlled (see the `trustProxy` boot warning). The header selects the tenant *candidate*; membership resolution authorizes it — same rule `resolveOrgFromHeader` follows for `x-organization-id`.

package/skills/arc-code-review/references/anti-patterns.md

@@ -627,7 +627,7 @@ output_mode: content
 
 **Why critical:** `verifySignature(body, ...)` throws `TypeError` if body isn't string/Buffer. Parsed body silently fails verification → forged webhooks accepted.
 
-**Fix:** `verifySignature(req.rawBody, ...)`. Mark webhook routes `raw: true` and ensure `@fastify/raw-body` is registered (arc registers it automatically when needed).
+**Fix:** `verifySignature(req.rawBody, ...)`. Declare webhook routes via `rawHandler` and ensure `@fastify/raw-body` is registered (arc registers it automatically when needed).
 
 ---
 
@@ -655,10 +655,10 @@ Or `presets: [{ name: 'filesUpload', storage, allowedMimeTypes, maxFileSize }]`.
 ```typescript
 routes: [
   {
-    method: 'GET', path: '/stream', raw: true,
+    method: 'GET', path: '/stream',
     preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }],
     permissions: requireAuth(),
-    handler: async (req, reply) => reply.send(stream),
+    rawHandler: async (req, reply) => reply.send(stream),
   },
 ],
 ```

package/dist/index-CZY4EGga.d.mts

@@ -1,107 +0,0 @@
-import { a as ModuleContribution, h as HealthCheck, n as ArcModuleInput, r as ArcModuleRegistry, t as ArcModule, u as ScheduleDefinition } from "./types-Cu6vVJmh.mjs";
-import { FastifyInstance } from "fastify";
-//#region src/factory/module/contributions.d.ts
-/**
- * Collect every module's `healthChecks` in the caller's order. Fails at boot
- * on a duplicate check `name` across modules, naming BOTH owning modules.
- * The host's app-level checks are appended AFTER this (modules-first,
- * host-last) by the caller.
- */
-declare function collectModuleHealthChecks(modules: readonly ArcModule[]): HealthCheck[];
-/**
- * Collect every module's `workflows`. Resolves factory contributions (so a
- * factory can close over a container the caller has already decorated on
- * `fastify`) and flattens to a single opaque array. Arc core deliberately
- * does NOT validate or interpret the values — the streamline integration
- * owns name/shape checks and registration. Called by the integration at init
- * time, not by arc's boot pipeline (workflows depend on the integration's
- * container).
- */
-declare function collectModuleWorkflows(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<unknown[]>;
-/**
- * Collect every module's `scheduledJobs`. Resolves factory contributions
- * (after bootstraps) and fails at boot on a duplicate job `name` across
- * modules. The caller passes the returned definitions to the canonical
- * schedules plugin; factories must therefore be resolved only once.
- */
-declare function collectModuleScheduledJobs(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<ScheduleDefinition[]>;
-//#endregion
-//#region src/factory/module/lifecycle.d.ts
-/**
- * Subscribe every module's `eventHandlers` in dependency order (pass the
- * `orderModules`-sorted list). Returns the ordered list of unsubscribe
- * functions so the caller can tear them down at shutdown BEFORE module
- * `onClose` (while module deps are still alive). Fails at boot on:
- *   - a duplicate NAMED handler across modules (attributing both owners);
- *   - a module declaring handlers while the event subsystem is unavailable.
- * Resolves factory contributions (after bootstraps) so a handler can close over
- * booted engines rather than a global getter.
- */
-declare function subscribeModuleEventHandlers(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<Array<() => void | Promise<void>>>;
-//#endregion
-//#region src/factory/module/order.d.ts
-/**
- * Order modules for composition by their `dependsOn` edges — a STABLE
- * topological sort. Called once at the start of the bootstrap phase; every
- * subsequent phase (bootstrap, resources, afterResources, and reverse-order
- * onClose) iterates the returned list, so a module's declared dependencies are
- * always composed before it.
- *
- * "Stable" = modules with no edge between them keep their original list order,
- * so declaring `dependsOn` on one module never silently reorders an unrelated
- * one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
- * returned unchanged.
- *
- * Fail-fast — throws (never reorders past a broken contract) on:
- *   - duplicate module names (the name is the graph key)
- *   - a `dependsOn` name not present in the composed set
- *   - a self-reference (`dependsOn` includes the module's own name)
- *   - a dependency cycle (reports the concrete `a → b → … → a` path)
- */
-declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
-//#endregion
-//#region src/factory/module/resolve.d.ts
-/**
- * Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
- * (this is where a dynamic `import()` fires); a promise (or plain module) is
- * awaited. Called once per module at the start of the bootstrap phase.
- */
-declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
-/** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
-declare function resolveContribution<T>(contribution: ModuleContribution<T> | undefined, fastify: FastifyInstance): Promise<readonly T[]>;
-//#endregion
-//#region src/factory/module/index.d.ts
-/**
- * Identity helper for authoring a typed module — mirrors `defineResource`.
- * Gives inference + a single obvious construction site; does no work.
- *
- * `TExports` is inferred from the `bootstrap` return value, so a module
- * author gets a typed public export for free:
- *
- * ```ts
- * export const accountingModule = (deps: Deps) =>
- *   defineModule({
- *     name: "accounting",
- *     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
- *   });
- * ```
- */
-declare function defineModule<TExports = unknown>(module: ArcModule<TExports>): ArcModule<TExports>;
-/**
- * Typed accessor for a module's public export (its `bootstrap` return value),
- * recorded at `fastify.arc.modules[name]`.
- *
- * Throwing, in line with the fail-fast contract (and `requireOrgId`-style
- * accessors): a missing entry means the module either isn't composed, is
- * composed AFTER the caller (list order = init order), or returned nothing —
- * all wiring bugs that must surface at boot, not as `undefined` downstream.
- *
- * The type parameter is an assertion, not a proof. Two ways to type it:
- *   - augment `ArcModuleRegistry` once — then the name alone infers the type:
- *     `getModuleExports(f, "accounting")` → `AccountingEngine`.
- *   - or pass it inline: `getModuleExports<AccountingEngine>(f, "accounting")`.
- */
-declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
-declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
-//#endregion
-export { orderModules as a, collectModuleScheduledJobs as c, resolveModule as i, collectModuleWorkflows as l, getModuleExports as n, subscribeModuleEventHandlers as o, resolveContribution as r, collectModuleHealthChecks as s, defineModule as t };

package/dist/module-_-M7C5ES.mjs

@@ -1,29 +0,0 @@
-//#region src/factory/module/index.ts
-/**
-* Identity helper for authoring a typed module — mirrors `defineResource`.
-* Gives inference + a single obvious construction site; does no work.
-*
-* `TExports` is inferred from the `bootstrap` return value, so a module
-* author gets a typed public export for free:
-*
-* ```ts
-* export const accountingModule = (deps: Deps) =>
-*   defineModule({
-*     name: "accounting",
-*     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
-*   });
-* ```
-*/
-function defineModule(module) {
-	return module;
-}
-function getModuleExports(fastify, name) {
-	const modules = fastify.arc?.modules;
-	if (!modules || !Object.hasOwn(modules, name)) {
-		const available = modules ? Object.keys(modules) : [];
-		throw new Error(`[arc] no public export recorded for module "${name}".\nA module's export is its bootstrap() return value; it is readable only AFTER that module's bootstrap ran (dependsOn / list order = init order).\nModules with recorded exports: ${available.length ? available.join(", ") : "(none)"}.`);
-	}
-	return modules[name];
-}
-//#endregion
-export { getModuleExports as n, defineModule as t };