turbine-orm 0.60.1 → 0.62.0

package/dist/cjs/query/types.d.ts

@@ -1,8 +1,122 @@
 /**
  * turbine-orm, Query builder types
  *
- * All exported type and interface definitions for the query builder module.
+ * All exported type and interface definitions for the query builder module,
+ * plus the small runtime guards that police the values those types describe
+ * (the {@link UNSAFE} sentinel and the orderBy-direction check). Those guards
+ * live here, next to the declarations they enforce, so a new privilege option
+ * or direction-bearing shape has one obvious place to be wired in.
  */
+/**
+ * The value that unlocks a PRIVILEGE option: `skipGlobalFilters`,
+ * `includePii`, `allowFullTableScan`.
+ *
+ * ## The bug this closes
+ *
+ * All three of those options are ordinary siblings of `where` on the query-args
+ * object, so a handler written the idiomatic way,
+ *
+ * ```ts
+ * app.get('/users', (req, res) => db.users.findMany({ ...req.body }));
+ * ```
+ *
+ * used to let the REQUEST BODY turn them on. `{"where":{"name":"x"},
+ * "skipGlobalFilters":true}` compiled to the same statement minus the tenant
+ * predicate: the documented multi-tenancy mechanism, removed by an attacker
+ * over the wire. `includePii: true` unlocked the PII projection the same way,
+ * and `allowFullTableScan: true` disarmed the empty-`where` guard that stops a
+ * mass update or delete.
+ *
+ * Typing the options `boolean` and writing "be careful" in the docs is not a
+ * fix: the escalation is a mass-assignment shape, and mass assignment happens
+ * because nobody enumerated the keys.
+ *
+ * ## Why a symbol
+ *
+ * `JSON.parse` cannot produce a symbol. There is no JSON document, no query
+ * string, no form body and no `structuredClone` of untrusted input that yields
+ * this value, so an attacker cannot put it on an args object at all. The
+ * escalation stops being "discouraged" and becomes STRUCTURALLY impossible,
+ * which is the only property that survives a refactor.
+ *
+ * Registered via `Symbol.for` rather than `Symbol()` on purpose: this package
+ * ships dual ESM + CJS builds, and a consumer can easily import `UNSAFE` from
+ * one copy while the query interface it calls came from the other. A plain
+ * `Symbol()` would be a different value in each copy and every privileged call
+ * would throw. The global registry makes the two copies agree. (Reachability of
+ * `Symbol.for` from application code is irrelevant to the threat model here:
+ * the attacker's channel is parsed data, which cannot carry a symbol either
+ * way.)
+ *
+ * @example
+ * ```ts
+ * import { UNSAFE } from 'turbine-orm';
+ *
+ * // Deliberate, in a background job that legitimately crosses tenants:
+ * await db.users.findMany({ where: { active: true }, skipGlobalFilters: UNSAFE });
+ *
+ * // Skip the global filter on named tables only (the head element is the opt-in):
+ * await db.users.findMany({ with: { posts: true }, skipGlobalFilters: [UNSAFE, 'posts'] });
+ * ```
+ */
+export declare const UNSAFE: unique symbol;
+/** The type of the {@link UNSAFE} sentinel. */
+export type Unsafe = typeof UNSAFE;
+/** Every privilege option, for the diagnostic below and for tests to enumerate. */
+export type PrivilegeOption = 'skipGlobalFilters' | 'includePii' | 'allowFullTableScan';
+/**
+ * Resolve a boolean-shaped privilege option (`includePii`,
+ * `allowFullTableScan`) into the boolean the builders use.
+ *
+ * - absent / `undefined` / `null` / `false` → `false`. These are unambiguously
+ *   NOT a request for the privilege, and throwing on them would break the
+ *   ordinary `allowFullTableScan: someFlag` call whose flag is off (prisma-compat
+ *   relies on `allowFullTableScan: false` staying a no-op, see its updateMany).
+ * - {@link UNSAFE} → `true`.
+ * - ANYTHING else, `true` included → throws {@link ValidationError} (E003).
+ *
+ * The literal `true` throws rather than being ignored ON PURPOSE. Ignoring it
+ * would swap an escalation bug for a silent-failure bug: a legitimate caller
+ * who has not migrated would keep reading rows with the PII columns quietly
+ * missing, or keep expecting a cross-tenant read that no longer happens, with
+ * no signal anywhere. Throwing turns the attacker's spread into a 500 and the
+ * legitimate caller's stale code into an immediate, self-describing error.
+ */
+export declare function resolveUnsafeFlag(value: unknown, option: PrivilegeOption): boolean;
+/**
+ * The internal form of {@link SkipGlobalFilters}: `true` (skip every table) or
+ * the list of table accessors to skip. This is what the global-filter resolver
+ * consumes, and it is produced ONLY by {@link resolveSkipGlobalFilters}.
+ */
+export type ResolvedSkipGlobalFilters = true | readonly string[];
+/**
+ * Validate and normalize {@link SkipGlobalFilters}.
+ *
+ * The array form is policed exactly as hard as the bare form: an attacker who
+ * can post `{"skipGlobalFilters":["users"]}` drops the tenant predicate on the
+ * table they care about, which is the same breach with an extra step. So the
+ * array must LEAD with the sentinel (`[UNSAFE, 'posts']`) and the rest must be
+ * table-name strings.
+ */
+export declare function resolveSkipGlobalFilters(value: unknown): ResolvedSkipGlobalFilters | undefined;
+/**
+ * Refuse an orderBy direction that is neither `asc` nor `desc`.
+ *
+ * Every direction consumer used to be spelled `String(v).toLowerCase() ===
+ * 'desc' ? 'DESC' : 'ASC'`, so `'descending'`, `''`, `null`, `1` and every
+ * other typo all emitted `ASC`. TypeScript rejects them, but the value that
+ * reaches this code in practice is `orderBy: { [field]: req.query.dir }`, which
+ * is `any` at the boundary, and the failure is SILENT: the caller gets a
+ * correct-looking page sorted the exact opposite way, which is worse than an
+ * error and identical to a successful response.
+ *
+ * Accepts any casing (`'DESC'` already worked) and leaves `undefined` alone
+ * (every consumer treats an undefined entry as absent). Recursive/compound
+ * orderBy shapes are validated one node at a time by their own consumers.
+ */
+export declare function assertOrderDirection(value: unknown, context: string): void;
+/** One direction token. `undefined` means "not specified", which defaults to asc. */
+export declare function assertDirectionToken(value: unknown, context: string): void;
 export type OrderDirection = 'asc' | 'desc';
 /**
  * How a query resolves its `with` relations.
@@ -186,13 +300,18 @@ export type GlobalFilters = {
     [tableAccessor: string]: WhereClause<any> | (() => WhereClause<any>);
 };
 /**
- * Per-query opt-out of the configured {@link GlobalFilters}. `true` skips the
- * global filter on the query's own table AND on every relation target it
- * touches; an array skips only the named table accessors (own table and/or
- * relation targets). Global filters never satisfy the empty-`where` guard for
- * `update`/`delete`, that guard always checks the user-supplied `where`.
+ * Per-query opt-out of the configured {@link GlobalFilters}. {@link UNSAFE}
+ * skips the global filter on the query's own table AND on every relation target
+ * it touches; `[UNSAFE, ...names]` skips only the named table accessors (own
+ * table and/or relation targets). Global filters never satisfy the empty-`where`
+ * guard for `update`/`delete`, that guard always checks the user-supplied
+ * `where`.
+ *
+ * PRIVILEGE OPTION: it removes the documented multi-tenancy boundary, so it is
+ * unlocked by the {@link UNSAFE} sentinel only. `true` / `['users']` throw
+ * (E003). See {@link UNSAFE} for why.
  */
