@proteinjs/db 1.35.0 → 1.36.0

package/dist/src/encryption/EncryptedColumns.js

@@ -0,0 +1,286 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptedColumns = void 0;
+var util_1 = require("@proteinjs/util");
+var Table_1 = require("../Table");
+var Record_1 = require("../Record");
+var Columns_1 = require("../Columns");
+var DbEncryptionConfig_1 = require("./DbEncryptionConfig");
+var EncryptionDerivedTableRegistry_1 = require("./EncryptionDerivedTableRegistry");
+/**
+ * The schema side of column encryption (`ColumnOptions.encrypted`): validation of the
+ * declaration, and derivation of the physical schema an encrypted column needs —
+ * automatically, at the framework seam, never by callers:
+ *
+ * - the ciphertext column itself widens to STRING(MAX) (envelopes outgrow declared widths);
+ * - `searchable: 'equality'` derives an indexed whole-value fingerprint companion column
+ *   (`<column>_enc_eq`); a `unique` declaration on the base column moves onto it (per-owner
+ *   value uniqueness — fingerprints are keyed per owner);
+ * - `searchable: 'contains'` derives a companion search-token TABLE (`<table>_enc_tok`) —
+ *   a plain indexed inverted index, portable across drivers (Spanner's native search
+ *   indexes are a named later optimization at the driver layer);
+ * - `sortKey: { revealPrefix: N }` derives an ordered-prefix companion column
+ *   (`<column>_enc_srt`) for native ORDER BY — the declared bounded reveal.
+ *
+ * `ensureSchema` is idempotent and runs wherever the physical schema is consulted
+ * (TableManager, the record serializer, the query translator).
+ */
+var EncryptedColumns = /** @class */ (function () {
+    function EncryptedColumns() {
+    }
+    /** Validate declarations and inject the derived physical schema (idempotent). */
+    EncryptedColumns.prototype.ensureSchema = function (table) {
+        if (table[EncryptedColumns.SCHEMA_APPLIED_MARKER]) {
+            return;
+        }
+        var hasContainsColumns = false;
+        var _loop_1 = function (prop) {
+            var column = table.columns[prop];
+            var config = this_1.validateDeclaration(table, prop, column);
+            if (!config) {
+                return "continue";
+            }
+            if (typeof column.maxLength !== 'undefined') {
+                // Envelopes outgrow the declared plaintext width; the physical column is MAX.
+                column.maxLength = 'MAX';
+            }
+            if (config.searchable === 'equality') {
+                this_1.injectEqualityCompanion(table, prop, column);
+            }
+            if (config.searchable === 'contains') {
+                hasContainsColumns = true;
+            }
+            if (config.sortKey) {
+                this_1.injectSortCompanion(table, prop, column, config.sortKey.revealPrefix);
+            }
+            // The column's QUERY-side contract (`Column.queryTransform` — the parallel of the
+            // storage-side serialize/deserialize seam), DERIVED from the declaration at this
+            // framework seam, never caller-declared. `QueryBuilder.applyColumnTransforms`
+            // consults it on every query. Call-time require: the transform pulls the key-store
+            // stack, which sits beside Db in the module graph.
+            column.queryTransform = function (runtime) {
+                var EncryptedColumnQueryTransform = 
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                require('./EncryptedColumnQueryTransform').EncryptedColumnQueryTransform;
+                return new EncryptedColumnQueryTransform(table, prop, column, config, runtime);
+            };
+        };
+        var this_1 = this;
+        for (var _i = 0, _a = Object.keys(table.columns); _i < _a.length; _i++) {
+            var prop = _a[_i];
+            _loop_1(prop);
+        }
+        if (hasContainsColumns) {
+            EncryptionDerivedTableRegistry_1.EncryptionDerivedTableRegistry.register(this.tokenTableShape(table));
+        }
+        // Marked only after full success: a validation throw above must re-validate (and
+        // re-throw, loudly) on every subsequent use, never half-apply.
+        table[EncryptedColumns.SCHEMA_APPLIED_MARKER] = true;
+    };
+    /**
+     * The mandatory-declaration gate (`DbEncryptionConfig.requireEncryptedDeclarations`):
+     * every text-holding column must declare `encrypted` (`false` or a config object), so no
+     * column can be added without deciding, and the encrypted set can never silently drift.
+     * Identifier-bearing column classes (uuids, references) are metadata by construction and
+     * are exempt.
+     */
+    EncryptedColumns.prototype.validateDeclarations = function (table) {
+        var _a;
+        var undeclared = [];
+        for (var _i = 0, _b = Object.keys(table.columns); _i < _b.length; _i++) {
+            var prop = _b[_i];
+            var column = table.columns[prop];
+            if (!this.isTextColumn(column) || this.isInternalColumn(column)) {
+                continue;
+            }
+            if (typeof ((_a = column.options) === null || _a === void 0 ? void 0 : _a.encrypted) === 'undefined') {
+                undeclared.push("".concat(prop, " ('").concat(column.name, "')"));
+            }
+        }
+        if (undeclared.length > 0) {
+            throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ") Every text-holding column must declare 'encrypted' (false, or a config ") +
+                "object such as {} or { searchable: 'contains' }). Missing declarations: ".concat(undeclared.join(', ')));
+        }
+    };
+    /** The `encrypted` config object for a column property, or undefined when not encrypted. */
+    EncryptedColumns.prototype.configFor = function (table, prop) {
+        var _a;
+        var column = table.columns[prop];
+        var encrypted = (_a = column === null || column === void 0 ? void 0 : column.options) === null || _a === void 0 ? void 0 : _a.encrypted;
+        return encrypted && typeof encrypted === 'object' ? encrypted : undefined;
+    };
+    /** Property names of this table's encrypted columns. */
+    EncryptedColumns.prototype.encryptedProps = function (table) {
+        var _this = this;
+        return Object.keys(table.columns).filter(function (prop) { return !!_this.configFor(table, prop); });
+    };
+    /** Property names declared `searchable: 'contains'`. */
+    EncryptedColumns.prototype.containsProps = function (table) {
+        var _this = this;
+        return this.encryptedProps(table).filter(function (prop) { return _this.configFor(table, prop).searchable === 'contains'; });
+    };
+    /** Does this write payload touch any encrypted column? */
+    EncryptedColumns.prototype.recordTouchesEncryptedColumns = function (table, record) {
+        return this.encryptedProps(table).some(function (prop) { return typeof record[prop] !== 'undefined'; });
+    };
+    EncryptedColumns.prototype.hasEncryptedColumns = function (table) {
+        return this.encryptedProps(table).length > 0;
+    };
+    /** The derived search-token table for `table`, or undefined when nothing is `contains`-searchable. */
+    EncryptedColumns.prototype.tokenTableFor = function (table) {
+        this.ensureSchema(table);
+        return EncryptionDerivedTableRegistry_1.EncryptionDerivedTableRegistry.get(this.tokenTableName(table));
+    };
+    EncryptedColumns.prototype.tokenTableName = function (table) {
+        return "".concat(table.name, "_enc_tok");
+    };
+    /** Companion property names EQUAL their column names (several seams assume prop == name). */
+    EncryptedColumns.prototype.eqCompanionProp = function (table, prop) {
+        return "".concat(table.columns[prop].name, "_enc_eq");
+    };
+    EncryptedColumns.prototype.sortCompanionProp = function (table, prop) {
+        return "".concat(table.columns[prop].name, "_enc_srt");
+    };
+    /** Framework-derived companion columns are dropped from deserialized records and exempt from declaration checks. */
+    EncryptedColumns.prototype.isInternalColumn = function (column) {
+        return !!column[EncryptedColumns.INTERNAL_COLUMN_MARKER];
+    };
+    EncryptedColumns.prototype.validateDeclaration = function (table, prop, column) {
+        var _a, _b, _c;
+        var encrypted = (_a = column.options) === null || _a === void 0 ? void 0 : _a.encrypted;
+        if (typeof encrypted === 'undefined' || encrypted === false) {
+            return undefined;
+        }
+        if (typeof encrypted !== 'object') {
+            throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ".").concat(prop, ") 'encrypted' must be false or a config object ") +
+                "(e.g. {}, { searchable: 'contains' }); got: ".concat(JSON.stringify(encrypted)));
+        }
+        if (!this.isTextColumn(column)) {
+            throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ".").concat(prop, ") 'encrypted' is only supported on text columns (StringColumn family). ") +
+                "Identifier and reference columns are metadata by construction; JSON-typed columns must use a " +
+                "string-serialized column type to encrypt.");
+        }
+        if (encrypted.searchable && encrypted.searchable !== 'contains' && encrypted.searchable !== 'equality') {
+            throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ".").concat(prop, ") encrypted.searchable must be 'contains' or 'equality'; ") +
+                "got: ".concat(JSON.stringify(encrypted.searchable)));
+        }
+        if ((encrypted.searchable || encrypted.sortKey) && (0, util_1.isInstanceOf)(column, Columns_1.ObjectColumn)) {
+            throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ".").concat(prop, ") encrypted.searchable / encrypted.sortKey require a plain string column ") +
+                "(the search and sort derivatives cover the value's text, not its serialization). " +
+                "Object/array columns may declare encrypted: {} (encrypted, never queried by value).");
+        }
+        if (encrypted.sortKey) {
+            var revealPrefix = encrypted.sortKey.revealPrefix;
+            if (!Number.isInteger(revealPrefix) || revealPrefix < 1) {
+                throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ".").concat(prop, ") encrypted.sortKey.revealPrefix must be a positive integer ") +
+                    "(the number of leading characters whose order the sort column reveals); " +
+                    "got: ".concat(JSON.stringify(revealPrefix)));
+            }
+        }
+        if (((_c = (_b = column.options) === null || _b === void 0 ? void 0 : _b.unique) === null || _c === void 0 ? void 0 : _c.unique) && encrypted.searchable !== 'equality') {
+            throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ".").concat(prop, ") a unique constraint on an encrypted column requires ") +
+                "encrypted: { searchable: 'equality' } \u2014 uniqueness is enforced through a unique index on " +
+                "the whole-value fingerprint (ciphertext is never equal, so a unique index on it cannot bite).");
+        }
+        return encrypted;
+    };
+    EncryptedColumns.prototype.injectEqualityCompanion = function (table, prop, column) {
+        var _a, _b;
+        var companionProp = "".concat(column.name, "_enc_eq");
+        var baseUnique = ((_b = (_a = column.options) === null || _a === void 0 ? void 0 : _a.unique) === null || _b === void 0 ? void 0 : _b.unique) === true;
+        var companion = new Columns_1.StringColumn("".concat(column.name, "_enc_eq"), __assign(__assign({ nullable: true }, (baseUnique ? { unique: { unique: true, indexName: "".concat(table.name, "_").concat(column.name, "_enc_eq_unique") } } : {})), { ui: { hidden: true } }), 64);
+        this.injectCompanionColumn(table, companionProp, companion);
+        if (baseUnique) {
+            // Uniqueness moves to the fingerprint column (see validateDeclaration).
+            delete column.options.unique;
+        }
+        else {
+            table.indexes.push({
+                columns: [companionProp],
+                name: "".concat(table.name, "_").concat(column.name, "_enc_eq_idx"),
+            });
+        }
+    };
+    EncryptedColumns.prototype.injectSortCompanion = function (table, prop, column, revealPrefix) {
+        var companion = new Columns_1.StringColumn("".concat(column.name, "_enc_srt"), { nullable: true, ui: { hidden: true } }, Math.max(revealPrefix, 1));
+        this.injectCompanionColumn(table, "".concat(column.name, "_enc_srt"), companion);
+    };
+    EncryptedColumns.prototype.injectCompanionColumn = function (table, companionProp, companion) {
+        if (table.columns[companionProp] && !this.isInternalColumn(table.columns[companionProp])) {
+            throw new DbEncryptionConfig_1.EncryptedColumnConfigError("(".concat(table.name, ") Column property '").concat(companionProp, "' collides with a framework-derived ") +
+                "encryption companion column. Rename the declared column.");
+        }
+        companion[EncryptedColumns.INTERNAL_COLUMN_MARKER] = true;
+        table.columns[companionProp] = companion;
+    };
+    /**
+     * The token table's SHAPE for `table`, independent of registration — the lifecycle
+     * walker's decrypt-out sweep needs it after the config stopped declaring any
+     * `searchable: 'contains'` column (when `tokenTableFor` no longer resolves).
+     */
+    EncryptedColumns.prototype.tokenTableShape = function (table) {
+        var tokenTableName = this.tokenTableName(table);
+        var tokenTable = new (/** @class */ (function (_super) {
+            __extends(class_1, _super);
+            function class_1() {
+                var _this = _super !== null && _super.apply(this, arguments) || this;
+                _this.name = tokenTableName;
+                _this.columns = (0, Record_1.withRecordColumns)({
+                    recordId: new Columns_1.StringColumn('record_id', { nullable: false }, 36),
+                    columnName: new Columns_1.StringColumn('column_name', { nullable: false }, 128),
+                    token: new Columns_1.StringColumn('token', { nullable: false }, 64),
+                });
+                _this.indexes = [
+                    { columns: ['token', 'columnName'], name: "".concat(tokenTableName, "_cover_idx") },
+                    { columns: ['recordId'], name: "".concat(tokenTableName, "_record_idx") },
+                ];
+                return _this;
+                // No auth block: default-deny for non-system callers; only framework system paths
+                // (EncryptionTokenMaintenance, the query translator's subqueries) touch token rows.
+            }
+            return class_1;
+        }(Table_1.Table)))();
+        return tokenTable;
+    };
+    EncryptedColumns.prototype.isTextColumn = function (column) {
+        if (!(0, util_1.isInstanceOf)(column, Columns_1.StringColumn)) {
+            return false;
+        }
+        return !((0, util_1.isInstanceOf)(column, Columns_1.UuidColumn) ||
+            (0, util_1.isInstanceOf)(column, Columns_1.ReferenceColumn) ||
+            (0, util_1.isInstanceOf)(column, Columns_1.ReferenceArrayColumn) ||
+            (0, util_1.isInstanceOf)(column, Columns_1.DynamicReferenceColumn) ||
+            (0, util_1.isInstanceOf)(column, Columns_1.DynamicReferenceTableNameColumn));
+    };
+    EncryptedColumns.SCHEMA_APPLIED_MARKER = '__encSchemaApplied';
+    EncryptedColumns.INTERNAL_COLUMN_MARKER = '__encInternalColumn';
+    return EncryptedColumns;
+}());
+exports.EncryptedColumns = EncryptedColumns;
+//# sourceMappingURL=EncryptedColumns.js.map

