@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

package/src/extensions/__tests__/iam-policy-points.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Pins the three registry points the IamPolicy domain adds and the one
+ * contract it widens (20260913.01, T01_1_review.md Q-OR-10), in the O5
+ * driver-point shape the registry already enforces for
+ * identityAccountStore and identityFederation:
+ *
+ *   - `drivers.iamPolicyStore` — the store driver (the cloud serves the
+ *     domain over cloud.iam_policy through it); single instance; absent =
+ *     the OSS adapter over the generic Store;
+ *   - `drivers.policyGrantScope` — which kinds a user may grant on and
+ *     with which roles (P1 gate Q7 iii; Q-OR-3); single instance; absent =
+ *     open source's default, the organization and nothing else;
+ *   - `drivers.authorizationQueries` — the tuple-half query engine
+ *     (Q-OR-8); single instance; absent = the three tuple-half RPCs and a
+ *     contextual checkMyPermission refuse UNIMPLEMENTED with the edition
+ *     reason (the domain suite pins the refusal; this file pins the
+ *     registry);
+ *   - `ResourceAuthorizationLifecycle` gains the OPTIONAL `onPolicyGranted`
+ *     and `onPolicyRevoked` (Q7 i): a unit's lifecycle that carries them
+ *     resolves through the existing single-instance point with both hooks
+ *     intact, and one that implements only the three required methods
+ *     still resolves — the widening is additive.
+ */
+import { describe, expect, it } from "vitest";
+
+import type { IamPolicyStore } from "../../domain/iampolicy/store.js";
+import type { AuthorizationQueryEngine } from "../authorization-queries.js";
+import type { PolicyGrantScope } from "../policy-grant-scope.js";
+import { resolveExtensions } from "../registry.js";
+import type { ResourceAuthorizationLifecycle } from "../resource-authorization.js";
+
+const unimplemented = () => Promise.reject(new Error("not exercised here"));
+
+const store: IamPolicyStore = {
+  save: unimplemented,
+  deleteById: unimplemented,
+  findById: unimplemented,
+  findByPrincipal: unimplemented,
+  findByResource: unimplemented,
+  findByPrincipalAndResource: unimplemented,
+  findByResourceWithRelations: unimplemented,
+  countDistinctPrincipalsByResource: unimplemented,
+  findScopeTuple: unimplemented,
+};
+
+const scope: PolicyGrantScope = {
+  grantableRoles: () => [],
+};
+
+const engine: AuthorizationQueryEngine = {
+  check: unimplemented,
+  listResourceIds: unimplemented,
+  listPrincipalIds: unimplemented,
+};
+
+describe("the iamPolicyStore driver point", () => {
+  it("is undefined with no extensions — the OSS adapter serves", () => {
+    expect(resolveExtensions([]).drivers.iamPolicyStore).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const resolved = resolveExtensions([
+      { name: "cloud-iam", drivers: { iamPolicyStore: store } },
+    ]);
+    expect(resolved.drivers.iamPolicyStore).toBe(store);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "store-a", drivers: { iamPolicyStore: store } },
+        { name: "store-b", drivers: { iamPolicyStore: store } },
+      ]),
+    ).toThrowError(
+      /extension 'store-b' registers an IamPolicyStore, but 'store-a' already did/,
+    );
+  });
+});
+
+describe("the policyGrantScope driver point", () => {
+  it("is undefined with no extensions — open source grants on organizations only", () => {
+    expect(resolveExtensions([]).drivers.policyGrantScope).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const resolved = resolveExtensions([
+      { name: "cloud-iam", drivers: { policyGrantScope: scope } },
+    ]);
+    expect(resolved.drivers.policyGrantScope).toBe(scope);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "scope-a", drivers: { policyGrantScope: scope } },
+        { name: "scope-b", drivers: { policyGrantScope: scope } },
+      ]),
+    ).toThrowError(
+      /extension 'scope-b' registers a PolicyGrantScope, but 'scope-a' already did/,
+    );
+  });
+});
+
+describe("the authorizationQueries capability point", () => {
+  it("is undefined with no extensions — the tuple-half RPCs refuse", () => {
+    expect(resolveExtensions([]).drivers.authorizationQueries).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const resolved = resolveExtensions([
+      { name: "cloud-iam", drivers: { authorizationQueries: engine } },
+    ]);
+    expect(resolved.drivers.authorizationQueries).toBe(engine);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "engine-a", drivers: { authorizationQueries: engine } },
+        { name: "engine-b", drivers: { authorizationQueries: engine } },
+      ]),
+    ).toThrowError(
+      /extension 'engine-b' registers an AuthorizationQueryEngine, but 'engine-a' already did/,
+    );
+  });
+});
+
+describe("the widened ResourceAuthorizationLifecycle contract", () => {
+  const resourceHooks = {
+    onResourceCreated: unimplemented,
+    onResourceDeleted: unimplemented,
+    onVisibilityChanged: unimplemented,
+  };
+
+  it("a lifecycle carrying the two policy hooks resolves with both intact — the cloud's tuple driver", () => {
+    const tupleDriver: ResourceAuthorizationLifecycle = {
+      ...resourceHooks,
+      onPolicyGranted: unimplemented,
+      onPolicyRevoked: unimplemented,
+    };
+    const resolved = resolveExtensions([
+      {
+        name: "cloud-iam",
+        drivers: { resourceAuthorizationLifecycle: tupleDriver },
+      },
+    ]);
+    expect(resolved.drivers.resourceAuthorizationLifecycle).toBe(tupleDriver);
+    expect(
+      resolved.drivers.resourceAuthorizationLifecycle?.onPolicyGranted,
+    ).toBe(unimplemented);
+    expect(
+      resolved.drivers.resourceAuthorizationLifecycle?.onPolicyRevoked,
+    ).toBe(unimplemented);
+  });
+
+  it("a lifecycle with only the three required methods still resolves — the widening is additive", () => {
+    const minimal: ResourceAuthorizationLifecycle = resourceHooks;
+    const resolved = resolveExtensions([
+      {
+        name: "some-unit",
+        drivers: { resourceAuthorizationLifecycle: minimal },
+      },
+    ]);
+    expect(resolved.drivers.resourceAuthorizationLifecycle).toBe(minimal);
+    expect(
+      resolved.drivers.resourceAuthorizationLifecycle?.onPolicyGranted,
+    ).toBeUndefined();
+  });
+});

