@monocloud/auth-core 0.1.7 → 0.1.8

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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-DmlJMcTH.mjs";
+import { A as PushedAuthorizationParams, B as ValidateJwtAccessTokenOptions, C as MonoCloudOidcBackendClientOptions, D as OnSessionCreating, E as MonoCloudUser, F as ResponseTypes, I as SecurityAlgorithms, L as TokenValidationOptionsBase, M as RefreshGrantOptions, N as RefreshSessionOptions, O as ParResponse, P as ResponseModes, R as Tokens, S as MonoCloudClientOptionsBase, T as MonoCloudSession, _ as IssuerMetadata, a as AuthenticateOptions, b as JwsHeaderParameters, c as CallbackParams, d as DisplayOptions, f as EndSessionParameters, g as IsUserInGroupOptions, h as IntrospectOptions, i as AuthState, j as RefetchUserInfoOptions, k as Prompt, l as ClientAuthMethod, m as IdTokenClaims, n as AccessTokenClaims, o as Authenticators, p as Group, r as Address, s as AuthorizationParams, t as AccessToken, u as CodeChallengeMethod, v as Jwk, w as MonoCloudOidcClientOptions, x as JwtClaims, y as Jwks, z as UserinfoResponse } from "./types-txr_P9Iq.mjs";
 
 //#region src/errors/monocloud-auth-base-error.d.ts
 /**
@@ -52,40 +52,55 @@ declare class MonoCloudTokenError extends MonoCloudAuthBaseError {}
  */
 declare class MonoCloudValidationError extends MonoCloudAuthBaseError {}
 //#endregion
-//#region src/monocloud-oidc-client.d.ts
+//#region src/monocloud-oidc-client-base.d.ts
 /**
  * @category Classes
  */
