import * as _exortek_jwks from '@exortek/jwks';

/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 *
 * @param {ProviderDefinition} def
 * @returns {(appOptions: ProviderAppOptions) => ResolvedProvider}
 *
 * @typedef {Object} ProviderDefinition
 * @property {string} id                        default provider key (`'google'`)
 * @property {'oidc'|'oauth2'} kind
 * @property {string} [authorizationEndpoint]
 * @property {string} [tokenEndpoint]
 * @property {string} [userinfoEndpoint]
 * @property {string} [jwksUri]
 * @property {string} [revocationEndpoint]
 * @property {string | ((claimed: string) => boolean)} [issuer]   OIDC issuer — exact string, or a validator (multi-tenant)
 * @property {string} [expectedIssuer]          overrides `issuer` for the RFC 9207 `iss` param
 * @property {boolean} [requireIssParam]        require the RFC 9207 `iss` response param (a provider known to send it)
 * @property {string} [emailEndpoint]           secondary email fetch (github)
 * @property {boolean} [discover]               resolve endpoints from `issuer` discovery
 * @property {boolean} [supportsPkce]           default true
 * @property {string[]} [defaultScopes]
 * @property {boolean} [autoOpenidScope]        prepend `openid` for OIDC (default true; Apple sets false)
 * @property {string[]} [idTokenAlgs]
 * @property {import('@exortek/jwks').RemoteJWKSOptions} [jwksOptions]  forwarded to the JWKS resolver
 * @property {'post'|'basic'} [clientAuth]                   client authentication at the token endpoint (default `post`)
 * @property {Record<string,string>} [authorizationParams]  extra static auth-request params
 * @property {Record<string,string>} [tokenHeaders]         extra headers on the token/refresh/revoke calls
 * @property {Record<string,string>} [userinfoHeaders]      extra headers on the userinfo/email calls (falls back to tokenHeaders)
 * @property {(raw: Record<string, unknown>, claims?: Record<string, unknown>) => NormalizedUserFields} mapUser
 *
 * @typedef {Object} ProviderAppOptions
 * @property {string} clientId
 * @property {string} [clientSecret]
 * @property {string[]} [scope]
 * @property {string} [redirectUri]
 * @property {string} [id]
 *
 * @typedef {Object} NormalizedUserFields
 * @property {string} sub
 * @property {string} [email]
 * @property {boolean} [emailVerified]
 * @property {string} [name]
 * @property {string} [picture]
 */
declare function defineProvider(def: ProviderDefinition): (appOptions: ProviderAppOptions) => ResolvedProvider$1;
/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 */
type ProviderDefinition = {
    /**
     * default provider key (`'google'`)
     */
    id: string;
    kind: "oidc" | "oauth2";
    authorizationEndpoint?: string | undefined;
    tokenEndpoint?: string | undefined;
    userinfoEndpoint?: string | undefined;
    jwksUri?: string | undefined;
    revocationEndpoint?: string | undefined;
    /**
     * OIDC issuer — exact string, or a validator (multi-tenant)
     */
    issuer?: string | ((claimed: string) => boolean) | undefined;
    /**
     * overrides `issuer` for the RFC 9207 `iss` param
     */
    expectedIssuer?: string | undefined;
    /**
     * require the RFC 9207 `iss` response param (a provider known to send it)
     */
    requireIssParam?: boolean | undefined;
    /**
     * secondary email fetch (github)
     */
    emailEndpoint?: string | undefined;
    /**
     * resolve endpoints from `issuer` discovery
     */
    discover?: boolean | undefined;
    /**
     * default true
     */
    supportsPkce?: boolean | undefined;
    defaultScopes?: string[] | undefined;
    /**
     * prepend `openid` for OIDC (default true; Apple sets false)
     */
    autoOpenidScope?: boolean | undefined;
    idTokenAlgs?: string[] | undefined;
    /**
     * forwarded to the JWKS resolver
     */
    jwksOptions?: _exortek_jwks.RemoteJWKSOptions;
    /**
     * client authentication at the token endpoint (default `post`)
     */
    clientAuth?: "post" | "basic" | undefined;
    /**
     * extra static auth-request params
     */
    authorizationParams?: Record<string, string> | undefined;
    /**
     * extra headers on the token/refresh/revoke calls
     */
    tokenHeaders?: Record<string, string> | undefined;
    /**
     * extra headers on the userinfo/email calls (falls back to tokenHeaders)
     */
    userinfoHeaders?: Record<string, string> | undefined;
    mapUser: (raw: Record<string, unknown>, claims?: Record<string, unknown>) => NormalizedUserFields;
};
/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 */
type ProviderAppOptions = {
    clientId: string;
    clientSecret?: string | undefined;
    scope?: string[] | undefined;
    redirectUri?: string | undefined;
    id?: string | undefined;
};
/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 */
type NormalizedUserFields = {
    sub: string;
    email?: string | undefined;
    emailVerified?: boolean | undefined;
    name?: string | undefined;
    picture?: string | undefined;
};
type Warning$1 = {
    code: string;
    message: string;
};
type ResolvedProvider$1 = ReturnType<ReturnType<typeof defineProvider>>;

