@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/authorization/organization-directory.ts

@@ -0,0 +1,114 @@
+/**
+ * The built-in organization directory — open source's driver for the
+ * organization-directory seam (extensions/organization-directory.ts),
+ * composed under the built-in posture. The cloud's directory answers
+ * `findMyOrganizations` with OpenFGA's list-objects for
+ * `organization#can_view`; this one answers the same question over the
+ * derived source: the candidates are the organizations the person's own
+ * IamPolicy rows name (on open source a person reaches an organization
+ * through a role row and nothing else — the derivation writes no
+ * organization tuple), and each candidate is kept when
+ * `can_view` holds for the person, evaluated by the same evaluator the
+ * Authorizer uses. An evaluation rather than a relation filter, so the
+ * answer stays right if the grant scope ever widens past the four roles,
+ * and stays equal to the cloud's today.
+ *
+ * `refusesEnumeration` is TRUE, the cloud's posture: `find` is
+ * skip-authorization by annotation, so under an enforcing server it would
+ * hand every member every organization row — the list that lies. The
+ * first-party clients list through `findMyOrganizations`. Trusted-local
+ * composes no directory and keeps enumerating (one caller, nothing to
+ * hide from).
+ *
+ * A caller who resolves to no account (an idp-shaped subject before
+ * provisioning) holds no rows and is answered `[]`, never a fault: the
+ * conformance sibling's readiness probe is this very RPC with a fresh
+ * subject. The `internal` class — the server acting as itself over the
+ * in-process transport — is answered `ALL_ORGANIZATIONS`: the Authorize
+ * step treats that class as the in-process authorization skip (pipeline/
+ * interceptors/auth.ts, ruling Q4), and a directory answer IS an
+ * authorization answer, so a server-internal hop sees what the permissive
+ * default showed it. `findMyOrganizations` is skip-authorization by
+ * annotation, which is why this driver meets that caller at all: a
+ * skip lane hands the directory the identity the interceptor stamped,
+ * and no Authorize arm ran before it. Every other caller gets the
+ * evaluated list. The listing context (`allow: false`) is the cloud's,
+ * though no organization line admits a wildcard.
+ * The controller loads each id it is handed and skips the ones whose row
+ * is gone (grants can outlive rows); the source has already loaded the
+ * row once for the evaluation — two primary-key reads per organization,
+ * a handful per person, and the contract's own read is the controller's.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
+import type { CallerIdentity } from "../extensions/identity.js";
+import type { OrganizationDirectory } from "../extensions/organization-directory.js";
+import { ALL_ORGANIZATIONS } from "../extensions/organization-directory.js";
+import { kindEnumName } from "../pipeline/apiresource-meta.js";
+import type { Store } from "../store/interface.js";
+import { newDerivedTupleSource } from "./derived-tuples.js";
+import { checkRelation } from "./evaluator.js";
+import type { Model } from "./model/index.js";
+import { builtInModel } from "./model/index.js";
+import type { AccountsByCaller } from "./person.js";
+import { resolvePerson } from "./person.js";
+
+export interface BuiltInOrganizationDirectoryDeps {
+  readonly store: Store;
+  readonly policies: IamPolicyStore;
+  readonly accounts: AccountsByCaller;
+  readonly model?: Model;
+}
+
+const ORGANIZATION = kindEnumName(ApiResourceKind.organization);
+
+export function newBuiltInOrganizationDirectory(
+  deps: BuiltInOrganizationDirectoryDeps,
+): OrganizationDirectory {
+  const model = deps.model ?? builtInModel;
+  return {
+    refusesEnumeration: true,
+
+    async listMyOrganizationIds(
+      caller: CallerIdentity,
+    ): Promise<ReadonlyArray<string> | typeof ALL_ORGANIZATIONS> {
+      if (caller.callerClass === "internal") {
+        return ALL_ORGANIZATIONS;
+      }
+      const person = await resolvePerson(deps.accounts, caller);
+      const source = newDerivedTupleSource(
+        {
+          store: deps.store,
+          policies: deps.policies,
+          accounts: deps.accounts,
+          model,
+        },
+        person,
+      );
+      // The candidates come from the source's ONE read of the person's
+      // rows — the same read `tuplesOf` will serve the evaluation from.
+      const candidates = new Set<string>();
+      for (const tuple of await source.personTuples()) {
+        if (tuple.object.type === ORGANIZATION && tuple.object.id !== "") {
+          candidates.add(tuple.object.id);
+        }
+      }
+      const visible: string[] = [];
+      for (const id of candidates) {
+        if (
+          await checkRelation(
+            { model, source },
+            { type: ORGANIZATION, id },
+            "can_view",
+            person,
+            { allow: false },
+          )
+        ) {
+          visible.push(id);
+        }
+      }
+      return visible;
+    },
+  };
+}

package/src/authorization/person.ts

@@ -0,0 +1,68 @@
+/**
+ * The caller as the model sees them — `Person`, built ONCE here for every
+ * built-in driver (the Authorizer, the organization directory, and the
+ * list scope when it lands), so "who is asking" cannot be answered two
+ * ways.
+ *
+ * Two steps, split so the pure half is testable without a store:
+ *
+ *   `resolvePerson(accounts, caller)` — the I/O: the account the caller
+ *   stands for through `accountForCaller` (domain/identityaccount/
+ *   resolve.ts, the domain's one statement of that question — the two
+ *   reads whoAmI makes), then `personFor`.
+ *
+ *   `personFor(caller, account)` — the pure half: the account id the
+ *   IamPolicy rows name, and every string a creator stamp may carry for
+ *   the same human. A provisioned caller carries the account id and the
+ *   account's issuer subject (rows the 3.14.x verifiers stamped with the
+ *   raw `sub` still match — the alias rule); an unprovisioned one
+ *   is their identity id alone and holds no rows. Nothing else is an
+ *   alias: an email stamp is nobody's, in the membership rules and here.
+ *
+ * Refuses an identity that names no person — the empty id and the
+ * unconfigured laptop's `"system"` placeholder — with the same predicate
+ * the derivation uses to keep such stamps out of tuples (`isPersonStamp`,
+ * the membership rules'). The two guards together are what make the
+ * evaluator's alias comparison a plain set membership: no tuple side and
+ * no person side ever carries a non-person string. Under the
+ * require-authentication posture neither id reaches a check (the
+ * verifiers stamp accounts or subjects; the in-process class skips
+ * authorization; the driver's own arm denies the empty id first), so the
+ * throw is the backstop for a caller built outside those lanes, and the
+ * driver folds it to `unavailable`.
+ */
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+
+import { isPersonStamp } from "../domain/iampolicy/membership.js";
+import type { AccountsByCaller } from "../domain/identityaccount/resolve.js";
+import { accountForCaller } from "../domain/identityaccount/resolve.js";
+import type { CallerIdentity } from "../extensions/identity.js";
+import type { Person } from "./tuples.js";
+
+export type { AccountsByCaller } from "../domain/identityaccount/resolve.js";
+
+export function personFor(
+  caller: CallerIdentity,
+  account: IdentityAccount | undefined,
+): Person {
+  const accountId = account?.metadata?.id ?? caller.identityId;
+  if (!isPersonStamp(accountId)) {
+    throw new Error(
+      `caller '${accountId}' names no person — the built-in authorizer evaluates people only`,
+    );
+  }
+  const aliases = new Set<string>([accountId]);
+  const subject = account?.spec?.idpId ?? "";
+  if (subject !== "") {
+    aliases.add(subject);
+  }
+  return { accountId, aliases };
+}
+
+/** The person a caller is, read through the account port; faults propagate as they are. */
+export async function resolvePerson(
+  accounts: AccountsByCaller,
+  caller: CallerIdentity,
+): Promise<Person> {
+  return personFor(caller, await accountForCaller(accounts, caller));
+}

