@authly/sdk 1.0.0 → 1.0.2

package/dist/config.d.ts

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

package/dist/config.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ALGORITHMS = exports.DEFAULT_JWKS_PATH = void 0;
+exports.DEFAULT_JWKS_PATH = "/.well-known/jwks.json";
+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/exceptions/index.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenExpiredError = exports.TokenInvalidError = exports.TokenError = exports.AuthlyError = void 0;
+/**
+ * Base exception for all Authly errors.
+ */
+class AuthlyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthlyError";
+    }
+}
+exports.AuthlyError = AuthlyError;
+/**
+ * Base exception for all token errors.
+ */
+class TokenError extends AuthlyError {
+    constructor(message) {
+        super(message);
+        this.name = "TokenError";
+    }
+}
+exports.TokenError = TokenError;
+/**
+ * Exception raised when a token is invalid:
+ * - bad signature
+ * - bad format
+ * - bad iss / aud
+ */
+class TokenInvalidError extends TokenError {
+    constructor(message) {
+        super(message);
+        this.name = "TokenInvalidError";
+    }
+}
+exports.TokenInvalidError = TokenInvalidError;
+/**
+ * Exception raised when a token is expired.
+ */
+class TokenExpiredError extends TokenError {
+    constructor(message) {
+        super(message);
+        this.name = "TokenExpiredError";
+    }
+}
+exports.TokenExpiredError = TokenExpiredError;

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

@@ -0,0 +1,50 @@
+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;
+    /**
+     * A list of allowed signing algorithms. If omitted, defaults to ["RS256"].
+     */
+    algorithms?: string[];
+}
+/**
+ * A client for verifying Authly JWT tokens.
+ *
+ * This client handles the validation of tokens against a specific issuer and audience,
+ * fetching the public keys (JWKS) automatically.
+ */
+export declare class AuthlyClient {
+    private readonly verifier;
+    private readonly serviceId;
+    private readonly issuer;
+    constructor(options: AuthlyClientOptions);
+    /**
+     * 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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthlyClient = void 0;
+const config_1 = require("../../config");
+const JWTVerifier_1 = require("./internal/JWTVerifier");
+/**
+ * A client for verifying Authly JWT tokens.
+ *
+ * This client handles the validation of tokens against a specific issuer and audience,
+ * fetching the public keys (JWKS) automatically.
+ */
+class AuthlyClient {
+    verifier;
+    serviceId;
+    issuer;
+    constructor(options) {
+        this.issuer = options.issuer.replace(/\/$/, "");
+        this.serviceId = options.serviceId;
+        const jwksPath = options.jwksPath || config_1.DEFAULT_JWKS_PATH;
+        this.verifier = new JWTVerifier_1.JWTVerifier({
+            issuer: this.issuer,
+            audience: options.audience,
+            jwksUrl: `${this.issuer}${jwksPath}`,
+            algorithms: options.algorithms,
+        });
+    }
+    /**
+     * 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).
+     */
+    async verify(token) {
+        return this.verifier.verify(token);
+    }
+}
+exports.AuthlyClient = AuthlyClient;

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/globals/clients/internal/JWTVerifier.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JWTVerifier = void 0;
+const jose_1 = require("jose");
+const config_1 = require("../../../config");
+const exceptions_1 = require("../../../exceptions");
+/**
+ * Internal class for verifying JWT tokens using jose.
+ */
+class JWTVerifier {
+    issuer;
+    audience;
+    algorithms;
+    JWKS;
+    constructor(params) {
+        this.issuer = params.issuer;
+        this.audience = params.audience;
+        this.algorithms = params.algorithms || config_1.DEFAULT_ALGORITHMS;
+        this.JWKS = params.jwks || (0, jose_1.createRemoteJWKSet)(new URL(params.jwksUrl));
+    }
+    /**
+     * 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.
+     */
+    async verify(token) {
+        try {
+            const options = {
+                issuer: this.issuer,
+                audience: this.audience,
+                algorithms: this.algorithms,
+            };
+            const { payload } = await (0, jose_1.jwtVerify)(token, this.JWKS, options);
+            return payload;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                const code = error.code;
+                if (code === "ERR_JWT_EXPIRED") {
+                    throw new exceptions_1.TokenExpiredError("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 exceptions_1.TokenInvalidError(error.message || "Token validation failed");
+                }
+            }
+            throw new exceptions_1.TokenInvalidError("Invalid token");
+        }
+    }
+}
+exports.JWTVerifier = JWTVerifier;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,2 +1,19 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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);
+__exportStar(require("./globals/clients/AuthlyClient"), exports);

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/Claims.js

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

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.0",
+    "version": "1.0.2",
     "author": {
         "name": "Anvoria",
         "url": "https://github.com/Anvoria"
@@ -9,7 +9,7 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/Anvoria/authly-sdk-ts.git"
+        "url": "git+https://github.com/Anvoria/authly-sdk-ts.git"
     },
     "homepage": "https://github.com/Anvoria/authly-sdk-ts",
     "bugs": {
@@ -67,5 +67,8 @@
         "tsx": "^4.21.0",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.50.0"
+    },
+    "dependencies": {
+        "jose": "^6.1.3"
     }
 }