@stigmer/server 3.15.2 → 3.15.3-dev.20260914100347

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__/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>>;
+}

package/src/extensions/drivers.ts

@@ -26,6 +26,11 @@
  *   - identity-account store + identity federation (the first domain
  *     whose persistence is a PORT, and the four federated RPC arms only
  *     one edition serves) — landed with 20260911.11, gate ruling Q-IA-9
+ *   - IamPolicy store + policy grant scope + authorization queries (the
+ *     IamPolicy domain's row half served in every edition; the store
+ *     port, which kinds an edition grants on, and the tuple-half query
+ *     engine only an authorization backend can answer) — landed with
+ *     20260913.01, gate ruling Q-OR-10
  *
  * Merge rules (enforced by resolveExtensions, DD-006 §2b): the two
  * provider kinds are single-instance points — a second declaring unit is
@@ -40,14 +45,17 @@
 import type { ArtifactStorageDriverFactory } from "../artifactstorage/artifact-storage.js";
 import type { ChannelRuntime } from "../domain/agentchannel/channel-runtime.js";
 import type { IdentityAccountStore } from "../domain/identityaccount/store.js";
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
 import type { SecretCodec } from "../encryption/codec.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
 import type { VisitorErrorPolicy } from "../pipeline/interceptors/error-boundary.js";
 import type { RunnerCredentialProvider } from "../runnerauth/runner-credential-provider.js";
 import type { SandboxProvisionerFactory } from "../sandbox/provisioner.js";
+import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { OrganizationDirectory } from "./organization-directory.js";
+import type { PolicyGrantScope } from "./policy-grant-scope.js";
 import type { ResourceAuthorizationLifecycle } from "./resource-authorization.js";
 import type { ScheduleFireCallerMint } from "./schedule-fire-caller.js";
 
@@ -90,8 +98,13 @@ export interface ExtensionDrivers {
    * The resource-authorization lifecycle seam (C2, ruling Q2;
    * single-instance point). When composed, the three shared tuple steps
    * (CreateAuthorizationTuples / CleanupIamPolicies /
-   * UpdateVisibilityTuples) deliver resolved events to it; when absent,
-   * those steps no-op — OSS behavior byte-identical.
+   * UpdateVisibilityTuples) deliver resolved events to it, and the
+   * IamPolicy grant path delivers the two policy hooks. Corrected
+   * 2026-09-13 (20260913.01 Q-OR-6): when absent, the steps no-op, but
+   * open source is no longer record-less — the composition root installs
+   * the built-in role lifecycle (domain/iampolicy/role-lifecycle.ts, the
+   * entry's slice 4), which writes IamPolicy rows, whenever no extension
+   * registers an Authorizer (resource-authorization.ts header).
    */
   readonly resourceAuthorizationLifecycle?: ResourceAuthorizationLifecycle;
   /**
@@ -169,4 +182,38 @@ export interface ExtensionDrivers {
    * edition reason — the organizationDirectory absent-method shape.
    */
   readonly identityFederation?: IdentityFederation;
+  /**
+   * The IamPolicy store driver (20260913.01, Q-OR-10; single-instance
+   * point). The IamPolicy domain's persistence is a PORT like the
+   * identity-account domain's: when composed, every row the one grant
+   * path writes, deletes or reads — user grants, the structural
+   * bootstrap lanes, the access lists and counts — goes through this
+   * driver (the cloud serves the domain over its own `cloud.iam_policy`
+   * table this way, legacy random ids included). When absent, the OSS
+   * adapter over the generic Store installs at the compose.ts
+   * consumption site — OSS behavior byte-identical.
+   */
+  readonly iamPolicyStore?: IamPolicyStore;
+  /**
+   * The policy grant scope (20260913.01, Q-OR-3; single-instance point):
+   * which kinds a user may grant a role on in this edition, with which
+   * roles. Narrows the proto's `grantable_roles`, total over the enum,
+   * synchronous (policy-grant-scope.ts carries the reasons). When
+   * composed, ValidateGrantableRole and checkMyPermission's
+   * `can_grant_access` arm read it; when absent, open source's
+   * organization-only default installs at the compose.ts consumption
+   * site — the organization grants its four proto roles, nothing else
+   * grants anything.
+   */
+  readonly policyGrantScope?: PolicyGrantScope;
+  /**
+   * The authorization-query engine (20260913.01, Q-OR-8; single-instance
+   * point): the tuple-half questions — checkAuthorization, the two
+   * listAuthorized*Ids, a checkMyPermission with contextual policies —
+   * only an authorization backend can answer over its own graph. When
+   * composed, the IamPolicy query controller dispatches to it after its
+   * own trust checks; when absent, those RPC arms refuse UNIMPLEMENTED
+   * with the edition reason — the identityFederation absent shape.
+   */
+  readonly authorizationQueries?: AuthorizationQueryEngine;
 }

