@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

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

@@ -0,0 +1,191 @@
+/**
+ * Access-list machinery (20260913.01 slice 5): the row-driven answer to
+ * "who has access, with which roles" behind `listResourceAccessByPrincipal`
+ * — the Java ResourceHierarchyResolver and PrincipalEnricher ports, moved
+ * as-is from the cloud's iam/policy/access-lists.ts so every edition
+ * renders an access list the same way over its own IamPolicyStore.
+ *
+ * The hierarchy walk climbs the resource's scope tuples (child →
+ * organization → platform, at most five steps, `platform` terminal) in the
+ * policy rows themselves — a structural link is a row whose principal is
+ * not a person and whose relation is not a role (store.ts `findScopeTuple`
+ * states the exclusions). Inherited grants carry their owning level so the
+ * console can say "inherited from organization". On open source no chain
+ * seeds scope links (a policy is the authorization record, not a protected
+ * resource — the IamPolicy chains splice no tuple step), so the walk is one
+ * level unless the platform's own pipeline bootstrapped a link.
+ *
+ * Display enrichment is a seam (`PrincipalDisplayResolver`) because the
+ * data lives in the identity-account domain; display-resolver.ts fills it
+ * over that domain's PORT. A principal the resolver does not answer for —
+ * any kind that is not an identity account, or an account whose row is
+ * gone — renders as kind/id with the id standing in as the display name,
+ * the Java `enrich()` fallback shape.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import type {
+  ApiResourceRefView,
+  PrincipalAccess,
+  RoleGrant,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import {
+  ApiResourceRefViewSchema,
+  PrincipalAccessSchema,
+  RoleGrantSchema,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import { ApiResourceRefSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { assignableRelations, roleInfoFromRelation } from "./roles.js";
+import type { IamPolicyStore } from "./store.js";
+
+/** The Java resolver's bounds: ≤5 steps, platform terminates the walk. */
+const MAX_HIERARCHY_DEPTH = 5;
+const TERMINAL_KINDS: ReadonlySet<string> = new Set([
+  kindEnumName(ApiResourceKind.platform),
+]);
+
+export interface HierarchyLevel {
+  readonly kind: string;
+  readonly id: string;
+}
+
+/**
+ * Child-first hierarchy via scope-tuple rows (Java resolve): index 0 is
+ * the resource itself; each later level is the previous one's structural
+ * scope parent.
+ */
+export async function resolveHierarchy(
+  policies: IamPolicyStore,
+  resourceKind: string,
+  resourceId: string,
+  includeInherited: boolean,
+): Promise<ReadonlyArray<HierarchyLevel>> {
+  const hierarchy: HierarchyLevel[] = [{ kind: resourceKind, id: resourceId }];
+  if (!includeInherited) {
+    return hierarchy;
+  }
+  let currentKind = resourceKind;
+  let currentId = resourceId;
+  for (
+    let depth = 0;
+    depth < MAX_HIERARCHY_DEPTH && !TERMINAL_KINDS.has(currentKind);
+    depth++
+  ) {
+    const scopeTuple = await policies.findScopeTuple(currentKind, currentId);
+    const parent = scopeTuple?.spec?.principal;
+    if (parent === undefined) {
+      break;
+    }
+    currentKind = parent.kind;
+    currentId = parent.id;
+    hierarchy.push({ kind: currentKind, id: currentId });
+  }
+  return hierarchy;
+}
+
+/**
+ * The display-enrichment seam (the Java PrincipalEnricher's account half):
+ * the views for the identity-account ids it can resolve, keyed by id. Ids
+ * it does not answer for fall back below.
+ */
+export interface PrincipalDisplayResolver {
+  resolveIdentityAccounts(
+    ids: ReadonlyArray<string>,
+  ): Promise<ReadonlyMap<string, ApiResourceRefView>>;
+}
+
+/**
+ * Groups assignable-role policies by principal in first-seen order (the
+ * Java LinkedHashMap contract), enriched where the resolver answers and
+ * the Java fallback shape (name = id) everywhere else.
+ */
+export async function buildPrincipalAccessList(
+  policies: IamPolicyStore,
+  displayResolver: PrincipalDisplayResolver,
+  hierarchy: ReadonlyArray<HierarchyLevel>,
+): Promise<ReadonlyArray<PrincipalAccess>> {
+  interface GrantAtLevel {
+    readonly policy: IamPolicy;
+    readonly isInherited: boolean;
+    readonly level: HierarchyLevel;
+  }
+  const grants: GrantAtLevel[] = [];
+  for (const [index, level] of hierarchy.entries()) {
+    const rows = await policies.findByResourceWithRelations(
+      level.kind,
+      level.id,
+      assignableRelations(),
+    );
+    for (const policy of rows) {
+      grants.push({ policy, isInherited: index > 0, level });
+    }
+  }
+  if (grants.length === 0) {
+    return [];
+  }
+
+  const accountKind = kindEnumName(ApiResourceKind.identity_account);
+  const accountIds = grants
+    .filter((g) => g.policy.spec?.principal?.kind === accountKind)
+    .map((g) => g.policy.spec?.principal?.id ?? "");
+  const enriched = await displayResolver.resolveIdentityAccounts(accountIds);
+
+  const grouped = new Map<
+    string,
+    { principal: ApiResourceRefView; roles: RoleGrant[] }
+  >();
+  for (const grant of grants) {
+    const principal = grant.policy.spec?.principal;
+    if (principal === undefined) {
+      continue;
+    }
+    const key = `${principal.kind}:${principal.id}`;
+    let entry = grouped.get(key);
+    if (entry === undefined) {
+      entry = {
+        // The Java enrich() fallback shape for unresolved principals of
+        // ANY kind: kind/id with the id standing in as the display name.
+        principal:
+          enriched.get(principal.id) ??
+          create(ApiResourceRefViewSchema, {
+            kind: principal.kind,
+            id: principal.id,
+            name: principal.id,
+          }),
+        roles: [],
+      };
+      grouped.set(key, entry);
+    }
+    entry.roles.push(buildGrant(grant.policy, grant.isInherited, grant.level));
+  }
+
+  return [...grouped.values()].map((entry) =>
+    create(PrincipalAccessSchema, {
+      principal: entry.principal,
+      roles: entry.roles,
+    }),
+  );
+}
+
+function buildGrant(
+  policy: IamPolicy,
+  isInherited: boolean,
+  level: HierarchyLevel,
+): RoleGrant {
+  return create(RoleGrantSchema, {
+    role: roleInfoFromRelation(policy.spec?.relation ?? ""),
+    isInherited,
+    ...(isInherited
+      ? {
+          ownerResource: create(ApiResourceRefSchema, {
+            kind: level.kind,
+            id: level.id,
+          }),
+        }
+      : {}),
+  });
+}

