@thotischner/observability-mcp 1.7.1 → 1.8.1

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

@@ -0,0 +1,65 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { JwksClient } from "./jwks.js";
+const jwks1 = { keys: [{ kty: "RSA", kid: "k-1", n: "abc", e: "AQAB" }] };
+const jwks12 = { keys: [
+        { kty: "RSA", kid: "k-1", n: "abc", e: "AQAB" },
+        { kty: "RSA", kid: "k-2", n: "def", e: "AQAB" },
+    ] };
+test("JwksClient.get — fetches and caches", async () => {
+    let calls = 0;
+    const client = new JwksClient({
+        fetcher: async () => { calls++; return new Response(JSON.stringify(jwks1), { status: 200 }); },
+        ttlMs: 60_000,
+    });
+    await client.get("https://idp.test/jwks");
+    await client.get("https://idp.test/jwks");
+    assert.equal(calls, 1);
+});
+test("JwksClient.findKey — returns key by kid on first try", async () => {
+    const client = new JwksClient({ fetcher: async () => new Response(JSON.stringify(jwks12), { status: 200 }) });
+    const key = await client.findKey("https://idp.test/jwks", "k-2");
+    assert.equal(key?.kid, "k-2");
+});
+test("JwksClient.findKey — refreshes once on unknown kid (key rotation)", async () => {
+    let calls = 0;
+    const responses = [jwks1, jwks12]; // First response missing k-2, second has it.
+    const client = new JwksClient({
+        fetcher: async () => { const body = responses[Math.min(calls, responses.length - 1)]; calls++; return new Response(JSON.stringify(body), { status: 200 }); },
+        refreshCooldownMs: 0,
+    });
+    const key = await client.findKey("https://idp.test/jwks", "k-2");
+    assert.equal(calls, 2, "expected one forced refresh after cache miss");
+    assert.equal(key?.kid, "k-2");
+});
+test("JwksClient.findKey — respects refresh cooldown on repeated misses", async () => {
+    let calls = 0;
+    let now = 1_000_000;
+    const client = new JwksClient({
+        fetcher: async () => { calls++; return new Response(JSON.stringify(jwks1), { status: 200 }); },
+        refreshCooldownMs: 60_000,
+        now: () => now,
+    });
+    // First miss → fetch + forced refresh = 2 calls
+    await client.findKey("https://idp.test/jwks", "k-unknown");
+    assert.equal(calls, 2);
+    // Same miss inside cooldown → no further fetch
+    await client.findKey("https://idp.test/jwks", "k-unknown");
+    assert.equal(calls, 2);
+    // After cooldown expires, one more forced refresh
+    now += 61_000;
+    await client.findKey("https://idp.test/jwks", "k-unknown");
+    assert.equal(calls, 3);
+});
+test("JwksClient.get — rejects malformed JWKS body", async () => {
+    const client = new JwksClient({
+        fetcher: async () => new Response(JSON.stringify({ not: "a jwks" }), { status: 200 }),
+    });
+    await assert.rejects(client.get("https://idp.test/jwks"), /not a valid JWKS/);
+});
+test("JwksClient.get — rejects HTTP failure", async () => {
+    const client = new JwksClient({
+        fetcher: async () => new Response("nope", { status: 500 }),
+    });
+    await assert.rejects(client.get("https://idp.test/jwks"), /HTTP 500/);
+});

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

