@stigmer/server 3.14.0 → 3.15.0

package/src/domain/identityaccount/operator.ts

@@ -0,0 +1,94 @@
+/**
+ * The trusted-local operator account (20260911.11, T01_1_review.md A2,
+ * A5): under the posture with no authentication, the server knows its one
+ * principal from config, so the server states the fact at boot instead of
+ * asking three clients to provision it (the console's gate is off on the
+ * laptop and the desktop has none).
+ *
+ * `ensureOperatorAccount` is create-if-absent under the derived id of
+ * `local|<operator email, or "system">`, through the domain's ONE create
+ * path AS the trusted-local identity, so the row is stamped, derived and
+ * tuple-lifecycled exactly like every other account. Create-if-absent
+ * means a later boot never touches the row: preferences set through
+ * `update` survive a reboot, and a changed display name is edited like
+ * any profile, never re-synced from config. A changed operator email is a
+ * different subject and therefore a different account — the platform
+ * already treats the email as the identity (boot/config.ts
+ * loadOperatorIdentity). Two replicas ensuring at once converge by
+ * primary key: a lost race reads the winner back.
+ *
+ * The operator arrives from the SAME seam the interceptor stamps the
+ * caller from (pipeline/interceptors/auth.ts operatorIdentitySnapshot,
+ * read by the composition root), and the account is created AS the
+ * identity that seam yields for it (trustedLocalIdentityFor — the one
+ * construction of that principal), never from config directly: one
+ * source, so the row, its audit stamp and the per-request caller cannot
+ * disagree (A5).
+ *
+ * Whether this runs at all — only when no authentication posture is on —
+ * is the composition root's decision (boot/compose.ts); the cloud and an
+ * OIDC self-host never create one.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { IdentityAccountSpecSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
+
+import { trustedLocalIdentityFor } from "../../pipeline/interceptors/auth.js";
+import { accountIdFor, localIdpIdFor } from "./constants.js";
+import type { CreateAccount } from "./provisioning.js";
+import { resolveCreateRace } from "./provisioning.js";
+import { assignDirectBackendFields } from "./steps.js";
+import type { IdentityAccountStore } from "./store.js";
+
+/** The operator as boot/config.ts loads it; empty email = the "system" placeholder. */
+export interface OperatorIdentity {
+  readonly email: string;
+  readonly displayName: string;
+}
+
+export interface OperatorAccountDeps {
+  readonly accounts: IdentityAccountStore;
+  readonly createAccount: CreateAccount;
+}
+
+/** The unconfigured laptop's operator: what the interceptor stamps as identityId. */
+const SYSTEM_OPERATOR = "system";
+
+export async function ensureOperatorAccount(
+  deps: OperatorAccountDeps,
+  operator: OperatorIdentity,
+): Promise<IdentityAccount> {
+  // The caller the interceptor would stamp for this operator; its
+  // identityId (the email, or "system") is the subject's local principal.
+  const caller = trustedLocalIdentityFor(operator);
+  const idpId = localIdpIdFor(caller.identityId);
+  const existing = await deps.accounts.findById(accountIdFor(idpId));
+  if (existing !== undefined) {
+    return existing;
+  }
+  const name =
+    operator.displayName !== ""
+      ? operator.displayName
+      : operator.email !== ""
+        ? operator.email
+        : SYSTEM_OPERATOR;
+  try {
+    return await deps.createAccount(
+      {
+        name,
+        spec: assignDirectBackendFields(
+          create(IdentityAccountSpecSchema, {
+            idpId,
+            email: operator.email,
+          }),
+        ),
+      },
+      caller,
+    );
+  } catch (error) {
+    return resolveCreateRace(error, () =>
+      deps.accounts.findById(accountIdFor(idpId)),
+    );
+  }
+}

package/src/domain/identityaccount/provisioning.ts

