@stigmer/server 3.14.0-dev.20260910084630

package/src/extensions/schedule-fire-caller.ts

@@ -0,0 +1,33 @@
+/**
+ * The schedule-fire caller seam (stigmer-cloud#572) — WHO a schedule fire
+ * acts as when the RunStarter re-enters the execution create pipeline.
+ *
+ * OSS deliberately has no caller identity on this lane (DD-015 D-G: the
+ * single-user edition has no tokens to carry one), so with no driver
+ * composed every fire enters as the in-process `internal` class — today's
+ * behavior, byte-identical. The cloud edition's Java baseline instead
+ * mints a schedule JWT per fire (sub = the org's system-schedule account,
+ * claim = the firing Schedule id) so the created session and execution
+ * carry real attribution and the schedule's viewer set reaches the run
+ * (the FGA model's session#schedule link — "without it a scheduled run is
+ * invisible to every human, including the schedule's owner"). This seam
+ * lets a composition supply that identity; the fire then propagates it
+ * through the R5 caller-propagation header exactly like the other
+ * request-origin in-process creates.
+ *
+ * Single-instance point. The mint is per fire — the schedule id is a
+ * claim of the minted credential, never a cached field — and a mint
+ * failure is an infrastructure fault: the RunStarter lets it propagate,
+ * so the tick activity retries (the deterministic execution name absorbs
+ * the retry) and a manual trigger surfaces the failure to its caller.
+ */
+import type { CallerIdentity } from "./identity.js";
+
+export interface ScheduleFireCallerMint {
+  /**
+   * Mints the caller identity one fire acts as. `rawToken` must carry the
+   * edition's verifiable credential for the identity (compositions read
+   * fire-scoped claims — e.g. the schedule id — from it downstream).
+   */
+  mintFireCaller(org: string, scheduleId: string): Promise<CallerIdentity>;
+}

package/src/extensions/status-hooks.ts

@@ -0,0 +1,55 @@
+/**
+ * Status-transition hook types — the execution-lifecycle seam of the
+ * convergence blueprint (20260826.02 blueprint/03 §7, DD-006 §3), carried
+ * by the extension registry from O1 (20260826.09) and CONSUMED by O4 at
+ * the updateStatus chokepoint (src/domain/agentexecution/update-status.ts,
+ * the single merge point every status transition funnels through).
+ *
+ * The ratified contract, verbatim: observers fire synchronously after the
+ * store write and MAY NOT mutate the execution; decorators may contribute
+ * only response fields the OSS reply schema already carries (the
+ * control-signal field exists on the shared proto); StreamBroker.broadcast
+ * stays last. The workflow `stigmer/agent-execution/invoke` stays
+ * byte-identical — no extension activities inside it (the rejected
+ * alternative in DD-006).
+ *
+ * Scope note (ratified census finding): this hook family spans the
+ * agent-execution family ONLY. Workflowexecution is unmetered in the cloud
+ * edition, and no hook is built ahead of need there.
+ */
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { UpdateStatusResponse } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+
+/** One observed phase transition, delivered post-merge (blueprint §7). */
+export interface AgentExecutionStatusTransition {
+  /** The merged, persisted execution snapshot. Observers may not mutate it. */
+  readonly execution: AgentExecution;
+  readonly oldPhase: ExecutionPhase;
+  readonly newPhase: ExecutionPhase;
+}
+
+/**
+ * Fires synchronously after the merge persists. A throwing observer is an
+ * extension bug logged by the chokepoint, never a failed transition — the
+ * cloud's expiry sweep remains the reconciliation backstop it already is.
+ */
+export type AgentExecutionStatusObserver = (
+  transition: AgentExecutionStatusTransition,
+) => void | Promise<void>;
+
+/**
+ * Runs after the merge, before the reply; may set only fields the shared
+ * reply schema carries. Decorator failure degrades the contributed fields
+ * to their defaults (the verified non-fatal posture), never the RPC.
+ */
+export type AgentExecutionResponseDecorator = (
+  execution: AgentExecution,
+  response: UpdateStatusResponse,
+) => void | Promise<void>;
+
+/** The hook bundle one extension unit contributes (both lists optional). */
+export interface AgentExecutionStatusHooks {
+  readonly observers?: ReadonlyArray<AgentExecutionStatusObserver>;
+  readonly responseDecorators?: ReadonlyArray<AgentExecutionResponseDecorator>;
+}

