@okta/auth-foundation 0.6.0

package/dist/types/FetchClient.d.ts

@@ -0,0 +1,28 @@
+import { APIClient, APIRequest, WWWAuth } from './http/index.ts';
+import { TokenOrchestrator } from './TokenOrchestrator.ts';
+/**
+ * @module FetchClient
+ */
+/**
+ * Wrapper around [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to perform authenticated requests
+ * to a resource server
+ *
+ * The provided {@link TokenOrchestrator} is used to retrieve {@link Token}s which match the criteria passed in via
+ * {@link TokenOrchestrator.AuthorizeParams}, like `issuer`, `client` and `scopes`. Once a valid {@link Token} is found, the request is made
+ */
+export declare class FetchClient<E extends APIClient.Events = APIClient.Events> extends APIClient<E> {
+    private readonly orchestrator;
+    constructor(orchestrator: TokenOrchestrator, ...[params]: ConstructorParameters<typeof APIClient>);
+    /**
+     * default options
+     */
+    defaultRequestOptions: APIClient.RequestOptions;
+    protected checkForDPoPNonceErrorResponse(response: Response): Promise<string | undefined>;
+    protected prepareDPoPNonceRetry(request: APIRequest, nonce: string): Promise<void>;
+    protected prepareAcrStepUpRetry(response: Response, request: APIRequest, error: WWWAuth.WWWAuthenticateError): Promise<void>;
+    protected processErrorResponse(response: Response, request: APIRequest): Promise<Response>;
+    protected prepare401Retry(response: Response, request: APIRequest): Promise<void>;
+    protected prepare429Retry(response: Response, request: APIRequest): Promise<void>;
+    protected authorize(request: APIRequest): Promise<void>;
+    fetch(input: string | URL | Request, init?: TokenOrchestrator.AuthorizeParams & RequestInit & Partial<APIClient.RequestOptions>): Promise<Response>;
+}

package/dist/types/Token.d.ts

