@thotischner/observability-mcp 1.7.0 → 1.8.1

package/dist/auth/oidc/client.js

@@ -0,0 +1,104 @@
+/**
+ * High-level OIDC client: glues discovery + JWKS + JWT verify + the
+ * auth-code+PKCE token exchange behind a single small surface.
+ *
+ * Designed to be wired into the existing session middleware in a
+ * later slice. This module stays HTTP-framework agnostic — the caller
+ * decides how to ferry the state/nonce/code_verifier between the
+ * `start()` redirect and the `complete()` callback (we recommend a
+ * short-lived signed cookie).
+ */
+import { DiscoveryClient } from "./discovery.js";
+import { JwksClient } from "./jwks.js";
+import { generatePkcePair } from "./pkce.js";
+import { verifyIdToken } from "./jwt.js";
+import { randomBytes } from "node:crypto";
+export class OidcClient {
+    discovery;
+    jwks;
+    cfg;
+    fetcher;
+    now;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.fetcher = cfg.fetcher ?? ((u, i) => fetch(u, i));
+        this.now = cfg.now ?? Date.now;
+        this.discovery = new DiscoveryClient({ fetcher: this.fetcher, now: this.now });
+        this.jwks = new JwksClient({ fetcher: this.fetcher, now: this.now });
+    }
+    /** Build an authorize URL + mint the state/nonce/PKCE-verifier the
+     * caller must persist until the callback. */
+    async start() {
+        const doc = await this.discovery.discover(this.cfg.issuer);
+        const pkce = generatePkcePair();
+        const state = base64url(randomBytes(24));
+        const nonce = base64url(randomBytes(24));
+        const params = new URLSearchParams({
+            response_type: "code",
+            client_id: this.cfg.clientId,
+            redirect_uri: this.cfg.redirectUri,
+            scope: this.cfg.scopes ?? "openid profile email",
+            state,
+            nonce,
+            code_challenge: pkce.challenge,
+            code_challenge_method: pkce.method,
+        });
+        return {
+            authorizeUrl: `${doc.authorization_endpoint}?${params.toString()}`,
+            flow: { state, nonce, codeVerifier: pkce.verifier },
+        };
+    }
+    /** Validate the callback: state match → token exchange → ID-token
+     *  signature + claim verification. Throws on any failure. */
+    async complete(opts) {
+        if (opts.state !== opts.flow.state)
+            throw new Error("OIDC callback: state mismatch");
+        const doc = await this.discovery.discover(this.cfg.issuer);
+        const body = new URLSearchParams({
+            grant_type: "authorization_code",
+            code: opts.code,
+            redirect_uri: this.cfg.redirectUri,
+            client_id: this.cfg.clientId,
+            code_verifier: opts.flow.codeVerifier,
+        });
+        const headers = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+        if (this.cfg.clientSecret) {
+            const basic = Buffer.from(`${encodeURIComponent(this.cfg.clientId)}:${encodeURIComponent(this.cfg.clientSecret)}`).toString("base64");
+            headers.authorization = `Basic ${basic}`;
+        }
+        const res = await this.fetcher(doc.token_endpoint, { method: "POST", headers, body: body.toString() });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`OIDC token exchange failed: HTTP ${res.status} ${text}`);
+        }
+        const tokens = (await res.json());
+        if (!tokens.id_token)
+            throw new Error("OIDC token response missing id_token");
+        const claims = await this.verify(tokens.id_token, doc, opts.flow.nonce);
+        return { claims, idToken: tokens.id_token, accessToken: tokens.access_token };
+    }
+    /** Verify a standalone ID token (refresh flows, replay checks). */
+    async verify(idToken, doc, nonce) {
+        const d = doc ?? (await this.discovery.discover(this.cfg.issuer));
+        const header = parseHeader(idToken);
+        const key = await this.jwks.findKey(d.jwks_uri, header.kid);
+        if (!key)
+            throw new Error(`OIDC: no JWKS key for kid=${header.kid ?? "?"}`);
+        return verifyIdToken(idToken, [key], {
+            issuer: this.cfg.issuer,
+            audience: this.cfg.clientId,
+            nonce,
+            now: this.now,
+        });
+    }
+}
+function base64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function parseHeader(jwt) {
+    const [h] = jwt.split(".");
+    if (!h)
+        throw new Error("malformed JWT");
+    const pad = h.length % 4 === 0 ? "" : "=".repeat(4 - (h.length % 4));
+    return JSON.parse(Buffer.from(h.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8"));
+}

package/dist/auth/oidc/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/oidc/client.test.js

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync, createPublicKey, createSign } from "node:crypto";
+import { OidcClient } from "./client.js";
+function b64u(s) {
+    const b = typeof s === "string" ? Buffer.from(s, "utf8") : s;
+    return b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// PEM-encoded sign — see jwt.test.ts for the Node-version-stability
+// reason this avoids the raw KeyObject destructure path.
+function signRs256(payload, privateKeyPem, kid) {
+    const header = b64u(JSON.stringify({ alg: "RS256", typ: "JWT", kid }));
+    const body = b64u(JSON.stringify(payload));
+    const signer = createSign("RSA-SHA256");
+    signer.update(`${header}.${body}`);
+    signer.end();
+    return `${header}.${body}.${b64u(signer.sign(privateKeyPem))}`;
+}
+function rsaKey() {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const jwk = createPublicKey(publicKey).export({ format: "jwk" });
+    jwk.kid = "test-kid";
+    return { jwk, privateKeyPem: privateKey };
+}
+function makeFetcher(handlers) {
+    return async (url, init) => {
+        for (const [pattern, handler] of Object.entries(handlers)) {
+            if (url === pattern)
+                return Promise.resolve(handler(init));
+        }
+        return new Response("not found", { status: 404 });
+    };
+}
+const ISSUER = "https://idp.test";
+const DISCOVERY = {
+    issuer: ISSUER,
+    authorization_endpoint: `${ISSUER}/auth`,
+    token_endpoint: `${ISSUER}/token`,
+    jwks_uri: `${ISSUER}/jwks`,
+};
+test("OidcClient.start — builds authorize URL with PKCE + nonce + state", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    const r = await client.start();
+    const u = new URL(r.authorizeUrl);
+    assert.equal(u.origin + u.pathname, `${ISSUER}/auth`);
+    assert.equal(u.searchParams.get("response_type"), "code");
+    assert.equal(u.searchParams.get("client_id"), "c-1");
+    assert.equal(u.searchParams.get("redirect_uri"), "https://app.test/cb");
+    assert.equal(u.searchParams.get("code_challenge_method"), "S256");
+    assert.ok(u.searchParams.get("code_challenge"));
+    assert.equal(u.searchParams.get("state"), r.flow.state);
+    assert.equal(u.searchParams.get("nonce"), r.flow.nonce);
+    assert.ok(r.flow.codeVerifier.length >= 43);
+});
+test("OidcClient.complete — verifies state, exchanges code, verifies id_token", async () => {
+    const { jwk, privateKeyPem } = rsaKey();
+    const now = 1_700_000_000;
+    const flow = { state: "S", nonce: "N", codeVerifier: "V_43charsminimum_______________________________________________" };
+    const idToken = signRs256({ iss: ISSUER, aud: "c-1", sub: "alice", exp: now + 60, iat: now, nonce: "N" }, privateKeyPem, jwk.kid);
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+        [`${ISSUER}/jwks`]: () => new Response(JSON.stringify({ keys: [jwk] }), { status: 200 }),
+        [`${ISSUER}/token`]: () => new Response(JSON.stringify({ id_token: idToken, access_token: "AT" }), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher, now: () => now * 1000 });
+    const r = await client.complete({ code: "ABC", state: "S", flow });
+    assert.equal(r.claims.sub, "alice");
+    assert.equal(r.accessToken, "AT");
+});
+test("OidcClient.complete — rejects state mismatch", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    await assert.rejects(client.complete({ code: "x", state: "wrong", flow: { state: "real", nonce: "n", codeVerifier: "v" } }), /state mismatch/);
+});
+test("OidcClient.complete — surfaces token-endpoint failures", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+        [`${ISSUER}/token`]: () => new Response(JSON.stringify({ error: "invalid_grant" }), { status: 400 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    await assert.rejects(client.complete({ code: "x", state: "S", flow: { state: "S", nonce: "n", codeVerifier: "v" } }), /HTTP 400/);
+});
+test("OidcClient.complete — rejects missing id_token in token response", async () => {
+    const fetcher = makeFetcher({
+        [`${ISSUER}/.well-known/openid-configuration`]: () => new Response(JSON.stringify(DISCOVERY), { status: 200 }),
+        [`${ISSUER}/token`]: () => new Response(JSON.stringify({ access_token: "AT" }), { status: 200 }),
+    });
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", redirectUri: "https://app.test/cb", fetcher });
+    await assert.rejects(client.complete({ code: "x", state: "S", flow: { state: "S", nonce: "n", codeVerifier: "v" } }), /missing id_token/);
+});
+test("OidcClient.complete — uses Basic auth when clientSecret set", async () => {
+    const { jwk, privateKeyPem } = rsaKey();
+    const now = 1_700_000_000;
+    const idToken = signRs256({ iss: ISSUER, aud: "c-1", sub: "alice", exp: now + 60, iat: now, nonce: "n" }, privateKeyPem, jwk.kid);
+    let captured;
+    const fetcher = async (url, init) => {
+        if (url === `${ISSUER}/.well-known/openid-configuration`)
+            return new Response(JSON.stringify(DISCOVERY), { status: 200 });
+        if (url === `${ISSUER}/jwks`)
+            return new Response(JSON.stringify({ keys: [jwk] }), { status: 200 });
+        if (url === `${ISSUER}/token`) {
+            captured = (init?.headers).authorization;
+            return new Response(JSON.stringify({ id_token: idToken }), { status: 200 });
+        }
+        return new Response("nf", { status: 404 });
+    };
+    const client = new OidcClient({ issuer: ISSUER, clientId: "c-1", clientSecret: "shh", redirectUri: "https://app.test/cb", fetcher, now: () => now * 1000 });
+    await client.complete({ code: "x", state: "S", flow: { state: "S", nonce: "n", codeVerifier: "v" } });
+    assert.ok(captured?.startsWith("Basic "));
+    const decoded = Buffer.from(captured.slice("Basic ".length), "base64").toString();
+    assert.equal(decoded, "c-1:shh");
+});

package/dist/auth/oidc/discovery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OIDC discovery-document fetcher with TTL cache.
+ *
+ * Resolves an issuer URL into the endpoint set the rest of the OIDC
+ * code-flow needs. Caches per-issuer for a configurable TTL (default
+ * 1 hour) — IdPs publish stable URLs but rotate them occasionally.
+ *
+ * `fetcher` is injectable so unit tests don't need a real network.
+ */
+export interface DiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    userinfo_endpoint?: string;
+    end_session_endpoint?: string;
+    response_types_supported?: string[];
+    id_token_signing_alg_values_supported?: string[];
+    scopes_supported?: string[];
+    [k: string]: unknown;
+}
+export type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+export interface DiscoveryClientOpts {
+    fetcher?: Fetcher;
+    ttlMs?: number;
+    now?: () => number;
+}
+export declare class DiscoveryClient {
+    private readonly fetcher;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly cache;
+    constructor(opts?: DiscoveryClientOpts);
+    /** Discover the OP metadata for the given issuer URL. */
+    discover(issuer: string): Promise<DiscoveryDocument>;
+    /** Drop the cache (test helper / manual rotation). */
+    invalidate(issuer?: string): void;
+}

