@stigmer/server 3.14.1 → 3.15.0

package/src/boot/compose.ts

@@ -28,6 +28,7 @@ import path from "node:path";
 
 import type { ConnectRouter, Transport } from "@connectrpc/connect";
 
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { HealthCheckResponse_ServingStatus as ServingStatus } from "@stigmer/protos/grpc/health/v1/health_pb";
 
 import { registerAgentServices } from "../domain/agent/controller.js";
@@ -64,6 +65,15 @@ import { registerChannelConversationServices } from "../domain/agentchannel/conv
 import { registerChannelMessageServices } from "../domain/agentchannel/message.js";
 import { registerAgentShareServices } from "../domain/agentshare/controller.js";
 import { registerApiKeyServices } from "../domain/apikey/controller.js";
+import {
+  newCreateAccountPath,
+  registerIdentityAccountServices,
+} from "../domain/identityaccount/controller.js";
+import { ensureOperatorAccount } from "../domain/identityaccount/operator.js";
+import { newDirectAccountProvisioner } from "../domain/identityaccount/provisioning.js";
+import { newResourceIdentityAccountStore } from "../domain/identityaccount/resource-store.js";
+import { newIssuerDiscovery } from "../identity/oidc-discovery.js";
+import { newOidcUserInfoClient } from "../identity/oidc-userinfo.js";
 import { newApiKeyIdentityVerifier } from "../domain/apikey/verifier.js";
 import type { IdentityVerifier } from "../extensions/identity.js";
 import { registerArtifactServices } from "../domain/artifact/controller.js";
@@ -117,6 +127,7 @@ import {
 } from "../observability/rpc-metrics.js";
 import { buildInterceptorChain } from "../pipeline/chain.js";
 import { createVerifierChainInterceptor } from "../pipeline/interceptors/auth.js";
+import { operatorIdentitySnapshot } from "../pipeline/steps/defaults.js";
 import { createErrorBoundaryInterceptor } from "../pipeline/interceptors/error-boundary.js";
 import { createRequestMetricsInterceptor } from "../pipeline/interceptors/request-metrics.js";
 import { newPermissiveSingleTeamAuthorizer } from "../pipeline/steps/authorize.js";
@@ -221,6 +232,13 @@ export interface ComposedServer {
    * them or reorder them, and both are the drift DD-007 rules out.
    */
   identityVerifiers: ReadonlyArray<IdentityVerifier>;
+  /**
+   * The one routes function both routers are built from (exposed for
+   * tests, the `store` posture — the tier-truthfulness invariant
+   * enumerates the services a composition registers through it; the
+   * server registers no reflection service, deliberately).
+   */
+  routes: (router: ConnectRouter) => void;
   /** Completes wiring, flips SERVING, binds the port; returns the bound port. */
   start(): Promise<number>;
   /** NOT_SERVING first, stop background work, drain connections. */
@@ -294,6 +312,75 @@ export async function composeServer(
     });
   }
 