package/src/authorization/posture.ts

@@ -0,0 +1,49 @@
+/**
+ * The authorization posture — WHICH authorizer a composed server runs,
+ * named once so the composition root, the boot log and the tests speak
+ * one word for it. Three postures, decided by two facts the registry and
+ * the config already hold:
+ *
+ *   - `unit-authorizer`: a unit registered its own Authorizer (the cloud
+ *     composes OpenFGA). Nothing built in is installed — not the
+ *     authorizer, not the directory, not the fire caller, and not the
+ *     role lifecycle or the membership rules either (a composition with
+ *     its own Authorizer has its own onboarding). The require-
+ *     authentication posture does not change this.
+ *   - `built-in`: no unit Authorizer AND the require-authentication
+ *     posture (the OSS OIDC issuer, or a unit's declaration). Open source
+ *     composes the built-in Authorizer, the organization directory and
+ *     the schedule fire caller — the cloud's model evaluated over derived
+ *     tuples — so the roles 2b records are enforced.
+ *   - `trusted-local`: no unit Authorizer and no authentication posture —
+ *     the laptop. The permissive default stays: one caller, nothing to
+ *     separate; the trusted-local identity carries the operator's EMAIL,
+ *     never an account id, and pre-2a rows are stamped `"system"`, so an
+ *     enforcing evaluator would refuse the laptop's own history. The roles
+ *     still exist (the lifecycle and the membership rules run) to feed the
+ *     Members page truthfully.
+ *
+ * The type lives with the module that gives it meaning (the precedent:
+ * `ConsoleSignInPosture` in transport/console/handler.ts); the
+ * composition root computes the value once and hands it down.
+ */
+export type AuthorizationPosture =
+  | "trusted-local"
+  | "built-in"
+  | "unit-authorizer";
+
+export interface AuthorizationPostureInputs {
+  /** A unit registered `authorizer` (ResolvedExtensions.authorizer !== undefined). */
+  readonly unitAuthorizer: boolean;
+  /** The require-authentication posture is on (the OIDC issuer or a unit's declaration). */
+  readonly requireAuthentication: boolean;
+}
+
+export function authorizationPostureOf(
+  inputs: AuthorizationPostureInputs,
+): AuthorizationPosture {
+  if (inputs.unitAuthorizer) {
+    return "unit-authorizer";
+  }
+  return inputs.requireAuthentication ? "built-in" : "trusted-local";
+}