-export type SkipGlobalFilters = true | readonly string[];
+export type SkipGlobalFilters = Unsafe | readonly [Unsafe, ...string[]];
 /**
  * Reserved key in a `with` clause that requests correlated relation counts.
  * `_count: true` counts every to-many relation of the table; a record form
@@ -463,8 +582,8 @@ export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithCla
     stableRelationOrder?: boolean;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
-    /** Include PII-tagged columns in the result. See {@link FindManyArgs.includePii}. */
-    includePii?: boolean;
+    /** Include PII-tagged columns (`includePii: UNSAFE`). See {@link FindManyArgs.includePii}. */
+    includePii?: Unsafe;
     /** Plan this query with its real parameter values. See {@link FindManyArgs.forceCustomPlan}. */
     forceCustomPlan?: boolean;
 }
@@ -518,8 +637,12 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
      *
      * Referencing a PII column in `where` / `orderBy` / `groupBy` / aggregates is
      * always allowed regardless of this flag (the reference is explicit).
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only
+     * (`includePii: UNSAFE`). A literal `true` throws (E003), because a request
+     * body spread into these args must not be able to unlock the PII projection.
      */
-    includePii?: boolean;
+    includePii?: Unsafe;
     /**
      * Plan THIS query with its actual parameter values, every execution.
      * PostgreSQL only (see the refusal below).
@@ -728,10 +851,15 @@ export interface UpdateArgs<T, R extends object = {}> {
      * Opt in to running this mutation when `where` resolves to an empty
      * predicate (e.g. `{}` or `{ id: undefined }`). Default `false`, an
      * empty predicate throws `ValidationError` to catch the common case of
-     * a filter value accidentally being `undefined`. Set this to `true` only
-     * when an unconditional mutation is the intended behaviour.
+     * a filter value accidentally being `undefined`.
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only
+     * (`allowFullTableScan: UNSAFE`), and only when an unconditional mutation is
+     * genuinely the intent. A literal `true` throws (E003): this guard is the
+     * last thing standing between a spread request body and an unconditional
+     * `UPDATE` / `DELETE` over the whole table.
      */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /**
      * Optimistic locking, prevents lost updates in concurrent scenarios.
      * Specify the version field and its expected value. The update adds a
@@ -762,7 +890,7 @@ export interface UpdateManyArgs<T, R extends object = {}> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
@@ -771,7 +899,7 @@ export interface DeleteArgs<T, R extends object = {}> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
@@ -780,7 +908,7 @@ export interface DeleteManyArgs<T, R extends object = {}> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
+    allowFullTableScan?: Unsafe;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
@@ -1085,8 +1213,11 @@ export interface GroupByArgs<T, R extends object = {}> {
      * STORED VALUES, so without this they throw `ValidationError` (E003).
      * `_count` (a count, not a value), `_sum` / `_avg`, and `where` / `orderBy` /
      * `having` on PII columns stay allowed.
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only. See
+     * {@link FindManyArgs.includePii}.
      */