@@ -0,0 +1,182 @@
+/**
+ * Direct-account self-provisioning (20260911.11, Q-IA-2; the cloud's
+ * iam/account/provisioning.ts steps 1 to 3 as OSS core): the console, the
+ * CLI and the React hook call provisionMyAccount when whoAmI answers
+ * NOT_FOUND on a first sign-in, and the caller's OWN authenticated request
+ * drives provisioning synchronously — no webhook, no external trigger.
+ *
+ * The flow:
+ *   1. Idempotent early return when the subject already has an account
+ *      (a primary-key read of the derived id; no userinfo call).
+ *   2. The profile. A token-bearing caller's comes from the userinfo
+ *      endpoint of the issuer that vouched for the token, fetched with the
+ *      caller's own access token — the token goes only where it came from
+ *      (T01_1_review.md A8). One path for every issuer: `given_name` and
+ *      `family_name` as the IdP states them, where splitting a `name`
+ *      claim would be guesswork. A caller with no issuer (the trusted-local
+ *      operator) never dials out: its profile is what the CallerIdentity
+ *      carries.
+ *   3. Create through the ONE create path the domain owns — the same chain
+ *      the create RPC runs, so the tuple lifecycle fires for both — AS the
+ *      caller: the account is created by the subject it is for, and its
+ *      audit stamp says so. A lost first-login race resolves the winner by
+ *      subject whatever the failure's shape (the cloud's idempotency arm):
+ *      the primary key guarantees one row, so a failed create with a row
+ *      underneath it is a win, not an error.
+ *
+ * Step 4 of the cloud's flow (the personal organization) is not core: it
+ * fires on the `identity-account-provision:post-persist` slot in the
+ * composition (A10), wired by the controller.
+ *
+ * This module holds the domain flow over two PORTS — the store and the
+ * userinfo client — and no network code; identity/oidc-userinfo.ts is the
+ * OIDC implementation the composition root wires in.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import type { IdentityAccountSpec } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
+import { IdentityAccountSpecSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
+
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { assignDirectBackendFields } from "./steps.js";
+import type { IdentityAccountStore } from "./store.js";
+
+/** The profile an identity provider's userinfo endpoint states. */
+export interface UserProfile {
+  readonly email: string;
+  readonly firstName: string;
+  readonly lastName: string;
+  readonly pictureUrl: string;
+}
+
+/** The userinfo port: `issuer` is the one that vouched for `accessToken`. */
+export interface UserInfoClient {
+  /** Throws on any failure to obtain a profile (the handler maps UNAVAILABLE). */
+  fetchUserProfile(issuer: string, accessToken: string): Promise<UserProfile>;
+}
+
+/** Thrown when the profile cannot be fetched; the handler answers UNAVAILABLE. */
+export class UserInfoFetchError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = "UserInfoFetchError";
+  }
+}
+
+/** 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;
+}
+
+/**
+ * The domain's one create path, as its callers see it: runs the create
+ * chain AS `caller` and answers the persisted account. Built by the
+ * controller (newCreateAccountPath); the provisioner and the operator
+ * ensure call it, nothing else builds an account.
+ */
+export type CreateAccount = (
+  input: CreateAccountInput,
+  caller: CallerIdentity,
+) => Promise<IdentityAccount>;
+
+export interface DirectAccountProvisionerDeps {
+  readonly accounts: IdentityAccountStore;
+  readonly createAccount: CreateAccount;
+  readonly userInfo: UserInfoClient;
+}
+
+export interface DirectAccountProvisioner {
+  /** provisionMyAccount's domain flow; `idpId` is the caller's verified subject. */
+  provisionDirectAccount(
+    idpId: string,
+    caller: CallerIdentity,
+  ): Promise<IdentityAccount>;
+}
+
+export function newDirectAccountProvisioner(
+  deps: DirectAccountProvisionerDeps,
+): DirectAccountProvisioner {
+  return {
+    async provisionDirectAccount(idpId, caller): Promise<IdentityAccount> {
+      const existing = await deps.accounts.findDirectByIdpId(idpId);
+      if (existing !== undefined) {
+        return existing;
+      }
+
+      const profile = await profileOf(deps.userInfo, caller);
+      const input: CreateAccountInput = {
+        name: displayNameOf(caller, profile),
+        spec: assignDirectBackendFields(
+          create(IdentityAccountSpecSchema, {
+            idpId,
+            email: profile.email,
+            firstName: profile.firstName,
+            lastName: profile.lastName,
+            pictureUrl: profile.pictureUrl,
+          }),
+        ),
+      };
+
+      try {
+        return await deps.createAccount(input, caller);
+      } catch (error) {
+        return resolveCreateRace(error, () =>
+          deps.accounts.findDirectByIdpId(idpId),
+        );
+      }
+    },
+  };
+}
+
+/** Userinfo for a token-bearing caller; the identity's own claims otherwise. */
+async function profileOf(
+  userInfo: UserInfoClient,
+  caller: CallerIdentity,
+): Promise<UserProfile> {
+  if (caller.issuer === "") {
+    return {
+      email: caller.email ?? "",
+      firstName: "",
+      lastName: "",
+      pictureUrl: "",
+    };
+  }
+  try {
+    return await userInfo.fetchUserProfile(caller.issuer, caller.rawToken);
+  } catch (error) {
+    throw new UserInfoFetchError(error);
+  }
+}
+
+/**
+ * The cloud names a provisioned account by its email; the trusted-local
+ * operator, who has no userinfo, by the display name the identity
+ * carries. An empty result is the chain's to default (DefaultAccountName).
+ */
+function displayNameOf(caller: CallerIdentity, profile: UserProfile): string {
+  if (caller.issuer === "") {
+    return caller.displayName ?? profile.email;
+  }
+  return profile.email;
+}
+
+/**
+ * The concurrent-create resolution every lane uses: on a failed create,
+ * read the winner back by the lane's natural key; a winner is the answer,
+ * whatever the failure's shape (the chain's ALREADY_EXISTS, a driver's
+ * DuplicateAccountError, a transport fault after the row landed). No
+ * winner means the failure was real — it propagates untouched.
+ */
+export async function resolveCreateRace(
+  error: unknown,
+  findWinner: () => Promise<IdentityAccount | undefined>,
+): Promise<IdentityAccount> {
+  const winner = await findWinner();
+  if (winner === undefined) {
+    throw error;
+  }
+  return winner;
+}

