@okta/auth-foundation 0.6.0 → 0.9.0

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

@@ -4,53 +4,127 @@
  */
 import type { ClientAuthentication, APIClientConfiguration, JSONSerializable, JsonRecord, OAuth2Params, DiscrimUnion } from '../types/index.ts';
 import { APIClient } from '../http/index.ts';
+/** @internal */
 export type OAuth2ClientConfigurations = DiscrimUnion<OAuth2Params & {
     baseURL: URL | string;
     discoveryURL?: URL | string;
 }, 'issuer' | 'baseURL'>;
+/**
+ * Configuration options for {@link OAuth2Client}
+ * @group OAuth2Client
+ */
 export type OAuth2ClientOptions = {
     authentication?: ClientAuthentication;
     allowHTTP?: boolean;
     syncClockWithAuthorizationServer?: boolean;
 };
 /**
- * @group Configuration
- * @useDeclaredType
+ * Options to provide to {@link Configuration} at instantiation
+ * @group OAuth2Client
+ * @interface
  */
 export type ConfigurationParams = OAuth2ClientConfigurations & OAuth2ClientOptions;
 /**
- * @group Configuration
+ * Options to customize the behavior of a {@link OAuth2Client} instance
+ * @group OAuth2Client
+ *
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc8414 | RFC 8414: OAuth 2.0 Authorization Server Metadata}
  */
 export declare class Configuration extends APIClient.Configuration implements APIClientConfiguration, JSONSerializable {
+    /**
+     * URL of the authorization server.
+     */
     readonly issuer: URL;
+    /**
+     * URL of the authorization server's Metadata document
+     * @defaultValue
+     * ```ts
+     * this.issuer + '/.well-known/openid-configuration'
+     * ```
+     *
+     * @see
+     * {@link https://datatracker.ietf.org/doc/html/rfc8414#section-3 | RFC 8414: Obtaining Authorization Server Metadata}
+     */
     readonly discoveryURL: URL;
+    /**
+     * Authorization server client identifier.
+     *
+     * @remarks
+     * The client identifier will be generated by the authorization server during client registration.
+     *
+     * @see
+     * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-2.2 | RFC 6749: Client Identifier}
+     */
     readonly clientId: string;
+    /**
+     * Default `scope` value to be provided in authenication and token requests to the authorization server.
+     *
+     * @see
+     * * {@link https://developer.okta.com/docs/api/openapi/okta-oauth/oauth/orgas/authorize#orgas/authorize/t=request&in=query&path=scope | Okta Auth Server}
+     * * {@link https://developer.okta.com/docs/api/oauth2 | Okta Scopes}
+     * * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-3.3 | RFC 6749: Access Token Scope}
+     */
     scopes: string;
+    /**
+     * Enum for possible authentication stratgies for authorization server requests. Defaults to `none` (aka public client)
+     *
+     * @see
+     * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-2.3 | RFC 6749: Client Authentication}
+     */
     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
+     * 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.
+     * 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-expose-headers` for this feature to work properly
+     * when requests the authorization server and application are hosted on different origins.
      *
      * Reference: https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header
      */
     syncClockWithAuthorizationServer: boolean;
+    /**
+     * @defaultValue
+     * ```ts
+     * {
+     *   allowHTTP: false,
+     *   syncClockWithAuthorizationServer: true,
+     *   authentication: 'none',
+     *
+     *   // inherited from APIClient
+     *   dpop: false
+     * }
+     * ```
+     */
     static DefaultOptions: Required<OAuth2ClientOptions> & typeof APIClient.Configuration.DefaultOptions;
     constructor(params: ConfigurationParams);
     /**
      * Alias to {@link issuer} for backwards compatibility
      */
     get baseURL(): URL;
+    /**
+     * Determines whether a parameter collection matches the configuration of this client
+     */
     matches(params: OAuth2Params): boolean;
+    /**
+     * Returns configurations values of the client, omitting OAuth2 parameters
+     *
+     * @see {@link Configuration.toJSON}
+     */
+    getOptions(): OAuth2ClientOptions;
+    /**
+     * Returns JSON representation of the client's configuration
+     *
+     * @see {@link Configuration.getOptions}
+     */
     toJSON(): JsonRecord;
 }

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

@@ -8,22 +8,27 @@ import { DPoPNonceCache } from './nonceCache.ts';
 export { DPoPNonceCache, DPoPStorage };
 export type { DPoPHeaders, DPoPClaims, DPoPProofParams };
 /**
+ * A Platform-level singleton for performing `DPoP` operations. The {@link DPoPSigningAuthority} is
+ * reasonable for mangaging `DPoP` key pairs and generate `DPoP` proofs for outgoing {@link !Request}s
  * @group DPoP
- *
  */
 export interface DPoPSigningAuthority {
     createDPoPKeyPair: () => Promise<string>;
     deleteDPoPKeyPair: (keyPairId: string) => Promise<void>;
     clearDPoPKeyPairs: () => Promise<void>;
+    /**
+     * Generates a `DPoP` proof for the provided {@link !Request} and writes the `dpop` request header.
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4 | RFC 9449 - DPoP Proof JWTs}
+     */
     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
- *
+ * @group DPoP
+ * @internal
  */
 export declare class DPoPSigningAuthorityImpl implements DPoPSigningAuthority {
     private readonly store;
@@ -64,7 +69,7 @@ export declare class DPoPSigningAuthorityImpl implements DPoPSigningAuthority {
      * 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
+     * @returns The provided {@link !Request} with an append `dpop` header
      */
     sign(request: Request, params: Omit<DPoPProofParams, 'request'>): Promise<Request>;
 }

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

@@ -3,7 +3,25 @@
  * @mergeModuleWith OAuth2
  */
 /**
+ * > The intent is that clients need to keep only one nonce value and
+ * servers need to keep a window of recent nonces.
+ *
+ * via https://datatracker.ietf.org/doc/html/rfc9449#section-8
+ *
+ * Authorization servers may provide the same `dpop-nonce` value for a window of time.
+ * The `DPoPNonceCache` serves as a cache of these nonce values to avoid unnecessary
+ * failures. {@link OAuth2.DPoPSigningAuthority.sign | DPoPSigningAuthority.sign} will
+ * use nonce values from the cache when available.
+ *
+ * @remarks
+ * A `DPoPNonceCache` instance will be create for each {@link Networking.APIClient | APIClient} instance,
+ * but `DPoPNonceCache` implementations will often share a common store
+ *
  * @group DPoP
+ * @see
+ * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-11.3 | RFC 9449 - DPoP Nonce Downgrade}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-8 | RFC 9449 - Authorization Server-Provided Nonce}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-9 | RFC 9449 - Resource Server-Provided Nonce}
  */
 export interface DPoPNonceCache {
     getNonce(key: string): Promise<string | undefined>;

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

@@ -3,6 +3,7 @@
  * @mergeModuleWith OAuth2
  */
 /**
+ * A simple storage interface for `DPoP` key pairs
  * @group DPoP
  */
 export interface DPoPStorage {

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

@@ -4,7 +4,10 @@
  */
 import type { JsonRecord } from '../../types/index.ts';
 /**
+ * `JWT` claims associated with a `DPoP` proof
  * @group DPoP
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4.2-3 | RFC 9499 - DPoP Proof Claims}
  */
 export interface DPoPClaims extends JsonRecord {
     /**
@@ -33,7 +36,10 @@ export interface DPoPClaims extends JsonRecord {
     ath?: string;
 }
 /**
+ * `JWT` header parameters for a `DPoP` proof
  * @group DPoP
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4.2-1 | RFC 9499 - DPoP Proof Header}
  */
 export interface DPoPHeaders {
     alg: 'RS256';
@@ -41,6 +47,7 @@ export interface DPoPHeaders {
     jwk: JsonWebKey;
 }
 /**
+ * Parameters required to generate a `DPoP` proof
  * @group DPoP
  */
 export interface DPoPProofParams {

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

@@ -3,21 +3,40 @@
  * @mergeModuleWith OAuth2
  */
 /**
+ * Defines the properties returned by {@link PKCE.generate}
  * @group PKCE
  */
 export type PKCE = PKCE.Challenge & PKCE.Verifier;
+/**
+ * Generates a `PKCE` challenge and verifier.
+ *
+ * @remarks
+ * Currently `S256` is the only hashing algorithm available. Per spec, `plain` (unhashed) challenges
+ * are valid for client which are unable to perform `S256`, but this isn't implemented within this client
+ */
 declare function generatePKCE(method?: string): Promise<PKCE>;
 /**
  * @group PKCE
  */
 export declare namespace PKCE {
+    /**
+     * Represents PKCE `code_challenge`
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 | RFC 7636 - Client Creates the Code Challenge}
+     */
     type Challenge = {
         challenge: string;
         method: string;
     };
+    /**
+     * Represents PKCE `code_verifier`
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.1 | RFC 7636 - Client Creates the Code Verifier}
+     */
     type Verifier = {
         verifier: string;
     };
+    /** @reexport */
     const generate: typeof generatePKCE;
 }
 export {};

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

@@ -6,7 +6,8 @@ import type { JsonPrimitive } from '../../types/index.ts';
 import { Token } from '../../Token.ts';
 import { OAuth2Request } from '../../http/index.ts';
 /**
- * @group OAuth2Request
+ * @inline
+ * @internal
  */
 export interface UserInfo {
     [key: string]: JsonPrimitive;

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

@@ -1,18 +1,65 @@
+/**
+ * `Platform` is a registry of platform-wide **singleton** dependencies (time, DPoP key signing, DPoP
+ * nonce storage, etc.) that are shared across the whole SDK ecosystem, rather than constructed
+ * per-instance by whatever class happens to need them.
+ *
+ * Some of these dependencies vary by JS environment - `DPoPSigningAuthority` and `DPoPNonceCache`
+ * need genuinely different implementations in a browser vs. React Native, since they lean on
+ * environment-specific crypto/storage APIs. Others, like `TimeCoordinator`, aren't tied to any
+ * particular runtime at all; they're registered here simply because the SDK needs exactly *one*
+ * shared instance (e.g. for clock-skew coordination) rather than one per consumer. Either way,
+ * funneling both kinds of dependency through the same `Platform` registry gives every part of the
+ * SDK one consistent, easy pattern for overriding behavior, instead of each dependency inventing
+ * its own configuration mechanism.
+ *
+ * Most consumers never need to touch this module directly. Platform packages like [@okta/spa-platform](/api/spa-platform/)
+ * or [@okta/react-native-platform](/api/spa-platform/) already register the right implementations for their environment,
+ * and importing from `@okta/auth-foundation` pulls in working defaults out of the box.
+ *
+ * Reach for `Platform` yourself only if you need to override a specific dependency (for example,
+ * providing a custom `TimeCoordinator` in tests) via {@link PlatformRegistry.configure}, or you're
+ * adding support for a runtime this SDK doesn't already target, via
+ * {@link PlatformRegistry.registerDefaultsLoader}.
+ *
+ * @remarks
+ * By convention, every `@okta/*` SDK package exports a `/core` entry point alongside its default
+ * entry point. The default entry point (e.g. `@okta/auth-foundation`) calls
+ * {@link PlatformRegistry.registerDefaultsLoader} on your behalf with that platform's default
+ * implementations already wired up - simple to use, but it means those defaults are always
+ * included in your bundle, even if you go on to override them.
+ *
+ * The `/core` entry point (e.g. `@okta/auth-foundation/core`) is identical, *except* it skips that
+ * `registerDefaultsLoader` call. This gives you a way to fully replace a `Platform` dependency
+ * without ever pulling its default implementation into your bundle - useful if the default is
+ * heavy, or simply not needed for your use case. If you go this route, you must call
+ * {@link PlatformRegistry.registerDefaultsLoader} yourself before any other SDK code runs, or
+ * {@link PlatformRegistryError} will be thrown the first time a dependency is accessed.
+ * @module Platform
+ */
 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
+ * The required {@link Platform} dependencies
  */
 export interface PlatformDependencies {
+    /** {@inheritDoc Core.TimeCoordinator} */
     TimeCoordinator: TimeCoordinator;
+    /** {@inheritDoc OAuth2.DPoPSigningAuthority} */
     DPoPSigningAuthority: DPoPSigningAuthority;
+    /** {@inheritDoc OAuth2.DPoPNonceCache} */
     DPoPNonceCache: DPoPNonceCache;
 }
+/**
+ * Thrown when the {@link Platform} registry cannot resolve a dependency.
+ */
 export declare class PlatformRegistryError extends AuthSdkError {
 }
 /**
+ * > [!Warning]
+ * > **DO NOT** construct an instance of this `PlatformRegistry`. Use `import { Platform } from '@okta/auth-foundation'`.
+ *
  * A singleton registry of globally-available singleton dependencies which can
  * provide platform-specific default implementations and enable overriding as needed
  *
@@ -21,7 +68,7 @@ export declare class PlatformRegistryError extends AuthSdkError {
  * as a {@link Platform} dependency enables consumers to access the {@link TimeCoordinator} via
  *
  * @example
- * ```
+ * ```ts
  * import { Platform } from '@okta/auth-foundation';
  * const currentTime = Platform.TimeCoordinator.now();
  * ```
@@ -68,7 +115,7 @@ export declare class PlatformRegistry implements PlatformDependencies {
      * Call this once at application startup before using any SDK components.
      *
      * @example
-     * ```
+     * ```ts
      * // src/auth.ts
      * import { Platform } from '@okta/auth-foundation/core';    // ensure "/core" is imported specifically
      *
@@ -118,4 +165,5 @@ export declare class PlatformRegistry implements PlatformDependencies {
      */
     get DPoPNonceCache(): DPoPNonceCache;
 }