@@ -0,0 +1,62 @@
+/**
+ * Minimal RFC 7519 JWT verifier scoped to OIDC ID tokens.
+ *
+ * Supports the two signature algorithms every real-world OIDC IdP
+ * speaks: RS256 and ES256. HS256 is intentionally excluded — for an
+ * OIDC code flow the client never shares an HMAC secret with the IdP.
+ * "none" is rejected as a matter of basic hygiene.
+ *
+ * The verifier does *not* fetch JWKS — it expects a JWK keyset
+ * already cached by the caller. See `./jwks.ts` for the cache.
+ */
+import { type KeyObject } from "node:crypto";
+export interface Jwk {
+    kty: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+    n?: string;
+    e?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+}
+export interface JwtHeader {
+    alg: string;
+    kid?: string;
+    typ?: string;
+}
+export interface JwtPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    nonce?: string;
+    [k: string]: unknown;
+}
+export interface VerifyOpts {
+    /** Expected `iss` claim — exact match. */
+    issuer: string;
+    /** Expected `aud` claim — match if `aud` is a string equal to this,
+     *  or an array including this. */
+    audience: string;
+    /** Expected `nonce` — must match the value tied to the auth-code
+     *  flow's state cookie. */
+    nonce?: string;
+    /** Clock-skew tolerance in seconds; default 30. */
+    clockSkewSec?: number;
+    /** Override `now` for tests (ms since epoch). */
+    now?: () => number;
+}
+export declare class JwtVerifyError extends Error {
+    constructor(msg: string);
+}
+/** Decode base64url to a Buffer (handles missing padding). */
+export declare function b64urlDecode(s: string): Buffer;
+/** Convert a JWK to a node KeyObject for verification. */
+export declare function jwkToKey(jwk: Jwk): KeyObject;
+/** Verify a compact-serialised JWT against a keyset (JWKS `keys` array)
+ * and return its payload. Throws JwtVerifyError on any failure. */
+export declare function verifyIdToken(jwt: string, keys: Jwk[], opts: VerifyOpts): JwtPayload;

package/dist/auth/oidc/jwt.js