package/src/domain/iampolicy/constants.ts

@@ -0,0 +1,243 @@
+/**
+ * IamPolicy domain constants (20260913.01, T01_0_plan.md §3a;
+ * T01_1_review.md Q-OR-6b, Q-OR-9; slice 2 ruling Q-S2-1): the derived
+ * policy id and the one spelling of a triple it hashes, the kinds the
+ * legacy-creator rule scans, and the byte-pinned wire copy.
+ *
+ * The derived id (Q-OR-9). A policy's id is a pure function of its triple:
+ * `iamp_` + `derivedId` (pipeline/steps/defaults.ts, the encoder shared
+ * with the identity account) over the triple's canonical text. The text
+ * IS the tuple notation the contract's own comment documents
+ * (`principal.kind:principal.id#principal.relation@resource.kind:resource.id#relation`,
+ * spec.proto), the principal's `#` present even when its qualifier is
+ * empty, so the natural key has one spelling and the primary key is the
+ * one home of "one row per triple" in open source: two concurrent grants
+ * converge by primary key with no secondary index and no scan. The golden
+ * vectors in __tests__/constants.test.ts are wire-adjacent contract: a
+ * change here re-addresses every policy open source ever wrote.
+ *
+ * The text's one weakness (Q-S2-1): `ApiResourceRef` fields carry no
+ * character pattern, so an id or relation holding one of the three
+ * delimiters could spell another triple's text (`a#b` with an empty
+ * qualifier and `a` with qualifier `b#` read alike). `malformedTripleField`
+ * names such a field; `policyIdFor` refuses to hash such a spec; the grant
+ * path turns the same check into INVALID_ARGUMENT before any read or write.
+ * No legitimate reference carries a delimiter: every kind is an enum member
+ * name, every id a `prefix_ulid`, a slug or the public wildcard `*`, every
+ * relation an FGA relation name — and OpenFGA itself rejects `:` and `#`
+ * in ids, so the cloud loses nothing it could ever have written.
+ *
+ * `BLUEPRINT_KINDS` (Q-OR-6b) is the legacy-creator rule's whole scan: the
+ * kinds an admin authors. Sessions, executions, keys and memories are
+ * personal and stay with their creator by DD-002 rule 2; they never appear
+ * here.
+ *
+ * The copy moved from the cloud's iam/policy/handlers.ts as-is: the CLI,
+ * 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.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type {
+  ApiResourceRef,
+  IamPolicySpec,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { derivedId } from "../../pipeline/steps/defaults.js";
+
+/** The kind's id prefix (kind_meta `iam_policy.id_prefix`). */
+export const POLICY_ID_PREFIX = "iamp";
+
+/**
+ * The proto's `api_version` const (api.proto). The cloud's Java-era rows
+ * carry `iam.stigmer.com/v1` and are read as they are (Q-OR-9); every row
+ * this domain writes carries the contract's value.
+ */
+export const IAM_POLICY_API_VERSION = "iam.stigmer.ai/v1";
+export const IAM_POLICY_KIND = "IamPolicy";
+
+/** The three characters the canonical text is built from; none may appear inside a field. */
+export const TRIPLE_DELIMITERS: ReadonlyArray<string> = [":", "#", "@"];
+
+/** A triple with both references present — the shape the text and the id are defined over. */
+interface CompleteTriple {
+  readonly principal: ApiResourceRef;
+  readonly resource: ApiResourceRef;
+  readonly relation: string;
+}
+
+function completeTriple(spec: IamPolicySpec): CompleteTriple {
+  if (spec.principal === undefined || spec.resource === undefined) {
+    throw new Error("policy spec must carry principal and resource");
+  }
+  return {
+    principal: spec.principal,
+    resource: spec.resource,
+    relation: spec.relation,
+  };
+}
+
+/**
+ * The proto's tuple notation, the one spelling of a triple:
+ * `principal.kind:principal.id#principal.relation@resource.kind:resource.id#relation`.
+ * The principal's `#` is always present (an empty qualifier reads `#@`),
+ * so the same triple never has two texts.
+ */
+export function canonicalTripleText(spec: IamPolicySpec): string {
+  const { principal, resource, relation } = completeTriple(spec);
+  return `${principal.kind}:${principal.id}#${principal.relation}@${resource.kind}:${resource.id}#${relation}`;
+}
+
+/**
+ * The first field, in the text's order, holding a delimiter — or
+ * `undefined` for a well-formed triple. Named in the proto's field paths so
+ * a refusal tells the caller exactly what to fix. Total over a spec
+ * missing a reference: that is `completeTriple`'s refusal, not this one.
+ */
+export function malformedTripleField(spec: IamPolicySpec): string | undefined {
+  const fields: ReadonlyArray<readonly [path: string, value: string]> = [
+    ["principal.kind", spec.principal?.kind ?? ""],
+    ["principal.id", spec.principal?.id ?? ""],
+    ["principal.relation", spec.principal?.relation ?? ""],
+    ["resource.kind", spec.resource?.kind ?? ""],
+    ["resource.id", spec.resource?.id ?? ""],
+    ["relation", spec.relation],
+  ];
+  for (const [path, value] of fields) {
+    if (TRIPLE_DELIMITERS.some((delimiter) => value.includes(delimiter))) {
+      return path;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The derived policy id of a triple. Pure; refuses a spec missing either
+ * reference (a triple is the whole key) and a spec whose text would be
+ * ambiguous (Q-S2-1) — both are the assert behind the grant path's gate,
+ * which is where a caller hears INVALID_ARGUMENT.
+ */
+export function policyIdFor(spec: IamPolicySpec): string {
+  const text = canonicalTripleText(spec);
+  const malformed = malformedTripleField(spec);
+  if (malformed !== undefined) {
+    throw new Error(malformedTripleMessage(malformed));
+  }
+  return derivedId(POLICY_ID_PREFIX, text);
+}
+
+/**
+ * The kinds an admin authors — the legacy-creator rule's scan (Q-OR-6b),
+ * in registry order. A caller who created one of these idp-shaped, before
+ * an account existed, becomes admin on first sign-in.
+ */
+export const BLUEPRINT_KINDS: ReadonlyArray<ApiResourceKind> = [
+  ApiResourceKind.agent,
+  ApiResourceKind.workflow,
+  ApiResourceKind.skill,
+  ApiResourceKind.mcp_server,
+  ApiResourceKind.environment,
+  ApiResourceKind.schedule,
+];
+
+/**
+ * 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
+ * (`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.
+ *
+ * Why the rule is load-bearing: the read side treats every principal
+ * outside this vocabulary as a structural parent (`findScopeTuple`,
+ * resource-store.ts, which derives its exclusion FROM this constant so the
+ * 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.
+ */
+export const USER_GRANT_PRINCIPAL_KINDS: ReadonlyArray<ApiResourceKind> = [
+  ApiResourceKind.identity_account,
+];
+
+// ---------------------------------------------------------------------------
+// Byte-pinned copy (the cloud handlers' sentences, moved as-is).
+// ---------------------------------------------------------------------------
+
+/** get on a missing policy (NOT_FOUND). */
+export function policyNotFoundMessage(id: string): string {
+  return `IAM policy not found: ${id}`;
+}
+
+/** A grant on a kind whose kind_meta lists no grantable roles (INVALID_ARGUMENT, every edition). */
+export function noGrantableRolesMessage(kind: string): string {
+  return `No roles can be granted on resource kind '${kind}'. Role assignments for this resource kind are system-managed.`;
+}
+
+/** A role the kind does not list (INVALID_ARGUMENT); the grantable list in kind_meta order. */
+export function roleNotGrantableMessage(
+  role: string,
+  kind: string,
+  grantable: ReadonlyArray<string>,
+): string {
+  return `Role '${role}' cannot be granted on resource kind '${kind}'. Grantable roles: [${grantable.join(", ")}]`;
+}
+
+/** checkMyPermission for a caller with no identity (UNAUTHENTICATED). */
+export const AUTHENTICATION_REQUIRED_MESSAGE =
+  "Authentication required to check permissions";
+
+/**
+ * A spec whose resource kind is not an ApiResourceKind member name
+ * (INVALID_ARGUMENT; the cloud's `kindFromSpecString` sentence). The grant
+ * path is where a permissive Authorizer's caller hears it; an enforcing
+ * Authorizer denies the unknown kind at position 1 first (slice 1, ruling 2).
+ */
+export function unknownResourceKindMessage(kind: string): string {
+  return `Unknown resource kind: '${kind}'`;
+}
+
+// ---------------------------------------------------------------------------
+// New copy (this entry's refusals).
+// ---------------------------------------------------------------------------
+
+/**
+ * A grant on a kind outside the composed grant scope (UNIMPLEMENTED) — the
+ * federation and kind-registry degrade-by-probe posture: the sentence a
+ * person can act on, naming the editions that serve it.
+ */
+export const PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE =
+  "per-resource access grants are served by the Enterprise and Cloud editions";
+
+/** The tuple-half queries on a composition without an AuthorizationQueryEngine (UNIMPLEMENTED). */
+export const AUTHORIZATION_QUERIES_UNIMPLEMENTED_MESSAGE =
+  "authorization queries are served by the Enterprise and Cloud editions";
+
+/** checkMyPermission with a relation that is no IamPermission name (INVALID_ARGUMENT). */
+export function unknownPermissionMessage(relation: string): string {
+  return `unknown permission '${relation}'`;
+}
+
+/** A spec whose principal kind is not an ApiResourceKind member name (INVALID_ARGUMENT). */
+export function unknownPrincipalKindMessage(kind: string): string {
+  return `Unknown principal kind: '${kind}'`;
+}
+
+/**
+ * A user grant whose principal is not a person (INVALID_ARGUMENT; Q-S9-2),
+ * in the role sentence's shape: the offending kind, then the vocabulary.
+ */
+export function principalNotGrantableMessage(kind: string): string {
+  const grantable = USER_GRANT_PRINCIPAL_KINDS.map((k) => kindEnumName(k));
+  return `Principal kind '${kind}' cannot be granted a role. Grantable principal kinds: [${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 '@'`;
+}