@@ -0,0 +1,246 @@
+import { type GrantType, type Expires, type TokenType, type RequestAuthorizer, type RequestAuthorizerInit, type Seconds, type JSONSerializable, type AcrValues, type TimeInterval, type JsonPrimitive, type JsonRecord } from './types/index.ts';
+import type { OAuth2Client } from './oauth2/client.ts';
+import { JWT } from './jwt/index.ts';
+import { OAuth2Request } from './http/index.ts';
+/**
+ * @module Token
+ */
+/**
+ * Object representation of a token response
+ * @group Types
+ */
+export type TokenResponse = {
+    id?: string;
+    tokenType: TokenType;
+    expiresIn: number;
+    issuedAt?: number;
+    scopes?: string | string[];
+    accessToken: string;
+    idToken?: string;
+    refreshToken?: string;
+    context: Token.Context;
+};
+/**
+ * Required and optional values to construct a {@link Token} instance
+ * @group Types
+ */
+export type TokenInit = Omit<TokenResponse, 'idToken'> & {
+    idToken?: string | JWT;
+};
+/**
+ * JSON representation of token (only contains primitive types)
+ * @group Types
+ */
+export type TokenPrimitiveInit = TokenResponse;
+/**
+ * Internal representation of a OAuth2/OIDC Token.
+ * Contains `accessToken`, conditionally contains `idToken` and `refreshToken`
+ *
+ * @group Token
+ *
+ * @remarks
+ * Most operations can be done by {@link Credential} methods. It's recommended
+ * to use those instead before reaching for a {@link Token.Token | Token} method
+ *
+ * @see
+ * - Okta Documentation: {@link https://developer.okta.com/docs/reference/api/oidc/#response-properties-4 | OIDC }
+ */
+export declare class Token implements JSONSerializable, Expires, RequestAuthorizer {
+    /** @internal */
+    static expiryTimeouts: {
+        [key: string]: ReturnType<typeof setTimeout>;
+    };
+    readonly id: string;
+    readonly issuedAt: Date;
+    /**
+     * The audience of the token. ex `Bearer` or `DPoP`
+     */
+    readonly tokenType: TokenType;
+    /**
+     * Seconds until token expires
+     */
+    readonly expiresIn: number;
+    /**
+     * OAuth2 / OIDC scopes associated with token
+     */
+    readonly scope: string;
+    /**
+     * String value of `accessToken`
+     */
+    readonly accessToken: string;
+    /**
+     * If the OAuth2 configuration includes OIDC, an `idToken` will be available
+     */
+    readonly idToken?: JWT;
+    /**
+     * If the OAuth2 configuration includes the scope `offline_access`, a `refreshToken` will be available
+     */
+    readonly refreshToken?: string;
+    /**
+     * Defines the context this token was issued from
+     */
+    readonly context: Token.Context;
+    /**
+     * The constructor of Token
+     */
+    constructor(obj: TokenInit);
+    /**
+     * @internal
+     *
+     * A static method (within this Base class) used to return instances of Derived classes
+     * References:
+     * - https://stackoverflow.com/questions/68672717/create-instance-of-derived-class-from-base-class-with-generic-types
+     * - https://stackoverflow.com/questions/60199917/in-typescript-how-to-return-sub-class-instance-in-a-static-function-in-base-cla
+     */
+    protected static create<T extends Token>(this: new (init: TokenInit) => T, init: TokenInit): T;
+    static serializer(t: object): string;
+    static isEqual(lhs: Token, rhs: Token): boolean;
+    static from(refreshToken: string, client: OAuth2Client): Promise<Token>;
+    /**
+     * When the Token will expire, represented as a `Date`
+     * @public
+     */
+    get expiresAt(): Date;
+    /**
+     * Compares `this.expiresAt` against `TimeCoordinator` to determine if Token is expired
+     * @public
+     */
+    get isExpired(): boolean;
+    /**
+     * Returns `true` if the {@link Token.Token | Token} is _not_ expired
+     *
+     * @see {@link Token.isExpired}
+     */
+    get isValid(): boolean;
+    /**
+     * Returns `true` if the {@link Token.Token | Token} will expire after a duration (seconds)
+     *
+     * @see {@link Token.willBeValidIn}
+     */
+    willBeExpiredIn(duration: Seconds): boolean;
+    /**
+     * Returns `true` if the {@link Token.Token | Token} will _not_ expire after a duration (seconds)
+     *
+     * @see {@link Token.willBeExpiredIn}
+     */
+    willBeValidIn(duration: Seconds): boolean;
+    /**
+     * Returns the OAuth2 `scope`(s) used to issue the token
+     */
+    get scopes(): string[];
+    /**
+     * Converts a {@link Token.Token | Token} instance to an serializable object literal representation
+     */
+    toJSON(): JsonRecord;
+    /**
+     * Used to merge separate {@link Token.Token | Token} instances together. Useful when handling token refresh as
+     * not every value is returned in a refresh request compared to the initial token request
+     *
+     * @param token the "old" token instance to be merged into the "new" token
+     * @returns new {@link Token.Token | Token} instance
+     */
+    merge(token: Token): Token;
+    serialize(): string;
+    /**
+     * Signs a outgoing {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request} with an `Authorization` header.
+     * Accepts the same method signature as {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch | fetch}
+     * @returns {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request} wrapped in a `Promise`
+     *
+     */
+    authorize(input: string | URL | Request, init?: RequestAuthorizerInit): Promise<Request>;
+}
+/**
+ * @group Token
+ */
+export declare namespace Token {
+    /**
+     * Context used to request the token
+     */
+    type Context = {
+        issuer: string;
+        clientId: string;
+        scopes: string[];
+        dpopPairId?: string;
+        acrValues?: AcrValues;
+        maxAge?: TimeInterval;
+    };
+    /**
+     * Utility function for extracting {@link Token.Context} from an union-type object like {@link Token.Metadata:TYPE | Token.Metadata}
+     */
+    function extractContext(input: {
+        [key: string]: unknown;
+    }): Token.Context;
+    /**
+     * Non-sensitive metadata values associated with a {@link Token.Token | Token}. Used to store {@link Token.Context} and additional
+     * metadata for a given {@link Token.Token | Token}
+     * {@label TYPE}
+     */
+    type Metadata = Context & {
+        id: string;
+        tags: string[];
+        claims?: JsonRecord;
+    };
+    function Metadata(token: Token, tags?: string[]): Metadata;
+    /** @internal */
+    interface TokenRequestParams extends OAuth2Request.RequestParams {
+        grantType: GrantType;
+        acrValues?: AcrValues;
+        maxAge?: TimeInterval;
+    }
+    /** @internal */
+    class TokenRequest extends OAuth2Request {
+        grantType: GrantType;
+        acrValues?: AcrValues;
+        maxAge?: TimeInterval;
+        constructor(params: TokenRequestParams);
+        get url(): string;
+    }
+    /** @internal */
+    interface RefreshRequestParams extends Omit<Token.TokenRequestParams, 'grantType'> {
+        id?: string;
+        scope?: string;
+        refreshToken: string;
+    }
+    /** @internal */
+    class RefreshRequest extends Token.TokenRequest {
+        id?: string;
+        scope?: string;
+        refreshToken: string;
+        constructor(params: RefreshRequestParams);
+    }
+    /**
+     * Possible values provided to {@link OAuth2.OAuth2Client.revoke | OAuth2Client.revoke} to determine which tokens to revoke
+     */
+    type RevokeType = 'ALL' | 'ACCESS' | 'REFRESH';
+    /** @internal */
+    interface RevokeRequestParams extends OAuth2Request.RequestParams {
+        token: string;
+        hint: 'access_token' | 'refresh_token';
+    }
+    /** @internal */
+    class RevokeRequest extends OAuth2Request {
+        constructor(params: RevokeRequestParams);
+        get url(): string;
+    }
+    /**
+     * Possible values provided to {@link OAuth2.OAuth2Client.introspect | OAuth2Client.introspect} to determine which token to introspect
+     */
+    type Kind = 'access_token' | 'refresh_token' | 'id_token';
+    /** @internal */
+    interface IntrospectRequestParams extends OAuth2Request.RequestParams {
+        token: Token;
+        type: Token.Kind;
+    }
+    /** @internal */
+    class IntrospectRequest extends OAuth2Request {
+        constructor(params: IntrospectRequestParams);
+        get url(): string;
+    }
+    /**
+     * Payload structure of a `/introspect` response
+     */
+    type IntrospectResponse = {
+        active: boolean;
+        [key: string]: JsonPrimitive;
+    };
+}

