@stigmer/server 3.24.0 → 3.25.0

package/src/extensions/registry.ts

@@ -49,9 +49,12 @@ import { BUILT_IN_STORAGE_TYPES } 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 { PlatformClientStore } from "../domain/platformclient/store.js";
 import type { SecretCodec } from "../encryption/codec.js";
 import { V1_VERSION } from "../encryption/v1-codec.js";
+import type { PlatformTokenKeyRing } from "../platformtoken/key-ring.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";
@@ -88,6 +91,17 @@ import type {
  */
 export type ExtensionServiceRegistration = (router: ConnectRouter) => void;
 
+/**
+ * A service registration with the unit that contributed it, so the routes
+ * stage can name the unit when a registration shadows a core route
+ * (compose.ts refuses that at boot: Connect's router keys handlers by
+ * request path and the last registration wins, silently).
+ */
+export interface ResolvedServiceRegistration {
+  readonly unit: string;
+  readonly register: ExtensionServiceRegistration;
+}
+
 /**
  * One named extension unit — a package's whole contribution to the server
  * composition. All fields but `name` are optional; an omitted field is
@@ -191,7 +205,7 @@ export interface ResolvedExtensions {
   readonly statusObservers: ReadonlyArray<AgentExecutionStatusObserver>;
   readonly responseDecorators: ReadonlyArray<AgentExecutionResponseDecorator>;
   readonly drivers: ResolvedExtensionDrivers;
-  readonly services: ReadonlyArray<ExtensionServiceRegistration>;
+  readonly services: ReadonlyArray<ResolvedServiceRegistration>;
   readonly workers: ReadonlyArray<WorkerFactory>;
 }
 
@@ -284,6 +298,22 @@ export interface ResolvedExtensionDrivers {
    * source's relaxed posture (only the link-local range refused).
    */
   readonly outboundEgress: OutboundEgressPolicy | undefined;
+  /**
+   * The platform-client store driver — undefined = compose.ts installs the
+   * OSS adapter over the generic Store.
+   */
+  readonly platformClientStore: PlatformClientStore | undefined;
+  /**
+   * The platform-token key ring — undefined = compose.ts composes open
+   * source's ring under an authentication posture, and refuses to boot a
+   * non-open-source edition that supplied none.
+   */
+  readonly platformTokenKeys: PlatformTokenKeyRing | undefined;
+  /**
+   * The guest-token capability — undefined = `mintGuestToken` refuses
+   * UNIMPLEMENTED with the edition sentence.
+   */
+  readonly guestTokenMinting: GuestTokenMinting | undefined;
 }
 
 /**
@@ -301,7 +331,7 @@ export function resolveExtensions(
   const gateSteps = new Map<string, ReadonlyArray<PipelineStep<DescMessage>>>();
   const statusObservers: AgentExecutionStatusObserver[] = [];
   const responseDecorators: AgentExecutionResponseDecorator[] = [];
-  const services: ExtensionServiceRegistration[] = [];
+  const services: ResolvedServiceRegistration[] = [];
   const workers: WorkerFactory[] = [];
 
   let edition: ServerEdition | undefined;
@@ -341,6 +371,12 @@ export function resolveExtensions(
   let licenseStatusDeclaredBy: string | undefined;
   let outboundEgress: OutboundEgressPolicy | undefined;
   let outboundEgressDeclaredBy: string | undefined;
+  let platformClientStore: PlatformClientStore | undefined;
+  let platformClientStoreDeclaredBy: string | undefined;
+  let platformTokenKeys: PlatformTokenKeyRing | undefined;
+  let platformTokenKeysDeclaredBy: string | undefined;
+  let guestTokenMinting: GuestTokenMinting | undefined;
+  let guestTokenMintingDeclaredBy: string | undefined;
   const artifactStorageDrivers = new Map<
     string,
     ArtifactStorageDriverFactory
@@ -552,6 +588,36 @@ export function resolveExtensions(
       outboundEgressDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.platformClientStore !== undefined) {
+      if (platformClientStoreDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a PlatformClientStore, but '${platformClientStoreDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      platformClientStore = unit.drivers.platformClientStore;
+      platformClientStoreDeclaredBy = unit.name;
+    }
+
+    if (unit.drivers?.platformTokenKeys !== undefined) {
+      if (platformTokenKeysDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a PlatformTokenKeyRing, but '${platformTokenKeysDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      platformTokenKeys = unit.drivers.platformTokenKeys;
+      platformTokenKeysDeclaredBy = unit.name;
+    }
+
+    if (unit.drivers?.guestTokenMinting !== undefined) {
+      if (guestTokenMintingDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a GuestTokenMinting capability, but '${guestTokenMintingDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      guestTokenMinting = unit.drivers.guestTokenMinting;
+      guestTokenMintingDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.artifactStorageDrivers !== undefined) {
       for (const [name, factory] of unit.drivers.artifactStorageDrivers) {
         if ((BUILT_IN_STORAGE_TYPES as ReadonlyArray<string>).includes(name)) {
@@ -643,7 +709,12 @@ export function resolveExtensions(
     responseDecorators.push(
       ...(unit.statusTransitionHooks?.responseDecorators ?? []),
     );
-    services.push(...(unit.services ?? []));
+    services.push(
+      ...(unit.services ?? []).map((register) => ({
+        unit: unit.name,
+        register,
+      })),
+    );
     workers.push(...(unit.workers ?? []));
   }
 
@@ -679,6 +750,9 @@ export function resolveExtensions(
       authorizationQueries,
       licenseStatus,
       outboundEgress,
+      platformClientStore,
+      platformTokenKeys,
+      guestTokenMinting,
     },
     services,
     workers,

package/src/index.ts

@@ -59,6 +59,7 @@ export type {
 export type {
   ExtensionServiceRegistration,
   ResolvedExtensions,
+  ResolvedServiceRegistration,
   ServerExtension,
 } from "./extensions/registry.js";
 export type {
@@ -166,6 +167,60 @@ export type { AuthorizationQueryEngine } from "./extensions/authorization-querie
 export type { IdentityFederation } from "./extensions/identity-federation.js";
 export type { AccountsBySubject } from "./domain/identityaccount/resolve.js";
 export { identityIdForSubject } from "./domain/identityaccount/resolve.js";
+// The PlatformClient seams: the store PORT a composition drives the domain
+// through (drivers.platformClientStore; a driver throws
+// DuplicatePlatformClientError for a held id, slug or client_id) and its
+// vitest-free contract kit; the guest-token capability
+// (drivers.guestTokenMinting — the one token method only an edition that
+// hosts shared-agent pages serves); and the builder of the system-managed
+// client such an edition keeps per organization under the reserved slug,
+// so the tokens it signs for guests and schedule fires name a real client.
+export type { PlatformClientStore } from "./domain/platformclient/store.js";
+export { DuplicatePlatformClientError } from "./domain/platformclient/store.js";
+export type {
+  PlatformClientStoreContractCase,
+  PlatformClientStoreContractFixture,
+} from "./domain/platformclient/store-contract.js";
+export { platformClientStoreContract } from "./domain/platformclient/store-contract.js";
+export type { GuestTokenMinting } from "./extensions/guest-token-minting.js";
+export type { SystemManagedPlatformClientInput } from "./domain/platformclient/system-managed.js";
+export { newSystemManagedPlatformClient } from "./domain/platformclient/system-managed.js";
+export { SYSTEM_SHARE_CLIENT_SLUG } from "./domain/platformclient/constants.js";
+// The platform-token envelope and its key ring: the RS256 JWT every token
+// the server signs for itself rides. A composition supplies its ring
+// (drivers.platformTokenKeys, built from its PEMs), signs its own typed
+// lanes through the envelope — each with its own lifetime when it is not
+// the ring's default, the expiry handed back — and verifies them with the
+// same function and refusal copy open source's user-token lane uses.
+export type {
+  PlatformTokenClaimValue,
+  PlatformTokenRefusal,
+  PlatformTokenSigningOptions,
+  PlatformTokenVerification,
+  SignedPlatformToken,
+  VerifiedPlatformToken,
+} from "./platformtoken/envelope.js";
+export {
+  PLATFORM_TOKEN_ISSUER,
+  PLATFORM_TOKEN_REFUSAL_MESSAGES,
+  TOKEN_TYPE_CLAIM,
+  decodeVerifiedPlatformTokenPayload,
+  platformTokenRefusalError,
+  signPlatformToken,
+  stringClaim,
+  verifyPlatformToken,
+} from "./platformtoken/envelope.js";
+export type {
+  PlatformTokenKeyMaterial,
+  PlatformTokenKeyRing,
+  PlatformTokenSigner,
+  SigningPlatformTokenKeyRing,
+} from "./platformtoken/key-ring.js";
+export {
+  DEFAULT_PLATFORM_TOKEN_TTL_SECONDS,
+  canSign,
+  platformTokenKeyRingFromPem,
+} from "./platformtoken/key-ring.js";
 // The built-in authorizer's model seams: the kind
 // declarations (transcripts of the cloud's `.fga` files), the evaluator,
 // and the OpenFGA store-test kit — exported so the cloud's drift test

package/src/pipeline/interceptors/auth.ts

@@ -216,6 +216,33 @@ export function trustedLocalIdentityFor(operator: {
   };
 }
 
+/**
+ * The server acting for a principal it has authenticated some other way —
+ * the one construction of an `internal` caller outside the in-process
+ * transport's own stamp. Its consumer is the PlatformClient mint
+ * (domain/platformclient/mint.ts): the request is public and tokenless
+ * (so the chain stamped the trusted-local operator), the client proved
+ * itself with its secret, and the end-user account and role the mint
+ * creates must name the CLIENT as their actor, never the operator.
+ * `internal` because the server is the one acting — the create path's
+ * Authorize skips it, as for every server-composed request — and never
+ * reachable from the wire: no verifier produces it, and the serving
+ * chassis overwrites position 1 on every request.
+ */
+export function serverActingFor(principalId: string): CallerIdentity {
+  if (principalId === "") {
+    throw new Error(
+      "the server acts for a named principal — refusing to build an internal caller with none",
+    );
+  }
+  return {
+    identityId: principalId,
+    callerClass: "internal",
+    issuer: "",
+    rawToken: "",
+  };
+}
+
 /**
  * The serving chain's position-1 identity source: walks the composed
  * verifiers in order (OSS entries first, extension entries after, in

package/src/pipeline/steps/__tests__/references.test.ts

@@ -39,6 +39,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { reference_kind } from "@stigmer/protos/ai/stigmer/commons/apiresource/field_options_pb";
 import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
 
 import type { Store } from "../../../store/interface.js";
 import { SqliteStore } from "../../../store/sqlite/store.js";
@@ -97,6 +98,7 @@ const SCHEMAS_UNDER_THE_RULE: ReadonlyArray<DescMessage> = [
   AgentExecutionSchema,
   WorkflowExecutionSchema,
   ExecutionContextSchema,
+  PlatformClientSchema,
   AgentCallTaskConfigSchema,
 ];
 

package/src/pipeline/steps/build-update-state.ts

@@ -115,9 +115,12 @@ function copyStatusFromExisting(
 /**
  * Go updateAuditFieldsReflect: spec_audit keeps the existing creation
  * identity with a fresh update stamp; status_audit is fully current (the
- * status was rebuilt); both carry event "updated".
+ * status was rebuilt); both carry event "updated". Exported for the one
+ * write that changes a stored resource outside this step — a
+ * PlatformClient secret rotation (domain/platformclient/steps.ts) — so an
+ * update's audit has one shape whichever step writes it.
  */
