@stigmer/server 3.24.0 → 3.26.0

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

@@ -0,0 +1,318 @@
+/**
+ * The PlatformClientStore PORT-CONTRACT KIT: every behavior an
+ * implementation of store.ts must satisfy identically, as cases a driver's
+ * test iterates. Open source runs them over its own adapter
+ * (resource-store.ts) on sqlite and Postgres in
+ * __tests__/resource-store.test.ts; a composition runs the SAME cases over
+ * the store it registers as `drivers.platformClientStore` (the cloud's
+ * `cloud.iam_platform_client` store), so "the port holds" is one statement
+ * proven per driver, never restated per repository.
+ *
+ * Shape: declarations over the port-contract runner (store/port-contract.ts),
+ * which owns the fresh fixture per case, the cleanup, and the reason the
+ * kit returns cases instead of calling vitest's `describe`. The
+ * disconnected-store case matters most here: the verifier reads this port
+ * on every request a minted token bears, so an outage that read as "no
+ * client" would revoke every live token instead of failing loudly.
+ *
+ * The duplicate arms check `instanceof DuplicatePlatformClientError` on the
+ * exported class, because that is how the create chain's Persist step
+ * catches it: a driver throwing a lookalike fails here for the reason it
+ * would fail a create.
+ *
+ * Case names are the contract lines, in the port's words. The OSS test pins
+ * the full list, so a case cannot drop out of the kit unnoticed.
+ */
+import assert from "node:assert/strict";
+
+import { create, equals } from "@bufbuild/protobuf";
+
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+
+import { portContractCases } from "../../store/port-contract.js";
+import type {
+  PortContractCase,
+  PortContractDeclaration,
+  PortContractFixture,
+} from "../../store/port-contract.js";
+import { DuplicatePlatformClientError } from "./store.js";
+import type { PlatformClientStore } from "./store.js";
+
+/** The runner's fixture over this port — the name a driver's test and the barrel know it by. */
+export type PlatformClientStoreContractFixture =
+  PortContractFixture<PlatformClientStore>;
+
+export type PlatformClientStoreContractCase = PortContractCase;
+
+/** A client as the domain writes it; each fixture names its own id, org, slug and client_id. */
+function platformClient(fields: {
+  id: string;
+  org: string;
+  slug: string;
+  clientId: string;
+  allowedOrigins?: string[];
+}): PlatformClient {
+  return create(PlatformClientSchema, {
+    apiVersion: "iam.stigmer.ai/v1",
+    kind: "PlatformClient",
+    metadata: {
+      id: fields.id,
+      name: fields.slug,
+      slug: fields.slug,
+      org: fields.org,
+    },
+    spec: {
+      clientId: fields.clientId,
+      clientSecretHash: `hash-of-${fields.clientId}`,
+      secretFingerprint: "abcdef",
+      autoProvisionAccounts: true,
+      allowedOrigins: fields.allowedOrigins ?? [],
+    },
+  });
+}
+
+function assertSameClient(
+  actual: PlatformClient | undefined,
+  expected: PlatformClient,
+  message: string,
+): void {
+  assert.ok(actual !== undefined, `${message}: no client was answered`);
+  assert.ok(equals(PlatformClientSchema, actual, expected), message);
+}
+
+async function assertDuplicate(
+  write: Promise<void>,
+  message: string,
+): Promise<void> {
+  await assert.rejects(
+    write,
+    (error: unknown) => error instanceof DuplicatePlatformClientError,
+    message,
+  );
+}
+
+const ACME_DASHBOARD = platformClient({
+  id: "pcl_contract_acme_dashboard",
+  org: "acme",
+  slug: "dashboard",
+  clientId: "stgm_cid_contract_acme_dashboard",
+});
+
+const CASES: ReadonlyArray<PortContractDeclaration<PlatformClientStore>> = [
+  [
+    "save then findById, findByClientId and findByOrgAndSlug answer the saved client",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      assertSameClient(
+        await store.findById("pcl_contract_acme_dashboard"),
+        ACME_DASHBOARD,
+        "findById must answer the saved row",
+      );
+      assertSameClient(
+        await store.findByClientId("stgm_cid_contract_acme_dashboard"),
+        ACME_DASHBOARD,
+        "findByClientId must answer the saved row",
+      );
+      assertSameClient(
+        await store.findByOrgAndSlug("acme", "dashboard"),
+        ACME_DASHBOARD,
+        "findByOrgAndSlug must answer the saved row",
+      );
+    },
+  ],
+  [
+    "lookups of a client that is not held answer undefined",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      assert.equal(await store.findById("pcl_contract_nobody"), undefined);
+      assert.equal(
+        await store.findByClientId("stgm_cid_contract_nobody"),
+        undefined,
+      );
+      assert.equal(await store.findByOrgAndSlug("acme", "nobody"), undefined);
+      assert.equal(
+        await store.findByOrgAndSlug("globex", "dashboard"),
+        undefined,
+        "a slug is scoped to its organization: another org's lookup must miss",
+      );
+    },
+  ],
+  [
+    "save under a held id raises DuplicatePlatformClientError",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      await assertDuplicate(
+        store.save(
+          platformClient({
+            id: "pcl_contract_acme_dashboard",
+            org: "acme",
+            slug: "other",
+            clientId: "stgm_cid_contract_other",
+          }),
+        ),
+        "a held id must be refused, never overwritten",
+      );
+    },
+  ],
+  [
+    "save under a held (org, slug) raises DuplicatePlatformClientError",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      await assertDuplicate(
+        store.save(
+          platformClient({
+            id: "pcl_contract_acme_second",
+            org: "acme",
+            slug: "dashboard",
+            clientId: "stgm_cid_contract_acme_second",
+          }),
+        ),
+        "a held (org, slug) must be refused",
+      );
+    },
+  ],
+  [
+    "save under a held client_id raises DuplicatePlatformClientError",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      await assertDuplicate(
+        store.save(
+          platformClient({
+            id: "pcl_contract_acme_third",
+            org: "acme",
+            slug: "third",
+            clientId: "stgm_cid_contract_acme_dashboard",
+          }),
+        ),
+        "a held client_id must be refused: the mint resolves a client by it",
+      );
+    },
+  ],
+  [
+    "the same slug in another organization is a different client",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      const globex = platformClient({
+        id: "pcl_contract_globex_dashboard",
+        org: "globex",
+        slug: "dashboard",
+        clientId: "stgm_cid_contract_globex_dashboard",
+      });
+      await store.save(globex);
+      assertSameClient(
+        await store.findByOrgAndSlug("globex", "dashboard"),
+        globex,
+        "each organization answers its own client for the shared slug",
+      );
+    },
+  ],
+  [
+    "update replaces the row in place",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      const edited = platformClient({
+        id: "pcl_contract_acme_dashboard",
+        org: "acme",
+        slug: "dashboard",
+        clientId: "stgm_cid_contract_acme_dashboard",
+        allowedOrigins: ["https://app.acme.example"],
+      });
+      await store.update(edited);
+      assertSameClient(
+        await store.findById("pcl_contract_acme_dashboard"),
+        edited,
+        "findById must answer the replaced row",
+      );
+      assertSameClient(
+        await store.findByClientId("stgm_cid_contract_acme_dashboard"),
+        edited,
+        "findByClientId must answer the replaced row",
+      );
+    },
+  ],
+  [
+    "update of an unknown id writes nothing",
+    async ({ store }) => {
+      await store.update(ACME_DASHBOARD);
+      assert.equal(
+        await store.findById("pcl_contract_acme_dashboard"),
+        undefined,
+        "update must replace, never create",
+      );
+    },
+  ],
+  [
+    "deleteById frees the id, the client_id and the slug; deleting an unknown id resolves",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      await store.deleteById("pcl_contract_acme_dashboard");
+      assert.equal(
+        await store.findById("pcl_contract_acme_dashboard"),
+        undefined,
+      );
+      assert.equal(
+        await store.findByClientId("stgm_cid_contract_acme_dashboard"),
+        undefined,
+        "a deleted client's client_id must stop resolving: the mint and the verifier read it",
+      );
+      assert.equal(
+        await store.findByOrgAndSlug("acme", "dashboard"),
+        undefined,
+      );
+      await store.save(ACME_DASHBOARD);
+      await store.deleteById("pcl_contract_nobody");
+    },
+  ],
+  [
+    "findByOrg answers every client of the organization and no other",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      await store.save(
+        platformClient({
+          id: "pcl_contract_acme_mobile",
+          org: "acme",
+          slug: "mobile",
+          clientId: "stgm_cid_contract_acme_mobile",
+        }),
+      );
+      await store.save(
+        platformClient({
+          id: "pcl_contract_globex_dashboard",
+          org: "globex",
+          slug: "dashboard",
+          clientId: "stgm_cid_contract_globex_dashboard",
+        }),
+      );
+      const ids = (await store.findByOrg("acme"))
+        .map((client) => client.metadata?.id ?? "")
+        .sort();
+      assert.deepEqual(ids, [
+        "pcl_contract_acme_dashboard",
+        "pcl_contract_acme_mobile",
+      ]);
+      assert.deepEqual(await store.findByOrg("initech"), []);
+    },
+  ],
+  [
+    "a disconnected store is an infrastructure fault, never 'not found'",
+    async (fixture) => {
+      await fixture.disconnect();
+      await assert.rejects(
+        fixture.store.findById("pcl_contract_acme_dashboard"),
+        "an id read on a disconnected store must reject: on the verifier's path 'not found' revokes every token",
+      );
+      await assert.rejects(
+        fixture.store.findByClientId("stgm_cid_contract_acme_dashboard"),
+        "a client_id read on a disconnected store must reject, never read as undefined",
+      );
+    },
+  ],
+];
+
+/** The port's cases over `makeFixture`, one fresh fixture per case. */
+export function platformClientStoreContract(
+  makeFixture: () => Promise<PlatformClientStoreContractFixture>,
+): ReadonlyArray<PlatformClientStoreContractCase> {
+  return portContractCases(CASES, makeFixture);
+}

