@ziqx/auth 0.0.4 → 1.0.0

package/README.md

@@ -27,6 +27,11 @@ import { ZAuthClient } from "@ziqx/auth";
 
 const auth = new ZAuthClient({
   authKey: "YOUR_AUTH_KEY",
+  redirectUrl: "YOUR_REDIRECT_URL",
+  codeChallenge: "YOUR_CODE_CHALLENGE",
+  // Optional parameters
+  // codeChallengeMethod: "S256",
+  // state: "YOUR_STATE_STRING"
 });
 ```
 
@@ -41,11 +46,29 @@ auth.login(); // Redirects to live auth environment
 If you're working in a development environment, enable dev mode:
 
 ```typescript
-auth.login(true); // Redirects to dev auth environment
+auth.login(true); // Redirects to dev auth environment (http://localhost:3000/zauth)
 ```
 
 ---
 
+## Access Token Exchange
+
+You can use the `ZAuthTokenService` class to exchange an authorization code for an access token.
+
+```typescript
+import { ZAuthTokenService } from "@ziqx/auth";
+
+const tokenService = new ZAuthTokenService();
+
+const tokenData = await tokenService.getAuthToken({
+  authAppKey: "your-app-key",
+  authSecret: "your-app-secret",
+  code: "authorization-code",
+  codeVerifier: "code-verifier",
+  redirectUri: "redirect-uri",
+});
+```
+
 ## Token Validation
 
 You can use the `ZAuthTokenService` class to validate authentication tokens issued by ZIQX.
@@ -73,12 +96,22 @@ if (isValid) {
 #### Constructor
 
 ```typescript
-new ZAuthClient(options: { authKey: string });
+new ZAuthClient(options: {
+  authKey: string;
+  redirectUrl: string;
+  codeChallenge: string;
+  codeChallengeMethod?: string;
+  state?: string;
+});
 ```
 
-| Parameter | Type   | Required | Description                               |
-| --------- | ------ | -------- | ----------------------------------------- |
-| `authKey` | string | ✅ Yes   | Your unique authentication key from ZIQX. |
+| Parameter             | Type   | Required | Description                                                       |
+| --------------------- | ------ | -------- | ----------------------------------------------------------------- |
+| `authKey`             | string | ✅ Yes   | Your unique authentication key from ZIQX.                         |
+| `redirectUrl`         | string | ✅ Yes   | The URL where the user should be redirected after authentication. |
+| `codeChallenge`       | string | ✅ Yes   | The code challenge for PKCE flow.                                 |
+| `codeChallengeMethod` | string | ❌ No    | (Optional) The code challenge method (e.g., "S256").              |
+| `state`               | string | ❌ No    | (Optional) An opaque value used to maintain state.                |
 
 #### Methods
 
@@ -105,21 +138,47 @@ auth.login(true); // Redirects to development portal
 
 ##### `validate(token: string): Promise<boolean>`
 
-Validates a given authentication token with the ZIQX Auth API.
+Validates a given authentication token with the ZIQX Auth API (V1).
 
 | Parameter | Type   | Required | Description                                |
 | --------- | ------ | -------- | ------------------------------------------ |
 | `token`   | string | ✅ Yes   | The authentication token (JWT or similar). |
 
+##### `validateV2(token: string): Promise<boolean>`
+
+Validates a given authentication token with the ZIQX Auth API (V2).
+
+| Parameter | Type   | Required | Description                           |
+| --------- | ------ | -------- | ------------------------------------- |
+| `token`   | string | ✅ Yes   | The authentication token to validate. |
+
+##### `getAuthToken(params: GetAuthTokenParams): Promise<any>`
+
+Exchanges an authorization code for an access token.
+
+**Parameters:**
+
+| Parameter      | Type   | Required | Description                                        |
+| -------------- | ------ | -------- | -------------------------------------------------- |
+| `authAppKey`   | string | ✅ Yes   | The application key.                               |
+| `authSecret`   | string | ✅ Yes   | The application secret.                            |
+| `code`         | string | ✅ Yes   | The authorization code received from the callback. |
+| `codeVerifier` | string | ✅ Yes   | The code verifier used in PKCE.                    |
+| `redirectUri`  | string | ✅ Yes   | The redirect URI used in the initial request.      |
+
 **Example:**
 
 ```typescript
 const tokenService = new ZAuthTokenService();
