@stigmer/server 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/authorization/store-test-kit.ts

@@ -0,0 +1,454 @@
+/**
+ * The OpenFGA store-test kit — runs a `.fga.yaml` store test (the format
+ * `fga model test` reads: fixture tuples, then named tests with `check`
+ * and `list_objects` assertions) against the built-in evaluator, so the
+ * cloud's own model tests — written by the model's authors and run
+ * against real OpenFGA in the cloud's CI — are the proof that this
+ * evaluator answers the same model the same way. Open source runs the
+ * kit over pinned copies of those documents (authorization/__tests__/
+ * fixtures/fga/); the cloud runs it over the LIVE documents at the
+ * re-pin, which is what makes the copies safe to hold.
+ *
+ * Shape: the port-contract kits' (store/port-contract.ts) — vitest-free,
+ * node:assert, cases the consumer's framework iterates — because a
+ * composition consumes it through the published barrel and vitest is a
+ * devDependency that must not enter the barrel's runtime graph.
+ *
+ * What is run and what is reported. One case per named test; a case
+ * asserts every `check` in the test whose object's kind the model
+ * declares, relation by relation, and FAILS on the first disagreement
+ * (the message names the check in the document's own words). Assertions
+ * the kit does not run are returned as `skipped`, each with its reason,
+ * so a consumer pins the list and a document that gains a scenario, or a
+ * declaration that lands, is a visible diff and never a quietly smaller
+ * proof. Three reasons: a check whose TARGET kind the model does not
+ * declare (`undeclared-kind`) and every `list_objects` assertion
+ * (`list-objects`, the list scope's proof) are known when the kit is
+ * built; the third is known only from the walk. A document may grant
+ * through a type the model does not declare — the cloud's platform
+ * tenancy reaches people through `identity_provider:<idp>#platform_user`,
+ * a kind this edition does not serve — and OpenFGA answers `true` where
+ * a model without that type resolves the userset to nobody. The kit runs
+ * every assertion over a recording view of the document's tuples, and an
+ * assertion whose walk READ a tuple naming an undeclared type is
+ * reported as `undeclared-subject-type` (the types named) instead of
+ * being asserted, whatever it would have answered: decided from the
+ * model and the data, per assertion, so the sibling arms of the same
+ * check block still run and a union that is settled before it reaches
+ * such a tuple runs too. Over a model that declares every type in the
+ * file (the cloud's drift test, built from the live model) nothing is
+ * recorded and everything runs — the same kit, no edition branch.
+ * `skipped` is therefore complete once every case has run; a consumer
+ * pins it after the cases, which is the order a test file declares them.
+ *
+ * Context. A check's `context.allow` is the `allow_public` parameter
+ * (tuples.ts). A check without a context runs with `allow: false`, the
+ * listing posture: OpenFGA itself would fault on a conditional tuple it
+ * reached with the parameter missing, so the cloud's documents never do
+ * that — their CI would already fail — and the choice cannot change an
+ * answer the oracle gives. The parser is strict on purpose: an unknown
+ * key anywhere is a thrown fault, so a change to the format upstream is
+ * loud here rather than half-run.
+ */
+import assert from "node:assert/strict";
+
+import { checkRelation } from "./evaluator.js";
+import type { Model } from "./model/index.js";
+import type {
+  CheckContext,
+  Person,
+  Subject,
+  Tuple,
+  TupleSource,
+} from "./tuples.js";
+import {
+  ACCOUNT_TYPE,
+  newInMemoryTupleSource,
+  parseObjectRef,
+  parseSubject,
+} from "./tuples.js";
+
+// ---------------------------------------------------------------------------
+// The document, typed exactly as the cloud's files use the format.
+// ---------------------------------------------------------------------------
+
+export interface StoreTestTuple {
+  readonly user: string;
+  readonly relation: string;
+  readonly object: string;
+  readonly condition?: { readonly name: string };
+}
+
+export interface StoreTestCheck {
+  readonly user: string;
+  readonly object: string;
+  readonly context?: CheckContext;
+  readonly assertions: Readonly<Record<string, boolean>>;
+}
+
+export interface StoreTestListObjects {
+  readonly user: string;
+  readonly type: string;
+  readonly context?: CheckContext;
+  readonly assertions: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+
+export interface StoreTest {
+  readonly name: string;
+  readonly check: ReadonlyArray<StoreTestCheck>;
+  readonly list_objects: ReadonlyArray<StoreTestListObjects>;
+}
+
+export interface StoreTestDocument {
+  readonly name: string;
+  readonly tuples: ReadonlyArray<StoreTestTuple>;
+  readonly tests: ReadonlyArray<StoreTest>;
+}
+
+/**
+ * Parses a loaded YAML value into a document, refusing anything the
+ * format the cloud's files use does not carry (`sourceName` names the
+ * file in every message).
+ */
+export function parseStoreTestDocument(
+  value: unknown,
+  sourceName: string,
+): StoreTestDocument {
+  const root = record(value, sourceName, [
+    "name",
+    "model_file",
+    "tuples",
+    "tests",
+  ]);
+  return {
+    name: text(root["name"], `${sourceName}: name`),
+    tuples: list(root["tuples"], `${sourceName}: tuples`).map((entry, index) =>
+      parseTuple(entry, `${sourceName}: tuples[${index}]`),
+    ),
+    tests: list(root["tests"], `${sourceName}: tests`).map((entry, index) =>
+      parseTest(entry, `${sourceName}: tests[${index}]`),
+    ),
+  };
+}
+
+function parseTuple(value: unknown, where: string): StoreTestTuple {
+  const entry = record(value, where, [
+    "user",
+    "relation",
+    "object",
+    "condition",
+  ]);
+  const tuple: StoreTestTuple = {
+    user: text(entry["user"], `${where}.user`),
+    relation: text(entry["relation"], `${where}.relation`),
+    object: text(entry["object"], `${where}.object`),
+  };
+  if (entry["condition"] === undefined) {
+    return tuple;
+  }
+  const condition = record(entry["condition"], `${where}.condition`, [
+    "name",
+    "context",
+  ]);
+  return {
+    ...tuple,
+    condition: { name: text(condition["name"], `${where}.condition.name`) },
+  };
+}
+
+function parseTest(value: unknown, where: string): StoreTest {
+  const entry = record(value, where, ["name", "check", "list_objects"]);
+  return {
+    name: text(entry["name"], `${where}.name`),
+    check: optionalList(entry["check"], `${where}.check`).map((item, index) =>
+      parseCheck(item, `${where}.check[${index}]`),
+    ),
+    list_objects: optionalList(
+      entry["list_objects"],
+      `${where}.list_objects`,
+    ).map((item, index) =>
+      parseListObjects(item, `${where}.list_objects[${index}]`),
+    ),
+  };
+}
+
+function parseCheck(value: unknown, where: string): StoreTestCheck {
+  const entry = record(value, where, [
+    "user",
+    "object",
+    "context",
+    "assertions",
+  ]);
+  const assertions = record(entry["assertions"], `${where}.assertions`);
+  const parsed: Record<string, boolean> = {};
+  for (const [relation, expected] of Object.entries(assertions)) {
+    if (typeof expected !== "boolean") {
+      throw new Error(`${where}.assertions.${relation}: expected a boolean`);
+    }
+    parsed[relation] = expected;
+  }
+  const context = parseContext(entry["context"], `${where}.context`);
+  return {
+    user: text(entry["user"], `${where}.user`),
+    object: text(entry["object"], `${where}.object`),
+    ...(context === undefined ? {} : { context }),
+    assertions: parsed,
+  };
+}
+
+function parseListObjects(value: unknown, where: string): StoreTestListObjects {
+  const entry = record(value, where, ["user", "type", "context", "assertions"]);
+  const assertions = record(entry["assertions"], `${where}.assertions`);
+  const parsed: Record<string, ReadonlyArray<string>> = {};
+  for (const [relation, expected] of Object.entries(assertions)) {
+    parsed[relation] = list(expected, `${where}.assertions.${relation}`).map(
+      (item, index) => text(item, `${where}.assertions.${relation}[${index}]`),
+    );
+  }
+  const context = parseContext(entry["context"], `${where}.context`);
+  return {
+    user: text(entry["user"], `${where}.user`),
+    type: text(entry["type"], `${where}.type`),
+    ...(context === undefined ? {} : { context }),
+    assertions: parsed,
+  };
+}
+
+function parseContext(value: unknown, where: string): CheckContext | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const entry = record(value, where, ["allow"]);
+  if (typeof entry["allow"] !== "boolean") {
+    throw new Error(`${where}.allow: expected a boolean`);
+  }
+  return { allow: entry["allow"] };
+}
+
+function record(
+  value: unknown,
+  where: string,
+  allowedKeys?: ReadonlyArray<string>,
+): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${where}: expected a mapping`);
+  }
+  const entry = value as Record<string, unknown>;
+  if (allowedKeys !== undefined) {
+    for (const key of Object.keys(entry)) {
+      if (!allowedKeys.includes(key)) {
+        throw new Error(`${where}: unknown key '${key}'`);
+      }
+    }
+  }
+  return entry;
+}
+
+function list(value: unknown, where: string): ReadonlyArray<unknown> {
+  if (!Array.isArray(value)) {
+    throw new Error(`${where}: expected a list`);
+  }
+  return value as ReadonlyArray<unknown>;
+}
+
+function optionalList(value: unknown, where: string): ReadonlyArray<unknown> {
+  return value === undefined ? [] : list(value, where);
+}
+
+function text(value: unknown, where: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`${where}: expected a string`);
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// The cases.
+// ---------------------------------------------------------------------------
+
+export interface StoreTestCase {
+  /** `<document> :: <test name>` — the framework prints it as the test name. */
+  readonly name: string;
+  run(): Promise<void>;
+}
+
+export type StoreTestSkipReason =
+  | "undeclared-kind"
+  | "list-objects"
+  | "undeclared-subject-type";
+
+/** One assertion (or assertion group) the kit did not run, in the document's words. */
+export interface StoreTestSkip {
+  readonly document: string;
+  readonly test: string;
+  readonly subject: string;
+  /** The check's object, or `<type>` for a list_objects assertion. */
+  readonly object: string;
+  /** The one relation, for a skip decided per assertion; absent for a group. */
+  readonly relation?: string;
+  readonly reason: StoreTestSkipReason;
+  /** For `undeclared-subject-type`: the types the walk read that the model does not declare, sorted. */
+  readonly types?: ReadonlyArray<string>;
+}
+
+export interface StoreTestKit {
+  readonly cases: ReadonlyArray<StoreTestCase>;
+  /** Complete once every case has run (the module header). */
+  readonly skipped: ReadonlyArray<StoreTestSkip>;
+}
+
+/** The listing posture, for a check the document leaves without a context (the module header). */
+const CONTEXT_WHEN_ABSENT: CheckContext = { allow: false };
+
+/**
+ * The document's tests as runnable cases over `model`, plus every
+ * assertion group the kit does not run.
+ */
+export function storeTestCases(
+  document: StoreTestDocument,
+  model: Model,
+): StoreTestKit {
+  const source = newInMemoryTupleSource(document.tuples.map(tupleOf));
+  const skipped: StoreTestSkip[] = [];
+  const cases: StoreTestCase[] = [];
+
+  for (const test of document.tests) {
+    const runnable: StoreTestCheck[] = [];
+    for (const item of test.check) {
+      const object = parseObjectRef(item.object);
+      if (model.byType(object.type) === undefined) {
+        skipped.push({
+          document: document.name,
+          test: test.name,
+          subject: item.user,
+          object: item.object,
+          reason: "undeclared-kind",
+        });
+      } else {
+        runnable.push(item);
+      }
+    }
+    for (const item of test.list_objects) {
+      skipped.push({
+        document: document.name,
+        test: test.name,
+        subject: item.user,
+        object: `<${item.type}>`,
+        reason: "list-objects",
+      });
+    }
+    if (runnable.length === 0) {
+      continue;
+    }
+    cases.push({
+      name: `${document.name} :: ${test.name}`,
+      async run() {
+        for (const item of runnable) {
+          const object = parseObjectRef(item.object);
+          const person = personOf(item.user);
+          const context = item.context ?? CONTEXT_WHEN_ABSENT;
+          for (const [relation, expected] of Object.entries(item.assertions)) {
+            const recording = recordUndeclaredTypes(source, model);
+            const actual = await checkRelation(
+              { model, source: recording },
+              object,
+              relation,
+              person,
+              context,
+            );
+            if (recording.reached.size > 0) {
+              skipped.push({
+                document: document.name,
+                test: test.name,
+                subject: item.user,
+                object: item.object,
+                relation,
+                reason: "undeclared-subject-type",
+                types: [...recording.reached].sort(),
+              });
+              continue;
+            }
+            assert.equal(
+              actual,
+              expected,
+              `${document.name} :: ${test.name}: ${item.user} ${relation} ${item.object} (allow: ${String(context.allow)}) expected ${String(expected)}, got ${String(actual)}`,
+            );
+          }
+        }
+      },
+    });
+  }
+  return { cases, skipped };
+}
+
+interface RecordingTupleSource extends TupleSource {
+  /** The undeclared types named by the subjects of the tuples the walk read. */
+  readonly reached: ReadonlySet<string>;
+}
+
+/**
+ * A view of `inner` that records, for one walk, every subject type the
+ * evaluator read that `model` does not declare. A person
+ * (`identity_account:<id>`, the wildcard) is a subject the evaluator
+ * compares, never a type it resolves, so it is not a "reach" whatever
+ * the model declares; a userset or a parent object of an undeclared
+ * type is.
+ */
+function recordUndeclaredTypes(
+  inner: TupleSource,
+  model: Model,
+): RecordingTupleSource {
+  const reached = new Set<string>();
+  return {
+    reached,
+    async tuplesOf(object, relation) {
+      const tuples = await inner.tuplesOf(object, relation);
+      for (const tuple of tuples) {
+        const type = resolvedTypeOf(tuple.subject);
+        if (type !== undefined && model.byType(type) === undefined) {
+          reached.add(type);
+        }
+      }
+      return tuples;
+    },
+  };
+}
+
+/** The type the evaluator would resolve a subject on, or undefined for a person. */
+function resolvedTypeOf(subject: Subject): string | undefined {
+  switch (subject.form) {
+    case "object":
+      return subject.object.type === ACCOUNT_TYPE
+        ? undefined
+        : subject.object.type;
+    case "userset":
+      return subject.object.type;
+    case "wildcard":
+      return undefined;
+    default: {
+      const exhaustive: never = subject;
+      throw new Error(`unknown subject form: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+
+function tupleOf(entry: StoreTestTuple): Tuple {
+  const subject = parseSubject(entry.user);
+  return {
+    object: parseObjectRef(entry.object),
+    relation: entry.relation,
+    subject:
+      subject.form === "wildcard" && entry.condition !== undefined
+        ? { ...subject, condition: entry.condition.name }
+        : subject,
+  };
+}
+
+/** The document's users are plain accounts; a user of another type is a format the kit does not run. */
+function personOf(user: string): Person {
+  const object = parseObjectRef(user);
+  if (object.type !== ACCOUNT_TYPE || object.id === "*") {
+    throw new Error(`store test users are accounts; got '${user}'`);
+  }
+  return { accountId: object.id, aliases: new Set([object.id]) };
+}