package/src/domain/platformclient/store.ts

@@ -0,0 +1,63 @@
+/**
+ * The PlatformClientStore PORT: the storage contract the platform-client
+ * domain writes and reads through, so the cloud serves the same chains
+ * over its own `cloud.iam_platform_client` table by registering an
+ * implementation as `drivers.platformClientStore` (the identity-account
+ * and IamPolicy precedent: a port for an IAM kind whose rows an edition
+ * keeps in its own table). Open source's implementation is
+ * resource-store.ts over the generic Store.
+ *
+ * The methods are exactly the lookups the domain asks: by id (every
+ * chain, and the verifier's liveness read), by client_id (the mint), by
+ * org-scoped slug (getByReference, update addressed by slug, the
+ * duplicate check), by organization (listByOrg). A port carries nothing
+ * only one edition calls.
+ *
+ * Contract every implementation must satisfy — proven by the port-contract
+ * kit (store-contract.ts, exported), which the OSS adapter's test iterates
+ * on both drivers and a composition's driver test iterates too:
+ *   - `save` is create-only in effect: a held id, a held (org, slug) or a
+ *     held client_id raises DuplicatePlatformClientError, never a silent
+ *     overwrite;
+ *   - `update` replaces by id and never creates: an unknown id writes
+ *     nothing;
+ *   - `deleteById` of an unknown id resolves;
+ *   - `findByOrg` answers every client of the organization and no other,
+ *     in no promised order (the chain sorts);
+ *   - a typed not-found reads as `undefined`; any other storage failure
+ *     propagates as the infrastructure fault it is (the ratified
+ *     store-fault mapping — an outage must never read as "no client", which
+ *     on the verifier's path would revoke every live token).
+ */
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+
+/**
+ * Raised by `save` when the id, the (org, slug) pair or the client_id is
+ * already held, so the create chain answers ALREADY_EXISTS. `cause`
+ * carries a driver's own error (the cloud's SQLSTATE 23505) for the logs;
+ * the message is the port's.
+ */
+export class DuplicatePlatformClientError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "DuplicatePlatformClientError";
+  }
+}
+
+export interface PlatformClientStore {
+  /** Insert; a held id, (org, slug) or client_id raises DuplicatePlatformClientError. */
+  save(client: PlatformClient): Promise<void>;
+  /** Full-row replace by id; an unknown id writes nothing. */
+  update(client: PlatformClient): Promise<void>;
+  /** Removes the row; no error when it does not exist. */
+  deleteById(id: string): Promise<void>;
+  findById(id: string): Promise<PlatformClient | undefined>;
+  /** The client holding this public identifier — the mint's lookup. */
+  findByClientId(clientId: string): Promise<PlatformClient | undefined>;
+  findByOrgAndSlug(
+    org: string,
+    slug: string,
+  ): Promise<PlatformClient | undefined>;
+  /** Every client of the organization, in no promised order. */
+  findByOrg(org: string): Promise<ReadonlyArray<PlatformClient>>;
+}

