@stigmer/server 3.23.1-dev.20260923075205 → 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/apiresource-labels.ts

@@ -45,15 +45,16 @@ export const SYSTEM_MANAGED_LABEL = `${RESERVED_LABEL_PREFIX}system-managed`;
 
 /**
  * Marks system content: a resource the platform itself seeded rather than a
- * user authored — the system organization, the default agent, the
- * platform's own MCP servers. The label predates this module (the retired
- * seedpack wrote it on every row it applied; the official plugins' overlays
- * carry it on the resources they replace) and has one server-side meaning:
- * a plugin push may adopt a system-content row that holds a slug the plugin
- * needs, keeping the row's id and everything bound to it, instead of
- * refusing the slug as taken. It never marks a user's resource, so a user's
- * row is never adopted (domain/plugin/members.ts, judgeSlug). The CLI names
- * the same bytes as SYSTEM_ORG_LABEL for the organization it ensures.
+ * user authored. The retired seedpack wrote it on every row it applied, and
+ * CLIs before the bootstrap stopped labelling stamped it on the `stigmer`
+ * organization they created. A plugin overlay may still carry it on a
+ * member (a reserved label, so the push charges the platform permission for
+ * it). It has one server-side meaning: a plugin
+ * push may adopt a system-content row that holds a slug the plugin needs,
+ * keeping the row's id and everything bound to it, instead of refusing the
+ * slug as taken. It never marks a user's resource, so a user's row is never
+ * adopted (domain/plugin/members.ts, judgeSlug); on an organization it is
+ * inert.
  */
 export const SYSTEM_LABEL = `${RESERVED_LABEL_PREFIX}system`;
 

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

@@ -5,7 +5,8 @@
  * task config, through the `reference_kind` field option); each clause on
  * each kind — no org refused, a same-organization target must exist, the
  * floor applies to the kinds the run reads as the person and to no other,
- * a cross-organization target is admitted only at platform visibility with
+ * a relative reference's floor is capped at org and its target must still
+ * exist in the resource's organization, a cross-organization target is admitted only at platform visibility with
  * ONE sentence whether it is missing or merely not shared; the MCP-server
  * copy that predates the rule is byte-identical and its siblings take its
  * shape; the walk reads a reference's kind from its field, not from the
@@ -38,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";
@@ -96,6 +98,7 @@ const SCHEMAS_UNDER_THE_RULE: ReadonlyArray<DescMessage> = [
   AgentExecutionSchema,
   WorkflowExecutionSchema,
   ExecutionContextSchema,
+  PlatformClientSchema,
   AgentCallTaskConfigSchema,
 ];
 
@@ -289,6 +292,39 @@ describe("checkReference", () => {
     ).toEqual({ kind: "below-floor", targetVisibility: V.visibility_org });
   });
 
