@confluentinc/mcp-confluent 1.2.2 → 1.3.0

package/dist/confluent/oauth/oauth-holder.js

@@ -0,0 +1,155 @@
+import { AuthContext } from "../../confluent/oauth/auth-context.js";
+import { getAuth0Config } from "../../confluent/oauth/auth0-config.js";
+import { generateOpaqueToken } from "../../confluent/oauth/crypto-utils.js";
+import { hasNonTransientError } from "../../confluent/oauth/errors.js";
+import { PkceLoginError, runPkceLogin, } from "../../confluent/oauth/pkce-login.js";
+import { TelemetryEvent, TelemetryService } from "../../confluent/telemetry.js";
+import { logger } from "../../logger.js";
+/**
+ * Owns the process's {@link AuthContext} and lazily drives PKCE on demand.
+ * Construction is side-effect-free; callers go through {@link ensureLoggedIn}.
+ *
+ * State machine:
+ *   - Idle: starts PKCE.
+ *   - Logging in: concurrent callers share the in-flight Promise.
+ *   - Logged in: no-op (or single-flight refresh if bearer tokens are stale).
+ *   - Failed / refresh-family expired: clears ctx and starts a fresh PKCE.
+ *   - Shut down: rejects.
+ */
+export class OAuthHolder {
+    env;
+    ctx;
+    cleared = false;
+    abortController = new AbortController();
+    inFlightLogin = null;
+    constructor(env) {
+        this.env = env;
+    }
+    getControlPlaneToken() {
+        return this.ctx?.getControlPlaneToken();
+    }
+    getDataPlaneToken() {
+        return this.ctx?.getDataPlaneToken();
+    }
+    /**
+     * Ensure the holder has usable bearer tokens, starting PKCE on demand.
+     * Single-flight, replayable after a PKCE failure, rejects after shutdown.
+     */
+    async ensureLoggedIn() {
+        if (this.cleared) {
+            throw new Error("OAuthHolder is shut down");
+        }
+        if (this.inFlightLogin) {
+            return this.inFlightLogin;
+        }
+        if (this.ctx) {
+            if (this.ctx.refreshTokenExpired() ||
+                hasNonTransientError(this.ctx.getErrors())) {
+                this.ctx.clear();
+                this.ctx = undefined;
+                // fall through to PKCE
+            }
+            else if (this.ctx.getControlPlaneToken() !== undefined &&
+                this.ctx.getDataPlaneToken() !== undefined) {
+                return;
+            }
+            else {
+                // Refresh token alive but bearer tokens stale (e.g., system sleep
+                // suspended the refresh-loop tick). Refresh on demand rather than
+                // re-prompt; `AuthContext.refresh()` joins any in-flight refresh.
+                await this.ctx.refresh();
+                if (this.cleared) {
+                    throw new Error("OAuthHolder is shut down");
+                }
+                if (this.ctx.getControlPlaneToken() !== undefined &&
+                    this.ctx.getDataPlaneToken() !== undefined) {
+                    return;
+                }
+                // Refresh didn't restore tokens. Surface a retry-friendly error
+                // rather than launch a browser; if the failure becomes
+                // non-transient, the next call falls through to PKCE.
+                throw new Error("OAuth bearer tokens unavailable after refresh; retry the tool call");
+            }
+        }
+        this.inFlightLogin = this.runLogin().finally(() => {
+            this.inFlightLogin = null;
+        });
+        return this.inFlightLogin;
+    }
+    /**
+     * Terminal — clears ctx (which stops the refresh loop) and aborts any
+     * in-flight PKCE. Idempotent.
+     */
+    shutdown() {
+        this.ctx?.clear();
+        this.ctx = undefined;
+        this.cleared = true;
+        this.abortController.abort();
+    }
+    async runLogin() {
+        const auth0Config = getAuth0Config(this.env);
+        logger.info({ env: this.env }, "Starting OAuth login");
+        let tokenChain;
+        try {
+            tokenChain = await runPkceLogin(auth0Config, this.abortController.signal);
+        }
+        catch (err) {
+            // The MCP tool-call wrapper rethrows but doesn't log; surface the
+            // failure here so server stderr captures the cause (timeout,
+            // port_in_use, configuration, user_aborted).
+            const reason = err instanceof PkceLoginError ? err.reason : undefined;
+            if (this.cleared) {
+                logger.info({ env: this.env }, "OAuth login aborted by shutdown");
+            }
+            else {
+                logger.error({ env: this.env, err, reason }, "OAuth login failed");
+            }
+            TelemetryService.getInstance().track(TelemetryEvent.CCLOUD_AUTHENTICATION, {
+                status: "error",
+                ccloudUserId: undefined,
+                ccloudDomain: undefined,
+                failureReason: reason,
+            });
+            throw err;
+        }
+        if (this.cleared) {
+            // shutdown() raced with PKCE completion — discard the tokens we just
+            // obtained rather than attaching them to a holder that's been
+            // explicitly torn down. Emit a terminal-outcome event so the warehouse
+            // still counts this attempt; the `user_aborted` reason matches what
+            // an upstream shutdown signal implies.
+            logger.info({ env: this.env }, "OAuth login completed but holder was cleared; discarding tokens");
+            TelemetryService.getInstance().track(TelemetryEvent.CCLOUD_AUTHENTICATION, {
+                status: "error",
+                ccloudUserId: undefined,
+                ccloudDomain: undefined,
+                failureReason: "user_aborted",
+            });
+            return;
+        }
+        // Explicit field copy: `TokenChainResult` carries identity fields
+        // (`resourceId`, `email`) that aren't part of `ConfluentTokenSet` and
+        // would otherwise be retained on the long-lived `AuthContext` via a
+        // spread. Pin the token set to just token material.
+        const tokens = {
+            refreshToken: tokenChain.refreshToken,
+            refreshTokenAbsoluteExpiresAt: tokenChain.refreshTokenAbsoluteExpiresAt,
+            refreshTokenIdleExpiresAt: tokenChain.refreshTokenIdleExpiresAt,
+            controlPlaneToken: tokenChain.controlPlaneToken,
+            controlPlaneExpiresAt: tokenChain.controlPlaneExpiresAt,
+            dataPlaneToken: tokenChain.dataPlaneToken,
+            dataPlaneExpiresAt: tokenChain.dataPlaneExpiresAt,
+            accessToken: generateOpaqueToken(),
+        };
+        const ctx = AuthContext.fromTokens(auth0Config, tokens);
+        ctx.startRefreshLoop();
+        this.ctx = ctx;
+        logger.info({ env: this.env }, "OAuth login successful");
+        TelemetryService.getInstance().track(TelemetryEvent.CCLOUD_AUTHENTICATION, {
+            status: "success",
+            ccloudUserId: tokenChain.resourceId,
+            ccloudDomain: tokenChain.email?.split("@")[1],
+        });
+    }
+}
+//# sourceMappingURL=oauth-holder.js.map

