@arikajs/encryption 0.0.3 → 0.0.5

package/README.md

@@ -2,7 +2,7 @@
 
 `@arikajs/encryption` provides secure, application-level encryption for the ArikaJS framework.
 
-It is responsible for encrypting and decrypting sensitive data such as sessions, cookies, signed payloads, and internal framework values — similar in spirit to Laravel’s `Illuminate\Encryption`.
+It is responsible for encrypting and decrypting sensitive data such as sessions, cookies, signed payloads, and internal framework values — providing a clean, secure API.
 
 This package is framework-agnostic at runtime, but designed to integrate seamlessly with `@arikajs/foundation` via service providers.
 
@@ -11,9 +11,10 @@ This package is framework-agnostic at runtime, but designed to integrate seamles
 ## ✨ Features
 
 - 🔐 **AES-256-GCM encryption** (modern & secure)
-- 🔑 **Single application key** (`APP_KEY`)
+- 🔑 **Multiple application keys** (support for key rotation)
 - 🧾 **Authenticated encryption** (tamper detection)
 - 🔄 **Encrypt / decrypt strings & JSON**
+- ✍️ **Signed-only payloads** (non-encrypted but authenticated)
 - 🧠 **Stateless design** (safe for queues & workers)
 - 🧩 **Framework service friendly**
 - 🟦 **TypeScript-first**
@@ -75,6 +76,72 @@ const data = encrypter.decrypt(token);
 
 Internally, objects are JSON-serialized automatically.
 
+### 🗜️ Optional Compression
+
+For large data (like long session strings or queue jobs), you can compress the payload before encryption to save space.
+
+```ts
+const encrypted = encrypter.encrypt(veryLargeObject, { compress: true });
+```
+
+### ⏳ Payload Expiration (TTL)
+
+You can create encrypted data that is only valid for a certain number of seconds.
+
+```ts
+// Valid for 5 minutes (300 seconds)
+const token = encrypter.encrypt('secret', { ttl: 300 });
+
+// After 5 minutes, decrypt() will throw a DecryptionException
+const data = encrypter.decrypt(token);
+```
+
+### 🔐 Contextual Encryption (AAD)
+
+Ensure the encrypted data is only used in the correct context (e.g., tying a token to a specific user). This uses **Additional Authenticated Data** to prevent payload reuse.
+
+```ts
+const token = encrypter.encrypt('sensitive', { context: 'user-id-123' });
+
+// This will succeed
+encrypter.decrypt(token, { context: 'user-id-123' });
+
+// This will throw even with the correct key!
+encrypter.decrypt(token, { context: 'user-id-456' });
+```
+
+---
+
+### ✍️ Signed Payloads (Non-encrypted)
+
+Sometimes you want to ensure data isn't tampered with but don't need to keep it secret (e.g., verification tokens).
+
+```ts
+const signed = encrypter.sign({ email: 'user@example.com' });
+
+// "eyJ2YWx1ZSI6InsiZW1haWwiOiJ1c2VyQGV4YW1..."
+
+const data = encrypter.verify(signed);
+// { email: 'user@example.com' }
+```
+
+---
+
+## 🔄 Key Rotation
+
+You can pass an array of keys to the `Encrypter`. The first key will be used for encryption/signing, but all keys will be tried during decryption/verification.
+
+```ts
+const encrypter = new Encrypter([
+  'base64:new-primary-key...',
+  'base64:old-key-1...',
+  'base64:old-key-2...'
+]);
+
+// Decrypts data created with any of the 3 keys
+const data = encrypter.decrypt(oldPayload);
+```
+
 ---
 
 ## 🧠 Integration with ArikaJS
