@classytic/arc 2.20.0 → 2.22.0

package/dist/discovery/index.d.mts

@@ -1,5 +1,4 @@
 import { FastifyPluginAsync } from "fastify";
-
 //#region src/discovery/index.d.ts
 /** A discovered resource — must have toPlugin() method */
 interface DiscoverableResource {

package/dist/docs/index.d.mts

@@ -1,7 +1,6 @@
-import { p as RegistryEntry } from "../index-_--GyzcO.mjs";
+import { p as RegistryEntry } from "../index-DbtgCOCj.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BE6wFpYv.mjs";
 import { FastifyPluginAsync } from "fastify";
-
 //#region src/docs/openapi/types.d.ts
 /**
  * OpenAPI 3.0 type primitives used by arc's spec emitter.

package/dist/docs/index.mjs

@@ -1,5 +1,5 @@
 import { t as getUserRoles } from "../types-XTApa8b6.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-Dq6RbEGK.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-BRpMZD7C.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/{elevation-xGUBq6p_.d.mts → elevation-C9s5hFP_.d.mts}

@@ -1,5 +1,4 @@
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
-
 //#region src/scope/elevation.d.ts
 interface ElevationOptions {
   /** Roles that can use elevation (default: ['superadmin']) */

package/dist/encryption/index.d.mts

@@ -1,135 +1,5 @@
-import { FastifyPluginAsync, FastifyRequest } from "fastify";
-
-//#region src/encryption/types.d.ts
-/** JWE key-management algorithm — the protected-header `alg`. */
-type JweAlg = "RSA-OAEP-256" | "RSA-OAEP-384" | "RSA-OAEP-512" | "ECDH-ES" | "ECDH-ES+A256KW" | "A256GCMKW" | "dir";
-/** JWE content-encryption algorithm — the protected-header `enc`. AEAD only. */
-type JweEnc = "A128GCM" | "A192GCM" | "A256GCM";
-/** Encryption strategy for a route's response. */
-type EncryptionMode = "jwe" | "fields";
-/**
- * Opaque key material. For `jwe` mode this is a `jose` `KeyLike` /
- * `CryptoKey` / `Uint8Array`; for `fields` mode a 32-byte secret
- * (`Buffer` / `Uint8Array`). Kept `unknown` at the contract layer so the
- * `KeyProvider` interface carries no hard `jose` type dependency — hosts
- * without `jose` installed can still implement field-mode providers.
- */
-type KeyMaterial = unknown;
-/** A key paired with its identifier — what encrypt operations consume. */
-interface ActiveKey {
-  /** Key id, stamped into the JWE `kid` header / field envelope for rotation. */
-  readonly kid: string;
-  /** The key material (public key for JWE, 32-byte secret for fields). */
-  readonly key: KeyMaterial;
-  /** Optional per-key `alg` override (else the plugin default applies). */
-  readonly alg?: JweAlg;
-}
-/** Context handed to the key provider so resolution can be request-scoped. */
-interface KeyContext {
-  readonly request: FastifyRequest;
-}
-type MaybePromise<T> = T | Promise<T>;
-/**
- * Pluggable key resolution. Arc owns the request-time plumbing — `kid` →
- * key, algorithm allowlist enforcement; the host owns the trust store —
- * which keys are valid and where they live (file / env / AWS KMS / GCP KMS
- * / Vault). Encryption and decryption are deliberately separate operations
- * because they often use DIFFERENT keys (JWE: a public key encrypts the
- * outbound response, a private key by `kid` decrypts the inbound request —
- * exactly Visa's two-key-pair model).
- *
- * Rotation mirrors `@fastify/secure-session`: the active key encrypts; any
- * key resolvable by `kid` can decrypt, so you can roll keys without dropping
- * in-flight traffic.
- */
-interface KeyProvider {
-  /** Active key for encrypting OUTBOUND responses. */
-  encryptionKey(ctx: KeyContext): MaybePromise<ActiveKey>;
-  /** Resolve a DECRYPTION key by the inbound message's `kid`. */
-  decryptionKey(kid: string, ctx: KeyContext): MaybePromise<KeyMaterial | undefined>;
-}
-/**
- * Per-resource encryption directive — the typed slice plugins register on
- * `ResourceExtensions`. Declared on a resource via
- * `defineResource({ extensions: { encryption: { … } } })`; arc threads it
- * to request time on `request.routeOptions.config.arcExtensions.encryption`.
- */
-interface EncryptionDirective {
-  /** Strategy. Defaults to the plugin-level `mode` (default `'jwe'`). */
-  readonly mode?: EncryptionMode;
-  /**
-   * For `mode: 'fields'` — dot-paths of fields to encrypt, resolved against
-   * the serialized response body (e.g. `'cardNumber'`, `'account.iban'`).
-   * Ignored for `mode: 'jwe'` (the whole body is encrypted).
-   */
-  readonly fields?: readonly string[];
-  /**
-   * Explicit opt-out — set `false` to disable encryption for this resource
-   * even when a plugin-level default (`routes`) would otherwise apply.
-   */
-  readonly enabled?: boolean;
-}
-/**
- * Plugin-level options. `keyProvider` is the only required field; everything
- * else has a secure default.
- */
-interface EncryptionOptions {
-  /**
-   * Master on/off. Default `true`. Set `false` to register the plugin as a
-   * typed no-op (config-gated environments) — same pattern as
-   * `idempotencyPlugin`.
-   */
-  readonly enabled?: boolean;
-  /** Key provider — resolves `kid` → key for encrypt/decrypt. Required. */
-  readonly keyProvider: KeyProvider;
-  /** Default mode when a route opts in without naming one. Default `'jwe'`. */
-  readonly mode?: EncryptionMode;
-  /** JWE key-management algorithm. Default `'RSA-OAEP-256'`. */
-  readonly alg?: JweAlg;
-  /** JWE content-encryption algorithm. Default `'A256GCM'`. */
-  readonly enc?: JweEnc;
-  /**
-   * Inbound-decryption algorithm allowlists — block algorithm-substitution
-   * downgrade attacks. Default `[alg]` / `[enc]`. Set explicitly only when a
-   * client legitimately uses more than one algorithm.
-   */
-  readonly allowedAlgs?: readonly JweAlg[];
-  readonly allowedEncs?: readonly JweEnc[];
-  /**
-   * Fallback opt-in for routes that don't declare
-   * `extensions.encryption`. Return a directive (or `true` for the default
-   * mode) to encrypt, `false`/`undefined` to skip. The per-resource
-   * `extensions.encryption` ALWAYS wins when present. Use this to scope ALE
-   * to sensitive prefixes without touching every resource.
-   *
-   * @example confine ALE to `/payments` and `/accounts`
-   * ```ts
-   * routes: (req) => /^\/(payments|accounts)\b/.test(req.url)
-   * ```
-   */
-  readonly routes?: (request: FastifyRequest) => EncryptionDirective | boolean | undefined;
-  /** Decrypt inbound `application/jose` request bodies. Default `true`. */
-  readonly decryptRequests?: boolean;
-  /** Media type that signals an encrypted REQUEST body. Default `'application/jose'`. */
-  readonly contentType?: string;
-  /** Content-Type set on full-body JWE RESPONSES. Default `'application/jose'`. */
-  readonly responseContentType?: string;
-  /**
-   * Response header advertising that the body is encrypted, so generic
-   * client SDKs know to decrypt. Default `'x-encrypted'`; set `false` to omit.
-   */
-  readonly flagHeader?: string | false;
-}
-/** Request decorations added by the plugin. */
-declare module "fastify" {
-  interface FastifyRequest {
-    /** `true` when the inbound body was decrypted from a JWE by this plugin. */
-    requestDecrypted?: boolean;
-    /** `true` when the outbound body was encrypted by this plugin. */
-    responseEncrypted?: boolean;
-  }
-}
-//#endregion
+import { a as JweAlg, c as KeyMaterial, i as EncryptionOptions, l as KeyProvider, n as EncryptionDirective, o as JweEnc, r as EncryptionMode, s as KeyContext, t as ActiveKey } from "../types-Cc91nXuA.mjs";
+import { FastifyPluginAsync } from "fastify";
 //#region src/encryption/encryptionPlugin.d.ts
 declare const encryptionPlugin: FastifyPluginAsync<EncryptionOptions>;
 declare const _default: FastifyPluginAsync<EncryptionOptions>;
@@ -207,16 +77,4 @@ interface StaticKeyProviderOptions {
  */
 declare function createStaticKeyProvider(options: StaticKeyProviderOptions): KeyProvider;
 //#endregion
-//#region src/encryption/index.d.ts
-declare module "../types/resource.js" {
-  interface ResourceExtensions {
-    /**
-     * Encrypt this resource's responses — full-body JWE or specific fields.
-     * Threaded to request time on
-     * `request.routeOptions.config.arcExtensions.encryption`.
-     */
-    encryption?: EncryptionDirective;
-  }
-}
-//#endregion
 export { type ActiveKey, type EncryptionDirective, type EncryptionMode, type EncryptionOptions, type JweAlg, type JweEnc, type KeyContext, type KeyMaterial, type KeyProvider, type ParsedFieldEnvelope, type StaticKeyProviderOptions, createStaticKeyProvider, decryptField, _default as default, encryptField, encryptionPlugin, parseFieldEnvelope };

package/dist/encryption/index.mjs

@@ -1,3 +1,5 @@
+import { t as ArcError } from "../errors-DkO8Nk6-.mjs";
+import { t as parseJsonBody } from "../jsonBody-BlzAoGCe.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/encryption/fieldCipher.ts
@@ -182,17 +184,19 @@ const encryptionPlugin = async (fastify, opts) => {
 	}
 	if (decryptRequests) fastify.addContentTypeParser(contentType, { parseAs: "string" }, async (request, body) => {
 		const provider = keyProvider;
-		const plaintext = await jweDecrypt(body, (kid) => provider.decryptionKey(kid, { request }), allowedAlgs, allowedEncs);
-		request.requestDecrypted = true;
-		if (plaintext.length === 0) return void 0;
+		let plaintext;
 		try {
-			return JSON.parse(plaintext);
+			plaintext = await jweDecrypt(body, (kid) => provider.decryptionKey(kid, { request }), allowedAlgs, allowedEncs);
 		} catch (cause) {
-			throw Object.assign(/* @__PURE__ */ new Error("[arc/encryption] decrypted request body is not valid JSON"), {
+			throw new ArcError("Invalid encrypted request body", {
+				code: "arc.bad_request",
 				statusCode: 400,
 				cause
 			});
 		}
+		request.requestDecrypted = true;
+		if (plaintext.length === 0) return void 0;
+		return parseJsonBody(plaintext, "Decrypted request body is not valid JSON");
 	});
 	fastify.addHook("preSerialization", async (request, reply, payload) => {
 		const directive = resolveDirective(request, defaultMode, fallback);

package/dist/{errorHandler-Dxf6P_kV.mjs → errorHandler-BTzXSwIg.mjs}

@@ -91,7 +91,7 @@ function mongooseValidationDetails(errors) {
 }
 async function errorHandlerPluginFn(fastify, options = {}) {
 	const isProduction = process.env.NODE_ENV === "production";
-	const { includeStack = !isProduction, onError, errorMap = {}, errorMappers = [], isDuplicateKeyError = defaultIsDuplicateKeyError } = options;
+	const { includeStack = !isProduction, exposeInternalMessages = !isProduction, onError, errorMap = {}, errorMappers = [], isDuplicateKeyError = defaultIsDuplicateKeyError } = options;
 	fastify.setErrorHandler(async (error, request, reply) => {
 		if (onError) try {
 			await onError(error, request);
@@ -112,6 +112,7 @@ async function errorHandlerPluginFn(fastify, options = {}) {
 			...Object.keys(meta).length > 0 ? { meta } : {}
 		};
 		const status = wire.status ?? 500;
+		if (status >= 500 && wire.code === "arc.internal_error" && !exposeInternalMessages) wire.message = "Internal Server Error";
 		if (status >= 500) request.log.error({
 			err: error,
 			status
@@ -120,11 +121,31 @@ async function errorHandlerPluginFn(fastify, options = {}) {
 			err: error,
 			status
 		}, "Client error");
-		if (isArcError(error) && error.cause) request.log.error({ cause: error.cause }, "Error cause chain");
+		if (isArcError(error) && error.cause) {
+			const causeLevel = status >= 500 ? "error" : "warn";
+			request.log[causeLevel]({ cause: error.cause }, "Error cause chain");
+		}
 		return reply.status(status).send(wire);
 	});
 }
 /**
+* Is `code` a caller-defined DOMAIN error code that is safe to surface on the
+* wire, as opposed to a framework/runtime code that must never leak?
+*
+* Rejects Fastify internals (`FST_*`) and Node system errnos (`ECONNREFUSED`,
+* `ENOENT`, …). Domain codes in the wild use separators (`PURCHASE_NOT_FOUND`,
+* `access.forbidden`) so they pass; a bare all-caps single word that collides
+* with the Node-errno shape (e.g. `EXPIRED`) is conservatively treated as a
+* runtime code — use a separatored code (`TOKEN_EXPIRED`) to surface it, or
+* throw via `createDomainError` which bypasses this heuristic entirely.
+*/
+function isDomainErrorCode(code) {
+	if (typeof code !== "string" || code.length === 0) return false;
+	if (code.startsWith("FST_")) return false;
+	if (/^E[A-Z]{2,}$/.test(code)) return false;
+	return true;
+}
+/**
 * Single-pass error → `ErrorContract` classifier. Dispatch order is fixed:
 *
 *   1. Class-based mappers (`instanceof`) — user-registered domain errors
@@ -167,7 +188,7 @@ function classify(error, ctx) {
 		};
 	}
 	if (typeof fastifyErr.statusCode === "number") return {
-		code: statusToArcCode(fastifyErr.statusCode),
+		code: (isDomainErrorCode(fastifyErr.code) ? fastifyErr.code : void 0) ?? statusToArcCode(fastifyErr.statusCode),
 		message: error.message || "Error",
 		status: fastifyErr.statusCode
 	};

package/dist/{errorHandler-BtUUDPEa.d.mts → errorHandler-C6yv4ZTW.d.mts}

@@ -1,6 +1,5 @@
 import { ErrorDetail } from "@classytic/repo-core/errors";
 import { FastifyInstance, FastifyRequest } from "fastify";
-
 //#region src/plugins/errorHandler.d.ts
 /**
  * Class-based error mapper — `instanceof` check converts a thrown class
@@ -19,6 +18,19 @@ interface ErrorMapper<T extends Error = Error> {
 interface ErrorHandlerOptions {
   /** Include `meta.stack` on the wire (defaults to `NODE_ENV !== 'production'`). */
   includeStack?: boolean;
+  /**
+   * Ship the raw `error.message` of UNCLASSIFIED 500s on the wire
+   * (defaults to `NODE_ENV !== 'production'`).
+   *
+   * Only the `arc.internal_error` fallback is affected — an unclassified
+   * throw carries whatever some driver/library put in the message (connection
+   * strings, file paths, SQL fragments), which must not reach clients in
+   * production. Deliberate 5xx contracts are untouched: `ArcError` /
+   * domain-coded throws (`payment.gateway.timeout`, …) keep their message
+   * because the thrower chose it for the client. The raw message is always
+   * logged via `request.log.error({ err })` regardless of this flag.
+   */
+  exposeInternalMessages?: boolean;
   /** Custom callback fired for every error — log to Sentry / Datadog / etc. */
   onError?: (error: Error, request: FastifyRequest) => void | Promise<void>;
   /** Map by `error.name` string. Lower priority than `errorMappers`. */

package/dist/{errors-DOHkjQlD.d.mts → errors-DHcHVAgk.d.mts}

@@ -1,5 +1,4 @@
 import { HttpError } from "@classytic/repo-core/errors";
-
 //#region src/utils/errors.d.ts
 interface ErrorOptions {
   code?: string;

package/dist/{eventPlugin-DbBFd3x_.d.mts → eventPlugin-A6EbthXR.d.mts}

@@ -1,6 +1,5 @@
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-IEn7Tn-Q.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-QmY7A258.mjs";
 import { FastifyPluginAsync } from "fastify";
-
 //#region src/events/defineEvent.d.ts
 interface EventSchema {
   type: "object";
@@ -249,7 +248,8 @@ interface EventPluginOptions {
    * failed events are published to the `$deadLetter` event type by default.
    */
   deadLetterQueue?: {
-    /** Custom store function. If omitted, publishes to '$deadLetter' event type. */store?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
+    /** Custom store function. If omitted, publishes to '$deadLetter' event type. */
+    store?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
   };
   /** Callback after successful publish (for metrics/tracking) */
   onPublish?: (event: DomainEvent) => void;
@@ -302,9 +302,13 @@ interface EventPluginOptions {
 declare module "fastify" {
   interface FastifyInstance {
     events: {
-      /** Publish an event */publish: <T>(type: string, payload: T, meta?: Partial<DomainEvent["meta"]>) => Promise<void>; /** Subscribe to events */
-      subscribe: (pattern: string, handler: EventHandler) => Promise<() => void>; /** Get transport name */
-      transportName: string; /** Event registry for introspection (undefined when no registry configured) */
+      /** Publish an event */
+      publish: <T>(type: string, payload: T, meta?: Partial<DomainEvent["meta"]>) => Promise<void>;
+      /** Subscribe to events */
+      subscribe: (pattern: string, handler: EventHandler) => Promise<() => void>;
+      /** Get transport name */
+      transportName: string;
+      /** Event registry for introspection (undefined when no registry configured) */
       registry?: EventRegistry;
     };
   }

package/dist/events/index.d.mts

@@ -1,9 +1,8 @@
-import { a as EventTransport, i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions, t as DeadLetteredEvent } from "../EventTransport-IEn7Tn-Q.mjs";
-import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-DbBFd3x_.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions, t as DeadLetteredEvent } from "../EventTransport-QmY7A258.mjs";
+import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-A6EbthXR.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-DsP1vqZB.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-iVR2l7aS.mjs";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
-
 //#region src/events/eventTypes.d.ts
 /**
  * Event Type Constants and Helpers
@@ -38,14 +37,18 @@ type CrudEventSuffix = (typeof CRUD_EVENT_SUFFIXES)[number];
 declare function crudEventType(resource: string, suffix: CrudEventSuffix): string;
 /** Arc framework lifecycle events — emitted automatically by the framework */
 declare const ARC_LIFECYCLE_EVENTS: Readonly<{
-  /** Emitted when a resource plugin is registered */readonly RESOURCE_REGISTERED: "arc.resource.registered"; /** Emitted when Arc is fully ready (all resources registered, onReady fired) */
+  /** Emitted when a resource plugin is registered */
+  readonly RESOURCE_REGISTERED: "arc.resource.registered";
+  /** Emitted when Arc is fully ready (all resources registered, onReady fired) */
   readonly READY: "arc.ready";
 }>;
 /** Type for Arc lifecycle event names */
 type ArcLifecycleEvent = (typeof ARC_LIFECYCLE_EVENTS)[keyof typeof ARC_LIFECYCLE_EVENTS];
 /** Cache-specific event types for observability and external triggers */
 declare const CACHE_EVENTS: Readonly<{
-  /** Emitted when a resource's cache version is bumped */readonly VERSION_BUMPED: "arc.cache.version.bumped"; /** Emitted when a tag version is bumped */
+  /** Emitted when a resource's cache version is bumped */
+  readonly VERSION_BUMPED: "arc.cache.version.bumped";
+  /** Emitted when a tag version is bumped */
   readonly TAG_VERSION_BUMPED: "arc.cache.tag.bumped";
 }>;
 /** Type for cache event names */

package/dist/events/transports/redis-stream-entry.d.mts

@@ -1,2 +1,2 @@
-import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-DsP1vqZB.mjs";
+import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-iVR2l7aS.mjs";
 export { type RedisStreamLike, RedisStreamTransport, type RedisStreamTransportOptions };

package/dist/events/transports/redis.d.mts

@@ -1,5 +1,4 @@
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-IEn7Tn-Q.mjs";
-
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-QmY7A258.mjs";
 //#region src/events/transports/redis.d.ts
 interface RedisLike {
   publish(channel: string, message: string): Promise<number>;

package/dist/factory/index.d.mts

@@ -1,14 +1,15 @@
-import { a as getModuleExports, c as LoadResourcesOptions, d as loadResources, i as defineModule, l as ResourceLike, n as ArcModuleInput, o as orderModules, r as ArcModuleRegistry, s as resolveModule, t as ArcModule, u as ResourceModule } from "../module-JYH9V0I8.mjs";
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as preloadResourcesAsync, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as preloadResources } from "../types-BHMKlMBU.mjs";
+import { a as getModuleExports, c as LoadResourcesOptions, d as loadResources, i as defineModule, l as ResourceLike, n as ArcModuleInput, o as orderModules, r as ArcModuleRegistry, s as resolveModule, t as ArcModule, u as ResourceModule } from "../module-B4u10iOJ.mjs";
+import "../fastify-augmentation-9_fuetB4.mjs";
+import { a as AuthOption, c as CustomPluginAuthOption, d as preloadResourcesAsync, i as UnderPressureOptions, l as JwtAuthOption, n as MultipartOptions, o as BetterAuthOption, r as RawBodyOptions, s as CustomAuthenticatorOption, t as CreateAppOptions, u as preloadResources } from "../index-BEu4wjbL.mjs";
+import { g as HealthCheck } from "../versioning-DLwklPlG.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
-
 //#region src/factory/createApp.d.ts
 /**
  * Create a production-ready Fastify application with Arc framework.
  *
  * Boot order:
  * ```
- * 0. Logger, validation, preset merge
+ * 0. Logger, validation → beforeBoot() (DB connect etc.), preset merge
  * 1. Create Fastify instance
  * 2. Security plugins (Helmet, CORS, Rate Limit) — opt-out
  * 3. Utility plugins (Under Pressure, Sensible, Multipart, Raw Body)
@@ -32,6 +33,29 @@ declare const ArcFactory: {
   testing(options: Omit<CreateAppOptions, "preset">): Promise<FastifyInstance>;
 };
 //#endregion
+//#region src/factory/createWorker.d.ts
+interface WorkerHealthOptions {
+  /** Port for the worker's ONLY listener (liveness/readiness probes). */
+  port: number;
+  /** Bind host. Default `0.0.0.0`. */
+  host?: string;
+  /** Readiness checks — same contract as the API role's healthPlugin. */
+  checks?: HealthCheck[];
+}
+interface CreateWorkerOptions {
+  /** Opt-in probe listener. Omit = the worker binds NOTHING. */
+  health?: WorkerHealthOptions;
+}
+interface ArcWorker {
+  /** The underlying Fastify instance (decorations, inject, logs). */
+  app: FastifyInstance;
+  /** Typed module-export accessor — same contract as `getModuleExports`. */
+  exports<TExports = unknown>(name: string): TExports;
+  /** Close app → module onClose (reverse) → app onClose. Idempotent. */
+  close(): Promise<void>;
+}
+declare function createWorker(options: CreateAppOptions, workerOptions?: CreateWorkerOptions): Promise<ArcWorker>;
+//#endregion
 //#region src/factory/edge.d.ts
 interface FetchHandlerOptions {
   /**
@@ -91,9 +115,6 @@ declare const testingPreset: Partial<CreateAppOptions>;
  * when using `toFetchHandler()` (routes through Fastify's `.inject()`).
  */
 declare const edgePreset: Partial<CreateAppOptions>;
-/**
- * Get preset by name
- */
-declare function getPreset(name: "production" | "development" | "testing" | "edge"): Partial<CreateAppOptions>;
+declare function getPreset(name: "production" | "development" | "testing" | "edge" | "worker"): Partial<CreateAppOptions>;
 //#endregion
-export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, createApp, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };
+export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type ArcWorker, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CreateWorkerOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, type WorkerHealthOptions, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };

package/dist/factory/index.mjs

@@ -1,6 +1,37 @@
-import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-CHw3_oA_.mjs";
-import { a as getModuleExports, c as developmentPreset, d as productionPreset, f as testingPreset, i as defineModule, l as edgePreset, n as createApp, o as orderModules, s as resolveModule, t as ArcFactory, u as getPreset } from "../createApp-D6uwzCKu.mjs";
-import { t as loadResources } from "../loadResources-B8UmpITt.mjs";
+import { a as edgePreset, c as testingPreset, d as getModuleExports, f as orderModules, h as preloadResourcesAsync, i as developmentPreset, l as workerPreset, m as preloadResources, n as createApp, o as getPreset, p as resolveModule, s as productionPreset, t as ArcFactory, u as defineModule } from "../createApp-Ci7yG5gv.mjs";
+import { t as healthPlugin } from "../health-ScyjIVo5.mjs";
+import { t as loadResources } from "../loadResources-DpU8pfjV.mjs";
+//#region src/factory/createWorker.ts
+async function createWorker(options, workerOptions = {}) {
+	const { auth: _auth, helmet: _helmet, cors: _cors, rateLimit: _rateLimit, multipart: _multipart, rawBody: _rawBody, sensible: _sensible, underPressure: _underPressure, replyHelpers: _replyHelpers, ...runtimeOptions } = options;
+	const app = await createApp({
+		...runtimeOptions,
+		preset: "worker",
+		...runtimeOptions.arcPlugins ? { arcPlugins: {
+			...workerPreset.arcPlugins,
+			...runtimeOptions.arcPlugins
+		} } : {}
+	});
+	if (workerOptions.health) {
+		const { port, host = "0.0.0.0", checks = [] } = workerOptions.health;
+		await app.register(healthPlugin, { checks });
+		await app.listen({
+			port,
+			host
+		});
+	} else await app.ready();
+	let closed = false;
+	return {
+		app,
+		exports: (name) => getModuleExports(app, name),
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			await app.close();
+		}
+	};
+}
+//#endregion
 //#region src/factory/edge.ts
 /**
 * Convert a Fastify app into a Web Standards fetch handler.
@@ -47,4 +78,4 @@ function toFetchHandler(app, options = {}) {
 	};
 }
 //#endregion
-export { ArcFactory, createApp, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };
+export { ArcFactory, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };

package/dist/{fastify-augmentation-CCQJEDgh.d.mts → fastify-augmentation-9_fuetB4.d.mts}

@@ -1,8 +1,7 @@
-import { bn as HookSystem, z as ResourceRegistry } from "./index-_--GyzcO.mjs";
+import { bn as HookSystem, z as ResourceRegistry } from "./index-DbtgCOCj.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
-import { r as ArcModuleRegistry } from "./module-JYH9V0I8.mjs";
+import { r as ArcModuleRegistry } from "./module-B4u10iOJ.mjs";
 import { FastifyPluginAsync } from "fastify";
-
 //#region src/core/arcCorePlugin.d.ts
 interface ArcCorePluginOptions {
   /** Enable event emission for CRUD operations (requires eventPlugin) */

package/dist/fields-D3lhgzhD.d.mts

@@ -0,0 +1,121 @@
+//#region src/permissions/fields.d.ts
+/**
+ * Field-Level Permissions
+ *
+ * Control field visibility and writability per role.
+ * Integrated into the response path (read) and sanitization path (write).
+ *
+ * @example
+ * ```typescript
+ * import { fields, defineResource } from '@classytic/arc';
+ *
+ * const userResource = defineResource({
+ *   name: 'user',
+ *   adapter: userAdapter,
+ *   fields: {
+ *     salary: fields.visibleTo(['admin', 'hr']),
+ *     internalNotes: fields.writableBy(['admin']),
+ *     email: fields.redactFor(['viewer']),
+ *     password: fields.hidden(),
+ *   },
+ * });
+ * ```
+ */
+type FieldPermissionType = "hidden" | "visibleTo" | "writableBy" | "redactFor";
+interface FieldPermission {
+  readonly _type: FieldPermissionType;
+  readonly roles?: readonly string[];
+  readonly redactValue?: unknown;
+}
+type FieldPermissionMap = Record<string, FieldPermission>;
+declare const fields: {
+  /**
+   * Field is never included in responses. Not writable via API.
+   *
+   * @example
+   * ```typescript
+   * fields: { password: fields.hidden() }
+   * ```
+   */
+  hidden(): FieldPermission;
+  /**
+   * Field is only visible to users with specified roles.
+   * Other users don't see the field at all.
+   *
+   * @example
+   * ```typescript
+   * fields: { salary: fields.visibleTo(['admin', 'hr']) }
+   * ```
+   */
+  visibleTo(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is only writable by users with specified roles.
+   * All users can still read the field. Users without the role
+   * have the field silently stripped from write operations.
+   *
+   * @example
+   * ```typescript
+   * fields: { role: fields.writableBy(['admin']) }
+   * ```
+   */
+  writableBy(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is redacted (replaced with a placeholder) for specified roles.
+   * Other users see the real value.
+   *
+   * @param roles - Roles that see the redacted value
+   * @param redactValue - Replacement value (default: '***')
+   *
+   * @example
+   * ```typescript
+   * fields: {
+   *   email: fields.redactFor(['viewer']),
+   *   ssn: fields.redactFor(['basic'], '***-**-****'),
+   * }
+   * ```
+   */
+  redactFor(roles: readonly string[], redactValue?: unknown): FieldPermission;
+};
+/**
+ * Apply field-level READ permissions to a response object.
+ * Strips hidden fields, enforces visibility, and applies redaction.
+ *
+ * @param data - The response object (mutated in place for performance)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles (empty array for unauthenticated)
+ * @returns The filtered object
+ */
+declare function applyFieldReadPermissions<T extends Record<string, unknown>>(data: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): T;
+/**
+ * Result of applying write permissions — includes both the filtered body
+ * and the list of fields that were stripped so callers can decide whether
+ * to reject the request (secure default) or silently strip (legacy).
+ */
+interface FieldWritePermissionResult<T extends Record<string, unknown>> {
+  readonly body: T;
+  readonly deniedFields: readonly string[];
+}
+/**
+ * Apply field-level WRITE permissions to request body.
+ *
+ * Returns both the filtered body and the list of denied fields. Callers are
+ * expected to reject the request when `deniedFields.length > 0` — silently
+ * stripping fields hides misconfigurations and real attacks. See
+ * `BodySanitizer` for the default policy.
+ *
+ * @param body - The request body (returns a new filtered copy)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles
+ */
+declare function applyFieldWritePermissions<T extends Record<string, unknown>>(body: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): FieldWritePermissionResult<T>;
+/**
+ * Resolve effective roles by merging global user roles with org-level roles.
+ *
+ * Global roles come from `req.user.role` (normalized via getUserRoles()).
+ * Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
+ *
+ * When no org context exists, returns global roles only — backward compatible.
+ */
+declare function resolveEffectiveRoles(userRoles: readonly string[], orgRoles: readonly string[]): string[];
+//#endregion
+export { applyFieldWritePermissions as a, applyFieldReadPermissions as i, FieldPermissionMap as n, fields as o, FieldPermissionType as r, resolveEffectiveRoles as s, FieldPermission as t };