@padua/cli 1.13.1 → 2.0.0

package/dist/mcp/token/manager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * OAuthTokenManager — concrete implementation of the TokenManager interface.
+ *
+ * Manages the full token lifecycle for a single OAuth service:
+ * - Transparent refresh with exponential backoff
+ * - Circuit breaker to avoid hammering a failing token endpoint
+ * - Mutex to coalesce concurrent refresh attempts into a single HTTP call
+ * - Optional cloud-ID resolution for Atlassian providers
+ */
+import type { TokenStore, StoredToken } from '../store/types';
+import type { OAuthConfig, TokenManager, TokenResult, TokenStatus } from './types';
+/**
+ * Formats a duration in seconds into a human-readable string.
+ * "2h 15m" when >= 1 hour, "3m 45s" when < 1 hour.
+ */
+export declare function formatExpiresIn(seconds: number): string;
+/**
+ * Maps a raw TokenResult from the token endpoint to the StoredToken shape.
+ * Carries over cloudId/cloudUrl from the existing token when present.
+ */
+export declare function tokenResultToStoredToken(result: TokenResult, existing?: StoredToken): StoredToken;
+export declare class OAuthTokenManager implements TokenManager {
+    private readonly config;
+    private readonly store;
+    private readonly service;
+    private readonly callbackPort;
+    private readonly options?;
+    private consecutiveFailures;
+    private circuitOpenUntil;
+    private retryAfterMs;
+    private refreshPromise;
+    constructor(config: OAuthConfig, store: TokenStore, service: string, callbackPort: number, options?: {
+        cloudIdResolver?: (accessToken: string) => Promise<{
+            cloudId: string;
+            cloudUrl: string;
+        }>;
+        /** Overrides openBrowser for testing. Defaults to the real openBrowser. */
+        openBrowser?: (url: string) => void;
+    });
+    getAccessToken(): Promise<string>;
+    authenticate(): Promise<void>;
+    isAuthenticated(): boolean;
+    getTokenStatus(): TokenStatus;
+    shutdown(): void;
+    private ensureFresh;
+    private doRefresh;
+    /**
+     * Computes and returns the exponential backoff delay in milliseconds.
+     * Base 1000ms, cap 30000ms, ±20% jitter.
+     * The caller decides whether to await it — inline retries are not done here.
+     */
+    private computeBackoffMs;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/mcp/token/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/mcp/token/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAwBnF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,EACnB,QAAQ,CAAC,EAAE,WAAW,GACrB,WAAW,CAgBb;AAMD,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAIvB;IAGF,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,gBAAgB,CAAK;IAE7B,OAAO,CAAC,YAAY,CAAK;IAGzB,OAAO,CAAC,cAAc,CAA8B;gBAGlD,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1F,2EAA2E;QAC3E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;KACrC;IAaG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAKjC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBnC,eAAe,IAAI,OAAO;IAI1B,cAAc,IAAI,WAAW;IAkB7B,QAAQ,IAAI,IAAI;YAYF,WAAW;YA6BX,SAAS;IAkCvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAKzB"}

package/dist/mcp/token/manager.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * OAuthTokenManager — concrete implementation of the TokenManager interface.
+ *
+ * Manages the full token lifecycle for a single OAuth service:
+ * - Transparent refresh with exponential backoff
+ * - Circuit breaker to avoid hammering a failing token endpoint
+ * - Mutex to coalesce concurrent refresh attempts into a single HTTP call
+ * - Optional cloud-ID resolution for Atlassian providers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthTokenManager = void 0;
+exports.formatExpiresIn = formatExpiresIn;
+exports.tokenResultToStoredToken = tokenResultToStoredToken;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("../errors");
+const oauth_1 = require("./oauth");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const EXPIRY_THRESHOLD_SECONDS = 60;
+const MAX_FAILURES = 5;
+const CIRCUIT_OPEN_MS = 5 * 60 * 1000; // 5 minutes
+const BACKOFF_BASE_MS = 1000;
+const BACKOFF_CAP_MS = 30_000;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Formats a duration in seconds into a human-readable string.
+ * "2h 15m" when >= 1 hour, "3m 45s" when < 1 hour.
+ */
+function formatExpiresIn(seconds) {
+    if (seconds <= 0)
+        return '0s';
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = Math.floor(seconds % 60);
+    if (hours > 0) {
+        return `${hours}h ${minutes}m`;
+    }
+    return `${minutes}m ${secs}s`;
+}
+/**
+ * Maps a raw TokenResult from the token endpoint to the StoredToken shape.
+ * Carries over cloudId/cloudUrl from the existing token when present.
+ */
+function tokenResultToStoredToken(result, existing) {
+    const expiresAt = Math.floor(Date.now() / 1000) + result.expiresIn;
+    const scopes = result.scope ? result.scope.split(' ') : (existing?.scopes ?? []);
+    const token = {
+        accessToken: result.accessToken,
+        refreshToken: result.refreshToken,
+        tokenType: result.tokenType,
+        expiresAt,
+        scopes,
+    };
+    if (existing?.cloudId)
+        token.cloudId = existing.cloudId;
+    if (existing?.cloudUrl)
+        token.cloudUrl = existing.cloudUrl;
+    return token;
+}
+// ---------------------------------------------------------------------------
+// OAuthTokenManager
+// ---------------------------------------------------------------------------
+class OAuthTokenManager {
+    config;
+    store;
+    service;
+    callbackPort;
+    options;
+    // Circuit breaker state
+    consecutiveFailures = 0;
+    circuitOpenUntil = 0;
+    // Computed backoff for diagnostics / future retry wiring
+    retryAfterMs = 0;
+    // Refresh mutex — collapses concurrent refresh attempts
+    refreshPromise = null;
+    constructor(config, store, service, callbackPort, options) {
+        this.config = config;
+        this.store = store;
+        this.service = service;
+        this.callbackPort = callbackPort;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    async getAccessToken() {
+        const token = await this.ensureFresh();
+        return token.accessToken;
+    }
+    async authenticate() {
+        const pkce = (0, oauth_1.generatePKCE)();
+        const state = (0, node_crypto_1.randomBytes)(16).toString('hex');
+        const authUrl = (0, oauth_1.buildAuthUrl)(this.config, state, pkce.codeChallenge);
+        const callbackPromise = (0, oauth_1.startCallbackServer)(this.callbackPort, state);
+        const browserFn = this.options?.openBrowser ?? oauth_1.openBrowser;
+        browserFn(authUrl);
+        const { code } = await callbackPromise;
+        const result = await (0, oauth_1.exchangeCode)(this.config, code, pkce.codeVerifier);
+        let token = tokenResultToStoredToken(result);
+        if (this.options?.cloudIdResolver) {
+            const { cloudId, cloudUrl } = await this.options.cloudIdResolver(result.accessToken);
+            token = { ...token, cloudId, cloudUrl };
+        }
+        this.store.upsert(this.service, token);
+    }
+    isAuthenticated() {
+        return this.store.get(this.service) !== null;
+    }
+    getTokenStatus() {
+        const token = this.store.get(this.service);
+        if (!token) {
+            return { authenticated: false, refreshable: false };
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const secondsRemaining = token.expiresAt - now;
+        return {
+            authenticated: true,
+            expiresAt: token.expiresAt,
+            expiresIn: formatExpiresIn(secondsRemaining),
+            refreshable: Boolean(token.refreshToken),
+        };
+    }
+    shutdown() {
+        // Reset circuit-breaker and mutex state
+        this.refreshPromise = null;
+        this.consecutiveFailures = 0;
+        this.circuitOpenUntil = 0;
+        this.retryAfterMs = 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Private: token freshness + mutex
+    // ---------------------------------------------------------------------------
+    async ensureFresh() {
+        const token = this.store.get(this.service);
+        if (!token) {
+            throw new errors_1.AuthError(`Not authenticated for ${this.service}`, errors_1.ErrorCodes.TOKEN_REFRESH_FAILED);
+        }
+        const now = Math.floor(Date.now() / 1000);
+        if (token.expiresAt - now > EXPIRY_THRESHOLD_SECONDS) {
+            return token; // still fresh
+        }
+        // Coalesce concurrent refresh attempts
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.doRefresh(token).finally(() => {
+                this.refreshPromise = null;
+            });
+        }
+        await this.refreshPromise;
+        return this.store.get(this.service);
+    }
+    // ---------------------------------------------------------------------------
+    // Private: circuit breaker + refresh
+    // ---------------------------------------------------------------------------
+    async doRefresh(token) {
+        const now = Date.now();
+        if (this.circuitOpenUntil > now) {
+            throw new errors_1.AuthError(`Circuit breaker open for ${this.service} — too many consecutive refresh failures`, errors_1.ErrorCodes.CIRCUIT_BREAKER_OPEN);
+        }
+        try {
+            const result = await (0, oauth_1.refreshToken)(this.config, token.refreshToken);
+            const refreshed = tokenResultToStoredToken(result, token);
+            this.store.upsert(this.service, refreshed);
+            this.consecutiveFailures = 0;
+            this.retryAfterMs = 0;
+        }
+        catch (err) {
+            this.consecutiveFailures += 1;
+            // Record backoff for diagnostics; no inline sleep — callers surface the
+            // failure immediately and the next call will check the circuit state.
+            this.retryAfterMs = this.computeBackoffMs();
+            if (this.consecutiveFailures >= MAX_FAILURES) {
+                this.circuitOpenUntil = Date.now() + CIRCUIT_OPEN_MS;
+                throw new errors_1.AuthError(`Circuit breaker opened for ${this.service} after ${this.consecutiveFailures} consecutive failures`, errors_1.ErrorCodes.CIRCUIT_BREAKER_OPEN);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Computes and returns the exponential backoff delay in milliseconds.
+     * Base 1000ms, cap 30000ms, ±20% jitter.
+     * The caller decides whether to await it — inline retries are not done here.
+     */
+    computeBackoffMs() {
+        const exponent = Math.min(this.consecutiveFailures - 1, 10);
+        const base = Math.min(BACKOFF_BASE_MS * Math.pow(2, exponent), BACKOFF_CAP_MS);
+        return base * (0.8 + Math.random() * 0.4);
+    }
+}
+exports.OAuthTokenManager = OAuthTokenManager;
+//# sourceMappingURL=manager.js.map

package/dist/mcp/token/manager.js.map

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

package/dist/mcp/token/null-token-manager.d.ts

@@ -0,0 +1,19 @@
+import type { TokenManager, TokenStatus } from './types';
+/**
+ * Null-object TokenManager for testing and fallback.
+ * Two factories: createAuthenticated() returns a manager with a fake token,
+ * createUnauthenticated() returns one that throws on getAccessToken().
+ */
+export declare class NullTokenManager implements TokenManager {
+    private readonly _authenticated;
+    private readonly _token;
+    private constructor();
+    static createAuthenticated(token?: string): NullTokenManager;
+    static createUnauthenticated(): NullTokenManager;
+    getAccessToken(): Promise<string>;
+    authenticate(): Promise<void>;
+    isAuthenticated(): boolean;
+    getTokenStatus(): TokenStatus;
+    shutdown(): void;
+}
+//# sourceMappingURL=null-token-manager.d.ts.map

package/dist/mcp/token/null-token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-token-manager.d.ts","sourceRoot":"","sources":["../../../src/mcp/token/null-token-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzD;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO;IAKP,MAAM,CAAC,mBAAmB,CAAC,KAAK,SAAkC,GAAG,gBAAgB;IAIrF,MAAM,CAAC,qBAAqB,IAAI,gBAAgB;IAI1C,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAOjC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC,eAAe,IAAI,OAAO;IAI1B,cAAc,IAAI,WAAW;IAY7B,QAAQ,IAAI,IAAI;CAGjB"}

package/dist/mcp/token/null-token-manager.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NullTokenManager = void 0;
+/**
+ * Null-object TokenManager for testing and fallback.
+ * Two factories: createAuthenticated() returns a manager with a fake token,
+ * createUnauthenticated() returns one that throws on getAccessToken().
+ */
+class NullTokenManager {
+    _authenticated;
+    _token;
+    constructor(authenticated, token) {
+        this._authenticated = authenticated;
+        this._token = token;
+    }
+    static createAuthenticated(token = 'null-token-manager-fake-token') {
+        return new NullTokenManager(true, token);
+    }
+    static createUnauthenticated() {
+        return new NullTokenManager(false, '');
+    }
+    async getAccessToken() {
+        if (!this._authenticated) {
+            throw new Error('Not authenticated');
+        }
+        return this._token;
+    }
+    async authenticate() {
+        // no-op
+    }
+    isAuthenticated() {
+        return this._authenticated;
+    }
+    getTokenStatus() {
+        if (this._authenticated) {
+            return {
+                authenticated: true,
+                expiresAt: Math.floor(Date.now() / 1000) + 3600,
+                expiresIn: '1h 0m',
+                refreshable: true,
+            };
+        }
+        return { authenticated: false, refreshable: false };
+    }
+    shutdown() {
+        // no-op
+    }
+}
+exports.NullTokenManager = NullTokenManager;
+//# sourceMappingURL=null-token-manager.js.map

package/dist/mcp/token/null-token-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-token-manager.js","sourceRoot":"","sources":["../../../src/mcp/token/null-token-manager.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACH,MAAa,gBAAgB;IACV,cAAc,CAAU;IACxB,MAAM,CAAS;IAEhC,YAAoB,aAAsB,EAAE,KAAa;QACvD,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,MAAM,CAAC,mBAAmB,CAAC,KAAK,GAAG,+BAA+B;QAChE,OAAO,IAAI,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,CAAC,qBAAqB;QAC1B,OAAO,IAAI,gBAAgB,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,QAAQ;IACV,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,cAAc;QACZ,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO;gBACL,aAAa,EAAE,IAAI;gBACnB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI;gBAC/C,SAAS,EAAE,OAAO;gBAClB,WAAW,EAAE,IAAI;aAClB,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACtD,CAAC;IAED,QAAQ;QACN,QAAQ;IACV,CAAC;CACF;AA/CD,4CA+CC"}

package/dist/mcp/token/oauth.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OAuth2 PKCE utilities for the MCP server integration.
+ *
+ * Implements the Authorization Code + PKCE flow as specified in RFC 7636.
+ * All HTTPS requests use the default TLS verification — rejectUnauthorized
+ * is never set to false.
+ */
+import type { OAuthConfig, TokenResult, PKCEPair } from './types';
+/**
+ * Generates a PKCE code verifier and its S256 code challenge.
+ * codeVerifier: 32 random bytes as base64url = 43 characters (RFC 7636 minimum).
+ */
+export declare function generatePKCE(): PKCEPair;
+/**
+ * Constructs the OAuth2 authorization URL with all required query parameters.
+ */
+export declare function buildAuthUrl(config: OAuthConfig, state: string, codeChallenge?: string): string;
+/**
+ * Exchanges an authorization code for tokens at the token endpoint.
+ * Throws AuthError(OAUTH_CODE_EXCHANGE_FAILED) on non-2xx responses.
+ */
+export declare function exchangeCode(config: OAuthConfig, code: string, codeVerifier?: string): Promise<TokenResult>;
+/**
+ * Exchanges a refresh token for a new token set at the token endpoint.
+ * Throws AuthError(TOKEN_REFRESH_FAILED) on non-2xx responses.
+ */
+export declare function refreshToken(config: OAuthConfig, currentRefreshToken: string): Promise<TokenResult>;
+/**
+ * Starts a local HTTP server on 127.0.0.1 to receive the OAuth2 callback.
+ * Resolves with { code, state } on success.
+ * Rejects with AuthError on OAuth error, state mismatch, port conflict, or timeout.
+ * The server is closed after handling the first request or on timeout.
+ * The authorization code is never logged.
+ */
+export declare function startCallbackServer(port: number, expectedState: string, timeoutMs?: number): Promise<{
+    code: string;
+    state: string;
+}>;
+/**
+ * Opens the given URL in the default system browser.
+ * Fire-and-forget — errors are silently ignored.
+ */
+export declare function openBrowser(url: string): void;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/mcp/token/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../../src/mcp/token/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAkBlE;;;GAGG;AACH,wBAAgB,YAAY,IAAI,QAAQ,CAIvC;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAqB/F;AAkFD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CA2BtB;AAMD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAQD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,SAAS,SAAqB,GAC7B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoE1C;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAa7C"}

package/dist/mcp/token/oauth.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * OAuth2 PKCE utilities for the MCP server integration.
+ *
+ * Implements the Authorization Code + PKCE flow as specified in RFC 7636.
+ * All HTTPS requests use the default TLS verification — rejectUnauthorized
+ * is never set to false.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePKCE = generatePKCE;
+exports.buildAuthUrl = buildAuthUrl;
+exports.exchangeCode = exchangeCode;
+exports.refreshToken = refreshToken;
+exports.startCallbackServer = startCallbackServer;
+exports.openBrowser = openBrowser;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const node_child_process_1 = require("node:child_process");
+const node_https_1 = require("node:https");
+const node_http_2 = require("node:http");
+const node_url_1 = require("node:url");
+const errors_1 = require("../errors");
+// ---------------------------------------------------------------------------
+// generatePKCE
+// ---------------------------------------------------------------------------
+/**
+ * Generates a PKCE code verifier and its S256 code challenge.
+ * codeVerifier: 32 random bytes as base64url = 43 characters (RFC 7636 minimum).
+ */
+function generatePKCE() {
+    const codeVerifier = (0, node_crypto_1.randomBytes)(32).toString('base64url');
+    const codeChallenge = (0, node_crypto_1.createHash)('sha256').update(codeVerifier).digest('base64url');
+    return { codeVerifier, codeChallenge };
+}
+// ---------------------------------------------------------------------------
+// buildAuthUrl
+// ---------------------------------------------------------------------------
+/**
+ * Constructs the OAuth2 authorization URL with all required query parameters.
+ */
+function buildAuthUrl(config, state, codeChallenge) {
+    const url = new node_url_1.URL(config.authUrl);
+    url.searchParams.set('client_id', config.clientId);
+    url.searchParams.set('redirect_uri', config.redirectUri);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('scope', config.scopes.join(' '));
+    url.searchParams.set('state', state);
+    if (config.usePKCE && codeChallenge) {
+        url.searchParams.set('code_challenge', codeChallenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+    }
+    if (config.additionalAuthParams) {
+        for (const [key, value] of Object.entries(config.additionalAuthParams)) {
+            url.searchParams.set(key, value);
+        }
+    }
+    return url.toString();
+}
+// ---------------------------------------------------------------------------
+// Internal HTTP POST helper
+// ---------------------------------------------------------------------------
+/**
+ * Posts form-encoded data to a URL using the appropriate protocol module.
+ * Only http: is used for localhost test endpoints; all real endpoints use https:.
+ */
+function postForm(url, params) {
+    return new Promise((resolve, reject) => {
+        const parsed = new node_url_1.URL(url);
+        const body = new node_url_1.URLSearchParams(params).toString();
+        const isHttp = parsed.protocol === 'http:';
+        const requestFn = isHttp ? node_http_2.request : node_https_1.request;
+        const options = {
+            hostname: parsed.hostname,
+            port: parsed.port || (isHttp ? 80 : 443),
+            path: parsed.pathname + parsed.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Length': Buffer.byteLength(body),
+            },
+        };
+        const req = requestFn(options, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                resolve({
+                    status: res.statusCode ?? 0,
+                    body: Buffer.concat(chunks).toString(),
+                });
+            });
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+// ---------------------------------------------------------------------------
+// extractOAuthError — safe extraction of error fields from token endpoint
+// ---------------------------------------------------------------------------
+function extractOAuthError(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const error = parsed.error ?? '';
+        const desc = parsed.error_description ?? '';
+        const detail = [error, desc].filter(Boolean).join(' — ');
+        return detail || 'Unknown error';
+    }
+    catch {
+        return 'Non-JSON error response';
+    }
+}
+// ---------------------------------------------------------------------------
+// mapTokenResponse
+// ---------------------------------------------------------------------------
+function mapTokenResponse(raw) {
+    return {
+        accessToken: raw.access_token,
+        refreshToken: raw.refresh_token,
+        tokenType: raw.token_type,
+        expiresIn: raw.expires_in,
+        scope: raw.scope,
+    };
+}
+// ---------------------------------------------------------------------------
+// exchangeCode
+// ---------------------------------------------------------------------------
+/**
+ * Exchanges an authorization code for tokens at the token endpoint.
+ * Throws AuthError(OAUTH_CODE_EXCHANGE_FAILED) on non-2xx responses.
+ */
+async function exchangeCode(config, code, codeVerifier) {
+    const params = {
+        grant_type: 'authorization_code',
+        client_id: config.clientId,
+        code,
+        redirect_uri: config.redirectUri,
+    };
+    if (config.clientSecret) {
+        params.client_secret = config.clientSecret;
+    }
+    if (codeVerifier) {
+        params.code_verifier = codeVerifier;
+    }
+    const { status, body } = await postForm(config.tokenUrl, params);
+    if (status < 200 || status >= 300) {
+        const detail = extractOAuthError(body);
+        throw new errors_1.AuthError(`Token exchange failed with status ${status}: ${detail}`, errors_1.ErrorCodes.OAUTH_CODE_EXCHANGE_FAILED);
+    }
+    return mapTokenResponse(JSON.parse(body));
+}
+// ---------------------------------------------------------------------------
+// refreshToken
+// ---------------------------------------------------------------------------
+/**
+ * Exchanges a refresh token for a new token set at the token endpoint.
+ * Throws AuthError(TOKEN_REFRESH_FAILED) on non-2xx responses.
+ */
+async function refreshToken(config, currentRefreshToken) {
+    const params = {
+        grant_type: 'refresh_token',
+        client_id: config.clientId,
+        refresh_token: currentRefreshToken,
+    };
+    if (config.clientSecret) {
+        params.client_secret = config.clientSecret;
+    }
+    const { status, body } = await postForm(config.tokenUrl, params);
+    if (status < 200 || status >= 300) {
+        const detail = extractOAuthError(body);
+        throw new errors_1.AuthError(`Token refresh failed with status ${status}: ${detail}`, errors_1.ErrorCodes.TOKEN_REFRESH_FAILED);
+    }
+    return mapTokenResponse(JSON.parse(body));
+}
+// ---------------------------------------------------------------------------
+// startCallbackServer
+// ---------------------------------------------------------------------------
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Starts a local HTTP server on 127.0.0.1 to receive the OAuth2 callback.
+ * Resolves with { code, state } on success.
+ * Rejects with AuthError on OAuth error, state mismatch, port conflict, or timeout.
+ * The server is closed after handling the first request or on timeout.
+ * The authorization code is never logged.
+ */
+function startCallbackServer(port, expectedState, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (action, server) => {
+            if (settled)
+                return;
+            settled = true;
+            server.close(() => action());
+        };
+        const server = (0, node_http_1.createServer)((req, res) => {
+            const reqUrl = new node_url_1.URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+            const errorParam = reqUrl.searchParams.get('error');
+            const errorDescription = reqUrl.searchParams.get('error_description') ?? '';
+            const state = reqUrl.searchParams.get('state') ?? '';
+            const code = reqUrl.searchParams.get('code');
+            if (errorParam) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(`<html><body><h1>Authentication Error</h1><p>${errorParam}: ${errorDescription}</p></body></html>`);
+                settle(() => reject(new errors_1.AuthError(`OAuth error: ${errorParam} — ${errorDescription}`, errors_1.ErrorCodes.OAUTH_CALLBACK_ERROR)), server);
+                return;
+            }
+            if (state !== expectedState) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>State Mismatch</h1><p>OAuth state parameter does not match. Please try again.</p></body></html>');
+                settle(() => reject(new errors_1.AuthError('OAuth state mismatch — possible CSRF attack', errors_1.ErrorCodes.OAUTH_STATE_EXPIRED)), server);
+                return;
+            }
+            if (code) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>Authentication successful</h1><p>You can close this tab.</p></body></html>');
+                settle(() => resolve({ code, state }), server);
+                return;
+            }
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h1>Bad Request</h1><p>Missing authorization code.</p></body></html>');
+        });
+        server.listen(port, '127.0.0.1', () => {
+            const timer = setTimeout(() => {
+                settle(() => reject(new errors_1.AuthError('OAuth callback timed out — no response received', errors_1.ErrorCodes.OAUTH_CALLBACK_TIMEOUT)), server);
+            }, timeoutMs);
+            // Ensure the timer does not prevent the process from exiting
+            timer.unref();
+        });
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                reject(new errors_1.AuthError(`Port ${port} is already in use`, errors_1.ErrorCodes.CALLBACK_PORT_IN_USE));
+                return;
+            }
+            reject(err);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// openBrowser
+// ---------------------------------------------------------------------------
+/**
+ * Opens the given URL in the default system browser.
+ * Fire-and-forget — errors are silently ignored.
+ */
+function openBrowser(url) {
+    const commands = {
+        darwin: 'open',
+        linux: 'xdg-open',
+        win32: 'start',
+    };
+    const cmd = commands[process.platform];
+    if (!cmd)
+        return;
+    (0, node_child_process_1.execFile)(cmd, [url], () => {
+        // intentionally empty — errors are ignored
+    });
+}
+//# sourceMappingURL=oauth.js.map