@stigmer/server 3.15.2-dev.20260913223433 → 3.15.3-dev.20260914100347

package/src/domain/iampolicy/display-resolver.ts

@@ -0,0 +1,123 @@
+/**
+ * The access-list display resolver (20260913.01 slice 5; Q-S5-4, Q-S5-8):
+ * the account half of the Java PrincipalEnricher — batch-loads identity
+ * accounts through the identity-account domain's PORT (`findByIds`, one
+ * row per distinct id, the port's own line) and renders the
+ * ApiResourceRefView shape access listings carry: display name, email,
+ * avatar, identity origin. Moved from the cloud's iam/account/
+ * display-resolver.ts; built by the IamPolicy controller over the accounts
+ * port it already holds, never composed as a seam — the data is a domain
+ * READ, the same in every edition.
+ *
+ * The display-name precedence is `first + last > first > last >
+ * metadata.name > email`. The `metadata.name` arm is this domain's one
+ * deliberate divergence from the Java code (Q-S5-4): the trusted-local
+ * operator account carries its display name THERE and empty first/last
+ * names (identityaccount/operator.ts), while the cloud names every
+ * provisioned account by its EMAIL and fills first/last from userinfo
+ * (identityaccount/provisioning.ts; the DefaultAccountName step) — so on
+ * the cloud this arm and the email arm answer the same string, and on a
+ * laptop the Members row reads the name the operator configured instead
+ * of an address. `email` stays as the last resort for a row whose name
+ * was never defaulted.
+ *
+ * The federated provider label stays empty (the cloud's 3C provider
+ * display-name lookup never landed in the shared shape); direct and
+ * machine accounts carry the "Stigmer" label, the Java constant.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
+import type { ApiResourceRefView } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import {
+  ApiResourceRefViewSchema,
+  IdentityOriginSchema,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import type { IdentityAccountStore } from "../identityaccount/store.js";
+import type { PrincipalDisplayResolver } from "./access-lists.js";
+
+/** The Java STIGMER_PROVIDER_LABEL constant. */
+const STIGMER_PROVIDER_LABEL = "Stigmer";
+
+/** The one read enrichment needs from the identity-account port. */
+export type AccountsByIds = Pick<IdentityAccountStore, "findByIds">;
+
+export function newAccountDisplayResolver(
+  accounts: AccountsByIds,
+): PrincipalDisplayResolver {
+  return {
+    async resolveIdentityAccounts(
+      ids,
+    ): Promise<ReadonlyMap<string, ApiResourceRefView>> {
+      const rows = await accounts.findByIds(ids);
+      const resolved = new Map<string, ApiResourceRefView>();
+      for (const account of rows) {
+        const id = account.metadata?.id ?? "";
+        resolved.set(id, viewOf(id, account));
+      }
+      return resolved;
+    },
+  };
+}
+
+function viewOf(id: string, account: IdentityAccount): ApiResourceRefView {
+  const spec = account.spec;
+  return create(ApiResourceRefViewSchema, {
+    kind: kindEnumName(ApiResourceKind.identity_account),
+    id,
+    name: displayNameOf(
+      spec?.firstName ?? "",
+      spec?.lastName ?? "",
+      account.metadata?.name ?? "",
+      spec?.email ?? "",
+    ),
+    email: spec?.email ?? "",
+    avatar: spec?.pictureUrl ?? "",
+    identityOrigin: create(IdentityOriginSchema, {
+      provisioningMode:
+        spec?.provisioningMode ??
+        IdentityAccountProvisioningMode.identity_account_provisioning_mode_unspecified,
+      providerDisplayName: providerLabelOf(spec?.provisioningMode),
+    }),
+  });
+}
+
+/** The Java buildDisplayName precedence, with the account's own name before the email (Q-S5-4). */
+function displayNameOf(
+  firstName: string,
+  lastName: string,
+  accountName: string,
+  email: string,
+): string {
+  if (firstName !== "" && lastName !== "") {
+    return `${firstName} ${lastName}`;
+  }
+  if (firstName !== "") {
+    return firstName;
+  }
+  if (lastName !== "") {
+    return lastName;
+  }
+  if (accountName !== "") {
+    return accountName;
+  }
+  return email;
+}
+
+function providerLabelOf(
+  mode: IdentityAccountProvisioningMode | undefined,
+): string {
+  switch (mode) {
+    case IdentityAccountProvisioningMode.direct:
+    case IdentityAccountProvisioningMode.machine:
+      return STIGMER_PROVIDER_LABEL;
+    default:
+      // federated / platform_client / unspecified carry no external
+      // provider label (the Java switch arms).
+      return "";
+  }
+}

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

