@stigmer/server 3.40.1 → 3.41.0

package/src/authorization/model/execution-viewer.ts

@@ -11,13 +11,21 @@
  * `#execution_viewer@organization:<org>#viewer`, the organization's full
  * read audience (the relation also admits `#member`, the legacy shape),
  * and `private` or unset derives nothing, so each run stays its
- * triggerer's. Pure over the row; no related row is read.
+ * triggerer's. Pure over the row; no related row is read. Which level
+ * names which audience is `executionAudienceShapes`
+ * (pipeline/steps/authorization-tuples.ts), the one mapping this
+ * derivation and the lifecycle event a tuple-storing edition hears both
+ * read, so the two editions cannot disagree about who sees the runs.
  */
 import { isMessage } from "@bufbuild/protobuf";
 
 import { WorkflowInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
 import { WorkflowExecutionVisibility } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/spec_pb";
 
+import { executionAudienceShapes } from "../../pipeline/steps/authorization-tuples.js";
+
+import type { Tuple } from "../tuples.js";
+
 import type { DerivedRelation } from "./rewrite.js";
 
 export const executionViewer: DerivedRelation = (object, row) => {
@@ -26,31 +34,28 @@ export const executionViewer: DerivedRelation = (object, row) => {
   }
   const level =
     row.spec?.executionVisibility ?? WorkflowExecutionVisibility.unspecified;
-  switch (level) {
-    case WorkflowExecutionVisibility.organization: {
-      const org = row.metadata?.org ?? "";
-      return Promise.resolve(
-        org === ""
-          ? []
-          : [
-              {
-                object,
-                relation: "execution_viewer",
-                subject: {
-                  form: "userset",
-                  object: { type: "organization", id: org },
-                  relation: "viewer",
-                },
-              },
-            ],
-      );
-    }
-    case WorkflowExecutionVisibility.private:
-    case WorkflowExecutionVisibility.unspecified:
-      return Promise.resolve([]);
-    default: {
-      const exhaustive: never = level;
-      throw new Error(`unknown execution visibility: ${String(exhaustive)}`);
-    }
+  const org = row.metadata?.org ?? "";
+  if (org === "") {
+    return Promise.resolve([]);
   }
+  return Promise.resolve(
+    [...executionAudienceShapes(level)].map((shape): Tuple => {
+      switch (shape) {
+        case "org-viewer":
+          return {
+            object,
+            relation: "execution_viewer",
+            subject: {
+              form: "userset",
+              object: { type: "organization", id: org },
+              relation: "viewer",
+            },
+          };
+        default: {
+          const exhaustive: never = shape;
+          throw new Error(`unknown execution audience: ${String(exhaustive)}`);
+        }
+      }
+    }),
+  );
 };

package/src/authorization/model/index.ts

@@ -18,7 +18,10 @@
  * evaluation (authorizer.ts, `kindServedByEdition`): open source refuses a
  * check that targets `team`, `identity_provider`, `invitation` or
  * `platform`, and a tuple that names one resolves over tuples alone, since
- * this edition stores no row of those kinds.
+ * open source stores no row of those kinds. An edition that serves them
+ * keeps their rows in its units' own stores and registers a reader for
+ * each (extensions/resource-row-reader.ts), which the derivation reads them
+ * through.
  *
  * `newModel` exists for tests that need a throwaway model (a cycle, a
  * chain past the depth bound).

package/src/authorization/model/rewrite.ts

@@ -15,10 +15,12 @@
  *   define can_view: viewer                    → computed("viewer")
  *
  * `and` exists for one shape: a relation that is true only while another
- * holds too (a team's member is a person granted the role AND still one
+ * holds too. Every direct grant on an organization-scoped type is bounded
+ * that way (`([identity_account] and affiliated from organization) or
+ * ...`), and a team's member is a person granted the role AND still one
  * of the organization's viewers, so leaving the organization ends every
- * team-derived grant with no cleanup). Operators nest to any depth, as
- * the DSL's parentheses allow; the evaluator recurses through them.
+ * grant with no cleanup. Operators nest to any depth, as the DSL's
+ * parentheses allow; the evaluator recurses through them.
  * `but not`, wildcards (`type:*`) and conditions have no form here: the
  * reader refuses them by name, and the day the model needs one is a
  * design act.

package/src/authorization/organization-directory.ts

@@ -42,6 +42,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 
 import type { IamPolicyStore } from "../domain/iampolicy/store.js";
 import type { CallerIdentity } from "../extensions/identity.js";
+import type { ResourceRowReader } from "../extensions/resource-row-reader.js";
 import type { OrganizationDirectory } from "../extensions/organization-directory.js";
 import { ALL_ORGANIZATIONS } from "../extensions/organization-directory.js";
 import { kindEnumName } from "../pipeline/apiresource-meta.js";
@@ -57,6 +58,8 @@ export interface BuiltInOrganizationDirectoryDeps {
   readonly store: Store;
   readonly policies: IamPolicyStore;
   readonly accounts: AccountsByCaller;
+  /** The readers of the kinds units keep themselves (`drivers.resourceRowReaders`), handed to every tuple source. */
+  readonly rowReaders?: ReadonlyMap<ApiResourceKind, ResourceRowReader>;
   readonly model?: Model;
 }
 
@@ -81,6 +84,7 @@ export function newBuiltInOrganizationDirectory(
           store: deps.store,
           policies: deps.policies,
           accounts: deps.accounts,
+          rowReaders: deps.rowReaders,
           model,
         },
         person,

package/src/authorization/person.ts

@@ -4,13 +4,17 @@
  * 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:
+ * The 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`.
  *
+ *   `personOfAccount(accounts, id)` — the person an account id names
+ *   when no caller stands for them (an invitation's creator), with the
+ *   same alias rule.
+ *
  *   `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
@@ -35,6 +39,7 @@ import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityacc
 
 import { isPersonStamp } from "../domain/iampolicy/membership.js";
 import type { AccountsByCaller } from "../domain/identityaccount/resolve.js";
+import type { IdentityAccountStore } from "../domain/identityaccount/store.js";
 import { accountForCaller } from "../domain/identityaccount/resolve.js";
 import type { CallerIdentity } from "../extensions/identity.js";
 import type { Person } from "./tuples.js";
@@ -51,6 +56,32 @@ export function personFor(
       `caller '${accountId}' names no person — the built-in authorizer evaluates people only`,
     );
   }
+  return withAliases(accountId, account);
+}
+
+/**
+ * The person an account id names when no caller stands for them: the
+ * creator of an invitation, asked whether they could still grant what it
+ * grants. The alias rule is `personFor`'s: the id itself, and the issuer
+ * subject when the account is found. An account that is gone is its id
+ * alone, and the rows that still name it are what the check reads.
+ */
+export async function personOfAccount(
+  accounts: Pick<IdentityAccountStore, "findById">,
+  accountId: string,
+): Promise<Person> {
+  if (!isPersonStamp(accountId)) {
+    throw new Error(
+      `account '${accountId}' names no person — the built-in authorizer evaluates people only`,
+    );
+  }
+  return withAliases(accountId, await accounts.findById(accountId));
+}
+
+function withAliases(
+  accountId: string,
+  account: IdentityAccount | undefined,
+): Person {
   const aliases = new Set<string>([accountId]);
   const subject = account?.spec?.idpId ?? "";
   if (subject !== "") {

package/src/authorization/policy-check.ts

@@ -0,0 +1,105 @@
+/**
+ * The built-in policy check — the one question of the authorization-query
+ * engine (extensions/authorization-queries.ts, `check`) that the built-in
+ * posture can answer from its own evaluator: "is this policy effectively
+ * held". A unit composed on the built-in posture asks it through the
+ * services the composition hands it (extensions/registry.ts,
+ * `ComposedServices`), exactly where a composition with its own engine
+ * hands that engine's `check`, so the unit asks one question in every
+ * edition and the model answers it one way.
+ *
+ * What it answers, and why no more:
+ *   - A policy whose principal is a person (`identity_account:<id>`): the
+ *     person the id names, with `personFor`'s alias rule (person.ts), and
+ *     the rows they and their teams hold — the same walk a point check
+ *     makes for a caller.
+ *   - A policy whose principal is any other object (`organization:<o>`):
+ *     the structural question a grant to a team asks — does this resource
+ *     belong to the team's organization — answered by the resource's own
+ *     derived links (derived-tuples.ts).
+ *   - Contextual policies are refused as a programming error. No caller
+ *     asks with them, and the derived source has no notion of a tuple held
+ *     only for the length of one check; answering without them would be a
+ *     silent wrong answer, the failure a throw prevents.
+ *   - A userset principal (`organization:<o>#member`) is refused the same
+ *     way: the engine contract checks direct principals.
+ *
+ * The engine's list verbs are not answered here: they enumerate, which the
+ * built-in posture does not do, and the tuple-half RPCs that expose them
+ * keep refusing in open source without an engine. One source per check,
+ * like the Authorizer: its memo is the check's. Faults propagate; the
+ * caller's own error mapping decides the wire.
+ */
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
+import type { IdentityAccountStore } from "../domain/identityaccount/store.js";
+import type { AuthorizationQueryEngine } from "../extensions/authorization-queries.js";
+import type { ResourceRowReader } from "../extensions/resource-row-reader.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 { personOfAccount } from "./person.js";
+import type { Principal } from "./tuples.js";
+import { ACCOUNT_TYPE } from "./tuples.js";
+
+export interface BuiltInPolicyCheckDeps {
+  readonly store: Store;
+  /** The port the grant path writes through — the principal's rows are read from the same instance. */
+  readonly policies: IamPolicyStore;
+  /** The account port: a person principal's aliases, and identity_account objects. */
+  readonly accounts: Pick<IdentityAccountStore, "findById">;
+  /** The readers of the kinds units keep themselves (`drivers.resourceRowReaders`). */
+  readonly rowReaders?: ReadonlyMap<ApiResourceKind, ResourceRowReader>;
+  /** The declarations to evaluate; the built-in model unless a test says otherwise. */
+  readonly model?: Model;
+}
+
+export function newBuiltInPolicyCheck(
+  deps: BuiltInPolicyCheckDeps,
+): Pick<AuthorizationQueryEngine, "check"> {
+  const model = deps.model ?? builtInModel;
+  return {
+    async check(policy, contextualPolicies) {
+      if (contextualPolicies.length > 0) {
+        throw new Error(
+          "the built-in policy check evaluates held policies only — contextual policies are not supported",
+        );
+      }
+      const principalRef = policy.principal;
+      const resource = policy.resource;
+      if (principalRef === undefined || resource === undefined) {
+        throw new Error(
+          "the built-in policy check needs a principal and a resource",
+        );
+      }
+      if (principalRef.relation !== "") {
+        throw new Error(
+          `the built-in policy check takes a direct principal — '${principalRef.kind}:${principalRef.id}#${principalRef.relation}' is a userset`,
+        );
+      }
+      const principal: Principal =
+        principalRef.kind === ACCOUNT_TYPE
+          ? await personOfAccount(deps.accounts, principalRef.id)
+          : { object: { type: principalRef.kind, id: principalRef.id } };
+      const source = newDerivedTupleSource(
+        {
+          store: deps.store,
+          policies: deps.policies,
+          accounts: deps.accounts,
+          rowReaders: deps.rowReaders,
+          model,
+        },
+        principal,
+      );
+      return checkRelation(
+        { model, source },
+        { type: resource.kind, id: resource.id },
+        policy.relation,
+        principal,
+      );
+    },
+  };
+}

package/src/authorization/posture.ts

@@ -14,19 +14,34 @@
  *     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.
+ *     tuples — so the roles 2b records are enforced. An edition above
+ *     open source may run it too, once every kind it serves has rows the
+ *     derivation can read (`kindsWithoutRows` below).
  *   - `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,
+ *     the laptop. The permissive driver (trusted-local-authorizer.ts): one
+ *     caller, nothing to separate, so every check is allowed except one
+ *     that names an Organization the server does not hold, which is
+ *     not-found as under the other two postures (stigmer#1163). 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.
+ *     Members page truthfully. Open source's edition only: a composition
+ *     serving an edition above it refuses to boot here, since an edition
+ *     of many organizations with no sign-in would act as the operator for
+ *     every request that carries no credential.
  *
  * 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.
  */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import type { ResourceRowReader } from "../extensions/resource-row-reader.js";
+import { kindServedByEdition } from "../pipeline/apiresource-meta.js";
+import type { Model } from "./model/index.js";
+
 export type AuthorizationPosture =
   | "trusted-local"
   | "built-in"
@@ -47,3 +62,29 @@ export function authorizationPostureOf(
   }
   return inputs.requireAuthentication ? "built-in" : "trusted-local";
 }
+
+/**
+ * The kinds an edition serves whose rows the built-in authorizer could not
+ * read: declared by the model with a row schema, served by the edition,
+ * not served by open source (whose kinds are its own store's), and not
+ * `identity_account` (read through the account port), with no reader
+ * registered for them. Empty means the built-in posture can answer every
+ * check the edition's lanes make. The composition root refuses a built-in
+ * posture that leaves any, rather than answer from rows that are not there.
+ */
+export function kindsWithoutRows(inputs: {
+  readonly edition: ServerEdition;
+  readonly model: Model;
+  readonly readers: ReadonlyMap<ApiResourceKind, ResourceRowReader>;
+}): ReadonlyArray<ApiResourceKind> {
+  return inputs.model.declarations
+    .filter(
+      (declaration) =>
+        declaration.schema !== undefined &&
+        declaration.kind !== ApiResourceKind.identity_account &&
+        kindServedByEdition(declaration.kind, inputs.edition) &&
+        !kindServedByEdition(declaration.kind, ServerEdition.oss) &&
+        !inputs.readers.has(declaration.kind),
+    )
+    .map((declaration) => declaration.kind);
+}

package/src/authorization/resource-creators.ts

@@ -0,0 +1,48 @@
+/**
+ * The removal sweep's one read outside the policy rows: a stored
+ * resource's recorded creator (`ResourceCreators`,
+ * domain/iampolicy/grant-path.ts). When an account leaves an
+ * organization, the grant path keeps the rows that record the account as
+ * a resource's author, and only the resource's own row says who that is.
+ *
+ * The row is read through the generic store with the schema the built-in
+ * model binds to its kind, the same read the derived tuple source makes
+ * for a check (derived-tuples.ts `loadRow`), and the creator is the stamp
+ * that source derives an author's `owner` tuple from (`createdByOf`). A
+ * kind the model binds no schema to, or a row the store does not hold (a
+ * kind a composition keeps in its own table), has no recorded creator
+ * here, so no row of it is kept as authorship.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { ResourceCreators } from "../domain/iampolicy/grant-path.js";
+import { kindByEnumName } from "../pipeline/apiresource-meta.js";
+import { createdByOf } from "../pipeline/steps/authorization-facts.js";
+import type { Store } from "../store/interface.js";
+import { ResourceNotFoundError } from "../store/interface.js";
+import { builtInModel } from "./model/index.js";
+
+export function newStoreResourceCreators(store: Store): ResourceCreators {
+  return {
+    async creatorOf(kindName, id): Promise<string | undefined> {
+      const kind = kindByEnumName(kindName);
+      const schema = builtInModel.byKind(kind)?.schema;
+      if (
+        kind === ApiResourceKind.api_resource_kind_unknown ||
+        kind === ApiResourceKind.identity_account ||
+        schema === undefined ||
+        id === ""
+      ) {
+        return undefined;
+      }
+      try {
+        return createdByOf(await store.getResource(kind, id, schema));
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+  };
+}

package/src/authorization/trusted-local-authorizer.ts

@@ -0,0 +1,91 @@
+/**
+ * The trusted-local Authorizer — open source's driver for the one
+ * authorization decision seam (extensions/authorizer.ts) under the
+ * trusted-local posture (posture.ts): the laptop, a server with no sign-in.
+ * It separates no callers (there is one, the operator), so every check is
+ * `allow`, with one exception that is not a permission question at all.
+ *
+ * A check whose target is an Organization the store does not hold is
+ * `not-found`. "Does this Organization exist" is a load question, and
+ * every posture's Authorizer answers it the same way: the built-in
+ * driver's arm 4 (authorizer.ts) before any permission is evaluated, and
+ * the cloud's on its deny path (stigmer-cloud
+ * src/authorizer/fga-authorizer.ts, the existence probe). The Authorize
+ * step turns the arm into the load-first chain's NOT_FOUND,
+ * `Organization not found: <slug>`, so a server without sign-in refuses a
+ * write into a phantom Organization with the sentence a server with
+ * sign-in answers, instead of storing it under a slug nothing lists
+ * (stigmer#1163). Reads that name the Organization (a list by org, a
+ * usage report) are answered the same way, as they are under sign-in.
+ *
+ * Why the Organization alone. Every org-scoped lane authorizes on it (a
+ * create by `metadata.org`, a list or report by `org`/`org_id`), and its
+ * absence is the one no later step catches. The other kinds' update, get
+ * and delete chains load their target first and answer NOT_FOUND
+ * themselves, and a general existence read would refuse the rowless
+ * `platform` (model/bindings.ts), whose checks the laptop must keep
+ * allowing. An Organization's id is its slug (domain/organization/
+ * steps.ts), so the read is one primary key; the posture is open source's
+ * edition only (compose.ts refuses a wider edition without sign-in), so
+ * every Organization is a row in this store.
+ *
+ * Arms, in order: an empty target id is `allow` (a platform-scoped write
+ * names no Organization, and the Authorize step maps a not-found on an
+ * empty id to INTERNAL); a kind other than the Organization is `allow`
+ * with no read; a missing Organization is `not-found`; a present one is
+ * `allow`. A store fault is `unavailable` with its cause, the built-in
+ * driver's guard: an outage is never softened into a refusal of a
+ * different kind, and the driver never throws.
+ *
+ * Proven by __tests__/trusted-local-authorizer.test.ts (the arms, on both
+ * store drivers) and extensions/__tests__/built-in-authorization-
+ * composed.test.ts (the wire, beside the same sentence under sign-in).
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+
+import type {
+  Authorizer,
+  AuthzCheck,
+  AuthzDecision,
+} from "../extensions/authorizer.js";
+import { ResourceNotFoundError } from "../store/interface.js";
+import type { Store } from "../store/interface.js";
+
+/** The one read the driver makes: the Organization's row by id. */
+export type TrustedLocalAuthorizerStore = Pick<Store, "getResource">;
+
+export interface TrustedLocalAuthorizerDeps {
+  readonly store: TrustedLocalAuthorizerStore;
+}
+
+export function newTrustedLocalAuthorizer(
+  deps: TrustedLocalAuthorizerDeps,
+): Authorizer {
+  return {
+    async authorize(_caller, check: AuthzCheck): Promise<AuthzDecision> {
+      if (
+        check.resourceKind !== ApiResourceKind.organization ||
+        check.resourceId === ""
+      ) {
+        return { kind: "allow" };
+      }
+      try {
+        await deps.store.getResource(
+          ApiResourceKind.organization,
+          check.resourceId,
+          OrganizationSchema,
+        );
+        return { kind: "allow" };
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          return { kind: "not-found" };
+        }
+        return {
+          kind: "unavailable",
+          cause: error instanceof Error ? error : new Error(String(error)),
+        };
+      }
+    },
+  };
+}

package/src/authorization/tuples.ts

@@ -83,6 +83,23 @@ export interface Person {
   readonly aliases: ReadonlySet<string>;
 }
 
+/**
+ * An object other than a person that a check asks about: "does
+ * `organization:o` hold `organization` on this agent", the question a
+ * grant to a team asks before it names the team on a resource. It matches
+ * a tuple's subject by its own reference, with no aliases.
+ */
+export interface ObjectPrincipal {
+  readonly object: ObjectRef;
+}
+
+/** Whom a check asks about: a person through their aliases, or any other object by its reference. */
+export type Principal = Person | ObjectPrincipal;
+
+export function isPerson(principal: Principal): principal is Person {
+  return "accountId" in principal;
+}
+
 // ---------------------------------------------------------------------------
 // The string notation.
 // ---------------------------------------------------------------------------