@authly/sdk 1.0.1 → 1.1.0

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_JWKS_PATH = "/.well-known/jwks.json";
+export declare const DEFAULT_AUTHORIZE_PATH = "/v1/oauth/authorize";
+export declare const DEFAULT_ALGORITHMS: string[];

package/dist/config.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ALGORITHMS = exports.DEFAULT_JWKS_PATH = void 0;
+exports.DEFAULT_ALGORITHMS = exports.DEFAULT_AUTHORIZE_PATH = exports.DEFAULT_JWKS_PATH = void 0;
 exports.DEFAULT_JWKS_PATH = "/.well-known/jwks.json";
+exports.DEFAULT_AUTHORIZE_PATH = "/v1/oauth/authorize";
 exports.DEFAULT_ALGORITHMS = ["RS256"];

package/dist/exceptions/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Base exception for all Authly errors.
+ */
+export declare class AuthlyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base exception for all token errors.
+ */
+export declare class TokenError extends AuthlyError {
+    constructor(message: string);
+}
+/**
+ * Exception raised when a token is invalid:
+ * - bad signature
+ * - bad format
+ * - bad iss / aud
+ */
+export declare class TokenInvalidError extends TokenError {
+    constructor(message: string);
+}
+/**
+ * Exception raised when a token is expired.
+ */
+export declare class TokenExpiredError extends TokenError {
+    constructor(message: string);
+}

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

@@ -0,0 +1,92 @@
+import type { Claims } from "../../models/Claims";
+/**
+ * Options for initializing the AuthlyClient.
+ */
+export interface AuthlyClientOptions {
+    /**
+     * The base URL of the identity provider (e.g., "https://auth.example.com").
+     */
+    issuer: string;
+    /**
+     * The expected audience claim (aud) in the token.
+     */
+    audience: string;
+    /**
+     * The ID of the service in Authly.
+     */
+    serviceId: string;
+    /**
+     * The path to the JWKS endpoint relative to the issuer. Defaults to "/.well-known/jwks.json".
+     */
+    jwksPath?: string;
+    /**
+     * The path to the authorize endpoint relative to the issuer. Defaults to "/v1/oauth/authorize".
+     */
+    authorizePath?: string;
+    /**
+     * A list of allowed signing algorithms. If omitted, defaults to ["RS256"].
+     */
+    algorithms?: string[];
+}
+/**
+ * Options for generating an authorization URL.
+ */
+export interface AuthorizeUrlOptions {
+    /**
+     * The URI to redirect back to after authentication.
+     */
+    redirectUri: string;
+    /**
+     * A unique state string to prevent CSRF.
+     */
+    state: string;
+    /**
+     * The PKCE code challenge.
+     */
+    codeChallenge: string;
+    /**
+     * The PKCE code challenge method. Defaults to "S256".
+     */
+    codeChallengeMethod?: "S256" | "plain";
+    /**
+     * The requested scopes. Defaults to "openid profile email".
+     */
+    scope?: string;
+    /**
+     * The OAuth2 response type. Defaults to "code".
+     */
+    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);
+    /**
+     * 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;
+    /**
+     * Verify a JWT token and return its decoded claims.
+     *
+     * 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).
+     */
+    verify(token: string): Promise<Claims>;
+}

package/dist/globals/clients/AuthlyClient.js

