timebasedcipher 3.0.1 → 3.0.2

package/README.md

@@ -1,187 +1,147 @@
 # timebasedcipher
 
-A lightweight, isomorphic (**Node + Browser**) library for **time-based rotating AES encryption with integrity protection**.
+A lightweight, isomorphic (**Node.js 18+ and modern browsers**) library
+for **time-based rotating AES-256-GCM encryption with integrity
+validation**.
 
-Built with [`crypto-js`](https://www.npmjs.com/package/crypto-js), this package provides:
+This implementation uses the **Web Crypto API** and provides:
 
-- **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**
+- Time-based rotating AES-256 keys derived using HKDF-SHA256
+- Authenticated encryption using AES-256-GCM
+- Encrypted signature validation
+- Works in both Node.js (v18+) and modern browser environments
+- No external crypto dependencies
 
 ---
 
 ## Installation
 
 ```bash
-npm install timebasedcipher crypto-js
+npm install timebasedcipher
 # or
-yarn add timebasedcipher crypto-js
+yarn add timebasedcipher
 # or
-pnpm add timebasedcipher crypto-js
+pnpm add timebasedcipher
 ```
 
+Node.js 18+ is required for native Web Crypto support.
+
 ---
 
 ## Quick Start
 
 ```ts
-import { generateKey, encrypt, decrypt } from "timebasedcipher";
+import { encrypt, decrypt } from "timebasedcipher";
 
-const sharedSecret = "mySuperSecret";
+const secret = "mySuperSecret";
 const intervalSeconds = 60; // key rotates every 60 seconds
 
-// Generate a rotating key
-const key = generateKey(sharedSecret, intervalSeconds);
+const data = { user: "TestUser", role: "admin", timestamp: Date.now() };
 
-// Encrypt data
-const data = { user: "Deb", role: "admin", timestamp: Date.now() };
-const cipher = encrypt(data, key);
+// Encrypt
+const cipher = await encrypt(data, secret, intervalSeconds);
 
-// Decrypt data
-const decrypted = decrypt(cipher, key);
+// Decrypt
+const decrypted = await decrypt(cipher, secret, intervalSeconds);
 
 console.log(decrypted);
 ```
 
-Works seamlessly in both **Node.js** and **browser** environments.
-
 ---
 
-## Function Reference
-
----
-
-### `generateKey(sharedSecretOrJwt: string, interval: number): string`
-
-Generates a **SHA-256–derived rotating key** that changes every `interval` seconds.
-
-- 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
-
-#### Parameters
-
-| Name                | Type     | Description                   |
-| ------------------- | -------- | ----------------------------- |
-| `sharedSecretOrJwt` | `string` | A shared secret or JWT string |
-| `interval`          | `number` | Rotation interval in seconds  |
-
-#### Returns
-
-- `string` — 64-character hex string (32-byte AES-256 key)
-
-#### Key Derivation
-
-```text
-SHA256(`${secretInput}:${timeSlot}`)
-```
+## API Reference
 
-Where:
+### encrypt`<T>`{=html}(data: T, secret: string, intervalSeconds: number): Promise`<string>`{=html}
 
-```text
-timeSlot = floor(Date.now() / (interval * 1000) + 1000)
-```
+Encrypts JSON-serializable data using a time-rotating AES-256-GCM key.
 
 ---
 
-### `encrypt(data: any, encryptionKeyHex: string, appName?: string): string`
+| Name              | Type     | Description                           |
+| ----------------- | -------- | ------------------------------------- |
+| `data`            | `any`    | JSON-serializable value               |
+| `secret`          | `string` | Shared secret used for key derivation |
+| `intervalSeconds` | `number` | Key rotation interval in seconds      |
 
-Encrypts data using **AES-256-CBC** and appends an **HMAC-SHA256** for integrity.
+---
 
-#### Parameters
+**Returns**
 
-| Name                   | Type     | Description                        |
-| ---------------------- | -------- | ---------------------------------- |
-| `data`                 | `any`    | Any JSON-serializable value        |
-| `encryptionKeyHex`     | `string` | 64-char hex key from `generateKey` |
-| `appName` _(optional)_ | `string` | Application context                |
+`Promise<string>` --- Ciphertext string.
 
-#### Returns
+---
 
-A ciphertext string in the format:
+### decrypt`<T>`{=html}(payload: string, secret: string, intervalSeconds: number): Promise`<T>`{=html}
 
-```text
-cipherHex:ivHex:hmacHex
-```
+Decrypts and validates ciphertext produced by `encrypt`.
 
 ---
 
-### `decrypt(cipherText: string, encryptionKeyHex: string, appName?: string): any`
-
-Decrypts and verifies ciphertext produced by `encrypt`.
-
-#### Parameters
+| Name              | Type     | Description                               |
+| ----------------- | -------- | ----------------------------------------- |
+| `payload`         | `string` | Encrypted string (`sigCipher:iv:data:iv`) |
+| `secret`          | `string` | Same shared secret used during encryption |
+| `intervalSeconds` | `number` | Same rotation interval used during        |
 
-| Name                   | Type     | Description                                  |
-| ---------------------- | -------- | -------------------------------------------- |
-| `cipherText`           | `string` | Encrypted string (`cipherHex:ivHex:hmacHex`) |
-| `encryptionKeyHex`     | `string` | Same key used during encryption              |
-| `appName` _(optional)_ | `string` | Must match encryption appName                |
+---
 
-#### Returns
+**Returns**
 
-- Original decrypted JavaScript value (parsed from JSON)
+`Promise<T>` --- Decrypted JavaScript value.
 
-#### Throws
+**Throws**
 
 - `Error("Invalid cipher format")`
-- `Error("Invalid HMAC: ciphertext may be tampered")`
-- `Error("Unable to decrypt")`
+- `Error("Invalid signature")`
+- Decryption errors if authentication fails
 
 ---
 
-## Application Context (`appName`)
-
-`appName` provides **cryptographic domain separation**.
+## Key Derivation
 
-- Prevents ciphertexts from being reused across apps
-- Prevents MAC key reuse
+Keys are derived using:
 
-### Example
+- HKDF with SHA-256
+- Salt = current time slot
+- Info = "time-based-encryption"
 
-```ts
-const key = generateKey(secret, 60);
+Time slot calculation:
 
-const cipher = encrypt(data, key, "billing-service");
-const plain = decrypt(cipher, key, "billing-service");
-```
+    timeSlot = floor(Date.now() / (intervalSeconds * 1000))
 
-Using a different `appName` will **fail decryption**.
+A new encryption key is automatically derived for each time window.
 
 ---
 
-## Browser + Node Compatibility
+## Security Model
 
-| Environment     | Supported | Notes                      |
-| --------------- | --------- | -------------------------- |
-| Node.js         | ✅        | Uses `crypto-js`           |
-| Browser         | ✅        | Fully supported            |
-| React / Next.js | ✅        | Works client & server-side |
+- Uses AES-256-GCM (authenticated encryption)
+- Provides built-in integrity and tamper detection
+- Includes encrypted signature validation
+- No manual HMAC required (GCM provides authentication)
+- Requires loosely synchronized clocks between encrypting and
+  decrypting systems
 
 ---
 
-## Security Notes
+## Environment Support
 
-- 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
+| Name              | Supported |
+| ----------------- | --------- |
+| `Node.js 18+`     | Yes       |
+| `Modern Browsers` | Yes       |
+| `React / Next.js` | Yes       |
 
 ---
 
 ## Requirements
 
-- Node.js ≥ 14 or modern browser
-- `crypto-js` dependency
+- Node.js 18+ or modern browser with Web Crypto API
+- No external cryptography libraries required
 
 ---
 
 ## License
 
-MIT License © 2026
-[**Deb Kalyan Mohanty**](https://github.com/debkalyanmohanty)
-
----
+MIT License © 2026\
+[Deb Kalyan Mohanty](https://github.com/debkalyanmohanty)

package/dist/index.d.ts

@@ -1,38 +1,30 @@
 /**
- * Generate a time-based rotating key using SHA-256.
+ * Time-Based Cipher with Encrypted Signature
  *
- * The key is derived as:
- *   SHA256(`${secretInput}:${timeSlot}`)
+ * Format:
+ *   sigCipherHex:sigIvHex:dataCipherHex:dataIvHex
  *
- * 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
+ * Requirements:
+ *   - Node.js 18+
+ *   - Modern browsers
  */
-export declare const generateKey: (sharedSecretOrJwt: string, interval: number) => string;
 /**
- * Encrypt arbitrary data using:
- *   - AES-256-CBC (confidentiality)
- *   - HMAC-SHA256 (integrity & authenticity)
+ * Encrypt JSON data with encrypted signature.
  *
- * Cipher format:
- *   cipherHex:ivHex:hmacHex
+ * @param data - JSON-serializable data.
+ * @param secret - Shared secret.
+ * @param intervalSeconds - Rotation interval in seconds.
  *
- * `appName`:
- *   - Included ONLY in HMAC key derivation
- *   - Ensures ciphertexts are bound to an application context
- *   - Must match during decryption
+ * @returns Promise resolving to ciphertext string.
  */
-export declare const encrypt: (data: any, encryptionKeyHex: string, appName?: string) => string;
+export declare function encrypt<T>(data: T, secret: string, intervalSeconds: number): Promise<string>;
 /**
- * Decrypt data encrypted by {@link encrypt}.
+ * Decrypt ciphertext with encrypted signature validation.
  *
- * Steps:
- *   1. Parse cipher format
- *   2. Recompute and verify HMAC (tamper detection)
- *   3. Decrypt AES-256-CBC
- *   4. Parse JSON payload
+ * @param payload - Ciphertext string.
+ * @param secret - Shared secret.
+ * @param intervalSeconds - Rotation interval.
  *
- * `appName` MUST match the value used during encryption.
+ * @returns Promise resolving to decrypted data.
  */
-export declare const decrypt: (cipherText: string, encryptionKeyHex: string, appName?: string) => unknown;
+export declare function decrypt<T>(payload: string, secret: string, intervalSeconds: number): Promise<T>;

package/dist/index.js

@@ -1,134 +1,122 @@
 "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 (seconds since epoch).
+ * Time-Based Cipher with Encrypted Signature
+ *
+ * Format:
+ *   sigCipherHex:sigIvHex:dataCipherHex:dataIvHex
  *
- * ⚠️ This does NOT verify authenticity — only structure and expiry.
+ * Requirements:
+ *   - Node.js 18+
+ *   - Modern browsers
  */
-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, "/");
-    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);
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+const cryptoObj = (() => {
+    if (typeof globalThis !== "undefined" && globalThis.crypto) {
+        return globalThis.crypto;
     }
-    catch {
-        throw new Error("Invalid JWT payload JSON");
+    throw new Error("Web Crypto API not available. Requires Node 18+ or modern browser.");
+})();
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Convert ArrayBuffer to hex string.
+ */
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Convert hex string to ArrayBuffer.
+ */
+function hexToBuffer(hex) {
+    if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length % 2 !== 0) {
+        throw new Error("Invalid hex string");
     }
-};
+    const bytes = new Uint8Array(hex.match(/.{1,2}/g).map((b) => parseInt(b, 16)));
+    return bytes.buffer;
+}
 /**
- * Derive a dedicated HMAC key from the encryption key.
- *
- * `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.
+ * Derive AES-256-GCM key using HKDF-SHA256.
  */
