@cerbos/orm-prisma 4.0.0 → 5.0.0

package/src/strings.ts

@@ -0,0 +1,152 @@
+// The receiver-sensitive string operators: `contains`, `startsWith`, `endsWith`.
+
+import type { PlanExpressionOperand } from "@cerbos/core";
+
+import { assertStringField, buildFieldFilter, buildPrefixFilter } from "./fields";
+import type { PrismaFilter } from "./index";
+import {
+  isResolvedFieldReference,
+  isResolvedValue,
+  recordErroringNullElement,
+} from "./mapping";
+import type { TranslationContext } from "./mapping";
+import { assertDefined } from "./plan";
+import { resolveOperand } from "./translate";
+import { UnsupportedQueryPlanError } from "./errors";
+import { isString } from "./narrowing";
+
+// Upper bound on the IN-list produced when enumerating a constant receiver's substrings.
+const MAX_ENUMERATED_NEEDLES = 1000;
+
+/**
+ * Every needle `haystack.<operator>(needle)` is true for: its prefixes for startsWith, its
+ * suffixes for endsWith, its substrings for contains — and the empty string for all three.
+ */
+function candidateNeedles(operator: string, haystack: string): Set<string> {
+  const candidates = new Set<string>([""]);
+
+  if (operator === "startsWith") {
+    for (let i = 1; i <= haystack.length; i++) {
+      candidates.add(haystack.slice(0, i));
+    }
+  } else if (operator === "endsWith") {
+    for (let i = 0; i < haystack.length; i++) {
+      candidates.add(haystack.slice(i));
+    }
+  } else {
+    for (let start = 0; start < haystack.length; start++) {
+      for (let end = start + 1; end <= haystack.length; end++) {
+        candidates.add(haystack.slice(start, end));
+      }
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * Helper function to handle string operators (contains, startsWith, endsWith).
+ *
+ * These operators are receiver-sensitive and the planner preserves policy source order:
+ * operand 0 is the receiver (haystack), operand 1 the needle. Swapping them silently
+ * inverts the match direction, so unlike symmetric comparisons they are never normalized.
+ */
+export function handleStringOperator(
+  operator: string,
+  operands: PlanExpressionOperand[],
+  context: TranslationContext
+): PrismaFilter {
+  if (operands.length !== 2) {
+    throw new UnsupportedQueryPlanError(`${operator} requires exactly two operands`);
+  }
+
+  const receiver = resolveOperand(
+    assertDefined(operands[0], `${operator} requires a receiver operand`),
+    context
+  );
+
+  const needle = resolveOperand(
+    assertDefined(operands[1], `${operator} requires a needle operand`),
+    context
+  );
+
+  if (isResolvedFieldReference(receiver)) assertStringField(receiver, operator);
+
+  if (isResolvedFieldReference(needle)) assertStringField(needle, operator);
+  // A null element of a projected list is a value, and a string function over it is an error.
+  recordErroringNullElement(context, operands[0]!, receiver);
+  recordErroringNullElement(context, operands[1]!, needle);
+
+  // Column receiver, constant needle: Prisma's LIKE-based filter.
+  if (isResolvedFieldReference(receiver) && isResolvedValue(needle)) {
+    const { value } = needle;
+
+    if (!isString(value)) {
+      throw new UnsupportedQueryPlanError(`${operator} operator requires string value`);
+    }
+
+    if (value.includes("\u0000")) {
+      throw new UnsupportedQueryPlanError(
+        `${operator} with a needle holding a NUL character: PostgreSQL text cannot hold one, and SQLite's LIKE stops reading the pattern at it, so %NUL% matched every row`,
+      );
+    }
+
+    // A prefix is matched by the range of strings it bounds, so startsWith needs no LIKE escaping
+    // (see buildPrefixFilter). Prisma emits LIKE without an ESCAPE clause and does not escape
+    // wildcard characters, so a contains or endsWith needle containing % or _ would match as a
+    // pattern instead of literally (contains("a_b") wrongly matches "axb"), and a suffix or
+    // substring bounds no range. Fail loudly rather than filter wrong.
+    //
+    // A backslash is the same hazard reached from the other direction, and only an executed
+    // PostgreSQL leg surfaces it (cerbos/query-plan-adapters#320): SQLite's LIKE has no escape
+    // character at all, so `\` is literal there, while PostgreSQL and MySQL treat it as the
+    // DEFAULT escape character even with no ESCAPE clause. `endsWith("\\")` is then a pattern
+    // ending in an escape character — a hard error on PostgreSQL — and a `\x` anywhere inside
+    // silently drops the backslash, so `contains("a\\b")` matches "ab", a row the PDP denies.
+    if (operator === "startsWith") {
+      return buildPrefixFilter(receiver, value);
+    }
+
+    if (/[%_\\]/.test(value)) {
+      throw new UnsupportedQueryPlanError(
+        `Cannot translate ${operator} with a needle containing LIKE metacharacters (%, _ or \\): ` +
+          "Prisma does not escape wildcards in string filters, and \\ is the default LIKE " +
+          "escape character on PostgreSQL and MySQL"
+      );
+    }
+
+    return buildFieldFilter(receiver, operator, value);
+  }
+
+  // Constant receiver, column needle (e.g. `"a-b-c".contains(R.attr.x)`): enumerate every
+  // candidate needle the constant admits into an exact IN filter. No LIKE, so no escaping
+  // hazards; a NULL needle column stays excluded (CEL missing-attribute deny).
+  if (isResolvedValue(receiver) && isResolvedFieldReference(needle)) {
+    if (!isString(receiver.value)) {
+      throw new UnsupportedQueryPlanError(`${operator} operator requires a string receiver`);
+    }
+
+    const candidates = candidateNeedles(operator, receiver.value);
+
+    if (candidates.size > MAX_ENUMERATED_NEEDLES) {
+      throw new UnsupportedQueryPlanError(
+        `Cannot translate ${operator} with a constant receiver of this length: ` +
+          `enumerating its ${candidates.size} candidate needles exceeds the ${MAX_ENUMERATED_NEEDLES}-entry limit`
+      );
+    }
+
+    return buildFieldFilter(needle, "in", [...candidates]);
+  }
+
+  if (isResolvedFieldReference(receiver) && isResolvedFieldReference(needle)) {
+    // A column-valued needle would need its LIKE metacharacters escaped per row, which
+    // Prisma's filters cannot do (and Prisma leaks wildcards from field references).
+    throw new UnsupportedQueryPlanError(
+      `Cannot translate ${operator} between two columns: Prisma cannot escape LIKE wildcards held in a column`
+    );
+  }
+
+  throw new UnsupportedQueryPlanError(
+    `${operator} between two constants must be folded by the Cerbos planner`
+  );
+}

package/src/ternary.ts

@@ -0,0 +1,359 @@
+// `cond ? a : b`, in boolean position and as an operand of a comparison. Both lower to the same
+// guarded disjunction, which keeps CEL's error semantics when the condition is UNKNOWN.
+
+import type { PlanExpressionOperand, Value } from "@cerbos/core";
+
+import { handleRelationalOperator } from "./comparison";
+import { evaluateConstantComparison } from "./evaluate";
+import { rejectConstantFalse } from "./fields";
+import type { PrismaFilter } from "./index";
+import type { TranslationContext } from "./mapping";
+import {
+  CERBOS_TO_PRISMA_OPERATOR,
+  assertDefined,
+  isOperatorOperand,
+  isValueOperand,
+  normalizeBinaryOperands,
+} from "./plan";
+import {
+  buildNegatedFilter,
+  buildPrismaFilterFromCerbosExpression,
+} from "./translate";
+import { normalizeRfc3339Milliseconds } from "./timestamp";
+import { UnsupportedQueryPlanError } from "./errors";
+import { isBoolean, isString, lookup } from "./narrowing";
+
+/** What one ternary branch contributes: a known constant, or a filter to be guarded. */
+type TernaryBranchPredicate =
+  | { kind: "constant"; value: boolean }
+  | { kind: "filter"; filter: PrismaFilter };
+
+// The comparison that holds exactly when `operator` does not, over two definite operands.
+const COMPLEMENT_OPERATOR = {
+  eq: "ne",
+  ne: "eq",
+  lt: "ge",
+  le: "gt",
+  gt: "le",
+  ge: "lt",
+} satisfies Record<string, string>;
+
+type TernaryOperands = {
+  condition: PlanExpressionOperand;
+  thenBranch: PlanExpressionOperand;
+  elseBranch: PlanExpressionOperand;
+};
+
+function getTernaryOperands(operands: PlanExpressionOperand[]): TernaryOperands {
+  if (operands.length !== 3) {
+    throw new UnsupportedQueryPlanError(
+      `if (ternary) requires exactly 3 operands (condition, then, else), got ${operands.length}`
+    );
+  }
+
+  return {
+    condition: assertDefined(
+      operands[0],
+      "if (ternary) requires a condition operand"
+    ),
+    thenBranch: assertDefined(
+      operands[1],
+      "if (ternary) requires a then operand"
+    ),
+    elseBranch: assertDefined(
+      operands[2],
+      "if (ternary) requires an else operand"
+    ),
+  };
+}
+
+function getConstantBooleanCondition(
+  condition: PlanExpressionOperand
+): boolean | undefined {
+  if (!isValueOperand(condition)) {
+    return undefined;
+  }
+
+  if (!isBoolean(condition.value)) {
+    throw new UnsupportedQueryPlanError("if (ternary) condition must be a boolean expression");
+  }
+
+  return condition.value;
+}
+
+function buildBooleanBranchFilter(
+  branch: PlanExpressionOperand,
+  context: TranslationContext
+): TernaryBranchPredicate {
+  if (!isValueOperand(branch)) {
+    return {
+      kind: "filter",
+      filter: buildPrismaFilterFromCerbosExpression(branch, context),
+    };
+  }
+
+  if (!isBoolean(branch.value)) {
+    throw new UnsupportedQueryPlanError(
+      "if (ternary) branch in boolean position must be a boolean"
+    );
+  }
+
+  return { kind: "constant", value: branch.value };
+}
+
+/**
+ * `(cond AND then) OR (NOT cond AND else) OR (cond AND NOT cond)`, dropping any arm a constant
+ * branch makes redundant.
+ *
+ * "The condition is definitively FALSE" is buildNegatedFilter's contract — three-valued, so a
+ * condition that is UNKNOWN (a NULL column, an erroring lambda body, an absent to-one parent)
+ * selects NEITHER branch. It delegates rather than spelling a second negation. A private copy is
+ * how the ternary missed the hop requirement #315/#316 added: a bare `NOT` over a chain filter is
+ * TRUE when the to-one parent is absent, so the else-branch was selected for rows CEL denies
+ * outright — the missing path is an evaluation error, not a false condition
+ * (cerbos/query-plan-adapters#334). Delegating also gives the ternary the De Morgan push-down,
+ * which a chained `and`/`or` condition needs for CEL's error absorption to survive.
+ */
+function buildGuardedTernaryFilter(
+  condition: PlanExpressionOperand,
+  thenFilter: TernaryBranchPredicate,
+  elseFilter: TernaryBranchPredicate,
+  context: TranslationContext
+): PrismaFilter {
+  const conditionTrue = buildPrismaFilterFromCerbosExpression(
+    condition,
+    context
+  );
+
+  const conditionFalse = buildNegatedFilter(condition, context);
+  const guardedBranches: PrismaFilter[] = [];
+
+  if (thenFilter.kind === "filter") {
+    guardedBranches.push({ AND: [conditionTrue, thenFilter.filter] });
+  } else if (thenFilter.value) {
+    guardedBranches.push(conditionTrue);
+  }
+
+  if (elseFilter.kind === "filter") {
+    guardedBranches.push({ AND: [conditionFalse, elseFilter.filter] });
+  } else if (elseFilter.value) {
+    guardedBranches.push(conditionFalse);
+  }
+
+  // For a known condition this contradiction is false. If the condition is
+  // NULL/error-derived, both sides are SQL UNKNOWN, which keeps the whole
+  // ternary UNKNOWN under an outer NOT instead of authorizing the row.
+  guardedBranches.push({ AND: [conditionTrue, conditionFalse] });
+
+  return { OR: guardedBranches };
+}
+
+function finalizeTernaryBranchPredicate(
+  predicate: TernaryBranchPredicate
+): PrismaFilter {
+  if (predicate.kind === "filter") {
+    return predicate.filter;
+  }
+
+  return predicate.value ? {} : rejectConstantFalse();
+}
+
+export function handleBooleanTernaryOperator(
+  operands: PlanExpressionOperand[],
+  context: TranslationContext
+): PrismaFilter {
+  const { condition, thenBranch, elseBranch } = getTernaryOperands(operands);
+  const constantCondition = getConstantBooleanCondition(condition);
+
+  if (constantCondition !== undefined) {
+    return finalizeTernaryBranchPredicate(
+      buildBooleanBranchFilter(
+        constantCondition ? thenBranch : elseBranch,
+        context
+      )
+    );
+  }
+
+  return buildGuardedTernaryFilter(
+    condition,
+    buildBooleanBranchFilter(thenBranch, context),
+    buildBooleanBranchFilter(elseBranch, context),
+    context
+  );
+}
+
+/** The comparison with its ternary operand replaced by `branch`, as a branch predicate. */
+// A timestamp() literal compares as its canonical instant, never against a bare string.
+function constantOf(
+  operand: PlanExpressionOperand | undefined
+): { value: Value; timestamp: boolean } | undefined {
+  if (operand === undefined) return undefined;
+
+  if (isValueOperand(operand)) return { value: operand.value, timestamp: false };
+
+  if (
+    isOperatorOperand(operand) &&
+    operand.operator === "timestamp" &&
+    operand.operands.length === 1
+  ) {
+    const literal = operand.operands[0];
+
+    if (literal !== undefined && isValueOperand(literal) && isString(literal.value)) {
+      return { value: normalizeRfc3339Milliseconds(literal.value), timestamp: true };
+    }
+  }
+
+  return undefined;
+}
+
+function buildTernaryComparisonBranch(
+  operator: string,
+  operands: PlanExpressionOperand[],
+  ternaryIndex: number,
+  branch: PlanExpressionOperand,
+  context: TranslationContext,
+  negated: boolean
+): TernaryBranchPredicate {
+  const substitutedOperands = operands.map((operand, index) =>
+    index === ternaryIndex ? branch : operand
+  );
+
+  assertDefined(substitutedOperands[0], `${operator} requires a left operand`);
+  assertDefined(substitutedOperands[1], `${operator} requires a right operand`);
+
+  // Membership is not symmetric: its member stays first even when it is the constant.
+  const normalized =
+    operator === "in"
+      ? { operator, operands: substitutedOperands }
+      : normalizeBinaryOperands(operator, substitutedOperands);
+
+  const [normalizedFirst, normalizedSecond] = normalized.operands;
+  const first = constantOf(normalizedFirst);
+  const second = constantOf(normalizedSecond);
+
+  if (
+    normalized.operands.length === 2 &&
+    first !== undefined &&
+    second !== undefined &&
+    first.timestamp === second.timestamp
+  ) {
+    return {
+      kind: "constant",
+      value:
+        evaluateConstantComparison(
+          normalized.operator,
+          first.value,
+          second.value
+        ) !== negated,
+    };
+  }
+
+  if (!negated) {
+    return {
+      kind: "filter",
+      filter: buildPrismaFilterFromCerbosExpression(normalized, context),
+    };
+  }
+
+  const nested = tryHandleTernaryComparison(
+    normalized.operator,
+    normalized.operands,
+    context,
+    true
+  );
+
+  if (nested !== null) return { kind: "filter", filter: nested };
+
+  if (normalized.operator === "in") {
+    return {
+      kind: "filter",
+      filter: buildNegatedFilter(
+        { operator: "in", operands: normalized.operands },
+        context
+      ),
+    };
+  }
+
+  // Keep missing-value and relation guards inside the selected branch. Constants
+  // are negated above, since !(NaN <= n) is true but NaN > n is false in CEL 0.30.
+  return {
+    kind: "filter",
+    filter: handleRelationalOperator(
+      assertDefined(
+        lookup(COMPLEMENT_OPERATOR, normalized.operator),
+        "Unsupported negated comparison"
+      ),
+      normalized.operands,
+      context
+    ),
+  };
+}
+
+/**
+ * A comparison or membership test with a ternary operand (`(c ? a : b) == x`,
+ * `x in (c ? a : b)`), translated by distributing the
+ * comparison into both branches; or null when `operator` is not a comparison or no operand is a
+ * ternary. `negated` builds the filter for the comparison's negation instead.
+ */
+export function tryHandleTernaryComparison(
+  operator: string,
+  operands: PlanExpressionOperand[],
+  context: TranslationContext,
+  negated = false
+): PrismaFilter | null {
+  if (lookup(CERBOS_TO_PRISMA_OPERATOR, operator) === undefined && operator !== "in") {
+    return null;
+  }
+
+  const ternaryIndex = operands.findIndex(
+    (operand) => isOperatorOperand(operand) && operand.operator === "if"
+  );
+
+  if (ternaryIndex === -1) {
+    return null;
+  }
+
+  if (operands.length !== 2) {
+    throw new UnsupportedQueryPlanError(
+      `${operator} with a ternary requires exactly 2 operands, got ${operands.length}`
+    );
+  }
+
+  const ternary = assertDefined(
+    operands[ternaryIndex],
+    "Ternary comparison operand is missing"
+  );
+
+  if (!isOperatorOperand(ternary)) {
+    throw new UnsupportedQueryPlanError("Ternary comparison operand must be an expression");
+  }
+
+  const { condition, thenBranch, elseBranch } = getTernaryOperands(
+    ternary.operands
+  );
+
+  const branchFor = (branch: PlanExpressionOperand) =>
+    buildTernaryComparisonBranch(
+      operator,
+      operands,
+      ternaryIndex,
+      branch,
+      context,
+      negated
+    );
+
+  const constantCondition = getConstantBooleanCondition(condition);
+
+  if (constantCondition !== undefined) {
+    return finalizeTernaryBranchPredicate(
+      branchFor(constantCondition ? thenBranch : elseBranch)
+    );
+  }
+
+  return buildGuardedTernaryFilter(
+    condition,
+    branchFor(thenBranch),
+    branchFor(elseBranch),
+    context
+  );
+}

package/src/test-setup.adversarial-url.ts

@@ -0,0 +1,21 @@
+/**
+ * The connection string a container-backed adversarial leg runs against — PostgreSQL or MySQL.
+ *
+ * `jest.globalSetup.adversarial.js` starts the container and exports `DATABASE_URL` before any
+ * test module loads. Throwing when it is missing is the point: a client that silently connected
+ * somewhere else — a developer's local PostgreSQL, an empty SQLite file — would replay the corpus
+ * against rows nobody seeded and report a passing differential over an empty store.
+ */
+export function adversarialDatabaseUrl(): string {
+  const url = process.env["DATABASE_URL"];
+
+  if (!url) {
+    throw new Error(
+      "DATABASE_URL is not set: a container-backed adversarial leg is started by " +
+        "jest.globalSetup.adversarial.js, so run it through " +
+        "`npm run test:adversarial:postgres` or `npm run test:adversarial:mysql`"
+    );
+  }
+
+  return url;
+}

package/src/test-setup.adversarial.mysql.v6.ts

@@ -0,0 +1,13 @@
+import { Prisma, PrismaClient } from "./generated/prisma-adversarial-mysql-v6";
+
+import { adversarialDatabaseUrl } from "./test-setup.adversarial-url";
+
+// Prisma 6 reads the datasource URL from the schema's `env("DATABASE_URL")`, which the jest
+// globalSetup exports once the container is up. Passing it explicitly as well keeps the failure
+// mode loud: `adversarialDatabaseUrl` throws when the variable is missing, rather than letting the
+// client fall back to whatever a developer happens to have in their environment.
+const prisma = new PrismaClient({
+  datasources: { db: { url: adversarialDatabaseUrl() } },
+});
+
+export { prisma, Prisma };

package/src/test-setup.adversarial.mysql.v7.ts

@@ -0,0 +1,12 @@
+import { PrismaMariaDb } from "@prisma/adapter-mariadb";
+import { Prisma, PrismaClient } from "./generated/prisma-adversarial-mysql/client";
+
+import { adversarialDatabaseUrl } from "./test-setup.adversarial-url";
+
+// Prisma 7 reaches a database only through a driver adapter, and `@prisma/adapter-mariadb` is the
+// one Prisma ships for the MySQL provider — the MariaDB connector speaks the MySQL protocol,
+// including MySQL 8.4's caching_sha2_password default.
+const adapter = new PrismaMariaDb(adversarialDatabaseUrl());
+const prisma = new PrismaClient({ adapter });
+
+export { prisma, Prisma };

package/src/test-setup.adversarial.pg.v6.ts

@@ -0,0 +1,13 @@
+import { Prisma, PrismaClient } from "./generated/prisma-adversarial-pg-v6";
+
+import { adversarialDatabaseUrl } from "./test-setup.adversarial-url";
+
+// Prisma 6 reads the datasource URL from the schema's `env("DATABASE_URL")`, which the jest
+// globalSetup exports once the container is up. Passing it explicitly as well keeps the failure
+// mode loud: `adversarialDatabaseUrl` throws when the variable is missing, rather than letting the
+// client fall back to whatever a developer happens to have in their environment.
+const prisma = new PrismaClient({
+  datasources: { db: { url: adversarialDatabaseUrl() } },
+});
+
+export { prisma, Prisma };

package/src/test-setup.adversarial.pg.v7.ts

@@ -0,0 +1,9 @@
+import { PrismaPg } from "@prisma/adapter-pg";
+import { Prisma, PrismaClient } from "./generated/prisma-adversarial-pg/client";
+
+import { adversarialDatabaseUrl } from "./test-setup.adversarial-url";
+
+const adapter = new PrismaPg({ connectionString: adversarialDatabaseUrl() });
+const prisma = new PrismaClient({ adapter });
+
+export { prisma, Prisma };

package/src/test-setup.adversarial.v7.ts

@@ -7,6 +7,7 @@ import {
 const adapter = new PrismaBetterSqlite3({
   url: "./prisma/dev-adversarial.db",
 });
+
 const prisma = new PrismaClient({ adapter });
 
 export { prisma, Prisma };