@payello-module/jwt 1.20240419.1635 → 1.20240419.2346

package/dist/{src/JwtError.d.ts → JwtError.d.ts}

@@ -1,4 +1,5 @@
 export declare class JwtError extends Error {
     type: "@payello/module-jwt#JwtError";
+    name: string;
     constructor(message: string, options?: ErrorOptions);
 }

package/dist/{src/JwtError.js → JwtError.js}

@@ -1,5 +1,6 @@
 export class JwtError extends Error {
     type = "@payello/module-jwt#JwtError";
+    name = "JwtError";
     constructor(message, options) {
         super(message, options);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payello-module/jwt",
-  "version": "1.20240419.1635",
+  "version": "1.20240419.2346",
   "author": "Payello <devsupport@payello.com> (https://payello.com/)",
   "displayName": "@payello-module/jwt",
   "description": "JSON Web Token Module",
@@ -18,12 +18,5 @@
   "files": [
     "dist/*"
   ],
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "https://git.fuse.hk/payello/dev/payello-module/jwt"
-  },
-  "dependencies": {
-    "@payello-module/encryption": "^0.1.3"
-  }
+  "license": "UNLICENSED"
 }

package/readme.md

@@ -1,14 +1,31 @@
 # JWT Module
 
-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.
+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 a variety of hashing algorithms.
 
 ## Features
 
+- **Generate key pairs:** Create keys for all supported algorithms.
 - **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.
+- **Extract JWTs:** Extract the header, payload, and signature from a JWT.
+- **Verify JWT Signature:** Verify the signature of a JWT against a verify key.
+
+### Supported algorithms
+This package supports all algorithms defined in [RFC 7518 (JSON Web Algorithms (JWA))](https://datatracker.ietf.org/doc/html/rfc7518).
+
+| Algorithm | Description |
+|-----------|-------------|
+| `HS256`   | HMAC using SHA-256 |
+| `HS384`   | HMAC using SHA-384 |
+| `HS512`   | HMAC using SHA-512 |
+| `RS256`   | RSASSA-PKCS1-v1_5 using SHA-256 |
+| `RS384`   | RSASSA-PKCS1-v1_5 using SHA-384 |
+| `RS512`   | RSASSA-PKCS1-v1_5 using SHA-512 |
+| `ES256`   | ECDSA using P-256 and SHA-256 |
+| `ES384`   | ECDSA using P-384 and SHA-384 |
+| `ES512`   | ECDSA using P-521 and SHA-512 |
+| `PS256`   | RSASSA-PSS using SHA-256 and MGF1 with SHA-256 |
+| `PS384`   | RSASSA-PSS using SHA-384 and MGF1 with SHA-384 |
+| `PS512`   | RSASSA-PSS using SHA-512 and MGF1 with SHA-512 |
 
 ## Installation
 
@@ -22,19 +39,33 @@ yarn add @payello-module/jwt
 
 ## Usage
 
+### Generating Key Pairs
+
+To generate a key pair for a specific algorithm, you can use the `generateKeys` method:
+
+```typescript
+import { JWT } from '@payello-module/jwt';
+
+const alg = 'RS256'; // or any other supported algorithm
+
+JWT.generateKeys(alg)
+  .then(keyPair => {
+    console.log('Sign Key (Private Key):', keyPair.sign.base64);
+    console.log('Verify Key (Public Key):', keyPair.verify.base64);
+  })
+  .catch(error => console.error(error));
+```
+
 ### 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'
-};
+const alg = 'HS512'; // or any other supported algorithm
+const key = 'your_signing_key';
 
-JWT.sign(payload, options)
+JWT.sign(payload, alg, key)
   .then(token => console.log(token))
   .catch(error => console.error(error));
 ```
@@ -59,29 +90,41 @@ JWT.extract(token)
 import { JWT } from '@payello-module/jwt';
 
 const token = 'your.jwt.token';
-const getSecretKey = async (issuer) => {
-  // Logic to retrieve the secret key for a given issuer
-  return 'secret_key';
+const getVerifyKey = async (header, payload) => {
+  // Logic to retrieve the verification key for the given header and payload
+  return 'verify_key';
 };
 
-JWT.verify(token, { getSecretKey })
-  .then(isVerified => console.log(isVerified))
+JWT.verifySignature(token, getVerifyKey)
+  .then(({ verified, extracted }) => {
+    if (verified) {
+      console.log('JWT is verified');
+      console.log(extracted);
+    } else {
+      console.log('JWT verification failed');
+    }
+  })
   .catch(error => console.error(error));
 ```
 
 ## API Reference
 
-#### `JWT.sign(payload: any, options: JwtSignOpts): Promise<string>`
+#### `JWT.generateKeys(alg?: JWTAlgorithm): Promise<JWTKeyPair>`
+
+Generates a new key pair for the given algorithm. If no algorithm is provided, it defaults to "HS256" (HMAC with SHA-256).
+
+#### `JWT.sign(payload: JWTPayload, alg: JWTAlgorithm, key: string | BufferSource): Promise<string>`
 
 Signs the provided payload and returns a JWT string.
 
-#### `JWT.extract(input: string, opts: JwtExtractOpts): Promise<JwtExtract>`
+#### `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>`
+#### `JWT.verifySignature(token: string, getVerifyKey: (header: JwtHeader, payload: JWTPayload) => Promise<BufferSource | string> | BufferSource | string, throwErrors?: boolean): Promise<{ verified: boolean, extracted: JwtExtract | null }>`
+
+Verifies a JWT string by checking the signature using the provided verification key. If `throwErrors` is set to `true`, it will throw a `JwtError` if the token is not valid.
 
-Verifies a JWT string against a secret key retrieved by the `getSecretKey` function.
 
 ## Contributing
 

package/dist/test/test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/test.js

@@ -1,46 +0,0 @@
-import { JWT } from "../src/JWT";
-import { JWTAlgorithms } from "../src/JWTAlgorithms";
-/**
- * Ensures that verification works for all algorithms
- */
-async function Test1() {
-    for (let key of Object.keys(JWTAlgorithms)) {
-        console.log("ALG: ", key);
-        const keys = await JWT.generateKeys(key);
-        console.log("KEYS: ", keys);
-        const signed = await JWT.sign({ iss: "Hello" }, key, keys.sign.base64);
-        console.log("SIGNED: ", signed);
-        const verify = await JWT.verifySignature(signed, () => { return keys.verify.base64; });
-        console.log("VERIFIED: ", verify);
-        if (!verify.verified) {
-            throw new Error("Not verified!");
-        }
-        console.log("----");
-    }
-}
-/**
- * Ensures that signature manipulation fails for all algorithms
- */
-async function Test2() {
-    for (let key of Object.keys(JWTAlgorithms)) {
-        console.log("ALG: ", key);
-        const keys = await JWT.generateKeys(key);
-        console.log("KEYS: ", keys);
-        const signed = await JWT.sign({ iss: "Hello" }, key, keys.sign.base64);
-        console.log("SIGNED: ", signed);
-        const signed2 = await JWT.sign({ iss: "Hello there" }, key, keys.sign.base64);
-        console.log("SIGNED2: ", signed);
-        const token = signed.split('.').map(x => (val, index) => {
-            if (index == 2)
-                return signed2.split('.')[index];
-            return val;
-        }).join('.');
-        const verify = await JWT.verifySignature(token, () => { return keys.verify.base64; });
-        console.log("VERIFIED: ", verify);
-        if (verify.verified) {
-            throw new Error("Somehow verified (shouldn't be)");
-        }
-        console.log("----");
-    }
-}
-Test1();