@classytic/mongokit 3.6.4 → 3.8.0

package/dist/{PaginationEngine-CunXkR9p.mjs → PaginationEngine-C2_tAvAD.mjs}

@@ -1,6 +1,7 @@
-import { a as warn, t as createError } from "./error-Bpbi_NKo.mjs";
-import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-CHToazHy.mjs";
-import { r as validateKeysetSort, t as getPrimaryField } from "./sort-C-BJEWUZ.mjs";
+import { r as warn } from "./logger-DJ7egMnd.mjs";
+import { t as createError } from "./error-Lw9GEAro.mjs";
+import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-J84rR6wG.mjs";
+import { r as validateKeysetSort, t as getPrimaryField } from "./sort-CrZjTK25.mjs";
 //#region src/pagination/utils/index-hint.ts
 /**
 * Read a Mongoose schema's declared indexes, defensively.
@@ -197,6 +198,8 @@ var PaginationEngine = class {
 			maxPage: config.maxPage ?? 1e4,
 			deepPageThreshold: config.deepPageThreshold ?? 100,
 			cursorVersion: config.cursorVersion ?? 1,
+			minCursorVersion: config.minCursorVersion ?? 1,
+			strictKeysetSortFields: config.strictKeysetSortFields,
 			useEstimatedCount: config.useEstimatedCount ?? false
 		};
 	}
@@ -298,7 +301,7 @@ var PaginationEngine = class {
 		const { filters = {}, sort, after, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, readPreference, collation } = options;
 		if (!sort) throw createError(400, "sort is required for keyset pagination");
 		const sanitizedLimit = validateLimit(limit, this.config);
-		const normalizedSort = validateKeysetSort(sort);
+		const normalizedSort = validateKeysetSort(sort, this.config.strictKeysetSortFields);
 		const sortWithoutIdTail = stripTrailingIdTiebreaker(normalizedSort);
 		const filterKeys = Object.keys(filters).filter((k) => !k.startsWith("$"));
 		const effectiveSortFields = Object.keys(sortWithoutIdTail);
@@ -307,7 +310,7 @@ var PaginationEngine = class {
 			warn(`[mongokit] Keyset pagination with filters [${filterKeys.join(", ")}] and sort [${effectiveSortFields.join(", ")}] has no matching schema-declared compound index. For O(1) performance, declare: { ${indexFields.join(", ")} }. (Collection-level indexes created outside the schema are not visible here.)`);
 		}
 		let query = { ...filters };
-		if (after) query = resolveCursorFilter(after, normalizedSort, this.config.cursorVersion, query);
+		if (after) query = resolveCursorFilter(after, normalizedSort, this.config.cursorVersion, query, this.config.minCursorVersion);
 		const effectiveSelect = ensureKeysetSelectIncludesCursorFields(select, normalizedSort);
 		let mongoQuery = this.Model.find(query);
 		if (effectiveSelect) mongoQuery = mongoQuery.select(effectiveSelect);

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-jzO5hMtF.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-DlSAFIc9.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { _ as aggregate_exports, f as delete_exports, h as create_exports, l as read_exports, r as update_exports } from "../update-AVfKWNGt.mjs";
+import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-yjSoNnWy.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { J as Plugin } from "../types-BoH1qdHo.mjs";
+import { Y as Plugin } from "../types-D57SZJeE.mjs";
 import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts
@@ -106,6 +106,28 @@ interface VectorPluginOptions {
    * If not provided, the error propagates and blocks the write.
    */
   onEmbedError?: (error: Error, doc: unknown) => void;
+  /**
+   * SSRF defense for media URLs (`image`, `audio`, entries in `media`).
+   *
+   * If set, only URLs whose origin (`scheme://host[:port]`) matches one of
+   * these entries are forwarded to `embedFn`. Entries can be exact origins
+   * (`https://cdn.example.com`) or wildcard hosts (`https://*.example.com`).
+   * When the allowlist is active, URLs failing validation are dropped with a
+   * warning and the doc is embedded without them (never passed to embedFn).
+   *
+   * Undefined (default) = no allowlist check — same as prior behavior.
+   */
+  allowedMediaOrigins?: string[];
+  /**
+   * When true, reject URLs that resolve to a private, loopback, or
+   * link-local IP literal (e.g., `http://169.254.169.254/…` cloud metadata,
+   * `http://127.0.0.1`, RFC1918 addresses). Hostnames that later resolve to
+   * private IPs via DNS are NOT caught here — that rebinding class of SSRF
+   * must be handled in your network/egress layer.
+   *
+   * Default: `false` (legacy behavior). Flip to `true` for production setups.
+   */
+  blockPrivateIpUrls?: boolean;
 }
 //#endregion
 //#region src/ai/vector.plugin.d.ts