package/src/domain/platformclient/system-managed.ts

@@ -0,0 +1,115 @@
+/**
+ * The one builder of a system-managed PlatformClient: the row an edition
+ * creates for itself, never through the create chain, so the tokens it
+ * signs on the platform's own behalf (a guest's, a schedule fire's) name a
+ * client that exists. Stigmer Cloud keeps one per organization under
+ * SYSTEM_SHARE_CLIENT_SLUG and persists it through its store driver.
+ *
+ * The domain already owns what such a client is — the create chain refuses
+ * its reserved slug (RefuseReservedSlug) and every mutation refuses its
+ * label (RefuseSystemManaged) — so the row is built here too, and the
+ * rules that make it safe hold by construction:
+ *   - it lives only under a reserved slug, which no user can create, so a
+ *     user client can never be mistaken for one;
+ *   - it carries the reserved `stigmer.ai/system-managed` label, so update,
+ *     delete and rotate refuse it;
+ *   - its credentials are real (a `client_id` unique like any other, a
+ *     hash, a fingerprint), but the secret is discarded here: nobody ever
+ *     authenticates as the platform's own client;
+ *   - its id is spelled like every other (`pcl_` + ULID, generateId);
+ *   - its audit names no actor, because no caller made it: the platform did.
+ *
+ * Who decides when one exists, and where it is stored, is the edition's:
+ * this function writes nothing. It writes no authorization tuples either —
+ * nothing authorizes against a system-managed client, and with none it
+ * stays out of every list and reference read a person makes.
+ */
+import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  ApiResourceAuditInfoSchema,
+  ApiResourceAuditSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+
+import {
+  RESERVED_LABEL_TRUE,
+  SYSTEM_MANAGED_LABEL,
+} from "../../pipeline/apiresource-labels.js";
+import {
+  defaultVisibilityFor,
+  getIdPrefix,
+} from "../../pipeline/apiresource-meta.js";
+import { generateId } from "../../pipeline/steps/defaults.js";
+import {
+  PLATFORM_CLIENT_KIND_NAME,
+  RESERVED_PLATFORM_CLIENT_SLUGS,
+} from "./constants.js";
+import {
+  generateClientId,
+  generateClientSecret,
+  hashClientSecret,
+  secretFingerprint,
+} from "./credentials.js";
+
+export interface SystemManagedPlatformClientInput {
+  /** The owning organization. */
+  readonly org: string;
+  /** A reserved slug (RESERVED_PLATFORM_CLIENT_SLUGS); anything else throws. */
+  readonly slug: string;
+  /** The display name a console would show. */
+  readonly name: string;
+  /** The creation instant stamped on both audit slots; defaults to the wall clock. */
+  readonly now?: Date;
+}
+
+/**
+ * A new system-managed client, ready for a store's `save`. Throws on an
+ * empty organization or a slug that is not reserved — an edition's
+ * programming error, never a request's.
+ */
+export function newSystemManagedPlatformClient(
+  input: SystemManagedPlatformClientInput,
+): PlatformClient {
+  if (input.org === "") {
+    throw new Error("a system-managed platform client needs an organization");
+  }
+  if (!RESERVED_PLATFORM_CLIENT_SLUGS.has(input.slug)) {
+    throw new Error(
+      `'${input.slug}' is not a reserved platform-client slug; a system-managed client lives only under one (${[...RESERVED_PLATFORM_CLIENT_SLUGS].join(", ")})`,
+    );
+  }
+  const secret = generateClientSecret();
+  const created = timestampFromDate(input.now ?? new Date());
+  const audit = create(ApiResourceAuditInfoSchema, {
+    createdAt: created,
+    updatedAt: created,
+    event: "created",
+  });
+  return create(PlatformClientSchema, {
+    apiVersion: "iam.stigmer.ai/v1",
+    kind: PLATFORM_CLIENT_KIND_NAME,
+    metadata: {
+      id: generateId(getIdPrefix(ApiResourceKind.platform_client)),
+      org: input.org,
+      name: input.name,
+      slug: input.slug,
+      labels: { [SYSTEM_MANAGED_LABEL]: RESERVED_LABEL_TRUE },
+      visibility: defaultVisibilityFor(ApiResourceKind.platform_client),
+    },
+    spec: {
+      clientId: generateClientId(),
+      clientSecretHash: hashClientSecret(secret),
+      secretFingerprint: secretFingerprint(secret),
+    },
+    status: {
+      audit: create(ApiResourceAuditSchema, {
+        specAudit: audit,
+        statusAudit: audit,
+      }),
+    },
+  });
+}