package/dist/types/TokenOrchestrator.d.ts

@@ -0,0 +1,64 @@
+import type { RequestAuthorizer, RequestAuthorizerInit, JsonRecord, AcrValues } from './types/index.ts';
+import { Token } from './Token.ts';
+import { EventEmitter } from './utils/EventEmitter.ts';
+/**
+ * @module TokenOrchestrator
+ */
+/**
+ * @abstract
+ *
+ * Defines how {@link Token | Tokens} are retrieved to be consumed within an application
+ *
+ * @see {@link FetchClient}
+ */
+export declare abstract class TokenOrchestrator<E extends TokenOrchestrator.Events = TokenOrchestrator.Events> implements RequestAuthorizer {
+    protected readonly emitter: EventEmitter<E>;
+    on(...args: Parameters<EventEmitter<E>['on']>): EventEmitter<E>;
+    off(...args: Parameters<EventEmitter<E>['off']>): EventEmitter<E>;
+    /**
+     * @abstract
+     * Retrieves a valid {@link Token.Token | Token} to be used within an application
+     *
+     */
+    abstract getToken(params: TokenOrchestrator.AuthorizeParams): Promise<Token | null>;
+    /**
+     * Signs an outgoing {@link !Request} with an `Authorization` header via {@link Token.Token | Token} retrieved from {@link getToken}
+     *
+     * Optionally {@link TokenOrchestrator.AuthorizeParams | AuthorizeParams} can be provided to be passed along to {@link getToken}
+     *
+     * @see {@link FetchClient}
+     */
+    authorize(input: string | URL | Request, init?: RequestAuthorizerInit & TokenOrchestrator.AuthorizeParams): Promise<Request>;
+}
+export declare namespace TokenOrchestrator {
+    type Events = {
+        error: {
+            error: Error | JsonRecord;
+            type?: string;
+        };
+    };
+    /**
+     * Parameters used to make OAuth2 token requests
+     */
+    type AuthorizeParams = {
+        issuer?: string | URL;
+        clientId?: string;
+        scopes?: string[];
+        maxAge?: number;
+        acrValues?: AcrValues;
+    };
+    /**
+     * Utility function to separate {@link AuthorizeParams} from other options.
+     * Intended to help separate params from intersected types in method signatures
+     *
+     * Convenient for custom {@link TokenOrchestrator} implementations
+     */
+    function extractAuthParams(input: {
+        [key: string]: any;
+    }): {
+        authParams: TokenOrchestrator.AuthorizeParams;
+        rest: {
+            [key: string]: any;
+        };
+    };
+}

package/dist/types/core.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module Core
+ */
+export * from './types/index.ts';
+export * from './http/index.ts';
+export * from './errors/index.ts';
+export * from './utils/index.ts';
+export * from './utils/EventEmitter.ts';
+export * from './utils/TimeCoordinator.ts';
+export * from './utils/TaskBridge.ts';
+export { randomBytes, shortID } from './crypto/index.ts';
+export * from './jwt/index.ts';
+export * from './oauth2/pkce.ts';
+export * from './oauth2/dpop/index.ts';
+export * from './oauth2/client.ts';
+export * from './Token.ts';
+export * from './Credential/index.ts';
+export * from './TokenOrchestrator.ts';
+export * from './FetchClient.ts';
+export { addEnv } from './http/oktaUserAgent.ts';
+export { Platform, type PlatformDependencies } from './platform/Platform.ts';

