@cerbos/orm-prisma 4.0.0 → 5.0.0

package/src/presence.ts

@@ -0,0 +1,114 @@
+// `has()`, the presence test the planner emits from Cerbos 0.57.0 for an attribute it does not
+// fold into a guard: whether the caller's attributes carry the key at all.
+
+import type { PlanExpressionOperand } from "@cerbos/core";
+
+import type { PrismaFilter } from "./index";
+import { getLeafField, namesToOneRelation, resolveFieldReference } from "./mapping";
+import type { TranslationContext } from "./mapping";
+import { isNamedOperand } from "./plan";
+import type { OperatorOperand } from "./plan";
+import { negateFilter, wrapInRelations } from "./relations";
+import { UnsupportedQueryPlanError } from "./errors";
+
+/**
+ * `has(ref)`, or `!has(ref)` when `negated`.
+ *
+ * Presence is a property of the caller's null convention, not of the column: an attribute sent as
+ * an explicit null is present, so `has()` is true for every row, and one omitted when its column
+ * is NULL is present exactly when the column is not NULL. Element columns inside a lambda follow
+ * the omitted convention unless they are declared `nullable: false`, as the collection macros
+ * already assume. A to-one relation is present when the related row exists.
+ *
+ * `has()` itself never errors on a missing value, so `!has()` is a plain NOT. The one error it can
+ * raise is selecting through a missing to-one hop, `has(parent.x)` on a parentless row, which
+ * denies under both polarities, so every hop BEFORE the tested key is required outside the NOT.
+ */
+export function handleHasOperator(
+  operands: PlanExpressionOperand[],
+  context: TranslationContext,
+  negated: boolean
+): PrismaFilter {
+  const [operand] = operands;
+
+  if (operands.length !== 1 || operand === undefined || !isNamedOperand(operand)) {
+    throw new UnsupportedQueryPlanError("has requires exactly one attribute reference");
+  }
+
+  const fieldRef = resolveFieldReference(operand.name, context);
+  const relations = fieldRef.relations ?? [];
+
+  if (relations.some((relation) => relation.type === "many")) {
+    throw new UnsupportedQueryPlanError(
+      `Cannot translate has(${operand.name}): a presence test over a to-many relation has no ` +
+        "Prisma filter that matches what the caller sends for it"
+    );
+  }
+
+  let presence: PrismaFilter;
+  let hops = relations;
+
+  if (namesToOneRelation(context.mapper, operand.name)) {
+    presence = wrapInRelations(relations, {});
+    hops = relations.slice(0, -1);
+  } else if (presenceFollowsColumn(operand.name, fieldRef, context)) {
+    presence = wrapInRelations(relations, {
+      [getLeafField(fieldRef.path)]: { not: null },
+    });
+  } else {
+    presence = wrapInRelations(relations, {});
+  }
+
+  if (!negated) return presence;
+  const absence = negateFilter(presence);
+
+  return hops.length === 0 ? absence : { AND: [wrapInRelations(hops, {}), absence] };
+}
+
+/**
+ * `has(R.attr.x)` on an attribute sent as an explicit null is true on every row, so it becomes the
+ * constant `true` before translation. Left to the translator it lowers to `{}`, which Prisma drops
+ * from an OR or a NOT, losing the rows it admits and, negated, admitting rows it denies.
+ */
+export function constantPresence(
+  node: OperatorOperand,
+  context: TranslationContext
+): PlanExpressionOperand | undefined {
+  const [operand] = node.operands;
+
+  if (
+    node.operator !== "has" ||
+    node.operands.length !== 1 ||
+    operand === undefined ||
+    !isNamedOperand(operand) ||
+    !operand.name.startsWith("request.") ||
+    namesToOneRelation(context.mapper, operand.name)
+  ) {
+    return undefined;
+  }
+
+  const fieldRef = resolveFieldReference(operand.name, context);
+
+  if ((fieldRef.relations ?? []).length > 0) return undefined;
+
+  return presenceFollowsColumn(operand.name, fieldRef, context) ? undefined : { value: true };
+}
+
+/** Whether a NULL column means the key is absent, rather than sent as an explicit null. */
+function presenceFollowsColumn(
+  reference: string,
+  fieldRef: ReturnType<typeof resolveFieldReference>,
+  context: TranslationContext
+): boolean {
+  const element = context.scopes.some((scope) =>
+    reference.startsWith(scope.variableName + ".")
+  );
+
+  if (element && fieldRef.nullAttributeRepresentation === undefined) {
+    return fieldRef.nullable !== false;
+  }
+
+  return (
+    (fieldRef.nullAttributeRepresentation ?? context.nullRepresentation) === "omitted"
+  );
+}

