@thotischner/observability-mcp 1.7.1 → 1.8.1

package/dist/auth/credentials.test.js

@@ -11,7 +11,7 @@ describe("single-tenant auth primitive", () => {
     it("parses name:token and bare token", () => {
         const creds = loadCredentials({ OMCP_API_KEYS: "ci:tok_abc, tok_bare " });
         assert.equal(creds.length, 2);
-        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined });
+        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined, bypassRedaction: undefined, tenant: undefined });
         assert.equal(creds[1].name, "key");
         assert.equal(creds[1].token, "tok_bare");
     });
@@ -23,6 +23,31 @@ describe("single-tenant auth primitive", () => {
         assert.deepEqual(creds[0].allowedSources, ["prom-prod", "loki-prod"]);
         assert.deepEqual(creds[1].allowedSources, ["prom-staging"]);
     });
+    it("parses OMCP_KEY_BYPASS_REDACTION → flags only the listed names", () => {
+        const creds = loadCredentials({
+            OMCP_API_KEYS: "agent:tok1,ci:tok2,unprivileged:tok3",
+            OMCP_KEY_BYPASS_REDACTION: "agent, ci",
+        });
+        assert.equal(creds.find((c) => c.name === "agent")?.bypassRedaction, true);
+        assert.equal(creds.find((c) => c.name === "ci")?.bypassRedaction, true);
+        // Unlisted keys MUST be undefined (not false) so JSON serialisation
+        // omits the field — keeps the audit log payload tidy.
+        assert.equal(creds.find((c) => c.name === "unprivileged")?.bypassRedaction, undefined);
+    });
+    it("OMCP_KEY_BYPASS_REDACTION absent → no key bypasses (least privilege default)", () => {
+        const creds = loadCredentials({ OMCP_API_KEYS: "agent:tok1,ci:tok2" });
+        for (const c of creds)
+            assert.equal(c.bypassRedaction, undefined);
+    });
+    it("parses OMCP_KEY_TENANTS → assigns tenant to named keys; unlisted stays undefined (default)", () => {
+        const creds = loadCredentials({
+            OMCP_API_KEYS: "agent:tok1,ci:tok2,nobody:tok3",
+            OMCP_KEY_TENANTS: "agent=acme;ci=BigCorp",
+        });
+        assert.equal(creds.find((c) => c.name === "agent")?.tenant, "acme");
+        assert.equal(creds.find((c) => c.name === "ci")?.tenant, "bigcorp", "lowercased");
+        assert.equal(creds.find((c) => c.name === "nobody")?.tenant, undefined);
+    });
     it("extractToken handles Bearer and X-API-Key", () => {
         assert.equal(extractToken({ authorization: "Bearer abc" }), "abc");
         assert.equal(extractToken({ authorization: "bearer  xyz " }), "xyz");

package/dist/auth/local-users.d.ts

@@ -0,0 +1,62 @@
+/**
+ * File-backed local user store for the management-plane "basic" auth mode.
+ *
+ * Password verification uses node's built-in `scrypt` so the server has no
+ * extra runtime dependency. The on-disk format is a small JSON document:
+ *
+ *   {
+ *     "users": [
+ *       {
+ *         "username": "alice",
+ *         "name": "Alice Operator",
+ *         "roles": ["operator"],
+ *         "passwordHash": "scrypt$N$r$p$<salt-b64>$<hash-b64>"
+ *       },
+ *       ...
+ *     ]
+ *   }
+ *
+ * The `passwordHash` field uses the PHC-like format `scrypt$N$r$p$salt$hash`,
+ * which encodes the cost parameters alongside the digest so operators can
+ * rotate them without breaking existing entries.
+ *
+ * Use `hashPassword()` to mint a new entry, e.g. from a one-shot CLI helper.
+ */
+export interface LocalUser {
+    username: string;
+    name: string;
+    roles?: string[];
+    /** Optional tenant assignment. Missing → DEFAULT_TENANT. */
+    tenant?: string;
+    passwordHash: string;
+}
+export interface LocalUsersFile {
+    users: LocalUser[];
+}
+/** Default scrypt cost — N=2^15, r=8, p=1. Matches OWASP 2023 baseline. */
+export declare const DEFAULT_SCRYPT_N: number;
+export declare const DEFAULT_SCRYPT_R = 8;
+export declare const DEFAULT_SCRYPT_P = 1;
+/** Produce a `scrypt$…` formatted hash for the given plaintext. */
+export declare function hashPassword(plaintext: string, opts?: {
+    N?: number;
+    r?: number;
+    p?: number;
+}): string;
+/** Upper bounds on scrypt cost parameters accepted during verify.
+ * The users file is operator-controlled, but an accidental typo
+ * ("N=21474836480") shouldn't be able to hang the auth path. The
+ * caps are well above any realistic production setting. */
+export declare const MAX_SCRYPT_N: number;
+export declare const MAX_SCRYPT_R = 16;
+export declare const MAX_SCRYPT_P = 4;
+/** Constant-time verify of a plaintext against a `scrypt$…` hash. */
+export declare function verifyPassword(plaintext: string, encoded: string): boolean;
+/**
+ * Read + parse the users file. Returns `null` (not throws) when the file
+ * doesn't exist or the JSON is malformed so the caller can fall through to
+ * anonymous mode cleanly.
+ */
+export declare function readUsersFile(path: string): Promise<LocalUsersFile | null>;
+/** Find a user by username (case-sensitive) and verify the supplied password. */
+export declare function authenticate(username: string, password: string, store: LocalUsersFile): LocalUser | null;

package/dist/auth/local-users.js

@@ -0,0 +1,143 @@
+/**
+ * File-backed local user store for the management-plane "basic" auth mode.
+ *
+ * Password verification uses node's built-in `scrypt` so the server has no
+ * extra runtime dependency. The on-disk format is a small JSON document:
+ *
+ *   {
+ *     "users": [
+ *       {
+ *         "username": "alice",
+ *         "name": "Alice Operator",
+ *         "roles": ["operator"],
+ *         "passwordHash": "scrypt$N$r$p$<salt-b64>$<hash-b64>"
+ *       },
+ *       ...
+ *     ]
+ *   }
+ *
+ * The `passwordHash` field uses the PHC-like format `scrypt$N$r$p$salt$hash`,
+ * which encodes the cost parameters alongside the digest so operators can
+ * rotate them without breaking existing entries.
+ *
+ * Use `hashPassword()` to mint a new entry, e.g. from a one-shot CLI helper.
+ */
+import { promises as fs } from "node:fs";
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+/** Default scrypt cost — N=2^15, r=8, p=1. Matches OWASP 2023 baseline. */
+export const DEFAULT_SCRYPT_N = 1 << 15;
+export const DEFAULT_SCRYPT_R = 8;
+export const DEFAULT_SCRYPT_P = 1;
+const HASH_KEYLEN = 32;
+/** Produce a `scrypt$…` formatted hash for the given plaintext. */
+export function hashPassword(plaintext, opts = {}) {
+    const N = opts.N ?? DEFAULT_SCRYPT_N;
+    const r = opts.r ?? DEFAULT_SCRYPT_R;
+    const p = opts.p ?? DEFAULT_SCRYPT_P;
+    const salt = randomBytes(16);
+    const hash = scryptSync(plaintext, salt, HASH_KEYLEN, { N, r, p, maxmem: 64 * 1024 * 1024 });
+    return `scrypt$${N}$${r}$${p}$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+/** Upper bounds on scrypt cost parameters accepted during verify.
+ * The users file is operator-controlled, but an accidental typo
+ * ("N=21474836480") shouldn't be able to hang the auth path. The
+ * caps are well above any realistic production setting. */
+export const MAX_SCRYPT_N = 1 << 20; // 1 048 576 — ~1 second on a modern core
+export const MAX_SCRYPT_R = 16;
+export const MAX_SCRYPT_P = 4;
+/** Constant-time verify of a plaintext against a `scrypt$…` hash. */
+export function verifyPassword(plaintext, encoded) {
+    const parts = encoded.split("$");
+    if (parts.length !== 6 || parts[0] !== "scrypt")
+        return false;
+    const N = Number(parts[1]);
+    const r = Number(parts[2]);
+    const p = Number(parts[3]);
+    if (!Number.isFinite(N) || !Number.isFinite(r) || !Number.isFinite(p))
+        return false;
+    if (N <= 0 || r <= 0 || p <= 0)
+        return false;
+    if (N > MAX_SCRYPT_N || r > MAX_SCRYPT_R || p > MAX_SCRYPT_P)
+        return false;
+    let salt;
+    let expected;
+    try {
+        salt = Buffer.from(parts[4], "base64");
+        expected = Buffer.from(parts[5], "base64");
+    }
+    catch {
+        return false;
+    }
+    if (expected.length === 0)
+        return false;
+    let candidate;
+    try {
+        candidate = scryptSync(plaintext, salt, expected.length, { N, r, p, maxmem: 256 * 1024 * 1024 });
+    }
+    catch {
+        return false;
+    }
+    if (candidate.length !== expected.length)
+        return false;
+    return timingSafeEqual(candidate, expected);
+}
+/**
+ * Read + parse the users file. Returns `null` (not throws) when the file
+ * doesn't exist or the JSON is malformed so the caller can fall through to
+ * anonymous mode cleanly.
+ */
+export async function readUsersFile(path) {
+    let raw;
+    try {
+        raw = await fs.readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isUsersFile(parsed))
+        return null;
+    return parsed;
+}
+function isUsersFile(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    if (!Array.isArray(o.users))
+        return false;
+    return o.users.every((u) => {
+        if (!u || typeof u !== "object")
+            return false;
+        const r = u;
+        if (typeof r.username !== "string" || !r.username)
+            return false;
+        if (typeof r.name !== "string")
+            return false;
+        if (typeof r.passwordHash !== "string")
+            return false;
+        if (r.roles !== undefined && !(Array.isArray(r.roles) && r.roles.every((x) => typeof x === "string")))
+            return false;
+        if (r.tenant !== undefined && typeof r.tenant !== "string")
+            return false;
+        return true;
+    });
+}
+/** Find a user by username (case-sensitive) and verify the supplied password. */
+export function authenticate(username, password, store) {
+    const u = store.users.find((x) => x.username === username);
+    if (!u) {
+        // Spend roughly the same time as a real verify so a missing username
+        // isn't trivially distinguishable by response timing.
+        verifyPassword(password, "scrypt$32768$8$1$AAAA$AAAA");
+        return null;
+    }
+    if (!verifyPassword(password, u.passwordHash))
+        return null;
+    return u;
+}

package/dist/auth/local-users.test.d.ts

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

package/dist/auth/local-users.test.js

@@ -0,0 +1,80 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hashPassword, verifyPassword, readUsersFile, authenticate, } from "./local-users.js";
+// Use a smaller N so the test suite stays under a second even on slow CI runners.
+const fastOpts = { N: 1 << 10, r: 8, p: 1 };
+test("hashPassword + verifyPassword — accepts correct password", () => {
+    const hash = hashPassword("hunter2", fastOpts);
+    assert.match(hash, /^scrypt\$1024\$8\$1\$/);
+    assert.equal(verifyPassword("hunter2", hash), true);
+});
+test("verifyPassword — rejects wrong password", () => {
+    const hash = hashPassword("hunter2", fastOpts);
+    assert.equal(verifyPassword("hunter3", hash), false);
+});
+test("verifyPassword — rejects malformed hash", () => {
+    assert.equal(verifyPassword("anything", ""), false);
+    assert.equal(verifyPassword("anything", "plain-text"), false);
+    assert.equal(verifyPassword("anything", "argon2$x$y$z"), false);
+    assert.equal(verifyPassword("anything", "scrypt$$$$$" /* empty fields */), false);
+    assert.equal(verifyPassword("anything", "scrypt$1024$8$1$AAAA$"), false);
+});
+test("verifyPassword — rejects absurd scrypt cost params (DoS guard)", () => {
+    // Far above our MAX_SCRYPT_N / R / P caps. Should fail fast (no hash work).
+    assert.equal(verifyPassword("x", "scrypt$1073741824$8$1$AAAA$AAAA"), false); // N too big
+    assert.equal(verifyPassword("x", "scrypt$32768$1024$1$AAAA$AAAA"), false); // r too big
+    assert.equal(verifyPassword("x", "scrypt$32768$8$1024$AAAA$AAAA"), false); // p too big
+});
+test("readUsersFile — returns null when the file is missing or malformed", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-users-"));
+    try {
+        assert.equal(await readUsersFile(join(dir, "nope.json")), null);
+        const bad = join(dir, "bad.json");
+        await writeFile(bad, "not json", "utf8");
+        assert.equal(await readUsersFile(bad), null);
+        const wrongShape = join(dir, "wrong.json");
+        await writeFile(wrongShape, JSON.stringify({ users: "string-not-array" }), "utf8");
+        assert.equal(await readUsersFile(wrongShape), null);
+        const missingFields = join(dir, "missing.json");
+        await writeFile(missingFields, JSON.stringify({ users: [{ username: "alice" }] }), "utf8");
+        assert.equal(await readUsersFile(missingFields), null);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("authenticate — returns user on correct credentials", () => {
+    const store = {
+        users: [
+            {
+                username: "alice",
+                name: "Alice",
+                roles: ["operator"],
+                passwordHash: hashPassword("hunter2", fastOpts),
+            },
+        ],
+    };
+    const u = authenticate("alice", "hunter2", store);
+    assert.ok(u);
+    assert.equal(u.username, "alice");
+    assert.deepEqual(u.roles, ["operator"]);
+});
+test("authenticate — returns null for unknown user", () => {
+    const store = { users: [] };
+    assert.equal(authenticate("nobody", "x", store), null);
+});
+test("authenticate — returns null for wrong password", () => {
+    const store = {
+        users: [
+            {
+                username: "alice",
+                name: "Alice",
+                passwordHash: hashPassword("hunter2", fastOpts),
+            },
+        ],
+    };
+    assert.equal(authenticate("alice", "wrong", store), null);
+});

package/dist/auth/middleware.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Express middleware wiring for the management-plane auth mode.
+ *
+ * Split into two pieces by design — the cookie-parsing middleware always
+ * runs (so identity-aware handlers like /api/me always see req.session),
+ * and the protected-route gate is mounted explicitly on the routes that
+ * need it. There is no `if (publicPath) next()` shortcut anywhere — the
+ * decision of "what is public" is encoded by which middleware Express
+ * registers on which route, not by a string match at request time.
+ *
+ * When `OMCP_AUTH` is unset or "anonymous" (the default) both middlewares
+ * are no-ops and every existing handler behaves exactly as before.
+ */
+import type { Request, RequestHandler } from "express";
+import { type SessionPayload, type SessionConfig } from "./session.js";
+export type AuthMode = "anonymous" | "basic" | "oidc";
+export interface AuthRuntime {
+    mode: AuthMode;
+    /** Present when mode is "basic" or "oidc" — both mint OMCP session
+     *  cookies the same way, just sourced from local creds vs. an IdP. */
+    session?: SessionConfig;
+    /** When true and `secret` not provided, the server generated one for this
+     * process — sessions will not survive a restart. The wire-up code logs a
+     * warning once when this happens. */
+    secretEphemeral?: boolean;
+    /** OIDC runtime, present only when mode === "oidc". Opaque to this
+     *  module — the OIDC HTTP endpoints in src/index.ts consume it.
+     *  Typed as `unknown` here to avoid importing the OIDC sub-module
+     *  and pulling its node:crypto dependency into the middleware
+     *  surface. The OIDC wire-up casts on the way in. */
+    oidc?: unknown;
+}
+export interface AuthedRequest extends Request {
+    session?: SessionPayload;
+}
+/**
+ * Best-effort cookie resolver. Attaches `req.session` when present and
+ * valid; otherwise leaves it undefined. Always calls `next()`. Mount this
+ * globally so every handler can read the identity.
+ */
+export declare function buildSessionAttacher(runtime: AuthRuntime): RequestHandler;
+/**
+ * Gate. Rejects requests that lack a valid session with HTTP 401 + a JSON
+ * body the UI's fetch wrapper recognises. Mount this on each protected
+ * route or router, NOT globally — paths the operator wants public
+ * (login, /api/me, /api/info, /healthz, ...) simply don't register it.
+ */
+export declare function buildRequireSession(runtime: AuthRuntime): RequestHandler;

package/dist/auth/middleware.js

@@ -0,0 +1,65 @@
+/**
+ * Express middleware wiring for the management-plane auth mode.
+ *
+ * Split into two pieces by design — the cookie-parsing middleware always
+ * runs (so identity-aware handlers like /api/me always see req.session),
+ * and the protected-route gate is mounted explicitly on the routes that
+ * need it. There is no `if (publicPath) next()` shortcut anywhere — the
+ * decision of "what is public" is encoded by which middleware Express
+ * registers on which route, not by a string match at request time.
+ *
+ * When `OMCP_AUTH` is unset or "anonymous" (the default) both middlewares
+ * are no-ops and every existing handler behaves exactly as before.
+ */
+import { readCookie, verifySession } from "./session.js";
+/**
+ * Best-effort cookie resolver. Attaches `req.session` when present and
+ * valid; otherwise leaves it undefined. Always calls `next()`. Mount this
+ * globally so every handler can read the identity.
+ */
+export function buildSessionAttacher(runtime) {
+    const sessionCfg = runtime.session;
+    // In anonymous mode the secret is meaningless — verifySession would
+    // throw on an empty secret — so install a true no-op middleware and
+    // skip every per-request branch.
+    if (runtime.mode === "anonymous" || !sessionCfg) {
+        return function noopAttacher(_req, _res, next) {
+            next();
+        };
+    }
+    return function sessionAttacher(req, _res, next) {
+        // verifySession is a pure parse + HMAC verify. It safely returns
+        // null on empty / null / malformed input, so call it unconditionally
+        // and let the result speak for itself — no attacker-controlled
+        // branch decides whether the check runs.
+        const raw = readCookie(req.headers.cookie || "");
+        const payload = verifySession(raw, sessionCfg);
+        if (payload)
+            req.session = payload;
+        next();
+    };
+}
+/**
+ * Gate. Rejects requests that lack a valid session with HTTP 401 + a JSON
+ * body the UI's fetch wrapper recognises. Mount this on each protected
+ * route or router, NOT globally — paths the operator wants public
+ * (login, /api/me, /api/info, /healthz, ...) simply don't register it.
+ */
+export function buildRequireSession(runtime) {
+    return function requireSession(req, res, next) {
+        if (runtime.mode === "anonymous" || !runtime.session) {
+            next();
+            return;
+        }
+        if (req.session) {
+            next();
+            return;
+        }
+        res.status(401).json({
+            error: "authentication required",
+            mode: runtime.mode,
+            // Recognised by the UI's fetch wrapper to trigger the login modal.
+            code: "OMCP_AUTH_REQUIRED",
+        });
+    };
+}

package/dist/auth/middleware.test.d.ts

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

package/dist/auth/middleware.test.js

@@ -0,0 +1,90 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildSessionAttacher, buildRequireSession } from "./middleware.js";
+import { issueSession } from "./session.js";
+const secret = "x".repeat(48);
+const sessionCfg = { secret };
+function mkReq(opts = {}) {
+    return {
+        path: opts.path ?? "/api/sources",
+        headers: { cookie: opts.cookieHeader || "" },
+    };
+}
+function mkRes() {
+    let statusCode = 0;
+    let body = null;
+    return {
+        status(c) { statusCode = c; return this; },
+        json(b) { body = b; return this; },
+        get statusCode() { return statusCode; },
+        get body() { return body; },
+    };
+}
+test("session attacher — anonymous passes through unchanged, no session", () => {
+    const attach = buildSessionAttacher({ mode: "anonymous" });
+    const req = mkReq();
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(req.session, undefined);
+});
+test("session attacher — basic mode without cookie still flows, no session attached", () => {
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg });
+    const req = mkReq();
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(req.session, undefined);
+});
+test("session attacher — basic mode WITH valid cookie attaches session", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice", roles: ["operator"] }, sessionCfg);
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg });
+    const req = mkReq({ cookieHeader: `omcp_session=${cookie}` });
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.ok(req.session);
+    assert.equal(req.session?.sub, "alice");
+});
+test("session attacher — tampered cookie leaves session undefined and still flows", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, sessionCfg);
+    const tampered = cookie.replace(/.$/, (c) => (c === "A" ? "B" : "A"));
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg });
+    const req = mkReq({ cookieHeader: `omcp_session=${tampered}` });
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(req.session, undefined);
+});
+test("require-session — anonymous always allows", () => {
+    const gate = buildRequireSession({ mode: "anonymous" });
+    const req = mkReq();
+    const res = mkRes();
+    let called = false;
+    gate(req, res, () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(res.statusCode, 0);
+});
+test("require-session — basic mode without session returns 401", () => {
+    const runtime = { mode: "basic", session: sessionCfg };
+    const gate = buildRequireSession(runtime);
+    const req = mkReq();
+    const res = mkRes();
+    let called = false;
+    gate(req, res, () => { called = true; });
+    assert.equal(called, false);
+    assert.equal(res.statusCode, 401);
+    const body = res.body;
+    assert.equal(body.code, "OMCP_AUTH_REQUIRED");
+});
+test("require-session — basic mode WITH attached session flows through", () => {
+    const runtime = { mode: "basic", session: sessionCfg };
+    const gate = buildRequireSession(runtime);
+    const req = mkReq();
+    req.session = { sub: "alice", name: "Alice", iat: 0, exp: Date.now() / 1000 + 60 };
+    const res = mkRes();
+    let called = false;
+    gate(req, res, () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(res.statusCode, 0);
+});

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

@@ -0,0 +1,73 @@
+/**
+ * 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 { type DiscoveryDocument, type Fetcher } from "./discovery.js";
+import { type JwtPayload } from "./jwt.js";
+export interface OidcConfig {
+    /** Issuer URL — what the IdP advertises in its discovery `issuer` field. */
+    issuer: string;
+    clientId: string;
+    /** Confidential clients only. Public/SPA clients omit and rely on PKCE. */
+    clientSecret?: string;
+    /** Absolute callback URL registered with the IdP. */
+    redirectUri: string;
+    /** Space-delimited scopes. Default: "openid profile email". */
+    scopes?: string;
+    /** Custom fetcher (tests). */
+    fetcher?: Fetcher;
+    /** Test clock. */
+    now?: () => number;
+}
+export interface StartResult {
+    /** Where to 302 the browser. */
+    authorizeUrl: string;
+    /** Caller stores these in a short-lived cookie until /callback. */
+    flow: {
+        state: string;
+        nonce: string;
+        codeVerifier: string;
+    };
+}
+export interface CompleteOpts {
+    /** Authorization code from the callback URL. */
+    code: string;
+    /** State returned by the IdP — must match the cookie's flow.state. */
+    state: string;
+    /** The flow object the caller stashed in the cookie at start(). */
+    flow: {
+        state: string;
+        nonce: string;
+        codeVerifier: string;
+    };
+}
+export interface CompleteResult {
+    /** Decoded + verified ID-token claims. */
+    claims: JwtPayload;
+    /** Raw ID token (for upstream propagation if the caller wants it). */
+    idToken: string;
+    /** Access token (opaque). */
+    accessToken?: string;
+}
+export declare class OidcClient {
+    private readonly discovery;
+    private readonly jwks;
+    private readonly cfg;
+    private readonly fetcher;
+    private readonly now;
+    constructor(cfg: OidcConfig);
+    /** Build an authorize URL + mint the state/nonce/PKCE-verifier the
+     * caller must persist until the callback. */
+    start(): Promise<StartResult>;
+    /** Validate the callback: state match → token exchange → ID-token
+     *  signature + claim verification. Throws on any failure. */
+    complete(opts: CompleteOpts): Promise<CompleteResult>;
+    /** Verify a standalone ID token (refresh flows, replay checks). */
+    verify(idToken: string, doc?: DiscoveryDocument, nonce?: string): Promise<JwtPayload>;
+}