-    includePii?: boolean;
+    includePii?: Unsafe;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
@@ -1187,8 +1318,11 @@ export interface AggregateArgs<T, R extends object = {}> {
      * `ValidationError` (E003) on a PII column. `_count` (a count, not a value)
      * and `_sum` / `_avg` (a computed total over many rows) stay allowed, as do
      * `where` filters on PII columns.
+     *
+     * PRIVILEGE OPTION: unlocked by the {@link UNSAFE} sentinel only. See
+     * {@link FindManyArgs.includePii}.
      */
-    includePii?: boolean;
+    includePii?: Unsafe;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */

package/dist/cjs/query/types.js

@@ -2,6 +2,217 @@
 /**
  * turbine-orm, Query builder types
  *
- * All exported type and interface definitions for the query builder module.
+ * All exported type and interface definitions for the query builder module,
+ * plus the small runtime guards that police the values those types describe
+ * (the {@link UNSAFE} sentinel and the orderBy-direction check). Those guards
+ * live here, next to the declarations they enforce, so a new privilege option
+ * or direction-bearing shape has one obvious place to be wired in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNSAFE = void 0;
+exports.resolveUnsafeFlag = resolveUnsafeFlag;
+exports.resolveSkipGlobalFilters = resolveSkipGlobalFilters;
+exports.assertOrderDirection = assertOrderDirection;
+exports.assertDirectionToken = assertDirectionToken;
+const errors_js_1 = require("../errors.js");
+// ---------------------------------------------------------------------------
+// The privilege sentinel
+// ---------------------------------------------------------------------------
+/**
+ * The value that unlocks a PRIVILEGE option: `skipGlobalFilters`,
+ * `includePii`, `allowFullTableScan`.
+ *
+ * ## The bug this closes
+ *
+ * All three of those options are ordinary siblings of `where` on the query-args
+ * object, so a handler written the idiomatic way,
+ *
+ * ```ts
+ * app.get('/users', (req, res) => db.users.findMany({ ...req.body }));
+ * ```
+ *
+ * used to let the REQUEST BODY turn them on. `{"where":{"name":"x"},
+ * "skipGlobalFilters":true}` compiled to the same statement minus the tenant
+ * predicate: the documented multi-tenancy mechanism, removed by an attacker
+ * over the wire. `includePii: true` unlocked the PII projection the same way,
+ * and `allowFullTableScan: true` disarmed the empty-`where` guard that stops a
+ * mass update or delete.
+ *
+ * Typing the options `boolean` and writing "be careful" in the docs is not a
+ * fix: the escalation is a mass-assignment shape, and mass assignment happens
+ * because nobody enumerated the keys.
+ *
+ * ## Why a symbol
+ *
+ * `JSON.parse` cannot produce a symbol. There is no JSON document, no query
+ * string, no form body and no `structuredClone` of untrusted input that yields
+ * this value, so an attacker cannot put it on an args object at all. The
+ * escalation stops being "discouraged" and becomes STRUCTURALLY impossible,
+ * which is the only property that survives a refactor.
+ *
+ * Registered via `Symbol.for` rather than `Symbol()` on purpose: this package
+ * ships dual ESM + CJS builds, and a consumer can easily import `UNSAFE` from
+ * one copy while the query interface it calls came from the other. A plain
+ * `Symbol()` would be a different value in each copy and every privileged call
+ * would throw. The global registry makes the two copies agree. (Reachability of
+ * `Symbol.for` from application code is irrelevant to the threat model here:
+ * the attacker's channel is parsed data, which cannot carry a symbol either
+ * way.)
+ *
+ * @example
+ * ```ts
+ * import { UNSAFE } from 'turbine-orm';
+ *
+ * // Deliberate, in a background job that legitimately crosses tenants:
+ * await db.users.findMany({ where: { active: true }, skipGlobalFilters: UNSAFE });
+ *
+ * // Skip the global filter on named tables only (the head element is the opt-in):
+ * await db.users.findMany({ with: { posts: true }, skipGlobalFilters: [UNSAFE, 'posts'] });
+ * ```
+ */
+exports.UNSAFE = Symbol.for('turbine-orm.UNSAFE');
+/** The one message shape every privilege refusal uses. */
+function privilegeRefusal(option, received, extra = '') {
+    return new errors_js_1.ValidationError(`[turbine] \`${option}\` must be the \`UNSAFE\` symbol, received ${describeValue(received)}. ` +
+        `${option} is a privilege option: it removes a safety boundary (a tenant filter, the PII ` +
+        'projection, or the empty-`where` guard), so it cannot be enabled by a plain value that ' +
+        'JSON.parse can produce. Import the sentinel and pass it explicitly: ' +
+        `import { UNSAFE } from 'turbine-orm';  →  { ${option}: UNSAFE }.${extra ? ` ${extra}` : ''} ` +
+        'If you did not write this option, an untrusted object was spread into these query args.');
+}
+/** Short, non-leaking rendering of a rejected value for the diagnostic. */
+function describeValue(value) {
+    if (typeof value === 'symbol')
+        return 'a different symbol';
+    if (Array.isArray(value))
+        return 'an array';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'object')
+        return 'an object';
+    if (typeof value === 'string')
+        return `the string ${JSON.stringify(value)}`;
+    return String(value);
+}
+/**
+ * Resolve a boolean-shaped privilege option (`includePii`,
+ * `allowFullTableScan`) into the boolean the builders use.
+ *
+ * - absent / `undefined` / `null` / `false` → `false`. These are unambiguously
+ *   NOT a request for the privilege, and throwing on them would break the
+ *   ordinary `allowFullTableScan: someFlag` call whose flag is off (prisma-compat
+ *   relies on `allowFullTableScan: false` staying a no-op, see its updateMany).
+ * - {@link UNSAFE} → `true`.
+ * - ANYTHING else, `true` included → throws {@link ValidationError} (E003).
+ *
+ * The literal `true` throws rather than being ignored ON PURPOSE. Ignoring it
+ * would swap an escalation bug for a silent-failure bug: a legitimate caller
+ * who has not migrated would keep reading rows with the PII columns quietly
+ * missing, or keep expecting a cross-tenant read that no longer happens, with
+ * no signal anywhere. Throwing turns the attacker's spread into a 500 and the
+ * legitimate caller's stale code into an immediate, self-describing error.
+ */
+function resolveUnsafeFlag(value, option) {
+    if (value === undefined || value === null || value === false)
+        return false;
+    if (value === exports.UNSAFE)
+        return true;
+    throw privilegeRefusal(option, value);
+}
+/**
+ * Validate and normalize {@link SkipGlobalFilters}.
+ *
+ * The array form is policed exactly as hard as the bare form: an attacker who
+ * can post `{"skipGlobalFilters":["users"]}` drops the tenant predicate on the
+ * table they care about, which is the same breach with an extra step. So the
+ * array must LEAD with the sentinel (`[UNSAFE, 'posts']`) and the rest must be
+ * table-name strings.
+ */
+function resolveSkipGlobalFilters(value) {
+    if (value === undefined || value === null || value === false)
+        return undefined;
+    if (value === exports.UNSAFE)
+        return true;
+    if (Array.isArray(value)) {
+        if (value[0] !== exports.UNSAFE) {
+            throw privilegeRefusal('skipGlobalFilters', value, 'The array form skips the named tables and must lead with the sentinel: [UNSAFE, "posts"].');
+        }
+        const tables = value.slice(1);
+        // `[UNSAFE]` names no table. It used to resolve to `[]`, which every
+        // consumer reads as "skip nothing", so the one shape that is an explicit,
+        // correctly-imported privilege request was ALSO the one shape that was
+        // silently a no-op. It is not read as "skip all" on purpose: that would let
+        // `[UNSAFE, ...tables]` ESCALATE to a global skip whenever `tables` happens
+        // to come back empty, which is the same accident with a much worse outcome.
+        if (tables.length === 0) {
+            throw new errors_js_1.ValidationError('[turbine] `skipGlobalFilters: [UNSAFE]` names no table, so it would skip nothing. ' +
+                'Pass the tables to skip (`[UNSAFE, "posts"]`), or the bare sentinel (`UNSAFE`) to skip every table.');
+        }
+        for (const t of tables) {
+            if (typeof t !== 'string') {
+                throw new errors_js_1.ValidationError('[turbine] `skipGlobalFilters: [UNSAFE, ...]` takes table accessor NAMES after the sentinel, ' +
+                    `received ${describeValue(t)}.`);
+            }
+        }
+        return tables;
+    }
+    throw privilegeRefusal('skipGlobalFilters', value);
+}
+// ---------------------------------------------------------------------------
+// orderBy direction validation
+// ---------------------------------------------------------------------------
+/**
+ * Refuse an orderBy direction that is neither `asc` nor `desc`.
+ *
+ * Every direction consumer used to be spelled `String(v).toLowerCase() ===
+ * 'desc' ? 'DESC' : 'ASC'`, so `'descending'`, `''`, `null`, `1` and every
+ * other typo all emitted `ASC`. TypeScript rejects them, but the value that
+ * reaches this code in practice is `orderBy: { [field]: req.query.dir }`, which
+ * is `any` at the boundary, and the failure is SILENT: the caller gets a
+ * correct-looking page sorted the exact opposite way, which is worse than an
+ * error and identical to a successful response.
+ *
+ * Accepts any casing (`'DESC'` already worked) and leaves `undefined` alone
+ * (every consumer treats an undefined entry as absent). Recursive/compound
+ * orderBy shapes are validated one node at a time by their own consumers.
+ */
+function assertOrderDirection(value, context) {
+    // `undefined` alone means "this entry carries no ordering" (every consumer
+    // skips it). `null` is a VALUE, and a measured silent-ASC case, so it is
+    // refused like any other bad token.
+    if (value === undefined)
+        return;
+    if (typeof value === 'string') {
+        assertDirectionToken(value, context);
+        return;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const v = value;
+        // `{ sort, nulls }` (OrderBySpec), `{ direction }` (JSON-path / pick-row),
+        // `{ distance: { metric, direction } }` (vector KNN).
+        if ('sort' in v)
+            assertDirectionToken(v.sort, context);
+        if ('direction' in v)
+            assertDirectionToken(v.direction, context);
+        const distance = v.distance;
+        if (distance !== null && typeof distance === 'object' && 'direction' in distance) {
+            assertDirectionToken(distance.direction, context);
+        }
+        return;
+    }
+    // A number or boolean is never a direction.
+    assertDirectionToken(value, context);
+}
+/** One direction token. `undefined` means "not specified", which defaults to asc. */
+function assertDirectionToken(value, context) {
+    if (value === undefined)
+        return;
+    if (typeof value === 'string') {
+        const lowered = value.toLowerCase();
+        if (lowered === 'asc' || lowered === 'desc')
+            return;
+    }
+    throw new errors_js_1.ValidationError(`[turbine] Invalid orderBy direction ${describeValue(value)} for ${context}. ` +
+        "Use 'asc' or 'desc'. An unrecognized direction used to sort ASCENDING silently, " +
+        'which returns a correct-looking page in the wrong order.');
+}