package/dist/types/crypto/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+/** @internal */
+export declare function buf(input: string): ArrayBuffer;
+export declare function buf(input: Uint8Array | ArrayBuffer): string;
+/** @internal */
+export declare function encodeBase64Url(input: Uint8Array | ArrayBuffer): string;
+/** @internal */
+export declare function decodeBase64Url(input: string): Uint8Array<ArrayBuffer>;
+/** @internal */
+export declare function b64u(input: string): ArrayBuffer;
+export declare function b64u(input: Uint8Array | ArrayBuffer): string;
+/**
+ * @internal
+ * @group Crypto
+ * @returns SHA-256 hash of input `string`
+ */
+export declare function hash(str: string): Promise<string>;
+/**
+ * Generates a cryptographically random string
+ *
+ * @group Crypto
+ */
+export declare function randomBytes(): string;
+/**
+ * Generates a cryptographically random short ID
+ *
+ * @group Crypto
+ */
+export declare function shortID(): string;

package/dist/types/errors/APIClientError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when an {@link Networking.APIClient} encounters an unexpected condition
+ *
+ * @group Errors
+ */
+export declare class APIClientError extends AuthSdkError {
+}

package/dist/types/errors/AuthSdkError.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { JsonRecord } from '../types/lib.ts';
+/**
+ * Base Error class for all errors defined within Okta Client JavaScript
+ *
+ * @group Errors
+ */
+export declare class AuthSdkError extends Error {
+    /**
+     * A dictionary to store the context in which the error was thrown
+     * For example: The authentication context when an error is thrown during an authentication flow
+     */
+    context: JsonRecord;
+    constructor(message?: string, options?: ErrorOptions & {
+        context?: JsonRecord;
+    });
+}

package/dist/types/errors/CredentialError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when a {@link Credential} instance encounters an unexpected condition
+ *
+ * @group Errors
+ */
+export declare class CredentialError extends AuthSdkError {
+}

package/dist/types/errors/DPoPError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when a problem occurs during a token DPoP operation
+ *
+ * @group Errors
+ */
+export declare class DPoPError extends AuthSdkError {
+}

package/dist/types/errors/JWTError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when a problem occurs during {@link JWT} parsing or processing
+ *
+ * @group Errors
+ */
+export declare class JWTError extends AuthSdkError {
+}

package/dist/types/errors/NetworkError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when a problem occurs when sending or processing a network request
+ *
+ * @group Errors
+ */
+export declare class NetworkError extends AuthSdkError {
+}

package/dist/types/errors/OAuth2Error.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { OAuth2ErrorResponse } from '../types/index.ts';
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when an OAuth2 request (like /token) returns an error status
+ *
+ * @group Errors
+ */
+export declare class OAuth2Error extends AuthSdkError {
+    description?: string;
+    uri?: string;
+    constructor(error: string | OAuth2ErrorResponse, description?: string, uri?: string);
+    get error(): string;
+}

package/dist/types/errors/TokenError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when a {@link Token | Token} instance encounters an unexpected condition
+ *
+ * @group Errors
+ */
+export declare class TokenError extends AuthSdkError {
+}

package/dist/types/errors/TokenOrchestratorError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import { AuthSdkError } from './AuthSdkError.ts';
+/**
+ * Thrown when a {@link TokenOrchestrator} encounters an unexpected condition
+ *
+ * @group Errors
+ */
+export declare class TokenOrchestratorError extends AuthSdkError {
+}

package/dist/types/errors/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+export * from './AuthSdkError.ts';
+export * from './OAuth2Error.ts';
+export * from './JWTError.ts';
+export * from './TokenError.ts';
+export * from './APIClientError.ts';
+export * from './DPoPError.ts';
+export * from './CredentialError.ts';
+export * from './TokenOrchestratorError.ts';
+export * from './NetworkError.ts';

