@stigmer/server 3.24.0 → 3.25.0

package/src/domain/identityaccount/controller.ts

@@ -108,6 +108,7 @@ import {
 import type {
   AccountCreatedHook,
   CreateAccount,
+  AccountProvisioning,
   CreateAccountInput,
   DirectAccountProvisioner,
 } from "./provisioning.js";
@@ -230,6 +231,7 @@ async function runCreateChain(
   account: IdentityAccount,
   caller: CallerIdentity,
   kind: ApiResourceKind,
+  provisioning: AccountProvisioning,
 ): Promise<IdentityAccount> {
   const reqCtx = new RequestContext(
     IdentityAccountSchema,
@@ -254,7 +256,7 @@ async function runCreateChain(
     .addStep(newCheckDuplicateStep(deps.accounts))
     .addStep(newBuildNewStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
-    .addStep(newAssignBackendFieldsStep())
+    .addStep(newAssignBackendFieldsStep(provisioning))
     .addStep(newPersistNewAccountStep(deps.accounts))
     .addStep(
       newCreateAuthorizationTuplesStep(
@@ -270,7 +272,9 @@ async function runCreateChain(
 /**
  * The create path as its in-process callers see it (provisioning.ts
  * `CreateAccount`): the input becomes the resource envelope the chain
- * expects, tagged with the kind this controller serves.
+ * expects, tagged with the kind this controller serves. A platform-client
+ * account carries its owning organization, as the cloud has always
+ * written it; a direct account belongs to no organization.
  */
 export function newCreateAccountPath(
   deps: CreateAccountPathDeps,
@@ -282,11 +286,17 @@ export function newCreateAccountPath(
       create(IdentityAccountSchema, {
         apiVersion: "iam.stigmer.ai/v1",
         kind: "IdentityAccount",
-        metadata: { name: input.name },
+        metadata: {
+          name: input.name,
+          ...(input.provisioning.mode === "platform_client"
+            ? { org: input.provisioning.org }
+            : {}),
+        },
         spec: input.spec,
       }),
       caller,
       kind,
+      input.provisioning,
     );
 }
 
@@ -303,7 +313,9 @@ function createRpc(
 ): Promise<IdentityAccount> {
   const caller = callerIdentityOf(ctx);
   guardInternalRpc(caller);
-  return runCreateChain(deps, account, caller, kindOf(ctx));
+  // The RPC creates the platform's own accounts only: a platform-client
+  // account is the mint's to provision, never a wire caller's.
+  return runCreateChain(deps, account, caller, kindOf(ctx), { mode: "direct" });
 }
 
 function guardInternalRpc(caller: CallerIdentity): void {

package/src/domain/identityaccount/operator.ts

@@ -83,6 +83,7 @@ export async function ensureOperatorAccount(
             email: operator.email,
           }),
         ),
+        provisioning: { mode: "direct" },
       },
       caller,
     );

package/src/domain/identityaccount/provisioning.ts

@@ -74,11 +74,27 @@ export class UserInfoFetchError extends Error {
   }
 }
 
+/**
+ * How the account being created was provisioned — the one input that
+ * decides its backend-assigned fields (steps.ts AssignBackendFields):
+ *   - `direct`: the platform's own subject (a first sign-in, the boot
+ *     operator, a machine account created over the RPC). Its subject may
+ *     not use the `stgm_pc|` prefix platform-client accounts reserve.
+ *   - `platform_client`: an end user a PlatformClient's mint provisioned
+ *     (domain/platformclient/mint.ts). Its subject is the reserved
+ *     composite, and it belongs to the client's owning organization, which
+ *     only this arm carries.
+ */
+export type AccountProvisioning =
+  | { readonly mode: "direct" }
+  | { readonly mode: "platform_client"; readonly org: string };
+
 /** What a caller of the create path supplies: the rest is the chain's. */
 export interface CreateAccountInput {
   /** `metadata.name`; the chain defaults an empty one. */
   readonly name: string;
   readonly spec: IdentityAccountSpec;
+  readonly provisioning: AccountProvisioning;
 }
 
 /**
@@ -152,6 +168,7 @@ export function newDirectAccountProvisioner(
             pictureUrl: profile.pictureUrl,
           }),
         ),
+        provisioning: { mode: "direct" },
       };
 
       try {

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

@@ -144,14 +144,18 @@ export function newResourceIdentityAccountStore(
 }
 
 /**
- * Non-federated: the platform's own subject. A federated account carries
- * its identity_provider_ref; open source never writes one (its create
- * path assigns `direct`), so this is the port's contract stated, not a
- * branch the OSS store expects to take.
+ * The platform's own subject: neither federated nor a platform-client end
+ * user. A federated account carries its identity_provider_ref (open source
+ * never writes one, so that arm is the port's contract stated); a
+ * platform-client account is the mint's, whose email and name the platform
+ * asserted, so no direct lookup — a verifier's subject resolve, getByEmail —
+ * may answer it.
  */
 function isDirect(account: IdentityAccount): boolean {
+  const mode = account.spec?.provisioningMode;
   return (
     account.spec?.identityProviderRef === undefined &&
-    account.spec?.provisioningMode !== IdentityAccountProvisioningMode.federated
+    mode !== IdentityAccountProvisioningMode.federated &&
+    mode !== IdentityAccountProvisioningMode.platform_client
   );
 }

package/src/domain/identityaccount/steps.ts

@@ -26,7 +26,8 @@
  *     subject, never its slug (the guideline's "domains with different
  *     uniqueness rules bring their own step under the same name").
  *   - AssignBackendFields: `is_machine_account` from the `@clients`
- *     suffix and `provisioning_mode direct` on create (the spec's
+ *     suffix and the provisioning mode the path was given (`direct`, or
+ *     `platform_client` for the mint's end users) on create (the spec's
  *     "assigned by backend" fields); on update, every backend-assigned
  *     field and the email are preserved from the existing row (A9: the
  *     cloud's writable surface — first/last name, picture, preferences —
@@ -63,11 +64,15 @@ import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
 import { TARGET_RESOURCE_KEY } from "../../pipeline/steps/load-target.js";
 import { idValueOf, metadataOf } from "../../pipeline/steps/shapes.js";
 import {
+  PLATFORM_CLIENT_SUBJECT_PREFIX,
   accountIdFor,
   accountNotFoundMessage,
   idpIdImmutableMessage,
   isMachineSubject,
+  isPlatformClientSubject,
+  reservedSubjectMessage,
 } from "./constants.js";
+import type { AccountProvisioning } from "./provisioning.js";
 import { DuplicateAccountError } from "./store.js";
 import type { IdentityAccountStore } from "./store.js";
 
@@ -158,11 +163,61 @@ export function assignDirectBackendFields(
   return spec;
 }
 
-export function newAssignBackendFieldsStep(): AccountStep {
+/**
+ * The backend-assigned fields of a PLATFORM-CLIENT account: the machine
+ * flag from the subject's shape (the cloud's rule for every mode), mode
+ * `platform_client`, no provider ref — the PlatformClient admits the user
+ * at mint time and is no ongoing authentication authority.
+ */
+function assignPlatformClientBackendFields(
+  spec: IdentityAccountSpec,
+): IdentityAccountSpec {
+  spec.isMachineAccount = isMachineSubject(spec.idpId);
+  spec.provisioningMode = IdentityAccountProvisioningMode.platform_client;
+  spec.identityProviderRef = undefined;
+  return spec;
+}
+
+/**
+ * AssignBackendFields on create, by how the account was provisioned. 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 must carry it — its absence is the mint's bug,
+ * never a client's input.
+ */
+export function newAssignBackendFieldsStep(
+  provisioning: AccountProvisioning,
+): AccountStep {
   return {
     name: "AssignBackendFields",
     execute(ctx: AccountContext): void {
-      assignDirectBackendFields(specOf(ctx));
+      const spec = specOf(ctx);
+      switch (provisioning.mode) {
+        case "direct":
+          if (isPlatformClientSubject(spec.idpId)) {
+            throw invalidArgumentError(reservedSubjectMessage(spec.idpId));
+          }
+          assignDirectBackendFields(spec);
+          return;
+        case "platform_client":
+          if (!isPlatformClientSubject(spec.idpId)) {
+            throw internalError(
+              new Error(
+                `a platform-client account's subject must carry the '${PLATFORM_CLIENT_SUBJECT_PREFIX}' prefix`,
+              ),
+              "assign backend fields",
+            );
+          }
+          assignPlatformClientBackendFields(spec);
+          return;
+        default: {
+          const exhaustive: never = provisioning;
+          throw internalError(
+            new Error(`unknown provisioning ${JSON.stringify(exhaustive)}`),
+            "assign backend fields",
+          );
+        }
+      }
     },
   };
 }

package/src/domain/identityaccount/store-contract.ts

@@ -109,6 +109,31 @@ function federatedAccount(overrides: {
   });
 }
 
+/**
+ * A platform-client end user as the mint provisions it: the reserved
+ * composite subject, mode `platform_client`, the owning organization, and
+ * the derived id of its subject (the id every subject lookup reads).
+ */
+function platformClientAccount(overrides: {
+  idpId: string;
+  email: string;
+}): IdentityAccount {
+  return create(IdentityAccountSchema, {
+    apiVersion: "iam.stigmer.ai/v1",
+    kind: "IdentityAccount",
+    metadata: {
+      id: accountIdFor(overrides.idpId),
+      name: overrides.email,
+      org: "acme",
+    },
+    spec: {
+      idpId: overrides.idpId,
+      email: overrides.email,
+      provisioningMode: IdentityAccountProvisioningMode.platform_client,
+    },
+  });
+}
+
 /** A direct account with no subject — the row no lookup could ever reach. */
 function subjectlessDirectAccount(): IdentityAccount {
   return create(IdentityAccountSchema, {
@@ -357,6 +382,32 @@ const CASES: ReadonlyArray<PortContractDeclaration<IdentityAccountStore>> = [
       );
     },
   ],
+  [
+    "findDirectByIdpId and findDirectByEmail never answer a platform-client account, while findByIdpId (any mode) does",
+    async ({ store }) => {
+      await store.save(
+        platformClientAccount({
+          idpId: "stgm_pc|acme|user-7",
+          email: "pat@example.com",
+        }),
+      );
+      assert.equal(
+        await store.findDirectByIdpId("stgm_pc|acme|user-7"),
+        undefined,
+        "the direct-subject lookup must not resolve to an account a platform client provisioned",
+      );
+      assert.equal(
+        await store.findDirectByEmail("pat@example.com"),
+        undefined,
+        "the direct-email lookup must not answer an email a platform asserted",
+      );
+      assert.equal(
+        (await store.findByIdpId("stgm_pc|acme|user-7"))?.spec?.provisioningMode,
+        IdentityAccountProvisioningMode.platform_client,
+        "the any-mode subject lookup — the mint's — must answer the platform-client account",
+      );
+    },
+  ],
   [
     "findByIds answers one row per distinct id, in first-occurrence order; an empty request answers an empty list",
     async ({ store }) => {

package/src/domain/identityaccount/store.ts

@@ -22,12 +22,14 @@
  *     with an empty `idp_id` is refused, since no lookup could reach it;
  *   - `update` replaces, never creates: an unknown id writes nothing;
  *   - `deleteById` of an unknown id resolves;
- *   - `findDirectByIdpId` answers only non-federated accounts (the
- *     platform's own subjects) — a customer's federated IdP may mint the
- *     same `auth0|…` shape and the platform lane must never resolve to it;
+ *   - `findDirectByIdpId` answers only the platform's own subjects —
+ *     never a federated account (a customer's federated IdP may mint the
+ *     same `auth0|…` shape and the platform lane must never resolve to it)
+ *     and never a platform-client end user (its subject is the mint's);
  *   - `findDirectByEmail` answers direct accounts only, by exact match:
  *     federation legitimately duplicates emails, so the email axis is
- *     non-unique;
+ *     non-unique, and a platform-client account's email is one its
+ *     platform asserted, so no email lookup may answer it;
  *   - `findByIds` answers one row per distinct id, in first-occurrence
  *     order, and skips unknown ids;
  *   - a typed not-found reads as `undefined`; any other storage failure
@@ -59,7 +61,7 @@ export interface IdentityAccountStore {
   findById(id: string): Promise<IdentityAccount | undefined>;
   /** Any provisioning mode — the getByIdpId RPC's lookup. */
   findByIdpId(idpId: string): Promise<IdentityAccount | undefined>;
-  /** Non-federated accounts only — the verifiers' and whoAmI's lookup. */
+  /** The platform's own subjects only (no federated, no platform-client) — the verifiers' and whoAmI's lookup. */
   findDirectByIdpId(idpId: string): Promise<IdentityAccount | undefined>;
   /** Direct accounts only, exact match — the getByEmail RPC's lookup. */
   findDirectByEmail(email: string): Promise<IdentityAccount | undefined>;

package/src/domain/platform/__tests__/platform.test.ts

@@ -17,7 +17,8 @@
  *     with the token fields empty (minting a proxy token is cloud-only);
  *   - getServerInfo reports the build stamp by default and the release a
  *     library consumer states through ComposeOptions.version otherwise
- *     (stigmer#1168: unbundled, the stamp is always "dev");
+ *     (stigmer#1168: unbundled, the stamp is always "dev"), and a
+ *     trusted-local server's posture as an explicit false;
  *   - getLicenseStatus answers `absent` with no claims and no key when no
  *     provider is composed, and the composed provider's report verbatim
  *     when one is — both stamped with the ONE instant the controller
@@ -138,6 +139,9 @@ describe("platform domain (composed server)", () => {
     // Unbundled runs report Go's unstamped default; release bundles stamp
     // the esbuild define (scripts/bundle-slim.mjs).
     expect(first.version).toBe("dev");
+    // A server that trusts every request says so on the wire: an explicit
+    // false, never an absent field a console would read as "unknown".
+    expect(first.authenticationRequired).toBe(false);
 
     const second = await client.getServerInfo({});
     expect(second.edition).toBe(first.edition);
@@ -285,6 +289,7 @@ describe("platform domain (keyless runner-token service)", () => {
         ),
         edition: ServerEdition.oss,
         version: "dev",
+        authenticationRequired: false,
         licenseStatus: ABSENT_LICENSE_STATUS,
         now: () => new Date(),
         logger: silentLogger,
@@ -320,6 +325,7 @@ describe("platform domain (license status)", () => {
         ),
         edition: ServerEdition.enterprise,
         version: "dev",
+        authenticationRequired: false,
         licenseStatus: provider,
         now: () => instant,
         logger: silentLogger,

package/src/domain/platform/controller.ts

@@ -106,6 +106,16 @@ export interface PlatformControllerDeps {
    * states its installed release and answers exactly as a bundle would.
    */
   readonly version: string;
+  /**
+   * The resolved require-authentication posture (compose.ts: the OSS
+   * issuer OR a unit's declaration), reported so a console can tell a
+   * server that verifies its callers from one that trusts every request —
+   * the features that hand out credentials only a verifying server
+   * honours (PlatformClient token minting) are unavailable on the latter.
+   * Always set on the wire, true or false: the field's absence is how a
+   * client recognises a server that predates it.
+   */
+  readonly authenticationRequired: boolean;
   /**
    * What license this server holds (extensions/license-status.ts). The
    * composition root installs the built-in `absent` provider when no unit
@@ -136,11 +146,12 @@ export function registerPlatformServices(
   });
 }
 
-/** Go GetServerInfo: the server edition and release version. */
+/** Go GetServerInfo: the server edition, release version and authentication posture. */
 function getServerInfo(deps: PlatformControllerDeps): GetServerInfoOutput {
   return create(GetServerInfoOutputSchema, {
     edition: deps.edition,
     version: deps.version,
+    authenticationRequired: deps.authenticationRequired,
   });
 }