-const isValid = await tokenService.validate("your-jwt-token");
+const tokenData = await tokenService.getAuthToken({
+  authAppKey: "your-app-key",
+  authSecret: "your-app-secret",
+  code: "authorization-code",
+  codeVerifier: "code-verifier",
+  redirectUri: "redirect-uri",
+});
 ```
 
-Returns `true` if the token is valid and authorized, otherwise `false`.
-
 ---
 
 ## Example Implementation
@@ -127,7 +186,11 @@ Returns `true` if the token is valid and authorized, otherwise `false`.
 ```typescript
 import { ZAuthClient, ZAuthTokenService } from "@ziqx/auth";
 
-const auth = new ZAuthClient({ authKey: "12345-xyz" });
+const auth = new ZAuthClient({
+  authKey: "12345-xyz",
+  redirectUrl: "https://myapp.com/callback",
+  codeChallenge: "pkce-challenge-string",
+});
 
 // Login
 const loginBtn = document.getElementById("loginBtn");
@@ -140,7 +203,7 @@ const tokenService = new ZAuthTokenService();
 const token = localStorage.getItem("ziqx_token");
 
 if (token) {
-  const isValid = await tokenService.validate(token);
+  const isValid = await tokenService.validateV2(token);
   console.log("Token valid:", isValid);
 }
 ```
@@ -151,7 +214,7 @@ if (token) {
 
 - Make sure your `authKey` is valid and corresponds to your environment.
 - Use `auth.login(true)` in development mode (e.g., on localhost or staging).
-- The `ZAuthTokenService` uses `https://ziqx.cc/api/auth/validate-token` internally.
+- The `ZAuthTokenService` uses `https://ziqx.cc/api/auth/validate-token` internally for V1 and `https://ziqx.cc/zauth/validate` for V2.
 - This SDK is for **client-side use** only.
 
 ---

package/dist/index.d.mts