package/src/extensions/identity.ts

@@ -97,3 +97,24 @@ export interface IdentityVerifier {
    */
   verify(token: string): Promise<CallerIdentity | null>;
 }
+
+/**
+ * Whether `caller` is one of the platform's own pipelines — the admission
+ * rule of the RPCs a person must never reach directly, stated ONCE
+ * (20260911.11 A7 for the identity-account `create` RPC; 20260913.01
+ * Q-OR-7 and Q-S5-10 for the three IamPolicy system RPCs): a `machine`
+ * account (the platform's service accounts), the `internal` class (the
+ * server acting as itself over the in-process transport) or ANY identity
+ * that entered through that transport (a propagated user the server is
+ * composing a request for). A wire `user`, a `runner` and a composition's
+ * own classes are refused by the RPC that reads this — under the
+ * permissive Authorizer the annotation alone would admit anyone, so the
+ * rule is load-bearing in open source.
+ */
+export function isPlatformPipelineCaller(caller: CallerIdentity): boolean {
+  return (
+    caller.callerClass === "machine" ||
+    caller.callerClass === "internal" ||
+    caller.origin === "in-process"
+  );
+}

package/src/extensions/policy-grant-scope.ts

@@ -0,0 +1,50 @@
+/**
+ * The policy-grant-scope driver point (20260913.01; the P1 gate's Q7 iii,
+ * T01_1_review.md Q-OR-3): WHICH kinds a user may grant a role on in this
+ * edition, and with which roles. Single instance, registered as
+ * `drivers.policyGrantScope` (the identityFederation shape: a driver point
+ * whose absence is open source's own behaviour). Absent, the composition
+ * root installs `newOrganizationOnlyGrantScope()`
+ * (domain/iampolicy/grant-scope.ts): the organization grants the roles its
+ * `kind_meta` lists — owner, admin, member, viewer (Q-OR-4) — and no other
+ * kind grants anything. Per-resource grants (a viewer on one agent) are
+ * what the Enterprise and Cloud editions add by registering a wider scope;
+ * the cloud registers every kind's `kind_meta` roles.
+ *
+ * Who reads it: the IamPolicy command controller's ValidateGrantableRole on
+ * `create` — AFTER the proto (`grantableRolesFor` in
+ * pipeline/apiresource-meta.ts, the source of "what can be granted at
+ * all"; a kind that lists no roles is system-managed in every edition and
+ * refused before the scope is asked) and never on `bootstrapPolicy`, the
+ * structural lane — and `checkMyPermission`'s second arm, which answers
+ * `can_grant_access` false for a kind outside the scope so the console's
+ * existing PermissionGate hides grant controls without a new SDK surface
+ * (Q-OR-5).
+ *
+ * The contract every scope is held to (Q-S3-3, 2026-09-13):
+ *
+ *   - It NARROWS the proto, never widens it. A scope's answer for a kind is
+ *     read as a subset of `kind_meta.authorization.grantable_roles`;
+ *     ValidateGrantableRole intersects the two, so a driver cannot admit a
+ *     role the contract does not list by accident.
+ *   - It is TOTAL over ApiResourceKind, the unknown kind included: a kind
+ *     it does not admit answers the empty list, never a throw.
+ *     checkMyPermission asks about a kind that came off the wire and was
+ *     resolved by `kindByEnumName`, which yields the unknown kind rather
+ *     than failing (apiresource-meta.ts header).
+ *   - It is SYNCHRONOUS: an edition's grant scope is a fact about the
+ *     edition, a proto read at most, never I/O. A scope that would need a
+ *     network to answer is a different seam.
+ */
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+/** The grant-scope contract (single-instance point, ExtensionDrivers.policyGrantScope). */
+export interface PolicyGrantScope {
+  /**
+   * The roles a user may grant on a resource of `kind` in this edition — a
+   * subset of the kind's proto `grantable_roles`; empty when the edition
+   * grants nothing on the kind (or the kind is unknown). Never throws.
+   */
+  grantableRoles(kind: ApiResourceKind): ReadonlyArray<IamRole>;
+}