@stigmer/server 3.15.2 → 3.15.3-dev.20260914100347

package/src/domain/iampolicy/roles.ts

@@ -0,0 +1,95 @@
+/**
+ * IAM role metadata (20260913.01 slice 5): display metadata for the five
+ * assignable roles and the assignable-relation allowlist that keeps
+ * structural relations (parent links, runtime grants, observability
+ * usersets) out of every access listing BY CONSTRUCTION — reads filter to
+ * this set rather than maintaining a denylist a new structural relation
+ * could slip past. Moved as-is from the cloud's iam/policy/roles.ts, itself
+ * the port of Java's apishape/authorization/IamRoleMetadata; the cloud's
+ * `grantableRolesFor` did not come along — it lives in
+ * pipeline/apiresource-meta.ts as the contract's one read of
+ * `kind_meta.grantable_roles`, and the cloud registers its own reading of
+ * it as the `policyGrantScope` driver.
+ *
+ * The four words this table renders for an organization are the four
+ * roles every edition grants there (Q-OR-4) and the ladder entry 3's
+ * authorizer enforces; the copy is shown verbatim by the console's role
+ * badges and selector, so it is contract.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type { RoleInfo } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import { RoleInfoSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+/** Display metadata for one assignable role (the Java ROLE_INFO_MAP copy). */
+interface RoleDisplay {
+  readonly role: IamRole;
+  readonly name: string;
+  readonly description: string;
+}
+
+const ROLE_DISPLAY: ReadonlyArray<RoleDisplay> = [
+  {
+    role: IamRole.owner,
+    name: "Owner",
+    description: "Full control of the resource including ownership transfer",
+  },
+  {
+    role: IamRole.admin,
+    name: "Administrator",
+    description:
+      "Administrative access with most permissions except ownership transfer",
+  },
+  {
+    role: IamRole.member,
+    name: "Member",
+    description: "Read and limited write access to the resource",
+  },
+  {
+    role: IamRole.viewer,
+    name: "Viewer",
+    description: "Read-only access to the resource",
+  },
+  // Grantable on agent_channel only (channel-conversations DD-010);
+  // omitting it would let the grant succeed while hiding the participant
+  // from every access listing (the Java IamRoleMetadataTest lesson).
+  {
+    role: IamRole.participant,
+    name: "Participant",
+    description:
+      "Reply to customers and manage conversation takeover on a channel",
+  },
+];
+
+const RELATION_TO_DISPLAY: ReadonlyMap<string, RoleDisplay> = new Map(
+  ROLE_DISPLAY.map((entry) => [IamRole[entry.role], entry]),
+);
+
+/** The allowlist for access-listing queries (Java assignableRelations). */
+export function assignableRelations(): ReadonlyArray<string> {
+  return [...RELATION_TO_DISPLAY.keys()];
+}
+
+/** True when the relation names an assignable IAM role, never structural. */
+export function isAssignableRole(relation: string): boolean {
+  return RELATION_TO_DISPLAY.has(relation);
+}
+
+/**
+ * Relation string → RoleInfo with display metadata; the default instance
+ * for unknown relations (the Java fromRelationString contract).
+ */
+export function roleInfoFromRelation(relation: string): RoleInfo {
+  const display = RELATION_TO_DISPLAY.get(relation);
+  if (display === undefined) {
+    return create(RoleInfoSchema);
+  }
+  const code = IamRole[display.role];
+  return create(RoleInfoSchema, {
+    id: code,
+    code,
+    name: display.name,
+    description: display.description,
+  });
+}

package/src/domain/iampolicy/specs.ts

