@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/authorization/evaluator.ts

@@ -0,0 +1,283 @@
+/**
+ * The evaluator — OpenFGA's check, over the built-in model and a tuple
+ * source, small because the model uses four rewrite forms and nothing
+ * else (model/rewrite.ts). `checkRelation(object, relation, person, context)`
+ * answers "does this person hold this relation on this object" the way
+ * the cloud's engine answers it over stored tuples, so the two editions
+ * share one meaning of authorization.
+ *
+ * The walk, in the order a `.fga` line reads:
+ *   - `this`: the tuples on (object, relation). A tuple counts only if
+ *     its subject's TYPE is in the line's restriction list — the check
+ *     OpenFGA makes at write time, made here at read time, so a derived
+ *     tuple the model no longer admits denies instead of allowing. An
+ *     object subject matches when it names one of the person's aliases;
+ *     a userset subject is resolved on its own object; the wildcard is
+ *     honoured only under its condition (`allow_public` reads the
+ *     context's `allow`; an unknown condition is a fault).
+ *   - `computed`: the same object, another relation.
+ *   - `from`: every object the tupleset relation links to (again within
+ *     the tupleset line's type restriction), resolved for the relation.
+ *   - `union`: the first true member wins; members are tried in the
+ *     line's order, so the cheap arms the model lists first (the person's
+ *     own owner tuple) are read before the hops.
+ *
+ * Bounds and faults. Every (object, relation) pair is resolved once per
+ * check (the memo — a diamond such as `owner` reached through `viewer`
+ * and through `can_edit` reads the source once). A pair re-entered while
+ * it is being resolved is a cycle in the declarations, which is a bug,
+ * and a resolution deeper than MAX_RESOLUTION_DEPTH is the same class of
+ * bug; both throw, because the alternative — a quiet `false` — would turn
+ * a broken transcript into a lockout nobody can see. A kind the model does
+ * not declare is a fault as the check's TARGET (the driver refuses
+ * unserved kinds before evaluation, so reaching here is a registry gap)
+ * and simply an object with no relations when reached through a tuple
+ * (`identity_provider#platform_user`, which no open-source tuple names).
+ * A relation the kind does not declare is `false` — the ruled answer for
+ * a wire question the model has no line for, where OpenFGA
+ * itself answers a validation error.
+ *
+ * The evaluator does no I/O of its own and knows no store: the source
+ * owns every read, and a fault it raises propagates through untouched,
+ * so the driver above can fold it into `unavailable` and never into a
+ * denial.
+ */
+import type { Model } from "./model/index.js";
+import type { Rewrite, SubjectType } from "./model/rewrite.js";
+import type {
+  CheckContext,
+  ObjectRef,
+  Person,
+  Subject,
+  TupleSource,
+} from "./tuples.js";
+import {
+  ACCOUNT_TYPE,
+  ALLOW_PUBLIC_CONDITION,
+  formatObjectRef,
+  pairKey,
+} from "./tuples.js";
+
+/**
+ * OpenFGA's default resolution-depth limit (its `resolveNodeLimit`), so
+ * the bound here is the oracle's own and not a number chosen locally. The
+ * deepest real chain in the model is under ten: an instance's `viewer
+ * from default_of` to its blueprint, the blueprint's `admin from
+ * organization`, then the organization's four-rung ladder.
+ */
+export const MAX_RESOLUTION_DEPTH = 25;
+
+export type EvaluationFault =
+  | "undeclared-target-kind"
+  | "resolution-depth-exceeded"
+  | "resolution-cycle"
+  | "unknown-condition";
+
+/** A fault in the model or its evaluation — never a denial; the driver maps it to `unavailable`. */
+export class AuthorizationEvaluationError extends Error {
+  readonly reason: EvaluationFault;
+
+  constructor(reason: EvaluationFault, message: string) {
+    super(message);
+    this.name = "AuthorizationEvaluationError";
+    this.reason = reason;
+  }
+}
+
+export interface EvaluationDeps {
+  readonly model: Model;
+  readonly source: TupleSource;
+}
+
+export async function checkRelation(
+  deps: EvaluationDeps,
+  object: ObjectRef,
+  relation: string,
+  person: Person,
+  context: CheckContext,
+): Promise<boolean> {
+  if (deps.model.byType(object.type) === undefined) {
+    throw new AuthorizationEvaluationError(
+      "undeclared-target-kind",
+      `no declaration for kind '${object.type}' (target ${formatObjectRef(object)})`,
+    );
+  }
+  return new Walk(deps, person, context).resolve(object, relation, 0);
+}
+
+/** One check's state: the memo and the in-progress set, over one source. */
+class Walk {
+  private readonly memo = new Map<string, Promise<boolean>>();
+  private readonly inProgress = new Set<string>();
+
+  constructor(
+    private readonly deps: EvaluationDeps,
+    private readonly person: Person,
+    private readonly context: CheckContext,
+  ) {}
+
+  resolve(
+    object: ObjectRef,
+    relation: string,
+    depth: number,
+  ): Promise<boolean> {
+    const key = pairKey(object, relation);
+    if (this.inProgress.has(key)) {
+      throw new AuthorizationEvaluationError(
+        "resolution-cycle",
+        `'${key}' re-entered while being resolved — the declarations cycle`,
+      );
+    }
+    if (depth > MAX_RESOLUTION_DEPTH) {
+      throw new AuthorizationEvaluationError(
+        "resolution-depth-exceeded",
+        `resolving '${key}' exceeded ${MAX_RESOLUTION_DEPTH} hops`,
+      );
+    }
+    const held = this.memo.get(key);
+    if (held !== undefined) {
+      return held;
+    }
+    const declaration = this.deps.model.byType(object.type);
+    const rewrite = declaration?.relations.get(relation);
+    if (declaration === undefined || rewrite === undefined) {
+      return Promise.resolve(false);
+    }
+    this.inProgress.add(key);
+    const result = this.evaluate(rewrite, object, relation, depth).finally(() =>
+      this.inProgress.delete(key),
+    );
+    this.memo.set(key, result);
+    return result;
+  }
+
+  private async evaluate(
+    rewrite: Rewrite,
+    object: ObjectRef,
+    relation: string,
+    depth: number,
+  ): Promise<boolean> {
+    switch (rewrite.node) {
+      case "this": {
+        const tuples = await this.deps.source.tuplesOf(object, relation);
+        for (const tuple of tuples) {
+          if (await this.subjectHolds(tuple.subject, rewrite.subjects, depth)) {
+            return true;
+          }
+        }
+        return false;
+      }
+      case "computed":
+        return this.resolve(object, rewrite.relation, depth + 1);
+      case "from": {
+        const linkTypes = this.objectTypesOf(object, rewrite.tupleset);
+        const links = await this.deps.source.tuplesOf(object, rewrite.tupleset);
+        for (const link of links) {
+          if (
+            link.subject.form === "object" &&
+            linkTypes.has(link.subject.object.type) &&
+            (await this.resolve(
+              link.subject.object,
+              rewrite.relation,
+              depth + 1,
+            ))
+          ) {
+            return true;
+          }
+        }
+        return false;
+      }
+      case "union": {
+        for (const member of rewrite.members) {
+          if (await this.evaluate(member, object, relation, depth)) {
+            return true;
+          }
+        }
+        return false;
+      }
+      default: {
+        const exhaustive: never = rewrite;
+        throw new Error(`unknown rewrite node: ${JSON.stringify(exhaustive)}`);
+      }
+    }
+  }
+
+  /** Whether one direct tuple's subject reaches the person, within the line's type restriction. */
+  private async subjectHolds(
+    subject: Subject,
+    restriction: ReadonlyArray<SubjectType>,
+    depth: number,
+  ): Promise<boolean> {
+    switch (subject.form) {
+      case "object":
+        return (
+          subject.object.type === ACCOUNT_TYPE &&
+          restriction.some(
+            (allowed) =>
+              allowed.form === "object" && allowed.type === ACCOUNT_TYPE,
+          ) &&
+          this.person.aliases.has(subject.object.id)
+        );
+      case "userset":
+        return (
+          restriction.some(
+            (allowed) =>
+              allowed.form === "userset" &&
+              allowed.type === subject.object.type &&
+              allowed.relation === subject.relation,
+          ) && (await this.resolve(subject.object, subject.relation, depth + 1))
+        );
+      case "wildcard": {
+        const allowed = restriction.some(
+          (entry) =>
+            entry.form === "wildcard" &&
+            entry.type === subject.type &&
+            entry.condition === subject.condition,
+        );
+        return allowed && this.conditionHolds(subject.condition);
+      }
+      default: {
+        const exhaustive: never = subject;
+        throw new Error(`unknown subject form: ${JSON.stringify(exhaustive)}`);
+      }
+    }
+  }
+
+  private conditionHolds(condition: string | undefined): boolean {
+    switch (condition) {
+      case ALLOW_PUBLIC_CONDITION:
+        return this.context.allow;
+      default:
+        throw new AuthorizationEvaluationError(
+          "unknown-condition",
+          `the model declares no condition '${String(condition)}'`,
+        );
+    }
+  }
+
+  /** The object types the tupleset line admits — `[organization]`, `[session]` — from its `this` nodes. */
+  private objectTypesOf(
+    object: ObjectRef,
+    tupleset: string,
+  ): ReadonlySet<string> {
+    const rewrite = this.deps.model
+      .byType(object.type)
+      ?.relations.get(tupleset);
+    const types = new Set<string>();
+    const collect = (node: Rewrite): void => {
+      if (node.node === "this") {
+        for (const subject of node.subjects) {
+          if (subject.form === "object") {
+            types.add(subject.type);
+          }
+        }
+      } else if (node.node === "union") {
+        node.members.forEach(collect);
+      }
+    };
+    if (rewrite !== undefined) {
+      collect(rewrite);
+    }
+    return types;
+  }
+}

