@monocloud/auth-core 0.1.4 → 0.1.5

package/dist/index.d.mts

@@ -1,25 +1,61 @@
-import { A as ResponseTypes, C as ParResponse, D as RefreshGrantOptions, E as RefetchUserInfoOptions, M as UserinfoResponse, O as RefreshSessionOptions, S as OnSessionCreating, T as PushedAuthorizationParams, _ as Jwks, a as Authenticators, b as MonoCloudSession, c as ClientAuthMethod, d as EndSessionParameters, f as Group, g as Jwk, h as JWSAlgorithm, i as AuthenticateOptions, j as Tokens, k as ResponseModes, l as CodeChallengeMethod, m as IssuerMetadata, n as Address, o as AuthorizationParams, p as IdTokenClaims, r as AuthState, s as CallbackParams, t as AccessToken, u as DisplayOptions, v as JwsHeaderParameters, w as Prompt, x as MonoCloudUser, y as MonoCloudClientOptions } from "./types-D3lVLgLQ.mjs";
+import { A as SecurityAlgorithms, C as Prompt, D as RefreshSessionOptions, E as RefreshGrantOptions, M as UserinfoResponse, O as ResponseModes, S as ParResponse, T as RefetchUserInfoOptions, _ as JwsHeaderParameters, a as Authenticators, b as MonoCloudUser, c as ClientAuthMethod, d as EndSessionParameters, f as Group, g as Jwks, h as Jwk, i as AuthenticateOptions, j as Tokens, k as ResponseTypes, l as CodeChallengeMethod, m as IssuerMetadata, n as Address, o as AuthorizationParams, p as IdTokenClaims, r as AuthState, s as CallbackParams, t as AccessToken, u as DisplayOptions, v as MonoCloudClientOptions, w as PushedAuthorizationParams, x as OnSessionCreating, y as MonoCloudSession } from "./types-hokU85Zr.mjs";
 
 //#region src/errors/monocloud-auth-base-error.d.ts
+/**
+ * Base class for all MonoCloud authentication errors.
+ *
+ * All errors thrown by the MonoCloud SDK extend this class, allowing applications to safely detect and handle MonoCloud-specific failures using `instanceof`.
+ *
+ * @category Error Classes
+ */
 declare class MonoCloudAuthBaseError extends Error {}
 //#endregion
 //#region src/errors/monocloud-op-error.d.ts
+/**
+ * OAuth error returned by the authorization server during an authentication or token request.
+ *
+ * These errors correspond to standard OAuth / OpenID Connect error responses such as `invalid_request`, `access_denied`, or `invalid_grant`.
+ *
+ * @category Error Classes
+ */
 declare class MonoCloudOPError extends MonoCloudAuthBaseError {
+  /** OAuth error code returned by the authorization server. */
   error: string;
+  /** Human-readable description of the error. */
   errorDescription?: string;
   constructor(error: string, errorDescription?: string);
 }
 //#endregion
 //#region src/errors/monocloud-http-error.d.ts
+/**
+ * Error thrown when a request to the MonoCloud authorization server fails.
+ *
+ * This error typically indicates a network failure, an unexpected HTTP response, or an unsuccessful response returned by the authorization server.
+ *
+ * @category Error Classes
+ */
 declare class MonoCloudHttpError extends MonoCloudAuthBaseError {}
 //#endregion
 //#region src/errors/monocloud-token-error.d.ts
+/**
+ * Error thrown when a token operation fails.
+ *
+ * @category Error Classes
+ */
 declare class MonoCloudTokenError extends MonoCloudAuthBaseError {}
 //#endregion
 //#region src/errors/monocloud-validation-error.d.ts
+/**
+ * Error thrown when validation fails.
+ *
+ * @category Error Classes
+ */
 declare class MonoCloudValidationError extends MonoCloudAuthBaseError {}
 //#endregion
 //#region src/monocloud-oidc-client.d.ts