@@ -0,0 +1,53 @@
+/**
+ * The IamPolicy specs server code builds ITSELF, spelled once
+ * (20260913.01 slice 4). A wire caller hands the domain a spec; the
+ * built-in role lifecycle, the membership rules and slice 5's
+ * `revokeOrgAccess` and contextual `checkMyPermission` build their own.
+ * The derived policy id hashes the spec's exact text (constants.ts
+ * `policyIdFor`), so two spellings of one triple would be two rows — this
+ * module is where "identity_account:<id> holds <role> on
+ * organization:<org>" has one spelling in production code, the way the
+ * test support's `orgRole` is that spelling for tests.
+ *
+ * Kinds are spelled through `kindEnumName` (the ApiResourceRef vocabulary,
+ * pipeline/apiresource-meta.ts); relations are the `IamRole` member names,
+ * which are the FGA model's relation names and the proto's grantable-role
+ * vocabulary. The zero value `iam_role_unspecified` is not a relation and
+ * is refused (the `accountIdFor("")` precedent): hashing it would mint a
+ * real row for a role nobody holds.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import { IamPolicySpecSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+
+/** The relation string a role grants — the enum member's own name. */
+export function relationOf(role: IamRole): string {
+  if (role === IamRole.iam_role_unspecified) {
+    throw new Error("iam_role_unspecified is not a relation");
+  }
+  return IamRole[role];
+}
+
+/** `identity_account:<accountId>` holds `<role>` on `organization:<organizationId>` — the organization role. */
+export function organizationRole(
+  accountId: string,
+  role: IamRole,
+  organizationId: string,
+): IamPolicySpec {
+  return create(IamPolicySpecSchema, {
+    principal: {
+      kind: kindEnumName(ApiResourceKind.identity_account),
+      id: accountId,
+    },
+    relation: relationOf(role),
+    resource: {
+      kind: kindEnumName(ApiResourceKind.organization),
+      id: organizationId,
+    },
+  });
+}

package/src/domain/iampolicy/steps.ts