package/dist/src/encryption/EncryptedColumns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptedColumns.js","sourceRoot":"","sources":["../../../src/encryption/EncryptedColumns.ts"],"names":[],"mappings":"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"}

package/dist/src/encryption/EncryptionDerivedTableRegistry.d.ts

@@ -0,0 +1,20 @@
+import type { Table } from '../Table';
+/**
+ * Registry of framework-DERIVED tables (search-token tables beside encrypted-searchable
+ * columns — see `EncryptedColumns`). Derived tables are synthesized from column config, not
+ * declared in source, so the reflection-backed table registry never sees them; `tableByName`
+ * consults this registry after the source registry misses.
+ *
+ * Lives on the global object so every live copy of this package (per-package installs)
+ * shares one registry — same pattern as `Db.getDefaultDbDriver`.
+ *
+ * Deliberately import-cycle-free: `Table` is a type-only import (erased at runtime), so
+ * `Table.ts` can import this module without closing a load-order loop.
+ */
+export declare class EncryptionDerivedTableRegistry {
+    private static readonly GLOBAL_KEY;
+    static get(tableName: string): Table<any> | undefined;
+    static register(table: Table<any>): void;
+    private static tables;
+}
+//# sourceMappingURL=EncryptionDerivedTableRegistry.d.ts.map