@@ -4,19 +4,22 @@ exports.AuthlyClient = void 0;
 const config_1 = require("../../config");
 const JWTVerifier_1 = require("./internal/JWTVerifier");
 /**
- * A client for verifying Authly JWT tokens.
+ * 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.
+ * fetching the public keys (JWKS) automatically, and provides utilities for
+ * starting the OAuth2 flow.
  */
 class AuthlyClient {
     verifier;
     serviceId;
     issuer;
+    authorizePath;
     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.verifier = new JWTVerifier_1.JWTVerifier({
             issuer: this.issuer,
             audience: options.audience,
@@ -24,6 +27,23 @@ class AuthlyClient {
             algorithms: options.algorithms,
         });
     }
+    /**
+     * Generate the authorization URL to redirect the user to.
+     *
+     * @param options - Options for generating the URL.
+     * @returns The full authorization URL.
+     */
+    getAuthorizeUrl(options) {
+        const url = new URL(`${this.issuer}${this.authorizePath}`);
+        url.searchParams.set("client_id", this.serviceId);
+        url.searchParams.set("redirect_uri", options.redirectUri);
+        url.searchParams.set("response_type", options.responseType || "code");
+        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");
+        return url.toString();
+    }
     /**
      * Verify a JWT token and return its decoded claims.
      *

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

@@ -0,0 +1,50 @@
+import type { IRequestResponseClient } from "../../models/globals/clients/interfaces/IRequestResponseClient";
+/**
+ * A class that provides a static method for making HTTP requests.
+ */
+declare class HttpClient {
+    private constructor();
+    /**
+     * 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.
+     * @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.
+     * @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.
+     * @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.
+     * @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.
+     * @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 delete<D>(url: string, options?: Omit<RequestInit, "method">): Promise<IRequestResponseClient<D>>;
+}
+export { HttpClient };

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

@@ -0,0 +1,26 @@
+import type { JWTVerifyGetKey } from "jose";
+import type { Claims } from "../../../models/Claims";
+/**
+ * Internal class for verifying JWT tokens using jose.
+ */
+export declare class JWTVerifier {
+    private readonly issuer;
+    private readonly audience;
+    private readonly algorithms;
+    private readonly JWKS;
+    constructor(params: {
+        issuer: string;
+        audience: string;
+        jwksUrl: string;
+        algorithms?: string[];
+        jwks?: JWTVerifyGetKey;
+    });
+    /**
+     * Verify the JWT token and return its claims.
+     * @param token - The encoded JWT token string.
+     * @returns The decoded claims from the token.
+     * @throws {TokenExpiredError} If the token's exp claim is in the past.
+     * @throws {TokenInvalidError} If the token is otherwise invalid.
+     */
+    verify(token: string): Promise<Claims>;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./models/Claims";
+export * from "./exceptions";
+export * from "./globals/clients/AuthlyClient";

package/dist/models/Claims.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Decoded JWT claims found in an Authly token.
+ *
+ * This interface contains both standard OIDC claims and Authly-specific claims
+ * like session ID (sid) and permissions.
+ */
+export interface Claims {
+    /**
+     * Subject identifier - the unique ID of the user.
+     */
+    sub: string;
+    /**
+     * Issuer identifier - the URL of the identity provider.
+     */
+    iss: string;
+    /**
+     * Audience(s) for which the token is intended.
+     */
+    aud: string | string[];
+    /**
+     * Expiration time (Unix timestamp).
+     */
+    exp: number;
+    /**
+     * Issued at time (Unix timestamp).
+     */
+    iat: number;
+    /**
+     * Session ID identifier.
+     */
+    sid: string;
+    /**
+     * Dictionary of permissions granted to the user, where keys are resource names and values are permission levels.
+     */
+    permissions: Record<string, number>;
+    /**
+     * Permission version.
+     */
+    pver?: number;
+    /**
+     * Space-separated list of scopes.
+     */
+    scope?: string;
+    /**
+     * Allow additional claims.
+     */
+    [key: string]: unknown;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Represents the error structure from the backend.
+ */
+interface APIError {
+    /**
+     * The error code.
+     */
+    readonly code: string;
+    /**
+     * The error message.
+     */
+    readonly message: string;
+    /**
+     * Optional error details.
+     */
+    readonly details?: unknown;
+}
+/**
+ * Represents the response from a request.
+ * @template D - The type of the data returned from the request.
+ */
+type IRequestResponseClient<D> = {
+    /**
+     * Whether the request was successful.
+     */
+    readonly success: true;
+    /**
+     * The data returned from the request.
+     */
+    readonly data: D;
+    /**
+     * The message returned from the request.
+     */
+    readonly message: string;
+} | {
+    /**
+     * Whether the request was successful.
+     */
+    readonly success: false;
+    /**
+     * The error returned from the request.
+     */
+    readonly error: APIError;
+};
+export type { IRequestResponseClient, APIError };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@authly/sdk",
     "description": "A library for building authentication systems using Authly.",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "author": {
         "name": "Anvoria",
         "url": "https://github.com/Anvoria"