package/src/gocompat/__tests__/query-escape.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Pins the Go net/url encoding ports on the exact characters where
+ * URLSearchParams would diverge — the reason these helpers exist. The
+ * artifact storage's signed-URL tests exercise goQueryEscape end-to-end;
+ * this file pins the primitive and the Values.Encode composition directly.
+ */
+import { describe, expect, it } from "vitest";
+
+import { goQueryEscape, goUrlValuesEncode } from "../query-escape.js";
+
+describe("goQueryEscape", () => {
+  it("matches Go url.QueryEscape on the divergent characters", () => {
+    expect(goQueryEscape("a b")).toBe("a+b"); // space → '+'
+    expect(goQueryEscape("~tilde")).toBe("~tilde"); // '~' unescaped (URLSearchParams escapes it)
+    expect(goQueryEscape("star*")).toBe("star%2A"); // '*' escaped (URLSearchParams leaves it bare)
+    expect(goQueryEscape("repo,read:user")).toBe("repo%2Cread%3Auser");
+    expect(goQueryEscape("https://x.example/cb")).toBe("https%3A%2F%2Fx.example%2Fcb");
+  });
+
+  it("percent-encodes multi-byte UTF-8 per byte, uppercase hex", () => {
+    expect(goQueryEscape("é")).toBe("%C3%A9");
+  });
+});
+
+describe("goUrlValuesEncode", () => {
+  it("sorts keys and escapes keys and values (Go url.Values.Encode)", () => {
+    expect(
+      goUrlValuesEncode({ b: "2 2", a: "1", "c:key": "v" }),
+    ).toBe("a=1&b=2+2&c%3Akey=v");
+  });
+
+  it("keeps empty values as key=", () => {
+    expect(goUrlValuesEncode({ a: "" })).toBe("a=");
+  });
+});

package/src/gocompat/__tests__/trim.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Pins goTrimSpace/goFields against Go's strings.TrimSpace/Fields on
+ * exactly the characters where JS's .trim()/\s+ disagree: U+FEFF (JS
+ * trims/splits, Go does NOT) and U+0085 (Go trims/splits, JS does NOT).
+ * A regression here flips search-mode selection and search-term
+ * tokenization on BOM'd or NEL-padded queries (the #8 BOM divergence class).
+ */
+import { describe, expect, it } from "vitest";
+
+import { goFields, goTrimSpace } from "../trim.js";
+
+describe("goTrimSpace", () => {
+  it("trims Go's White_Space set including U+0085 and U+00A0", () => {
+    expect(goTrimSpace("  foo  ")).toBe("foo");
+    expect(goTrimSpace("\t\nfoo\r\n")).toBe("foo");
+    expect(goTrimSpace("\u0085foo\u0085")).toBe("foo");
+    expect(goTrimSpace("\u00A0foo\u3000")).toBe("foo");
+  });
+
+  it("does NOT trim U+FEFF — Go keeps the BOM", () => {
+    expect(goTrimSpace("\uFEFFfoo")).toBe("\uFEFFfoo");
+    expect(goTrimSpace("\uFEFF")).toBe("\uFEFF");
+  });
+
+  it("reduces all-space input to empty", () => {
+    expect(goTrimSpace("")).toBe("");
+    expect(goTrimSpace(" \t\u0085\u2003 ")).toBe("");
+  });
+});
+
+describe("goFields", () => {
+  it("splits around runs of Go's space set, no empty fields", () => {
+    expect(goFields("foo bar")).toEqual(["foo", "bar"]);
+    expect(goFields("  foo \t bar  ")).toEqual(["foo", "bar"]);
+    expect(goFields("foo\u0085bar")).toEqual(["foo", "bar"]);
+  });
+
+  it("does NOT split on U+FEFF — one Go token", () => {
+    expect(goFields("foo\uFEFFbar")).toEqual(["foo\uFEFFbar"]);
+  });
+
+  it("yields [] for empty and all-space input", () => {
+    expect(goFields("")).toEqual([]);
+    expect(goFields(" \n\u0085 ")).toEqual([]);
+  });
+});

