@ricokahler/oauth2-popup-flow/index.d.ts

/**
 * The type of the configuration object used to create a `OAuth2PopupFlow`
 *
 * Each property has a JSDOC description to explain what it does.
 */
export interface OAuth2PopupFlowOptions<TokenPayload extends {
    exp: number;
}> {
    /**
     * REQUIRED
     * The full URI of the authorization endpoint provided by the authorization server.
     *
     * e.g. `https://example.com/oauth/authorize`
     */
    authorizationUri: string;
    /**
     * REQUIRED
     * The client ID of your application provided by the authorization server.
     *
     * This client ID is sent to the authorization server using `authorizationUrl` endpoint in the
     * query portion of the URL along with the other parameters.
     * This value will be URL encoded like so:
     *
     * `https://example.com/oauth/authorize?client_id=SOME_CLIENT_ID_VALUE...`
     */
    clientId: string;
    /**
     * REQUIRED
     * The URI that the authorization server will to redirect after the user has been authenticated.
     * This redirect URI *must* be a URI from *your application* and it must also be registered with
     * the authorization server. Some authorities call this a "callback URLs" or "login URLs" etc.
     *
     * > e.g. `http://localhost:4200/redirect` for local testing
     * >
     * > or `https://my-application.com/redirect` for prod
     *
     * This redirect URI is sent to the authorization server using `authorizationUrl` endpoint in the
     * query portion of the URL along with the other parameters.
     * This value will be URL encoded like so:
     *
     * `https://example.com/oauth/authorize?redirect_URI=http%3A%2F%2Flocalhost%2Fredirect...`
     */
    redirectUri: string;
    /**
     * REQUIRED
     * A list permission separated by spaces that is the scope of permissions your application is
     * requesting from the authorization server. If the user is logging in the first time, it may ask
     * them to approve those permission before authorizing your application.
     *
     * > e.g. `openid profile`
     *
     * The scopes are sent to the authorization server using `authorizationUrl` endpoint in the
     * query portion of the URL along with the other parameters.
     * This value will be URL encoded like so:
     *
     * `https://example.com/oauth/authorize?scope=openid%20profile...`
     */
    scope: string;
    /**
     * OPTIONAL
     * `response_type` is an argument to be passed to the authorization server via the
     * `authorizationUri` endpoint in the query portion of the URL.
     *
     * Most implementations of oauth2 use the default value of `token` to tell the authorization
     * server to start the implicit grant flow but you may override that value with this option.
     *
     * For example, Auth0--an OAuth2 authority/authorization server--requires the value `id_token`
     * instead of `token` for the implicit flow.
     *
     * The response type is sent to the authorization server using `authorizationUrl` endpoint in the
     * query portion of the URL along with the other parameters.
     * This value will be URL encoded like so:
     *
     * `https://example.com/oauth/authorize?response_type=token...`
     */
    responseType?: string;
    /**
     * OPTIONAL
     * The key used to save the token in the given storage. The default key is `token` so the token
     * would be persisted in `localStorage.getItem('token')` if `localStorage` was the configured
     * `Storage`.
     */
    accessTokenStorageKey?: string;
    /**
     * OPTIONAL
     * During `handleRedirect`, the method will try to parse `window.location.hash` to an object using
     * `OAuth2PopupFlow.decodeUriToObject`. After that object has been decoded, this property
     * determines the key to use that will retrieve the token from that object.
     *
     * By default it is `access_token` but you you may need to change that e.g. Auth0 uses `id_token`.
     */
    accessTokenResponseKey?: string;
    /**
     * OPTIONAL
     * The storage implementation of choice. It can be `localStorage` or `sessionStorage` or something
     * else. By default, this is `localStorage` and `localStorage` is the preferred `Storage`.
     */
    storage?: Storage;
    /**
     * OPTIONAL
     * The `authenticated` method periodically checks `loggedIn()` and resolves when `loggedIn()`
     * returns `true`.
     *
     * This property is how long it will wait between checks. By default it is `200`.
     */
    pollingTime?: number;
    /**
     * OPTIONAL
     * Some oauth authorities require additional parameters to be passed to the `authorizationUri`
     * URL in order for the implicit grant flow to work.
     *
     * For example: [Auth0--an OAuth2 authority/authorization server--requires the parameters
     * `nonce`][0]
     * be passed along with every call to the `authorizationUri`. You can do that like so:
     *
     * ```ts
     * const auth = OAuth2PopupFlow({
     *   authorizationUri: 'https://example.com/oauth/authorize',
     *   clientId: 'foo_client',
     *   redirectUri: 'http://localhost:8080/redirect',
     *   scope: 'openid profile',
     *   // this can be a function or static object
     *   additionalAuthorizationParameters: () => {
     *     // in prod, consider something more cryptographic
     *     const nonce = Math.floor(Math.random() * 1000).toString();
     *     localStorage.setItem('nonce', nonce);
     *     return { nonce };
     *     // `nonce` will now be encoded in the URL like so:
     *     // https://example.com/oauth/authorize?client_id=foo_client...nonce=1234
     *   },
     *   // the token returned by Auth0, has the `nonce` in the payload
     *   // you can add this additional check now
     *   tokenValidator: ({ payload }) => {
     *     const storageNonce = parseInt(localStorage.getItem('nonce'), 10);
     *     const payloadNonce = parseInt(payload.nonce, 10);
     *     return storageNonce === payloadNonce;
     *   },
     * });
     * ```
     *
     * [0]: https://auth0.com/docs/api-auth/tutorials/nonce#generate-a-cryptographically-random-nonce
     */
    additionalAuthorizationParameters?: (() => {
        [key: string]: string;
    }) | {
        [key: string]: string;
    };
    /**
     * OPTIONAL
     * This function intercepts the `loggedIn` method and causes it to return early with `false` if
     * this function itself returns `false`. Use this function to validate claims in the token payload
     * or token.
     *
     * [For example: validating the `nonce`:][0]
     *
     * ```ts
     * const auth = OAuth2PopupFlow({
     *   authorizationUri: 'https://example.com/oauth/authorize',
     *   clientId: 'foo_client',
     *   redirectUri: 'http://localhost:8080/redirect',
     *   scope: 'openid profile',
     *   // this can be a function or static object
     *   additionalAuthorizationParameters: () => {
     *     // in prod, consider something more cryptographic
     *     const nonce = Math.floor(Math.random() * 1000).toString();
     *     localStorage.setItem('nonce', nonce);
     *     return { nonce };
     *     // `nonce` will now be encoded in the URL like so:
     *     // https://example.com/oauth/authorize?client_id=foo_client...nonce=1234
     *   },
     *   // the token returned by Auth0, has the `nonce` in the payload
     *   // you can add this additional check now
     *   tokenValidator: ({ payload }) => {
     *     const storageNonce = parseInt(localStorage.getItem('nonce'), 10);
     *     const payloadNonce = parseInt(payload.nonce, 10);
     *     return storageNonce === payloadNonce;
     *   },
     * });
     * ```
     *
     * [0]: https://auth0.com/docs/api-auth/tutorials/nonce#generate-a-cryptographically-random-nonce
     */
    tokenValidator?: (options: {
        payload: TokenPayload;
        token: string;
    }) => boolean;
    /**
     * OPTIONAL
     * A hook that runs in `tryLoginPopup` before any popup is opened. This function can return a
     * `Promise` and the popup will not open until it resolves.
     *
     * A typical use case would be to wait a certain amount of time before opening the popup to let
     * the user see why the popup is happening.
     */
    beforePopup?: () => any | Promise<any>;
    /**
     * OPTIONAL
     * A hook that runs in `handleRedirect` that takes in the result of the hash payload from the
     * authorization server. Use this hook to grab more from the response or to debug the response
     * from the authorization URL.
     */
    afterResponse?: (authorizationResponse: {
        [key: string]: string | undefined;
    }) => void;
}
declare const FixedTypesOAuth2PopupFlow: <TokenPayload extends {
    exp: number;
}>(opts: OAuth2PopupFlowOptions<TokenPayload>) => Pick<{
    /**
     * REQUIRED
     * The full URI of the authorization endpoint provided by the authorization server.
     *
     * e.g. `https://example.com/oauth/authorize`
     */
    authorizationUri: string;
    /**
     * REQUIRED
     * The client ID of your application provided by the authorization server.
     *
     * This client ID is sent to the authorization server using `authorizationUrl` endpoint in the
     * query portion of the URL along with the other parameters.
     * This value will be URL encoded like so:
     *
     * `https://example.com/oauth/authorize?client_id=SOME_CLIENT_ID_VALUE...`
     */
    clientId: string;
    /**
     * REQUIRED
     * The URI that the authorization server will to redirect after the user has been authenticated.
     * This redirect URI *must* be a URI from *your application* and it must also be registered with
     * the authorization server. Some authorities call this a "callback URLs" or "login URLs" etc.
     *
     * > e.g. `http://localhost:4200/redirect` for local testing
     * >
     * > or `https://my-application.com/redirect` for prod
     *
     * This redirect URI is sent to the authorization server using `authorizationUrl` endpoint in the
     * query portion of the URL along with the other parameters.
     * This value will be URL encoded like so:
     *
     * `https://example.com/oauth/authorize?redirect_URI=http%3A%2F%2Flocalhost%2Fredirect...`
     */
    redirectUri: string;
    /**
     * REQUIRED
     * A list permission separated by spaces that is the scope of permissions your application is
     * requesting from the authorization server. If the user is logging in the first time, it may ask
     * them to approve those permission before authorizing your application.
     *
     * > e.g. `openid profile`
     *
     * The scopes are sent to the authorization server using `authorizationUrl` endpoint in the
     * query portion of the URL along with the other parameters.
     * This value will be URL encoded like so:
     *
     * `https://example.com/oauth/authorize?scope=openid%20profile...`
     */
    scope: string;
    /**
     * OPTIONAL
     * Some oauth authorities require additional parameters to be passed to the `authorizationUri`
     * URL in order for the implicit grant flow to work.
     *
     * For example: [Auth0--an OAuth2 authority/authorization server--requires the parameters
     * `nonce`][0]
     * be passed along with every call to the `authorizationUri`. You can do that like so:
     *
     * ```ts
     * const auth = OAuth2PopupFlow({
     *   authorizationUri: 'https://example.com/oauth/authorize',
     *   clientId: 'foo_client',
     *   redirectUri: 'http://localhost:8080/redirect',
     *   scope: 'openid profile',
     *   // this can be a function or static object
     *   additionalAuthorizationParameters: () => {
     *     // in prod, consider something more cryptographic
     *     const nonce = Math.floor(Math.random() * 1000).toString();
     *     localStorage.setItem('nonce', nonce);
     *     return { nonce };
     *     // `nonce` will now be encoded in the URL like so:
     *     // https://example.com/oauth/authorize?client_id=foo_client...nonce=1234
     *   },
     *   // the token returned by Auth0, has the `nonce` in the payload
     *   // you can add this additional check now
     *   tokenValidator: ({ payload }) => {
     *     const storageNonce = parseInt(localStorage.getItem('nonce'), 10);
     *     const payloadNonce = parseInt(payload.nonce, 10);
     *     return storageNonce === payloadNonce;
     *   },
     * });
     * ```
     *
     * [0]: https://auth0.com/docs/api-auth/tutorials/nonce#generate-a-cryptographically-random-nonce
     */
    additionalAuthorizationParameters?: {
        [key: string]: string;
    } | (() => {
        [key: string]: string;
    }) | undefined;
    /**
     * OPTIONAL
     * This function intercepts the `loggedIn` method and causes it to return early with `false` if
     * this function itself returns `false`. Use this function to validate claims in the token payload
     * or token.
     *
     * [For example: validating the `nonce`:][0]
     *
     * ```ts
     * const auth = OAuth2PopupFlow({
     *   authorizationUri: 'https://example.com/oauth/authorize',
     *   clientId: 'foo_client',
     *   redirectUri: 'http://localhost:8080/redirect',
     *   scope: 'openid profile',
     *   // this can be a function or static object
     *   additionalAuthorizationParameters: () => {
     *     // in prod, consider something more cryptographic
     *     const nonce = Math.floor(Math.random() * 1000).toString();
     *     localStorage.setItem('nonce', nonce);
     *     return { nonce };
     *     // `nonce` will now be encoded in the URL like so:
     *     // https://example.com/oauth/authorize?client_id=foo_client...nonce=1234
     *   },
     *   // the token returned by Auth0, has the `nonce` in the payload
     *   // you can add this additional check now
     *   tokenValidator: ({ payload }) => {
     *     const storageNonce = parseInt(localStorage.getItem('nonce'), 10);
     *     const payloadNonce = parseInt(payload.nonce, 10);
     *     return storageNonce === payloadNonce;
     *   },
     * });
     * ```
     *
     * [0]: https://auth0.com/docs/api-auth/tutorials/nonce#generate-a-cryptographically-random-nonce
     */
    tokenValidator?: ((options: {
        payload: {
            exp: number;
        };
        token: string;
    }) => boolean) | undefined;
    /**
     * OPTIONAL
     * A hook that runs in `tryLoginPopup` before any popup is opened. This function can return a
     * `Promise` and the popup will not open until it resolves.
     *
     * A typical use case would be to wait a certain amount of time before opening the popup to let
     * the user see why the popup is happening.
     */
    beforePopup?: (() => any) | undefined;
    /**
     * OPTIONAL
     * A hook that runs in `handleRedirect` that takes in the result of the hash payload from the
     * authorization server. Use this hook to grab more from the response or to debug the response
     * from the authorization URL.
     */
    afterResponse?: ((authorizationResponse: {
        [key: string]: string | undefined;
    }) => void) | undefined;
    responseType: string;
    accessTokenStorageKey: string;
    accessTokenResponseKey: string;
    storage: Storage;
    pollingTime: number;
    addEventListener: (type: string, listener: EventListenerOrEventListenerObject) => void;
    dispatchEvent: (event: Event) => boolean;
    removeEventListener: (type: string, listener: EventListenerOrEventListenerObject) => void;
    loggedIn: () => boolean;
    logout: () => void;
    tokenExpired: () => boolean;
    handleRedirect: () => "REDIRECT_URI_MISMATCH" | "FALSY_HASH" | "FALSY_TOKEN" | "SUCCESS";
    tryLoginPopup: () => Promise<"SUCCESS" | "ALREADY_LOGGED_IN" | "POPUP_FAILED">;
    authenticated: () => Promise<void>;
    token: () => Promise<string>;
    tokenPayload: () => Promise<{
        exp: number;
    }>;
}, "storage" | "responseType" | "token" | "accessTokenStorageKey" | "accessTokenResponseKey" | "pollingTime" | "authorizationUri" | "clientId" | "redirectUri" | "scope" | "additionalAuthorizationParameters" | "tokenValidator" | "beforePopup" | "afterResponse" | "logout" | "addEventListener" | "dispatchEvent" | "removeEventListener" | "loggedIn" | "tokenExpired" | "handleRedirect" | "tryLoginPopup" | "authenticated" | "tokenPayload">;
export { FixedTypesOAuth2PopupFlow as OAuth2PopupFlow };
export default FixedTypesOAuth2PopupFlow;