import { Subject } from '@voltro/protocol';

/**
 * Mint the verifier + state and build the authorize URL. Nothing is sent yet;
 * the app opens `url` and waits for its redirect URI to be hit.
 */
export declare const beginNativeLogin: (options: NativeLoginOptions) => Promise<NativeLoginHandoff>;

/** Trade the code + verifier for the session value. */
export declare const exchangeNativeCode: (input: {
    readonly code: string;
    readonly codeVerifier: string;
}, options: Pick<NativeLoginOptions, "apiBaseUrl" | "prefix"> & {
    readonly fetch?: typeof fetch;
}) => Promise<NativeSession>;

export declare type NativeCallback = {
    readonly kind: 'code';
    readonly code: string;
} | {
    readonly kind: 'error';
    readonly error: string;
} | {
    readonly kind: 'ignored';
    readonly reason: 'not-the-callback' | 'state-mismatch' | 'no-code';
};

/** RFC 7636 S256 challenge for a verifier, through the injected hash. */
export declare const nativeCodeChallenge: (verifier: string, crypto: NativeCrypto) => Promise<string>;

/** The platform's entropy and hash. `randomBytes(n)` must be a CSPRNG. */
export declare interface NativeCrypto {
    readonly randomBytes: (length: number) => Uint8Array;
    readonly sha256: (bytes: Uint8Array) => Promise<Uint8Array>;
}

export declare class NativeExchangeError extends Error {
    readonly status: number;
    readonly code: string;
    constructor(status: number, code: string);
}

export declare interface NativeLoginHandoff {
    /** Open this in the SYSTEM browser (not an in-app webview): the user's
     *  existing browser session and password manager are the point. */
    readonly url: string;
    /** Keep both until the callback arrives — they are what makes the code
     *  usable by this app and this attempt only. */
    readonly codeVerifier: string;
    readonly state: string;
}

export declare interface NativeLoginOptions {
    /** The api origin the `/auth/*` routes live on (`https://api.example.com`),
     *  or the web origin that proxies them. No trailing slash needed. */
    readonly apiBaseUrl: string;
    /** The URL the app listens on, byte for byte one of the plugin's
     *  `native.redirectUris`. */
    readonly redirectUri: string;
    readonly crypto: NativeCrypto;
    /** The auth routes' prefix. Default `/auth`. */
    readonly prefix?: string;
}

export declare interface NativeLoginRunner extends NativeLoginOptions {
    /** Open the authorize URL in the system browser. */
    readonly open: (url: string) => void | Promise<void>;
    /** Resolve with the callback URL the OS hands the app (the first one that
     *  is this login's; see `parseNativeCallback`). */
    readonly awaitCallback: (isOurs: (url: string) => NativeCallback) => Promise<NativeCallback>;
    readonly fetch?: typeof fetch;
}

export declare interface NativeSession {
    /** Present this on `x-voltro-session` — see {@link sessionHeaders}. */
    readonly session: string;
    /** Unix seconds the session expires. Probe `GET /auth/session` before then
     *  to receive a renewed value. */
    readonly expiresAt: number;
    readonly subject: Subject;
}

/**
 * Read the callback the system browser sent the app to. `state` must match
 * the handoff's; an unrelated URL (the app's ordinary deep links pass through
 * the same listener) is `ignored`.
 */
export declare const parseNativeCallback: (url: string, handoff: Pick<NativeLoginHandoff, "state">, redirectUri: string) => NativeCallback;

/**
 * Probe `GET /auth/session` with a header-presented value. Answers the
 * renewed value when the server rotated it, the same value otherwise, or
 * `null` when the session no longer authenticates (sign the user in again).
 */
export declare const probeNativeSession: (session: string, options: Pick<NativeLoginOptions, "apiBaseUrl" | "prefix"> & {
    readonly fetch?: typeof fetch;
}) => Promise<NativeSession | null>;

/** One call: open the browser, wait for the callback, exchange the code. */
export declare const runNativeLogin: (runner: NativeLoginRunner) => Promise<NativeSession>;

/** The rpc headers for a session value — hand to `ResolvableHeaders`. */
export declare const sessionHeaders: (session: string) => Readonly<Record<string, string>>;

export { }