@stigmer/server 3.40.1 → 3.41.0

package/src/domain/iampolicy/access-lists.ts

@@ -24,6 +24,17 @@
  * with the id standing in as the display name, the Java `enrich()`
  * fallback shape.
  *
+ * A resource's list names only people who belong to its organization.
+ * The model bounds every direct grant on an organization-scoped object by
+ * the organization (fga/model/tenancy/organization.fga `affiliated`), and
+ * the grant path revokes a departed person's shares, but it keeps their
+ * authorship row (grant-path.ts), which reaches nothing while they are
+ * away. A row that grants nothing is not access, so an account that holds
+ * no row on the resource's organization is left out of that resource's
+ * list, read from the same rows (one indexed `findByPrincipal` per listed
+ * account). An organization's own list is its roles and is never
+ * filtered.
+ *
  * Every entry names its grantee exactly as the rows hold it: kind, id AND
  * the relation qualifier (`team:<id>#member`), and entries group by all
  * three. A revoke matches the qualifier exactly (grant-path.ts
@@ -54,6 +65,9 @@ import {
 import { assignableRelations, roleInfoFromRelation } from "./roles.js";
 import type { IamPolicyStore } from "./store.js";
 
+const ACCOUNT_KIND = kindEnumName(ApiResourceKind.identity_account);
+const ORGANIZATION_KIND = kindEnumName(ApiResourceKind.organization);
+
 /** The Java resolver's bounds: ≤5 steps, platform terminates the walk. */
 const MAX_HIERARCHY_DEPTH = 5;
 const TERMINAL_KINDS: ReadonlySet<string> = new Set([
@@ -141,9 +155,21 @@ export async function buildPrincipalAccessList(
   if (grants.length === 0) {
     return [];
   }
+  const departed = await accountsOutsideOrganization(
+    policies,
+    hierarchy,
+    grants.map((grant) => grant.policy),
+  );
+  const current = grants.filter((grant) => {
+    const principal = grant.policy.spec?.principal;
+    return !(principal?.kind === ACCOUNT_KIND && departed.has(principal.id));
+  });
+  if (current.length === 0) {
+    return [];
+  }
 
   const enriched = await resolvePrincipalViews(
-    grants.map((g) => g.policy),
+    current.map((g) => g.policy),
     displayResolver,
     principalDisplay,
   );
@@ -152,7 +178,7 @@ export async function buildPrincipalAccessList(
     string,
     { principal: ApiResourceRefView; roles: RoleGrant[] }
   >();
-  for (const grant of grants) {
+  for (const grant of current) {
     const principal = grant.policy.spec?.principal;
     if (principal === undefined) {
       continue;
@@ -190,6 +216,48 @@ export async function buildPrincipalAccessList(
   );
 }
 
+/**
+ * The accounts among the rows that hold no row on the resource's
+ * organization (the module header's rule). Empty for an organization's own
+ * list and for a resource no organization holds.
+ */
+async function accountsOutsideOrganization(
+  policies: IamPolicyStore,
+  hierarchy: ReadonlyArray<HierarchyLevel>,
+  rows: ReadonlyArray<IamPolicy>,
+): Promise<ReadonlySet<string>> {
+  const resource = hierarchy[0];
+  if (resource === undefined || resource.kind === ORGANIZATION_KIND) {
+    return new Set();
+  }
+  const levels = hierarchy.some((level) => level.kind === ORGANIZATION_KIND)
+    ? hierarchy
+    : await resolveHierarchy(policies, resource.kind, resource.id, true);
+  const organization = levels.find((level) => level.kind === ORGANIZATION_KIND);
+  if (organization === undefined) {
+    return new Set();
+  }
+  const accounts = new Set<string>();
+  for (const row of rows) {
+    if (row.spec?.principal?.kind === ACCOUNT_KIND) {
+      accounts.add(row.spec.principal.id);
+    }
+  }
+  const outside = new Set<string>();
+  for (const account of accounts) {
+    const held = await policies.findByPrincipal(ACCOUNT_KIND, account);
+    const inOrganization = held.some(
+      (policy) =>
+        policy.spec?.resource?.kind === ORGANIZATION_KIND &&
+        policy.spec.resource.id === organization.id,
+    );
+    if (!inOrganization) {
+      outside.add(account);
+    }
+  }
+  return outside;
+}
+
 /**
  * The display views of every distinct principal the rows name, keyed
  * `kind:id` (the grouping key, so two kinds can never share an id's view):

package/src/domain/iampolicy/change.ts

@@ -0,0 +1,109 @@
+/**
+ * What the grant path says about a change to a policy row: who made it,
+ * through which door, and in which organization. The grant path
+ * (grant-path.ts) builds one for every row it writes or deletes that
+ * grants access, and hands it to the store beside the row
+ * (`IamPolicyStore.save` and `deleteById`), so an edition that keeps a
+ * permission history writes it in the same atomic unit as the row. Open
+ * source keeps no history table; the same facts ride the path's grant and
+ * revoke log lines.
+ *
+ * The cause names a door the grant path already has, never an edition's
+ * business reason: an edition that grants on a person's behalf (an
+ * invitation, a federated sign-in) says whom it acted for through the
+ * actor (`serverActingFor`, pipeline/interceptors/auth.ts), not through a
+ * cause of its own. The strings are stored bytes in an edition's history:
+ * a cause is added, never renamed or reused.
+ *
+ * An access row is a row that lets someone reach something: it names a
+ * person, or an audience written as a userset (`team:T#member`,
+ * `organization:O#viewer`, `identity_provider:I#platform_user`). A row
+ * naming a resource as its principal with no relation is a structural link
+ * (a parent, a default instance, a managed organization), the bookkeeping
+ * a resource's own creation implies; it carries no change record.
+ *
+ * The actor is the caller's id and class and nothing else: never the email,
+ * the display name or the token, so a history holds no more of a person
+ * than the rows it describes already do.
+ */
+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 type { CallerClass, CallerIdentity } from "../../extensions/identity.js";
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+
+/**
+ * The door a change came through. Stored bytes in an edition's history.
+ *
+ *   - `grant`: IamPolicy.create, a grant on the user lane.
+ *   - `revoke`: IamPolicy.delete.
+ *   - `structural`: IamPolicy.bootstrapPolicy, the server recording what a
+ *     resource's creation or visibility implies (its creator's authorship,
+ *     its audience).
+ *   - `organization_access_revoked`: revokeOrgAccess and its system twin,
+ *     a person removed from an organization.
+ *   - `left_organization`: the sweep that follows a person's last role on
+ *     an organization, revoking what they held on its resources.
+ *   - `resource_deleted`: the rows that die with a deleted resource
+ *     (cleanupResourcePolicies, the built-in lifecycle's delete cleanup,
+ *     an organization's revoke before its row goes).
+ *   - `organization_created`: open source's creator `owner` row.
+ *   - `first_sign_in`: open source's membership rules for a new account.
+ *   - `role_reconciliation`: the one-shot pass that gives existing
+ *     accounts the roles the membership rules would have.
+ *   - `operator_ownership`: the trusted-local operator made owner of an
+ *     organization nobody owns.
+ *   - `platform_client_grant`: a PlatformClient's auto-granted role on the
+ *     account it mints.
+ */
+export type PolicyChangeCause =
+  | "grant"
+  | "revoke"
+  | "structural"
+  | "organization_access_revoked"
+  | "left_organization"
+  | "resource_deleted"
+  | "organization_created"
+  | "first_sign_in"
+  | "role_reconciliation"
+  | "operator_ownership"
+  | "platform_client_grant";
+
+/** Who made a change: the caller's id and class, nothing that identifies a person beyond the id. */
+export interface PolicyActor {
+  readonly id: string;
+  readonly callerClass: CallerClass;
+}
+
+/**
+ * What the store is handed beside an access row it writes or deletes. An
+ * implementation that keeps a history records exactly one entry for it, in
+ * the same atomic unit as the row change, and none when the row did not
+ * change (IamPolicyStore, store.ts).
+ */
+export interface PolicyChangeRecord {
+  readonly actor: PolicyActor;
+  readonly cause: PolicyChangeCause;
+  /**
+   * The organization the row's resource belongs to, resolved before any
+   * row of the operation is deleted; "" when none can be found (a kind
+   * outside organization scope, a legacy row with no scope link).
+   */
+  readonly organizationId: string;
+}
+
+const ACCOUNT_KIND = kindEnumName(ApiResourceKind.identity_account);
+
+/** The actor a caller is recorded as. */
+export function policyActorOf(caller: CallerIdentity): PolicyActor {
+  return { id: caller.identityId, callerClass: caller.callerClass };
+}
+
+/** Whether a row lets someone reach something (a person or an audience), as opposed to a structural link. */
+export function grantsAccess(spec: IamPolicySpec): boolean {
+  const principal = spec.principal;
+  if (principal === undefined) {
+    return false;
+  }
+  return principal.kind === ACCOUNT_KIND || principal.relation !== "";
+}

package/src/domain/iampolicy/constants.ts

@@ -308,6 +308,14 @@ export function malformedTripleMessage(field: string): string {
 export const OWNER_ASSIGNMENT_DENIED_MESSAGE =
   "only an owner of the organization can grant, revoke or remove the owner role";
 
+/**
+ * A grant of the organization's `affiliated` relation (INVALID_ARGUMENT, on
+ * every lane): it is derived from a person's organization roles, never
+ * granted (fga/model/tenancy/organization.fga).
+ */
+export const AFFILIATION_NOT_GRANTABLE_MESSAGE =
+  "affiliated is derived from a person's organization roles and is never granted";
+
 /** Revoking or removing the last owner of an organization (FAILED_PRECONDITION). */
 export const LAST_OWNER_MESSAGE =
   "an organization must keep at least one owner; make another member an owner first";

package/src/domain/iampolicy/controller.ts

@@ -172,6 +172,7 @@ import {
   policyNotFoundMessage,
   unknownPermissionMessage,
 } from "./constants.js";
+import type { PolicyChangeCause } from "./change.js";
 import { newAccountDisplayResolver } from "./display-resolver.js";
 import type { AccountsByIds } from "./display-resolver.js";
 import type { IamPolicyGrantPath } from "./grant-path.js";
@@ -242,7 +243,14 @@ export function registerIamPolicyServices(
     delete: (spec, ctx) => deletePolicy(deps, spec, ctx),
     bootstrapPolicy: (spec, ctx) => {
       guardSystemRpc(command.bootstrapPolicy, callerIdentityOf(ctx));
-      return grantThroughChain(deps, command.bootstrapPolicy, spec, ctx, false);
+      return grantThroughChain(
+        deps,
+        command.bootstrapPolicy,
+        spec,
+        ctx,
+        false,
+        "structural",
+      );
     },
     cleanupResourcePolicies: (ref, ctx) => {
       guardSystemRpc(command.cleanupResourcePolicies, callerIdentityOf(ctx));
@@ -318,6 +326,7 @@ function createPolicy(
     spec,
     ctx,
     true,
+    "grant",
   );
 }
 
@@ -325,7 +334,8 @@ function createPolicy(
  * The grant chain both `create` and `bootstrapPolicy` run; only the user
  * lane validates the role, asks for an owner's authority when it grants
  * owner, and runs the create gate slot — bootstrap writes structural
- * relations no scope would admit and no edition gates.
+ * relations no scope would admit and no edition gates. `cause` is the
+ * lane's door, recorded with every access row it writes.
  */
 async function grantThroughChain(
   deps: IamPolicyControllerDeps,
@@ -333,6 +343,7 @@ async function grantThroughChain(
   spec: IamPolicySpec,
   ctx: HandlerContext,
   validateRole: boolean,
+  cause: PolicyChangeCause,
 ): Promise<IamPolicy> {
   const reqCtx = new RequestContext(
     IamPolicySpecSchema,
@@ -358,7 +369,10 @@ async function grantThroughChain(
       pipeline.addStep(step);
     }
   }
-  await pipeline.addStep(newGrantStep(deps.grantPath)).build().execute(reqCtx);
+  await pipeline
+    .addStep(newGrantStep(deps.grantPath, cause))
+    .build()
+    .execute(reqCtx);
   return policyResultOf(reqCtx, method);
 }