@happyvertical/smrt-core 0.40.69 → 0.40.70

package/dist/collection.js

@@ -3,6 +3,7 @@ import { GlobalInterceptors, createInterceptorContext } from "./interceptors.js"
 import { SmrtClass } from "./class.js";
 import { EmbeddingProvider } from "./embeddings/provider.js";
 import { EmbeddingStorage } from "./embeddings/storage.js";
+import { QueryBoundsError, QueryOrderByError } from "./query-bounds.js";
 import { classnameToTablename, toSnakeCase } from "./utils/naming.js";
 import { verifyPersistenceTable } from "./schema/table-verifier.js";
 import { fieldsFromClass, formatDataJs, toCamelCase } from "./utils.js";
@@ -13,6 +14,40 @@ import { buildWhere } from "@happyvertical/sql";
 //#region src/collection.ts
 var logger = createLogger({ level: "info" });
 /**
+* Validate an optional collection-level list bound (#2367).
+*
+* @returns the bound, or `undefined` when the option was not supplied
+* @throws {QueryBoundsError} when the option is present but not a positive
+*   integer — a `maxListLimit` of `0` or `-1` would silently make every read on
+*   the collection return nothing
+*/
+function assertOptionalListBound(value, optionName) {
+	if (value === void 0) return void 0;
+	if (!Number.isSafeInteger(value) || value < 1) throw new QueryBoundsError(`Invalid ${optionName}: expected a positive integer, got ${String(value)}.`, "INVALID_QUERY_BOUNDS", {
+		optionName,
+		value
+	});
+	return value;
+}
+/**
+* Validate a per-query `limit`/`offset` before it is bound (#2367).
+*
+* `0` is allowed — `LIMIT 0` and `OFFSET 0` are both meaningful — but `NaN`,
+* `Infinity`, negatives and fractions are not: they used to be bound verbatim
+* and surface as a driver-level 500 for what is a caller error.
+*
+* @returns the bound, or `undefined` when the caller supplied none
+* @throws {QueryBoundsError} when the value is not a non-negative integer
+*/
+function assertQueryBound(value, parameterName) {
+	if (value === void 0 || value === null) return void 0;
+	if (!Number.isSafeInteger(value) || value < 0) throw new QueryBoundsError(`Invalid ${parameterName}: expected a non-negative integer, got ${String(value)}.`, "INVALID_QUERY_BOUNDS", {
+		parameterName,
+		value
+	});
+	return value;
+}
+/**
 * Resolve _meta_type in WHERE clause from simple class name to qualified name (Issue #713)
 *
 * This helper function allows queries like { _meta_type: 'Image' } to work correctly
@@ -91,6 +126,13 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	* @private
 	*/
 	_cachedFields = null;
+	/**
+	* Opt-in list bounds (#2367). See {@link SmrtCollectionOptions.defaultListLimit}
+	* and {@link SmrtCollectionOptions.maxListLimit}.
+	* @private
+	*/
+	_defaultListLimit;
+	_maxListLimit;
 	getRegisteredItemClass() {
 		return ObjectRegistry.getClassByConstructor(this._itemClass) || ObjectRegistry.getClass(this._itemClass.name);
 	}
