@okta/auth-foundation 0.6.0

package/dist/types/oauth2/requests/UserInfo.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+import type { JsonPrimitive } from '../../types/index.ts';
+import { Token } from '../../Token.ts';
+import { OAuth2Request } from '../../http/index.ts';
+/**
+ * @group OAuth2Request
+ */
+export interface UserInfo {
+    [key: string]: JsonPrimitive;
+}
+/**
+ * @internal
+ */
+export declare namespace UserInfo {
+    /**
+     * @internal
+     */
+    interface RequestParams extends OAuth2Request.RequestParams {
+        token: Token;
+    }
+    /**
+     * @internal
+     */
+    class Request extends OAuth2Request {
+        token: Token;
+        constructor(params: RequestParams);
+        get url(): string;
+    }
+}

package/dist/types/platform/Platform.d.ts

@@ -0,0 +1,121 @@
+import { AuthSdkError } from '../errors/AuthSdkError.ts';
+import type { DPoPSigningAuthority } from '../oauth2/dpop/index.ts';
+import type { TimeCoordinator } from '../utils/TimeCoordinator.ts';
+import type { DPoPNonceCache } from '../oauth2/dpop/index.ts';
+/**
+ * The required Platform dependencies
+ */
+export interface PlatformDependencies {
+    TimeCoordinator: TimeCoordinator;
+    DPoPSigningAuthority: DPoPSigningAuthority;
+    DPoPNonceCache: DPoPNonceCache;
+}
+export declare class PlatformRegistryError extends AuthSdkError {
+}
+/**
+ * A singleton registry of globally-available singleton dependencies which can
+ * provide platform-specific default implementations and enable overriding as needed
+ *
+ * For example, the {@link TimeCoordinator} should be globally available to be a
+ * centralized entity to perform all time calculations. Registering the {@link TimeCoordinator}
+ * as a {@link Platform} dependency enables consumers to access the {@link TimeCoordinator} via
+ *
+ * @example
+ * ```
+ * import { Platform } from '@okta/auth-foundation';
+ * const currentTime = Platform.TimeCoordinator.now();
+ * ```
+ *
+ * To enable tree-shaking and prevent including default implementations (bundle bloat) which
+ * will be instantaneously overwritten, default implementations can be selectively included.
+ *
+ * @remarks
+ * Use `import * from '@okta/auth-foundation'` for standard usage, including all default platform
+ * dependency implementations.
+ *
+ * Use `import * from '@okta/auth-foundation/core'` for deeper customizations of platform dependencies,
+ * this does not include any default implementations. {@link PlatformRegistryError} will be thrown if
+ * a dependency is used before an implementation is provided
+ */
+export declare class PlatformRegistry implements PlatformDependencies {
+    #private;
+    /**
+     * Override default platform dependencies globally
+     *
+     * This pattern will include the default implementations within the resulting bundle,
+     * causing essentially dead code to be bundled. This will likely be acceptable for
+     * most standard use cases. For scenarios where deeper customizations are required
+     * see {@link PlatformRegistry.registerDefaultsLoader}
+     *
+     * @remarks
+     * Call this once at application startup before using any SDK components.
+     * Partial updates are supported - only override what you need.
+     */
+    configure(dependencies: Partial<PlatformDependencies>): void;
+    /**
+     * Registers a loader to provide the platform dependency default implementations
+     *
+     * When a deeper customization of platform dependencies is required, this method can
+     * be used to provide custom implementations of platform dependencies without including
+     * the provided default implementations in any resulting bundle.
+     *
+     * This pattern is not recommended for standard SDK usage and should only be used if deep
+     * customization is required (like providing support to an otherwise unsupported runtime environment)
+     *
+     * For standard usage, see {@link PlatformRegistry.configure}
+     *
+     * @remarks
+     * Call this once at application startup before using any SDK components.
+     *
+     * @example
+     * ```
+     * // src/auth.ts
+     * import { Platform } from '@okta/auth-foundation/core';    // ensure "/core" is imported specifically
+     *
+     * Platform.registerDefaultsLoader(() => ({
+     *   TimeCoordinator: MyCustomTimeCoordinator
+     *   // define other dependencies
+     * }));
+     *
+     * // ensure this module is loaded before any other '@okta/*' dependencies
+     * ```
+     */
+    registerDefaultsLoader(loader: () => PlatformDependencies): void;
+    /**
+     * @internal
+     * Resets loaded dependencies. For testing purposes mostly.
+     */
+    reset(): void;
+    /**
+     * @internal
+     * Get all current dependencies (configured or defaults)
+     */
+    protected get resolved(): PlatformDependencies;
+    /**
+     * @internal
+     * Override in subclasses to provide platform-specific defaults
+     */
+    protected getDefaults(): PlatformDependencies;
+    /**
+     * Get the current TimeCoordinator instance
+     *
+     * @remarks
+     * Returns configured override or factory default
+     */
+    get TimeCoordinator(): TimeCoordinator;
+    /**
+     * Get the current DPoPSigningAuthority instance
+     *
+     * @remarks
+     * Returns configured override or factory default
+     */
+    get DPoPSigningAuthority(): DPoPSigningAuthority;
+    /**
+     * Get the current DPoPNonceCache instance
+     *
+     * @remarks
+     * Returns configured override or factory default
+     */
+    get DPoPNonceCache(): DPoPNonceCache;
+}
+export declare const Platform: PlatformRegistry;