package/src/authorization/schedule-fire-caller.ts

@@ -0,0 +1,87 @@
+/**
+ * The built-in schedule fire caller — a fire acts as the schedule's
+ * CREATOR. Open source's driver for the scheduleFireCaller seam
+ * (extensions/schedule-fire-caller.ts), composed under the built-in
+ * authorization posture.
+ *
+ * Why the creator: with no driver a fire enters the create pipeline as
+ * the `internal` class carrying the operator's email or `"system"`, and
+ * under an enforcing authorizer the fired session belongs to nobody the
+ * model recognizes — the person who scheduled it cannot see it, the
+ * operator cannot, the runner cannot report on it. The creator is the
+ * one person the schedule row names, and the person the runner will act
+ * as once its own lane lands. The run and its auto-created session are
+ * stamped with their account, so their `owner` derives, and the create
+ * runs the full chain as them: a creator who has since lost `can_execute`
+ * on the agent is refused by the launch gate, which the RunStarter already
+ * counts against the schedule.
+ *
+ * Recorded difference from the cloud: there the schedule's org admins and
+ * grantees also see the run, through the session#schedule tuple; here
+ * only the creator does, because deriving that link from the
+ * client-suppliable schedule-id label is what the cloud explicitly
+ * refused.
+ *
+ * The creator's account is resolved from the row's stamp through the
+ * identity-account domain's `accountForStamp` — as an account id (rows
+ * stamped since 3.15.0) and as the raw issuer subject (rows the 3.14.x
+ * verifiers stamped), the same two shapes `Person` aliases and the same
+ * read the runner-subject verifier makes of an execution's stamp. A
+ * stamp that resolves to no account
+ * is the seam's DETERMINISTIC refusal (`ScheduleFireCallerRefusedError`):
+ * the empty stamp, the laptop's `"system"`, an email from the
+ * trusted-local era, a deleted account — no retry will make that schedule
+ * anyone's, so the RunStarter pauses it with this message rather than
+ * failing every tick. A missing schedule row or a store fault is an
+ * infrastructure throw, as for every other mint.
+ *
+ * The identity is `accountAsCaller(account)` (domain/identityaccount/
+ * actor.ts, the one construction of an account acting as itself): a
+ * `user` with no issuer and no token — open source reads no fire-scoped
+ * claims downstream, and the propagation lane stamps `origin:
+ * "in-process"` on it.
+ */
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { accountAsCaller } from "../domain/identityaccount/actor.js";
+import { accountForStamp } from "../domain/identityaccount/resolve.js";
+import type { AccountsByCaller } from "../domain/identityaccount/resolve.js";
+import type { ScheduleFireCallerMint } from "../extensions/schedule-fire-caller.js";
+import { ScheduleFireCallerRefusedError } from "../extensions/schedule-fire-caller.js";
+import { auditOf } from "../pipeline/steps/defaults.js";
+import type { Store } from "../store/interface.js";
+
+export interface BuiltInScheduleFireCallerDeps {
+  readonly store: Store;
+  /** The account port: the stamp is resolved as an account id, then as a direct subject. */
+  readonly accounts: AccountsByCaller;
+}
+
+/** The refusal's copy — written for the person who scheduled the run (the schedule's status carries it). */
+export function scheduleHasNoPersonMessage(scheduleId: string): string {
+  return `schedule ${scheduleId} was created by nobody this server recognizes as a person; recreate it while signed in`;
+}
+
+export function newBuiltInScheduleFireCaller(
+  deps: BuiltInScheduleFireCallerDeps,
+): ScheduleFireCallerMint {
+  return {
+    async mintFireCaller(_org, scheduleId) {
+      const schedule = await deps.store.getResource(
+        ApiResourceKind.schedule,
+        scheduleId,
+        ScheduleSchema,
+      );
+      const stamp =
+        auditOf(ScheduleSchema, schedule)?.specAudit?.createdBy?.id ?? "";
+      const account = await accountForStamp(deps.accounts, stamp);
+      if (account === undefined) {
+        throw new ScheduleFireCallerRefusedError(
+          scheduleHasNoPersonMessage(scheduleId),
+        );
+      }
+      return accountAsCaller(account);
+    },
+  };
+}