@thotischner/observability-mcp 1.7.1 → 3.0.0

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

@@ -0,0 +1,109 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { validateDcrRequest, mintRegistration, appendRegistration, loadRegistrations, toResponse, dcrEnabled, dcrStorePath, DcrValidationError, } from "./dcr.js";
+function tmp() {
+    return join(mkdtempSync(join(tmpdir(), "dcr-")), "dcr.json");
+}
+test("dcrEnabled — true/1/yes/on (any case), unset = false", () => {
+    for (const v of ["true", "1", "yes", "on", "TRUE", "Yes"]) {
+        assert.equal(dcrEnabled({ OMCP_OIDC_DCR_ENABLED: v }), true, v);
+    }
+    for (const v of ["", "false", "0", "anything-else"]) {
+        assert.equal(dcrEnabled({ OMCP_OIDC_DCR_ENABLED: v }), false, v);
+    }
+    assert.equal(dcrEnabled({}), false);
+});
+test("dcrStorePath — defaults to /tmp/oidc-dcr.json, env override wins", () => {
+    assert.equal(dcrStorePath({}), "/tmp/oidc-dcr.json");
+    assert.equal(dcrStorePath({ OMCP_OIDC_DCR_STORE: "/var/lib/dcr.json" }), "/var/lib/dcr.json");
+});
+test("validateDcrRequest — requires non-empty redirect_uris", () => {
+    assert.throws(() => validateDcrRequest({}), DcrValidationError);
+    assert.throws(() => validateDcrRequest({ redirect_uris: [] }), DcrValidationError);
+});
+test("validateDcrRequest — rejects http:// for non-loopback hosts", () => {
+    assert.throws(() => validateDcrRequest({ redirect_uris: ["http://example.com/cb"] }), /must use https/);
+    assert.doesNotThrow(() => validateDcrRequest({ redirect_uris: ["http://localhost:5173/cb"] }));
+    assert.doesNotThrow(() => validateDcrRequest({ redirect_uris: ["http://127.0.0.1:5173/cb"] }));
+});
+test("validateDcrRequest — accepts https:// always", () => {
+    const v = validateDcrRequest({
+        redirect_uris: ["https://app.example.com/oauth/callback"],
+    });
+    assert.deepEqual(v.redirect_uris, ["https://app.example.com/oauth/callback"]);
+});
+test("validateDcrRequest — defaults for grant_types/response_types/auth_method", () => {
+    const v = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    assert.deepEqual(v.grant_types, ["authorization_code"]);
+    assert.deepEqual(v.response_types, ["code"]);
+    assert.equal(v.token_endpoint_auth_method, "client_secret_basic");
+});
+test("validateDcrRequest — preserves explicit values", () => {
+    const v = validateDcrRequest({
+        redirect_uris: ["https://x/cb"],
+        grant_types: ["refresh_token"],
+        response_types: ["code id_token"],
+        token_endpoint_auth_method: "none",
+        client_name: "Claude.ai",
+        scope: "openid profile",
+    });
+    assert.deepEqual(v.grant_types, ["refresh_token"]);
+    assert.equal(v.token_endpoint_auth_method, "none");
+    assert.equal(v.client_name, "Claude.ai");
+    assert.equal(v.scope, "openid profile");
+});
+test("mintRegistration — issues client_id (UUID), client_secret (base64url), no secret for 'none' auth", () => {
+    const now = new Date("2026-06-05T20:00:00Z");
+    const validated = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    const reg = mintRegistration(validated, "10.0.0.1", { now: () => now });
+    assert.match(reg.client_id, /^[0-9a-f-]{36}$/);
+    assert.ok(reg.client_secret && reg.client_secret.length > 30);
+    assert.equal(reg.client_id_issued_at, Math.floor(now.getTime() / 1000));
+    assert.equal(reg.client_secret_expires_at, 0);
+    assert.ok(reg.registration_access_token && reg.registration_access_token.length > 30);
+    assert.equal(reg._meta.sourceIp, "10.0.0.1");
+    assert.equal(reg._meta.createdAtIso, now.toISOString());
+    // Public client (PKCE, no secret) — RFC 7591 §3.2.1
+    const pub = mintRegistration(validateDcrRequest({
+        redirect_uris: ["https://x/cb"],
+        token_endpoint_auth_method: "none",
+    }), "10.0.0.1", { now: () => now });
+    assert.equal(pub.client_secret, undefined);
+});
+test("appendRegistration + loadRegistrations — round-trips, file is 0600", async () => {
+    const store = tmp();
+    const validated = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    const reg = mintRegistration(validated, "10.0.0.7");
+    await appendRegistration(store, reg);
+    const loaded = await loadRegistrations(store);
+    assert.equal(loaded.length, 1);
+    assert.equal(loaded[0]?.client_id, reg.client_id);
+    // File-mode check — DCR registrations contain secrets.
+    const mode = statSync(store).mode & 0o777;
+    assert.equal(mode, 0o600, `expected mode 0o600 got ${mode.toString(8)}`);
+});
+test("loadRegistrations — missing file returns []", async () => {
+    const store = tmp();
+    // No file written.
+    const loaded = await loadRegistrations(store);
+    assert.deepEqual(loaded, []);
+});
+test("toResponse — strips internal _meta so secrets don't leak source IP", () => {
+    const validated = validateDcrRequest({ redirect_uris: ["https://x/cb"] });
+    const reg = mintRegistration(validated, "10.0.0.7");
+    const response = toResponse(reg);
+    assert.equal(response._meta, undefined);
+    assert.equal(response.client_id, reg.client_id);
+    assert.equal(response.client_secret, reg.client_secret);
+});
+test("appendRegistration — atomic write (tmp+rename) survives a missing parent dir", async () => {
+    const parent = mkdtempSync(join(tmpdir(), "dcr-parent-"));
+    const store = join(parent, "sub", "nested", "dcr.json");
+    const reg = mintRegistration(validateDcrRequest({ redirect_uris: ["https://x/cb"] }), "10.0.0.7");
+    await appendRegistration(store, reg);
+    const onDisk = JSON.parse(readFileSync(store, "utf8"));
+    assert.equal(onDisk.length, 1);
+});

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,168 @@
+/**
+ * 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 rateLimit from "express-rate-limit";
+import { issueSession, setCookieHeader, clearCookieHeader } from "../session.js";
+import { issueFlowCookie, verifyFlowCookie, setFlowCookieHeader, clearFlowCookieHeader, readFlowCookie, isSafeReturnTo, } from "./flow-cookie.js";
+import { dcrEnabled, dcrStorePath, validateDcrRequest, mintRegistration, appendRegistration, toResponse, DcrValidationError, } from "./dcr.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();
+    });
+    // RFC 7591 Dynamic Client Registration. Off by default; flip
+    // OMCP_OIDC_DCR_ENABLED=true to accept self-registration POSTs
+    // (Claude.ai / Cursor / future MCP clients use this to introduce
+    // themselves to the gateway). Registrations land at
+    // OMCP_OIDC_DCR_STORE (default /tmp/oidc-dcr.json, mode 0600).
+    if (dcrEnabled()) {
+        const storePath = dcrStorePath();
+        // Per-source-IP throttle: 10 registrations per IP per hour. The
+        // endpoint is unauthenticated by design (RFC 7591) so without a
+        // limiter a single misbehaving client can fill the JSON store.
+        // Operators that need a different rate front the gateway with
+        // their ingress limiter and lift this floor accordingly.
+        const dcrLimiter = rateLimit({
+            windowMs: 60 * 60 * 1000,
+            max: 10,
+            standardHeaders: true,
+            legacyHeaders: false,
+            message: { error: "rate_limit_exceeded", error_description: "DCR rate limit hit; try later" },
+        });
+        app.post("/api/auth/oidc/register", dcrLimiter, async (req, res) => {
+            try {
+                const validated = validateDcrRequest((req.body ?? {}));
+                const sourceIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+                    req.ip ||
+                    "unknown";
+                const reg = mintRegistration(validated, sourceIp);
+                await appendRegistration(storePath, reg);
+                res.status(201).json(toResponse(reg));
+            }
+            catch (e) {
+                if (e instanceof DcrValidationError) {
+                    // RFC 7591 §3.2.2 error response shape.
+                    res.status(400).json({
+                        error: e.error,
+                        error_description: e.message,
+                    });
+                    return;
+                }
+                respondError(res, 500, "registration_failed", e.message);
+            }
+        });
+    }
+}
+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 {};