@stigmer/server 3.26.0 → 3.27.1

package/src/authorization/model/__tests__/registry.test.ts

@@ -5,7 +5,11 @@
  * kind is reached by enum and by FGA type name alike, and that every
  * permission the wire can ask about (the IamPermission vocabulary) is
  * either a declared relation of the kind or absent from its `.fga` file —
- * never a relation the transcript forgot.
+ * never a relation the transcript forgot — and that the relations whose
+ * direct list admits a team (`team#member`) are exactly the roles the
+ * kind's `team_grantable_roles` names, a subset of what a person can be
+ * granted and never ownership, so the grant step and the model cannot
+ * disagree about where a team may be granted.
  *
  * The kind list is pinned twice on purpose: as the literal in registry
  * order (a reordering or a dropped file is a visible diff) and as
@@ -20,13 +24,19 @@ import {
   ApiResourceKindSchema,
   ResourceTier,
 } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import { IamPermissionSchema } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import {
+  IamPermissionSchema,
+  IamRole,
+} from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import {
   getKindMeta,
+  grantableRolesFor,
   kindEnumName,
+  teamGrantableRolesFor,
 } from "../../../pipeline/apiresource-meta.js";
 import { builtInModel, declarationFor } from "../index.js";
+import type { Rewrite, SubjectType } from "../rewrite.js";
 
 /** The open-source tier, in registry order (the `fga.mod` order of their files). */
 const DECLARED_KINDS = [
@@ -121,6 +131,7 @@ const WIRE_PERMISSIONS_BY_TYPE: Readonly<
     "can_create_execution_in",
     "can_create_agent_share",
     "can_create_agent_instance",
+    "can_create_team",
     "can_grant_access",
     "can_view_access",
     "can_view_billing",
@@ -238,6 +249,32 @@ const WIRE_PERMISSIONS_BY_TYPE: Readonly<
   ],
 };
 
