@stigmer/server 3.36.0 → 3.37.0

package/src/domain/organization/controller.ts

@@ -9,7 +9,10 @@
  * __tests__/organization.test.ts.
  *
  * getByExternalOrgId is implemented ONLY when the composed
- * OrganizationDirectory provides the lookup (C2, ruling Q7) — with no
+ * OrganizationDirectory provides the lookup (C2, ruling Q7). It answers
+ * only a caller who may view the identity provider the request names,
+ * and resolves the external id within that provider alone (see the
+ * handler); with no
  * directory the method stays absent from the partial service
  * implementation and ConnectRPC answers Unimplemented (the SDK
  * capability-probes this and must see UNIMPLEMENTED, not NotFound;
@@ -32,6 +35,7 @@ import type { FindApiResourcesRequest } from "@stigmer/protos/ai/stigmer/commons
 import { OrganizationCommandController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/command_pb";
 import { OrganizationQueryController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/query_pb";
 import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 import {
   OrganizationListSchema,
@@ -61,7 +65,10 @@ import { newPipeline } from "../../pipeline/pipeline.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
 import { RequestContext } from "../../pipeline/request-context.js";
-import { newAuthorizeStep } from "../../pipeline/steps/authorize.js";
+import {
+  authorizeResolvedResource,
+  newAuthorizeStep,
+} from "../../pipeline/steps/authorize.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import { newBuildNewStateStep } from "../../pipeline/steps/defaults.js";
 import { newBuildUpdateStateStep } from "../../pipeline/steps/build-update-state.js";
@@ -129,7 +136,7 @@ export function registerOrganizationServices(
   // partial implementation and ConnectRPC answers Unimplemented (the
   // capability-probed pin; see the module header).
   const externalLookup =
-    deps.organizationDirectory?.getOrganizationIdByExternalOrgId?.bind(
+    deps.organizationDirectory?.lookupExternalOrganization?.bind(
       deps.organizationDirectory,
     );
   router.service(OrganizationQueryController, {
@@ -548,15 +555,22 @@ async function findMyOrganizations(
 
 /**
  * GetByExternalOrgId — registered only with a directory lookup composed
- * (ruling Q7). The chain stays controller-owned: Authorize → validate →
- * directory resolves the external id → LoadTarget-shaped store read.
- * Both miss arms (no mapping, mapped row gone) answer the same NotFound
- * — an external caller cannot distinguish a stale mapping from a
- * missing org.
+ * (ruling Q7). The chain stays controller-owned: Authorize (a no-op for
+ * this skip-annotated method) → validate → the directory resolves the
+ * named identity provider and the external id within it → `can_view` on
+ * that provider → LoadTarget-shaped store read.
+ *
+ * The contract's check is the provider's, so it runs here, on the id the
+ * directory resolved mid-chain (`authorizeResolvedResource`, the pattern
+ * for skip lanes the annotation cannot express), and before the answer
+ * says whether a mapping exists: a caller who may not view the provider
+ * learns nothing about its tenants. Every miss arm (no such provider, no
+ * mapping, mapped row gone) answers the same NotFound, so an external
+ * caller cannot tell a stale mapping from a missing org.
  */
 async function getByExternalOrgId(
   deps: OrganizationControllerDeps,
-  lookup: (externalOrgId: string) => Promise<string | undefined>,
+  lookup: NonNullable<OrganizationDirectory["lookupExternalOrganization"]>,
   input: OrganizationExternalLookup,
   ctx: HandlerContext,
 ): Promise<Organization> {
@@ -582,7 +596,27 @@ async function getByExternalOrgId(
   if (input.externalOrgId === "") {
     throw invalidArgumentError("external_org_id is required");
   }
-  const orgId = await lookup(input.externalOrgId);
+  const found = await lookup(
+    {
+      org: input.identityProviderRef?.org ?? "",
+      slug: input.identityProviderRef?.slug ?? "",
+    },
+    input.externalOrgId,
+  );
+  if (found.kind === "no-identity-provider") {
+    throw notFoundError("Organization", input.externalOrgId);
+  }
+  await authorizeResolvedResource(
+    deps.authorizer,
+    reqCtx.callerIdentity,
+    {
+      permission: IamPermission.can_view,
+      resourceKind: ApiResourceKind.identity_provider,
+      resourceId: found.identityProviderId,
+    },
+    EXTERNAL_LOOKUP_DENIED_MESSAGE,
+  );
+  const orgId = found.organizationId;
   if (orgId === undefined) {
     throw notFoundError("Organization", input.externalOrgId);
   }
@@ -599,3 +633,6 @@ async function getByExternalOrgId(
     throw internalError(error, "failed to load organization");
   }
 }
+
+/** The lookup's deny copy: the provider's own `get` annotation's words. */
+const EXTERNAL_LOOKUP_DENIED_MESSAGE = "unauthorized to view identity provider";

package/src/domain/workflow/__tests__/version-audit-degradation.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Pins SaveVersionAudit's safe-degradation arms at step level — the
+ * composed suite (workflow.test.ts) cannot make the real store fail
+ * selectively:
+ *
+ *   - archive (saveAudit) failure clears status.version_hash and
+ *     metadata.version.id, so the head never references an unresolvable
+ *     audit entry, and the tag is never assigned;
+ *   - tag assignment (setAuditTag) failure clears the live
+ *     metadata.version.tag, so the head never advertises a tag the audit
+ *     column cannot resolve (stigmer/stigmer#855);
+ *   - persistOnRevert flushes either revert to the stored row, because on
+ *     create no Persist step follows this one; without it (update) the
+ *     chain's own Persist flushes the revert and the step writes nothing;
+ *   - a failing re-persist is logged, never a failed apply.
+ */
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import { AuditNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+import { newSaveVersionAuditStep } from "../steps.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const HASH = "c".repeat(64);
+
+/** What the stored row carried at each re-persist. */
+interface PersistedHead {
+  versionHash: string;
+  versionId: string;
+  tag: string;
+}
+
+interface FakeAuditStore {
+  saveAuditError: Error | undefined;
+  setAuditTagError: Error | undefined;
+  saveResourceError: Error | undefined;
+  setAuditTagCalls: number;
+  persisted: PersistedHead[];
+}
+
+/** A store exposing ONLY the members the step touches; the cast is the seam. */
+function fakeStore(overrides?: Partial<FakeAuditStore>): {
+  store: Store;
+  state: FakeAuditStore;
+} {
+  const state: FakeAuditStore = {
+    saveAuditError: undefined,
+    setAuditTagError: undefined,
+    saveResourceError: undefined,
+    setAuditTagCalls: 0,
+    persisted: [],
+    ...overrides,
+  };
+  const store = {
+    async getAuditByHash(): Promise<never> {
+      throw new AuditNotFoundError("not archived");
+    },
+    async saveAudit(): Promise<void> {
+      if (state.saveAuditError !== undefined) {
+        throw state.saveAuditError;
+      }
+    },
+    async setAuditTag(): Promise<void> {
+      state.setAuditTagCalls += 1;
+      if (state.setAuditTagError !== undefined) {
+        throw state.setAuditTagError;
+      }
+    },
+    async saveResource(
+      _k: unknown,
+      _id: unknown,
+      _schema: unknown,
+      wf: Workflow,
+    ): Promise<void> {
+      state.persisted.push({
+        versionHash: wf.status?.versionHash ?? "",
+        versionId: wf.metadata?.version?.id ?? "",
+        tag: wf.metadata?.version?.tag ?? "",
+      });
+      if (state.saveResourceError !== undefined) {
+        throw state.saveResourceError;
+      }
+    },
+  } as unknown as Store;
+  return { store, state };
+}
+
+function contextWithWorkflow(
+  tag: string,
+): RequestContext<typeof WorkflowSchema> {
+  return new RequestContext(
+    WorkflowSchema,
+    create(WorkflowSchema, {
+      metadata: {
+        id: "wfl_test",
+        org: "acme",
+        version: { id: HASH, tag },
+      },
+      status: { versionHash: HASH },
+    }),
+    testCallerIdentity(),
+    ApiResourceKind.workflow,
+  );
+}
+
+/** The create chain's arguments: isCreate, and no Persist follows. */
+function createStep(store: Store) {
+  return newSaveVersionAuditStep(store, silentLogger, true, true);
+}
+
+describe("SaveVersionAudit — safe degradation", () => {
+  it("tag failure on create clears the live tag and re-persists the row tagless", async () => {
+    const { store, state } = fakeStore({
+      setAuditTagError: new Error("tag column locked"),
+    });
+    const ctx = contextWithWorkflow("stable");
+
+    await createStep(store).execute(ctx);
+
+    expect(ctx.newState.metadata?.version?.tag).toBe("");
+    expect(state.persisted).toEqual([
+      { versionHash: HASH, versionId: HASH, tag: "" },
+    ]);
+  });
+
+  it("tag failure without persistOnRevert clears the live tag and leaves the write to the chain's Persist", async () => {
+    const { store, state } = fakeStore({
+      setAuditTagError: new Error("tag column locked"),
+    });
+    const ctx = contextWithWorkflow("stable");
+
+    await newSaveVersionAuditStep(store, silentLogger, true, false).execute(
+      ctx,
+    );
+
+    expect(ctx.newState.metadata?.version?.tag).toBe("");
+    expect(state.persisted).toEqual([]);
+  });
+
+  it("archive failure on create clears the hash and version id, re-persists, and never assigns the tag", async () => {
+    const { store, state } = fakeStore({
+      saveAuditError: new Error("disk full"),
+    });
+    const ctx = contextWithWorkflow("stable");
+
+    await createStep(store).execute(ctx);
+
+    expect(ctx.newState.status?.versionHash).toBe("");
+    expect(ctx.newState.metadata?.version?.id).toBe("");
+    expect(state.setAuditTagCalls).toBe(0);
+    expect(state.persisted).toEqual([
+      { versionHash: "", versionId: "", tag: "stable" },
+    ]);
+  });
+
+  it("a failing re-persist after a tag failure is logged, and the step does not throw", async () => {
+    const { store, state } = fakeStore({
+      setAuditTagError: new Error("tag column locked"),
+      saveResourceError: new Error("connection reset"),
+    });
+    const ctx = contextWithWorkflow("stable");
+
+    await expect(createStep(store).execute(ctx)).resolves.toBeUndefined();
+
+    expect(ctx.newState.metadata?.version?.tag).toBe("");
+    expect(state.persisted).toHaveLength(1);
+  });
+
+  it("a clean archive and tag write nothing beyond the audit row", async () => {
+    const { store, state } = fakeStore();
+    const ctx = contextWithWorkflow("stable");
+
+    await createStep(store).execute(ctx);
+
+    expect(ctx.newState.metadata?.version?.tag).toBe("stable");
+    expect(state.setAuditTagCalls).toBe(1);
+    expect(state.persisted).toEqual([]);
+  });
+});

package/src/domain/workflow/controller.ts

@@ -217,7 +217,8 @@ function kindOf(ctx: HandlerContext): ApiResourceKind {
  * created via the in-process client AFTER Persist (children need the
  * parent's id), status.default_instance_id lands in an explicit second
  * persist, and v1 archives LAST so the snapshot captures it (the audit
- * step re-persists on revert because no Persist follows it here).
+ * step re-persists either of its reverts, a stripped hash or a cleared
+ * tag, because no Persist follows it here).
  */
 async function createWorkflow(
   deps: WorkflowControllerDeps,

package/src/domain/workflow/steps.ts

@@ -354,10 +354,13 @@ export function newPopulateVersionHashStep(
  * duplicate row beats a failed apply.
  *
  * On archive failure the version hash is stripped from the workflow so a
- * set hash always resolves to an audit entry (the revert invariant);
- * persistOnRevert re-persists when this step runs AFTER the final persist
- * (the create path archives last so default_instance_id is captured; the
- * update path has a Persist step following that flushes the revert).
+ * set hash always resolves to an audit entry (the revert invariant); on
+ * tag-assignment failure the live tag is cleared so the head never
+ * advertises a tag the audit column cannot resolve (stigmer/stigmer#855).
+ * persistOnRevert flushes either revert to the stored row, for a chain in
+ * which no Persist step follows this one (the create path archives last so
+ * default_instance_id is captured; the update path has a Persist step
+ * following that flushes the revert itself).
  */
 export function newSaveVersionAuditStep(
   store: Store,
@@ -385,6 +388,27 @@ export function newSaveVersionAuditStep(
           ? ctx.apiResourceKind
           : ApiResourceKind.workflow;
 
+      // A revert changes the head after the chain's last write, so it
+      // reaches the stored row only through this re-persist. A failure here
+      // is logged, never a failed apply: the response is already consistent
+      // and the next apply rewrites the row.
+      const flushRevert = async (revert: string): Promise<void> => {
+        if (!persistOnRevert) {
+          return;
+        }
+        try {
+          await store.saveResource(kind, workflowId, WorkflowSchema, wf);
+        } catch (persistError) {
+          logger.error(`failed to re-persist workflow after ${revert}`, {
+            error:
+              persistError instanceof Error
+                ? persistError.message
+                : String(persistError),
+            workflowId,
+          });
+        }
+      };
+
       let alreadyArchived = false;
       try {
         await store.getAuditByHash(kind, workflowId, versionHash, WorkflowSchema);
@@ -428,20 +452,7 @@ export function newSaveVersionAuditStep(
             wf.metadata.version.id = "";
           }
           ctx.setNewState(wf);
-
-          if (persistOnRevert) {
-            try {
-              await store.saveResource(kind, workflowId, WorkflowSchema, wf);
-            } catch (persistError) {
-              logger.error("failed to re-persist workflow after reverting version hash", {
-                error:
-                  persistError instanceof Error
-                    ? persistError.message
-                    : String(persistError),
-                workflowId,
-              });
-            }
-          }
+          await flushRevert("reverting version hash");
           return;
         }
       }
@@ -468,6 +479,7 @@ export function newSaveVersionAuditStep(
           if (wf.metadata?.version !== undefined) {
             wf.metadata.version.tag = "";
             ctx.setNewState(wf);
+            await flushRevert("clearing its tag");
           }
         }
       }

package/src/extensions/__tests__/extension-composition.test.ts

@@ -8,7 +8,10 @@
  * services), and the registry-declared edition answers on getServerInfo.
  * Later entries add their own composed arms below: caller guards
  * (20260902.02), the require-authentication posture (20260904.02), the
- * O5 drivers, the O4 slots and hooks, the C2 tuple lifecycle.
+ * O5 drivers, the O4 slots and hooks, the C2 tuple lifecycle, and the
+ * organization directory's external-id lookup: scoped to the identity
+ * provider the request names, and answered only to a caller who may view
+ * that provider, with one NotFound for every miss.
  *
  * The empty-set arm — no extensions composed, wire behavior byte-identical
  * to before the parameter existed — is pinned where it belongs: the
@@ -43,6 +46,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { ApiKeyCommandController } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/command_pb";
 import { ApiKeyQueryController } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/query_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 import {
   PlatformQueryController,
   ServerEdition,
@@ -62,6 +66,7 @@ import type { ComposedServer } from "../../boot/compose.js";
 import { createLogger } from "../../boot/logger.js";
 import { AUTHENTICATION_TOKEN_MISSING_MESSAGE } from "../../pipeline/interceptors/auth.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { AuthzCheck } from "../authorizer.js";
 import type { GateSlotName } from "../gate-slots.js";
 import type { OrganizationDirectory } from "../organization-directory.js";
 import type {
@@ -73,6 +78,16 @@ import type {
 import type { AgentExecutionStatusTransition } from "../status-hooks.js";
 import type { ServerExtension } from "../registry.js";
 
+/** The refusal a call answered; a call that succeeds fails the case. */
+async function refusalOf(work: Promise<unknown>): Promise<ConnectError> {
+  try {
+    await work;
+  } catch (error) {
+    return ConnectError.from(error);
+  }
+  throw new Error("the call was admitted");
+}
+
 const BILLING_PROCEDURE =
   "/ai.stigmer.billing.v1.BillingQueryController/getBillingAccount";
 
@@ -1019,16 +1034,46 @@ describe("extension composition (C2 tuple lifecycle + organization directory)",
   // The directory answers are test-mutable so each case can stage its
   // own world without a second composed server.
   const myOrgIds: string[] = [];
+  // Providers by `org/slug` → id, and mappings by `providerId:externalId`:
+  // the directory scopes every lookup to the provider the request names.
+  const providers = new Map<string, string>([
+    ["c2seededorg/test-idp", "idp_viewable"],
+    ["c2seededorg/other-idp", "idp_other"],
+    ["c2seededorg/hidden-idp", "idp_hidden"],
+  ]);
   const externalOrgMap = new Map<string, string>();
   const fakeDirectory: OrganizationDirectory = {
     refusesEnumeration: true,
     listMyOrganizationIds: async () => [...myOrgIds],
-    getOrganizationIdByExternalOrgId: async (externalOrgId) =>
-      externalOrgMap.get(externalOrgId),
+    lookupExternalOrganization: async (ref, externalOrgId) => {
+      const providerId = providers.get(`${ref.org}/${ref.slug}`);
+      return providerId === undefined
+        ? { kind: "no-identity-provider" }
+        : {
+            kind: "resolved",
+            identityProviderId: providerId,
+            organizationId: externalOrgMap.get(`${providerId}:${externalOrgId}`),
+          };
+    },
   };
+  // Every check is allowed except viewing the providers named here, so the
+  // lookup's own authorization is the one refusal the suite can see.
+  const deniedProviders = new Set<string>(["idp_hidden"]);
+  const lookupChecks: AuthzCheck[] = [];
 
   const iamExtension: ServerExtension = {
     name: "fake-iam",
+    authorizer: {
+      authorize: (_caller, check) => {
+        if (check.resourceKind === ApiResourceKind.identity_provider) {
+          lookupChecks.push(check);
+          if (deniedProviders.has(check.resourceId)) {
+            return Promise.resolve({ kind: "deny", reason: "" });
+          }
+        }
+        return Promise.resolve({ kind: "allow" });
+      },
+    },
     drivers: {
       resourceAuthorizationLifecycle: fakeLifecycle,
       organizationDirectory: fakeDirectory,
@@ -1077,7 +1122,8 @@ describe("extension composition (C2 tuple lifecycle + organization directory)",
     expect(event.parentLinks).toEqual([]);
     expect(event.caller.identityId).not.toBe("");
     myOrgIds.push(org.metadata?.id ?? "");
-    externalOrgMap.set("ext-org-42", org.metadata?.id ?? "");
+    externalOrgMap.set("idp_viewable:ext-org-42", org.metadata?.id ?? "");
+    externalOrgMap.set("idp_hidden:ext-org-42", org.metadata?.id ?? "");
   });
 
   it("agent create fires creation events for the agent AND its in-process default instance", async () => {
@@ -1236,26 +1282,52 @@ describe("extension composition (C2 tuple lifecycle + organization directory)",
     expect(mine.entries.map((org) => org.metadata?.id)).toEqual(myOrgIds);
   });
 
-  it("getByExternalOrgId registers with the directory lookup and resolves the mapping", async () => {
+  it("getByExternalOrgId resolves a mapping under the named provider for a caller who may view it", async () => {
     const query = createClient(OrganizationQueryController, portTransport);
-    // identity_provider_ref is proto-required on the lookup message; the
-    // directory's resolution key is the (globally unique) external id.
-    const idpRef = { org: "c2seededorg", slug: "test-idp" };
+    lookupChecks.length = 0;
     const org = await query.getByExternalOrgId({
-      identityProviderRef: idpRef,
+      identityProviderRef: { org: "c2seededorg", slug: "test-idp" },
       externalOrgId: "ext-org-42",
     });
     expect(org.metadata?.id).toBe(myOrgIds[0]);
+    expect(lookupChecks).toEqual([
+      {
+        permission: IamPermission.can_view,
+        resourceKind: ApiResourceKind.identity_provider,
+        resourceId: "idp_viewable",
+      },
+    ]);
+  });
 
-    let missing: ConnectError | undefined;
-    try {
-      await query.getByExternalOrgId({
-        identityProviderRef: idpRef,
-        externalOrgId: "ext-org-unknown",
-      });
-    } catch (error) {
-      missing = ConnectError.from(error);
+  it("getByExternalOrgId refuses a caller who may not view the named provider, before saying whether a mapping exists", async () => {
+    const query = createClient(OrganizationQueryController, portTransport);
+    for (const externalOrgId of ["ext-org-42", "ext-org-unknown"]) {
+      const refused = await refusalOf(
+        query.getByExternalOrgId({
+          identityProviderRef: { org: "c2seededorg", slug: "hidden-idp" },
+          externalOrgId,
+        }),
+      );
+      expect(refused.code).toBe(Code.PermissionDenied);
+      expect(refused.rawMessage).toBe("unauthorized to view identity provider");
+    }
+  });
+
+  it("getByExternalOrgId answers one NotFound for an unknown provider, an unmapped id, and another provider's mapping", async () => {
+    const query = createClient(OrganizationQueryController, portTransport);
+    for (const [slug, externalOrgId] of [
+      ["no-such-idp", "ext-org-42"],
+      ["test-idp", "ext-org-unknown"],
+      ["other-idp", "ext-org-42"],
+    ] as const) {
+      const missing = await refusalOf(
+        query.getByExternalOrgId({
+          identityProviderRef: { org: "c2seededorg", slug },
+          externalOrgId,
+        }),
+      );
+      expect(missing.code).toBe(Code.NotFound);
+      expect(missing.rawMessage).toBe(`Organization not found: ${externalOrgId}`);
     }
-    expect(missing?.code).toBe(Code.NotFound);
   });
 });

package/src/extensions/organization-directory.ts

@@ -15,7 +15,11 @@
  *     and the built-in directory filter to what the caller may view.
  *   - `getByExternalOrgId` (capability `externalOrgLookup`): deliberately
  *     absent from the OSS partial registration (UNIMPLEMENTED by
- *     construction); the cloud resolves external IdP org ids.
+ *     construction); the cloud resolves external IdP org ids. The lookup
+ *     is scoped to the identity provider the request names: the directory
+ *     resolves that provider and the external id within it, and the
+ *     controller answers only a caller who may view the provider, so one
+ *     integrator's tenant ids never answer another's organizations.
  *
  * No directory composed = the trusted-local behavior, byte-identical; the
  * built-in directory (authorization/organization-directory.ts) composes
@@ -47,12 +51,34 @@ export interface OrganizationDirectory {
     caller: CallerIdentity,
   ): Promise<ReadonlyArray<string> | typeof ALL_ORGANIZATIONS>;
   /**
-   * Resolves an external IdP organization id to the org's resource id;
-   * undefined = no mapping. When this method is present, the controller
-   * registers `getByExternalOrgId` (its chain stays controller-owned);
-   * when absent, the RPC stays unregistered and answers UNIMPLEMENTED.
+   * Resolves the identity provider a lookup names, and the external IdP
+   * organization id within that provider alone. When this method is
+   * present, the controller registers `getByExternalOrgId` (its chain,
+   * the provider's authorization included, stays controller-owned); when
+   * absent, the RPC stays unregistered and answers UNIMPLEMENTED.
    */
-  getOrganizationIdByExternalOrgId?(
+  lookupExternalOrganization?(
+    identityProviderRef: IdentityProviderRef,
     externalOrgId: string,
-  ): Promise<string | undefined>;
+  ): Promise<ExternalOrganizationLookup>;
 }
+
+/** The identity provider a lookup names: its organization and its slug. */
+export interface IdentityProviderRef {
+  readonly org: string;
+  readonly slug: string;
+}
+
+/**
+ * What a directory found for a lookup: no such identity provider, or the
+ * provider's id with the organization its external id maps to under it
+ * (undefined = no mapping). The controller authorizes on the provider's
+ * id before it reveals whether a mapping exists.
+ */
+export type ExternalOrganizationLookup =
+  | { readonly kind: "no-identity-provider" }
+  | {
+      readonly kind: "resolved";
+      readonly identityProviderId: string;
+      readonly organizationId: string | undefined;
+    };

package/src/index.ts

@@ -116,7 +116,11 @@ export type {
   VisibilityTupleShape,
   ResolvedParentLink,
 } from "./extensions/resource-authorization.js";
-export type { OrganizationDirectory } from "./extensions/organization-directory.js";
+export type {
+  ExternalOrganizationLookup,
+  IdentityProviderRef,
+  OrganizationDirectory,
+} from "./extensions/organization-directory.js";
 export { ALL_ORGANIZATIONS } from "./extensions/organization-directory.js";
 // The license-status seam (drivers.licenseStatus): the provider an
 // Enterprise composition registers so getLicenseStatus answers from its