timebasedcipher 3.0.0 → 3.0.1

package/README.md

@@ -1,13 +1,14 @@
 # timebasedcipher
 
-A lightweight, isomorphic (**Node + Browser**) library for **time-based rotating AES encryption** with optional **JWT-based key validation**.
+A lightweight, isomorphic (**Node + Browser**) library for **time-based rotating AES encryption with integrity protection**.
 
-Built with [`crypto-js`](https://www.npmjs.com/package/crypto-js), this package provides a simple interface to:
+Built with [`crypto-js`](https://www.npmjs.com/package/crypto-js), this package provides:
 
-- 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
+- **Time-based rotating AES-256 keys**
+- **AES-256-CBC encryption**
+  -️ **HMAC-SHA256 integrity & tamper detection**
+- **Application-level domain separation (`appName`)**
+- Works in **Node.js and browser environments**
 
 ---
 
@@ -29,180 +30,158 @@ pnpm add timebasedcipher crypto-js
 import { generateKey, encrypt, decrypt } from "timebasedcipher";
 
 const sharedSecret = "mySuperSecret";
-const intervalSeconds = 60; // key changes every 60 seconds
+const intervalSeconds = 60; // key rotates every 60 seconds
 
-// Step 1: Generate a rotating key
+// Generate a rotating key
 const key = generateKey(sharedSecret, intervalSeconds);
-console.log("Generated Key:", key);
 
-// Step 2: Encrypt some data
+// Encrypt data
 const data = { user: "Deb", role: "admin", timestamp: Date.now() };
 const cipher = encrypt(data, key);
-console.log("Encrypted:", cipher);
 
-// Step 3: Decrypt it
+// Decrypt data
 const decrypted = decrypt(cipher, key);
-console.log("Decrypted:", decrypted);
+
+console.log(decrypted);
 ```
 
-Works in both **Node.js** and **browser** environments.
+Works seamlessly 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:**
+### `generateKey(sharedSecretOrJwt: string, interval: number): string`
 
-- `Error("Invalid JWT: missing payload part")` — malformed token
-- `Error("JWT payload does not contain a valid 'exp' claim")`
-- `Error("JWT is expired")`
+Generates a **SHA-256–derived rotating key** that changes every `interval` seconds.
 
-#### Example (with JWT validation)
+- The input can be a **shared secret** or a **JWT string**
+- JWTs are treated as **opaque entropy**
+- **JWT validation (exp, signature)** is expected to be handled upstream
 
-```ts
-const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // your JWT
-const interval = 120;
+#### Parameters
 
-const key = generateKey(jwt, interval, true); // validates exp claim
-```
+| Name                | Type     | Description                   |
+| ------------------- | -------- | ----------------------------- |
+| `sharedSecretOrJwt` | `string` | A shared secret or JWT string |
+| `interval`          | `number` | Rotation interval in seconds  |
 
----
+#### Returns
 
-### `encrypt(data: any, encryptionKeyHex: string): string`
+- `string` — 64-character hex string (32-byte AES-256 key)
 
-Encrypts any serializable JavaScript object or string using **AES-256-CBC**.
+#### Key Derivation
 
-| Parameter          | Type     | Description                                       |
-| ------------------ | -------- | ------------------------------------------------- |
-| `data`             | `any`    | The object or value to encrypt.                   |
-| `encryptionKeyHex` | `string` | 64-character hex string key (from `generateKey`). |
+```text
+SHA256(`${secretInput}:${timeSlot}`)
+```
 
-**Returns:**
-A string in format:
+Where:
 
-```
-cipherHex:ivHex
+```text
+timeSlot = floor(Date.now() / (interval * 1000) + 1000)
 ```
 
 ---
 
-### `decrypt(cipherText: string, encryptionKeyHex: string): any`
+### `encrypt(data: any, encryptionKeyHex: string, appName?: string): string`
 
-Decrypts ciphertext previously produced by `encrypt`.
+Encrypts data using **AES-256-CBC** and appends an **HMAC-SHA256** for integrity.
 
-| Parameter          | Type     | Description                                             |
-| ------------------ | -------- | ------------------------------------------------------- |
-| `cipherText`       | `string` | Ciphertext in `"cipherHex:ivHex"` format.               |
-| `encryptionKeyHex` | `string` | 64-character hex string key (same key used to encrypt). |
+#### Parameters
 
-**Returns:**
-The decrypted JavaScript value (automatically parsed from JSON).
+| Name                   | Type     | Description                        |
+| ---------------------- | -------- | ---------------------------------- |
+| `data`                 | `any`    | Any JSON-serializable value        |
+| `encryptionKeyHex`     | `string` | 64-char hex key from `generateKey` |
+| `appName` _(optional)_ | `string` | Application context                |
 
-**Throws:**
+#### Returns
 
-- `Error("Invalid cipher format, expected cipherHex:ivHex")`
-- `Error("Decryption produced empty string")`
-- `Error("Unable to decrypt: no valid key found or invalid payload")`
+A ciphertext string in the format:
 
----
+```text
+cipherHex:ivHex:hmacHex
+```
 
-## ⚙️ How It Works
+---
 
-- The key **rotates** every defined interval (e.g., every 60 seconds)
+### `decrypt(cipherText: string, encryptionKeyHex: string, appName?: string): any`
 
-- Derived using:
+Decrypts and verifies ciphertext produced by `encrypt`.
 
-  ```
-  SHA256(`${secretInput}:${timeSlot}`)
-  ```
+#### Parameters
 
-  where
-  `timeSlot = floor(Date.now() / (interval * 1000) + 1000)`
+| Name                   | Type     | Description                                  |
+| ---------------------- | -------- | -------------------------------------------- |
+| `cipherText`           | `string` | Encrypted string (`cipherHex:ivHex:hmacHex`) |
+| `encryptionKeyHex`     | `string` | Same key used during encryption              |
+| `appName` _(optional)_ | `string` | Must match encryption appName                |
 
-- AES encryption uses:
+#### Returns
 
-  - **AES-256-CBC**
-  - **PKCS#7 padding**
-  - **Random 16-byte IV**
+- Original decrypted JavaScript value (parsed from JSON)
 
-- Encrypted output format:
+#### Throws
 
-  ```
-  <cipherHex>:<ivHex>
-  ```
+- `Error("Invalid cipher format")`
+- `Error("Invalid HMAC: ciphertext may be tampered")`
+- `Error("Unable to decrypt")`
 
-**Both ends** must:
+---
 
-- Use the **same secret** (or JWT)
-- Use the **same rotation interval**
-- Have **roughly synchronized clocks** (within ±1 interval)
+## Application Context (`appName`)
 
----
+`appName` provides **cryptographic domain separation**.
 
-## Handling Key Rotation Drift
+- Prevents ciphertexts from being reused across apps
+- Prevents MAC key reuse
 
-If decryption fails due to slight clock drift, try nearby intervals:
+### Example
 
 ```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);
-  }
-}
+const key = generateKey(secret, 60);
+
+const cipher = encrypt(data, key, "billing-service");
+const plain = decrypt(cipher, key, "billing-service");
 ```
 
+Using a different `appName` will **fail decryption**.
+
 ---
 
 ## 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 |
+| Environment     | Supported | Notes                      |
+| --------------- | --------- | -------------------------- |
+| Node.js         | ✅        | Uses `crypto-js`           |
+| Browser         | ✅        | Fully supported            |
+| React / Next.js | ✅        | Works client & server-side |
 
 ---
 
 ## 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.
+- Uses **Encrypt-then-MAC** (AES + HMAC) — secure against tampering
+- `appName` ensures **cross-application isolation**
+- JWTs are treated as entropy only — **authentication must happen elsewhere**
+- Do **not** embed secrets in frontend code
+- Requires roughly synchronized clocks
 
 ---
 
 ## Requirements
 
-- Node.js ≥ 14 or any modern browser
-- `crypto-js` dependency (installed automatically)
+- Node.js ≥ 14 or modern browser
+- `crypto-js` dependency
 
 ---
 
 ## License
 
-MIT License © 2025 [Deb Kalyan Mohanty](https://github.com/debkalyanmohanty)
+MIT License © 2026
+[**Deb Kalyan Mohanty**](https://github.com/debkalyanmohanty)
+
+---

package/dist/index.d.ts

@@ -1,62 +1,38 @@
 /**
- * Generate a time-based rotating key (SHA256 hash of sharedSecret + current interval).
+ * Generate a time-based rotating key using SHA-256.
  *
- * The key is derived from:
+ * The key is derived as:
  *   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.
+ * Notes:
+ * - If `sharedSecretOrJwt` is a JWT, it is treated as opaque input
+ * - JWT validation (signature / exp) is assumed to be handled elsewhere
+ * - This function is purely a key-derivation utility
  */
-export declare const generateKey: (sharedSecretOrJwt: string, interval: number, isJwt?: boolean) => string;
+export declare const generateKey: (sharedSecretOrJwt: string, interval: number) => string;
 /**
- * Encrypt an arbitrary JavaScript value using AES-256-CBC with a random IV.
+ * Encrypt arbitrary data using:
+ *   - AES-256-CBC (confidentiality)
+ *   - HMAC-SHA256 (integrity & authenticity)
  *
- * 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"
+ * Cipher format:
+ *   cipherHex:ivHex:hmacHex
  *
- * @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.
+ * `appName`:
+ *   - Included ONLY in HMAC key derivation
+ *   - Ensures ciphertexts are bound to an application context
+ *   - Must match during decryption
  */
-export declare const encrypt: (data: any, encryptionKeyHex: string) => string;
+export declare const encrypt: (data: any, encryptionKeyHex: string, appName?: 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
+ * Decrypt data encrypted by {@link encrypt}.
  *
- * 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
+ * Steps:
+ *   1. Parse cipher format
+ *   2. Recompute and verify HMAC (tamper detection)
+ *   3. Decrypt AES-256-CBC
+ *   4. Parse JSON payload
  *
- * @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.
+ * `appName` MUST match the value used during encryption.
  */
-export declare const decrypt: (cipherText: string, encryptionKeyHex: string) => unknown;
+export declare const decrypt: (cipherText: string, encryptionKeyHex: string, appName?: string) => unknown;

package/dist/index.js

@@ -7,11 +7,9 @@ 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).
+ * Used only to read the `exp` claim (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.
+ * ⚠️ This does NOT verify authenticity — only structure and expiry.
  */
 const decodeJwtPayload = (token) => {
     const parts = token.split(".");
@@ -20,7 +18,6 @@ const decodeJwtPayload = (token) => {
     }
     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 {
@@ -31,112 +28,96 @@ const decodeJwtPayload = (token) => {
     }
 };
 /**
- * Generate a time-based rotating key (SHA256 hash of sharedSecret + current interval).
+ * Derive a dedicated HMAC key from the encryption key.
  *
- * The key is derived from:
- *   SHA256(`${secretInput}:${timeSlot}`)
- * where:
- *   timeSlot = floor(Date.now() / (interval * 1000) + 1000)
+ * `appName` acts as cryptographic context (domain separation):
+ *   - Different apps using the same encryption key will NOT share MAC keys
+ *   - Prevents cross-application replay or substitution attacks
+ *
+ * Default appName = "timebasedcipher" for backward compatibility.
+ */
+const deriveHmacKeyHex = (encryptionKeyHex, appName = "timebasedcipher") => {
+    return crypto_js_1.default.SHA256(`${appName}-hmac:${encryptionKeyHex}`).toString(crypto_js_1.default.enc.Hex);
+};
+/**
+ * Generate a time-based rotating key using SHA-256.
  *
- * 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
+ * The key is derived as:
+ *   SHA256(`${secretInput}:${timeSlot}`)
  *
- * @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.
+ * Notes:
+ * - If `sharedSecretOrJwt` is a JWT, it is treated as opaque input
+ * - JWT validation (signature / exp) is assumed to be handled elsewhere
+ * - This function is purely a key-derivation utility
  */
-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 generateKey = (sharedSecretOrJwt, interval) => {
     const timeSlot = Math.floor(Date.now() / (interval * 1000) + 1000);
-    const input = `${secretInput}:${timeSlot}`;
-    // SHA-256 → hex string
+    const input = `${sharedSecretOrJwt}:${timeSlot}`;
     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.
+ * Encrypt arbitrary data using:
+ *   - AES-256-CBC (confidentiality)
+ *   - HMAC-SHA256 (integrity & authenticity)
  *
- * 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"
+ * Cipher format:
+ *   cipherHex:ivHex:hmacHex
  *
- * @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.
+ * `appName`:
+ *   - Included ONLY in HMAC key derivation
+ *   - Ensures ciphertexts are bound to an application context
+ *   - Must match during decryption
  */
-const encrypt = (data, encryptionKeyHex) => {
+const encrypt = (data, encryptionKeyHex, appName = "timebasedcipher") => {
     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 key = crypto_js_1.default.enc.Hex.parse(encryptionKeyHex);
+        const iv = crypto_js_1.default.lib.WordArray.random(16);
         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}`;
+        // Derive MAC key using encryption key + appName context
+        const hmacKeyHex = deriveHmacKeyHex(encryptionKeyHex, appName);
+        const hmacKey = crypto_js_1.default.enc.Hex.parse(hmacKeyHex);
+        const mac = crypto_js_1.default.HmacSHA256(`${cipherHex}:${ivHex}`, hmacKey).toString(crypto_js_1.default.enc.Hex);
+        return `${cipherHex}:${ivHex}:${mac}`;
     }
     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}.
+ * Decrypt data encrypted 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
+ * Steps:
+ *   1. Parse cipher format
+ *   2. Recompute and verify HMAC (tamper detection)
+ *   3. Decrypt AES-256-CBC
+ *   4. Parse JSON payload
  *
- * 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.
+ * `appName` MUST match the value used during encryption.
  */
-const decrypt = (cipherText, encryptionKeyHex) => {
-    const [encryptedHex, ivHex] = cipherText.split(":");
-    if (!ivHex || !encryptedHex) {
-        throw new Error("Invalid cipher format, expected cipherHex:ivHex");
+const decrypt = (cipherText, encryptionKeyHex, appName = "timebasedcipher") => {
+    const parts = cipherText.split(":");
+    if (parts.length !== 3) {
+        throw new Error("Invalid cipher format, expected cipherHex:ivHex:hmacHex");
+    }
+    const [encryptedHex, ivHex, hmacHex] = parts;
+    // Re-derive MAC key using same appName context
+    const hmacKeyHex = deriveHmacKeyHex(encryptionKeyHex, appName);
+    const hmacKey = crypto_js_1.default.enc.Hex.parse(hmacKeyHex);
+    const recomputedMac = crypto_js_1.default.HmacSHA256(`${encryptedHex}:${ivHex}`, hmacKey).toString(crypto_js_1.default.enc.Hex);
+    // Not constant-time, but acceptable for most non-hostile environments
+    if (recomputedMac !== hmacHex) {
+        throw new Error("Invalid HMAC: ciphertext may be tampered or key/appName is wrong");
     }
     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,
-    });
+    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);
@@ -146,9 +127,8 @@ const decrypt = (cipherText, encryptionKeyHex) => {
         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");
+        console.error("Error decrypting:", err);
+        throw new Error("Unable to decrypt: invalid key, appName, or corrupted payload");
     }
 };
 exports.decrypt = decrypt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "timebasedcipher",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Time-based key generation and AES encryption/decryption SDK",
   "main": "dist/index.js",
   "module": "dist/index.js",