@@ -102,6 +144,135 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 		return registered?.qualifiedName || registered?.name || this._itemClass.name;
 	}
 	/**
+	* Resolve the identifier whitelist and the sensitive-column blocklist that
+	* every caller-supplied identifier on this collection is checked against.
+	*
+	* Extracted from `convertWhereKeys()` so `orderBy` validation enforces the
+	* *same* sets (#2367). `where` (#1540) and `select` (#1902) both rejected
+	* sensitive columns while `orderBy` accepted any identifier, which made
+	* `?orderBy=api_secret&limit=1` an ordering oracle over a column the same
+	* request is forbidden to filter on or project.
+	*
+	* @returns the snake_case identifiers this collection accepts, the sensitive
+	*   names it must refuse, and whether whitelist enforcement applies at all —
+	*   classes with no registered fields (manifest-less inline test classes,
+	*   #869) have nothing to validate against and fall through to SQL.
+	* @private
+	*/
+	collectQueryableFieldNames(fields) {
+		const validFieldNames = new Set(Object.keys(fields).map((f) => toSnakeCase(f)));
+		const sensitiveFieldNames = this.collectSensitiveFieldNames(fields);
+		const readPermissionFieldNames = this.collectReadPermissionFieldNames(fields);
+		validFieldNames.add("id");
+		validFieldNames.add("slug");
+		validFieldNames.add("context");
+		validFieldNames.add("created_at");
+		validFieldNames.add("updated_at");
+		const itemClassName = this.getResolvedItemClassName();
+		const itemQualifiedName = this.getResolvedItemQualifiedName();
+		if (ObjectRegistry.getTableStrategy(itemQualifiedName) === "sti") {
+			validFieldNames.add("_meta_type");
+			validFieldNames.add("meta_type");
+			validFieldNames.add("_meta_data");
+			validFieldNames.add("meta_data");
+			const inheritanceChain = ObjectRegistry.getInheritanceChain(itemQualifiedName);
+			for (const ancestorName of inheritanceChain) {
+				if (ancestorName === "SmrtObject" || ancestorName === "SmrtClass" || ancestorName === itemQualifiedName || ancestorName === itemClassName) continue;
+				const ancestorFields = ObjectRegistry.getFields(ancestorName);
+				for (const fieldName of ancestorFields.keys()) validFieldNames.add(toSnakeCase(fieldName));
+				this.collectSensitiveFieldNames(ancestorFields, sensitiveFieldNames);
+				this.collectReadPermissionFieldNames(ancestorFields, readPermissionFieldNames);
+			}
+			const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
+			if (stiBase) for (const descendant of ObjectRegistry.getDescendants(stiBase)) {
+				const descendantFields = ObjectRegistry.getFields(descendant);
+				this.collectSensitiveFieldNames(descendantFields, sensitiveFieldNames);
+				this.collectReadPermissionFieldNames(descendantFields, readPermissionFieldNames);
+			}
+		}
+		return {
+			readPermissionFieldNames,
+			skipFieldValidation: Object.keys(fields).length === 0,
+			sensitiveFieldNames,
+			validFieldNames
+		};
+	}
+	/**
+	* Build the `ORDER BY` clause for `list()`, validating every term against the
+	* same whitelist and sensitive-column blocklist as `where` and `select`
+	* (#2367).
+	*
+	* `orderBy` is interpolated UNPARAMETERIZED into the identifier position, and
+	* it arrives from the generated REST/MCP/SvelteKit surfaces as caller input.
+	* The identifier regex here has always blocked injection; what it did not
+	* block was ordering by a column the caller may not read. Sorting is a
+	* comparison, and a comparison against a secret is an oracle: repeatedly
+	* requesting `?orderBy=api_secret&limit=1` (with a shrinking `where`) walks
+	* the secret's value ordering without ever serializing the column.
+	*
+	* @param orderBy - one `'<field> [ASC|DESC]'` term or an array of them
+	* @param fields - the collection's cached field definitions
+	* @returns the `' ORDER BY ...'` fragment, or `''` when no ordering was asked
+	*   for
+	* @throws {QueryOrderByError} on a malformed term, an unknown column, or a
+	*   sensitive column — all rendered as a 400 by the generated surfaces
+	* @private
+	*/
+	buildOrderBySql(orderBy, fields) {
+		if (!orderBy) return "";
+		const orderByItems = Array.isArray(orderBy) ? orderBy : [orderBy];
+		if (orderByItems.length === 0) return "";
+		const itemClassName = this.getResolvedItemClassName();
+		const { readPermissionFieldNames, sensitiveFieldNames, skipFieldValidation, validFieldNames } = this.collectQueryableFieldNames(fields);
+		const definitionByColumn = /* @__PURE__ */ new Map();
+		for (const [fieldName, fieldDef] of Object.entries(fields)) definitionByColumn.set(toSnakeCase(fieldName), fieldDef);
+		const customPrimaryKey = this.hasCustomPrimaryKey(fields);
+		const registeredFields = ObjectRegistry.getFields(this.getResolvedItemQualifiedName());
+		const explicitFieldNames = new Set((registeredFields.size > 0 ? registeredFields : ObjectRegistry.getFields(itemClassName)).keys());
+		return ` ORDER BY ${orderByItems.map((item) => {
+			const [field, direction = "ASC"] = String(item).trim().split(/\s+/);
+			if (!/^[a-zA-Z0-9_]+$/.test(field)) throw new QueryOrderByError(`Invalid field name for ordering: ${field}`, `Invalid field name for ordering: ${field}`, "INVALID_ORDER_BY", { field });
+			const normalizedDirection = direction.toUpperCase();
+			if (normalizedDirection !== "ASC" && normalizedDirection !== "DESC") throw new QueryOrderByError(`Invalid sort direction: ${direction}. Must be ASC or DESC.`, `Invalid sort direction: ${direction}. Must be ASC or DESC.`, "INVALID_ORDER_BY", { direction });
+			const strippedName = toSnakeCase(field);
+			const columnName = definitionByColumn.has(strippedName) ? strippedName : this.toDbColumnName(field);
+			if (sensitiveFieldNames.has(columnName) || sensitiveFieldNames.has(field)) throw new QueryOrderByError(`Invalid orderBy field: '${field}'. Ordering by sensitive fields is not allowed.`, `Invalid orderBy field: '${field}'. Ordering by sensitive fields is not allowed.`, "INVALID_ORDER_BY_SENSITIVE", { field });
+			if (readPermissionFieldNames.has(columnName) || readPermissionFieldNames.has(field)) throw new QueryOrderByError(`Invalid orderBy field: '${field}'. Ordering by permission-gated fields is not allowed.`, `Invalid orderBy field: '${field}'. Ordering by permission-gated fields is not allowed.`, "INVALID_ORDER_BY_RESTRICTED", { field });
+			if (!skipFieldValidation && !validFieldNames.has(columnName)) throw new QueryOrderByError(`Invalid orderBy field: '${field}'. Field does not exist on ${itemClassName}. Valid fields: ${Array.from(validFieldNames).sort().join(", ")}`, `Invalid orderBy field: '${field}'.`, "INVALID_ORDER_BY_UNKNOWN_FIELD", {
+				field,
+				itemClassName
+			});
+			const fieldDef = definitionByColumn.get(columnName);
+			const fieldType = fieldDef?.type;
+			const isTransient = fieldDef?.transient === true || fieldDef?._meta?.transient === true;
+			if (fieldType === "meta" || fieldType === "oneToMany" || fieldType === "manyToMany" || isTransient || this.isOmittedCustomPrimaryKeySystemField(columnName, customPrimaryKey, explicitFieldNames)) throw new QueryOrderByError(`Invalid orderBy field: '${field}'. Field is not column-backed on ${itemClassName}.`, `Invalid orderBy field: '${field}'. Field is not column-backed.`, "INVALID_ORDER_BY_NOT_COLUMN_BACKED", {
+				field,
+				itemClassName
+			});
+			return `${columnName} ${normalizedDirection}`;
+		}).join(", ")}`;
+	}
+	/**
+	* Apply this collection's configured list bounds (#2367).
+	*
+	* Both bounds are opt-in (`defaultListLimit` / `maxListLimit` collection
+	* options) and default to unset. `list()` is the framework's bulk-read
+	* primitive — relationship loaders, junction hydration and `listByIds()` all
+	* go through it expecting every matching row — so a framework-wide implicit
+	* default would silently truncate correct queries instead of bounding an
+	* attack surface. The generated surfaces, where untrusted input actually
+	* arrives, apply {@link DEFAULT_LIST_LIMIT}/{@link MAX_LIST_LIMIT}
+	* unconditionally; an application that wants the same ceiling on its own
+	* programmatic reads sets `maxListLimit` when constructing the collection.
+	*
+	* @private
+	*/
+	applyListBounds(limit) {
+		const effective = limit ?? this._defaultListLimit;
+		if (effective === void 0) return void 0;
+		return this._maxListLimit === void 0 ? effective : Math.min(effective, this._maxListLimit);
+	}
+	/**
 	* Convert WHERE clause field names from camelCase to snake_case while preserving operators.
 	* Validates operators and field names to prevent SQL injection and invalid queries.
 	*
@@ -131,31 +302,8 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 		];
 		const UNSUPPORTED_OPERATOR_HINTS = /* @__PURE__ */ new Map([["contains", "Use 'like' with explicit wildcards instead, e.g. { 'name like': '%term%' }."]]);
 		const fields = this.getFieldsSync();
