@classytic/arc 2.8.5 → 2.10.3

package/dist/{BaseController-DAGGc5Xn.mjs → BaseController-CbKKIflT.mjs}

@@ -1,19 +1,12 @@
-import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-Cxde4rpC.mjs";
+import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-BhY1OHoH.mjs";
 import { _ as isElevated, n as PUBLIC_SCOPE, o as getOrgId, v as isMember } from "./types-AOD8fxIw.mjs";
 import { t as buildQueryKey } from "./keys-qcD-TVJl.mjs";
-import { getUserId } from "./types/index.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-ipsbIRPK.mjs";
-import { t as getUserRoles } from "./types-ZUu_h0jp.mjs";
-import { t as ArcQueryParser } from "./queryParser-CgCtsjti.mjs";
+import { n as getUserId } from "./types-Csi3FLfq.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-bxkeltzz.mjs";
+import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
+import { r as ForbiddenError } from "./errors-D5c-5BJL.mjs";
+import { t as ArcQueryParser } from "./queryParser-DBqBB6AC.mjs";
 //#region src/core/AccessControl.ts
-/**
-* AccessControl - Composable access control logic extracted from BaseController.
-*
-* Handles ID filtering, policy filter checking, org/tenant scope validation,
-* ownership verification, and fetch-with-access-control patterns.
-*
-* Designed to be used standalone or composed into controllers.
-*/
 var AccessControl = class AccessControl {
 	tenantField;
 	idField;
@@ -95,20 +88,82 @@ var AccessControl = class AccessControl {
 	*   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
 	*/
 	async fetchWithAccessControl(id, req, repository, queryOptions) {
+		return (await this.fetchDetailed(id, req, repository, queryOptions)).doc;
+	}
+	/**
+	* Same as `fetchWithAccessControl` but returns a structured result with
+	* a denial reason so callers can distinguish "doc doesn't exist" from
+	* "doc exists but was filtered by policy/org scope" from "repo threw".
+	*
+	* Codes:
+	* - `null`               — doc was found, no denial
+	* - `'NOT_FOUND'`        — doc genuinely doesn't exist in the DB
+	* - `'POLICY_FILTERED'`  — doc exists but the request's policy filters exclude it
+	* - `'ORG_SCOPE_DENIED'` — doc exists but the caller's org context doesn't match
+	* - `'REPO_ERROR'`       — the repository threw a "not found" error (mongokit style)
+	*/
+	async fetchDetailed(id, req, repository, queryOptions) {
 		const compoundFilter = this.buildIdFilter(id, req);
-		const needsCompoundLookup = Object.keys(compoundFilter).length > 1 || this.idField !== "_id";
+		const hasCompoundFilters = Object.keys(compoundFilter).length > 1;
+		const needsCompoundLookup = hasCompoundFilters || this.idField !== "_id";
+		const translateStatus404 = (error) => {
+			if (error && typeof error === "object" && error.status === 404) return {
+				doc: null,
+				reason: "NOT_FOUND"
+			};
+			return null;
+		};
 		try {
-			if (needsCompoundLookup && typeof repository.getOne === "function") return await repository.getOne(compoundFilter, queryOptions);
+			if (needsCompoundLookup && typeof repository.getOne === "function") {
+				const doc = await repository.getOne(compoundFilter, queryOptions);
+				if (doc) return {
+					doc,
+					reason: null
+				};
+				if (hasCompoundFilters) {
+					const idOnly = { [this.idField]: id };
+					const rawDoc = await repository.getOne(idOnly);
+					if (rawDoc) {
+						const arcContext = this._meta(req);
+						if (!this.checkOrgScope(rawDoc, arcContext)) return {
+							doc: null,
+							reason: "ORG_SCOPE_DENIED"
+						};
+						return {
+							doc: null,
+							reason: "POLICY_FILTERED"
+						};
+					}
+				}
+				return {
+					doc: null,
+					reason: "NOT_FOUND"
+				};
+			}
 			if (this.idField !== "_id") {
 				if (typeof repository.getOne !== "function") throw new Error(`Resource with idField="${this.idField}" requires repository.getOne() to look up by custom field. Arc's BaseController cannot fall back to getById() because it would query by _id.`);
 			}
 			const item = await repository.getById(id, queryOptions);
-			if (!item) return null;
+			if (!item) return {
+				doc: null,
+				reason: "NOT_FOUND"
+			};
 			const arcContext = this._meta(req);
-			if (!this.checkOrgScope(item, arcContext) || !this.checkPolicyFilters(item, req)) return null;
-			return item;
+			if (!this.checkOrgScope(item, arcContext)) return {
+				doc: null,
+				reason: "ORG_SCOPE_DENIED"
+			};
+			if (!this.checkPolicyFilters(item, req)) return {
+				doc: null,
+				reason: "POLICY_FILTERED"
+			};
+			return {
+				doc: item,
+				reason: null
+			};
 		} catch (error) {
-			if (error instanceof Error && error.message?.includes("not found")) return null;
+			const translated = translateStatus404(error);
+			if (translated) return translated;
 			throw error;
 		}
 	}
@@ -224,20 +279,12 @@ var AccessControl = class AccessControl {
 		}
 	}
 };