package/src/domain/identityaccount/resolve.ts

@@ -0,0 +1,52 @@
+/**
+ * Subject → identity resolution (20260911.11; T01_0_plan.md Q-IA-2,
+ * T01_1_review.md A1 and A6): the ONE statement of "what identityId does
+ * this subject get stamped with", called by every verifier after its own
+ * credential checks pass — the OIDC lane with the token's `sub`, the
+ * API-key lane with the key's creator stamp.
+ *
+ * The rule is the cloud's direct-login posture (iam/direct/verifier.ts):
+ * one primary-key read of the DIRECT account for the subject; a hit
+ * stamps the account id, so the Authorizer, the audit actor and the
+ * tuple lifecycle see one principal shape for every provisioned user; a
+ * miss returns the subject unchanged, so an unprovisioned caller is
+ * admitted idp-shaped and exactly two RPCs mean anything to them —
+ * whoAmI (NOT_FOUND) and provisionMyAccount. No cache between the two
+ * (Q5's liveness posture): a row that appears is seen by the very next
+ * request, a row that is deleted stops resolving on the next.
+ *
+ * It lives in the domain, not in either verifier, because it is the
+ * domain's knowledge that a subject and an account are two names for one
+ * principal; a verifier only knows which string it was handed. Stated
+ * once, both lanes cannot drift, and a stamp that is already an account
+ * id needs no special case: no account carries an `ida_` as its subject,
+ * so the read is a miss and the stamp is kept.
+ *
+ * Faults: a store failure propagates as the error it is — the chassis
+ * maps a non-ConnectError to INTERNAL (pipeline/interceptors/auth.ts),
+ * so an outage never reads as a bad credential. A hit whose row carries
+ * no id is the one deliberate divergence from the cloud's inline
+ * `metadata?.id ?? ""`: a `""` principal is the silent-junk failure the
+ * oss#405 doctrine forbids, so it is a loud fault naming the subject.
+ */
+import type { IdentityAccountStore } from "./store.js";
+
+/** The one read a verifier needs from the domain: the direct account for a subject. */
+export type AccountsBySubject = Pick<IdentityAccountStore, "findDirectByIdpId">;
+
+export async function identityIdForSubject(
+  accounts: AccountsBySubject,
+  subject: string,
+): Promise<string> {
+  const account = await accounts.findDirectByIdpId(subject);
+  if (account === undefined) {
+    return subject;
+  }
+  const id = account.metadata?.id ?? "";
+  if (id === "") {
+    throw new Error(
+      `identity account for subject '${subject}' carries no id — refusing to stamp an empty principal`,
+    );
+  }
+  return id;
+}

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