@@ -0,0 +1,178 @@
+/**
+ * IamPolicy pipeline steps (20260913.01 slice 5; Q-S5-1): the domain-local
+ * steps the six command chains splice after the shared `Authorize` and
+ * `ValidateProto`. The write itself is never here — every step that writes
+ * calls the ONE grant and revoke path (grant-path.ts, which owns the
+ * cloud#425 orderings, the by-triple read and the wire refusals) and leaves
+ * its answer under POLICY_RESULT_KEY for the handler. The chains are
+ * deliberately short: `Authorize → ValidateProto → <one of these>`, so the
+ * pipeline executor's fault mapping (a step's ConnectError keeps its code;
+ * a raw store fault becomes the sanitized INTERNAL) covers the path's two
+ * error shapes with no second idiom in the handlers.
+ *
+ * ValidateGrantableRole (the `create` chain only; `bootstrapPolicy` is the
+ * structural lane and skips it) is the one step with branching logic. It
+ * runs BEFORE Grant — the cloud's validate-before-write order, so a held
+ * legacy row under a role the kind does not grant is refused rather than
+ * answered as a duplicate — and reads, in this order (Q-OR-3 as refined;
+ * Q-S3-3):
+ *   1. the wire refusals: an unknown resource kind is `Unknown resource
+ *      kind`, never a role sentence — the second line behind the
+ *      controller's pre-position-1 refusal (Q-S6-1), kept so the step's
+ *      own contract holds for whoever splices it;
+ *   2. the PROTO (`grantableRolesFor`): a kind that lists no role is
+ *      system-managed in every edition — the cloud's byte-pinned copy,
+ *      whatever the composed scope claims;
+ *   3. the composed SCOPE: a kind it lists nothing for is a per-resource
+ *      grant this edition does not serve — UNIMPLEMENTED naming the
+ *      editions that do;
+ *   4. proto ∩ scope, in proto order: the role must be in the
+ *      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
+ *      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.
+ */
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+
+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 {
+  ApiResourceRef,
+  ApiResourceRefSchema,
+  IamPolicySpecSchema,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+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 type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import {
+  PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE,
+  USER_GRANT_PRINCIPAL_KINDS,
+  noGrantableRolesMessage,
+  principalNotGrantableMessage,
+  roleNotGrantableMessage,
+} from "./constants.js";
+import type { IamPolicyGrantPath } from "./grant-path.js";
+import {
+  requireKnownPrincipalKind,
+  requireKnownResourceKind,
+} from "./wire-refusals.js";
+
+/** The row a write chain answers — the granted row, or the revoked row (the default instance when there was none). */
+export const POLICY_RESULT_KEY = "policyResult";
+
+/** The `create` chain's role check; see the module header for the four arms. */
+export function newValidateGrantableRoleStep(
+  scope: PolicyGrantScope,
+): PipelineStep<typeof IamPolicySpecSchema> {
+  return {
+    name: "ValidateGrantableRole",
+    execute(ctx: RequestContext<typeof IamPolicySpecSchema>): void {
+      const spec = ctx.input;
+      const kindName = spec.resource?.kind ?? "";
+      const kind = requireKnownResourceKind(kindName);
+      const contract = grantableRolesFor(kind);
+      if (contract.length === 0) {
+        throw new ConnectError(
+          noGrantableRolesMessage(kindName),
+          Code.InvalidArgument,
+        );
+      }
+      const scoped = new Set(scope.grantableRoles(kind));
+      if (scoped.size === 0) {
+        throw new ConnectError(
+          PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE,
+          Code.Unimplemented,
+        );
+      }
+      const grantable = contract.filter((role) => scoped.has(role));
+      if (!grantable.some((role) => IamRole[role] === spec.relation)) {
+        throw new ConnectError(
+          roleNotGrantableMessage(
+            spec.relation,
+            kindName,
+            grantable.map((role) => IamRole[role]),
+          ),
+          Code.InvalidArgument,
+        );
+      }
+      const principalKindName = spec.principal?.kind ?? "";
+      const principalKind = requireKnownPrincipalKind(principalKindName);
+      if (!USER_GRANT_PRINCIPAL_KINDS.includes(principalKind)) {
+        throw new ConnectError(
+          principalNotGrantableMessage(principalKindName),
+          Code.InvalidArgument,
+        );
+      }
+    },
+  };
+}
+
+/** Grant the spec as the chain's caller; the row (fresh or held) is the result. */
+export function newGrantStep(
+  grantPath: IamPolicyGrantPath,
+): PipelineStep<typeof IamPolicySpecSchema> {
+  return {
+    name: "Grant",
+    async execute(
+      ctx: RequestContext<typeof IamPolicySpecSchema>,
+    ): Promise<void> {
+      const { policy } = await grantPath.grant(ctx.input, ctx.callerIdentity);
+      ctx.set(POLICY_RESULT_KEY, policy);
+    },
+  };
+}
+
+/** Revoke the spec's row; absent, the default instance is the result (Java's idempotent delete). */
+export function newRevokeStep(
+  grantPath: IamPolicyGrantPath,
+): PipelineStep<typeof IamPolicySpecSchema> {
+  return {
+    name: "Revoke",
+    async execute(
+      ctx: RequestContext<typeof IamPolicySpecSchema>,
+    ): Promise<void> {
+      const revoked = await grantPath.revokeBySpec(ctx.input);
+      ctx.set(POLICY_RESULT_KEY, revoked ?? create(IamPolicySchema));
+    },
+  };
+}
+
+/** Revoke every relation the account holds directly on the organization. */
+export function newRevokeOrgAccessStep(
+  grantPath: IamPolicyGrantPath,
+): PipelineStep<typeof RevokeOrgAccessInputSchema> {
+  return {
+    name: "RevokeOrgAccess",
+    execute(
+      ctx: RequestContext<typeof RevokeOrgAccessInputSchema>,
+    ): Promise<void> {
+      return grantPath.revokeOrgAccess(
+        ctx.input.identityAccountId,
+        ctx.input.organizationId,
+      );
+    },
+  };
+}
+
+/** Revoke every row naming the ref as resource or principal — the deleted resource's cleanup. */
+export function newCleanupResourceStep(
+  grantPath: IamPolicyGrantPath,
+): PipelineStep<typeof ApiResourceRefSchema> {
+  return {
+    name: "CleanupResource",
+    execute(ctx: RequestContext<typeof ApiResourceRefSchema>): Promise<void> {
+      const ref: ApiResourceRef = ctx.input;
+      return grantPath.cleanupResource(ref);
+    },
+  };
+}