@classytic/arc 2.8.5 → 2.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.8.5",
+  "version": "2.10.3",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -44,6 +44,10 @@
       "types": "./dist/presets/filesUpload.d.mts",
       "default": "./dist/presets/filesUpload.mjs"
     },
+    "./presets/search": {
+      "types": "./dist/presets/search.d.mts",
+      "default": "./dist/presets/search.mjs"
+    },
     "./auth": {
       "types": "./dist/auth/index.d.mts",
       "default": "./dist/auth/index.mjs"
@@ -84,10 +88,6 @@
       "types": "./dist/audit/index.d.mts",
       "default": "./dist/audit/index.mjs"
     },
-    "./audit/mongodb": {
-      "types": "./dist/audit/mongodb.d.mts",
-      "default": "./dist/audit/mongodb.mjs"
-    },
     "./docs": {
       "types": "./dist/docs/index.d.mts",
       "default": "./dist/docs/index.mjs"
@@ -100,10 +100,6 @@
       "types": "./dist/idempotency/redis.d.mts",
       "default": "./dist/idempotency/redis.mjs"
     },
-    "./idempotency/mongodb": {
-      "types": "./dist/idempotency/mongodb.d.mts",
-      "default": "./dist/idempotency/mongodb.mjs"
-    },
     "./events": {
       "types": "./dist/events/index.d.mts",
       "default": "./dist/events/index.mjs"
@@ -116,10 +112,6 @@
       "types": "./dist/events/transports/redis-stream-entry.d.mts",
       "default": "./dist/events/transports/redis-stream-entry.mjs"
     },
-    "./dynamic": {
-      "types": "./dist/dynamic/index.d.mts",
-      "default": "./dist/dynamic/index.mjs"
-    },
     "./testing": {
       "types": "./dist/testing/index.d.mts",
       "default": "./dist/testing/index.mjs"
@@ -128,10 +120,6 @@
       "types": "./dist/testing/storageContract.d.mts",
       "default": "./dist/testing/storageContract.mjs"
     },
-    "./policies": {
-      "types": "./dist/policies/index.d.mts",
-      "default": "./dist/policies/index.mjs"
-    },
     "./factory": {
       "types": "./dist/factory/index.d.mts",
       "default": "./dist/factory/index.mjs"
@@ -192,10 +180,6 @@
       "types": "./dist/scope/index.d.mts",
       "default": "./dist/scope/index.mjs"
     },
-    "./rpc": {
-      "types": "./dist/rpc/index.d.mts",
-      "default": "./dist/rpc/index.mjs"
-    },
     "./mcp": {
       "types": "./dist/integrations/mcp/index.d.mts",
       "default": "./dist/integrations/mcp/index.mjs"
@@ -239,7 +223,8 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.6.0",
+    "@classytic/mongokit": ">=3.10.2",
+    "@classytic/repo-core": ">=0.1.0",
     "@classytic/streamline": ">=2.1.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -259,11 +244,11 @@
     "@sinclair/typebox": ">=0.34.0",
     "better-auth": ">=1.6.2",
     "bullmq": ">=5.0.0",
-    "fastify": ">=5.0.0",
+    "fastify": "^5.8.5",
     "fastify-raw-body": ">=5.0.0",
     "ioredis": ">=5.0.0",
     "mongodb": ">=7.0.0",
-    "mongoose": ">=9.4.1",
+    "mongoose": "^9.4.1",
     "pino-pretty": ">=13.0.0",
     "zod": ">=4.0.0"
   },
@@ -271,6 +256,9 @@
     "@classytic/mongokit": {
       "optional": true
     },
+    "@classytic/repo-core": {
+      "optional": true
+    },
     "mongodb": {
       "optional": true
     },
