@authly/sdk 1.1.1 → 1.2.0

package/dist/globals/{clients → internal}/HttpClient.js

@@ -2,12 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClient = void 0;
 /**
- * A class that provides a static method for making HTTP requests.
+ * @summary A class that provides a static method for making HTTP requests.
  */
 class HttpClient {
     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.
@@ -35,7 +35,7 @@ class HttpClient {
         }
     }
     /**
-     * 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.
@@ -47,7 +47,7 @@ class HttpClient {
         });
     }
     /**
-     * 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.
@@ -59,7 +59,7 @@ class HttpClient {
         });
     }
     /**
-     * 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.
@@ -71,7 +71,7 @@ class HttpClient {
         });
     }
     /**
-     * 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.
@@ -83,7 +83,7 @@ class HttpClient {
         });
     }
     /**
-     * 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.

package/dist/globals/internal/JWTVerifier.d.ts

@@ -0,0 +1,37 @@
+import type { IDecodedTokenClaim } from "../../models/globals/clients/interfaces/IDecodedTokenClaim";
+import type { IJWTVerifierOptions } from "../../models/globals/clients/internal/interfaces/IJWTVerifierOptions";
+/**
+ * @summary Internal class for verifying JWT tokens using jose.
+ */
+declare class JWTVerifier {
+    /**
+     * @summary The issuer of the token.
+     */
+    private readonly issuer;
+    /**
+     * @summary The audience of the token.
+     */
+    private readonly audience;
+    /**
+     * @summary The algorithms to use for the token.
+     */
+    private readonly algorithms;
+    /**
+     * @summary The JWKS to use for the token.
+     */
+    private readonly JWKS;
+    /**
+     * @summary Constructs a new JWTVerifier.
+     * @param params - The options for the JWTVerifier.
+     */
+    constructor(params: IJWTVerifierOptions);
+    /**
+     * @summary Verify the JWT token and return its claims.
+     * @param token - The encoded JWT token string.
+     * @returns The decoded claims from the token.
+     * @throws {AuthlyTokenExpiredError} If the token's exp claim is in the past.
+     * @throws {AuthlyTokenInvalidError} If the token is otherwise invalid.
+     */
+    verify(token: string): Promise<IDecodedTokenClaim>;
+}
+export { JWTVerifier };

package/dist/globals/internal/JWTVerifier.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JWTVerifier = void 0;
+const jose_1 = require("jose");
+const AuthlyTokenExpiredError_1 = require("../../models/builders/process-errors/tokens/AuthlyTokenExpiredError");
+const AuthlyTokenInvalidError_1 = require("../../models/builders/process-errors/tokens/AuthlyTokenInvalidError");
+const AuthlyConfiguration_1 = require("../configuration/AuthlyConfiguration");
+/**
+ * @summary Internal class for verifying JWT tokens using jose.
+ */
+class JWTVerifier {
+    /**
+     * @summary The issuer of the token.
+     */
+    issuer;
+    /**
+     * @summary The audience of the token.
+     */
+    audience;
+    /**
+     * @summary The algorithms to use for the token.
+     */
+    algorithms;
+    /**
+     * @summary The JWKS to use for the token.
+     */
+    JWKS;
+    /**
+     * @summary Constructs a new JWTVerifier.
+     * @param params - The options for the JWTVerifier.
+     */
+    constructor(params) {
+        this.issuer = params.issuer;
+        this.audience = params.audience;
+        this.algorithms = params.algorithms || AuthlyConfiguration_1.AuthlyConfiguration.DEFAULT_ALGORITHMS;
+        this.JWKS = params.jwks || (0, jose_1.createRemoteJWKSet)(new URL(params.jwksUrl));
+    }
+    /**
+     * @summary Verify the JWT token and return its claims.
+     * @param token - The encoded JWT token string.
+     * @returns The decoded claims from the token.
+     * @throws {AuthlyTokenExpiredError} If the token's exp claim is in the past.
+     * @throws {AuthlyTokenInvalidError} If the token is otherwise invalid.
+     */
+    async verify(token) {
+        try {
+            const { payload } = await (0, jose_1.jwtVerify)(token, this.JWKS, {
+                issuer: this.issuer,
+                audience: this.audience,
+                algorithms: this.algorithms,
+            });
+            return payload;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                const code = error.code;
+                if (code === "ERR_JWT_EXPIRED") {
+                    throw new AuthlyTokenExpiredError_1.AuthlyTokenExpiredError("Token has expired");
+                }
+                if (code === "ERR_JWT_CLAIM_VALIDATION_FAILED" ||
+                    code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED" ||
+                    code === "ERR_JWS_INVALID" ||
+                    code === "ERR_JWT_INVALID") {
+                    throw new AuthlyTokenInvalidError_1.AuthlyTokenInvalidError(error.message ?? "Token validation failed");
+                }
+            }
+            throw new AuthlyTokenInvalidError_1.AuthlyTokenInvalidError("Invalid token");
+        }
+    }
+}
+exports.JWTVerifier = JWTVerifier;

