@classytic/arc 2.23.0 → 2.28.0

package/README.md

@@ -1,5 +1,7 @@
 # @classytic/arc
 
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
+
 Database-agnostic resource framework for Fastify. One `defineResource()` call -> REST + auth + permissions + events + caching + OpenAPI + MCP tools.
 
 Fastify 5+ | Node.js 22+ | ESM only

package/dist/{BaseController-BQ8KNvWC.mjs → BaseController-B65zbz9m.mjs}

@@ -1,14 +1,14 @@
 import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { d as createDomainError, f as createError, i as NotFoundError, r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
-import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-bHblZ9YN.mjs";
+import { d as createDomainError, f as createError, i as NotFoundError, p as isArcError, r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
+import { n as getUserRoles, t as getUserId } from "./userHelpers-Cg_y3fBz.mjs";
+import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-CSyCxl2V.mjs";
 import { t as simpleEqualityMatcher } from "./simpleEqualityMatcher-Cg05HPsn.mjs";
-import { a as applyFieldWritePermissions, s as resolveEffectiveRoles } from "./applyPermissionResult-Tw4iXtlf.mjs";
-import { t as getUserRoles } from "./types-XTApa8b6.mjs";
-import { _ as ArcQueryParser, r as scheduleBackground, t as getUserId } from "./utils-CZyeRXTh.mjs";
+import { a as applyFieldWritePermissions, s as resolveEffectiveRoles } from "./applyPermissionResult-BnyVE9eD.mjs";
+import { g as ArcQueryParser, n as scheduleBackground } from "./utils-taUVD4p3.mjs";
 import { t as buildQueryKey } from "./keys-Cd316u_y.mjs";
 //#region src/core/AccessControl.ts
-const log = arcLog("access-control");
+const log$1 = arcLog("access-control");
 var AccessControl = class {
 	tenantField;
 	idField;
@@ -88,7 +88,7 @@ var AccessControl = class {
 	_warnNoMatcher(policyFilters) {
 		if (this._warnedNoMatcher) return;
 		this._warnedNoMatcher = true;
-		log.warn("`_policyFilters` contains operator-shaped entries (e.g. `$in`, `$ne`, `$regex`) but `DataAdapter.matchesFilter` is not set. Arc's flat-equality fallback cannot evaluate operators and will reject these items on non-compound fetches (`validateItemAccess`, `getBySlug`, cache revalidation). Wire up `matchesFilter` on your adapter — use `matchFilter` from `@classytic/repo-core/filter` for IR-based adapters, or your DB's native predicate engine.", { policyFilterKeys: Object.keys(policyFilters) });
+		log$1.warn("`_policyFilters` contains operator-shaped entries (e.g. `$in`, `$ne`, `$regex`) but `DataAdapter.matchesFilter` is not set. Arc's flat-equality fallback cannot evaluate operators and will reject these items on non-compound fetches (`validateItemAccess`, `getBySlug`, cache revalidation). Wire up `matchesFilter` on your adapter — use `matchFilter` from `@classytic/repo-core/filter` for IR-based adapters, or your DB's native predicate engine.", { policyFilterKeys: Object.keys(policyFilters) });
 	}
 	/**
 	* Check org/tenant scope for a document — uses configurable tenantField.
@@ -453,6 +453,7 @@ async function executeHookedOp(ctx, args, executor) {
 		const beforeReturn = await hooks.executeBefore(resourceName, args.op, args.input, hookOpts);
 		if (pipeProcessed) processedData = beforeReturn;
 	} catch (err) {
+		if (isArcError(err)) throw err;
 		throw createError(400, "Hook execution failed", {
 			code: `BEFORE_${args.op.toUpperCase()}_HOOK_ERROR`,
 			message: err.message
@@ -618,6 +619,20 @@ const defaultParser = new ArcQueryParser();
 function getDefaultQueryParser() {
 	return defaultParser;
 }
+const log = arcLog("query");
+/**
+* Deny-by-default (2.24 flip): `populate=` / `lookup=` with NO allowlist
+* configured is rejected — client-driven joins/population are an easy
+* accidental N+1 / expensive-join surface, and "absent means all" made
+* every resource opt into it silently. A one-shot dev log explains the
+* drop the first time a request hits it.
+*/
+let notedDeniedJoins = false;
+function noteDeniedJoins(kind) {
+	if (notedDeniedJoins || process.env.NODE_ENV === "production") return;
+	notedDeniedJoins = true;
+	log.warn(`client requested ${kind} but no allowlist is configured — DENIED (2.24 default flip; it was allow-all). Set schemaOptions.query.allowedPopulate / allowedLookups to enable client-driven joins. (dev-only note, shown once)`);
+}
 var QueryResolver = class {
 	queryParser;
 	maxLimit;
@@ -709,7 +724,10 @@ var QueryResolver = class {
 		const allowedPopulate = schemaOptions.query?.allowedPopulate;
 		const requested = typeof populate === "string" ? populate.split(",").map((p) => p.trim()) : Array.isArray(populate) ? populate.map(String) : [];
 		if (requested.length === 0) return void 0;
-		if (!allowedPopulate) return requested;
+		if (!allowedPopulate) {
+			noteDeniedJoins("populate");
+			return;
+		}
 		const sanitized = requested.filter((p) => allowedPopulate.includes(p));
 		return sanitized.length > 0 ? sanitized : void 0;
 	}
@@ -717,25 +735,32 @@ var QueryResolver = class {
 	sanitizePopulateOptions(options, schemaOptions) {
 		if (!options || options.length === 0) return void 0;
 		const allowedPopulate = schemaOptions.query?.allowedPopulate;
-		if (!allowedPopulate) return options;
+		if (!allowedPopulate) {
+			noteDeniedJoins("populate");
+			return;
+		}
 		const sanitized = options.filter((opt) => allowedPopulate.includes(opt.path));
 		return sanitized.length > 0 ? sanitized : void 0;
 	}
 	/**
-	* Sanitize lookup/join options.
-	* If schemaOptions.query.allowedLookups is set, only those collections are allowed.
-	* Validates lookup structure to prevent injection.
+	* Sanitize lookup/join options. Deny-by-default: `allowedLookups` must be
+	* configured for any client-driven lookup to pass; listed collections are
+	* then structurally validated to prevent injection.
 	*/
 	sanitizeLookups(lookups, schemaOptions) {
 		if (!lookups || lookups.length === 0) return void 0;
 		const allowedLookups = schemaOptions.query?.allowedLookups;
+		if (!allowedLookups) {
+			noteDeniedJoins("lookups");
+			return;
+		}
 		const validFieldName = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
 		const sanitized = lookups.filter((lookup) => {
 			if (!lookup.from || !lookup.localField || !lookup.foreignField) return false;
 			if (!validFieldName.test(lookup.from)) return false;
 			if (!validFieldName.test(lookup.localField)) return false;
 			if (!validFieldName.test(lookup.foreignField)) return false;
-			if (allowedLookups && !allowedLookups.includes(lookup.from)) return false;
+			if (!allowedLookups.includes(lookup.from)) return false;
 			return true;
 		});
 		return sanitized.length > 0 ? sanitized : void 0;
@@ -1083,6 +1108,45 @@ var BaseCrudController = class {
 	async runAfterHook(req, op, data, meta) {
 		return executeAfterHook(this.hookOpContext(req), op, data, meta);
 	}
+	/**
+	* Per-instance single-flight for cache fills — concurrent requests for
+	* the SAME cache key coalesce onto one repository query instead of each
+	* issuing its own (a popular entry expiring under 1,000 concurrent
+	* readers must produce 1 DB query, not 1,000). Keys already encode the
+	* resolved query + user/org scope + resource version, so coalescing can
+	* never cross tenants, scopes, or invalidation generations. Per-process
+	* by design; distributed refresh leases are a store-level concern
+	* (planned with the repo-core CacheEngine façade, which ships
+	* single-flight natively).
+	*/
+	inFlightCacheFills = /* @__PURE__ */ new Map();
+	cacheSingleFlight(key, fill) {
+		const existing = this.inFlightCacheFills.get(key);
+		if (existing) return existing;
+		const flight = fill().finally(() => {
+			this.inFlightCacheFills.delete(key);
+		});
+		this.inFlightCacheFills.set(key, flight);
+		return flight;
+	}
+	/**
+	* Register a background SWR refresh for `key` unless one is already in
+	* flight. Registration is SYNCHRONOUS (before the deferred tick) so a
+	* burst of stale readers arriving in the same tick schedules exactly one
+	* revalidation.
+	*/
+	scheduleCacheRefresh(key, refresh) {
+		if (this.inFlightCacheFills.has(key)) return;
+		const flight = new Promise((resolve) => {
+			scheduleBackground(() => {
+				refresh().catch(() => {}).finally(() => {
+					this.inFlightCacheFills.delete(key);
+					resolve();
+				});
+			});
+		});
+		this.inFlightCacheFills.set(key, flight);
+	}
 	/** Cached `list()` flow with SWR semantics. Returns null when cache is disabled. */
 	async withListCache(req, options) {
 		const cacheConfig = this.resolveCacheConfig("list");
@@ -1095,13 +1159,17 @@ var BaseCrudController = class {
 		const { data, status } = await qc.get(key);
 		if (status === "fresh") return this.cacheResponse(data, "HIT");
 		if (status === "stale") {
-			scheduleBackground(() => {
-				this.executeListQuery(options, req).then((fresh) => qc.set(key, fresh, cacheConfig)).catch(() => {});
+			this.scheduleCacheRefresh(key, async () => {
+				const fresh = await this.executeListQuery(options, req);
+				await qc.set(key, fresh, cacheConfig);
 			});
 			return this.cacheResponse(data, "STALE");
 		}
-		const result = await this.executeListQuery(options, req);
-		await qc.set(key, result, cacheConfig);
+		const result = await this.cacheSingleFlight(key, async () => {
+			const fresh = await this.executeListQuery(options, req);
+			await qc.set(key, fresh, cacheConfig);
+			return fresh;
+		});
 		return this.cacheResponse(result, "MISS");
 	}
 	/** Cached `get()` flow with SWR semantics. Returns null when cache is disabled. */
@@ -1119,16 +1187,18 @@ var BaseCrudController = class {
 		const { data, status } = await qc.get(key);
 		if (status === "fresh") return this.cacheResponse(data, "HIT");
 		if (status === "stale") {
-			scheduleBackground(() => {
-				this.executeGetQuery(id, options, req).then(({ doc: fresh }) => {
-					if (fresh) qc.set(key, fresh, cacheConfig);
-				}).catch(() => {});
+			this.scheduleCacheRefresh(key, async () => {
+				const { doc: fresh } = await this.executeGetQuery(id, options, req);
+				if (fresh) await qc.set(key, fresh, cacheConfig);
 			});
 			return this.cacheResponse(data, "STALE");
 		}
-		const { doc, reason } = await this.executeGetQuery(id, options, req);
+		const { doc, reason } = await this.cacheSingleFlight(key, async () => {
+			const result = await this.executeGetQuery(id, options, req);
+			if (result.doc) await qc.set(key, result.doc, cacheConfig);
+			return result;
+		});
 		if (!doc) this.throwNotFound(reason);
-		await qc.set(key, doc, cacheConfig);
 		return this.cacheResponse(doc, "MISS");
 	}
 	async list(req) {
@@ -1614,6 +1684,7 @@ function SoftDeleteMixin(Base) {
 					meta: { id }
 				});
 			} catch (err) {
+				if (isArcError(err)) throw err;
 				throw createError(400, "Hook execution failed", {
 					code: "BEFORE_RESTORE_HOOK_ERROR",
 					message: err.message

package/dist/QueryCache-DOMT_iq7.d.mts

@@ -0,0 +1,72 @@
+import { r as CacheStore } from "./interface-BGZCzOGL.mjs";
+//#region src/cache/QueryCache.d.ts
+/** Metadata wrapper stored in CacheStore */
+interface CacheEnvelope<T = unknown> {
+  data: T;
+  createdAt: number;
+  staleAfter: number;
+  expiresAt: number;
+  tags: string[];
+}
+interface QueryCacheConfig {
+  /** Seconds data is "fresh" (no revalidation). Default: 0 */
+  staleTime?: number;
+  /** Seconds stale data stays cached (SWR window). Default: 60 */
+  gcTime?: number;
+  /** Tags for group invalidation */
+  tags?: string[];
+  /**
+   * Randomized freshness jitter (0–1, default 0 = off). Each write varies
+   * its effective `staleTime` by ±(jitter × staleTime), so entries cached
+   * together don't all go stale in the same instant — spreading
+   * revalidation load instead of synchronizing a refresh burst.
+   * Single-flight coalescing (BaseCrudController) handles same-key
+   * stampedes; jitter de-synchronizes ACROSS keys. 0.1 is a sane value.
+   */
+  jitter?: number;
+}
+type CacheStatus = "fresh" | "stale" | "miss";
+interface CacheResult<T> {
+  data: T;
+  status: CacheStatus;
+}
+declare class QueryCache {
+  private readonly store;
+  constructor(store: CacheStore);
+  get<T>(key: string): Promise<CacheResult<T>>;
+  set<T>(key: string, data: T, config: QueryCacheConfig): Promise<void>;
+  invalidate(key: string): Promise<void>;
+  /** Get current version for a resource (defaults to 0 if not set) */
+  getResourceVersion(resource: string): Promise<number>;
+  /** Bump resource version — orphans all cached queries for this resource */
+  bumpResourceVersion(resource: string): Promise<void>;
+  /** Get current version for a tag */
+  getTagVersion(tag: string): Promise<number>;
+  /** Bump tag version — orphans all cached queries tagged with this tag */
+  bumpTagVersion(tag: string): Promise<void>;
+  /**
+   * Version-bump semantics:
+   *
+   *  - `store.increment` present (Redis `INCR`) — atomic and strictly
+   *    monotonic across replicas; concurrent bumps can never collide or
+   *    go backwards.
+   *  - fallback — read-modify-write with `max(now, current + 1)`: two
+   *    bumps in the same millisecond and clock regressions still advance
+   *    the version. Concurrent bumps from DIFFERENT replicas can lose one
+   *    write, which is why distributed hosts should use an incrementing
+   *    store (`runtime: 'distributed'` already requires a shared one).
+   *
+   * Version keys must outlive every derived cache entry — that invariant
+   * is what makes version invalidation sound (a version key expiring back
+   * to 0 would make entries written under the pre-reset version
+   * addressable again). The 1-year TTL applies with the repo-core
+   * TTL-ON-CREATE semantics, so a version key expires one year after its
+   * FIRST bump — safe, because a revived collision would need an entry to
+   * outlive that reset and entry TTLs are minutes-scale (staleTime +
+   * gcTime). The read-modify-write fallback uses plain `set`, which
+   * refreshes the TTL per bump — strictly longer-lived, equally safe.
+   */
+  private bumpVersion;
+}
+//#endregion
+export { QueryCacheConfig as a, QueryCache as i, CacheResult as n, CacheStatus as r, CacheEnvelope as t };

package/dist/actionPermissions-CAphcmUG.mjs

@@ -0,0 +1,24 @@
+//#region src/core/actionPermissions.ts
+/**
+* Return the effective `PermissionCheck` for a single action, or `undefined`
+* when the resource declares no gate at any level.
+*
+* Callers decide what "no gate" means:
+*   - HTTP: boot-time throw in `normalizeActionsToRouterConfig`.
+*   - MCP: tool-generation throw in `resourceToTools` (mirrors HTTP — the
+*     two surfaces fail closed identically so MCP can't expose an
+*     unauthenticated mutating tool when the HTTP plugin lifecycle hasn't
+*     run).
+*   - OpenAPI: docs advertise the endpoint as unauthenticated.
+*/
+function resolveActionPermission(input) {
+	const { action, resourcePermissions, resourceActionPermissions, globalAuth } = input;
+	const explicit = typeof action !== "function" && action.permissions ? action.permissions : void 0;
+	if (explicit) return explicit;
+	if (resourceActionPermissions) return resourceActionPermissions;
+	if (globalAuth) return globalAuth;
+	const updateFallback = resourcePermissions?.update;
+	if (updateFallback) return updateFallback;
+}
+//#endregion
+export { resolveActionPermission as t };

package/dist/{applyPermissionResult-Tw4iXtlf.mjs → applyPermissionResult-BnyVE9eD.mjs}

@@ -1,3 +1,4 @@
+import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
 //#region src/permissions/fields.ts
 /**
 * Field-Level Permissions
@@ -238,6 +239,15 @@ async function evaluateAndApplyPermission(check, context, request, reply, opts)
 			resource: context.resource,
 			action: context.action
 		}, "Permission check threw");
+		if (err instanceof ArcError) {
+			reply.code(err.status).send({
+				code: err.code,
+				message: err.message,
+				status: err.status,
+				...err.meta ? { meta: err.meta } : {}
+			});
+			return false;
+		}
 		reply.code(403).send({
 			code: "arc.forbidden",
 			message: "Permission denied",

package/dist/audit/index.d.mts

@@ -1,5 +1,5 @@
-import "../index-BBsvQt7U.mjs";
-import { i as UserBase } from "../types-Csxga7d3.mjs";
+import "../index-DPRH0Cme.mjs";
+import { i as UserBase } from "../types-Dmw-6Qeo.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/audit/stores/interface.d.ts
@@ -131,6 +131,17 @@ interface AuditPluginOptions {
     /** Interval between purges in ms. Default 86_400_000 (24h). 0 disables the timer. */
     purgeIntervalMs?: number;
   };
+  /**
+   * Unit-of-Work session provider for the built-in `repository` store. When a
+   * request runs inside a `transactionContext.run(session, …)` scope, the audit
+   * row is written **with that session**, so it commits/rolls back atomically
+   * with the domain write. Defaults to `() => transactionContext.get()`, so
+   * atomic audit works out of the box for kits that honor a write session
+   * (mongokit). Outside a transaction scope the provider returns `undefined`
+   * and the audit write proceeds session-less (unchanged). Pass `false` (or
+   * `() => undefined`) to opt out.
+   */
+  sessionProvider?: (() => unknown) | false;
   /**
    * Automatically audit CRUD operations via the hook system (default: true when enabled).
    * When enabled, create/update/delete operations are auto-logged without manual calls.
@@ -207,7 +218,25 @@ declare const auditPlugin: FastifyPluginAsync<AuditPluginOptions>;
 declare const _default: FastifyPluginAsync<AuditPluginOptions>;
 //#endregion
 //#region src/audit/repository-audit-adapter.d.ts
-declare function repositoryAsAuditStore(repository: RepositoryLike): AuditStore;
+/** Options for {@link repositoryAsAuditStore}. */
+interface RepositoryAuditStoreOptions {
+  /**
+   * Unit-of-Work session provider (AsyncLocalStorage integration), mirroring
+   * {@link EventOutbox}'s `sessionProvider`. When set, `log()` calls it to get
+   * the active DB session and writes the audit row **with that session**, so
+   * the audit entry commits/rolls back **atomically with the domain write**
+   * that produced it — no unaudited successful write, and no orphan audit for a
+   * rolled-back write. Returns `undefined` outside a transaction scope, in
+   * which case the write proceeds session-less (unchanged legacy behaviour).
+   *
+   * Wire with arc's `transactionContext` (auditPlugin does this by default):
+   * ```ts
+   * repositoryAsAuditStore(repo, { sessionProvider: () => transactionContext.get() })
+   * ```
+   */
+  readonly sessionProvider?: () => unknown;
+}
+declare function repositoryAsAuditStore(repository: RepositoryLike, options?: RepositoryAuditStoreOptions): AuditStore;
 //#endregion
 //#region src/audit/stores/memory.d.ts
 interface MemoryAuditStoreOptions {

package/dist/audit/index.mjs

@@ -1,8 +1,10 @@
+import { t as transactionContext } from "../transactionContext-PNdoyLLm.mjs";
 import fp from "fastify-plugin";
 import { and, anyOf, eq, gte, lt, lte } from "@classytic/repo-core/filter";
 //#region src/audit/repository-audit-adapter.ts
-function repositoryAsAuditStore(repository) {
+function repositoryAsAuditStore(repository, options = {}) {
 	const idField = repository.idField ?? "_id";
+	const { sessionProvider } = options;
 	return {
 		name: "repository",
 		async log(entry) {
@@ -22,7 +24,8 @@ function repositoryAsAuditStore(repository) {
 				metadata: entry.metadata,
 				timestamp: entry.timestamp
 			};
-			await repository.create(doc);
+			const session = sessionProvider?.();
+			await repository.create(doc, session != null ? { session } : void 0);
 		},
 		async purgeOlderThan(cutoff) {
 			if (!repository.deleteMany) return 0;
@@ -173,7 +176,7 @@ var MemoryAuditStore = class {
 //#endregion
 //#region src/audit/auditPlugin.ts
 const auditPlugin = async (fastify, opts = {}) => {
-	const { enabled = false, repository, customStores = [] } = opts;
+	const { enabled = false, repository, customStores = [], sessionProvider = () => transactionContext.get() } = opts;
 	if (!enabled) {
 		fastify.decorate("audit", createNoopLogger());
 		fastify.decorateRequest("auditContext", void 0);
@@ -181,7 +184,7 @@ const auditPlugin = async (fastify, opts = {}) => {
 		return;
 	}
 	const stores = [];
-	if (repository) stores.push(repositoryAsAuditStore(repository));
+	if (repository) stores.push(repositoryAsAuditStore(repository, { sessionProvider: sessionProvider === false ? void 0 : sessionProvider }));
 	stores.push(...customStores);
 	if (stores.length === 0) stores.push(new MemoryAuditStore());
 	async function logToStores(entry) {

package/dist/auth/index.d.mts

@@ -1,5 +1,5 @@
-import { Ht as AuthHelpers, Ut as AuthPluginOptions } from "../index-BBsvQt7U.mjs";
-import { t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { Ht as AuthHelpers, Ut as AuthPluginOptions } from "../index-DPRH0Cme.mjs";
+import { t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BE6wFpYv.mjs";
 import { a as SessionManagerOptions, c as createSessionManager, i as SessionData, n as MemorySessionStoreOptions, o as SessionManagerResult, r as SessionCookieOptions, s as SessionStore, t as MemorySessionStore } from "../sessionManager-BHOM3N_0.mjs";
 import { FastifyPluginAsync, FastifyReply as FastifyReply$1, FastifyRequest } from "fastify";