-declare class MonoCloudOidcClient {
-  private readonly tenantDomain;
-  private readonly clientId;
-  private readonly clientSecret?;
-  private readonly authMethod;
-  private readonly idTokenSigningAlgorithm;
-  private jwks?;
-  private jwksCacheExpiry;
-  private jwksCacheDuration;
-  private metadata?;
-  private metadataCacheExpiry;
-  private metadataCacheDuration;
-  constructor(tenantDomain: string, clientId: string, options?: MonoCloudClientOptions);
+declare class MonoCloudOidcClientBase {
   /**
-   * Generates an authorization URL with specified parameters.
-   *
-   * If no values are provided for `responseType`, or `codeChallengeMethod`, they default to `code`, and `S256`, respectively.
-   *
-   * @param params - Authorization URL parameters.
-   *
-   * @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.
+   * The normalized tenant domain URL used as the base for discovery endpoints.
+   */
+  protected readonly tenantDomain: string;
+  /**
+   * Cached JSON Web Key Set retrieved from the issuer's JWKS endpoint.
+   */
+  protected jwks?: Jwks;
+  /**
+   * Timestamp (in seconds) when the cached JWKS expires.
+   */
+  protected jwksCacheExpiry: number;
+  /**
+   * Duration (in seconds) for which the JWKS is cached. Defaults to 300 (5 minutes).
+   */
+  protected jwksCacheDuration: number;
+  /**
+   * Cached issuer metadata retrieved from the OpenID Connect discovery endpoint.
+   */
+  protected metadata?: IssuerMetadata;
+  /**
+   * Timestamp (in seconds) when the cached metadata expires.
+   */
+  protected metadataCacheExpiry: number;
+  /**
+   * Duration (in seconds) for which the metadata is cached. Defaults to 300 (5 minutes).
+   */
+  protected metadataCacheDuration: number;
+  /**
+   * Custom fetch implementation used for making HTTP requests. Falls back to the global `fetch` if not provided.
+   */
+  protected fetcher?: typeof fetch;
+  /**
+   * Creates a new instance of MonoCloudOidcClientBase.
    *
+   * @param tenantDomain - The tenant domain URL.
+   * @param metadataCacheDuration - Duration (in seconds) to cache OpenID Connect discovery metadata. Defaults to 300 (5 minutes).
+   * @param jwksCacheDuration - Duration (in seconds) to cache the JSON Web Key Set (JWKS). Defaults to 300 (5 minutes).
+   * @param fetcher - Custom `fetch` implementation used for making HTTP requests. Falls back to the global `fetch` if not provided.
    */
-  authorizationUrl(params: AuthorizationParams): Promise<string>;
+  constructor(tenantDomain: string, metadataCacheDuration?: number, jwksCacheDuration?: number, fetcher?: typeof fetch);
   /**
    * Fetches the authorization server metadata from the .well-known endpoint.
-   * The metadata is cached for 1 minute.
+   * The metadata is cached for 5 minutes by default.
    *
    * @param forceRefresh - If `true`, bypasses the cache and fetches fresh metadata from the server.
    *
@@ -98,7 +113,7 @@ declare class MonoCloudOidcClient {
   getMetadata(forceRefresh?: boolean): Promise<IssuerMetadata>;
   /**
    * Fetches the JSON Web Keys used to sign the ID token.
-   * The JWKS is cached for 1 minute.
+   * The JWKS is cached for 5 minutes by default.
    *
    * @param forceRefresh - If `true`, bypasses the cache and fetches fresh set of JWKS from the server.
    *
@@ -109,6 +124,52 @@ declare class MonoCloudOidcClient {
    *
    */
   getJwks(forceRefresh?: boolean): Promise<Jwks>;
+  /**
+   * Decodes the payload of a JSON Web Token (JWT) and returns it as an object.
+   *
+   * >Note: THIS METHOD DOES NOT VERIFY JWT TOKENS.
+   *
+   * @param jwt - JWT to decode.
+   *
+   * @returns Decoded payload.
+   *
+   * @throws {@link MonoCloudTokenError} - If decoding fails
+   *
+   */
+  static decodeJwt(jwt: string): JwtClaims;
+}
+//#endregion
+//#region src/monocloud-oidc-client.d.ts
+/**
+ * @category Classes
+ */
+declare class MonoCloudOidcClient extends MonoCloudOidcClientBase {
+  private readonly clientId;
+  private readonly clientSecret?;
+  private readonly authMethod;
+  private readonly idTokenSigningAlgorithm;
+  /**
+   * Creates a new instance of MonoCloudOidcClient.
+   *
+   * @param tenantDomain - The tenant domain URL.
+   * @param clientId - Client id of the application registered in MonoCloud.
+   * @param options - Additional client configuration options.
+   */
+  constructor(tenantDomain: string, clientId: string, options?: MonoCloudOidcClientOptions);
+  /**
+   * Generates an authorization URL with specified parameters.
+   *
+   * If no values are provided for `responseType`, or `codeChallengeMethod`, they default to `code`, and `S256`, respectively.
+   *
+   * @param params - Authorization URL parameters.
+   *
+   * @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.
+   *
+   */
+  authorizationUrl(params: AuthorizationParams): Promise<string>;
   /**
    * Performs a pushed authorization request.
    *
@@ -292,20 +353,87 @@ declare class MonoCloudOidcClient {
    *
    */
   validateIdToken(idToken: string, jwks: Jwk[], clockSkew: number, clockTolerance: number, maxAge?: number, nonce?: string): Promise<IdTokenClaims>;
+}
+//#endregion
+//#region src/monocloud-oidc-backend-client.d.ts
+/**
+ * @category Classes
+ */
+declare class MonoCloudOidcBackendClient extends MonoCloudOidcClientBase {
+  private readonly clientId?;
+  private readonly clientSecret?;
+  private readonly authMethod;
+  private readonly audience;
+  private readonly groupOptions?;
   /**
-   * Decodes the payload of a JSON Web Token (JWT) and returns it as an object.
+   * Number of seconds to adjust the current time to account for clock differences between the client and server during time-based claim validation. Defaults to 0.
+   */
+  protected clockSkew: number;
+  /**
+   * Additional time tolerance in seconds applied when validating time-based claims (`exp`, `nbf`). Defaults to 300 (5 minutes).
+   */
+  protected clockTolerance: number;
+  /**
+   * Creates a new instance of MonoCloudOidcBackendClient.
    *
-   * >Note: THIS METHOD DOES NOT VERIFY JWT TOKENS.
+   * @param tenantDomain - The tenant domain URL.
+   * @param audience - The expected audience value used to validate the `aud` claim in access tokens.
+   * @param options - Additional client configuration options.
+   */
+  constructor(tenantDomain: string, audience: string, options?: MonoCloudOidcBackendClientOptions);
+  /**
+   * Validates an opaque access token using the OAuth 2.0 Token Introspection endpoint (RFC 7662).
    *
-   * @param jwt - JWT to decode.
+   * @param accessToken - The access token string to introspect.
+   * @param options - Claims validation options.
    *
-   * @returns Decoded payload.
+   * @returns Validated access token claims (without the `active` field).
    *
-   * @throws {@link MonoCloudTokenError} - If decoding fails
+   * @throws {@link MonoCloudTokenError} - If the token is not active or claim validation fails.
+   *
+   * @throws {@link MonoCloudOPError} - When the introspection endpoint returns a standardized
+   * OAuth 2.0 error response.
+   *
+   * @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.
+   *
+   * @throws {@link MonoCloudValidationError} - When the access token is empty or the introspection
+   * endpoint is not available in the issuer metadata or claims validation fails.
+   *
+   */
+  introspectAccessToken(accessToken: string, options?: IntrospectOptions): Promise<AccessTokenClaims>;
+  /**
+   * Validates a JWT access token by verifying the signature and claims.
+   *
+   * @param accessToken - The access token JWT string to validate.
+   * @param options - Validation options.
    *
+   * @returns Validated access token claims.
+   *
+   * @throws {@link MonoCloudTokenError} - If JWT parsing, signature verification, or claim 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.
+   *
+   * @throws {@link MonoCloudValidationError} - When the access token is empty or claims validation fails.
+   *
+   */
+  validateJwtAccessToken(accessToken: string, options?: ValidateJwtAccessTokenOptions): Promise<AccessTokenClaims>;
+  /**
+   * Sets clock skew used for access token time-based claim validation.
+   *
+   * @param clockSkew - Number of seconds to adjust the current time to account for clock differences.
+   */
+  setClockSkew(clockSkew: number): void;
+  /**
+   * Sets clock tolerance used for access token time-based claim validation.
+   *
+   * @param clockTolerance - Additional time tolerance in seconds for time-based claim validation.
    */
-  static decodeJwt(jwt: string): IdTokenClaims;
+  setClockTolerance(clockTolerance: number): void;
+  private validateAccessTokenClaims;
+  private validateCertificateBinding;
 }
 //#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 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 };
+export { type AccessToken, type AccessTokenClaims, 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 IntrospectOptions, type IsUserInGroupOptions, type IssuerMetadata, type Jwk, type Jwks, type JwsHeaderParameters, type JwtClaims, MonoCloudAuthBaseError, type MonoCloudClientOptionsBase, MonoCloudHttpError, MonoCloudOPError, MonoCloudOidcBackendClient, type MonoCloudOidcBackendClientOptions, MonoCloudOidcClient, MonoCloudOidcClientBase, type MonoCloudOidcClientOptions, 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 TokenValidationOptionsBase, type Tokens, type UserinfoResponse, type ValidateJwtAccessTokenOptions };
 //# sourceMappingURL=index.d.mts.map