package/src/regex.ts

@@ -0,0 +1,596 @@
+// `matches(column, "pattern")` for the RE2 patterns whose language a boolean combination of LIKE
+// filters decides exactly. Everything else is refused.
+
+import type { PlanExpressionOperand } from "@cerbos/core";
+import { RE2JS } from "re2js";
+
+import { assertStringField, buildFieldFilter, buildPrefixFilter } from "./fields";
+import type { PrismaFilter } from "./index";
+import { isResolvedFieldReference, resolveFieldReference } from "./mapping";
+import type { ResolvedFieldReference, TranslationContext } from "./mapping";
+import { isNamedOperand, isValueOperand } from "./plan";
+import { UnsupportedQueryPlanError } from "./errors";
+import { isString, pair } from "./narrowing";
+
+/** Past this many alternatives, a pattern is refused rather than spelled out. */
+const MAX_ALTERNATIVES = 256;
+
+// -- the pattern ---------------------------------------------------------------------------------
+
+/** One position of an expanded pattern: a literal character, `.` (not a newline), or `.*`. */
+type Token = { char: string } | { any: true } | { star: true };
+
+type Node =
+  | { kind: "alt"; branches: Node[][] }
+  | { kind: "char"; chars: string[] }
+  | { kind: "any" }
+  | { kind: "begin" }
+  | { kind: "end" }
+  | { kind: "repeat"; node: Node; min: number; max: number };
+
+/**
+ * A pattern RE2 itself rejects, as the parser below sees it. Whether RE2 rejects a pattern is
+ * decided by re2js (isInvalidPattern), not by this parser, whose refusals are always safe.
+ */
+export class InvalidRegexError extends Error {}
+
+function refuse(pattern: string, why: string): never {
+  throw new UnsupportedQueryPlanError(
+    `Cannot translate matches() with pattern ${JSON.stringify(pattern)}: ${why}. Prisma has no ` +
+      "regex filter; only patterns a combination of LIKE filters decides exactly are translated"
+  );
+}
+
+const DIGITS = [..."0123456789"];
+
+/**
+ * A repetition count, `{n}`, `{n,}` or `{n,m}`; any other brace is a literal to RE2. A count is
+ * read as Go's `regexp/syntax` `parseInt` reads it, which takes no leading zero: `a{01}` is `a`
+ * then the text "{01}".
+ */
+const REPEAT = /^\{(0|[1-9]\d*)(,(0|[1-9]\d*)?)?\}/;
+
+/** RE2's bound on the copies a counted repetition, nested ones included, may make. */
+const MAX_REPEAT = 1000;
+
+/**
+ * Go's `repeatIsValid`: each repetition divides the budget by its count (its maximum, or its
+ * minimum when unbounded), and a count beyond what is left is invalid: `(a{2}){600}`.
+ */
+function repeatIsValid(node: Node, budget: number): boolean {
+  switch (node.kind) {
+    case "repeat": {
+      if (node.max === 0) return true;
+      const count = node.max === Infinity ? node.min : node.max;
+
+      if (count > budget) return false;
+
+      return repeatIsValid(node.node, count === 0 ? budget : Math.floor(budget / count));
+    }
+
+    case "alt":
+      return node.branches.every((branch) => branch.every((inner) => repeatIsValid(inner, budget)));
+    default:
+      return true;
+  }
+}
+
+/** RE2's simple case folding over ASCII letters: `k` and `s` fold with a non-ASCII sign too. */
+function foldOrbit(char: string): string[] {
+  const lower = char.toLowerCase();
+
+  if (!/^[a-z]$/.test(lower)) return [char];
+  const orbit = [lower, lower.toUpperCase()];
+
+  if (lower === "k") orbit.push("K");
+
+  if (lower === "s") orbit.push("ſ");
+
+  return orbit;
+}
+
+/** A recursive-descent parser over the pattern's code points (RE2 matches code points). */
+class Parser {
+  private index = 0;
+  private caseInsensitive = false;
+  private readonly chars: string[];
+
+  constructor(private readonly pattern: string) {
+    this.chars = Array.from(pattern);
+  }
+
+  parse(): Node[][] {
+    if (this.pattern.startsWith("(?i)")) {
+      this.caseInsensitive = true;
+      this.index = 4;
+    }
+
+    const branches = this.alternation();
+
+    if (this.index !== this.chars.length) refuse(this.pattern, "unbalanced parenthesis");
+
+    return branches;
+  }
+
+  private peek(offset = 0): string | undefined {
+    return this.chars[this.index + offset];
+  }
+
+  private rest(): string {
+    return this.chars.slice(this.index).join("");
+  }
+
+  private next(): string | undefined {
+    return this.chars[this.index++];
+  }
+
+  private alternation(): Node[][] {
+    const branches: Node[][] = [this.sequence()];
+
+    while (this.peek() === "|") {
+      this.index++;
+      branches.push(this.sequence());
+    }
+
+    return branches;
+  }
+
+  private sequence(): Node[] {
+    const nodes: Node[] = [];
+
+    for (let char = this.peek(); char !== undefined && char !== "|" && char !== ")"; char = this.peek()) {
+      nodes.push(this.quantified(this.atom()));
+    }
+
+    return nodes;
+  }
+
+  private quantified(node: Node): Node {
+    const char = this.peek();
+    let min: number;
+    let max: number;
+
+    if (char === "*" || char === "+" || char === "?") {
+      this.index++;
+      [min, max] = char === "*" ? [0, Infinity] : char === "+" ? [1, Infinity] : [0, 1];
+    } else if (char === "{") {
+      const match = REPEAT.exec(this.rest());
+
+      // RE2 reads a brace that does not open a repetition as a literal.
+      if (match === null) return node;
+      this.index += Array.from(match[0]).length;
+      min = Number(match[1]);
+      max = match[2] === undefined ? min : match[3] === undefined ? Infinity : Number(match[3]);
+
+      if (min > MAX_REPEAT || (max !== Infinity && (max > MAX_REPEAT || max < min))) {
+        throw new InvalidRegexError("invalid repeat count");
+      }
+    } else {
+      return node;
+    }
+
+    const next = this.peek();
+
+    if (next === "?") refuse(this.pattern, "non-greedy repetition");
+
+    if (next === "*" || next === "+" || (next === "{" && REPEAT.test(this.rest()))) {
+      throw new InvalidRegexError("invalid nested repetition");
+    }
+
+    if (node.kind === "begin" || node.kind === "end") {
+      refuse(this.pattern, "a repeated anchor");
+    }
+
+    const repeat: Node = { kind: "repeat", node, min, max };
+
+    if (!repeatIsValid(repeat, MAX_REPEAT)) throw new InvalidRegexError("invalid repeat count");
+
+    return repeat;
+  }
+
+  private atom(): Node {
+    const char = this.next()!;
+
+    switch (char) {
+      case "^":
+        return { kind: "begin" };
+      case "$":
+        return { kind: "end" };
+      case ".":
+        return { kind: "any" };
+      case "(": {
+        if (this.peek() === "?") {
+          const rest = this.rest();
+
+          if (/^\?(=|!|<=|<!)/.test(rest)) throw new InvalidRegexError("lookaround");
+
+          if (rest.startsWith("?:")) {
+            this.index += 2;
+          } else {
+            refuse(this.pattern, "a group flag");
+          }
+        }
+
+        const branches = this.alternation();
+
+        if (this.peek() !== ")") refuse(this.pattern, "unbalanced parenthesis");
+        this.index++;
+
+        return { kind: "alt", branches };
+      }
+
+      case "[":
+        return this.characterClass();
+      case "\\":
+        return this.escape();
+      case "*":
+      case "+":
+      case "?":
+        throw new InvalidRegexError("missing argument to repetition operator");
+      case "{":
+        // A count with nothing before it to repeat; a brace that is not a count stays a literal.
+        if (REPEAT.test(`{${this.rest()}`)) {
+          throw new InvalidRegexError("missing argument to repetition operator");
+        }
+
+        return this.literal(char);
+      default:
+        return this.literal(char);
+    }
+  }
+
+  private literal(char: string): Node {
+    if (this.caseInsensitive && /[^\x00-\x7F]/.test(char)) {
+      refuse(this.pattern, "case-insensitive matching of a non-ASCII character");
+    }
+
+    return { kind: "char", chars: this.caseInsensitive ? foldOrbit(char) : [char] };
+  }
+
+  private escape(): Node {
+    const char = this.next();
+
+    if (char === undefined) throw new InvalidRegexError("trailing backslash");
+
+    if (char === "d") return { kind: "char", chars: DIGITS };
+    const octal = this.octalEscape(char);
+
+    if (octal !== undefined) return this.literal(octal);
+
+    if (/[A-Za-z0-9]/.test(char)) refuse(this.pattern, `the escape \\${char}`);
+
+    return this.literal(char);
+  }
+
+  /**
+   * The character of an octal escape whose first digit was just read, as Go's regexp/syntax reads
+   * it: `\0` on its own, and `\1` to `\7` only when another octal digit follows (alone, each is
+   * a backreference, which RE2 rejects); up to three digits in all. `\11` is a tab.
+   */
+  private octalEscape(first: string): string | undefined {
+    const isOctal = (c: string | undefined): c is string => c !== undefined && c >= "0" && c <= "7";
+
+    if (!isOctal(first)) {
+      if (/[89]/.test(first)) throw new InvalidRegexError(`invalid escape sequence: \\${first}`);
+
+      return undefined;
+    }
+
+    if (first !== "0" && !isOctal(this.peek())) {
+      throw new InvalidRegexError(`invalid escape sequence: \\${first}`);
+    }
+
+    let code = Number(first);
+
+    for (let digits = 1; digits < 3 && isOctal(this.peek()); digits++) {
+      code = code * 8 + Number(this.next());
+    }
+
+    return String.fromCodePoint(code);
+  }
+
+  private characterClass(): Node {
+    if (this.peek() === "^") refuse(this.pattern, "a negated character class");
+    const chars = new Set<string>();
+    let first = true;
+
+    for (;;) {
+      const char = this.next();
+
+      if (char === undefined) throw new InvalidRegexError("missing closing ]");
+
+      if (char === "]" && !first) break;
+      first = false;
+
+      if (char === "[" && this.rest().startsWith(":digit:]")) {
+        this.index += ":digit:]".length;
+        DIGITS.forEach((digit) => chars.add(digit));
+        continue;
+      }
+
+      if (char === "[" && this.peek() === ":") refuse(this.pattern, "a POSIX class other than digit");
+      let from = char;
+
+      if (char === "\\") {
+        const escaped = this.next();
+
+        if (escaped === undefined) throw new InvalidRegexError("trailing backslash");
+
+        if (escaped === "d") {
+          DIGITS.forEach((digit) => chars.add(digit));
+          continue;
+        }
+
+        const octal = this.octalEscape(escaped);
+
+        if (octal !== undefined) {
+          from = octal;
+        } else {
+          if (/[A-Za-z0-9]/.test(escaped)) refuse(this.pattern, `the escape \\${escaped}`);
+          from = escaped;
+        }
+      }
+
+      if (this.peek() === "-" && this.peek(1) !== "]") {
+        this.index++;
+        const to = this.next();
+
+        if (to === undefined || to === "\\") refuse(this.pattern, "an escaped class range");
+        const start = from.codePointAt(0)!;
+        const end = to.codePointAt(0)!;
+
+        if (end < start) throw new InvalidRegexError("invalid character class range");
+
+        if (end - start > 128) refuse(this.pattern, "a wide character range");
+
+        for (let code = start; code <= end; code++) chars.add(String.fromCodePoint(code));
+        continue;
+      }
+
+      chars.add(from);
+    }
+
+    const members = [...chars].flatMap((char) => {
+      if (this.caseInsensitive && /[^\x00-\x7F]/.test(char)) {
+        refuse(this.pattern, "case-insensitive matching of a non-ASCII character");
+      }
+
+      return this.caseInsensitive ? foldOrbit(char) : [char];
+    });
+
+    return { kind: "char", chars: [...new Set(members)] };
+  }
+}
+
+// -- expansion -----------------------------------------------------------------------------------
+
+type Expansion = { begin: boolean; end: boolean; tokens: Token[] };
+
+function product(pattern: string, left: Token[][], right: Token[][]): Token[][] {
+  if (left.length * right.length > MAX_ALTERNATIVES) {
+    refuse(pattern, `more than ${MAX_ALTERNATIVES} alternatives`);
+  }
+
+  return left.flatMap((l) => right.map((r) => [...l, ...r]));
+}
+
+/** Every token sequence `nodes` (holding no anchor) can match. */
+function expand(pattern: string, nodes: Node[]): Token[][] {
+  let sequences: Token[][] = [[]];
+
+  for (const node of nodes) {
+    sequences = product(pattern, sequences, expandNode(pattern, node));
+  }
+
+  return sequences;
+}
+
+function expandNode(pattern: string, node: Node): Token[][] {
+  switch (node.kind) {
+    case "char":
+      return node.chars.map((char) => [{ char }]);
+    case "any":
+      return [[{ any: true }]];
+    case "alt": {
+      const all = node.branches.flatMap((branch) => expand(pattern, branch));
+
+      if (all.length > MAX_ALTERNATIVES) refuse(pattern, `more than ${MAX_ALTERNATIVES} alternatives`);
+
+      return all;
+    }
+
+    case "repeat": {
+      if (node.max === Infinity) {
+        if (node.node.kind !== "any") refuse(pattern, "unbounded repetition of anything but .");
+
+        return [[...Array.from({ length: node.min }, (): Token => ({ any: true })), { star: true }]];
+      }
+
+      const unit = expandNode(pattern, node.node);
+      const results: Token[][] = [];
+      let power: Token[][] = [[]];
+
+      for (let count = 0; count <= node.max; count++) {
+        if (count >= node.min) results.push(...power);
+
+        if (results.length > MAX_ALTERNATIVES) refuse(pattern, `more than ${MAX_ALTERNATIVES} alternatives`);
+
+        if (count < node.max) power = product(pattern, power, unit);
+      }
+
+      return results;
+    }
+
+    default:
+      refuse(pattern, "an anchor inside a group or away from the pattern's ends");
+  }
+}
+
+/** The pattern as alternatives, each anchored at its ends or not. */
+export function expandPattern(pattern: string): Expansion[] {
+  const branches = new Parser(pattern).parse();
+  const expansions: Expansion[] = [];
+
+  for (const branch of branches) {
+    let nodes = branch;
+    const begin = nodes[0]?.kind === "begin";
+
+    if (begin) nodes = nodes.slice(1);
+    const end = nodes[nodes.length - 1]?.kind === "end";
+
+    if (end) nodes = nodes.slice(0, -1);
+
+    for (const tokens of expand(pattern, nodes)) {
+      expansions.push({ begin, end, tokens });
+
+      if (expansions.length > MAX_ALTERNATIVES) {
+        refuse(pattern, `more than ${MAX_ALTERNATIVES} alternatives`);
+      }
+    }
+  }
+
+  return expansions;
+}
+
+// -- the filter ----------------------------------------------------------------------------------
+
+const LIKE_METACHARACTERS = /[%_\\]/;
+
+/**
+ * One alternative as a filter on the column. Without a wildcard it is `equals`, `startsWith`,
+ * `endsWith` or `contains` as its anchors say. With one, only a pattern anchored at both ends is
+ * translated: a LIKE of `_` for `.` and `%` for `.*`, and no newline anywhere in the value — the
+ * literal characters are not newlines, so every newline in a match falls in a wildcard, which RE2's
+ * `.` does not match.
+ */
+function alternativeFilter(
+  pattern: string,
+  fieldRef: ResolvedFieldReference,
+  { begin, end, tokens }: Expansion
+): PrismaFilter {
+  const characters = tokens.flatMap((token) => ("char" in token ? [token.char] : []));
+  const literal = characters.length === tokens.length ? characters.join("") : undefined;
+
+  if (literal !== undefined && begin && end) {
+    return buildFieldFilter(fieldRef, "equals", literal);
+  }
+
+  const likeText = tokens
+    .map((token) => ("char" in token ? token.char : "any" in token ? "_" : "%"))
+    .join("");
+
+  // A prefix is matched as a range, so it needs no escaping (see buildPrefixFilter).
+  if (literal !== undefined && begin) return buildPrefixFilter(fieldRef, literal);
+  const literals = tokens.flatMap((token) => ("char" in token ? [token.char] : []));
+
+  if (literals.some((char) => LIKE_METACHARACTERS.test(char))) {
+    refuse(pattern, "a literal LIKE metacharacter (%, _ or \\), which Prisma does not escape");
+  }
+
+  if (literal !== undefined) {
+    return buildFieldFilter(fieldRef, end ? "endsWith" : "contains", literal);
+  }
+
+  if (!begin || !end) {
+    refuse(pattern, "a wildcard in a pattern not anchored at both ends");
+  }
+
+  if (literals.includes("\n")) refuse(pattern, "a literal newline beside a wildcard");
+  const noNewline: PrismaFilter = { NOT: buildFieldFilter(fieldRef, "contains", "\n") };
+  const segments = likeText.split("%");
+
+  if (segments.length === 1) {
+    // Exactly the pattern's length: it matches as a prefix, and one more character never fits.
+    return {
+      AND: [
+        buildFieldFilter(fieldRef, "startsWith", likeText),
+        { NOT: buildFieldFilter(fieldRef, "startsWith", `${likeText}_`) },
+        noNewline,
+      ],
+    };
+  }
+
+  if (segments.length > 2) refuse(pattern, "more than one .* in one alternative");
+  // `A.*B`: A at the start, B at the end, and room for both without overlapping.
+  const [head, tail] = pair(segments);
+  const filters: PrismaFilter[] = [];
+
+  if (head !== "") filters.push(buildFieldFilter(fieldRef, "startsWith", head));
+
+  if (tail !== "") filters.push(buildFieldFilter(fieldRef, "endsWith", tail));
+
+  if (head !== "" && tail !== "") {
+    filters.push(buildFieldFilter(fieldRef, "startsWith", "_".repeat(Array.from(head).length + Array.from(tail).length)));
+  }
+
+  if (filters.length === 0) filters.push(buildFieldFilter(fieldRef, "startsWith", ""));
+
+  return { AND: [...filters, noNewline] };
+}
+
+/**
+ * Whether the pattern is one RE2 rejects, so that `matches()` raises an error on every row: what
+ * re2js, a port of RE2, refuses to compile. A pattern this adapter cannot translate is not invalid;
+ * it is refused when translated.
+ */
+export function isInvalidPattern(pattern: string): boolean {
+  return re2Rejection(pattern) !== undefined;
+}
+
+/** RE2's reason for rejecting the pattern, or undefined when it compiles. */
+function re2Rejection(pattern: string): string | undefined {
+  try {
+    RE2JS.compile(pattern);
+
+    return undefined;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+export function handleMatchesOperator(
+  operands: PlanExpressionOperand[],
+  context: TranslationContext
+): PrismaFilter {
+  const [receiver, patternOperand] = operands;
+
+  if (
+    operands.length !== 2 ||
+    receiver === undefined ||
+    !isNamedOperand(receiver) ||
+    patternOperand === undefined ||
+    !isValueOperand(patternOperand) ||
+    !isString(patternOperand.value)
+  ) {
+    throw new UnsupportedQueryPlanError(
+      "matches() is translated only for a column receiver and a literal pattern"
+    );
+  }
+
+  const pattern = patternOperand.value;
+  const fieldRef = resolveFieldReference(receiver.name, context);
+
+  if (!isResolvedFieldReference(fieldRef)) {
+    throw new UnsupportedQueryPlanError("matches() requires a column receiver");
+  }
+
+  assertStringField(fieldRef, "matches");
+  const rejection = re2Rejection(pattern);
+
+  if (rejection !== undefined) refuse(pattern, `RE2 rejects it (${rejection})`);
+  let expansions: Expansion[];
+
+  try {
+    expansions = expandPattern(pattern);
+  } catch (error) {
+    if (error instanceof InvalidRegexError) {
+      refuse(pattern, `RE2 rejects it (${error.message})`);
+    }
+
+    throw error;
+  }
+
+  const filters = expansions.map((expansion) => alternativeFilter(pattern, fieldRef, expansion));
+
+  return filters.length === 1 ? filters[0]! : { OR: filters };
+}