package/src/extensions/__tests__/identity-account-composed.test.ts

@@ -37,7 +37,8 @@
  * The registered driver is the REAL OSS adapter over a SECOND SqliteStore
  * behind a call recorder, so the proof of consumption is WHERE the rows
  * land, and the pair under test is one that runs in production. The fake
- * verifier of (B) and (C) vouches for an unsigned JWT-shaped token with no
+ * verifier of (B) and (C) (composed-support.ts, shared with the other
+ * composed proofs) vouches for an unsigned JWT-shaped token with no
  * issuer: idpIdOf reads the `sub` from the raw token and the provisioner
  * takes the identity's own claims when there is no issuer, so a real first
  * provisioning runs with no network. The OSS OIDC verifier over a driver is
@@ -52,8 +53,7 @@ import path from "node:path";
 import { create, fromBinary } from "@bufbuild/protobuf";
 import type { DescMessage } from "@bufbuild/protobuf";
 import { Code, ConnectError, createClient } from "@connectrpc/connect";
-import type { Client, Interceptor, Transport } from "@connectrpc/connect";
-import { createGrpcTransport } from "@connectrpc/connect-node";
+import type { Client } from "@connectrpc/connect";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -68,7 +68,6 @@ import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 import { loadConfig } from "../../boot/config.js";
 import { composeServer } from "../../boot/compose.js";
 import type { ComposedServer } from "../../boot/compose.js";
-import { createLogger } from "../../boot/logger.js";
 import { accountIdFor } from "../../domain/identityaccount/constants.js";
 import { newResourceIdentityAccountStore } from "../../domain/identityaccount/resource-store.js";
 import type { IdentityAccountStore } from "../../domain/identityaccount/store.js";
@@ -81,18 +80,19 @@ import type { Store } from "../../store/interface.js";
 import { SqliteStore } from "../../store/sqlite/store.js";
 import type { Authorizer } from "../authorizer.js";
 import type { GateSlotName } from "../gate-slots.js";
-import type { CallerIdentity, IdentityVerifier } from "../identity.js";
+import type { CallerIdentity } from "../identity.js";
 import type { IdentityFederation } from "../identity-federation.js";
 import type { ServerExtension } from "../registry.js";
