@thotischner/observability-mcp 1.7.1 → 1.8.1

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

@@ -0,0 +1,304 @@
+/**
+ * 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.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import express from "express";
+import { createServer } from "node:http";
+import { generateKeyPairSync, createPublicKey, createSign } from "node:crypto";
+import { registerOidcRoutes } from "./endpoints.js";
+import { buildOidcRuntime } from "./runtime.js";
+import { OidcClient } from "./client.js";
+const SECRET = "x".repeat(32);
+const ISSUER = "https://idp.test";
+const CLIENT_ID = "c-1";
+const REDIRECT_URI = "http://app.test/api/auth/oidc/callback";
+function b64u(s) {
+    const b = typeof s === "string" ? Buffer.from(s, "utf8") : s;
+    return b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+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 = "k-1";
+    return { jwk, privateKeyPem: privateKey };
+}
+function signRs256(payload, pem, kid) {
+    const h = b64u(JSON.stringify({ alg: "RS256", typ: "JWT", kid }));
+    const b = b64u(JSON.stringify(payload));
+    const s = createSign("RSA-SHA256");
+    s.update(`${h}.${b}`);
+    s.end();
+    return `${h}.${b}.${b64u(s.sign(pem))}`;
+}
+async function listen(app) {
+    const server = createServer(app);
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const addr = server.address();
+    return {
+        server,
+        base: `http://127.0.0.1:${addr.port}`,
+        close: () => new Promise((r) => server.close(() => r())),
+    };
+}
+function discoveryDoc() {
+    return {
+        issuer: ISSUER,
+        authorization_endpoint: `${ISSUER}/auth`,
+        token_endpoint: `${ISSUER}/token`,
+        jwks_uri: `${ISSUER}/jwks`,
+    };
+}
+function configForTest() {
+    return {
+        issuer: ISSUER,
+        clientId: CLIENT_ID,
+        clientSecret: undefined,
+        redirectUri: REDIRECT_URI,
+        scopes: "openid profile email",
+        rolesClaim: "groups",
+        roleMap: { "omcp-admin": "admin", "omcp-ops": "operator" },
+        logoutRedirect: "/",
+        tenantClaim: "",
+    };
+}
+test("GET /api/auth/oidc/login — 302 to IdP and sets flow cookie", async () => {
+    const cfg = configForTest();
+    const fetcher = async (url) => {
+        if (url.endsWith("/.well-known/openid-configuration"))
+            return new Response(JSON.stringify(discoveryDoc()), { status: 200 });
+        return new Response("nf", { status: 404 });
+    };
+    const client = new OidcClient({ issuer: cfg.issuer, clientId: cfg.clientId, redirectUri: cfg.redirectUri, fetcher });
+    const oidc = buildOidcRuntime(cfg, { client });
+    const app = express();
+    registerOidcRoutes(app, { sessionCfg: { secret: SECRET }, oidc });
+    const { base, close } = await listen(app);
+    try {
+        const res = await fetch(`${base}/api/auth/oidc/login`, { redirect: "manual" });
+        assert.equal(res.status, 302);
+        const loc = res.headers.get("location") ?? "";
+        assert.ok(loc.startsWith(`${ISSUER}/auth?`), `unexpected redirect target: ${loc}`);
+        const u = new URL(loc);
+        assert.equal(u.searchParams.get("client_id"), CLIENT_ID);
+        assert.equal(u.searchParams.get("response_type"), "code");
+        assert.ok(u.searchParams.get("code_challenge"));
+        const setCookie = res.headers.get("set-cookie") ?? "";
+        assert.match(setCookie, /^omcp_oidc_flow=/, "must set the flow cookie");
+        assert.match(setCookie, /HttpOnly/);
+    }
+    finally {
+        await close();
+    }
+});
+test("GET /api/auth/oidc/login — honours safe ?return_to=, ignores hostile", async () => {
+    const cfg = configForTest();
+    const fetcher = async (_url) => new Response(JSON.stringify(discoveryDoc()), { status: 200 });
+    const client = new OidcClient({ issuer: cfg.issuer, clientId: cfg.clientId, redirectUri: cfg.redirectUri, fetcher });
+    const oidc = buildOidcRuntime(cfg, { client });
+    const app = express();
+    registerOidcRoutes(app, { sessionCfg: { secret: SECRET }, oidc });
+    const { base, close } = await listen(app);
+    try {
+        // Safe path goes into the cookie payload (we'll re-decode on
+        // callback). We can't easily inspect cookie content from outside
+        // here without re-implementing the verify; we trust the
+        // unit-test coverage of issueFlowCookie/isSafeReturnTo for that.
+        const safe = await fetch(`${base}/api/auth/oidc/login?return_to=/dashboard`, { redirect: "manual" });
+        assert.equal(safe.status, 302);
+        const hostile = await fetch(`${base}/api/auth/oidc/login?return_to=https://evil.example`, { redirect: "manual" });
+        assert.equal(hostile.status, 302);
+    }
+    finally {
+        await close();
+    }
+});
+test("GET /api/auth/oidc/callback — end-to-end happy path mints session cookie + redirects to returnTo", async () => {
+    const { jwk, privateKeyPem } = rsaKey();
+    const now = Math.floor(Date.now() / 1000);
+    // Capture state/nonce/verifier the login mints, so we can sign a
+    // matching id_token before issuing the callback.
+    let mintedFlow = null;
+    const cfg = configForTest();
+    const fetcher = async (url) => {
+        if (url.endsWith("/.well-known/openid-configuration"))
+            return new Response(JSON.stringify(discoveryDoc()), { status: 200 });
+        if (url === `${ISSUER}/jwks`)
+            return new Response(JSON.stringify({ keys: [jwk] }), { status: 200 });
+        if (url === `${ISSUER}/token`) {
+            // Sign id_token with the actual nonce we minted in /login.
+            const idToken = signRs256({
+                iss: ISSUER, aud: CLIENT_ID, sub: "alice", name: "Alice", email: "alice@example.test",
+                exp: now + 60, iat: now, nonce: mintedFlow.nonce, groups: ["omcp-admin", "omcp-ops", "ignored"],
+            }, privateKeyPem, jwk.kid);
+            return new Response(JSON.stringify({ id_token: idToken, access_token: "AT", token_type: "Bearer" }), { status: 200 });
+        }
+        return new Response("nf", { status: 404 });
+    };
+    // Patched client that also exposes the minted flow.
+    const baseClient = new OidcClient({ issuer: cfg.issuer, clientId: cfg.clientId, redirectUri: cfg.redirectUri, fetcher });
+    const wrapped = Object.create(baseClient);
+    wrapped.start = async () => {
+        const out = await baseClient.start();
+        mintedFlow = out.flow;
+        return out;
+    };
+    const oidc = buildOidcRuntime(cfg, { client: wrapped });
+    const app = express();
+    registerOidcRoutes(app, { sessionCfg: { secret: SECRET }, oidc });
+    const { base, close } = await listen(app);
+    try {
+        // 1) /login → grab the flow cookie + the IdP's `state` from the URL
+        const loginRes = await fetch(`${base}/api/auth/oidc/login?return_to=/audit`, { redirect: "manual" });
+        assert.equal(loginRes.status, 302);
+        const flowCookie = (loginRes.headers.get("set-cookie") ?? "").split(";")[0];
+        const idpRedirect = new URL(loginRes.headers.get("location"));
+        const state = idpRedirect.searchParams.get("state");
+        assert.equal(state, mintedFlow.state, "state in URL must match flow cookie payload");
+        // 2) Simulate IdP redirect back: GET /callback?code=ABC&state=...
+        //    Send the flow cookie back to the server.
+        const cbRes = await fetch(`${base}/api/auth/oidc/callback?code=ABC&state=${state}`, {
+            redirect: "manual",
+            headers: { cookie: flowCookie },
+        });
+        assert.equal(cbRes.status, 302, `callback should 302; got ${cbRes.status}, body=${await cbRes.text()}`);
+        assert.equal(cbRes.headers.get("location"), "/audit", "callback should redirect to the returnTo");
+        // Inspect cookies individually — undici joins multi-Set-Cookie
+        // headers with `, ` when read via .get("set-cookie"), which makes
+        // a naive regex match the wrong adjacent cookie's attributes.
+        const cookies = cbRes.headers.getSetCookie();
+        assert.ok(cookies.some((c) => /^omcp_session=[^;]+;/.test(c)), `session cookie should be set, got ${JSON.stringify(cookies)}`);
+        const cleared = cookies.find((c) => c.startsWith("omcp_oidc_flow="));
+        assert.ok(cleared, `flow cookie should appear in Set-Cookie, got ${JSON.stringify(cookies)}`);
+        assert.match(cleared, /^omcp_oidc_flow=;/, "flow cookie value must be empty (cleared)");
+        assert.match(cleared, /Max-Age=0/, "flow cookie must carry Max-Age=0");
+    }
+    finally {
+        await close();
+    }
+});
+test("GET /api/auth/oidc/callback — 400 when flow cookie missing", async () => {
+    const cfg = configForTest();
+    const fetcher = async (_url) => new Response(JSON.stringify(discoveryDoc()), { status: 200 });
+    const client = new OidcClient({ issuer: cfg.issuer, clientId: cfg.clientId, redirectUri: cfg.redirectUri, fetcher });
+    const oidc = buildOidcRuntime(cfg, { client });
+    const app = express();
+    registerOidcRoutes(app, { sessionCfg: { secret: SECRET }, oidc });
+    const { base, close } = await listen(app);
+    try {
+        const res = await fetch(`${base}/api/auth/oidc/callback?code=ABC&state=XYZ`, { redirect: "manual" });
+        assert.equal(res.status, 400);
+        const body = await res.json();
+        assert.equal(body.error, "oidc_flow_cookie_missing");
+    }
+    finally {
+        await close();
+    }
+});
+test("GET /api/auth/oidc/callback — surfaces IdP-side error parameter", async () => {
+    const cfg = configForTest();
+    const fetcher = async (_url) => new Response(JSON.stringify(discoveryDoc()), { status: 200 });
+    const client = new OidcClient({ issuer: cfg.issuer, clientId: cfg.clientId, redirectUri: cfg.redirectUri, fetcher });
+    const oidc = buildOidcRuntime(cfg, { client });
+    const app = express();
+    registerOidcRoutes(app, { sessionCfg: { secret: SECRET }, oidc });
+    const { base, close } = await listen(app);
+    try {
+        const res = await fetch(`${base}/api/auth/oidc/callback?error=access_denied`, { redirect: "manual" });
+        assert.equal(res.status, 400);
+        const body = await res.json();
+        assert.equal(body.error, "oidc_idp_error");
+        assert.match(body.message, /access_denied/);
+    }
+    finally {
+        await close();
+    }
+});
+test("GET /api/auth/oidc/callback — persists verified email; drops unverified email", async () => {
+    // Build two end-to-end runs against the same setup, varying only
+    // the `email_verified` claim. Inspect the resulting session cookie
+    // payload by parsing it client-side (the cookie shape is documented
+    // in src/auth/session.ts).
+    async function runWith(emailVerified) {
+        const { jwk, privateKeyPem } = rsaKey();
+        const now = Math.floor(Date.now() / 1000);
+        let mintedFlow = null;
+        const cfg = configForTest();
+        const fetcher = async (url) => {
+            if (url.endsWith("/.well-known/openid-configuration"))
+                return new Response(JSON.stringify(discoveryDoc()), { status: 200 });
+            if (url === `${ISSUER}/jwks`)
+                return new Response(JSON.stringify({ keys: [jwk] }), { status: 200 });
+            if (url === `${ISSUER}/token`) {
+                const claims = {
+                    iss: ISSUER, aud: CLIENT_ID, sub: "alice", name: "Alice",
+                    email: "alice@example.test", exp: now + 60, iat: now, nonce: mintedFlow.nonce,
+                };
+                if (emailVerified !== undefined)
+                    claims.email_verified = emailVerified;
+                const idToken = signRs256(claims, privateKeyPem, jwk.kid);
+                return new Response(JSON.stringify({ id_token: idToken }), { status: 200 });
+            }
+            return new Response("nf", { status: 404 });
+        };
+        const baseClient = new OidcClient({ issuer: cfg.issuer, clientId: cfg.clientId, redirectUri: cfg.redirectUri, fetcher });
+        const wrapped = Object.create(baseClient);
+        wrapped.start = async () => { const o = await baseClient.start(); mintedFlow = o.flow; return o; };
+        const oidc = buildOidcRuntime(cfg, { client: wrapped });
+        const app = express();
+        registerOidcRoutes(app, { sessionCfg: { secret: SECRET }, oidc });
+        const { base, close } = await listen(app);
+        try {
+            const login = await fetch(`${base}/api/auth/oidc/login`, { redirect: "manual" });
+            const flowCookie = (login.headers.get("set-cookie") ?? "").split(";")[0];
+            const state = new URL(login.headers.get("location")).searchParams.get("state");
+            const cb = await fetch(`${base}/api/auth/oidc/callback?code=ABC&state=${state}`, { redirect: "manual", headers: { cookie: flowCookie } });
+            const setCookies = cb.headers.getSetCookie();
+            const session = setCookies.find((c) => c.startsWith("omcp_session="));
+            const value = session.slice("omcp_session=".length).split(";")[0];
+            const payloadB64 = value.split(".")[0];
+            const pad = payloadB64.length % 4 === 0 ? "" : "=".repeat(4 - (payloadB64.length % 4));
+            return JSON.parse(Buffer.from(payloadB64.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8"));
+        }
+        finally {
+            await close();
+        }
+    }
+    // email_verified absent → trust the email
+    const absent = await runWith(undefined);
+    assert.equal(absent.email, "alice@example.test");
+    // email_verified=true → persist
+    const verified = await runWith(true);
+    assert.equal(verified.email, "alice@example.test");
+    // email_verified=false → drop
+    const unverified = await runWith(false);
+    assert.equal(unverified.email, undefined);
+});
+test("POST /api/auth/oidc/logout — 204 and clears the session cookie", async () => {
+    const cfg = configForTest();
+    const fetcher = async (_url) => new Response("nf", { status: 404 });
+    const client = new OidcClient({ issuer: cfg.issuer, clientId: cfg.clientId, redirectUri: cfg.redirectUri, fetcher });
+    const oidc = buildOidcRuntime(cfg, { client });
+    const app = express();
+    registerOidcRoutes(app, { sessionCfg: { secret: SECRET }, oidc });
+    const { base, close } = await listen(app);
+    try {
+        const res = await fetch(`${base}/api/auth/oidc/logout`, { method: "POST" });
+        assert.equal(res.status, 204);
+        const cookies = res.headers.getSetCookie();
+        const cleared = cookies.find((c) => c.startsWith("omcp_session="));
+        assert.ok(cleared, `logout should clear the session cookie; got ${JSON.stringify(cookies)}`);
+        assert.match(cleared, /^omcp_session=;/);
+        assert.match(cleared, /Max-Age=0/);
+    }
+    finally {
+        await close();
+    }
+});

package/dist/auth/oidc/flow-cookie.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Short-lived signed cookie that carries the OIDC code-flow state
+ * (state, nonce, code_verifier, returnTo) between the /login redirect
+ * and the /callback handler.
+ *
+ * Signed with HMAC-SHA256 using the same session secret the OMCP
+ * session cookie uses — keeps the trust boundary single and obviates
+ * a separate key. The payload is a JSON object; the cookie is
+ * `<base64url-payload>.<base64url-sig>` like the main session cookie.
+ *
+ * TTL is intentionally short (5 minutes by default). The auth-code
+ * flow is interactive: an IdP that takes longer than that to redirect
+ * back is broken, not slow. Short TTL also bounds the window during
+ * which a leaked state cookie is exploitable.
+ */
+export interface FlowState {
+    state: string;
+    nonce: string;
+    codeVerifier: string;
+    /** Where to 302 after a successful callback. Always a same-origin
+     *  path that begins with `/`; verified at consume time. */
+    returnTo: string;
+    /** Issued-at, seconds since epoch. */
+    iat: number;
+    /** Expiry, seconds since epoch. */
+    exp: number;
+}
+export declare const DEFAULT_FLOW_COOKIE_NAME = "omcp_oidc_flow";
+export declare const DEFAULT_FLOW_TTL_SECONDS = 300;
+export interface FlowCookieConfig {
+    secret: string;
+    ttlSeconds?: number;
+    cookieName?: string;
+}
+/** Build the cookie value carrying the flow state. */
+export declare function issueFlowCookie(flow: {
+    state: string;
+    nonce: string;
+    codeVerifier: string;
+    returnTo: string;
+}, cfg: FlowCookieConfig, now?: number): string;
+/** Decode + verify a cookie value. Returns the flow state on success,
+ *  null on any failure (signature mismatch, expired, malformed). */
+export declare function verifyFlowCookie(cookieValue: string | undefined | null, cfg: FlowCookieConfig, now?: number): FlowState | null;
+export declare function setFlowCookieHeader(value: string, cfg: FlowCookieConfig, opts?: {
+    secure?: boolean;
+}): string;
+export declare function clearFlowCookieHeader(cfg: FlowCookieConfig, opts?: {
+    secure?: boolean;
+}): string;
+/** Validate a returnTo before using it for the post-callback redirect.
+ *  Defends against an attacker stuffing a hostile absolute URL into
+ *  the login link (open-redirect). */
+export declare function isSafeReturnTo(path: unknown): path is string;
+/** Parse a Cookie header for the flow cookie's value. Tolerates other
+ *  cookies (session, CSRF, etc.) sharing the header. */
+export declare function readFlowCookie(cookieHeader: string | undefined | null, name?: string): string | null;

