@stigmer/server 3.14.1 → 3.15.0

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([]);
+  });
+});