/**
 * @typedef {Object} OAuthConfig
 * @property {string} baseUrl                       app origin, e.g. `https://app.com`
 * @property {string} callback                      callback template, e.g. `/auth/{provider}/callback`
 * @property {SessionStore} [store]                 optional server-side session store (keyed by `state`)
 * @property {{ maxAuthAge?: string|number, clockTolerance?: string|number }} [security]
 * @property {ResolvedProvider[]} providers         provider descriptors from `./providers/*`
 *
 * @typedef {Object} SessionStore
 * @property {(key: string, value: string, ttlMs: number) => unknown} set
 * @property {(key: string) => (string | null | undefined) | Promise<string | null | undefined>} get
 * @property {(key: string) => unknown} delete
 *
 * @typedef {import('./providers/_base.js').ResolvedProvider} ResolvedProvider
 */
/**
 * @param {OAuthConfig} config
 */
declare function createOAuth(config: OAuthConfig): {
    /**
     * Begin the flow. Returns the authorization `url` to redirect to and
     * an opaque `session` string to stash (cookie / store). When a store
     * is configured the session is also persisted keyed by `state`.
     *
     * @param {string} name
     * @param {{ scope?: string[], sessionBinding?: string, params?: Record<string,string> }} [options]
     */
    authorize(name: string, options?: {
        scope?: string[];
        sessionBinding?: string;
        params?: Record<string, string>;
    }): Promise<{
        url: string;
        session: string;
        warnings: Warning$1[];
    }>;
    /**
     * Complete the flow. Provide the `session` returned by `authorize`,
     * or rely on the configured store to look it up by `query.state`.
     *
     * @param {string} name
     * @param {Record<string, unknown>} query   the callback query params
     * @param {{ session?: string, sessionBinding?: string }} [options]
     */
    callback(name: string, query: Record<string, unknown>, options?: {
        session?: string;
        sessionBinding?: string;
    }): Promise<{
        tokens: Record<string, unknown>;
        user: NormalizedUser;
        warnings: Warning[];
    }>;
    /**
     * Exchange a refresh token for a fresh access token (RFC 6749 §6).
     *
     * @param {string} name
     * @param {string} refreshToken
     * @returns {Promise<Record<string, unknown>>}
     */
    refresh(name: string, refreshToken: string): Promise<Record<string, unknown>>;
    /**
     * Revoke an access or refresh token (RFC 7009).
     *
     * @param {string} name
     * @param {string} token
     * @param {string} [tokenTypeHint]  `'access_token'` | `'refresh_token'`
     * @returns {Promise<Record<string, unknown>>}
     */
    revoke(name: string, token: string, tokenTypeHint?: string): Promise<Record<string, unknown>>;
    /** @returns {string[]} the registered provider ids */
    readonly providers: string[];
    /** @param {string} name @returns {boolean} */
    has(name: string): boolean;
};
type OAuthConfig = {
    /**
     * app origin, e.g. `https://app.com`
     */
    baseUrl: string;
    /**
     * callback template, e.g. `/auth/{provider}/callback`
     */
    callback: string;
    /**
     * optional server-side session store (keyed by `state`)
     */
    store?: SessionStore | undefined;
    security?: {
        maxAuthAge?: string | number;
        clockTolerance?: string | number;
    } | undefined;
    /**
     * provider descriptors from `./providers/*`
     */
    providers: ResolvedProvider[];
};
type SessionStore = {
    set: (key: string, value: string, ttlMs: number) => unknown;
    get: (key: string) => (string | null | undefined) | Promise<string | null | undefined>;
    delete: (key: string) => unknown;
};
type ResolvedProvider = ResolvedProvider$1;

type LoginMode = "web" | "api";
type LoginConfig = {
    oauth: ReturnType<typeof createOAuth>;
    mode?: LoginMode | undefined;
    /**
     * start route (router `:provider` syntax)
     */
    loginPath?: string | undefined;
    /**
     * MUST match the `callback` template given to createOAuth
     */
    callbackPath?: string | undefined;
    cookie?: {
        name?: string;
        secret?: string;
        path?: string;
        secure?: boolean;
        sameSite?: "lax" | "strict" | "none";
        maxAge?: number;
    } | undefined;
    /**
     * key to protect the client-held session (api mode)
     */
    secret?: string | undefined;
    /**
     * 'sign' = HMAC (tamper-evident); 'jwe' = encrypt (also confidential)
     */
    seal?: "sign" | "jwe" | undefined;
    scope?: string[] | undefined;
    onSuccess?: ((ctx: object) => unknown) | undefined;
    onError?: ((ctx: object) => unknown) | undefined;
    attach?: string | undefined;
};

/**
 * Build the `{ start, callback }` Express handlers for the login flow —
 * mount them on your own routes. `method` tells you which verb to use
 * (`'get'` for web, `'post'` for api), and `loginPath` / `callbackPath`
 * are the defaults if you want them.
 *
 * @param {import('./core.js').LoginConfig} config
 * @returns {{ start: Function, callback: Function, method: 'get'|'post', loginPath: string, callbackPath: string }}
 */
declare function oauthLogin(config: LoginConfig): {
    start: Function;
    callback: Function;
    method: "get" | "post";
    loginPath: string;
    callbackPath: string;
};
/**
 * Register the login + callback routes on an Express app / router — the
 * one-call form of {@link oauthLogin}.
 *
 * @param {any} app
 * @param {import('./core.js').LoginConfig} config
 */
declare function mountOAuthLogin(app: any, config: LoginConfig): void;

export { mountOAuthLogin, oauthLogin };