@classytic/arc 2.3.0 → 2.4.1

package/dist/BaseController-CkM5dUh_.mjs

@@ -0,0 +1,1031 @@
+import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-Cxde4rpC.mjs";
+import { d as isMember, n as PUBLIC_SCOPE, r as getOrgId, u as isElevated } from "./types-C6TQjtdi.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";
+//#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;
+	_adapterMatchesFilter;
+	/** Patterns that indicate dangerous regex (nested quantifiers, excessive backtracking).
+	*  Uses [^...] character classes instead of .+ to avoid backtracking in the detector itself. */
+	static DANGEROUS_REGEX = /(\{[0-9]+,\}[^{]*\{[0-9]+,\})|(\+[^+]*\+)|(\*[^*]*\*)|(\.\*){3,}|\\1/;
+	/** Forbidden paths that could lead to prototype pollution */
+	static FORBIDDEN_PATHS = [
+		"__proto__",
+		"constructor",
+		"prototype"
+	];
+	constructor(config) {
+		this.tenantField = config.tenantField;
+		this.idField = config.idField;
+		this._adapterMatchesFilter = config.matchesFilter;
+	}
+	/**
+	* Build filter for single-item operations (get/update/delete)
+	* Combines ID filter with policy/org filters for proper security enforcement
+	*/
+	buildIdFilter(id, req) {
+		const filter = { [this.idField]: id };
+		const arcContext = this._meta(req);
+		const policyFilters = arcContext?._policyFilters;
+		if (policyFilters) Object.assign(filter, policyFilters);
+		const scope = arcContext?._scope;
+		const orgId = scope ? getOrgId(scope) : void 0;
+		if (this.tenantField && orgId && !policyFilters?.[this.tenantField]) filter[this.tenantField] = orgId;
+		return filter;
+	}
+	/**
+	* Check if item matches policy filters (for get/update/delete operations)
+	* Validates that fetched item satisfies all policy constraints
+	*
+	* Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
+	* otherwise falls back to built-in MongoDB-style matching.
+	*/
+	checkPolicyFilters(item, req) {
+		const policyFilters = this._meta(req)?._policyFilters;
+		if (!policyFilters) return true;
+		if (this._adapterMatchesFilter) return this._adapterMatchesFilter(item, policyFilters);
+		return this.defaultMatchesPolicyFilters(item, policyFilters);
+	}
+	/**
+	* Check org/tenant scope for a document — uses configurable tenantField.
+	*
+	* SECURITY: When org scope is active (orgId present), documents that are
+	* missing the tenant field are DENIED by default. This prevents legacy or
+	* unscoped records from leaking across tenants.
+	*/
+	checkOrgScope(item, arcContext) {
+		if (!this.tenantField) return true;
+		const scope = arcContext?._scope;
+		const orgId = scope ? getOrgId(scope) : void 0;
+		if (!item || !orgId) return true;
+		if (scope && isElevated(scope) && !orgId) return true;
+		const itemOrgId = item[this.tenantField];
+		if (!itemOrgId) return false;
+		return String(itemOrgId) === String(orgId);
+	}
+	/** Check ownership for update/delete (ownedByUser preset) */
+	checkOwnership(item, req) {
+		const ownershipCheck = this._meta(req)?._ownershipCheck;
+		if (!item || !ownershipCheck) return true;
+		const { field, userId } = ownershipCheck;
+		const itemOwnerId = item[field];
+		if (!itemOwnerId) return true;
+		return String(itemOwnerId) === String(userId);
+	}
+	/**
+	* Fetch a single document with full access control enforcement.
+	* Combines compound DB filter (ID + org + policy) with post-hoc fallback.
+	*
+	* Takes repository as a parameter to avoid coupling.
+	*
+	* Replaces the duplicated pattern in get/update/delete:
+	*   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
+	*/
+	async fetchWithAccessControl(id, req, repository, queryOptions) {
+		const compoundFilter = this.buildIdFilter(id, req);
+		const hasCompoundFilters = Object.keys(compoundFilter).length > 1;
+		try {
+			if (hasCompoundFilters && typeof repository.getOne === "function") return await repository.getOne(compoundFilter, queryOptions);
+			const item = await repository.getById(id, queryOptions);
+			if (!item) return null;
+			const arcContext = this._meta(req);
+			if (!this.checkOrgScope(item, arcContext) || !this.checkPolicyFilters(item, req)) return null;
+			return item;
+		} catch (error) {
+			if (error instanceof Error && error.message?.includes("not found")) return null;
+			throw error;
+		}
+	}
+	/**
+	* Post-fetch access control validation for items fetched by non-ID queries
+	* (e.g., getBySlug, restore). Applies org scope, policy filters, and
+	* ownership checks — the same guarantees as fetchWithAccessControl.
+	*/
+	validateItemAccess(item, req) {
+		if (!item) return false;
+		const arcContext = this._meta(req);
+		if (!this.checkOrgScope(item, arcContext)) return false;
+		if (!this.checkPolicyFilters(item, req)) return false;
+		return true;
+	}
+	/** Extract typed Arc internal metadata from request */
+	_meta(req) {
+		return req.metadata;
+	}
+	/**
+	* Check if a value matches a MongoDB query operator
+	*/
+	matchesOperator(itemValue, operator, filterValue) {
+		const equalsByValue = (a, b) => String(a) === String(b);
+		switch (operator) {
+			case "$eq": return equalsByValue(itemValue, filterValue);
+			case "$ne": return !equalsByValue(itemValue, filterValue);
+			case "$gt": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue > filterValue;
+			case "$gte": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue >= filterValue;
+			case "$lt": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue < filterValue;
+			case "$lte": return typeof itemValue === "number" && typeof filterValue === "number" && itemValue <= filterValue;
+			case "$in":
+				if (!Array.isArray(filterValue)) return false;
+				if (Array.isArray(itemValue)) return itemValue.some((v) => filterValue.some((fv) => equalsByValue(v, fv)));
+				return filterValue.some((fv) => equalsByValue(itemValue, fv));
+			case "$nin":
+				if (!Array.isArray(filterValue)) return false;
+				if (Array.isArray(itemValue)) return itemValue.every((v) => filterValue.every((fv) => !equalsByValue(v, fv)));
+				return filterValue.every((fv) => !equalsByValue(itemValue, fv));
+			case "$exists": return filterValue ? itemValue !== void 0 : itemValue === void 0;
+			case "$regex":
+				if (typeof itemValue === "string" && (typeof filterValue === "string" || filterValue instanceof RegExp)) return (typeof filterValue === "string" ? AccessControl.safeRegex(filterValue) : filterValue)?.test(itemValue) ?? false;
+				return false;
+			default: return false;
+		}
+	}
+	/**
+	* Check if item matches a single filter condition
+	* Supports nested paths (e.g., "owner.id", "metadata.status")
+	*/
+	matchesFilter(item, key, filterValue) {
+		const itemValue = key.includes(".") ? this.getNestedValue(item, key) : item[key];
+		if (filterValue && typeof filterValue === "object" && !Array.isArray(filterValue)) {
+			if (Object.keys(filterValue).some((op) => op.startsWith("$"))) {
+				for (const [operator, opValue] of Object.entries(filterValue)) if (!this.matchesOperator(itemValue, operator, opValue)) return false;
+				return true;
+			}
+		}
+		if (Array.isArray(itemValue)) return itemValue.some((v) => String(v) === String(filterValue));
+		return String(itemValue) === String(filterValue);
+	}
+	/**
+	* Built-in MongoDB-style policy filter matching.
+	* Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
+	*/
+	defaultMatchesPolicyFilters(item, policyFilters) {
+		if (policyFilters.$and && Array.isArray(policyFilters.$and)) {
+			if (!policyFilters.$and.every((condition) => {
+				return Object.entries(condition).every(([key, value]) => {
+					return this.matchesFilter(item, key, value);
+				});
+			})) return false;
+		}
+		if (policyFilters.$or && Array.isArray(policyFilters.$or)) {
+			if (!policyFilters.$or.some((condition) => {
+				return Object.entries(condition).every(([key, value]) => {
+					return this.matchesFilter(item, key, value);
+				});
+			})) return false;
+		}
+		for (const [key, value] of Object.entries(policyFilters)) {
+			if (key.startsWith("$")) continue;
+			if (!this.matchesFilter(item, key, value)) return false;
+		}
+		return true;
+	}
+	/**
+	* Get nested value from object using dot notation (e.g., "owner.id")
+	* Security: Validates path against forbidden patterns to prevent prototype pollution
+	*/
+	getNestedValue(obj, path) {
+		if (AccessControl.FORBIDDEN_PATHS.some((p) => path.toLowerCase().includes(p))) return;
+		const keys = path.split(".");
+		let value = obj;
+		for (const key of keys) {
+			if (value == null) return void 0;
+			if (AccessControl.FORBIDDEN_PATHS.includes(key.toLowerCase())) return;
+			value = value[key];
+		}
+		return value;
+	}
+	/**
+	* Create a safe RegExp from a string, guarding against ReDoS.
+	* Returns null if the pattern is invalid or dangerous.
+	*/
+	static safeRegex(pattern) {
+		if (pattern.length > 200) return null;
+		if (AccessControl.DANGEROUS_REGEX.test(pattern)) return null;
+		try {
+			return new RegExp(pattern);
+		} catch {
+			return null;
+		}
+	}
+};
+//#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;
+	constructor(config) {
+		this.schemaOptions = config.schemaOptions;
+	}
+	/**
+	* Strip readonly and system-managed fields from request body.
+	* Prevents clients from overwriting _id, timestamps, __v, etc.
+	*
+	* Also applies field-level write permissions when the request has
+	* field permission metadata.
+	*/
+	sanitize(body, _operation, req, meta) {
+		let sanitized = { ...body };
+		for (const field of SYSTEM_FIELDS) delete sanitized[field];
+		const fieldRules = this.schemaOptions.fieldRules ?? {};
+		for (const [field, rules] of Object.entries(fieldRules)) if (rules.systemManaged || rules.readonly) delete sanitized[field];
+		if (req) {
+			const arcContext = meta ?? req.metadata;
+			const scope = arcContext?._scope ?? PUBLIC_SCOPE;
+			if (!isElevated(scope)) {
+				const fieldPerms = arcContext?.arc?.fields;
+				if (fieldPerms) {
+					const effectiveRoles = resolveEffectiveRoles(getUserRoles(req.user), isMember(scope) ? scope.orgRoles : []);
+					sanitized = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
+				}
+			}
+		}
+		return sanitized;
+	}
+};
+//#endregion
+//#region src/core/QueryResolver.ts
+/**
+* QueryResolver - Composable query resolution logic extracted from BaseController.
+*
+* Resolves a request into parsed query options (pagination, filters, sorting,
+* select, populate) in a single pass. Applies org/tenant scope and policy
+* filters from the request metadata.
+*
+* Designed to be used standalone or composed into controllers.
+*/
+const defaultParser = new ArcQueryParser();
+function getDefaultQueryParser() {
+	return defaultParser;
+}
+var QueryResolver = class {
+	queryParser;
+	maxLimit;
+	defaultLimit;
+	defaultSort;
+	schemaOptions;
+	tenantField;
+	constructor(config = {}) {
+		this.queryParser = config.queryParser ?? getDefaultQueryParser();
+		this.maxLimit = config.maxLimit ?? 100;
+		this.defaultLimit = config.defaultLimit ?? 20;
+		this.defaultSort = config.defaultSort ?? "-createdAt";
+		this.schemaOptions = config.schemaOptions ?? {};
+		this.tenantField = config.tenantField !== void 0 ? config.tenantField : DEFAULT_TENANT_FIELD;
+	}
+	/**
+	* Resolve a request into parsed query options -- ONE parse per request.
+	* Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
+	*/
+	resolve(req, meta) {
+		const parsed = this.queryParser.parse(req.query);
+		const arcContext = meta ?? req.metadata;
+		delete parsed.filters?._policyFilters;
+		const limit = Math.min(Math.max(1, parsed.limit || this.defaultLimit), this.maxLimit);
+		const page = parsed.after ? void 0 : parsed.page ? Math.max(1, parsed.page) : 1;
+		const sortString = parsed.sort ? Object.entries(parsed.sort).map(([k, v]) => v === -1 ? `-${k}` : k).join(",") : this.defaultSort;
+		const rawSelect = parsed.select ?? req.query?.select;
+		const filters = { ...parsed.filters };
+		const policyFilters = arcContext?._policyFilters;
+		if (policyFilters) Object.assign(filters, policyFilters);
+		const scope = arcContext?._scope;
+		const orgId = scope ? getOrgId(scope) : void 0;
+		if (this.tenantField && orgId && !policyFilters?.[this.tenantField]) filters[this.tenantField] = orgId;
+		return {
+			page,
+			limit,
+			sort: sortString,
+			select: this.sanitizeSelectAny(rawSelect, this.schemaOptions),
+			populate: this.sanitizePopulate(parsed.populate, this.schemaOptions),
+			populateOptions: this.sanitizePopulateOptions(parsed.populateOptions, this.schemaOptions),
+			lookups: this.sanitizeLookups(parsed.lookups, this.schemaOptions),
+			filters,
+			search: parsed.search,
+			after: parsed.after,
+			user: req.user,
+			context: arcContext
+		};
+	}
+	/**
+	* Sanitize select — preserves the input format (string, array, or object).
+	* This is critical for db-agnostic support: MongoKit returns object projections,
+	* Mongoose uses space-separated strings, SQL adapters may use arrays.
+	*/
+	sanitizeSelectAny(select, schemaOptions) {
+		if (!select) return void 0;
+		const blockedFields = this.getBlockedFields(schemaOptions);
+		if (blockedFields.length === 0) return select;
+		if (typeof select === "object" && !Array.isArray(select)) {
+			const sanitized = {};
+			for (const [field, val] of Object.entries(select)) if (!blockedFields.includes(field)) sanitized[field] = val;
+			return Object.keys(sanitized).length > 0 ? sanitized : void 0;
+		}
+		if (Array.isArray(select)) {
+			const sanitized = select.filter((f) => {
+				const fieldName = f.replace(/^-/, "");
+				return !blockedFields.includes(fieldName);
+			});
+			return sanitized.length > 0 ? sanitized : void 0;
+		}
+		const sanitized = select.split(/[\s,]+/).filter(Boolean).filter((f) => {
+			const fieldName = f.replace(/^-/, "");
+			return !blockedFields.includes(fieldName);
+		});
+		return sanitized.length > 0 ? sanitized.join(" ") : void 0;
+	}
+	/** Sanitize populate fields */
+	sanitizePopulate(populate, schemaOptions) {
+		if (!populate) return void 0;
+		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;
+		const sanitized = requested.filter((p) => allowedPopulate.includes(p));
+		return sanitized.length > 0 ? sanitized : void 0;
+	}
+	/** Sanitize advanced populate options against allowedPopulate */
+	sanitizePopulateOptions(options, schemaOptions) {
+		if (!options || options.length === 0) return void 0;
+		const allowedPopulate = schemaOptions.query?.allowedPopulate;
+		if (!allowedPopulate) return options;
+		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.
+	*/
+	sanitizeLookups(lookups, schemaOptions) {
+		if (!lookups || lookups.length === 0) return void 0;
+		const allowedLookups = schemaOptions.query?.allowedLookups;
+		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;
+			return true;
+		});
+		return sanitized.length > 0 ? sanitized : void 0;
+	}
+	/** Get blocked fields from schema options */
+	getBlockedFields(schemaOptions) {
+		const fieldRules = schemaOptions.fieldRules ?? {};
+		return Object.entries(fieldRules).filter(([, rules]) => rules.systemManaged || rules.hidden).map(([field]) => field);
+	}
+};
+//#endregion
+//#region src/core/BaseController.ts
+/**
+* Framework-agnostic base controller implementing IController.
+*
+* Composes AccessControl, BodySanitizer, and QueryResolver for clean
+* separation of concerns. CRUD methods delegate directly to these
+* composed classes — no intermediate wrapper methods.
+*
+* @template TDoc - The document type
+* @template TRepository - The repository type (defaults to RepositoryLike)
+*/
+var BaseController = class {
+	repository;
+	schemaOptions;
+	queryParser;
+	maxLimit;
+	defaultLimit;
+	defaultSort;
+	resourceName;
+	tenantField;
+	idField = "_id";
+	/** Composable access control (ID filtering, policy checks, org scope, ownership) */
+	accessControl;
+	/** Composable body sanitization (field permissions, system fields) */
+	bodySanitizer;
+	/** Composable query resolution (parsing, pagination, sort, select/populate) */
+	queryResolver;
+	_matchesFilter;
+	_presetFields = {};
+	_cacheConfig;
+	constructor(repository, options = {}) {
+		this.repository = repository;
+		this.schemaOptions = options.schemaOptions ?? {};
+		this.queryParser = options.queryParser ?? getDefaultQueryParser();
+		this.maxLimit = options.maxLimit ?? 100;
+		this.defaultLimit = options.defaultLimit ?? 20;
+		this.defaultSort = options.defaultSort ?? "-createdAt";
+		this.resourceName = options.resourceName;
+		this.tenantField = options.tenantField !== void 0 ? options.tenantField : DEFAULT_TENANT_FIELD;
+		this.idField = options.idField ?? "_id";
+		this._matchesFilter = options.matchesFilter;
+		if (options.cache) this._cacheConfig = options.cache;
+		if (options.presetFields) this._presetFields = options.presetFields;
+		this.accessControl = new AccessControl({
+			tenantField: this.tenantField,
+			idField: this.idField,
+			matchesFilter: this._matchesFilter
+		});
+		this.bodySanitizer = new BodySanitizer({ schemaOptions: this.schemaOptions });
+		this.queryResolver = new QueryResolver({
+			queryParser: this.queryParser,
+			maxLimit: this.maxLimit,
+			defaultLimit: this.defaultLimit,
+			defaultSort: this.defaultSort,
+			schemaOptions: this.schemaOptions,
+			tenantField: this.tenantField
+		});
+		this.list = this.list.bind(this);
+		this.get = this.get.bind(this);
+		this.create = this.create.bind(this);
+		this.update = this.update.bind(this);
+		this.delete = this.delete.bind(this);
+	}
+	/**
+	* Get the tenant field name if multi-tenant scoping is enabled.
+	* Returns `undefined` when `tenantField` is `false` (platform-universal mode).
+	*
+	* Use this in subclass overrides instead of accessing `this.tenantField` directly
+	* to avoid TypeScript indexing errors with `string | false`.
+	*/
+	getTenantField() {
+		return this.tenantField || void 0;
+	}
+	/** Extract typed Arc internal metadata from request */
+	meta(req) {
+		return req.metadata;
+	}
+	/** Get hook system from request context (instance-scoped) */
+	getHooks(req) {
+		return this.meta(req)?.arc?.hooks ?? null;
+	}
+	/** Resolve cache config for a specific operation, merging per-op overrides */
+	resolveCacheConfig(operation) {
+		const cfg = this._cacheConfig;
+		if (!cfg || cfg.disabled) return null;
+		const opOverride = cfg[operation];
+		return {
+			staleTime: opOverride?.staleTime ?? cfg.staleTime ?? 0,
+			gcTime: opOverride?.gcTime ?? cfg.gcTime ?? 60,
+			tags: cfg.tags
+		};
+	}
+	/**
+	* Extract user/org IDs from request for cache key scoping.
+	* Only includes orgId when this resource uses tenant-scoped data (tenantField is set).
+	* Universal resources (tenantField: false) get shared cache keys to avoid fragmentation.
+	*/
+	cacheScope(req) {
+		return {
+			userId: getUserId(req.user),
+			orgId: this.tenantField ? (() => {
+				const scope = this.meta(req)?._scope;
+				return scope ? getOrgId(scope) : void 0;
+			})() : void 0
+		};
+	}
+	async list(req) {
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const cacheConfig = this.resolveCacheConfig("list");
+		const qc = req.server?.queryCache;
+		if (cacheConfig && qc) {
+			const version = await qc.getResourceVersion(this.resourceName);
+			const { userId, orgId } = this.cacheScope(req);
+			const key = buildQueryKey(this.resourceName, "list", version, options, userId, orgId);
+			const { data, status } = await qc.get(key);
+			if (status === "fresh") return {
+				success: true,
+				data,
+				status: 200,
+				headers: { "x-cache": "HIT" }
+			};
+			if (status === "stale") {
+				setImmediate(() => {
+					this.executeListQuery(options, req).then((fresh) => qc.set(key, fresh, cacheConfig)).catch(() => {});
+				});
+				return {
+					success: true,
+					data,
+					status: 200,
+					headers: { "x-cache": "STALE" }
+				};
+			}
+			const result = await this.executeListQuery(options, req);
+			await qc.set(key, result, cacheConfig);
+			return {
+				success: true,
+				data: result,
+				status: 200,
+				headers: { "x-cache": "MISS" }
+			};
+		}
+		return {
+			success: true,
+			data: await this.executeListQuery(options, req),
+			status: 200
+		};
+	}
+	/** Execute list query through hooks (extracted for cache revalidation) */
+	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, {
+			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;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const cacheConfig = this.resolveCacheConfig("byId");
+		const qc = req.server?.queryCache;
+		if (cacheConfig && qc) {
+			const version = await qc.getResourceVersion(this.resourceName);
+			const { userId, orgId } = this.cacheScope(req);
+			const key = buildQueryKey(this.resourceName, "get", version, {
+				id,
+				...options
+			}, userId, orgId);
+			const { data, status } = await qc.get(key);
+			if (status === "fresh") return {
+				success: true,
+				data,
+				status: 200,
+				headers: { "x-cache": "HIT" }
+			};
+			if (status === "stale") {
+				setImmediate(() => {
+					this.executeGetQuery(id, options, req).then((fresh) => {
+						if (fresh) qc.set(key, fresh, cacheConfig);
+					}).catch(() => {});
+				});
+				return {
+					success: true,
+					data,
+					status: 200,
+					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);
+			return {
+				success: true,
+				data: item,
+				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;
+		}
+	}
+	/** 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;
+	}
+	async create(req) {
+		const arcContext = this.meta(req);
+		const data = this.bodySanitizer.sanitize(req.body ?? {}, "create", req, arcContext);
+		const scope = arcContext?._scope;
+		const createOrgId = scope ? getOrgId(scope) : void 0;
+		if (this.tenantField && createOrgId) data[this.tenantField] = createOrgId;
+		const userId = getUserId(req.user);
+		if (userId) data.createdBy = userId;
+		const hooks = this.getHooks(req);
+		const user = req.user;
+		let processedData = data;
+		if (hooks && this.resourceName) try {
+			processedData = await hooks.executeBefore(this.resourceName, "create", data, {
+				user,
+				context: arcContext
+			});
+		} catch (err) {
+			return {
+				success: false,
+				error: "Hook execution failed",
+				details: {
+					code: "BEFORE_CREATE_HOOK_ERROR",
+					message: err.message
+				},
+				status: 400
+			};
+		}
+		const repoCreate = async () => this.repository.create(processedData, {
+			user,
+			context: arcContext
+		});
+		let item;
+		if (hooks && this.resourceName) {
+			item = await hooks.executeAround(this.resourceName, "create", processedData, repoCreate, {
+				user,
+				context: arcContext
+			});
+			await hooks.executeAfter(this.resourceName, "create", item, {
+				user,
+				context: arcContext
+			});
+		} else item = await repoCreate();
+		return {
+			success: true,
+			data: item,
+			status: 201,
+			meta: { message: "Created successfully" }
+		};
+	}
+	async update(req) {
+		const id = req.params.id;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		const arcContext = this.meta(req);
+		const data = this.bodySanitizer.sanitize(req.body ?? {}, "update", req, arcContext);
+		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
+		};
+		if (!this.accessControl.checkOwnership(existing, req)) return {
+			success: false,
+			error: "You do not have permission to modify this resource",
+			details: { code: "OWNERSHIP_DENIED" },
+			status: 403
+		};
+		const hooks = this.getHooks(req);
+		let processedData = data;
+		if (hooks && this.resourceName) try {
+			processedData = await hooks.executeBefore(this.resourceName, "update", data, {
+				user,
+				context: arcContext,
+				meta: {
+					id,
+					existing
+				}
+			});
+		} catch (err) {
+			return {
+				success: false,
+				error: "Hook execution failed",
+				details: {
+					code: "BEFORE_UPDATE_HOOK_ERROR",
+					message: err.message
+				},
+				status: 400
+			};
+		}
+		const repoUpdate = async () => this.repository.update(id, processedData, {
+			user,
+			context: arcContext
+		});
+		let item;
+		if (hooks && this.resourceName) {
+			item = await hooks.executeAround(this.resourceName, "update", processedData, repoUpdate, {
+				user,
+				context: arcContext,
+				meta: {
+					id,
+					existing
+				}
+			});
+			if (item) await hooks.executeAfter(this.resourceName, "update", item, {
+				user,
+				context: arcContext,
+				meta: {
+					id,
+					existing
+				}
+			});
+		} else item = await repoUpdate();
+		if (!item) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		return {
+			success: true,
+			data: item,
+			status: 200,
+			meta: { message: "Updated successfully" }
+		};
+	}
+	async delete(req) {
+		const id = req.params.id;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		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
+		};
+		if (!this.accessControl.checkOwnership(existing, req)) return {
+			success: false,
+			error: "You do not have permission to delete this resource",
+			details: { code: "OWNERSHIP_DENIED" },
+			status: 403
+		};
+		const hooks = this.getHooks(req);
+		if (hooks && this.resourceName) try {
+			await hooks.executeBefore(this.resourceName, "delete", existing, {
+				user,
+				context: arcContext,
+				meta: { id }
+			});
+		} catch (err) {
+			return {
+				success: false,
+				error: "Hook execution failed",
+				details: {
+					code: "BEFORE_DELETE_HOOK_ERROR",
+					message: err.message
+				},
+				status: 400
+			};
+		}
+		const repoDelete = async () => this.repository.delete(id, {
+			user,
+			context: arcContext
+		});
+		let result;
+		if (hooks && this.resourceName) result = await hooks.executeAround(this.resourceName, "delete", existing, repoDelete, {
+			user,
+			context: arcContext,
+			meta: { id }
+		});
+		else result = await repoDelete();
+		if (!(typeof result === "object" && result !== null ? result.success : result)) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "delete", existing, {
+			user,
+			context: arcContext,
+			meta: { id }
+		});
+		const deleteResult = typeof result === "object" && result !== null ? result : {};
+		return {
+			success: true,
+			data: {
+				message: deleteResult.message || "Deleted successfully",
+				...id ? { id } : {},
+				...deleteResult.soft ? { soft: true } : {}
+			},
+			status: 200
+		};
+	}
+	async getBySlug(req) {
+		const repo = this.repository;
+		if (!repo.getBySlug) return {
+			success: false,
+			error: "Slug lookup not implemented",
+			status: 501
+		};
+		const slugField = this._presetFields.slugField ?? "slug";
+		const slug = req.params[slugField] ?? req.params.slug;
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const item = await repo.getBySlug(slug, options);
+		if (!this.accessControl.validateItemAccess(item, req)) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		return {
+			success: true,
+			data: item,
+			status: 200
+		};
+	}
+	async getDeleted(req) {
+		const repo = this.repository;
+		if (!repo.getDeleted) return {
+			success: false,
+			error: "Soft delete not implemented",
+			status: 501
+		};
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		const result = await repo.getDeleted(options);
+		if (Array.isArray(result)) return {
+			success: true,
+			data: {
+				docs: result,
+				page: 1,
+				limit: result.length,
+				total: result.length,
+				pages: 1,
+				hasNext: false,
+				hasPrev: false
+			},
+			status: 200
+		};
+		return {
+			success: true,
+			data: result,
+			status: 200
+		};
+	}
+	async restore(req) {
+		const repo = this.repository;
+		if (!repo.restore) return {
+			success: false,
+			error: "Restore not implemented",
+			status: 501
+		};
+		const id = req.params.id;
+		if (!id) return {
+			success: false,
+			error: "ID parameter is required",
+			status: 400
+		};
+		const existing = await this.accessControl.fetchWithAccessControl(id, req, repo);
+		if (!existing) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		if (!this.accessControl.checkOwnership(existing, req)) return {
+			success: false,
+			error: "You do not have permission to restore this resource",
+			details: { code: "OWNERSHIP_DENIED" },
+			status: 403
+		};
+		const item = await repo.restore(id);
+		if (!item) return {
+			success: false,
+			error: "Resource not found",
+			status: 404
+		};
+		return {
+			success: true,
+			data: item,
+			status: 200,
+			meta: { message: "Restored successfully" }
+		};
+	}
+	async getTree(req) {
+		const repo = this.repository;
+		if (!repo.getTree) return {
+			success: false,
+			error: "Tree structure not implemented",
+			status: 501
+		};
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		return {
+			success: true,
+			data: await repo.getTree(options),
+			status: 200
+		};
+	}
+	async getChildren(req) {
+		const repo = this.repository;
+		if (!repo.getChildren) return {
+			success: false,
+			error: "Tree structure not implemented",
+			status: 501
+		};
+		const parentField = this._presetFields.parentField ?? "parent";
+		const parentId = req.params[parentField] ?? req.params.parent ?? req.params.id;
+		const options = this.queryResolver.resolve(req, this.meta(req));
+		return {
+			success: true,
+			data: await repo.getChildren(parentId, options),
+			status: 200
+		};
+	}
+	async bulkCreate(req) {
+		const repo = this.repository;
+		if (!repo.createMany) return {
+			success: false,
+			error: "Repository does not support createMany",
+			status: 501
+		};
+		const items = req.body?.items;
+		if (!items || items.length === 0) return {
+			success: false,
+			error: "Bulk create requires a non-empty items array",
+			status: 400
+		};
+		const created = await repo.createMany(items);
+		return {
+			success: true,
+			data: created,
+			status: 201,
+			meta: { count: created.length }
+		};
+	}
+	async bulkUpdate(req) {
+		const repo = this.repository;
+		if (!repo.updateMany) return {
+			success: false,
+			error: "Repository does not support updateMany",
+			status: 501
+		};
+		const body = req.body;
+		if (!body.filter || Object.keys(body.filter).length === 0) return {
+			success: false,
+			error: "Bulk update requires a non-empty filter",
+			status: 400
+		};
+		if (!body.data || Object.keys(body.data).length === 0) return {
+			success: false,
+			error: "Bulk update requires non-empty data",
+			status: 400
+		};
+		return {
+			success: true,
+			data: await repo.updateMany(body.filter, body.data),
+			status: 200
+		};
+	}
+	async bulkDelete(req) {
+		const repo = this.repository;
+		if (!repo.deleteMany) return {
+			success: false,
+			error: "Repository does not support deleteMany",
+			status: 501
+		};
+		const body = req.body;
+		if (!body.filter || Object.keys(body.filter).length === 0) return {
+			success: false,
+			error: "Bulk delete requires a non-empty filter",
+			status: 400
+		};
+		return {
+			success: true,
+			data: await repo.deleteMany(body.filter),
+			status: 200
+		};
+	}
+};
+//#endregion
+export { AccessControl as i, QueryResolver as n, BodySanitizer as r, BaseController as t };