+  it("(ii) a relative reference's floor is capped at org: a platform resource may run with its organization's org-visible target, never a private one, and the target must exist", () => {
+    const relative = (slug: string): SpecReference => ({
+      ...ref(K.mcp_server, "acme", slug),
+      resolvesIn: "running-organization",
+    });
+    const privateTarget: SpecReference = {
+      ...ref(K.skill, "acme", "my-skill"),
+      resolvesIn: "running-organization",
+    };
+    const ACME_PLATFORM: ReferenceParent = {
+      org: "acme",
+      visibility: V.visibility_platform,
+    };
+    expect(checkReference(targets, ACME_PLATFORM, relative("github"))).toEqual({
+      kind: "ok",
+    });
+    expect(checkReference(targets, ACME_PLATFORM, privateTarget)).toEqual({
+      kind: "below-floor",
+      targetVisibility: V.visibility_private,
+    });
+    expect(checkReference(targets, ACME_PLATFORM, relative("ghost"))).toEqual({
+      kind: "missing",
+    });
+    // Below the cap the resource's own level decides, as for any reference.
+    expect(checkReference(targets, ACME_ORG, privateTarget)).toEqual({
+      kind: "below-floor",
+      targetVisibility: V.visibility_private,
+    });
+    expect(checkReference(targets, ACME_PRIVATE, privateTarget)).toEqual({
+      kind: "ok",
+    });
+  });
+
   it("(ii) the floor does not apply to what the server resolves on the run's behalf", () => {
     // An org-visible instance over a private personal environment: the
     // ordinary shape of a personal instance, admitted.

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/pipeline/steps/references.ts

@@ -28,7 +28,8 @@
  *        channel apps are resolved by the server on the run's behalf and
  *        never read by the person, so their level is not a leak the floor
  *        closes, and an org-visible instance may hold a private personal
- *        environment as it always has.
+ *        environment as it always has. A RELATIVE reference (below) is
+ *        compared against the resource's level capped at org.
  *   (iii) Another organization: the target must exist AND be
  *        platform-visible, answered with ONE sentence that does not say
  *        which failed. The caller has no standing to learn what another
@@ -48,14 +49,32 @@
  * the rule must agree with the runtime. A reference with an empty slug is
  * unset and skipped (the field-level CEL rules own "required").
  *
+ * A reference is RELATIVE when it names no organization of its own and
+ * the runtime resolves it in the organization the resource RUNS in, not
+ * the one it is stored in. Exactly one exists: a workflow `agent_call`
+ * task's bare slug (domain/workflow/agent-call-references.ts), which the
+ * runner resolves in the execution's organization; any workflow a person
+ * may execute can run from another organization by id. The rule judges
+ * it in the resource's own organization — the one its author can see, so
+ * the target must exist there — and caps its floor at org: only the
+ * running organization's own people ever read a target through it, and
+ * they can read an org-visible one. The cap changes nothing for a
+ * private or org resource and lets a platform-visible workflow call its
+ * organization's org-visible agent. A value fixed only at run (an
+ * `agent_call` agent holding a runtime expression) is not a reference at
+ * all: the collector yields nothing for it, and the run reads the
+ * resolved target as the person the run acts as, as it reads every
+ * id-bound binding.
+ *
  * The floor has a second door. Raising a resource's level through
  * updateVisibility could open the same gap a create cannot, so
  * GuardReferenceFloorOnEscalation runs on the two chains whose rows carry
  * run-read references (agent, workflow) after ValidateVisibilityUpdate:
  * when the requested level is above the stored one, every run-read
- * reference the STORED row carries must be at least the requested level,
- * judged by the same function over the same collectors, else the
- * escalation is refused naming the dependencies. Only the floor is asked at
+ * reference the STORED row carries must be at least the requested level
+ * (a relative one, at least the requested level capped at org), judged by
+ * the same function over the same collectors, else the escalation is
+ * refused naming the dependencies. Only the floor is asked at
  * that door — a dependency that has since left or stopped being shared was
  * judged when the row was written and is the run's to refuse.
  *
@@ -182,6 +201,13 @@ export interface SpecReference {
   readonly kind: ApiResourceKind;
   readonly slug: string;
   readonly org: string;
+  /**
+   * Present only on a RELATIVE reference (the module header): `org` is the
+   * resource's own, filled by the collector, and the runtime resolves the
+   * slug in the organization the resource runs in. The generic walker
+   * never sets it; only the `agent_call` collector does.
+   */
+  readonly resolvesIn?: "running-organization";
 }
 
 /** The resource the references belong to, as the rule needs it. */
@@ -279,13 +305,31 @@ export function checkReference(
   const entry = referenceTargetKind(ref.kind);
   if (
     entry?.readByRun === true &&
-    visibilityRank(target) < visibilityRank(parent.visibility)
+    visibilityRank(target) < visibilityRank(floorOf(parent, ref))
   ) {
     return { kind: "below-floor", targetVisibility: target };
   }
   return { kind: "ok" };
 }
 
+/**
+ * The level a same-organization target must reach: the resource's own,
+ * capped at org for a relative reference (the module header).
+ */
+function floorOf(
+  parent: ReferenceParent,
+  ref: SpecReference,
+): ApiResourceVisibility {
+  if (
+    ref.resolvesIn === "running-organization" &&
+    visibilityRank(parent.visibility) >
+      visibilityRank(ApiResourceVisibility.visibility_org)
+  ) {
+    return ApiResourceVisibility.visibility_org;
+  }
+  return parent.visibility;
+}
+
 /**
  * The order the floor compares on: private < org < platform, an unset
  * level reading as private (the level a row with no config holds). The