package/dist/types/http/APIClient.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @module
+ * @mergeModuleWith Networking
+ */
+import type { JsonRecord, JSONSerializable } from '../types/index.ts';
+import { DPoPNonceCache } from '../oauth2/dpop/nonceCache.ts';
+import { APIRequest } from './requests/APIRequest.ts';
+import { EventEmitter } from '../utils/EventEmitter.ts';
+import { APIClientError } from '../errors/index.ts';
+export * from './requests/APIRequest.ts';
+export * from './requests/OAuth2Request.ts';
+/**
+ * @group APIClient
+ */
+export declare abstract class APIClient<E extends APIClient.Events = APIClient.Events> {
+    #private;
+    readonly configuration: APIClient.Configuration;
+    readonly emitter: EventEmitter<E>;
+    protected readonly dpopNonceCache: DPoPNonceCache;
+    protected readonly interceptors: APIClient.RequestInterceptor[];
+    defaultHeaders: Record<string, string>;
+    defaultRequestOptions: APIClient.RequestOptions;
+    constructor(params?: APIClient.ConfigurationParams | APIClient.Configuration);
+    protected getDPoPNonceCacheKey(request: Request): string;
+    protected getDPoPNonceFromCache(request: Request): Promise<string | undefined>;
+    protected cacheDPoPNonce(request: Request, nonce: string): Promise<void>;
+    /**
+     * Registers an {@link APIClient.RequestInterceptor} on the {@link APIClient}
+     *
+     * @example
+     * const interceptor = (request: Request) => {
+     *   req.headers.append('foo', '1');
+     *   return req;
+     * };
+     * client.addInterceptor(interceptor);
+     */
+    addInterceptor(interceptor: APIClient.RequestInterceptor): void;
+    /**
+     * Unregisters an {@link APIClient.RequestInterceptor} on the {@link APIClient}
+     *
+     * @example
+     * const interceptor = (request: Request) => { ... };
+     * client.addInterceptor(interceptor);
+     * ...
+     * client.removeInterceptor(interceptor);
+     */
+    removeInterceptor(interceptor: APIClient.RequestInterceptor): void;
+    protected applyInterceptors(request: APIRequest): Promise<Request>;
+    protected abstract checkForDPoPNonceErrorResponse(response: Response): Promise<string | undefined>;
+    protected abstract prepareDPoPNonceRetry(request: APIRequest, nonce: string): Promise<void>;
+    protected processResponse(response: Response, request: APIRequest): Promise<void>;
+    protected processErrorResponse(response: Response, request: APIRequest): Promise<Response>;
+    protected authorize(request: APIRequest): Promise<void>;
+    protected sendRequest(request: Request): Promise<Response>;
+    protected send(request: APIRequest): Promise<Response>;
+    protected retry(request: APIRequest): Promise<Response>;
+    protected getRetryDelay(response: Response, request: APIRequest): number;
+    fetch(...args: ConstructorParameters<typeof APIRequest>): Promise<Response>;
+}
+/**
+ * @group APIClient
+ */
+export declare namespace APIClient {
+    type ConfigurationParams = {
+        dpop?: boolean;
+        fetchImpl?: typeof fetch;
+    };
+    class Configuration implements JSONSerializable {
+        dpop: boolean;
+        fetchImpl?: typeof fetch;
+        static DefaultOptions: {
+            dpop: boolean;
+            fetchImpl?: typeof fetch;
+        };
+        constructor(params: APIClient.ConfigurationParams);
+        toJSON(): JsonRecord;
+    }
+    type RequestOptions = {
+        /**
+         * When `true`, utilizes the provided {@link TokenOrchestrator} to acquire an access token to sign the outgoing request with the proper
+         * `Authorization` and `Dpop` headers, depending on the {@link TokenType} of the acquired {@link Token}. Defaults to `true`
+         */
+        authorizeRequest: boolean | ((request: APIRequest) => boolean);
+    };
+    type RequestInterceptor = (request: APIRequest) => (Promise<APIRequest> | APIRequest);
+    type Events = {
+        /**
+         * Fired before a request is sent
+         *
+         * @remarks
+         * The `request` instance is `readonly`. For outgoing request customization see {@link APIClient.addInterceptor}
+         */
+        'will_send': {
+            request: Request;
+        };
+        /**
+         * Fired after a response is received
+         */
+        'did_send': {
+            request: Request;
+            response: Response;
+        };
+        /**
+         * Fired after a {@link fetch} call fails to complete (`TypeError: Failed to fetch`)
+         */
+        'network_failure': {
+            request: Request;
+            error: APIClientError;
+            cause: Error;
+        };
+    };
+    function isNetworkError(err: unknown): boolean;
+}

package/dist/types/http/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module Networking
+ */
+export * from './requests/OAuth2Request.ts';
+export * from './APIClient.ts';
+export * as WWWAuth from './wwwAuthenticate.ts';

package/dist/types/http/oktaUserAgent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+/** @internal */
+export declare function addEnv(env: string): void;
+/** @internal */
+export declare function getOktaUserAgent(): string;