secure-jwtx

🔐 Secure JWT-like token system with AES-GCM encryption and HMAC-SHA256 signing in pure JavaScript.

Features

• AES-GCM encrypted payload (confidentiality)
• HMAC-SHA256 signature (integrity)
• Token expiration support
• Token refresh support
• Works in browsers and Node.js (v15+)

Installation

npm install secure-jwtx


Usage

Browser

1 - Include the library as ES module (via bundler or native <script type="module">):


import SecureJWTx from 'secure-jwtx';

const jwt = new SecureJWTx({
  password: 'your-encryption-password',
  secret: 'your-signing-secret',
  expiry: 3600 // token validity in seconds (1 hour)
});

(async () => {
  const token = await jwt.sign({ user: 'pradeep' });
  console.log('Token:', token);

  const payload = await jwt.verify(token);
  console.log('Payload:', payload);

  const refreshedToken = await jwt.refresh(token);
  console.log('Refreshed Token:', refreshedToken);
})();


Note : Modern browsers support Web Crypto API (crypto.subtle) natively.


Node.js (v15+ recommended)

1 - Ensure your Node.js version is v15 or higher.
2 - Your Node.js environment needs the Web Crypto API available as crypto.subtle. To enable this, add the following at the very start of your main script before importing secure-jwtx:

import { webcrypto } from 'crypto';
global.crypto = webcrypto;  // Polyfill Web Crypto API globally for this runtime

3 - Then import and use the package as usual:

import SecureJWTx from 'secure-jwtx';

const jwt = new SecureJWTx({
  password: 'your-encryption-password',
  secret: 'your-signing-secret',
  expiry: 3600
});

(async () => {
  const token = await jwt.sign({ user: 'pradeep' });
  console.log('Token:', token);

  const payload = await jwt.verify(token);
  console.log('Payload:', payload);

  const refreshedToken = await jwt.refresh(token);
  console.log('Refreshed Token:', refreshedToken);
})();


Note: This step is necessary because Node.js exposes the Web Crypto API under crypto.webcrypto, not as a global crypto by default.

If you omit this, calls to crypto.subtle in the package will fail.

For Node.js versions below 15, upgrade Node.js or run in a browser environment.



| Method                    | Description                                  | Parameters                              | Returns                     |
| ------------------------- | -------------------------------------------- | --------------------------------------- | --------------------------- |
| `new SecureJWTx(options)` | Create a new instance.                       | `options`: `{password, secret, expiry}` | Instance                    |
| `sign(payload)`           | Create a signed and encrypted token.         | `payload`: Object to include in token   | Promise<string> (token)     |
| `verify(token)`           | Verify signature, decrypt, and check expiry. | `token`: token string                   | Promise<Object> (payload)   |
| `refresh(token)`          | Refresh token by resetting expiry.           | `token`: existing token                 | Promise<string> (new token) |




| Option     | Type   | Default | Description                                        |
| ---------- | ------ | ------- | -------------------------------------------------- |
| `password` | string | —       | Secret key used for AES-GCM encryption.            |
| `secret`   | string | —       | Secret key used for HMAC-SHA256 signing.           |
| `expiry`   | number | 3600    | Token expiration time in seconds (default 1 hour). |


Notes : - 
1 - Keep password and secret secure and private.

2 - Do not expose secrets in public frontend code in production.

3 - The package requires a Web Crypto API compatible environment (modern browsers or Node.js 15+).

4 - The token format is similar to JWT but encrypted, making payload confidential.



Troubleshooting: - 
-- crypto.subtle not available?
    Upgrade Node.js to v15+ or run in a browser with Web Crypto API support.

-- Using CommonJS (require)?
   This package uses ES Modules.
   Either enable ES module support ("type": "module") or use a bundler that supports ES modules.

License - 
MIT © Pradeep Sahani