@stigmer/server 3.14.1 → 3.15.1

package/src/identity/oidc-verifier.ts

@@ -18,27 +18,43 @@
  *   - everything else → "invalid token"
  *
  * Discovery and key handling: the issuer's /.well-known/openid-configuration
- * is fetched once (memoized on success, retried on the next request after
- * a failure — a flaky IdP at boot must not permanently brick the lane),
- * its `issuer` field must match the configured issuer exactly (RFC 8414
- * §3.3), and the JWKS rides jose's createRemoteJWKSet (cached, rotation-
- * aware). Discovery/JWKS OUTAGES are infrastructure faults — thrown as
+ * is read through the shared oidc-discovery module the composition root
+ * builds once for every lane (20260911.11 A8 — the userinfo client reads
+ * the same document, so one issuer is discovered once and validated the
+ * same way wherever it is consumed: `issuer` must match exactly, RFC 8414
+ * §3.3; `jwks_uri` required). The module memoizes on success only, so a
+ * flaky IdP at boot never permanently bricks the lane. The JWKS client
+ * (jose's createRemoteJWKSet — cached, rotation-aware) is built ONCE per
+ * verifier from the discovered location and kept: discovery hands back a
+ * URI, and a client rebuilt per request would refetch the keys per
+ * request. Discovery/JWKS OUTAGES are infrastructure faults — thrown as
  * plain errors so the chassis maps them to INTERNAL, never a credential
  * rejection (the DD-007 unavailable doctrine).
  *
- * Identity: identityId = `sub` (rejected as invalid when absent), issuer =
- * the configured issuer, email/displayName from the standard `email`/`name`
- * claims when present (the DD-007 Q5 addendum added the fields for exactly
- * these claims).
+ * Identity (20260911.11 Q-IA-2, A1 — the cloud's direct-login posture):
+ * after the token verifies, `sub` (rejected as invalid when absent) is
+ * resolved through the identity-account domain (identityIdForSubject):
+ * a subject with a direct account stamps the ACCOUNT id; a subject
+ * without one is admitted idp-shaped (identityId = sub) so whoAmI can
+ * answer NOT_FOUND and provisionMyAccount can run. One primary-key read
+ * per request, no cache; a store fault is an infrastructure fault. The
+ * issuer is the configured issuer; email/displayName come from the
+ * standard `email`/`name` claims when present (the DD-007 Q5 addendum
+ * added the fields for exactly these claims), whichever way the subject
+ * resolved. Claim-or-pass runs before any of this: a non-JWT token
+ * passes with no network.
  */
 import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
 import type { JWTPayload } from "jose";
 import { Code, ConnectError } from "@connectrpc/connect";
 
+import { identityIdForSubject } from "../domain/identityaccount/resolve.js";
+import type { AccountsBySubject } from "../domain/identityaccount/resolve.js";
 import type {
   CallerIdentity,
   IdentityVerifier,
 } from "../extensions/identity.js";
+import type { IssuerDiscovery } from "./oidc-discovery.js";
 
 /** Java classifyAuthError arms — byte-pinned cross-edition copy. */
 export const TOKEN_EXPIRED_MESSAGE = "token has expired";
@@ -52,42 +68,28 @@ export interface OidcVerifierConfig {
   readonly issuer: string;
   /** The audience access tokens must carry. */
   readonly audience: string;
+  /** The identity-account domain's subject lookup — REQUIRED: what identityId means depends on it. */
+  readonly accounts: AccountsBySubject;
+  /** The composition root's one discovery for every lane (A8). */
+  readonly discovery: IssuerDiscovery;
 }
 
-interface DiscoveredIssuer {
-  readonly jwks: ReturnType<typeof createRemoteJWKSet>;
-}
+type RemoteJwks = ReturnType<typeof createRemoteJWKSet>;
 
 export function newOidcIdentityVerifier(
   config: OidcVerifierConfig,
 ): IdentityVerifier {
-  let discovered: DiscoveredIssuer | undefined;
+  // Set on the first successful discovery only: a failed discovery leaves
+  // it unset so the next request retries (the module caches no failure).
+  let jwks: RemoteJwks | undefined;
 
-  async function discover(): Promise<DiscoveredIssuer> {
-    if (discovered !== undefined) {
-      return discovered;
-    }
-    const url = discoveryUrl(config.issuer);
-    const response = await fetch(url);
-    if (!response.ok) {
-      throw new Error(
-        `OIDC discovery failed: ${url} answered HTTP ${response.status}`,
-      );
-    }
-    const document = (await response.json()) as {
-      issuer?: string;
-      jwks_uri?: string;
-    };
-    if (document.issuer !== config.issuer) {
-      throw new Error(
-        `OIDC discovery failed: document issuer '${document.issuer ?? ""}' does not match configured issuer '${config.issuer}'`,
-      );
+  async function jwksFor(): Promise<RemoteJwks> {
+    if (jwks !== undefined) {
+      return jwks;
     }
-    if (typeof document.jwks_uri !== "string" || document.jwks_uri === "") {
-      throw new Error(`OIDC discovery failed: ${url} carries no jwks_uri`);
-    }
-    discovered = { jwks: createRemoteJWKSet(new URL(document.jwks_uri)) };
-    return discovered;
+    const { jwksUri } = await config.discovery.discover(config.issuer);
+    jwks = createRemoteJWKSet(new URL(jwksUri));
+    return jwks;
   }
 
   return {
@@ -96,10 +98,10 @@ export function newOidcIdentityVerifier(
       if (!isJwtShaped(token)) {
         return null;
       }
-      const issuer = await discover();
+      const keys = await jwksFor();
       let payload: JWTPayload;
       try {
-        ({ payload } = await jwtVerify(token, issuer.jwks, {
+        ({ payload } = await jwtVerify(token, keys, {
           issuer: config.issuer,
           audience: config.audience,
         }));
@@ -110,7 +112,7 @@ export function newOidcIdentityVerifier(
         throw new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
       }
       return {
-        identityId: payload.sub,
+        identityId: await identityIdForSubject(config.accounts, payload.sub),
         callerClass: "user",
         issuer: config.issuer,
         rawToken: token,
@@ -125,11 +127,6 @@ export function newOidcIdentityVerifier(
   };
 }
 
-/** issuer + /.well-known/openid-configuration (trailing-slash tolerant). */
-function discoveryUrl(issuer: string): string {
-  return `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
-}
-
 /** Three non-empty dot-separated segments — the JWS compact shape. */
 function isJwtShaped(token: string): boolean {
   const segments = token.split(".");

package/src/index.ts

@@ -109,6 +109,25 @@ export type {
 } from "./extensions/resource-authorization.js";
 export type { OrganizationDirectory } from "./extensions/organization-directory.js";
 export { ALL_ORGANIZATIONS } from "./extensions/organization-directory.js";
+// The 20260911.11 identity-account seams (Q-IA-9): the store PORT a
+// composition drives the domain through (drivers.identityAccountStore;
+// a driver throws DuplicateAccountError for a held id), the federation
+// capability (drivers.identityFederation), and the ONE subject →
+// identityId rule both OSS verifiers already apply, exported so a
+// composition's own verifier converges on it instead of restating it.
+export type { IdentityAccountStore } from "./domain/identityaccount/store.js";
+export { DuplicateAccountError } from "./domain/identityaccount/store.js";
+// The port's contract as a vitest-free kit: a driver's own test iterates
+// the same cases the OSS adapter passes, so the port is proven per
+// driver, never restated per repository.
+export type {
+  IdentityAccountStoreContractCase,
+  IdentityAccountStoreContractFixture,
+} from "./domain/identityaccount/store-contract.js";
+export { identityAccountStoreContract } from "./domain/identityaccount/store-contract.js";
+export type { IdentityFederation } from "./extensions/identity-federation.js";
+export type { AccountsBySubject } from "./domain/identityaccount/resolve.js";
+export { identityIdForSubject } from "./domain/identityaccount/resolve.js";
 export type {
   ListReadScope,
   ListEntryMeta,

package/src/pipeline/interceptors/auth.ts

@@ -172,7 +172,19 @@ export function callerIdentityOf(ctx: HandlerContext): CallerIdentity {
  * operator seam remains process-global.
  */
 export function trustedLocalIdentity(): CallerIdentity {
-  const operator = operatorIdentitySnapshot();
+  return trustedLocalIdentityFor(operatorIdentitySnapshot());
+}
+
+/**
+ * The trusted-local identity for a given operator — the one construction
+ * of that principal, shared by the per-request stamp above and by the
+ * boot-time operator account (domain/identityaccount/operator.ts), so the
+ * row the server ensures and the caller it stamps can never disagree.
+ */
+export function trustedLocalIdentityFor(operator: {
+  readonly email: string;
+  readonly displayName: string;
+}): CallerIdentity {
   if (operator.email === "") {
     return {
       identityId: "system",

package/src/pipeline/steps/__tests__/authorize-annotation-completeness.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The annotation-completeness invariant for the Authorize step (stigmer#1073;
+ * found on the 20260911.11 cloud readout, 2026-09-13): an `rpc.config`
+ * annotation that names a resource KIND must also name where the resource
+ * ID comes from (`field_path` or `resource_id`). A kind without an id is a
+ * check against `<kind>:` with an empty id — the step resolves it to "" by
+ * doctrine (resolution never throws, see authorize.ts) and an enforcing
+ * authorizer refuses it for EVERY caller, while the open-source permissive
+ * default allows it, so no `local*` conformance target can see the gap.
+ * `getActorInfo` shipped that way: green on every OSS gate, denied on the
+ * cloud composition the moment the annotation-driven step replaced the
+ * cloud's hand-written handler (which had passed `id.value` by hand).
+ *
+ * Scope is every method the open-source server SERVES — the empty
+ * composition's `routes` replayed into a recording router, the
+ * tier-truthfulness precedent — because that is exactly the set the OSS
+ * Authorize step governs; a composition's own services are its own
+ * `direct-handler-authorization` conformance suite's business. Two arms are
+ * exempt by construction: `is_public` and `is_skip_authorization` methods
+ * never reach the annotation's resolution (the skip lanes resolve their
+ * target in the handler through `authorizeDirect`'s override). A config
+ * that names NO kind (static or by path) is outside this invariant: the
+ * check is then about the kind, not the id, and today no OSS-served method
+ * is shaped that way (the IamPolicy RPCs that are belong to
+ * `sp.oss-organization-roles`).
+ *
+ * The mutation arms prove the check bites over the same function.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { getOption, hasOption } from "@bufbuild/protobuf";
+import type { DescService } from "@bufbuild/protobuf";
+import type { ConnectRouter } from "@connectrpc/connect";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  config as rpcAuthorizationConfig,
+  is_public,
+  is_skip_authorization,
+} from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
+
+import { loadConfig } from "../../../boot/config.js";
+import { composeServer } from "../../../boot/compose.js";
+import type { ComposedServer } from "../../../boot/compose.js";
+import { createLogger } from "../../../boot/logger.js";
+
+/** One annotated method as the invariant reads it. */
+interface AnnotationTarget {
+  readonly method: string;
+  readonly namesKind: boolean;
+  readonly namesId: boolean;
+  readonly skipsResolution: boolean;
+}
+
+/** Replays the composed routes into a recorder and returns the served services. */
+function servedServices(
+  routes: (router: ConnectRouter) => void,
+): DescService[] {
+  const served: DescService[] = [];
+  const recorder = {
+    handlers: [],
+    service(desc: DescService) {
+      served.push(desc);
+      return recorder;
+    },
+    rpc() {
+      return recorder;
+    },
+  };
+  routes(recorder as unknown as ConnectRouter);
+  return served;
+}
+
+/** Every `rpc.config`-annotated method of the given services, read once. */
+function annotationTargets(services: DescService[]): AnnotationTarget[] {
+  const targets: AnnotationTarget[] = [];
+  for (const service of services) {
+    for (const method of service.methods) {
+      if (!hasOption(method, rpcAuthorizationConfig)) continue;
+      const config = getOption(method, rpcAuthorizationConfig);
+      targets.push({
+        method: `${service.typeName}/${method.name}`,
+        namesKind:
+          config.resourceKind !== ApiResourceKind.api_resource_kind_unknown ||
+          config.resourceKindPath !== "",
+        namesId: config.fieldPath !== "" || config.resourceId !== "",
+        skipsResolution:
+          getOption(method, is_public) ||
+          getOption(method, is_skip_authorization),
+      });
+    }
+  }
+  return targets;
+}
+
+/** The methods whose annotation names a kind but no id, one sentence each. */
+function unresolvableTargets(targets: AnnotationTarget[]): string[] {
+  return targets
+    .filter((t) => !t.skipsResolution && t.namesKind && !t.namesId)
+    .map(
+      (t) =>
+        `${t.method} names a resource kind but neither field_path nor resource_id — the Authorize step would check an empty id`,
+    );
+}
+
+describe("authorization annotations name where the resource id comes from", () => {
+  let dir: string;
+  let server: ComposedServer;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "authorize-annotations-test-"));
+    server = await composeServer({
+      config: loadConfig({
+        STIGMER_MODEL_REGISTRY_REFRESH: "off",
+        TEMPORAL_HOST_PORT: "127.0.0.1:1",
+        DB_PATH: path.join(dir, "stigmer.db"),
+        STORAGE_PATH: path.join(dir, "storage"),
+        ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+      }),
+      logger: createLogger({ level: "error", pretty: false, write: () => {} }),
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("every served method that names a kind also names its id (field_path or resource_id)", () => {
+    const targets = annotationTargets(servedServices(server.routes));
+    expect(targets.length).toBeGreaterThan(100);
+    expect(unresolvableTargets(targets)).toEqual([]);
+  });
+
+  it("getActorInfo is annotated exactly like get — the arm stigmer#1073 was missing", () => {
+    const targets = annotationTargets(servedServices(server.routes));
+    const byName = new Map(targets.map((t) => [t.method, t]));
+    const get = byName.get(
+      "ai.stigmer.iam.identityaccount.v1.IdentityAccountQueryController/get",
+    );
+    const actor = byName.get(
+      "ai.stigmer.iam.identityaccount.v1.IdentityAccountQueryController/getActorInfo",
+    );
+    expect(get?.namesId, "get names its id").toBe(true);
+    expect(actor?.namesId, "getActorInfo names its id").toBe(true);
+  });
+});
+
+describe("the check bites (mutation proofs over the same function)", () => {
+  const shaped = (overrides: Partial<AnnotationTarget>): AnnotationTarget => ({
+    method: "x.v1.Query/probe",
+    namesKind: true,
+    namesId: true,
+    skipsResolution: false,
+    ...overrides,
+  });
+
+  it("a kind with no id is reported, by method name", () => {
+    expect(unresolvableTargets([shaped({ namesId: false })])).toEqual([
+      "x.v1.Query/probe names a resource kind but neither field_path nor resource_id — the Authorize step would check an empty id",
+    ]);
+  });
+
+  it("a kind with an id is not", () => {
+    expect(unresolvableTargets([shaped({})])).toEqual([]);
+  });
+
+  it("a skip or public method is exempt — its target is the handler's, not the annotation's", () => {
+    expect(
+      unresolvableTargets([shaped({ namesId: false, skipsResolution: true })]),
+    ).toEqual([]);
+  });
+
+  it("a config that names no kind is outside this invariant", () => {
+    expect(
+      unresolvableTargets([shaped({ namesKind: false, namesId: false })]),
+    ).toEqual([]);
+  });
+});

package/src/transport/console/__tests__/handler.test.ts

@@ -4,7 +4,14 @@
  *
  *   - documents, flight payloads, redirects, and the 404 posture arrive
  *     with the right status, Content-Type, and Cache-Control;
- *   - /config.json is synthesized per request with a Host-derived apiUrl;
+ *   - /config.json is synthesized per request: apiUrl is the empty string
+ *     the console reads as "my own origin" (20260913.02 Q-CL-3), and the
+ *     sign-in block tells the truth about the server's posture — trusted
+ *     local says `disabled`; the OIDC posture says `oidc` with the issuer,
+ *     the audience and the console's client id, the client id empty when
+ *     the operator has not registered one (Q-CL-1, Q-CL-2);
+ *   - the OIDC return leg: /auth/callback with the provider's query
+ *     resolves to the callback document;
  *   - the guard: RPC (POST and service-shaped GET), /v1/* paths, and
  *     OPTIONS preflights flow exactly as they do WITHOUT the lane — the
  *     wire-invisibility half of the P3 acceptance;
@@ -30,8 +37,8 @@ import {
   createUnifiedPortServer,
   type UnifiedPortServer,
 } from "../../server.js";
-import { resolveConsoleAssets } from "../assets.js";
-import { createConsoleLane } from "../handler.js";
+import { resolveConsoleAssets, type ConsoleAssets } from "../assets.js";
+import { createConsoleLane, type ConsoleSignInPosture } from "../handler.js";
 
 const silentLogger = createLogger({
   level: "error",
@@ -46,6 +53,7 @@ const FIXTURE_FILES: Record<string, string> = {
   "embed.js": "// embed loader",
   "conversations.html": "<html>conversations</html>",
   "conversations.txt": "flight:conversations",
+  "auth/callback.html": "<html>completing sign-in</html>",
   "sessions/__placeholder__.html": "<html>session detail</html>",
   "sessions/__placeholder__.txt": "flight:session",
   "sessions/__placeholder__/__next.sessions.txt": "flight:nested-session",
@@ -53,25 +61,18 @@ const FIXTURE_FILES: Record<string, string> = {
 };
 
 let fixtureRoot: string;
+let assets: ConsoleAssets;
 let server: UnifiedPortServer;
 let port: number;
 let baseUrl: string;
 
-beforeAll(async () => {
-  fixtureRoot = mkdtempSync(path.join(tmpdir(), "console-lane-fixture-"));
-  for (const [file, content] of Object.entries(FIXTURE_FILES)) {
-    const target = path.join(fixtureRoot, ...file.split("/"));
-    mkdirSync(path.dirname(target), { recursive: true });
-    writeFileSync(target, content);
-  }
-
-  const assets = resolveConsoleAssets(fixtureRoot, silentLogger);
-  if (assets === undefined) {
-    throw new Error("fixture export was not discovered");
-  }
+/** A unified-port server whose console lane serves the fixture under `signIn`. */
+async function startServer(
+  signIn: ConsoleSignInPosture,
+): Promise<UnifiedPortServer> {
   const healthState = new HealthState();
   healthState.setOverall(ServingStatus.SERVING);
-  server = createUnifiedPortServer({
+  return createUnifiedPortServer({
     logger: silentLogger,
     routes: (router) => registerHealthService(router, healthState),
     interceptors: [],
@@ -83,12 +84,24 @@ beforeAll(async () => {
       response.setHeader("x-lane", "model");
       response.end("{}");
     },
-    consoleLane: createConsoleLane({
-      assets,
-      grpcPort: 7234,
-      logger: silentLogger,
-    }),
+    consoleLane: createConsoleLane({ assets, signIn, logger: silentLogger }),
   });
+}
+
+beforeAll(async () => {
+  fixtureRoot = mkdtempSync(path.join(tmpdir(), "console-lane-fixture-"));
+  for (const [file, content] of Object.entries(FIXTURE_FILES)) {
+    const target = path.join(fixtureRoot, ...file.split("/"));
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, content);
+  }
+
+  const discovered = resolveConsoleAssets(fixtureRoot, silentLogger);
+  if (discovered === undefined) {
+    throw new Error("fixture export was not discovered");
+  }
+  assets = discovered;
+  server = await startServer({ posture: "trusted-local" });
   port = await server.listen(0, "127.0.0.1");
   baseUrl = `http://127.0.0.1:${port}`;
 });
@@ -175,8 +188,19 @@ describe("document serving", () => {
   });
 });
 
+describe("the OIDC return leg", () => {
+  it("serves /auth/callback with the provider's query the callback document", async () => {
+    const response = await fetch(`${baseUrl}/auth/callback?code=abc&state=xyz`);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toBe(
+      "text/html; charset=utf-8",
+    );
+    expect(await response.text()).toBe(FIXTURE_FILES["auth/callback.html"]);
+  });
+});
+
 describe("/config.json synthesis", () => {
-  it("derives apiUrl from the request Host and forbids caching", async () => {
+  it("under trusted local: same-origin apiUrl, sign-in disabled, never cached", async () => {
     const response = await fetch(`${baseUrl}/config.json`);
     expect(response.status).toBe(200);
     expect(response.headers.get("content-type")).toBe("application/json");
@@ -184,7 +208,7 @@ describe("/config.json synthesis", () => {
       "no-cache, no-store, must-revalidate",
     );
     expect(await response.json()).toEqual({
-      apiUrl: `http://127.0.0.1:${port}`,
+      apiUrl: "",
       appUrl: "",
       authMode: "disabled",
       oidcIssuer: "",
@@ -192,6 +216,52 @@ describe("/config.json synthesis", () => {
       oidcAudience: "",
     });
   });
+
+  describe("under the OIDC posture", () => {
+    const ISSUER = "https://auth.example.com/realms/main";
+    const AUDIENCE = "https://stigmer.example.com/";
+
+    async function configUnder(consoleClientId: string): Promise<unknown> {
+      const oidcServer = await startServer({
+        posture: "oidc",
+        issuer: ISSUER,
+        audience: AUDIENCE,
+        consoleClientId,
+      });
+      const oidcPort = await oidcServer.listen(0, "127.0.0.1");
+      try {
+        const response = await fetch(
+          `http://127.0.0.1:${oidcPort}/config.json`,
+        );
+        expect(response.status).toBe(200);
+        return await response.json();
+      } finally {
+        await oidcServer.shutdown();
+      }
+    }
+
+    it("tells the console the issuer, the audience and its client id", async () => {
+      expect(await configUnder("stigmer-console")).toEqual({
+        apiUrl: "",
+        appUrl: "",
+        authMode: "oidc",
+        oidcIssuer: ISSUER,
+        oidcClientId: "stigmer-console",
+        oidcAudience: AUDIENCE,
+      });
+    });
+
+    it("keeps authMode honest when no console client is registered — the client id is empty, never a disabled lie", async () => {
+      expect(await configUnder("")).toEqual({
+        apiUrl: "",
+        appUrl: "",
+        authMode: "oidc",
+        oidcIssuer: ISSUER,
+        oidcClientId: "",
+        oidcAudience: AUDIENCE,
+      });
+    });
+  });
 });
 
 describe("the guard: RPC and /v1/* flow exactly as without the lane", () => {

package/src/transport/console/__tests__/resolver.test.ts

@@ -32,6 +32,7 @@ const index = buildConsoleFileIndex([
   "/__next._tree.txt",
   "/conversations.html",
   "/conversations.txt",
+  "/auth/callback.html",
   "/auth/github/callback.html",
   "/sessions/__placeholder__.html",
   "/sessions/__placeholder__.txt",
@@ -69,6 +70,11 @@ describe("page contract (the nginx chain)", () => {
     expect(servedFile("/auth/github/callback")).toBe(
       "/auth/github/callback.html",
     );
+    // The OIDC return leg (20260913.02): the provider redirects here with
+    // `?code&state`; the handler strips the query, so the resolver sees
+    // exactly this path and must answer the callback document, never
+    // the 404 page — a 404 here is a login that can never complete.
+    expect(servedFile("/auth/callback")).toBe("/auth/callback.html");
   });
 
   it("resolves one trailing dynamic segment to its placeholder document", () => {