package/dist/cjs/query/where.d.ts

@@ -15,7 +15,7 @@ import type { Dialect } from '../dialect.js';
 import { ValidationError } from '../errors.js';
 import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
 import type { TemporalInfinityReading } from './deferred.js';
-import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, SkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
+import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, ResolvedSkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
 import { type SqlCacheEntry } from './utils.js';
 import { type WhereHost, type WhereRecord } from './where-compile.js';
 /**
@@ -58,7 +58,7 @@ export interface BuilderCtx {
      * synchronous SQL-build + param-collect tree reads it deep inside
      * `resolveGlobalFilter`.
      */
-    currentSkip: SkipGlobalFilters | undefined;
+    currentSkip: ResolvedSkipGlobalFilters | undefined;
     q(name: string): string;
     p(index: number): string;
     inParam(values: unknown): unknown;
@@ -216,7 +216,7 @@ export declare function buildWhere<T extends object>(qi: BuilderCtx, where: Wher
  * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
  * no filter applies, the query opted out, or the filter is empty.
  */
-export declare function resolveGlobalFilter(qi: BuilderCtx, table: string, skip?: SkipGlobalFilters | undefined): Record<string, unknown> | null;
+export declare function resolveGlobalFilter(qi: BuilderCtx, table: string, skip?: ResolvedSkipGlobalFilters | undefined): Record<string, unknown> | null;
 /**
  * AND-merge this table's resolved global filter into a user `where`. Either
  * side may be absent. When no filter applies the user where is returned by

package/dist/cjs/query/where.js

@@ -529,13 +529,19 @@ function userPredicateIsEmpty(qi, userWhere) {
     const throwaway = [];
     return buildWhereClause(qi, userWhere, throwaway) === null;
 }
-function assertMutationHasPredicate(qi, operation, whereSql, allowFullTableScan) {
+function assertMutationHasPredicate(qi, operation, whereSql, 
+// Already RESOLVED by the caller (writes.ts) through `resolveUnsafeFlag`, so
+// the sentinel check happens on every mutation, not only the guarded ones: a
+// literal `allowFullTableScan: true` must throw even when the `where` is
+// non-empty, or the escalation attempt goes unreported on most calls.
+allowFullTableScan) {
     if (whereSql.length > 0)
         return;
     if (allowFullTableScan === true)
         return;
     throw new errors_js_1.ValidationError(`[turbine] ${operation} on "${qi.table}" refused: the \`where\` clause is empty. ` +
-        `Pass \`allowFullTableScan: true\` to opt in, or check that your filter values are defined.`);
+        "Pass `allowFullTableScan: UNSAFE` to opt in (import { UNSAFE } from 'turbine-orm'), " +
+        'or check that your filter values are defined.');
 }
 /**
  * Build the inner WHERE expression (without the WHERE keyword).

package/dist/cjs/query/writes.js

@@ -71,6 +71,7 @@ const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
 const compound_unique_js_1 = require("./compound-unique.js");
 const filters_js_1 = require("./filters.js");
+const types_js_1 = require("./types.js");
 const utils_js_1 = require("./utils.js");
 const whereMod = __importStar(require("./where.js"));
 /**
@@ -365,7 +366,7 @@ function buildCreateMany(qi, args) {
 }
 function buildUpdate(qi, args) {
     assertWritable(qi, 'update');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
     // `updatedAt`-tagged columns are filled in before anything reads `data`, so
     // the SET list, the fingerprint and the param collector all see one object.
     const dataObj = applyUpdatedAtColumns(qi, args.data);
@@ -378,7 +379,7 @@ function buildUpdate(qi, args) {
     // The empty-`where` guard checks the USER predicate only, a global filter
     // must never turn an unguarded mass update into an allowed one.
     const userHasPredicate = !whereMod.userPredicateIsEmpty(qi, userWhere) || !!lock;
-    whereMod.assertMutationHasPredicate(qi, 'update', userHasPredicate ? ' WHERE x' : '', args.allowFullTableScan);
+    whereMod.assertMutationHasPredicate(qi, 'update', userHasPredicate ? ' WHERE x' : '', (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'));
     // The SQL is built from the global-filter-merged where (soft-delete keeps an
     // update from touching already-deleted rows).
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
@@ -507,11 +508,11 @@ function buildUpdate(qi, args) {
 }
 function buildDelete(qi, args) {
     assertWritable(qi, 'delete');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
     // Prisma compound-unique selector → the column conjunction (before the guard).
     const userWhere = (0, compound_unique_js_1.expandCompoundUniqueWhere)(qi.tableMeta, args.where);
     // Guard the USER predicate (a global filter must not satisfy the guard).
-    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, userWhere) ? '' : ' WHERE x', args.allowFullTableScan);
+    whereMod.assertMutationHasPredicate(qi, 'delete', whereMod.userPredicateIsEmpty(qi, userWhere) ? '' : ' WHERE x', (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'));
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = `d:${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
@@ -562,7 +563,7 @@ function buildUpsert(qi, args) {
     assertWritable(qi, 'upsert');
     assertNoGeneratedColumns(qi, args.create, 'upsert');
     assertNoGeneratedColumns(qi, args.update, 'upsert');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
     // Prisma compound-unique selector on the conflict target → its member columns.
     const upsertWhere = (0, compound_unique_js_1.expandCompoundUniqueWhere)(qi.tableMeta, args.where);
     // Build the INSERT part from create data
@@ -631,10 +632,10 @@ function buildUpsert(qi, args) {
 }
 function buildUpdateMany(qi, args) {
     assertWritable(qi, 'updateMany');
-    qi.currentSkip = args.skipGlobalFilters;
+    qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
     const dataObj = applyUpdatedAtColumns(qi, args.data);
     assertNoGeneratedColumns(qi, dataObj, 'updateMany');
-    whereMod.assertMutationHasPredicate(qi, 'updateMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', args.allowFullTableScan);
+    whereMod.assertMutationHasPredicate(qi, 'updateMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'));
     const whereObj = (whereMod.mergeGlobalFilter(qi, args.where) ?? {});
     // Nothing to SET: a no-op, for the same reason as `update` above (that path
     // has the full rationale). Reports `count: 0` because zero rows were
@@ -673,8 +674,8 @@ function buildUpdateMany(qi, args) {
 }
 function buildDeleteMany(qi, args) {
     assertWritable(qi, 'deleteMany');
-    qi.currentSkip = args.skipGlobalFilters;
-    whereMod.assertMutationHasPredicate(qi, 'deleteMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', args.allowFullTableScan);
+    qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
+    whereMod.assertMutationHasPredicate(qi, 'deleteMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', (0, types_js_1.resolveUnsafeFlag)(args.allowFullTableScan, 'allowFullTableScan'));
     const whereObj = (whereMod.mergeGlobalFilter(qi, args.where) ?? {});
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = `dm:${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;

package/dist/cli/config.d.ts

@@ -189,4 +189,44 @@ export declare function resolveConfig(fileConfig: TurbineCliConfig, overrides: C
  * order (root-level first, then the `turbine/` location `init` scaffolds).
  */
 export declare function resolveSeedFile(config: Pick<TurbineCliConfig, 'seed' | 'seedFile'>, cwd?: string): string | null;
+/**
+ * Does this connection string carry a password?
+ *
+ * `turbine init --url` used to inline whatever it was given straight into
+ * `turbine.config.ts`, a file projects commit, so the documented one-liner
+ * (`turbine init --url postgres://user:PASSWORD@host/db`) committed a live
+ * database password. Everything that decides between "inline the string" and
+ * "read `process.env.DATABASE_URL`" asks this function, so there is exactly one
+ * definition of "this value is a secret".
+ *
+ * Three spellings carry a password, and libpq (and `pg-connection-string`,
+ * which is what `pg` actually parses with) accepts all three:
+ *
+ *  1. URL userinfo: `postgres://user:pass@host/db`.
+ *  2. URL query parameter: `postgres://user@host/db?password=pass`, and its
+ *     siblings such as `?sslpassword=`. This one was missed, on the reasoning
+ *     that a successful `new URL` ruled out the keyword form below, which is
+ *     true and irrelevant: the secret was in the query string.
+ *  3. libpq keyword form: `host=... password=...` (also `sslpassword=`), which
+ *     is not a URL at all.
+ *
+ * The query-parameter test reuses `PASSWORD_QUERY_PARAM_PATTERN`, the very
+ * regex `redactUrl` redacts with, so a spelling the terminal output hides can
+ * never be a spelling this function calls safe to commit. `pg-connection-string`
+ * itself would be the ideal oracle, but it is only a TRANSITIVE dependency (of
+ * `pg`), and importing an undeclared package would break on any strict,
+ * non-hoisting installer. Detection stays self-contained.
+ *
+ * @internal exported for tests.
+ */
+export declare function connectionStringHasPassword(connectionString: string): boolean;
+/**
+ * The `turbine.config.ts` scaffold.
+ *
+ * A password-bearing `connectionString` is NEVER inlined: the emitted config
+ * reads `process.env.DATABASE_URL` instead, and `turbine init` scaffolds the
+ * `.env` that holds the real value. The refusal lives here rather than at the
+ * call site so no future caller can reintroduce the leak by passing the raw
+ * `--url` through.
+ */
 export declare function configTemplate(connectionString?: string): string;