@stigmer/server 3.27.1 → 3.28.0

package/src/authorization/model/default-of.ts

@@ -14,8 +14,8 @@
  * resolves the blueprint's `viewer` on — one read serves both. Which spec
  * field names the blueprint is `kind_meta`'s to say (the instance kind's
  * `additional_parents` entry for the blueprint kind), never restated
- * here; an instance kind without that entry is a transcript bug and
- * throws at first use rather than deriving nothing.
+ * here; an instance kind without that entry is a binding bug
+ * (bindings.ts) and throws at first use rather than deriving nothing.
  *
  * A user-created instance points at a blueprint whose pointer names a
  * different row (or none), so the rule derives nothing for it and its

package/src/authorization/model/execution-viewer.ts

@@ -0,0 +1,56 @@
+/**
+ * The `execution_viewer` derived rule of a workflow instance. The model
+ * (fga/model/agentic/workflow_instance.fga) keeps the instance's RUN
+ * history audience apart from `viewer`, so making an instance
+ * org-runnable never exposes other people's run inputs and outputs;
+ * workflow_execution reads it through `execution_viewer from
+ * workflow_instance`.
+ *
+ * It is derived from `spec.execution_visibility`, which `kind_meta`
+ * cannot express: `organization` derives
+ * `#execution_viewer@organization:<org>#viewer`, the organization's full
+ * read audience (the relation also admits `#member`, the legacy shape),
+ * and `private` or unset derives nothing, so each run stays its
+ * triggerer's. Pure over the row; no related row is read.
+ */
+import { isMessage } from "@bufbuild/protobuf";
+
+import { WorkflowInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { WorkflowExecutionVisibility } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/spec_pb";
+
+import type { DerivedRelation } from "./rewrite.js";
+
+export const executionViewer: DerivedRelation = (object, row) => {
+  if (!isMessage(row, WorkflowInstanceSchema)) {
+    return Promise.resolve([]);
+  }
+  const level =
+    row.spec?.executionVisibility ?? WorkflowExecutionVisibility.unspecified;
+  switch (level) {
+    case WorkflowExecutionVisibility.organization: {
+      const org = row.metadata?.org ?? "";
+      return Promise.resolve(
+        org === ""
+          ? []
+          : [
+              {
+                object,
+                relation: "execution_viewer",
+                subject: {
+                  form: "userset",
+                  object: { type: "organization", id: org },
+                  relation: "viewer",
+                },
+              },
+            ],
+      );
+    }
+    case WorkflowExecutionVisibility.private:
+    case WorkflowExecutionVisibility.unspecified:
+      return Promise.resolve([]);
+    default: {
+      const exhaustive: never = level;
+      throw new Error(`unknown execution visibility: ${String(exhaustive)}`);
+    }
+  }
+};

package/src/authorization/model/index.ts

@@ -1,52 +1,37 @@
 /**
- * The built-in model — every kind declaration open source evaluates,
- * registered once in the order the cloud's `fga.mod` files them, and
- * reached by kind (the driver's `AuthzCheck.resourceKind`) or by FGA type
- * name (an object reference inside a tuple). A kind with no declaration
- * is one this edition does not evaluate: as a check TARGET that is a
- * registry gap the evaluator throws on (the driver refuses unserved kinds
- * before any evaluation, so the throw is a backstop); reached through a
- * tuple it is simply an object with no relations.
+ * The built-in model: every type of the authorization model, reached by
+ * kind (the driver's `AuthzCheck.resourceKind`) or by FGA type name (an
+ * object reference inside a tuple), in `fga.mod` order.
  *
- * `newModel` exists for tests that need a throwaway model (a cycle, a
- * chain past the depth bound) and for the cloud's drift test, which
- * builds a model from the live `.fga` files and compares.
+ * It is built at module load from the one set of bytes every edition
+ * reads: data/authorization-model.json, OpenFGA's JSON compiled from the
+ * `.fga` files under fga/model (`make gen-authorization-model`), which the
+ * engine suites under fga/tests also run against. The reader
+ * (openfga-json.ts) turns it into the evaluator's vocabulary, and the
+ * binding table (bindings.ts) adds what JSON cannot carry: each kind's row
+ * schema and its derived rules. A model this server cannot evaluate, or a
+ * type and a binding that disagree, fails the load, so it fails the boot
+ * and every test that imports the model, never an answer.
+ *
+ * The model declares every type, whichever edition serves it. Which kinds
+ * an edition evaluates is the tier's question, answered before any
+ * evaluation (authorizer.ts, `kindServedByEdition`): open source refuses a
+ * check that targets `team`, `identity_provider`, `invitation` or
+ * `platform`, and a tuple that names one resolves over tuples alone, since
+ * this edition stores no row of those kinds.
  *
- * Registered: every kind of the open-source tier — the twenty-four
- * `kind_meta.tier: open_source` members — and nothing else. The three
- * files `fga.mod` lists that have no declaration here (`platform`,
- * `identity_provider`, `invitation`) are kinds this edition does not
- * serve: a check that targets one is refused by the
- * driver, and a tuple that names one (`identity_provider#platform_user`)
- * resolves to nobody. The registry test pins the list against the tier.
+ * `newModel` exists for tests that need a throwaway model (a cycle, a
+ * chain past the depth bound).
  */
-import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
-import { agentDeclaration } from "./agent.js";
-import { agentChannelDeclaration } from "./agent_channel.js";
-import { agentExecutionDeclaration } from "./agent_execution.js";
-import { agentInstanceDeclaration } from "./agent_instance.js";
-import { agentShareDeclaration } from "./agent_share.js";
-import { apiKeyDeclaration } from "./api_key.js";
-import { artifactDeclaration } from "./artifact.js";
-import { channelAppDeclaration } from "./channel_app.js";
-import { environmentDeclaration } from "./environment.js";
-import { executionContextDeclaration } from "./execution_context.js";
-import { iamPolicyDeclaration } from "./iam_policy.js";
-import { identityAccountDeclaration } from "./identity_account.js";
-import { mcpServerDeclaration } from "./mcp_server.js";
-import { memoryDeclaration } from "./memory.js";
-import { oauthAppDeclaration } from "./oauth_app.js";
-import { organizationDeclaration } from "./organization.js";
-import { platformClientDeclaration } from "./platform_client.js";
-import { pluginDeclaration } from "./plugin.js";
-import type { KindDeclaration } from "./rewrite.js";
-import { scheduleDeclaration } from "./schedule.js";
-import { sessionDeclaration } from "./session.js";
-import { skillDeclaration } from "./skill.js";
-import { workflowDeclaration } from "./workflow.js";
-import { workflowExecutionDeclaration } from "./workflow_execution.js";
-import { workflowInstanceDeclaration } from "./workflow_instance.js";
+import { kindByEnumName } from "../../pipeline/apiresource-meta.js";
+import type { KindBinding } from "./bindings.js";
+import { KIND_BINDINGS } from "./bindings.js";
+import compiledModel from "./data/authorization-model.json" with { type: "json" };
+import type { ModelType } from "./openfga-json.js";
+import { readOpenFgaModel } from "./openfga-json.js";
+import type { DerivedRelation, KindDeclaration } from "./rewrite.js";
 
 export interface Model {
   /** In registry order. */
@@ -72,35 +57,59 @@ export function newModel(declarations: ReadonlyArray<KindDeclaration>): Model {
   };
 }
 
-/** The declarations this edition evaluates, in `fga.mod` order. */
-export const builtInModel: Model = newModel([
-  identityAccountDeclaration,
-  iamPolicyDeclaration,
-  apiKeyDeclaration,
-  oauthAppDeclaration,
-  platformClientDeclaration,
-  organizationDeclaration,
-  agentDeclaration,
-  agentChannelDeclaration,
-  agentShareDeclaration,
-  channelAppDeclaration,
-  agentInstanceDeclaration,
-  agentExecutionDeclaration,
-  artifactDeclaration,
-  environmentDeclaration,
-  executionContextDeclaration,
-  mcpServerDeclaration,
-  memoryDeclaration,
-  scheduleDeclaration,
-  sessionDeclaration,
-  skillDeclaration,
-  workflowDeclaration,
-  workflowInstanceDeclaration,
-  workflowExecutionDeclaration,
-  pluginDeclaration,
-]);
+/**
+ * Joins the compiled model's types with their bindings, in the model's
+ * order. Refuses a type that names no `ApiResourceKind`, a type with no
+ * binding, a binding with no type, and a derived rule for a relation the
+ * type does not define.
+ */
+export function bindModel(
+  types: ReadonlyArray<ModelType>,
+  bindings: ReadonlyMap<ApiResourceKind, KindBinding>,
+): ReadonlyArray<KindDeclaration> {
+  const bound = new Set<ApiResourceKind>();
+  const declarations = types.map((entry): KindDeclaration => {
+    const kind = kindByEnumName(entry.type);
+    if (kind === ApiResourceKind.api_resource_kind_unknown) {
+      throw new Error(`${entry.source}: type '${entry.type}' names no ApiResourceKind`);
+    }
+    const binding = bindings.get(kind);
+    if (binding === undefined) {
+      throw new Error(`${entry.source}: type '${entry.type}' has no binding (model/bindings.ts)`);
+    }
+    bound.add(kind);
+    const derived = new Map<string, DerivedRelation>();
+    for (const [relation, rule] of Object.entries(binding.derived ?? {})) {
+      if (!entry.relations.has(relation)) {
+        throw new Error(
+          `model/bindings.ts: a derived rule for '${entry.type}#${relation}', which ${entry.source} does not define`,
+        );
+      }
+      derived.set(relation, rule);
+    }
+    return {
+      kind,
+      type: entry.type,
+      schema: binding.schema,
+      source: entry.source,
+      relations: entry.relations,
+      derived,
+    };
+  });
+  for (const kind of bindings.keys()) {
+    if (!bound.has(kind)) {
+      throw new Error(`model/bindings.ts: a binding for '${ApiResourceKind[kind]}', which the model does not define`);
+    }
+  }
+  return declarations;
+}
+
+/** Every type of the authorization model, in `fga.mod` order. */
+export const builtInModel: Model = newModel(
+  bindModel(readOpenFgaModel(compiledModel as unknown), KIND_BINDINGS),
+);
 
-/** The built-in model's declaration for a kind, or undefined for a kind it does not evaluate. */
+/** The built-in model's declaration for a kind, or undefined for a kind the model does not define. */
 export function declarationFor(
   kind: ApiResourceKind,
 ): KindDeclaration | undefined {

package/src/authorization/model/openfga-json.ts

@@ -0,0 +1,310 @@
+/**
+ * The reader of the compiled authorization model: OpenFGA's own JSON
+ * (data/authorization-model.json, written by `make gen-authorization-model`
+ * from the `.fga` files under fga/model) turned into the evaluator's
+ * vocabulary (rewrite.ts), one entry per type in the file's order.
+ *
+ * The file is OpenFGA's format, not this server's, so it is read as
+ * `unknown` and refused loudly (strict-json.ts): every key the compiled
+ * model carries is listed below, and any other key, at any depth, is a
+ * thrown fault naming where. It runs when model/index.ts loads, so a model
+ * this server cannot evaluate fails the boot and every test that imports
+ * the model, never an answer.
+ *
+ * What is accepted, which is what the compiled model uses:
+ *   - `schema_version` "1.2" and `type_definitions`;
+ *   - per type: `type`, `relations`, and `metadata.{module, relations,
+ *     source_info.file}`;
+ *   - per relation's metadata: `directly_related_user_types[]`, each an
+ *     object type (`{type}`) or a userset (`{type, relation}`);
+ *   - per rewrite node: `this`, `computedUserset.relation`,
+ *     `tupleToUserset.{tupleset,computedUserset}.relation`, `union.child`
+ *     and `intersection.child`, nested to any depth (the evaluator
+ *     recurses through any nesting).
+ *
+ * What is refused by name, because the evaluator does not implement it
+ * and the day the model needs it is a design act: `difference` (`but
+ * not`), conditions (a `conditions` map, or a type reference carrying
+ * `condition`), wildcards (`type:*`), a `computedUserset` that names
+ * another object, and any schema version but 1.2.
+ *
+ * What is re-asserted, though OpenFGA's validator proved it when the file
+ * was compiled, because the file is committed data and a hand edit must
+ * fail here rather than in an answer: every computed target and tupleset
+ * is a relation of its own type; every subject type names a declared type,
+ * and a userset subject a relation that type declares; and a relation
+ * lists direct subject types exactly when its rewrite has a `this` node,
+ * which is where the evaluator reads that list from.
+ *
+ * Relations come out sorted by name (the canonical file sorts keys; the
+ * evaluator only looks relations up). A union's or an intersection's
+ * children keep the file's order: the evaluator short-circuits in that
+ * order, so it is what the cost of a check rides on.
+ *
+ * The reader imports nothing but the vocabulary and the strict-read
+ * helpers, so the reader and the evaluator stay a self-contained pair.
+ */
+import { list, record, text } from "../strict-json.js";
+import type { Rewrite, SubjectType } from "./rewrite.js";
+
+/** The only schema version this reader accepts: the modular DSL's. */
+export const SUPPORTED_SCHEMA_VERSION = "1.2";
+
+/** One type of the compiled model, in the evaluator's vocabulary. */
+export interface ModelType {
+  /** The FGA type name: an `ApiResourceKind` member name (`agent`, `identity_account`). */
+  readonly type: string;
+  /** The `.fga` file the type is defined in, relative to the server package (`fga/model/agentic/agent.fga`). */
+  readonly source: string;
+  /** Every relation the type defines, sorted by name. */
+  readonly relations: ReadonlyMap<string, Rewrite>;
+}
+
+/** Where the `.fga` files live, relative to the server package; `source_info.file` is relative to it. */
+const MODEL_SOURCE_DIR = "fga/model";
+
+/**
+ * Reads a parsed compiled model. `where` names the file in every message.
+ * Throws on anything the module header says is refused or re-asserted.
+ */
+export function readOpenFgaModel(
+  value: unknown,
+  where = "authorization-model.json",
+): ReadonlyArray<ModelType> {
+  const root = record(value, where, ["schema_version", "type_definitions", "conditions"]);
+  if (root["conditions"] !== undefined) {
+    throw new Error(`${where}: conditions are not evaluated by this server`);
+  }
+  const version = text(root["schema_version"], `${where}: schema_version`);
+  if (version !== SUPPORTED_SCHEMA_VERSION) {
+    throw new Error(
+      `${where}: schema_version '${version}' is not ${SUPPORTED_SCHEMA_VERSION}, the only version this server reads`,
+    );
+  }
+
+  const types: ModelType[] = [];
+  const seen = new Set<string>();
+  list(root["type_definitions"], `${where}: type_definitions`).forEach((entry, index) => {
+    const parsed = readType(entry, `${where}: type_definitions[${index}]`);
+    if (seen.has(parsed.type)) {
+      throw new Error(`${where}: type '${parsed.type}' is defined twice`);
+    }
+    seen.add(parsed.type);
+    types.push(parsed);
+  });
+  assertReferencesResolve(types, where);
+  return types;
+}
+
+function readType(value: unknown, where: string): ModelType {
+  const entry = record(value, where, ["type", "relations", "metadata"]);
+  const type = text(entry["type"], `${where}.type`);
+  const at = `${where} (${type})`;
+  const metadata = record(entry["metadata"], `${at}.metadata`, [
+    "module",
+    "relations",
+    "source_info",
+  ]);
+  text(metadata["module"], `${at}.metadata.module`);
+  const sourceInfo = record(metadata["source_info"], `${at}.metadata.source_info`, ["file"]);
+  const file = text(sourceInfo["file"], `${at}.metadata.source_info.file`);
+
+  const directTypes = readDirectTypes(metadata["relations"], `${at}.metadata.relations`);
+  const rewrites =
+    entry["relations"] === undefined ? {} : record(entry["relations"], `${at}.relations`);
+
+  for (const relation of directTypes.keys()) {
+    if (!(relation in rewrites)) {
+      throw new Error(`${at}.metadata.relations.${relation}: metadata for a relation ${type} does not define`);
+    }
+  }
+
+  const relations = new Map<string, Rewrite>();
+  for (const name of Object.keys(rewrites).sort()) {
+    const subjects = directTypes.get(name);
+    const rewrite = readRewrite(rewrites[name], `${at}.relations.${name}`, subjects);
+    const hasThis = containsThis(rewrite);
+    if (hasThis && subjects === undefined) {
+      throw new Error(`${at}.relations.${name}: a direct relation with no directly_related_user_types`);
+    }
+    if (!hasThis && subjects !== undefined) {
+      throw new Error(`${at}.relations.${name}: directly_related_user_types on a relation with no direct node`);
+    }
+    relations.set(name, rewrite);
+  }
+  return { type, source: `${MODEL_SOURCE_DIR}/${file}`, relations };
+}
+
+/** Each relation's direct subject types; a relation whose metadata is `{}` lists none and is absent. */
+function readDirectTypes(value: unknown, where: string): ReadonlyMap<string, ReadonlyArray<SubjectType>> {
+  const out = new Map<string, ReadonlyArray<SubjectType>>();
+  if (value === undefined) {
+    return out;
+  }
+  for (const [relation, meta] of Object.entries(record(value, where))) {
+    const entry = record(meta, `${where}.${relation}`, ["directly_related_user_types"]);
+    if (entry["directly_related_user_types"] === undefined) {
+      continue;
+    }
+    const at = `${where}.${relation}.directly_related_user_types`;
+    out.set(
+      relation,
+      list(entry["directly_related_user_types"], at).map((item, index) =>
+        readSubjectType(item, `${at}[${index}]`),
+      ),
+    );
+  }
+  return out;
+}
+
+function readSubjectType(value: unknown, where: string): SubjectType {
+  const entry = record(value, where, ["type", "relation", "wildcard", "condition"]);
+  if (entry["wildcard"] !== undefined) {
+    throw new Error(`${where}: wildcard subject types are not evaluated by this server`);
+  }
+  if (entry["condition"] !== undefined) {
+    throw new Error(`${where}: conditional subject types are not evaluated by this server`);
+  }
+  const type = text(entry["type"], `${where}.type`);
+  return entry["relation"] === undefined
+    ? { form: "object", type }
+    : { form: "userset", type, relation: text(entry["relation"], `${where}.relation`) };
+}
+
+/**
+ * One rewrite node. `subjects` is the relation's direct list, which a
+ * `this` node takes; it is checked against the node's presence by the
+ * caller.
+ */
+function readRewrite(
+  value: unknown,
+  where: string,
+  subjects: ReadonlyArray<SubjectType> | undefined,
+): Rewrite {
+  const node = record(value, where, [
+    "this",
+    "computedUserset",
+    "tupleToUserset",
+    "union",
+    "intersection",
+    "difference",
+  ]);
+  const keys = Object.keys(node);
+  if (keys.length !== 1) {
+    throw new Error(`${where}: a rewrite node has exactly one form, found ${keys.length}`);
+  }
+  const form = keys[0];
+  switch (form) {
+    case "this":
+      record(node["this"], `${where}.this`, []);
+      return { node: "this", subjects: subjects ?? [] };
+    case "computedUserset":
+      return { node: "computed", relation: localRelation(node["computedUserset"], `${where}.computedUserset`) };
+    case "tupleToUserset": {
+      const ttu = record(node["tupleToUserset"], `${where}.tupleToUserset`, [
+        "tupleset",
+        "computedUserset",
+      ]);
+      return {
+        node: "from",
+        tupleset: localRelation(ttu["tupleset"], `${where}.tupleToUserset.tupleset`),
+        relation: localRelation(ttu["computedUserset"], `${where}.tupleToUserset.computedUserset`),
+      };
+    }
+    case "union":
+    case "intersection": {
+      const operator = record(node[form], `${where}.${form}`, ["child"]);
+      const members = list(operator["child"], `${where}.${form}.child`).map((child, index) =>
+        readRewrite(child, `${where}.${form}.child[${index}]`, subjects),
+      );
+      if (members.length === 0) {
+        throw new Error(`${where}.${form}: an operator with no children`);
+      }
+      return { node: form, members };
+    }
+    case "difference":
+      throw new Error(`${where}: 'but not' (difference) is not evaluated by this server`);
+    default:
+      throw new Error(`${where}: unknown rewrite form '${String(form)}'`);
+  }
+}
+
+/** An `ObjectRelation` naming a relation of the same object: `object` must be unset. */
+function localRelation(value: unknown, where: string): string {
+  const entry = record(value, where, ["relation", "object"]);
+  if (entry["object"] !== undefined) {
+    throw new Error(`${where}: a relation on another object is not evaluated by this server`);
+  }
+  return text(entry["relation"], `${where}.relation`);
+}
+
+function containsThis(rewrite: Rewrite): boolean {
+  switch (rewrite.node) {
+    case "this":
+      return true;
+    case "computed":
+    case "from":
+      return false;
+    case "union":
+    case "intersection":
+      return rewrite.members.some(containsThis);
+    default: {
+      const exhaustive: never = rewrite;
+      throw new Error(`unknown rewrite node: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+
+/** The cross-type re-assertions of the module header. */
+function assertReferencesResolve(types: ReadonlyArray<ModelType>, where: string): void {
+  const byType = new Map(types.map((entry) => [entry.type, entry]));
+  for (const entry of types) {
+    for (const [name, rewrite] of entry.relations) {
+      const at = `${where}: ${entry.type}#${name}`;
+      walk(rewrite, (node) => {
+        switch (node.node) {
+          case "computed":
+            if (!entry.relations.has(node.relation)) {
+              throw new Error(`${at}: names relation '${node.relation}', which ${entry.type} does not define`);
+            }
+            return;
+          case "from":
+            if (!entry.relations.has(node.tupleset)) {
+              throw new Error(`${at}: names tupleset '${node.tupleset}', which ${entry.type} does not define`);
+            }
+            return;
+          case "this":
+            for (const subject of node.subjects) {
+              const target = byType.get(subject.type);
+              if (target === undefined) {
+                throw new Error(`${at}: admits subject type '${subject.type}', which the model does not define`);
+              }
+              if (subject.form === "userset" && !target.relations.has(subject.relation)) {
+                throw new Error(
+                  `${at}: admits '${subject.type}#${subject.relation}', which ${subject.type} does not define`,
+                );
+              }
+            }
+            return;
+          case "union":
+          case "intersection":
+            return;
+          default: {
+            const exhaustive: never = node;
+            throw new Error(`unknown rewrite node: ${JSON.stringify(exhaustive)}`);
+          }
+        }
+      });
+    }
+  }
+}
+
+/** Visits every node of a rewrite, depth first, in order. */
+function walk(rewrite: Rewrite, visit: (node: Rewrite) => void): void {
+  visit(rewrite);
+  if (rewrite.node === "union" || rewrite.node === "intersection") {
+    for (const member of rewrite.members) {
+      walk(member, visit);
+    }
+  }
+}