-
-const silentLogger = createLogger({
-  level: "error",
-  pretty: false,
-  write: () => {},
-});
+import {
+  baseConfig,
+  fakeJwt,
+  fakeVerifier,
+  silentLogger,
+  transportFor,
+} from "./composed-support.js";
 
 // ---------------------------------------------------------------------------
-// Shared fakes
+// Shared fakes (the composition-shaped ones live in composed-support.ts)
 // ---------------------------------------------------------------------------
 
 /** The port's eight methods, delegating to the real adapter and recording each call by name. */
@@ -161,62 +161,6 @@ async function accountIdsIn(store: Store): Promise<ReadonlyArray<string>> {
   );
 }
 
-/**
- * An unsigned JWT-shaped token (`header.payload.unsigned`): the fake
- * verifier below vouches for it, and idpIdOf reads its `sub` exactly as it
- * reads a real token's — the signature was the verifier's business.
- */
-function fakeJwt(sub: string, email: string): string {
-  const segment = (value: unknown): string =>
-    Buffer.from(JSON.stringify(value)).toString("base64url");
-  return `${segment({ alg: "none" })}.${segment({ sub, email })}.unsigned`;
-}
-
-/**
- * The composition's own verifier (the cloud's shape): admits the fake
- * token as a `user` whose identityId is the raw subject and whose issuer is
- * empty — it does NOT resolve to an account, exactly like a verifier that
- * runs before any row exists. Passes on everything else, so the OSS API-key
- * lane composed ahead of it keeps its claim.
- */
-const fakeVerifier: IdentityVerifier = {
-  name: "fake-composition-verifier",
-  verify: (token) => {
-    const segments = token.split(".");
-    if (segments.length !== 3 || segments[2] !== "unsigned") {
-      return Promise.resolve(null);
-    }
-    const claims = JSON.parse(
-      Buffer.from(segments[1] ?? "", "base64url").toString("utf8"),
-    ) as { sub?: unknown; email?: unknown };
-    if (typeof claims.sub !== "string") {
-      return Promise.resolve(null);
-    }
-    const identity: CallerIdentity = {
-      identityId: claims.sub,
-      callerClass: "user",
-      issuer: "",
-      rawToken: token,
-      ...(typeof claims.email === "string" ? { email: claims.email } : {}),
-    };
-    return Promise.resolve(identity);
-  },
-};
-
-function bearer(token: string): Interceptor {
-  return (next) => (request) => {
-    request.header.set("authorization", `Bearer ${token}`);
-    return next(request);
-  };
-}
-
-function transportFor(port: number, token?: string): Transport {
-  return createGrpcTransport({
-    baseUrl: `http://127.0.0.1:${port}`,
-    interceptors: token !== undefined ? [bearer(token)] : [],
-  });
-}
-
 async function connectErrorOf(
   promise: Promise<unknown>,
 ): Promise<ConnectError> {
@@ -244,16 +188,6 @@ function accountInput(idpId: string) {
   };
 }
 
-function baseConfig(dir: string): Record<string, string> {
-  return {
-    STIGMER_MODEL_REGISTRY_REFRESH: "off",
-    TEMPORAL_HOST_PORT: "127.0.0.1:1",
-    DB_PATH: path.join(dir, "stigmer.db"),
-    STORAGE_PATH: path.join(dir, "storage"),
-    ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
-  };
-}
-
 // ---------------------------------------------------------------------------
 // (A) trusted-local: the store driver, the federation capability
 // ---------------------------------------------------------------------------

