@classytic/arc 2.30.0 → 2.32.0

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/fastify-augmentation-0WhPnUH7.d.mts

@@ -1,76 +0,0 @@
-import { mn as HookSystem, z as ResourceRegistry } from "./index-Q5gzEIWY.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
-import { h as HealthCheck, r as ArcModuleRegistry, t as ArcModule, u as ScheduleDefinition } from "./types-D_n8L6VY.mjs";
-import "./index-CCzVR-N3.mjs";
-import { FastifyPluginAsync } from "fastify";
-//#region src/core/arcCorePlugin.d.ts
-interface ArcCorePluginOptions {
-  /** Enable event emission for CRUD operations (requires eventPlugin) */
-  emitEvents?: boolean;
-  /** Hook system instance (for testing/custom setup) */
-  hookSystem?: HookSystem;
-  /** Resource registry instance (for testing/custom setup) */
-  registry?: ResourceRegistry;
-}
-interface PluginMeta {
-  name: string;
-  version?: string;
-  options?: Record<string, unknown>;
-  registeredAt: string;
-}
-interface ArcCore {
-  /** Instance-scoped hook system */
-  hooks: HookSystem;
-  /** Instance-scoped resource registry */
-  registry: ResourceRegistry;
-  /** Whether event emission is enabled */
-  emitEvents: boolean;
-  /** External OpenAPI paths contributed by auth adapters or third-party integrations */
-  externalOpenApiPaths: ExternalOpenApiPaths[];
-  /** Registered plugins for introspection */
-  plugins: Map<string, PluginMeta>;
-  /**
-   * Module public exports — `bootstrap()` return values keyed by module name
-   * (see `src/factory/module.ts`). Read via `getModuleExports(fastify, name)`:
-   * augment `ArcModuleRegistry` once and the name infers the export type;
-   * otherwise pass it inline. `Partial<ArcModuleRegistry>` gives augmented
-   * apps typed direct access (`fastify.arc.modules.order`), while the
-   * `Record<string, unknown>` intersection keeps un-augmented reads open.
-   * Populated lazily by `registerResources` — absent until a module exports.
-   */
-  modules?: Partial<ArcModuleRegistry> & Record<string, unknown>;
-  /**
-   * Module-contributed readiness checks, collected in dependency order and
-   * frozen by `createApp`. The API role merges these into its `healthPlugin`;
-   * `createWorker` reads this to give its probe listener the identical union
-   * (the worker preset disables the main health plugin, so this is how module
-   * checks reach the probe without a double registration). Empty until
-   * `createApp` populates it.
-   */
-  healthChecks?: readonly HealthCheck[];
-  /**
-   * The resolved, dependency-ordered module definitions (frozen by createApp).
-   * Integrations that collect a module arm at their OWN init time — e.g. the
-   * streamline integration calling `collectModuleWorkflows(fastify, defs)` after
-   * it has created + decorated its container — read the list from here. Empty
-   * until createApp populates it.
-   */
-  moduleDefinitions?: readonly ArcModule[];
-  /**
-   * Module-contributed recurring schedules, resolved once in dependency order
-   * and frozen after bootstraps. The same definitions are executed by Arc's
-   * schedules plugin and exposed here for introspection. Empty until collection.
-   */
-  scheduledJobs?: readonly Readonly<ScheduleDefinition>[];
-}
-declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;
-declare const _default: FastifyPluginAsync<ArcCorePluginOptions>;
-//#endregion
-//#region src/types/fastify-augmentation.d.ts
-declare module "fastify" {
-  interface FastifyInstance {
-    arc?: ArcCore;
-  }
-}
-//#endregion
-export { arcCorePlugin as a, _default as i, ArcCorePluginOptions as n, PluginMeta as r, ArcCore as t };

package/dist/index-CCzVR-N3.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-D_n8L6VY.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 };