package/dist/src/encryption/EncryptionDerivedTableRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionDerivedTableRegistry.d.ts","sourceRoot":"","sources":["../../../src/encryption/EncryptionDerivedTableRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,qBAAa,8BAA8B;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAA4C;IAE9E,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS;IAIrD,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI;IAIxC,OAAO,CAAC,MAAM,CAAC,MAAM;CAQtB"}

package/dist/src/encryption/EncryptionDerivedTableRegistry.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptionDerivedTableRegistry = void 0;
+/**
+ * Registry of framework-DERIVED tables (search-token tables beside encrypted-searchable
+ * columns — see `EncryptedColumns`). Derived tables are synthesized from column config, not
+ * declared in source, so the reflection-backed table registry never sees them; `tableByName`
+ * consults this registry after the source registry misses.
+ *
+ * Lives on the global object so every live copy of this package (per-package installs)
+ * shares one registry — same pattern as `Db.getDefaultDbDriver`.
+ *
+ * Deliberately import-cycle-free: `Table` is a type-only import (erased at runtime), so
+ * `Table.ts` can import this module without closing a load-order loop.
+ */
+var EncryptionDerivedTableRegistry = /** @class */ (function () {
+    function EncryptionDerivedTableRegistry() {
+    }
+    EncryptionDerivedTableRegistry.get = function (tableName) {
+        return EncryptionDerivedTableRegistry.tables().get(tableName);
+    };
+    EncryptionDerivedTableRegistry.register = function (table) {
+        EncryptionDerivedTableRegistry.tables().set(table.name, table);
+    };
+    EncryptionDerivedTableRegistry.tables = function () {
+        var globalObject = globalThis;
+        if (!globalObject[EncryptionDerivedTableRegistry.GLOBAL_KEY]) {
+            globalObject[EncryptionDerivedTableRegistry.GLOBAL_KEY] = new Map();
+        }
+        return globalObject[EncryptionDerivedTableRegistry.GLOBAL_KEY];
+    };
+    EncryptionDerivedTableRegistry.GLOBAL_KEY = '__proteinjs_db_encryptionDerivedTables';
+    return EncryptionDerivedTableRegistry;
+}());
+exports.EncryptionDerivedTableRegistry = EncryptionDerivedTableRegistry;
+//# sourceMappingURL=EncryptionDerivedTableRegistry.js.map