package/src/extensions/__tests__/identity.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Pins `isPlatformPipelineCaller` (extensions/identity.ts; 20260913.01
+ * slice 5, Q-S5-10): the ONE definition of "the platform's own pipelines"
+ * — a `machine` or `internal` caller, or any identity that entered
+ * through the in-process transport — read by the identity-account
+ * `create` RPC's admission rule (2a A7) and the three IamPolicy system
+ * RPCs' (Q-OR-7). A wire `user`, `runner` or a composition's own class
+ * (guest) is never one.
+ */
+import { describe, expect, it } from "vitest";
+
+import { isPlatformPipelineCaller } from "../identity.js";
+import type { CallerIdentity } from "../identity.js";
+
+function caller(fields: Partial<CallerIdentity>): CallerIdentity {
+  return {
+    identityId: "ida_x",
+    callerClass: "user",
+    issuer: "",
+    rawToken: "",
+    ...fields,
+  };
+}
+
+describe("isPlatformPipelineCaller", () => {
+  it("admits machine and internal callers whatever their origin", () => {
+    expect(isPlatformPipelineCaller(caller({ callerClass: "machine" }))).toBe(
+      true,
+    );
+    expect(isPlatformPipelineCaller(caller({ callerClass: "internal" }))).toBe(
+      true,
+    );
+    expect(
+      isPlatformPipelineCaller(
+        caller({ callerClass: "machine", origin: "wire" }),
+      ),
+    ).toBe(true);
+  });
+
+  it("admits any identity that entered through the in-process transport — a propagated user included", () => {
+    expect(
+      isPlatformPipelineCaller(
+        caller({ callerClass: "user", origin: "in-process" }),
+      ),
+    ).toBe(true);
+  });
+
+  it("refuses wire users, runners and a composition's own classes", () => {
+    expect(isPlatformPipelineCaller(caller({ callerClass: "user" }))).toBe(
+      false,
+    );
+    expect(
+      isPlatformPipelineCaller(caller({ callerClass: "user", origin: "wire" })),
+    ).toBe(false);
+    expect(isPlatformPipelineCaller(caller({ callerClass: "runner" }))).toBe(
+      false,
+    );
+    expect(isPlatformPipelineCaller(caller({ callerClass: "guest" }))).toBe(
+      false,
+    );
+  });
+});

package/src/extensions/__tests__/list-read-scope.test.ts

@@ -14,6 +14,12 @@
  *     a fraction of the candidates);
  *   - the candidates carry {id, org, labels} — the driver's guest
  *     cookie rule keys on labels;
+ *   - a kind whose authorization is its parent's (kind_meta PARENT scope
+ *     + INHERITED owner; agent_execution → session) carries
+ *     `authorizationParent` on every candidate whose spec names it, the
+ *     same ResolvedParentLink the tuple lifecycle wrote; every other kind
+ *     and every parentless row carries none (stigmer-cloud 20260913.04
+ *     T04);
  *   - a scope failure PROPAGATES — never an empty result (the outage
  *     contract: empty means "authorized to see nothing", outage means
  *     INTERNAL through the caller's sanitized arm).
@@ -155,6 +161,138 @@ describe("restrictListByReadScope", () => {
     ]);
   });
 