package/dist/confluent/oauth/oauth-holder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-holder.js","sourceRoot":"","sources":["../../../src/confluent/oauth/oauth-holder.ts"],"names":[],"mappings":"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"}

package/dist/confluent/oauth/pkce-login.d.ts

@@ -0,0 +1,26 @@
+import { type TokenChainResult } from "../../confluent/oauth/token-chain.js";
+import type { Auth0Config } from "../../confluent/oauth/types.js";
+/** Maximum time to wait for the user to complete the browser PKCE flow. */
+export declare const PKCE_LOGIN_TIMEOUT_MS = 120000;
+/** Reasons a PKCE login can fail. Carried on {@link PkceLoginError}. */
+export type PkceLoginFailureReason = "timeout" | "user_aborted" | "port_in_use" | "auth0_unreachable" | "configuration";
+/** Structured error so callers can react to the cause of a failed PKCE login. */
+export declare class PkceLoginError extends Error {
+    readonly reason: PkceLoginFailureReason;
+    constructor(reason: PkceLoginFailureReason, message: string);
+}
+/**
+ * Runs the PKCE flow end-to-end:
+ *  - generates verifier / challenge / state
+ *  - binds a one-shot HTTP listener on {@link OAUTH_CALLBACK_PORT}
+ *  - opens the browser to the Auth0 authorization endpoint
+ *  - waits for the redirect carrying the auth code
+ *  - exchanges the code for the full Confluent token chain
+ *
+ * Bounded by {@link PKCE_LOGIN_TIMEOUT_MS}. Throws {@link PkceLoginError} on
+ * failure with a structured `reason`. If `signal` aborts before the auth
+ * code arrives, throws `PkceLoginError("user_aborted", ...)` and the finally
+ * block tears down the timer + HTTP server.
+ */
+export declare function runPkceLogin(auth0Config: Auth0Config, signal?: AbortSignal): Promise<TokenChainResult>;
+//# sourceMappingURL=pkce-login.d.ts.map