package/src/authorization/facts.ts

@@ -0,0 +1,47 @@
+/**
+ * The facts a stored row carries that its authorization tuples are
+ * derived from, as the built-in authorizer names them — the seam's
+ * `RowAuthorizationFacts` (extensions/resource-authorization.ts) with the
+ * kind beside them, because the derivation (derived-tuples.ts) reads the
+ * kind's `kind_meta` and names the object by its type.
+ *
+ * The facts have two producers and one resolver. A LOADED row (the
+ * point-check driver's path, `rowFactsOf`) and a list lane's candidate
+ * (`ListEntryMeta`, built by the lanes' shared helper; `rowFactsOfEntry`)
+ * both read through pipeline/steps/authorization-facts.ts — the read-time
+ * twin of the tuple lifecycle's create-time resolution, lenient where that
+ * one throws (a legacy row's missing organization is a fact, not a fault),
+ * and pinned equal to it in __tests__/facts.test.ts. Naming the shape once
+ * is what lets the derivation stay one function and what states exactly
+ * which facts a list candidate must carry: a candidate's facts ARE these,
+ * so a list evaluates the model over what the lane already decoded and
+ * never reads a candidate's row a second time.
+ */
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { RowAuthorizationFacts } from "../extensions/resource-authorization.js";
+import { rowAuthorizationFactsOf } from "../pipeline/steps/authorization-facts.js";
+
+export interface RowFacts extends RowAuthorizationFacts {
+  readonly kind: ApiResourceKind;
+}
+
+/** The facts of a loaded row of `kind`. */
+export function rowFactsOf(kind: ApiResourceKind, row: object): RowFacts {
+  return { kind, ...rowAuthorizationFactsOf(kind, row) };
+}
+
+/** The facts a list candidate of `kind` carries — the same facts, already read by the lane's helper. */
+export function rowFactsOfEntry(
+  kind: ApiResourceKind,
+  entry: RowAuthorizationFacts,
+): RowFacts {
+  return {
+    kind,
+    id: entry.id,
+    org: entry.org,
+    visibility: entry.visibility,
+    createdBy: entry.createdBy,
+    parentLinks: entry.parentLinks,
+  };
+}

