@konneal/engine 0.1.0

package/workers/worker_public/src/modelplane.ts

@@ -0,0 +1,213 @@
+// The model plane (TODO.ai-platform/05) — the ask path's model-native
+// grounding. The packages' machine content (the requirements' constraints,
+// the applicability rules, the acceptance criteria, the term definitions)
+// indexes alongside the prose corpus; this module is the deterministic
+// half at ask time:
+//
+//   1. BIND — "this requirement" on a model surface (the platform's
+//      entity chip) names the model node by its canonical id (the label
+//      leads with it, e.g. "this requirement /req/metrological/mpe — …");
+//      a question may name one too. The grammar is strict — a node id is
+//      a machine shape, never fuzzy-matched.
+//   2. GROUND — the bound node's own content (from the model_nodes D1
+//      store, loaded from the smart repo's derived bundles) joins the
+//      prompt as a structured grounding block: the constraint (quoted
+//      verbatim), the applicability, the acceptance, the provenance, the
+//      tests. A DECLARED source discrepancy (the model and the text
+//      disagree) rides verbatim — the clause-drift doctrine's posture is
+//      structural: the answer must surface it and cite both.
+//   3. ECHO — context_applied.model names the bound node so the panel's
+//      honest context line never invents the grounding.
+//
+// The verdict-explanation discipline is the smart repo's (its engine's
+// trace seam — never reimplemented here): this module grounds in the
+// model NODE (the static constraint + clause + acceptance); a live
+// verdict's explanation is the platform's computation, quoted when the
+// platform serves it — this service never recomputes one.
+
+/** The strict model-node id grammar: the kind prefix + one or two
+ *  slug segments (the packages' identifier shapes — /req/<class>/<id>,
+ *  /conf/<class>/<id>, /term/<id>, /constraint/<id>, /characteristic/<id>,
+ *  /state-machine/<id>, /dimension/<id>). */
+const NODE_RE = /(?:^|[\s("'`])\/(req|conf|term|constraint|characteristic|state-machine|dimension)\/([a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)?)(?=[\s)"'`,;:.]|$)/i;
+
+/** The first model-node id a text names (the declared chip label first,
+ *  the question second — the caller orders). */
+export function modelNodeRefIn(text: string | undefined | null): string | null {
+  if (!text) return null;
+  const m = text.match(NODE_RE);
+  if (!m) return null;
+  const id = `/${m[1]!.toLowerCase()}/${m[2]}`;
+  return id.length <= 120 ? id : null;
+}
+
+/** The doc scope's publication family → the model plane's standard
+ *  (doc_number "60" → oiml-r60). Only the four modeled Recommendations
+ *  carry a plane; anything else resolves null (honest: no model to bind). */
+export function standardForDocNumber(docNumber: string | undefined): string | null {
+  if (!docNumber) return null;
+  return ["60", "91", "129", "144"].includes(docNumber) ? `oiml-r${docNumber}` : null;
+}
+
+export interface BoundModelNode {
+  standard: string;
+  node_id: string;
+  kind: string;
+  name: string;
+  clause: { doc: string; ref: string; urn: string } | null;
+  /** The node's bundle projection (verbatim JSON). */
+  content: any;
+}
+
+async function fetchNode(env: any, standard: string, nodeId: string): Promise<BoundModelNode | null> {
+  try {
+    const row = await env.DB.prepare(
+      "SELECT standard, node_id, kind, name, clause_doc, clause_ref, content FROM model_nodes WHERE standard = ?1 AND node_id = ?2",
+    )
+      .bind(standard, nodeId)
+      .first();
+    if (!row) return null;
+    const content = JSON.parse(String(row.content));
+    const clause =
+      row.clause_doc && row.clause_ref
+        ? { doc: String(row.clause_doc), ref: String(row.clause_ref), urn: `${row.clause_doc}#clause-${row.clause_ref}` }
+        : row.clause_doc
+          ? { doc: String(row.clause_doc), ref: "", urn: String(row.clause_doc) }
+          : null;
+    return {
+      standard: String(row.standard),
+      node_id: String(row.node_id),
+      kind: String(row.kind),
+      name: String(row.name ?? row.node_id),
+      clause,
+      content,
+    };
+  } catch {
+    // the table predates the migration on this deployment, or D1 hiccuped:
+    // the model plane degrades honestly (retrieval still carries the model
+    // chunks) — never a hard failure of the ask.
+    return null;
+  }
+}
+
+/** Bind the ask's model node: the declared entity label's id wins (the
+ *  model-aware chip), then a node id the question names. The standard
+ *  comes from the declared doc scope when it carries one; without a scope
+ *  the node binds only when it exists in EXACTLY ONE indexed standard —
+ *  ambiguity is refused honestly (retrieval still surfaces the chunks). */
+export async function bindModelNode(
+  env: any,
+  opts: { label?: string; query: string; standard?: string | null },
+): Promise<BoundModelNode | null> {
+  const nodeId = modelNodeRefIn(opts.label) ?? modelNodeRefIn(opts.query);
+  if (!nodeId) return null;
+  if (opts.standard) return fetchNode(env, opts.standard, nodeId);
+  try {
+    const rows = await env.DB.prepare("SELECT standard FROM model_nodes WHERE node_id = ?1 LIMIT 2").bind(nodeId).all();
+    const standards = (rows?.results ?? []).map((r: any) => String(r.standard));
+    if (standards.length === 1) return fetchNode(env, standards[0]!, nodeId);
+    return null; // zero (not indexed) or ambiguous (several standards) — no silent pick
+  } catch {
+    return null;
+  }
+}
+
+// ── the grounding block (the node's own content, composed) ───────────
+
+function clip(s: unknown, n = 500): string {
+  const t = String(s ?? "").trim();
+  return t.length <= n ? t : t.slice(0, n - 1).trimEnd() + " …";
+}
+
+function applicabilityText(app: any): string {
+  if (!app || typeof app !== "object") return "";
+  const parts: string[] = [];
+  for (const [dim, cond] of Object.entries(app)) {
+    if (Array.isArray(cond)) parts.push(`${dim.replace(/_/g, " ")}: ${cond.join(", ")}`);
+    else if (cond && typeof cond === "object" && Array.isArray((cond as any).values)) {
+      parts.push(`${dim.replace(/_/g, " ")} (${(cond as any).match ?? "any"}): ${(cond as any).values.join(", ")}`);
+    }
+  }
+  return parts.join("; ");
+}
+
+/** The structured grounding block for the prompt — every line is the
+ *  node's own declared content (the bundle projection), never a model
+ *  paraphrase. The discrepancy block, when the model declares one, is the
+ *  model/prose disagreement posture made structural. */
+export function modelGroundingBlock(node: BoundModelNode): string {
+  const c = node.content ?? {};
+  const lines: string[] = [];
+  lines.push(
+    `Model grounding — the OIML SMART model plane (the platform's machine-readable Recommendation model, derived from the Primmel packages, the models' single source of truth):`,
+  );
+  lines.push(`Node: ${node.node_id} (${node.kind.replace(/_/g, " ")}) — ${node.name} [${node.standard}]`);
+  if (node.clause) lines.push(`Provenance: ${node.clause.urn}`);
+  if (c.statement) lines.push(`Statement: ${clip(c.statement)}`);
+  if (c.definition) lines.push(`Definition: ${clip(c.definition)}`);
+  if (c.purpose) lines.push(`Purpose: ${clip(c.purpose)}`);
+  const limit = c.limit ?? {};
+  if (limit.expression) lines.push(`Machine limit (the constraint the platform's verdict engine evaluates — quote it verbatim): ${limit.expression}`);
+  if (limit.accepts?.verdict) lines.push(`Machine limit: ${limit.accepts.verdict} ${limit.accepts.op} ${limit.accepts.limit} (the canonical acceptance chain)`);
+  if (c.check) lines.push(`Machine check: ${c.check}`);
+  if (c.derive) lines.push(`Derivation: ${c.derive}${Array.isArray(c.inputs) ? ` (inputs: ${c.inputs.join(", ")})` : ""}`);
+  const app = applicabilityText(c.applicability);
+  const scopeApp = applicabilityText(c.scope_applicability);
+  if (app || scopeApp) lines.push(`Applicability: ${[scopeApp, app].filter(Boolean).join("; ")}`);
+  if (Array.isArray(c.binds_to) && c.binds_to.length) lines.push(`Binds to: ${c.binds_to.join(", ")}`);
+  if (Array.isArray(c.targets) && c.targets.length) lines.push(`Verifies requirements: ${c.targets.join(", ")}`);
+  if (Array.isArray(c.preconditions) && c.preconditions.length) {
+    const pcs = c.preconditions.map((p: any) => `${p.id}: ${clip(p.check ?? (p.state ? `state = ${p.state}` : ""), 120)}`).join("; ");
+    lines.push(`Run-validity preconditions (a violation voids the run — invalid, never a fail): ${pcs}`);
+  }
+  if (c.acceptance_criteria?.description) lines.push(`Acceptance: ${clip(c.acceptance_criteria.description, 300)}`);
+  if (c.violation_meaning) lines.push(`Violation meaning (verbatim): ${clip(c.violation_meaning, 300)} — on violation: ${c.on_violation ?? "invalid"}`);
+  if (Array.isArray(c.values) && c.values.length) {
+    lines.push(`Values: ${c.values.map((v: any) => `${v.id}${v.implies?.length ? ` (implies ${v.implies.join(", ")})` : ""}`).join("; ")}`);
+  }
+  if (c.source_discrepancy) {
+    const sd = c.source_discrepancy;
+    lines.push(
+      `DECLARED SOURCE DISCREPANCY — the model and the text disagree; you MUST surface this and cite both: ${clip(sd.summary, 300)} ` +
+        `Sources: ${(sd.sources ?? []).join(" and ")}. The model ${sd.resolution === "follows_clause_x" ? "follows one side" : "records the conflict without resolving it"}: ${clip(sd.rationale, 300)}`,
+    );
+  }
+  lines.push(
+    "Rules for this answer: the machine facts (the constraint, the applicability, the acceptance, the provenance) come from THIS node — quote the machine limit verbatim, never invent one the node does not carry. If this model content and a prose passage disagree — including a passage from a different edition — say so explicitly and cite both (this node and the prose clause).",
+  );
+  return lines.join("\n");
+}
+
+/** The citation the panel renders for the bound node (the model plane is
+ *  a first-class corpus: the citation names the node + its clause). */
+export function modelCitation(node: BoundModelNode) {
+  return {
+    doc_id: `model:${node.standard}`,
+    docidentifier: `OIML SMART model (${node.standard.replace(/^oiml-r/, "R ")})`,
+    edition: "",
+    language: "en",
+    clause_anchor: node.clause?.ref || "model",
+    clause_title: `${node.kind.replace(/_/g, " ")} — ${node.name} (${node.node_id})`,
+    status: "in-force",
+    corpus: "smart-model",
+    url: undefined,
+    snippet: `${node.node_id}${node.clause ? ` · ${node.clause.urn}` : ""}${node.content?.statement ? ` — ${clip(node.content.statement, 240)}` : ""}`,
+    score: 1,
+  };
+}
+
+/** The context_applied echo's model block — the honest context line's
+ *  grounding record. */
+export function modelEcho(node: BoundModelNode) {
+  return {
+    node_id: node.node_id.slice(0, 120),
+    kind: node.kind.slice(0, 40),
+    standard: node.standard.slice(0, 40),
+    ...(node.clause?.urn ? { clause: node.clause.urn.slice(0, 120) } : {}),
+  };
+}
+
+/** The per-corpus guidance note (config.ts's DATASETS pattern — every
+ *  retrieved model-plane chunk carries it, chip or no chip). */
+export const MODEL_CORPUS_NOTE =
+  "Some passages are the OIML SMART model plane (labeled OIML SMART model) — the platform's machine-readable Recommendation models derived from the Primmel packages. Treat their machine limits, applicability rules and acceptance criteria as the model's own statement of them (quote machine limits verbatim); where a model passage and a prose passage disagree, say so explicitly and cite both.";

package/workers/worker_public/src/oidc.ts

@@ -0,0 +1,333 @@
+// OIDC relying-party half of the Authorization Code + PKCE flow,
+// hand-rolled on WebCrypto + fetch. Ported from the estate's reference
+// implementation (oimlsmart/smart packages/platform-server/src/oidc.ts)
+// per docs/identity-service.md — zero library dependencies by design.
+
+export type OidcFailureReason =
+  | 'not_configured'
+  | 'discovery'
+  | 'issuer_mismatch'
+  | 'exchange'
+  | 'state'
+  | 'token_malformed'
+  | 'token_alg'
+  | 'token_signature'
+  | 'token_issuer'
+  | 'token_audience'
+  | 'token_expired'
+  | 'token_nonce';
+
+export class OidcError extends Error {
+  constructor(readonly reason: OidcFailureReason, message: string) {
+    super(message);
+    this.name = "OidcError";
+  }
+}
+
+export interface OidcMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  jwks_uri: string;
+  end_session_endpoint?: string;
+  userinfo_endpoint?: string;
+}
+
+interface CachedMetadata {
+  metadata: OidcMetadata;
+  fetchedAt: number;
+}
+const metadataCache = new Map<string, CachedMetadata>();
+const METADATA_TTL_MS = 60 * 60 * 1000;
+
+/** UserInfo (the OP declares the endpoint): the ID token carries the
+ *  profile contract (name/email + policy families) — `picture` rides
+ *  userinfo. Returns {} on any failure (the picture is a nicety, never
+ *  a gate); the CALLER must check `sub` matches the ID token's. */
+export async function fetchUserinfo(meta: OidcMetadata, accessToken: string): Promise<Record<string, unknown>> {
+  if (!meta.userinfo_endpoint) return {};
+  try {
+    const res = await fetch(meta.userinfo_endpoint, { headers: { authorization: `Bearer ${accessToken}` } });
+    if (!res.ok) return {};
+    const claims: unknown = await res.json();
+    return claims && typeof claims === "object" ? (claims as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function discoverIssuer(issuer: string): Promise<OidcMetadata> {
+  const cached = metadataCache.get(issuer);
+  if (cached && Date.now() - cached.fetchedAt < METADATA_TTL_MS) return cached.metadata;
+
+  const wellKnown = `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+  let body: unknown;
+  try {
+    const res = await fetch(wellKnown);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    body = await res.json();
+  } catch (err) {
+    throw new OidcError("discovery", `could not fetch ${wellKnown}: ${(err as Error).message}`);
+  }
+  const meta = body as Partial<OidcMetadata>;
+  if (
+    typeof meta?.issuer !== "string" ||
+    typeof meta?.authorization_endpoint !== "string" ||
+    typeof meta?.token_endpoint !== "string" ||
+    typeof meta?.jwks_uri !== "string"
+  ) {
+    throw new OidcError("discovery", `the metadata at ${wellKnown} is incomplete`);
+  }
+  if (meta.issuer.replace(/\/$/, "") !== issuer.replace(/\/$/, "")) {
+    throw new OidcError("issuer_mismatch", `the metadata declares issuer ${meta.issuer}, not ${issuer}`);
+  }
+  const metadata: OidcMetadata = {
+    issuer: meta.issuer,
+    authorization_endpoint: meta.authorization_endpoint,
+    token_endpoint: meta.token_endpoint,
+    jwks_uri: meta.jwks_uri,
+    ...(typeof meta.end_session_endpoint === "string" ? { end_session_endpoint: meta.end_session_endpoint } : {}),
+    ...(typeof meta.userinfo_endpoint === "string" ? { userinfo_endpoint: meta.userinfo_endpoint } : {}),
+  };
+  metadataCache.set(issuer, { metadata, fetchedAt: Date.now() });
+  return metadata;
+}
+
+function base64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64urlDecode(s: string): Uint8Array {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice(0, (4 - (s.length % 4)) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function randomToken(): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(24)));
+}
+
+export interface PkcePair {
+  verifier: string;
+  challenge: string;
+}
+
+export async function generatePkce(): Promise<PkcePair> {
+  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}
+
+export function buildAuthorizationUrl(
+  metadata: OidcMetadata,
+  params: {
+    clientId: string;
+    redirectUri: string;
+    scopes: string;
+    state: string;
+    nonce: string;
+    codeChallenge: string;
+  },
+): string {
+  const url = new URL(metadata.authorization_endpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", params.clientId);
+  url.searchParams.set("redirect_uri", params.redirectUri);
+  url.searchParams.set("scope", params.scopes);
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("nonce", params.nonce);
+  url.searchParams.set("code_challenge", params.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+export interface OidcTokenResponse {
+  id_token: string;
+  access_token?: string;
+  token_type?: string;
+  expires_in?: number;
+}
+
+export async function exchangeCode(
+  metadata: OidcMetadata,
+  params: { clientId: string; clientSecret?: string; code: string; redirectUri: string; codeVerifier: string },
+): Promise<OidcTokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: params.code,
+    redirect_uri: params.redirectUri,
+    client_id: params.clientId,
+    code_verifier: params.codeVerifier,
+  });
+  const headers: Record<string, string> = { "content-type": "application/x-www-form-urlencoded" };
+  // The OP's WAF classifies Origin-less POSTs as cross-site form
+  // submissions and rejects them with 403. The backchannel is
+  // server-to-server (PKCE + client auth are the real security), so we
+  // present the issuer's own origin to pass its same-origin check.
+  headers.origin = new URL(metadata.token_endpoint).origin;
+  if (params.clientSecret) {
+    headers.authorization = `Basic ${btoa(`${encodeURIComponent(params.clientId)}:${encodeURIComponent(params.clientSecret)}`)}`;
+  }
+  let json: unknown;
+  try {
+    const res = await fetch(metadata.token_endpoint, { method: "POST", headers, body });
+    json = await res.json();
+    if (!res.ok) {
+      const err = (json as { error?: string; error_description?: string }) ?? {};
+      throw new Error(`HTTP ${res.status} ${err.error ?? ""} ${err.error_description ?? ""}`.trim());
+    }
+  } catch (err) {
+    throw new OidcError("exchange", `the token endpoint refused the exchange: ${(err as Error).message}`);
+  }
+  const token = json as Partial<OidcTokenResponse>;
+  if (typeof token?.id_token !== "string") {
+    throw new OidcError("exchange", "the token response carries no id_token");
+  }
+  return token as OidcTokenResponse;
+}
+
+interface Jwk {
+  kty: string;
+  kid?: string;
+  alg?: string;
+  use?: string;
+  n?: string;
+  e?: string;
+  x?: string;
+  y?: string;
+  crv?: string;
+}
+
+interface CachedJwks {
+  keys: Jwk[];
+  fetchedAt: number;
+}
+const jwksCache = new Map<string, CachedJwks>();
+const JWKS_TTL_MS = 60 * 60 * 1000;
+
+async function fetchJwks(jwksUri: string, force: boolean): Promise<Jwk[]> {
+  const cached = jwksCache.get(jwksUri);
+  if (!force && cached && Date.now() - cached.fetchedAt < JWKS_TTL_MS) return cached.keys;
+  let body: unknown;
+  try {
+    const res = await fetch(jwksUri);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    body = await res.json();
+  } catch (err) {
+    throw new OidcError("token_signature", `could not fetch the signing keys: ${(err as Error).message}`);
+  }
+  const keys = (body as { keys?: Jwk[] })?.keys;
+  if (!Array.isArray(keys)) {
+    throw new OidcError("token_signature", "the JWKS carries no keys array");
+  }
+  jwksCache.set(jwksUri, { keys, fetchedAt: Date.now() });
+  return keys;
+}
+
+export interface OidcIdTokenClaims {
+  iss: string;
+  sub: string;
+  aud: string | string[];
+  exp: number;
+  iat?: number;
+  nonce?: string;
+  azp?: string;
+  email?: string;
+  email_verified?: boolean;
+  name?: string;
+  roles?: string[];
+  groups?: string[];
+  org?: unknown;
+  [claim: string]: unknown;
+}
+
+const EXPIRY_LEEWAY_MS = 60_000;
+
+export async function validateIdToken(
+  idToken: string,
+  expectations: { issuer: string; clientId: string; nonce: string; jwksUri: string },
+): Promise<OidcIdTokenClaims> {
+  const parts = idToken.split(".");
+  if (parts.length !== 3) {
+    throw new OidcError("token_malformed", "the ID token is not a three-part JWT");
+  }
+  let header: { alg?: string; kid?: string };
+  let claims: OidcIdTokenClaims;
+  try {
+    header = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[0])));
+    claims = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[1]))) as OidcIdTokenClaims;
+  } catch {
+    throw new OidcError("token_malformed", "the ID token header/claims are not JSON");
+  }
+  if (header.alg !== "RS256" && header.alg !== "ES256") {
+    throw new OidcError("token_alg", `the ID token uses ${header.alg ?? "no declared algorithm"}`);
+  }
+
+  const signedContent = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+  const signature = base64urlDecode(parts[2]) as BufferSource;
+  let verified = false;
+  for (const force of [false, true]) {
+    const keys = await fetchJwks(expectations.jwksUri, force);
+    const candidates = keys.filter(
+      (k) => (!header.kid || k.kid === header.kid) && (header.alg === "RS256" ? k.kty === "RSA" : k.kty === "EC"),
+    );
+    for (const jwk of candidates) {
+      try {
+        const key = await crypto.subtle.importKey(
+          "jwk",
+          jwk as JsonWebKey,
+          header.alg === "RS256" ? { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" } : { name: "ECDSA", namedCurve: "P-256" },
+          false,
+          ["verify"],
+        );
+        verified = await crypto.subtle.verify(
+          header.alg === "RS256" ? { name: "RSASSA-PKCS1-v1_5" } : { name: "ECDSA", hash: "SHA-256" },
+          key,
+          signature,
+          signedContent,
+        );
+      } catch {
+        verified = false;
+      }
+      if (verified) break;
+    }
+    if (verified) break;
+  }
+  if (!verified) {
+    throw new OidcError("token_signature", "the ID token signature does not verify against the issuer's published keys");
+  }
+
+  if (claims.iss?.replace(/\/$/, "") !== expectations.issuer.replace(/\/$/, "")) {
+    throw new OidcError("token_issuer", "the ID token's issuer is not the configured issuer");
+  }
+  const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+  if (!audiences.includes(expectations.clientId)) {
+    throw new OidcError("token_audience", "the ID token was not issued for this application");
+  }
+  if (audiences.length > 1 && claims.azp && claims.azp !== expectations.clientId) {
+    throw new OidcError("token_audience", "the ID token's authorized party is not this application");
+  }
+  if (typeof claims.exp !== "number" || claims.exp * 1000 + EXPIRY_LEEWAY_MS < Date.now()) {
+    throw new OidcError("token_expired", "the ID token has expired");
+  }
+  if (claims.nonce !== expectations.nonce) {
+    throw new OidcError("token_nonce", "the ID token's nonce does not match the request");
+  }
+  return claims;
+}
+
+export function buildEndSessionUrl(
+  metadata: OidcMetadata,
+  params: { idTokenHint?: string | null; clientId: string; postLogoutRedirectUri: string },
+): string | null {
+  if (!metadata.end_session_endpoint) return null;
+  const url = new URL(metadata.end_session_endpoint);
+  if (params.idTokenHint) url.searchParams.set("id_token_hint", params.idTokenHint);
+  url.searchParams.set("client_id", params.clientId);
+  url.searchParams.set("post_logout_redirect_uri", params.postLogoutRedirectUri);
+  return url.toString();
+}