@curity/identityserver-haapi-web-driver/index.d.ts

Curity Identity Server HAAPI Web driver

/**
 * TypeScript/JavaScript library with classes and functions to access the Curity Identity Server {@link https://developer.curity.io/docs/latest/developer-guide/haapi/index.html | Hypermedia Authentication API (HAAPI) } from browser-based applications.
 *
 * @remarks
 * The library is available on the npm public registry and can be installed using:
 * ```
 * npm install @curity/identityserver-haapi-web-driver
 * ```
 *
 * @example
 * ```js
 * // 0 - Import the createHaapiFetch function
 * import { createHaapiFetch } from '@curity/identityserver-haapi-web-driver';
 *
 * // 1 - Create a fetch-like function to perform HAAPI requests
 * const haapiFetch = createHaapiFetch({
 *     clientId: 'test-client-id',
 *     tokenEndpoint: 'https://localhost:8443/dev/oauth/token',
 * });
 *
 * // 2 - Use haapiFetch to access HAAPI resources
 * const authorizeRequest = '/dev/oauth/authorize?client_id=test-client-id&response_type=code&scope=read&state=foobar&redirect_uri=https://localhost:7777/client-callback';
 * haapiFetch(authorizeRequest)
 *     .then(res => {
 *         // ...
 *     });
 * ```
 *
 * @packageDocumentation
 */

/**
 * Creates a fetch-like function that can be used to perform HAAPI requests, managing attestation, access tokens, DPoP tokens, and Session-Id.
 *
 * @remarks
 * This function ensures that there's at most one active fetch-like function. A previously created fetch-like function becomes unusable after
 * a new one is created.
 *
 * The initialization of the fetch-like function requires asynchronous steps. Errors during that phase are not reported when this function is
 * invoked; instead, the promise returned by the fetch-like function is rejected with an appropriate error (see {@link InitializationError}).
 *
 * @param config - the configuration options
 * @returns a {@link FetchLike} function
 *
 * @public
 */
export declare function createHaapiFetch(config: HaapiConfiguration): FetchLike;

/**
 * A function similar to `fetch` used to perform HAAPI requests.
 *
 * @remarks
 * The `init` parameter accepts less or stricter properties than its equivalent in `fetch`, namely for the types allowed in `body`.
 *
 * If the {@link HaapiConfiguration.timeout | configured timeout} is exceeded, the returned promise is rejected with a {@link TimeoutError}.
 *
 * @remarks
 * The initialization of this function requires asynchronous steps. Errors during that phase are not reported when the function is created; instead,
 * the returned promise is rejected with an appropriate error (see {@link InitializationError}). Subsequent invocations will retry a failed initialization.
 *
 * If additional control is needed, initialization can be done explicitly via the `init` method. Failed initializations can be retried by invoking
 * the method again.
 *
 * An existing instance can be disposed using the `close` method, which will discard pending requests and remove used resources.
 * The function becomes unusable after this.
 *
 * @example
 * Explicit initialization
 * ```
 * const haapiFetch = await createHaapiFetch(...).init(); // throws if initialization fails
 * const res = await haapiFetch(...);
 * ```
 *
 * @public
 */
export declare type FetchLike = {
    (link: string, init?: {
        method?: string;
        body?: URLSearchParams | Record<string, string> | string | null;
        credentials?: RequestCredentials;
        headers?: HeadersInit;
        signal?: AbortSignal;
    }): Promise<Response>;
    init(): Promise<FetchLike>;
    close(): void;
};

/**
 * Configuration for HAAPI access.
 *
 * @public
 */
export declare interface HaapiConfiguration {
    /**
     * The client ID for the client application.
     */
    clientId: string;
    /**
     * URL of the Authorization Server's token endpoint.
     */
    tokenEndpoint: string;
    /**
     * Base URL of the HAAPI.
     *
     * @defaultValue the origin of the URL configured in {@link HaapiConfiguration.tokenEndpoint | tokenEndpoint}.
     */
    baseUrl?: string;
    /**
     * Timeout for the acquisition of the CAT, in seconds.
     *
     * @defaultValue 5 seconds.
     *
     */
    timeout?: number;
    /**
     * An optional unique identifier for the device browser making the request.
     * It should be unique to the user's browser and preserved across sessions.
     * Used for risk assessment purposes.
     *
     * Available since version 1.3.0
     */
    deviceIdentifier?: string;
}

/**
 * An error during the driver initialization. One likely cause is that client attestation could not be completed.
 *
 * @public
 */
export declare class InitializationError extends Error {
    constructor(cause: Error);
}

/**
 * A timeout during HAAPI requests.
 *
 * @public
 */
export declare class TimeoutError extends Error {
    constructor(message: string);
}

export { }