@@ -85,13 +152,13 @@ Internally, objects are JSON-serialized automatically.
 import { Encrypter } from '@arikajs/encryption';
 
 this.app.singleton('encrypter', () => {
-  const key = config('app.key');
+  const keys = config('app.keys'); // Array of keys from config
 
-  if (!key) {
+  if (!keys || keys.length === 0) {
     throw new Error('APP_KEY is not defined.');
   }
 
-  return new Encrypter(key);
+  return new Encrypter(keys);
 });
 ```
 
@@ -107,13 +174,15 @@ const value = encrypter.encrypt('hello');
 
 ## 🔒 Security Guarantees
 
-- Uses **AES-256-GCM**
-- Every payload includes:
+- Uses **AES-256-GCM** for encryption
+- Uses **HMAC-SHA256** for signing
+- Every encrypted payload includes:
   - Random IV (Initialization Vector)
   - Authentication tag
+  - Version identifier
 - Any tampering → automatic decryption failure
 - No weak or legacy algorithms
-- If data is modified, `decrypt()` will throw.
+- Uses timing-safe comparisons for signatures
 
 ---
 
@@ -124,7 +193,7 @@ This package is a core dependency for:
 | Package | Usage |
 | :--- | :--- |
 | `@arikajs/session` | Encrypted sessions |
-| `@arikajs/http` | Encrypted cookies |
+| `@arikajs/http` | Encrypted cookies / Signed URLs |
 | `@arikajs/queue` | Secure job payloads |
 | `@arikajs/auth` | Token encryption |
 | `@arikajs/mail` | Signed mail data |
@@ -133,51 +202,42 @@ This package is a core dependency for:
 
 ## 🧠 API Reference
 
-### `new Encrypter(key: string)`
-Creates a new encrypter instance.
-
-### `encrypt(value: string | object): string`
-Encrypts a value and returns a string payload.
+### `new Encrypter(key: string | string[])`
+Creates a new encrypter instance. Accepts a single key or an array for rotation.
 
-### `decrypt(payload: string): any`
-Decrypts a payload and returns the original value.
+### `encrypt(value: any, options?: object): string`
+Encrypts a value. Options include:
+- `serialize`: (default: true)
+- `compress`: (default: false) uses zlib deflation
+- `ttl`: seconds until expiration
+- `context`: Additional Authenticated Data (AAD)
 
-Throws if:
-- Payload is invalid
-- Payload is tampered
-- Key is incorrect
+### `decrypt(payload: string, options?: object): any`
+Decrypts a payload. Options include:
+- `unserialize`: (default: true)
+- `context`: Must match the context used during encryption
 
 ---
 
 ## 🏗 Architecture
 
-```
+```text
 encryption/
 ├── src/
-│   ├── Encrypter.ts
-│   ├── Contracts/
+│   ├── Contracts
 │   │   └── Encrypter.ts
-│   ├── Exceptions/
+│   ├── Exceptions
 │   │   └── DecryptionException.ts
+│   ├── Encrypter.ts
 │   └── index.ts
 ├── tests/
 ├── package.json
 ├── tsconfig.json
-├── README.md
-└── LICENSE
+└── README.md
 ```
 
 ---
 
-## 🚧 Planned (v1.x+)
-
-- 🔄 Key rotation support
-- 🧪 Encrypted payload versioning
-- 🔑 Multiple key support (fallback decryption)
-- 🧷 Signed-only (non-encrypted) payloads
-
----
-
 ## 🧭 Philosophy
 
 > "Encryption should be invisible, mandatory, and impossible to misuse."

package/dist/Contracts/Encrypter.d.ts

@@ -2,9 +2,25 @@ export interface Encrypter {
     /**
      * Encrypt the given value.
      */
-    encrypt(value: any): string;
+    encrypt(value: any, options?: {
+        serialize?: boolean;
+        compress?: boolean;
+        ttl?: number;
+        context?: string;
+    }): string;
     /**
      * Decrypt the given value.
      */
-    decrypt(payload: string): any;
+    decrypt(payload: string, options?: {
+        unserialize?: boolean;
+        context?: string;
+    }): any;
+    /**
+     * Sign the given value.
+     */
+    sign(value: any): string;
+    /**
+     * Verify the given signed payload.
+     */
+    verify(payload: string): any;
 }

package/dist/Encrypter.d.ts

@@ -1,8 +1,8 @@
 import { Encrypter as EncrypterContract } from './Contracts/Encrypter';
 export declare class Encrypter implements EncrypterContract {
-    private readonly key;
+    private readonly keys;
     private readonly cipher;
-    constructor(key: string);
+    constructor(key: string | string[]);
     /**
      * Parse the encryption key.
      */
@@ -10,11 +10,31 @@ export declare class Encrypter implements EncrypterContract {
     /**
      * Encrypt the given value.
      */
-    encrypt(value: any): string;
+    encrypt(value: any, options?: {
+        serialize?: boolean;
+        compress?: boolean;
+        ttl?: number;
+        context?: string;
+    }): string;
     /**
      * Decrypt the given value.
      */
-    decrypt(payload: string): any;
+    decrypt(payload: string, options?: {
+        unserialize?: boolean;
+        context?: string;
+    }): any;
+    /**
+     * Sign the given value (non-encrypted but authenticated).
+     */
+    sign(value: any): string;
+    /**
+     * Verify the given signed payload.
+     */
+    verify(payload: string): any;
+    /**
+     * Create a hash (HMAC) of the given value.
+     */
+    protected hash(value: string): string;
     /**
      * Get the JSON payload from the given string.
      */

package/dist/Encrypter.js

@@ -2,14 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Encrypter = void 0;
 const crypto_1 = require("crypto");
+const zlib_1 = require("zlib");
 const DecryptionException_1 = require("./Exceptions/DecryptionException");
 class Encrypter {
-    key;
+    keys;
     cipher = 'aes-256-gcm';
     constructor(key) {
-        this.key = this.parseKey(key);
-        if (this.key.length !== 32) {
-            throw new Error('The encryption key must be 32 bytes.');
+        const keys = Array.isArray(key) ? key : [key];
+        this.keys = keys.map(k => this.parseKey(k));
+        if (this.keys.length === 0) {
+            throw new Error('At least one encryption key must be provided.');
+        }
+        for (const k of this.keys) {
+            if (k.length !== 32) {
+                throw new Error('Each encryption key must be 32 bytes.');
+            }
         }
     }
     /**
@@ -24,38 +31,124 @@ class Encrypter {
     /**
      * Encrypt the given value.
      */
-    encrypt(value) {
+    encrypt(value, options = {}) {
         const iv = (0, crypto_1.randomBytes)(16);
-        const cipher = (0, crypto_1.createCipheriv)(this.cipher, this.key, iv);
-        const jsonValue = JSON.stringify(value);
-        let encrypted = cipher.update(jsonValue, 'utf8', 'base64');
-        encrypted += cipher.final('base64');
+        const cipher = (0, crypto_1.createCipheriv)(this.cipher, this.keys[0], iv);
+        if (options.context) {
+            cipher.setAAD(Buffer.from(options.context));
+        }
+        const serialize = options.serialize !== false;
+        let data;
+        if (serialize) {
+            data = JSON.stringify(value);
+        }
+        else {
+            data = Buffer.isBuffer(value) ? value : String(value);
+        }
+        if (options.compress === true) {
+            data = (0, zlib_1.deflateSync)(Buffer.from(data));
+        }
+        let encrypted = cipher.update(data);
+        encrypted = Buffer.concat([encrypted, cipher.final()]);
         const tag = cipher.getAuthTag();
         const payload = {
             iv: iv.toString('base64'),
-            value: encrypted,
+            value: encrypted.toString('base64'),
             tag: tag.toString('base64'),
+            v: 1,
         };
+        if (options.compress)
+            payload.c = true;
+        if (options.ttl) {
+            payload.exp = Date.now() + (options.ttl * 1000);
+        }
+        if (options.context)
+            payload.aad = true;
         return Buffer.from(JSON.stringify(payload)).toString('base64');
     }
     /**
      * Decrypt the given value.
      */
-    decrypt(payload) {
+    decrypt(payload, options = {}) {
         const jsonPayload = this.getJsonPayload(payload);
+        // Check for TTL expiration
+        if (jsonPayload.exp && Date.now() > jsonPayload.exp) {
+            throw new DecryptionException_1.DecryptionException('The payload has expired.');
+        }
+        // Verify context requirements
+        if (jsonPayload.aad && !options.context) {
+            throw new DecryptionException_1.DecryptionException('The payload requires a context for decryption.');
+        }
         const iv = Buffer.from(jsonPayload.iv, 'base64');
         const tag = Buffer.from(jsonPayload.tag, 'base64');
         const value = jsonPayload.value;
+        const compressed = jsonPayload.c === true;
+        // Try decrypting with all available keys (support rotation)
+        for (const key of this.keys) {
+            try {
+                const decipher = (0, crypto_1.createDecipheriv)(this.cipher, key, iv);
+                if (options.context) {
+                    decipher.setAAD(Buffer.from(options.context));
+                }
+                decipher.setAuthTag(tag);
+                let decrypted = decipher.update(value, 'base64');
+                decrypted = Buffer.concat([decrypted, decipher.final()]);
+                let result = decrypted;
+                if (compressed) {
+                    result = (0, zlib_1.inflateSync)(result);
+                }
+                const finalData = result.toString('utf8');
+                return options.unserialize === false ? finalData : JSON.parse(finalData);
+            }
+            catch (error) {
+                // Try next key
+                continue;
+            }
+        }
+        throw new DecryptionException_1.DecryptionException();
+    }
+    /**
+     * Sign the given value (non-encrypted but authenticated).
+     */
+    sign(value) {
+        const jsonValue = JSON.stringify(value);
+        const signature = this.hash(jsonValue);
+        return Buffer.from(JSON.stringify({
+            value: jsonValue,
+            signature: signature
+        })).toString('base64');
+    }
+    /**
+     * Verify the given signed payload.
+     */
+    verify(payload) {
         try {
-            const decipher = (0, crypto_1.createDecipheriv)(this.cipher, this.key, iv);
-            decipher.setAuthTag(tag);
-            let decrypted = decipher.update(value, 'base64', 'utf8');
-            decrypted += decipher.final('utf8');
-            return JSON.parse(decrypted);
+            const decoded = JSON.parse(Buffer.from(payload, 'base64').toString('utf8'));
+            if (!decoded.value || !decoded.signature) {
+                throw new DecryptionException_1.DecryptionException('Invalid signed payload.');
+            }
+            // Verify with all available keys
+            for (const key of this.keys) {
+                const signature = (0, crypto_1.createHmac)('sha256', key)
+                    .update(decoded.value)
+                    .digest('hex');
+                if ((0, crypto_1.timingSafeEqual)(Buffer.from(signature), Buffer.from(decoded.signature))) {
+                    return JSON.parse(decoded.value);
+                }
+            }
         }
-        catch (error) {
-            throw new DecryptionException_1.DecryptionException();
+        catch (e) {
+            // Fall through 
         }
+        throw new DecryptionException_1.DecryptionException('Signature verification failed.');
+    }
+    /**
+     * Create a hash (HMAC) of the given value.
+     */
+    hash(value) {
+        return (0, crypto_1.createHmac)('sha256', this.keys[0])
+            .update(value)
+            .digest('hex');
     }
     /**
      * Get the JSON payload from the given string.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arikajs/encryption",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Secure, application-level encryption for the ArikaJS framework.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -8,7 +8,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist",
-    "prepare": "echo skip"
+    "prepare": "echo skip",
+    "test": "npm run build && node --test 'dist/tests/**/*.test.js'",
+    "test:watch": "npm run build && node --test --watch 'dist/tests/**/*.test.js'",
+    "dev": "tsc -p tsconfig.json --watch"
   },
   "files": [
     "dist"
@@ -18,8 +21,18 @@
   },
   "dependencies": {},
   "devDependencies": {
+    "tsx": "^4.7.1",
     "@types/node": "^20.11.24",
     "typescript": "^5.3.3"
   },
-  "author": "Prakash Tank"
+  "author": "Prakash Tank",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArikaJs/arikajs.git",
+    "directory": "packages/encryption"
+  },
+  "bugs": {
+    "url": "https://github.com/ArikaJs/arikajs/issues"
+  },
+  "homepage": "https://github.com/ArikaJs/arikajs/tree/main/packages/encryption#readme"
 }