package/dist/types/platform/defaults.d.ts

@@ -0,0 +1,10 @@
+import type { PlatformDependencies } from './Platform.ts';
+import { DefaultTimeCoordinator } from '../utils/TimeCoordinator.ts';
+declare const TimeCoordinator: DefaultTimeCoordinator;
+export { TimeCoordinator };
+/**
+ * @internal
+ * *DO NOT IMPORT THIS FILE* in any location other than `src/index.ts` to avoid including default
+ * platform implementations in bundle output
+ */
+export declare const PlatformDefaults: PlatformDependencies;

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

@@ -0,0 +1,6 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+export * from './lib.ts';
+export * from './oauth.ts';

package/dist/types/types/lib.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @module
+ * @mergeModuleWith Core
+ */
+/** @internal */
+export type Constructor<T = Record<string, unknown>> = new (...args: any[]) => T;
+/** @internal */
+export type AnyFunction<T = any> = (...args: any[]) => T;
+/** @internal */
+export type Mixin<T extends AnyFunction> = InstanceType<ReturnType<T>>;
+/** @internal */
+export type Nullable<T> = {
+    [K in keyof T]: T[K] | null;
+};
+/** @internal */
+export type Neverable<T> = {
+    [K in keyof T]: T[K] | never;
+};
+/** @internal */
+export type Nullify<T> = {
+    [K in keyof T]: null;
+};
+/** @internal */
+export type Neverify<T> = {
+    [K in keyof T]: never;
+};
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonRecord = {
+    [key in string]?: Json | JsonPrimitive;
+};
+export type JsonArray = (Json | JsonPrimitive)[];
+export type Json = JsonRecord | JsonArray;
+/** @internal */
+export type SubSet<T extends Record<string, any>, K extends keyof T, R extends T[K]> = Omit<T, K> & {
+    [P in K]: R;
+};
+/**
+ * @internal
+ * Discrimintated Union
+ *
+ * Required<Pick<T, K>> – The property K is required.
+ * Partial<Record<Exclude<Keys, K>, undefined>> – All other keys in the union are explicitly set undefined (or omitted).
+ * Omit<T, Keys> – All extra properties outside of Keys are freely allowed.
+ * The union [K in Keys] ... [Keys] generates one type for each allowed key.
+ */
+export type DiscrimUnion<T, Keys extends keyof T = keyof T> = {
+    [K in Keys]: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, undefined>> & Omit<T, Keys>;
+}[Keys];
+/**
+ * A duration of time, in seconds
+ */
+export type TimeInterval = number;
+/**
+ * Number of seconds elapsed since midnight, Jan 1, 1970 UTC
+ */
+export type EpochTimestamp = number;
+export type Seconds = number;
+/**
+ * An entity which can be respresented as a primitive (like string)
+ */
+export interface RawRepresentable<T = string> {
+    get rawValue(): T;
+}
+/**
+ * Defines utility methods to determine if an entity has expired
+ * or when it will expire in the future
+ */
+export interface Expires {
+    get expiresAt(): Date | undefined;
+    get expiresIn(): TimeInterval;
+    get isExpired(): boolean;
+    get isValid(): boolean;
+    get issuedAt(): Date | undefined;
+}
+/**
+ * An entity which can be converted to a JSON representation, usually used for serialization
+ */
+export interface JSONSerializable {
+    toJSON(): JsonRecord;
+}
+export type RequestAuthorizerInit = RequestInit & {
+    dpopNonce?: string;
+};
+/**
+ * An entity which can sign an outgoing {@link !Request}, minimally adding a `Authorization` header
+ */
+export interface RequestAuthorizer {
+    authorize(input: string | URL | Request, init?: RequestAuthorizerInit): Promise<Request>;
+}
+/**
+ * An entity which opens a communication channel (and therefore will need to close the channel)
+ */
+export interface Broadcaster {
+    close(): void;
+}
+/**
+ * A communication channel which follows a similar API pattern to {@link !BroadcastChannel}
+ */
+export interface BroadcastChannelLike<M extends JsonRecord, E = object> {
+    name: string;
+    onmessage: ((message: {
+        data: M & E;
+    }, reply?: (data: M) => any) => any) | null;
+    postMessage(message: M): void;
+    close(): void;
+}