-function updateAuditFields(
+export function updateAuditFields(
   schema: DescMessage,
   resource: Message,
   existing: Message,

package/src/platformtoken/__tests__/envelope.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Pins the platform-token envelope against the cloud verifier's semantics,
+ * which every token in the field was accepted under:
+ *   - a signed token round-trips with the envelope's claims and the lane's;
+ *   - a lane's own lifetime replaces the ring's default, and the expiry the
+ *     signer returns is the instant the `exp` claim names;
+ *   - a token signed by the previous key still verifies (the rotation
+ *     window), and the header's kid never selects a key;
+ *   - the forgeries a JWT verifier must refuse are refused as a bad
+ *     signature: `alg: none`, and an HMAC token keyed with the public key;
+ *   - expiry is strict (no leeway), a missing `aud` is tolerated, a wrong
+ *     one refused, and a missing `sub` refused — each with its pinned copy;
+ *   - anything that is not a three-part `iss: "stigmer"` JWT is foreign,
+ *     never refused, so the next verifier judges it;
+ *   - a lane cannot set a claim the envelope owns.
+ */
+import { createHmac, generateKeyPairSync } from "node:crypto";
+
+import { Code } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import {
+  PLATFORM_TOKEN_REFUSAL_MESSAGES,
+  decodeVerifiedPlatformTokenPayload,
+  platformTokenRefusalError,
+  signPlatformToken,
+  verifyPlatformToken,
+} from "../envelope.js";
+import { platformTokenKeyRingFromPem } from "../key-ring.js";
+import type { SigningPlatformTokenKeyRing } from "../key-ring.js";
+
+function pemPair(): { privateKeyPem: string; publicKeyPem: string } {
+  const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+  });
+  return {
+    privateKeyPem: privateKey
+      .export({ format: "pem", type: "pkcs8" })
+      .toString(),
+    publicKeyPem: publicKey.export({ format: "pem", type: "spki" }).toString(),
+  };
+}
+
+const active = pemPair();
+const previous = pemPair();
+
+function signingRing(
+  options: {
+    pair?: { privateKeyPem: string; publicKeyPem: string };
+    audience?: string;
+    ttlSeconds?: number;
+  } = {},
+): SigningPlatformTokenKeyRing {
+  const pair = options.pair ?? active;
+  const ring = platformTokenKeyRingFromPem({
+    privateKeyPem: pair.privateKeyPem,
+    kid: "stigmer-signing-key-1",
+    publicKeyPems: [pair.publicKeyPem],
+    audience: options.audience ?? "",
+    ttlSeconds: options.ttlSeconds ?? 900,
+  });
+  if (ring.signer === undefined) throw new Error("fixture ring must sign");
+  return { ...ring, signer: ring.signer };
+}
+
+const NOW = new Date("2026-09-23T10:00:00Z");
+
+function base64UrlJson(value: object): string {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+
+describe("the platform-token envelope", () => {
+  it("round-trips a signed token: the envelope's claims, then the lane's", () => {
+    const ring = signingRing({ audience: "https://api.stigmer.ai" });
+    const token = signPlatformToken(
+      ring,
+      { sub: "ida_1", platform_client_id: "pcl_1" },
+      { now: NOW },
+    ).token;
+
+    const result = verifyPlatformToken(ring, token, NOW);
+    expect(result.outcome).toBe("verified");
+    if (result.outcome !== "verified") return;
+    expect(result.token.subject).toBe("ida_1");
+    expect(result.token.tokenType).toBeUndefined();
+    expect(result.token.payload).toMatchObject({
+      iss: "stigmer",
+      iat: NOW.getTime() / 1000,
+      exp: NOW.getTime() / 1000 + 900,
+      aud: "https://api.stigmer.ai",
+      platform_client_id: "pcl_1",
+    });
+    const header = JSON.parse(
+      Buffer.from(token.split(".")[0] ?? "", "base64url").toString(),
+    );
+    expect(header).toEqual({
+      alg: "RS256",
+      typ: "JWT",
+      kid: "stigmer-signing-key-1",
+    });
+  });
+
+  it("signs with the lane's own lifetime when it names one, and returns the expiry the token carries", () => {
+    const ring = signingRing({ ttlSeconds: 900 });
+
+    const byDefault = signPlatformToken(ring, { sub: "ida_1" }, { now: NOW });
+    expect(byDefault.expiresAt).toEqual(new Date(NOW.getTime() + 900_000));
+
+    const sandbox = signPlatformToken(
+      ring,
+      { sub: "ida_1", token_type: "sandbox" },
+      { now: NOW, ttlSeconds: 14_400 },
+    );
+    expect(sandbox.expiresAt).toEqual(new Date(NOW.getTime() + 14_400_000));
+    const verified = verifyPlatformToken(ring, sandbox.token, NOW);
+    expect(verified.outcome === "verified" && verified.token.payload.exp).toBe(
+      sandbox.expiresAt.getTime() / 1000,
+    );
+    expect(
+      verifyPlatformToken(
+        ring,
+        sandbox.token,
+        new Date(NOW.getTime() + 900_000),
+      ).outcome,
+    ).toBe("verified");
+  });
+
+  it("refuses a lifetime that is not a positive whole number of seconds", () => {
+    for (const ttlSeconds of [0, -1, 1.5, Number.NaN]) {
+      expect(() =>
+        signPlatformToken(signingRing(), { sub: "ida_1" }, { ttlSeconds }),
+      ).toThrow(/positive integer number of seconds/);
+    }
+  });
+
+  it("reads token_type as the lane discriminator", () => {
+    const ring = signingRing();
+    const token = signPlatformToken(
+      ring,
+      { sub: "ida_guest", token_type: "guest" },
+      { now: NOW },
+    ).token;
+    const result = verifyPlatformToken(ring, token, NOW);
+    expect(result.outcome === "verified" && result.token.tokenType).toBe(
+      "guest",
+    );
+  });
+
+  it("verifies a token signed by the previous key while it is still accepted, whatever the kid says", () => {
+    const old = signPlatformToken(
+      signingRing({ pair: previous }),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    const ring = platformTokenKeyRingFromPem({
+      privateKeyPem: active.privateKeyPem,
+      kid: "stigmer-signing-key-1",
+      publicKeyPems: [active.publicKeyPem, previous.publicKeyPem],
+    });
+    expect(verifyPlatformToken(ring, old, NOW).outcome).toBe("verified");
+  });
+
+  it("refuses `alg: none` and an HMAC token keyed with the public key as a bad signature", () => {
+    const ring = signingRing();
+    const payload = base64UrlJson({
+      iss: "stigmer",
+      sub: "ida_1",
+      exp: NOW.getTime() / 1000 + 60,
+    });
+
+    const unsigned = `${base64UrlJson({ alg: "none", typ: "JWT" })}.${payload}.`;
+    expect(verifyPlatformToken(ring, unsigned, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "signature",
+    });
+
+    const hmacHeader = base64UrlJson({ alg: "HS256", typ: "JWT" });
+    const forged = createHmac("sha256", active.publicKeyPem)
+      .update(`${hmacHeader}.${payload}`)
+      .digest("base64url");
+    expect(
+      verifyPlatformToken(ring, `${hmacHeader}.${payload}.${forged}`, NOW),
+    ).toEqual({
+      outcome: "refused",
+      refusal: "signature",
+    });
+  });
+
+  it("refuses a token signed by a key the ring does not hold", () => {
+    const stranger = signPlatformToken(
+      signingRing({ pair: pemPair() }),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    expect(verifyPlatformToken(signingRing(), stranger, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "signature",
+    });
+  });
+
+  it("refuses an expired token strictly, with no leeway", () => {
+    const ring = signingRing({ ttlSeconds: 60 });
+    const token = signPlatformToken(ring, { sub: "ida_1" }, { now: NOW }).token;
+    const atExpiry = new Date(NOW.getTime() + 60_000);
+    expect(verifyPlatformToken(ring, token, atExpiry)).toEqual({
+      outcome: "refused",
+      refusal: "expired",
+    });
+  });
+
+  it("tolerates a missing aud and refuses one that names another audience", () => {
+    const noAudience = signPlatformToken(
+      signingRing(),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    const expecting = signingRing({ audience: "https://api.stigmer.ai" });
+    expect(verifyPlatformToken(expecting, noAudience, NOW).outcome).toBe(
+      "verified",
+    );
+
+    const elsewhere = signPlatformToken(
+      signingRing({ audience: "https://staging.stigmer.ai" }),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    expect(verifyPlatformToken(expecting, elsewhere, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "audience",
+    });
+  });
+
+  it("refuses a token with no subject", () => {
+    const ring = signingRing();
+    const token = signPlatformToken(
+      ring,
+      { platform_client_id: "pcl_1" },
+      { now: NOW },
+    ).token;
+    expect(verifyPlatformToken(ring, token, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "subject",
+    });
+  });
+
+  it("answers foreign for anything that is not a stigmer-issued three-part JWT", () => {
+    const ring = signingRing();
+    expect(verifyPlatformToken(ring, "stk_an_api_key", NOW).outcome).toBe(
+      "foreign",
+    );
+    expect(verifyPlatformToken(ring, "a.b", NOW).outcome).toBe("foreign");
+    const otherIssuer = `${base64UrlJson({ alg: "RS256" })}.${base64UrlJson({ iss: "https://issuer.example", sub: "x" })}.sig`;
+    expect(verifyPlatformToken(ring, otherIssuer, NOW).outcome).toBe("foreign");
+    expect(decodeVerifiedPlatformTokenPayload(otherIssuer)).toBeUndefined();
+    expect(decodeVerifiedPlatformTokenPayload("")).toBeUndefined();
+  });
+
+  it("refuses a lane claim that collides with an envelope claim", () => {
+    expect(
+      () =>
+        signPlatformToken(signingRing(), { sub: "ida_1", exp: 1 }, { now: NOW })
+          .token,
+    ).toThrow(/belongs to the envelope/);
+  });
+
+  it("maps every refusal to UNAUTHENTICATED with the cloud verifier's copy", () => {
+    expect(PLATFORM_TOKEN_REFUSAL_MESSAGES).toEqual({
+      signature: "platform token signature verification failed",
+      expired: "platform token is expired",
+      audience: "platform token was minted for another environment",
+      subject: "platform token carries no subject",
+    });
+    const error = platformTokenRefusalError("expired");
+    expect(error.code).toBe(Code.Unauthenticated);
+    expect(error.rawMessage).toBe("platform token is expired");
+  });
+});