package/src/gocompat/query-escape.ts

@@ -0,0 +1,41 @@
+/**
+ * Byte-exact ports of Go's net/url query encoding — shared by the artifact
+ * storage's signed URLs (#17) and the github broker's authorize-URL/token
+ * exchange (#13). Promoted out of src/artifactstorage/ on its second
+ * consumer per the shared-steps guideline.
+ *
+ * WHY not URLSearchParams: it differs from Go's url.QueryEscape on two
+ * characters ('~' escaped, '*' bare), which would break URL byte parity
+ * for values carrying them. The Go server is the behavioral reference for
+ * every URL a client sees during coexistence.
+ */
+
+/**
+ * Go url.QueryEscape, byte-exact: unreserved [A-Za-z0-9-_.~] pass, space
+ * becomes '+', everything else percent-encodes.
+ */
+export function goQueryEscape(s: string): string {
+  let out = "";
+  for (const byte of Buffer.from(s, "utf-8")) {
+    const c = String.fromCharCode(byte);
+    if (/[A-Za-z0-9\-_.~]/.test(c)) {
+      out += c;
+    } else if (c === " ") {
+      out += "+";
+    } else {
+      out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  return out;
+}
+
+/**
+ * Go url.Values.Encode for single-valued params: keys sorted
+ * lexicographically, keys and values QueryEscape'd, joined with '&'.
+ */
+export function goUrlValuesEncode(values: Record<string, string>): string {
+  return Object.keys(values)
+    .sort()
+    .map((key) => `${goQueryEscape(key)}=${goQueryEscape(values[key] ?? "")}`)
+    .join("&");
+}

package/src/gocompat/trim.ts

@@ -0,0 +1,38 @@
+/**
+ * Go strings.TrimSpace — trims by unicode.IsSpace, the Unicode White_Space
+ * property (ASCII spaces, U+0085, U+00A0, U+1680, U+2000–U+200A, U+2028,
+ * U+2029, U+202F, U+205F, U+3000) — which EXCLUDES U+FEFF. JS String.trim's
+ * set is White_Space PLUS U+FEFF and MINUS U+0085, so the two disagree on
+ * BOM'd and NEL-padded input: a .trim()-based port flips Go's verdict on
+ * both (first found by the #8 skill parity panel on BOM'd SKILL.md files;
+ * promoted here when search criteria became the second consumer — a
+ * .trim()'d search query of exactly "\uFEFF" reads as LIST MODE where Go
+ * runs an empty-match SEARCH, and "\u0085" the mirror image).
+ *
+ * Proven by src/gocompat/__tests__/trim.test.ts and both consumers' suites.
+ */
+const GO_SPACE_CLASS =
+  "\\t\\n\\v\\f\\r \\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000";
+
+const GO_TRIM_PATTERN = new RegExp(
+  `^[${GO_SPACE_CLASS}]+|[${GO_SPACE_CLASS}]+$`,
+  "g",
+);
+
+const GO_FIELDS_PATTERN = new RegExp(`[${GO_SPACE_CLASS}]+`);
+
+export function goTrimSpace(value: string): string {
+  return value.replace(GO_TRIM_PATTERN, "");
+}
+
+/**
+ * Go strings.Fields — splits around runs of unicode.IsSpace. The JS twin
+ * hazard mirrors trim's: `\s` splits on U+FEFF (Go does not) and misses
+ * U+0085 (Go splits) — a `\s+`-based split changes which search terms a
+ * query produces on exactly those inputs. Returns no empty fields; an
+ * all-space (or empty) input yields [].
+ */
+export function goFields(value: string): string[] {
+  const trimmed = goTrimSpace(value);
+  return trimmed === "" ? [] : trimmed.split(GO_FIELDS_PATTERN);
+}

package/src/identity/__tests__/oidc-verifier.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Pins the OIDC identity verifier against a hermetic local issuer (an
+ * in-process HTTP server serving real discovery + JWKS documents, tokens
+ * signed with a real RS256 keypair — no network, no mocks of jose):
+ * claim-or-pass (non-JWT shapes pass, JWT shapes are claimed), the
+ * identity mapping (sub/iss/email/name), the four byte-pinned Java
+ * classifyAuthError arms, and the infrastructure-fault posture (discovery
+ * failures are plain errors for the chassis's INTERNAL arm — never
+ * credential rejections).
+ */
+import { createServer } from "node:http";
+import type { Server } from "node:http";
+import { once } from "node:events";
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import { SignJWT, exportJWK, generateKeyPair } from "jose";
+import type { GenerateKeyPairResult } from "jose";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import {
+  INVALID_TOKEN_MESSAGE,
+  TOKEN_AUDIENCE_MESSAGE,
+  TOKEN_EXPIRED_MESSAGE,
+  TOKEN_SIGNATURE_MESSAGE,
+  newOidcIdentityVerifier,
+} from "../oidc-verifier.js";
+
+const AUDIENCE = "https://api.stigmer.test/";
+
+let issuerServer: Server;
+let issuer: string;
+let keys: GenerateKeyPairResult;
+let strangerKeys: GenerateKeyPairResult;
+
+beforeAll(async () => {
+  keys = await generateKeyPair("RS256");
+  strangerKeys = await generateKeyPair("RS256");
+  const jwk = { ...(await exportJWK(keys.publicKey)), kid: "test-key", alg: "RS256" };
+
+  issuerServer = createServer((req, res) => {
+    if (req.url === "/.well-known/openid-configuration") {
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify({ issuer, jwks_uri: `${issuer}/jwks` }));
+      return;
+    }
+    if (req.url === "/jwks") {
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify({ keys: [jwk] }));
+      return;
+    }
+    res.statusCode = 404;
+    res.end();
+  });
+  issuerServer.listen(0, "127.0.0.1");
+  await once(issuerServer, "listening");
+  const address = issuerServer.address();
+  if (address === null || typeof address === "string") {
+    throw new Error("issuer server did not bind a port");
+  }
+  issuer = `http://127.0.0.1:${address.port}`;
+});
+
+afterAll(async () => {
+  issuerServer.close();
+  await once(issuerServer, "close");
+});
+
+interface TokenOptions {
+  sub?: string | undefined;
+  audience?: string;
+  expiresIn?: string;
+  email?: string;
+  name?: string;
+  signWith?: "issuer" | "stranger";
+  issuerClaim?: string;
+}
+
+async function mintToken(options: TokenOptions = {}): Promise<string> {
+  const jwt = new SignJWT({
+    ...(options.email !== undefined ? { email: options.email } : {}),
+    ...(options.name !== undefined ? { name: options.name } : {}),
+  })
+    .setProtectedHeader({ alg: "RS256", kid: "test-key" })
+    .setIssuer(options.issuerClaim ?? issuer)
+    .setAudience(options.audience ?? AUDIENCE)
+    .setIssuedAt()
+    .setExpirationTime(options.expiresIn ?? "5m");
+  if (options.sub !== undefined) {
+    jwt.setSubject(options.sub);
+  }
+  const key =
+    options.signWith === "stranger" ? strangerKeys.privateKey : keys.privateKey;
+  return jwt.sign(key);
+}
+
+function verifier() {
+  return newOidcIdentityVerifier({ issuer, audience: AUDIENCE });
+}
+
+async function rejectionOf(promise: Promise<unknown>): Promise<unknown> {
+  return promise.then(
+    () => {
+      throw new Error("expected rejection");
+    },
+    (error: unknown) => error,
+  );
+}
+
+describe("claim-or-pass", () => {
+  it("passes (null) on non-JWT shapes — the apikey lane stays reachable", async () => {
+    expect(await verifier().verify("stk_notajwt")).toBeNull();
+    expect(await verifier().verify("two.segments")).toBeNull();
+    expect(await verifier().verify("a..c")).toBeNull();
+  });
+});
+
+describe("identity mapping", () => {
+  it("maps sub/iss and the email/name claims (the DD-007 Q5 fields)", async () => {
+    const token = await mintToken({
+      sub: "auth0|user123",
+      email: "person@example.com",
+      name: "Real Person",
+    });
+    expect(await verifier().verify(token)).toEqual({
+      identityId: "auth0|user123",
+      callerClass: "user",
+      issuer,
+      rawToken: token,
+      email: "person@example.com",
+      displayName: "Real Person",
+    });
+  });
+
+  it("omits the display fields when the claims are absent", async () => {
+    const token = await mintToken({ sub: "auth0|min" });
+    const identity = await verifier().verify(token);
+    expect(identity?.email).toBeUndefined();
+    expect(identity?.displayName).toBeUndefined();
+  });
+
+  it("a token without sub is invalid — no principal, no identity", async () => {
+    const token = await mintToken({});
+    const error = await rejectionOf(verifier().verify(token));
+    expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
+  });
+});
+
+describe("the byte-pinned classifyAuthError arms", () => {
+  it("expired → 'token has expired'", async () => {
+    const token = await mintToken({ sub: "s", expiresIn: "-5m" });
+    const error = await rejectionOf(verifier().verify(token));
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe(TOKEN_EXPIRED_MESSAGE);
+  });
+
+  it("audience mismatch → the audience copy", async () => {
+    const token = await mintToken({ sub: "s", audience: "https://other.api/" });
+    const error = await rejectionOf(verifier().verify(token));
+    expect(ConnectError.from(error).rawMessage).toBe(TOKEN_AUDIENCE_MESSAGE);
+  });
+
+  it("a stranger's signature → the signature copy", async () => {
+    const token = await mintToken({ sub: "s", signWith: "stranger" });
+    const error = await rejectionOf(verifier().verify(token));
+    expect(ConnectError.from(error).rawMessage).toBe(TOKEN_SIGNATURE_MESSAGE);
+  });
+
+  it("issuer-claim mismatch → 'invalid token' (the fallback arm)", async () => {
+    const token = await mintToken({ sub: "s", issuerClaim: "https://evil.test" });
+    const error = await rejectionOf(verifier().verify(token));
+    expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
+  });
+
+  it("a garbage three-segment token → 'invalid token'", async () => {
+    const error = await rejectionOf(verifier().verify("aaa.bbb.ccc"));
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
+  });
+});
+
+describe("infrastructure faults are never credential rejections", () => {
+  it("an unreachable issuer throws a PLAIN error (chassis maps INTERNAL)", async () => {
+    const dead = newOidcIdentityVerifier({
+      // Port 1 is deterministically closed.
+      issuer: "http://127.0.0.1:1",
+      audience: AUDIENCE,
+    });
+    const error = await rejectionOf(dead.verify(await mintToken({ sub: "s" })));
+    expect(error).not.toBeInstanceOf(ConnectError);
+  });
+
+  it("a discovery document with the wrong issuer throws a PLAIN error", async () => {
+    const misconfigured = newOidcIdentityVerifier({
+      // Points at the real test issuer but claims to expect a different
+      // one — the discovery-document identity check must refuse.
+      issuer: `${issuer}/`,
+      audience: AUDIENCE,
+    });
+    const error = await rejectionOf(
+      misconfigured.verify(await mintToken({ sub: "s" })),
+    );
+    expect(error).not.toBeInstanceOf(ConnectError);
+    expect(String(error)).toContain("does not match configured issuer");
+  });
+});

