@authly/sdk 1.1.1 → 1.2.0

package/dist/globals/clients/AuthlyClient.d.ts

@@ -1,92 +1,125 @@
-import type { Claims } from "../../models/Claims";
+import type { IAuthlyClientOptions } from "../../models/globals/clients/interfaces/IAuthlyClientOptions";
+import type { IAuthorizeUrlOptions } from "../../models/globals/clients/interfaces/IAuthorizeUrlOptions";
+import type { IDecodedTokenClaim } from "../../models/globals/clients/interfaces/IDecodedTokenClaim";
+import type { ITokenResponse } from "../../models/globals/clients/interfaces/ITokenResponse";
+import type { IUserProfile } from "../../models/globals/clients/interfaces/IUserProfile";
 /**
- * Options for initializing the AuthlyClient.
+ * @summary A client for interacting with Authly.
+ * @description This client handles the validation of tokens against a specific issuer and audience,
+ * fetching the public keys (JWKS) automatically, and provides utilities for
+ * starting the OAuth2 flow.
  */
-export interface AuthlyClientOptions {
+declare class AuthlyClient {
+    private static readonly ACCESS_TOKEN_KEY;
     /**
-     * The base URL of the identity provider (e.g., "https://auth.example.com").
+     * @summary The JWT verifier for the client.
      */
-    issuer: string;
-    /**
-     * The expected audience claim (aud) in the token.
-     */
-    audience: string;
+    private readonly verifier;
     /**
-     * The ID of the service in Authly.
+     * @summary The service ID of the client.
      */
-    serviceId: string;
+    private readonly serviceId;
     /**
-     * The path to the JWKS endpoint relative to the issuer. Defaults to "/.well-known/jwks.json".
+     * @summary The issuer of the client.
      */
-    jwksPath?: string;
+    private readonly issuer;
     /**
-     * The path to the authorize endpoint relative to the issuer. Defaults to "/v1/oauth/authorize".
+     * @summary The authorize path of the client.
      */
-    authorizePath?: string;
+    private readonly authorizePath;
     /**
-     * A list of allowed signing algorithms. If omitted, defaults to ["RS256"].
+     * @summary The token path of the client.
      */
-    algorithms?: string[];
-}
-/**
- * Options for generating an authorization URL.
- */
-export interface AuthorizeUrlOptions {
+    private readonly tokenPath;
     /**
-     * The URI to redirect back to after authentication.
+     * @summary The user info path of the client.
      */
-    redirectUri: string;
+    private readonly userInfoPath;
     /**
-     * A unique state string to prevent CSRF.
+     * @summary The redirect URI for the client.
      */
-    state: string;
+    private readonly redirectUri?;
     /**
-     * The PKCE code challenge.
+     * @summary The storage implementation.
      */
-    codeChallenge: string;
+    private readonly storage?;
     /**
-     * The PKCE code challenge method. Defaults to "S256".
+     * @summary Memory cache for the access token.
      */
-    codeChallengeMethod?: "S256" | "plain";
+    private accessToken;
     /**
-     * The requested scopes. Defaults to "openid profile email".
+     * @summary Constructs a new AuthlyClient.
+     * @param options - The options for the client.
      */
-    scope?: string;
+    constructor(options: IAuthlyClientOptions);
     /**
-     * The OAuth2 response type. Defaults to "code".
+     * @summary Prepares the authorization request, stores PKCE state, and returns the URL.
+     * @param options - Optional overrides for the authorization request.
+     * @returns A promise that resolves to the authorization URL.
      */
-    responseType?: string;
-}
-/**
- * A client for interacting with Authly.
- *
- * This client handles the validation of tokens against a specific issuer and audience,
- * fetching the public keys (JWKS) automatically, and provides utilities for
- * starting the OAuth2 flow.
- */
-export declare class AuthlyClient {
-    private readonly verifier;
-    private readonly serviceId;
-    private readonly issuer;
-    private readonly authorizePath;
-    constructor(options: AuthlyClientOptions);
+    authorize(options?: Partial<IAuthorizeUrlOptions>): Promise<string>;
     /**
-     * Generate the authorization URL to redirect the user to.
-     *
+     * @summary Generate the authorization URL to redirect the user to.
      * @param options - Options for generating the URL.
      * @returns The full authorization URL.
      */
-    getAuthorizeUrl(options: AuthorizeUrlOptions): string;
+    getAuthorizeUrl(options: IAuthorizeUrlOptions): string;
+    /**
+     * @summary Exchanges the authorization code for tokens using PKCE flow and state validation.
+     * @param urlParams - The URLSearchParams containing 'code' and 'state'.
+     * @returns A promise that resolves to the token response.
+     */
+    exchangeToken(urlParams: URLSearchParams): Promise<ITokenResponse>;
+    /**
+     * @summary Set the current session.
+     * @param response - The token response from Authly.
+     */
+    setSession(response: ITokenResponse): Promise<void>;
+    /**
+     * @summary Get the current access token.
+     * @returns The access token or null if not found.
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * @summary Refreshes the access token using the refresh_token grant.
+     * @description In the browser, this relies on the 'session' cookie if no explicit refresh token is provided.
+     * @param refreshToken - Optional explicit refresh token.
+     * @returns A promise that resolves to the new access token.
+     */
+    refreshToken(refreshToken?: string): Promise<string | null>;
+    /**
+     * @summary Fetches the user profile from the userinfo endpoint.
+     * @description Automatically handles token expiration by attempting to refresh the token once.
+     * @returns A promise that resolves to the user profile or null if not authenticated.
+     */
+    getUser(): Promise<IUserProfile | null>;
+    /**
+     * @summary Synchronously check if the user is authenticated based on token presence and expiration.
+     * @description This only checks the token locally and does not perform a network request.
+     * @returns True if a valid token exists and is not expired.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * @summary Logs out the user by clearing the session from storage and memory.
+     */
+    logout(): Promise<void>;
+    /**
+     * @summary Exchange the authorization code for an access token.
+     * @param code - The authorization code received from the callback.
+     * @param redirectUri - The redirect URI used in the authorize request.
+     * @param codeVerifier - The PKCE code verifier (required if used in authorize).
+     * @returns A promise that resolves to the token response.
+     */
+    exchangeCodeForToken(code: string, redirectUri: string, codeVerifier?: string): Promise<ITokenResponse>;
     /**
-     * Verify a JWT token and return its decoded claims.
-     *
-     * This method verifies the token's signature using the provider's JWKS,
+     * @summary Verify a JWT token and return its decoded claims.
+     * @description This method verifies the token's signature using the provider's JWKS,
      * and validates standard claims like expiration, issuer, and audience.
-     *
      * @param token - The encoded JWT token string.
      * @returns A promise that resolves to the token claims (e.g., sub, iss, aud).
-     * @throws {TokenExpiredError} If the token has expired.
-     * @throws {TokenInvalidError} If the token is invalid (e.g., bad signature, invalid audience).
+     * @throws {AuthlyTokenExpiredError} If the token has expired.
+     * @throws {AuthlyTokenInvalidError} If the token is invalid (e.g., bad signature, invalid audience).
      */
-    verify(token: string): Promise<Claims>;
+    verify(token: string): Promise<IDecodedTokenClaim>;
 }
+export { AuthlyClient };

package/dist/globals/clients/AuthlyClient.js

@@ -1,35 +1,104 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthlyClient = void 0;
-const config_1 = require("../../config");
-const JWTVerifier_1 = require("./internal/JWTVerifier");
+const jose_1 = require("jose");
+const JWTVerifier_1 = require("../internal/JWTVerifier");
+const HttpClient_1 = require("../internal/HttpClient");
+const PKCEUtils_1 = require("../internal/PKCEUtils");
+const AuthlyConfiguration_1 = require("../configuration/AuthlyConfiguration");
 /**
- * A client for interacting with Authly.
- *
- * This client handles the validation of tokens against a specific issuer and audience,
+ * @summary A client for interacting with Authly.
+ * @description This client handles the validation of tokens against a specific issuer and audience,
  * fetching the public keys (JWKS) automatically, and provides utilities for
  * starting the OAuth2 flow.
  */
 class AuthlyClient {
+    static ACCESS_TOKEN_KEY = "authly_access_token";
+    /**
+     * @summary The JWT verifier for the client.
+     */
     verifier;
+    /**
+     * @summary The service ID of the client.
+     */
     serviceId;
+    /**
+     * @summary The issuer of the client.
+     */
     issuer;
+    /**
+     * @summary The authorize path of the client.
+     */
     authorizePath;
+    /**
+     * @summary The token path of the client.
+     */
+    tokenPath;
+    /**
+     * @summary The user info path of the client.
+     */
+    userInfoPath;
+    /**
+     * @summary The redirect URI for the client.
+     */
+    redirectUri;
+    /**
+     * @summary The storage implementation.
+     */
+    storage;
+    /**
+     * @summary Memory cache for the access token.
+     */
+    accessToken = null;
+    /**
+     * @summary Constructs a new AuthlyClient.
+     * @param options - The options for the client.
+     */
     constructor(options) {
         this.issuer = options.issuer.replace(/\/$/, "");
         this.serviceId = options.serviceId;
-        const jwksPath = options.jwksPath || config_1.DEFAULT_JWKS_PATH;
-        this.authorizePath = options.authorizePath || config_1.DEFAULT_AUTHORIZE_PATH;
+        this.authorizePath = options.authorizePath || AuthlyConfiguration_1.AuthlyConfiguration.DEFAULT_AUTHORIZE_PATH;
+        this.tokenPath = options.tokenPath || AuthlyConfiguration_1.AuthlyConfiguration.DEFAULT_TOKEN_PATH;
+        this.userInfoPath = options.userInfoPath || AuthlyConfiguration_1.AuthlyConfiguration.DEFAULT_USER_INFO_PATH;
+        this.redirectUri = options.redirectUri;
+        this.storage = options.storage;
+        if (!this.storage && typeof window !== "undefined" && window.sessionStorage) {
+            this.storage = window.sessionStorage;
+        }
         this.verifier = new JWTVerifier_1.JWTVerifier({
             issuer: this.issuer,
             audience: options.audience,
-            jwksUrl: `${this.issuer}${jwksPath}`,
+            jwksUrl: `${this.issuer}${options.jwksPath || AuthlyConfiguration_1.AuthlyConfiguration.DEFAULT_JWKS_PATH}`,
             algorithms: options.algorithms,
         });
     }
     /**
-     * Generate the authorization URL to redirect the user to.
-     *
+     * @summary Prepares the authorization request, stores PKCE state, and returns the URL.
+     * @param options - Optional overrides for the authorization request.
+     * @returns A promise that resolves to the authorization URL.
+     */
+    async authorize(options) {
+        if (!this.storage) {
+            throw new Error("Storage is not configured. Cannot save state and code verifier.");
+        }
+        if (!this.redirectUri && !options?.redirectUri) {
+            throw new Error("Redirect URI is required but not configured.");
+        }
+        const state = options?.state || PKCEUtils_1.PKCEUtils.generateRandomString();
+        const codeVerifier = PKCEUtils_1.PKCEUtils.generateRandomString();
+        const codeChallenge = await PKCEUtils_1.PKCEUtils.generateCodeChallenge(codeVerifier);
+        await this.storage.setItem("pkce_state", state);
+        await this.storage.setItem("pkce_verifier", codeVerifier);
+        return this.getAuthorizeUrl({
+            redirectUri: (options?.redirectUri || this.redirectUri),
+            ...options,
+            state,
+            codeChallenge,
+            codeChallengeMethod: "S256",
+        });
+    }
+    /**
+     * @summary Generate the authorization URL to redirect the user to.
      * @param options - Options for generating the URL.
      * @returns The full authorization URL.
      */
@@ -41,19 +110,188 @@ class AuthlyClient {
         url.searchParams.set("scope", options.scope || "openid profile email");
         url.searchParams.set("state", options.state);
         url.searchParams.set("code_challenge", options.codeChallenge);
-        url.searchParams.set("code_challenge_method", options.codeChallengeMethod || "S256");
+        url.searchParams.set("code_challenge_method", options.codeChallengeMethod || "s256");
         return url.toString();
     }
     /**
-     * Verify a JWT token and return its decoded claims.
-     *
-     * This method verifies the token's signature using the provider's JWKS,
+     * @summary Exchanges the authorization code for tokens using PKCE flow and state validation.
+     * @param urlParams - The URLSearchParams containing 'code' and 'state'.
+     * @returns A promise that resolves to the token response.
+     */
+    async exchangeToken(urlParams) {
+        const code = urlParams.get("code");
+        const state = urlParams.get("state");
+        if (!code) {
+            throw new Error("No authorization code found in URL parameters.");
+        }
+        if (!this.storage) {
+            throw new Error("Storage is not configured. Cannot retrieve state and code verifier.");
+        }
+        const storedState = await this.storage.getItem("pkce_state");
+        if (!state || state !== storedState) {
+            throw new Error("Invalid state. Possible CSRF attack.");
+        }
+        const codeVerifier = await this.storage.getItem("pkce_verifier");
+        if (!codeVerifier) {
+            throw new Error("No code verifier found in storage.");
+        }
+        if (!this.redirectUri) {
+            throw new Error("Redirect URI is not configured in AuthlyClient options.");
+        }
+        const tokenResponse = await this.exchangeCodeForToken(code, this.redirectUri, codeVerifier);
+        await this.setSession(tokenResponse);
+        // Clear temporary storage
+        await this.storage.removeItem("pkce_state");
+        await this.storage.removeItem("pkce_verifier");
+        return tokenResponse;
+    }
+    /**
+     * @summary Set the current session.
+     * @param response - The token response from Authly.
+     */
+    async setSession(response) {
+        this.accessToken = response.access_token;
+        if (this.storage) {
+            await this.storage.setItem(AuthlyClient.ACCESS_TOKEN_KEY, response.access_token);
+        }
+    }
+    /**
+     * @summary Get the current access token.
+     * @returns The access token or null if not found.
+     */
+    async getAccessToken() {
+        if (this.accessToken)
+            return this.accessToken;
+        if (this.storage) {
+            this.accessToken = await this.storage.getItem(AuthlyClient.ACCESS_TOKEN_KEY);
+        }
+        return this.accessToken;
+    }
+    /**
+     * @summary Refreshes the access token using the refresh_token grant.
+     * @description In the browser, this relies on the 'session' cookie if no explicit refresh token is provided.
+     * @param refreshToken - Optional explicit refresh token.
+     * @returns A promise that resolves to the new access token.
+     */
+    async refreshToken(refreshToken) {
+        const url = `${this.issuer}${this.tokenPath}`;
+        const body = {
+            grant_type: "refresh_token",
+            client_id: this.serviceId,
+        };
+        if (refreshToken) {
+            body.refresh_token = refreshToken;
+        }
+        const response = await HttpClient_1.HttpClient.post(url, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: new URLSearchParams(body).toString(),
+        });
+        if (!response.success) {
+            return null;
+        }
+        await this.setSession(response.data);
+        return response.data.access_token;
+    }
+    /**
+     * @summary Fetches the user profile from the userinfo endpoint.
+     * @description Automatically handles token expiration by attempting to refresh the token once.
+     * @returns A promise that resolves to the user profile or null if not authenticated.
+     */
+    async getUser() {
+        let token = await this.getAccessToken();
+        if (!token)
+            return null;
+        const fetchInfo = async (currentBuffer) => {
+            return HttpClient_1.HttpClient.get(`${this.issuer}${this.userInfoPath}`, {
+                headers: {
+                    Authorization: `Bearer ${currentBuffer}`,
+                },
+            });
+        };
+        let response = await fetchInfo(token);
+        // If unauthorized (401), try to refresh token once
+        if (!response.success && response.error?.code === "UNAUTHORIZED") {
+            token = await this.refreshToken();
+            if (token) {
+                response = await fetchInfo(token);
+            }
+        }
+        if (!response.success) {
+            if (response.error?.code === "UNAUTHORIZED") {
+                await this.logout();
+            }
+            return null;
+        }
+        return response.data;
+    }
+    /**
+     * @summary Synchronously check if the user is authenticated based on token presence and expiration.
+     * @description This only checks the token locally and does not perform a network request.
+     * @returns True if a valid token exists and is not expired.
+     */
+    async isAuthenticated() {
+        const token = await this.getAccessToken();
+        if (!token)
+            return false;
+        try {
+            const decoded = (0, jose_1.decodeJwt)(token);
+            if (!decoded.exp)
+                return true;
+            const now = Math.floor(Date.now() / 1000);
+            return decoded.exp > now + 10;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * @summary Logs out the user by clearing the session from storage and memory.
+     */
+    async logout() {
+        this.accessToken = null;
+        if (this.storage) {
+            await this.storage.removeItem(AuthlyClient.ACCESS_TOKEN_KEY);
+        }
+    }
+    /**
+     * @summary Exchange the authorization code for an access token.
+     * @param code - The authorization code received from the callback.
+     * @param redirectUri - The redirect URI used in the authorize request.
+     * @param codeVerifier - The PKCE code verifier (required if used in authorize).
+     * @returns A promise that resolves to the token response.
+     */
+    async exchangeCodeForToken(code, redirectUri, codeVerifier) {
+        const url = `${this.issuer}${this.tokenPath}`;
+        const body = {
+            grant_type: "authorization_code",
+            client_id: this.serviceId,
+            code,
+            redirect_uri: redirectUri,
+        };
+        if (codeVerifier) {
+            body.code_verifier = codeVerifier;
+        }
+        const response = await HttpClient_1.HttpClient.post(url, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: new URLSearchParams(body).toString(),
+        });
+        if (!response.success) {
+            throw new Error(response.error?.message || "Failed to exchange code for token");
+        }
+        return response.data;
+    }
+    /**
+     * @summary Verify a JWT token and return its decoded claims.
+     * @description This method verifies the token's signature using the provider's JWKS,
      * and validates standard claims like expiration, issuer, and audience.
-     *
      * @param token - The encoded JWT token string.
      * @returns A promise that resolves to the token claims (e.g., sub, iss, aud).
-     * @throws {TokenExpiredError} If the token has expired.
-     * @throws {TokenInvalidError} If the token is invalid (e.g., bad signature, invalid audience).
+     * @throws {AuthlyTokenExpiredError} If the token has expired.
+     * @throws {AuthlyTokenInvalidError} If the token is invalid (e.g., bad signature, invalid audience).
      */
     async verify(token) {
         return this.verifier.verify(token);

package/dist/globals/configuration/AuthlyConfiguration.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @summary Configuration for the Authly library.
+ */
+declare class AuthlyConfiguration {
+    /**
+     * @summary Private constructor to prevent instantiation.
+     */
+    private constructor();
+    /**
+     * @summary The default JWKS path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/.well-known/jwks.json"
+     */
+    static readonly DEFAULT_JWKS_PATH: string;
+    /**
+     * @summary The default authorize path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/authorize"
+     */
+    static readonly DEFAULT_AUTHORIZE_PATH: string;
+    /**
+     * @summary The default token path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/oauth/token"
+     */
+    static readonly DEFAULT_TOKEN_PATH: string;
+    /**
+     * @summary The default user info path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/v1/oauth/userinfo"
+     */
+    static readonly DEFAULT_USER_INFO_PATH: string;
+    /**
+     * @summary The default algorithms.
+     * @readonly This property is readonly and cannot be changed.
+     * @default ["RS256"]
+     */
+    static readonly DEFAULT_ALGORITHMS: readonly string[];
+}
+export { AuthlyConfiguration };

package/dist/globals/configuration/AuthlyConfiguration.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthlyConfiguration = void 0;
+/**
+ * @summary Configuration for the Authly library.
+ */
+class AuthlyConfiguration {
+    /**
+     * @summary Private constructor to prevent instantiation.
+     */
+    constructor() { }
+    /**
+     * @summary The default JWKS path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/.well-known/jwks.json"
+     */
+    static DEFAULT_JWKS_PATH = "/.well-known/jwks.json";
+    /**
+     * @summary The default authorize path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/authorize"
+     */
+    static DEFAULT_AUTHORIZE_PATH = "/authorize";
+    /**
+     * @summary The default token path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/oauth/token"
+     */
+    static DEFAULT_TOKEN_PATH = "/oauth/token";
+    /**
+     * @summary The default user info path.
+     * @readonly This property is readonly and cannot be changed.
+     * @default "/v1/oauth/userinfo"
+     */
+    static DEFAULT_USER_INFO_PATH = "/v1/oauth/userinfo";
+    /**
+     * @summary The default algorithms.
+     * @readonly This property is readonly and cannot be changed.
+     * @default ["RS256"]
+     */
+    static DEFAULT_ALGORITHMS = ["RS256"];
+}
+exports.AuthlyConfiguration = AuthlyConfiguration;

package/dist/globals/{clients → internal}/HttpClient.d.ts

@@ -1,46 +1,46 @@
 import type { IRequestResponseClient } from "../../models/globals/clients/interfaces/IRequestResponseClient";
 /**
- * A class that provides a static method for making HTTP requests.
+ * @summary A class that provides a static method for making HTTP requests.
  */
 declare class HttpClient {
     private constructor();
     /**
-     * Makes an HTTP request to the specified URL.
+     * @summary Makes an HTTP request to the specified URL.
      * @param url - The URL to make the request to.
      * @param options - The options for the request.
      * @returns A promise that resolves to the response data.
      */
     private static request;
     /**
-     * Makes a GET request to the specified URL.
+     * @summary Makes a GET request to the specified URL.
      * @param url - The URL to make the request to.
      * @param options - The options for the request.
      * @returns A promise that resolves to the response data.
      */
     static get<D>(url: string, options?: Omit<RequestInit, "method">): Promise<IRequestResponseClient<D>>;
     /**
-     * Makes a POST request to the specified URL.
+     * @summary Makes a POST request to the specified URL.
      * @param url - The URL to make the request to.
      * @param options - The options for the request.
      * @returns A promise that resolves to the response data.
      */
     static post<D>(url: string, options?: Omit<RequestInit, "method">): Promise<IRequestResponseClient<D>>;
     /**
-     * Makes a PUT request to the specified URL.
+     * @summary Makes a PUT request to the specified URL.
      * @param url - The URL to make the request to.
      * @param options - The options for the request.
      * @returns A promise that resolves to the response data.
      */
     static put<D>(url: string, options?: Omit<RequestInit, "method">): Promise<IRequestResponseClient<D>>;
     /**
-     * Makes a PATCH request to the specified URL.
+     * @summary Makes a PATCH request to the specified URL.
      * @param url - The URL to make the request to.
      * @param options - The options for the request.
      * @returns A promise that resolves to the response data.
      */
     static patch<D>(url: string, options?: Omit<RequestInit, "method">): Promise<IRequestResponseClient<D>>;
     /**
-     * Makes a DELETE request to the specified URL.
+     * @summary Makes a DELETE request to the specified URL.
      * @param url - The URL to make the request to.
      * @param options - The options for the request.
      * @returns A promise that resolves to the response data.