package/dist/types/types/oauth.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @module
+ * @mergeModuleWith OAuth2
+ */
+import type { JWK, JWKS } from '../jwt/index.ts';
+import type { ConfigurationParams } from '../oauth2/configuration.ts';
+import type { OpenIdConfiguration } from './openid.ts';
+/**
+ * JSON format of an error response from an OAuth2 server
+ *
+ * @group Types
+ */
+export interface OAuth2ErrorResponse {
+    readonly error: string;
+    readonly errorDescription?: string;
+    readonly error_description?: string;
+    readonly errorUri?: string;
+    readonly error_uri?: string;
+}
+/**
+ * Predicate for {@link OAuth2ErrorResponse}
+ *
+ * @group Types
+ */
+export declare function isOAuth2ErrorResponse(input: unknown): input is OAuth2ErrorResponse;
+export { OpenIdConfiguration };
+/**
+ * Predicate for {@link OpenIdConfiguration}
+ *
+ * @group Types
+ */
+export declare function isOpenIdConfiguration(input: unknown): input is OpenIdConfiguration;
+/**
+ * Predicate for {@link Core.JWK | JWK}
+ *
+ * @group Types
+ */
+export declare function isJWK(input: unknown): input is JWK;
+/**
+ * Predicate for {@link Core.JWKS | JWKS}
+ *
+ * @group Types
+ */
+export declare function isJWKS(input: unknown): input is JWKS;
+export type { ConfigurationParams };
+/**
+ * Parameters needed to define an OAuth2 flow
+ *
+ * @group Types
+ */
+export type OAuth2Params = {
+    issuer: string | URL;
+    clientId: string;
+    scopes: string | string[];
+    dpop?: boolean;
+};
+/**
+ * Possible values of `grant_type` for a `/token` request
+ *
+ * @group Types
+ */
+export type GrantType = 'authorization_code' | 'refresh_token';
+/**
+ * Possible values of `token_type` from a `/token` response
+ *
+ * @group Types
+ */
+export type TokenType = 'Bearer' | 'DPoP';
+/**
+ * Possible values of {@link OAuth2.Configuration.authentication} property.
+ * Determines how the {@link OAuth2Client} will sign OAuth2 requests
+ *
+ * @group Types
+ */
+export type ClientAuthentication = 'none';
+export interface APIClientConfiguration {
+    readonly baseURL: URL;
+}
+/**
+ * Possible types of `acr_values` for OAuth2 requests
+ *
+ * @group Types
+ */
+export type AcrValues = OktaAcrValues | string | string[];
+/**
+ * Possible `acr_values` of Okta Authorization Servers
+ *
+ * @group Types
+ *
+ * @see
+ * https://developer.okta.com/docs/api/openapi/okta-oauth/oauth/tag/OrgAS/#tag/OrgAS/operation/authorize!in=query&path=acr_values&t=request
+ */
+export type OktaAcrValues = 
+/**
+ * Phishing-Resistant
+ */
+'phr' | 
+/**
+ * Phishing-Resistant Hardware-Protected
+ */
+'phrh' | 
+/**
+ * Any one factor
+ */
+'urn:okta:loa:1fa:any' | 
+/**
+ * Password only
+ */
+'urn:okta:loa:1fa:pwd' | 
+/**
+ * Any two factors
+ */
+'urn:okta:loa:2fa:any' | 
+/**
+ * Any two factors, if possible. Any two factors are presented only if the user is enrolled, otherwise any one factor is presented.
+ */
+'urn:okta:loa:2fa:any:ifpossible';