package/dist/auth/oidc/flow-cookie.js

@@ -0,0 +1,142 @@
+/**
+ * Short-lived signed cookie that carries the OIDC code-flow state
+ * (state, nonce, code_verifier, returnTo) between the /login redirect
+ * and the /callback handler.
+ *
+ * Signed with HMAC-SHA256 using the same session secret the OMCP
+ * session cookie uses — keeps the trust boundary single and obviates
+ * a separate key. The payload is a JSON object; the cookie is
+ * `<base64url-payload>.<base64url-sig>` like the main session cookie.
+ *
+ * TTL is intentionally short (5 minutes by default). The auth-code
+ * flow is interactive: an IdP that takes longer than that to redirect
+ * back is broken, not slow. Short TTL also bounds the window during
+ * which a leaked state cookie is exploitable.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const DEFAULT_FLOW_COOKIE_NAME = "omcp_oidc_flow";
+export const DEFAULT_FLOW_TTL_SECONDS = 300; // 5 min
+const MAX_COOKIE_BYTES = 4096;
+function b64u(buf) {
+    return buf.toString("base64url");
+}
+function unb64u(s) {
+    try {
+        return Buffer.from(s, "base64url");
+    }
+    catch {
+        return null;
+    }
+}
+function sign(secret, payload) {
+    return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+/** Build the cookie value carrying the flow state. */
+export function issueFlowCookie(flow, cfg, now = Math.floor(Date.now() / 1000)) {
+    if (!cfg.secret || cfg.secret.length < 32)
+        throw new Error("flow-cookie secret must be ≥ 32 chars");
+    const ttl = cfg.ttlSeconds ?? DEFAULT_FLOW_TTL_SECONDS;
+    const payload = { ...flow, iat: now, exp: now + ttl };
+    const payloadStr = b64u(Buffer.from(JSON.stringify(payload)));
+    const sig = sign(cfg.secret, payloadStr);
+    return `${payloadStr}.${sig}`;
+}
+/** Decode + verify a cookie value. Returns the flow state on success,
+ *  null on any failure (signature mismatch, expired, malformed). */
+export function verifyFlowCookie(cookieValue, cfg, now = Math.floor(Date.now() / 1000)) {
+    if (!cookieValue)
+        return null;
+    if (cookieValue.length > MAX_COOKIE_BYTES)
+        return null;
+    if (!cfg.secret || cfg.secret.length < 32)
+        return null;
+    const dot = cookieValue.indexOf(".");
+    if (dot <= 0 || dot === cookieValue.length - 1)
+        return null;
+    const payloadStr = cookieValue.slice(0, dot);
+    const sig = cookieValue.slice(dot + 1);
+    const expected = sign(cfg.secret, payloadStr);
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return null;
+    const raw = unb64u(payloadStr);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isFlowState(parsed))
+        return null;
+    if (parsed.exp <= now)
+        return null;
+    return parsed;
+}
+function isFlowState(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    return typeof o.state === "string"
+        && typeof o.nonce === "string"
+        && typeof o.codeVerifier === "string"
+        && typeof o.returnTo === "string"
+        && typeof o.iat === "number"
+        && typeof o.exp === "number";
+}
+export function setFlowCookieHeader(value, cfg, opts = {}) {
+    const ttl = cfg.ttlSeconds ?? DEFAULT_FLOW_TTL_SECONDS;
+    const name = cfg.cookieName ?? DEFAULT_FLOW_COOKIE_NAME;
+    const parts = [`${name}=${value}`, `Max-Age=${ttl}`, "Path=/", "HttpOnly", "SameSite=Lax"];
+    if (opts.secure !== false)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+export function clearFlowCookieHeader(cfg, opts = {}) {
+    const name = cfg.cookieName ?? DEFAULT_FLOW_COOKIE_NAME;
+    const parts = [`${name}=`, "Max-Age=0", "Path=/", "HttpOnly", "SameSite=Lax"];
+    if (opts.secure !== false)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+/** Validate a returnTo before using it for the post-callback redirect.
+ *  Defends against an attacker stuffing a hostile absolute URL into
+ *  the login link (open-redirect). */
+export function isSafeReturnTo(path) {
+    if (typeof path !== "string")
+        return false;
+    if (path.length === 0 || path.length > 2048)
+        return false;
+    // Reject any absolute / scheme-relative shape — only same-origin
+    // paths beginning with `/` and NOT `//` are accepted.
+    if (!path.startsWith("/"))
+        return false;
+    if (path.startsWith("//"))
+        return false;
+    if (path.startsWith("/\\"))
+        return false;
+    // Reject control characters — a CRLF would be folded into the
+    // eventual Location header (header-injection / response-splitting
+    // defence in depth; Express also sanitises, but two layers cost
+    // nothing).
+    if (/[\x00-\x1f\x7f]/.test(path))
+        return false;
+    return true;
+}
+/** Parse a Cookie header for the flow cookie's value. Tolerates other
+ *  cookies (session, CSRF, etc.) sharing the header. */
+export function readFlowCookie(cookieHeader, name = DEFAULT_FLOW_COOKIE_NAME) {
+    if (!cookieHeader)
+        return null;
+    for (const part of cookieHeader.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq <= 0)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return null;
+}

package/dist/auth/oidc/flow-cookie.test.d.ts

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

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

@@ -0,0 +1,7 @@
+/** Public barrel for the OIDC core library. */
+export { OidcClient } from "./client.js";
+export type { OidcConfig, StartResult, CompleteOpts, CompleteResult } from "./client.js";
+export { DiscoveryClient, type DiscoveryDocument, type Fetcher } from "./discovery.js";
+export { JwksClient, type Jwks } from "./jwks.js";
+export { verifyIdToken, JwtVerifyError, type Jwk, type JwtPayload } from "./jwt.js";
+export { generatePkcePair, generateCodeVerifier, challengeFromVerifier } from "./pkce.js";

package/dist/auth/oidc/index.js

@@ -0,0 +1,6 @@
+/** Public barrel for the OIDC core library. */
+export { OidcClient } from "./client.js";
+export { DiscoveryClient } from "./discovery.js";
+export { JwksClient } from "./jwks.js";
+export { verifyIdToken, JwtVerifyError } from "./jwt.js";
+export { generatePkcePair, generateCodeVerifier, challengeFromVerifier } from "./pkce.js";

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

@@ -0,0 +1,36 @@
+/**
+ * JWKS fetcher + cache for OIDC ID-token signature verification.
+ *
+ * One cache per (issuer, jwks_uri). TTL defaults to 1 hour; a cache
+ * miss on an unknown `kid` triggers a single refresh in case the IdP
+ * rotated the key — this is the standard "kid not found → refresh
+ * once, then fail" pattern recommended by jose, openid-client etc.
+ */
+import type { Jwk } from "./jwt.js";
+import type { Fetcher } from "./discovery.js";
+export interface Jwks {
+    keys: Jwk[];
+}
+export interface JwksClientOpts {
+    fetcher?: Fetcher;
+    ttlMs?: number;
+    /** Cooldown between forced refresh attempts on cache miss; default 60s. */
+    refreshCooldownMs?: number;
+    now?: () => number;
+}
+export declare class JwksClient {
+    private readonly fetcher;
+    private readonly ttlMs;
+    private readonly cooldownMs;
+    private readonly now;
+    private readonly cache;
+    constructor(opts?: JwksClientOpts);
+    /** Return the JWKS for the given URI, fetching if missing or expired. */
+    get(jwksUri: string): Promise<Jwks>;
+    /** Look up a single key by kid. On miss, refresh once (subject to
+     * the cooldown) — IdPs rotate keys without warning and the
+     * discovery doc rarely changes when they do. */
+    findKey(jwksUri: string, kid: string | undefined): Promise<Jwk | undefined>;
+    invalidate(jwksUri?: string): void;
+    private refresh;
+}

package/dist/auth/oidc/jwks.js

@@ -0,0 +1,69 @@
+/**
+ * JWKS fetcher + cache for OIDC ID-token signature verification.
+ *
+ * One cache per (issuer, jwks_uri). TTL defaults to 1 hour; a cache
+ * miss on an unknown `kid` triggers a single refresh in case the IdP
+ * rotated the key — this is the standard "kid not found → refresh
+ * once, then fail" pattern recommended by jose, openid-client etc.
+ */
+export class JwksClient {
+    fetcher;
+    ttlMs;
+    cooldownMs;
+    now;
+    cache = new Map();
+    constructor(opts = {}) {
+        this.fetcher = opts.fetcher ?? ((u, i) => fetch(u, i));
+        this.ttlMs = opts.ttlMs ?? 3_600_000;
+        this.cooldownMs = opts.refreshCooldownMs ?? 60_000;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Return the JWKS for the given URI, fetching if missing or expired. */
+    async get(jwksUri) {
+        const cached = this.cache.get(jwksUri);
+        if (cached && cached.expiresAt > this.now())
+            return cached.jwks;
+        return await this.refresh(jwksUri);
+    }
+    /** Look up a single key by kid. On miss, refresh once (subject to
+     * the cooldown) — IdPs rotate keys without warning and the
+     * discovery doc rarely changes when they do. */
+    async findKey(jwksUri, kid) {
+        let jwks = await this.get(jwksUri);
+        let key = pickKey(jwks, kid);
+        if (key)
+            return key;
+        const cached = this.cache.get(jwksUri);
+        if (cached && cached.lastForceRefresh + this.cooldownMs > this.now())
+            return undefined;
+        jwks = await this.refresh(jwksUri, /*forced*/ true);
+        key = pickKey(jwks, kid);
+        return key;
+    }
+    invalidate(jwksUri) {
+        if (jwksUri)
+            this.cache.delete(jwksUri);
+        else
+            this.cache.clear();
+    }
+    async refresh(jwksUri, forced = false) {
+        const res = await this.fetcher(jwksUri);
+        if (!res.ok)
+            throw new Error(`JWKS fetch failed for ${jwksUri}: HTTP ${res.status}`);
+        const body = (await res.json());
+        if (!body || !Array.isArray(body.keys))
+            throw new Error(`JWKS body for ${jwksUri} is not a valid JWKS document`);
+        const entry = {
+            jwks: body,
+            expiresAt: this.now() + this.ttlMs,
+            lastForceRefresh: forced ? this.now() : (this.cache.get(jwksUri)?.lastForceRefresh ?? 0),
+        };
+        this.cache.set(jwksUri, entry);
+        return body;
+    }
+}
+function pickKey(jwks, kid) {
+    if (!kid)
+        return jwks.keys.find((k) => !!k.n || !!k.x) ?? jwks.keys[0];
+    return jwks.keys.find((k) => k.kid === kid);
+}

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

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