turbine-orm 0.35.0 → 0.36.0

package/dist/cjs/powdb.js

@@ -90,7 +90,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PowqlInterface = exports.introspectPowdbDatabase = exports.PowdbEmbeddedPool = exports.PowdbPool = exports.DEFAULT_TX_QUEUE_TIMEOUT_MS = exports.POWQL_KEYWORDS = exports.ALL_POWDB_CAPABILITIES = exports.MIN_POWDB_VERSION = exports.PowdbJsonParam = exports.PowdbFloatParam = exports.powdbDialect = void 0;
+exports.PowqlInterface = exports.introspectPowdbDatabase = exports.PowdbEmbeddedPool = exports.POWQL_LEXER_TESTED_CEILING = exports.PowdbPool = exports.DEFAULT_TX_QUEUE_TIMEOUT_MS = exports.POWQL_KEYWORDS = exports.ALL_POWDB_CAPABILITIES = exports.MIN_POWDB_VERSION = exports.PowdbJsonParam = exports.PowdbFloatParam = exports.powdbDialect = void 0;
 exports.parsePowdbUrl = parsePowdbUrl;
 exports.assertSupportedPowdbVersion = assertSupportedPowdbVersion;
 exports.capabilitiesFromVersion = capabilitiesFromVersion;
@@ -1430,6 +1430,26 @@ function encodePowqlLiteral(value) {
         return encodePowqlString(value);
     throw new errors_js_1.ValidationError(`[turbine] Value of type ${typeof value} cannot be encoded as a PowDB literal.`);
 }