package/src/authorization/lane-admission.ts

@@ -0,0 +1,73 @@
+/**
+ * Lane admission over the Authorizer seam — open source's rendering of
+ * the cloud's decorator (stigmer-cloud `authorizer/lane-admission.ts`,
+ * stigmer-cloud#709), composed around the built-in Authorizer under the
+ * built-in authorization posture (boot/compose.ts).
+ *
+ * The OSS AuthorizeRunTarget step asks the Authorizer, for every caller
+ * but the internal class, whether the caller may run what a session or
+ * execution targets — the run-gate checks (`isRunGateCheck`, the
+ * OSS-owned definition of that set: `can_execute` on the blueprints and
+ * instances, `can_create_execution_in` on a session). A runner acting
+ * for a WORKFLOW execution creates the workflow's child agent executions
+ * (the `agent_call` activity), and it does so AS THE HUMAN whose workflow
+ * it is (runnerauth/runner-subject-verifier.ts). Checked as that human,
+ * a member running an organization-visible workflow that calls another
+ * member's private agent would be refused at the child create — but
+ * the parent workflow execution already passed its own run gate, and
+ * the human's visibility of the agents a shared workflow calls is not
+ * the question. The cloud admits its `workflow_sandbox` lane on exactly
+ * these checks for exactly this reason; this decorator gives an
+ * enforcing self-host the same answer, so a workflow behaves the same in
+ * both editions (the parent program's rule: nothing diverges silently).
+ *
+ * Why a predicate and not a class set: the cloud keys its decorator on
+ * `callerClass` because there the class IS the token type. In open
+ * source the class is `runner` for every bound execution, and the
+ * binding's KIND lives in the token, readable by the one function that
+ * interprets runner tokens (`isWorkflowBoundRunner` in
+ * runnerauth/built-in-runner-credential-provider.ts). Handing that
+ * reading in as `isAdmittedLane` keeps this module free of token
+ * knowledge and lets the cloud adopt the same shape later without a
+ * second class name. An AGENT-bound runner is NOT admitted: a subagent
+ * create is checked as the human, the cloud's `sandbox` posture.
+ *
+ * Narrow by construction: an admitted lane on any NON-run-gate check,
+ * and any other caller on any check, delegate untouched. The cloud's
+ * header records one caveat — a human who can view a workflow execution
+ * can exchange for its token and replay it against the run gate. Open
+ * source has no such caveat: under this posture the exchange is a mint
+ * gate that answers only the run's own person (the built-in provider's
+ * exchangeScopedToken, runnerauth/built-in-runner-credential-provider.ts),
+ * so the only human who can hold a workflow's credential is the one whose
+ * workflow it is — and their own run gate already passed.
+ */
+import type { CallerIdentity } from "../extensions/identity.js";
+import type {
+  Authorizer,
+  AuthzCheck,
+  AuthzDecision,
+} from "../extensions/authorizer.js";
+import { isRunGateCheck } from "../pipeline/steps/authorize-run-target.js";
+
+const ADMITTED: AuthzDecision = { kind: "allow" };
+
+/** Whether `caller` is a lane whose admission to CREATE a run was decided upstream. */
+export type LaneAdmissionPredicate = (caller: CallerIdentity) => boolean;
+
+export function newLaneAdmittedAuthorizer(
+  inner: Authorizer,
+  isAdmittedLane: LaneAdmissionPredicate,
+): Authorizer {
+  return {
+    authorize(
+      caller: CallerIdentity,
+      check: AuthzCheck,
+    ): Promise<AuthzDecision> {
+      if (isRunGateCheck(check) && isAdmittedLane(caller)) {
+        return Promise.resolve(ADMITTED);
+      }
+      return inner.authorize(caller, check);
+    },
+  };
+}

