@stigmer/server 3.24.0 → 3.25.0

package/src/encryption/key-manager.ts

@@ -1,20 +1,26 @@
 /**
  * Named-key loader — ports pkg/encryption/keymanager.go.
  *
- * One convention for every 32-byte key the server holds (sub-project
- * DD-002): env var (Base64) → ~/.stigmer/<file> (raw bytes, 0600) →
- * auto-generate and persist. The loader is generalized over the env var
- * and file name so sibling key material (the runner-token signing key,
- * oss#535) rides the same ladder instead of growing a divergent loader.
+ * One convention for every key the server holds: env var (Base64) →
+ * ~/.stigmer/<file> (0600) → auto-generate and persist. The
+ * loader is generalized over the env var, the file name and a KeyCodec so
+ * sibling key material rides the same ladder instead of growing a
+ * divergent loader: the runner-token signing key (oss#535) and the
+ * encryption key are 32 raw bytes (RAW_32_BYTE_KEY); the platform-token
+ * signing key is an RSA private key (platformtoken/key-ring.ts). The codec
+ * says what a key IS — how an env value and a file decode, how one is
+ * generated and written — and nothing about the ladder, which stays one.
  *
- * Ladder semantics, exactly Go's:
+ * Ladder semantics, exactly Go's, for every codec:
  *   - An EXPLICITLY configured env key that is unusable (bad Base64, wrong
- *     length) is an ERROR, never a degrade — silently ignoring deliberate
- *     configuration would be worse than refusing to boot.
+ *     length, not the key type the codec holds) is an ERROR, never a
+ *     degrade — silently ignoring deliberate configuration would be worse
+ *     than refusing to boot.
  *   - A key file that fails its load checks (permissions other than 0600,
- *     wrong size) is never adopted; the ladder FALLS THROUGH to
- *     auto-generate, which overwrites the file's content — Go's shipped
- *     behavior (loadKeyFromFile error → generate → save), ported as-is.
+ *     content the codec does not accept) is never adopted; the ladder
+ *     FALLS THROUGH to auto-generate, which overwrites the file's content —
+ *     Go's shipped behavior (loadKeyFromFile error → generate → save),
+ *     ported as-is.
  *   - Auto-generation persists for future boots; a persist FAILURE is a
  *     stderr warning only — the key is still usable for this process.
  *
@@ -50,34 +56,81 @@ export interface KeyLoaderOptions {
 }
 
 /**
- * Go GetOrCreateNamedKey: env var → key file → auto-generate. Throws only
- * on unusable EXPLICIT configuration (bad env value) or when no key can be
- * produced at all.
+ * What one kind of key is, for the ladder. `fromEnv` receives the env
+ * value already strictly Base64-decoded and THROWS when the bytes are not
+ * a usable key (explicit configuration is never silently ignored);
+ * `fromFile` answers `undefined` for content it does not accept, so the
+ * ladder falls through exactly as it does for a wrong-sized raw key.
+ */
+export interface KeyCodec<Key> {
+  fromEnv(envVar: string, decoded: Buffer): Key;
+  fromFile(content: Buffer): Key | undefined;
+  generate(): Key;
+  toFile(key: Key): Buffer;
+}
+
+/** The 32 raw bytes the encryption and runner-token keys are. */
+export const RAW_32_BYTE_KEY: KeyCodec<Buffer> = {
+  fromEnv(envVar, decoded) {
+    if (decoded.length !== KEY_SIZE) {
+      throw new Error(
+        `${envVar} must be exactly 32 bytes (256 bits) when decoded, got ${decoded.length} bytes`,
+      );
+    }
+    return decoded;
+  },
+  fromFile(content) {
+    return content.length === KEY_SIZE ? content : undefined;
+  },
+  generate() {
+    return randomBytes(KEY_SIZE);
+  },
+  toFile(key) {
+    return key;
+  },
+};
+
+/**
+ * Go GetOrCreateNamedKey: env var → key file → auto-generate, for a 32-byte
+ * raw key. Throws only on unusable EXPLICIT configuration (bad env value)
+ * or when no key can be produced at all.
  */
 export function getOrCreateNamedKey(
   envVar: string,
   fileName: string,
   options: KeyLoaderOptions = {},
 ): Buffer {
+  return getOrCreateKey(RAW_32_BYTE_KEY, envVar, fileName, options);
+}
+
+/** The ladder over any codec: env var → key file → auto-generate. */
+export function getOrCreateKey<Key>(
+  codec: KeyCodec<Key>,
+  envVar: string,
+  fileName: string,
+  options: KeyLoaderOptions = {},
+): Key {
   const env = options.env ?? process.env;
 
-  // 1. Environment variable (highest priority) — Base64-encoded 32 bytes.
+  // 1. Environment variable (highest priority) — Base64-encoded.
   const envValue = env[envVar];
   if (envValue !== undefined && envValue !== "") {
-    return decodeEnvKey(envVar, envValue);
+    return codec.fromEnv(envVar, decodeEnvBase64(envVar, envValue));
   }
 
-  // 2. Local key file — raw 32 bytes, refused on insecure permissions.
+  // 2. Local key file — refused on insecure permissions or content the
+  //    codec does not accept.
   const keyPath = namedKeyFilePath(fileName, options);
-  const fromFile = loadKeyFromFile(keyPath);
+  const content = readKeyFile(keyPath);
+  const fromFile = content === undefined ? undefined : codec.fromFile(content);
   if (fromFile !== undefined) {
     return fromFile;
   }
 
   // 3. Auto-generate (local development); persist for future boots.
-  const key = randomBytes(KEY_SIZE);
+  const key = codec.generate();
   try {
-    saveKeyToFile(keyPath, key);
+    saveKeyToFile(keyPath, codec.toFile(key));
   } catch (error) {
     // Warn but don't fail — the key is still usable (Go's posture).
     process.stderr.write(
@@ -87,22 +140,17 @@ export function getOrCreateNamedKey(
   return key;
 }
 
-/** Strict Base64 decode + length check for an env-configured key. */
-function decodeEnvKey(envVar: string, value: string): Buffer {
-  const key = Buffer.from(value, "base64");
+/** Strict Base64 decode for an env-configured key. */
+function decodeEnvBase64(envVar: string, value: string): Buffer {
+  const decoded = Buffer.from(value, "base64");
   // Node's base64 decoder is lenient (skips invalid characters, accepts
   // missing padding) and never throws; Go's StdEncoding errors on any
   // non-canonical input. Round-tripping — Buffer always re-emits the
   // canonical padded form — restores Go's strictness.
-  if (key.toString("base64") !== value) {
+  if (decoded.toString("base64") !== value) {
     throw new Error(`invalid Base64 encoding in ${envVar}`);
   }
-  if (key.length !== KEY_SIZE) {
-    throw new Error(
-      `${envVar} must be exactly 32 bytes (256 bits) when decoded, got ${key.length} bytes`,
-    );
-  }
-  return key;
+  return decoded;
 }
 
 /** Path to a named key file under <home>/.stigmer. */
@@ -115,13 +163,13 @@ export function namedKeyFilePath(
 }
 
 /**
- * Reads raw key bytes, mirroring Go loadKeyFromFile: missing file →
- * undefined (fall through the ladder); present-but-wrong (insecure
- * permissions, wrong size) also falls through — exactly Go's behavior,
- * where any load error falls to auto-generate. The 0600 check is skipped
- * on Windows, where POSIX modes are not meaningful.
+ * Reads a key file's bytes, mirroring Go loadKeyFromFile: missing file →
+ * undefined (fall through the ladder); present with insecure permissions
+ * also falls through — exactly Go's behavior, where any load error falls
+ * to auto-generate. The 0600 check is skipped on Windows, where POSIX
+ * modes are not meaningful.
  */
-function loadKeyFromFile(keyPath: string): Buffer | undefined {
+function readKeyFile(keyPath: string): Buffer | undefined {
   let stat: fs.Stats;
   try {
     stat = fs.statSync(keyPath);
@@ -134,23 +182,18 @@ function loadKeyFromFile(keyPath: string): Buffer | undefined {
       return undefined;
     }
   }
-  let key: Buffer;
   try {
-    key = fs.readFileSync(keyPath);
+    return fs.readFileSync(keyPath);
   } catch {
     return undefined;
   }
-  if (key.length !== KEY_SIZE) {
-    return undefined;
-  }
-  return key;
 }
 
 /** Writes the key with secure permissions (dir 0700, file 0600). */
-function saveKeyToFile(keyPath: string, key: Buffer): void {
+function saveKeyToFile(keyPath: string, content: Buffer): void {
   fs.mkdirSync(path.dirname(keyPath), {
     recursive: true,
     mode: KEY_DIR_PERMISSIONS,
   });
-  fs.writeFileSync(keyPath, key, { mode: KEY_FILE_PERMISSIONS });
+  fs.writeFileSync(keyPath, content, { mode: KEY_FILE_PERMISSIONS });
 }

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

@@ -549,8 +549,9 @@ describe("extension composition (require-authentication posture)", () => {
     // composes its Authorizer, and with it the runner-subject verifier
     // between the API-key lane and the unit's own (runnerauth/
     // runner-subject-verifier.ts). A unit with its own Authorizer gets
-    // neither (runner-subject-composed.test.ts pins that chain).
-    expect(parsed.verifiers).toBe("apikey, runner, fake-verifier");
+    // neither (runner-subject-composed.test.ts pins that chain). The
+    // PlatformClient lane rides the posture itself, ahead of both.
+    expect(parsed.verifiers).toBe("apikey, platform-client, runner, fake-verifier");
   });
 
   it("a declared posture whose unit registers no verifier of its own is a boot throw naming the unit — the API-key lane alone cannot bootstrap", async () => {

package/src/extensions/__tests__/platform-client-composed.test.ts

@@ -0,0 +1,288 @@
+/**
+ * The PlatformClient lane on a composed server in the authentication
+ * posture with the built-in Authorizer (a unit that vouches for tokens,
+ * declares the posture and registers no Authorizer — the open-source OIDC
+ * self-host's shape), with the key ring supplied so the run is hermetic:
+ *   - the founder creates a client; an anonymous mint answers a token; the
+ *     token authenticates as the end user's derived account, which holds the
+ *     auto-grant role on the owning organization and sees that one alone;
+ *   - the platform-client verifier sits ahead of the unit's verifier and
+ *     claims only its lane: the founder's tokens still pass, and a TYPED
+ *     platform token (a lane open source does not speak) is refused as
+ *     unclaimed;
+ *   - the origin guard refuses an unlisted Origin with the cloud's copy and
+ *     passes a request without one;
+ *   - deleting the client refuses its token on the next request with the
+ *     cloud's liveness copy;
+ *   - an outsider cannot read the client by reference.
+ */
+import { generateKeyPairSync } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import type { Interceptor, Transport } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IdentityAccountCommandController } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/command_pb";
+import { IdentityAccountQueryController } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/query_pb";
+import { PlatformClientCommandController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/command_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 { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+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 { loadConfig } from "../../boot/config.js";
+import { composeServer } from "../../boot/compose.js";
+import type { ComposedServer } from "../../boot/compose.js";
+import { accountIdFor } from "../../domain/identityaccount/constants.js";
+import {
+  DELETED_CLIENT_MESSAGE,
+  originRefusalMessage,
+} from "../../domain/platformclient/constants.js";
+import { signPlatformToken } from "../../platformtoken/envelope.js";
+import { platformTokenKeyRingFromPem } from "../../platformtoken/key-ring.js";
+import type { SigningPlatformTokenKeyRing } from "../../platformtoken/key-ring.js";
+import type { ServerExtension } from "../registry.js";
+import {
+  baseConfig,
+  bearer,
+  fakeJwt,
+  fakeVerifier,
+  silentLogger,
+  transportFor,
+} from "./composed-support.js";
+
+const FOUNDER = "fake|pc-founder";
+const OUTSIDER = "fake|pc-outsider";
+const ORG = "pc-org";
+
+const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+});
+const built = platformTokenKeyRingFromPem({
+  privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+  publicKeyPems: [publicKey.export({ format: "pem", type: "spki" }).toString()],
+});
+if (built.signer === undefined) throw new Error("fixture ring must sign");
+const RING: SigningPlatformTokenKeyRing = { ...built, signer: built.signer };
+
+/** Stamps the lowercase `origin` header a browser attaches to a cross-origin call. */
+function browserOrigin(origin: string): Interceptor {
+  return (next) => (request) => {
+    request.header.set("origin", origin);
+    return next(request);
+  };
+}
+
+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("PlatformClient on a composed server (authentication posture, built-in Authorizer)", () => {
+  let dir: string;
+  let server: ComposedServer;
+  let port: number;
+
+  const asFounder = (): Transport =>
+    transportFor(port, fakeJwt(FOUNDER, "founder@example.com"));
+  const asOutsider = (): Transport =>
+    transportFor(port, fakeJwt(OUTSIDER, "outsider@example.com"));
+  const presenting = (token: string, origin?: string): Transport =>
+    createGrpcTransport({
+      baseUrl: `http://127.0.0.1:${port}`,
+      interceptors: [
+        bearer(token),
+        ...(origin !== undefined ? [browserOrigin(origin)] : []),
+      ],
+    });
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "platform-client-composed-"));
+    const unit: ServerExtension = {
+      name: "fake-oidc-only",
+      requireAuthentication: true,
+      identityVerifiers: [fakeVerifier],
+      drivers: { platformTokenKeys: RING },
+    };
+    server = await composeServer({
+      config: loadConfig(baseConfig(dir)),
+      logger: silentLogger,
+      extensions: [unit],
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    port = await server.start();
+
+    await createClient(
+      IdentityAccountCommandController,
+      asFounder(),
+    ).provisionMyAccount({});
+    await createClient(OrganizationCommandController, asFounder()).create({
+      apiVersion: "tenancy.stigmer.ai/v1",
+      kind: "Organization",
+      metadata: { name: ORG, slug: ORG, org: "" },
+      spec: { description: ORG },
+    });
+    await createClient(
+      IdentityAccountCommandController,
+      asOutsider(),
+    ).provisionMyAccount({});
+  });
+
+  afterAll(async () => {
+    await server?.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  async function createPlatformClient(allowedOrigins: string[] = []) {
+    const created = await createClient(
+      PlatformClientCommandController,
+      asFounder(),
+    ).create({
+      apiVersion: "iam.stigmer.ai/v1",
+      kind: "PlatformClient",
+      metadata: {
+        name: `client-${Math.random().toString(36).slice(2, 8)}`,
+        org: ORG,
+      },
+      spec: {
+        autoProvisionAccounts: true,
+        autoGrantOnOrg: true,
+        autoGrantRole: IamRole.member,
+        allowedOrigins,
+      },
+    });
+    return {
+      id: created.platformClient?.metadata?.id ?? "",
+      slug: created.platformClient?.metadata?.slug ?? "",
+      clientId: created.platformClient?.spec?.clientId ?? "",
+      clientSecret: created.clientSecret,
+    };
+  }
+
+  async function mint(
+    client: { clientId: string; clientSecret: string },
+    userId: string,
+  ) {
+    const minted = await createClient(
+      PlatformClientTokenController,
+      transportFor(port),
+    ).mintUserToken({
+      clientId: client.clientId,
+      clientSecret: client.clientSecret,
+      userId,
+      userEmail: `${userId}@product.example`,
+      userName: "Product User",
+    });
+    return minted.accessToken;
+  }
+
+  it("mints for the end user's derived account, which sees its owning organization alone", async () => {
+    const client = await createPlatformClient();
+    const token = await mint(client, "user-1");
+
+    const me = await createClient(
+      IdentityAccountQueryController,
+      presenting(token),
+    ).whoAmI({});
+    expect(me.metadata?.id).toBe(accountIdFor(`stgm_pc|${ORG}|user-1`));
+
+    const mine = await createClient(
+      OrganizationQueryController,
+      presenting(token),
+    ).findMyOrganizations({});
+    expect(
+      mine.entries.map((organization) => organization.metadata?.slug),
+    ).toEqual([ORG]);
+  });
+
+  it("claims only its lane: the unit's tokens still pass, and a typed platform token is refused as unclaimed", async () => {
+    await createClient(
+      OrganizationQueryController,
+      asFounder(),
+    ).findMyOrganizations({});
+
+    const guest = signPlatformToken(RING, {
+      sub: "ida_guest",
+      token_type: "guest",
+    }).token;
+    const refused = await refusal(
+      createClient(
+        OrganizationQueryController,
+        presenting(guest),
+      ).findMyOrganizations({}),
+    );
+    expect(refused.code).toBe(Code.Unauthenticated);
+  });
+
+  it("refuses an unlisted Origin with the cloud's copy and passes a request without one", async () => {
+    const client = await createPlatformClient(["https://app.example"]);
+    const token = await mint(client, "user-2");
+
+    const denied = await refusal(
+      createClient(
+        OrganizationQueryController,
+        presenting(token, "https://evil.example"),
+      ).findMyOrganizations({}),
+    );
+    expect(denied.code).toBe(Code.PermissionDenied);
+    expect(denied.rawMessage).toBe(
+      originRefusalMessage("https://evil.example"),
+    );
+
+    await createClient(
+      OrganizationQueryController,
+      presenting(token),
+    ).findMyOrganizations({});
+    await createClient(
+      OrganizationQueryController,
+      presenting(token, "https://app.example"),
+    ).findMyOrganizations({});
+  });
+
+  it("refuses a deleted client's token on the next request with the liveness copy", async () => {
+    const client = await createPlatformClient();
+    const token = await mint(client, "user-3");
+    await createClient(
+      OrganizationQueryController,
+      presenting(token),
+    ).findMyOrganizations({});
+
+    await createClient(PlatformClientCommandController, asFounder()).delete({
+      resourceId: client.id,
+    });
+
+    const denied = await refusal(
+      createClient(
+        OrganizationQueryController,
+        presenting(token),
+      ).findMyOrganizations({}),
+    );
+    expect(denied.code).toBe(Code.Unauthenticated);
+    expect(denied.rawMessage).toBe(DELETED_CLIENT_MESSAGE);
+  });
+
+  it("an outsider cannot read the client by reference", async () => {
+    const client = await createPlatformClient();
+    const denied = await refusal(
+      createClient(PlatformClientQueryController, asOutsider()).getByReference({
+        org: ORG,
+        slug: client.slug,
+        kind: ApiResourceKind.platform_client,
+      }),
+    );
+    expect(denied.code).toBe(Code.PermissionDenied);
+    expect(denied.rawMessage).toBe("unauthorized to view platform client");
+  });
+});

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

@@ -193,7 +193,10 @@ describe("resolveExtensions — merge semantics", () => {
       "g2",
       "g3",
     ]);
-    expect(resolved.services).toEqual([registerA, registerB]);
+    expect(resolved.services).toEqual([
+      { unit: "alpha", register: registerA },
+      { unit: "beta", register: registerB },
+    ]);
     expect(resolved.workers).toEqual([workerFactory]);
     expect(resolved.statusObservers).toEqual([observerA]);
     expect(resolved.responseDecorators).toEqual([decoratorB]);

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

@@ -218,6 +218,14 @@ describe("tier truthfulness against the empty composition", () => {
     );
     expect(served.has("iampolicy")).toBe(true);
   });
+
+  it("platform_client is open_source and served in the empty composition — the mint refuses without a posture, the kind does not", () => {
+    const served = servedKindSegments(server.routes);
+    expect(getKindMeta(ApiResourceKind.platform_client).tier).toBe(
+      ResourceTier.open_source,
+    );
+    expect(served.has("platformclient")).toBe(true);
+  });
 });
 
 describe("the check bites (mutation proofs over the same function)", () => {

package/src/extensions/caller-guards.ts

@@ -10,9 +10,14 @@
  * allowed_origins, oss#375). Java separates the two classes the same way.
  *
  * List point — guards concatenate in unit order and run in composed
- * order; the first throw wins. OSS composes zero guards, so with none
- * registered the serving chain behaves byte-identically to before the
- * point existed (the conformance rosters pin that).
+ * order; the first throw wins. Open source's own guards run first (the
+ * verifier list's "OSS entries first" rule): today the PlatformClient
+ * origin guard (domain/platformclient/origin-guard.ts), composed only
+ * under an authentication posture, where PlatformClient tokens exist.
+ * Liveness is not a guard in open source: the PlatformClient verifier
+ * refuses a deleted client's tokens itself, so verifier-only lanes (the
+ * extension HTTP edges) refuse them too. With no posture and no unit
+ * guards, the serving chain runs no guard at all.
  *
  * The in-process exemption is STRUCTURAL, not policed: guards are a
  * parameter of the serving chain's identity source only

package/src/extensions/drivers.ts

@@ -35,6 +35,11 @@
  *     it reaches a URL a user supplied: the MCP endpoint it probes at save
  *     time and the login server it reaches on Sign in) — landed with the
  *     save-time OAuth completion for URL-only MCP servers, 2026-09-19
+ *   - platform-client store + platform-token keys + guest-token minting
+ *     (PlatformClient served in every edition: the port the cloud's
+ *     `cloud.iam_platform_client` driver fills, the RS256 key ring every
+ *     self-signed token rides, and the one token method only an edition
+ *     that hosts shared-agent pages serves) — landed 2026-09-23
  *
  * Merge rules (enforced by resolveExtensions, DD-006 §2b): the two
  * provider kinds are single-instance points — a second declaring unit is
@@ -50,12 +55,15 @@ import type { ArtifactStorageDriverFactory } from "../artifactstorage/artifact-s
 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 { PlatformClientStore } from "../domain/platformclient/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 { PlatformTokenKeyRing } from "../platformtoken/key-ring.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 { GuestTokenMinting } from "./guest-token-minting.js";
 import type { IdentityFederation } from "./identity-federation.js";
 import type { LicenseStatusProvider } from "./license-status.js";
 import type { OutboundEgressPolicy } from "./outbound-egress.js";
@@ -247,4 +255,33 @@ export interface ExtensionDrivers {
    * (extensions/outbound-egress.ts carries the contract).
    */
   readonly outboundEgress?: OutboundEgressPolicy;
+  /**
+   * The platform-client store driver (single-instance point). The
+   * platform-client domain's persistence is a PORT like the
+   * identity-account domain's: when composed, every chain, the mint and
+   * the verifier's liveness read go through this driver (the cloud serves
+   * the domain over its own `cloud.iam_platform_client` table this way,
+   * legacy `pc_` ids included). When absent, the OSS adapter over the
+   * generic Store installs at the compose.ts consumption site.
+   */
+  readonly platformClientStore?: PlatformClientStore;
+  /**
+   * The platform-token key ring (single-instance point): the RS256 keys
+   * every token the server signs for itself rides
+   * (platformtoken/key-ring.ts). Consumed only under an authentication
+   * posture — nothing verifies a token on a server that trusts every
+   * request. When absent there, open source composes its own ring on the
+   * key-manager ladder; a composition declaring an edition other than
+   * open source must supply one (compose.ts refuses to boot without it,
+   * so a hosted edition never signs with a generated key).
+   */
+  readonly platformTokenKeys?: PlatformTokenKeyRing;
+  /**
+   * The guest-token capability (single-instance point): the one
+   * PlatformClientTokenController method only an edition hosting
+   * shared-agent pages serves. When absent, `mintGuestToken` refuses
+   * UNIMPLEMENTED with the edition sentence
+   * (extensions/guest-token-minting.ts carries the contract).
+   */
+  readonly guestTokenMinting?: GuestTokenMinting;
 }

package/src/extensions/guest-token-minting.ts

@@ -0,0 +1,32 @@
+/**
+ * The guest-token capability: `PlatformClientTokenController.mintGuestToken`,
+ * the credential-free mint for anonymous visitors of a shared agent's
+ * hosted page. Single instance, registered as `drivers.guestTokenMinting`
+ * (the identityFederation shape: a driver point whose absence is a
+ * refusal, never a silent no-op).
+ *
+ * Why a capability and not a second service: open source registers the
+ * whole PlatformClientTokenController, because `mintUserToken` is core,
+ * and the composition refuses an extension that registers a service the
+ * core already routes. Guest sharing — the hosted page, its rate limits,
+ * the share resolution, the org's system-managed client and guest
+ * account — is an edition's, so the one method that needs it is
+ * dispatched here.
+ *
+ * Absent, the controller answers UNIMPLEMENTED with the edition sentence
+ * (domain/platformclient/constants.ts). Present, the capability owns the
+ * whole arm: the request has passed the protovalidate interceptor, and
+ * `headers` carries the request's `origin` for the embed checks. It signs
+ * with the ring its own composition supplied (`signPlatformToken`).
+ */
+import type {
+  MintGuestTokenRequest,
+  MintGuestTokenResponse,
+} from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+
+export interface GuestTokenMinting {
+  mintGuestToken(
+    request: MintGuestTokenRequest,
+    headers: Headers,
+  ): Promise<MintGuestTokenResponse>;
+}

package/src/extensions/identity.ts

@@ -23,10 +23,12 @@
  * known classes from the type surface).
  *
  * `internal` is ratified contract with a structural guarantee: it is
- * minted ONLY by the in-process chain's identity interceptor
- * (boot/inprocess.ts). No IdentityVerifier may produce it — the serving
- * chain always overwrites the position-1 identity from the wire, so a
- * spoofed internal class cannot enter through a transport.
+ * minted ONLY by server code, in pipeline/interceptors/auth.ts — the
+ * in-process chain's identity interceptor (boot/inprocess.ts) and
+ * `serverActingFor`, the server acting for a principal it authenticated
+ * itself (the PlatformClient mint). No IdentityVerifier may produce it —
+ * the serving chain always overwrites the position-1 identity from the
+ * wire, so a spoofed internal class cannot enter through a transport.
  */
 export type CallerClass =
   | "user"