+/**
+ * The newest PowDB engine LINE (major.minor) whose lexer escape handling
+ * {@link encodePowqlString} is VERIFIED against by reading
+ * `crates/query/src/lexer.rs`. The legacy materialize path
+ * ({@link materializePowql}) inlines encoded string literals directly into query
+ * text, so it is only injection-safe while the lexer recognizes exactly the
+ * escape set the escaper emits (`\"`, `\\`, `\n`, `\t`, everything else raw). If
+ * a future engine line teaches the lexer new escapes (e.g. `\u`, `\x`), a string
+ * that the escaper leaves raw could be re-interpreted by the lexer and break out
+ * of the literal, turning the fallback into an injection primitive.
+ *
+ * CONTRACT: bump this ceiling ONLY after re-verifying the escape handling in
+ * `crates/query/src/lexer.rs` for the newer line AND confirming
+ * {@link encodePowqlString} still escapes every breakout vector the lexer
+ * recognizes. The legacy path guards on this value (see
+ * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
+ * the ceiling yet still routes through the string wire is refused rather than
+ * materialized.
+ */
+exports.POWQL_LEXER_TESTED_CEILING = '0.15';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
 function encodePowqlString(s) {
     let out = '"';
@@ -1532,6 +1552,26 @@ class PowdbEmbeddedPool {
         // Legacy string wire (addon < 0.14): the engine takes no params array, so
         // materialize each `$N` into a PowQL literal. Byte-for-byte unchanged, kept
         // live and tested as the pre-0.14 fallback.
+        //
+        // Safety assertion (see {@link POWQL_LEXER_TESTED_CEILING}): an addon whose
+        // engine line EXCEEDS the escaper's verified lexer ceiling must never be
+        // materialized: a newer lexer may recognize escapes the escaper leaves raw,
+        // making the inline path an injection primitive. Reachability: addons >= 0.14
+        // expose `queryWithParams` and take the native path above, so the ONLY way to
+        // reach this branch with a newer-than-ceiling engine is the anomalous
+        // newer-addon-without-native case (feature-detect failed). Refuse it rather
+        // than inline-encode against an unverified lexer.
+        const engineSem = parsePowdbSemver(this.capabilities.engineVersion);
+        const ceiling = parsePowdbSemver(exports.POWQL_LEXER_TESTED_CEILING);
+        if (engineSem &&
+            ceiling &&
+            (engineSem.major > ceiling.major || (engineSem.major === ceiling.major && engineSem.minor > ceiling.minor))) {
+            throw new errors_js_1.ValidationError(`[turbine] Refusing the PowDB legacy string wire: this embedded addon reports engine ` +
+                `${this.capabilities.engineVersion}, which is newer than the escaper's verified lexer range ` +
+                `(<= ${exports.POWQL_LEXER_TESTED_CEILING}) AND such an addon exposes the parameterized native API, so ` +
+                `reaching the legacy materialize path means the queryWithParams feature-detect failed. Upgrade ` +
+                `turbine-orm so its PowQL escaper is verified against this engine line before running on it.`);
+        }
         const materialized = materializePowql(powql, params);
         return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
     }

package/dist/cjs/powql.js

@@ -653,10 +653,17 @@ class PowqlInterface {
     // -------------------------------------------------------------------------
     // Projection / order
     // -------------------------------------------------------------------------
-    /** Resolve the set of columns to project, honouring `select` / `omit`. */
-    projectedColumns(select, omit) {
+    /**
+     * Resolve the set of columns to project, honouring `select` / `omit` and the
+     * query-level `includePii` opt-in. PII-tagged (`defineSchema` `pii: true`)
+     * columns are EXCLUDED from a default (or omit-only) projection unless
+     * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
+     * and returns it regardless. Untagged tables project exactly as before.
+     */
+    projectedColumns(select, omit, includePii) {
         let cols = this.meta.columns.map((c) => c.name);
-        if (select && Object.keys(select).length) {
+        const hasSelect = select && Object.keys(select).length;
+        if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
                 .map(([k]) => this.column(k).name));
@@ -665,6 +672,14 @@ class PowqlInterface {
                 picked.add(pk);
             cols = cols.filter((c) => picked.has(c));
         }
+        else if (!includePii) {
+            // Default / omit-only projection: drop PII columns (kept above only when a
+            // caller names them in `select`). PK is never PII in practice; if one is
+            // tagged it is still dropped here, so tag sensitive data, not keys.
+            const pii = this.piiColumnNames();
+            if (pii.size)
+                cols = cols.filter((c) => !pii.has(c));
+        }
         if (omit && Object.keys(omit).length) {
             const dropped = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
@@ -673,6 +688,47 @@ class PowqlInterface {
         }
         return cols;
     }
+    /**
+     * The snake_case names of this table's PII-tagged columns. Empty for a table
+     * with no `pii: true` column, so untagged tables keep their prior projection.
+     */
+    piiColumnNames() {
+        const out = new Set();
+        for (const col of this.meta.columns) {
+            if (col.pii)
+                out.add(col.name);
+        }
+        return out;
+    }
+    /**
+     * The camelCase field names of this table's PII-tagged columns: the read
+     * policy applied to a write's returned row (create/update/upsert/delete accept
+     * no `includePii`/`select`, so their result always drops PII; you may still
+     * write PII fields freely).
+     *
+     * SPEC LIMITATION (PowQL): the driver contract
+     * (`docs/integrations/powql-for-drivers.md`) exposes `returning` only as a
+     * bare keyword that hands back every column; it accepts NO column list, so
+     * (unlike the SQL engines, which emit an explicit non-PII `RETURNING`/`OUTPUT`
+     * projection) the create/update/delete `returning` paths cannot exclude PII at
+     * the query-language level and must strip it here after the fact. This is the
+     * client-side strip of last resort, not defense-in-depth, for those paths; we
+     * do NOT reverse-engineer an undocumented projection form. The upsert path is
+     * different: it has no `returning` and reselects by PK through the read
+     * projection ({@link projectedColumns}), which already omits PII, so PII never
+     * crosses the wire there. If a future spec revision lets `returning` take a
+     * projection, switch the write paths to emit the non-PII list and this strip
+     * becomes a no-op like {@link parseWriteRow} on the SQL engines.
+     */
+    stripWritePii(entity) {
+        if (!entity)
+            return entity;
+        for (const col of this.meta.columns) {
+            if (col.pii)
+                delete entity[col.field];
+        }
+        return entity;
+    }
     /** `{ .c1, .c2, … }` projection clause. */
     projection(cols) {
         return `{ ${cols.map((c) => `.${c}`).join(', ')} }`;
@@ -877,10 +933,7 @@ class PowqlInterface {
             const { rows, native, resolvedWhere } = await this.runFind(args, 'findMany');
             const entities = this.shape(rows, native);
             if (args.with) {
-                await this.loadRelations(entities, args.with, args.timeout, 0, {
-                    args,
-                    resolvedWhere,
-                });
+                await this.loadRelations(entities, args.with, args.timeout, 0, { args, resolvedWhere }, args.includePii === true);
             }
             return entities;
         });
@@ -897,7 +950,7 @@ class PowqlInterface {
         }
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
         const where = this.buildWhere(resolvedWhere, params);
-        const cols = this.projectedColumns(args.select, args.omit);
+        const cols = this.projectedColumns(args.select, args.omit, args.includePii === true);
         const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
         const order = this.buildOrder(args.orderBy, params);
@@ -949,7 +1002,7 @@ class PowqlInterface {
                 return null;
             const entities = this.shape(rows, native);
             if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout);
+                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -960,7 +1013,7 @@ class PowqlInterface {
                 return null;
             const entities = this.shape(rows, native);
             if (args.with)
-                await this.loadRelations(entities, args.with, args.timeout);
+                await this.loadRelations(entities, args.with, args.timeout, 0, undefined, args.includePii === true);
             return entities[0];
         });
     }
@@ -990,7 +1043,7 @@ class PowqlInterface {
      * the default `'batched'` strategy) keeps the loaders. Output is byte-equal
      * either way (the join reuses the same stitch / shape helpers).
      */
-    async loadRelations(parents, withClause, timeout, depth = 0, parent) {
+    async loadRelations(parents, withClause, timeout, depth = 0, parent, includePii = false) {
         if (depth >= 10) {
             throw new errors_js_1.ValidationError(`[turbine] Nested 'with' on PowDB exceeded depth 10 (relation cycle?).`);
         }
@@ -1010,7 +1063,7 @@ class PowqlInterface {
                 throw new errors_js_1.ValidationError(`[turbine] Unknown relation "${relName}" on "${this.table}".`);
             if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
                 if (this.capabilities.serverJoins) {
-                    await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout);
+                    await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
                     continue;
                 }
                 // An otherwise-eligible relation the engine cannot join: a PER-QUERY
@@ -1022,7 +1075,7 @@ class PowqlInterface {
                 }
             }
             if (rel.type === 'manyToMany') {
-                await this.loadManyToMany(parents, rel, relName, opt, timeout);
+                await this.loadManyToMany(parents, rel, relName, opt, timeout, includePii);
                 continue;
             }
             const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
@@ -1079,6 +1132,7 @@ class PowqlInterface {
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
+                    includePii,
                 }));
                 for (const child of children) {
                     const k = this.joinKey(child[childKeyField]);
@@ -1115,7 +1169,7 @@ class PowqlInterface {
      * single-key N+1 loaders; the junction's source/target columns must be single
      * (composite junction keys would need PowQL tuple-`in`, which it lacks).
      */
-    async loadManyToMany(parents, rel, relName, opt, timeout) {
+    async loadManyToMany(parents, rel, relName, opt, timeout, includePii = false) {
         const through = rel.through;
         if (!through)
             throw new errors_js_1.ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
@@ -1179,6 +1233,7 @@ class PowqlInterface {
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
+                includePii,
             }));
             for (const t of targets)
                 targetByPk.set(String(t[targetPkField]), t);
@@ -1296,9 +1351,9 @@ class PowqlInterface {
         return tableMeta.indexes.some((idx) => idx.unique && !idx.docPath && idx.columns.length === 1 && idx.columns[0] === col);
     }
     /** Dispatch one eligible relation to the correct native-join loader. */
-    async loadRelationViaJoin(parents, rel, relName, opt, parent, timeout) {
+    async loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii = false) {
         if (rel.type === 'manyToMany') {
-            await this.loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout);
+            await this.loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
             return;
         }
         const options = (opt === true ? {} : opt);
@@ -1316,7 +1371,7 @@ class PowqlInterface {
         const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const parentKeyField = this.meta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
         const params = [];
-        const childCols = this.joinChildCols(targetQi, options);
+        const childCols = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
         const order = targetQi.buildOrder(options.orderBy, params, 'c');
         const limitClause = options.limit !== undefined ? ` limit ${this.param(options.limit, params)}` : '';
@@ -1340,7 +1395,7 @@ class PowqlInterface {
      * → the already-fetched side (alias `p`), correlating `__tpk` from the
      * junction's source key. Always a list, stitched exactly like the loader.
      */
-    async loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout) {
+    async loadManyToManyViaJoin(parents, rel, relName, opt, parent, timeout, includePii = false) {
         const through = rel.through;
         if (!through)
             throw new errors_js_1.ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
@@ -1355,7 +1410,7 @@ class PowqlInterface {
         const targetPkCol = targetMeta.primaryKey[0];
         const parentRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
         const params = [];
-        const childCols = this.joinChildCols(targetQi, options);
+        const childCols = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 't', params, options.timeout ?? timeout);
         const proj = this.joinProjection(childCols, `j.${(0, powdb_js_1.quotePowqlIdent)(sourceJCol)}`, 't');
         const powql = `${targetQi.qt} as t ` +
@@ -1374,8 +1429,8 @@ class PowqlInterface {
      * with a loud guard: a real column named `__tpk` would collide with the
      * reserved correlation alias, so refuse rather than silently mis-stitch.
      */
-    joinChildCols(targetQi, options) {
-        const cols = targetQi.projectedColumns(options.select, options.omit);
+    joinChildCols(targetQi, options, includePii = false) {
+        const cols = targetQi.projectedColumns(options.select, options.omit, includePii);
         if (cols.includes('__tpk')) {
             throw new errors_js_1.ValidationError(`[turbine] relation target "${targetQi.table}" has a column named "__tpk", which collides with the reserved ` +
                 `join correlation alias. Rename the column or load this relation with relationLoadStrategy: 'batched'.`);
@@ -1504,7 +1559,7 @@ class PowqlInterface {
                 .join(', ');
             // `returning` surfaces the inserted row (all columns, schema order) in one round-trip.
             const { rows, native } = await this.exec(`insert ${this.qt} { ${body} } returning`, params, args.timeout, 'create');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new errors_js_1.NotFoundError({ table: this.table, where: data });
             return row;
@@ -1522,7 +1577,7 @@ class PowqlInterface {
             });
             // Multi-row insert with `returning` hands back every inserted row in one round-trip.
             const { rows, native } = await this.exec(`insert ${this.qt} ${tuples.join(', ')} returning`, params, args.timeout, 'createMany');
-            return this.shape(rows, native);
+            return this.shape(rows, native).map((r) => this.stripWritePii(r));
         });
     }
     async update(args) {
@@ -1537,7 +1592,7 @@ class PowqlInterface {
             const setClause = this.buildUpdateAssignments(args.data, params);
             // `returning` hands back the post-update row(s); take the first (single-row contract).
             const { rows, native } = await this.exec(`${this.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout, 'update');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new errors_js_1.NotFoundError({ table: this.table, where: args.where });
             return row;
@@ -1683,7 +1738,7 @@ class PowqlInterface {
             this.assertCompiledWhere(where, false, 'delete');
             // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
-            const row = rows.length ? this.shape(rows, native)[0] : null;
+            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
                 throw new errors_js_1.NotFoundError({ table: this.table, where: args.where });
             return row;