+  describe("authorizationParent — the parent a kind's authorization is (20260913.04 T04)", () => {
+    function recordingScope(keep: ReadonlyArray<string>) {
+      const seen: ReadonlyArray<ListEntryMeta>[] = [];
+      const scope: ListReadScope = {
+        authorizedResourceIds: () => Promise.resolve(new Set<string>()),
+        restrictListEntries: (_caller, _kind, entries) => {
+          seen.push(entries);
+          return Promise.resolve(new Set(keep));
+        },
+      };
+      return { scope, seen };
+    }
+
+    it("an agent_execution candidate carries its session as the ResolvedParentLink the tuple lifecycle wrote", async () => {
+      const executions = [
+        {
+          metadata: { id: "aex_1", org: "acme", labels: {} },
+          spec: { sessionId: "ses_a" },
+        },
+        {
+          metadata: { id: "aex_2", org: "acme", labels: {} },
+          spec: { sessionId: "ses_a" },
+        },
+        {
+          metadata: { id: "aex_3", org: "acme", labels: {} },
+          spec: { sessionId: "ses_b" },
+        },
+      ];
+      const { scope, seen } = recordingScope(["aex_1", "aex_3"]);
+      const kept = await restrictListByReadScope(
+        scope,
+        caller,
+        ApiResourceKind.agent_execution,
+        executions,
+        "",
+      );
+      expect(kept.map((r) => r.metadata.id)).toEqual(["aex_1", "aex_3"]);
+      expect(seen[0]).toEqual([
+        {
+          id: "aex_1",
+          org: "acme",
+          labels: {},
+          authorizationParent: {
+            relation: "session",
+            parentKind: ApiResourceKind.session,
+            parentId: "ses_a",
+          },
+        },
+        {
+          id: "aex_2",
+          org: "acme",
+          labels: {},
+          authorizationParent: {
+            relation: "session",
+            parentKind: ApiResourceKind.session,
+            parentId: "ses_a",
+          },
+        },
+        {
+          id: "aex_3",
+          org: "acme",
+          labels: {},
+          authorizationParent: {
+            relation: "session",
+            parentKind: ApiResourceKind.session,
+            parentId: "ses_b",
+          },
+        },
+      ]);
+    });
+
+    it("a row whose spec does not name its parent carries no parent — offered as itself, never dropped", async () => {
+      const executions = [
+        { metadata: { id: "aex_orphan", org: "acme", labels: {} }, spec: {} },
+        { metadata: { id: "aex_specless", org: "acme", labels: {} } },
+      ];
+      const { scope, seen } = recordingScope(["aex_orphan", "aex_specless"]);
+      const kept = await restrictListByReadScope(
+        scope,
+        caller,
+        ApiResourceKind.agent_execution,
+        executions,
+        "",
+      );
+      expect(kept.map((r) => r.metadata.id)).toEqual([
+        "aex_orphan",
+        "aex_specless",
+      ]);
+      expect(seen[0]).toEqual([
+        { id: "aex_orphan", org: "acme", labels: {} },
+        { id: "aex_specless", org: "acme", labels: {} },
+      ]);
+    });
+
+    it("a kind whose authorization is its own carries no parent even when its spec names one", async () => {
+      // A workflow_execution links its workflow_instance (an additional
+      // parent, partial opt-in inheritance) and owns itself: not the pair.
+      const runs = [
+        {
+          metadata: { id: "wex_1", org: "acme", labels: {} },
+          spec: { workflowInstanceId: "wfi_1" },
+        },
+      ];
+      const { scope, seen } = recordingScope(["wex_1"]);
+      await restrictListByReadScope(
+        scope,
+        caller,
+        ApiResourceKind.workflow_execution,
+        runs,
+        "",
+      );
+      expect(seen[0]).toEqual([{ id: "wex_1", org: "acme", labels: {} }]);
+    });
+
+    it("no scope composed = the input unchanged, the parent never resolved", async () => {
+      const executions = [
+        {
+          metadata: { id: "aex_1", org: "acme", labels: {} },
+          spec: { sessionId: "ses_a" },
+        },
+      ];
+      const kept = await restrictListByReadScope(
+        undefined,
+        caller,
+        ApiResourceKind.agent_execution,
+        executions,
+        "acme",
+      );
+      expect(kept).toEqual(executions);
+    });
+  });
+
   it("a scope failure propagates — never an empty result", async () => {
     const failing: ListReadScope = {
       authorizedResourceIds: () => Promise.reject(new Error("fga down")),

package/src/extensions/__tests__/tier-truthfulness.test.ts

@@ -218,6 +218,14 @@ describe("tier truthfulness against the empty composition", () => {
     );
     expect(served.has("identityaccount")).toBe(true);
   });
+
+  it("iam_policy is open_source and served — the row half lives in open source (20260913.01, Q-EC-2b again)", () => {
+    const served = servedKindSegments(server.routes);
+    expect(getKindMeta(ApiResourceKind.iam_policy).tier).toBe(
+      ResourceTier.open_source,
+    );
+    expect(served.has("iampolicy")).toBe(true);
+  });
 });
 
 describe("the check bites (mutation proofs over the same function)", () => {

package/src/extensions/authorization-queries.ts

@@ -0,0 +1,97 @@
+/**
+ * The authorization-query capability (20260913.01, T01_1_review.md Q-OR-8):
+ * the TUPLE half of the IamPolicy query surface — the questions only an
+ * authorization engine can answer over its own graph, as opposed to the
+ * ROW half (who holds which role on what) that every edition answers from
+ * IamPolicy rows. Single instance, registered as
+ * `drivers.authorizationQueries` (the identityFederation shape: a driver
+ * point that is open source's own behaviour when absent).
+ *
+ * Absent, the IamPolicy query controller refuses `checkAuthorization`,
+ * `listAuthorizedResourceIds`, `listAuthorizedPrincipalIds`, and a
+ * `checkMyPermission` that carries contextual policies, UNIMPLEMENTED with
+ * the edition reason (domain/iampolicy/constants.ts
+ * AUTHORIZATION_QUERIES_UNIMPLEMENTED_MESSAGE) — never INTERNAL, the
+ * organization directory's absent-method precedent. Present, the
+ * controller still owns everything that is not the graph question: the
+ * annotation's Authorize step, `checkAuthorization`'s principal-trust rule
+ * (a user asks only about their own account; machine and internal about
+ * anyone), the UNAUTHENTICATED refusal, and the plain
+ * `checkMyPermission` that rides the composed Authorizer instead. The
+ * engine receives boundary-validated refs and never asks who is calling.
+ *
+ * The engine speaks the CONTRACT's vocabulary, not a backend's (Q-S3-1,
+ * 2026-09-13): `ApiResourceRef` for a principal or resource (kind = the
+ * enum member name, id, and for a principal an optional relation — the
+ * userset form `organization:X#member`), `IamPolicySpec` for a policy and
+ * for the what-if policies every query may carry, and the relation and
+ * kind strings as the wire sends them. The cloud's driver renders these to
+ * OpenFGA's `type:id#relation` strings itself; that grammar belongs to the
+ * store that runs it and never enters this library.
+ *
+ * Semantics the controller and the conformance suite rely on (the Java
+ * check-handler posture the cloud's client already implements):
+ *
+ *   - `check` answers a public grant (a wildcard principal resolves), so
+ *     "may I read this public agent" is true for anyone.
+ *   - the two listings never expand wildcards, and `listPrincipalIds`
+ *     answers DIRECT principals only — a listing is an inventory of who
+ *     was named, never a resolution of who could reach.
+ *   - contextual policies are evaluated as if held, and nothing is written.
+ *
+ * Error doctrine (the ListReadScope rule, verbatim in spirit: a seam that
+ * cannot answer THROWS — never an empty set, never false): `false` and
+ * `[]` are REAL answers. A backend outage surfaces as a throw; a
+ * ConnectError keeps its code (the cloud maps its three OpenFGA wire arms —
+ * DEADLINE_EXCEEDED, UNAVAILABLE, INTERNAL — before throwing), any other
+ * throw is INTERNAL through the pipeline's boundary. A denial dressed as
+ * an outage, or an outage dressed as a denial, is the fail-open class this
+ * contract exists to refuse.
+ *
+ * Why this is not `ListReadScope`: the read scope narrows the server's OWN
+ * list lanes for the calling identity with no what-if input; this engine
+ * answers the wire's explicit queries about an ARBITRARY principal with
+ * contextual policies. Both are ratified seams with distinct consumers;
+ * a cloud driver may wrap one client for both, and that is its business.
+ */
+import type {
+  ApiResourceRef,
+  IamPolicySpec,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+
+/** The query-engine contract (single-instance point, ExtensionDrivers.authorizationQueries). */
+export interface AuthorizationQueryEngine {
+  /**
+   * Whether `policy` is effectively held — its principal has its relation
+   * on its resource — given `contextualPolicies` evaluated as if held.
+   * The proto's CheckAuthorizationInput shape; `checkMyPermission` builds
+   * the spec from the caller's account ref. The spec's refs are present
+   * (boundary-validated, or controller-built).
+   */
+  check(
+    policy: IamPolicySpec,
+    contextualPolicies: ReadonlyArray<IamPolicySpec>,
+  ): Promise<boolean>;
+  /**
+   * The ids of `resourceKind` resources on which `principal` holds
+   * `relation` (ListAuthorizedResourceIdsInput's field order). Wildcards
+   * are not expanded.
+   */
+  listResourceIds(
+    principal: ApiResourceRef,
+    relation: string,
+    resourceKind: string,
+    contextualPolicies: ReadonlyArray<IamPolicySpec>,
+  ): Promise<ReadonlyArray<string>>;
+  /**
+   * The ids of `principalKind` principals holding `relation` on `resource`
+   * (ListAuthorizedPrincipalIdsInput's field order). Direct principals
+   * only; wildcards are not expanded.
+   */
+  listPrincipalIds(
+    resource: ApiResourceRef,
+    relation: string,
+    principalKind: string,
+    contextualPolicies: ReadonlyArray<IamPolicySpec>,
+  ): Promise<ReadonlyArray<string>>;
+}