package/src/domain/platformclient/token-controller.ts

@@ -0,0 +1,49 @@
+/**
+ * PlatformClientTokenController — the two public token RPCs, registered in
+ * every composition so the service has one owner (the routes stage refuses
+ * an extension that registers it again, boot/route-shadowing.ts):
+ *
+ *   - mintUserToken: the PlatformClient mint (mint.ts). Public on the wire
+ *     — the client authenticates with its credentials in the body, not a
+ *     bearer token — so there is no annotation to evaluate; the mint never
+ *     reads the chain's caller.
+ *   - mintGuestToken: the credential-free mint for anonymous visitors of a
+ *     shared agent's hosted page, dispatched to the composed guest-token
+ *     capability (extensions/guest-token-minting.ts). Without one — open
+ *     source hosts no shared-agent pages — it answers UNIMPLEMENTED with
+ *     the edition sentence, the identityFederation absent shape.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { ConnectRouter } from "@connectrpc/connect";
+
+import { PlatformClientTokenController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+
+import type { GuestTokenMinting } from "../../extensions/guest-token-minting.js";
+import { GUEST_MINT_UNIMPLEMENTED_MESSAGE } from "./constants.js";
+import { mintUserToken } from "./mint.js";
+import type { PlatformClientMintDeps } from "./mint.js";
+
+export interface PlatformClientTokenControllerDeps {
+  readonly mint: PlatformClientMintDeps;
+  /** The composed capability; undefined = mintGuestToken refuses UNIMPLEMENTED. */
+  readonly guestTokenMinting: GuestTokenMinting | undefined;
+}
+
+/** Registers the token service on the router (routes stage). */
+export function registerPlatformClientTokenService(
+  router: ConnectRouter,
+  deps: PlatformClientTokenControllerDeps,
+): void {
+  router.service(PlatformClientTokenController, {
+    mintUserToken: (request) => mintUserToken(deps.mint, request),
+    mintGuestToken: (request, ctx) => {
+      if (deps.guestTokenMinting === undefined) {
+        throw new ConnectError(
+          GUEST_MINT_UNIMPLEMENTED_MESSAGE,
+          Code.Unimplemented,
+        );
+      }
+      return deps.guestTokenMinting.mintGuestToken(request, ctx.requestHeader);
+    },
+  });
+}