+  // The require-authentication posture has two sources OR'd here: the
+  // OSS OIDC issuer (O3 rulings Q1+Q2) and a composed unit's declaration
+  // (registry point, entry 20260904.02). Neither source = the OSS
+  // trusted-local posture, byte-identical wire behavior. Resolved in the
+  // storage stage because the posture decides a WRITE below (the operator
+  // account); the verifier chain it also governs is built at the end.
+  const authEnabled = config.oidcIssuer !== "";
+  const requireAuthentication =
+    authEnabled || extensions.requireAuthentication !== undefined;
+
+  // Stage: identity accounts (20260911.11) — the first domain whose
+  // persistence is a PORT rather than the generic Store. The composed
+  // driver (`drivers.identityAccountStore`, Q-IA-9) serves when a unit
+  // registers one; otherwise open source's adapter over `store` installs
+  // HERE (the default lives with the consumer, never in the registry).
+  // This ONE binding is what the create path, the provisioner, the
+  // operator ensure and both OSS verifiers read, so a composed driver is
+  // followed everywhere by construction. The domain's one create path is
+  // built once and shared by the create RPC, provisioning and the operator
+  // ensure below.
+  const identityAccounts =
+    extensions.drivers.identityAccountStore ??
+    newResourceIdentityAccountStore(store);
+  const identityAccountPath = {
+    accounts: identityAccounts,
+    logger,
+    authorizer,
+    authorizationLifecycle,
+  };
+  const createIdentityAccount = newCreateAccountPath(
+    identityAccountPath,
+    ApiResourceKind.identity_account,
+  );
+  // ONE issuer discovery for every lane that reads a well-known document
+  // (A8): provisioning's userinfo client here and the OIDC verifier's
+  // JWKS location below share it, so an issuer is discovered once per
+  // process and validated the same way wherever it is consumed. Built in
+  // this stage, not inside routes() (which runs twice) — the same reason
+  // the searchRegistry lives here.
+  const issuerDiscovery = newIssuerDiscovery();
+  // Provisioning reads the caller's profile from the userinfo endpoint of
+  // the issuer that vouched for the token, discovered per issuer and
+  // cached (A8) — so a composition whose own verifiers name their issuer
+  // on the identity needs no knob here.
+  const identityAccountProvisioner = newDirectAccountProvisioner({
+    accounts: identityAccounts,
+    createAccount: createIdentityAccount,
+    userInfo: newOidcUserInfoClient(issuerDiscovery),
+  });
+  // Under the trusted-local posture the server knows its one principal
+  // from the operator seam (the SAME seam the interceptor stamps callers
+  // from — never config directly, so the row and the stamp cannot
+  // disagree; T01_1_review.md A2, A5) and states the fact at boot:
+  // create-if-absent, so preferences set later survive every reboot. A
+  // composition with an authentication posture never creates one — its
+  // users provision themselves on first sign-in. A stage that writes a
+  // resource is new here; it earns its place because it is the truth of
+  // that posture, and a failure is a loud boot throw like the storage
+  // stage's own.
+  if (!requireAuthentication) {
+    const operator = await ensureOperatorAccount(
+      { accounts: identityAccounts, createAccount: createIdentityAccount },
+      operatorIdentitySnapshot(),
+    );
+    logger.info("trusted-local operator account ensured", {
+      accountId: operator.metadata?.id ?? "",
+    });
+  }
+
   // Stage: keys — the ratified fail-loud boot ASYMMETRY (D2 cross-domain
   // invariants; Go server.go:277-293):
   //
@@ -799,6 +886,17 @@ export async function composeServer(
       authorizationLifecycle,
       listReadScope: extensions.drivers.listReadScope,
     });