@@ -0,0 +1,270 @@
+/**
+ * The ONE grant and revoke path of the IamPolicy domain (20260913.01,
+ * T01_0_plan.md §3a; T01_1_review.md Q-OR-1), moved from the cloud's
+ * iam/policy/service.ts into open source so every edition writes and
+ * deletes a policy row the same way. Its callers: the IamPolicy command
+ * controller (user grants and the three system RPCs), the built-in role
+ * lifecycle (the organization creator's `owner` row; cleanup on delete)
+ * and the membership rules (first-sign-in roles). Nothing else builds,
+ * saves or deletes a policy row; a composition reaches this path as
+ * in-process RPCs, never through an exported constructor.
+ *
+ * The two cloud#425 ordering invariants live here, nowhere else:
+ *   CREATE: row before tuple — a crash between the two leaves
+ *     row-without-tuple (granted on paper, denied in practice), healed by
+ *     the caller's natural retry (the tuple write deliberately runs on
+ *     duplicates too — the inline heal) or the boot backfill.
+ *   DELETE: tuple before row — a crash leaves row+tuple (revoke failed,
+ *     retry works); the reverse order was the fail-open incident class
+ *     ("revoke access" silently becoming "keep access forever").
+ * "Tuple" here is whatever the composed ResourceAuthorizationLifecycle does
+ * in `onPolicyGranted` and `onPolicyRevoked`; with none composed, or one
+ * without the two optional hooks, the path writes rows and notifies
+ * nothing (the OSS posture: rows are the record).
+ *
+ * The row for a triple is found BY TRIPLE, never by derived id. Open
+ * source's rows carry the derived id (constants.ts policyIdFor), so the
+ * two lookups would agree here; the cloud's Java-era rows carry random
+ * `iamp_<ulid>` ids and must revoke and deduplicate through this same
+ * code, so `findByTriple` (the pair's rows filtered by relation) is the
+ * one definition of "the row for this triple" and `findById` serves the
+ * `get` RPC alone. On the OSS adapter that read is one scan of the kind
+ * (resource-store.ts); §4 measures it.
+ *
+ * The path is the one writer, so it refuses before it writes (Q-S2-1;
+ * slice 1 ruling 2): before any read, write or hook, `grant` and
+ * `revokeBySpec` run the domain's wire refusals (wire-refusals.ts — a spec
+ * whose resource or principal kind is not an ApiResourceKind member name,
+ * or whose fields hold a canonical-text delimiter, is INVALID_ARGUMENT
+ * with the pinned copy; slice 5 made that module the one home of the rule
+ * the controller and the ValidateGrantableRole step share). The
+ * controller refuses the same kinds BEFORE position 1 (Q-S6-1), so a wire
+ * caller never reaches this check; it stands for the callers that enter
+ * here without the controller — the built-in lifecycle and the membership
+ * rules — and is what keeps a garbage row out of the store and a garbage
+ * spec away from a composition's tuple delete from every door.
+ * `cleanupResource` and `revokeOrgAccess` take refs and ids their callers
+ * read from rows, so they do not refuse.
+ *
+ * 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
+ * `buildNewPolicy` stamped neither org nor creator; this path stamps the
+ * creator and, like the cloud, no `metadata.org`, because a policy may
+ * span organizations and none owns it.
+ */
+import { create } from "@bufbuild/protobuf";
+
+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";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import type {
+  ApiResourceRef,
+  IamPolicySpec,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import type { ResourceAuthorizationLifecycle } from "../../extensions/resource-authorization.js";
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { setAuditFieldsForCreate } from "../../pipeline/steps/defaults.js";
+import {
+  IAM_POLICY_API_VERSION,
+  IAM_POLICY_KIND,
+  policyIdFor,
+} from "./constants.js";
+import { DuplicatePolicyError } from "./store.js";
+import type { IamPolicyStore } from "./store.js";
+import { refsOf, requireWellFormedTriple } from "./wire-refusals.js";
+
+export interface GrantResult {
+  readonly policy: IamPolicy;
+  /** True when the triple was already held: no row was written, the hook still fired. */
+  readonly duplicate: boolean;
+}
+
+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(spec: IamPolicySpec, caller: CallerIdentity): 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.
+   */
+  revokeBySpec(spec: IamPolicySpec): Promise<IamPolicy | undefined>;
+  /**
+   * Revoke every row naming the ref as its resource, then every row naming
+   * it as its principal, each through the revoke order; a row that is both
+   * is revoked once. Nothing to clean is a no-op.
+   */
+  cleanupResource(ref: ApiResourceRef): Promise<void>;
+  /** Revoke every relation the account holds directly on the organization. */
+  revokeOrgAccess(
+    identityAccountId: string,
+    organizationId: string,
+  ): Promise<void>;
+}
+
+export interface IamPolicyGrantPathDeps {
+  readonly policies: IamPolicyStore;
+  /** The composed driver, if any; a driver without the two policy hooks is the same as none. */
+  readonly lifecycle: ResourceAuthorizationLifecycle | undefined;
+  readonly logger: Logger;
+}
+
+export function newIamPolicyGrantPath(
+  deps: IamPolicyGrantPathDeps,
+): IamPolicyGrantPath {
+  const { policies, lifecycle, logger } = deps;
+
+  /** The row holding this exact triple — the pair's rows, filtered by relation. */
+  async function findByTriple(
+    spec: IamPolicySpec,
+  ): Promise<IamPolicy | undefined> {
+    const { principal, resource } = refsOf(spec);
+    const onPair = await policies.findByPrincipalAndResource(
+      principal.kind,
+      principal.id,
+      resource.kind,
+      resource.id,
+    );
+    return onPair.find(
+      (policy) =>
+        policy.spec !== undefined &&
+        policy.spec.relation === spec.relation &&
+        policy.spec.principal?.relation === principal.relation,
+    );
+  }
+
+  /** The revoke order for one row: the hook, then the delete. */
+  async function revokeRow(policy: IamPolicy): Promise<void> {
+    const spec = policy.spec;
+    if (spec === undefined) {
+      throw new Error(
+        `policy ${policy.metadata?.id ?? "?"} has no spec — corrupt row`,
+      );
+    }
+    await lifecycle?.onPolicyRevoked?.({ spec, policy });
+    const id = policy.metadata?.id ?? "";
+    await policies.deleteById(id);
+    logger.info("iam policy revoked", fieldsOf(id, spec));
+  }
+
+  return {
+    async grant(spec, caller): Promise<GrantResult> {
+      requireWellFormedTriple(spec);
+      let policy = await findByTriple(spec);
+      let duplicate = policy !== undefined;
+      if (policy === undefined) {
+        const fresh = buildRow(spec, caller);
+        try {
+          await policies.save(fresh);
+          policy = fresh;
+          logger.info("iam policy granted", fieldsOf(policyIdFor(spec), spec));
+        } catch (error) {
+          if (!(error instanceof DuplicatePolicyError)) {
+            throw error;
+          }
+          // Lost the race to another writer of the same triple: the
+          // winner's row is the grant, exactly as if it had been found
+          // above. A winner that cannot be read back means the refusal
+          // was not a race — propagate it.
+          const winner = await findByTriple(spec);
+          if (winner === undefined) {
+            throw error;
+          }
+          policy = winner;
+          duplicate = true;
+        }
+      }
+      if (duplicate) {
+        logger.debug(
+          "iam policy already held",
+          fieldsOf(policy.metadata?.id ?? "", spec),
+        );
+      }
+      // Deliberately unconditional (cloud#425): a duplicate re-grant is the
+      // inline heal for a row whose tuple never landed.
+      await lifecycle?.onPolicyGranted?.({ policy, duplicate });
+      return { policy, duplicate };
+    },
+
+    async revokeBySpec(spec): Promise<IamPolicy | undefined> {
+      requireWellFormedTriple(spec);
+      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;
+      }
+      await revokeRow(existing);
+      return existing;
+    },
+
+    async cleanupResource(ref): Promise<void> {
+      const asResource = await policies.findByResource(ref.kind, ref.id);
+      const asPrincipal = await policies.findByPrincipal(ref.kind, ref.id);
+      for (const policy of distinctById([...asResource, ...asPrincipal])) {
+        await revokeRow(policy);
+      }
+    },
+
+    async revokeOrgAccess(identityAccountId, organizationId): Promise<void> {
+      const direct = await policies.findByPrincipalAndResource(
+        kindEnumName(ApiResourceKind.identity_account),
+        identityAccountId,
+        kindEnumName(ApiResourceKind.organization),
+        organizationId,
+      );
+      for (const policy of direct) {
+        await revokeRow(policy);
+      }
+    },
+  };
+}
+
+/** The row for a fresh grant: the contract's identity strings, the derived id, the caller's stamp. */
+function buildRow(spec: IamPolicySpec, caller: CallerIdentity): IamPolicy {
+  const policy = create(IamPolicySchema, {
+    apiVersion: IAM_POLICY_API_VERSION,
+    kind: IAM_POLICY_KIND,
+    metadata: create(ApiResourceMetadataSchema, { id: policyIdFor(spec) }),
+    spec,
+  });
+  setAuditFieldsForCreate(IamPolicySchema, policy, caller);
+  return policy;
+}
+
+/** One row per id, at its first position. */
+function distinctById(
+  policies: ReadonlyArray<IamPolicy>,
+): ReadonlyArray<IamPolicy> {
+  const seen = new Set<string>();
+  return policies.filter((policy) => {
+    const id = policy.metadata?.id ?? "";
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
+}
+
+/** The structured fields every log line carries — ids and kinds, never a token. */
+function fieldsOf(id: string, spec: IamPolicySpec): Record<string, string> {
+  return {
+    policyId: id,
+    relation: spec.relation,
+    principalKind: spec.principal?.kind ?? "",
+    principalId: spec.principal?.id ?? "",
+    resourceKind: spec.resource?.kind ?? "",
+    resourceId: spec.resource?.id ?? "",
+  };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Open source's PolicyGrantScope (20260913.01, T01_1_review.md Q-OR-3 and
+ * Q-OR-4): the ORGANIZATION grants the roles its `kind_meta` lists —
+ * owner, admin, member, viewer — and no other kind grants anything. This
+ * is what lights the console's Members page in every edition while a
+ * viewer on one agent, the per-resource grant, stays what the Enterprise
+ * and Cloud editions add by composing a wider scope
+ * (extensions/policy-grant-scope.ts carries the contract every scope is
+ * held to: narrows the proto, total over the enum, synchronous).
+ *
+ * Installed by the composition root when no unit registers
+ * `drivers.policyGrantScope` — the `newPermissiveSingleTeamAuthorizer`
+ * shape: the default lives with the domain that defines its semantics and
+ * is called at the `??` site, never held by the registry.
+ *
+ * The organization's roles are READ from the proto through
+ * `grantableRolesFor`, not written here: the four words the Members page
+ * shows and entry 3's authorizer enforces have one source, and a proto
+ * change is the only way to change them (grant-scope.test.ts pins the
+ * equality; grantable-roles-for.test.ts pins the four).
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { PolicyGrantScope } from "../../extensions/policy-grant-scope.js";
+import { grantableRolesFor } from "../../pipeline/apiresource-meta.js";
+
+/** The open-source default: organization → its proto roles; every other kind → none. */
+export function newOrganizationOnlyGrantScope(): PolicyGrantScope {
+  return {
+    grantableRoles(kind) {
+      return kind === ApiResourceKind.organization
+        ? grantableRolesFor(kind)
+        : [];
+    },
+  };
+}