package/dist/auth/oidc/discovery.js

@@ -0,0 +1,48 @@
+/**
+ * OIDC discovery-document fetcher with TTL cache.
+ *
+ * Resolves an issuer URL into the endpoint set the rest of the OIDC
+ * code-flow needs. Caches per-issuer for a configurable TTL (default
+ * 1 hour) — IdPs publish stable URLs but rotate them occasionally.
+ *
+ * `fetcher` is injectable so unit tests don't need a real network.
+ */
+export class DiscoveryClient {
+    fetcher;
+    ttlMs;
+    now;
+    cache = new Map();
+    constructor(opts = {}) {
+        this.fetcher = opts.fetcher ?? ((u, i) => fetch(u, i));
+        this.ttlMs = opts.ttlMs ?? 3_600_000;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Discover the OP metadata for the given issuer URL. */
+    async discover(issuer) {
+        const cached = this.cache.get(issuer);
+        if (cached && cached.expiresAt > this.now())
+            return cached.doc;
+        const url = issuer.replace(/\/$/, "") + "/.well-known/openid-configuration";
+        const res = await this.fetcher(url);
+        if (!res.ok)
+            throw new Error(`OIDC discovery failed for ${issuer}: HTTP ${res.status}`);
+        const doc = (await res.json());
+        // Spec §4.3 — issuer in the doc MUST exactly equal the requested
+        // issuer (defends against open-redirect-style metadata swaps).
+        if (doc.issuer !== issuer) {
+            throw new Error(`OIDC discovery issuer mismatch: requested ${issuer}, document advertised ${doc.issuer}`);
+        }
+        if (!doc.authorization_endpoint || !doc.token_endpoint || !doc.jwks_uri) {
+            throw new Error(`OIDC discovery document for ${issuer} is missing required endpoints`);
+        }
+        this.cache.set(issuer, { doc, expiresAt: this.now() + this.ttlMs });
+        return doc;
+    }
+    /** Drop the cache (test helper / manual rotation). */
+    invalidate(issuer) {
+        if (issuer)
+            this.cache.delete(issuer);
+        else
+            this.cache.clear();
+    }
+}

package/dist/auth/oidc/discovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/oidc/discovery.test.js

@@ -0,0 +1,68 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { DiscoveryClient } from "./discovery.js";
+function mockFetch(map) {
+    return async (url) => {
+        const r = map[url];
+        if (!r)
+            return new Response("not found", { status: 404 });
+        return new Response(JSON.stringify(r.body), { status: r.status, headers: { "content-type": "application/json" } });
+    };
+}
+const happyDoc = {
+    issuer: "https://idp.test",
+    authorization_endpoint: "https://idp.test/auth",
+    token_endpoint: "https://idp.test/token",
+    jwks_uri: "https://idp.test/jwks",
+};
+test("DiscoveryClient — fetches and returns the doc", async () => {
+    const client = new DiscoveryClient({
+        fetcher: mockFetch({ "https://idp.test/.well-known/openid-configuration": { status: 200, body: happyDoc } }),
+    });
+    const d = await client.discover("https://idp.test");
+    assert.equal(d.token_endpoint, "https://idp.test/token");
+});
+test("DiscoveryClient — caches within TTL, refetches after expiry", async () => {
+    let calls = 0;
+    const fetcher = async (url) => {
+        calls++;
+        return new Response(JSON.stringify(happyDoc), { status: 200 });
+    };
+    let now = 1_000_000;
+    const client = new DiscoveryClient({ fetcher, ttlMs: 5_000, now: () => now });
+    await client.discover("https://idp.test");
+    await client.discover("https://idp.test");
+    assert.equal(calls, 1, "second call within TTL should hit cache");
+    now += 6_000;
+    await client.discover("https://idp.test");
+    assert.equal(calls, 2, "after TTL expiry a fresh fetch should happen");
+});
+test("DiscoveryClient — rejects HTTP failure", async () => {
+    const client = new DiscoveryClient({
+        fetcher: mockFetch({ "https://idp.test/.well-known/openid-configuration": { status: 500, body: { error: "boom" } } }),
+    });
+    await assert.rejects(client.discover("https://idp.test"), /HTTP 500/);
+});
+test("DiscoveryClient — rejects issuer mismatch (RFC 8414 §3)", async () => {
+    const lying = { ...happyDoc, issuer: "https://other.example" };
+    const client = new DiscoveryClient({
+        fetcher: mockFetch({ "https://idp.test/.well-known/openid-configuration": { status: 200, body: lying } }),
+    });
+    await assert.rejects(client.discover("https://idp.test"), /issuer mismatch/);
+});
+test("DiscoveryClient — rejects missing required endpoints", async () => {
+    const broken = { issuer: "https://idp.test" };
+    const client = new DiscoveryClient({
+        fetcher: mockFetch({ "https://idp.test/.well-known/openid-configuration": { status: 200, body: broken } }),
+    });
+    await assert.rejects(client.discover("https://idp.test"), /missing required endpoints/);
+});
+test("DiscoveryClient — trailing slash on issuer is normalised", async () => {
+    let captured = "";
+    const client = new DiscoveryClient({
+        fetcher: async (url) => { captured = url; return new Response(JSON.stringify({ ...happyDoc, issuer: "https://idp.test/" }), { status: 200 }); },
+    });
+    // Caller passes issuer with trailing slash; URL should still be canonical.
+    await client.discover("https://idp.test/");
+    assert.equal(captured, "https://idp.test/.well-known/openid-configuration");
+});

package/dist/auth/oidc/endpoints.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Express handlers for the OIDC code flow.
+ *
+ *   GET  /api/auth/oidc/login     redirect to IdP
+ *   GET  /api/auth/oidc/callback  exchange code → mint OMCP session
+ *   POST /api/auth/oidc/logout    clear session (+ optional IdP RP-init logout)
+ *
+ * The handlers are HTTP-framework-aware (they use Express's Request /
+ * Response) but otherwise pure; the OIDC client + role resolver come
+ * from the runtime built in `./runtime.ts`.
+ */
+import type { Application } from "express";
+import type { OidcRuntime } from "./runtime.js";
+import { type SessionConfig } from "../session.js";
+export interface OidcEndpointDeps {
+    sessionCfg: SessionConfig;
+    oidc: OidcRuntime;
+}
+/** Register the three OIDC endpoints on the given Express app. */
+export declare function registerOidcRoutes(app: Application, deps: OidcEndpointDeps): void;

package/dist/auth/oidc/endpoints.js

@@ -0,0 +1,124 @@
+/**
+ * Express handlers for the OIDC code flow.
+ *
+ *   GET  /api/auth/oidc/login     redirect to IdP
+ *   GET  /api/auth/oidc/callback  exchange code → mint OMCP session
+ *   POST /api/auth/oidc/logout    clear session (+ optional IdP RP-init logout)
+ *
+ * The handlers are HTTP-framework-aware (they use Express's Request /
+ * Response) but otherwise pure; the OIDC client + role resolver come
+ * from the runtime built in `./runtime.ts`.
+ */
+import { issueSession, setCookieHeader, clearCookieHeader } from "../session.js";
+import { issueFlowCookie, verifyFlowCookie, setFlowCookieHeader, clearFlowCookieHeader, readFlowCookie, isSafeReturnTo, } from "./flow-cookie.js";
+function isSecure(req) {
+    return req.secure || req.headers["x-forwarded-proto"] === "https";
+}
+/** Register the three OIDC endpoints on the given Express app. */
+export function registerOidcRoutes(app, deps) {
+    const { sessionCfg, oidc } = deps;
+    const flowCfg = { secret: sessionCfg.secret };
+    app.get("/api/auth/oidc/login", async (req, res) => {
+        try {
+            const requested = typeof req.query.return_to === "string" ? req.query.return_to : "/";
+            const returnTo = isSafeReturnTo(requested) ? requested : "/";
+            const start = await oidc.client.start();
+            const cookie = issueFlowCookie({ state: start.flow.state, nonce: start.flow.nonce, codeVerifier: start.flow.codeVerifier, returnTo }, flowCfg);
+            res.setHeader("Set-Cookie", setFlowCookieHeader(cookie, flowCfg, { secure: isSecure(req) }));
+            res.redirect(302, start.authorizeUrl);
+        }
+        catch (e) {
+            respondError(res, 502, "oidc_start_failed", e.message);
+        }
+    });
+    app.get("/api/auth/oidc/callback", async (req, res) => {
+        const code = typeof req.query.code === "string" ? req.query.code : "";
+        const state = typeof req.query.state === "string" ? req.query.state : "";
+        const errParam = typeof req.query.error === "string" ? req.query.error : "";
+        if (errParam) {
+            // The IdP redirected with an error (user cancelled, consent
+            // denied, …). Surface plainly; no token exchange needed.
+            res.setHeader("Set-Cookie", clearFlowCookieHeader(flowCfg, { secure: isSecure(req) }));
+            respondError(res, 400, "oidc_idp_error", errParam);
+            return;
+        }
+        if (!code || !state) {
+            // Symmetric with the other early-return paths — once the
+            // callback aborts, the flow cookie has no further use; clearing
+            // it eagerly avoids reuse on a refresh.
+            res.setHeader("Set-Cookie", clearFlowCookieHeader(flowCfg, { secure: isSecure(req) }));
+            respondError(res, 400, "oidc_missing_code_or_state", "callback requires both code and state query params");
+            return;
+        }
+        const flowCookieValue = readFlowCookie(req.headers.cookie);
+        const flow = verifyFlowCookie(flowCookieValue, flowCfg);
+        if (!flow) {
+            respondError(res, 400, "oidc_flow_cookie_missing", "no valid flow cookie (expired or absent — please restart login)");
+            return;
+        }
+        let result;
+        try {
+            result = await oidc.client.complete({
+                code,
+                state,
+                flow: { state: flow.state, nonce: flow.nonce, codeVerifier: flow.codeVerifier },
+            });
+        }
+        catch (e) {
+            res.setHeader("Set-Cookie", clearFlowCookieHeader(flowCfg, { secure: isSecure(req) }));
+            respondError(res, 400, "oidc_token_exchange_failed", e.message);
+            return;
+        }
+        const claims = result.claims;
+        const sub = sanitiseClaim(claims.sub) ?? "unknown";
+        const name = sanitiseClaim(claims.name)
+            ?? sanitiseClaim(claims.preferred_username)
+            ?? sanitiseClaim(claims.email)
+            ?? sub;
+        // Only persist email when the IdP marked it verified — an
+        // unverified email is operator-supplied user input from the
+        // IdP's perspective and shouldn't appear next to a name in
+        // an admin UI as if it were authoritative. When the claim is
+        // absent we trust it (most IdPs default to verified for the
+        // primary identity).
+        const emailVerified = claims.email_verified === undefined || claims.email_verified === true;
+        const email = emailVerified ? sanitiseClaim(claims.email) : undefined;
+        const roles = oidc.resolveRoles(claims);
+        const tenant = oidc.resolveTenant(claims);
+        const { cookie } = issueSession({ sub, name, email, roles, tenant }, sessionCfg);
+        // Two cookies: clear the now-spent flow cookie, set the long-lived
+        // session cookie. The browser accepts both in a single response.
+        res.setHeader("Set-Cookie", [
+            clearFlowCookieHeader(flowCfg, { secure: isSecure(req) }),
+            setCookieHeader(cookie, sessionCfg, { secure: isSecure(req) }),
+        ]);
+        res.redirect(302, flow.returnTo);
+    });
+    app.post("/api/auth/oidc/logout", (req, res) => {
+        res.setHeader("Set-Cookie", clearCookieHeader(sessionCfg, { secure: isSecure(req) }));
+        // RP-initiated logout via the discovery doc's end_session_endpoint
+        // is intentionally out of scope for slice 3 (we'd need to ferry
+        // the id_token through the session payload). Operators wanting an
+        // IdP-side logout can configure `OMCP_OIDC_LOGOUT_REDIRECT` to
+        // point at their IdP's end-session URL — we 200 here and the UI
+        // navigates the user.
+        res.status(204).end();
+    });
+}
+function respondError(res, status, code, message) {
+    res.status(status).json({ error: code, message });
+}
+/** Normalise an IdP-provided claim before we stuff it in the session
+ *  cookie: must be a non-empty string, length-capped (so a hostile
+ *  IdP can't blow up the cookie), control-character-stripped (so
+ *  downstream UIs that render it via innerHTML aren't a vector).
+ *  Returns undefined when the claim isn't usable. */
+function sanitiseClaim(v) {
+    if (typeof v !== "string")
+        return undefined;
+    // Strip control characters; keep printable.
+    const cleaned = v.replace(/[\x00-\x1f\x7f]/g, "").trim();
+    if (cleaned.length === 0)
+        return undefined;
+    return cleaned.slice(0, 200);
+}

package/dist/auth/oidc/endpoints.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Integration test for the three OIDC HTTP endpoints. Boots a real
+ * Express app, registers the routes against a stubbed OidcClient
+ * (mock fetcher) so the IdP round-trip is in-process, and walks
+ * through the redirect → callback → session-cookie flow end-to-end.
+ */
+export {};