@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/authorization/model/rewrite.ts

@@ -0,0 +1,213 @@
+/**
+ * The relation-rewrite vocabulary the model declarations are written in —
+ * the four forms an OpenFGA `define` line takes in the cloud's 27 `.fga`
+ * files, and nothing more:
+ *
+ *   define organization: [organization]                      → direct(objectOf("organization"))
+ *   define owner: [identity_account] or admin from organization
+ *                → union(direct(objectOf("identity_account")), from("admin", "organization"))
+ *   define viewer: [identity_account, identity_account:* with allow_public,
+ *                   organization#member, organization#viewer] or owner or platform_viewer
+ *                → union(direct(objectOf(...), publicWith(...), usersetOf(...), usersetOf(...)),
+ *                        computed("owner"), computed("platform_viewer"))
+ *   define can_view: viewer                                   → computed("viewer")
+ *
+ * A declaration file (model/<kind>.ts) is a TRANSCRIPT of its `.fga`
+ * file: the same relations, in the file's order, each line rewritten in
+ * these builders so a reader with the model open sees the same text, and
+ * so a structural compare against the file (the cloud's drift test at
+ * the re-pin) needs no translation table. Intersection and exclusion
+ * (`and`, `but not`) do not appear in the model and have no node here;
+ * the day they do, the transcript cannot be written and the gap is a
+ * design act, not a silent approximation.
+ *
+ * The direct form carries its type restrictions (`[identity_account,
+ * organization#viewer]`) because the evaluator ENFORCES them: a tuple
+ * whose subject the line does not list is ignored, which is what OpenFGA
+ * does at write time. That is the fail-closed property of this design —
+ * a derivation that drifts from the model (a userset the line dropped)
+ * makes open source deny, never allow.
+ *
+ * `derived` names the relations `kind_meta.authorization` cannot derive
+ * from the row alone: `default_of` on an instance (the
+ * blueprint's `status.default_instance_id` must name this row — one
+ * blueprint read through the loader; default-of.ts, shared by the two
+ * instance kinds) and `execution_viewer` on a workflow instance
+ * (`spec.execution_visibility`; workflow_instance.ts). A declaration that
+ * has such a relation states the rule beside the transcript; the tuple
+ * source dispatches to it by relation.
+ */
+import type { DescMessage, Message } from "@bufbuild/protobuf";
+
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import type { ObjectRef, RowLoader, Tuple } from "../tuples.js";
+
+/** One entry of a direct line's type restriction list. */
+export type SubjectType =
+  /** `[organization]`, `[identity_account]` — objects of the type. */
+  | { readonly form: "object"; readonly type: string }
+  /** `[organization#viewer]` — everyone holding `relation` on an object of the type. */
+  | {
+      readonly form: "userset";
+      readonly type: string;
+      readonly relation: string;
+    }
+  /** `[identity_account:* with allow_public]` — every object of the type, under the condition. */
+  | {
+      readonly form: "wildcard";
+      readonly type: string;
+      readonly condition: string;
+    };
+
+export type Rewrite =
+  /** `[…]` — the tuples stored on the relation itself, restricted to the listed subject types. */
+  | { readonly node: "this"; readonly subjects: ReadonlyArray<SubjectType> }
+  /** `or owner` — another relation of the same object. */
+  | { readonly node: "computed"; readonly relation: string }
+  /** `admin from organization` — `relation` on every object the `tupleset` relation links to. */
+  | {
+      readonly node: "from";
+      readonly relation: string;
+      readonly tupleset: string;
+    }
+  /** `a or b or c` — the first true member wins, in the line's order. */
+  | { readonly node: "union"; readonly members: ReadonlyArray<Rewrite> };
+
+// ---------------------------------------------------------------------------
+// Builders — named so a transcript reads like its `.fga` line.
+// ---------------------------------------------------------------------------
+
+export function objectOf(type: string): SubjectType {
+  return { form: "object", type };
+}
+
+export function usersetOf(type: string, relation: string): SubjectType {
+  return { form: "userset", type, relation };
+}
+
+export function publicWith(type: string, condition: string): SubjectType {
+  return { form: "wildcard", type, condition };
+}
+
+export function direct(...subjects: ReadonlyArray<SubjectType>): Rewrite {
+  return { node: "this", subjects };
+}
+
+export function computed(relation: string): Rewrite {
+  return { node: "computed", relation };
+}
+
+export function from(relation: string, tupleset: string): Rewrite {
+  return { node: "from", relation, tupleset };
+}
+
+export function union(...members: ReadonlyArray<Rewrite>): Rewrite {
+  return { node: "union", members };
+}
+
+// ---------------------------------------------------------------------------
+// A kind's declaration.
+// ---------------------------------------------------------------------------
+
+/**
+ * A relation the row does not carry as a `kind_meta` fact: the rule that
+ * derives its tuples for `object` from its decoded row, reading related
+ * rows through the loader. The source hands the object it already
+ * resolved so a rule never re-derives its own reference from the row.
+ * Pure over its inputs; faults propagate.
+ */
+export type DerivedRelation = (
+  object: ObjectRef,
+  row: Message,
+  loader: RowLoader,
+) => Promise<ReadonlyArray<Tuple>>;
+
+export interface KindDeclaration {
+  readonly kind: ApiResourceKind;
+  /** The FGA type name — the kind's enum member name, as the cloud renders objects. */
+  readonly type: string;
+  /** The kind's message schema: what a stored row decodes with, and where its audit lives. */
+  readonly schema: DescMessage;
+  /** The `.fga` file this transcribes, relative to the cloud's `fga/` folder. */
+  readonly source: string;
+  /** Every relation the file defines, in the file's order. */
+  readonly relations: ReadonlyMap<string, Rewrite>;
+  /** The relations `kind_meta` cannot derive (the module header). */
+  readonly derived: ReadonlyMap<string, DerivedRelation>;
+}
+
+export interface KindDeclarationInput {
+  readonly kind: ApiResourceKind;
+  readonly schema: DescMessage;
+  readonly source: string;
+  readonly relations: ReadonlyArray<readonly [name: string, rewrite: Rewrite]>;
+  readonly derived?: ReadonlyArray<
+    readonly [name: string, rule: DerivedRelation]
+  >;
+}
+
+/**
+ * Builds a declaration and refuses a transcript that cannot be right at
+ * module load: a relation declared twice, a `computed` naming a relation
+ * the kind does not define, a `from` whose tupleset the kind does not
+ * define (its `relation` is the PARENT's and is resolved at evaluation),
+ * a derived rule for a relation the transcript does not declare.
+ */
+export function declareKind(input: KindDeclarationInput): KindDeclaration {
+  const type = kindEnumName(input.kind);
+  const relations = new Map<string, Rewrite>();
+  for (const [name, rewrite] of input.relations) {
+    if (relations.has(name)) {
+      throw new Error(`${input.source}: relation '${name}' is declared twice`);
+    }
+    relations.set(name, rewrite);
+  }
+  for (const [name, rewrite] of relations) {
+    for (const reference of localReferences(rewrite)) {
+      if (!relations.has(reference.relation)) {
+        throw new Error(
+          `${input.source}: '${name}' names ${reference.role} '${reference.relation}', which ${type} does not declare`,
+        );
+      }
+    }
+  }
+  const derived = new Map<string, DerivedRelation>();
+  for (const [name, rule] of input.derived ?? []) {
+    if (!relations.has(name)) {
+      throw new Error(
+        `${input.source}: a derived rule for '${name}', which ${type} does not declare`,
+      );
+    }
+    derived.set(name, rule);
+  }
+  return {
+    kind: input.kind,
+    type,
+    schema: input.schema,
+    source: input.source,
+    relations,
+    derived,
+  };
+}
+
+/** The relations of the SAME kind a rewrite names: computed targets and tuplesets. */
+function localReferences(
+  rewrite: Rewrite,
+): ReadonlyArray<{ readonly role: string; readonly relation: string }> {
+  switch (rewrite.node) {
+    case "this":
+      return [];
+    case "computed":
+      return [{ role: "relation", relation: rewrite.relation }];
+    case "from":
+      return [{ role: "tupleset", relation: rewrite.tupleset }];
+    case "union":
+      return rewrite.members.flatMap(localReferences);
+    default: {
+      const exhaustive: never = rewrite;
+      throw new Error(`unknown rewrite node: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}

package/src/authorization/model/schedule.ts

@@ -0,0 +1,40 @@
+/**
+ * Transcript of fga/model/agentic/schedule.fga — a scheduled run's
+ * definition, admin-owned like a blueprint and viewable by its owners and
+ * explicit grantees. The sessions its fires create name it back through
+ * `session#schedule`, a link the cloud writes and this edition does not
+ * (session.ts); the schedule's own relations are unaffected.
+ */
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const scheduleDeclaration = declareKind({
+  kind: ApiResourceKind.schedule,
+  schema: ScheduleSchema,
+  source: "fga/model/agentic/schedule.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    [
+      "owner",
+      union(
+        direct(objectOf("identity_account")),
+        from("admin", "organization"),
+      ),
+    ],
+    ["viewer", union(direct(objectOf("identity_account")), computed("owner"))],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/session.ts

@@ -0,0 +1,50 @@
+/**
+ * Transcript of fga/model/agentic/session.fga — a personal resource: the
+ * owner and explicit grantees, and NO admin arm anywhere ("private
+ * conversations that admins have no business accessing", the file's own
+ * words). Three parent links beside the organization: `agent_instance`,
+ * `channel` and `schedule`. None is a `kind_meta` fact — the cloud's
+ * channel and schedule lanes write them — so on this edition the
+ * derivation produces no such tuple and `viewer from channel` / `viewer
+ * from schedule` resolve to nobody; the lines stand in the transcript
+ * because they are the model's, and a scheduled run reaches its creator
+ * through the fire caller's stamp on the session instead.
+ */
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const sessionDeclaration = declareKind({
+  kind: ApiResourceKind.session,
+  schema: SessionSchema,
+  source: "fga/model/agentic/session.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    ["agent_instance", direct(objectOf("agent_instance"))],
+    ["channel", direct(objectOf("agent_channel"))],
+    ["schedule", direct(objectOf("schedule"))],
+    ["owner", direct(objectOf("identity_account"))],
+    ["viewer", union(direct(objectOf("identity_account")), computed("owner"))],
+    [
+      "can_view",
+      union(
+        computed("viewer"),
+        from("viewer", "channel"),
+        from("viewer", "schedule"),
+      ),
+    ],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_create_execution_in", computed("viewer")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/skill.ts

@@ -0,0 +1,60 @@
+/**
+ * Transcript of fga/model/agentic/skill.fga — a blueprint whose verbs are
+ * `can_use` and `can_clone` rather than `can_execute`. Only `can_view`,
+ * `can_edit`, `can_delete`, `can_grant_access` and `can_view_access` are
+ * in the wire's IamPermission vocabulary; the others are the model's and
+ * are carried so the transcript is the file.
+ */
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  publicWith,
+  union,
+  usersetOf,
+} from "./rewrite.js";
+
+export const skillDeclaration = declareKind({
+  kind: ApiResourceKind.skill,
+  schema: SkillSchema,
+  source: "fga/model/agentic/skill.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    [
+      "owner",
+      union(
+        direct(objectOf("identity_account")),
+        from("admin", "organization"),
+      ),
+    ],
+    [
+      "platform_viewer",
+      direct(usersetOf("identity_provider", "platform_user")),
+    ],
+    [
+      "viewer",
+      union(
+        direct(
+          objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
+          usersetOf("organization", "member"),
+          usersetOf("organization", "viewer"),
+        ),
+        computed("owner"),
+        computed("platform_viewer"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_use", computed("viewer")],
+    ["can_clone", computed("viewer")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/workflow.ts

@@ -0,0 +1,60 @@
+/**
+ * Transcript of fga/model/agentic/workflow.fga — the agent's shape
+ * without `can_create_instance` (a workflow instance is created through
+ * the workflow-instance lane, gated by the organization). Kept as its own
+ * transcript, not a shared "blueprint" helper, so the file-by-file drift
+ * compare sees exactly this file's lines.
+ */
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  publicWith,
+  union,
+  usersetOf,
+} from "./rewrite.js";
+
+export const workflowDeclaration = declareKind({
+  kind: ApiResourceKind.workflow,
+  schema: WorkflowSchema,
+  source: "fga/model/agentic/workflow.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    [
+      "owner",
+      union(
+        direct(objectOf("identity_account")),
+        from("admin", "organization"),
+      ),
+    ],
+    [
+      "platform_viewer",
+      direct(usersetOf("identity_provider", "platform_user")),
+    ],
+    [
+      "viewer",
+      union(
+        direct(
+          objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
+          usersetOf("organization", "member"),
+          usersetOf("organization", "viewer"),
+        ),
+        computed("owner"),
+        computed("platform_viewer"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_execute", computed("viewer")],
+    ["can_clone", computed("viewer")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/workflow_execution.ts

@@ -0,0 +1,44 @@
+/**
+ * Transcript of fga/model/agentic/workflow_execution.fga — a run with an
+ * owner of its own (the person who triggered it; `kind_meta` attribution
+ * DIRECT, unlike agent_execution's inherited owner) and two ways in for
+ * others: an explicit per-run grant, or the instance's opt-in run
+ * audience through `execution_viewer from workflow_instance`, standing on
+ * the `workflow_instance` link the derivation writes from
+ * `spec.workflow_instance_id`. No `can_delete`: run history outlives its
+ * instance by design.
+ */
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const workflowExecutionDeclaration = declareKind({
+  kind: ApiResourceKind.workflow_execution,
+  schema: WorkflowExecutionSchema,
+  source: "fga/model/agentic/workflow_execution.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    ["workflow_instance", direct(objectOf("workflow_instance"))],
+    ["owner", direct(objectOf("identity_account"))],
+    [
+      "viewer",
+      union(
+        direct(objectOf("identity_account")),
+        computed("owner"),
+        from("execution_viewer", "workflow_instance"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/authorization/model/workflow_instance.ts

@@ -0,0 +1,122 @@
+/**
+ * Transcript of fga/model/agentic/workflow_instance.fga — the agent
+ * instance's shape plus one relation of its own: `execution_viewer`, the
+ * opt-in audience for the instance's RUN history, kept apart from
+ * `viewer` so making an instance org-runnable never exposes other
+ * people's run inputs and outputs. Consumed by workflow_execution through
+ * `execution_viewer from workflow_instance`.
+ *
+ * `execution_viewer` is derived here from `spec.execution_visibility`
+ * (the second rule `kind_meta` cannot express): `organization` derives
+ * `#execution_viewer@organization:<org>#viewer` — the organization's full
+ * read audience, the shape the file's comment names and the cloud's own
+ * store test writes, with `#member` the legacy shape the line still
+ * admits — and `private` or unset derives nothing, so each run stays its
+ * triggerer's. The cloud has no writer for this tuple today; this
+ * edition enforces the field as the contract states it.
+ */
+import { isMessage } from "@bufbuild/protobuf";
+
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+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 { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { defaultOfBlueprint } from "./default-of.js";
+import type { DerivedRelation } from "./rewrite.js";
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  publicWith,
+  union,
+  usersetOf,
+} from "./rewrite.js";
+
+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)}`);
+    }
+  }
+};
+
+export const workflowInstanceDeclaration = declareKind({
+  kind: ApiResourceKind.workflow_instance,
+  schema: WorkflowInstanceSchema,
+  source: "fga/model/agentic/workflow_instance.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    ["workflow", direct(objectOf("workflow"))],
+    ["default_of", direct(objectOf("workflow"))],
+    ["owner", direct(objectOf("identity_account"))],
+    [
+      "viewer",
+      union(
+        direct(
+          objectOf("identity_account"),
+          publicWith("identity_account", "allow_public"),
+          usersetOf("organization", "member"),
+          usersetOf("organization", "viewer"),
+        ),
+        computed("owner"),
+        from("viewer", "default_of"),
+      ),
+    ],
+    [
+      "execution_viewer",
+      direct(
+        objectOf("identity_account"),
+        usersetOf("organization", "member"),
+        usersetOf("organization", "viewer"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_execute", computed("can_view")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+  derived: [
+    [
+      "default_of",
+      defaultOfBlueprint({
+        kind: ApiResourceKind.workflow,
+        schema: WorkflowSchema,
+        defaultInstanceIdOf: (workflow) =>
+          workflow.status?.defaultInstanceId ?? "",
+      }),
+    ],
+    ["execution_viewer", executionViewer],
+  ],
+});