@stigmer/server 3.27.1 → 3.28.0

package/src/authorization/__tests__/support.ts

@@ -15,6 +15,11 @@
  * parent), which is what lets the parity pin run over all of them.
  * `spec` and `status` overrides sit on top for the arms that need a
  * pointer or a level set.
+ *
+ * A fixture row exists only for a kind this edition stores rows of: every
+ * type of the model but a rowless one (`platform`, model/bindings.ts), so
+ * the builders take a StoredKindDeclaration and `storedDeclaration`
+ * refuses a rowless type by name.
  */
 import { create } from "@bufbuild/protobuf";
 import type { DescMessage, Message } from "@bufbuild/protobuf";
@@ -26,6 +31,7 @@ import {
   getKindMeta,
   kindEnumName,
 } from "../../pipeline/apiresource-meta.js";
+import { builtInModel } from "../model/index.js";
 import type { KindDeclaration } from "../model/rewrite.js";
 
 export interface FixtureRowFacts {
@@ -39,6 +45,28 @@ export interface FixtureRowFacts {
   readonly status?: Readonly<Record<string, unknown>>;
 }
 
+/** A declaration of a kind with stored rows: what a fixture row is built, saved and decoded with. */
+export type StoredKindDeclaration = KindDeclaration & { readonly schema: DescMessage };
+
+/** Whether rows of the declaration's kind are stored: every type but a rowless one. */
+export function hasStoredRows(
+  declaration: KindDeclaration,
+): declaration is StoredKindDeclaration {
+  return declaration.schema !== undefined;
+}
+
+/** The built-in model's declaration of `type`, which must be a kind with stored rows. */
+export function storedDeclaration(type: string): StoredKindDeclaration {
+  const declaration = builtInModel.byType(type);
+  if (declaration === undefined) {
+    throw new Error(`${type} is not a type of the model`);
+  }
+  if (!hasStoredRows(declaration)) {
+    throw new Error(`${type} is rowless: no row of it is stored`);
+  }
+  return declaration;
+}
+
 /** The id the fixture gives the parent of `parentKind`: `<type>-1`. */
 export function fixtureParentId(parentKind: string): string {
   return `${kindEnumName(getKindEnum(parentKind))}-1`;
@@ -46,7 +74,7 @@ export function fixtureParentId(parentKind: string): string {
 
 /** A row of `declaration.kind` carrying exactly the given facts, its parents filled. */
 export function fixtureRow(
-  declaration: KindDeclaration,
+  declaration: StoredKindDeclaration,
   facts: FixtureRowFacts,
 ): Message {
   // Typed loosely on purpose: the schema is any declared kind's, and
@@ -70,7 +98,7 @@ export function fixtureRow(
 }
 
 /** `kind_meta`'s parent spec fields for the kind, by generated name, each naming `<parentKind>-1`. */
-function parentFieldsOf(declaration: KindDeclaration): Record<string, string> {
+function parentFieldsOf(declaration: StoredKindDeclaration): Record<string, string> {
   const config = getKindMeta(declaration.kind).authorization;
   const spec = specSchemaOf(declaration.schema);
   const fields: Record<string, string> = {};

package/src/authorization/__tests__/throwaway-model.ts

@@ -0,0 +1,75 @@
+/**
+ * Builders for tests' throwaway models: a declaration written by hand in
+ * the evaluator's vocabulary (model/rewrite.ts), for the shapes the one
+ * real model must never hold (a cycle, a chain past the depth bound) and
+ * for proving a mechanism over a model small enough to read in the test.
+ * The built-in model is never written this way: it is the compiled
+ * OpenFGA JSON, read by model/openfga-json.ts.
+ *
+ * Nothing here validates: a test that declares a cycle means to. The
+ * builders are named so a declaration reads like the `.fga` line it
+ * stands for:
+ *
+ *   define viewer: [identity_account, organization#viewer] or owner
+ *     → union(direct(objectOf("identity_account"), usersetOf("organization", "viewer")), computed("owner"))
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import type {
+  DerivedRelation,
+  KindDeclaration,
+  Rewrite,
+  SubjectType,
+} from "../model/rewrite.js";
+
+export function objectOf(type: string): SubjectType {
+  return { form: "object", type };
+}
+
+export function usersetOf(type: string, relation: string): SubjectType {
+  return { form: "userset", type, relation };
+}
+
+export function direct(...subjects: ReadonlyArray<SubjectType>): Rewrite {
+  return { node: "this", subjects };
+}
+
+export function computed(relation: string): Rewrite {
+  return { node: "computed", relation };
+}
+
+export function from(relation: string, tupleset: string): Rewrite {
+  return { node: "from", relation, tupleset };
+}
+
+export function union(...members: ReadonlyArray<Rewrite>): Rewrite {
+  return { node: "union", members };
+}
+
+export function intersection(...members: ReadonlyArray<Rewrite>): Rewrite {
+  return { node: "intersection", members };
+}
+
+export interface ThrowawayDeclarationInput {
+  readonly kind: ApiResourceKind;
+  /** Omitted for a rowless type. */
+  readonly schema?: DescMessage;
+  readonly source?: string;
+  readonly relations: ReadonlyArray<readonly [name: string, rewrite: Rewrite]>;
+  readonly derived?: ReadonlyArray<readonly [name: string, rule: DerivedRelation]>;
+}
+
+/** A declaration exactly as written, for `newModel`. */
+export function throwawayDeclaration(input: ThrowawayDeclarationInput): KindDeclaration {
+  return {
+    kind: input.kind,
+    type: kindEnumName(input.kind),
+    schema: input.schema,
+    source: input.source ?? "throwaway",
+    relations: new Map(input.relations),
+    derived: new Map(input.derived ?? []),
+  };
+}

package/src/authorization/__tests__/wire-permissions.test.ts

@@ -1,83 +1,136 @@
 /**
- * Pins that every question the wire can ask this edition's authorizer
- * has a line in the model: for every `rpc.config`-annotated method the
- * open-source server SERVES whose annotation names a static kind this
- * edition serves, the permission is a relation that kind's transcript
- * declares. A relation the kind does not define answers `deny` here
- * (evaluator.ts) — an RPC annotated with such a pair would refuse every
- * caller, green on the permissive `local*` targets and dark only under
- * enforcement, so the gap is caught at the registry instead of on a
- * self-host.
+ * Pins the contract to the model over the whole wire: every question an
+ * RPC annotation asks the authorization model is a relation the model
+ * defines. The model (fga/model) and the contract (apis/, reaching this
+ * package as `@stigmer/protos`) are both this repository's, so their
+ * agreement is this repository's to keep, whichever edition serves the
+ * RPC. That is why the scope here is every service in `@stigmer/protos`,
+ * where authorize-annotation-completeness.test.ts scopes itself to the
+ * methods open source serves: that test governs the Authorize step, and a
+ * composition's own services are its own conformance suite's business;
+ * this one asks whether the model and the contract say the same thing.
  *
- * Scope follows authorize-annotation-completeness.test.ts: the empty
- * composition's routes, replayed into a recorder, are exactly the methods
- * the OSS Authorize step governs. Outside the pin, each for a stated
- * reason: `is_public` and `is_skip_authorization` methods (the annotation
- * is never resolved); a kind the edition does not serve (`platform`; the
- * driver refuses it before any evaluation, so under the built-in posture
- * nobody holds a platform permission); a kind named by
- * `resource_kind_path` (the IamPolicy lane's — the kind is the request's,
- * and the target's own declaration answers at run time).
+ * Two invariants:
+ *   - every `rpc.config` annotation that names a static kind asks a
+ *     permission that kind's type defines. A relation the type does not
+ *     define answers `deny` in the built-in evaluator and a validation
+ *     error in OpenFGA, so such an RPC refuses every caller, dark until
+ *     someone runs it under enforcement;
+ *   - the permission of every `resource_kind_path` lane (the IamPolicy
+ *     lanes, whose kind is the request's) is defined on every kind whose
+ *     `kind_meta` lists grantable roles, because each such kind is one the
+ *     grant path admits.
+ *
+ * Outside the pin, as in the annotation-completeness precedent: `is_public`
+ * and `is_skip_authorization` methods (their annotation is never
+ * resolved), and a `config` that names no kind (`IamPolicyQueryController.get`,
+ * which authorizes the loaded policy's resource).
+ *
+ * What does not hold today is pinned, never dropped: `KNOWN_GAPS` lists
+ * each disagreement, and the test requires the computed list to equal it,
+ * so a fix to the model or the contract fails here until its line is
+ * removed.
+ *
+ * The walk reads the stubs' built `dist`. `make test-server` builds them
+ * first; a bare `vitest` run in a checkout whose `dist` is stale reads
+ * services the contract no longer has.
  */
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { readdirSync } from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 
+import type { DescService } from "@bufbuild/protobuf";
 import { getOption, hasOption } from "@bufbuild/protobuf";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { beforeAll, describe, expect, it } from "vitest";
 
-import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import {
   config as rpcAuthorizationConfig,
   is_public,
   is_skip_authorization,
 } from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
-import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 
-import { loadConfig } from "../../boot/config.js";
-import { composeServer } from "../../boot/compose.js";
-import type { ComposedServer } from "../../boot/compose.js";
-import {
-  baseConfig,
-  servedServices,
-  silentLogger,
-} from "../../extensions/__tests__/composed-support.js";
-import {
-  kindEnumName,
-  kindServedByEdition,
-} from "../../pipeline/apiresource-meta.js";
-import { declarationFor } from "../model/index.js";
+import { grantableRolesFor, kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { builtInModel } from "../model/index.js";
+
+/**
+ * Today's disagreements between the contract and the model, each with its
+ * reason. Removing a gap from the model or the contract fails the test
+ * until its line is removed here.
+ */
+const KNOWN_GAPS: ReadonlyArray<string> = [
+  // Contract ahead of model, on purpose: Plan's proto says the relation
+  // lands in the model with the entry that serves the kind
+  // (apis/ai/stigmer/billing/plan/v1/command.proto), and no edition serves
+  // Plan yet.
+  "ai.stigmer.billing.plan.v1.PlanCommandController/create asks can_manage_plans on platform",
+  "ai.stigmer.billing.plan.v1.PlanCommandController/retire asks can_manage_plans on platform",
+  // Artifacts are grantable in kind_meta, but the model defines no access
+  // relations on them: https://github.com/stigmer/stigmer/issues/1268.
+  "the resource_kind_path lanes ask can_grant_access on artifact",
+  "the resource_kind_path lanes ask can_view_access on artifact",
+];
 
-/** One annotated, served, statically-targeted method: the question the wire asks. */
+/** One annotated method: the question it asks the model. */
 interface WireQuestion {
   readonly method: string;
+  /** The static kind, or unknown when the kind is the request's (`kindPath`). */
   readonly kind: ApiResourceKind;
+  readonly kindPath: string;
   readonly permission: string;
 }
 
-describe("every static (kind, permission) the served RPCs ask about is a declared relation", () => {
-  let dir: string;
-  let server: ComposedServer;
+/** Every service descriptor the stubs package exports, loaded through its own specifiers. */
+async function everyService(): Promise<ReadonlyArray<DescService>> {
+  const require = createRequire(import.meta.url);
+  const anchor = "ai/stigmer/iam/v1/enum_pb";
+  const resolved = require.resolve(`@stigmer/protos/${anchor}`);
+  const dist = resolved.slice(0, resolved.length - `${anchor}.js`.length);
+  const modules = readdirSync(path.join(dist, "ai"), { recursive: true, encoding: "utf8" })
+    .filter((file) => file.endsWith("_pb.js"))
+    .map((file) => `ai/${file.slice(0, -".js".length).split(path.sep).join("/")}`)
+    .sort();
+  const services: DescService[] = [];
+  for (const specifier of modules) {
+    const loaded: Record<string, unknown> = await import(`@stigmer/protos/${specifier}`);
+    for (const value of Object.values(loaded)) {
+      if (isService(value)) {
+        services.push(value);
+      }
+    }
+  }
+  return services;
+}
 
-  beforeAll(async () => {
-    dir = mkdtempSync(path.join(tmpdir(), "wire-permissions-test-"));
-    server = await composeServer({
-      config: loadConfig(baseConfig(dir)),
-      logger: silentLogger,
-      portOverride: 0,
-      host: "127.0.0.1",
-    });
-  });
+function isService(value: unknown): value is DescService {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "service" &&
+    "methods" in value
+  );
+}
 
-  afterAll(async () => {
-    await server.shutdown();
-    rmSync(dir, { recursive: true, force: true });
+/** The model's relations on a kind, or none when the model does not define it. */
+function relationsOf(kind: ApiResourceKind): ReadonlySet<string> {
+  return new Set(builtInModel.byKind(kind)?.relations.keys() ?? []);
+}
+
+describe("the contract asks the model only what the model defines", () => {
+  let services: ReadonlyArray<DescService>;
+
+  beforeAll(async () => {
+    services = await everyService();
   });
 
-  function wireQuestions(): WireQuestion[] {
-    const questions: WireQuestion[] = [];
-    for (const service of servedServices(server.routes)) {
+  function annotated(): ReadonlyArray<WireQuestion> {
+    const out: WireQuestion[] = [];
+    for (const service of services) {
       for (const method of service.methods) {
         if (
           !hasOption(method, rpcAuthorizationConfig) ||
@@ -87,68 +140,49 @@ describe("every static (kind, permission) the served RPCs ask about is a declare
           continue;
         }
         const config = getOption(method, rpcAuthorizationConfig);
-        if (
-          config.resourceKind === ApiResourceKind.api_resource_kind_unknown ||
-          !kindServedByEdition(config.resourceKind, ServerEdition.oss)
-        ) {
-          continue;
-        }
-        questions.push({
+        out.push({
           method: `${service.typeName}/${method.name}`,
           kind: config.resourceKind,
+          kindPath: config.resourceKindPath,
           permission: IamPermission[config.permission] ?? "",
         });
       }
     }
-    return questions;
+    return out;
   }
 
-  it("names a declared relation for every question, with none undeclared", () => {
-    const questions = wireQuestions();
-    expect(questions.length).toBeGreaterThan(60);
-    const undeclared = questions
-      .filter(
-        (q) => declarationFor(q.kind)?.relations.has(q.permission) !== true,
-      )
-      .map(
-        (q) =>
-          `${q.method} asks ${q.permission} on ${kindEnumName(q.kind)}, which its transcript does not declare`,
-      );
-    expect(undeclared).toEqual([]);
+  it("reads the whole contract, the IamPolicy lanes included", () => {
+    const questions = annotated();
+    expect(services.length).toBeGreaterThan(60);
+    expect(questions.length).toBeGreaterThan(150);
+    expect(questions.some((q) => q.kindPath !== "")).toBe(true);
   });
 
-  it("asks about every served kind the model declares except the one no RPC targets statically", () => {
-    // iam_policy's RPCs target the policy's RESOURCE (`resource_kind_path`
-    // or the load-then-authorize `get`). Every other declared kind is asked
-    // about by at least one static annotation — execution_context through
-    // its `get` and `delete`; its runner-token lane stays a skip.
-    const asked = new Set(wireQuestions().map((q) => kindEnumName(q.kind)));
-    expect([...asked].sort()).toEqual(
-      [
-        "agent",
-        "agent_channel",
-        "agent_execution",
-        "agent_instance",
-        "agent_share",
-        "api_key",
-        "artifact",
-        "channel_app",
-        "environment",
-        "execution_context",
-        "identity_account",
-        "mcp_server",
-        "memory",
-        "oauth_app",
-        "organization",
-        "platform_client",
-        "plugin",
-        "schedule",
-        "session",
-        "skill",
-        "workflow",
-        "workflow_execution",
-        "workflow_instance",
-      ].sort(),
+  it("defines every relation the contract asks about, except the known gaps", () => {
+    const questions = annotated();
+    const gaps: string[] = [];
+
+    for (const q of questions) {
+      if (q.kind !== ApiResourceKind.api_resource_kind_unknown && !relationsOf(q.kind).has(q.permission)) {
+        gaps.push(`${q.method} asks ${q.permission} on ${kindEnumName(q.kind)}`);
+      }
+    }
+
+    const pathPermissions = new Set(
+      questions.filter((q) => q.kindPath !== "").map((q) => q.permission),
     );
+    for (const value of ApiResourceKindSchema.values) {
+      const kind = value.number as ApiResourceKind;
+      if (kind === ApiResourceKind.api_resource_kind_unknown || grantableRolesFor(kind).length === 0) {
+        continue;
+      }
+      for (const permission of [...pathPermissions].sort()) {
+        if (!relationsOf(kind).has(permission)) {
+          gaps.push(`the resource_kind_path lanes ask ${permission} on ${kindEnumName(kind)}`);
+        }
+      }
+    }
+
+    expect(gaps.sort()).toEqual([...KNOWN_GAPS].sort());
   });
 });

package/src/authorization/authorizer.ts

@@ -5,8 +5,8 @@
  * 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 two editions answer one question the same way, over the one model
+ * both read (model/index.ts).
  *
  * The arms, in order:
  *   1. The cloud's four pre-checks with the Java service's copy, each a
@@ -47,8 +47,10 @@
  *
  * 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.
+ * idp-shaped), the person's IamPolicy rows (1 read of the port, once per
+ * source, indexed by principal on the OSS adapter; one more per team the
+ * person holds, which open source never has — derived-tuples.ts), 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";
@@ -85,7 +87,7 @@ import { formatObjectRef } from "./tuples.js";
  * their rows live in its own tables, out of its probe's reach; matching
  * the set here keeps the wire identical across editions (an unknown
  * platform client's id is PERMISSION_DENIED with the annotation's copy in
- * both). The cloud's model drift test pins every kind here inside its
+ * both). The cloud pins every kind here inside its own
  * `PROBE_EXEMPT_KINDS`, which is why this set is exported; a kind that
  * moves into open source joins this set in the same change.
  *