@classytic/arc 2.8.4 → 2.9.1

package/skills/arc/references/mcp.md

@@ -537,7 +537,7 @@ Use to verify the MCP server is alive before configuring Claude CLI.
 
 ### ArcRequest — Typed Fastify Request
 
-For `wrapHandler: false` routes, use `ArcRequest` instead of `(req as any).user`:
+For `raw: true` routes, use `ArcRequest` instead of `(req as any).user`:
 
 ```typescript
 import type { ArcRequest } from '@classytic/arc';
@@ -589,28 +589,15 @@ throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { bal
 // Arc's error handler auto-maps statusCode to HTTP response
 ```
 
-### onRegister — Resource Lifecycle Hook
-
-Called during plugin registration with the scoped Fastify instance:
-
-```typescript
-defineResource({
-  name: 'notification',
-  onRegister: (fastify) => {
-    setSseManager(fastify.sseManager);
-  },
-})
-```
-
 ### preAuth — Pre-Auth Handlers for SSE/WebSocket
 
 Run before auth middleware. Use for promoting `?token=` to `Authorization` header (EventSource can't set headers):
 
 ```typescript
-additionalRoutes: [{
+routes: [{
   method: 'GET',
   path: '/stream',
-  wrapHandler: false,
+  raw: true,
   permissions: requireAuth(),
   preAuth: [(req) => {
     const token = req.query?.token;
@@ -625,7 +612,7 @@ additionalRoutes: [{
 Auto-sets SSE headers and bypasses Arc's response wrapper:
 
 ```typescript
-additionalRoutes: [{
+routes: [{
   method: 'POST',
   path: '/stream',
   streamResponse: true,        // SSE headers + no { success, data } wrapper

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

@@ -178,6 +178,49 @@ Arc does NOT auto-derive scope from `request.user.organizationId` — that's a f
 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.
+5. **multiTenant preset injects org on UPDATE (v2.9).** Body-supplied `organizationId` is overwritten with the caller's scope — closes the tenant-hop vector where a member could PATCH their own doc into another tenant. Elevated scope with no org still bypasses (admin cross-tenant).
+
+## Mongokit tenant-context helper (optional)
+
+If your adapter is mongokit ≥3.7, you can wire mongokit's `createTenantContext()` to propagate the org id through `AsyncLocalStorage` — useful when domain code outside arc routes needs the current tenant without threading `req` everywhere:
+
+```ts
+import { createTenantContext, multiTenantPlugin, Repository } from '@classytic/mongokit';
+import { getOrgId } from '@classytic/arc/scope';
+
+const tenantContext = createTenantContext();
+const repo = new Repository(Model, [
+  multiTenantPlugin({ tenantField: 'organizationId', context: tenantContext }),
+]);
+
+// Install scope → ALS bridge once in your app:
+fastify.addHook('preHandler', (req, _reply, done) => {
+  const scope = (req.metadata as { _scope?: unknown } | undefined)?._scope;
+  const orgId = scope ? getOrgId(scope as never) : undefined;
+  if (orgId) tenantContext.run(orgId, done);
+  else done();
+});
+
+// Now any domain code can read it:
+import { getTenantId } from './tenantContext.js';
+await someService.doThing({ orgId: getTenantId() });
+```
+
+Arc doesn't bundle this — it's mongokit-specific. Arc's scope helpers (`getOrgId`, `getOrgContext`) remain the source of truth inside the request cycle; `createTenantContext()` is a complement for code that lives outside it.
+
+## Plugin-order safety (mongokit ≥3.7)
+
+Mongokit's `Repository` constructor accepts `pluginOrderChecks: 'warn' | 'throw' | 'off'` (default `'warn'`). Pass `'throw'` in production to catch foot-guns — e.g. installing `softDeletePlugin` AFTER `batchOperationsPlugin` silently bypasses soft-delete on `deleteMany`:
+
+```ts
+new Repository(Model, [
+  multiTenantPlugin({...}),       // must precede cache + batch-ops
+  softDeletePlugin(),             // must precede batch-ops
+  batchOperationsPlugin(),
+], {}, { pluginOrderChecks: 'throw' });
+```
+
+Arc doesn't surface this option — configure it directly on the mongokit `Repository` you hand to `defineResource({ adapter: createMongooseAdapter({ repository }) })`.
 
 ## Helpers reference
 

package/skills/arc/references/production.md

@@ -2,6 +2,15 @@
 
 Health checks, audit trail, idempotency, tracing, SSE, caching, graceful shutdown.
 
+## v2.9 Security Defaults
+
+- **Field-write perms reject by default** — `defineResource({ fields, onFieldWriteDenied })`. Default `'reject'` → 403 with denied field list. Legacy silent-strip: `onFieldWriteDenied: 'strip'`.
+- **Elevation always emits `arc.scope.elevated`** — subscribe via `fastify.events.subscribe('arc.scope.elevated', handler)` for audit. `onElevation` callback still supported.
+- **multiTenant injects org on UPDATE** — closes cross-tenant hop vector. Body-supplied `organizationId` overwritten with caller's scope.
+- **`verifySignature(body, secret, sig)` throws TypeError** if body isn't string/Buffer — register `@fastify/raw-body` before webhook routes; pass `req.rawBody`.
+- **Upload `sanitizeFilename` (preset)** — strict by default; `false` / `'*'` / custom fn to relax per adapter needs.
+- **Idempotency `namespace`** — fold an env key into the fingerprint when multiple deployments share a Redis (prod + canary, api + jobs).
+
 ## Health Plugin
 
 Kubernetes-ready liveness/readiness probes:
@@ -56,22 +65,21 @@ await fastify.register(gracefulShutdownPlugin, {
 
 ## Audit Plugin
 
-Change tracking with pluggable storage:
+Change tracking. Pass a `RepositoryLike` for persistence, or omit for in-memory dev:
 
 ```typescript
 import { auditPlugin } from '@classytic/arc/audit';
+import { Repository } from '@classytic/mongokit';
 
-// Development
-await fastify.register(auditPlugin, { enabled: true, stores: ['memory'] });
+// Development (in-memory)
+await fastify.register(auditPlugin, { enabled: true });
 
-// Production
+// Production — any kit (mongokit / prismakit / custom)
 await fastify.register(auditPlugin, {
   enabled: true,
-  stores: ['mongodb'],
-  mongoConnection: mongoose.connection,
-  mongoCollection: 'audit_logs',
-  ttlDays: 90,     // Auto-cleanup via TTL index
+  repository: new Repository(AuditModel),
 });
+// TTL / retention owned by your DB (TTL index on `timestamp`, cron DELETE, etc.)
 
 // Usage
 await fastify.audit.create('product', product._id, product, request.auditContext);
@@ -137,16 +145,18 @@ fetch('/api/orders', {
 **Storage backends:**
 
 ```typescript
-// Memory (default, dev)
+// Memory (default, dev) — omit both `repository` and `store`
 import { MemoryIdempotencyStore } from '@classytic/arc/idempotency';
 
 // Redis (production, multi-instance)
 import { RedisIdempotencyStore } from '@classytic/arc/idempotency/redis';
 store: new RedisIdempotencyStore({ client: redis, prefix: 'idem:', ttlMs: 86400000 })
 
-// MongoDB (production, no Redis)
-import { MongoIdempotencyStore } from '@classytic/arc/idempotency/mongodb';
-store: new MongoIdempotencyStore({ connection: mongoose.connection, collection: 'arc_idempotency', createIndex: true })
+// DB-backed via RepositoryLike (mongokit / prismakit / custom)
+import { Repository, methodRegistryPlugin, batchOperationsPlugin, mongoOperationsPlugin } from '@classytic/mongokit';
+repository: new Repository(IdempotencyModel, [
+  methodRegistryPlugin(), batchOperationsPlugin(), mongoOperationsPlugin(),
+])
 ```
 
 **IdempotencyStore interface:**
@@ -532,20 +542,25 @@ Transactional outbox pattern — at-least-once delivery even if transport is dow
 
 ```typescript
 import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
+import { Repository } from '@classytic/mongokit';
+
+// Dev
+const outbox = new EventOutbox({ store: new MemoryOutboxStore(), transport: redisTransport });
 
+// Production — any RepositoryLike
 const outbox = new EventOutbox({
-  store: new MemoryOutboxStore(),  // or MongoOutboxStore for production
+  repository: new Repository(OutboxModel),
   transport: redisTransport,
 });
 
-// In business logic (same DB transaction)
-await outbox.store(event);
+// In business logic (same DB transaction via `{ session }`)
+await outbox.store(event, { session });
 
 // Relay cron (runs every few seconds)
 const relayed = await outbox.relay();  // publishes pending → transport
 ```
 
-**OutboxStore interface**: `save(event)`, `getPending(limit)`, `acknowledge(eventId)`.
+**OutboxStore interface**: `save(event)`, `getPending(limit)`, `acknowledge(eventId)` (+ optional `claimPending`, `fail`, `getDeadLettered`, `purge`). When you pass `repository`, arc adapts it internally.
 
 ## RPC Service Client — Schema Versioning
 
@@ -655,16 +670,16 @@ await withCompensation('checkout', steps, { orderId }, {
 });
 ```
 
-**In an additionalRoute with Arc auth:**
+**In a custom route with Arc auth:**
 
 ```typescript
 defineResource({
   name: 'order',
-  additionalRoutes: [{
+  routes: [{
     method: 'POST',
     path: '/:id/checkout',
     permissions: requireAuth(),
-    wrapHandler: false,
+    raw: true,
     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 });

package/dist/EventTransport-CinyO7zQ.d.mts

@@ -1,135 +0,0 @@
-//#region src/events/EventTransport.d.ts
-/**
- * Event Transport Interface
- *
- * Defines contract for event delivery backends.
- * Implement for durable transports (Redis, RabbitMQ, Kafka, etc.)
- *
- * @example
- * // Redis Pub/Sub implementation
- * class RedisEventTransport implements EventTransport {
- *   async publish(event) {
- *     await redis.publish(event.type, JSON.stringify(event));
- *   }
- *   async subscribe(pattern, handler) {
- *     redis.psubscribe(pattern);
- *     redis.on('pmessage', (p, channel, msg) => handler(JSON.parse(msg)));
- *   }
- * }
- */
-interface DomainEvent<T = unknown> {
-  /** Event type (e.g., 'product.created', 'order.shipped') */
-  type: string;
-  /** Event payload */
-  payload: T;
-  /** Event metadata */
-  meta: {
-    /** Unique event ID */id: string; /** Event timestamp */
-    timestamp: Date; /** Source resource */
-    resource?: string; /** Resource ID */
-    resourceId?: string; /** User who triggered the event */
-    userId?: string; /** Organization context */
-    organizationId?: string; /** Correlation ID for tracing */
-    correlationId?: string;
-  };
-}
-type EventHandler<T = unknown> = (event: DomainEvent<T>) => void | Promise<void>;
-/**
- * Minimal logger interface for event transports.
- * Compatible with `console`, `pino`, `fastify.log`, and any custom logger.
- *
- * @example
- * ```typescript
- * // Use Fastify's logger
- * new MemoryEventTransport({ logger: fastify.log });
- *
- * // Use a custom logger
- * new MemoryEventTransport({ logger: { warn: myWarn, error: myError } });
- *
- * // Default: console (no logger option needed)
- * new MemoryEventTransport();
- * ```
- */
-interface EventLogger {
-  warn(message: string, ...args: unknown[]): void;
-  error(message: string, ...args: unknown[]): void;
-}
-interface EventTransport {
-  /** Transport name for logging */
-  readonly name: string;
-  /**
-   * Publish an event to the transport
-   */
-  publish(event: DomainEvent): Promise<void>;
-  /**
-   * Publish a batch of events to the transport (optional, v2.8.1+).
-   *
-   * Transports that can efficiently batch (Kafka producer, Redis pipeline,
-   * RabbitMQ publisher confirms, SQS send-message-batch) should implement
-   * this. {@link import('./outbox.js').EventOutbox.relay} auto-detects and
-   * uses it for much higher throughput than per-event publishing.
-   *
-   * **Contract**: the returned `PublishManyResult` must describe the
-   * per-event outcome so the caller can acknowledge successes and fail the
-   * rest. Partial success is allowed — the transport reports it per event.
-   *
-   * If not implemented, `EventOutbox.relay` falls back to calling
-   * {@link publish} once per event.
-   *
-   * @param events - Events to publish (in order)
-   * @returns Per-event outcome map keyed by `event.meta.id`
-   */
-  publishMany?(events: readonly DomainEvent[]): Promise<PublishManyResult>;
-  /**
-   * Subscribe to events matching a pattern
-   * @param pattern - Event type pattern (e.g., 'product.*', '*')
-   * @param handler - Handler function
-   * @returns Unsubscribe function
-   */
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  /**
-   * Close transport connections
-   */
-  close?(): Promise<void>;
-}
-/**
- * Per-event outcome returned by {@link EventTransport.publishMany}.
- *
- * The key is `event.meta.id`; the value is `null` for success or an `Error`
- * for per-event failure. Transports MUST include an entry for every event
- * in the input batch.
- */
-type PublishManyResult = ReadonlyMap<string, Error | null>;
-interface MemoryEventTransportOptions {
-  /** Logger for error/warning messages (default: console) */
-  logger?: EventLogger;
-}
-/**
- * In-memory event transport (default)
- * Events are delivered synchronously within the process.
- * Not suitable for multi-instance deployments.
- */
-declare class MemoryEventTransport implements EventTransport {
-  readonly name = "memory";
-  private handlers;
-  private logger;
-  constructor(options?: MemoryEventTransportOptions);
-  publish(event: DomainEvent): Promise<void>;
-  /**
-   * Reference `publishMany` implementation — delegates to `publish()` in order.
-   *
-   * Production transports (Kafka, Redis pipeline, SQS batch) should override
-   * this with a single batched network call. Memory transport has nothing to
-   * batch, so we just loop — the loop still returns a proper result map so
-   * `EventOutbox.relay` can exercise the batched code path in tests.
-   */
-  publishMany(events: readonly DomainEvent[]): Promise<PublishManyResult>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
-}
-/**
- * Create a domain event with auto-generated metadata
- */
-declare function createEvent<T>(type: string, payload: T, meta?: Partial<DomainEvent["meta"]>): DomainEvent<T>;
-//#endregion
-export { MemoryEventTransport as a, createEvent as c, EventTransport as i, EventHandler as n, MemoryEventTransportOptions as o, EventLogger as r, PublishManyResult as s, DomainEvent as t };

package/dist/audit/mongodb.d.mts

@@ -1,2 +0,0 @@
-import { n as MongoAuditStoreOptions, t as MongoAuditStore } from "../mongodb-B8U2xaLj.mjs";
-export { MongoAuditStore, type MongoAuditStoreOptions };

package/dist/audit/mongodb.mjs

@@ -1,2 +0,0 @@
-import { t as MongoAuditStore } from "../mongodb-B5O6xaW1.mjs";
-export { MongoAuditStore };

package/dist/idempotency/mongodb.d.mts

@@ -1,2 +0,0 @@
-import { n as MongoIdempotencyStoreOptions, t as MongoIdempotencyStore } from "../mongodb-X7LbEjTN.mjs";
-export { MongoIdempotencyStore, type MongoIdempotencyStoreOptions };

package/dist/idempotency/mongodb.mjs

@@ -1,123 +0,0 @@
-//#region src/idempotency/stores/mongodb.ts
-var MongoIdempotencyStore = class {
-	name = "mongodb";
-	connection;
-	collectionName;
-	ttlMs;
-	indexCreated = false;
-	shouldEnsureIndex;
-	logger;
-	constructor(options) {
-		this.connection = options.connection;
-		this.collectionName = options.collection ?? "arc_idempotency";
-		this.ttlMs = options.ttlMs ?? 864e5;
-		this.shouldEnsureIndex = options.createIndex !== false;
-		this.logger = options.logger ?? console;
-		if (this.shouldEnsureIndex) this.ensureIndex().catch(() => {});
-	}
-	get collection() {
-		return this.connection.db.collection(this.collectionName);
-	}
-	async ensureIndex() {
-		if (this.indexCreated) return;
-		try {
-			await this.collection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
-			this.indexCreated = true;
-		} catch (err) {
-			const code = err?.code;
-			if (code === 85 || code === 86) {
-				this.indexCreated = true;
-				return;
-			}
-			this.logger.warn(`[MongoIdempotencyStore] TTL index creation failed (will retry on next write): ${err.message ?? err}`);
-		}
-	}
-	async get(key) {
-		const doc = await this.collection.findOne({ _id: key });
-		if (!doc?.result) return void 0;
-		if (new Date(doc.expiresAt) < /* @__PURE__ */ new Date()) return;
-		return {
-			key,
-			statusCode: doc.result.statusCode,
-			headers: doc.result.headers,
-			body: doc.result.body,
-			createdAt: new Date(doc.createdAt),
-			expiresAt: new Date(doc.expiresAt)
-		};
-	}
-	async set(key, result) {
-		if (this.shouldEnsureIndex && !this.indexCreated) await this.ensureIndex().catch(() => {});
-		await this.collection.updateOne({ _id: key }, {
-			$set: {
-				result: {
-					statusCode: result.statusCode,
-					headers: result.headers,
-					body: result.body
-				},
-				createdAt: result.createdAt,
-				expiresAt: result.expiresAt
-			},
-			$unset: { lock: "" }
-		}, { upsert: true });
-	}
-	async tryLock(key, requestId, ttlMs) {
-		if (this.shouldEnsureIndex && !this.indexCreated) await this.ensureIndex().catch(() => {});
-		const now = /* @__PURE__ */ new Date();
-		const expiresAt = new Date(now.getTime() + ttlMs);
-		try {
-			const result = await this.collection.updateOne({
-				_id: key,
-				$or: [{ lock: { $exists: false } }, { "lock.expiresAt": { $lt: now } }]
-			}, {
-				$set: { lock: {
-					requestId,
-					expiresAt
-				} },
-				$setOnInsert: {
-					createdAt: now,
-					expiresAt: new Date(now.getTime() + this.ttlMs)
-				}
-			}, { upsert: true });
-			return result.matchedCount === 1 || (result.upsertedCount ?? 0) === 1;
-		} catch (err) {
-			if (err?.code === 11e3) return false;
-			throw err;
-		}
-	}
-	async unlock(key, requestId) {
-		await this.collection.updateOne({
-			_id: key,
-			"lock.requestId": requestId
-		}, { $unset: { lock: "" } });
-	}
-	async isLocked(key) {
-		const doc = await this.collection.findOne({ _id: key });
-		if (!doc?.lock) return false;
-		return new Date(doc.lock.expiresAt) > /* @__PURE__ */ new Date();
-	}
-	async delete(key) {
-		await this.collection.deleteOne({ _id: key });
-	}
-	async deleteByPrefix(prefix) {
-		return (await this.collection.deleteMany({ _id: { $regex: `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}` } })).deletedCount;
-	}
-	async findByPrefix(prefix) {
-		const doc = await this.collection.findOne({
-			_id: { $regex: `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}` },
-			result: { $exists: true },
-			expiresAt: { $gt: /* @__PURE__ */ new Date() }
-		});
-		if (!doc?.result) return void 0;
-		return {
-			key: doc._id,
-			statusCode: doc.result.statusCode,
-			headers: doc.result.headers,
-			body: doc.result.body,
-			createdAt: new Date(doc.createdAt),
-			expiresAt: new Date(doc.expiresAt)
-		};
-	}
-	async close() {}
-};
-//#endregion
-export { MongoIdempotencyStore };

package/dist/mongodb-B5O6xaW1.mjs

@@ -1,90 +0,0 @@
-//#region src/audit/stores/mongodb.ts
-var MongoAuditStore = class {
-	name = "mongodb";
-	collection;
-	initialized = false;
-	ttlDays;
-	constructor(options) {
-		const collectionName = options.collection ?? "audit_logs";
-		this.collection = options.connection.collection(collectionName);
-		this.ttlDays = options.ttlDays ?? 90;
-	}
-	async ensureIndexes() {
-		if (this.initialized) return;
-		try {
-			await this.collection.createIndex({
-				resource: 1,
-				documentId: 1,
-				timestamp: -1
-			});
-			await this.collection.createIndex({
-				userId: 1,
-				timestamp: -1
-			});
-			await this.collection.createIndex({
-				organizationId: 1,
-				timestamp: -1
-			});
-			if (this.ttlDays > 0) await this.collection.createIndex({ timestamp: 1 }, { expireAfterSeconds: this.ttlDays * 24 * 60 * 60 });
-			this.initialized = true;
-		} catch {
-			this.initialized = true;
-		}
-	}
-	async log(entry) {
-		await this.ensureIndexes();
-		await this.collection.insertOne({
-			_id: entry.id,
-			resource: entry.resource,
-			documentId: entry.documentId,
-			action: entry.action,
-			userId: entry.userId,
-			organizationId: entry.organizationId,
-			before: entry.before,
-			after: entry.after,
-			changes: entry.changes,
-			requestId: entry.requestId,
-			ipAddress: entry.ipAddress,
-			userAgent: entry.userAgent,
-			metadata: entry.metadata,
-			timestamp: entry.timestamp
-		});
-	}
-	async query(options = {}) {
-		await this.ensureIndexes();
-		const query = {};
-		if (options.resource) query.resource = options.resource;
-		if (options.documentId) query.documentId = options.documentId;
-		if (options.userId) query.userId = options.userId;
-		if (options.organizationId) query.organizationId = options.organizationId;
-		if (options.action) {
-			const actions = Array.isArray(options.action) ? options.action : [options.action];
-			query.action = actions.length === 1 ? actions[0] : { $in: actions };
-		}
-		if (options.from || options.to) {
-			query.timestamp = {};
-			if (options.from) query.timestamp.$gte = options.from;
-			if (options.to) query.timestamp.$lte = options.to;
-		}
-		const offset = options.offset ?? 0;
-		const limit = options.limit ?? 100;
-		return (await this.collection.find(query).sort({ timestamp: -1 }).skip(offset).limit(limit).toArray()).map((doc) => ({
-			id: String(doc._id),
-			resource: doc.resource,
-			documentId: doc.documentId,
-			action: doc.action,
-			userId: doc.userId,
-			organizationId: doc.organizationId,
-			before: doc.before,
-			after: doc.after,
-			changes: doc.changes,
-			requestId: doc.requestId,
-			ipAddress: doc.ipAddress,
-			userAgent: doc.userAgent,
-			metadata: doc.metadata,
-			timestamp: doc.timestamp
-		}));
-	}
-};
-//#endregion
-export { MongoAuditStore as t };