/**
 * Shared authentication helpers for native extensions and CLI commands.
 *
 * Provides:
 *   - `runOAuthFlow()`      — opens browser for OAuth, returns JWT token
 *   - `ensureAuthenticated()` — checks token validity, triggers OAuth re-login on 401/403
 *   - `isAuthError()`       — checks if an error indicates auth failure
 *
 * Extensions (aexol-mcp, image-generation) call ensureAuthenticated() when they
 * detect an auth failure so the user can re-authenticate without dropping
 * out to the terminal and running `spectral login` manually.
 */
import { type SpectralConfig } from "./config.js";
export interface EnsureAuthResult {
    ok: boolean;
    config: SpectralConfig | null;
    reason?: string;
}
export interface OAuthResult {
    ok: boolean;
    token?: string;
    reason?: string;
}
/**
 * Short human-readable reason strings passed to the landing page via the
 * `reason` URL param so the frontend can render a contextual banner above
 * the login form (e.g. "Please authorize your CLI with your account").
 */
export declare const OAUTH_REASON: {
    /** User ran `spectral login` and chose the browser flow. */
    readonly LOGIN: "login";
    /** User ran `spectral serve` / a command that needs a registered machine. */
    readonly SERVE: "serve";
    /** Background re-auth after a 401/403 from the backend. */
    readonly REAUTH: "reauth";
    /** Aexol Studio authorization step. */
    readonly STUDIO: "studio";
};
export type OAuthReason = (typeof OAUTH_REASON)[keyof typeof OAUTH_REASON];
/**
 * Run the OAuth browser flow to obtain a fresh JWT token.
 *
 * Opens the user's browser to the Aexol Studio CLI auth page. The landing
 * app redirects back to localhost with a JWT in the query string.
 *
 * Returns `{ ok: true, token }` on success, `{ ok: false, reason }` on failure.
 */
export declare function runOAuthFlow(apiUrl?: string, timeoutMs?: number, reason?: OAuthReason): Promise<OAuthResult>;
/** Check if an error indicates an authentication failure (401 or 403). */
export declare function isAuthError(err: unknown): boolean;
/**
 * Ensure the user is authenticated.
 *
 * Call this when a tool or extension encounters an auth error (401/403).
 * It verifies the current token is valid by pinging the backend. If the
 * token is expired or missing, it triggers the OAuth browser flow.
 *
 * Only attempts OAuth re-login when stdout is a TTY (interactive session).
 * In headless/CI environments, it returns `{ ok: false }` immediately.
 *
 * Returns `{ ok: true, config }` with fresh config on success,
 * or `{ ok: false, reason }` when auth could not be established.
 */
export declare function ensureAuthenticated(): Promise<EnsureAuthResult>;
//# sourceMappingURL=auth-helper.d.ts.map