@@ -0,0 +1,157 @@
+/**
+ * The open-source IdentityAccountStore: the port (store.ts) over the
+ * generic Store, rows of the `resources` table by kind (20260911.11,
+ * T01_1_review.md A1). The composition root installs it when no
+ * extension registers `drivers.identityAccountStore`.
+ *
+ * Every subject lookup is a PRIMARY-KEY read of the derived id
+ * (constants.ts accountIdFor): open source has no legacy random ids, so
+ * "the account with subject S" IS "the row with id accountIdFor(S)". That
+ * is what makes the OIDC lane's per-request resolve, whoAmI and the
+ * provisioning idempotency check O(1) reads with no secondary index and
+ * no scan, and it is why `save` refuses a direct account whose id is not
+ * its derived id — a stray row would be unreachable by subject forever.
+ * `findDirectByEmail` is the one lookup that scans (Store.findByField, a
+ * decode-and-scan of the kind's rows, T01_1_review.md finding 2): an
+ * administrative RPC, never a per-request path.
+ *
+ * `save` and `update` are both read-then-write because the generic
+ * Store's saveResource is an upsert with neither a create-only nor an
+ * update-only form. `save` refuses when the read finds a row (the port:
+ * a held id is DuplicateAccountError, never a silent overwrite); `update`
+ * returns when the read finds none (the port, A12: replace, never
+ * create — a driver whose UPDATE matches no row writes nothing, and this
+ * adapter must not differ). The residual window between the read and
+ * the write admits a same-content overwrite of the first writer's audit
+ * stamp, or a row recreated under a concurrent delete, by milliseconds —
+ * the posture every chain on the platform has today (CheckDuplicate then
+ * upsert); conditional store writes are a platform-wide follow-up, not
+ * this adapter's to invent. The primary key still guarantees ONE row per
+ * subject, which is the invariant that matters.
+ *
+ * Store faults follow the ratified mapping (domain/apikey/lookup.ts): a
+ * typed ResourceNotFoundError reads as `undefined`; anything else
+ * propagates — an outage must never read as "no account".
+ *
+ * The port's contract is proven by store-contract.ts, run over this
+ * adapter on both drivers in __tests__/resource-store.test.ts, which
+ * also pins the two invariants above that are this adapter's own.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/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 { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import { accountIdFor } from "./constants.js";
+import { DuplicateAccountError } from "./store.js";
+import type { IdentityAccountStore } from "./store.js";
+
+const KIND = ApiResourceKind.identity_account;
+
+export function newResourceIdentityAccountStore(
+  store: Store,
+): IdentityAccountStore {
+  async function readById(id: string): Promise<IdentityAccount | undefined> {
+    try {
+      return await store.getResource(KIND, id, IdentityAccountSchema);
+    } catch (error) {
+      if (error instanceof ResourceNotFoundError) {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  /** The row for a subject — undefined for the empty subject, which no account carries. */
+  async function readBySubject(
+    idpId: string,
+  ): Promise<IdentityAccount | undefined> {
+    if (idpId === "") {
+      return undefined;
+    }
+    return readById(accountIdFor(idpId));
+  }
+
+  return {
+    async save(account): Promise<void> {
+      const id = account.metadata?.id ?? "";
+      const idpId = account.spec?.idpId ?? "";
+      if (isDirect(account) && id !== accountIdFor(idpId)) {
+        throw new Error("direct account id must be derived from its idp_id");
+      }
+      if ((await readById(id)) !== undefined) {
+        throw new DuplicateAccountError(
+          `identity account '${id}' already exists`,
+        );
+      }
+      await store.saveResource(KIND, id, IdentityAccountSchema, account);
+    },
+
+    async update(account): Promise<void> {
+      const id = account.metadata?.id ?? "";
+      if ((await readById(id)) === undefined) {
+        return;
+      }
+      await store.saveResource(KIND, id, IdentityAccountSchema, account);
+    },
+
+    async deleteById(id): Promise<void> {
+      await store.deleteResource(KIND, id);
+    },
+
+    findById: readById,
+
+    findByIdpId: readBySubject,
+
+    async findDirectByIdpId(idpId): Promise<IdentityAccount | undefined> {
+      const account = await readBySubject(idpId);
+      return account !== undefined && isDirect(account) ? account : undefined;
+    },
+
+    async findDirectByEmail(email): Promise<IdentityAccount | undefined> {
+      let account: IdentityAccount;
+      try {
+        account = await store.findByField(
+          KIND,
+          "spec.email",
+          email,
+          IdentityAccountSchema,
+        );
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          return undefined;
+        }
+        throw error;
+      }
+      return isDirect(account) ? account : undefined;
+    },
+
+    async findByIds(ids): Promise<ReadonlyArray<IdentityAccount>> {
+      const found: IdentityAccount[] = [];
+      // One row per distinct id, at its first position (the port, A12):
+      // a Set iterates in insertion order, so the dedupe keeps the order.
+      for (const id of new Set(ids)) {
+        const account = await readById(id);
+        if (account !== undefined) {
+          found.push(account);
+        }
+      }
+      return found;
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+function isDirect(account: IdentityAccount): boolean {
+  return (
+    account.spec?.identityProviderRef === undefined &&
+    account.spec?.provisioningMode !== IdentityAccountProvisioningMode.federated
+  );
+}