package/src/authorization/tuples.ts

@@ -0,0 +1,190 @@
+/**
+ * The tuple vocabulary of the built-in authorizer — the OpenFGA notions
+ * the cloud's model is written in (object, relation, subject; a subject
+ * being an object, a userset `type:id#relation`, or the public wildcard
+ * `type:*` under a condition), typed once so the evaluator, the
+ * derivation and the store-test kit speak one language. Nothing here is
+ * stored: open source derives every tuple from a row (derived-tuples.ts)
+ * or reads it from an IamPolicy row, and this module only names what a
+ * tuple IS.
+ *
+ * `Person` is the caller as the evaluator sees them: the account id the
+ * IamPolicy rows name, and every string a creator stamp may carry for the
+ * same human — the account id and the account's issuer subject (rows the
+ * 3.14.x verifiers stamped with the raw `sub`). A tuple naming
+ * `identity_account:<x>` matches the person when `x` is one of the
+ * aliases; rows are read by the account id alone, because every row open
+ * source writes names an account (domain/iampolicy/role-lifecycle.ts).
+ * The type is named here; the construction (`personFor`, `resolvePerson`)
+ * is person.ts's, so this module stays vocabulary with no I/O.
+ *
+ * `CheckContext` is the FGA condition context. The one condition the
+ * model declares is `allow_public(allow: bool)` on the public wildcard,
+ * and the cloud's own posture (stigmer-cloud authorizer/fga-authorizer.ts,
+ * the Java BuildCheckRequest) is `allow: true` on a point check — a public
+ * resource reads for any authenticated caller — and `allow: false` in a
+ * listing, which keeps a public wildcard from flooding an organization's
+ * catalog. The parameter is required so a caller states which posture it
+ * is in; there is no default because either one is wrong for the other.
+ *
+ * The string forms (`agent:x`, `organization:acme#viewer`,
+ * `identity_account:*`) are the notation the cloud's store tests and the
+ * IamPolicy proto both use; parse and format are here so the kit and the
+ * tests never spell them a second way.
+ */
+import type { Message } from "@bufbuild/protobuf";
+
+/** The FGA type name of the kind every person is: `identity_account:<id>`. */
+export const ACCOUNT_TYPE = "identity_account";
+
+/** The one condition the model declares; it guards the public wildcard. */
+export const ALLOW_PUBLIC_CONDITION = "allow_public";
+
+/** `type:id` — an object of the model. */
+export interface ObjectRef {
+  readonly type: string;
+  readonly id: string;
+}
+
+/** The subject (the FGA "user") of a tuple. */
+export type Subject =
+  /** `type:id` — an object, including a person as `identity_account:<id>`. */
+  | { readonly form: "object"; readonly object: ObjectRef }
+  /** `type:id#relation` — everyone who holds `relation` on the object. */
+  | {
+      readonly form: "userset";
+      readonly object: ObjectRef;
+      readonly relation: string;
+    }
+  /** `type:*` — every object of the type, honoured only when its condition holds. */
+  | {
+      readonly form: "wildcard";
+      readonly type: string;
+      readonly condition: string | undefined;
+    };
+
+export interface Tuple {
+  readonly object: ObjectRef;
+  readonly relation: string;
+  readonly subject: Subject;
+}
+
+/**
+ * Where the evaluator reads tuples from: every tuple on `object` with
+ * `relation`. A source MAY return only the tuples that can concern the
+ * person it was built for (the product source reads the person's own
+ * rows; a fixture source knows no person and returns them all) — the
+ * evaluator is correct over either, because a tuple whose subject is
+ * another person is never a match. It MUST NOT omit a userset or an
+ * object subject on the pair, which is how the person may be reached
+ * indirectly. Faults propagate; "absent" is the empty array.
+ */
+export interface TupleSource {
+  tuplesOf(object: ObjectRef, relation: string): Promise<ReadonlyArray<Tuple>>;
+}
+
+/** A declaration's derived-relation rule reads related rows through this (default_of needs the blueprint). */
+export interface RowLoader {
+  /** The decoded row, or undefined when there is none or the kind is not declared. */
+  load(object: ObjectRef): Promise<Message | undefined>;
+}
+
+/** The caller as the model sees them. */
+export interface Person {
+  /** The id the IamPolicy rows name. */
+  readonly accountId: string;
+  /** Every string a creator stamp may carry for this person; always contains `accountId`. */
+  readonly aliases: ReadonlySet<string>;
+}
+
+/** The condition parameters of a check (the module header). */
+export interface CheckContext {
+  readonly allow: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// The string notation.
+// ---------------------------------------------------------------------------
+
+/** `type:id` → ObjectRef; the id may itself contain `:` (issuer subjects do). */
+export function parseObjectRef(text: string): ObjectRef {
+  const colon = text.indexOf(":");
+  if (colon <= 0) {
+    throw new Error(`not an object reference: '${text}'`);
+  }
+  return { type: text.slice(0, colon), id: text.slice(colon + 1) };
+}
+
+export function formatObjectRef(object: ObjectRef): string {
+  return `${object.type}:${object.id}`;
+}
+
+/**
+ * `type:id`, `type:id#relation` or `type:*` → Subject. A wildcard parsed
+ * from text carries no condition; the caller attaches one when its source
+ * says so (the store tests carry it on the tuple, the derivation attaches
+ * the model's).
+ */
+export function parseSubject(text: string): Subject {
+  const hash = text.indexOf("#");
+  if (hash > 0) {
+    return {
+      form: "userset",
+      object: parseObjectRef(text.slice(0, hash)),
+      relation: text.slice(hash + 1),
+    };
+  }
+  const object = parseObjectRef(text);
+  if (object.id === "*") {
+    return { form: "wildcard", type: object.type, condition: undefined };
+  }
+  return { form: "object", object };
+}
+
+export function formatSubject(subject: Subject): string {
+  switch (subject.form) {
+    case "object":
+      return formatObjectRef(subject.object);
+    case "userset":
+      return `${formatObjectRef(subject.object)}#${subject.relation}`;
+    case "wildcard":
+      return subject.condition === undefined
+        ? `${subject.type}:*`
+        : `${subject.type}:* with ${subject.condition}`;
+    default: {
+      const exhaustive: never = subject;
+      throw new Error(`unknown subject form: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+
+/** `object#relation@subject` — the IamPolicy proto's own tuple notation. */
+export function formatTuple(tuple: Tuple): string {
+  return `${formatObjectRef(tuple.object)}#${tuple.relation}@${formatSubject(tuple.subject)}`;
+}
+
+/** The memo and fixture key of an (object, relation) pair. */
+export function pairKey(object: ObjectRef, relation: string): string {
+  return `${formatObjectRef(object)}#${relation}`;
+}
+
+/** A source over a fixed tuple list — the store-test kit's and the unit tests' fixture. */
+export function newInMemoryTupleSource(
+  tuples: ReadonlyArray<Tuple>,
+): TupleSource {
+  const byPair = new Map<string, Tuple[]>();
+  for (const tuple of tuples) {
+    const key = pairKey(tuple.object, tuple.relation);
+    const held = byPair.get(key);
+    if (held === undefined) {
+      byPair.set(key, [tuple]);
+    } else {
+      held.push(tuple);
+    }
+  }
+  return {
+    tuplesOf(object, relation) {
+      return Promise.resolve(byPair.get(pairKey(object, relation)) ?? []);
+    },
+  };
+}