@stigmer/server 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/authorization/authorizer.ts

@@ -0,0 +1,208 @@
+/**
+ * The built-in Authorizer — open source's driver for the one
+ * authorization decision seam (extensions/authorizer.ts), composed under
+ * the built-in posture (posture.ts): the cloud's model evaluated over the
+ * tuples this row would have had, derived on the fly (evaluator.ts over
+ * derived-tuples.ts). Every arm below mirrors the cloud's driver
+ * (stigmer-cloud src/authorizer/fga-authorizer.ts) by name and copy, so
+ * the two editions answer one question the same way and the drift test
+ * can pin the arms and not only the model.
+ *
+ * The arms, in order:
+ *   1. The cloud's four pre-checks with the Java service's copy, each a
+ *      `deny` with the reason: an unspecified permission, an empty
+ *      identity, an empty resource id, the unknown kind. No wire caller
+ *      reaches the unknown kind since the kind refusals landed; the
+ *      arm is the backstop, not a path.
+ *   2. A kind this edition does not serve is `deny` (`kindServedByEdition`,
+ *      the predicate 2b's `checkMyPermission` arm 1 uses, so the console
+ *      and the server agree by construction). `platform` is the one that
+ *      arrives, through `can_set_public_visibility` — under the built-in
+ *      posture nobody sets public visibility, the model's own reason for
+ *      making it a platform operator's act.
+ *   3. The caller as a person (person.ts) and one derived tuple source for
+ *      them; the target loaded ONCE through the source's memoised loader,
+ *      so the read that decides not-found is the read the derivation
+ *      uses.
+ *   4. A missing target is `not-found` — the Authorize step answers the
+ *      load-first chain's NOT_FOUND (stigmer#224) — EXCEPT for the kinds
+ *      the cloud never probes (NOT_FOUND_EXEMPT_KINDS): there a missing
+ *      row is evaluated like any other and denies, so an authenticated
+ *      member cannot learn which account ids exist. Present or exempt, the
+ *      row is then evaluated: the cloud asks OpenFGA whether or not the row
+ *      exists, and so does this driver.
+ *   5. `checkRelation` with the point-check context (`allow: true`: a
+ *      public resource reads for any authenticated caller, the cloud's
+ *      posture). True is `allow`; false is `deny` with an EMPTY reason, so
+ *      the method annotation's byte-pinned `error_msg` wins on the wire,
+ *      exactly the cloud's genuine-denial path.
+ *
+ * Faults. Everything past the pre-checks runs under one guard: a store
+ * fault, a person that names nobody (`personFor`), an evaluation fault
+ * (a cycle, the depth bound, an undeclared target — a registry gap the
+ * edition pin makes unreachable) all answer `unavailable` with the cause,
+ * which the Authorize step maps to INTERNAL. A denial is never a softened
+ * outage and an outage is never a denial; the driver itself never throws.
+ *
+ * Logging. One debug line per deny and per not-found, naming the person's
+ * account id, the permission and the object — what an operator needs to
+ * answer "why can Alice not see this" — and never the token. Allows are
+ * silent; they are the common case.
+ *
+ * Cost, per check (measured at slice 4): the target row (1), the caller's
+ * account (1 primary-key read; 2 for a caller a composition verifier left
+ * idp-shaped), the person's IamPolicy rows (1 scan of the port, once per
+ * source), and one row per parent hop the model walks.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import type { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import type { Logger } from "../boot/logger.js";
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
+import type {
+  Authorizer,
+  AuthzCheck,
+  AuthzDecision,
+} from "../extensions/authorizer.js";
+import type { CallerIdentity } from "../extensions/identity.js";
+import {
+  kindEnumName,
+  kindServedByEdition,
+} 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";
+import type { ObjectRef } from "./tuples.js";
+import { formatObjectRef } from "./tuples.js";
+
+/**
+ * Kinds whose missing row is a denial, never `not-found` (arm 4): the
+ * cloud's `PROBE_EXEMPT_KINDS` restricted to the kinds this edition
+ * serves — `platform`, `identity_provider`, `platform_client` and
+ * `invitation` are refused by arm 2 before any row is asked about. The
+ * cloud's drift test pins the two sets equal over the open-source tier.
+ *
+ * `iam_policy` is reachable as a target through the IamPolicy RPCs' own
+ * `resource.kind` (a caller may name it); the grant scope refuses such a
+ * target after the Authorize step in both editions, and the arm here
+ * keeps the wire the same on the way there.
+ */
+export const NOT_FOUND_EXEMPT_KINDS: ReadonlySet<ApiResourceKind> = new Set([
+  ApiResourceKind.identity_account,
+  ApiResourceKind.iam_policy,
+]);
+
+/** The Java RequestAuthorizationService's pre-check copy, byte for byte (the cloud renders the same). */
+export const UNKNOWN_PERMISSION_DENY_REASON =
+  "authorization cannot be performed with unknown permission";
+export const EMPTY_IDENTITY_DENY_REASON =
+  "authorization cannot be performed on empty identity string";
+export const EMPTY_RESOURCE_ID_DENY_REASON =
+  "authorization cannot be performed on empty api-resource-id";
+export const UNKNOWN_KIND_DENY_REASON =
+  "authorization cannot be performed on unknown api-resource-kind";
+/** This edition's own arm; the cloud has no unserved kind to deny. */
+export const UNSERVED_KIND_DENY_REASON =
+  "authorization cannot be performed on a kind this edition does not serve";
+
+export interface BuiltInAuthorizerDeps {
+  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 identity_account targets. */
+  readonly accounts: AccountsByCaller;
+  /** The served edition (`extensions.edition`); the built-in posture pins it to `oss` at boot. */
+  readonly edition: ServerEdition;
+  readonly logger: Logger;
+  /** The declarations to evaluate; the built-in model unless a test says otherwise. */
+  readonly model?: Model;
+}
+
+export function newBuiltInAuthorizer(deps: BuiltInAuthorizerDeps): Authorizer {
+  const model = deps.model ?? builtInModel;
+  return {
+    async authorize(
+      caller: CallerIdentity,
+      check: AuthzCheck,
+    ): Promise<AuthzDecision> {
+      if (check.permission === IamPermission.unspecified) {
+        return deny(UNKNOWN_PERMISSION_DENY_REASON);
+      }
+      if (caller.identityId === "") {
+        return deny(EMPTY_IDENTITY_DENY_REASON);
+      }
+      if (check.resourceId === "") {
+        return deny(EMPTY_RESOURCE_ID_DENY_REASON);
+      }
+      if (check.resourceKind === ApiResourceKind.api_resource_kind_unknown) {
+        return deny(UNKNOWN_KIND_DENY_REASON);
+      }
+      if (!kindServedByEdition(check.resourceKind, deps.edition)) {
+        return deny(UNSERVED_KIND_DENY_REASON);
+      }
+
+      const object: ObjectRef = {
+        type: kindEnumName(check.resourceKind),
+        id: check.resourceId,
+      };
+      const relation = IamPermission[check.permission];
+      try {
+        const person = await resolvePerson(deps.accounts, caller);
+        const source = newDerivedTupleSource(
+          {
+            store: deps.store,
+            policies: deps.policies,
+            accounts: deps.accounts,
+            model,
+          },
+          person,
+        );
+        const row = await source.loader.load(object);
+        if (
+          row === undefined &&
+          !NOT_FOUND_EXEMPT_KINDS.has(check.resourceKind)
+        ) {
+          deps.logger.debug("authorization target not found", {
+            account: person.accountId,
+            permission: relation,
+            object: formatObjectRef(object),
+          });
+          return { kind: "not-found" };
+        }
+        const allowed = await checkRelation(
+          { model, source },
+          object,
+          relation,
+          person,
+          { allow: true },
+        );
+        if (allowed) {
+          return { kind: "allow" };
+        }
+        deps.logger.debug("authorization denied", {
+          account: person.accountId,
+          permission: relation,
+          object: formatObjectRef(object),
+        });
+        // Empty on purpose: the Authorize step then surfaces the method
+        // annotation's byte-pinned error_msg (or its fallback copy), the
+        // cloud's genuine-denial path.
+        return deny("");
+      } catch (error) {
+        return {
+          kind: "unavailable",
+          cause: error instanceof Error ? error : new Error(String(error)),
+        };
+      }
+    },
+  };
+}
+
+function deny(reason: string): AuthzDecision {
+  return { kind: "deny", reason };
+}

