@atscript/db 0.1.102 → 0.1.104

package/dist/index.cjs

@@ -1,9 +1,145 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DXwEzmYJ.cjs");
-const require_db_view = require("./db-view-GcbegVBD.cjs");
+const require_db_view = require("./db-view-Bw_hlrWw.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-f43UcYiY.cjs");
+const require_validator = require("./validator-BSk8lPH1.cjs");
+let node_crypto = require("node:crypto");
 let _uniqu_core = require("@uniqu/core");
+//#region src/encryption.ts
+const ENVELOPE_VERSION = "aes1";
+const ALGORITHM = "aes-256-gcm";
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+const TAG_BYTES = 16;
+/** `aes1$<keyId>$<iv>$<tag>$<ciphertext>` — every segment base64url, keyId [A-Za-z0-9_.-]. */
+const ENVELOPE_RE = /^aes1\$[\w.-]+\$[\w-]+\$[\w-]+\$[\w-]+$/;
+const KEY_ID_RE = /^[\w.-]+$/;
+/**
+* Normalizes key material to a 32-byte Buffer.
+* Accepts: a 32-byte Buffer, a 64-char hex string, a base64/base64url string
+* decoding to 32 bytes, or a raw utf8 string of exactly 32 bytes.
+*/
+function normalizeKey(keyId, material) {
+	if (Buffer.isBuffer(material)) {
+		if (material.length === KEY_BYTES) return material;
+		throw keyInvalid(keyId, `expected ${KEY_BYTES} bytes, got ${material.length}`);
+	}
+	if (typeof material === "string") {
+		if (/^[0-9a-f]{64}$/i.test(material)) return Buffer.from(material, "hex");
+		if (/^[\w+/-]+={0,2}$/.test(material)) {
+			const decoded = Buffer.from(material, "base64");
+			if (decoded.length === KEY_BYTES) return decoded;
+		}
+		const utf8 = Buffer.from(material, "utf8");
+		if (utf8.length === KEY_BYTES) return utf8;
+		throw keyInvalid(keyId, `cannot derive a ${KEY_BYTES}-byte key from the provided string`);
+	}
+	throw keyInvalid(keyId, "key material must be a string or Buffer");
+}
+function keyInvalid(keyId, reason) {
+	return new require_db_error.DbError("ENC_KEY_INVALID", [{
+		path: `encryption.keys.${keyId}`,
+		message: `Invalid encryption key "${keyId}": ${reason}`
+	}]);
+}
+/**
+* AES-256-GCM envelope encryption service for `@db.encrypted` fields.
+*
+* Owned by `DbSpace` and shared across all tables in the space. Values are
+* `JSON.stringify`'d before encryption (type-exact round-trips) and stored as
+* a single ASCII envelope string: `aes1$<keyId>$<iv>$<tag>$<ciphertext>`.
+*
+* Key material is validated eagerly at construction (`ENC_KEY_INVALID`);
+* `resolveKey` lookups are cached per keyId for the process lifetime.
+*/
+var DbEncryption = class {
+	defaultKeyId;
+	onUnencrypted;
+	_keys = /* @__PURE__ */ new Map();
+	_resolveKey;
+	_resolved = /* @__PURE__ */ new Map();
+	constructor(options) {
+		if (!options.defaultKeyId || !KEY_ID_RE.test(options.defaultKeyId)) throw new require_db_error.DbError("ENC_KEY_INVALID", [{
+			path: "encryption.defaultKeyId",
+			message: `Invalid defaultKeyId "${options.defaultKeyId}" — expected a non-empty id matching [A-Za-z0-9_.-]+`
+		}]);
+		this.defaultKeyId = options.defaultKeyId;
+		this.onUnencrypted = options.onUnencrypted ?? "error";
+		this._resolveKey = options.resolveKey;
+		if (options.keys) for (const [keyId, material] of Object.entries(options.keys)) {
+			if (!KEY_ID_RE.test(keyId)) throw keyInvalid(keyId, "key ids must match [A-Za-z0-9_.-]+ (no '$')");
+			this._keys.set(keyId, normalizeKey(keyId, material));
+		}
+		if (!this._keys.has(this.defaultKeyId) && !this._resolveKey) throw new require_db_error.DbError("ENC_KEY_INVALID", [{
+			path: "encryption.defaultKeyId",
+			message: `defaultKeyId "${this.defaultKeyId}" is not in the key registry and no resolveKey() was provided`
+		}]);
+	}
+	/** True when `value` looks like an encryption envelope produced by this service. */
+	isEnvelope(value) {
+		return typeof value === "string" && ENVELOPE_RE.test(value);
+	}
+	/** Encrypts a JSON-serializable value into an envelope string using the default key. */
+	async encrypt(value) {
+		const keyId = this.defaultKeyId;
+		const key = await this._getKey(keyId);
+		const iv = (0, node_crypto.randomBytes)(IV_BYTES);
+		const cipher = (0, node_crypto.createCipheriv)(ALGORITHM, key, iv);
+		const ciphertext = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+		const tag = cipher.getAuthTag();
+		return [
+			ENVELOPE_VERSION,
+			keyId,
+			iv.toString("base64url"),
+			tag.toString("base64url"),
+			ciphertext.toString("base64url")
+		].join("$");
+	}
+	/** Decrypts an envelope string back into its plaintext value. */
+	async decrypt(envelope, ctx) {
+		const parts = envelope.split("$");
+		if (parts.length !== 5 || parts[0] !== ENVELOPE_VERSION) throw this._decryptFailed(ctx, "unknown", "malformed envelope");
+		const [, keyId, ivB64, tagB64, ctB64] = parts;
+		let key;
+		try {
+			key = await this._getKey(keyId);
+		} catch {
+			throw this._decryptFailed(ctx, keyId, `unknown encryption key "${keyId}"`);
+		}
+		try {
+			const iv = Buffer.from(ivB64, "base64url");
+			const tag = Buffer.from(tagB64, "base64url");
+			if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) throw new Error("bad iv/tag length");
+			const decipher = (0, node_crypto.createDecipheriv)(ALGORITHM, key, iv);
+			decipher.setAuthTag(tag);
+			const plaintext = Buffer.concat([decipher.update(Buffer.from(ctB64, "base64url")), decipher.final()]).toString("utf8");
+			return JSON.parse(plaintext);
+		} catch {
+			throw this._decryptFailed(ctx, keyId, "authentication failed or corrupted ciphertext");
+		}
+	}
+	_decryptFailed(ctx, keyId, reason) {
+		const where = ctx?.table || ctx?.field ? ` on ${ctx?.table ?? "?"}.${ctx?.field ?? "?"}` : "";
+		return new require_db_error.DbError("ENC_DECRYPT_FAILED", [{
+			path: ctx?.field ?? "",
+			message: `Decryption failed${where} (keyId: ${keyId}): ${reason}`
+		}]);
+	}
+	_getKey(keyId) {
+		const known = this._keys.get(keyId);
+		if (known) return Promise.resolve(known);
+		let pending = this._resolved.get(keyId);
+		if (!pending) {
+			const resolver = this._resolveKey;
+			if (!resolver) return Promise.reject(keyInvalid(keyId, "not in the key registry"));
+			pending = Promise.resolve().then(() => resolver(keyId)).then((material) => normalizeKey(keyId, material));
+			pending.catch(() => this._resolved.delete(keyId));
+			this._resolved.set(keyId, pending);
+		}
+		return pending;
+	}
+};
+//#endregion
 //#region src/with-optimistic-retry.ts
 /**
 * Runs a read-modify-write loop under optimistic concurrency control (OCC).
@@ -74,15 +210,27 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 */
 var DbSpace = class {
 	adapterFactory;
-	logger;
 	_readables = /* @__PURE__ */ new WeakMap();
 	/** All tables created in this space — used for reverse FK lookup during cascade. */
 	_allTables = /* @__PURE__ */ new Set();
 	/** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
 	_adminAdapter;
-	constructor(adapterFactory, logger = require_db_view.NoopLogger) {
+	logger;
+	/** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
+	_encryption;
+	/**
+	* @param adapterFactory - Creates a fresh adapter per table/view.
+	* @param loggerOrOptions - Either a logger (legacy signature) or a
+	*   {@link TDbSpaceOptions} bag carrying `logger` and/or `encryption`.
+	*/
+	constructor(adapterFactory, loggerOrOptions) {
 		this.adapterFactory = adapterFactory;
-		this.logger = logger;
+		if (loggerOrOptions && typeof loggerOrOptions.error === "function") this.logger = loggerOrOptions;
+		else {
+			const options = loggerOrOptions ?? {};
+			this.logger = options.logger ?? require_db_view.NoopLogger;
+			if (options.encryption) this._encryption = new DbEncryption(options.encryption);
+		}
 	}
 	/**
 	* Auto-detects whether the type is a table or view and returns the
@@ -106,6 +254,7 @@ var DbSpace = class {
 			this._allTables.add(readable);
 			readable.setCascadeResolver((tableName) => this._getCascadeTargets(tableName));
 			readable.setFkLookupResolver((tableName) => this._getFkLookupTarget(tableName));
+			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
 		}
 		return readable;
@@ -118,6 +267,7 @@ var DbSpace = class {
 		let readable = this._readables.get(type);
 		if (!readable) {
 			readable = new require_db_view.AtscriptDbView(type, this.adapterFactory(), logger || this.logger, (t) => this.get(t));
+			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
 		}
 		return readable;
@@ -205,6 +355,7 @@ exports.AtscriptDbTable = require_db_view.AtscriptDbTable;
 exports.AtscriptDbView = require_db_view.AtscriptDbView;
 exports.BaseDbAdapter = require_db_view.BaseDbAdapter;
 exports.CasExhaustedError = require_db_error.CasExhaustedError;
+exports.DbEncryption = DbEncryption;
 exports.DbError = require_db_error.DbError;
 exports.DbSpace = DbSpace;
 exports.DocumentFieldMapper = require_db_view.DocumentFieldMapper;
@@ -215,6 +366,7 @@ exports.NoopLogger = require_db_view.NoopLogger;
 exports.RelationalFieldMapper = require_db_view.RelationalFieldMapper;
 exports.TableMetadata = require_db_view.TableMetadata;
 exports.UniquSelect = require_db_view.UniquSelect;
+exports.assertGeoPoint = require_db_view.assertGeoPoint;
 exports.assertNoVersionWrites = require_db_view.assertNoVersionWrites;
 exports.buildDbValidator = require_validator.buildDbValidator;
 exports.buildValidationContext = require_validator.buildValidationContext;
@@ -229,7 +381,12 @@ exports.decomposePatch = require_db_view.decomposePatch;
 exports.forceNavNonOptional = require_validator.forceNavNonOptional;
 exports.getDbFieldOp = require_ops.getDbFieldOp;
 exports.getKeyProps = require_validator.getKeyProps;
+exports.guardAggregate = require_db_view.guardAggregate;
+exports.guardFilter = require_db_view.guardFilter;
+exports.guardQuery = require_db_view.guardQuery;
 exports.isDbFieldOp = require_ops.isDbFieldOp;
+exports.isGeoIndexableType = require_db_view.isGeoIndexableType;
+exports.isGeoPointType = require_db_view.isGeoPointType;
 exports.isNavRelation = require_validator.isNavRelation;
 Object.defineProperty(exports, "isPrimitive", {
 	enumerable: true,

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { $ as TMetadataOverrides, A as TDbCollation, B as TDbInsertResult, C as TColumnDiff, D as TDbActionIntent, E as TDbActionInfo, F as TDbForeignKey, G as TExistingColumn, H as TDbRelation, I as TDbIndex, J as TFkLookupResolver, K as TExistingTableOption, L as TDbIndexField, M as TDbDefaultValue, N as TDbDeleteResult, O as TDbActionLevel, P as TDbFieldMeta, Q as TMetaResponse, R as TDbIndexType, S as TCascadeTarget, T as TCrudPermissions, U as TDbStorageType, V as TDbReferentialAction, W as TDbUpdateResult, X as TIdDescriptor, Y as TFkLookupTarget, Z as TIdentification, _ as FlatOf, a as FieldMappingStrategy, at as TValueFormatterPair, b as PrimaryKeyOf, c as AggregateExpr, ct as Uniquery, d as AggregateResult, dt as TableMetadata, et as TRelationInfo, f as AtscriptDbWritable, ft as NoopLogger, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as TTableResolver, j as TDbDefaultFn, k as TDbActionProcessor, l as AggregateFn, lt as UniqueryControls, m as DbQuery, mt as UniquSelect, n as DbResponse, nt as TSyncColumnResult, o as BaseDbAdapter, ot as TWriteTableResolver, p as DbControls, pt as TGenericLogger, q as TFieldMeta, r as resolveDesignType, rt as TTableOptionDiff, s as AggregateControls, st as TypedWithRelation, t as AtscriptDbReadable, tt as TSearchIndexInfo, u as AggregateQuery, ut as WithRelation, v as NavPropsOf, w as TCrudOp, x as TCascadeResolver, y as OwnPropsOf, z as TDbInsertManyResult } from "./db-readable-mhPp-MPv.cjs";
+import { $ as TIdentification, A as TDbActionLevel, B as TDbIndexType, C as TCascadeResolver, D as TCrudPermissions, E as TCrudOp, F as TDbDeleteResult, G as TDbStorageType, H as TDbInsertResult, I as TDbFieldMeta, J as TExistingTableOption, K as TDbUpdateResult, L as TDbForeignKey, M as TDbCollation, N as TDbDefaultFn, O as TDbActionInfo, P as TDbDefaultValue, Q as TIdDescriptor, R as TDbIndex, S as PrimaryKeyOf, T as TColumnDiff, U as TDbReferentialAction, V as TDbInsertManyResult, W as TDbRelation, X as TFkLookupResolver, Y as TFieldMeta, Z as TFkLookupTarget, _ as FieldOpsFor, _t as TGenericLogger, a as TDbEncryptionOptions, at as TTableOptionDiff, b as NavPropsOf, c as BaseDbAdapter, ct as TWriteTableResolver, d as AggregateFn, dt as UniqueryControls, et as TMetaResponse, f as AggregateQuery, ft as WithRelation, g as DbQuery, gt as NoopLogger, h as DbControls, ht as isGeoPointType, i as DbEncryption, it as TSyncColumnResult, j as TDbActionProcessor, k as TDbActionIntent, l as AggregateControls, lt as TypedWithRelation, m as AtscriptDbWritable, mt as isGeoIndexableType, n as DbResponse, nt as TRelationInfo, o as DocumentFieldMapper, ot as TTableResolver, p as AggregateResult, pt as TableMetadata, q as TExistingColumn, r as resolveDesignType, rt as TSearchIndexInfo, s as FieldMappingStrategy, st as TValueFormatterPair, t as AtscriptDbReadable, tt as TMetadataOverrides, u as AggregateExpr, ut as Uniquery, v as FilterExpr, vt as UniquSelect, w as TCascadeTarget, x as OwnPropsOf, y as FlatOf, z as TDbIndexField } from "./db-readable-BepVc21V.cjs";
 import { a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateFieldOps, h as separateCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-DJRnNTVo.cjs";
-import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-BhOc9_OO.cjs";
+import { a as TViewColumnMapping, c as AtscriptQueryNode, d as TViewPlan, f as translateQueryTree, h as NativeIntegrity, i as AtscriptDbView, l as AtscriptRef, m as IntegrityStrategy, n as TAdapterFactory, o as AtscriptQueryComparison, p as AtscriptDbTable, r as TDbSpaceOptions, s as AtscriptQueryFieldRef, t as DbSpace, u as TViewJoin } from "./db-space-CWhIEC7E.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
 import { c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-Crqe6vRW.cjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
@@ -81,7 +81,7 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
 }
 //#endregion
 //#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED";
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{
@@ -107,6 +107,36 @@ declare class CasExhaustedError extends DbError {
   constructor(attempts: number, lastSeenVersion: number | undefined);
 }
 //#endregion
+//#region src/query/query-guards.d.ts
+/**
+ * Engine-agnostic query-time guards, applied in the core layer BEFORE filter
+ * translation (field-encryption spec §6, geo-index spec §4.2):
+ *
+ * - filters referencing an `@db.encrypted` field (incl. nested paths into an
+ *   encrypted object) → `ENC_FIELD_FILTER`
+ * - `$sort` on an encrypted field → `ENC_FIELD_SORT`
+ * - `$groupBy` / aggregate refs on an encrypted field → `ENC_FIELD_AGG`
+ * - `$geoWithin` on a non-geoPoint field → `FILTER_TYPE_MISMATCH`
+ * - `$geoWithin` with a malformed circle → `INVALID_QUERY`
+ * - `$geoWithin` on an adapter without geo support → `GEO_NOT_SUPPORTED`
+ */
+/** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
+declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
+/**
+ * Walks a filter expression, rejecting encrypted-field references and
+ * validating `$geoWithin` operator nodes.
+ */
+declare function guardFilter(meta: TableMetadata, adapter: BaseDbAdapter, filter: FilterExpr$1 | undefined, encCode?: "ENC_FIELD_FILTER" | "ENC_FIELD_AGG"): void;
+/** Shared read-path guard: filter + $sort. */
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: {
+  filter?: FilterExpr$1;
+  controls?: {
+    $sort?: unknown;
+  };
+} | undefined): void;
+/** Aggregate-path guard: $groupBy / $select / $having refs + filter + $sort. */
+declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1): void;
+//#endregion
 //#region src/with-optimistic-retry.d.ts
 interface WithOptimisticRetryOptions {
   /** Maximum number of attempts before giving up. Defaults to `5`. */
@@ -185,4 +215,4 @@ declare function decomposePatch(payload: Record<string, unknown>, table: Atscrip
  */
 declare function assertNoVersionWrites(data: Record<string, unknown>, versionColumn: string): void;
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { $ as TMetadataOverrides, A as TDbCollation, B as TDbInsertResult, C as TColumnDiff, D as TDbActionIntent, E as TDbActionInfo, F as TDbForeignKey, G as TExistingColumn, H as TDbRelation, I as TDbIndex, J as TFkLookupResolver, K as TExistingTableOption, L as TDbIndexField, M as TDbDefaultValue, N as TDbDeleteResult, O as TDbActionLevel, P as TDbFieldMeta, Q as TMetaResponse, R as TDbIndexType, S as TCascadeTarget, T as TCrudPermissions, U as TDbStorageType, V as TDbReferentialAction, W as TDbUpdateResult, X as TIdDescriptor, Y as TFkLookupTarget, Z as TIdentification, _ as FlatOf, a as FieldMappingStrategy, at as TValueFormatterPair, b as PrimaryKeyOf, c as AggregateExpr, ct as Uniquery, d as AggregateResult, dt as TableMetadata, et as TRelationInfo, f as AtscriptDbWritable, ft as NoopLogger, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as TTableResolver, j as TDbDefaultFn, k as TDbActionProcessor, l as AggregateFn, lt as UniqueryControls, m as DbQuery, mt as UniquSelect, n as DbResponse, nt as TSyncColumnResult, o as BaseDbAdapter, ot as TWriteTableResolver, p as DbControls, pt as TGenericLogger, q as TFieldMeta, r as resolveDesignType, rt as TTableOptionDiff, s as AggregateControls, st as TypedWithRelation, t as AtscriptDbReadable, tt as TSearchIndexInfo, u as AggregateQuery, ut as WithRelation, v as NavPropsOf, w as TCrudOp, x as TCascadeResolver, y as OwnPropsOf, z as TDbInsertManyResult } from "./db-readable-CXdHBtF6.mjs";
+import { $ as TIdentification, A as TDbActionLevel, B as TDbIndexType, C as TCascadeResolver, D as TCrudPermissions, E as TCrudOp, F as TDbDeleteResult, G as TDbStorageType, H as TDbInsertResult, I as TDbFieldMeta, J as TExistingTableOption, K as TDbUpdateResult, L as TDbForeignKey, M as TDbCollation, N as TDbDefaultFn, O as TDbActionInfo, P as TDbDefaultValue, Q as TIdDescriptor, R as TDbIndex, S as PrimaryKeyOf, T as TColumnDiff, U as TDbReferentialAction, V as TDbInsertManyResult, W as TDbRelation, X as TFkLookupResolver, Y as TFieldMeta, Z as TFkLookupTarget, _ as FieldOpsFor, _t as TGenericLogger, a as TDbEncryptionOptions, at as TTableOptionDiff, b as NavPropsOf, c as BaseDbAdapter, ct as TWriteTableResolver, d as AggregateFn, dt as UniqueryControls, et as TMetaResponse, f as AggregateQuery, ft as WithRelation, g as DbQuery, gt as NoopLogger, h as DbControls, ht as isGeoPointType, i as DbEncryption, it as TSyncColumnResult, j as TDbActionProcessor, k as TDbActionIntent, l as AggregateControls, lt as TypedWithRelation, m as AtscriptDbWritable, mt as isGeoIndexableType, n as DbResponse, nt as TRelationInfo, o as DocumentFieldMapper, ot as TTableResolver, p as AggregateResult, pt as TableMetadata, q as TExistingColumn, r as resolveDesignType, rt as TSearchIndexInfo, s as FieldMappingStrategy, st as TValueFormatterPair, t as AtscriptDbReadable, tt as TMetadataOverrides, u as AggregateExpr, ut as Uniquery, v as FilterExpr, vt as UniquSelect, w as TCascadeTarget, x as OwnPropsOf, y as FlatOf, z as TDbIndexField } from "./db-readable-Ds01ezjj.mjs";
 import { a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateFieldOps, h as separateCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-DJRnNTVo.mjs";
-import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-BYyVZnL1.mjs";
+import { a as TViewColumnMapping, c as AtscriptQueryNode, d as TViewPlan, f as translateQueryTree, h as NativeIntegrity, i as AtscriptDbView, l as AtscriptRef, m as IntegrityStrategy, n as TAdapterFactory, o as AtscriptQueryComparison, p as AtscriptDbTable, r as TDbSpaceOptions, s as AtscriptQueryFieldRef, t as DbSpace, u as TViewJoin } from "./db-space-0U_4PiNS.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
 import { c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-Crqe6vRW.mjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
@@ -81,7 +81,7 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
 }
 //#endregion
 //#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED";
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED" | "VERSION_COLUMN_WRITE" | "CAS_EXHAUSTED" | "ENC_CONFIG_MISSING" | "ENC_KEY_INVALID" | "ENC_NOT_ENCRYPTED" | "ENC_DECRYPT_FAILED" | "ENC_FIELD_FILTER" | "ENC_FIELD_SORT" | "ENC_FIELD_AGG" | "ENC_FIELD_PATCH_OP" | "GEO_INDEX_MISSING" | "GEO_NOT_SUPPORTED" | "FILTER_TYPE_MISMATCH";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{
@@ -107,6 +107,36 @@ declare class CasExhaustedError extends DbError {
   constructor(attempts: number, lastSeenVersion: number | undefined);
 }
 //#endregion
+//#region src/query/query-guards.d.ts
+/**
+ * Engine-agnostic query-time guards, applied in the core layer BEFORE filter
+ * translation (field-encryption spec §6, geo-index spec §4.2):
+ *
+ * - filters referencing an `@db.encrypted` field (incl. nested paths into an
+ *   encrypted object) → `ENC_FIELD_FILTER`
+ * - `$sort` on an encrypted field → `ENC_FIELD_SORT`
+ * - `$groupBy` / aggregate refs on an encrypted field → `ENC_FIELD_AGG`
+ * - `$geoWithin` on a non-geoPoint field → `FILTER_TYPE_MISMATCH`
+ * - `$geoWithin` with a malformed circle → `INVALID_QUERY`
+ * - `$geoWithin` on an adapter without geo support → `GEO_NOT_SUPPORTED`
+ */
+/** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
+declare function assertGeoPoint(point: unknown, path: string): asserts point is [number, number];
+/**
+ * Walks a filter expression, rejecting encrypted-field references and
+ * validating `$geoWithin` operator nodes.
+ */
+declare function guardFilter(meta: TableMetadata, adapter: BaseDbAdapter, filter: FilterExpr$1 | undefined, encCode?: "ENC_FIELD_FILTER" | "ENC_FIELD_AGG"): void;
+/** Shared read-path guard: filter + $sort. */
+declare function guardQuery(meta: TableMetadata, adapter: BaseDbAdapter, query: {
+  filter?: FilterExpr$1;
+  controls?: {
+    $sort?: unknown;
+  };
+} | undefined): void;
+/** Aggregate-path guard: $groupBy / $select / $having refs + filter + $sort. */
+declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1): void;
+//#endregion
 //#region src/with-optimistic-retry.d.ts
 interface WithOptimisticRetryOptions {
   /** Maximum number of attempts before giving up. Defaults to `5`. */
@@ -185,4 +215,4 @@ declare function decomposePatch(payload: Record<string, unknown>, table: Atscrip
  */
 declare function assertNoVersionWrites(data: Record<string, unknown>, versionColumn: string): void;
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };

package/dist/index.mjs

@@ -1,8 +1,144 @@
 import { n as DbError, t as CasExhaustedError } from "./db-error-BHPXOKzc.mjs";
-import { a as ApplicationIntegrity, c as NativeIntegrity, d as RelationalFieldMapper, f as DocumentFieldMapper, g as NoopLogger, h as TableMetadata, i as decomposePatch, l as AtscriptDbReadable, m as UniquSelect, n as AtscriptDbTable, o as BaseDbAdapter, p as FieldMappingStrategy, r as assertNoVersionWrites, s as IntegrityStrategy, t as AtscriptDbView, u as resolveDesignType } from "./db-view-Sq4wCceR.mjs";
+import { S as NoopLogger, _ as FieldMappingStrategy, a as ApplicationIntegrity, b as isGeoIndexableType, c as NativeIntegrity, d as assertGeoPoint, f as guardAggregate, g as DocumentFieldMapper, h as RelationalFieldMapper, i as decomposePatch, l as AtscriptDbReadable, m as guardQuery, n as AtscriptDbTable, o as BaseDbAdapter, p as guardFilter, r as assertNoVersionWrites, s as IntegrityStrategy, t as AtscriptDbView, u as resolveDesignType, v as UniquSelect, x as isGeoPointType, y as TableMetadata } from "./db-view-TyzB5VFb.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps } from "./ops.mjs";
-import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-bLsSgi0N.mjs";
+import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-C7plt6Kf.mjs";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+//#region src/encryption.ts
+const ENVELOPE_VERSION = "aes1";
+const ALGORITHM = "aes-256-gcm";
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+const TAG_BYTES = 16;
+/** `aes1$<keyId>$<iv>$<tag>$<ciphertext>` — every segment base64url, keyId [A-Za-z0-9_.-]. */
+const ENVELOPE_RE = /^aes1\$[\w.-]+\$[\w-]+\$[\w-]+\$[\w-]+$/;
+const KEY_ID_RE = /^[\w.-]+$/;
+/**
+* Normalizes key material to a 32-byte Buffer.
+* Accepts: a 32-byte Buffer, a 64-char hex string, a base64/base64url string
+* decoding to 32 bytes, or a raw utf8 string of exactly 32 bytes.
+*/
+function normalizeKey(keyId, material) {
+	if (Buffer.isBuffer(material)) {
+		if (material.length === KEY_BYTES) return material;
+		throw keyInvalid(keyId, `expected ${KEY_BYTES} bytes, got ${material.length}`);
+	}
+	if (typeof material === "string") {
+		if (/^[0-9a-f]{64}$/i.test(material)) return Buffer.from(material, "hex");
+		if (/^[\w+/-]+={0,2}$/.test(material)) {
+			const decoded = Buffer.from(material, "base64");
+			if (decoded.length === KEY_BYTES) return decoded;
+		}
+		const utf8 = Buffer.from(material, "utf8");
+		if (utf8.length === KEY_BYTES) return utf8;
+		throw keyInvalid(keyId, `cannot derive a ${KEY_BYTES}-byte key from the provided string`);
+	}
+	throw keyInvalid(keyId, "key material must be a string or Buffer");
+}
+function keyInvalid(keyId, reason) {
+	return new DbError("ENC_KEY_INVALID", [{
+		path: `encryption.keys.${keyId}`,
+		message: `Invalid encryption key "${keyId}": ${reason}`
+	}]);
+}
+/**
+* AES-256-GCM envelope encryption service for `@db.encrypted` fields.
+*
+* Owned by `DbSpace` and shared across all tables in the space. Values are
+* `JSON.stringify`'d before encryption (type-exact round-trips) and stored as
+* a single ASCII envelope string: `aes1$<keyId>$<iv>$<tag>$<ciphertext>`.
+*
+* Key material is validated eagerly at construction (`ENC_KEY_INVALID`);
+* `resolveKey` lookups are cached per keyId for the process lifetime.
+*/
+var DbEncryption = class {
+	defaultKeyId;
+	onUnencrypted;
+	_keys = /* @__PURE__ */ new Map();
+	_resolveKey;
+	_resolved = /* @__PURE__ */ new Map();
+	constructor(options) {
+		if (!options.defaultKeyId || !KEY_ID_RE.test(options.defaultKeyId)) throw new DbError("ENC_KEY_INVALID", [{
+			path: "encryption.defaultKeyId",
+			message: `Invalid defaultKeyId "${options.defaultKeyId}" — expected a non-empty id matching [A-Za-z0-9_.-]+`
+		}]);
+		this.defaultKeyId = options.defaultKeyId;
+		this.onUnencrypted = options.onUnencrypted ?? "error";
+		this._resolveKey = options.resolveKey;
+		if (options.keys) for (const [keyId, material] of Object.entries(options.keys)) {
+			if (!KEY_ID_RE.test(keyId)) throw keyInvalid(keyId, "key ids must match [A-Za-z0-9_.-]+ (no '$')");
+			this._keys.set(keyId, normalizeKey(keyId, material));
+		}
+		if (!this._keys.has(this.defaultKeyId) && !this._resolveKey) throw new DbError("ENC_KEY_INVALID", [{
+			path: "encryption.defaultKeyId",
+			message: `defaultKeyId "${this.defaultKeyId}" is not in the key registry and no resolveKey() was provided`
+		}]);
+	}
+	/** True when `value` looks like an encryption envelope produced by this service. */
+	isEnvelope(value) {
+		return typeof value === "string" && ENVELOPE_RE.test(value);
+	}
+	/** Encrypts a JSON-serializable value into an envelope string using the default key. */
+	async encrypt(value) {
+		const keyId = this.defaultKeyId;
+		const key = await this._getKey(keyId);
+		const iv = randomBytes(IV_BYTES);
+		const cipher = createCipheriv(ALGORITHM, key, iv);
+		const ciphertext = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+		const tag = cipher.getAuthTag();
+		return [
+			ENVELOPE_VERSION,
+			keyId,
+			iv.toString("base64url"),
+			tag.toString("base64url"),
+			ciphertext.toString("base64url")
+		].join("$");
+	}
+	/** Decrypts an envelope string back into its plaintext value. */
+	async decrypt(envelope, ctx) {
+		const parts = envelope.split("$");
+		if (parts.length !== 5 || parts[0] !== ENVELOPE_VERSION) throw this._decryptFailed(ctx, "unknown", "malformed envelope");
+		const [, keyId, ivB64, tagB64, ctB64] = parts;
+		let key;
+		try {
+			key = await this._getKey(keyId);
+		} catch {
+			throw this._decryptFailed(ctx, keyId, `unknown encryption key "${keyId}"`);
+		}
+		try {
+			const iv = Buffer.from(ivB64, "base64url");
+			const tag = Buffer.from(tagB64, "base64url");
+			if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) throw new Error("bad iv/tag length");
+			const decipher = createDecipheriv(ALGORITHM, key, iv);
+			decipher.setAuthTag(tag);
+			const plaintext = Buffer.concat([decipher.update(Buffer.from(ctB64, "base64url")), decipher.final()]).toString("utf8");
+			return JSON.parse(plaintext);
+		} catch {
+			throw this._decryptFailed(ctx, keyId, "authentication failed or corrupted ciphertext");
+		}
+	}
+	_decryptFailed(ctx, keyId, reason) {
+		const where = ctx?.table || ctx?.field ? ` on ${ctx?.table ?? "?"}.${ctx?.field ?? "?"}` : "";
+		return new DbError("ENC_DECRYPT_FAILED", [{
+			path: ctx?.field ?? "",
+			message: `Decryption failed${where} (keyId: ${keyId}): ${reason}`
+		}]);
+	}
+	_getKey(keyId) {
+		const known = this._keys.get(keyId);
+		if (known) return Promise.resolve(known);
+		let pending = this._resolved.get(keyId);
+		if (!pending) {
+			const resolver = this._resolveKey;
+			if (!resolver) return Promise.reject(keyInvalid(keyId, "not in the key registry"));
+			pending = Promise.resolve().then(() => resolver(keyId)).then((material) => normalizeKey(keyId, material));
+			pending.catch(() => this._resolved.delete(keyId));
+			this._resolved.set(keyId, pending);
+		}
+		return pending;
+	}
+};
+//#endregion
 //#region src/with-optimistic-retry.ts
 /**
 * Runs a read-modify-write loop under optimistic concurrency control (OCC).
@@ -73,15 +209,27 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 */
 var DbSpace = class {
 	adapterFactory;
-	logger;
 	_readables = /* @__PURE__ */ new WeakMap();
 	/** All tables created in this space — used for reverse FK lookup during cascade. */
 	_allTables = /* @__PURE__ */ new Set();
 	/** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
 	_adminAdapter;
-	constructor(adapterFactory, logger = NoopLogger) {
+	logger;
+	/** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
+	_encryption;
+	/**
+	* @param adapterFactory - Creates a fresh adapter per table/view.
+	* @param loggerOrOptions - Either a logger (legacy signature) or a
+	*   {@link TDbSpaceOptions} bag carrying `logger` and/or `encryption`.
+	*/
+	constructor(adapterFactory, loggerOrOptions) {
 		this.adapterFactory = adapterFactory;
-		this.logger = logger;
+		if (loggerOrOptions && typeof loggerOrOptions.error === "function") this.logger = loggerOrOptions;
+		else {
+			const options = loggerOrOptions ?? {};
+			this.logger = options.logger ?? NoopLogger;
+			if (options.encryption) this._encryption = new DbEncryption(options.encryption);
+		}
 	}
 	/**
 	* Auto-detects whether the type is a table or view and returns the
@@ -105,6 +253,7 @@ var DbSpace = class {
 			this._allTables.add(readable);
 			readable.setCascadeResolver((tableName) => this._getCascadeTargets(tableName));
 			readable.setFkLookupResolver((tableName) => this._getFkLookupTarget(tableName));
+			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
 		}
 		return readable;
@@ -117,6 +266,7 @@ var DbSpace = class {
 		let readable = this._readables.get(type);
 		if (!readable) {
 			readable = new AtscriptDbView(type, this.adapterFactory(), logger || this.logger, (t) => this.get(t));
+			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
 		}
 		return readable;
@@ -189,4 +339,4 @@ function translateQueryTree(node, resolveField) {
 	return { [leftField]: { [comp.op]: comp.right } };
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };