@auth0/auth0-spa-js 2.18.1 → 2.18.2

package/dist/typings/TokenExchange.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Represents the configuration options required for initiating a Custom Token Exchange request
+ * following RFC 8693 specifications.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 | RFC 8693: OAuth 2.0 Token Exchange}
+ */
+export type CustomTokenExchangeOptions = {
+    /**
+     * The type identifier for the subject token being exchanged
+     *
+     * @pattern
+     * - Must be a namespaced URI under your organization's control
+     * - Forbidden patterns:
+     *   - `^urn:ietf:params:oauth:*` (IETF reserved)
+     *   - `^https:\/\/auth0\.com/*` (Auth0 reserved)
+     *   - `^urn:auth0:*` (Auth0 reserved)
+     *
+     * @example
+     * "urn:acme:legacy-system-token"
+     * "https://api.yourcompany.com/token-type/v1"
+     */
+    subject_token_type: string;
+    /**
+     * The opaque token value being exchanged for Auth0 tokens
+     *
+     * @security
+     * - Must be validated in Auth0 Actions using strong cryptographic verification
+     * - Implement replay attack protection
+     * - Recommended validation libraries: `jose`, `jsonwebtoken`
+     *
+     * @example
+     * "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+     */
+    subject_token: string;
+    /**
+     * The target audience for the requested Auth0 token
+     *
+     * @remarks
+     * Must match exactly with an API identifier configured in your Auth0 tenant.
+     * If not provided, falls back to the client's default audience.
+     *
+     * @example
+     * "https://api.your-service.com/v1"
+     */
+    audience?: string;
+    /**
+     * Space-separated list of OAuth 2.0 scopes being requested
+     *
+     * @remarks
+     * Subject to API authorization policies configured in Auth0
+     *
+     * @example
+     * "openid profile email read:data write:data"
+     */
+    scope?: string;
+    /**
+     * ID or name of the organization to use when authenticating a user.
+     * When provided, the user will be authenticated using the organization context.
+     * The organization ID will be present in the access token payload.
+     */
+    organization?: string;
+    /**
+     * Additional custom parameters for Auth0 Action processing
+     *
+     * @remarks
+     * Accessible in Action code via `event.request.body`
+     *
+     * @example
+     * ```typescript
+     * {
+     *   custom_parameter: "session_context",
+     *   device_fingerprint: "a3d8f7...",
+     * }
+     * ```
+     */
+    [key: string]: unknown;
+};

package/dist/typings/api.d.ts

@@ -0,0 +1,2 @@
+import { TokenEndpointOptions, TokenEndpointResponse } from './global';
+export declare function oauthToken({ baseUrl, timeout, audience, scope, auth0Client, useFormData, useMrrt, dpop, ...options }: TokenEndpointOptions, worker?: Worker): Promise<TokenEndpointResponse>;

package/dist/typings/cache/cache-localstorage.d.ts

@@ -0,0 +1,7 @@
+import { ICache, Cacheable, MaybePromise } from './shared';
+export declare class LocalStorageCache implements ICache {
+    set<T = Cacheable>(key: string, entry: T): void;
+    get<T = Cacheable>(key: string): MaybePromise<T | undefined>;
+    remove(key: string): void;
+    allKeys(): string[];
+}

package/dist/typings/cache/cache-manager.d.ts

@@ -0,0 +1,56 @@
+import { CacheKeyManifest } from './key-manifest';
+import { CacheEntry, ICache, CacheKey, DecodedToken, IdTokenEntry } from './shared';
+export declare class CacheManager {
+    private cache;
+    private keyManifest?;
+    private nowProvider;
+    constructor(cache: ICache, keyManifest?: CacheKeyManifest | undefined, nowProvider?: () => number | Promise<number>);
+    setIdToken(clientId: string, idToken: string, decodedToken: DecodedToken): Promise<void>;
+    getIdToken(cacheKey: CacheKey): Promise<IdTokenEntry | undefined>;
+    get(cacheKey: CacheKey, expiryAdjustmentSeconds?: number, useMrrt?: boolean, cacheMode?: string): Promise<Partial<CacheEntry> | undefined>;
+    private modifiedCachedEntry;
+    set(entry: CacheEntry): Promise<void>;
+    remove(client_id: string, audience?: string, scope?: string): Promise<void>;
+    clear(clientId?: string): Promise<void>;
+    private wrapCacheEntry;
+    private getCacheKeys;
+    /**
+     * Returns the cache key to be used to store the id token
+     * @param clientId The client id used to link to the id token
+     * @returns The constructed cache key, as a string, to store the id token
+     */
+    private getIdTokenCacheKey;
+    /**
+     * Finds the corresponding key in the cache based on the provided cache key.
+     * The keys inside the cache are in the format {prefix}::{clientId}::{audience}::{scope}.
+     * The first key in the cache that satisfies the following conditions is returned
+     *  - `prefix` is strict equal to Auth0's internally configured `keyPrefix`
+     *  - `clientId` is strict equal to the `cacheKey.clientId`
+     *  - `audience` is strict equal to the `cacheKey.audience`
+     *  - `scope` contains at least all the `cacheKey.scope` values
+     *  *
+     * @param keyToMatch The provided cache key
+     * @param allKeys A list of existing cache keys
+     */
+    private matchExistingCacheKey;
+    /**
+     * Returns the first entry that contains a refresh_token that satisfies the following conditions
+     * The keys inside the cache are in the format {prefix}::{clientId}::{audience}::{scope}.
+     * - `prefix` is strict equal to Auth0's internally configured `keyPrefix`
+     * - `clientId` is strict equal to the `cacheKey.clientId`
+     * @param keyToMatch The provided cache key
+     * @param allKeys A list of existing cache keys
+     */
+    private getEntryWithRefreshToken;
+    /**
+     * Updates the refresh token in all cache entries that contain the old refresh token.
+     *
+     * When a refresh token is rotated, multiple cache entries (for different audiences/scopes)
+     * may share the same refresh token. This method propagates the new refresh token to all
+     * matching entries.
+     *
+     * @param oldRefreshToken The refresh token that was used and is now invalid
+     * @param newRefreshToken The new refresh token received from the server
+     */
+    updateEntry(oldRefreshToken: string, newRefreshToken: string): Promise<void>;
+}

package/dist/typings/cache/cache-memory.d.ts

@@ -0,0 +1,4 @@
+import { ICache } from './shared';
+export declare class InMemoryCache {
+    enclosedCache: ICache;
+}

package/dist/typings/cache/index.d.ts

@@ -0,0 +1,4 @@
+export * from './cache-localstorage';
+export * from './cache-memory';
+export * from './cache-manager';
+export * from './shared';

package/dist/typings/cache/key-manifest.d.ts

@@ -0,0 +1,12 @@
+import { ICache, KeyManifestEntry, MaybePromise } from './shared';
+export declare class CacheKeyManifest {
+    private cache;
+    private clientId;
+    private readonly manifestKey;
+    constructor(cache: ICache, clientId: string);
+    add(key: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    get(): MaybePromise<KeyManifestEntry | undefined>;
+    clear(): MaybePromise<void>;
+    private createManifestKeyFrom;
+}

package/dist/typings/cache/shared.d.ts

@@ -0,0 +1,68 @@
+import { IdToken, User } from '../global';
+export declare const CACHE_KEY_PREFIX = "@@auth0spajs@@";
+export declare const CACHE_KEY_ID_TOKEN_SUFFIX = "@@user@@";
+export type CacheKeyData = {
+    audience?: string;
+    scope?: string;
+    clientId: string;
+};
+export declare class CacheKey {
+    prefix: string;
+    suffix?: string | undefined;
+    clientId: string;
+    scope?: string;
+    audience?: string;
+    constructor(data: CacheKeyData, prefix?: string, suffix?: string | undefined);
+    /**
+     * Converts this `CacheKey` instance into a string for use in a cache
+     * @returns A string representation of the key
+     */
+    toKey(): string;
+    /**
+     * Converts a cache key string into a `CacheKey` instance.
+     * @param key The key to convert
+     * @returns An instance of `CacheKey`
+     */
+    static fromKey(key: string): CacheKey;
+    /**
+     * Utility function to build a `CacheKey` instance from a cache entry
+     * @param entry The entry
+     * @returns An instance of `CacheKey`
+     */
+    static fromCacheEntry(entry: CacheEntry): CacheKey;
+}
+export interface DecodedToken {
+    claims: IdToken;
+    user: User;
+}
+export interface IdTokenEntry {
+    id_token: string;
+    decodedToken: DecodedToken;
+}
+export type CacheEntry = {
+    id_token?: string;
+    token_type?: string;
+    access_token: string;
+    expires_in: number;
+    decodedToken?: DecodedToken;
+    audience: string;
+    scope: string;
+    client_id: string;
+    refresh_token?: string;
+    oauthTokenScope?: string;
+};
+export type WrappedCacheEntry = {
+    body: Partial<CacheEntry>;
+    expiresAt: number;
+};
+export type KeyManifestEntry = {
+    keys: string[];
+};
+export type Cacheable = WrappedCacheEntry | KeyManifestEntry;
+export type MaybePromise<T> = Promise<T> | T;
+export interface ICache {
+    set<T = Cacheable>(key: string, entry: T): MaybePromise<void>;
+    get<T = Cacheable>(key: string): MaybePromise<T | undefined>;
+    remove(key: string): MaybePromise<void>;
+    allKeys?(): MaybePromise<string[]>;
+}

package/dist/typings/constants.d.ts

@@ -0,0 +1,58 @@
+import { PopupConfigOptions } from './global';
+/**
+ * @ignore
+ */
+export declare const DEFAULT_AUTHORIZE_TIMEOUT_IN_SECONDS = 60;
+/**
+ * @ignore
+ */
+export declare const DEFAULT_POPUP_CONFIG_OPTIONS: PopupConfigOptions;
+/**
+ * @ignore
+ */
+export declare const DEFAULT_SILENT_TOKEN_RETRY_COUNT = 3;
+/**
+ * @ignore
+ */
+export declare const CLEANUP_IFRAME_TIMEOUT_IN_SECONDS = 2;
+/**
+ * @ignore
+ */
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 10000;
+export declare const CACHE_LOCATION_MEMORY = "memory";
+export declare const CACHE_LOCATION_LOCAL_STORAGE = "localstorage";
+/**
+ * @ignore
+ */
+export declare const MISSING_REFRESH_TOKEN_ERROR_MESSAGE = "Missing Refresh Token";
+/**
+ * @ignore
+ */
+export declare const INVALID_REFRESH_TOKEN_ERROR_MESSAGE = "invalid refresh token";
+/**
+ * @ignore
+ */
+export declare const USER_BLOCKED_ERROR_MESSAGE = "user is blocked";
+/**
+ * @ignore
+ * The error_description returned by the /authorize endpoint when MFA is required
+ * but prompt=none prevents interaction (iframe silent auth flow).
+ */
+export declare const MFA_STEP_UP_ERROR_DESCRIPTION = "Multifactor authentication required";
+/**
+ * @ignore
+ */
+export declare const DEFAULT_SCOPE = "openid profile email";
+/**
+ * @ignore
+ */
+export declare const DEFAULT_SESSION_CHECK_EXPIRY_DAYS = 1;
+/**
+ * @ignore
+ */
+export declare const DEFAULT_AUTH0_CLIENT: {
+    name: string;
+    version: string;
+};
+export declare const DEFAULT_NOW_PROVIDER: () => number;
+export declare const DEFAULT_AUDIENCE = "default";

package/dist/typings/dpop/dpop.d.ts

@@ -0,0 +1,17 @@
+import { DpopStorage } from './storage';
+import * as dpopUtils from './utils';
+export declare class Dpop {
+    protected readonly storage: DpopStorage;
+    constructor(clientId: string);
+    getNonce(id?: string): Promise<string | undefined>;
+    setNonce(nonce: string, id?: string): Promise<void>;
+    protected getOrGenerateKeyPair(): Promise<dpopUtils.KeyPair>;
+    generateProof(params: {
+        url: string;
+        method: string;
+        nonce?: string;
+        accessToken?: string;
+    }): Promise<string>;
+    calculateThumbprint(): Promise<string>;
+    clear(): Promise<void>;
+}

package/dist/typings/dpop/storage.d.ts

@@ -0,0 +1,27 @@
+import { type KeyPair } from './utils';
+declare const TABLES: {
+    readonly NONCE: "nonce";
+    readonly KEYPAIR: "keypair";
+};
+type Table = (typeof TABLES)[keyof typeof TABLES];
+export declare class DpopStorage {
+    protected readonly clientId: string;
+    protected dbHandle: IDBDatabase | undefined;
+    constructor(clientId: string);
+    protected getVersion(): number;
+    protected createDbHandle(): Promise<IDBDatabase>;
+    protected getDbHandle(): Promise<IDBDatabase>;
+    protected executeDbRequest<T = unknown>(table: string, mode: IDBTransactionMode, requestFactory: (table: IDBObjectStore) => IDBRequest<T>): Promise<T>;
+    protected buildKey(id?: string): string;
+    setNonce(nonce: string, id?: string): Promise<void>;
+    setKeyPair(keyPair: KeyPair): Promise<void>;
+    protected save(table: Table, key: IDBValidKey, obj: unknown): Promise<void>;
+    findNonce(id?: string): Promise<string | undefined>;
+    findKeyPair(): Promise<KeyPair | undefined>;
+    protected find<T = unknown>(table: Table, key: IDBValidKey): Promise<T | undefined>;
+    protected deleteBy(table: Table, predicate: (key: IDBValidKey) => boolean): Promise<void>;
+    protected deleteByClientId(table: Table, clientId: string): Promise<void>;
+    clearNonces(): Promise<void>;
+    clearKeyPairs(): Promise<void>;
+}
+export {};

package/dist/typings/dpop/utils.d.ts

@@ -0,0 +1,15 @@
+import * as dpopLib from 'dpop';
+export declare const DPOP_NONCE_HEADER = "dpop-nonce";
+export type KeyPair = Readonly<dpopLib.KeyPair>;
+type GenerateProofParams = {
+    keyPair: KeyPair;
+    url: string;
+    method: string;
+    nonce?: string;
+    accessToken?: string;
+};
+export declare function generateKeyPair(): Promise<KeyPair>;
+export declare function calculateThumbprint(keyPair: Pick<KeyPair, 'publicKey'>): Promise<string>;
+export declare function generateProof({ keyPair, url, method, nonce, accessToken }: GenerateProofParams): Promise<string>;
+export declare function isGrantTypeSupported(grantType: string): boolean;
+export {};

package/dist/typings/errors.d.ts

@@ -0,0 +1,96 @@
+/**
+ * MFA requirements from an mfa_required error response
+ */
+export interface MfaRequirements {
+    /** Required enrollment types */
+    enroll?: Array<{
+        type: string;
+    }>;
+    /** Required challenge types */
+    challenge?: Array<{
+        type: string;
+    }>;
+}
+/**
+ * Thrown when network requests to the Auth server fail.
+ */
+export declare class GenericError extends Error {
+    error: string;
+    error_description: string;
+    constructor(error: string, error_description: string);
+    static fromPayload({ error, error_description }: {
+        error: string;
+        error_description: string;
+    }): GenericError;
+}
+/**
+ * Thrown when handling the redirect callback fails, will be one of Auth0's
+ * Authentication API's Standard Error Responses: https://auth0.com/docs/api/authentication?javascript#standard-error-responses
+ */
+export declare class AuthenticationError extends GenericError {
+    state: string;
+    appState: any;
+    constructor(error: string, error_description: string, state: string, appState?: any);
+}
+/**
+ * Thrown when handling the redirect callback for the connect flow fails, will be one of Auth0's
+ * Authentication API's Standard Error Responses: https://auth0.com/docs/api/authentication?javascript#standard-error-responses
+ */
+export declare class ConnectError extends GenericError {
+    connection: string;
+    state: string;
+    appState: any;
+    constructor(error: string, error_description: string, connection: string, state: string, appState?: any);
+}
+/**
+ * Thrown when silent auth times out (usually due to a configuration issue) or
+ * when network requests to the Auth server timeout.
+ */
+export declare class TimeoutError extends GenericError {
+    constructor();
+}
+/**
+ * Error thrown when the login popup times out (if the user does not complete auth)
+ */
+export declare class PopupTimeoutError extends TimeoutError {
+    popup: Window;
+    constructor(popup: Window);
+}
+export declare class PopupCancelledError extends GenericError {
+    popup: Window;
+    constructor(popup: Window);
+}
+export declare class PopupOpenError extends GenericError {
+    constructor();
+}
+/**
+ * Error thrown when the token exchange results in a `mfa_required` error
+ */
+export declare class MfaRequiredError extends GenericError {
+    mfa_token: string;
+    mfa_requirements: MfaRequirements;
+    constructor(error: string, error_description: string, mfa_token: string, mfa_requirements: MfaRequirements);
+}
+/**
+ * Error thrown when there is no refresh token to use
+ */
+export declare class MissingRefreshTokenError extends GenericError {
+    audience: string;
+    scope: string;
+    constructor(audience: string, scope: string);
+}
+/**
+ * Error thrown when there are missing scopes after refreshing a token
+ */
+export declare class MissingScopesError extends GenericError {
+    audience: string;
+    scope: string;
+    constructor(audience: string, scope: string);
+}
+/**
+ * Error thrown when the wrong DPoP nonce is used and a potential subsequent retry wasn't able to fix it.
+ */
+export declare class UseDpopNonceError extends GenericError {
+    newDpopNonce: string | undefined;
+    constructor(newDpopNonce: string | undefined);
+}

package/dist/typings/fetcher.d.ts

@@ -0,0 +1,54 @@
+import { GetTokenSilentlyVerboseResponse } from './global';
+export type ResponseHeaders = Record<string, string | null | undefined> | [string, string][] | {
+    get(name: string): string | null | undefined;
+};
+export type CustomFetchMinimalOutput = {
+    status: number;
+    headers: ResponseHeaders;
+};
+export type CustomFetchImpl<TOutput extends CustomFetchMinimalOutput> = (req: Request) => Promise<TOutput>;
+export type AuthParams = {
+    scope?: string[];
+    audience?: string;
+};
+type AccessTokenFactory = (authParams?: AuthParams) => Promise<string | GetTokenSilentlyVerboseResponse>;
+export type FetcherConfig<TOutput extends CustomFetchMinimalOutput> = {
+    getAccessToken?: AccessTokenFactory;
+    baseUrl?: string;
+    fetch?: CustomFetchImpl<TOutput>;
+    dpopNonceId?: string;
+};
+export type FetcherHooks = {
+    isDpopEnabled: () => boolean;
+    getAccessToken: AccessTokenFactory;
+    getDpopNonce: () => Promise<string | undefined>;
+    setDpopNonce: (nonce: string) => Promise<void>;
+    generateDpopProof: (params: {
+        url: string;
+        method: string;
+        nonce?: string;
+        accessToken: string;
+    }) => Promise<string>;
+};
+export type FetchWithAuthCallbacks<TOutput> = {
+    onUseDpopNonceError?(): Promise<TOutput>;
+};
+export declare class Fetcher<TOutput extends CustomFetchMinimalOutput> {
+    protected readonly config: Omit<FetcherConfig<TOutput>, 'fetch'> & Required<Pick<FetcherConfig<TOutput>, 'fetch'>>;
+    protected readonly hooks: FetcherHooks;
+    constructor(config: FetcherConfig<TOutput>, hooks: FetcherHooks);
+    protected isAbsoluteUrl(url: string): boolean;
+    protected buildUrl(baseUrl: string | undefined, url: string | undefined): string;
+    protected getAccessToken(authParams?: AuthParams): Promise<string | GetTokenSilentlyVerboseResponse>;
+    protected extractUrl(info: RequestInfo | URL): string;
+    protected buildBaseRequest(info: RequestInfo | URL, init: RequestInit | undefined): Request;
+    protected setAuthorizationHeader(request: Request, accessToken: string, tokenType?: string): void;
+    protected setDpopProofHeader(request: Request, accessToken: string): Promise<void>;
+    protected prepareRequest(request: Request, authParams?: AuthParams): Promise<void>;
+    protected getHeader(headers: ResponseHeaders, name: string): string;
+    protected hasUseDpopNonceError(response: TOutput): boolean;
+    protected handleResponse(response: TOutput, callbacks: FetchWithAuthCallbacks<TOutput>): Promise<TOutput>;
+    protected internalFetchWithAuth(info: RequestInfo | URL, init: RequestInit | undefined, callbacks: FetchWithAuthCallbacks<TOutput>, authParams?: AuthParams): Promise<TOutput>;
+    fetchWithAuth(info: RequestInfo | URL, init?: RequestInit, authParams?: AuthParams): Promise<TOutput>;
+}
+export {};