@@ -0,0 +1,113 @@
+/**
+ * Minimal RFC 7519 JWT verifier scoped to OIDC ID tokens.
+ *
+ * Supports the two signature algorithms every real-world OIDC IdP
+ * speaks: RS256 and ES256. HS256 is intentionally excluded — for an
+ * OIDC code flow the client never shares an HMAC secret with the IdP.
+ * "none" is rejected as a matter of basic hygiene.
+ *
+ * The verifier does *not* fetch JWKS — it expects a JWK keyset
+ * already cached by the caller. See `./jwks.ts` for the cache.
+ */
+import { createPublicKey, createVerify } from "node:crypto";
+export class JwtVerifyError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "JwtVerifyError";
+    }
+}
+/** Decode base64url to a Buffer (handles missing padding). */
+export function b64urlDecode(s) {
+    const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+    return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64");
+}
+function decodeJson(b64) {
+    return JSON.parse(b64urlDecode(b64).toString("utf8"));
+}
+/** Convert a JWK to a node KeyObject for verification. */
+export function jwkToKey(jwk) {
+    // Node accepts JWK directly via `format: "jwk"` since Node 16.
+    return createPublicKey({ key: jwk, format: "jwk" });
+}
+/** Verify a compact-serialised JWT against a keyset (JWKS `keys` array)
+ * and return its payload. Throws JwtVerifyError on any failure. */
+export function verifyIdToken(jwt, keys, opts) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3)
+        throw new JwtVerifyError("malformed JWT (expected 3 parts)");
+    const [headerB64, payloadB64, sigB64] = parts;
+    let header;
+    let payload;
+    try {
+        header = decodeJson(headerB64);
+        payload = decodeJson(payloadB64);
+    }
+    catch {
+        throw new JwtVerifyError("malformed JWT (header/payload not JSON)");
+    }
+    if (header.alg === "none" || !header.alg)
+        throw new JwtVerifyError(`disallowed alg: ${header.alg}`);
+    if (header.alg !== "RS256" && header.alg !== "ES256") {
+        throw new JwtVerifyError(`unsupported alg: ${header.alg}`);
+    }
+    // Pick the key by (kty, kid). When the header has a kid we require
+    // a matching JWK kid — accepting a kid-less JWK here would let a
+    // misconfigured JWKS with one untagged key validate tokens claiming
+    // any kid. The kid-less fallback only applies when the header
+    // itself doesn't carry one (single-key IdP / very old tokens).
+    const wantedKty = header.alg === "RS256" ? "RSA" : "EC";
+    let candidates = keys.filter((k) => k.kty === wantedKty);
+    if (header.kid)
+        candidates = candidates.filter((k) => k.kid === header.kid);
+    if (candidates.length === 0)
+        throw new JwtVerifyError(`no JWK matches kid=${header.kid ?? "?"} kty=${wantedKty}`);
+    const signingInput = Buffer.from(`${headerB64}.${payloadB64}`, "utf8");
+    const signature = b64urlDecode(sigB64);
+    let verified = false;
+    let lastErr;
+    for (const jwk of candidates) {
+        try {
+            const key = jwkToKey(jwk);
+            if (header.alg === "RS256") {
+                const v = createVerify("RSA-SHA256");
+                v.update(signingInput);
+                v.end();
+                if (v.verify(key, signature)) {
+                    verified = true;
+                    break;
+                }
+            }
+            else {
+                // ES256: signature is raw (R||S) 64 bytes. Node accepts that
+                // via `dsaEncoding: 'ieee-p1363'`.
+                const v = createVerify("SHA256");
+                v.update(signingInput);
+                v.end();
+                if (v.verify({ key, dsaEncoding: "ieee-p1363" }, signature)) {
+                    verified = true;
+                    break;
+                }
+            }
+        }
+        catch (e) {
+            lastErr = e;
+        }
+    }
+    if (!verified)
+        throw new JwtVerifyError(`signature verification failed${lastErr ? `: ${lastErr.message}` : ""}`);
+    // Claim checks
+    const now = Math.floor((opts.now ? opts.now() : Date.now()) / 1000);
+    const skew = opts.clockSkewSec ?? 30;
+    if (payload.iss !== opts.issuer)
+        throw new JwtVerifyError(`iss mismatch (expected ${opts.issuer}, got ${payload.iss ?? "?"})`);
+    const audOk = Array.isArray(payload.aud) ? payload.aud.includes(opts.audience) : payload.aud === opts.audience;
+    if (!audOk)
+        throw new JwtVerifyError(`aud mismatch (expected ${opts.audience}, got ${JSON.stringify(payload.aud)})`);
+    if (typeof payload.exp !== "number" || now - skew > payload.exp)
+        throw new JwtVerifyError("token expired");
+    if (typeof payload.nbf === "number" && now + skew < payload.nbf)
+        throw new JwtVerifyError("token not yet valid");
+    if (opts.nonce !== undefined && payload.nonce !== opts.nonce)
+        throw new JwtVerifyError("nonce mismatch");
+    return payload;
+}

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

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

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

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createSign, generateKeyPairSync, createPublicKey } from "node:crypto";
+import { verifyIdToken, b64urlDecode, JwtVerifyError } from "./jwt.js";
+function b64u(s) {
+    const b = typeof s === "string" ? Buffer.from(s, "utf8") : s;
+    return b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// Sign with a PEM-encoded private key. PEM strings work identically
+// across every Node version we ship on; raw KeyObject destructuring
+// of generateKeyPairSync hit a "Invalid key object type public,
+// expected private" error in CI's Node 20 (private/public swap
+// somewhere in the destructure result). PEM avoids the whole class.
+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();
+    const sig = b64u(signer.sign(privateKeyPem));
+    return `${header}.${body}.${sig}`;
+}
+function rsaKeypair() {
+    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-key-1";
+    return { jwk, privateKeyPem: privateKey };
+}
+test("b64urlDecode — round-trips standard and padded inputs", () => {
+    assert.equal(b64urlDecode("AQ").toString("hex"), "01");
+    assert.equal(b64urlDecode("-_-_").toString("hex"), "fbffbf");
+});
+test("verifyIdToken — happy path on RS256", () => {
+    const { jwk, privateKeyPem } = rsaKeypair();
+    const now = 1_700_000_000;
+    const payload = { iss: "https://idp.test", aud: "client-1", sub: "alice", exp: now + 60, iat: now, nonce: "n-1" };
+    const jwt = signRs256(payload, privateKeyPem, jwk.kid);
+    const out = verifyIdToken(jwt, [jwk], { issuer: "https://idp.test", audience: "client-1", nonce: "n-1", now: () => now * 1000 });
+    assert.equal(out.sub, "alice");
+});
+test("verifyIdToken — rejects alg=none", () => {
+    const header = b64u(JSON.stringify({ alg: "none", typ: "JWT" }));
+    const body = b64u(JSON.stringify({ iss: "x", aud: "x", exp: 9_999_999_999 }));
+    const jwt = `${header}.${body}.`;
+    assert.throws(() => verifyIdToken(jwt, [], { issuer: "x", audience: "x" }), JwtVerifyError);
+});
+test("verifyIdToken — rejects unsupported alg (HS256)", () => {
+    const header = b64u(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+    const body = b64u(JSON.stringify({ iss: "x", aud: "x", exp: 9_999_999_999 }));
+    const jwt = `${header}.${body}.AAAA`;
+    assert.throws(() => verifyIdToken(jwt, [], { issuer: "x", audience: "x" }), /unsupported alg/);
+});
+test("verifyIdToken — rejects expired token (beyond clock skew)", () => {
+    const { jwk, privateKeyPem } = rsaKeypair();
+    const now = 1_700_000_000;
+    const jwt = signRs256({ iss: "https://idp.test", aud: "c", exp: now - 1000 }, privateKeyPem, jwk.kid);
+    assert.throws(() => verifyIdToken(jwt, [jwk], { issuer: "https://idp.test", audience: "c", now: () => now * 1000 }), /expired/);
+});
+test("verifyIdToken — rejects iss / aud / nonce mismatch", () => {
+    const { jwk, privateKeyPem } = rsaKeypair();
+    const now = 1_700_000_000;
+    const jwt = signRs256({ iss: "https://idp.test", aud: "c", exp: now + 60, nonce: "real" }, privateKeyPem, jwk.kid);
+    assert.throws(() => verifyIdToken(jwt, [jwk], { issuer: "wrong", audience: "c", now: () => now * 1000 }), /iss mismatch/);
+    assert.throws(() => verifyIdToken(jwt, [jwk], { issuer: "https://idp.test", audience: "wrong", now: () => now * 1000 }), /aud mismatch/);
+    assert.throws(() => verifyIdToken(jwt, [jwk], { issuer: "https://idp.test", audience: "c", nonce: "other", now: () => now * 1000 }), /nonce mismatch/);
+});
+test("verifyIdToken — aud as array including expected", () => {
+    const { jwk, privateKeyPem } = rsaKeypair();
+    const now = 1_700_000_000;
+    const jwt = signRs256({ iss: "https://idp.test", aud: ["c", "other"], exp: now + 60 }, privateKeyPem, jwk.kid);
+    const out = verifyIdToken(jwt, [jwk], { issuer: "https://idp.test", audience: "c", now: () => now * 1000 });
+    assert.deepEqual(out.aud, ["c", "other"]);
+});
+test("verifyIdToken — bad signature is rejected", () => {
+    const { jwk, privateKeyPem } = rsaKeypair();
+    const now = 1_700_000_000;
+    const jwt = signRs256({ iss: "https://idp.test", aud: "c", exp: now + 60 }, privateKeyPem, jwk.kid);
+    // Flip the FIRST char of the signature. Every bit of position-0
+    // contributes to the decoded bytes; the LAST char of a 342-char
+    // signature (RSA-2048 → 256 bytes = 4·85+2) shares a 12-bit
+    // window encoding only 8 useful bits, so its bottom 4 bits are
+    // discarded — flipping A↔B there preserved the decoded byte and
+    // the signature still verified, making the test flaky.
+    const parts = jwt.split(".");
+    const sig = parts[2];
+    const first = sig.charAt(0);
+    const flipped = first >= "A" && first <= "Z" ? first.toLowerCase()
+        : first >= "a" && first <= "z" ? first.toUpperCase()
+            : first === "_" ? "-" : "_";
+    const tampered = `${parts[0]}.${parts[1]}.${flipped}${sig.slice(1)}`;
+    assert.throws(() => verifyIdToken(tampered, [jwk], { issuer: "https://idp.test", audience: "c", now: () => now * 1000 }), /signature verification failed/);
+});
+test("verifyIdToken — happy path on ES256 (P-256 EC key)", () => {
+    // PEM-encode for the same Node-version-stability reason as RS256
+    // above.
+    const { publicKey, privateKey } = generateKeyPairSync("ec", {
+        namedCurve: "P-256",
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const jwk = createPublicKey(publicKey).export({ format: "jwk" });
+    jwk.kid = "ec-key-1";
+    const now = 1_700_000_000;
+    const header = b64u(JSON.stringify({ alg: "ES256", typ: "JWT", kid: jwk.kid }));
+    const body = b64u(JSON.stringify({ iss: "https://idp.test", aud: "client-1", sub: "bob", exp: now + 60 }));
+    // Node's default ECDSA signature is DER; convert to raw R||S 64-byte
+    // ieee-p1363 for JWS spec compliance.
+    const signer = createSign("SHA256");
+    signer.update(`${header}.${body}`);
+    signer.end();
+    const sig = signer.sign({ key: privateKey, dsaEncoding: "ieee-p1363" });
+    assert.equal(sig.length, 64, "ES256 raw signature must be 64 bytes");
+    const jwt = `${header}.${body}.${b64u(sig)}`;
+    const out = verifyIdToken(jwt, [jwk], { issuer: "https://idp.test", audience: "client-1", now: () => now * 1000 });
+    assert.equal(out.sub, "bob");
+});
+test("verifyIdToken — strict kid match: header kid does not silently match kid-less JWK", () => {
+    const { jwk, privateKeyPem } = rsaKeypair();
+    // JWK with NO kid in the keyset
+    const untagged = { ...jwk };
+    delete untagged.kid;
+    const now = 1_700_000_000;
+    // Token claims kid=ghost — JWK doesn't have one, must reject.
+    const jwt = signRs256({ iss: "i", aud: "c", exp: now + 60 }, privateKeyPem, "ghost-kid");
+    assert.throws(() => verifyIdToken(jwt, [untagged], { issuer: "i", audience: "c", now: () => now * 1000 }), /no JWK matches kid=ghost-kid/);
+});
+test("verifyIdToken — picks key by kid when JWKS has multiple", () => {
+    const a = rsaKeypair();
+    a.jwk.kid = "k-a";
+    const b = rsaKeypair();
+    b.jwk.kid = "k-b";
+    const now = 1_700_000_000;
+    const jwt = signRs256({ iss: "i", aud: "c", exp: now + 60 }, b.privateKeyPem, "k-b");
+    // Both keys in the JWKS — verifier should reach for k-b.
+    const out = verifyIdToken(jwt, [a.jwk, b.jwk], { issuer: "i", audience: "c", now: () => now * 1000 });
+    assert.equal(out.iss, "i");
+});

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

@@ -0,0 +1,19 @@
+/**
+ * PKCE (RFC 7636) helpers for the OIDC authorization-code flow.
+ *
+ * The `S256` method only — `plain` is disallowed by spec for native /
+ * SPA clients and we have no reason to weaken it. Verifier length
+ * follows the RFC's recommended 43–128 unreserved-char range.
+ */
+/** Base64url-encode a Buffer (RFC 4648 §5, no padding). */
+export declare function base64url(buf: Buffer): string;
+/** Generate a fresh PKCE code_verifier — 64 unreserved chars. */
+export declare function generateCodeVerifier(): string;
+/** Derive the S256 code_challenge from a verifier. */
+export declare function challengeFromVerifier(verifier: string): string;
+/** Convenience: fresh {verifier, challenge} pair. */
+export declare function generatePkcePair(): {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+};

package/dist/auth/oidc/pkce.js

@@ -0,0 +1,43 @@
+/**
+ * PKCE (RFC 7636) helpers for the OIDC authorization-code flow.
+ *
+ * The `S256` method only — `plain` is disallowed by spec for native /
+ * SPA clients and we have no reason to weaken it. Verifier length
+ * follows the RFC's recommended 43–128 unreserved-char range.
+ */
+import { createHash, randomBytes } from "node:crypto";
+const UNRESERVED = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+/** Base64url-encode a Buffer (RFC 4648 §5, no padding). */
+export function base64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Generate a fresh PKCE code_verifier — 64 unreserved chars. */
+export function generateCodeVerifier() {
+    // Uniform-sample one unreserved char per output position via
+    // rejection sampling: 256 mod 66 = 58, so bytes in [0, 198) map
+    // uniformly; bytes ≥ 198 are rejected and re-drawn. Plain modulo
+    // would over-represent the first 58 of 66 chars (CodeQL flags it
+    // as a high-severity finding). 64 output chars yields ~380 bits
+    // of entropy, well above the spec's 256-bit floor.
+    const N = UNRESERVED.length; // 66
+    const UNIFORM_CEIL = 256 - (256 % N); // 198
+    const out = [];
+    while (out.length < 64) {
+        const buf = randomBytes(64);
+        for (let i = 0; i < buf.length && out.length < 64; i++) {
+            const b = buf[i];
+            if (b < UNIFORM_CEIL)
+                out.push(UNRESERVED[b % N]);
+        }
+    }
+    return out.join("");
+}
+/** Derive the S256 code_challenge from a verifier. */
+export function challengeFromVerifier(verifier) {
+    return base64url(createHash("sha256").update(verifier).digest());
+}
+/** Convenience: fresh {verifier, challenge} pair. */
+export function generatePkcePair() {
+    const verifier = generateCodeVerifier();
+    return { verifier, challenge: challengeFromVerifier(verifier), method: "S256" };
+}

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

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

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

@@ -0,0 +1,55 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { base64url, generateCodeVerifier, challengeFromVerifier, generatePkcePair } from "./pkce.js";
+test("base64url — strips padding and rewrites +/", () => {
+    // Buffer that hits + and / under standard base64 encoding
+    const b = Buffer.from([0xfb, 0xff, 0xbf]);
+    assert.equal(b.toString("base64"), "+/+/"); // sanity
+    assert.equal(base64url(b), "-_-_");
+    // Padding case
+    assert.equal(base64url(Buffer.from([0x01])), "AQ");
+});
+test("generateCodeVerifier — only unreserved chars, length 64", () => {
+    const v = generateCodeVerifier();
+    assert.equal(v.length, 64);
+    assert.match(v, /^[A-Za-z0-9\-._~]+$/);
+});
+test("generateCodeVerifier — two calls produce distinct values", () => {
+    const a = generateCodeVerifier();
+    const b = generateCodeVerifier();
+    assert.notEqual(a, b);
+});
+test("generateCodeVerifier — distribution is roughly uniform across the 66 unreserved chars", () => {
+    // Rejection-sampling guarantee: every char must appear approximately
+    // N*64/66 ≈ 0.97 times per verifier on average. A weak smoke test:
+    // across 200 verifiers (12_800 chars) no character class is empty
+    // and the most-common / least-common counts stay within a 2x ratio.
+    // With biased modulo, the last 8 chars would be ~20% under-represented;
+    // this asserts that's no longer the case.
+    const counts = new Map();
+    for (let i = 0; i < 200; i++) {
+        for (const c of generateCodeVerifier())
+            counts.set(c, (counts.get(c) ?? 0) + 1);
+    }
+    assert.equal(counts.size, 66, "every unreserved char should appear at least once");
+    const all = [...counts.values()];
+    const min = Math.min(...all);
+    const max = Math.max(...all);
+    assert.ok(max / min < 2, `distribution too skewed (min=${min} max=${max})`);
+});
+test("challengeFromVerifier — matches base64url(sha256(verifier))", () => {
+    const v = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"; // RFC 7636 §4.4 sample
+    const expected = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"; // RFC 7636 §4.4
+    assert.equal(challengeFromVerifier(v), expected);
+});
+test("challengeFromVerifier — deterministic", () => {
+    const v = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789--__";
+    assert.equal(challengeFromVerifier(v), challengeFromVerifier(v));
+});
+test("generatePkcePair — challenge matches S256(verifier) and method is S256", () => {
+    const p = generatePkcePair();
+    const expect = Buffer.from(createHash("sha256").update(p.verifier).digest()).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    assert.equal(p.challenge, expect);
+    assert.equal(p.method, "S256");
+});

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

@@ -0,0 +1,63 @@
+/**
+ * Resolve the OIDC configuration from environment variables and turn
+ * it into the runtime shape the rest of the auth layer consumes.
+ *
+ * Mirrors the basic-mode resolution in src/index.ts: fail-closed on
+ * missing required config, allow an `OMCP_AUTH_ALLOW_FALLBACK=true`
+ * opt-out (handled by the caller — this module just signals via the
+ * `error` field).
+ *
+ * Required env (when OMCP_AUTH=oidc):
+ *   OMCP_OIDC_ISSUER         — IdP base URL (no trailing /.well-known/...)
+ *   OMCP_OIDC_CLIENT_ID
+ *   OMCP_OIDC_REDIRECT_URI   — absolute, MUST match the registration
+ *
+ * Optional env:
+ *   OMCP_OIDC_CLIENT_SECRET  — confidential clients; public clients omit
+ *   OMCP_OIDC_SCOPES         — default "openid profile email"
+ *   OMCP_OIDC_ROLES_CLAIM    — dotted path; default "groups"
+ *   OMCP_OIDC_ROLE_MAP       — JSON {"<claim-value>": "<omcp-role>"};
+ *                              entries map directly to RBAC roles
+ *                              (viewer / operator / admin or custom).
+ *   OMCP_OIDC_LOGOUT_REDIRECT — post-logout landing URL (default "/")
+ */
+import { OidcClient } from "./client.js";
+export interface OidcRuntimeConfig {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    scopes: string;
+    rolesClaim: string;
+    roleMap: Record<string, string>;
+    logoutRedirect: string;
+    /** Dotted claim path to read the tenant from. Empty / missing → all
+     *  OIDC sessions land in the "default" tenant. */
+    tenantClaim: string;
+}
+export interface ResolveOidcResult {
+    /** Fully validated runtime config; absent when `error` is set. */
+    config?: OidcRuntimeConfig;
+    /** Human-readable misconfiguration reason; used for the boot log
+     *  + fail-closed exit. */
+    error?: string;
+}
+/** Pure env-to-config translator. No I/O. */
+export declare function resolveOidcConfig(env?: NodeJS.ProcessEnv): ResolveOidcResult;
+/** Build the OidcClient + the role-resolution helper from a resolved
+ * runtime config. Tests can stub OidcClient by passing a custom one. */
+export interface OidcRuntime {
+    cfg: OidcRuntimeConfig;
+    client: OidcClient;
+    /** Walk a JWT claim set, follow the rolesClaim dotted path, and
+     *  return the OMCP role names the user inherits via roleMap.
+     *  Unknown claim values are silently dropped (least-privilege). */
+    resolveRoles(claims: Record<string, unknown>): string[];
+    /** Walk a JWT claim set, follow the configured tenant claim path,
+     *  and return a normalised tenant id. Empty / missing / invalid →
+     *  DEFAULT_TENANT. */
+    resolveTenant(claims: Record<string, unknown>): string;
+}
+export declare function buildOidcRuntime(cfg: OidcRuntimeConfig, opts?: {
+    client?: OidcClient;
+}): OidcRuntime;