@okta/auth-foundation 0.6.0

package/dist/types/http/requests/APIRequest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @group APIClient
+ */
+export type APIRequestInit = RequestInit & {
+    context?: object;
+};
+/**
+ * @group APIClient
+ */
+export declare class APIRequest extends Request {
+    #private;
+    static MaxRetryAttempts: number;
+    readonly context: Record<string, any>;
+    constructor(input: string | URL | Request, init?: APIRequestInit);
+    get retryAttempt(): number;
+    canRetry(): boolean;
+    markRetry(): void;
+    clone(): APIRequest;
+}

package/dist/types/http/requests/OAuth2Request.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+import type { OpenIdConfiguration } from '../../types/index.ts';
+import type { OAuth2Client } from '../../oauth2/client.ts';
+import { APIRequest } from './APIRequest.ts';
+/**
+ * @group OAuth2Request
+ */
+export declare abstract class OAuth2Request {
+    headers: Headers;
+    body: URLSearchParams;
+    openIdConfiguration: OpenIdConfiguration;
+    clientConfiguration: OAuth2Client.Configuration;
+    clientAuthentication: any;
+    constructor(params: OAuth2Request.RequestParams);
+    abstract get url(): string;
+    prepare(context?: object): APIRequest;
+}
+/**
+ * @group OAuth2Request
+ */
+export declare namespace OAuth2Request {
+    interface RequestParams {
+        openIdConfiguration: OpenIdConfiguration;
+        clientConfiguration: OAuth2Client.Configuration;
+        clientAuthentication?: any;
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * @module
+ * @mergeModuleWith Networking
+ */
+/**
+ * @group WWWAuthenticate
+ */
+export interface WWWAuthenticateError {
+    readonly error: string;
+    readonly errorDescription: string;
+    readonly scheme: string;
+    [key: string]: string;
+}
+/**
+ * @group WWWAuthenticate
+ */
+export declare function isWWWAuthenticateError(input: unknown): input is WWWAuthenticateError;
+/**
+ * parses a www-authenticate header and builds an object representation of the error condition
+ *
+ * @group WWWAuthenticate
+ */
+export declare function parse(header: string | Headers | Response): WWWAuthenticateError | null;
+/**
+ * Returns string value of a `www-authenticate` header
+ *
+ * @remarks
+ * `HeadersInit` allows for a few different representations of headers with different access patterns (.get vs [key])
+ *
+ * @group WWWAuthenticate
+ */
+export declare function getHeader(headers: HeadersInit): string | null;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @module Core
+ */
+export * from './core.ts';

package/dist/types/internal.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+export * from './utils/validators.ts';
+export { addEnv } from './http/oktaUserAgent.ts';
+export { buf, b64u } from './crypto/index.ts';
+export * from './platform/defaults.ts';

package/dist/types/jwt/IDTokenValidator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import type { AcrValues } from '../types/index.ts';
+import type { JWT } from './JWT.ts';
+/**
+ * @group JWT
+ */
+export interface IDTokenValidatorContext {
+    nonce?: string;
+    maxAge?: number;
+    acrValues?: AcrValues;
+    supportedAlgs?: string[];
+}
+/**
+ * @group JWT
+ */
+export interface IDTokenValidator {
+    issuedAtGraceInterval: number;
+    checks: IDTokenValidator.ValidationCheck[];
+    validate: (token: JWT, issuer: URL, clientId: string, context?: IDTokenValidatorContext) => void;
+}
+/**
+ * @group JWT
+ *
+ * @remarks
+ * https://openid.net/specs/openid-connect-core-1_0-final.html#IDToken
+ */
+export declare namespace IDTokenValidator {
+    /**
+     * A list of validition checks which will be performed to validate a {@link JWT}
+     */
+    const allValidationChecks: readonly ["issuer", "audience", "scheme", "algorithm", "expirationTime", "issuedAtTime", "nonce", "maxAge", "subject", "acr"];
+    type ValidationCheck = (typeof allValidationChecks)[number];
+}
+/** @internal */
+export declare const DefaultIDTokenValidator: IDTokenValidator;

package/dist/types/jwt/JWK.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import type { JWT } from './JWT.ts';
+/**
+ * @group JWT
+ */
+export interface JWK extends JsonWebKey {
+    alg: JWK.Algorithm;
+    kid: string;
+}
+/**
+ * @group JWT
+ */
+export type JWKS = JWK[];
+/**
+ * @group JWT
+ */
+export type JWKValidator = {
+    validate: (token: JWT, keySet: JWKS) => Promise<boolean>;
+};
+/** @internal */
+export declare const DefaultJWKValidator: JWKValidator;
+/**
+ * @group JWT
+ */
+export declare namespace JWK {
+    type Algorithm = 'RS256';
+    const validator: JWKValidator;
+}

package/dist/types/jwt/JWT.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import type { JsonRecord, RawRepresentable, Expires, TimeInterval } from '../types/index.ts';
+import { JWKS } from './JWK.ts';
+import { IDTokenValidator } from './IDTokenValidator.ts';
+/**
+ * @group JWT
+ */
+export interface JWTHeader {
+    alg: string;
+    kid?: string;
+    typ?: string;
+}
+/**
+ * @group JWT
+ */
+export type JWTPayload = {
+    aud?: string;
+    iss?: string;
+    sub?: string;
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    jti?: string;
+    scp?: string[];
+    acr?: string;
+    at_hash?: string;
+} & JsonRecord;
+/**
+ * A class representation of a JWT
+ *
+ * @group JWT
+ *
+ * @see
+ * https://datatracker.ietf.org/doc/html/rfc7519
+ */
+export declare class JWT implements RawRepresentable, Expires {
+    #private;
+    constructor(jwtStr: string);
+    /**
+     * Writes a signed JWT string
+     */
+    static write(header: JWTHeader, claims: JsonRecord, signingKey: CryptoKey): Promise<string>;
+    get header(): JWTHeader;
+    get claims(): JWTPayload;
+    get payload(): JWTPayload;
+    /**
+     * @remarks
+     * `RawRepresentable`
+     * @returns stringified representation of the JWT
+     */
+    get rawValue(): string;
+    /**
+     * @group JWT Claim accessor
+     */
+    get audience(): string | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get expirationTime(): Date | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get expiresIn(): TimeInterval;
+    /**
+     * @group JWT Claim accessor
+     */
+    get issuer(): string | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get issuedAt(): Date | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get notBefore(): Date | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get scope(): string[] | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get scopes(): string[] | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get subject(): string | undefined;
+    /**
+     * @group JWT Claim accessor
+     */
+    get expiresAt(): Date | undefined;
+    get isExpired(): boolean;
+    get isValid(): boolean;
+    verifySignature(keySet: JWKS): Promise<boolean>;
+    validate(keySet: JWKS): Promise<boolean>;
+    toJSON(): {
+        rawValue: string;
+    };
+    toString(): string;
+}
+/**
+ * @group JWT
+ */
+export type JWTValidator = IDTokenValidator;

package/dist/types/jwt/TokenHashValidator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+import type { JWT } from './JWT.ts';
+/**
+ * @group JWT
+ */
+export interface TokenHashValidator {
+    validate: (token: string, idToken: JWT) => Promise<void>;
+}
+/** @internal */
+export declare function DefaultTokenHashValidator(hashKey: string): TokenHashValidator;

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

@@ -0,0 +1,8 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+export * from './JWK.ts';
+export * from './JWT.ts';
+export * from './IDTokenValidator.ts';
+export * from './TokenHashValidator.ts';

package/dist/types/oauth2/client.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @module OAuth2
+ */
+import type { OpenIdConfiguration, OAuth2ErrorResponse, JsonRecord } from '../types/index.ts';
+import { JWKS, IDTokenValidator, TokenHashValidator } from '../jwt/index.ts';
+import { APIClient, APIRequest } from '../http/index.ts';
+import { Configuration as ConfigurationConstructor, type ConfigurationParams } from './configuration.ts';
+import { Token } from '../Token.ts';
+import { UserInfo } from './requests/UserInfo.ts';
+import { PromiseQueue } from '../utils/PromiseQueue.ts';
+import { EventEmitter } from '../utils/EventEmitter.ts';
+/**
+ * @group OAuth2Client
+ * @noInheritDoc
+ */
+export declare class OAuth2Client<E extends OAuth2Client.Events = OAuth2Client.Events> extends APIClient<E> {
+    #private;
+    /**
+     * @group Customizations
+     */
+    static readonly idTokenValidator: IDTokenValidator;
+    /**
+     * @group Customizations
+     */
+    static readonly accessTokenValidator: TokenHashValidator;
+    /** @internal */
+    protected readonly queue: PromiseQueue;
+    readonly emitter: EventEmitter<E>;
+    readonly configuration: OAuth2Client.Configuration;
+    constructor(params: ConfigurationParams | OAuth2Client.Configuration);
+    /** @internal */
+    protected getDPoPNonceCacheKey(request: APIRequest): string;
+    /**
+     * @remarks
+     * Auth Servers return a 400 with dpop-nonce header and a json body identifying the error
+     *
+     * @see
+     * - https://datatracker.ietf.org/doc/html/rfc9449#section-8
+     * - https://datatracker.ietf.org/doc/html/rfc9449#figure-20
+     *
+     * @internal
+     */
+    protected checkForDPoPNonceErrorResponse(response: Response): Promise<string | undefined>;
+    /** @internal */
+    protected prepareDPoPNonceRetry(request: APIRequest, nonce: string): Promise<void>;
+    protected signTokenRequestWithDPoP(request: APIRequest, nonce?: string): Promise<void>;
+    protected processResponse(response: Response, request: APIRequest): Promise<void>;
+    /** @internal */
+    protected getJson(url: URL, options?: OAuth2Client.GetJsonOptions): Promise<JsonRecord>;
+    /**
+     * Retrieves the Authorization Server's OpenID configuration
+     */
+    openIdConfiguration(options?: OAuth2Client.GetJsonOptions): Promise<OpenIdConfiguration>;
+    /**
+     * Retrieves the Authorization Server's {@link Core.JWKS | JWKS} key configuration
+     */
+    jwks(options?: OAuth2Client.GetJsonOptions): Promise<JWKS>;
+    /** @internal */
+    protected sendTokenRequest(tokenRequest: Token.TokenRequest, requestContext?: OAuth2Client.TokenRequestContext): Promise<Token | OAuth2ErrorResponse>;
+    /** @internal */
+    protected validateToken(request: Token.TokenRequest, keySet: JWKS, token: Token): Promise<Token | OAuth2ErrorResponse>;
+    /**
+     * Attempts to exchange, and verify, a token from the provided request
+     */
+    exchange(request: Token.TokenRequest): Promise<Token | OAuth2ErrorResponse>;
+    /**
+     * Attempts to refresh the provided token, using the {@link Token.Token.refreshToken | refreshToken} if it is available
+     */
+    refresh(token: Token, scopes?: string[]): Promise<Token | OAuth2ErrorResponse>;
+    /** @internal */
+    protected prepareRefreshRequest(token: Token, scopes?: string[]): Promise<Token | OAuth2ErrorResponse>;
+    /** @internal */
+    protected performRefresh(token: Token, scopes?: string[]): Promise<OAuth2ErrorResponse | Token>;
+    /**
+     * Attempts to revoke the provided token
+     */
+    revoke(token: Token, type: Token.RevokeType): Promise<void | OAuth2ErrorResponse>;
+    /** @internal */
+    protected revokeAll(token: Token): Promise<void | OAuth2ErrorResponse>;
+    /**
+     * Introspects the provided token information
+     */
+    introspect(token: Token, kind: Token.Kind): Promise<Token.IntrospectResponse | OAuth2ErrorResponse>;
+    /**
+     * Fetches the {@link UserInfo} associated with the provided token
+     */
+    userInfo(token: Token): Promise<UserInfo | OAuth2ErrorResponse>;
+}
+/**
+ * @group OAuth2Client
+ */
+export declare namespace OAuth2Client {
+    class Configuration extends ConfigurationConstructor {
+    }
+    type Events = {
+        /**
+         * Triggered when a token refresh attempt begins
+         */
+        'token_will_refresh': {
+            token: Token;
+        };
+        /**
+         * Triggered when a token refresh attempt succeeds
+         */
+        'token_did_refresh': {
+            token: Token;
+        };
+    } & APIClient.Events;
+    /** @internal */
+    type TokenRequestContext = {
+        dpopPairId?: string;
+    };
+    /** @internal */
+    const DefaultGetJsonOptions: GetJsonOptions;
+    /** @internal */
+    type GetJsonOptions = {
+        skipCache?: boolean;
+    };
+    function isDPoPProofClockSkewError(error: OAuth2ErrorResponse): boolean;
+}

package/dist/types/oauth2/configuration.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+import type { ClientAuthentication, APIClientConfiguration, JSONSerializable, JsonRecord, OAuth2Params, DiscrimUnion } from '../types/index.ts';
+import { APIClient } from '../http/index.ts';
+export type OAuth2ClientConfigurations = DiscrimUnion<OAuth2Params & {
+    baseURL: URL | string;
+    discoveryURL?: URL | string;
+}, 'issuer' | 'baseURL'>;
+export type OAuth2ClientOptions = {
+    authentication?: ClientAuthentication;
+    allowHTTP?: boolean;
+    syncClockWithAuthorizationServer?: boolean;
+};
+/**
+ * @group Configuration
+ * @useDeclaredType
+ */
+export type ConfigurationParams = OAuth2ClientConfigurations & OAuth2ClientOptions;
+/**
+ * @group Configuration
+ */
+export declare class Configuration extends APIClient.Configuration implements APIClientConfiguration, JSONSerializable {
+    readonly issuer: URL;
+    readonly discoveryURL: URL;
+    readonly clientId: string;
+    scopes: string;
+    authentication: ClientAuthentication;
+    /**
+     * When `true`, issuer and other .well-known endpoints can be HTTP. Defaults to `false`
+     */
+    allowHTTP: boolean;
+    /**
+     * When `true`, the `Date` header from HTTP requests made to the Authorization Server will be
+     * used to calculate a clock skew between the Authorization Server and the system clock. This is
+     * useful for situations when the client's system clock is set to something other than the "true time".
+     *
+     * Defaults to `true`.
+     *
+     * @remarks
+     * By default, the `Date` header is not safelisted for CORS requests. The Authorization Server will need
+     * to include the `Date` header in the `allow-control-exppose-headers` for this feature to work properly.
+     *
+     * Reference: https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header
+     */
+    syncClockWithAuthorizationServer: boolean;
+    static DefaultOptions: Required<OAuth2ClientOptions> & typeof APIClient.Configuration.DefaultOptions;
+    constructor(params: ConfigurationParams);
+    /**
+     * Alias to {@link issuer} for backwards compatibility
+     */
+    get baseURL(): URL;
+    matches(params: OAuth2Params): boolean;
+    toJSON(): JsonRecord;
+}

package/dist/types/oauth2/dpop/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+import type { DPoPHeaders, DPoPClaims, DPoPProofParams } from './types.ts';
+import { DPoPStorage } from './storage.ts';
+import { DPoPNonceCache } from './nonceCache.ts';
+export { DPoPNonceCache, DPoPStorage };
+export type { DPoPHeaders, DPoPClaims, DPoPProofParams };
+/**
+ * @group DPoP
+ *
+ */
+export interface DPoPSigningAuthority {
+    createDPoPKeyPair: () => Promise<string>;
+    deleteDPoPKeyPair: (keyPairId: string) => Promise<void>;
+    clearDPoPKeyPairs: () => Promise<void>;
+    sign: (request: Request, params: Omit<DPoPProofParams, 'request'>) => Promise<Request>;
+}
+/**
+ * @internal
+ * @group DPoP
+ * Default implementation of a DPoP Signing Authority.
+ * Signs outgoing network requests with a dpop proof (private key JWT) as well as
+ * creates, stores and retrieves the Crypto Key Pairs necessary for the signing operation
+ *
+ */
+export declare class DPoPSigningAuthorityImpl implements DPoPSigningAuthority {
+    private readonly store;
+    constructor(store: DPoPStorage);
+    /**
+     * @internal
+     * @group DPoP
+     * @returns a public/private key pair. The private key will be non-extractable
+     */
+    private generateKeyPair;
+    /**
+     * Generates a (non-extractable) key pair and writes it to storage, to be used for `DPoP` signatures
+     *
+     * @group DPoP
+     * @returns `id` representing the generated key pair
+     */
+    createDPoPKeyPair(): Promise<string>;
+    /**
+     * Removes a `DPoP` key pair from storage
+     *
+     * @group DPoP
+     */
+    deleteDPoPKeyPair(keyPairId: string): Promise<void>;
+    /**
+     * Clears `DPoP` storage of all key pairs
+     *
+     * @group DPoP
+     */
+    clearDPoPKeyPairs(): Promise<void>;
+    /**
+     * TODO: Document method
+     *
+     * @group DPoP
+     * @returns A `DPoP` `JWT` proof for the provided `Request`
+     */
+    private generateDPoPProof;
+    /**
+     * Signs an outgoing network requests with a DPoP proof
+     * @param request - outgoing network request to be sign with a DPoP proof
+     * @param params - the required component necessary to generate the DPoP proof
+     * @returns
+     */
+    sign(request: Request, params: Omit<DPoPProofParams, 'request'>): Promise<Request>;
+}

package/dist/types/oauth2/dpop/nonceCache.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+/**
+ * @group DPoP
+ */
+export interface DPoPNonceCache {
+    getNonce(key: string): Promise<string | undefined>;
+    cacheNonce(key: string, nonce: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * @internal
+ */
+export declare namespace DPoPNonceCache {
+    /**
+     * @internal
+     * Implementation of an in-memory cache; backed via `Map`
+     */
+    class InMemoryCache implements DPoPNonceCache {
+        #private;
+        getNonce(key: string): Promise<string | undefined>;
+        cacheNonce(key: string, nonce: string): Promise<void>;
+        clear(): Promise<void>;
+    }
+}

package/dist/types/oauth2/dpop/storage.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+/**
+ * @group DPoP
+ */
+export interface DPoPStorage {
+    add(id: string, keyPair: CryptoKeyPair): Promise<void>;
+    get(id: string): Promise<CryptoKeyPair | null>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * @group DPoP
+ * @internal
+ */
+export declare namespace DPoPStorage {
+    /** @internal */
+    class MemoryStore implements DPoPStorage {
+        #private;
+        add(id: string, keyPair: CryptoKeyPair): Promise<void>;
+        get(id: string): Promise<CryptoKeyPair | null>;
+        remove(id: string): Promise<void>;
+        clear(): Promise<void>;
+    }
+}

package/dist/types/oauth2/dpop/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+import type { JsonRecord } from '../../types/index.ts';
+/**
+ * @group DPoP
+ */
+export interface DPoPClaims extends JsonRecord {
+    /**
+     * (http) request method (verb)
+     */
+    htm: string;
+    /**
+     * (http) request url
+     */
+    htu: string;
+    /**
+     * issued at (timestamp)
+     */
+    iat: number;
+    /**
+     * unique identifier
+     */
+    jti: string;
+    /**
+     * nonce value (provided by dpop-nonce header)
+     */
+    nonce?: string;
+    /**
+     * access token hash
+     */
+    ath?: string;
+}
+/**
+ * @group DPoP
+ */
+export interface DPoPHeaders {
+    alg: 'RS256';
+    typ: 'dpop+jwt';
+    jwk: JsonWebKey;
+}
+/**
+ * @group DPoP
+ */
+export interface DPoPProofParams {
+    request: Request;
+    keyPairId?: string;
+    keyPair?: CryptoKeyPair;
+    nonce?: string;
+    accessToken?: string;
+}

package/dist/types/oauth2/pkce.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+/**
+ * @group PKCE
+ */
+export type PKCE = PKCE.Challenge & PKCE.Verifier;
+declare function generatePKCE(method?: string): Promise<PKCE>;
+/**
+ * @group PKCE
+ */
+export declare namespace PKCE {
+    type Challenge = {
+        challenge: string;
+        method: string;
+    };
+    type Verifier = {
+        verifier: string;
+    };
+    const generate: typeof generatePKCE;
+}
+export {};