@classytic/arc 2.7.1 → 2.7.7

package/skills/arc/SKILL.md

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

package/skills/arc/references/integrations.md

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

package/skills/arc/references/mcp.md

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

package/skills/arc/references/production.md

@@ -267,6 +267,75 @@ import { errorHandlerPlugin } from '@classytic/arc/plugins';
 // Auto-registered by createApp()
 ```
 
+### Error Mappers (v2.7.3)
+
+Class-based domain error → HTTP response mapping. Register once, handlers just throw:
+
+```typescript
+class AccountingError extends Error {
+  constructor(message: string, public status: number, public code: string) { super(message); }
+}
+
+const app = await createApp({
+  errorHandler: {
+    errorMappers: [{
+      type: AccountingError,
+      toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
+    }],
+  },
+});
+// Now handlers just throw — Arc catches and maps automatically
+```
+
+Mappers are checked via `instanceof` before all other error classification. Multiple mappers supported — first match wins.
+
+## Reply Helpers (v2.7.3)
+
+Opt-in response envelope decorators: `createApp({ replyHelpers: true })`
+
+```typescript
+return reply.ok({ name: 'MacBook' });              // → 200 { success: true, data: {...} }
+return reply.ok(product, 201);                      // → 201 { success: true, data: {...} }
+return reply.fail('Not found', 404);                // → 404 { success: false, error: '...' }
+return reply.fail(['err1', 'err2'], 422);           // → 422 { success: false, errors: [...] }
+return reply.paginated({ docs, total, page, limit });
+```
+
+### Streaming Responses
+
+```typescript
+// CSV export
+return reply.stream(csvReadableStream, { contentType: 'text/csv', filename: 'export.csv' });
+// PDF download
+return reply.stream(pdfBuffer, { contentType: 'application/pdf', filename: 'report.pdf' });
+// Raw stream (Fastify native — works without reply helpers too)
+return reply.header('content-type', 'text/csv').send(readableStream);
+```
+
+### BigInt Serialization
+
+Opt-in: `createApp({ serializeBigInt: true })` — auto-converts BigInt → Number in all JSON responses.
+
+## Multipart Body Middleware (v2.7.3)
+
+Opt-in file upload support for CRUD routes — parses multipart form fields into `req.body`, attaches files to `req.body._files`:
+
+```typescript
+import { multipartBody } from '@classytic/arc/middleware';
+
+defineResource({
+  middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png'], maxFileSize: 5_000_000 })] },
+  hooks: {
+    'before:create': async (data) => {
+      if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
+      return data;
+    },
+  },
+});
+```
+
+No-op for JSON requests — safe to always add. Options: `maxFileSize`, `maxFiles`, `allowedMimeTypes`, `filesKey`.
+
 ## Migrations
 
 ```typescript