@stigmer/server 3.25.0 → 3.27.0

package/src/domain/iampolicy/constants.ts

@@ -36,7 +36,9 @@
  * console and SDK show these sentences verbatim, so they are contract. The
  * new sentences are the two edition refusals (the federation shape), the
  * unknown permission, the unknown principal kind (the resource sentence's
- * shape) and the malformed triple.
+ * shape), the malformed triple, and the four principal refusals a team
+ * grantee brought (a person's qualifier, a team's qualifier, a kind no
+ * team may be granted, a role a team may not hold).
  */
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type {
@@ -157,8 +159,8 @@ export const ROLES_RECONCILED_KEY = "membership_rules_reconciled";
 /**
  * The principal kinds a PERSON may grant a role to — the user `create`
  * lane's grantee vocabulary (2026-09-14, session 9 ruling Q-S9-2; the
- * security read's finding 41). A role names a person, so the one grantee
- * is the identity account. A row whose principal is a RESOURCE
+ * security read's finding 41): a person (the identity account) and a team
+ * of people. A row whose principal is a RESOURCE
  * (`organization:A#organization@platform_client:X`, `#managed_org`) is a
  * structural link, and structural links are `bootstrapPolicy`'s — the
  * platform's own lane, which skips role validation by design.
@@ -169,14 +171,27 @@ export const ROLES_RECONCILED_KEY = "membership_rules_reconciled";
  * two cannot drift), and the hierarchy walk follows it. Without the arm, a
  * person with `can_grant_access` on organization B could write
  * `organization:A#member@organization:B` and B's Members page, asked for
- * inherited access, would list A's people. The cloud's `create` had the
- * same gap; the store's exclusion also keeps the cloud's Java-era `team`,
- * which is not an ApiResourceKind and so no wire spec can name.
+ * inherited access, would list A's people.
+ *
+ * Each kind grants through its own list: a person the kind's
+ * `grantable_roles`, a team its `team_grantable_roles`, always as the
+ * team's members (`TEAM_MEMBERS_RELATION`). A kind that lists no team role
+ * — `organization` among them, so open source's organization-only scope —
+ * grants a team nothing.
  */
 export const USER_GRANT_PRINCIPAL_KINDS: ReadonlyArray<ApiResourceKind> = [
   ApiResourceKind.identity_account,
+  ApiResourceKind.team,
 ];
 
+/**
+ * The one relation a team principal names: the team's members. A grant to
+ * `team:<id>#member` is a grant to every member, and membership is bounded
+ * by organization membership in the model, so leaving the organization
+ * ends the grant with no cleanup.
+ */
+export const TEAM_MEMBERS_RELATION = "member";
+
 // ---------------------------------------------------------------------------
 // Byte-pinned copy (the cloud handlers' sentences, moved as-is).
 // ---------------------------------------------------------------------------
@@ -249,6 +264,35 @@ export function principalNotGrantableMessage(kind: string): string {
   return `Principal kind '${kind}' cannot be granted a role. Grantable principal kinds: [${grantable.join(", ")}]`;
 }
 
+/**
+ * A person principal carrying a relation qualifier (INVALID_ARGUMENT). A
+ * person is granted a role directly; `identity_account:<id>#<relation>`
+ * names no one, and OpenFGA would refuse the tuple after the row was
+ * written.
+ */
+export function personQualifierMessage(relation: string): string {
+  return `Principal kind 'identity_account' takes no relation; got '${relation}'`;
+}
+
+/** A team principal naming a relation other than its members (INVALID_ARGUMENT). */
+export function teamQualifierMessage(relation: string): string {
+  return `A team principal must name the relation '${TEAM_MEMBERS_RELATION}' (the team's members); got '${relation}'`;
+}
+
+/** A team grant on a kind that lists no team role (INVALID_ARGUMENT). */
+export function teamNotGrantableMessage(kind: string): string {
+  return `A team cannot be granted access to resource kind '${kind}'.`;
+}
+
+/** A team grant of a role the kind does not let a team hold (INVALID_ARGUMENT); the list in kind_meta order. */
+export function teamRoleNotGrantableMessage(
+  role: string,
+  kind: string,
+  grantable: ReadonlyArray<string>,
+): string {
+  return `Role '${role}' cannot be granted to a team on resource kind '${kind}'. Roles a team can hold: [${grantable.join(", ")}]`;
+}
+
 /** A triple field holding a canonical-text delimiter (INVALID_ARGUMENT; Q-S2-1). */
 export function malformedTripleMessage(field: string): string {
   return `policy ${field} must not contain ':', '#' or '@'`;

package/src/domain/iampolicy/controller.ts

@@ -31,9 +31,11 @@
  *     triple — strictly safer than the cloud's silent default instance.
  *   - `create` validates the role BEFORE it writes (the cloud's order): a
  *     held row under a role the kind does not grant is refused, never
- *     answered as a duplicate. It also grants to PEOPLE only (Q-S9-2,
- *     2026-09-14): a principal that is not an identity account is
- *     INVALID_ARGUMENT — a row naming a resource as its principal is the
+ *     answered as a duplicate. It also grants to PEOPLE and TEAMS only
+ *     (Q-S9-2, 2026-09-14): any other principal is INVALID_ARGUMENT, and a
+ *     team only on the roles its kind lets a team hold (steps.ts) and,
+ *     where an edition serves teams, only a team the create gate slot
+ *     admits — a row naming a resource as its principal is the
  *     structural link the hierarchy walk follows, `bootstrapPolicy`'s to
  *     write, and through this lane would have let a right on one
  *     organization list another's members. The cloud's create had the
@@ -136,9 +138,12 @@ import type { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/serve
 import type { Logger } from "../../boot/logger.js";
 import type { AuthorizationQueryEngine } from "../../extensions/authorization-queries.js";
 import type { Authorizer } from "../../extensions/authorizer.js";
+import { stepsForSlot } from "../../extensions/gate-slots.js";
+import type { ResolvedGateSteps } from "../../extensions/gate-slots.js";
 import { isPlatformPipelineCaller } from "../../extensions/identity.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
 import type { PolicyGrantScope } from "../../extensions/policy-grant-scope.js";
+import type { PrincipalDisplay } from "../../extensions/principal-display.js";
 import {
   kindByEnumName,
   kindEnumName,
@@ -209,6 +214,10 @@ export interface IamPolicyControllerDeps {
   readonly grantScope: PolicyGrantScope;
   /** The composed query engine — undefined = the tuple-half RPCs refuse UNIMPLEMENTED. */
   readonly queries: AuthorizationQueryEngine | undefined;
+  /** The composed principal display — undefined = a non-person grantee renders in the id fallback shape. */
+  readonly principalDisplay: PrincipalDisplay | undefined;
+  /** The merged gate steps; `create` splices `iam-policy-create:pre-side-effect-gate`. */
+  readonly gateSteps: ResolvedGateSteps;
   /** The served edition — `checkMyPermission`'s first arm reads a kind's tier against it. */
   readonly edition: ServerEdition;
   readonly logger: Logger;
@@ -285,7 +294,10 @@ function guardSystemRpc(method: DescMethod, caller: CallerIdentity): void {
 // The command chains
 // ---------------------------------------------------------------------------
 
-/** `create`: the wire refusal, then Authorize → ValidateProto → ValidateGrantableRole → Grant. */
+/**
+ * `create`: the wire refusal, then Authorize → ValidateProto →
+ * ValidateGrantableRole → [iam-policy-create:pre-side-effect-gate] → Grant.
+ */
 function createPolicy(
   deps: IamPolicyControllerDeps,
   spec: IamPolicySpec,
@@ -303,8 +315,8 @@ function createPolicy(
 
 /**
  * The grant chain both `create` and `bootstrapPolicy` run; only the user
- * lane validates the role — bootstrap writes structural relations no
- * scope would admit.
+ * lane validates the role and runs the create gate slot — bootstrap writes
+ * structural relations no scope would admit and no edition gates.
  */
 async function grantThroughChain(
   deps: IamPolicyControllerDeps,
@@ -327,6 +339,12 @@ async function grantThroughChain(
     .addStep(newValidateProtoStep());
   if (validateRole) {
     pipeline.addStep(newValidateGrantableRoleStep(deps.grantScope));
+    for (const step of stepsForSlot<typeof IamPolicySpecSchema>(
+      deps.gateSteps,
+      "iam-policy-create:pre-side-effect-gate",
+    )) {
+      pipeline.addStep(step);
+    }
   }
   await pipeline.addStep(newGrantStep(deps.grantPath)).build().execute(reqCtx);
   return policyResultOf(reqCtx, method);
@@ -600,7 +618,12 @@ async function listResourceAccessByPrincipal(
       resource.id,
       input.includeInherited,
     );
-    return buildPrincipalAccessList(deps.policies, displayResolver, hierarchy);
+    return buildPrincipalAccessList(
+      deps.policies,
+      displayResolver,
+      deps.principalDisplay,
+      hierarchy,
+    );
   }, "failed to list resource access");
   return create(ResourceAccessByPrincipalListSchema, {
     entries: [...entries],

package/src/domain/iampolicy/resource-store.ts

@@ -54,13 +54,10 @@ const KIND = ApiResourceKind.iam_policy;
  * principal half is derived from the user lane's grantee vocabulary
  * (constants.ts USER_GRANT_PRINCIPAL_KINDS; Q-S9-2) so the writer's "who a
  * person may grant to" and the reader's "what is a person, not a parent"
- * are one definition; `team` stays for the cloud's Java-era rows (not an
- * ApiResourceKind, so no wire spec names it).
+ * are one definition: the identity account and the team.
  */
-const NON_STRUCTURAL_PRINCIPAL_KINDS: ReadonlyArray<string> = [
-  ...USER_GRANT_PRINCIPAL_KINDS.map((kind) => kindEnumName(kind)),
-  "team",
-];
+const NON_STRUCTURAL_PRINCIPAL_KINDS: ReadonlyArray<string> =
+  USER_GRANT_PRINCIPAL_KINDS.map((kind) => kindEnumName(kind));
 const NON_STRUCTURAL_RELATIONS: ReadonlyArray<string> = ["owner", "creator"];
 
 export function newResourceIamPolicyStore(store: Store): IamPolicyStore {

package/src/domain/iampolicy/steps.ts

@@ -30,17 +30,32 @@
  *      intersection — the cloud's second copy listing it. Intersecting is
  *      what keeps a scope from WIDENING the contract by accident;
  *   5. the PRINCIPAL (Q-S9-2, 2026-09-14; constants.ts
- *      USER_GRANT_PRINCIPAL_KINDS): a person grants roles to people — the
- *      identity account — and to nothing else. A row whose principal is a
+ *      USER_GRANT_PRINCIPAL_KINDS): a person grants roles to people and to
+ *      teams of people, and to nothing else. A row whose principal is a
  *      resource is a structural link (the hierarchy walk's parent edge),
  *      which is `bootstrapPolicy`'s to write; through this lane it would
  *      let a right on one organization read another's members. Last, so
  *      every answer the cloud's create gives today is unchanged and only
- *      the row it should never have written is refused.
+ *      the row it should never have written is refused. A person names no
+ *      relation qualifier: `identity_account:<id>#<anything>` names
+ *      nobody, and OpenFGA would refuse the tuple after the row was
+ *      written, a grant on paper that is denied in practice.
+ *
+ * A TEAM principal takes its own list in place of arm 4: the kind's
+ * `team_grantable_roles` ∩ scope, never the person list, because a team
+ * is granted only what its members could each be granted and never
+ * ownership. It must name the team's members (`TEAM_MEMBERS_RELATION`).
+ * A kind that lists no team role refuses a team whatever the role, so
+ * open source (organization-only scope, and `organization` lists none)
+ * grants a team nothing without a branch of its own. Whether the team
+ * exists and belongs to the resource's organization needs a read, which
+ * this synchronous step does not make: that is the
+ * `iam-policy-create:pre-side-effect-gate` slot's, spliced after it.
  */
 import { create } from "@bufbuild/protobuf";
 import { Code, ConnectError } from "@connectrpc/connect";
 
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 import type { RevokeOrgAccessInputSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
 import type {
@@ -51,15 +66,23 @@ import type {
 import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import type { PolicyGrantScope } from "../../extensions/policy-grant-scope.js";
-import { grantableRolesFor } from "../../pipeline/apiresource-meta.js";
+import {
+  grantableRolesFor,
+  kindEnumName,
+  teamGrantableRolesFor,
+} from "../../pipeline/apiresource-meta.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import type { RequestContext } from "../../pipeline/request-context.js";
 import {
   PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE,
-  USER_GRANT_PRINCIPAL_KINDS,
+  TEAM_MEMBERS_RELATION,
   noGrantableRolesMessage,
+  personQualifierMessage,
   principalNotGrantableMessage,
   roleNotGrantableMessage,
+  teamNotGrantableMessage,
+  teamQualifierMessage,
+  teamRoleNotGrantableMessage,
 } from "./constants.js";
 import type { IamPolicyGrantPath } from "./grant-path.js";
 import {
@@ -94,6 +117,17 @@ export function newValidateGrantableRoleStep(
           Code.Unimplemented,
         );
       }
+      const principal = spec.principal;
+      if (principal?.kind === TEAM_KIND_NAME) {
+        requireTeamGrant(
+          spec.relation,
+          principal.relation,
+          kind,
+          kindName,
+          scoped,
+        );
+        return;
+      }
       const grantable = contract.filter((role) => scoped.has(role));
       if (!grantable.some((role) => IamRole[role] === spec.relation)) {
         throw new ConnectError(
@@ -105,18 +139,66 @@ export function newValidateGrantableRoleStep(
           Code.InvalidArgument,
         );
       }
-      const principalKindName = spec.principal?.kind ?? "";
+      const principalKindName = principal?.kind ?? "";
       const principalKind = requireKnownPrincipalKind(principalKindName);
-      if (!USER_GRANT_PRINCIPAL_KINDS.includes(principalKind)) {
+      if (principalKind !== ApiResourceKind.identity_account) {
         throw new ConnectError(
           principalNotGrantableMessage(principalKindName),
           Code.InvalidArgument,
         );
       }
+      const qualifier = principal?.relation ?? "";
+      if (qualifier !== "") {
+        throw new ConnectError(
+          personQualifierMessage(qualifier),
+          Code.InvalidArgument,
+        );
+      }
     },
   };
 }
 
+/** The wire name of the team kind, as an `ApiResourceRef.kind` carries it. */
+const TEAM_KIND_NAME = kindEnumName(ApiResourceKind.team);
+
+/**
+ * The team arm of ValidateGrantableRole (the module header): the role
+ * against the kind's team list narrowed by the scope, then the qualifier.
+ */
+function requireTeamGrant(
+  role: string,
+  qualifier: string,
+  kind: ApiResourceKind,
+  kindName: string,
+  scoped: ReadonlySet<IamRole>,
+): void {
+  const teamGrantable = teamGrantableRolesFor(kind).filter((r) =>
+    scoped.has(r),
+  );
+  if (teamGrantable.length === 0) {
+    throw new ConnectError(
+      teamNotGrantableMessage(kindName),
+      Code.InvalidArgument,
+    );
+  }
+  if (!teamGrantable.some((r) => IamRole[r] === role)) {
+    throw new ConnectError(
+      teamRoleNotGrantableMessage(
+        role,
+        kindName,
+        teamGrantable.map((r) => IamRole[r]),
+      ),
+      Code.InvalidArgument,
+    );
+  }
+  if (qualifier !== TEAM_MEMBERS_RELATION) {
+    throw new ConnectError(
+      teamQualifierMessage(qualifier),
+      Code.InvalidArgument,
+    );
+  }
+}
+
 /** Grant the spec as the chain's caller; the row (fresh or held) is the result. */
 export function newGrantStep(
   grantPath: IamPolicyGrantPath,

package/src/domain/session/list-index.ts

@@ -0,0 +1,28 @@
+/**
+ * The session list index (store/list-index.ts): `agent_instance` is the
+ * key `listByAgentInstance` reads, `channel` the one `listByChannel` reads
+ * (the channel's id is stamped as a label by the channel lanes, not held
+ * in the spec). A session belongs to one organization, which is every
+ * declaration's first fact, so `session.list` narrows by it when the
+ * request names one.
+ *
+ * A change to `keys` bumps `revision` (boot/__tests__/list-indexes.test.ts
+ * pins the pair).
+ */
+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 { declareListIndex, field, label } from "../../store/list-index.js";
+
+/** The label the channel lanes stamp on every session they open. */
+export const SESSION_CHANNEL_ID_LABEL = "stigmer.ai/channel-id";
+
+export const sessionListIndex = declareListIndex({
+  kind: ApiResourceKind.session,
+  schema: SessionSchema,
+  revision: 1,
+  keys: {
+    agent_instance: field("spec.agent_instance_id"),
+    channel: label(SESSION_CHANNEL_ID_LABEL),
+  },
+});