@cerbos/orm-prisma 4.0.0 → 5.0.0

package/src/corpus.ts

@@ -0,0 +1,597 @@
+import * as fs from "fs";
+import * as path from "path";
+import { isDeepStrictEqual } from "util";
+
+import { fromBinary, fromJson, fromJsonString, toBinary } from "@bufbuild/protobuf";
+import type { JsonObject, JsonValue } from "@bufbuild/protobuf";
+import type { PlanResourcesRequest } from "@cerbos/api/cerbos/request/v1/request_pb";
+import type { PlanResourcesResponse as PlanResourcesResponseMessage } from "@cerbos/api/cerbos/response/v1/response_pb";
+import { CerbosService } from "@cerbos/api/cerbos/svc/v1/svc_pb";
+import type { PlanResourcesResponse } from "@cerbos/core";
+import { GRPC } from "@cerbos/grpc";
+import { HTTP } from "@cerbos/http";
+import { Server, ServerCredentials } from "@grpc/grpc-js";
+import type { sendUnaryData, ServerUnaryCall } from "@grpc/grpc-js";
+import { afterAll } from "@jest/globals";
+
+import type { MapperConfig } from ".";
+import { isObject, isString } from "./narrowing";
+
+/**
+ * What both of this adapter's suites read from the shared `../conformance/` corpus: the recorded
+ * golden plans and the one mapper every case is translated through. `adversarial.test.ts` replays
+ * the goldens against a real store; `translator.test.ts` uses the same mapper for the caller-option
+ * tests the corpus cannot vary.
+ *
+ * Duplicated across adapters on purpose — adapters share data, not code (ADR 0007).
+ * Test-only: excluded from `tsc --build` by `tsconfig.json`, so nothing here reaches `lib/`.
+ */
+
+export const CONFORMANCE_DIR = path.join(__dirname, "..", "..", "conformance");
+
+/** A file the conformance generator wrote: its shape is the generator's contract with these types. */
+function readJson<T>(file: string): T {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+export function readCorpusJson<T>(file: string): T {
+  return readJson(path.join(CONFORMANCE_DIR, file));
+}
+
+/** The Prisma model the corpus's resource kind maps onto. */
+export const MODEL = "AdversarialResource";
+
+// -- the golden files ----------------------------------------------------------------------------
+
+export interface Golden {
+  id: string;
+  pdp: string;
+  tier: "core" | "extended" | "adversarial";
+  plan: JsonObject;
+  allowed: string[];
+  plannerDivergence: { pdp?: string[]; issue: string; reason?: string } | null;
+}
+
+/** The PDP tags the goldens were recorded against: current first, then previous. */
+export function pdpTags(): string[] {
+  const versions = readCorpusJson<Record<
+    "current" | "previous",
+    { tag: string }
+  >>("pdp-versions.json");
+
+  return [versions.current.tag, versions.previous.tag];
+}
+
+/** Every golden file recorded against `tag`, sorted by case id. */
+export function readGoldens(tag: string): Golden[] {
+  const root = FUZZ_DIR ? path.join(FUZZ_DIR, tag) : path.join(CONFORMANCE_DIR, "golden", tag);
+
+  const files = fs.readdirSync(root, { recursive: true, encoding: "utf8" })
+    .filter((file) => file.endsWith(".json"))
+    .map((file) => readJson<Golden>(path.join(root, file)));
+
+  return files.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function readGolden(tag: string, id: string): Golden {
+  return readJson(path.join(CONFORMANCE_DIR, "golden", tag, `${id}.json`));
+}
+
+// -- fuzz mode ------------------------------------------------------------------------------------
+
+/**
+ * The directory a fuzz run was recorded into (conformance/README.md, "Fuzzing"). When it is set,
+ * `readGoldens` reads the generated cases from it instead of the corpus, and the harness judges
+ * each case by `fuzzVerdict` instead of the ledger: a refusal is always acceptable, since the
+ * ledger has no entry for a shape nobody has written down yet.
+ */
+export const FUZZ_DIR = process.env["QPA_FUZZ_DIR"] || undefined;
+
+export interface FuzzVerdict {
+  pdp: string;
+  id: string;
+  verdict: "match" | "refused" | "over-grant" | "under-grant" | "error";
+  expected?: string[];
+  returned?: string[];
+  detail?: string;
+}
+
+/** Judges the ids a translated filter returned against the ids the PDP allowed. */
+export function fuzzVerdict(golden: Golden, expected: string[], returned: string[]): FuzzVerdict {
+  const base = { pdp: golden.pdp, id: golden.id };
+
+  // Compared element by element: under jest the arrays come from different realms, which
+  // isDeepStrictEqual tells apart.
+  if (returned.length === expected.length && returned.every((id, i) => id === expected[i])) {
+    return { ...base, verdict: "match" };
+  }
+
+  const allowed = new Set(expected);
+  const got = new Set(returned);
+
+  const verdict = returned.some((id) => !allowed.has(id))
+    ? "over-grant"
+    : expected.some((id) => !got.has(id))
+      ? "under-grant"
+      : "error";
+
+  if (verdict === "error") {
+    return { ...base, verdict, expected, returned, detail: "the right rows, but repeated or out of order" };
+  }
+
+  return { ...base, verdict, expected, returned };
+}
+
+/** A translation or query that threw, judged: the adapter's refusal type is the invariant working. */
+export function fuzzThrown(golden: Golden, cause: unknown, refusal: abstract new (...args: never[]) => Error): FuzzVerdict {
+  const base = { pdp: golden.pdp, id: golden.id };
+
+  if (cause instanceof refusal) return { ...base, verdict: "refused" };
+
+  return { ...base, verdict: "error", detail: cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause) };
+}
+
+/** Fails the case unless its verdict is a match or a refusal. */
+export function assertFuzzVerdict(verdict: FuzzVerdict): void {
+  if (verdict.verdict === "match" || verdict.verdict === "refused") return;
+  throw new Error(
+    `${verdict.verdict}: expected [${verdict.expected?.join(", ") ?? ""}], returned [${verdict.returned?.join(", ") ?? ""}]${verdict.detail ? `: ${verdict.detail}` : ""}`,
+  );
+}
+
+/** Writes `<FUZZ_DIR>/results/<adapter>-<store>.json`, which `fuzz-report` reads. */
+export function writeFuzzResults(adapter: string, store: string, results: FuzzVerdict[]): void {
+  if (!FUZZ_DIR) return;
+  const dir = path.join(FUZZ_DIR, "results");
+  fs.mkdirSync(dir, { recursive: true });
+  const sorted = [...results].sort((a, b) => a.id.localeCompare(b.id) || a.pdp.localeCompare(b.pdp));
+  fs.writeFileSync(
+    path.join(dir, `${adapter}-${store}.json`),
+    `${JSON.stringify({ adapter, store, results: sorted }, null, 2)}\n`,
+  );
+}
+
+/**
+ * The instant substituted for `__NOW_MINUS_24H__`, the literal the planner folds
+ * `now() - duration("24h")` into. The PDP folds its clock at nanosecond precision, so the
+ * substitute carries sub-millisecond digits too: a tidy millisecond instant would translate here
+ * while the same case refuses in production (`Timestamp value exceeds millisecond precision`).
+ */
+export function nowMinus24h(): string {
+  const ms = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+
+  return `${ms.slice(0, -1)}456789Z`;
+}
+
+// -- the plans, as the SDK returns them ----------------------------------------------------------
+
+/*
+ * A golden reaches the adapter through both official JS clients, `@cerbos/http` and
+ * `@cerbos/grpc`, so it arrives as an application's `planResources` call returns it. Only the PDP
+ * is replaced: each transport has a stub that answers PlanResources with the response registered
+ * under the request's `requestId`, a token unique to one call. A plan the two clients decode
+ * differently fails the case, so every case also proves the adapter is handed the same input
+ * whichever transport the application uses.
+ */
+
+/**
+ * The base URL of the stubbed HTTP PDP. `.invalid` never resolves, so a request that escapes the
+ * stub fails rather than reaching a real server.
+ */
+const STUB_HTTP_PDP = "http://stub-pdp.invalid";
+
+const planResources = CerbosService.method.planResources;
+
+/** The response bodies waiting to be served, by the `requestId` of the call that will read them. */
+const pendingResponses = new Map<string, JsonObject>();
+let requestCount = 0;
+
+function takeResponse(requestId: string): JsonObject {
+  const body = pendingResponses.get(requestId);
+  pendingResponses.delete(requestId);
+
+  if (body === undefined) throw new Error(`stub PDP: no response for request ${requestId}`);
+
+  return body;
+}
+
+function requestUrl(input: Parameters<typeof fetch>[0]): string {
+  if (isString(input)) return input;
+
+  return input instanceof URL ? input.href : input.url;
+}
+
+/**
+ * An `@cerbos/http` client whose PlanResources call is answered here. Only requests to
+ * `STUB_HTTP_PDP` are intercepted; every other `fetch` goes through untouched.
+ */
+function httpClient(): HTTP {
+  const passthrough = globalThis.fetch;
+  globalThis.fetch = async (input, init) => {
+    if (!requestUrl(input).startsWith(STUB_HTTP_PDP)) return passthrough(input, init);
+    const { requestId } = fromJsonString(planResources.input, String(init?.body), { ignoreUnknownFields: true });
+
+    return new Response(toProtoJson(takeResponse(requestId)), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  return new HTTP(STUB_HTTP_PDP);
+}
+
+/**
+ * An `@cerbos/grpc` client connected to an in-process gRPC server on a loopback port, which
+ * answers PlanResources with the registered response encoded as the protobuf a PDP sends.
+ */
+async function grpcClient(): Promise<{ client: GRPC; server: Server }> {
+  const server = new Server();
+  server.addService(
+    {
+      planResources: {
+        path: `/${CerbosService.typeName}/${planResources.name}`,
+        requestStream: false,
+        responseStream: false,
+        requestSerialize: (message: PlanResourcesRequest) =>
+          Buffer.from(toBinary(planResources.input, message)),
+        requestDeserialize: (bytes: Buffer) => fromBinary(planResources.input, bytes),
+        responseSerialize: (message: PlanResourcesResponseMessage) =>
+          Buffer.from(toBinary(planResources.output, message)),
+        responseDeserialize: (bytes: Buffer) => fromBinary(planResources.output, bytes),
+      },
+    },
+    {
+      planResources: (
+        call: ServerUnaryCall<PlanResourcesRequest, PlanResourcesResponseMessage>,
+        respond: sendUnaryData<PlanResourcesResponseMessage>
+      ) => {
+        try {
+          respond(null, fromJson(planResources.output, takeResponse(call.request.requestId)));
+        } catch (error) {
+          respond(error instanceof Error ? error : new Error(String(error)), null);
+        }
+      },
+    }
+  );
+
+  const port = await new Promise<number>((resolve, reject) =>
+    server.bindAsync("127.0.0.1:0", ServerCredentials.createInsecure(), (error, bound) =>
+      error ? reject(error) : resolve(bound)
+    )
+  );
+
+  // The stub is on loopback; never route it through an ambient proxy.
+  const client = new GRPC(`127.0.0.1:${port}`, {
+    tls: false,
+    channelOptions: { "grpc.enable_http_proxy": 0 },
+  });
+
+  return { client, server };
+}
+
+let stubClients: Promise<{ http: HTTP; grpc: GRPC; server: Server }> | undefined;
+
+function sdkClients(): Promise<{ http: HTTP; grpc: GRPC; server: Server }> {
+  stubClients ??= grpcClient().then(({ client, server }) => ({
+    http: httpClient(),
+    grpc: client,
+    server,
+  }));
+
+  return stubClients;
+}
+
+afterAll(async () => {
+  if (!stubClients) return;
+  const { grpc, server } = await stubClients;
+  grpc.close();
+  server.forceShutdown();
+});
+
+/**
+ * JSON as the PDP writes it. `JSON.stringify` writes -0 as `0`, where protojson keeps the sign, so
+ * a stub serialising with it would hand the SDK a different number from the one the PDP sends.
+ */
+function toProtoJson(node: JsonValue): string {
+  if (Object.is(node, -0)) return "-0";
+
+  if (Array.isArray(node)) return `[${node.map(toProtoJson).join(",")}]`;
+
+  if (isObject(node)) {
+    const members = Object.entries(node).map(
+      ([key, child]) => `${JSON.stringify(key)}:${toProtoJson(child)}`
+    );
+
+    return `{${members.join(",")}}`;
+  }
+
+  return JSON.stringify(node);
+}
+
+function substituteNow(node: JsonValue, now: string): JsonValue {
+  if (node === "__NOW_MINUS_24H__") return now;
+
+  if (Array.isArray(node)) return node.map((child) => substituteNow(child, now));
+
+  if (isObject(node)) {
+    return Object.fromEntries(
+      Object.entries(node).map(([key, child]) => [key, substituteNow(child, now)])
+    );
+  }
+
+  return node;
+}
+
+/** One PlanResources call through `client`, answered with `response`. */
+function fetchPlan(
+  client: HTTP | GRPC,
+  golden: Golden,
+  response: JsonObject
+): Promise<PlanResourcesResponse> {
+  const requestId = `${golden.id}#${++requestCount}`;
+  pendingResponses.set(requestId, response);
+
+  return client.planResources({
+    requestId,
+    principal: { id: "stub", roles: ["USER"] },
+    resource: { kind: "conformance" },
+    action: golden.id,
+  });
+}
+
+/**
+ * A golden's plan as the SDK returns it: the recorded `filter` is served as the response to a
+ * stubbed PlanResources call over each transport, so the SDK's own decoding produces what the
+ * adapter receives.
+ */
+export async function planOf(
+  golden: Golden,
+  now: string = nowMinus24h()
+): Promise<PlanResourcesResponse> {
+  const response: JsonObject = {
+    requestId: golden.id,
+    action: golden.id,
+    resourceKind: "conformance",
+    policyVersion: "default",
+    filter: substituteNow(golden.plan, now),
+  };
+
+  const { http, grpc } = await sdkClients();
+
+  const [overHttp, overGrpc] = await Promise.all([
+    fetchPlan(http, golden, response),
+    fetchPlan(grpc, golden, response),
+  ]);
+
+  if (!isDeepStrictEqual(overHttp, overGrpc)) {
+    throw new Error(`${golden.id}: @cerbos/http and @cerbos/grpc decode the plan differently`);
+  }
+
+  return overGrpc;
+}
+
+// -- the mapper ----------------------------------------------------------------------------------
+
+interface ConformanceMapper {
+  [reference: string]: MapperConfig;
+}
+
+export const MAPPER: ConformanceMapper = {
+  // The primary key, reached as `request.resource.id` rather than through `attr` (the
+  // `identifier/*` cases). It is a mapping like any other here, which is the point: an adapter that resolves
+  // references by stripping a `request.resource.attr.` prefix never sees this name.
+  "request.resource.id": { field: "id", valueType: "string" },
+  // Every attribute resources.json OMITS when its column is NULL follows the omitted convention:
+  // aBool, aString and aNumber (NULL on j3, j1, j2), aOptionalString, aDouble, scope, createdAt,
+  // updatedAt, obj.inner and every `parent` field. A null literal against one is then a
+  // missing-attribute error the PDP denies, never an IS NULL match (#528).
+  "request.resource.attr.aBool": {
+    field: "aBool",
+    valueType: "boolean",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.aString": {
+    field: "aString",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.aNumber": {
+    field: "aNumber",
+    valueType: "number",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.aDouble": {
+    field: "aDouble",
+    valueType: "number",
+    nullAttributeRepresentation: "omitted",
+  },
+  // resources.json OMITS aOptionalString when the column is NULL, so `== null` against it is a
+  // missing-attribute error the PDP denies, never an IS NULL match.
+  "request.resource.attr.aOptionalString": {
+    field: "aOptionalString",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.createdBy": { field: "createdBy", valueType: "string" },
+  "request.resource.attr.scope": {
+    field: "scope",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.createdAt": {
+    field: "createdAt",
+    valueType: "dateTime",
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.updatedAt": {
+    field: "updatedAt",
+    valueType: "dateTime",
+    nullAttributeRepresentation: "omitted",
+  },
+  // `owner` and `coOwner` alias columns that `aOptionalString` and `scope` also map, under the
+  // OTHER null convention: the oracle sends a real null attribute for them rather than omitting
+  // it. Declaring that here is what makes the equality family definite for these two attributes
+  // and leaves it untouched for every other mapping (cerbos/query-plan-adapters#308).
+  "request.resource.attr.owner": {
+    field: "aOptionalString",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "explicit",
+  },
+  "request.resource.attr.coOwner": {
+    field: "scope",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "explicit",
+  },
+  // obj.inner is not a real nested column — mirrors aString, same trick the spring-data reference
+  // harness uses for the comparison/equals/nested-map-member case. `parent.inner` below is the
+  // opposite: a real two-level join. The two are kept side by side on purpose.
+  "request.resource.attr.obj.inner": {
+    field: "aString",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  // The corpus's one REAL to-one chain (the `relation/*` cases). `type: "one"` is what makes the
+  // adapter emit `is:` rather than `some:`, and `is:` on an optional relation is what requires
+  // the hop to exist — the absent-parent guard the negated shapes discriminate. `inner` nests
+  // the same declaration one level further out; two levels is where alias scoping breaks.
+  // A column reached through a relation takes the relation entry's null convention, so the one
+  // declaration here covers every `parent.*` and `parent.inner.*` field.
+  "request.resource.attr.parent": {
+    nullAttributeRepresentation: "omitted",
+    relation: {
+      name: "parent",
+      type: "one",
+      model: "AdversarialParent",
+      fields: {
+        aBool: { field: "aBool", valueType: "boolean", nullable: true },
+        aString: { field: "aString", valueType: "string", nullable: true },
+        aNumber: { field: "aNumber", valueType: "number", nullable: true },
+        aOptionalString: { field: "aOptionalString", valueType: "string", nullable: true  },
+        inner: {
+          relation: {
+            name: "inner",
+            type: "one",
+            model: "AdversarialInner",
+            fields: {
+              aBool: { field: "aBool", valueType: "boolean", nullable: true },
+              aString: { field: "aString", valueType: "string", nullable: true },
+              aNumber: { field: "aNumber", valueType: "number", nullable: true },
+              aOptionalString: { field: "aOptionalString", valueType: "string", nullable: true  },
+            },
+          },
+        },
+      },
+    },
+  },
+  "request.resource.attr.tags": {
+    relation: {
+      name: "tags",
+      type: "many",
+      // Model name enables field-to-field comparisons between tag columns. `name` is NULLable
+      // in the schema, so it keeps the adapter's three-valued-logic guards for collection
+      // macros over elements whose name column is NULL (a missing attribute — a CEL error,
+      // hence deny — on the check side). Those guards are the default; every REQUIRED element
+      // column below says `nullable: false`, because Prisma rejects `{ name: null }` on one.
+      model: "AdversarialTag",
+      fields: {
+        id: { field: "tagId", nullable: false },
+        name: { field: "name", valueType: "string", nullable: true  },
+      },
+    },
+  },
+  "request.resource.attr.tagNames": {
+    relation: {
+      name: "tags",
+      type: "many",
+      field: "name",
+      fields: { name: { field: "name", valueType: "string", nullable: true  } },
+    },
+  },
+  // The two homogeneous scalar lists, one owned row per element, projected the way `tagNames`
+  // is. `valueType` sits on the list mapping itself because that is where a membership test reads
+  // it: a literal of another type (`"2" in aNumberList`) is refused rather than bound, since CEL's
+  // heterogeneous equality answers it false and a store that coerces would not. The element column
+  // is nullable because a6 and a4 hold a null element, which is a VALUE in CEL.
+  "request.resource.attr.aNumberList": {
+    valueType: "number",
+    relation: {
+      name: "numberList",
+      type: "many",
+      field: "value",
+      fields: { value: { field: "value", valueType: "number", nullable: true } },
+    },
+  },
+  "request.resource.attr.aBoolList": {
+    valueType: "boolean",
+    relation: {
+      name: "boolList",
+      type: "many",
+      field: "value",
+      fields: { value: { field: "value", valueType: "boolean", nullable: true } },
+    },
+  },
+  "request.resource.attr.categories": {
+    relation: {
+      name: "categories",
+      type: "many",
+      fields: {
+        name: { field: "name", valueType: "string", nullable: false },
+        subCategories: {
+          relation: {
+            name: "subCategories",
+            type: "many",
+            fields: {
+              name: { field: "name", valueType: "string", nullable: false },
+              labels: {
+                relation: {
+                  name: "labels",
+                  type: "many",
+                  fields: {
+                    name: { field: "name", valueType: "string", nullable: true  },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+  // The multi-hop chain (the `relation/*/*-to-one-chain` cases): mainCategory mirrors the SAME
+  // categories/subCategories relation as a single-object dotted chain on the check side (every
+  // seed holds at most one category), pinning that the adapter joins through every intermediate
+  // hop, never off the root.
+  "request.resource.attr.mainCategory": {
+    relation: {
+      name: "categories",
+      type: "many",
+      fields: {
+        name: { field: "name", valueType: "string", nullable: false },
+        subCategories: {
+          relation: {
+            name: "subCategories",
+            type: "many",
+            fields: { name: { field: "name", valueType: "string", nullable: false } },
+          },
+        },
+        // subNames: the same 2-hop chain but with a bare `field`, so plain `in` membership
+        // compares the flattened tail's name column directly.
+        subNames: {
+          relation: {
+            name: "subCategories",
+            type: "many",
+            field: "name",
+          },
+        },
+      },
+    },
+  },
+};

package/src/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * The error `queryPlanToPrisma` raises when a plan holds a shape this adapter cannot translate
+ * without returning rows the PDP would deny: a CEL operator with no faithful Prisma filter, a
+ * literal it cannot bind exactly, a construct CEL itself rejects, or a plan that is malformed.
+ *
+ * It extends `Error`, so existing `catch` blocks keep working. Mapper misconfiguration — a
+ * missing `model` option or `relation.model`, an empty field path — is not a refusal and stays a
+ * plain `Error`: that is a bug in the caller's mapping, not a limitation of the adapter.
+ */
+export class UnsupportedQueryPlanError extends Error {
+  override readonly name = "UnsupportedQueryPlanError";
+}