@stigmer/server 3.24.0 → 3.25.0

package/src/authorization/authorizer.ts

@@ -78,10 +78,16 @@ import { formatObjectRef } from "./tuples.js";
 
 /**
  * Kinds whose missing row is a denial, never `not-found` (arm 4): the
- * cloud's `PROBE_EXEMPT_KINDS` restricted to the kinds this edition
- * serves — `platform`, `identity_provider`, `platform_client` and
- * `invitation` are refused by arm 2 before any row is asked about. The
- * cloud's drift test pins the two sets equal over the open-source tier.
+ * cloud's `PROBE_EXEMPT_KINDS` (stigmer-cloud
+ * src/authorizer/fga-authorizer.ts) restricted to the kinds this edition
+ * serves — `platform`, `identity_provider` and `invitation` are refused by
+ * arm 2 before any row is asked about. The cloud exempts them because
+ * 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
+ * `PROBE_EXEMPT_KINDS`, which is why this set is exported; a kind that
+ * moves into open source joins this set in the same change.
  *
  * `iam_policy` is reachable as a target through the IamPolicy RPCs' own
  * `resource.kind` (a caller may name it); the grant scope refuses such a
@@ -91,6 +97,7 @@ import { formatObjectRef } from "./tuples.js";
 export const NOT_FOUND_EXEMPT_KINDS: ReadonlySet<ApiResourceKind> = new Set([
   ApiResourceKind.identity_account,
   ApiResourceKind.iam_policy,
+  ApiResourceKind.platform_client,
 ]);
 
 /** The Java RequestAuthorizationService's pre-check copy, byte for byte (the cloud renders the same). */

package/src/authorization/model/__tests__/registry.test.ts

@@ -34,6 +34,7 @@ const DECLARED_KINDS = [
   ApiResourceKind.iam_policy,
   ApiResourceKind.api_key,
   ApiResourceKind.oauth_app,
+  ApiResourceKind.platform_client,
   ApiResourceKind.organization,
   ApiResourceKind.agent,
   ApiResourceKind.agent_channel,
@@ -94,6 +95,13 @@ const WIRE_PERMISSIONS_BY_TYPE: Readonly<
     "can_grant_access",
     "can_view_access",
   ],