+/**
+ * @category Classes
+ */
 declare class MonoCloudOidcClient {
   private readonly tenantDomain;
   private readonly clientId;
@@ -38,9 +74,9 @@ declare class MonoCloudOidcClient {
    *
    * If no values are provided for `responseType`, or `codeChallengeMethod`, they default to `code`, and `S256`, respectively.
    *
-   * @param params Authorization URL parameters
+   * @param params - Authorization URL parameters.
    *
-   * @returns Tenant's authorization url.
+   * @returns Tenant's authorization URL.
    *
    * @throws {@link MonoCloudHttpError} - Thrown if there is a network error during the request or
    * unexpected status code during the request or a serialization error while processing the response.
@@ -61,7 +97,7 @@ declare class MonoCloudOidcClient {
    */
   getMetadata(forceRefresh?: boolean): Promise<IssuerMetadata>;
   /**
-   * Fetches the JSON Web Keys used to sign the id token.
+   * Fetches the JSON Web Keys used to sign the ID token.
    * The JWKS is cached for 1 minute.
    *
    * @param forceRefresh - If `true`, bypasses the cache and fetches fresh set of JWKS from the server.
@@ -76,9 +112,9 @@ declare class MonoCloudOidcClient {
   /**
    * Performs a pushed authorization request.
    *
-   * @param params - Authorization Parameters
+   * @param params - Authorization Parameters.
    *
-   * @returns Response from Pushed Authorization Request (PAR) endpoint
+   * @returns Response from Pushed Authorization Request (PAR) endpoint.
    *
    * @throws {@link MonoCloudOPError} - When the request is invalid.
    *
@@ -106,13 +142,13 @@ declare class MonoCloudOidcClient {
    */
   userinfo(accessToken: string): Promise<UserinfoResponse>;
   /**
-   * Generates OpenID end session url for signing out.
+   * Generates OpenID end session URL for signing out.
    *
    * Note - The `state` is added only when `postLogoutRedirectUri` is present.
    *
-   * @param params - Parameters to build end session url
+   * @param params - Parameters to build end session URL.
    *
-   * @returns Tenant's end session url
+   * @returns Tenant's end session URL.
    *
    * @throws {@link MonoCloudHttpError} - Thrown if there is a network error during the request or
    * unexpected status code during the request or a serialization error while processing the response.
@@ -125,7 +161,7 @@ declare class MonoCloudOidcClient {
    * @param code - The authorization code received from the authorization server.
    * @param redirectUri - The redirect URI used in the initial authorization request.
    * @param codeVerifier - Code verifier for PKCE.
-   * @param resource - Space-separated list of resources the access token should be scoped to
+   * @param resource - Space-separated list of resources the access token should be scoped to.
    *
    * @returns Tokens obtained by exchanging an authorization code at the token endpoint.
    *
@@ -156,23 +192,23 @@ declare class MonoCloudOidcClient {
   /**
    * Generates a session with user and tokens by exchanging authorization code from callback params.
    *
-   * @param code - The authorization code received from the callback
-   * @param redirectUri - The redirect URI that was used in the authorization request
+   * @param code - The authorization code received from the callback.
+   * @param redirectUri - The redirect URI that was used in the authorization request.
    * @param requestedScopes - A space-separated list of scopes originally requested via the `/authorize` endpoint.
    * This is stored in the session to ensure the correct access token can be identified and refreshed during `refreshSession()`.
    * @param resource - A space-separated list of resource indicators originally requested via the `/authorize` endpoint.
    * Used alongside scopes to uniquely identify and refresh the specific access token associated with these resources.
-   * @param options - Options for authenticating a user with authorization code
+   * @param options - Options for authenticating a user with authorization code.
    *
    * @returns The user's session containing authentication tokens and user information.
    *
    * @throws {@link MonoCloudValidationError} - When the token scope does not contain the openid scope,
    * or if 'expires_in' or 'scope' is missing from the token response.
    *
-   * @throws {@link MonoCloudOPError} - When the OpenID Provider returns a standardized
+   * @throws {@link MonoCloudOPError} - When the OpenID Provider returns a standardized.
    * OAuth 2.0 error response.
    *
-   * @throws {@link MonoCloudTokenError} - If ID Token validation fails
+   * @throws {@link MonoCloudTokenError} - If ID Token validation fails.
    *
    * @throws {@link MonoCloudHttpError} - Thrown if there is a network error during the request or
    * unexpected status code during the request or a serialization error while processing the response.
@@ -183,11 +219,11 @@ declare class MonoCloudOidcClient {
    * Refetches user information for an existing session using the userinfo endpoint.
    * Updates the session's user object with the latest user information while preserving existing properties.
    *
-   * @param accessToken - Access token used to fetch the userinfo
-   * @param session - The current MonoCloudSession
-   * @param options - Userinfo refetch options
+   * @param accessToken - Access token used to fetch the userinfo.
+   * @param session - The current MonoCloudSession.
+   * @param options - Userinfo refetch options.
    *
-   * @returns Updated session with the latest userinfo
+   * @returns Updated session with the latest userinfo.
    *
    * @throws {@link MonoCloudValidationError} - When the token scope does not contain openid scope
    *
@@ -205,8 +241,8 @@ declare class MonoCloudOidcClient {
    * Refreshes an existing session using the refresh token.
    * This function requests new tokens using the refresh token and optionally updates user information.
    *
-   * @param session - The current MonoCloudSession containing the refresh token
-   * @param options - Session refresh options
+   * @param session - The current MonoCloudSession containing the refresh token.
+   * @param options - Session refresh options.
    *
    * @returns User's session containing refreshed authentication tokens and user information.
    *
@@ -226,10 +262,10 @@ declare class MonoCloudOidcClient {
   /**
    * Revokes an access token or refresh token, rendering it invalid for future use.
    *
-   * @param token - The token string to be revoked
-   * @param tokenType - Hint about the token type ('access_token' or 'refresh_token')
+   * @param token - The token string to be revoked.
+   * @param tokenType - Hint about the token type ('access_token' or 'refresh_token').
    *
-   * @returns If token revocation succeeded
+   * @returns If token revocation succeeded.
    *
    * @throws {@link MonoCloudValidationError} - If token is invalid or unsupported token type
    *
@@ -243,14 +279,14 @@ declare class MonoCloudOidcClient {
   /**
    * Validates an ID Token.
    *
-   * @param idToken - The ID Token JWT string to validate
-   * @param jwks - Array of JSON Web Keys (JWK) used to verify the token's signature
-   * @param clockSkew - Number of seconds to adjust the current time to account for clock differences
-   * @param clockTolerance - Additional time tolerance in seconds for time-based claim validation
-   * @param maxAge - maximum authentication age in seconds
-   * @param nonce - nonce value to validate against the token's nonce claim
+   * @param idToken - The ID Token JWT string to validate.
+   * @param jwks - Array of JSON Web Keys (JWK) used to verify the token's signature.
+   * @param clockSkew - Number of seconds to adjust the current time to account for clock differences.
+   * @param clockTolerance - Additional time tolerance in seconds for time-based claim validation.
+   * @param maxAge - Maximum authentication age in seconds.
+   * @param nonce - Nonce value to validate against the token's nonce claim.
    *
-   * @returns Validated ID Token claims
+   * @returns Validated ID Token claims.
    *
    * @throws {@link MonoCloudTokenError} - If ID Token validation fails
    *
@@ -258,11 +294,12 @@ declare class MonoCloudOidcClient {
   validateIdToken(idToken: string, jwks: Jwk[], clockSkew: number, clockTolerance: number, maxAge?: number, nonce?: string): Promise<IdTokenClaims>;
   /**
    * Decodes the payload of a JSON Web Token (JWT) and returns it as an object.
-   * **THIS METHOD DOES NOT VERIFY JWT TOKENS**.
    *
-   * @param jwt - JWT to decode
+   * >Note: THIS METHOD DOES NOT VERIFY JWT TOKENS.
+   *
+   * @param jwt - JWT to decode.
    *
-   * @returns Decoded payload
+   * @returns Decoded payload.
    *
    * @throws {@link MonoCloudTokenError} - If decoding fails
    *
@@ -270,5 +307,5 @@ declare class MonoCloudOidcClient {
   static decodeJwt(jwt: string): IdTokenClaims;
 }
 //#endregion
-export { type AccessToken, type Address, type AuthState, type AuthenticateOptions, type Authenticators, type AuthorizationParams, type CallbackParams, type ClientAuthMethod, type CodeChallengeMethod, type DisplayOptions, type EndSessionParameters, type Group, type IdTokenClaims, type IssuerMetadata, type JWSAlgorithm, type Jwk, type Jwks, type JwsHeaderParameters, MonoCloudAuthBaseError, type MonoCloudClientOptions, MonoCloudHttpError, MonoCloudOPError, MonoCloudOidcClient, type MonoCloudSession, MonoCloudTokenError, type MonoCloudUser, MonoCloudValidationError, type OnSessionCreating, type ParResponse, type Prompt, type PushedAuthorizationParams, type RefetchUserInfoOptions, type RefreshGrantOptions, type RefreshSessionOptions, type ResponseModes, type ResponseTypes, type Tokens, type UserinfoResponse };
+export { type AccessToken, type Address, type AuthState, type AuthenticateOptions, type Authenticators, type AuthorizationParams, type CallbackParams, type ClientAuthMethod, type CodeChallengeMethod, type DisplayOptions, type EndSessionParameters, type Group, type IdTokenClaims, type IssuerMetadata, type Jwk, type Jwks, type JwsHeaderParameters, MonoCloudAuthBaseError, type MonoCloudClientOptions, MonoCloudHttpError, MonoCloudOPError, MonoCloudOidcClient, type MonoCloudSession, MonoCloudTokenError, type MonoCloudUser, MonoCloudValidationError, type OnSessionCreating, type ParResponse, type Prompt, type PushedAuthorizationParams, type RefetchUserInfoOptions, type RefreshGrantOptions, type RefreshSessionOptions, type ResponseModes, type ResponseTypes, type SecurityAlgorithms, type Tokens, type UserinfoResponse };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,10 +1,24 @@
 import { decodeBase64Url, encodeBase64Url, findToken, getPublicSigKeyFromIssuerJwks, now, parseSpaceSeparated, randomBytes, stringToArrayBuffer } from "./utils/internal.mjs";
 
 //#region src/errors/monocloud-auth-base-error.ts
+/**
+* Base class for all MonoCloud authentication errors.
+*
+* All errors thrown by the MonoCloud SDK extend this class, allowing applications to safely detect and handle MonoCloud-specific failures using `instanceof`.
+*
+* @category Error Classes
+*/
 var MonoCloudAuthBaseError = class extends Error {};
 
 //#endregion
 //#region src/errors/monocloud-op-error.ts
+/**
+* OAuth error returned by the authorization server during an authentication or token request.
+*
+* These errors correspond to standard OAuth / OpenID Connect error responses such as `invalid_request`, `access_denied`, or `invalid_grant`.
+*
+* @category Error Classes
+*/
 var MonoCloudOPError = class extends MonoCloudAuthBaseError {
 	constructor(error, errorDescription) {
 		super(error);
@@ -15,14 +29,31 @@ var MonoCloudOPError = class extends MonoCloudAuthBaseError {
 
 //#endregion
 //#region src/errors/monocloud-http-error.ts
+/**
+* Error thrown when a request to the MonoCloud authorization server fails.
+*
+* This error typically indicates a network failure, an unexpected HTTP response, or an unsuccessful response returned by the authorization server.
+*
+* @category Error Classes
+*/
 var MonoCloudHttpError = class extends MonoCloudAuthBaseError {};
 
 //#endregion
 //#region src/errors/monocloud-token-error.ts
+/**
+* Error thrown when a token operation fails.
+*
+* @category Error Classes
+*/
 var MonoCloudTokenError = class extends MonoCloudAuthBaseError {};
 
 //#endregion
 //#region src/errors/monocloud-validation-error.ts
+/**
+* Error thrown when validation fails.
+*
+* @category Error Classes
+*/
 var MonoCloudValidationError = class extends MonoCloudAuthBaseError {};
 
 //#endregion
@@ -223,12 +254,15 @@ const deserializeJson = async (res) => {
 		);
 	}
 };
+/**
+* @category Classes
+*/
 var MonoCloudOidcClient = class MonoCloudOidcClient {
 	constructor(tenantDomain, clientId, options) {
 		this.jwksCacheExpiry = 0;
-		this.jwksCacheDuration = 60;
+		this.jwksCacheDuration = 300;
 		this.metadataCacheExpiry = 0;
-		this.metadataCacheDuration = 60;
+		this.metadataCacheDuration = 300;
 		tenantDomain ??= "";
 		/* v8 ignore next -- @preserve */
 		this.tenantDomain = `${!tenantDomain.startsWith("https://") ? "https://" : ""}${tenantDomain.endsWith("/") ? tenantDomain.slice(0, -1) : tenantDomain}`;
@@ -244,9 +278,9 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	*
 	* If no values are provided for `responseType`, or `codeChallengeMethod`, they default to `code`, and `S256`, respectively.
 	*
-	* @param params Authorization URL parameters
+	* @param params - Authorization URL parameters.
 	*
-	* @returns Tenant's authorization url.
+	* @returns Tenant's authorization URL.
 	*
 	* @throws {@link MonoCloudHttpError} - Thrown if there is a network error during the request or
 	* unexpected status code during the request or a serialization error while processing the response.
@@ -305,7 +339,7 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 		return metadata;
 	}
 	/**
-	* Fetches the JSON Web Keys used to sign the id token.
+	* Fetches the JSON Web Keys used to sign the ID token.
 	* The JWKS is cached for 1 minute.
 	*
 	* @param forceRefresh - If `true`, bypasses the cache and fetches fresh set of JWKS from the server.
@@ -331,9 +365,9 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	/**
 	* Performs a pushed authorization request.
 	*
-	* @param params - Authorization Parameters
+	* @param params - Authorization Parameters.
 	*
-	* @returns Response from Pushed Authorization Request (PAR) endpoint
+	* @returns Response from Pushed Authorization Request (PAR) endpoint.
 	*
 	* @throws {@link MonoCloudOPError} - When the request is invalid.
 	*
@@ -423,13 +457,13 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 		return await deserializeJson(response);
 	}
 	/**
-	* Generates OpenID end session url for signing out.
+	* Generates OpenID end session URL for signing out.
 	*
 	* Note - The `state` is added only when `postLogoutRedirectUri` is present.
 	*
-	* @param params - Parameters to build end session url
+	* @param params - Parameters to build end session URL.
 	*
-	* @returns Tenant's end session url
+	* @returns Tenant's end session URL.
 	*
 	* @throws {@link MonoCloudHttpError} - Thrown if there is a network error during the request or
 	* unexpected status code during the request or a serialization error while processing the response.
@@ -453,7 +487,7 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	* @param code - The authorization code received from the authorization server.
 	* @param redirectUri - The redirect URI used in the initial authorization request.
 	* @param codeVerifier - Code verifier for PKCE.
-	* @param resource - Space-separated list of resources the access token should be scoped to
+	* @param resource - Space-separated list of resources the access token should be scoped to.
 	*
 	* @returns Tokens obtained by exchanging an authorization code at the token endpoint.
 	*
@@ -536,23 +570,23 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	/**
 	* Generates a session with user and tokens by exchanging authorization code from callback params.
 	*
-	* @param code - The authorization code received from the callback
-	* @param redirectUri - The redirect URI that was used in the authorization request
+	* @param code - The authorization code received from the callback.
+	* @param redirectUri - The redirect URI that was used in the authorization request.
 	* @param requestedScopes - A space-separated list of scopes originally requested via the `/authorize` endpoint.
 	* This is stored in the session to ensure the correct access token can be identified and refreshed during `refreshSession()`.
 	* @param resource - A space-separated list of resource indicators originally requested via the `/authorize` endpoint.
 	* Used alongside scopes to uniquely identify and refresh the specific access token associated with these resources.
-	* @param options - Options for authenticating a user with authorization code
+	* @param options - Options for authenticating a user with authorization code.
 	*
 	* @returns The user's session containing authentication tokens and user information.
 	*
 	* @throws {@link MonoCloudValidationError} - When the token scope does not contain the openid scope,
 	* or if 'expires_in' or 'scope' is missing from the token response.
 	*
-	* @throws {@link MonoCloudOPError} - When the OpenID Provider returns a standardized
+	* @throws {@link MonoCloudOPError} - When the OpenID Provider returns a standardized.
 	* OAuth 2.0 error response.
 	*
-	* @throws {@link MonoCloudTokenError} - If ID Token validation fails
+	* @throws {@link MonoCloudTokenError} - If ID Token validation fails.
 	*
 	* @throws {@link MonoCloudHttpError} - Thrown if there is a network error during the request or
 	* unexpected status code during the request or a serialization error while processing the response.
@@ -596,11 +630,11 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	* Refetches user information for an existing session using the userinfo endpoint.
 	* Updates the session's user object with the latest user information while preserving existing properties.
 	*
-	* @param accessToken - Access token used to fetch the userinfo
-	* @param session - The current MonoCloudSession
-	* @param options - Userinfo refetch options
+	* @param accessToken - Access token used to fetch the userinfo.
+	* @param session - The current MonoCloudSession.
+	* @param options - Userinfo refetch options.
 	*
-	* @returns Updated session with the latest userinfo
+	* @returns Updated session with the latest userinfo.
 	*
 	* @throws {@link MonoCloudValidationError} - When the token scope does not contain openid scope
 	*
@@ -627,8 +661,8 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	* Refreshes an existing session using the refresh token.
 	* This function requests new tokens using the refresh token and optionally updates user information.
 	*
-	* @param session - The current MonoCloudSession containing the refresh token
-	* @param options - Session refresh options
+	* @param session - The current MonoCloudSession containing the refresh token.
+	* @param options - Session refresh options.
 	*
 	* @returns User's session containing refreshed authentication tokens and user information.
 	*
@@ -690,10 +724,10 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	/**
 	* Revokes an access token or refresh token, rendering it invalid for future use.
 	*
-	* @param token - The token string to be revoked
-	* @param tokenType - Hint about the token type ('access_token' or 'refresh_token')
+	* @param token - The token string to be revoked.
+	* @param tokenType - Hint about the token type ('access_token' or 'refresh_token').
 	*
-	* @returns If token revocation succeeded
+	* @returns If token revocation succeeded.
 	*
 	* @throws {@link MonoCloudValidationError} - If token is invalid or unsupported token type
 	*
@@ -727,14 +761,14 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	/**
 	* Validates an ID Token.
 	*
-	* @param idToken - The ID Token JWT string to validate
-	* @param jwks - Array of JSON Web Keys (JWK) used to verify the token's signature
-	* @param clockSkew - Number of seconds to adjust the current time to account for clock differences
-	* @param clockTolerance - Additional time tolerance in seconds for time-based claim validation
-	* @param maxAge - maximum authentication age in seconds
-	* @param nonce - nonce value to validate against the token's nonce claim
+	* @param idToken - The ID Token JWT string to validate.
+	* @param jwks - Array of JSON Web Keys (JWK) used to verify the token's signature.
+	* @param clockSkew - Number of seconds to adjust the current time to account for clock differences.
+	* @param clockTolerance - Additional time tolerance in seconds for time-based claim validation.
+	* @param maxAge - Maximum authentication age in seconds.
+	* @param nonce - Nonce value to validate against the token's nonce claim.
 	*
-	* @returns Validated ID Token claims
+	* @returns Validated ID Token claims.
 	*
 	* @throws {@link MonoCloudTokenError} - If ID Token validation fails
 	*
@@ -787,11 +821,12 @@ var MonoCloudOidcClient = class MonoCloudOidcClient {
 	}
 	/**
 	* Decodes the payload of a JSON Web Token (JWT) and returns it as an object.
-	* **THIS METHOD DOES NOT VERIFY JWT TOKENS**.
 	*
-	* @param jwt - JWT to decode
+	* >Note: THIS METHOD DOES NOT VERIFY JWT TOKENS.
+	*
+	* @param jwt - JWT to decode.
 	*
-	* @returns Decoded payload
+	* @returns Decoded payload.
 	*
 	* @throws {@link MonoCloudTokenError} - If decoding fails
 	*