package/dist/ai/index.mjs

@@ -1,3 +1,163 @@
+import { r as warn } from "../logger-DJ7egMnd.mjs";
+//#region src/ai/url-policy.ts
+/**
+* URL policy helpers for the vector plugin media pipeline.
+*
+* Protects callers from passing hostile document URLs straight into an
+* embedding service that may fetch them. The policy is pure / side-effect-
+* free so it can be reused by anyone composing their own embed pipeline.
+*/
+/**
+* Returns true when the string is a safe media URL under the given policy.
+*
+* - Non-URL strings (data URLs, base64 blobs, relative paths) are accepted —
+*   they never trigger an outbound HTTP fetch, so SSRF isn't a concern.
+* - `data:` URLs are accepted.
+* - `http` / `https` URLs must pass:
+*     a) origin allowlist (if `allowedOrigins` is set)
+*     b) private-IP rejection (if `blockPrivateIpUrls` is true)
+*
+* Any parse failure returns `true` only when strict mode is off — a string
+* that doesn't parse as a URL cannot be used to SSRF either. In strict mode
+* (either option set), unparseable http(s)-looking strings are rejected.
+*/
+function isMediaUrlAllowed(value, policy = {}) {
+	if (typeof value !== "string" || value.length === 0) return false;
+	if (value.startsWith("data:")) return true;
+	if (!/^https?:\/\//i.test(value)) return true;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	if (policy.blockPrivateIpUrls && isPrivateOrLocalHost(url.hostname)) return false;
+	if (policy.allowedOrigins && policy.allowedOrigins.length > 0) {
+		const origin = `${url.protocol}//${url.host}`;
+		if (!policy.allowedOrigins.some((entry) => matchesOriginEntry(origin, entry, url))) return false;
+	}
+	return true;
+}
+function matchesOriginEntry(origin, entry, url) {
+	if (!entry) return false;
+	if (entry === origin) return true;
+	const wildcardMatch = entry.match(/^(https?:)\/\/\*\.(.+)$/i);
+	if (wildcardMatch) {
+		const [, entryProtocol, suffix] = wildcardMatch;
+		if (url.protocol.toLowerCase() !== entryProtocol.toLowerCase()) return false;
+		return url.hostname.toLowerCase().endsWith("." + suffix.toLowerCase());
+	}
+	return false;
+}
+/**
+* Literal-IP private/loopback/link-local checks. Does NOT perform DNS
+* resolution — callers who need rebinding-proof behavior must handle that
+* at the HTTP layer.
+*/
+function isPrivateOrLocalHost(hostname) {
+	const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	if (h === "::1" || h.startsWith("fe80:") || h.startsWith("fc") || h.startsWith("fd")) return true;
+	if (h === "localhost" || h === "localhost.localdomain") return true;
+	const ipv4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+	if (!ipv4) return false;
+	const octets = ipv4.slice(1).map(Number);
+	if (octets.some((o) => o < 0 || o > 255)) return false;
+	const [a, b] = octets;
+	if (a === 10) return true;
+	if (a === 127) return true;
+	if (a === 169 && b === 254) return true;
+	if (a === 172 && b >= 16 && b <= 31) return true;
+	if (a === 192 && b === 168) return true;
+	if (a === 0) return true;
+	if (a === 100 && b >= 64 && b <= 127) return true;
+	return false;
+}
+//#endregion
+//#region src/ai/vector-error-hints.ts
+/**
+* Pure classifier. Takes the raw error and the context the plugin knows
+* (index name, dimensions, filter paths it tried to use) and returns a hint.
+*
+* Returns `{ code: 'UNKNOWN', ... }` when no pattern matches — callers
+* should then fall back to rethrowing the original.
+*/
+function classifyVectorSearchError(err, ctx) {
+	const lower = extractErrorMessage(err).toLowerCase();
+	if (lower.includes("unrecognized pipeline stage name: '$vectorsearch'") || lower.includes("unrecognized pipeline stage name: \"$vectorsearch\"") || lower.includes("$vectorsearch is only supported") || lower.includes("$vectorsearch stage is only allowed") || lower.includes("$vectorsearch is only allowed") || lower.includes("unknown top level operator: $vectorsearch") || lower.includes("$vectorsearch") && lower.includes("atlas") && (lower.includes("only") || lower.includes("require"))) return {
+		code: "NOT_ATLAS",
+		summary: "MongoDB did not recognize the `$vectorSearch` stage. This stage is Atlas-only — it doesn't exist on standalone MongoDB, self-hosted Community/Enterprise, or mongodb-memory-server.",
+		hints: [
+			"Run against MongoDB Atlas — create a cluster and point your app at its connection string.",
+			"If you're testing locally, use the integration suite that mocks `$vectorSearch` (see tests/integration/vector-*.test.ts) rather than calling `searchSimilar` directly.",
+			"Atlas Free tier (M0) supports Vector Search as of late 2024; older free tiers do not."
+		]
+	};
+	if (lower.includes("$vectorsearch") && lower.includes("index") || lower.includes("couldn't find index") || lower.includes("search index") && lower.includes("not found") || lower.includes("no such index") || lower.includes("index") && lower.includes(ctx.indexName.toLowerCase())) return {
+		code: "INDEX_NOT_FOUND",
+		summary: `Atlas reported the vector search index "${ctx.indexName}" is not available on the target collection.`,
+		hints: [
+			`Verify an index named "${ctx.indexName}" exists on the collection in the Atlas UI (Search → Indexes) or via \`db.collection.listSearchIndexes()\`.`,
+			`If you just created the index, wait until it reports \`queryable: true\`. Builds typically take 1–3 minutes on new clusters.`,
+			`The index's \`numDimensions\` must match your vector config (${ctx.dimensions}), and \`path\` must match the field name.`
+		]
+	};
+	if (lower.includes("not a supported filter field") || lower.includes("is not a filter field") || lower.includes("filter") && lower.includes("path") && lower.includes("not") || lower.includes("unknown filter path")) return {
+		code: "FILTER_FIELD_NOT_INDEXED",
+		summary: "Atlas rejected the `filter` clause because at least one of its paths is not declared as a `filter`-typed field in the vector search index.",
+		hints: [
+			`Add every path you filter on as \`{ type: "filter", path: "<field>" }\` in the index definition.`,
+			`Paths passed in this call: ${ctx.filterPaths?.length ? ctx.filterPaths.join(", ") : "(none declared)"}.`,
+			`Example for multi-tenant: index must include \`{ type: "filter", path: "tenantId" }\` when you call \`searchSimilar({ filter: { tenantId: "..." } })\`.`
+		]
+	};
+	if (lower.includes("dimension") && (lower.includes("mismatch") || lower.includes("expected"))) return {
+		code: "DIMENSION_MISMATCH",
+		summary: "Atlas rejected the query vector — its length does not match the index definition.",
+		hints: [`Your vectorPlugin config says \`dimensions: ${ctx.dimensions}\`. The Atlas index for "${ctx.indexName}" must declare the same \`numDimensions\`.`, `If the index was created with a different dimension count, re-create it with the correct value (indexes are immutable for dimensions).`]
+	};
+	if (lower.includes("vectorsearch") && (lower.includes("requires") || lower.includes("expected") || lower.includes("missing"))) return {
+		code: "MALFORMED_PIPELINE",
+		summary: "The `$vectorSearch` stage is missing a required argument. This is almost always a mongokit bug — please file an issue with the full error text.",
+		hints: ["Capture the original error (`err.cause`) and attach it to the bug report."]
+	};
+	return {
+		code: "UNKNOWN",
+		summary: "",
+		hints: []
+	};
+}
+/**
+* Wrap an error-producing promise so known-recognizable failures become
+* mongokit errors with hint context. On unrecognized errors, rethrows the
+* original untouched.
+*/
+async function withVectorErrorHints(op, ctx) {
+	try {
+		return await op();
+	} catch (err) {
+		const hint = classifyVectorSearchError(err, ctx);
+		if (hint.code === "UNKNOWN") throw err;
+		const message = `[mongokit:vector] ${hint.summary}\n` + hint.hints.map((h) => `  • ${h}`).join("\n");
+		const wrapped = new Error(message, { cause: err });
+		wrapped.code = hint.code;
+		throw wrapped;
+	}
+}
+function extractErrorMessage(err) {
+	if (typeof err === "string") return err;
+	if (err && typeof err === "object") {
+		const e = err;
+		if (typeof e.message === "string") return e.message;
+		if (typeof e.errmsg === "string") return e.errmsg;
+		try {
+			return JSON.stringify(err);
+		} catch {
+			return String(err);
+		}
+	}
+	return String(err);
+}
+//#endregion
 //#region src/ai/vector.plugin.ts
 /** Maximum numCandidates allowed by Atlas Vector Search */
 const MAX_NUM_CANDIDATES = 1e4;
@@ -28,23 +188,35 @@ function getNestedValue(obj, path) {
 	}, obj);
 }
 /**
-* Builds EmbeddingInput from document source fields
+* Builds EmbeddingInput from document source fields.
+*
+* `urlPolicy` is applied to every media value that looks like an http(s)
+* URL. Values that fail the policy are silently dropped (with a warn log)
+* — never forwarded to the embedding service. Non-URL strings (base64,
+* data URLs, file paths) are untouched.
 */