package/dist/confluent/oauth/pkce-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce-login.d.ts","sourceRoot":"","sources":["../../../src/confluent/oauth/pkce-login.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAGjE,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAE7C,wEAAwE;AACxE,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,cAAc,GACd,aAAa,GACb,mBAAmB,GACnB,eAAe,CAAC;AAEpB,iFAAiF;AACjF,qBAAa,cAAe,SAAQ,KAAK;aAErB,MAAM,EAAE,sBAAsB;gBAA9B,MAAM,EAAE,sBAAsB,EAC9C,OAAO,EAAE,MAAM;CAKlB;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,WAAW,EACxB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAqJ3B"}

package/dist/confluent/oauth/pkce-login.js

@@ -0,0 +1,161 @@
+import { nodeHttp, nodeOpen } from "../../confluent/node-deps.js";
+import { OAUTH_CALLBACK_HOST, OAUTH_CALLBACK_PATH, OAUTH_CALLBACK_PORT, } from "../../confluent/oauth/auth0-config.js";
+import { renderErrorPage, renderSuccessPage, } from "../../confluent/oauth/callback-pages.js";
+import { generateCodeChallenge, generateCodeVerifier, generateOpaqueToken, } from "../../confluent/oauth/crypto-utils.js";
+import { executeFullTokenChain, } from "../../confluent/oauth/token-chain.js";
+import { logger } from "../../logger.js";
+/** Maximum time to wait for the user to complete the browser PKCE flow. */
+export const PKCE_LOGIN_TIMEOUT_MS = 120_000;
+/** Structured error so callers can react to the cause of a failed PKCE login. */
+export class PkceLoginError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "PkceLoginError";
+    }
+}
+function sendHtml(res, status, body) {
+    res.writeHead(status, { "Content-Type": "text/html; charset=UTF-8" });
+    res.end(body);
+}
+function buildAuthorizationUrl(auth0Config, codeChallenge, state) {
+    const params = new URLSearchParams({
+        client_id: auth0Config.clientId,
+        response_type: "code",
+        redirect_uri: auth0Config.callbackUrl,
+        scope: auth0Config.scopes,
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+        state,
+    });
+    return `https://${auth0Config.domain}/authorize?${params.toString()}`;
+}
+/**
+ * Runs the PKCE flow end-to-end:
+ *  - generates verifier / challenge / state
+ *  - binds a one-shot HTTP listener on {@link OAUTH_CALLBACK_PORT}
+ *  - opens the browser to the Auth0 authorization endpoint
+ *  - waits for the redirect carrying the auth code
+ *  - exchanges the code for the full Confluent token chain
+ *
+ * Bounded by {@link PKCE_LOGIN_TIMEOUT_MS}. Throws {@link PkceLoginError} on
+ * failure with a structured `reason`. If `signal` aborts before the auth
+ * code arrives, throws `PkceLoginError("user_aborted", ...)` and the finally
+ * block tears down the timer + HTTP server.
+ */
+export async function runPkceLogin(auth0Config, signal) {
+    // Early abort: skip the bind/open work entirely if the caller has already
+    // signaled cancellation.
+    if (signal?.aborted) {
+        throw new PkceLoginError("user_aborted", "PKCE login aborted");
+    }
+    if (!auth0Config.clientId) {
+        throw new PkceLoginError("configuration", "Auth0 clientId is not configured for the selected environment");
+    }
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const state = generateOpaqueToken();
+    let resolveCode = () => undefined;
+    let rejectFlow = () => undefined;
+    const codePromise = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectFlow = reject;
+    });
+    const server = nodeHttp.createServer((req, res) => {
+        const reqUrl = req.url ?? "";
+        const parsed = new URL(reqUrl, "http://127.0.0.1");
+        if (parsed.pathname !== OAUTH_CALLBACK_PATH) {
+            sendHtml(res, 404, renderErrorPage("Not found"));
+            return;
+        }
+        const receivedState = parsed.searchParams.get("state");
+        if (receivedState !== state) {
+            sendHtml(res, 400, renderErrorPage("State mismatch"));
+            return;
+        }
+        const errorParam = parsed.searchParams.get("error");
+        if (errorParam) {
+            sendHtml(res, 400, renderErrorPage(`Authentication failed: ${errorParam}`));
+            rejectFlow(new PkceLoginError("user_aborted", `Auth0 redirect carried error=${errorParam}`));
+            return;
+        }
+        const code = parsed.searchParams.get("code");
+        if (!code) {
+            sendHtml(res, 400, renderErrorPage("Missing authorization code"));
+            return;
+        }
+        sendHtml(res, 200, renderSuccessPage());
+        resolveCode(code);
+    });
+    let bound = false;
+    const bindResult = new Promise((resolve, reject) => {
+        const onBindError = (err) => {
+            if (err.code === "EADDRINUSE") {
+                reject(new PkceLoginError("port_in_use", `Port ${OAUTH_CALLBACK_PORT} is already in use; another mcp-confluent OAuth session may be active`));
+            }
+            else {
+                reject(new PkceLoginError("configuration", `Failed to bind PKCE callback server on ${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}: ${err.message}`));
+            }
+        };
+        server.on("error", onBindError);
+        server.listen(OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_HOST, () => {
+            bound = true;
+            server.off("error", onBindError);
+            // Replace the bind-time rejector with a log-only listener so a stray
+            // post-bind socket error doesn't escape as an uncaught 'error' event.
+            server.on("error", (err) => {
+                logger.warn({ err }, "PKCE callback server post-bind error");
+            });
+            resolve();
+        });
+    });
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new PkceLoginError("timeout", `PKCE login timed out after ${PKCE_LOGIN_TIMEOUT_MS}ms`));
+        }, PKCE_LOGIN_TIMEOUT_MS);
+    });
+    // One abortPromise + listener races every long-lived await below, so a
+    // cancellation observed during bind/open also unblocks promptly.
+    let abortListener;
+    const abortPromise = new Promise((_, reject) => {
+        abortListener = () => reject(new PkceLoginError("user_aborted", "PKCE login aborted"));
+        signal?.addEventListener("abort", abortListener, { once: true });
+    });
+    let authCode;
+    try {
+        await Promise.race([bindResult, abortPromise]);
+        try {
+            await Promise.race([
+                nodeOpen.open(buildAuthorizationUrl(auth0Config, codeChallenge, state)),
+                abortPromise,
+            ]);
+        }
+        catch (err) {
+            // Preserve user_aborted from the race; wrap any other open() failure.
+            if (err instanceof PkceLoginError)
+                throw err;
+            throw new PkceLoginError("configuration", `Failed to open browser: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        authCode = await Promise.race([codePromise, timeoutPromise, abortPromise]);
+    }
+    finally {
+        // Remove the abort listener if the race resolved via something other
+        // than abort, so we don't leak a listener on a long-lived AbortSignal.
+        if (signal && abortListener) {
+            signal.removeEventListener("abort", abortListener);
+        }
+        clearTimeout(timer);
+        if (bound)
+            server.close();
+    }
+    logger.info("PKCE auth code received; exchanging for token chain");
+    try {
+        return await executeFullTokenChain(auth0Config, authCode, codeVerifier);
+    }
+    catch (err) {
+        throw new PkceLoginError("auth0_unreachable", `Token chain failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=pkce-login.js.map

package/dist/confluent/oauth/pkce-login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce-login.js","sourceRoot":"","sources":["../../../src/confluent/oauth/pkce-login.ts"],"names":[],"mappings":"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"}

package/dist/confluent/oauth/token-chain.d.ts

@@ -0,0 +1,53 @@
+import type { Auth0Config, Auth0TokenResponse, ControlPlaneTokenResponse, DataPlaneTokenResponse } from "../../confluent/oauth/types.js";
+/** Result of a full initial-login token chain from {@link executeFullTokenChain}. */
+export interface TokenChainResult {
+    refreshToken: string;
+    /** Set once on initial login and preserved across subsequent refreshes. */
+    refreshTokenAbsoluteExpiresAt: number;
+    /** Set on initial login; subsequent refreshes bump this value in the store directly. */
+    refreshTokenIdleExpiresAt: number;
+    controlPlaneToken: string;
+    controlPlaneExpiresAt: number;
+    dataPlaneToken: string;
+    dataPlaneExpiresAt: number;
+    /**
+     * User identity fields lifted from the `/api/sessions` response body
+     * (`response.user`). Surface here so callers (the OAuth holder) can
+     * attach the user's identity to telemetry without having to parse the
+     * raw CP response themselves. Either field is `undefined` when the
+     * response omits `user` or the underlying field.
+     */
+    resourceId: string | undefined;
+    email: string | undefined;
+}
+/**
+ * Exchanges an authorization code for Auth0 tokens (ID token + refresh token).
+ * This is the first step in the Confluent token chain.
+ */
+export declare function exchangeAuthCodeForTokens(auth0Config: Auth0Config, authCode: string, codeVerifier: string): Promise<Auth0TokenResponse>;
+/**
+ * Exchanges an Auth0 ID token for a Confluent Cloud control plane token.
+ * POST {apiUrl}/api/sessions with the ID token in the body.
+ */
+export declare function exchangeIdTokenForControlPlaneToken(apiUrl: string, idToken: string): Promise<ControlPlaneTokenResponse>;
+/**
+ * Exchanges a control plane token for a Confluent Cloud data plane token.
+ * POST {apiUrl}/api/access_tokens with the CP token as Bearer auth.
+ */
+export declare function exchangeControlPlaneForDataPlaneToken(apiUrl: string, controlPlaneToken: string): Promise<DataPlaneTokenResponse>;
+/**
+ * Exchanges a refresh token for a new Auth0 token set (ID token + rotated
+ * refresh token). This is a single-use destructive operation: on success the
+ * old refresh token is invalidated by Auth0. Callers that then derive CP/DP
+ * tokens should persist the new refresh token BEFORE the CP/DP calls so a
+ * failure there doesn't lose the rotated token.
+ */
+export declare function exchangeRefreshTokenForAuth0Tokens(auth0Config: Auth0Config, refreshToken: string): Promise<Auth0TokenResponse>;
+/**
+ * Runs the full token chain from an authorization code.
+ * auth code → ID token + refresh token → control plane → data plane
+ *
+ * Sets both absolute (8hr) and idle (4hr) refresh token expiry.
+ */
+export declare function executeFullTokenChain(auth0Config: Auth0Config, authCode: string, codeVerifier: string): Promise<TokenChainResult>;
+//# sourceMappingURL=token-chain.d.ts.map

package/dist/confluent/oauth/token-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-chain.d.ts","sourceRoot":"","sources":["../../../src/confluent/oauth/token-chain.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,+BAA+B,CAAC;AAMvC,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,6BAA6B,EAAE,MAAM,CAAC;IACtC,wFAAwF;IACxF,yBAAyB,EAAE,MAAM,CAAC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAoCD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAyB7B;AAED;;;GAGG;AACH,wBAAsB,mCAAmC,CACvD,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,yBAAyB,CAAC,CAcpC;AAED;;;GAGG;AACH,wBAAsB,qCAAqC,CACzD,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,sBAAsB,CAAC,CAiBjC;AAED;;;;;;GAMG;AACH,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAuB7B;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CA6B3B"}

package/dist/confluent/oauth/token-chain.js

@@ -0,0 +1,141 @@
+import { nodeFetch } from "../../confluent/node-deps.js";
+import { CONTROL_PLANE_TOKEN_LIFETIME_MS, DATA_PLANE_TOKEN_LIFETIME_MS, REFRESH_TOKEN_ABSOLUTE_LIFETIME_MS, REFRESH_TOKEN_IDLE_LIFETIME_MS, } from "../../confluent/oauth/token-lifetimes.js";
+import { logger } from "../../logger.js";
+/** Per-request timeout bounding each Auth0/Confluent HTTP call. */
+const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * POSTs to the OAuth/Confluent endpoint and returns the decoded JSON body,
+ * throwing a labeled error when the response is not OK. Each request is bounded
+ * by {@link REQUEST_TIMEOUT_MS} so a hung Auth0/Confluent call can't stall the
+ * refresh loop.
+ */
+async function postJson(url, init, operation) {
+    let response;
+    try {
+        response = await nodeFetch.fetch(url, {
+            ...init,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "TimeoutError") {
+            logger.error(`${operation} timed out`);
+            throw new Error(`${operation} timed out after ${REQUEST_TIMEOUT_MS}ms`);
+        }
+        throw err;
+    }
+    if (!response.ok) {
+        const errorText = await response.text();
+        logger.error({ status: response.status }, `${operation} failed`);
+        throw new Error(`${operation} failed (${response.status}): ${errorText}`);
+    }
+    return (await response.json());
+}
+/**
+ * Exchanges an authorization code for Auth0 tokens (ID token + refresh token).
+ * This is the first step in the Confluent token chain.
+ */
+export async function exchangeAuthCodeForTokens(auth0Config, authCode, codeVerifier) {
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: auth0Config.clientId,
+        code: authCode,
+        code_verifier: codeVerifier,
+        redirect_uri: auth0Config.callbackUrl,
+    });
+    const response = await postJson(`https://${auth0Config.domain}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    }, "Auth0 token exchange");
+    if (!response.id_token) {
+        throw new Error("Auth0 token exchange: missing id_token");
+    }
+    if (!response.refresh_token) {
+        throw new Error("Auth0 token exchange: missing refresh_token");
+    }
+    return response;
+}
+/**
+ * Exchanges an Auth0 ID token for a Confluent Cloud control plane token.
+ * POST {apiUrl}/api/sessions with the ID token in the body.
+ */
+export async function exchangeIdTokenForControlPlaneToken(apiUrl, idToken) {
+    const response = await postJson(`${apiUrl}/api/sessions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ id_token: idToken }),
+    }, "Control plane token exchange");
+    if (!response.token) {
+        throw new Error("Control plane token exchange: missing token");
+    }
+    return response;
+}
+/**
+ * Exchanges a control plane token for a Confluent Cloud data plane token.
+ * POST {apiUrl}/api/access_tokens with the CP token as Bearer auth.
+ */
+export async function exchangeControlPlaneForDataPlaneToken(apiUrl, controlPlaneToken) {
+    const response = await postJson(`${apiUrl}/api/access_tokens`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${controlPlaneToken}`,
+        },
+        body: JSON.stringify({}),
+    }, "Data plane token exchange");
+    if (!response.token) {
+        throw new Error("Data plane token exchange: missing token");
+    }
+    return response;
+}
+/**
+ * Exchanges a refresh token for a new Auth0 token set (ID token + rotated
+ * refresh token). This is a single-use destructive operation: on success the
+ * old refresh token is invalidated by Auth0. Callers that then derive CP/DP
+ * tokens should persist the new refresh token BEFORE the CP/DP calls so a
+ * failure there doesn't lose the rotated token.
+ */
+export async function exchangeRefreshTokenForAuth0Tokens(auth0Config, refreshToken) {
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: auth0Config.clientId,
+        refresh_token: refreshToken,
+    });
+    const response = await postJson(`https://${auth0Config.domain}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    }, "Auth0 token refresh");
+    if (!response.id_token) {
+        throw new Error("Auth0 token refresh: missing id_token");
+    }
+    if (!response.refresh_token) {
+        throw new Error("Auth0 token refresh: missing refresh_token");
+    }
+    return response;
+}
+/**
+ * Runs the full token chain from an authorization code.
+ * auth code → ID token + refresh token → control plane → data plane
+ *
+ * Sets both absolute (8hr) and idle (4hr) refresh token expiry.
+ */
+export async function executeFullTokenChain(auth0Config, authCode, codeVerifier) {
+    const auth0Response = await exchangeAuthCodeForTokens(auth0Config, authCode, codeVerifier);
+    const cpResponse = await exchangeIdTokenForControlPlaneToken(auth0Config.apiUrl, auth0Response.id_token);
+    const dpResponse = await exchangeControlPlaneForDataPlaneToken(auth0Config.apiUrl, cpResponse.token);
+    const now = Date.now();
+    return {
+        refreshToken: auth0Response.refresh_token,
+        refreshTokenAbsoluteExpiresAt: now + REFRESH_TOKEN_ABSOLUTE_LIFETIME_MS,
+        refreshTokenIdleExpiresAt: now + REFRESH_TOKEN_IDLE_LIFETIME_MS,
+        controlPlaneToken: cpResponse.token,
+        controlPlaneExpiresAt: now + CONTROL_PLANE_TOKEN_LIFETIME_MS,
+        dataPlaneToken: dpResponse.token,
+        dataPlaneExpiresAt: now + DATA_PLANE_TOKEN_LIFETIME_MS,
+        resourceId: cpResponse.user?.resource_id,
+        email: cpResponse.user?.email,
+    };
+}
+//# sourceMappingURL=token-chain.js.map

package/dist/confluent/oauth/token-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-chain.js","sourceRoot":"","sources":["../../../src/confluent/oauth/token-chain.ts"],"names":[],"mappings":"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"}

package/dist/confluent/oauth/token-lifetimes.d.ts

@@ -0,0 +1,13 @@
+/** 5 minutes in milliseconds — control plane token lifetime */
+export declare const CONTROL_PLANE_TOKEN_LIFETIME_MS: number;
+/** 10 minutes in milliseconds — data plane token lifetime */
+export declare const DATA_PLANE_TOKEN_LIFETIME_MS: number;
+/** 8 hours in milliseconds — refresh token absolute lifetime from original login */
+export declare const REFRESH_TOKEN_ABSOLUTE_LIFETIME_MS: number;
+/** 4 hours in milliseconds — refresh token idle timeout, resets on each rotation */
+export declare const REFRESH_TOKEN_IDLE_LIFETIME_MS: number;
+/** 30 seconds in milliseconds — refresh control plane token this much before expiry */
+export declare const CONTROL_PLANE_REFRESH_WINDOW_MS: number;
+/** Failure count at which the auth context is flagged as permanently failed. */
+export declare const MAX_CONSECUTIVE_TRANSIENT_FAILURES = 50;
+//# sourceMappingURL=token-lifetimes.d.ts.map

package/dist/confluent/oauth/token-lifetimes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-lifetimes.d.ts","sourceRoot":"","sources":["../../../src/confluent/oauth/token-lifetimes.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,eAAO,MAAM,+BAA+B,QAAgB,CAAC;AAE7D,6DAA6D;AAC7D,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAE3D,oFAAoF;AACpF,eAAO,MAAM,kCAAkC,QAAqB,CAAC;AAErE,oFAAoF;AACpF,eAAO,MAAM,8BAA8B,QAAqB,CAAC;AAEjE,uFAAuF;AACvF,eAAO,MAAM,+BAA+B,QAAY,CAAC;AAEzD,gFAAgF;AAChF,eAAO,MAAM,kCAAkC,KAAK,CAAC"}

package/dist/confluent/oauth/token-lifetimes.js

@@ -0,0 +1,13 @@
+/** 5 minutes in milliseconds — control plane token lifetime */
+export const CONTROL_PLANE_TOKEN_LIFETIME_MS = 5 * 60 * 1000;
+/** 10 minutes in milliseconds — data plane token lifetime */
+export const DATA_PLANE_TOKEN_LIFETIME_MS = 10 * 60 * 1000;
+/** 8 hours in milliseconds — refresh token absolute lifetime from original login */
+export const REFRESH_TOKEN_ABSOLUTE_LIFETIME_MS = 8 * 60 * 60 * 1000;
+/** 4 hours in milliseconds — refresh token idle timeout, resets on each rotation */
+export const REFRESH_TOKEN_IDLE_LIFETIME_MS = 4 * 60 * 60 * 1000;
+/** 30 seconds in milliseconds — refresh control plane token this much before expiry */
+export const CONTROL_PLANE_REFRESH_WINDOW_MS = 30 * 1000;
+/** Failure count at which the auth context is flagged as permanently failed. */
+export const MAX_CONSECUTIVE_TRANSIENT_FAILURES = 50;
+//# sourceMappingURL=token-lifetimes.js.map

package/dist/confluent/oauth/token-lifetimes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-lifetimes.js","sourceRoot":"","sources":["../../../src/confluent/oauth/token-lifetimes.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE7D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3D,oFAAoF;AACpF,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAErE,oFAAoF;AACpF,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjE,uFAAuF;AACvF,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,GAAG,IAAI,CAAC;AAEzD,gFAAgF;AAChF,MAAM,CAAC,MAAM,kCAAkC,GAAG,EAAE,CAAC"}