-		const validFieldNames = new Set(Object.keys(fields).map((f) => toSnakeCase(f)));
-		const sensitiveFieldNames = this.collectSensitiveFieldNames(fields);
-		validFieldNames.add("id");
-		validFieldNames.add("slug");
-		validFieldNames.add("context");
-		validFieldNames.add("created_at");
-		validFieldNames.add("updated_at");
 		const itemClassName = this.getResolvedItemClassName();
-		const itemQualifiedName = this.getResolvedItemQualifiedName();
-		if (ObjectRegistry.getTableStrategy(itemQualifiedName) === "sti") {
-			validFieldNames.add("_meta_type");
-			validFieldNames.add("meta_type");
-			validFieldNames.add("_meta_data");
-			validFieldNames.add("meta_data");
-			const inheritanceChain = ObjectRegistry.getInheritanceChain(itemQualifiedName);
-			for (const ancestorName of inheritanceChain) {
-				if (ancestorName === "SmrtObject" || ancestorName === "SmrtClass" || ancestorName === itemQualifiedName || ancestorName === itemClassName) continue;
-				const ancestorFields = ObjectRegistry.getFields(ancestorName);
-				for (const fieldName of ancestorFields.keys()) validFieldNames.add(toSnakeCase(fieldName));
-				this.collectSensitiveFieldNames(ancestorFields, sensitiveFieldNames);
-			}
-			const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
-			if (stiBase) for (const descendant of ObjectRegistry.getDescendants(stiBase)) this.collectSensitiveFieldNames(ObjectRegistry.getFields(descendant), sensitiveFieldNames);
-		}
-		const skipFieldValidation = !(Object.keys(fields).length > 0);
+		const { sensitiveFieldNames, skipFieldValidation, validFieldNames } = this.collectQueryableFieldNames(fields);
 		const converted = {};
 		if (Object.hasOwn(where, "__proto__") || Object.hasOwn(where, "constructor") || Object.hasOwn(where, "prototype")) throw new Error("Invalid WHERE clause: Prototype pollution attempts are not allowed. Detected dangerous properties in WHERE clause.");
 		for (const [key, value] of Object.entries(where)) {
@@ -212,6 +360,23 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 		}
 		return target;
 	}