+/** The subject types a relation's direct lists name, wherever they sit in its rewrite. */
+function directSubjects(rewrite: Rewrite): ReadonlyArray<SubjectType> {
+  switch (rewrite.node) {
+    case "this":
+      return rewrite.subjects;
+    case "computed":
+    case "from":
+      return [];
+    case "union":
+    case "intersection":
+      return rewrite.members.flatMap(directSubjects);
+    default: {
+      const exhaustive: never = rewrite;
+      throw new Error(`unknown rewrite node: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+
+function isTeamMembers(subject: SubjectType): boolean {
+  return (
+    subject.form === "userset" &&
+    subject.type === "team" &&
+    subject.relation === "member"
+  );
+}
+
 /** Every kind whose `kind_meta.tier` is the open-source tier, by enum number. */
 function openSourceTierKinds(): ReadonlySet<ApiResourceKind> {
   const kinds = new Set<ApiResourceKind>();
@@ -271,6 +308,7 @@ describe("the built-in model's registry", () => {
       ApiResourceKind.platform,
       ApiResourceKind.identity_provider,
       ApiResourceKind.invitation,
+      ApiResourceKind.team,
     ]) {
       expect(declarationFor(unserved), kindEnumName(unserved)).toBeUndefined();
     }
@@ -304,6 +342,30 @@ describe("the built-in model's registry", () => {
     }
   });
 
+  it("admits a team exactly on the roles each kind's team_grantable_roles lists — the transcript and the contract say one thing", () => {
+    for (const declaration of builtInModel.declarations) {
+      const admitsTeam = [...declaration.relations]
+        .filter(([, rewrite]) => directSubjects(rewrite).some(isTeamMembers))
+        .map(([relation]) => relation)
+        .sort();
+      const contract = teamGrantableRolesFor(declaration.kind)
+        .map((role) => IamRole[role])
+        .sort();
+      expect(admitsTeam, declaration.type).toEqual(contract);
+    }
+  });
+
+  it("lets a team hold only roles a person can hold on the kind, and never ownership", () => {
+    for (const value of ApiResourceKindSchema.values) {
+      const kind = value.number as ApiResourceKind;
+      const person = grantableRolesFor(kind);
+      for (const role of teamGrantableRolesFor(kind)) {
+        expect(person, `${value.name}: ${IamRole[role]}`).toContain(role);
+        expect(role, value.name).not.toBe(IamRole.owner);
+      }
+    }
+  });
+
   it("carries a derived rule only where kind_meta cannot derive the relation: default_of on the two instance kinds, execution_viewer on the workflow instance", () => {
     const derived = builtInModel.declarations
       .flatMap((d) => [...d.derived.keys()].map((r) => `${d.type}#${r}`))

package/src/authorization/model/agent.ts

@@ -5,7 +5,9 @@
  * and `organization#viewer` usersets on `viewer` are the org-visibility
  * tuple's two shapes (the cloud writes `#viewer` since cloud#257; `#member`
  * is the legacy shape it still honours), and `platform_viewer` is an
- * identity-provider userset no open-source tuple ever names.
+ * identity-provider userset no open-source tuple ever names. `team#member`
+ * is the Enterprise team grant; open source serves no team, so no tuple
+ * here ever names one.
  */
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -44,6 +46,7 @@ export const agentDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         computed("platform_viewer"),

package/src/authorization/model/agent_channel.ts

@@ -4,7 +4,8 @@
  * between owner and viewer: the conversation-participation role
  * (reply and takeover without configuration authority), grantable as a
  * role on this kind alone. Every owner participates; every participant
- * views.
+ * views. Both grantable relations may name an Enterprise team
+ * (`team#member`), which no open-source tuple ever does.
  */
 import { AgentChannelSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -16,6 +17,7 @@ import {
   from,
   objectOf,
   union,
+  usersetOf,
 } from "./rewrite.js";
 
 export const agentChannelDeclaration = declareKind({
@@ -33,11 +35,17 @@ export const agentChannelDeclaration = declareKind({
     ],
     [
       "participant",
-      union(direct(objectOf("identity_account")), computed("owner")),
+      union(
+        direct(objectOf("identity_account"), usersetOf("team", "member")),
+        computed("owner"),
+      ),
     ],
     [
       "viewer",
-      union(direct(objectOf("identity_account")), computed("participant")),
+      union(
+        direct(objectOf("identity_account"), usersetOf("team", "member")),
+        computed("participant"),
+      ),
     ],
     ["can_view", computed("viewer")],
     ["can_edit", computed("owner")],

package/src/authorization/model/agent_instance.ts

@@ -6,7 +6,8 @@
  * viewer set (`viewer from default_of`; default-of.ts). `agent` is the
  * parent link written on every instance for tracking and walked by
  * nothing; `default_of` is the derived link written on the default
- * instance alone.
+ * instance alone. `team#member` on `viewer` is the Enterprise team grant,
+ * which no open-source tuple ever names.
  */
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
@@ -39,6 +40,7 @@ export const agentInstanceDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         from("viewer", "default_of"),

package/src/authorization/model/mcp_server.ts

@@ -1,7 +1,8 @@
 /**
  * Transcript of fga/model/agentic/mcp_server.fga — a blueprint with three
  * read-side verbs: `can_use`, `can_clone` and `can_connect` (the OAuth
- * connect lane's gate), all `viewer`.
+ * connect lane's gate), all `viewer`. `team#member` on `viewer` is the
+ * Enterprise team grant, which no open-source tuple ever names.
  */
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -40,6 +41,7 @@ export const mcpServerDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         computed("platform_viewer"),

package/src/authorization/model/organization.ts

@@ -12,6 +12,8 @@
  * share-link visitor; no open-source lane mints one (claim check C5), so
  * the relation resolves to nothing and `can_create_session: member or
  * guest` is `member` here — the transcript still carries the line.
+ * `can_create_team` is carried the same way: open source serves no Team
+ * kind, so nothing here asks it.
  */
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
@@ -48,6 +50,7 @@ export const organizationDeclaration = declareKind({
     ["can_create_execution_in", union(computed("member"), computed("guest"))],
     ["can_create_agent_share", computed("admin")],
     ["can_create_agent_instance", computed("member")],
+    ["can_create_team", computed("admin")],
     ["can_grant_access", computed("admin")],
     ["can_view_access", computed("viewer")],
     ["can_view_billing", computed("viewer")],

package/src/authorization/model/plugin.ts

@@ -5,7 +5,9 @@
  * the org's members and viewers and the platform viewer. Its verbs are the blueprint set: `can_view`, `can_edit`
  * (visibility), `can_delete` (uninstall), `can_grant_access`,
  * `can_view_access`; `can_use` is carried as the model's word for
- * "install from" though no wire permission names it yet.
+ * "install from" though no wire permission names it yet. `team#member` on
+ * `viewer` is the Enterprise team grant, which no open-source tuple ever
+ * names.
  *
  * The members a plugin materialises are NOT reached through this type:
  * each is an ordinary skill, MCP server, agent or workflow with its own
@@ -48,6 +50,7 @@ export const pluginDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         computed("platform_viewer"),

package/src/authorization/model/rewrite.ts

@@ -1,7 +1,7 @@
 /**
  * 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:
+ * the forms an OpenFGA `define` line takes in the cloud's `.fga` files,
+ * and nothing more:
  *
  *   define organization: [organization]                      → direct(objectOf("organization"))
  *   define owner: [identity_account] or admin from organization
@@ -10,8 +10,20 @@
  *                   or owner or platform_viewer
  *                → union(direct(objectOf(...), usersetOf(...), usersetOf(...)),
  *                        computed("owner"), computed("platform_viewer"))
+ *   define member: [identity_account] and viewer from organization
+ *                → intersection(direct(objectOf("identity_account")), from("viewer", "organization"))
  *   define can_view: viewer                                   → computed("viewer")
  *
+ * `and` exists for one shape: a relation that is true only while another
+ * holds too — a team's member is a person granted the role AND still one
+ * of the organization's viewers, so leaving the organization ends every
+ * team-derived grant with no cleanup. A line is either a union or an
+ * intersection of leaves, never both: the DSL would need parentheses to
+ * mix them, the cloud's reader refuses parentheses, and `declareKind`
+ * refuses the nesting that would need them. `but not` has no node; the day
+ * a line needs it, the transcript cannot be written and the gap is a
+ * design act.
+ *
  * A subject type is an object type or a userset; the model admits no
  * wildcard (`type:*`) and declares no condition, so neither has a form
  * here. The day a line needs one, the transcript cannot be written and
@@ -21,10 +33,7 @@
  * 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 re-pin) needs no translation table.
  *
  * The direct form carries its type restrictions (`[identity_account,
  * organization#viewer]`) because the evaluator ENFORCES them: a tuple
@@ -72,7 +81,12 @@ export type Rewrite =
       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> };
+  | { readonly node: "union"; readonly members: ReadonlyArray<Rewrite> }
+  /** `a and b` — true only when every member is, in the line's order; the first false one ends it. */
+  | {
+      readonly node: "intersection";
+      readonly members: ReadonlyArray<Rewrite>;
+    };
 
 // ---------------------------------------------------------------------------
 // Builders — named so a transcript reads like its `.fga` line.
@@ -102,6 +116,10 @@ export function union(...members: ReadonlyArray<Rewrite>): Rewrite {
   return { node: "union", members };
 }
 
+export function intersection(...members: ReadonlyArray<Rewrite>): Rewrite {
+  return { node: "intersection", members };
+}
+
 // ---------------------------------------------------------------------------
 // A kind's declaration.
 // ---------------------------------------------------------------------------
@@ -148,7 +166,10 @@ export interface KindDeclarationInput {
  * 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.
+ * a derived rule for a relation the transcript does not declare, and a
+ * line no `.fga` file could hold without parentheses (a union inside an
+ * intersection or the reverse, an operator nested in itself, an operator
+ * over fewer than two members).
  */
 export function declareKind(input: KindDeclarationInput): KindDeclaration {
   const type = kindEnumName(input.kind);
@@ -157,6 +178,10 @@ export function declareKind(input: KindDeclarationInput): KindDeclaration {
     if (relations.has(name)) {
       throw new Error(`${input.source}: relation '${name}' is declared twice`);
     }
+    const shape = unwritableShape(rewrite);
+    if (shape !== undefined) {
+      throw new Error(`${input.source}: '${name}' ${shape}`);
+    }
     relations.set(name, rewrite);
   }
   for (const [name, rewrite] of relations) {
@@ -199,6 +224,7 @@ function localReferences(
     case "from":
       return [{ role: "tupleset", relation: rewrite.tupleset }];
     case "union":
+    case "intersection":
       return rewrite.members.flatMap(localReferences);
     default: {
       const exhaustive: never = rewrite;
@@ -206,3 +232,34 @@ function localReferences(
     }
   }
 }
+
+/**
+ * Why a line could not be written in a `.fga` file without parentheses,
+ * or undefined when it can: an operator's members are leaves (a direct
+ * list, a sibling relation, a tuple-to-userset), and there are at least
+ * two of them.
+ */
+function unwritableShape(rewrite: Rewrite): string | undefined {
+  switch (rewrite.node) {
+    case "this":
+    case "computed":
+    case "from":
+      return undefined;
+    case "union":
+    case "intersection": {
+      if (rewrite.members.length < 2) {
+        return `is ${rewrite.node === "union" ? "an or" : "an and"} over fewer than two members`;
+      }
+      const nested = rewrite.members.find(
+        (member) => member.node === "union" || member.node === "intersection",
+      );
+      return nested === undefined
+        ? undefined
+        : `nests ${nested.node === "union" ? "or" : "and"} inside ${rewrite.node === "union" ? "or" : "and"}, which a .fga line cannot say without parentheses`;
+    }
+    default: {
+      const exhaustive: never = rewrite;
+      throw new Error(`unknown rewrite node: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}

package/src/authorization/model/schedule.ts

@@ -3,7 +3,9 @@
  * 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.
+ * (session.ts); the schedule's own relations are unaffected. An explicit
+ * grant may name an Enterprise team (`team#member`), which no open-source
+ * tuple ever does.
  */
 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";
@@ -15,6 +17,7 @@ import {
   from,
   objectOf,
   union,
+  usersetOf,
 } from "./rewrite.js";
 
 export const scheduleDeclaration = declareKind({
@@ -30,7 +33,13 @@ export const scheduleDeclaration = declareKind({
         from("admin", "organization"),
       ),
     ],
-    ["viewer", union(direct(objectOf("identity_account")), computed("owner"))],
+    [
+      "viewer",
+      union(
+        direct(objectOf("identity_account"), usersetOf("team", "member")),
+        computed("owner"),
+      ),
+    ],
     ["can_view", computed("viewer")],
     ["can_edit", computed("owner")],
     ["can_delete", computed("owner")],

package/src/authorization/model/skill.ts

@@ -3,7 +3,8 @@
  * `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.
+ * are carried so the transcript is the file. `team#member` on `viewer` is
+ * the Enterprise team grant, which no open-source tuple ever names.
  */
 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";
@@ -42,6 +43,7 @@ export const skillDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         computed("platform_viewer"),

package/src/authorization/model/workflow.ts

@@ -3,7 +3,8 @@
  * 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.
+ * compare sees exactly this file's lines. `team#member` on `viewer` is the
+ * Enterprise team grant, which no open-source tuple ever names.
  */
 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";
@@ -42,6 +43,7 @@ export const workflowDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         computed("platform_viewer"),

package/src/authorization/model/workflow_execution.ts

@@ -6,7 +6,8 @@
  * 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.
+ * instance by design. The per-run grant may name an Enterprise team
+ * (`team#member`), which no open-source tuple ever does.
  */
 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";
@@ -18,6 +19,7 @@ import {
   from,
   objectOf,
   union,
+  usersetOf,
 } from "./rewrite.js";
 
 export const workflowExecutionDeclaration = declareKind({
@@ -31,7 +33,7 @@ export const workflowExecutionDeclaration = declareKind({
     [
       "viewer",
       union(
-        direct(objectOf("identity_account")),
+        direct(objectOf("identity_account"), usersetOf("team", "member")),
         computed("owner"),
         from("execution_viewer", "workflow_instance"),
       ),

package/src/authorization/model/workflow_instance.ts

@@ -14,6 +14,10 @@
  * 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.
+ *
+ * `team#member` on `viewer` is the Enterprise team grant, which no
+ * open-source tuple ever names; `execution_viewer` is not a grantable role
+ * and admits no team.
  */
 import { isMessage } from "@bufbuild/protobuf";
 
@@ -85,6 +89,7 @@ export const workflowInstanceDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         from("viewer", "default_of"),

package/src/boot/compose.ts

@@ -1309,6 +1309,8 @@ export async function composeServer(
       grantScope:
         extensions.drivers.policyGrantScope ?? newOrganizationOnlyGrantScope(),
       queries: extensions.drivers.authorizationQueries,
+      principalDisplay: extensions.drivers.principalDisplay,
+      gateSteps: extensions.gateSteps,
       edition: extensions.edition,
       logger,
     });