timebasedcipher 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Deb Kalyan Mohanty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# timebasedcipher
+
+A lightweight, isomorphic (**Node + Browser**) library for **time-based rotating AES encryption** with optional **JWT-based key validation**.
+
+Built with [`crypto-js`](https://www.npmjs.com/package/crypto-js), this package provides a simple interface to:
+
+- Generate **time-based rotating AES keys**
+- Encrypt and decrypt JavaScript objects or strings
+- Validate JWTs before key derivation (optional)
+- Works seamlessly in both **frontend** and **backend** environments
+
+---
+
+## Installation
+
+```bash
+npm install timebasedcipher crypto-js
+# or
+yarn add timebasedcipher crypto-js
+# or
+pnpm add timebasedcipher crypto-js
+```
+
+---
+
+## Quick Start
+
+```ts
+import { generateKey, encrypt, decrypt } from "timebasedcipher";
+
+const sharedSecret = "mySuperSecret";
+const intervalSeconds = 60; // key changes every 60 seconds
+
+// Step 1: Generate a rotating key
+const key = generateKey(sharedSecret, intervalSeconds);
+console.log("Generated Key:", key);
+
+// Step 2: Encrypt some data
+const data = { user: "Deb", role: "admin", timestamp: Date.now() };
+const cipher = encrypt(data, key);
+console.log("Encrypted:", cipher);
+
+// Step 3: Decrypt it
+const decrypted = decrypt(cipher, key);
+console.log("Decrypted:", decrypted);
+```
+
+Works in both **Node.js** and **browser** environments.
+
+---
+
+## Function Reference
+
+### `generateKey(sharedSecretOrJwt: string, interval: number, isJwt?: boolean): string`
+
+Generates a **SHA-256 key** that rotates every `interval` seconds.
+When `isJwt` is set to `true`, the input is treated as a **JWT string** — its `exp` claim is validated before key derivation.
+
+| Parameter            | Type      | Description                                                                 |
+| -------------------- | --------- | --------------------------------------------------------------------------- |
+| `sharedSecretOrJwt`  | `string`  | A pre-shared secret or a JWT string when `isJwt = true`.                    |
+| `interval`           | `number`  | Time in seconds after which the key rotates.                                |
+| `isJwt` _(optional)_ | `boolean` | When `true`, validates JWT expiry and uses the raw JWT as the secret input. |
+
+**Returns:** `string` — a 64-character hex string (256-bit key).
+
+**Throws:**
+
+- `Error("Invalid JWT: missing payload part")` — malformed token
+- `Error("JWT payload does not contain a valid 'exp' claim")`
+- `Error("JWT is expired")`
+
+#### Example (with JWT validation)
+
+```ts
+const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // your JWT
+const interval = 120;
+
+const key = generateKey(jwt, interval, true); // validates exp claim
+```
+
+---
+
+### `encrypt(data: any, encryptionKeyHex: string): string`
+
+Encrypts any serializable JavaScript object or string using **AES-256-CBC**.
+
+| Parameter          | Type     | Description                                       |
+| ------------------ | -------- | ------------------------------------------------- |
+| `data`             | `any`    | The object or value to encrypt.                   |
+| `encryptionKeyHex` | `string` | 64-character hex string key (from `generateKey`). |
+
+**Returns:**
+A string in format:
+
+```
+cipherHex:ivHex
+```
+
+---
+
+### `decrypt(cipherText: string, encryptionKeyHex: string): any`
+
+Decrypts ciphertext previously produced by `encrypt`.
+
+| Parameter          | Type     | Description                                             |
+| ------------------ | -------- | ------------------------------------------------------- |
+| `cipherText`       | `string` | Ciphertext in `"cipherHex:ivHex"` format.               |
+| `encryptionKeyHex` | `string` | 64-character hex string key (same key used to encrypt). |
+
+**Returns:**
+The decrypted JavaScript value (automatically parsed from JSON).
+
+**Throws:**
+
+- `Error("Invalid cipher format, expected cipherHex:ivHex")`
+- `Error("Decryption produced empty string")`
+- `Error("Unable to decrypt: no valid key found or invalid payload")`
+
+---
+
+## ⚙️ How It Works
+
+- The key **rotates** every defined interval (e.g., every 60 seconds)
+
+- Derived using:
+
+  ```
+  SHA256(`${secretInput}:${timeSlot}`)
+  ```
+
+  where
+  `timeSlot = floor(Date.now() / (interval * 1000) + 1000)`
+
+- AES encryption uses:
+
+  - **AES-256-CBC**
+  - **PKCS#7 padding**
+  - **Random 16-byte IV**
+
+- Encrypted output format:
+
+  ```
+  <cipherHex>:<ivHex>
+  ```
+
+**Both ends** must:
+
+- Use the **same secret** (or JWT)
+- Use the **same rotation interval**
+- Have **roughly synchronized clocks** (within ±1 interval)
+
+---
+
+## Handling Key Rotation Drift
+
+If decryption fails due to slight clock drift, try nearby intervals:
+
+```ts
+const now = Date.now();
+const interval = 60;
+const secret = "mySuperSecret";
+
+const currentKey = generateKey(secret, interval);
+const prevKey = generateKey(secret, interval); // simulate earlier slot
+const nextKey = generateKey(secret, interval); // simulate next slot
+
+try {
+  return decrypt(cipher, currentKey);
+} catch {
+  try {
+    return decrypt(cipher, prevKey);
+  } catch {
+    return decrypt(cipher, nextKey);
+  }
+}
+```
+
+---
+
+## Browser + Node Compatibility
+
+| Environment     | Supported | Notes                                      |
+| --------------- | --------- | ------------------------------------------ |
+| Node.js         | ✅        | Uses `crypto-js`, no native crypto needed  |
+| React / Browser | ✅        | Fully supported                            |
+| Next.js         | ✅        | Works in both server and client components |
+
+---
+
+## Security Notes
+
+- AES-256-CBC provides **confidentiality**, not integrity — consider adding an **HMAC** if you need tamper detection.
+- Avoid embedding secrets in frontend code — end users can access them.
+- JWT mode only validates the `exp` claim.
+
+---
+
+## Requirements
+
+- Node.js ≥ 14 or any modern browser
+- `crypto-js` dependency (installed automatically)
+
+---
+
+## License
+
+MIT License © 2025 [Deb Kalyan Mohanty](https://github.com/debkalyanmohanty)

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generate a time-based rotating key (SHA256 hash of sharedSecret + current interval).
+ *
+ * The key is derived from:
+ *   SHA256(`${secretInput}:${timeSlot}`)
+ * where:
+ *   timeSlot = floor(Date.now() / (interval * 1000) + 1000)
+ *
+ * When `isJwt` is true:
+ *   - `sharedSecretOrJwt` is treated as a JWT string
+ *   - The JWT payload is decoded
+ *   - The `exp` claim (if present) is checked against current time
+ *   - If the JWT is expired, an error is thrown and no key is generated
+ *   - The *raw JWT string* is still used as the secret input for key derivation
+ *
+ * @param sharedSecretOrJwt - A pre-shared secret string, or a JWT when `isJwt` is true.
+ * @param interval - The rotation interval in seconds. The timeSlot calculation
+ *                   is based on this value, so both sides must use the same interval.
+ * @param isJwt - Optional flag (default: false). When true, `sharedSecretOrJwt` is
+ *                treated as a JWT and its `exp` is validated before deriving the key.
+ * @returns A 64-character hexadecimal SHA-256 hash string to be used as an AES-256 key.
+ * @throws If `isJwt` is true and the JWT is malformed or expired.
+ */
+export declare const generateKey: (sharedSecretOrJwt: string, interval: number, isJwt?: boolean) => string;
+/**
+ * Encrypt an arbitrary JavaScript value using AES-256-CBC with a random IV.
+ *
+ * The function:
+ *   - JSON stringifies the input `data`
+ *   - Uses the provided hex-encoded key as AES-256 key material
+ *   - Generates a random 16-byte IV
+ *   - Encrypts using AES-256-CBC
+ *   - Returns a concatenated string in the format: "cipherHex:ivHex"
+ *
+ * @param data - Any serializable JavaScript value (e.g. object, array, string) to encrypt.
+ * @param encryptionKeyHex - A 64-character hex string representing a 32-byte key
+ *                           (typically the output of {@link generateKey}).
+ * @returns A string in the format `"cipherHex:ivHex"` where both parts are hex-encoded.
+ * @throws If encryption fails or JSON serialization fails.
+ */
+export declare const encrypt: (data: any, encryptionKeyHex: string) => string;
+/**
+ * Decrypt an AES-256-CBC ciphertext string produced by {@link encrypt}.
+ *
+ * The function expects the input to be in the format:
+ *   "cipherHex:ivHex"
+ * where:
+ *   - cipherHex is the hex-encoded ciphertext
+ *   - ivHex is the hex-encoded 16-byte IV
+ *
+ * It will:
+ *   - Split and parse the hex components
+ *   - Decrypt using AES-256-CBC with the provided key
+ *   - Parse the resulting UTF-8 JSON back into the original JavaScript value
+ *
+ * @param cipherText - The ciphertext string in the format `"cipherHex:ivHex"`.
+ * @param encryptionKeyHex - A 64-character hex string representing a 32-byte key
+ *                           (must match the key used for encryption).
+ * @returns The decrypted JavaScript value (e.g. object, array, string).
+ * @throws If the format is invalid, decryption fails, or the decrypted output is empty/invalid JSON.
+ */
+export declare const decrypt: (cipherText: string, encryptionKeyHex: string) => unknown;

package/dist/index.js

@@ -0,0 +1,154 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decrypt = exports.encrypt = exports.generateKey = void 0;
+const crypto_js_1 = __importDefault(require("crypto-js"));
+/**
+ * Decode the payload of a JWT without verifying its signature.
+ * Used only to read the `exp` claim (in seconds since epoch).
+ *
+ * @param token - The JWT string (header.payload.signature)
+ * @returns Parsed payload object.
+ * @throws If the token is malformed or payload is not valid JSON.
+ */
+const decodeJwtPayload = (token) => {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+        throw new Error("Invalid JWT: missing payload part");
+    }
+    const base64Url = parts[1];
+    const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+    // Use CryptoJS to decode base64 → UTF-8
+    const wordArray = crypto_js_1.default.enc.Base64.parse(base64);
+    const json = wordArray.toString(crypto_js_1.default.enc.Utf8);
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        throw new Error("Invalid JWT payload JSON");
+    }
+};
+/**
+ * Generate a time-based rotating key (SHA256 hash of sharedSecret + current interval).
+ *
+ * The key is derived from:
+ *   SHA256(`${secretInput}:${timeSlot}`)
+ * where:
+ *   timeSlot = floor(Date.now() / (interval * 1000) + 1000)
+ *
+ * When `isJwt` is true:
+ *   - `sharedSecretOrJwt` is treated as a JWT string
+ *   - The JWT payload is decoded
+ *   - The `exp` claim (if present) is checked against current time
+ *   - If the JWT is expired, an error is thrown and no key is generated
+ *   - The *raw JWT string* is still used as the secret input for key derivation
+ *
+ * @param sharedSecretOrJwt - A pre-shared secret string, or a JWT when `isJwt` is true.
+ * @param interval - The rotation interval in seconds. The timeSlot calculation
+ *                   is based on this value, so both sides must use the same interval.
+ * @param isJwt - Optional flag (default: false). When true, `sharedSecretOrJwt` is
+ *                treated as a JWT and its `exp` is validated before deriving the key.
+ * @returns A 64-character hexadecimal SHA-256 hash string to be used as an AES-256 key.
+ * @throws If `isJwt` is true and the JWT is malformed or expired.
+ */
+const generateKey = (sharedSecretOrJwt, interval, isJwt = false) => {
+    let secretInput = sharedSecretOrJwt;
+    if (isJwt) {
+        const payload = decodeJwtPayload(sharedSecretOrJwt);
+        if (typeof payload.exp !== "number") {
+            throw new Error("JWT payload does not contain a valid 'exp' claim");
+        }
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        if (payload.exp <= nowSeconds) {
+            throw new Error("JWT is expired");
+        }
+    }
+    const timeSlot = Math.floor(Date.now() / (interval * 1000) + 1000);
+    const input = `${secretInput}:${timeSlot}`;
+    // SHA-256 → hex string
+    return crypto_js_1.default.SHA256(input).toString(crypto_js_1.default.enc.Hex);
+};
+exports.generateKey = generateKey;
+/**
+ * Encrypt an arbitrary JavaScript value using AES-256-CBC with a random IV.
+ *
+ * The function:
+ *   - JSON stringifies the input `data`
+ *   - Uses the provided hex-encoded key as AES-256 key material
+ *   - Generates a random 16-byte IV
+ *   - Encrypts using AES-256-CBC
+ *   - Returns a concatenated string in the format: "cipherHex:ivHex"
+ *
+ * @param data - Any serializable JavaScript value (e.g. object, array, string) to encrypt.
+ * @param encryptionKeyHex - A 64-character hex string representing a 32-byte key
+ *                           (typically the output of {@link generateKey}).
+ * @returns A string in the format `"cipherHex:ivHex"` where both parts are hex-encoded.
+ * @throws If encryption fails or JSON serialization fails.
+ */
+const encrypt = (data, encryptionKeyHex) => {
+    const json = JSON.stringify(data);
+    try {
+        // key and IV as WordArray
+        const key = crypto_js_1.default.enc.Hex.parse(encryptionKeyHex); // 32 bytes
+        const iv = crypto_js_1.default.lib.WordArray.random(16); // 16 bytes
+        const encrypted = crypto_js_1.default.AES.encrypt(json, key, { iv });
+        const cipherHex = encrypted.ciphertext.toString(crypto_js_1.default.enc.Hex);
+        const ivHex = iv.toString(crypto_js_1.default.enc.Hex);
+        return `${cipherHex}:${ivHex}`;
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.error("Error in encrypt:", err);
+        throw err;
+    }
+};
+exports.encrypt = encrypt;
+/**
+ * Decrypt an AES-256-CBC ciphertext string produced by {@link encrypt}.
+ *
+ * The function expects the input to be in the format:
+ *   "cipherHex:ivHex"
+ * where:
+ *   - cipherHex is the hex-encoded ciphertext
+ *   - ivHex is the hex-encoded 16-byte IV
+ *
+ * It will:
+ *   - Split and parse the hex components
+ *   - Decrypt using AES-256-CBC with the provided key
+ *   - Parse the resulting UTF-8 JSON back into the original JavaScript value
+ *
+ * @param cipherText - The ciphertext string in the format `"cipherHex:ivHex"`.
+ * @param encryptionKeyHex - A 64-character hex string representing a 32-byte key
+ *                           (must match the key used for encryption).
+ * @returns The decrypted JavaScript value (e.g. object, array, string).
+ * @throws If the format is invalid, decryption fails, or the decrypted output is empty/invalid JSON.
+ */
+const decrypt = (cipherText, encryptionKeyHex) => {
+    const [encryptedHex, ivHex] = cipherText.split(":");
+    if (!ivHex || !encryptedHex) {
+        throw new Error("Invalid cipher format, expected cipherHex:ivHex");
+    }
+    const key = crypto_js_1.default.enc.Hex.parse(encryptionKeyHex);
+    const iv = crypto_js_1.default.enc.Hex.parse(ivHex);
+    const ciphertext = crypto_js_1.default.enc.Hex.parse(encryptedHex);
+    // Proper CipherParams object
+    const cipherParams = crypto_js_1.default.lib.CipherParams.create({
+        ciphertext,
+    });
+    try {
+        const decrypted = crypto_js_1.default.AES.decrypt(cipherParams, key, { iv });
+        const utf8 = decrypted.toString(crypto_js_1.default.enc.Utf8);
+        if (!utf8) {
+            throw new Error("Decryption produced empty string");
+        }
+        return JSON.parse(utf8);
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.error("Error decrypting with current key:", err);
+        throw new Error("Unable to decrypt: no valid key found or invalid payload");
+    }
+};
+exports.decrypt = decrypt;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "timebasedcipher",
+  "version": "3.0.0",
+  "description": "Time-based key generation and AES encryption/decryption SDK",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "crypto",
+    "aes",
+    "encryption",
+    "sdk",
+    "time-based",
+    "cipher",
+    "security",
+    "expiry",
+    "jwt",
+    "jwt based cipher"
+  ],
+  "author": "Vipul Naik & Deb Kalyan Mohanty",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.2",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "crypto-js": "^4.2.0"
+  }
+}