package/dist/src/encryption/EncryptionDerivedTableRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionDerivedTableRegistry.js","sourceRoot":"","sources":["../../../src/encryption/EncryptionDerivedTableRegistry.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH;IAAA;IAmBA,CAAC;IAhBQ,kCAAG,GAAV,UAAW,SAAiB;QAC1B,OAAO,8BAA8B,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC;IAEM,uCAAQ,GAAf,UAAgB,KAAiB;QAC/B,8BAA8B,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACjE,CAAC;IAEc,qCAAM,GAArB;QACE,IAAM,YAAY,GAAG,UAAiB,CAAC;QACvC,IAAI,CAAC,YAAY,CAAC,8BAA8B,CAAC,UAAU,CAAC,EAAE;YAC5D,YAAY,CAAC,8BAA8B,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,EAAsB,CAAC;SACzF;QAED,OAAO,YAAY,CAAC,8BAA8B,CAAC,UAAU,CAAC,CAAC;IACjE,CAAC;IAjBuB,yCAAU,GAAG,wCAAwC,CAAC;IAkBhF,qCAAC;CAAA,AAnBD,IAmBC;AAnBY,wEAA8B"}

package/dist/src/encryption/EncryptionEnvelope.d.ts

@@ -0,0 +1,25 @@
+import type { DataKeyMaterial } from './DataKeyStore';
+/**
+ * The self-describing ciphertext envelope an encrypted column stores:
+ *
+ *   `pjenc:1:<ownerId>:<keyVersion>:<base64url(iv || authTag || ciphertext)>`
+ *
+ * Decrypt resolves the key FROM the envelope (owner + version), never from who is asking —
+ * a shared row decrypts for whoever the permission layer admits, and key rotation is a
+ * background rewrite. Cipher: AES-256-GCM (12-byte IV, 16-byte tag), the data key's cipher
+ * half (`DataKeyMaterial.cipherKey`).
+ */
+export declare class EncryptionEnvelope {
+    static readonly PREFIX = "pjenc:1:";
+    private static readonly ENVELOPE_PATTERN;
+    encrypt(plaintext: string, key: DataKeyMaterial): string;
+    decrypt(envelope: string, key: DataKeyMaterial): string;
+    /** Owner + version + payload when `value` is an envelope, else undefined. */
+    parse(value: unknown): {
+        owner: string;
+        version: number;
+        payload: string;
+    } | undefined;
+    isEnvelope(value: unknown): boolean;
+}
+//# sourceMappingURL=EncryptionEnvelope.d.ts.map