package/src/authorization/derived-tuples.ts

@@ -0,0 +1,384 @@
+/**
+ * The derived tuple view — the ONE place the built-in authorizer knows
+ * what open source's tuples would have been. The cloud stores tuples its
+ * driver writes from every row's lifecycle (stigmer-cloud
+ * iam/tuple-lifecycle.ts); open source stores none and computes the same
+ * tuples from the row when a check asks ("derived state over stored
+ * state"). `deriveTuples` is that computation, pure over `RowFacts`, in
+ * the driver's own shapes:
+ *
+ *   - parent links:   <row>#<relation>@<parentKind>:<parentId>   (the scope link, then the additional parents)
+ *   - owner DIRECT:   <row>#owner@identity_account:<creator stamp>
+ *   - owner SELF:     <row>#owner@identity_account:<row id>
+ *   - creator:        <row>#creator@identity_account:<creator stamp>   (kinds flagged requires_creator_tuple)
+ *   - org-viewer:     <row>#viewer@organization:<org>#viewer          (visibility_org; cloud#257's shape)
+ *   - public-viewer:  <row>#viewer@identity_account:* with allow_public
+ *   - platform-viewer: none — it fans out over identity providers, a kind this edition does not serve
+ *
+ * Two facts are this edition's own and are stated here, nowhere else:
+ *   - The ORGANIZATION's owner is a ROW, not a derivation. 2b's role
+ *     lifecycle (domain/iampolicy/role-lifecycle.ts) writes the creator's
+ *     `owner` row for exactly that kind, and the grant path writes every
+ *     other role; deriving an owner tuple from the creator stamp as well
+ *     would keep a revoked founder owner forever. ROW_RECORDED_OWNER_KINDS
+ *     is the read side of the lifecycle's "only organization" guard.
+ *   - A stamp that names no person becomes no tuple: `""` and the
+ *     unconfigured laptop's `"system"` (`isPersonStamp`, the membership
+ *     rules' one predicate). The person comparison itself is the
+ *     evaluator's, over the aliases `Person` carries.
+ *
+ * The SOURCE joins two records per (object, relation): the person's own
+ * IamPolicy rows on the object (read ONCE per source through
+ * `findByPrincipal` — every row open source writes names an account id,
+ * so the person's account id is the whole key, and on the OSS adapter one
+ * read is one scan whatever the number of organizations walked) and the
+ * tuples derived from the object's row (loaded once per object through
+ * the loader, which a declaration's `derived` rule also reads related
+ * rows through). An absent row is no tuples — the target's own not-found
+ * is the driver's arm, and a parent that no longer exists simply grants
+ * nothing, as in the cloud; any other store fault propagates so the
+ * driver folds it to `unavailable`. One source per check (or per list
+ * call for the list scope): its memo is the check's.
+ *
+ * A source may be SEEDED with the facts of objects the caller already
+ * holds (the list scope's candidates, decoded by the lane and carried on
+ * every `ListEntryMeta`): a seeded object's tuples derive from those facts
+ * and its row is never read — the facts are exactly what the derivation
+ * reads (facts.ts). The seed stands in for the row only where the row
+ * would have been read for FACTS; a declaration's `derived` rule reads
+ * the row it needs through the loader as before (`default_of` reads the
+ * instance's blueprint pointer, `execution_viewer` the instance's level —
+ * spec fields the facts do not carry), so listing the two instance kinds
+ * costs one row read per candidate, stated in the scope's cost pins.
+ *
+ * Rows are read through the generic Store, with one exception: an
+ * `identity_account` object is read through the account PORT
+ * (`accounts.findById`), the binding every other reader of accounts —
+ * the verifiers, whoAmI, the create path — follows. A composition that
+ * registers its own account store and keeps the built-in authorizer
+ * therefore still lets a person read their own account (the derivation
+ * is `owner@self`); a generic read would miss and deny them their own
+ * row. IamPolicy rows are already the port's (`findByPrincipal`), so no
+ * second exception is needed for them.
+ */
+import type { Message } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { OwnerAttributionType } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+
+import { isPersonStamp } from "../domain/iampolicy/membership.js";
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
+import type { IdentityAccountStore } from "../domain/identityaccount/store.js";
+import type { VisibilityTupleShape } from "../extensions/resource-authorization.js";
+import {
+  getKindMeta,
+  kindByEnumName,
+  kindEnumName,
+} from "../pipeline/apiresource-meta.js";
+import { visibilityShapesFor } from "../pipeline/steps/authorization-tuples.js";
+import type { Store } from "../store/interface.js";
+import { ResourceNotFoundError } from "../store/interface.js";
+import type { RowFacts } from "./facts.js";
+import { rowFactsOf } from "./facts.js";
+import type { Model } from "./model/index.js";
+import { builtInModel } from "./model/index.js";
+import type {
+  ObjectRef,
+  Person,
+  RowLoader,
+  Subject,
+  Tuple,
+  TupleSource,
+} from "./tuples.js";
+import {
+  ACCOUNT_TYPE,
+  ALLOW_PUBLIC_CONDITION,
+  formatObjectRef,
+} from "./tuples.js";
+
+/**
+ * Kinds whose `[identity_account]` owner is recorded as an IamPolicy row
+ * by this edition (the module header): the derivation writes no owner
+ * tuple for them. Mirrors role-lifecycle.ts's create arm, which writes
+ * the row for `organization` and nothing else.
+ */
+export const ROW_RECORDED_OWNER_KINDS: ReadonlySet<ApiResourceKind> = new Set([
+  ApiResourceKind.organization,
+]);
+
+function account(id: string): Subject {
+  return { form: "object", object: { type: ACCOUNT_TYPE, id } };
+}
+
+/** The tuples a row stands for, in the cloud driver's shapes and order. */
+export function deriveTuples(facts: RowFacts): ReadonlyArray<Tuple> {
+  const object: ObjectRef = { type: kindEnumName(facts.kind), id: facts.id };
+  const config = getKindMeta(facts.kind).authorization;
+  if (config === undefined) {
+    return [];
+  }
+  const tuples: Tuple[] = [];
+  for (const link of facts.parentLinks) {
+    tuples.push({
+      object,
+      relation: link.relation,
+      subject: {
+        form: "object",
+        object: { type: kindEnumName(link.parentKind), id: link.parentId },
+      },
+    });
+  }
+  const stampIsPerson = isPersonStamp(facts.createdBy);
+  switch (config.ownerType) {
+    case OwnerAttributionType.DIRECT:
+      if (stampIsPerson && !ROW_RECORDED_OWNER_KINDS.has(facts.kind)) {
+        tuples.push({
+          object,
+          relation: "owner",
+          subject: account(facts.createdBy),
+        });
+      }
+      break;
+    case OwnerAttributionType.SELF:
+      tuples.push({ object, relation: "owner", subject: account(facts.id) });
+      break;
+    case OwnerAttributionType.INHERITED:
+    case OwnerAttributionType.NONE:
+    case OwnerAttributionType.UNSPECIFIED:
+      // Inherited: the model walks `owner from <parent>`; none: the kind has no owner.
+      break;
+    default: {
+      const exhaustive: never = config.ownerType;
+      throw new Error(`unknown owner attribution: ${String(exhaustive)}`);
+    }
+  }
+  if (config.requiresCreatorTuple && stampIsPerson) {
+    tuples.push({
+      object,
+      relation: "creator",
+      subject: account(facts.createdBy),
+    });
+  }
+  for (const shape of visibilityShapesFor(facts.kind, facts.visibility)) {
+    const subject = visibilitySubject(shape, facts.org);
+    if (subject !== undefined) {
+      tuples.push({ object, relation: "viewer", subject });
+    }
+  }
+  return tuples;
+}
+
+/** The driver's grant table for a visibility shape; undefined where this edition writes nothing. */
+function visibilitySubject(
+  shape: VisibilityTupleShape,
+  org: string,
+): Subject | undefined {
+  switch (shape) {
+    case "org-viewer":
+      // No organization to point at (a legacy row): no userset.
+      return org === ""
+        ? undefined
+        : {
+            form: "userset",
+            object: { type: "organization", id: org },
+            relation: "viewer",
+          };
+    case "public-viewer":
+      return {
+        form: "wildcard",
+        type: ACCOUNT_TYPE,
+        condition: ALLOW_PUBLIC_CONDITION,
+      };
+    case "platform-viewer":
+      return undefined;
+    default: {
+      const exhaustive: never = shape;
+      throw new Error(`unknown visibility shape: ${String(exhaustive)}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The source.
+// ---------------------------------------------------------------------------
+
+export interface DerivedTupleSourceDeps {
+  readonly store: Store;
+  /** The port the grant path writes through — the rows are read from the same instance. */
+  readonly policies: IamPolicyStore;
+  /** The account port — an `identity_account` object is read through it, never the generic Store (the module header). */
+  readonly accounts: Pick<IdentityAccountStore, "findById">;
+  /** The declarations to derive with; the built-in model unless a test says otherwise. */
+  readonly model?: Model;
+}
+
+export interface DerivedTupleSource extends TupleSource {
+  /** The memoised row reads, exposed for a declaration's `derived` rules and for tests. */
+  readonly loader: RowLoader;
+  /**
+   * The person's own IamPolicy rows as tuples — the ONE read of them this
+   * source makes, shared with `tuplesOf`. A list-shaped consumer (the
+   * organization directory; the list scope) reads its candidate objects
+   * from here instead of scanning the port a second time.
+   */
+  personTuples(): Promise<ReadonlyArray<Tuple>>;
+}
+
+export interface DerivedTupleSourceSeed {
+  /** Objects whose facts the caller already holds; their rows are not read for derivation. */
+  readonly facts: ReadonlyArray<RowFacts>;
+}
+
+export function newDerivedTupleSource(
+  deps: DerivedTupleSourceDeps,
+  person: Person,
+  seed?: DerivedTupleSourceSeed,
+): DerivedTupleSource {
+  const model = deps.model ?? builtInModel;
+  const rows = new Map<string, Promise<Message | undefined>>();
+  const derived = new Map<string, Promise<ReadonlyArray<Tuple>>>();
+  const seeded = new Map<string, RowFacts>();
+  for (const facts of seed?.facts ?? []) {
+    seeded.set(
+      formatObjectRef({ type: kindEnumName(facts.kind), id: facts.id }),
+      facts,
+    );
+  }
+  let personRows: Promise<ReadonlyArray<Tuple>> | undefined;
+
+  const loader: RowLoader = {
+    load(object) {
+      const key = formatObjectRef(object);
+      const held = rows.get(key);
+      if (held !== undefined) {
+        return held;
+      }
+      const loading = loadRow(deps, model, object);
+      rows.set(key, loading);
+      return loading;
+    },
+  };
+
+  function derivedTuplesOf(object: ObjectRef): Promise<ReadonlyArray<Tuple>> {
+    const key = formatObjectRef(object);
+    const held = derived.get(key);
+    if (held !== undefined) {
+      return held;
+    }
+    const declaration = model.byType(object.type);
+    const known = seeded.get(key);
+    let deriving: Promise<ReadonlyArray<Tuple>>;
+    if (declaration === undefined) {
+      deriving = Promise.resolve([]);
+    } else if (known !== undefined) {
+      deriving = Promise.resolve(deriveTuples(known));
+    } else {
+      deriving = loader
+        .load(object)
+        .then((row) =>
+          row === undefined
+            ? []
+            : deriveTuples(rowFactsOf(declaration.kind, row)),
+        );
+    }
+    derived.set(key, deriving);
+    return deriving;
+  }
+
+  function rowTuples(): Promise<ReadonlyArray<Tuple>> {
+    if (personRows === undefined) {
+      personRows = deps.policies
+        .findByPrincipal(ACCOUNT_TYPE, person.accountId)
+        .then((found) => found.map(tupleOfRow));
+    }
+    return personRows;
+  }
+
+  return {
+    loader,
+    personTuples: rowTuples,
+    async tuplesOf(object, relation) {
+      const onPair = (tuple: Tuple): boolean =>
+        tuple.relation === relation &&
+        tuple.object.type === object.type &&
+        tuple.object.id === object.id;
+      const fromRows = (await rowTuples()).filter(onPair);
+      const declaration = model.byType(object.type);
+      if (declaration === undefined) {
+        return fromRows;
+      }
+      const fromRow = (await derivedTuplesOf(object)).filter(onPair);
+      const rule = declaration.derived.get(relation);
+      if (rule === undefined) {
+        return [...fromRows, ...fromRow];
+      }
+      const row = await loader.load(object);
+      const fromRule = row === undefined ? [] : await rule(object, row, loader);
+      return [...fromRows, ...fromRow, ...fromRule];
+    },
+  };
+}
+
+/** The decoded row for an object, or undefined when the kind is not declared or the row does not exist. */
+async function loadRow(
+  deps: Pick<DerivedTupleSourceDeps, "store" | "accounts">,
+  model: Model,
+  object: ObjectRef,
+): Promise<Message | undefined> {
+  const declaration = model.byType(object.type);
+  const kind = kindByEnumName(object.type);
+  if (
+    declaration === undefined ||
+    kind === ApiResourceKind.api_resource_kind_unknown ||
+    object.id === ""
+  ) {
+    return undefined;
+  }
+  if (kind === ApiResourceKind.identity_account) {
+    return deps.accounts.findById(object.id);
+  }
+  try {
+    return await deps.store.getResource(kind, object.id, declaration.schema);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/** An IamPolicy row as the tuple it records: `resource#relation@principal`. */
+function tupleOfRow(row: IamPolicy): Tuple {
+  const spec = row.spec;
+  const principal = spec?.principal;
+  const resource = spec?.resource;
+  const object: ObjectRef = {
+    type: resource?.kind ?? "",
+    id: resource?.id ?? "",
+  };
+  const principalObject: ObjectRef = {
+    type: principal?.kind ?? "",
+    id: principal?.id ?? "",
+  };
+  let subject: Subject;
+  if (principal !== undefined && principal.relation !== "") {
+    subject = {
+      form: "userset",
+      object: principalObject,
+      relation: principal.relation,
+    };
+  } else if (principalObject.id === "*") {
+    // A wildcard row carries no condition of its own; the evaluator
+    // honours it only where a line admits an unconditioned wildcard,
+    // which no line in the model does.
+    subject = {
+      form: "wildcard",
+      type: principalObject.type,
+      condition: undefined,
+    };
+  } else {
+    subject = { form: "object", object: principalObject };
+  }
+  return { object, relation: spec?.relation ?? "", subject };
+}