package/src/identity/oidc-verifier.ts

@@ -0,0 +1,172 @@
+/**
+ * The generic OIDC identity verifier (O3, 20260827.06; DD-003: verification
+ * is OSS, the issuer is configuration) — the second OSS entry on the
+ * chassis's verifier chain, the TS rendering of the cloud's Nimbus
+ * JwtDecoders.fromOidcIssuerLocation + audience validator stack. Stigmer
+ * Cloud points STIGMER_OIDC_ISSUER at Auth0 and registers NO code here;
+ * any self-host points it at their own issuer (Keycloak, Okta, Dex, …).
+ *
+ * Claim rule: any JWT-shaped token (three non-empty dot-separated
+ * segments). API keys never look like JWTs (`stk_` + one Base64URL run),
+ * so ordering after the apikey verifier keeps both claims disjoint; a
+ * JWT-shaped token that fails verification THROWS (identity.ts contract)
+ * with the Java classifyAuthError copy, byte-pinned:
+ *
+ *   - expiry → "token has expired"
+ *   - audience mismatch → "token audience does not match the expected audience"
+ *   - signature / JWKS-key failures → "token signature verification failed"
+ *   - 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
+ * 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).
+ */
+import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
+import type { JWTPayload } from "jose";
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import type {
+  CallerIdentity,
+  IdentityVerifier,
+} from "../extensions/identity.js";
+
+/** Java classifyAuthError arms — byte-pinned cross-edition copy. */
+export const TOKEN_EXPIRED_MESSAGE = "token has expired";
+export const TOKEN_AUDIENCE_MESSAGE =
+  "token audience does not match the expected audience";
+export const TOKEN_SIGNATURE_MESSAGE = "token signature verification failed";
+export const INVALID_TOKEN_MESSAGE = "invalid token";
+
+export interface OidcVerifierConfig {
+  /** The issuer URL (already URL-validated by the config loader). */
+  readonly issuer: string;
+  /** The audience access tokens must carry. */
+  readonly audience: string;
+}
+
+interface DiscoveredIssuer {
+  readonly jwks: ReturnType<typeof createRemoteJWKSet>;
+}
+
+export function newOidcIdentityVerifier(
+  config: OidcVerifierConfig,
+): IdentityVerifier {
+  let discovered: DiscoveredIssuer | 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}'`,
+      );
+    }
+    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;
+  }
+
+  return {
+    name: "oidc",
+    async verify(token: string): Promise<CallerIdentity | null> {
+      if (!isJwtShaped(token)) {
+        return null;
+      }
+      const issuer = await discover();
+      let payload: JWTPayload;
+      try {
+        ({ payload } = await jwtVerify(token, issuer.jwks, {
+          issuer: config.issuer,
+          audience: config.audience,
+        }));
+      } catch (error) {
+        throw classifyJoseError(error);
+      }
+      if (typeof payload.sub !== "string" || payload.sub === "") {
+        throw new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
+      }
+      return {
+        identityId: payload.sub,
+        callerClass: "user",
+        issuer: config.issuer,
+        rawToken: token,
+        ...(typeof payload["email"] === "string" && payload["email"] !== ""
+          ? { email: payload["email"] }
+          : {}),
+        ...(typeof payload["name"] === "string" && payload["name"] !== ""
+          ? { displayName: payload["name"] }
+          : {}),
+      };
+    },
+  };
+}
+
+/** 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(".");
+  return segments.length === 3 && segments.every((s) => s !== "");
+}
+
+/**
+ * Maps jose's verification failures onto the Java classifyAuthError arms.
+ * JWKS transport failures (discovery succeeded, key fetch did not) are
+ * NOT credential rejections — they rethrow as plain errors for the
+ * chassis's INTERNAL arm.
+ */
+function classifyJoseError(error: unknown): unknown {
+  if (error instanceof joseErrors.JWTExpired) {
+    return new ConnectError(TOKEN_EXPIRED_MESSAGE, Code.Unauthenticated);
+  }
+  if (error instanceof joseErrors.JWTClaimValidationFailed) {
+    if (error.claim === "aud") {
+      return new ConnectError(TOKEN_AUDIENCE_MESSAGE, Code.Unauthenticated);
+    }
+    return new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
+  }
+  if (
+    error instanceof joseErrors.JWSSignatureVerificationFailed ||
+    error instanceof joseErrors.JWKSNoMatchingKey ||
+    error instanceof joseErrors.JWKSMultipleMatchingKeys ||
+    error instanceof joseErrors.JWKSInvalid
+  ) {
+    return new ConnectError(TOKEN_SIGNATURE_MESSAGE, Code.Unauthenticated);
+  }
+  if (
+    error instanceof joseErrors.JWTInvalid ||
+    error instanceof joseErrors.JWSInvalid
+  ) {
+    return new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
+  }
+  // JWKSTimeout, fetch failures, and anything unclassified: infrastructure —
+  // the chassis maps a non-ConnectError throw to INTERNAL.
+  return error;
+}