+    // IdentityAccount (20260911.11): served once by open source in every
+    // edition over the store PORT bound in the identity-accounts stage; a
+    // composition adds what differs per edition through the registry —
+    // the federation capability (the four federated RPC arms) and the
+    // provision slot's gate steps (the cloud's personal organization).
+    registerIdentityAccountServices(router, {
+      ...identityAccountPath,
+      provisioner: identityAccountProvisioner,
+      federation: extensions.drivers.identityFederation,
+      gateSteps: extensions.gateSteps,
+    });
     registerEnvironmentServices(router, {
       store,
       logger,
@@ -1092,14 +1190,8 @@ export async function composeServer(
   const inProcessWiring = createInProcessClients(routes, logger);
   inProcess = inProcessWiring.clients;
 
-  // The require-authentication posture has two sources OR'd here: the
-  // OSS OIDC issuer (O3 rulings Q1+Q2) and a composed unit's declaration
-  // (registry point, entry 20260904.02). Neither source = the OSS
-  // trusted-local posture, byte-identical wire behavior.
-  const authEnabled = config.oidcIssuer !== "";
-  const requireAuthentication =
-    authEnabled || extensions.requireAuthentication !== undefined;
-  // What the posture registers, in Java's ProviderManager order (opaque
+  // What the posture (resolved in the storage stage) registers, in Java's
+  // ProviderManager order (opaque
   // keys first — the cheapest claim — then the JWT lanes), ahead of the
   // extension entries ("OSS entries first", the registry contract):
   //   - the API-key verifier rides the POSTURE, not the issuer
@@ -1108,19 +1200,31 @@ export async function composeServer(
   //     authentication posture must honor the keys it issues. Gating it on
   //     the issuer left a posture-declaring composition minting keys
   //     nothing verified.
-  //   - the OIDC verifier rides the ISSUER alone: it resolves callers to
-  //     the token's `sub`, which is the wrong principal for a composition
-  //     whose own lanes resolve users to their account ids — that is why a
-  //     declared posture never borrows the issuer knob.
+  //   - the OIDC verifier rides the ISSUER alone: it is open source's
+  //     single-issuer lane, and a composition with verifiers of its own
+  //     names their issuers and audiences itself and declares the posture
+  //     instead — so the knob and the extension entries never both claim
+  //     one JWT.
+  //   - both OSS verifiers resolve their subject through the identity-
+  //     account domain (20260911.11 Q-IA-2, A6): a provisioned user is
+  //     stamped with the account id whichever credential they present,
+  //     an unprovisioned one is admitted idp-shaped. They read the SAME
+  //     port the domain writes through (`identityAccounts`, the
+  //     identity-accounts stage — a composed driver included), so a row
+  //     provisioning creates resolves on the very next request.
   // The runner's credential in either posture is an operator-minted API
   // token via STIGMER_TOKEN (O3 ruling Q3) — no runner-specific verifier.
   const identityVerifiers = [
-    ...(requireAuthentication ? [newApiKeyIdentityVerifier(store)] : []),
+    ...(requireAuthentication
+      ? [newApiKeyIdentityVerifier({ store, accounts: identityAccounts })]
+      : []),
     ...(authEnabled
       ? [
           newOidcIdentityVerifier({
             issuer: config.oidcIssuer,
             audience: config.oidcAudience,
+            accounts: identityAccounts,
+            discovery: issuerDiscovery,
           }),
         ]
       : []),
@@ -1203,6 +1307,7 @@ export async function composeServer(
     workflowExecutionStreamBroker,
     inProcessTransport: inProcessWiring.transport,
     identityVerifiers,
+    routes,
 
     async start(): Promise<number> {
       // Temporal boot is NON-fatal end to end (Go server.go): a failed

package/src/domain/apikey/__tests__/verifier.test.ts

@@ -6,6 +6,15 @@
  * authenticates-as-owner identity mapping (created_by actor → identityId
  * + display fields), and instant revocation (delete visible on the very
  * next verify — the no-cache posture).
+ *
+ * Since 20260911.11 (T01_1_review.md A6) the creator stamp is resolved
+ * the way the OIDC lane resolves `sub`: a key minted before its owner
+ * was provisioned carries the raw subject and answers the owner's
+ * ACCOUNT id once one exists; a stamp that is already an account id is
+ * kept; one primary-key read either way, no cache. The account store is
+ * the REAL open-source adapter over the same SQLite store the keys live
+ * in, so what is pinned is the production pair; only the fault arm
+ * substitutes a one-method lookup that rejects.
  */
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -18,9 +27,15 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import { IdentityAccountSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
 
 import { createLogger } from "../../../boot/logger.js";
 import { SqliteStore } from "../../../store/sqlite/store.js";
+import { accountIdFor } from "../../identityaccount/constants.js";
+import type { AccountsBySubject } from "../../identityaccount/resolve.js";
+import { newResourceIdentityAccountStore } from "../../identityaccount/resource-store.js";
+import type { IdentityAccountStore } from "../../identityaccount/store.js";
 import { generateApiKeyPlaintext, hashApiKey } from "../keymaterial.js";
 import {
   INVALID_TOKEN_MESSAGE,
@@ -30,6 +45,7 @@ import {
 
 let dir: string;
 let store: SqliteStore;
+let accounts: IdentityAccountStore;
 
 beforeAll(() => {
   dir = mkdtempSync(path.join(tmpdir(), "apikey-verifier-test-"));
@@ -37,8 +53,32 @@ beforeAll(() => {
     path.join(dir, "stigmer.db"),
     createLogger({ level: "error", pretty: false, write: () => {} }),
   );
+  accounts = newResourceIdentityAccountStore(store);
 });
 
+/** The verifier as compose builds it: the key store and the account port over ONE store. */
+function verifier(lookup: AccountsBySubject = accounts) {
+  return newApiKeyIdentityVerifier({ store, accounts: lookup });
+}
+
+/** A direct account for `sub` through the real adapter — derived id, as provisioning writes it. */
+async function provisionAccount(sub: string, email: string): Promise<string> {
+  const id = accountIdFor(sub);
+  await accounts.save(
+    create(IdentityAccountSchema, {
+      apiVersion: "iam.stigmer.ai/v1",
+      kind: "IdentityAccount",
+      metadata: { id, name: email },
+      spec: {
+        idpId: sub,
+        email,
+        provisioningMode: IdentityAccountProvisioningMode.direct,
+      },
+    }),
+  );
+  return id;
+}
+
 afterAll(async () => {
   await store.close();
   rmSync(dir, { recursive: true, force: true });
@@ -75,7 +115,10 @@ async function seedKey(options?: {
           : {}),
       },
       status: {
-        audit: { specAudit: { createdBy: owner }, statusAudit: { createdBy: owner } },
+        audit: {
+          specAudit: { createdBy: owner },
+          statusAudit: { createdBy: owner },
+        },
       },
     }),
   );
@@ -84,16 +127,16 @@ async function seedKey(options?: {
 
 describe("claim-or-pass", () => {
   it("passes (null) on anything without the stk_ prefix", async () => {
-    const verifier = newApiKeyIdentityVerifier(store);
-    expect(await verifier.verify("eyJhbGciOiJSUzI1NiJ9.x.y")).toBeNull();
-    expect(await verifier.verify("Basic-ish-token")).toBeNull();
+    const apikey = verifier();
+    expect(await apikey.verify("eyJhbGciOiJSUzI1NiJ9.x.y")).toBeNull();
+    expect(await apikey.verify("Basic-ish-token")).toBeNull();
   });
 
   it("claims stk_ tokens case-insensitively (Java startsWithIgnoreCase)", async () => {
-    const verifier = newApiKeyIdentityVerifier(store);
+    const apikey = verifier();
     // Recognized but unknown — must THROW, never pass (a forged key must
     // not fall through to a laxer verifier).
-    await expect(verifier.verify("STK_unknown")).rejects.toSatisfy(
+    await expect(apikey.verify("STK_unknown")).rejects.toSatisfy(
       (error: unknown) => {
         expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
         expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
@@ -110,7 +153,7 @@ describe("verification arms", () => {
       email: "owner@example.com",
       displayName: "Key Owner",
     });
-    const identity = await newApiKeyIdentityVerifier(store).verify(plaintext);
+    const identity = await verifier().verify(plaintext);
     expect(identity).toEqual({
       identityId: "ida_owner1",
       callerClass: "user",
@@ -125,29 +168,29 @@ describe("verification arms", () => {
     const { plaintext } = await seedKey({
       expiresAt: new Date(Date.now() - 60_000),
     });
-    await expect(
-      newApiKeyIdentityVerifier(store).verify(plaintext),
-    ).rejects.toSatisfy((error: unknown) => {
-      expect(ConnectError.from(error).rawMessage).toBe(TOKEN_EXPIRED_MESSAGE);
-      return true;
-    });
+    await expect(verifier().verify(plaintext)).rejects.toSatisfy(
+      (error: unknown) => {
+        expect(ConnectError.from(error).rawMessage).toBe(TOKEN_EXPIRED_MESSAGE);
+        return true;
+      },
+    );
   });
 
   it("a future expiry verifies fine (expires_at set and NOT past)", async () => {
     const { plaintext } = await seedKey({
       expiresAt: new Date(Date.now() + 60_000),
     });
-    const identity = await newApiKeyIdentityVerifier(store).verify(plaintext);
+    const identity = await verifier().verify(plaintext);
     expect(identity?.callerClass).toBe("user");
   });
 
   it("a deleted key is rejected on the very next verify (no cache)", async () => {
     const { plaintext, id } = await seedKey();
-    const verifier = newApiKeyIdentityVerifier(store);
-    expect(await verifier.verify(plaintext)).not.toBeNull();
+    const apikey = verifier();
+    expect(await apikey.verify(plaintext)).not.toBeNull();
 
     await store.deleteResource(ApiResourceKind.api_key, id);
-    await expect(verifier.verify(plaintext)).rejects.toSatisfy(
+    await expect(apikey.verify(plaintext)).rejects.toSatisfy(
       (error: unknown) => {
         expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
         return true;
@@ -170,11 +213,92 @@ describe("verification arms", () => {
         spec: { keyHash: hashApiKey(plaintext) },
       }),
     );
-    await expect(
-      newApiKeyIdentityVerifier(store).verify(plaintext),
-    ).rejects.toSatisfy((error: unknown) => {
-      expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
-      return true;
+    await expect(verifier().verify(plaintext)).rejects.toSatisfy(
+      (error: unknown) => {
+        expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
+        return true;
+      },
+    );
+  });
+});
+
+describe("creator stamp → account resolution (20260911.11 A6)", () => {
+  it("a key minted BEFORE its owner was provisioned resolves to the owner's account once one exists; the display fields stay the stamp's", async () => {
+    const { plaintext } = await seedKey({
+      ownerId: "auth0|early-adopter",
+      email: "early@example.com",
+      displayName: "Early Adopter",
+    });
+    const accountId = await provisionAccount(
+      "auth0|early-adopter",
+      "early@example.com",
+    );
+    expect(await verifier().verify(plaintext)).toEqual({
+      identityId: accountId,
+      callerClass: "user",
+      issuer: "",
+      rawToken: plaintext,
+      email: "early@example.com",
+      displayName: "Early Adopter",
     });
   });
+
+  it("a stamp that is already an account id is kept — no account carries it as a subject", async () => {
+    const accountId = await provisionAccount(
+      "auth0|provisioned-first",
+      "first@example.com",
+    );
+    const { plaintext } = await seedKey({ ownerId: accountId });
+    expect((await verifier().verify(plaintext))?.identityId).toBe(accountId);
+  });
+
+  it("resolution is one read per verify with no cache — an account provisioned between two verifies is seen by the second", async () => {
+    const { plaintext } = await seedKey({ ownerId: "auth0|late-bloomer" });
+    const apikey = verifier();
+    expect((await apikey.verify(plaintext))?.identityId).toBe(
+      "auth0|late-bloomer",
+    );
+    const accountId = await provisionAccount(
+      "auth0|late-bloomer",
+      "late@example.com",
+    );
+    expect((await apikey.verify(plaintext))?.identityId).toBe(accountId);
+  });
+
+  it("an account-store fault is an infrastructure fault (plain error), never a credential rejection", async () => {
+    const { plaintext } = await seedKey({ ownerId: "auth0|anyone" });
+    const broken: AccountsBySubject = {
+      findDirectByIdpId: () => Promise.reject(new Error("store is on fire")),
+    };
+    const error = await verifier(broken)
+      .verify(plaintext)
+      .then(
+        () => {
+          throw new Error("expected rejection");
+        },
+        (e: unknown) => e,
+      );
+    expect(error).not.toBeInstanceOf(ConnectError);
+    expect(String(error)).toContain("store is on fire");
+  });
+
+  it("a revoked or expired key never reaches the account store — credential checks come first", async () => {
+    const reads: string[] = [];
+    const counting: AccountsBySubject = {
+      findDirectByIdpId: async (idpId) => {
+        reads.push(idpId);
+        return undefined;
+      },
+    };
+    const { plaintext: expired } = await seedKey({
+      expiresAt: new Date(Date.now() - 60_000),
+    });
+    await expect(verifier(counting).verify(expired)).rejects.toBeInstanceOf(
+      ConnectError,
+    );
+    await expect(
+      verifier(counting).verify("stk_never_minted"),
+    ).rejects.toBeInstanceOf(ConnectError);
+    expect(reads).toEqual([]);
+  });
 });

package/src/domain/apikey/verifier.ts

@@ -23,6 +23,16 @@
  * seam wants. Expiry is "expires_at set and past"; never_expires is
  * deliberately not read — Java parity (never-expiring keys leave
  * expires_at unset).
+ *
+ * The stamp is then resolved the way the OIDC lane resolves `sub`
+ * (20260911.11, T01_1_review.md A6; domain/identityaccount/resolve.ts):
+ * a key minted before its owner was provisioned carries the raw subject
+ * and answers the owner's ACCOUNT id once one exists, so no write over a
+ * legacy key mints a raw-subject stamp again; a stamp that is already an
+ * account id is kept — one primary-key read either way, no cache. Only
+ * identityId changes on a hit: email/displayName stay the stamp's, the
+ * actor the key recorded at minting. The credential checks run first, so
+ * a revoked or expired key never reaches the account store.
  */
 import { Code, ConnectError } from "@connectrpc/connect";
 import { timestampDate } from "@bufbuild/protobuf/wkt";
@@ -32,6 +42,8 @@ import type {
   IdentityVerifier,
 } from "../../extensions/identity.js";
 import type { Store } from "../../store/interface.js";
+import { identityIdForSubject } from "../identityaccount/resolve.js";
+import type { AccountsBySubject } from "../identityaccount/resolve.js";
 import { hashApiKey, isApiKeyToken } from "./keymaterial.js";
 import { findApiKeyByHash } from "./lookup.js";
 
@@ -41,7 +53,17 @@ export const INVALID_TOKEN_MESSAGE = "invalid token";
 /** Java classifyAuthError's "expired" arm. */
 export const TOKEN_EXPIRED_MESSAGE = "token has expired";
 
-export function newApiKeyIdentityVerifier(store: Store): IdentityVerifier {
+export interface ApiKeyVerifierDeps {
+  /** Where the keys live — the generic Store, by hash (lookup.ts). */
+  readonly store: Store;
+  /** The identity-account domain's subject lookup the creator stamp resolves through (A6). */
+  readonly accounts: AccountsBySubject;
+}
+
+export function newApiKeyIdentityVerifier(
+  deps: ApiKeyVerifierDeps,
+): IdentityVerifier {
+  const { store, accounts } = deps;
   return {
     name: "apikey",
     async verify(token: string): Promise<CallerIdentity | null> {
@@ -64,7 +86,7 @@ export function newApiKeyIdentityVerifier(store: Store): IdentityVerifier {
         throw new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
       }
       return {
-        identityId: owner.id,
+        identityId: await identityIdForSubject(accounts, owner.id),
         callerClass: "user",
         issuer: "",
         rawToken: token,

package/src/domain/identityaccount/__tests__/constants.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Pins the identity-account domain's constants (project 20260911.11,
+ * T01_1_review.md A1 and A2):
+ *
+ *   - the account-id derivation — `ida_` + the top 130 bits of
+ *     sha256(idp_id) as 26 lowercase Crockford-base32 characters, so a
+ *     derived id is indistinguishable in shape from a minted `{prefix}_{ulid}`
+ *     and the primary key is the one home of "one account per subject".
+ *     The golden vectors are wire-adjacent constants: a change here
+ *     re-addresses every direct account open source ever created;
+ *   - `idpIdOf(caller)` — the ONE place a caller becomes an issuer subject:
+ *     a token-bearing caller's JWT `sub`; `local|<identityId>` for a caller
+ *     with no issuer and no token (the trusted-local posture);
+ *   - the byte-pinned copy moved from the cloud's handlers as-is, plus the
+ *     two new sentences (the federation refusal, the immutable subject).
+ */
+import { describe, expect, it } from "vitest";
+
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import {
+  ACCOUNT_NOT_FOUND_FOR_CALLER_MESSAGE,
+  FEDERATION_UNIMPLEMENTED_REASON,
+  LOCAL_IDP_ID_PREFIX,
+  NO_IDP_ID_MESSAGE,
+  USERINFO_UNAVAILABLE_PREFIX,
+  accountIdFor,
+  accountNotFoundMessage,
+  federationUnimplementedMessage,
+  idpIdImmutableMessage,
+  idpIdOf,
+  localIdpIdFor,
+} from "../constants.js";
+
+const CROCKFORD_ID = /^ida_[0-9abcdefghjkmnpqrstvwxyz]{26}$/;
+
+describe("accountIdFor — the derived account id", () => {
+  it("pins the golden vectors (a change re-addresses every OSS account)", () => {
+    expect(accountIdFor("auth0|user123")).toBe(
+      "ida_wtr3jcf281yfk9xx61kj59fsme",
+    );
+    expect(accountIdFor("local|system")).toBe("ida_fn0zdvkkkhhrb4wry43zba8gnn");
+    expect(accountIdFor("local|operator@example.com")).toBe(
+      "ida_0byc5k14t1e7b7kdxft7hwz1f7",
+    );
+  });
+
+  it("has the shape of every minted id: prefix, underscore, 26 Crockford chars", () => {
+    for (const subject of [
+      "auth0|user123",
+      "google-oauth2|109876543210",
+      "x",
+    ]) {
+      expect(accountIdFor(subject)).toMatch(CROCKFORD_ID);
+    }
+  });
+
+  it("is a pure function of the subject", () => {
+    expect(accountIdFor("auth0|user123")).toBe(accountIdFor("auth0|user123"));
+  });
+
+  it("separates subjects that differ by one character", () => {
+    expect(accountIdFor("auth0|user123")).not.toBe(
+      accountIdFor("auth0|user124"),
+    );
+    expect(accountIdFor("auth0|user123")).not.toBe(
+      accountIdFor("auth0|User123"),
+    );
+  });
+
+  it("hashes the UTF-8 bytes — unicode and long subjects derive stably", () => {
+    expect(accountIdFor("ünïcödé|日本語")).toBe(
+      "ida_sk0tfhnzv2mshyh5cvpb2c84fd",
+    );
+    expect(accountIdFor("a".repeat(4096))).toMatch(CROCKFORD_ID);
+  });
+
+  it("refuses an empty subject — no principal, no address", () => {
+    expect(() => accountIdFor("")).toThrow("idp_id must not be empty");
+  });
+});
+
+describe("idpIdOf — the one place a caller becomes a subject", () => {
+  const base = { callerClass: "user", rawToken: "" } as const;
+
+  it("a caller with no issuer and no token is the local operator: local|<identityId>", () => {
+    const operator: CallerIdentity = {
+      ...base,
+      identityId: "operator@example.com",
+      issuer: "",
+    };
+    expect(idpIdOf(operator)).toBe("local|operator@example.com");
+    expect(localIdpIdFor("system")).toBe(`${LOCAL_IDP_ID_PREFIX}system`);
+  });
+
+  it("a token-bearing caller is its JWT subject, whatever identityId was resolved to", async () => {
+    // A three-segment JWT whose payload carries sub — the verifier already
+    // proved the signature; this function only reads the claim.
+    const payload = Buffer.from(
+      JSON.stringify({ sub: "auth0|user123" }),
+    ).toString("base64url");
+    const resolved: CallerIdentity = {
+      ...base,
+      identityId: accountIdFor("auth0|user123"),
+      issuer: "https://issuer.test",
+      rawToken: `eyJhbGciOiJSUzI1NiJ9.${payload}.sig`,
+    };
+    expect(idpIdOf(resolved)).toBe("auth0|user123");
+  });
+
+  it("a token without a readable subject yields the empty string (the UNAUTHENTICATED arm's input)", () => {
+    const opaque: CallerIdentity = {
+      ...base,
+      identityId: "ida_whatever",
+      issuer: "https://issuer.test",
+      rawToken: "stk_not_a_jwt",
+    };
+    expect(idpIdOf(opaque)).toBe("");
+  });
+});
+
+describe("byte-pinned copy", () => {
+  it("moves the cloud handlers' sentences as-is", () => {
+    expect(ACCOUNT_NOT_FOUND_FOR_CALLER_MESSAGE).toBe(
+      "Identity account not found for the authenticated user",
+    );
+    expect(NO_IDP_ID_MESSAGE).toBe(
+      "Cannot provision account: no IDP ID in authentication context",
+    );
+    expect(USERINFO_UNAVAILABLE_PREFIX).toBe(
+      "Failed to fetch user profile from identity provider: ",
+    );
+    expect(accountNotFoundMessage("ida_x")).toBe(
+      "Identity account not found: ida_x",
+    );
+  });
+
+  it("the two new sentences name the edition and the subject", () => {
+    // The organization directory's absent-method shape ("<method> is not
+    // implemented", controller.ts refusesEnumeration) so clients that match
+    // on it keep working, followed by the reason a person can act on.
+    expect(FEDERATION_UNIMPLEMENTED_REASON).toBe(
+      "federated identity accounts are served by the Enterprise and Cloud editions",
+    );
+    expect(
+      federationUnimplementedMessage(
+        "ai.stigmer.iam.identityaccount.v1.IdentityAccountCommandController.createFederatedAccount",
+      ),
+    ).toBe(
+      "ai.stigmer.iam.identityaccount.v1.IdentityAccountCommandController.createFederatedAccount is not implemented: federated identity accounts are served by the Enterprise and Cloud editions",
+    );
+    expect(idpIdImmutableMessage("auth0|user123")).toBe(
+      "spec.idp_id is immutable (account subject is 'auth0|user123') — create a new account for a different subject",
+    );
+  });
+});