import { type LoadResult, type TokenStore } from "./tokenStore";
/** Options for `getValidAccessToken`. */
export interface GetValidAccessTokenOptions {
    /** OIDC issuer URL. Must match the stored entry's `issuerURL`; mismatch throws NOT_AUTHENTICATED. */
    issuerURL: string;
    /** OAuth client identifier. Must match the stored entry's `clientId`; same mismatch behavior as `issuerURL`. */
    clientId: string;
    /**
     * How close to expiry preemptive refresh kicks in, in ms. Default
     * 60_000. Buffer covers clock skew vs. the server. Assumes
     * access-token TTL ≫ this; otherwise every call refreshes.
     */
    expiryBufferMs?: number;
    /** Override for the token store. */
    tokenStore?: TokenStore;
    /** Pre-loaded `tokenStore.load()` result so the dispatcher's keychain read isn't repeated. */
    loadedEntry?: LoadResult;
    /** Aborts discovery + the refresh POST when fired. */
    signal?: AbortSignal;
    /** Forwarded to discovery; permits non-loopback http. */
    allowInsecureIssuer?: boolean;
    /** Called for soft warnings (e.g. rotated tokens couldn't be persisted — see HAZARD note in the body). Default prints to stderr only when stderr is a TTY. */
    onWarning?: (message: string) => void;
    /** Source of `now`. Defaults to `Date.now`. Injected for test determinism. */
    now?: () => number;
}
/**
 * Returns a currently-valid access token string for the given issuer,
 * refreshing via the stored refresh token if the cached access token
 * is within `expiryBufferMs` of expiring (or already expired).
 *
 * Throws `OAuthFlowError("NOT_AUTHENTICATED", ...)` when the user
 * must re-run `axe-auth login` — covers an empty / corrupt /
 * version-mismatched store, an expired access token with no refresh
 * token to rotate with, and a refresh attempt rejected with
 * `invalid_grant` (which also clears the stored tokens).
 *
 * Throws `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)` for transient
 * failures during refresh (network errors, 5xx, malformed responses)
 * and leaves the stored tokens intact so a retry is possible.
 *
 * Throws `OAuthFlowError("DISCOVERY_FAILED", ...)` when the issuer
 * URL cannot be reached or parsed at refresh time.
 *
 * **Concurrency note.** Not safe against parallel invocations for
 * the same issuer. Keycloak rotates refresh tokens by default; if
 * two parallel calls both land on the refresh path, only one
 * winner's rotated refresh token will be persisted and the loser's
 * rotated token is stranded. The intended consumer is the
 * `axe-auth token` CLI (a one-shot), so this is fine in context;
 * per-request callers should wrap in an in-flight-Promise singleton
 * keyed by issuer.
 */
export declare function getValidAccessToken(options: GetValidAccessTokenOptions): Promise<string>;