package/src/domain/platformclient/verifier.ts

@@ -0,0 +1,106 @@
+/**
+ * The PlatformClient user-token verifier: open source's one platform-token
+ * lane. It claims a token with `iss: "stigmer"` and NO `token_type` — the
+ * user token the mint signs — and passes every other token on:
+ *   - a token that is not a platform token is another verifier's (the
+ *     OIDC verifier's, an API key's);
+ *   - a typed platform token (guest, schedule, channel, the sandbox
+ *     family) belongs to the edition that mints it; open source verifies
+ *     only its own vocabulary, and on a server with no verifier for that
+ *     lane the chain refuses it as unclaimed.
+ * A platform token whose signature, expiry, audience or subject fails is
+ * refused here with the envelope's pinned copy, whichever lane it names —
+ * the refusal the cloud's verifier has always answered for it.
+ *
+ * Liveness is the verifier's (not a guard's), so every lane that
+ * authenticates — the serving chain and the extension HTTP edges that run
+ * the verifier chain without guards — refuses a deleted client's tokens on
+ * the next request, with the cloud's copy. A store fault propagates as the
+ * infrastructure fault it is, never as a revocation.
+ *
+ * Composed between `apikey` and `oidc`, only under an authentication
+ * posture (compose.ts): the OIDC verifier claims every JWT-shaped token and
+ * throws on one it cannot verify, so a platform token must be claimed
+ * before it gets there (stigmer#1137's lesson).
+ *
+ * The identity is the account the token was minted for: `sub` IS the
+ * account id (the mint signs it), so no account read is needed; class
+ * `user`, issuer "stigmer", the token carried (the memory-capture gate and
+ * the origin guard read its `platform_client_id`), and the email and name
+ * the platform asserted, for display only.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import type {
+  CallerIdentity,
+  IdentityVerifier,
+} from "../../extensions/identity.js";
+import {
+  PLATFORM_TOKEN_ISSUER,
+  platformTokenRefusalError,
+  stringClaim,
+  verifyPlatformToken,
+} from "../../platformtoken/envelope.js";
+import type { PlatformTokenKeyRing } from "../../platformtoken/key-ring.js";
+import {
+  DELETED_CLIENT_MESSAGE,
+  TOKEN_NAMES_NO_CLIENT_MESSAGE,
+  USER_TOKEN_CLAIMS,
+} from "./constants.js";
+import type { PlatformClientStore } from "./store.js";
+
+export interface PlatformClientTokenVerifierDeps {
+  readonly keys: PlatformTokenKeyRing;
+  readonly clients: Pick<PlatformClientStore, "findById">;
+  readonly now?: () => Date;
+}
+
+export function newPlatformClientTokenVerifier(
+  deps: PlatformClientTokenVerifierDeps,
+): IdentityVerifier {
+  return {
+    name: "platform-client",
+    async verify(token: string): Promise<CallerIdentity | null> {
+      const result = verifyPlatformToken(deps.keys, token, deps.now?.());
+      switch (result.outcome) {
+        case "foreign":
+          return null;
+        case "refused":
+          throw platformTokenRefusalError(result.refusal);
+        case "verified":
+          break;
+        default: {
+          const exhaustive: never = result;
+          throw new Error(`unknown verification ${JSON.stringify(exhaustive)}`);
+        }
+      }
+      const verified = result.token;
+      if (verified.tokenType !== undefined) {
+        return null;
+      }
+      const platformClientId = stringClaim(
+        verified.payload,
+        USER_TOKEN_CLAIMS.platformClientId,
+      );
+      if (platformClientId === undefined) {
+        throw new ConnectError(
+          TOKEN_NAMES_NO_CLIENT_MESSAGE,
+          Code.Unauthenticated,
+        );
+      }
+      if ((await deps.clients.findById(platformClientId)) === undefined) {
+        throw new ConnectError(DELETED_CLIENT_MESSAGE, Code.Unauthenticated);
+      }
+      const email = stringClaim(verified.payload, USER_TOKEN_CLAIMS.email);
+      const displayName = stringClaim(verified.payload, USER_TOKEN_CLAIMS.name);
+      return {
+        identityId: verified.subject,
+        callerClass: "user",
+        issuer: PLATFORM_TOKEN_ISSUER,
+        rawToken: token,
+        ...(email !== undefined ? { email } : {}),
+        ...(displayName !== undefined ? { displayName } : {}),
+      };
+    },
+  };
+}

package/src/domain/session/list-index.ts

@@ -0,0 +1,28 @@
+/**
+ * The session list index (store/list-index.ts): `agent_instance` is the
+ * key `listByAgentInstance` reads, `channel` the one `listByChannel` reads
+ * (the channel's id is stamped as a label by the channel lanes, not held
+ * in the spec). A session belongs to one organization, which is every
+ * declaration's first fact, so `session.list` narrows by it when the
+ * request names one.
+ *
+ * A change to `keys` bumps `revision` (boot/__tests__/list-indexes.test.ts
+ * pins the pair).
+ */
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { declareListIndex, field, label } from "../../store/list-index.js";
+
+/** The label the channel lanes stamp on every session they open. */
+export const SESSION_CHANNEL_ID_LABEL = "stigmer.ai/channel-id";
+
+export const sessionListIndex = declareListIndex({
+  kind: ApiResourceKind.session,
+  schema: SessionSchema,
+  revision: 1,
+  keys: {
+    agent_instance: field("spec.agent_instance_id"),
+    channel: label(SESSION_CHANNEL_ID_LABEL),
+  },
+});