@@ -1,49 +1,63 @@
 /**
  * ZAuthClient - A lightweight authentication client for ZIQX Auth.
  *
- * This class helps redirect users to the ZIQX authentication gateway.
+ * This class facilitates redirection to the ZIQX authentication gateway.
  *
  * Example:
  * ```ts
  * import { ZAuthClient } from "@ziqx/auth";
  *
  * const auth = new ZAuthClient({
- *   authKey: "your-auth-key"
+ *   authKey: "your-auth-key",
+ *   redirectUrl: "http://localhost:3000/callback",
+ *   codeChallenge: "your-code-challenge"
  * });
  *
  * // Redirects user to ZIQX Auth
  * auth.login();
  *
- * // For development mode
+ * // For development mode (redirects to localhost)
  * auth.login(true);
  * ```
  */
 declare class ZAuthClient {
     private authKey;
+    private redirectUrl;
+    private codeChallenge;
+    private codeChallengeMethod?;
+    private state?;
     /**
      * Creates a new ZAuthClient instance.
      *
      * @param options - The configuration options.
      * @param options.authKey - The authentication key provided by ZIQX.
+     * @param options.redirectUrl - The URL where the user should be redirected after authentication.
+     * @param options.codeChallenge - The code challenge for PKCE flow.
+     * @param options.codeChallengeMethod - (Optional) The code challenge method (e.g., "S256"). Default is "plaintext".
+     * @param options.state - (Optional) An opaque value used to maintain state between the request and the callback.
+     * @throws Will throw an error if `authKey`, `redirectUrl`, or `codeChallenge` are missing.
      */
-    constructor({ authKey }: {
+    constructor({ authKey, redirectUrl, codeChallenge, codeChallengeMethod, state, }: {
         authKey: string;
+        redirectUrl: string;
+        codeChallenge: string;
+        codeChallengeMethod?: string;
+        state?: string;
     });
     /**
      * Redirects the user to the ZIQX authentication page.
-     *
-     * @param isDev - (Optional) Set to `true` to use development mode. Defaults to `false`.
-     *
-     * @example
-     * ```ts
-     * const client = new ZAuthClient({ authKey: "your-auth-key" });
-     * client.login(); // Redirects to production auth page
-     * client.login(true); // Redirects to development auth page
-     * ```
      */
-    login(isDev?: boolean): void;
+    login(): void;
 }
 
+type GetAuthTokenParams = {
+    authAppKey: string;
+    authSecret: string;
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+};
+
 /**
  * ZAuthTokenService - A simple token validation service for ZIQX Auth.
  *
@@ -77,6 +91,18 @@ declare class ZAuthTokenService {
      * ```
      */
     validate(token: string): Promise<boolean>;
+    /**
+     * Exchanges an authorization code for an access token.
+     *
+     * @param params - The parameters required to exchange the code for a token.
+     * @param params.authAppKey - The application key.
+     * @param params.authSecret - The application secret.
+     * @param params.code - The authorization code received from the callback.
+     * @param params.codeVerifier - The code verifier used in PKCE.
+     * @param params.redirectUri - The redirect URI used in the initial request.
+     * @returns A Promise that resolves to the token response data.
+     */
+    getAuthToken({ authAppKey, authSecret, code, codeVerifier, redirectUri, }: GetAuthTokenParams): Promise<any>;
 }
 
 export { ZAuthClient, ZAuthTokenService };

package/dist/index.d.ts

@@ -1,49 +1,63 @@
 /**
  * ZAuthClient - A lightweight authentication client for ZIQX Auth.
  *
- * This class helps redirect users to the ZIQX authentication gateway.
+ * This class facilitates redirection to the ZIQX authentication gateway.
  *
  * Example:
  * ```ts
  * import { ZAuthClient } from "@ziqx/auth";
  *
  * const auth = new ZAuthClient({
- *   authKey: "your-auth-key"
+ *   authKey: "your-auth-key",
+ *   redirectUrl: "http://localhost:3000/callback",
+ *   codeChallenge: "your-code-challenge"
  * });
  *
  * // Redirects user to ZIQX Auth
  * auth.login();
  *
- * // For development mode
+ * // For development mode (redirects to localhost)
  * auth.login(true);
  * ```
  */
 declare class ZAuthClient {
     private authKey;
+    private redirectUrl;
+    private codeChallenge;
+    private codeChallengeMethod?;
+    private state?;
     /**
      * Creates a new ZAuthClient instance.
      *
      * @param options - The configuration options.
      * @param options.authKey - The authentication key provided by ZIQX.
+     * @param options.redirectUrl - The URL where the user should be redirected after authentication.
+     * @param options.codeChallenge - The code challenge for PKCE flow.
+     * @param options.codeChallengeMethod - (Optional) The code challenge method (e.g., "S256"). Default is "plaintext".
+     * @param options.state - (Optional) An opaque value used to maintain state between the request and the callback.
+     * @throws Will throw an error if `authKey`, `redirectUrl`, or `codeChallenge` are missing.
      */
-    constructor({ authKey }: {
+    constructor({ authKey, redirectUrl, codeChallenge, codeChallengeMethod, state, }: {
         authKey: string;
+        redirectUrl: string;
+        codeChallenge: string;
+        codeChallengeMethod?: string;
+        state?: string;
     });
     /**
      * Redirects the user to the ZIQX authentication page.
-     *
-     * @param isDev - (Optional) Set to `true` to use development mode. Defaults to `false`.
-     *
-     * @example
-     * ```ts
-     * const client = new ZAuthClient({ authKey: "your-auth-key" });
-     * client.login(); // Redirects to production auth page
-     * client.login(true); // Redirects to development auth page
-     * ```
      */
-    login(isDev?: boolean): void;
+    login(): void;
 }
 
+type GetAuthTokenParams = {
+    authAppKey: string;
+    authSecret: string;
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+};
+
 /**
  * ZAuthTokenService - A simple token validation service for ZIQX Auth.
  *
@@ -77,6 +91,18 @@ declare class ZAuthTokenService {
      * ```
      */
     validate(token: string): Promise<boolean>;
+    /**
+     * Exchanges an authorization code for an access token.
+     *
+     * @param params - The parameters required to exchange the code for a token.
+     * @param params.authAppKey - The application key.
+     * @param params.authSecret - The application secret.
+     * @param params.code - The authorization code received from the callback.
+     * @param params.codeVerifier - The code verifier used in PKCE.
+     * @param params.redirectUri - The redirect URI used in the initial request.
+     * @returns A Promise that resolves to the token response data.
+     */
+    getAuthToken({ authAppKey, authSecret, code, codeVerifier, redirectUri, }: GetAuthTokenParams): Promise<any>;
 }
 
 export { ZAuthClient, ZAuthTokenService };

package/dist/index.js

@@ -27,38 +27,52 @@ module.exports = __toCommonJS(src_exports);
 
 // src/constants.ts
 var ZAUTH_BASE_URL = "https://ziqx.cc/zauth";
-var VALIDATION_URL = "https://ziqx.cc/api/auth/validate-token";
+var TOKEN_URL = "https://ziqx.cc/zauth/token";
+var VALIDATION_URL_V2 = "https://ziqx.cc/zauth/validate";
 
 // src/ZAuthClient.ts
 var ZAuthClient = class {
   authKey;
+  redirectUrl;
+  codeChallenge;
+  codeChallengeMethod;
+  state;
   /**
    * Creates a new ZAuthClient instance.
    *
    * @param options - The configuration options.
    * @param options.authKey - The authentication key provided by ZIQX.
+   * @param options.redirectUrl - The URL where the user should be redirected after authentication.
+   * @param options.codeChallenge - The code challenge for PKCE flow.
+   * @param options.codeChallengeMethod - (Optional) The code challenge method (e.g., "S256"). Default is "plaintext".
+   * @param options.state - (Optional) An opaque value used to maintain state between the request and the callback.
+   * @throws Will throw an error if `authKey`, `redirectUrl`, or `codeChallenge` are missing.
    */
-  constructor({ authKey }) {
-    if (!authKey) {
-      throw new Error("ZAuthClient: authKey is required.");
+  constructor({
+    authKey,
+    redirectUrl,
+    codeChallenge,
+    codeChallengeMethod,
+    state
+  }) {
+    if (!authKey || !redirectUrl || !codeChallenge) {
+      throw new Error(
+        "ZAuthClient: Missing required parameters. `authKey`, `redirectUrl`, and `codeChallenge` are required."
+      );
     }
     this.authKey = authKey;
+    this.redirectUrl = redirectUrl;
+    this.codeChallenge = codeChallenge;
+    this.codeChallengeMethod = codeChallengeMethod;
+    this.state = state;
   }
   /**
    * Redirects the user to the ZIQX authentication page.
-   *
-   * @param isDev - (Optional) Set to `true` to use development mode. Defaults to `false`.
-   *
-   * @example
-   * ```ts
-   * const client = new ZAuthClient({ authKey: "your-auth-key" });
-   * client.login(); // Redirects to production auth page
-   * client.login(true); // Redirects to development auth page
-   * ```
    */
-  login(isDev = false) {
-    const devQuery = isDev ? "&dev=true" : "";
-    const loginUrl = `${ZAUTH_BASE_URL}?key=${this.authKey}${devQuery}`;
+  login() {
+    const stateQuery = this.state ? `&state=${this.state}` : "";
+    const codeChallengeMethodQuery = this.codeChallengeMethod ? `&challenge_method=${this.codeChallengeMethod}` : "";
+    const loginUrl = `${ZAUTH_BASE_URL}?key=${this.authKey}&redir=${this.redirectUrl}&code_challenge=${this.codeChallenge}${codeChallengeMethodQuery}${stateQuery}`;
     window.location.href = loginUrl;
   }
 };
@@ -82,7 +96,7 @@ var ZAuthTokenService = class {
       throw new Error("ZAuthTokenService: token is required for validation.");
     }
     try {
-      const response = await fetch(VALIDATION_URL, {
+      const response = await fetch(VALIDATION_URL_V2, {
         method: "GET",
         headers: {
           Authorization: token
@@ -97,6 +111,44 @@ var ZAuthTokenService = class {
       return false;
     }
   }
+  /**
+   * Exchanges an authorization code for an access token.
+   *
+   * @param params - The parameters required to exchange the code for a token.
+   * @param params.authAppKey - The application key.
+   * @param params.authSecret - The application secret.
+   * @param params.code - The authorization code received from the callback.
+   * @param params.codeVerifier - The code verifier used in PKCE.
+   * @param params.redirectUri - The redirect URI used in the initial request.
+   * @returns A Promise that resolves to the token response data.
+   */
+  async getAuthToken({
+    authAppKey,
+    authSecret,
+    code,
+    codeVerifier,
+    redirectUri
+  }) {
+    if (!authAppKey || !authSecret || !code || !codeVerifier || !redirectUri) {
+      throw new Error("ZAuthTokenService: All parameters are required");
+    }
+    const response = await fetch(TOKEN_URL, {
+      method: "POST",
+      body: JSON.stringify({
+        code,
+        grant_type: "authorization_code",
+        code_verifier: codeVerifier,
+        redirect_uri: redirectUri
+      }),
+      headers: {
+        "Content-Type": "application/json",
+        "x-app-key": authAppKey,
+        "x-app-secret": authSecret
+      }
+    });
+    const data = await response.json();
+    return data;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1,37 +1,51 @@
 // src/constants.ts
 var ZAUTH_BASE_URL = "https://ziqx.cc/zauth";
-var VALIDATION_URL = "https://ziqx.cc/api/auth/validate-token";
+var TOKEN_URL = "https://ziqx.cc/zauth/token";
+var VALIDATION_URL_V2 = "https://ziqx.cc/zauth/validate";
 
 // src/ZAuthClient.ts
 var ZAuthClient = class {
   authKey;
+  redirectUrl;
+  codeChallenge;
+  codeChallengeMethod;
+  state;
   /**
    * Creates a new ZAuthClient instance.
    *
    * @param options - The configuration options.
    * @param options.authKey - The authentication key provided by ZIQX.
+   * @param options.redirectUrl - The URL where the user should be redirected after authentication.
+   * @param options.codeChallenge - The code challenge for PKCE flow.
+   * @param options.codeChallengeMethod - (Optional) The code challenge method (e.g., "S256"). Default is "plaintext".
+   * @param options.state - (Optional) An opaque value used to maintain state between the request and the callback.
+   * @throws Will throw an error if `authKey`, `redirectUrl`, or `codeChallenge` are missing.
    */
-  constructor({ authKey }) {
-    if (!authKey) {
-      throw new Error("ZAuthClient: authKey is required.");
+  constructor({
+    authKey,
+    redirectUrl,
+    codeChallenge,
+    codeChallengeMethod,
+    state
+  }) {
+    if (!authKey || !redirectUrl || !codeChallenge) {
+      throw new Error(
+        "ZAuthClient: Missing required parameters. `authKey`, `redirectUrl`, and `codeChallenge` are required."
+      );
     }
     this.authKey = authKey;
+    this.redirectUrl = redirectUrl;
+    this.codeChallenge = codeChallenge;
+    this.codeChallengeMethod = codeChallengeMethod;
+    this.state = state;
   }
   /**
    * Redirects the user to the ZIQX authentication page.
-   *
-   * @param isDev - (Optional) Set to `true` to use development mode. Defaults to `false`.
-   *
-   * @example
-   * ```ts
-   * const client = new ZAuthClient({ authKey: "your-auth-key" });
-   * client.login(); // Redirects to production auth page
-   * client.login(true); // Redirects to development auth page
-   * ```
    */
-  login(isDev = false) {
-    const devQuery = isDev ? "&dev=true" : "";
-    const loginUrl = `${ZAUTH_BASE_URL}?key=${this.authKey}${devQuery}`;
+  login() {
+    const stateQuery = this.state ? `&state=${this.state}` : "";
+    const codeChallengeMethodQuery = this.codeChallengeMethod ? `&challenge_method=${this.codeChallengeMethod}` : "";
+    const loginUrl = `${ZAUTH_BASE_URL}?key=${this.authKey}&redir=${this.redirectUrl}&code_challenge=${this.codeChallenge}${codeChallengeMethodQuery}${stateQuery}`;
     window.location.href = loginUrl;
   }
 };
@@ -55,7 +69,7 @@ var ZAuthTokenService = class {
       throw new Error("ZAuthTokenService: token is required for validation.");
     }
     try {
-      const response = await fetch(VALIDATION_URL, {
+      const response = await fetch(VALIDATION_URL_V2, {
         method: "GET",
         headers: {
           Authorization: token
@@ -70,6 +84,44 @@ var ZAuthTokenService = class {
       return false;
     }
   }
+  /**
+   * Exchanges an authorization code for an access token.
+   *
+   * @param params - The parameters required to exchange the code for a token.
+   * @param params.authAppKey - The application key.
+   * @param params.authSecret - The application secret.
+   * @param params.code - The authorization code received from the callback.
+   * @param params.codeVerifier - The code verifier used in PKCE.
+   * @param params.redirectUri - The redirect URI used in the initial request.
+   * @returns A Promise that resolves to the token response data.
+   */
+  async getAuthToken({
+    authAppKey,
+    authSecret,
+    code,
+    codeVerifier,
+    redirectUri
+  }) {
+    if (!authAppKey || !authSecret || !code || !codeVerifier || !redirectUri) {
+      throw new Error("ZAuthTokenService: All parameters are required");
+    }
+    const response = await fetch(TOKEN_URL, {
+      method: "POST",
+      body: JSON.stringify({
+        code,
+        grant_type: "authorization_code",
+        code_verifier: codeVerifier,
+        redirect_uri: redirectUri
+      }),
+      headers: {
+        "Content-Type": "application/json",
+        "x-app-key": authAppKey,
+        "x-app-secret": authSecret
+      }
+    });
+    const data = await response.json();
+    return data;
+  }
 };
 export {
   ZAuthClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziqx/auth",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "description": "SDK for Ziqx Authentication",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",