@@ -356,9 +344,12 @@
     "secure-json-parse": "^4.1.0"
   },
   "devDependencies": {
+    "@better-auth/drizzle-adapter": "^1.6.2",
     "@better-auth/mongo-adapter": "^1.6.2",
     "@biomejs/biome": "^2.4.11",
-    "@classytic/mongokit": "file:../../packages/mongokit/classytic-mongokit-3.6.0.tgz",
+    "@classytic/mongokit": "^3.10.2",
+    "@classytic/repo-core": "^0.1.0",
+    "@classytic/sqlitekit": "^0.1.0",
     "@classytic/streamline": "^2.1.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
@@ -376,15 +367,18 @@
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^8.18.0",
     "better-auth": "^1.6.2",
+    "better-sqlite3": "^12.9.0",
     "bullmq": "^5.73.5",
     "dotenv": "^17.4.2",
+    "drizzle-orm": "^0.45.2",
+    "fast-check": "^4.6.0",
     "fastify-raw-body": "^5.0.0",
     "ioredis": "^5.10.1",
     "jsonwebtoken": "^9.0.0",
     "knip": "^6.4.1",
     "mongodb": "^7.1.0",
     "mongodb-memory-server": "^11.0.1",
-    "mongoose": "^9.4.1",
+    "mongoose": ">=9.4.1",
     "tsdown": "^0.21.7",
     "typescript": "^6.0.2",
     "vitest": "^3.0.0",

package/skills/arc/SKILL.md

@@ -8,11 +8,11 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.8.1
+version: 2.10.3
 license: MIT
 metadata:
   author: Classytic
-  version: "2.8.0"
+  version: "2.10.3"
 tags:
   - fastify
   - rest-api
@@ -68,6 +68,22 @@ await app.register(productResource.toPlugin());
 await app.listen({ port: 8040, host: '0.0.0.0' });
 ```
 
+## v2.9 Security Defaults (breaking)
+
+- **Field-write perms: `reject` (default)** — requests carrying non-writable fields get 403 with denied-field list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
+- **multiTenant injects org on UPDATE** — body-supplied `organizationId` overwritten with caller's scope. Closes tenant-hop vector.
+- **Elevation always emits `arc.scope.elevated` event** — audit via `fastify.events.subscribe(...)`.
+- **`verifySignature(body, ...)` throws on parsed body** — pass `req.rawBody`, not `req.body`.
+- **Upload `sanitizeFilename`** — strict by default (no `/ \ .. \0 >255ch`). Pass `false` / `'*'` / custom fn to relax.
+- **Idempotency `namespace`** option for shared-store prod+canary deployments.
+
+## Removed in v2.9
+
+- `createActionRouter`, `buildActionBodySchema` — use `actions` on `defineResource`
+- `ResourceConfig.onRegister` — use `actions` or resource `hooks`
+- `AdditionalRoute` type + `resource.additionalRoutes` field — use `RouteDefinition` and `resource.routes` (single source of truth; no normalised mirror)
+- `wrapHandler` on route defs — derived from `!route.raw` at use-site (set `raw: true` to opt out of the arc pipeline)
+
 ## defineResource()
 
 Single API to define a full REST resource:
@@ -109,7 +125,7 @@ const productResource = defineResource({
     { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
   ],
 
-  // Actions (replaces onRegister + createActionRouter)
+  // Actions — single POST /:id/action endpoint, discriminated on `action` body field
   actions: {
     approve: async (id, data, req) => service.approve(id, req.user._id),
     cancel: {
@@ -489,6 +505,8 @@ permissions: { list: acl.canAction('product', 'read') }
 | `multiTenant` | none (middleware) | — | `{ tenantField }` OR `{ tenantFields: TenantFieldSpec[] }` (2.7.1+) |
 | `audited` | none (middleware) | — | — |
 | `bulk` | POST/PATCH/DELETE /bulk | — | `{ operations?, maxCreateItems? }` |
+| `filesUpload` | POST /upload, GET /:id, DELETE /:id | — (uses `Storage` adapter) | `{ storage, sanitizeFilename?, allowedMimeTypes?, maxFileSize? }` |
+| `search` | POST /search, /search-similar, /embed (opt-in) | — | `{ repository?, search?, similar?, embed?, routes? }` |
 
 ```typescript
 // Single-field (default, backwards compatible)
@@ -546,7 +564,7 @@ Default is `'_id'`. Override for resources keyed by a business identifier (UUID,
 defineResource({
   name: 'job',
   adapter: createMongooseAdapter(JobModel, jobRepository),
-  idField: 'jobId',     // ← one line
+  idField: 'jobId',     // ← one line (or omit and auto-derive from repository.idField — see below)
 });
 
 // GET /jobs/job-5219f346-a4d  → controller runs { jobId: 'job-5219f346-a4d' }
@@ -559,10 +577,66 @@ Changes all three layers:
 - **OpenAPI docs** — `spec.paths['/jobs/{id}']` emits a plain string `id` with description
 - **MCP tools** — auto-generated CRUD tools use `idField` transparently
 
-URL path segment stays `:id` (not `:jobId`) — clients send the ID value, Arc maps it server-side. User-provided `openApiSchemas.params` still overrides everything.
+**Auto-derive from repository** (2.7.x+). If you don't set `idField` on `defineResource` but your `adapter.repository` exposes one (e.g. `new Repository(Model, [], {}, { idField: 'slug' })`), Arc picks it up automatically. Configure in one place, not two.
+
+**URL path segment is ALWAYS `:id` and `req.params.id` is ALWAYS named `id`** — regardless of what `idField` is set to. `idField` controls the *lookup field*, not the *URL parameter name*. This is the same convention Stripe / GitHub / most REST APIs use:
+
+```typescript
+// idField: 'slug'
+// Client sends:  POST /agents/sadman/action
+// In handler:    req.params.id === 'sadman'       ← always keyed 'id'
+//                repo.update(id, data)             ← mongokit resolves by slug via repo.idField
+```
+
+This applies to CRUD routes (`GET/PATCH/DELETE /:id`), action routes (`POST /:id/action`), and any `routes: [...]` entries that use `:id`.
+
+**Common confusion pattern.** A 404 on `PATCH /agents/sadman` when `GET /agents/sadman` returns 200 looks like an `idField` bug but usually isn't. Check whether your **update permission** returns `filters` — arc merges those into the compound DB lookup (`{ slug: 'sadman', ...filters }`), and a filter that excludes the doc is what's returning null. Fix is in the permission, not `idField`.
+
+User-provided `openApiSchemas.params` still overrides everything.
 
 For custom adapters, honor the new `AdapterSchemaContext` passed to `generateSchemas(options, context?)` to emit the right `params.id` pattern from the start. Legacy adapters still work — Arc's safety net strips mismatched ObjectId patterns automatically.
 
+## searchPreset (text + vector + embed)
+
+Backend-agnostic routes for Elasticsearch / OpenSearch / Algolia / Typesense / Atlas `$vectorSearch` / Pinecone / Qdrant / Milvus. Opt-in per section; `mcp: false` skips per path.
+
+```typescript
+import { searchPreset } from '@classytic/arc/presets/search';
+
+// A — auto-wire from a repo with search/searchSimilar/embed methods
+// (mongokit's elasticSearchPlugin + vectorPlugin register exactly these).
+// Each method's native calling convention is honoured:
+//   search(query, options)          — positional (elasticSearchPlugin)
+//   searchSimilar(VectorSearchParams) — single object (vectorPlugin)
+//   embed(input)                    — single arg (vectorPlugin)
+searchPreset({
+  repository: productRepo,
+  search: true,    // POST /search         → repo.search(body.query, body)
+  similar: true,   // POST /search-similar → repo.searchSimilar(body)
+  // embed omitted → /embed not mounted
+})
+
+// B — external backends + custom path + Zod schema
+searchPreset({
+  search: {
+    path: '/full-text',
+    schema: { body: z.object({ q: z.string().min(1) }) },
+    handler: (req) => elastic.search({ index: 'products', q: req.body.q }),
+  },
+  similar: { handler: (req) => pinecone.query({ vector: req.body.vector, topK: 10 }), mcp: false },
+  routes: [  // bespoke paths
+    { method: 'GET', path: '/autocomplete', permissions: allowPublic(),
+      handler: (req) => algolia.suggest((req.query as { q: string }).q) },
+  ],
+})
+```
+
+**Defaults:** search/similar → POST, permissions fall back to resource `list` → `allowPublic()`. Embed → POST + `requireAuth()`. Every field (`path`, `method`, `schema`, `permissions`, `mcp`, `summary`, `tags`, `operation`) is overridable per section. Zod v4 schemas auto-convert to JSON Schema for both Fastify validation and OpenAPI.
+
+**MCP namespacing:** tool names are `{op}_{resource}` — many resources can register their own searchPreset under one `mcpPlugin` endpoint without colliding (`product_search`, `order_search`, …).
+
+**When to use `routes` directly instead:** one-off search endpoints, or when you want full control without the preset's defaults.
+
 ## QueryCache
 
 TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
@@ -618,14 +692,11 @@ class ProductController extends BaseController<Product> {
 import { createMongooseAdapter } from '@classytic/arc';
 const adapter = createMongooseAdapter({ model: ProductModel, repository: productRepo });
 
-// Custom adapter — implement CrudRepository interface:
-interface CrudRepository<TDoc> {
-  getAll(params?): Promise<TDoc[] | PaginatedResult<TDoc>>;
-  getById(id: string): Promise<TDoc | null>;
-  create(data): Promise<TDoc>;
-  update(id: string, data): Promise<TDoc | null>;
-  delete(id: string): Promise<boolean>;
-}
+// Custom adapter — implement MinimalRepo from @classytic/repo-core/repository:
+import type { MinimalRepo } from '@classytic/repo-core/repository';
+// MinimalRepo<TDoc> = five-method floor (getAll, getById, create, update, delete)
+// StandardRepo<TDoc> = MinimalRepo + optional batch ops, CAS, soft-delete, etc.
+// Arc feature-detects optional methods at call sites.
 ```
 
 ## Events
@@ -652,7 +723,11 @@ CRUD events auto-emit: `{resource}.created`, `{resource}.updated`, `{resource}.d
 
 **Transports:** Memory (default) | Redis Pub/Sub (fire-and-forget) | Redis Streams (durable, at-least-once, consumer groups, DLQ)
 
-**Event Outbox** — at-least-once delivery via transactional outbox pattern. Arc ships `OutboxStore` interface + `MemoryOutboxStore` (dev). You implement the store for your DB (Mongoose, Drizzle, Knex, etc.). Cleanup via optional `purge()` contract or native DB tools (TTL index, pg_cron, key expiry).
+**Event Outbox** — at-least-once delivery via transactional outbox pattern. Pass `repository: RepositoryLike` (mongokit / prismakit / custom) for production, or `store: MemoryOutboxStore()` for dev. Arc adapts the repo to the `OutboxStore` contract internally — `create` / `findAll` / `deleteMany` / `findOneAndUpdate` cover save, claim, ack, fail, DLQ.
+
+**Event contract (v2.9):** `EventMeta` = `id`, `timestamp`, optional `schemaVersion`, `correlationId`, `causationId`, `partitionKey`, `source`, `idempotencyKey`, `resource`, `resourceId`, `userId`, `organizationId`, `aggregate: { type, id }`. `createChildEvent(parent, ...)` inherits correlation/causation/source/idempotencyKey; aggregate stays explicit. `DeadLetteredEvent<T>` + optional `transport.deadLetter()` for typed DLQ. `withRetry({ transport })` auto-routes exhausted events — no custom plumbing for Kafka/SQS. `@classytic/primitives` mirrors these shapes — arc is source of truth.
+
+**Outbox (v2.9):** `EventOutbox.store()` auto-maps `meta.idempotencyKey` → `dedupeKey`. `new EventOutbox({ failurePolicy: ({ attempts }) => ({ retryAt, deadLetter }) })` centralises retry/DLQ. `outbox.getDeadLettered(limit)` returns typed `DeadLetteredEvent[]`. `RelayResult.deadLettered` for per-batch DLQ count. Durable store: `new EventOutbox({ repository: new Repository(OutboxModel), transport })` (v2.9.1) — multi-worker claim, session-threaded writes, and dedupe semantics come from the repo's backing kit.
 
 ## Factory — createApp()
 
@@ -948,7 +1023,7 @@ defineResource({ name: 'order', audit: true });
 defineResource({ name: 'payment', audit: { operations: ['delete'] } });
 defineResource({ name: 'product' }); // not audited
 
-// Manual custom() for MCP/additionalRoutes/read auditing
+// Manual custom() for MCP tools / custom routes / read auditing
 app.post('/orders/:id/refund', async (req) => {
   await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
 });
@@ -980,7 +1055,6 @@ permissions: {
 
 ```typescript
 // Typed request for raw routes — no more (req as any).user
-// v2.8: `raw: true` replaces `wrapHandler: false` (wrapHandler still works but is deprecated)
 import type { ArcRequest } from '@classytic/arc';
 handler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
 
@@ -996,15 +1070,16 @@ const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
 import { createDomainError } from '@classytic/arc';
 throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
 
-// Resource lifecycle hook — wire singletons during registration
-// v2.8: for action routes, use `actions` config instead of onRegister + createActionRouter
-defineResource({ name: 'notification', onRegister: (f) => setSseManager(f.sseManager) });
+// Custom routes — always `routes: [...]` with optional `raw: true` for non-JSON
+defineResource({
+  routes: [{ method: 'GET', path: '/stats', handler: 'getStats', permissions: allowPublic() }],
+});
 
 // SSE auth — preAuth runs BEFORE auth middleware (EventSource can't set headers)
-additionalRoutes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
+routes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
 
-// SSE streaming — auto headers + bypasses response wrapper
-additionalRoutes: [{ streamResponse: true, handler: async (req, reply) => reply.send(stream) }]
+// SSE streaming — raw: true + stream the response
+routes: [{ method: 'GET', path: '/stream', raw: true, handler: async (req, reply) => reply.send(stream) }]
 ```
 
 ## DX Helpers (v2.7.3+)
@@ -1100,7 +1175,6 @@ import {
 } from '@classytic/arc/scope';
 import { createTenantKeyGenerator } from '@classytic/arc/scope';
 import { createRoleHierarchy } from '@classytic/arc/permissions';
-import { createServiceClient } from '@classytic/arc/rpc';
 import { metricsPlugin, versioningPlugin } from '@classytic/arc/plugins';
 import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
 import { mcpPlugin, createMcpServer, defineTool, definePrompt, fieldRulesToZod, resourceToTools } from '@classytic/arc/mcp';

package/skills/arc/references/auth.md

@@ -225,6 +225,100 @@ auth: {
 }
 ```
 
+## Service Identity (Machine Principals)
+
+Arc distinguishes **machine callers** (API clients, spawned agents, cron workers) from **human users** via `RequestScope.service` — a first-class scope kind with `clientId` + OAuth-style `scopes`. Any auth mechanism (arc JWT, API keys, Better Auth client credentials, mTLS, gateway headers) can install it; arc does not ship a "service token" issuer — the app picks its credential flow and maps the result to scope.
+
+Install service scope from your `authenticate` callback — arc's default JWT verify installs `member` scope by design, so custom authenticators are the extension point:
+
+```typescript
+await createApp({
+  auth: {
+    type: 'jwt',
+    jwt: { secret: process.env.JWT_SECRET! },
+    authenticate: async (request, { jwt }) => {
+      const token = request.headers.authorization?.slice(7);
+      if (!token) return null;
+      const decoded = jwt.verify(token) as {
+        clientId?: string; userId?: string;
+        organizationId?: string; scopes?: string[];
+      };
+      // Machine principal — clientId present, no human user record.
+      if (decoded.clientId) {
+        request.scope = {
+          kind: 'service',
+          clientId: decoded.clientId,
+          organizationId: decoded.organizationId ?? '',
+          scopes: decoded.scopes ?? [],
+        };
+        return { clientId: decoded.clientId };   // returned value → request.user
+      }
+      // Human principal — fall through to user lookup.
+      return await User.findById(decoded.userId);
+    },
+  },
+});
+```
+
+Gate routes on service identity using the scope helpers + a permission builder:
+
+```typescript
+import { isService, getClientId, getServiceScopes } from '@classytic/arc/scope';
+import type { PermissionCheck } from '@classytic/arc/permissions';
+
+const requireScope = (scope: string): PermissionCheck => (ctx) => {
+  if (!isService(ctx.request.scope)) return { granted: false, reason: 'service only' };
+  const has = getServiceScopes(ctx.request.scope).includes(scope);
+  return has ? { granted: true } : { granted: false, reason: `missing scope: ${scope}` };
+};
+
+defineResource({
+  name: 'order',
+  permissions: { create: requireScope('orders:write') },
+});
+```
+
+**Mixing humans and services on the same route** — compose arc's builders:
+
+```typescript
+// Humans with 'editor' role OR services with 'orders:write' scope
+permissions: {
+  create: anyOf(requireOrgRole('editor'), requireScope('orders:write')),
+}
+```
+
+**Audit differentiation** — because `scope.kind === 'service'` carries `clientId` instead of `userId`, your audit plugin's `actor` resolver can tag machine actions distinctly:
+
+```typescript
+auditPlugin({
+  actor: (request) =>
+    isService(request.scope)
+      ? { kind: 'service', clientId: getClientId(request.scope) }
+      : { kind: 'user', userId: getUserId(request.scope) },
+});
+```
+
+**Rate-limit separation** — gate a separate bucket per `clientId` so one noisy agent can't starve humans in the same org:
+
+```typescript
+rateLimit: {
+  keyGenerator: (req) =>
+    isService(req.scope) ? `svc:${getClientId(req.scope)}` : `org:${getOrgId(req.scope)}`,
+}
+```
+
+**Credential-flow choice is the app's** — arc does not pick for you:
+
+| Flow | Wire via `authenticate` callback |
+|---|---|
+| Arc JWT with `clientId` claim | example above |
+| API key in header (DB lookup) | read `x-api-key`, look up client, set `scope` to service |
+| Better Auth client credentials | `auth.api.getSession({ headers })`, detect client-credential grant |
+| mTLS cert DN → client | read cert from terminator header, map DN → `clientId` |
+| OAuth2 client-credentials | verify token via introspection endpoint |
+
+All five produce the same downstream primitive: `RequestScope.service`. Permission builders, audit hooks, and rate-limit keys compose the same way regardless.
+
 ## Microservice Gateway Pattern
 
 ```