+	/**
+	* The `collectSensitiveFieldNames` sibling for `@field({ readPermission })`
+	* columns (#2367).
+	*
+	* These are per-caller redacted by `toPublicJSON()` and refused outright by
+	* `select`, so an ordering over one leaks comparisons about a value the
+	* caller may not read. `list()` has no permission context, so — exactly as
+	* `select` does — they are refused unconditionally rather than conditionally.
+	*/
+	collectReadPermissionFieldNames(fieldMap, target = /* @__PURE__ */ new Set()) {
+		const entries = fieldMap instanceof Map ? fieldMap.entries() : Object.entries(fieldMap);
+		for (const [fieldName, fieldDef] of entries) if (this.getReadPermissionFieldDefinition(fieldDef) !== void 0) {
+			target.add(toSnakeCase(fieldName));
+			target.add(fieldName);
+		}
+		return target;
+	}
 	hasCustomPrimaryKey(fields) {
 		return Object.values(fields).some((fieldDef) => fieldDef.primaryKey === true || fieldDef._meta?.primaryKey === true);
 	}
@@ -337,6 +502,8 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	*/
 	constructor(options = {}) {
 		super(options);
+		this._defaultListLimit = assertOptionalListBound(options.defaultListLimit, "defaultListLimit");
+		this._maxListLimit = assertOptionalListBound(options.maxListLimit, "maxListLimit");
 		const collectionCtor = this.constructor;
 		if (this.constructor !== SmrtCollection && collectionCtor._itemClass) {
 			const itemClass = collectionCtor._itemClass;
@@ -370,14 +537,16 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	* ```
 	*/
 	static async create(options = {}) {
-		const { _className, db, persistence, ai, fs, logging, metrics, pubsub, sanitization, signals } = options;
+		const { _className, db, defaultListLimit, persistence, ai, fs, logging, maxListLimit, metrics, pubsub, sanitization, signals } = options;
 		const collectionOptions = {
 			_className,
 			db,
 			persistence,
 			ai,
+			defaultListLimit,
 			fs,
 			logging,
+			maxListLimit,
 			metrics,
 			pubsub,
 			sanitization,
@@ -472,8 +641,18 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	* This is a convenience method that avoids N+1 queries when you have
 	* a list of IDs and need to fetch the corresponding records.
 	*
+	* The id list is chunked at `IN_LIST_CHUNK_SIZE` (#2367). `collection.list()`
+	* expands an array-valued WHERE into one `id IN (?, ?, ...)` clause and does
+	* not chunk it, so an unbounded caller-sized array hits the backend's
+	* bind-variable ceiling — `SQLITE_MAX_VARIABLE_NUMBER` (999 pre-3.32, 32766
+	* after) or PostgreSQL's 65535 — and the whole query fails before it runs.
+	* The relationship, junction and hierarchy loaders have chunked at this value
+	* for exactly this reason; `listByIds()` is the remaining path that took ids
+	* straight from the caller and did not.
+	*
 	* @param ids - Array of UUIDs to fetch
-	* @returns Promise resolving to array of objects (order not guaranteed)
+	* @returns Promise resolving to array of objects (order not guaranteed;
+	*   results are concatenated in chunk order)
 	*
 	* @example
 	* ```typescript
@@ -482,7 +661,17 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	*/
 	async listByIds(ids) {
 		if (ids.length === 0) return [];
-		return this.list({ where: { id: ids } });
+		const chunks = chunkArray(ids, this._maxListLimit === void 0 ? 900 : Math.min(900, this._maxListLimit));
+		if (chunks.length === 1) return this.list({
+			limit: chunks[0].length,
+			where: { id: chunks[0] }
+		});
+		const results = [];
+		for (const idChunk of chunks) results.push(...await this.list({
+			limit: idChunk.length,
+			where: { id: idChunk }
+		}));
+		return results;
 	}
 	/**
 	* Resolve the effective cache config for a read (issue #1498).
@@ -576,7 +765,7 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 			};
 		}
 		const { sql: whereSql, values: whereValues } = buildWhere(this.convertWhereKeys(where));
-		const fullSQL = `SELECT * FROM ${this.tableName} ${whereSql}`;
+		const fullSQL = `SELECT * FROM ${this.tableName} ${whereSql} LIMIT 1`;
 		const rows = await this.queryRowsWithCache(fullSQL, whereValues, this.resolveReadCacheConfig(options.cache));
 		if (!rows?.[0]) return await GlobalInterceptors.executeAfterGet(itemClassName, null, interceptorContext);
 		const fields = this.getFieldsSync();
@@ -603,27 +792,19 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 		const fields = this.getFieldsSync();
 		const projection = select !== void 0 ? this.resolveProjectionSelect(select, fields, isSTI) : void 0;
 		if (projection && interceptedOptions.include && interceptedOptions.include.length > 0) throw new Error("collection.list({ select }) returns plain projection rows and cannot eager-load relationships. Remove include or omit select.");
-		let orderBySql = "";
-		if (orderBy) {
-			orderBySql = " ORDER BY ";
-			orderBySql += (Array.isArray(orderBy) ? orderBy : [orderBy]).map((item) => {
-				const [field, direction = "ASC"] = item.split(" ");
-				if (!/^[a-zA-Z0-9_]+$/.test(field)) throw new Error(`Invalid field name for ordering: ${field}`);
-				const normalizedDirection = direction.toUpperCase();
-				if (normalizedDirection !== "ASC" && normalizedDirection !== "DESC") throw new Error(`Invalid sort direction: ${direction}. Must be ASC or DESC.`);
-				return `${toSnakeCase(field)} ${normalizedDirection}`;
-			}).join(", ");
-		}
+		const orderBySql = this.buildOrderBySql(orderBy, fields);
 		let limitOffsetSql = "";
 		const limitOffsetValues = [];
 		let paramIndex = whereValues.length + 1;
-		if (limit !== void 0) {
+		const boundedLimit = this.applyListBounds(assertQueryBound(limit, "limit"));
+		const boundedOffset = assertQueryBound(offset, "offset");
+		if (boundedLimit !== void 0) {
 			limitOffsetSql += ` LIMIT $${paramIndex++}`;
-			limitOffsetValues.push(limit);
+			limitOffsetValues.push(boundedLimit);
 		}
-		if (offset !== void 0) {
+		if (boundedOffset !== void 0) {
 			limitOffsetSql += ` OFFSET $${paramIndex++}`;
-			limitOffsetValues.push(offset);
+			limitOffsetValues.push(boundedOffset);
 		}
 		const sql = `SELECT ${projection ? projection.sql : "*"} FROM ${this.tableName} ${whereSql} ${orderBySql} ${limitOffsetSql}`;
 		const params = [...whereValues, ...limitOffsetValues];