-const deriveHmacKeyHex = (encryptionKeyHex, appName = "timebasedcipher") => {
-    return crypto_js_1.default.SHA256(`${appName}-hmac:${encryptionKeyHex}`).toString(crypto_js_1.default.enc.Hex);
-};
+async function deriveKey(secret, intervalSeconds) {
+    if (!secret)
+        throw new Error("Secret must not be empty");
+    if (intervalSeconds <= 0)
+        throw new Error("intervalSeconds must be positive");
+    const now = Date.now() - 1000;
+    const timeSlot = Math.floor(now / (intervalSeconds * 1000));
+    const baseKey = await cryptoObj.subtle.importKey("raw", encoder.encode(secret).buffer, { name: "HKDF" }, false, ["deriveKey"]);
+    return cryptoObj.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: encoder.encode(String(timeSlot)).buffer,
+        info: encoder.encode("time-based-encryption").buffer,
+    }, baseKey, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
 /**
- * Generate a time-based rotating key using SHA-256.
- *
- * The key is derived as:
- *   SHA256(`${secretInput}:${timeSlot}`)
- *
- * 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
+ * Encrypt raw ArrayBuffer with AES-GCM.
  */
-const generateKey = (sharedSecretOrJwt, interval) => {
-    const timeSlot = Math.floor(Date.now() / (interval * 1000) + 1000);
-    const input = `${sharedSecretOrJwt}:${timeSlot}`;
-    return crypto_js_1.default.SHA256(input).toString(crypto_js_1.default.enc.Hex);
-};
-exports.generateKey = generateKey;
+async function aesEncrypt(key, data) {
+    const ivBytes = cryptoObj.getRandomValues(new Uint8Array(12));
+    const iv = ivBytes.buffer;
+    const cipher = await cryptoObj.subtle.encrypt({ name: "AES-GCM", iv }, key, data);
+    return { cipher, iv };
+}
 /**
- * Encrypt arbitrary data using:
- *   - AES-256-CBC (confidentiality)
- *   - HMAC-SHA256 (integrity & authenticity)
+ * Decrypt raw ArrayBuffer with AES-GCM.
+ */
+async function aesDecrypt(key, cipher, iv) {
+    return cryptoObj.subtle.decrypt({ name: "AES-GCM", iv }, key, cipher);
+}
+/**
+ * Encrypt JSON data with encrypted signature.
  *
- * Cipher format:
- *   cipherHex:ivHex:hmacHex
+ * @param data - JSON-serializable data.
+ * @param secret - Shared secret.
+ * @param intervalSeconds - Rotation interval in seconds.
  *
- * `appName`:
- *   - Included ONLY in HMAC key derivation
- *   - Ensures ciphertexts are bound to an application context
- *   - Must match during decryption
+ * @returns Promise resolving to ciphertext string.
  */
