import { type ScaiErrorCode } from "../shared/errors.js";
/**
 * Whether a cached JWT is still safe to use. The default 60 s skew
 * absorbs clock drift + in-flight request latency: a token within
 * that window is treated as already expired so the call mints fresh
 * rather than racing the clock and 401-ing mid-flight.
 */
export declare const isTokenFresh: (jwt: string, skewSeconds?: number) => boolean;
/** A resolved credential ready to be exchanged for an access token. */
export interface ResolvedCredential {
    clientId: string;
    clientSecret: string;
    /** Authority defaults to `https://auth.sitecorecloud.io`. */
    authority?: string;
    /** Audience defaults to `https://api.sitecorecloud.io`. */
    audience?: string;
}
/** Specification of one API's auth seam. See module-level JSDoc. */
export interface ApiAuthSpec {
    /** Slot identifier passed to the keychain helpers (org id, env, …). */
    keychainKey: string;
    /** Reads the cached token from this credential class's keychain slot. */
    getCachedToken: (key: string) => Promise<string | undefined>;
    /** Writes a freshly-minted token to this credential class's keychain slot. */
    setCachedToken: (key: string, token: string) => Promise<unknown>;
    /**
     * Resolves a usable `{ clientId, clientSecret, ... }` pair. Returning
     * `undefined` triggers the `onMissingCredential` error path.
     */
    resolveCredential: () => Promise<ResolvedCredential | undefined>;
    /**
     * M2M `scope` parameter, joined by spaces. Pass `undefined` to mint
     * without an explicit scope (Auth0 issues the client's per-key grant).
     */
    scopes?: string;
    /** Post-mint scope assertion. Omit to skip granted-scope validation. */
    requiredScopes?: readonly string[];
    /** Code thrown for every failure branch. */
    errorCode: ScaiErrorCode;
    /** Message + hint when `resolveCredential()` returned `undefined`. */
    onMissingCredential: () => {
        message: string;
        hint?: string;
    };
    /** Message + hint when `requestClientCredentialsToken` rejected. */
    onMintFailure: (error: unknown) => {
        message: string;
        hint?: string;
    };
    /** Message + hint when the mint succeeded but the IdP returned no token. */
    onNoAccessToken: () => {
        message: string;
        hint?: string;
    };
    /**
     * Message + hint when the minted token is missing one or more entries
     * from `requiredScopes`. Receives the granted scope list (extracted
     * from the JWT) so callers can render rich diagnostics — the
     * publishing path infers credential class (org-level vs env-level)
     * from the granted scopes here.
     */
    onMissingScopes?: (token: string, granted: readonly string[]) => {
        message: string;
        hint?: string;
    };
}
/**
 * Re-exported from `@/shared/jwt` so callers that already pull
 * factory primitives don't have to reach across to `shared/` for
 * the scope decoder. Implementation lives in shared/jwt.ts.
 */
export declare const extractScopes: (token: string) => string[];
/**
 * Builds the per-domain token acquirer. Returns an async function that
 * implements the standard cache → resolve → mint → validate → cache
 * loop with the spec's per-caller knobs filled in.
 */
export declare const createApiAuth: (spec: ApiAuthSpec) => (() => Promise<string>);