@payello-module/jwt 0.1.1 → 0.1.2

package/dist/JWT.d.ts

@@ -1,9 +1,31 @@
 import { JwtSignOpts } from "./JwtSignOpts";
 import { JwtExtract } from "./JwtExtract";
 import { JwtExtractOpts } from "./JwtExtractOpts";
+/**
+ * Class representing JSON Web Tokens (JWT) functionalities, including signing, extracting components,
+ * and verifying the signature of the token.
+ */
 export declare class JWT {
+    /**
+     * Signs the given payload and returns a JWT string.
+     * @param payload - The payload of the JWT which is the content that you want to protect.
+     * @param options - The options for signing the JWT, including the private key, public key, and algorithm.
+     * @returns A promise that resolves to the signed JWT string.
+     */
     static sign(payload: any, options?: JwtSignOpts): Promise<string>;
+    /**
+     * Extracts and returns the header, payload, and signature components from a JWT string.
+     * @param input - The JWT string to be parsed.
+     * @param opts - Optional parameters, including the requirements for the presence of required properties in the payload.
+     * @returns A promise that resolves to an object containing the separated components of the JWT (header, payload, signature).
+     */
     static extract(input: string, opts?: JwtExtractOpts): Promise<JwtExtract>;
+    /**
+     * Verifies the given JWT string using the secret key fetched by the given issuer.
+     * @param input - The JWT string to be verified.
+     * @param opts - An object containing a function getSecretKey to retrieve the secret key based on the issuer.
+     * @returns A promise that resolves to a boolean indicating whether the JWT has been verified successfully or not.
+     */
     static verify(input: string, opts: {
         getSecretKey(issuer: string): Promise<string>;
     }): Promise<true>;

package/dist/JWT.js

@@ -1,11 +1,22 @@
 import { HmacSha256, HmacSha512 } from "@payello-module/encryption";
 import { JwtError } from "./JwtError";
+/**
+ * Class representing JSON Web Tokens (JWT) functionalities, including signing, extracting components,
+ * and verifying the signature of the token.
+ */
 export class JWT {
+    /**
+     * Signs the given payload and returns a JWT string.
+     * @param payload - The payload of the JWT which is the content that you want to protect.
+     * @param options - The options for signing the JWT, including the private key, public key, and algorithm.
+     * @returns A promise that resolves to the signed JWT string.
+     */
     static async sign(payload, options = { privKey: '', pubKey: '', algorithm: 'HS512' }) {
         const _header = {
             typ: 'JWT',
             alg: options.algorithm
         };
+        // Create payload with unique identifier, issued-at time, and incorporate the public key if provided.
         const _payload = {
             jti: `jti_${Date.now().valueOf()}`,
             iat: Math.floor(Date.now().valueOf() / 1000),
@@ -14,6 +25,7 @@ export class JWT {
         };
         const _body = btoa(JSON.stringify(_header)) + "." + btoa(JSON.stringify(_payload));
         let signature = "";
+        // Create signature based on selected algorithm.
         switch (options.algorithm) {
             case 'HS256':
                 signature = await HmacSha256.encrypt(_body, options.privKey);
@@ -22,10 +34,18 @@ export class JWT {
                 signature = await HmacSha512.encrypt(_body, options.privKey);
                 break;
         }
+        // Returns the final JWT token as a concatenation of header, payload, and signature
         return _body + "." + signature;
     }
+    /**
+     * Extracts and returns the header, payload, and signature components from a JWT string.
+     * @param input - The JWT string to be parsed.
+     * @param opts - Optional parameters, including the requirements for the presence of required properties in the payload.
+     * @returns A promise that resolves to an object containing the separated components of the JWT (header, payload, signature).
+     */
     static async extract(input, opts = {}) {
         const bits = input.split(".");
+        // Ensures that the JWT string has three parts: header, payload, and signature.
         if (bits.length !== 3) {
             throw new JwtError(`Invalid number of parts in JWT string. Expected 3 but got ${bits.length}`);
         }
@@ -37,26 +57,37 @@ export class JWT {
         if (!payload || !payload.jti) {
             throw new JwtError("Payload invalid or missing jti value");
         }
+        // Validates the present of required properties in the payload.
         const requiredProps = opts.requiredProps || ["jti", "iss", "iat"];
         for (const prop in requiredProps) {
             if (!payload[prop]) {
                 throw new JwtError(`Payload missing ${prop} value`);
             }
         }
+        // Returns an object containing the extracted components of the JWT.
         return {
             header: header,
             payload: payload,
             signature: bits[2]
         };
     }
+    /**
+     * Verifies the given JWT string using the secret key fetched by the given issuer.
+     * @param input - The JWT string to be verified.
+     * @param opts - An object containing a function getSecretKey to retrieve the secret key based on the issuer.
+     * @returns A promise that resolves to a boolean indicating whether the JWT has been verified successfully or not.
+     */
     static async verify(input, opts) {
         const extracted = await this.extract(input);
+        // Fetches the secret key based on the issuer in the payload.
         const secretKey = await opts.getSecretKey(extracted.payload.jti);
         if (!secretKey) {
             throw new JwtError(`Public key not found`);
         }
         let verify = false;
+        // Preparation of the data to verify the signature.
         const data = `${btoa(JSON.stringify(extracted.header))}.${btoa(JSON.stringify(extracted.payload))}`;
+        // Verification of the signature based on the algorithm specified in the header.
         switch (extracted.header.alg) {
             case 'HS256':
                 verify = await HmacSha256.verify(data, extracted.signature, secretKey);
@@ -70,6 +101,7 @@ export class JWT {
         if (!verify) {
             throw new JwtError(`Signature not verified`);
         }
+        // Returns the result of the verification process.
         return verify;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@payello-module/jwt",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "author": "Payello <devsupport@payello.com> (https://payello.com/)",
     "displayName": "@payello-module/jwt",
     "description": "JSON Web Token Module",
@@ -23,6 +23,6 @@
         "url": "https://git.fuse.hk/payello/dev/payello-module/jwt"
     },
     "dependencies": {
-        "@payello-module/encryption": "^0.1.2"
+        "@payello-module/encryption": "^0.1.3"
     }
 }

package/readme.md

@@ -1,28 +1,94 @@
 # JWT Module
-JWT Module is used to generate JSON Web Tokens.
+
+This is a TypeScript library for working with JSON Web Tokens (JWT). It provides easy-to-use asynchronous methods to sign, extract, and verify JWTs using HMAC SHA256 and HMAC SHA512 hashing algorithms.
+
+This module relies on the `@payello-module/encryption` package for encryption operations.
+
+## Features
+
+- **Sign JWTs:** Create signed JWTs with custom payloads and options.
+- **Extract JWTs:** Extract the payload, header, and signature from a JWT.
+- **Verify JWTs:** Verify the authenticity of a JWT against a secret key.
+
+## Installation
+
+You can install the module using npm or yarn:
+
+```shell
+npm install @payello-module/jwt
+# or
+yarn add @payello-module/jwt
+```
 
 ## Usage
-First install the module to your project.
+
+### Signing a JWT
+
+```typescript
+import { JWT } from '@payello-module/jwt';
+
+const payload = { /* Your JWT payload here */ };
+const options = {
+  privKey: 'your_private_key',
+  pubKey: 'your_public_key',
+  algorithm: 'HS512' // or 'HS256'
+};
+
+JWT.sign(payload, options)
+  .then(token => console.log(token))
+  .catch(error => console.error(error));
 ```
-npm i @payello-module/jwt
+
+### Extracting a JWT
+
+```typescript
+import { JWT } from '@payello-module/jwt';
+
+const token = 'your.jwt.token';
+
+JWT.extract(token)
+  .then(({ header, payload, signature }) => {
+    console.log(header, payload, signature);
+  })
+  .catch(error => console.error(error));
 ```
 
-Then you can use the JWT Module as below:
-```ts
-import { JWT } from "@payello-module/jwt";
+### Verifying a JWT
 
-const payload = {
-    exp: Math.floor(Date.now().valueOf() / 1000) + 300 // Expire in 300 seconds
-};
+```typescript
+import { JWT } from '@payello-module/jwt';
 
-const opts = {
-    privKey: "79c4e267e63845a986e669388fce66e9", // Secret Key
-    pubKey: "f266a28e-5e9a-4fe3-90a8-2e8b2ef0f62d", // Issuer ID
-    algorithm: "HS256" // Possible values: HS256 or HS512
+const token = 'your.jwt.token';
+const getSecretKey = async (issuer) => {
+  // Logic to retrieve the secret key for a given issuer
+  return 'secret_key';
 };
 
-const jwt = await JWT.sign(payload, opts);
+JWT.verify(token, { getSecretKey })
+  .then(isVerified => console.log(isVerified))
+  .catch(error => console.error(error));
+```
+
+## API Reference
+
+#### `JWT.sign(payload: any, options: JwtSignOpts): Promise<string>`
+
+Signs the provided payload and returns a JWT string.
+
+#### `JWT.extract(input: string, opts: JwtExtractOpts): Promise<JwtExtract>`
+
+Extracts and returns the header, payload, and signature from a JWT string.
+
+#### `JWT.verify(input: string, opts: { getSecretKey(issuer: string): Promise<string> }): Promise<boolean>`
+
+Verifies a JWT string against a secret key retrieved by the `getSecretKey` function.
+
+## Contributing
 
-console.log(jwt);
+We welcome contributions to this module! Please consider the following guidelines when contributing:
 
-```
+1. Fork the repository and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. Ensure your code passes existing tests.
+4. Ensure your code follows the existing code style.
+5. Issue that pull request!