package/src/authorization/list-read-scope.ts

@@ -0,0 +1,216 @@
+/**
+ * The built-in list read scope — open source's driver for the list-read
+ * seam (extensions/list-read-scope.ts), composed under the built-in
+ * posture (posture.ts). The cloud's driver asks OpenFGA `can_view` for
+ * every candidate a list lane offers and ListObjects for the enumeration
+ * lanes; this one asks the same question of the same model, evaluated by
+ * the same evaluator the built-in Authorizer uses (evaluator.ts), over
+ * the tuples each candidate's row would have had — derived from the
+ * facts the candidate already carries (`ListEntryMeta` is the row's
+ * `RowAuthorizationFacts`; facts.ts), so a list never reads a candidate's
+ * row a second time. A self-host's lists show a person exactly what a
+ * `get` would let them read.
+ *
+ * Both verbs ask under the LISTING context, `allow: false` — the public
+ * wildcard suppressed, the cloud's own posture (its Java
+ * listAuthorizedResourceIds set it): a legacy PUBLIC row reads for any
+ * signed-in person on a point check and never expands into an outsider's
+ * listing; the organization's own people still reach it through the
+ * org-viewer shape public also emits.
+ *
+ *   - `restrictListEntries`: one derived source for the caller, seeded
+ *     with every candidate's facts; one `checkRelation` per unique id —
+ *     one evaluator walk per candidate, never shared, because the walk's
+ *     memo and its cycle detector are one object and a shared walk would
+ *     read a second candidate's in-flight resolution of the same pair as
+ *     a cycle. The candidates run concurrently: the only shared state is
+ *     the source, whose promise memo dedupes the loads (the person's rows
+ *     once; each distinct parent once — an execution list reads its
+ *     distinct SESSIONS, entry 9's parent-check exactly). The kept set is
+ *     a subset of the offered ids; order is the lane's.
+ *   - `authorizedResourceIds`: the kind scanned, decoded and evaluated
+ *     the same way. There is no tuple index to enumerate from and the
+ *     answer is genuinely not "everything" (private blueprints exist), so
+ *     the verb costs one scan of the kind — the console library rides
+ *     it (blueprints have no list RPC; the library is a search), measured
+ *     and recorded rather than assumed. A row that does not decode is
+ *     skipped with a warning, the `loadAll*` idiom every lane follows: no
+ *     lane can show it either.
+ *
+ * The `internal` class — the server acting as itself over the in-process
+ * transport — keeps every offered id and enumerates every id of the kind:
+ * the in-process authorization skip (pipeline/interceptors/auth.ts, ruling
+ * Q4) applied to a list answer, as the built-in directory applies it to a
+ * directory answer. No in-process edge reaches a list lane today; the arm
+ * is pinned so a future one meets the same rule every other lane keeps.
+ *
+ * Faults THROW and are never an empty answer (the seam: an empty set means
+ * "authorized to see nothing"; an outage is the pipeline's sanitized
+ * INTERNAL). A kind the model does not declare is a consumer bug by the
+ * seam's contract and faults through the evaluator, loud; the model
+ * declares exactly the open-source tier, so no served lane can reach it.
+ *
+ * Logging. One debug line per call — kind, offered, kept, elapsed — what
+ * an operator needs to answer "why is Alice's list short" beside the
+ * Authorizer's per-denial lines; never the token.
+ */
+import { fromBinary } from "@bufbuild/protobuf";
+
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Logger } from "../boot/logger.js";
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
+import type { CallerIdentity } from "../extensions/identity.js";
+import type {
+  ListEntryMeta,
+  ListReadScope,
+} from "../extensions/list-read-scope.js";
+import { kindEnumName } from "../pipeline/apiresource-meta.js";
+import type { Store } from "../store/interface.js";
+import { newDerivedTupleSource } from "./derived-tuples.js";
+import { AuthorizationEvaluationError, checkRelation } from "./evaluator.js";
+import type { RowFacts } from "./facts.js";
+import { rowFactsOf, rowFactsOfEntry } from "./facts.js";
+import type { Model } from "./model/index.js";
+import { builtInModel } from "./model/index.js";
+import type { KindDeclaration } from "./model/rewrite.js";
+import type { AccountsByCaller } from "./person.js";
+import { resolvePerson } from "./person.js";
+import type { CheckContext, ObjectRef, Person } from "./tuples.js";
+
+/** The relation every list lane reads through (the cloud's LIST_RELATION). */
+const LIST_RELATION = "can_view";
+
+/** The listing context: the public wildcard suppressed (the module header). */
+const LISTING: CheckContext = { allow: false };
+
+export interface BuiltInListReadScopeDeps {
+  readonly store: Store;
+  /** The port the grant path writes through — the person's rows are read from the same instance. */
+  readonly policies: IamPolicyStore;
+  /** The account port: the caller's account, and the parent hops that land on one. */
+  readonly accounts: AccountsByCaller;
+  readonly logger: Logger;
+  /** The declarations to evaluate; the built-in model unless a test says otherwise. */
+  readonly model?: Model;
+}
+
+export function newBuiltInListReadScope(
+  deps: BuiltInListReadScopeDeps,
+): ListReadScope {
+  const model = deps.model ?? builtInModel;
+
+  /** The candidates the caller may view, each answered by its own walk over one seeded source. */
+  async function visibleAmong(
+    caller: CallerIdentity,
+    kind: ApiResourceKind,
+    candidates: ReadonlyArray<RowFacts>,
+  ): Promise<ReadonlySet<string>> {
+    if (candidates.length === 0) {
+      return new Set();
+    }
+    const started = performance.now();
+    const person: Person = await resolvePerson(deps.accounts, caller);
+    const source = newDerivedTupleSource(
+      {
+        store: deps.store,
+        policies: deps.policies,
+        accounts: deps.accounts,
+        model,
+      },
+      person,
+      { facts: candidates },
+    );
+    const type = kindEnumName(kind);
+    const answers = await Promise.all(
+      candidates.map(async (facts) => {
+        const object: ObjectRef = { type, id: facts.id };
+        const allowed = await checkRelation(
+          { model, source },
+          object,
+          LIST_RELATION,
+          person,
+          LISTING,
+        );
+        return allowed ? facts.id : undefined;
+      }),
+    );
+    const kept = new Set<string>();
+    for (const id of answers) {
+      if (id !== undefined) {
+        kept.add(id);
+      }
+    }
+    deps.logger.debug("list scope evaluated candidates", {
+      account: person.accountId,
+      kind: type,
+      offered: candidates.length,
+      kept: kept.size,
+      elapsedMs: Math.round(performance.now() - started),
+    });
+    return kept;
+  }
+
+  /** The declaration a verb evaluates against; an undeclared kind is the evaluator's own fault, raised before any read. */
+  function requireDeclared(kind: ApiResourceKind): KindDeclaration {
+    const declaration = model.byKind(kind);
+    if (declaration === undefined) {
+      throw new AuthorizationEvaluationError(
+        "undeclared-target-kind",
+        `no declaration for kind '${kindEnumName(kind)}' — a list lane asked the scope about a kind the model does not declare`,
+      );
+    }
+    return declaration;
+  }
+
+  /** Every row of `kind` the store holds, as facts; a row that does not decode is skipped. */
+  async function everyRowOf(declaration: KindDeclaration): Promise<RowFacts[]> {
+    const kind = declaration.kind;
+    const rows = await deps.store.listResources(kind);
+    const facts: RowFacts[] = [];
+    for (const bytes of rows) {
+      try {
+        facts.push(rowFactsOf(kind, fromBinary(declaration.schema, bytes)));
+      } catch (error) {
+        deps.logger.warn("list scope skipped a row that does not decode", {
+          kind: kindEnumName(kind),
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return facts;
+  }
+
+  return {
+    async restrictListEntries(
+      caller: CallerIdentity,
+      kind: ApiResourceKind,
+      entries: ReadonlyArray<ListEntryMeta>,
+    ): Promise<ReadonlySet<string>> {
+      requireDeclared(kind);
+      // One candidate per unique id: a lane offers each row once, and a
+      // duplicate would only spend a walk to learn the same answer.
+      const unique = new Map<string, RowFacts>();
+      for (const entry of entries) {
+        if (!unique.has(entry.id)) {
+          unique.set(entry.id, rowFactsOfEntry(kind, entry));
+        }
+      }
+      if (caller.callerClass === "internal") {
+        return new Set(unique.keys());
+      }
+      return visibleAmong(caller, kind, [...unique.values()]);
+    },
+
+    async authorizedResourceIds(
+      caller: CallerIdentity,
+      kind: ApiResourceKind,
+    ): Promise<ReadonlySet<string>> {
+      const candidates = await everyRowOf(requireDeclared(kind));
+      if (caller.callerClass === "internal") {
+        return new Set(candidates.map((facts) => facts.id));
+      }
+      return visibleAmong(caller, kind, candidates);
+    },
+  };
+}