+/** @internal */
 export declare const Platform: PlatformRegistry;

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

@@ -1,5 +1,6 @@
 import type { PlatformDependencies } from './Platform.ts';
 import { DefaultTimeCoordinator } from '../utils/TimeCoordinator.ts';
+/** @internal */
 declare const TimeCoordinator: DefaultTimeCoordinator;
 export { TimeCoordinator };
 /**

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

@@ -24,12 +24,20 @@ export type Nullify<T> = {
 export type Neverify<T> = {
     [K in keyof T]: never;
 };
+/**
+ * Primitive types representable in `JSON` objects.
+ */
 export type JsonPrimitive = string | number | boolean | null;
+/**
+ * Type respresentation of a `JSON` object.
+ */
 export type JsonRecord = {
     [key in string]?: Json | JsonPrimitive;
 };
-export type JsonArray = (Json | JsonPrimitive)[];
-export type Json = JsonRecord | JsonArray;
+/**
+ * Type respresentation of a `JSON` object or array.
+ */
+export type Json = JsonRecord | (Json | JsonPrimitive)[];
 /** @internal */
 export type SubSet<T extends Record<string, any>, K extends keyof T, R extends T[K]> = Omit<T, K> & {
     [P in K]: R;
@@ -54,6 +62,9 @@ export type TimeInterval = number;
  * Number of seconds elapsed since midnight, Jan 1, 1970 UTC
  */
 export type EpochTimestamp = number;
+/**
+ * Alias for `number`, but more descriptive
+ */
 export type Seconds = number;
 /**
  * An entity which can be respresented as a primitive (like string)
@@ -78,6 +89,9 @@ export interface Expires {
 export interface JSONSerializable {
     toJSON(): JsonRecord;
 }
+/**
+ * @inline
+ */
 export type RequestAuthorizerInit = RequestInit & {
     dpopNonce?: string;
 };

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

@@ -6,7 +6,7 @@ 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
+ * JSON format of an error response returned by authorization server
  *
  * @group Types
  */
@@ -25,19 +25,19 @@ export interface OAuth2ErrorResponse {
 export declare function isOAuth2ErrorResponse(input: unknown): input is OAuth2ErrorResponse;
 export { OpenIdConfiguration };
 /**
- * Predicate for {@link OpenIdConfiguration}
+ * Type predicate for {@link OpenIdConfiguration}
  *
  * @group Types
  */
 export declare function isOpenIdConfiguration(input: unknown): input is OpenIdConfiguration;
 /**
- * Predicate for {@link Core.JWK | JWK}
+ * Type predicate for {@link Core.JWK | JWK}
  *
  * @group Types
  */
 export declare function isJWK(input: unknown): input is JWK;
 /**
- * Predicate for {@link Core.JWKS | JWKS}
+ * Type predicate for {@link Core.JWKS | JWKS}
  *
  * @group Types
  */
@@ -83,7 +83,7 @@ export interface APIClientConfiguration {
  */
 export type AcrValues = OktaAcrValues | string | string[];
 /**
- * Possible `acr_values` of Okta Authorization Servers
+ * Possible `acr_values` of Okta authorization servers
  *
  * @group Types
  *