package/dist/src/encryption/EncryptionEnvelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionEnvelope.d.ts","sourceRoot":"","sources":["../../../src/encryption/EncryptionEnvelope.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,MAAM,cAAc;IACpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAA8C;IAEtF,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM;IASxD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM;IAevD,6EAA6E;IAC7E,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAatF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;CAGpC"}

package/dist/src/encryption/EncryptionEnvelope.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptionEnvelope = void 0;
+var crypto_1 = require("crypto");
+var Base64Url_1 = require("./Base64Url");
+/**
+ * The self-describing ciphertext envelope an encrypted column stores:
+ *
+ *   `pjenc:1:<ownerId>:<keyVersion>:<base64url(iv || authTag || ciphertext)>`
+ *
+ * Decrypt resolves the key FROM the envelope (owner + version), never from who is asking —
+ * a shared row decrypts for whoever the permission layer admits, and key rotation is a
+ * background rewrite. Cipher: AES-256-GCM (12-byte IV, 16-byte tag), the data key's cipher
+ * half (`DataKeyMaterial.cipherKey`).
+ */
+var EncryptionEnvelope = /** @class */ (function () {
+    function EncryptionEnvelope() {
+    }
+    EncryptionEnvelope.prototype.encrypt = function (plaintext, key) {
+        var iv = (0, crypto_1.randomBytes)(12);
+        var cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', key.cipherKey, iv);
+        var ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        var authTag = cipher.getAuthTag();
+        var payload = Base64Url_1.Base64Url.encode(Buffer.concat([iv, authTag, ciphertext]));
+        return "".concat(EncryptionEnvelope.PREFIX).concat(key.owner, ":").concat(key.version, ":").concat(payload);
+    };
+    EncryptionEnvelope.prototype.decrypt = function (envelope, key) {
+        var parsed = this.parse(envelope);
+        if (!parsed) {
+            throw new Error("Value is not a ciphertext envelope");
+        }
+        var bytes = Base64Url_1.Base64Url.decode(parsed.payload);
+        var iv = bytes.subarray(0, 12);
+        var authTag = bytes.subarray(12, 28);
+        var ciphertext = bytes.subarray(28);
+        var decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', key.cipherKey, iv);
+        decipher.setAuthTag(authTag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    };
+    /** Owner + version + payload when `value` is an envelope, else undefined. */
+    EncryptionEnvelope.prototype.parse = function (value) {
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        var match = EncryptionEnvelope.ENVELOPE_PATTERN.exec(value);
+        if (!match) {
+            return undefined;
+        }
+        return { owner: match[1], version: parseInt(match[2], 10), payload: match[3] };
+    };
+    EncryptionEnvelope.prototype.isEnvelope = function (value) {
+        return this.parse(value) !== undefined;
+    };
+    EncryptionEnvelope.PREFIX = 'pjenc:1:';
+    EncryptionEnvelope.ENVELOPE_PATTERN = /^pjenc:1:([^:]+):(\d+):([A-Za-z0-9_-]+)$/;
+    return EncryptionEnvelope;
+}());
+exports.EncryptionEnvelope = EncryptionEnvelope;
+//# sourceMappingURL=EncryptionEnvelope.js.map

package/dist/src/encryption/EncryptionEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionEnvelope.js","sourceRoot":"","sources":["../../../src/encryption/EncryptionEnvelope.ts"],"names":[],"mappings":";;;AAAA,iCAAuE;AACvE,yCAAwC;AAGxC;;;;;;;;;GASG;AACH;IAAA;IA6CA,CAAC;IAzCC,oCAAO,GAAP,UAAQ,SAAiB,EAAE,GAAoB;QAC7C,IAAM,EAAE,GAAG,IAAA,oBAAW,EAAC,EAAE,CAAC,CAAC;QAC3B,IAAM,MAAM,GAAG,IAAA,uBAAc,EAAC,aAAa,EAAE,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAChE,IAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACrF,IAAM,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QACpC,IAAM,OAAO,GAAG,qBAAS,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3E,OAAO,UAAG,kBAAkB,CAAC,MAAM,SAAG,GAAG,CAAC,KAAK,cAAI,GAAG,CAAC,OAAO,cAAI,OAAO,CAAE,CAAC;IAC9E,CAAC;IAED,oCAAO,GAAP,UAAQ,QAAgB,EAAE,GAAoB;QAC5C,IAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE;YACX,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;SACvD;QAED,IAAM,KAAK,GAAG,qBAAS,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjC,IAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACvC,IAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACtC,IAAM,QAAQ,GAAG,IAAA,yBAAgB,EAAC,aAAa,EAAE,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACpE,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzF,CAAC;IAED,6EAA6E;IAC7E,kCAAK,GAAL,UAAM,KAAc;QAClB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;YAC7B,OAAO,SAAS,CAAC;SAClB;QAED,IAAM,KAAK,GAAG,kBAAkB,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9D,IAAI,CAAC,KAAK,EAAE;YACV,OAAO,SAAS,CAAC;SAClB;QAED,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,CAAC;IAED,uCAAU,GAAV,UAAW,KAAc;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;IACzC,CAAC;IA3Ce,yBAAM,GAAG,UAAU,CAAC;IACZ,mCAAgB,GAAG,0CAA0C,CAAC;IA2CxF,yBAAC;CAAA,AA7CD,IA6CC;AA7CY,gDAAkB"}

package/dist/src/encryption/EncryptionLifecycleWalker.d.ts

@@ -0,0 +1,65 @@
+import type { Table } from '../Table';
+/**
+ * The config-lifecycle transitions, all riding this one walker:
+ * - `encrypt` — plaintext → `encrypted: {...}` adoption: rewrite rows whose stored value is
+ *   not yet an envelope (also how the initial adoption wave lands).
+ * - `retokenize` — a `searchable`/`sortKey` capability added later: rewrite every non-null
+ *   value so the write seam derives the new companions/tokens.
+ * - `decrypt` — `encrypted` → `false` (a deliberate, reviewed reclassification): rewrite
+ *   rows whose stored value is still an envelope; pass the affected columns explicitly
+ *   (the config no longer marks them). Stale token rows are swept.
+ * - `rotate-keys` — after `DataKeyStore.rotateKey`: rewrite rows whose envelope names an
+ *   older version (plaintext stragglers are encrypted too), then the caller retires the old
+ *   version.
+ */
+export type EncryptionWalkMode = 'encrypt' | 'retokenize' | 'decrypt' | 'rotate-keys';
+export interface EncryptionWalkSummary {
+    scanned: number;
+    rewritten: number;
+}
+export interface EncryptionWalkOptions {
+    /**
+     * Column property names to walk. Required for mode 'decrypt' (the config no longer marks
+     * the columns); defaults to every encrypted-declared column otherwise.
+     */
+    columns?: string[];
+    /** Resume after this row id (the walk is id-ordered; re-running from the start is also safe — done rows are skipped). */
+    startAfterId?: string;
+    windowSize?: number;
+    /** The driver to scan with; defaults to the process's default driver. */
+    dbDriver?: import('../Db').DbDriver;
+    /** The Db to rewrite through (must be a SYSTEM db); defaults to `getDbAsSystem()`. */
+    db?: import('../Db').Db<any>;
+}
+/**
+ * The reusable ONLINE backfill behind every encrypted-column config transition (and key
+ * rotation) — the migration-runner pattern: a server-side, id-ordered, windowed table walk
+ * that rewrites pending rows THROUGH the normal write seam (so encryption, companions, and
+ * search tokens all derive exactly as a live write would).
+ *
+ * Idempotent and resumable by construction: pending-ness is detected from the stored value
+ * itself (envelope or not, version current or not), so a re-run — after a crash, or just to
+ * be sure — skips completed rows and continues. Rows written by live traffic mid-walk are
+ * already in the new shape and skip too. Run it from a `Migration.run()` for deploy-coupled
+ * transitions.
+ */
+export declare class EncryptionLifecycleWalker {
+    private static readonly DEFAULT_WINDOW_SIZE;
+    private logger;
+    private encryptedColumns;
+    private envelope;
+    walkTable(table: Table<any>, mode: EncryptionWalkMode, options?: EncryptionWalkOptions): Promise<EncryptionWalkSummary>;
+    private isPending;
+    /**
+     * Rewrite one row through the normal seam: read it (the deserialize hook decrypts — or
+     * passes plaintext through, the adoption path), write the pending columns back (the
+     * serialize hook re-derives ciphertext, companions, and tokens under the current config).
+     */
+    private rewriteRow;
+    /** Raw (un-deserialized) id-ordered window — pending-ness must see stored bytes, not decrypted values. */
+    private rawWindow;
+    /** After decrypt-out, the decrypted columns' token rows are stale — sweep them. */
+    private sweepTokenRows;
+    private resolveProps;
+}
+//# sourceMappingURL=EncryptionLifecycleWalker.d.ts.map

package/dist/src/encryption/EncryptionLifecycleWalker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionLifecycleWalker.d.ts","sourceRoot":"","sources":["../../../src/encryption/EncryptionLifecycleWalker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAKtC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,aAAa,CAAC;AAEtF,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yHAAyH;IACzH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,OAAO,EAAE,QAAQ,CAAC;IACpC,sFAAsF;IACtF,EAAE,CAAC,EAAE,OAAO,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAO;IAClD,OAAO,CAAC,MAAM,CAA+C;IAC7D,OAAO,CAAC,gBAAgB,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAA4B;IAEtC,SAAS,CACb,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,qBAAqB,CAAC;YA4DnB,SAAS;IA+BvB;;;;OAIG;YACW,UAAU;IAyBxB,0GAA0G;YAC5F,SAAS;IAiBvB,mFAAmF;YACrE,cAAc;IAc5B,OAAO,CAAC,YAAY;CAwBrB"}