+  platform_client: [
+    "can_view",
+    "can_edit",
+    "can_delete",
+    "can_grant_access",
+    "can_view_access",
+  ],
   organization: [
     "can_view",
     "can_edit",
@@ -262,7 +270,6 @@ describe("the built-in model's registry", () => {
     for (const unserved of [
       ApiResourceKind.platform,
       ApiResourceKind.identity_provider,
-      ApiResourceKind.platform_client,
       ApiResourceKind.invitation,
     ]) {
       expect(declarationFor(unserved), kindEnumName(unserved)).toBeUndefined();

package/src/authorization/model/index.ts

@@ -12,11 +12,11 @@
  * chain past the depth bound) and for the cloud's drift test, which
  * builds a model from the live `.fga` files and compares.
  *
- * Registered: every kind of the open-source tier — the twenty-three
- * `kind_meta.tier: open_source` members — and nothing else. The four
+ * Registered: every kind of the open-source tier — the twenty-four
+ * `kind_meta.tier: open_source` members — and nothing else. The three
  * files `fga.mod` lists that have no declaration here (`platform`,
- * `identity_provider`, `platform_client`, `invitation`) are kinds this
- * edition does not serve: a check that targets one is refused by the
+ * `identity_provider`, `invitation`) are kinds this edition does not
+ * serve: a check that targets one is refused by the
  * driver, and a tuple that names one (`identity_provider#platform_user`)
  * resolves to nobody. The registry test pins the list against the tier.
  */
@@ -38,6 +38,7 @@ import { mcpServerDeclaration } from "./mcp_server.js";
 import { memoryDeclaration } from "./memory.js";
 import { oauthAppDeclaration } from "./oauth_app.js";
 import { organizationDeclaration } from "./organization.js";
+import { platformClientDeclaration } from "./platform_client.js";
 import { pluginDeclaration } from "./plugin.js";
 import type { KindDeclaration } from "./rewrite.js";
 import { scheduleDeclaration } from "./schedule.js";
@@ -77,6 +78,7 @@ export const builtInModel: Model = newModel([
   iamPolicyDeclaration,
   apiKeyDeclaration,
   oauthAppDeclaration,
+  platformClientDeclaration,
   organizationDeclaration,
   agentDeclaration,
   agentChannelDeclaration,

package/src/authorization/model/oauth_app.ts

@@ -1,6 +1,7 @@
 /**
- * Transcript of fga/model/iam/oauth_app.fga — the one organization-scoped
- * kind whose `owner` has NO admin arm while its `viewer` does: the file's
+ * Transcript of fga/model/iam/oauth_app.fga — an organization-scoped kind
+ * whose `owner` has NO admin arm while its `viewer` does (platform_client
+ * shares the shape, for the same reason): the file's
  * "administrative visibility" for the organization's admins over a
  * registration that holds vendor client credentials, with change and
  * deletion the creator's (or an explicit grant's) alone, and no public

package/src/authorization/model/platform_client.ts

@@ -0,0 +1,43 @@
+/**
+ * Transcript of fga/model/iam/platform_client.fga — relation for relation
+ * the oauth_app shape: organization-scoped, an `owner` with no admin arm
+ * and a `viewer` that has one. A platform client holds credential material,
+ * so the model is restricted: its creator (the owner) edits, deletes,
+ * rotates and grants; the organization's admins may view it; ordinary
+ * members have no access at all, which is why listByOrg narrows through
+ * the list read scope. There is no public level.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const platformClientDeclaration = declareKind({
+  kind: ApiResourceKind.platform_client,
+  schema: PlatformClientSchema,
+  source: "fga/model/iam/platform_client.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    ["owner", direct(objectOf("identity_account"))],
+    [
+      "viewer",
+      union(
+        direct(objectOf("identity_account")),
+        computed("owner"),
+        from("admin", "organization"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/boot/__tests__/auth-enabled-composition.test.ts

@@ -236,10 +236,11 @@ describe("the require-authentication posture on the wire", () => {
     );
   });
 
-  it("is_public methods stay reachable tokenless (getServerInfo)", async () => {
+  it("is_public methods stay reachable tokenless (getServerInfo), and it reports the posture", async () => {
     const platform = createClient(PlatformQueryController, transportWith());
     const info = await platform.getServerInfo({});
     expect(info.edition).not.toBe("");
+    expect(info.authenticationRequired).toBe(true);
   });
 
   it("the gRPC health service stays reachable tokenless — a Kubernetes grpc probe survives the posture (stigmer#974)", async () => {

package/src/boot/__tests__/route-shadowing.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Pins the routes stage's refusal of a shadowing registration: Connect's
+ * router lets the last registration of a path win silently, so an
+ * extension that registers a service the core already serves — or that
+ * another extension already registered — must fail boot, naming itself and
+ * whoever serves the path. Distinct services pass untouched, in order.
+ */
+import { createConnectRouter } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { OAuthAppQueryController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/query_pb";
+import { PlatformClientQueryController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/query_pb";
+import { PlatformClientTokenController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+
+import { registerExtensionServicesUnshadowed } from "../route-shadowing.js";
+
+describe("registerExtensionServicesUnshadowed", () => {
+  it("refuses an extension service the core already serves, naming the unit and the path", () => {
+    const router = createConnectRouter();
+    router.service(PlatformClientTokenController, {});
+    expect(() =>
+      registerExtensionServicesUnshadowed(router, [
+        {
+          unit: "cloud-iam",
+          register: (r) => void r.service(PlatformClientTokenController, {}),
+        },
+      ]),
+    ).toThrow(
+      /extension 'cloud-iam' registers \/ai\.stigmer\.iam\.platformclient\.v1\.PlatformClientTokenController\/mintUserToken, which the core already serves/,
+    );
+  });
+
+  it("refuses a second extension registering what a first one did", () => {
+    const router = createConnectRouter();
+    expect(() =>
+      registerExtensionServicesUnshadowed(router, [
+        {
+          unit: "first",
+          register: (r) => void r.service(OAuthAppQueryController, {}),
+        },
+        {
+          unit: "second",
+          register: (r) =>
+            void r.rpc(OAuthAppQueryController.method.get, () => {
+              throw new Error("never called");
+            }),
+        },
+      ]),
+    ).toThrow(
+      /extension 'second' registers .*OAuthAppQueryController\/get, which extension 'first' already serves/,
+    );
+  });
+
+  it("registers distinct services from every unit", () => {
+    const router = createConnectRouter();
+    router.service(OAuthAppQueryController, {});
+    registerExtensionServicesUnshadowed(router, [
+      {
+        unit: "billing",
+        register: (r) => void r.service(PlatformClientQueryController, {}),
+      },
+    ]);
+    expect(router.handlers.map((handler) => handler.requestPath)).toContain(
+      "/ai.stigmer.iam.platformclient.v1.PlatformClientQueryController/listByOrg",
+    );
+  });
+});

package/src/boot/compose.ts

@@ -108,6 +108,11 @@ import { registerExecutionContextServices } from "../domain/executioncontext/con
 import { registerGitHubServices } from "../domain/github/controller.js";
 import { registerMemoryServices } from "../domain/memory/controller.js";
 import { registerOAuthAppServices } from "../domain/oauthapp/controller.js";
+import { registerPlatformClientServices } from "../domain/platformclient/controller.js";
+import { newPlatformClientOriginGuard } from "../domain/platformclient/origin-guard.js";
+import { newResourcePlatformClientStore } from "../domain/platformclient/resource-store.js";
+import { registerPlatformClientTokenService } from "../domain/platformclient/token-controller.js";
+import { newPlatformClientTokenVerifier } from "../domain/platformclient/verifier.js";
 import { registerOrganizationServices } from "../domain/organization/controller.js";
 import { registerMcpServerServices } from "../domain/mcpserver/controller.js";
 import { registerPlatformServices } from "../domain/platform/controller.js";
@@ -144,6 +149,7 @@ import {
 import type { SecretCodec } from "../encryption/codec.js";
 import { getOrCreateNamedKey } from "../encryption/key-manager.js";
 import { V1_VERSION } from "../encryption/v1-codec.js";
+import { resolvePlatformTokenKeys } from "../platformtoken/key-ring.js";
 import { registerActivityServices } from "../query/activity/controller.js";
 import { ActivityHandler } from "../query/activity/handler.js";
 import { registerSearchServices } from "../query/search/controller.js";
@@ -203,6 +209,7 @@ import {
 } from "../transport/console/handler.js";
 import { createRegistryLanes } from "../transport/registry/lanes.js";
 import { createUnifiedPortServer } from "../transport/server.js";
+import { registerExtensionServicesUnshadowed } from "./route-shadowing.js";
 import type { ServerConfig } from "./config.js";
 import { createInProcessClients } from "./inprocess.js";
 import type { InProcessClients } from "./inprocess.js";
@@ -413,6 +420,14 @@ export async function composeServer(
   // bindings are what the IamPolicy controller registers over (routes).
   const iamPolicies =
     extensions.drivers.iamPolicyStore ?? newResourceIamPolicyStore(store);
+  // The PlatformClient store PORT, bound the same way
+  // (`drivers.platformClientStore`; open source's adapter over `store`
+  // when absent): the chains, the mint and the verifier's liveness read all
+  // go through this one binding, so a composed driver is followed
+  // everywhere by construction.
+  const platformClients =
+    extensions.drivers.platformClientStore ??
+    newResourcePlatformClientStore(store);
   const iamPolicyGrantPath = newIamPolicyGrantPath({
     policies: iamPolicies,
     lifecycle: extensions.drivers.resourceAuthorizationLifecycle,
@@ -690,6 +705,26 @@ export async function composeServer(
       writeVersionValue === "" ? DEFAULT_WRITE_VERSION : writeVersionValue,
     registeredCodecs: [...secretCodecs.keys()].sort(),
   });
+  // The platform-token key ring joins the FATAL side of the asymmetry:
+  // under an authentication posture a server that cannot sign or verify
+  // its own tokens would refuse every PlatformClient-minted caller, and an
+  // explicitly configured key that does not load is configuration the
+  // operator meant (the ladder's rule). No posture, no ring
+  // (resolvePlatformTokenKeys carries the four arms).
+  const platformTokenKeys = resolvePlatformTokenKeys({
+    requireAuthentication,
+    supplied: extensions.drivers.platformTokenKeys,
+    edition: extensions.edition,
+  });
+  logger.info("platform-token keys resolved", {
+    source:
+      platformTokenKeys === undefined
+        ? "none (no authentication posture)"
+        : extensions.drivers.platformTokenKeys !== undefined
+          ? "extension"
+          : "open-source ladder",
+    signing: platformTokenKeys?.signer !== undefined,
+  });
   // Stage: temporal (#18). Construction is sync and connection-free —
   // initialConnect/startWorkers/startHealthMonitor run in start(), all
   // NON-fatal (Go server.go: the server boots and serves with the engine
@@ -1284,6 +1319,34 @@ export async function composeServer(
       authorizer,
       authorizationLifecycle,
     });
+    // PlatformClient, OAuthApp's inbound counterpart: served in every
+    // composition over the store PORT bound above. The token service is
+    // registered here too — mintGuestToken dispatches to the composed
+    // capability — so nothing else may register it (route-shadowing.ts).
+    // The mint writes end users through the identity-account create path
+    // and the one grant path, as the platform client (mint.ts), and signs
+    // with the ring the keys stage resolved (none without a posture: the
+    // mint then refuses).
+    registerPlatformClientServices(router, {
+      clients: platformClients,
+      store,
+      logger,
+      authorizer,
+      authorizationLifecycle,
+      listReadScope,
+    });
+    registerPlatformClientTokenService(router, {
+      mint: {
+        clients: platformClients,
+        accounts: identityAccounts,
+        createAccount: createIdentityAccount,
+        grantPath: iamPolicyGrantPath,
+        keys: platformTokenKeys,
+        logger,
+        now: () => new Date(),
+      },
+      guestTokenMinting: extensions.drivers.guestTokenMinting,
+    });
     registerExecutionContextServices(router, {
       store,
       logger,
@@ -1549,6 +1612,7 @@ export async function composeServer(
       runnerAuthService: runnerCredentials,
       edition: extensions.edition,
       version: options.version ?? SERVER_VERSION,
+      authenticationRequired: requireAuthentication,
       // The built-in `absent` answer installs here, at the consumer, when
       // no unit registered a license-status provider: open source and the
       // cloud hold no key, and only an Enterprise unit ever has one.
@@ -1559,10 +1623,9 @@ export async function composeServer(
     // Extension services register after the whole OSS set, inside the ONE
     // routes closure — so the serving router AND the in-process transport
     // see them by construction (blueprint §2a; DD-002's parity doctrine
-    // extends to extension services unchanged).
-    for (const registerExtensionServices of extensions.services) {
-      registerExtensionServices(router);
-    }
+    // extends to extension services unchanged). A registration that would
+    // shadow a route already served is a boot throw (route-shadowing.ts).
+    registerExtensionServicesUnshadowed(router, extensions.services);
   };
   const inProcessWiring = createInProcessClients(routes, logger);
   inProcess = inProcessWiring.clients;
@@ -1610,6 +1673,18 @@ export async function composeServer(
     ...(requireAuthentication
       ? [newApiKeyIdentityVerifier({ store, accounts: identityAccounts })]
       : []),
+    // The PlatformClient user-token lane rides the ring, which the keys
+    // stage resolves only under an authentication posture. It sits before
+    // `oidc` for the runner-subject verifier's reason (stigmer#1137): the
+    // OIDC verifier would claim the platform token and throw on it.
+    ...(platformTokenKeys !== undefined
+      ? [
+          newPlatformClientTokenVerifier({
+            keys: platformTokenKeys,
+            clients: platformClients,
+          }),
+        ]
+      : []),
     ...(authorizationPosture === "built-in"
       ? [
           newRunnerSubjectIdentityVerifier({
@@ -1652,6 +1727,16 @@ export async function composeServer(
       ? [`extension '${extensions.requireAuthentication.declaredBy}'`]
       : []),
   ];
+  // Caller guards: open source's own first, then the extensions' — the
+  // rule the verifier list follows ("OSS entries first"). The origin guard
+  // exists only where PlatformClient tokens can be presented, under the
+  // posture that verifies them.
+  const callerGuards = [
+    ...(platformTokenKeys !== undefined
+      ? [newPlatformClientOriginGuard({ clients: platformClients, logger })]
+      : []),
+    ...extensions.callerGuards,
+  ];
   logger.info("authentication posture resolved", {
     posture: requireAuthentication ? "required" : "trusted-local",
     source: postureSources.length > 0 ? postureSources.join(" + ") : "none",
@@ -1680,7 +1765,7 @@ export async function composeServer(
       logger,
       createVerifierChainInterceptor(
         identityVerifiers,
-        extensions.callerGuards,
+        callerGuards,
         logger,
         requireAuthentication,
       ),

package/src/boot/route-shadowing.ts

@@ -0,0 +1,47 @@
+/**
+ * The routes stage's one refusal: an extension may not register a route
+ * the router already serves.
+ *
+ * Connect's router keeps every registration, and both the serving adapter
+ * and the in-process transport build their path table with a plain map
+ * set, so a second registration of `/<service>/<method>` silently wins.
+ * Extensions register after the whole core set (compose.ts), so a
+ * composition that re-registers a service the core has come to serve —
+ * the moment a cloud domain moves into open source and the cloud's pin
+ * advances without deleting its own handlers — would shadow the core with
+ * no error, and serve from whatever store its old handlers read. Refusing
+ * at boot turns that into the loudest possible failure; the fix is always
+ * the domain's driver point, never a second service.
+ *
+ * Checked per request path, because `router.service` registers every
+ * method of a descriptor (the unimplemented ones answering UNIMPLEMENTED)
+ * and `router.rpc` registers one; two extensions colliding with each
+ * other are refused the same way.
+ */
+import type { ConnectRouter } from "@connectrpc/connect";
+
+import type { ResolvedServiceRegistration } from "../extensions/registry.js";
+
+/** Runs each extension registration, refusing any path already routed. */
+export function registerExtensionServicesUnshadowed(
+  router: ConnectRouter,
+  registrations: ReadonlyArray<ResolvedServiceRegistration>,
+): void {
+  // Request path → who serves it, as the refusal names them.
+  const servedBy = new Map<string, string>(
+    router.handlers.map((handler) => [handler.requestPath, "the core"]),
+  );
+  for (const { unit, register } of registrations) {
+    const before = router.handlers.length;
+    register(router);
+    for (const handler of router.handlers.slice(before)) {
+      const server = servedBy.get(handler.requestPath);
+      if (server !== undefined) {
+        throw new Error(
+          `extension '${unit}' registers ${handler.requestPath}, which ${server} already serves — a route is never registered twice; an edition changes a core domain's behaviour through its driver points`,
+        );
+      }
+      servedBy.set(handler.requestPath, `extension '${unit}'`);
+    }
+  }
+}

package/src/domain/iampolicy/__tests__/membership.test.ts

@@ -639,6 +639,13 @@ describe("membership rules", () => {
         IdentityAccountProvisioningMode.machine;
       expect(isPersonAccount(machineMode)).toBe(false);
     });
+
+    it("a platform-client end user is not: the mint grants it its client's role and nothing else", () => {
+      const endUser = account("stgm_pc|acme|user-7", OPERATOR_EMAIL);
+      endUser.spec!.provisioningMode =
+        IdentityAccountProvisioningMode.platform_client;
+      expect(isPersonAccount(endUser)).toBe(false);
+    });
   });
 
   describe("ensureRolesForExistingAccounts", () => {

package/src/domain/iampolicy/membership.ts

@@ -195,14 +195,20 @@ export function isPersonStamp(stamp: string): boolean {
  * `user`-class gate, for the reconciliation, which has a row and no
  * caller. A machine account (`is_machine_account`, or the `machine`
  * provisioning mode) earns no role, exactly as a `machine`-class caller
- * earns none at the hook.
+ * earns none at the hook. Nor does a platform-client end user: it is a
+ * person on its platform's product, not on this install — the mint grants
+ * it exactly its client's auto-grant role on the owning organization and
+ * never runs these rules, and the reconciliation must not either, or every
+ * product user would become a member of every organization (and the
+ * operator-email arm would read an email the platform asserted).
  */
 export function isPersonAccount(account: IdentityAccount): boolean {
   const spec = account.spec;
   return (
     spec !== undefined &&
     !spec.isMachineAccount &&
-    spec.provisioningMode !== IdentityAccountProvisioningMode.machine
+    spec.provisioningMode !== IdentityAccountProvisioningMode.machine &&
+    spec.provisioningMode !== IdentityAccountProvisioningMode.platform_client
   );
 }
 

package/src/domain/identityaccount/__tests__/platform-client-accounts.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Pins the identity-account create path's platform-client arm over the OSS
+ * adapter on sqlite:
+ *   - `platform_client` provisioning writes the mode, the owning
+ *     organization and the derived id, with the actor the caller named;
+ *   - the `stgm_pc|` subject namespace is reserved in both directions: a
+ *     direct account refuses it INVALID_ARGUMENT before anything is written,
+ *     and a platform-client account without it is the caller's bug;
+ *   - the direct lookups never answer the platform-client account, while the
+ *     any-mode lookup (the mint's) does.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
+import { IdentityAccountSpecSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
+
+import { silentLogger } from "../../../extensions/__tests__/composed-support.js";
+import { serverActingFor } from "../../../pipeline/interceptors/auth.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { tempStore } from "../../../store/sqlite/__tests__/support.js";
+import type { TempStore } from "../../../store/sqlite/__tests__/support.js";
+import { accountIdFor, reservedSubjectMessage } from "../constants.js";
+import { newCreateAccountPath } from "../controller.js";
+import type { CreateAccount } from "../provisioning.js";
+import { newResourceIdentityAccountStore } from "../resource-store.js";
+import type { IdentityAccountStore } from "../store.js";
+
+let temp: TempStore;
+let accounts: IdentityAccountStore;
+let createAccount: CreateAccount;
+
+beforeEach(() => {
+  temp = tempStore();
+  accounts = newResourceIdentityAccountStore(temp.store);
+  createAccount = newCreateAccountPath(
+    {
+      accounts,
+      logger: silentLogger,
+      authorizer: newPermissiveSingleTeamAuthorizer(),
+      authorizationLifecycle: undefined,
+    },
+    ApiResourceKind.identity_account,
+  );
+});
+
+afterEach(() => {
+  temp.cleanup();
+});
+
+const SUBJECT = "stgm_pc|acme|user-7";
+const CLIENT = serverActingFor("pcl_dashboard");
+
+async function refusal(promise: Promise<unknown>): Promise<ConnectError> {
+  try {
+    await promise;
+  } catch (error) {
+    if (error instanceof ConnectError) return error;
+    throw error;
+  }
+  throw new Error("expected a ConnectError refusal");
+}
+
+describe("the create path's platform-client arm", () => {
+  it("writes the mode, the owning organization and the derived id, stamped as the client", async () => {
+    const account = await createAccount(
+      {
+        name: "pat@example.com",
+        spec: create(IdentityAccountSpecSchema, {
+          idpId: SUBJECT,
+          email: "pat@example.com",
+        }),
+        provisioning: { mode: "platform_client", org: "acme" },
+      },
+      CLIENT,
+    );
+    expect(account.metadata?.id).toBe(accountIdFor(SUBJECT));
+    expect(account.metadata?.org).toBe("acme");
+    expect(account.spec?.provisioningMode).toBe(
+      IdentityAccountProvisioningMode.platform_client,
+    );
+    expect(account.status?.audit?.specAudit?.createdBy?.id).toBe(
+      "pcl_dashboard",
+    );
+
+    expect(await accounts.findDirectByIdpId(SUBJECT)).toBeUndefined();
+    expect(await accounts.findDirectByEmail("pat@example.com")).toBeUndefined();
+    expect((await accounts.findByIdpId(SUBJECT))?.metadata?.id).toBe(
+      accountIdFor(SUBJECT),
+    );
+  });
+
+  it("refuses a direct account under the reserved subject prefix, writing nothing", async () => {
+    const denied = await refusal(
+      createAccount(
+        {
+          name: "impostor",
+          spec: create(IdentityAccountSpecSchema, { idpId: SUBJECT }),
+          provisioning: { mode: "direct" },
+        },
+        CLIENT,
+      ),
+    );
+    expect(denied.code).toBe(Code.InvalidArgument);
+    expect(denied.rawMessage).toBe(reservedSubjectMessage(SUBJECT));
+    expect(await accounts.findByIdpId(SUBJECT)).toBeUndefined();
+  });
+
+  it("refuses a platform-client account without the reserved prefix as a server fault", async () => {
+    const denied = await refusal(
+      createAccount(
+        {
+          name: "stray",
+          spec: create(IdentityAccountSpecSchema, { idpId: "auth0|stray" }),
+          provisioning: { mode: "platform_client", org: "acme" },
+        },
+        CLIENT,
+      ),
+    );
+    expect(denied.code).toBe(Code.Internal);
+  });
+});

package/src/domain/identityaccount/__tests__/resource-store.test.ts

@@ -54,6 +54,7 @@ const CONTRACT_CASE_NAMES = [
   "a disconnected store is an infrastructure fault, never 'not found'",
   "two concurrent saves of one subject end in fulfilments and DuplicateAccountErrors only, and the winner is readable by subject",
   "findDirectByIdpId and findDirectByEmail never answer a federated account, while findByIdpId (any mode) does",
+  "findDirectByIdpId and findDirectByEmail never answer a platform-client account, while findByIdpId (any mode) does",
   "findByIds answers one row per distinct id, in first-occurrence order; an empty request answers an empty list",
   "update of an unknown id is a no-op: no row appears",
   "deleteById of an unknown id resolves",

package/src/domain/identityaccount/constants.ts

@@ -110,6 +110,26 @@ export function isMachineSubject(idpId: string): boolean {
   return idpId.endsWith(MACHINE_ACCOUNT_SUFFIX);
 }
 
+/**
+ * The subject namespace of PlatformClient end users:
+ * `stgm_pc|<org>|<external_user_id>` (the composite every client of one
+ * organization resolves a user to; domain/platformclient/mint.ts builds
+ * it). Reserved in both directions, because derived account ids make every
+ * subject one namespace: a direct account may not take a `stgm_pc|`
+ * subject (an issuer emitting one would otherwise provision an account the
+ * mint then resolves), and the mint refuses a `stgm_pc|` account in any
+ * other mode.
+ */
+export const PLATFORM_CLIENT_SUBJECT_PREFIX = "stgm_pc|";
+
+export function isPlatformClientSubject(idpId: string): boolean {
+  return idpId.startsWith(PLATFORM_CLIENT_SUBJECT_PREFIX);
+}
+
+export function reservedSubjectMessage(idpId: string): string {
+  return `subject '${idpId}' uses the '${PLATFORM_CLIENT_SUBJECT_PREFIX}' prefix reserved for accounts a platform client provisions`;
+}
+
 // ---------------------------------------------------------------------------
 // Byte-pinned copy (the cloud handlers' sentences, moved as-is).
 // ---------------------------------------------------------------------------