-function buildInputFromDoc(data, field) {
+function buildInputFromDoc(data, field, urlPolicy = {}) {
 	const input = {};
 	if (field.sourceFields?.length) {
 		const text = field.sourceFields.map((f) => getNestedValue(data, f)).filter(Boolean).join(" ");
 		if (text.trim()) input.text = text;
 	}
+	const policyActive = urlPolicy.allowedOrigins && urlPolicy.allowedOrigins.length > 0 || urlPolicy.blockPrivateIpUrls === true;
+	const screenMediaValue = (mf, value) => {
+		if (!policyActive) return value;
+		if (typeof value !== "string") return value;
+		if (isMediaUrlAllowed(value, urlPolicy)) return value;
+		warn(`[mongokit] vectorPlugin: blocked media URL in field "${mf}" by URL policy`);
+	};
 	if (field.mediaFields?.length) {
 		const firstImageField = field.mediaFields[0];
-		const imageValue = getNestedValue(data, firstImageField);
-		if (typeof imageValue === "string") input.image = imageValue;
+		const screenedImage = screenMediaValue(firstImageField, getNestedValue(data, firstImageField));
+		if (typeof screenedImage === "string") input.image = screenedImage;
 		if (field.mediaFields.length > 1) {
 			input.media = {};
 			for (const mf of field.mediaFields) {
-				const val = getNestedValue(data, mf);
-				if (val != null) input.media[mf] = val;
+				const screened = screenMediaValue(mf, getNestedValue(data, mf));
+				if (screened != null) input.media[mf] = screened;
 			}
 		}
 	}
@@ -88,7 +260,11 @@ function buildVectorSearchPipeline(field, queryVector, params) {
 function vectorPlugin(options) {
 	const { fields, autoEmbed = false } = options;
 	if (!fields?.length) throw new Error("[mongokit] vectorPlugin requires at least one field config");
-	const { embedFn, batchEmbedFn } = options;
+	const { embedFn, batchEmbedFn, allowedMediaOrigins, blockPrivateIpUrls } = options;
+	const urlPolicy = {
+		allowedOrigins: allowedMediaOrigins,
+		blockPrivateIpUrls
+	};
 	return {
 		name: "vector",
 		apply(repo) {
@@ -105,7 +281,11 @@ function vectorPlugin(options) {
 				const pipeline = buildVectorSearchPipeline(field, queryVector, params);
 				const agg = repo.Model.aggregate(pipeline);
 				if (params.session) agg.session(params.session);
-				return (await agg.exec()).map((doc) => {
+				return (await withVectorErrorHints(() => agg.exec(), {
+					indexName: field.index,
+					dimensions: field.dimensions,
+					filterPaths: params.filter ? Object.keys(params.filter) : void 0
+				})).map((doc) => {
 					const score = doc._score ?? 0;
 					const { _score, ...rest } = doc;
 					return {
@@ -133,7 +313,7 @@ function vectorPlugin(options) {
 				};
 				const embedFromSource = async (data, field) => {
 					if (data[field.path] && Array.isArray(data[field.path])) return;
-					const input = buildInputFromDoc(data, field);
+					const input = buildInputFromDoc(data, field, urlPolicy);
 					if (!hasContent(input)) return;
 					const vector = await safeEmbed(input, data);
 					if (vector) data[field.path] = vector;
@@ -143,7 +323,7 @@ function vectorPlugin(options) {
 					for (let i = 0; i < dataArray.length; i++) {
 						const data = dataArray[i];
 						if (data[field.path] && Array.isArray(data[field.path])) continue;
-						const input = buildInputFromDoc(data, field);
+						const input = buildInputFromDoc(data, field, urlPolicy);
 						if (hasContent(input)) toEmbed.push({
 							idx: i,
 							input
@@ -181,7 +361,9 @@ function vectorPlugin(options) {
 						return allFields.length > 0 && contextData && allFields.some((f) => f in contextData);
 					});
 					if (!fieldsToEmbed.length) return;
-					const existing = await repo.Model.findById(context.id).lean().session(context.session ?? null);
+					const idField = repo.idField || "_id";
+					const lookupQuery = idField === "_id" ? { _id: context.id } : { [idField]: context.id };
+					const existing = await repo.Model.findOne(lookupQuery).lean().session(context.session ?? null);
 					if (!existing) return;
 					for (const field of fieldsToEmbed) {
 						const merged = {
@@ -189,7 +371,7 @@ function vectorPlugin(options) {
 							...context.data
 						};
 						delete merged[field.path];
-						const input = buildInputFromDoc(merged, field);
+						const input = buildInputFromDoc(merged, field, urlPolicy);
 						if (!hasContent(input)) continue;
 						const vector = await safeEmbed(input, merged);
 						if (vector) context.data[field.path] = vector;

package/dist/{cursor-CHToazHy.mjs → cursor-J84rR6wG.mjs}

@@ -180,14 +180,18 @@ function validateCursorSort(cursorSort, currentSort) {
 	if (JSON.stringify(cursorSort) !== JSON.stringify(currentSort)) throw new Error("Cursor sort does not match current query sort");
 }
 /**
-* Validates cursor version matches expected version
+* Validates cursor version against the server's expected range.
 *
-* @param cursorVersion - Version from cursor
-* @param expectedVersion - Expected version from config
-* @throws Error if versions don't match
+* - Cursors newer than `expectedVersion` are rejected (client ahead of server).
+* - Cursors older than `minVersion` are rejected (client cached a cursor from
+*   a pre-breaking-change deploy). Default `minVersion = 1` keeps the legacy
+*   "accept anything <= expected" behavior; bump it when you ship a breaking
+*   cursor format change so old clients restart pagination cleanly instead of
+*   silently paginating from the wrong position.
 */
-function validateCursorVersion(cursorVersion, expectedVersion) {
+function validateCursorVersion(cursorVersion, expectedVersion, minVersion = 1) {
 	if (cursorVersion > expectedVersion) throw new Error(`Cursor version ${cursorVersion} is newer than expected version ${expectedVersion}. Please upgrade.`);
+	if (cursorVersion < minVersion) throw new Error(`Cursor version ${cursorVersion} is older than minimum supported ${minVersion}. Pagination must restart.`);
 }
 /**
 * Serializes a value for cursor storage
@@ -232,7 +236,7 @@ function rehydrateValue(serialized, type) {
 * - Base64-encoded cursor tokens (standard cursor)
 * - Cursor version and sort validation
 */
-function resolveCursorFilter(after, sort, cursorVersion, baseFilters = {}) {
+function resolveCursorFilter(after, sort, cursorVersion, baseFilters = {}, minCursorVersion = 1) {
 	if (/^[a-f0-9]{24}$/i.test(after)) {
 		const objectId = new mongoose.Types.ObjectId(after);
 		const idOperator = (sort._id || -1) === 1 ? "$gt" : "$lt";
@@ -242,7 +246,7 @@ function resolveCursorFilter(after, sort, cursorVersion, baseFilters = {}) {
 		};
 	}
 	const cursor = decodeCursor(after);
-	validateCursorVersion(cursor.version, cursorVersion);
+	validateCursorVersion(cursor.version, cursorVersion, minCursorVersion);
 	validateCursorSort(cursor.sort, sort);
 	return buildKeysetFilter(baseFilters, sort, cursor.value, cursor.id, cursor.values);
 }

package/dist/error-Lw9GEAro.mjs

@@ -0,0 +1,46 @@
+//#region src/utils/error.ts
+/**
+* Creates an error with HTTP status code
+*
+* @param status - HTTP status code
+* @param message - Error message
+* @returns Error with status property
+*
+* @example
+* throw createError(404, 'Document not found');
+* throw createError(400, 'Invalid input');
+* throw createError(403, 'Access denied');
+*/
+function createError(status, message) {
+	const error = new Error(message);
+	error.status = status;
+	return error;
+}
+/**
+* Detect and convert a MongoDB E11000 duplicate-key error into
+* a 409 HttpError with an actionable message.
+*
+* PII-safe by default: the error message lists only the conflicting field
+* names, never the values. Structured field names are attached under
+* `error.duplicate.fields` for downstream handlers. Pass
+* `{ exposeValues: true }` to opt into including the values (dev or trusted
+* server-to-server contexts only).
+*
+* Returns `null` when the error is not a duplicate-key error.
+*/
+function parseDuplicateKeyError(error, options = {}) {
+	if (!error || typeof error !== "object") return null;
+	const mongoErr = error;
+	if (mongoErr.code !== 11e3) return null;
+	const fields = mongoErr.keyPattern ? Object.keys(mongoErr.keyPattern) : [];
+	const exposed = options.exposeValues === true;
+	const valuesString = exposed && mongoErr.keyValue ? Object.entries(mongoErr.keyValue).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ") : "";
+	const httpError = createError(409, fields.length ? `Duplicate value for ${fields.join(", ")}${valuesString ? ` (${valuesString})` : ""}` : "Duplicate key error");
+	httpError.duplicate = {
+		fields,
+		...exposed && mongoErr.keyValue ? { values: { ...mongoErr.keyValue } } : {}
+	};
+	return httpError;
+}
+//#endregion
+export { parseDuplicateKeyError as n, createError as t };

package/dist/{index-jzO5hMtF.d.mts → index-DlSAFIc9.d.mts}

@@ -1,4 +1,4 @@
-import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-BoH1qdHo.mjs";
+import { B as MinMaxResult, D as FindOneAndUpdateOptions, G as OperationOptions, H as ObjectId, O as GroupResult, Q as PopulateSpec, _t as UpdateManyResult, a as AnyDocument, b as DeleteResult, ct as SelectSpec, et as ReadPreferenceType, g as CreateOptions, jt as LookupOptions, mt as SortSpec, vt as UpdateOptions, yt as UpdateWithValidationResult } from "./types-D57SZJeE.mjs";
 import { ClientSession, Model, PipelineStage } from "mongoose";
 
 //#region src/actions/aggregate.d.ts
@@ -213,7 +213,7 @@ declare function exists<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<st
   _id: unknown;
 } | null>;
 declare namespace update_d_exports {
-  export { increment, pullFromArray, pushToArray, update, updateByQuery, updateMany, updateWithConstraints, updateWithValidation };
+  export { findOneAndUpdate, increment, pullFromArray, pushToArray, update, updateByQuery, updateMany, updateWithConstraints, updateWithValidation };
 }
 /**
  * Update by ID
@@ -255,6 +255,14 @@ declare function updateMany(Model: Model<unknown>, query: Record<string, unknown
  * Update by query
  */
 declare function updateByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
+/**
+ * Atomic findOneAndUpdate primitive.
+ *
+ * Returns the matched document (post-update by default) or null when no doc
+ * matches and `upsert` is false. Used by outbox relays, distributed locks,
+ * and workflow semaphores that need compare-and-set in a single round-trip.
+ */
+declare function findOneAndUpdate<TDoc = AnyDocument>(Model: Model<TDoc>, filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
 /**
  * Increment field
  */

package/dist/index.d.mts

@@ -1,13 +1,49 @@
-import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-BoH1qdHo.mjs";
-import { t as index_d_exports } from "./index-jzO5hMtF.mjs";
+import { $ as ReadOptions, A as HttpError, At as LookupBuilder, B as MinMaxResult, C as EventPayload, Ct as ValidatorDefinition, D as FindOneAndUpdateOptions, Dt as IControllerResponse, E as FieldRules, Et as IController, F as KeysetPaginationOptions, G as OperationOptions, H as ObjectId, I as KeysetPaginationResult, J as PartialBy, K as PaginationConfig, L as Logger, M as InferRawDoc, N as JsonSchema, O as GroupResult, Ot as IRequestContext, P as KeysOfType, Q as PopulateSpec, R as LookupPopulateOptions, S as EventHandlers, St as ValidationResult, T as FieldPreset, Tt as WithTransactionOptions, U as OffsetPaginationOptions, V as NonNullableFields, W as OffsetPaginationResult, X as PluginFunction, Y as Plugin, Z as PluginType, _ as CrudSchemas, _t as UpdateManyResult, a as AnyDocument, at as RepositoryOptions, b as DeleteResult, bt as UserContext, c as CacheOperationOptions, ct as SelectSpec, d as CacheableOptions, dt as SoftDeleteOptions, et as ReadPreferenceType, f as CascadeOptions, ft as SoftDeleteRepository, g as CreateOptions, gt as UpdateInput, h as CreateInput, ht as Strict, i as AllPluginMethods, it as RepositoryOperation, j as InferDocument, jt as LookupOptions, k as HookMode, kt as IResponseFormatter, l as CacheOptions, lt as SessionOptions, m as CollationOptions, mt as SortSpec, n as AggregatePaginationOptions, nt as RepositoryEvent, o as AnyModel, ot as RequiredBy, p as CascadeRelation, pt as SortDirection, q as PaginationResult, r as AggregatePaginationResult, rt as RepositoryInstance, s as CacheAdapter, st as SchemaBuilderOptions, t as AggregateOptions, tt as RepositoryContext, u as CacheStats, ut as SoftDeleteFilterMode, v as DecodedCursor, vt as UpdateOptions, w as EventPhase, wt as WithPlugins, x as DocField, xt as ValidationChainOptions, y as DeepPartial, yt as UpdateWithValidationResult, z as LookupPopulateResult } from "./types-D57SZJeE.mjs";
+import { t as index_d_exports } from "./index-DlSAFIc9.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, R as BulkWriteResult, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, z as batchOperationsPlugin } from "./validation-chain.plugin-BXx6Ogpp.mjs";
-import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-B19MD38s.mjs";
-import { n as SchemaIndexes } from "./indexes-qIBCZ3mY.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-BvD1NDl9.mjs";
+import { $ as aggregateHelpersPlugin, A as PrefixedIdOptions, B as BatchOperationsMethods, C as methodRegistryPlugin, D as CustomIdOptions, E as elasticSearchPlugin, F as prefixedId, G as AuditQueryOptions, H as batchOperationsPlugin, I as sequentialId, J as AuditTrailOptions, K as AuditQueryResult, L as cascadePlugin, M as customIdPlugin, N as dateSequentialId, O as DateSequentialIdOptions, P as getNextSequence, Q as AggregateHelpersMethods, R as CacheMethods, T as ElasticSearchOptions, U as AuditEntry, V as BulkWriteResult, W as AuditOperation, X as auditTrailPlugin, Y as AuditTrailQuery, Z as auditLogPlugin, _ as observabilityPlugin, a as uniqueField, b as MongoOperationsMethods, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as SequentialIdOptions, k as IdGenerator, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, q as AuditTrailMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MultiTenantOptions, w as fieldFilterPlugin, x as mongoOperationsPlugin, y as multiTenantPlugin, z as cachePlugin } from "./validation-chain.plugin-wGF34Ym-.mjs";
+import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-oM8G4b6m.mjs";
+import { n as SchemaIndexes } from "./indexes-C26GNZRU.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-BZaKOXXI.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 
+//#region src/operations.d.ts
+/**
+ * Where a plugin should inject its scoping filter (multi-tenant scope,
+ * soft-delete filter, etc.) on the RepositoryContext.
+ *
+ * - `data`        — single-doc create payload (`context.data`)
+ * - `dataArray`   — multi-doc create payload (`context.dataArray`)
+ * - `query`       — raw filter (`context.query`); the dominant convention
+ * - `filters`     — paginated list options' filter sub-bag (`context.filters`)
+ * - `operations`  — bulkWrite per-sub-op (special — plugins walk each entry)
+ * - `none`        — no scoping target (op accepts no filter input)
+ */
+type PolicyKey = 'data' | 'dataArray' | 'query' | 'filters' | 'operations' | 'none';
+interface OperationDescriptor {
+  /** Where multi-tenant / soft-delete plugins inject their scoping filter. */
+  policyKey: PolicyKey;
+  /** Whether this op writes to the database. Drives audit + cache invalidation. */
+  mutates: boolean;
+  /** True when `context.id` is populated by the time before/after hooks fire. */
+  hasIdContext: boolean;
+}
+/**
+ * The registry. Order intentionally groups by category for readability.
+ * Adding a new RepositoryOperation requires exactly one entry here, after
+ * which every bundled plugin auto-classifies it correctly.
+ */
+declare const OP_REGISTRY: Readonly<Record<RepositoryOperation, OperationDescriptor>>;
+/** All known repository operations, in registry order. */
+declare const ALL_OPERATIONS: RepositoryOperation[];
+/** Operations that mutate the database. Drives audit + cache invalidation lists. */
+declare const MUTATING_OPERATIONS: readonly RepositoryOperation[];
+/** Operations that don't mutate. Drives default cacheable ops. */
+declare const READ_OPERATIONS: readonly RepositoryOperation[];
+/** Filter ops by their policy injection key. */
+declare function operationsByPolicyKey(key: PolicyKey): RepositoryOperation[];
+//#endregion
 //#region src/query/AggregationBuilder.d.ts
 /** Options for $vectorSearch stage (Atlas only) */
 interface VectorSearchOptions {
@@ -596,15 +632,37 @@ declare class QueryParser {
    */
   private readonly _schemaIndexes;
   /**
-   * Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
-   * Detects:
+   * Regex patterns that can cause catastrophic backtracking (ReDoS attacks).
+   * Detects common footguns:
    * - Quantifiers: {n,m}
    * - Possessive quantifiers: *+, ++, ?+
    * - Nested quantifiers: (a+)+, (a*)*
    * - Backreferences: \1, \2, etc.
    * - Complex character classes: [...]...[...]
+   *
+   * This pattern detector is FAIL-SAFE (on match, the input is escaped), but
+   * it is not exhaustive. {@link _regexComplexityExceedsBudget} complements
+   * it with a deterministic static complexity budget so patterns that happen
+   * to evade the detector still fail over when their unbounded-quantifier
+   * density is pathological.
    */
   private readonly dangerousRegexPatterns;
+  /**
+   * Static complexity budget for user-supplied regex patterns.
+   * Returns `true` if the pattern crosses a budget that empirically correlates
+   * with ReDoS risk — independent of the heuristic regex detector.
+   *
+   * Budget components (any single threshold crossed → over budget):
+   *   - unbounded quantifiers (`*`, `+`, `?`) — hard cap 20
+   *   - nested groups `(` — hard cap 8
+   *   - alternations `|` — hard cap 10
+   *   - combined: (quantifiers * groups) — hard cap 40
+   *
+   * These thresholds are intentionally permissive for legitimate queries and
+   * tight enough to refuse known-pathological patterns like `(a+)+b` with
+   * heavy repetition.
+   */
+  private _regexComplexityExceedsBudget;
   constructor(options?: QueryParserOptions);
   /**
    * Structured view of the configured schema's indexes — geo fields, text
@@ -976,6 +1034,36 @@ declare class Repository<TDoc = unknown> {
    * Update document by ID
    */
   update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
+  /**
+   * Atomic findOneAndUpdate (compare-and-set primitive).
+   *
+   * Single round-trip match-and-mutate for outbox relays, distributed locks,
+   * and workflow semaphores. Goes through the full hook pipeline so
+   * multi-tenant scope, soft-delete, audit, and cache plugins all apply.
+   *
+   * Returns the matched document (post-update by default) or `null` when no
+   * document matches and `upsert` is false.
+   *
+   * @example FIFO claim-lease for an outbox worker
+   * ```ts
+   * const claimed = await outboxRepo.findOneAndUpdate(
+   *   { status: 'pending', leaseExpiresAt: { $lt: new Date() } },
+   *   { $set: { status: 'processing', leaseExpiresAt: leaseUntil, leasedBy: workerId } },
+   *   { sort: { createdAt: 1 }, returnDocument: 'after' },
+   * );
+   * if (!claimed) return; // queue empty
+   * ```
+   *
+   * @example CAS upsert
+   * ```ts
+   * const lock = await locksRepo.findOneAndUpdate(
+   *   { _id: lockKey, ownerId: { $in: [null, workerId] } },
+   *   { $set: { ownerId: workerId, expiresAt: leaseUntil } },
+   *   { upsert: true },
+   * );
+   * ```
+   */
+  findOneAndUpdate<TResult = TDoc>(filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: FindOneAndUpdateOptions): Promise<TResult | null>;
   /**
    * Delete a document by ID.
    *
@@ -1210,4 +1298,4 @@ declare function isTransactionUnsupported(error: Error): boolean;
  */
 declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FieldType, type FilterQuery, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin, withTransaction };