-//#endregion
-//#region src/core/BodySanitizer.ts
-/**
-* BodySanitizer - Composable body sanitization logic extracted from BaseController.
-*
-* Strips readonly fields, system-managed fields, and applies field-level
-* write permissions from request bodies before create/update operations.
-*
-* Designed to be used standalone or composed into controllers.
-*/
 var BodySanitizer = class {
 	schemaOptions;
+	onFieldWriteDenied;
 	constructor(config) {
 		this.schemaOptions = config.schemaOptions;
+		this.onFieldWriteDenied = config.onFieldWriteDenied ?? "reject";
 	}
 	/**
 	* Strip readonly and system-managed fields from request body.
@@ -261,7 +308,9 @@ var BodySanitizer = class {
 				const fieldPerms = arcContext?.arc?.fields;
 				if (fieldPerms) {
 					const effectiveRoles = resolveEffectiveRoles(getUserRoles(req.user), isMember(scope) ? scope.orgRoles : []);
-					sanitized = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
+					const { body: filtered, deniedFields } = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
+					if (deniedFields.length > 0 && this.onFieldWriteDenied === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
+					sanitized = filtered;
 				}
 			}
 		}
@@ -404,6 +453,12 @@ var QueryResolver = class {
 //#endregion
 //#region src/core/BaseController.ts
 /**
+* Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
+* available in Bun workers, Deno, Cloudflare Workers, or edge runtimes. Fall
+* back to queueMicrotask (universal) when setImmediate is absent.
+*/
+const scheduleBackground = typeof setImmediate === "function" ? (cb) => void setImmediate(cb) : (cb) => queueMicrotask(cb);
+/**
 * Framework-agnostic base controller implementing IController.
 *
 * Composes AccessControl, BodySanitizer, and QueryResolver for clean
@@ -450,7 +505,10 @@ var BaseController = class {
 			idField: this.idField,
 			matchesFilter: this._matchesFilter
 		});
-		this.bodySanitizer = new BodySanitizer({ schemaOptions: this.schemaOptions });
+		this.bodySanitizer = new BodySanitizer({
+			schemaOptions: this.schemaOptions,
+			onFieldWriteDenied: options.onFieldWriteDenied
+		});
 		this.queryResolver = new QueryResolver({
 			queryParser: this.queryParser,
 			maxLimit: this.maxLimit,
@@ -506,6 +564,28 @@ var BaseController = class {
 		if (repoIdField && repoIdField === this.idField) return id;
 		return String(existing["_id"] ?? id);
 	}
+	/**
+	* Centralized 404 response builder. Maps the denial reason from
+	* `fetchDetailed()` into a structured `details.code` so consumers can
+	* programmatically distinguish "doc doesn't exist" from "doc filtered
+	* by policy/org scope" without parsing error strings.
+	*
+	* Error messages are intentionally vague in the `error` field (don't
+	* leak whether the doc exists) — the detail is in `details.code` only.
+	*/
+	notFoundResponse(reason = "NOT_FOUND") {
+		const code = reason ?? "NOT_FOUND";
+		return {
+			success: false,
+			error: {
+				NOT_FOUND: "Resource not found",
+				POLICY_FILTERED: "Resource not found",
+				ORG_SCOPE_DENIED: "Resource not found"
+			}[code] ?? "Resource not found",
+			status: 404,
+			details: { code }
+		};
+	}
 	/** Resolve cache config for a specific operation, merging per-op overrides */
 	resolveCacheConfig(operation) {
 		const cfg = this._cacheConfig;
@@ -547,7 +627,7 @@ var BaseController = class {
 				headers: { "x-cache": "HIT" }
 			};
 			if (status === "stale") {
-				setImmediate(() => {
+				scheduleBackground(() => {
 					this.executeListQuery(options, req).then((fresh) => qc.set(key, fresh, cacheConfig)).catch(() => {});
 				});
 				return {
@@ -576,20 +656,10 @@ var BaseController = class {
 	async executeListQuery(options, req) {
 		const hooks = this.getHooks(req);
 		const repoGetAll = async () => this.repository.getAll(options);
-		const result = hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "list", options, repoGetAll, {
+		return hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "list", options, repoGetAll, {
 			user: req.user,
 			context: this.meta(req)
 		}) : await repoGetAll();
-		if (Array.isArray(result)) return {
-			docs: result,
-			page: 1,
-			limit: result.length,
-			total: result.length,
-			pages: 1,
-			hasNext: false,
-			hasPrev: false
-		};
-		return result;
 	}
 	async get(req) {
 		const id = req.params.id;
@@ -616,8 +686,8 @@ var BaseController = class {
 				headers: { "x-cache": "HIT" }
 			};
 			if (status === "stale") {
-				setImmediate(() => {
-					this.executeGetQuery(id, options, req).then((fresh) => {
+				scheduleBackground(() => {
+					this.executeGetQuery(id, options, req).then(({ doc: fresh }) => {
 						if (fresh) qc.set(key, fresh, cacheConfig);
 					}).catch(() => {});
 				});
@@ -628,49 +698,42 @@ var BaseController = class {
 					headers: { "x-cache": "STALE" }
 				};
 			}
-			const item = await this.executeGetQuery(id, options, req);
-			if (!item) return {
-				success: false,
-				error: "Resource not found",
-				status: 404
-			};
-			await qc.set(key, item, cacheConfig);
+			const { doc: cached, reason: cacheReason } = await this.executeGetQuery(id, options, req);
+			if (!cached) return this.notFoundResponse(cacheReason);
+			await qc.set(key, cached, cacheConfig);
 			return {
 				success: true,
-				data: item,
+				data: cached,
 				status: 200,
 				headers: { "x-cache": "MISS" }
 			};
 		}
-		try {
-			const item = await this.executeGetQuery(id, options, req);
-			if (!item) return {
-				success: false,
-				error: "Resource not found",
-				status: 404
-			};
-			return {
-				success: true,
-				data: item,
-				status: 200
-			};
-		} catch (error) {
-			if (error instanceof Error && error.message?.includes("not found")) return {
-				success: false,
-				error: "Resource not found",
-				status: 404
-			};
-			throw error;
-		}
+		const { doc, reason } = await this.executeGetQuery(id, options, req);
+		if (!doc) return this.notFoundResponse(reason);
+		return {
+			success: true,
+			data: doc,
+			status: 200
+		};
 	}
 	/** Execute get query through hooks (extracted for cache revalidation) */
 	async executeGetQuery(id, options, req) {
 		const hooks = this.getHooks(req);
-		const fetchItem = async () => this.accessControl.fetchWithAccessControl(id, req, this.repository, options);
-		return (hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "read", null, fetchItem, {
-			user: req.user,
-			context: this.meta(req)
-		}) : await fetchItem()) ?? null;
+		const fetchItem = async () => {
+			return await this.accessControl.fetchDetailed(id, req, this.repository, options);
+		};
+		if (hooks && this.resourceName) {
+			const result = await fetchItem();
+			if (!result.doc) return result;
+			return {
+				doc: await hooks.executeAround(this.resourceName, "read", null, async () => result.doc, {
+					user: req.user,
+					context: this.meta(req)
+				}) ?? null,
+				reason: null
+			};
+		}
+		return fetchItem();
 	}
 	async create(req) {
 		const arcContext = this.meta(req);
@@ -733,12 +796,8 @@ var BaseController = class {
 		const user = req.user;
 		const userId = getUserId(user);
 		if (userId) data.updatedBy = userId;
-		const existing = await this.accessControl.fetchWithAccessControl(id, req, this.repository);
-		if (!existing) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		const { doc: existing, reason: updateReason } = await this.accessControl.fetchDetailed(id, req, this.repository);
+		if (!existing) return this.notFoundResponse(updateReason);
 		if (!this.accessControl.checkOwnership(existing, req)) return {
 			success: false,
 			error: "You do not have permission to modify this resource",
@@ -791,11 +850,7 @@ var BaseController = class {
 				}
 			});
 		} else item = await repoUpdate();
-		if (!item) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!item) return this.notFoundResponse("NOT_FOUND");
 		return {
 			success: true,
 			data: item,
@@ -812,12 +867,8 @@ var BaseController = class {
 		};
 		const arcContext = this.meta(req);
 		const user = req.user;
-		const existing = await this.accessControl.fetchWithAccessControl(id, req, this.repository);
-		if (!existing) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		const { doc: existing, reason: deleteReason } = await this.accessControl.fetchDetailed(id, req, this.repository);
+		if (!existing) return this.notFoundResponse(deleteReason);
 		if (!this.accessControl.checkOwnership(existing, req)) return {
 			success: false,
 			error: "You do not have permission to delete this resource",
@@ -862,11 +913,7 @@ var BaseController = class {
 			if (typeof r.success === "boolean") return r.success;
 			if (typeof r.deletedCount === "number") return r.deletedCount > 0;
 			return true;
-		})()) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		})()) return this.notFoundResponse("NOT_FOUND");
 		if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "delete", existing, {
 			user,
 			context: arcContext,
@@ -901,11 +948,7 @@ var BaseController = class {
 			error: "Slug lookup not implemented — repository needs getBySlug() or getOne()",
 			status: 501
 		};
-		if (!this.accessControl.validateItemAccess(item, req)) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!this.accessControl.validateItemAccess(item, req)) return this.notFoundResponse(item ? "POLICY_FILTERED" : "NOT_FOUND");
 		return {
 			success: true,
 			data: item,
@@ -920,27 +963,9 @@ var BaseController = class {
 			status: 501
 		};
 		const parsed = this.queryResolver.resolve(req, this.meta(req));
-		const result = await repo.getDeleted(parsed, parsed);
-		if (Array.isArray(result)) {
-			const docs = result;
-			return {
-				success: true,
-				data: {
-					method: "offset",
-					docs,
-					page: 1,
-					limit: docs.length,
-					total: docs.length,
-					pages: 1,
-					hasNext: false,
-					hasPrev: false
-				},
-				status: 200
-			};
-		}
 		return {
 			success: true,
-			data: result,
+			data: await repo.getDeleted(parsed, parsed),
 			status: 200
 		};
 	}
@@ -958,11 +983,7 @@ var BaseController = class {
 			status: 400
 		};
 		const existing = await this.accessControl.fetchWithAccessControl(id, req, repo, { includeDeleted: true });
-		if (!existing) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!existing) return this.notFoundResponse("NOT_FOUND");
 		if (!this.accessControl.checkOwnership(existing, req)) return {
 			success: false,
 			error: "You do not have permission to restore this resource",
@@ -998,11 +1019,7 @@ var BaseController = class {
 			meta: { id }
 		});
 		else item = await repoRestore();
-		if (!item) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!item) return this.notFoundResponse("NOT_FOUND");
 		if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "restore", item, {
 			user,
 			context: arcContext,
@@ -1052,13 +1069,15 @@ var BaseController = class {
 			error: "Repository does not support createMany",
 			status: 501
 		};
-		const items = req.body?.items;
-		if (!items || items.length === 0) return {
+		const rawItems = req.body?.items;
+		if (!Array.isArray(rawItems) || rawItems.length === 0) return {
 			success: false,
 			error: "Bulk create requires a non-empty items array",
 			status: 400
 		};
+		const items = rawItems;
 		const arcContext = this.meta(req);
+		const user = req.user;
 		const sanitizedItems = items.map((item) => this.bodySanitizer.sanitize(item ?? {}, "create", req, arcContext));
 		let scopedItems = sanitizedItems;
 		if (this.tenantField) {
@@ -1086,7 +1105,10 @@ var BaseController = class {
 				}
 			}
 		}
-		const created = await repo.createMany(scopedItems);
+		const created = await repo.createMany(scopedItems, {
+			user,
+			context: arcContext
+		});
 		const requested = items.length;
 		const inserted = created.length;
 		const skipped = requested - inserted;
@@ -1157,13 +1179,23 @@ var BaseController = class {
 	*/
 	sanitizeBulkUpdateData(data, req, arcContext) {
 		const stripped = /* @__PURE__ */ new Set();
-		if (!Object.keys(data).some((k) => k.startsWith("$"))) {
+		const keys = Object.keys(data);
+		const operatorKeys = keys.filter((k) => k.startsWith("$"));
+		const flatKeys = keys.filter((k) => !k.startsWith("$"));
+		const isOperatorShape = operatorKeys.length > 0;
+		if (isOperatorShape && flatKeys.length > 0) return {
+			sanitized: {},
+			stripped: [],
+			mixedShape: true
+		};
+		if (!isOperatorShape) {
 			const before = new Set(Object.keys(data));
 			const sanitized = this.bodySanitizer.sanitize(data, "update", req, arcContext);
 			for (const key of before) if (!(key in sanitized)) stripped.add(key);
 			return {
 				sanitized,
-				stripped: [...stripped]
+				stripped: [...stripped],
+				mixedShape: false
 			};
 		}
 		const sanitized = {};
@@ -1180,7 +1212,8 @@ var BaseController = class {
 		}
 		return {
 			sanitized,
-			stripped: [...stripped]
+			stripped: [...stripped],
+			mixedShape: false
 		};
 	}
 	async bulkUpdate(req) {
@@ -1209,7 +1242,14 @@ var BaseController = class {
 			status: 403
 		};
 		const arcContext = this.meta(req);
-		const { sanitized, stripped } = this.sanitizeBulkUpdateData(body.data, req, arcContext);
+		const user = req.user;
+		const { sanitized, stripped, mixedShape } = this.sanitizeBulkUpdateData(body.data, req, arcContext);
+		if (mixedShape) return {
+			success: false,
+			error: "Bulk update payload cannot mix operator keys ($set, $inc, ...) with flat fields. Pick one shape.",
+			details: { code: "MIXED_UPDATE_SHAPE" },
+			status: 400
+		};
 		if (Object.keys(sanitized).length === 0) return {
 			success: false,
 			error: "Bulk update payload contained only protected fields",
@@ -1221,7 +1261,10 @@ var BaseController = class {
 		};
 		return {
 			success: true,
-			data: await repo.updateMany(scopedFilter, sanitized),
+			data: await repo.updateMany(scopedFilter, sanitized, {
+				user,
+				context: arcContext
+			}),
 			status: 200,
 			...stripped.length > 0 && { meta: { stripped } }
 		};
@@ -1272,9 +1315,16 @@ var BaseController = class {
 			details: { code: "ORG_CONTEXT_REQUIRED" },
 			status: 403
 		};
+		const hardHint = req.query?.hard === "true" || req.query?.hard === true || body.mode === "hard";
+		const arcContext = this.meta(req);
+		const options = {
+			user: req.user,
+			context: arcContext
+		};
+		if (hardHint) options.mode = "hard";
 		return {
 			success: true,
-			data: req.query?.hard === "true" || req.query?.hard === true || body.mode === "hard" ? await repo.deleteMany(scopedFilter, { mode: "hard" }) : await repo.deleteMany(scopedFilter),
+			data: await repo.deleteMany(scopedFilter, options),
 			status: 200
 		};
 	}