package/dist/globals/internal/PKCEUtils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @summary Utilities for PKCE (Proof Key for Code Exchange).
+ */
+export declare class PKCEUtils {
+    /**
+     * @summary Generate a random string for state or code verifier.
+     * @param length - The length of the string.
+     * @returns The generated string.
+     */
+    static generateRandomString(length?: number): string;
+    /**
+     * @summary Generate the code challenge from the code verifier.
+     * @param codeVerifier - The code verifier.
+     * @returns A promise that resolves to the code challenge.
+     */
+    static generateCodeChallenge(codeVerifier: string): Promise<string>;
+    /**
+     * @summary Base64 URL encode a buffer.
+     * @param buffer - The buffer to encode.
+     * @returns The base64 URL encoded string.
+     */
+    private static base64URLEncode;
+}

package/dist/globals/internal/PKCEUtils.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PKCEUtils = void 0;
+/**
+ * @summary Utilities for PKCE (Proof Key for Code Exchange).
+ */
+class PKCEUtils {
+    /**
+     * @summary Generate a random string for state or code verifier.
+     * @param length - The length of the string.
+     * @returns The generated string.
+     */
+    static generateRandomString(length = 43) {
+        const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+        let result = "";
+        const randomValues = new Uint8Array(length);
+        if (typeof window !== "undefined" && window.crypto) {
+            window.crypto.getRandomValues(randomValues);
+        }
+        else {
+            for (let i = 0; i < length; i++) {
+                randomValues[i] = Math.floor(Math.random() * 256);
+            }
+        }
+        for (let i = 0; i < length; i++) {
+            result += charset[randomValues[i] % charset.length];
+        }
+        return result;
+    }
+    /**
+     * @summary Generate the code challenge from the code verifier.
+     * @param codeVerifier - The code verifier.
+     * @returns A promise that resolves to the code challenge.
+     */
+    static async generateCodeChallenge(codeVerifier) {
+        const encoder = new TextEncoder();
+        const data = encoder.encode(codeVerifier);
+        if (typeof window !== "undefined" && window.crypto && window.crypto.subtle) {
+            const hashBuffer = await window.crypto.subtle.digest("SHA-256", data);
+            return this.base64URLEncode(hashBuffer);
+        }
+        // TODO: Add a fallback for non-browser environments. (crypto module)
+        throw new Error("Crypto API is not available in this environment.");
+    }
+    /**
+     * @summary Base64 URL encode a buffer.
+     * @param buffer - The buffer to encode.
+     * @returns The base64 URL encoded string.
+     */
+    static base64URLEncode(buffer) {
+        const bytes = new Uint8Array(buffer);
+        let binary = "";
+        for (let i = 0; i < bytes.byteLength; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    }
+}
+exports.PKCEUtils = PKCEUtils;

package/dist/index.d.ts

@@ -1,3 +1,26 @@
-export * from "./models/Claims";
-export * from "./exceptions";
+/**
+ * @authly/sdk
+ *
+ * A library for building authentication systems using Authly.
+ *
+ * @author Anvoria
+ * @license MIT
+ */
+/**
+ * Clients.
+ */
 export * from "./globals/clients/AuthlyClient";
+export * from "./globals/configuration/AuthlyConfiguration";
+/**
+ * Models.
+ */
+export * from "./models/builders/process-errors/base/AuthlyError";
+export * from "./models/builders/process-errors/base/AuthlyTokenError";
+export * from "./models/builders/process-errors/tokens/AuthlyTokenExpiredError";
+export * from "./models/builders/process-errors/tokens/AuthlyTokenInvalidError";
+export * from "./models/globals/clients/interfaces/IAuthlyClientOptions";
+export * from "./models/globals/clients/interfaces/IAuthorizeUrlOptions";
+export * from "./models/globals/clients/interfaces/IDecodedTokenClaim";
+export * from "./models/globals/clients/interfaces/ITokenResponse";
+export * from "./models/globals/clients/interfaces/IAuthlyStorage";
+export * from "./models/globals/clients/interfaces/IUserProfile";

package/dist/index.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * @authly/sdk
+ *
+ * A library for building authentication systems using Authly.
+ *
+ * @author Anvoria
+ * @license MIT
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -14,6 +22,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./models/Claims"), exports);
-__exportStar(require("./exceptions"), exports);
+/**
+ * Clients.
+ */
 __exportStar(require("./globals/clients/AuthlyClient"), exports);
+__exportStar(require("./globals/configuration/AuthlyConfiguration"), exports);
+/**
+ * Models.
+ */
+__exportStar(require("./models/builders/process-errors/base/AuthlyError"), exports);
+__exportStar(require("./models/builders/process-errors/base/AuthlyTokenError"), exports);
+__exportStar(require("./models/builders/process-errors/tokens/AuthlyTokenExpiredError"), exports);
+__exportStar(require("./models/builders/process-errors/tokens/AuthlyTokenInvalidError"), exports);
+__exportStar(require("./models/globals/clients/interfaces/IAuthlyClientOptions"), exports);
+__exportStar(require("./models/globals/clients/interfaces/IAuthorizeUrlOptions"), exports);
+__exportStar(require("./models/globals/clients/interfaces/IDecodedTokenClaim"), exports);
+__exportStar(require("./models/globals/clients/interfaces/ITokenResponse"), exports);
+__exportStar(require("./models/globals/clients/interfaces/IAuthlyStorage"), exports);
+__exportStar(require("./models/globals/clients/interfaces/IUserProfile"), exports);

package/dist/models/builders/process-errors/base/AuthlyError.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @summary Base exception for all Authly errors.
+ */
+declare abstract class AuthlyError extends Error {
+    /**
+     * @summary Constructs a new AuthlyError.
+     * @param message - The error message.
+     */
+    constructor(message: string);
+}
+export { AuthlyError };

package/dist/models/builders/process-errors/base/AuthlyError.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthlyError = void 0;
+/**
+ * @summary Base exception for all Authly errors.
+ */
+class AuthlyError extends Error {
+    /**
+     * @summary Constructs a new AuthlyError.
+     * @param message - The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "AuthlyError";
+        Object.setPrototypeOf(this, AuthlyError.prototype);
+    }
+}
+exports.AuthlyError = AuthlyError;

package/dist/models/builders/process-errors/base/AuthlyTokenError.d.ts

@@ -0,0 +1,12 @@
+import { AuthlyError } from "./AuthlyError";
+/**
+ * @summary Base exception for all Authly token errors.
+ */
+declare abstract class AuthlyTokenError extends AuthlyError {
+    /**
+     * @summary Constructs a new AuthlyTokenError.
+     * @param message - The error message.
+     */
+    constructor(message: string);
+}
+export { AuthlyTokenError };

package/dist/models/builders/process-errors/base/AuthlyTokenError.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthlyTokenError = void 0;
+const AuthlyError_1 = require("./AuthlyError");
+/**
+ * @summary Base exception for all Authly token errors.
+ */
+class AuthlyTokenError extends AuthlyError_1.AuthlyError {
+    /**
+     * @summary Constructs a new AuthlyTokenError.
+     * @param message - The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "AuthlyTokenError";
+        Object.setPrototypeOf(this, AuthlyTokenError.prototype);
+    }
+}
+exports.AuthlyTokenError = AuthlyTokenError;

package/dist/models/builders/process-errors/tokens/AuthlyTokenExpiredError.d.ts

@@ -0,0 +1,13 @@
+import { AuthlyTokenError } from "../base/AuthlyTokenError";
+/**
+ * @summary Exception raised when a token is expired.
+ * @throws This error is thrown when the token's expiration time is in the past.
+ */
+declare class AuthlyTokenExpiredError extends AuthlyTokenError {
+    /**
+     * @summary Constructs a new AuthlyTokenExpiredError.
+     * @param message - The error message.
+     */
+    constructor(message: string);
+}
+export { AuthlyTokenExpiredError };

package/dist/models/builders/process-errors/tokens/AuthlyTokenExpiredError.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthlyTokenExpiredError = void 0;
+const AuthlyTokenError_1 = require("../base/AuthlyTokenError");
+/**
+ * @summary Exception raised when a token is expired.
+ * @throws This error is thrown when the token's expiration time is in the past.
+ */
+class AuthlyTokenExpiredError extends AuthlyTokenError_1.AuthlyTokenError {
+    /**
+     * @summary Constructs a new AuthlyTokenExpiredError.
+     * @param message - The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "AuthlyTokenExpiredError";
+        Object.setPrototypeOf(this, AuthlyTokenExpiredError.prototype);
+    }
+}
+exports.AuthlyTokenExpiredError = AuthlyTokenExpiredError;

package/dist/models/builders/process-errors/tokens/AuthlyTokenInvalidError.d.ts

@@ -0,0 +1,16 @@
+import { AuthlyTokenError } from "../base/AuthlyTokenError";
+/**
+ * @summary Exception raised when a token is invalid.
+ * @throws This error is thrown when:
+ * - The token has an invalid signature.
+ * - The token has an invalid format.
+ * - The token has an invalid issuer or audience.
+ */
+declare class AuthlyTokenInvalidError extends AuthlyTokenError {
+    /**
+     * @summary Constructs a new AuthlyTokenInvalidError.
+     * @param message - The error message.
+     */
+    constructor(message: string);
+}
+export { AuthlyTokenInvalidError };

package/dist/models/builders/process-errors/tokens/AuthlyTokenInvalidError.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthlyTokenInvalidError = void 0;
+const AuthlyTokenError_1 = require("../base/AuthlyTokenError");
+/**
+ * @summary Exception raised when a token is invalid.
+ * @throws This error is thrown when:
+ * - The token has an invalid signature.
+ * - The token has an invalid format.
+ * - The token has an invalid issuer or audience.
+ */
+class AuthlyTokenInvalidError extends AuthlyTokenError_1.AuthlyTokenError {
+    /**
+     * @summary Constructs a new AuthlyTokenInvalidError.
+     * @param message - The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "AuthlyTokenInvalidError";
+        Object.setPrototypeOf(this, AuthlyTokenInvalidError.prototype);
+    }
+}
+exports.AuthlyTokenInvalidError = AuthlyTokenInvalidError;

package/dist/models/globals/clients/interfaces/IAuthlyClientOptions.d.ts

@@ -0,0 +1,62 @@
+import type { IAuthlyStorage } from "./IAuthlyStorage";
+/**
+ * @summary Options for initializing the AuthlyClient.
+ */
+interface IAuthlyClientOptions {
+    /**
+     * @summary The base URL of the identity provider.
+     * @example "https://auth.example.com"
+     */
+    readonly issuer: string;
+    /**
+     * @summary The expected audience claim (aud) in the token.
+     * @example "https://app.example.com"
+     */
+    readonly audience: string;
+    /**
+     * @summary The ID of the service in Authly.
+     * @example "1234567890"
+     */
+    readonly serviceId: string;
+    /**
+     * @summary The redirect URI to use for the authorization flow.
+     * @example "https://app.example.com/api/auth/callback"
+     */
+    readonly redirectUri?: string;
+    /**
+     * @summary The storage implementation to use for PKCE state and verifier.
+     * @default localStorage (in browser)
+     */
+    readonly storage?: IAuthlyStorage;
+    /**
+     * @summary The path to the JWKS endpoint relative to the issuer.
+     * @example "/.well-known/jwks.json"
+     * @default "/.well-known/jwks.json"
+     */
+    readonly jwksPath?: string;
+    /**
+     * @summary The path to the authorize endpoint relative to the issuer.
+     * @example "/v1/oauth/authorize"
+     * @default "/authorize"
+     */
+    readonly authorizePath?: string;
+    /**
+     * @summary The path to the token endpoint relative to the issuer.
+     * @example "/v1/oauth/token"
+     * @default "/oauth/token"
+     */
+    readonly tokenPath?: string;
+    /**
+     * @summary The path to the user info endpoint relative to the issuer.
+     * @example "/v1/oauth/userinfo"
+     * @default "/v1/oauth/userinfo"
+     */
+    readonly userInfoPath?: string;
+    /**
+     * @summary A list of allowed signing algorithms.
+     * @example ["RS256"]
+     * @default ["RS256"]
+     */
+    readonly algorithms?: string[];
+}
+export type { IAuthlyClientOptions };

package/dist/models/globals/clients/interfaces/IAuthlyStorage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @summary Interface for storage used by AuthlyClient.
+ */
+export interface IAuthlyStorage {
+    /**
+     * @summary Retrieve an item from storage.
+     * @param _key - The key of the item to retrieve.
+     * @returns The value of the item, or null if not found.
+     */
+    getItem(_key: string): string | null | Promise<string | null>;
+    /**
+     * @summary Add key and value to storage.
+     * @param _key - The key of the item to add.
+     * @param _value - The value of the item to add.
+     */
+    setItem(_key: string, _value: string): void | Promise<void>;
+    /**
+     * @summary Remove an item from storage.
+     * @param _key - The key of the item to remove.
+     */
+    removeItem(_key: string): void | Promise<void>;
+}

package/dist/models/globals/clients/interfaces/IAuthlyStorage.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/models/globals/clients/interfaces/IAuthorizeUrlOptions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @summary Options for generating an authorization URL.
+ */
+interface IAuthorizeUrlOptions {
+    /**
+     * @summary The URI to redirect back to after authentication.
+     * @example "https://app.example.com/callback"
+     */
+    readonly redirectUri: string;
+    /**
+     * @summary A unique state string to prevent CSRF.
+     * @example "1234567890"
+     */
+    readonly state: string;
+    /**
+     * @summary The PKCE code challenge.
+     * @example "1234567890"
+     */
+    readonly codeChallenge: string;
+    /**
+     * @summary The PKCE code challenge method.
+     * @example "S256"
+     */
+    readonly codeChallengeMethod?: "S256" | "plain";
+    /**
+     * @summary The requested scopes.
+     * @example "openid profile email"
+     */
+    readonly scope?: string;
+    /**
+     * @summary The OAuth2 response type.
+     * @example "code"
+     */
+    readonly responseType?: string;
+}
+export type { IAuthorizeUrlOptions };

package/dist/models/globals/clients/interfaces/IAuthorizeUrlOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/models/globals/clients/interfaces/IDecodedTokenClaim.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @summary Interface for decoded token claims.
+ */
+interface IDecodedTokenClaim {
+    /**
+     * @summary Subject identifier - the unique ID of the user.
+     * @example "1234567890"
+     */
+    readonly sub: string;
+    /**
+     * @summary Issuer identifier - the URL of the identity provider.
+     * @example "https://auth.example.com"
+     */
+    readonly iss: string;
+    /**
+     * @summary Audience(s) for which the token is intended.
+     * @example "https://app.example.com"
+     * @example ["https://app.example.com", "https://app.example.com/api"]
+     */
+    readonly aud: string | string[];
+    /**
+     * @summary Expiration time (Unix timestamp).
+     * @example 1715145600
+     */
+    readonly exp: number;
+    /**
+     * @summary Issued at time (Unix timestamp).
+     * @example 1715145600
+     */
+    readonly iat: number;
+    /**
+     * @summary Session ID identifier.
+     * @example "1234567890"
+     */
+    readonly sid: string;
+    /**
+     * @summary Dictionary of permissions granted to the user, where keys are resource names and values are permission levels.
+     * @example
+     * ```json
+     * {
+     *     "read": 1,
+     *     "write": 0
+     * }
+     * ```
+     */
+    readonly permissions: Record<string, number>;
+    /**
+     * @summary Permission version.
+     * @example 1
+     */
+    readonly pver?: number;
+    /**
+     * @summary Space-separated list of scopes.
+     * @example "openid profile email"
+     */
+    readonly scope?: string;
+    /**
+     * @summary Allow additional claims.
+     * @example
+     * ```json
+     * {
+     *     "custom": "custom-value"
+     * }
+     * ```
+     */
+    readonly [key: string]: unknown;
+}
+export type { IDecodedTokenClaim };

package/dist/models/globals/clients/interfaces/IDecodedTokenClaim.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });