@stigmer/server 3.23.1-dev.20260923075205 → 3.25.0

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,
   });
 }
 

package/src/domain/platformclient/__tests__/controller.test.ts

@@ -0,0 +1,397 @@
+/**
+ * Pins the PlatformClient chains over the OSS adapter on sqlite, through the
+ * package's own interceptor chain (validation included):
+ *   - create answers the secret once and a client whose stored hash never
+ *     leaves: not on create, get, getByReference, listByOrg, update,
+ *     rotateSecret or delete — while the ROW keeps the hash the mint needs;
+ *   - update replaces the spec and keeps the credentials, addressed by id
+ *     or by org-scoped slug;
+ *   - rotateSecret replaces the secret and fingerprint under the same
+ *     client_id, and the row's hash follows;
+ *   - the reserved slug is refused, the two auto-grant rules are refused on
+ *     the contract, and a system-managed client refuses update, delete and
+ *     rotate with the cloud's copy;
+ *   - create and update run the reference rule on `environment_refs`: a
+ *     bare slug is stored under the client's organization, a missing
+ *     environment is refused on either chain before anything is stored, and
+ *     another organization's environment is refused with the rule's one
+ *     sentence;
+ *   - listByOrg answers the organization's clients, newest first.
+ * Who may read a client is the enforcing lane's conformance suite's.
+ */
+import {
+  Code,
+  ConnectError,
+  createClient,
+  createRouterTransport,
+} from "@connectrpc/connect";
+import type { Client } from "@connectrpc/connect";
+import { clone, create } from "@bufbuild/protobuf";
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_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 { PlatformClientSpecSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/spec_pb";
+import type { PlatformClientSpec } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/spec_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import { silentLogger } from "../../../extensions/__tests__/composed-support.js";
+import {
+  SYSTEM_MANAGED_LABEL,
+  RESERVED_LABEL_TRUE,
+} from "../../../pipeline/apiresource-labels.js";
+import { buildInterceptorChain } from "../../../pipeline/chain.js";
+import { createInProcessCallerInterceptor } from "../../../pipeline/interceptors/auth.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import {
+  missingReferencesMessage,
+  notAvailableReferenceMessage,
+  referenceTargetKind,
+} from "../../../pipeline/steps/references.js";
+import type { Store } from "../../../store/interface.js";
+import { tempStore } from "../../../store/sqlite/__tests__/support.js";
+import { reservedSlugMessage, systemManagedMessage } from "../constants.js";
+import { registerPlatformClientServices } from "../controller.js";
+import { hashClientSecret } from "../credentials.js";
+import { newResourcePlatformClientStore } from "../resource-store.js";
+import type { PlatformClientStore } from "../store.js";
+
+let cleanup: () => void;
+let store: Store;
+let clients: PlatformClientStore;
+let command: Client<typeof PlatformClientCommandController>;
+let query: Client<typeof PlatformClientQueryController>;
+
+beforeEach(() => {
+  const temp = tempStore();
+  cleanup = () => temp.cleanup();
+  store = temp.store;
+  clients = newResourcePlatformClientStore(temp.store);
+  const transport = createRouterTransport(
+    (router) =>
+      registerPlatformClientServices(router, {
+        clients,
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        listReadScope: undefined,
+      }),
+    {
+      router: {
+        interceptors: buildInterceptorChain(
+          silentLogger,
+          createInProcessCallerInterceptor(),
+        ),
+      },
+    },
+  );
+  command = createClient(PlatformClientCommandController, transport);
+  query = createClient(PlatformClientQueryController, transport);
+});
+
+afterEach(() => cleanup());
+
+function input(
+  name: string,
+  spec: MessageInitShape<typeof PlatformClientSpecSchema> = {},
+) {
+  return create(PlatformClientSchema, {
+    apiVersion: "iam.stigmer.ai/v1",
+    kind: "PlatformClient",
+    metadata: { name, org: "acme" },
+    spec: { autoProvisionAccounts: true, ...spec },
+  });
+}
+
+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");
+}
+
+async function seedEnvironment(org: string, slug: string): Promise<void> {
+  const id = `env_${org}_${slug}`;
+  await store.saveResource(
+    ApiResourceKind.environment,
+    id,
+    EnvironmentSchema,
+    create(EnvironmentSchema, {
+      apiVersion: "agentic.stigmer.ai/v1",
+      kind: "Environment",
+      metadata: {
+        id,
+        name: slug,
+        slug,
+        org,
+        visibility: ApiResourceVisibility.visibility_org,
+      },
+    }),
+  );
+}
+
+function environmentRef(slug: string, org = "") {
+  return { org, slug, kind: ApiResourceKind.environment };
+}
+
+function environmentTarget() {
+  const entry = referenceTargetKind(ApiResourceKind.environment);
+  if (entry === undefined)
+    throw new Error("environment is not a reference target kind");
+  return entry;
+}
+
+describe("PlatformClient chains", () => {
+  it("shows the secret once and never returns the stored hash, which the row keeps", async () => {
+    const created = await command.create(input("Dashboard"));
+    const id = created.platformClient?.metadata?.id ?? "";
+    expect(id).toMatch(/^pcl_/);
+    expect(created.clientSecret).toMatch(/^stgm_cs_/);
+    expect(created.platformClient?.spec?.clientSecretHash).toBe("");
+    expect(created.platformClient?.spec?.secretFingerprint).toBe(
+      created.clientSecret.slice(-6),
+    );
+
+    expect((await clients.findById(id))?.spec?.clientSecretHash).toBe(
+      hashClientSecret(created.clientSecret),
+    );
+    expect((await query.get({ value: id })).spec?.clientSecretHash).toBe("");
+    expect(
+      (
+        await query.getByReference({
+          org: "acme",
+          slug: "dashboard",
+          kind: ApiResourceKind.platform_client,
+        })
+      ).spec?.clientSecretHash,
+    ).toBe("");
+    const listed = await query.listByOrg({ org: "acme" });
+    expect(listed.entries.map((entry) => entry.spec?.clientSecretHash)).toEqual(
+      [""],
+    );
+  });
+
+  it("update keeps the credentials, addressed by id or by slug", async () => {
+    const created = await command.create(input("Dashboard"));
+    const stored = created.platformClient;
+    const clientId = stored?.spec?.clientId ?? "";
+
+    if (stored?.spec === undefined) throw new Error("create answered no spec");
+    const byId = clone(PlatformClientSchema, stored);
+    byId.spec = clone(PlatformClientSpecSchema, stored.spec);
+    byId.spec.clientId = "stgm_cid_forged";
+    byId.spec.allowedOrigins = ["https://a.example"];
+    const updated = await command.update(byId);
+    expect(updated.spec?.clientId).toBe(clientId);
+    expect(updated.spec?.allowedOrigins).toEqual(["https://a.example"]);
+    expect(updated.spec?.clientSecretHash).toBe("");
+
+    const bySlug = create(PlatformClientSchema, {
+      apiVersion: "iam.stigmer.ai/v1",
+      kind: "PlatformClient",
+      metadata: { name: "Dashboard", org: "acme", slug: "dashboard" },
+      spec: { autoProvisionAccounts: false },
+    });
+    const viaSlug = await command.update(bySlug);
+    expect(viaSlug.metadata?.id).toBe(stored?.metadata?.id);
+    expect(viaSlug.spec?.clientId).toBe(clientId);
+    expect(
+      (await clients.findById(stored?.metadata?.id ?? ""))?.spec
+        ?.clientSecretHash,
+    ).toBe(hashClientSecret(created.clientSecret));
+  });
+
+  it("rotateSecret replaces the secret under the same client_id, and the row follows", async () => {
+    const created = await command.create(input("Dashboard"));
+    const id = created.platformClient?.metadata?.id ?? "";
+    const rotated = await command.rotateSecret({ value: id });
+
+    expect(rotated.clientSecret).not.toBe(created.clientSecret);
+    expect(rotated.platformClient?.spec?.clientId).toBe(
+      created.platformClient?.spec?.clientId,
+    );
+    expect(rotated.platformClient?.spec?.secretFingerprint).toBe(
+      rotated.clientSecret.slice(-6),
+    );
+    expect(rotated.platformClient?.spec?.clientSecretHash).toBe("");
+    expect((await clients.findById(id))?.spec?.clientSecretHash).toBe(
+      hashClientSecret(rotated.clientSecret),
+    );
+  });
+
+  it("refuses the reserved slug and the two auto-grant rules", async () => {
+    const reserved = await refusal(
+      command.create(
+        create(PlatformClientSchema, {
+          apiVersion: "iam.stigmer.ai/v1",
+          kind: "PlatformClient",
+          metadata: { name: "System Share Client", org: "acme" },
+        }),
+      ),
+    );
+    expect(reserved.code).toBe(Code.InvalidArgument);
+    expect(reserved.rawMessage).toBe(
+      reservedSlugMessage("system-share-client"),
+    );
+
+    const owner = await refusal(
+      command.create(
+        input("Owner grant", {
+          autoGrantOnOrg: true,
+          autoGrantRole: IamRole.owner,
+        }),
+      ),
+    );
+    expect(owner.code).toBe(Code.InvalidArgument);
+
+    const noProvision = await refusal(
+      command.create(
+        input("No provision", {
+          autoProvisionAccounts: false,
+          autoGrantOnOrg: true,
+        }),
+      ),
+    );
+    expect(noProvision.code).toBe(Code.InvalidArgument);
+  });
+
+  it("stores a bare environment slug under the client's organization", async () => {
+    await seedEnvironment("acme", "support-secrets");
+    const created = await command.create(
+      input("Dashboard", {
+        environmentRefs: [environmentRef("support-secrets")],
+      }),
+    );
+    const refsOf = (spec: PlatformClientSpec | undefined) =>
+      (spec?.environmentRefs ?? []).map((ref) => `${ref.org}/${ref.slug}`);
+    expect(refsOf(created.platformClient?.spec)).toEqual([
+      "acme/support-secrets",
+    ]);
+    const id = created.platformClient?.metadata?.id ?? "";
+    expect(refsOf((await clients.findById(id))?.spec)).toEqual([
+      "acme/support-secrets",
+    ]);
+  });
+
+  it("refuses a missing environment on create and on update, storing nothing", async () => {
+    const missing = missingReferencesMessage(environmentTarget(), [
+      { slug: "ghost", org: "acme" },
+    ]);
+
+    const onCreate = await refusal(
+      command.create(
+        input("Dashboard", { environmentRefs: [environmentRef("ghost")] }),
+      ),
+    );
+    expect(onCreate.code).toBe(Code.FailedPrecondition);
+    expect(onCreate.rawMessage).toBe(missing);
+    expect((await query.listByOrg({ org: "acme" })).entries).toEqual([]);
+
+    const created = await command.create(input("Dashboard"));
+    const stored = created.platformClient;
+    if (stored?.spec === undefined) throw new Error("create answered no spec");
+    const withGhost = clone(PlatformClientSchema, stored);
+    withGhost.spec = clone(PlatformClientSpecSchema, stored.spec);
+    withGhost.spec.environmentRefs = [
+      create(ApiResourceReferenceSchema, environmentRef("ghost")),
+    ];
+    const onUpdate = await refusal(command.update(withGhost));
+    expect(onUpdate.code).toBe(Code.FailedPrecondition);
+    expect(onUpdate.rawMessage).toBe(missing);
+    expect(
+      (await clients.findById(stored.metadata?.id ?? ""))?.spec
+        ?.environmentRefs,
+    ).toEqual([]);
+  });
+
+  it("refuses another organization's environment with the rule's one sentence", async () => {
+    await seedEnvironment("globex", "shared");
+    const foreign = await refusal(
+      command.create(
+        input("Dashboard", {
+          environmentRefs: [environmentRef("shared", "globex")],
+        }),
+      ),
+    );
+    expect(foreign.code).toBe(Code.FailedPrecondition);
+    expect(foreign.rawMessage).toBe(
+      notAvailableReferenceMessage(environmentTarget(), {
+        kind: ApiResourceKind.environment,
+        org: "globex",
+        slug: "shared",
+      }),
+    );
+  });
+
+  it("refuses to update, delete or rotate a system-managed client", async () => {
+    await clients.save(
+      create(PlatformClientSchema, {
+        apiVersion: "iam.stigmer.ai/v1",
+        kind: "PlatformClient",
+        metadata: {
+          id: "pcl_system",
+          name: "System Share Client",
+          org: "acme",
+          slug: "system-share-client",
+          labels: { [SYSTEM_MANAGED_LABEL]: RESERVED_LABEL_TRUE },
+        },
+        spec: { clientId: "stgm_cid_system" },
+      }),
+    );
+    const stored = await clients.findById("pcl_system");
+    if (stored === undefined) throw new Error("seeded client missing");
+
+    const update = await refusal(command.update(stored));
+    expect(update.code).toBe(Code.FailedPrecondition);
+    expect(update.rawMessage).toBe(systemManagedMessage("updated"));
+
+    const rotate = await refusal(command.rotateSecret({ value: "pcl_system" }));
+    expect(rotate.rawMessage).toBe(systemManagedMessage("rotated"));
+
+    const remove = await refusal(command.delete({ resourceId: "pcl_system" }));
+    expect(remove.rawMessage).toBe(systemManagedMessage("deleted"));
+    expect(await clients.findById("pcl_system")).toBeDefined();
+  });
+
+  it("listByOrg answers the organization's clients newest first", async () => {
+    for (const [id, seconds] of [
+      ["pcl_older", 1_000],
+      ["pcl_newer", 2_000],
+    ] as const) {
+      await clients.save(
+        create(PlatformClientSchema, {
+          metadata: { id, name: id, org: "acme", slug: id },
+          spec: { clientId: `stgm_cid_${id}` },
+          status: {
+            audit: { specAudit: { createdAt: { seconds: BigInt(seconds) } } },
+          },
+        }),
+      );
+    }
+    const listed = await query.listByOrg({ org: "acme" });
+    expect(listed.entries.map((entry) => entry.metadata?.id)).toEqual([
+      "pcl_newer",
+      "pcl_older",
+    ]);
+    expect((await query.listByOrg({ org: "globex" })).entries).toEqual([]);
+  });
+
+  it("delete answers the client without its hash and removes it", async () => {
+    const created = await command.create(input("Dashboard"));
+    const id = created.platformClient?.metadata?.id ?? "";
+
+    const deleted = await command.delete({ resourceId: id });
+    expect(deleted.spec?.clientSecretHash).toBe("");
+    expect(await clients.findById(id)).toBeUndefined();
+  });
+});