-const encrypt = (data, encryptionKeyHex, appName = "timebasedcipher") => {
-    const json = JSON.stringify(data);
-    try {
-        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);
-        // 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) {
-        console.error("Error in encrypt:", err);
-        throw err;
-    }
-};
-exports.encrypt = encrypt;
+async function encrypt(data, secret, intervalSeconds) {
+    const key = await deriveKey(secret, intervalSeconds);
+    // Signature payload (can be customized)
+    const signaturePayload = encoder.encode("signature-v1").buffer;
+    const sigEncrypted = await aesEncrypt(key, signaturePayload);
+    const dataBuffer = encoder.encode(JSON.stringify(data)).buffer;
+    const dataEncrypted = await aesEncrypt(key, dataBuffer);
+    return [
+        toHex(sigEncrypted.cipher),
+        toHex(sigEncrypted.iv),
+        toHex(dataEncrypted.cipher),
+        toHex(dataEncrypted.iv),
+    ].join(":");
+}
 /**
- * Decrypt data encrypted by {@link encrypt}.
+ * Decrypt ciphertext with encrypted signature validation.
  *
- * Steps:
- *   1. Parse cipher format
- *   2. Recompute and verify HMAC (tamper detection)
- *   3. Decrypt AES-256-CBC
- *   4. Parse JSON payload
+ * @param payload - Ciphertext string.
+ * @param secret - Shared secret.
+ * @param intervalSeconds - Rotation interval.
  *
- * `appName` MUST match the value used during encryption.
+ * @returns Promise resolving to decrypted data.
  */
-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");
+async function decrypt(payload, secret, intervalSeconds) {
+    const parts = payload.split(":");
+    if (parts.length !== 4) {
+        throw new Error("Invalid cipher format");
     }
-    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);
-    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);
+    const [sigCipherHex, sigIvHex, dataCipherHex, dataIvHex,] = parts;
+    const key = await deriveKey(secret, intervalSeconds);
+    // Decrypt signature
+    const sigPlain = await aesDecrypt(key, hexToBuffer(sigCipherHex), hexToBuffer(sigIvHex));
+    const sigText = decoder.decode(sigPlain);
+    if (sigText !== "signature-v1") {
+        throw new Error("Invalid signature");
     }
-    catch (err) {
-        console.error("Error decrypting:", err);
-        throw new Error("Unable to decrypt: invalid key, appName, or corrupted payload");
-    }
-};
-exports.decrypt = decrypt;
+    // Decrypt actual data
+    const dataPlain = await aesDecrypt(key, hexToBuffer(dataCipherHex), hexToBuffer(dataIvHex));
+    return JSON.parse(decoder.decode(dataPlain));
+}

package/package.json

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