@stigmer/server 3.40.1 → 3.41.0

package/src/domain/iampolicy/grant-path.ts

@@ -46,6 +46,52 @@
  * `cleanupResource` and `revokeOrgAccess` take refs and ids their callers
  * read from rows, so they do not refuse.
  *
+ * Leaving an organization. The model bounds every direct grant on an
+ * organization-scoped object by the organization (`[identity_account]
+ * and affiliated from organization`, fga/model/tenancy/organization.fga),
+ * so a person with no role left in an organization reaches nothing in it
+ * on the next check. This path keeps the ROWS truthful to that: when a
+ * revoke leaves an account with no row on an organization, it revokes the
+ * rows the account holds on that organization's resources (a share, a
+ * team membership, an owner granted by someone else), each through the
+ * revoke order, so a departed person is listed nowhere and a return does
+ * not bring the shares back. It keeps AUTHORSHIP: an `owner` or `creator`
+ * row whose principal is the resource's recorded creator, exactly the
+ * tuple open source derives from the creator stamp instead of storing it
+ * (authorization/derived-tuples.ts), so both editions keep the same fact
+ * and the model's bound governs it in both. `revokeOrgAccess` always
+ * sweeps, so a retry after a crash mid-sweep converges; `revokeBySpec`
+ * sweeps when the row it revoked was the account's last on that
+ * organization; `cleanupResource` never sweeps (an organization's or an
+ * account's delete, where the bound already leaves every row inert and a
+ * sweep per member would add failure points to a delete that stops on
+ * the first fault). A resource's organization is read from the scope
+ * links the rows hold (`resolveHierarchy`); open source writes none and
+ * grants nothing below the organization (grant-scope.ts), so there the
+ * sweep finds nothing to do.
+ *
+ * Affiliation. The model's bound reads `organization#affiliated`, a stored
+ * relation that stands exactly while the person holds a row on the
+ * organization. This path is the one writer of those rows, so it announces
+ * every change of them through the lifecycle and never decides the answer
+ * itself: `onOrganizationAffiliationChanging` before a row naming an
+ * account on an organization is deleted (the driver removes the tuple
+ * first, fail-closed), `onOrganizationAffiliationChanged` after such a row
+ * is written or deleted (the driver re-derives the tuple from the committed
+ * rows). `affiliated` itself is refused as a grant on every lane; it is
+ * derived, never granted.
+ *
+ * Who and why. Every method takes the caller, and the grants take the door
+ * they came through (change.ts `PolicyChangeCause`); the revokes know
+ * theirs. For every access row it writes or deletes, the path hands the
+ * store a change record (the actor, the cause, the row's organization), so
+ * an edition that keeps a permission history writes it in the same atomic
+ * unit as the row (store.ts). The organization is resolved before any row
+ * of the operation is deleted: `cleanupResource` removes a resource's
+ * scope link before its owner rows, and the sweep already knows its
+ * organization. The grant and revoke log lines carry the same facts, open
+ * source's own trail.
+ *
  * The row this path builds: the proto's apiVersion const and kind, the
  * derived id, the spec as given, and the caller's audit stamp through the
  * platform's one stamper (setAuditFieldsForCreate) — the cloud's
@@ -54,6 +100,7 @@
  * span organizations and none owns 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 { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
@@ -67,14 +114,25 @@ import type {
 
 import type { Logger } from "../../boot/logger.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
-import type { ResourceAuthorizationLifecycle } from "../../extensions/resource-authorization.js";
+import type {
+  OrganizationAffiliationEvent,
+  ResourceAuthorizationLifecycle,
+} from "../../extensions/resource-authorization.js";
 import { kindEnumName } from "../../pipeline/apiresource-meta.js";
 import { setAuditFieldsForCreate } from "../../pipeline/steps/defaults.js";
 import {
+  AFFILIATION_NOT_GRANTABLE_MESSAGE,
   IAM_POLICY_API_VERSION,
   IAM_POLICY_KIND,
   policyIdFor,
 } from "./constants.js";
+import { resolveHierarchy } from "./access-lists.js";
+import { grantsAccess, policyActorOf } from "./change.js";
+import type {
+  PolicyActor,
+  PolicyChangeCause,
+  PolicyChangeRecord,
+} from "./change.js";
 import { DuplicatePolicyError } from "./store.js";
 import type { IamPolicyStore } from "./store.js";
 import { refsOf, requireWellFormedTriple } from "./wire-refusals.js";
@@ -82,6 +140,45 @@ import { refsOf, requireWellFormedTriple } from "./wire-refusals.js";
 /** The relation `cleanupResource` revokes last on the ref's own rows. */
 const OWNER_RELATION = IamRole[IamRole.owner];
 
+const ACCOUNT_KIND = kindEnumName(ApiResourceKind.identity_account);
+const ORGANIZATION_KIND = kindEnumName(ApiResourceKind.organization);
+
+/** The organization relation derived from a person's roles (fga/model/tenancy/organization.fga). */
+const AFFILIATED_RELATION = "affiliated";
+
+/**
+ * The (account, organization) pair a row's affiliation hangs on, or
+ * undefined when the row is not a person's row on an organization (a
+ * structural link, a userset principal, a row on any other kind).
+ */
+function affiliationOf(
+  spec: IamPolicySpec,
+): OrganizationAffiliationEvent | undefined {
+  const principal = spec.principal;
+  const resource = spec.resource;
+  if (
+    principal === undefined ||
+    resource === undefined ||
+    principal.kind !== ACCOUNT_KIND ||
+    principal.relation !== "" ||
+    resource.kind !== ORGANIZATION_KIND
+  ) {
+    return undefined;
+  }
+  return { identityAccountId: principal.id, organizationId: resource.id };
+}
+
+/**
+ * The relations a resource's creation records for its creator: `owner`
+ * on a kind whose owner is its creator, `creator` on a kind that also
+ * records one (the proto's `requires_creator_tuple`). The removal sweep
+ * keeps these when they name the resource's recorded creator.
+ */
+const AUTHORSHIP_RELATIONS: ReadonlySet<string> = new Set([
+  OWNER_RELATION,
+  "creator",
+]);
+
 export interface GrantResult {
   readonly policy: IamPolicy;
   /** True when the triple was already held: no row was written, the hook still fired. */
@@ -90,18 +187,26 @@ export interface GrantResult {
 
 export interface IamPolicyGrantPath {
   /**
-   * Grant the triple as `caller`: gate, find by triple, write the row when
-   * absent (the caller's audit stamp), then `onPolicyGranted` — on the
-   * duplicate arm too. A hook throw fails the grant with the row in place.
+   * Grant the triple as `caller`, through the door `cause` names: gate,
+   * find by triple, write the row when absent (the caller's audit stamp),
+   * then `onPolicyGranted` — on the duplicate arm too. A hook throw fails
+   * the grant with the row in place.
    */
-  grant(spec: IamPolicySpec, caller: CallerIdentity): Promise<GrantResult>;
+  grant(
+    spec: IamPolicySpec,
+    caller: CallerIdentity,
+    cause: PolicyChangeCause,
+  ): Promise<GrantResult>;
   /**
-   * Revoke the triple: gate, find by triple, `onPolicyRevoked` (with the
-   * row, or with the spec alone on the absent arm), then delete the row.
-   * A hook throw leaves row and tuple. Answers the revoked row, or
-   * `undefined` when there was none.
+   * Revoke the triple as `caller` (IamPolicy.delete's door): gate, find by
+   * triple, `onPolicyRevoked` (with the row, or with the spec alone on the
+   * absent arm), then delete the row. A hook throw leaves row and tuple.
+   * Answers the revoked row, or `undefined` when there was none.
    */
-  revokeBySpec(spec: IamPolicySpec): Promise<IamPolicy | undefined>;
+  revokeBySpec(
+    spec: IamPolicySpec,
+    caller: CallerIdentity,
+  ): Promise<IamPolicy | undefined>;
   /**
    * Revoke every row naming the ref as its principal, then every row naming
    * it as its resource with the `owner` rows last, each through the revoke
@@ -109,27 +214,88 @@ export interface IamPolicyGrantPath {
    * The order matters where the ref still exists: an organization's delete
    * runs this before its row goes and fails on the first fault, so a
    * cleanup that stops partway has not yet removed the owners who may
-   * retry it.
+   * retry it. `caller` is whoever deleted the resource.
+   */
+  cleanupResource(ref: ApiResourceRef, caller: CallerIdentity): Promise<void>;
+  /**
+   * Revoke every relation the account holds directly on the organization,
+   * then every row it holds on the organization's resources except its
+   * authorship (the module header's sweep), as `caller`.
    */
-  cleanupResource(ref: ApiResourceRef): Promise<void>;
-  /** Revoke every relation the account holds directly on the organization. */
   revokeOrgAccess(
     identityAccountId: string,
     organizationId: string,
+    caller: CallerIdentity,
   ): Promise<void>;
 }
 
+/**
+ * The recorded creator of a stored resource, the one fact the removal
+ * sweep needs from outside the policy rows.
+ */
+export interface ResourceCreators {
+  /**
+   * The row's `status.audit.spec_audit.created_by.id`, or undefined when
+   * this server stores no row of that kind and id.
+   */
+  creatorOf(kind: string, id: string): Promise<string | undefined>;
+}
+
 export interface IamPolicyGrantPathDeps {
   readonly policies: IamPolicyStore;
+  readonly creators: ResourceCreators;
   /** The composed driver, if any; a driver without the two policy hooks is the same as none. */
   readonly lifecycle: ResourceAuthorizationLifecycle | undefined;
   readonly logger: Logger;
 }
 
+/** Who made a change and through which door; the organization is resolved per row. */
+interface Change {
+  readonly actor: PolicyActor;
+  readonly cause: PolicyChangeCause;
+}
+
+/** How a row's organization is found: the scope walk, or a value its operation already knows. */
+type OrganizationOf = (resource: ApiResourceRef) => Promise<string>;
+
 export function newIamPolicyGrantPath(
   deps: IamPolicyGrantPathDeps,
 ): IamPolicyGrantPath {
-  const { policies, lifecycle, logger } = deps;
+  const { policies, creators, lifecycle, logger } = deps;
+
+  /** The organization a resource belongs to, through its scope links; "" when it names none. */
+  async function organizationByScope(
+    resource: ApiResourceRef,
+  ): Promise<string> {
+    if (resource.kind === ORGANIZATION_KIND) {
+      return resource.id;
+    }
+    const hierarchy = await resolveHierarchy(
+      policies,
+      resource.kind,
+      resource.id,
+      true,
+    );
+    return (
+      hierarchy.find((level) => level.kind === ORGANIZATION_KIND)?.id ?? ""
+    );
+  }
+
+  /** The record the store keeps beside an access row; none for a structural link. */
+  async function recordFor(
+    spec: IamPolicySpec,
+    change: Change,
+    organizationOf: OrganizationOf,
+  ): Promise<PolicyChangeRecord | undefined> {
+    if (spec.resource === undefined || !grantsAccess(spec)) {
+      return undefined;
+    }
+    return {
+      actor: change.actor,
+      cause: change.cause,
+      organizationId: await organizationOf(spec.resource),
+    };
+  }
 
   /** The row holding this exact triple — the pair's rows, filtered by relation. */
   async function findByTriple(
@@ -150,31 +316,129 @@ export function newIamPolicyGrantPath(
     );
   }
 
-  /** The revoke order for one row: the hook, then the delete. */
-  async function revokeRow(policy: IamPolicy): Promise<void> {
+  /** The revoke order for one row: its record resolved, the hook, then the delete. */
+  async function revokeRow(
+    policy: IamPolicy,
+    change: Change,
+    organizationOf: OrganizationOf = organizationByScope,
+  ): Promise<void> {
     const spec = policy.spec;
     if (spec === undefined) {
       throw new Error(
         `policy ${policy.metadata?.id ?? "?"} has no spec — corrupt row`,
       );
     }
+    const record = await recordFor(spec, change, organizationOf);
+    const affiliation = affiliationOf(spec);
+    if (affiliation !== undefined) {
+      await lifecycle?.onOrganizationAffiliationChanging?.(affiliation);
+    }
     await lifecycle?.onPolicyRevoked?.({ spec, policy });
     const id = policy.metadata?.id ?? "";
-    await policies.deleteById(id);
-    logger.info("iam policy revoked", fieldsOf(id, spec));
+    await policies.deleteById(id, record);
+    logger.info("iam policy revoked", fieldsOf(id, spec, change, record));
+    if (affiliation !== undefined) {
+      await lifecycle?.onOrganizationAffiliationChanged?.(affiliation);
+    }
+  }
+
+  /** Whether the account still holds any row on the organization. */
+  async function holdsOrganizationRow(
+    accountId: string,
+    organizationId: string,
+  ): Promise<boolean> {
+    const held = await policies.findByPrincipal(ACCOUNT_KIND, accountId);
+    return held.some(
+      (policy) =>
+        policy.spec?.resource?.kind === ORGANIZATION_KIND &&
+        policy.spec.resource.id === organizationId,
+    );
+  }
+
+  /** Whether the row records the resource's creator as its author. */
+  async function isAuthorship(
+    policy: IamPolicy,
+    accountId: string,
+  ): Promise<boolean> {
+    const spec = policy.spec;
+    if (
+      spec?.resource === undefined ||
+      !AUTHORSHIP_RELATIONS.has(spec.relation)
+    ) {
+      return false;
+    }
+    const creator = await creators.creatorOf(
+      spec.resource.kind,
+      spec.resource.id,
+    );
+    return creator === accountId;
+  }
+
+  /** Revoke what the account holds on the organization's resources, authorship kept. */
+  async function sweepOrganization(
+    accountId: string,
+    organizationId: string,
+    actor: PolicyActor,
+  ): Promise<void> {
+    const change: Change = { actor, cause: "left_organization" };
+    const inThisOrganization: OrganizationOf = async () => organizationId;
+    const held = await policies.findByPrincipal(ACCOUNT_KIND, accountId);
+    let revoked = 0;
+    for (const policy of held) {
+      const resource = policy.spec?.resource;
+      if (resource === undefined || resource.kind === ORGANIZATION_KIND) {
+        continue;
+      }
+      const hierarchy = await resolveHierarchy(
+        policies,
+        resource.kind,
+        resource.id,
+        true,
+      );
+      const inOrganization = hierarchy.some(
+        (level) =>
+          level.kind === ORGANIZATION_KIND && level.id === organizationId,
+      );
+      if (!inOrganization || (await isAuthorship(policy, accountId))) {
+        continue;
+      }
+      await revokeRow(policy, change, inThisOrganization);
+      revoked++;
+    }
+    if (revoked > 0) {
+      logger.info("iam policy organization access swept", {
+        identityAccountId: accountId,
+        organizationId,
+        revoked: String(revoked),
+      });
+    }
   }
 
   return {
-    async grant(spec, caller): Promise<GrantResult> {
+    async grant(spec, caller, cause): Promise<GrantResult> {
       requireWellFormedTriple(spec);
+      const change: Change = { actor: policyActorOf(caller), cause };
+      if (
+        spec.relation === AFFILIATED_RELATION &&
+        spec.resource?.kind === ORGANIZATION_KIND
+      ) {
+        throw new ConnectError(
+          AFFILIATION_NOT_GRANTABLE_MESSAGE,
+          Code.InvalidArgument,
+        );
+      }
       let policy = await findByTriple(spec);
       let duplicate = policy !== undefined;
       if (policy === undefined) {
         const fresh = buildRow(spec, caller);
+        const record = await recordFor(spec, change, organizationByScope);
         try {
-          await policies.save(fresh);
+          await policies.save(fresh, record);
           policy = fresh;
-          logger.info("iam policy granted", fieldsOf(policyIdFor(spec), spec));
+          logger.info(
+            "iam policy granted",
+            fieldsOf(policyIdFor(spec), spec, change, record),
+          );
         } catch (error) {
           if (!(error instanceof DuplicatePolicyError)) {
             throw error;
@@ -194,31 +458,66 @@ export function newIamPolicyGrantPath(
       if (duplicate) {
         logger.debug(
           "iam policy already held",
-          fieldsOf(policy.metadata?.id ?? "", spec),
+          fieldsOf(policy.metadata?.id ?? "", spec, change, undefined),
         );
       }
       // Deliberately unconditional (cloud#425): a duplicate re-grant is the
       // inline heal for a row whose tuple never landed.
       await lifecycle?.onPolicyGranted?.({ policy, duplicate });
+      // The same unconditional heal for the affiliation the row stands for.
+      const affiliation = affiliationOf(spec);
+      if (affiliation !== undefined) {
+        await lifecycle?.onOrganizationAffiliationChanged?.(affiliation);
+      }
       return { policy, duplicate };
     },
 
-    async revokeBySpec(spec): Promise<IamPolicy | undefined> {
+    async revokeBySpec(spec, caller): Promise<IamPolicy | undefined> {
       requireWellFormedTriple(spec);
+      const actor = policyActorOf(caller);
       const existing = await findByTriple(spec);
       if (existing === undefined) {
         // No row: a composition still deletes the bare tuple (one written
         // before the row mirror existed); converges the store either way.
         await lifecycle?.onPolicyRevoked?.({ spec, policy: undefined });
-        return undefined;
+        const affiliation = affiliationOf(spec);
+        if (affiliation !== undefined) {
+          // Nothing was deleted; re-deriving from the rows heals a tuple
+          // that outlived them.
+          await lifecycle?.onOrganizationAffiliationChanged?.(affiliation);
+        }
+      } else {
+        await revokeRow(existing, { actor, cause: "revoke" });
+      }
+      const { principal, resource } = refsOf(spec);
+      if (
+        principal.kind === ACCOUNT_KIND &&
+        resource.kind === ORGANIZATION_KIND &&
+        !(await holdsOrganizationRow(principal.id, resource.id))
+      ) {
+        await sweepOrganization(principal.id, resource.id, actor);
       }
-      await revokeRow(existing);
       return existing;
     },
 
-    async cleanupResource(ref): Promise<void> {
+    async cleanupResource(ref, caller): Promise<void> {
+      const change: Change = {
+        actor: policyActorOf(caller),
+        cause: "resource_deleted",
+      };
       const asPrincipal = await policies.findByPrincipal(ref.kind, ref.id);
       const asResource = await policies.findByResource(ref.kind, ref.id);
+      // The ref's own scope link is one of its resource-side rows and goes
+      // before its owners, so its organization is read once, up front.
+      const refOrganization = asResource.some(
+        (policy) => policy.spec !== undefined && grantsAccess(policy.spec),
+      )
+        ? await organizationByScope(ref)
+        : "";
+      const organizationOf: OrganizationOf = async (resource) =>
+        resource.kind === ref.kind && resource.id === ref.id
+          ? refOrganization
+          : organizationByScope(resource);
       const isOwner = (policy: IamPolicy): boolean =>
         policy.spec?.relation === OWNER_RELATION;
       for (const policy of distinctById([
@@ -226,11 +525,17 @@ export function newIamPolicyGrantPath(
         ...asResource.filter((policy) => !isOwner(policy)),
         ...asResource.filter(isOwner),
       ])) {
-        await revokeRow(policy);
+        await revokeRow(policy, change, organizationOf);
       }
     },
 
-    async revokeOrgAccess(identityAccountId, organizationId): Promise<void> {
+    async revokeOrgAccess(
+      identityAccountId,
+      organizationId,
+      caller,
+    ): Promise<void> {
+      const actor = policyActorOf(caller);
+      const change: Change = { actor, cause: "organization_access_revoked" };
       const direct = await policies.findByPrincipalAndResource(
         kindEnumName(ApiResourceKind.identity_account),
         identityAccountId,
@@ -238,8 +543,9 @@ export function newIamPolicyGrantPath(
         organizationId,
       );
       for (const policy of direct) {
-        await revokeRow(policy);
+        await revokeRow(policy, change);
       }
+      await sweepOrganization(identityAccountId, organizationId, actor);
     },
   };
 }
@@ -271,8 +577,16 @@ function distinctById(
   });
 }
 
-/** The structured fields every log line carries — ids and kinds, never a token. */
-function fieldsOf(id: string, spec: IamPolicySpec): Record<string, string> {
+/**
+ * The structured fields every log line carries — ids, kinds, who and why,
+ * never a token; the organization when the row is an access row.
+ */
+function fieldsOf(
+  id: string,
+  spec: IamPolicySpec,
+  change: Change,
+  record: PolicyChangeRecord | undefined,
+): Record<string, string> {
   return {
     policyId: id,
     relation: spec.relation,
@@ -280,5 +594,9 @@ function fieldsOf(id: string, spec: IamPolicySpec): Record<string, string> {
     principalId: spec.principal?.id ?? "",
     resourceKind: spec.resource?.kind ?? "",
     resourceId: spec.resource?.id ?? "",
+    actorId: change.actor.id,
+    actorClass: change.actor.callerClass,
+    cause: change.cause,
+    ...(record === undefined ? {} : { organizationId: record.organizationId }),
   };
 }

package/src/domain/iampolicy/membership.ts

@@ -59,8 +59,9 @@
  *   one of them would be an outsider on every organization with nobody
  *   able to grant a way back. At the first boot where the bootstrap-state
  *   marker (ROLES_RECONCILED_KEY) is absent, the arms above run for every
- *   PERSON account (`isPersonAccount`: not a machine account, the row-
- *   level twin of the `user`-class gate), acting as that account, in
+ *   PERSON account (`isPersonAccount`: not a machine, platform-client or
+ *   federated account, the row-level twin of the `user`-class gate),
+ *   acting as that account, in
  *   creation order — the order the sign-ins would have run the hook in,
  *   so arm 4 hands an unclaimed organization to its first sign-in and
  *   not to whoever sorts first by id — and the marker is written after
@@ -131,6 +132,7 @@ import type { Store } from "../../store/interface.js";
 import { rfc3339Seconds } from "../../store/rfc3339.js";
 import { accountAsCaller } from "../identityaccount/actor.js";
 import type { AccountCreatedHook } from "../identityaccount/provisioning.js";
+import type { PolicyChangeCause } from "./change.js";
 import { BLUEPRINT_KINDS, ROLES_RECONCILED_KEY } from "./constants.js";
 import type { IamPolicyGrantPath } from "./grant-path.js";
 import { organizationRole, relationOf } from "./specs.js";
@@ -200,7 +202,14 @@ export function isPersonStamp(stamp: string): boolean {
  * it exactly its client's auto-grant role on the owning organization and
  * never runs these rules, and the reconciliation must not either, or every
  * product user would become a member of every organization (and the
- * operator-email arm would read an email the platform asserted).
+ * operator-email arm would read an email the platform asserted). Nor does a
+ * federated account, for the same reason at every arm: its subject and its
+ * email are the ones an organization's identity provider asserted, so the
+ * alias rule would read a subject the provider chose as a founder's stamp
+ * (`owner`), the operator-email arm an email it chose (`admin`), and arm 5
+ * would make it a member of every organization. A federated person's roles
+ * come from their provider's configuration and the organization's
+ * administrators, never from these rules.
  */
 export function isPersonAccount(account: IdentityAccount): boolean {
   const spec = account.spec;
@@ -208,7 +217,8 @@ export function isPersonAccount(account: IdentityAccount): boolean {
     spec !== undefined &&
     !spec.isMachineAccount &&
     spec.provisioningMode !== IdentityAccountProvisioningMode.machine &&
-    spec.provisioningMode !== IdentityAccountProvisioningMode.platform_client
+    spec.provisioningMode !== IdentityAccountProvisioningMode.platform_client &&
+    spec.provisioningMode !== IdentityAccountProvisioningMode.federated
   );
 }
 
@@ -331,14 +341,15 @@ export function newMembershipRules(deps: MembershipRulesDeps): MembershipRules {
 
   /**
    * The arms for ONE account over a scanned world: a row on every
-   * organization the account holds none on, granted as `caller`. Shared
-   * by the hook (one account, the world scanned for it) and the
-   * reconciliation (the world scanned once for every account).
+   * organization the account holds none on, granted as `caller` through
+   * `cause`'s door. Shared by the hook (one account, the world scanned for
+   * it) and the reconciliation (the world scanned once for every account).
    */
   async function applyRulesTo(
     account: IdentityAccount,
     caller: CallerIdentity,
     world: ScannedWorld,
+    cause: PolicyChangeCause,
   ): Promise<void> {
     const accountId = account.metadata?.id ?? "";
     if (accountId === "") {
@@ -369,6 +380,7 @@ export function newMembershipRules(deps: MembershipRulesDeps): MembershipRules {
       await grantPath.grant(
         organizationRole(accountId, role, organization.id),
         caller,
+        cause,
       );
     }
   }
@@ -402,10 +414,12 @@ export function newMembershipRules(deps: MembershipRulesDeps): MembershipRules {
       if (organizations.length === 0) {
         return;
       }
-      await applyRulesTo(account, caller, {
-        organizations,
-        blueprints: await scanBlueprints(),
-      });
+      await applyRulesTo(
+        account,
+        caller,
+        { organizations, blueprints: await scanBlueprints() },
+        "first_sign_in",
+      );
     },
 
     async ensureRolesForExistingAccounts(): Promise<void> {
@@ -419,7 +433,12 @@ export function newMembershipRules(deps: MembershipRulesDeps): MembershipRules {
           // As the account itself (actor.ts, the one construction), so the
           // row's audit actor reads exactly as the person's own first
           // sign-in would have stamped it.
-          await applyRulesTo(account, accountAsCaller(account), world);
+          await applyRulesTo(
+            account,
+            accountAsCaller(account),
+            world,
+            "role_reconciliation",
+          );
         }
       }
       // After the last account, never before: a fault above leaves the
@@ -452,6 +471,7 @@ export function newMembershipRules(deps: MembershipRulesDeps): MembershipRules {
         await grantPath.grant(
           organizationRole(accountId, IamRole.owner, organization.id),
           actor,
+          "operator_ownership",
         );
       }
     },

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

@@ -32,6 +32,10 @@
  * way). Conditional store writes are a platform-wide follow-up, not this
  * adapter's to invent.
  *
+ * History. Open source keeps no permission history: the change record the
+ * grant path hands `save` and `deleteById` (store.ts) is not read here, and
+ * the same facts ride the grant path's log lines.
+ *
  * Store faults follow the ratified mapping (domain/apikey/lookup.ts): a
  * typed ResourceNotFoundError reads as `undefined`; anything else
  * propagates — an outage must never read as "no grant".

package/src/domain/iampolicy/role-lifecycle.ts

@@ -109,6 +109,7 @@ export function newBuiltInRoleLifecycle(
       await grantPath.grant(
         organizationRole(accountId, IamRole.owner, event.resourceId),
         { ...event.caller, identityId: accountId },
+        "organization_created",
       );
     },
 
@@ -121,6 +122,7 @@ export function newBuiltInRoleLifecycle(
           kind: kindEnumName(event.kind),
           id: event.resourceId,
         }),
+        event.caller,
       );
     },
 

package/src/domain/iampolicy/roles.ts

@@ -60,6 +60,14 @@ const ROLE_DISPLAY: ReadonlyArray<RoleDisplay> = [
     description:
       "Reply to customers and manage conversation takeover on a channel",
   },
+  // Grantable per resource on agent, workflow and mcp_server; omitting it
+  // would hide every editor from the resource's access listing.
+  {
+    role: IamRole.editor,
+    name: "Editor",
+    description:
+      "Edit and run the resource; cannot delete it or change who has access",
+  },
 ];
 
 const RELATION_TO_DISPLAY: ReadonlyMap<string, RoleDisplay> = new Map(