@arikajs/encryption 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArikaJs
+
+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,195 @@
+## Arika Encryption
+
+`@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`.
+
+This package is framework-agnostic at runtime, but designed to integrate seamlessly with `@arikajs/foundation` via service providers.
+
+---
+
+## ✨ Features
+
+- 🔐 **AES-256-GCM encryption** (modern & secure)
+- 🔑 **Single application key** (`APP_KEY`)
+- 🧾 **Authenticated encryption** (tamper detection)
+- 🔄 **Encrypt / decrypt strings & JSON**
+- 🧠 **Stateless design** (safe for queues & workers)
+- 🧩 **Framework service friendly**
+- 🟦 **TypeScript-first**
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @arikajs/encryption
+# or
+yarn add @arikajs/encryption
+# or
+pnpm add @arikajs/encryption
+```
+
+---
+
+## 🔑 Application Key (Required)
+
+This package requires an application key, usually provided via:
+
+```ini
+APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+> **Note:** The key must be 32 bytes, Base64-encoded.
+> You can generate one using:
+> `arika key:generate`
+
+---
+
+## 🚀 Basic Usage (Standalone)
+
+```ts
+import { Encrypter } from '@arikajs/encryption';
+
+const encrypter = new Encrypter('base64:your-app-key');
+
+const encrypted = encrypter.encrypt('secret data');
+const decrypted = encrypter.decrypt(encrypted);
+
+console.log(decrypted); // "secret data"
+```
+
+### 📦 Encrypting Objects / JSON
+
+```ts
+const payload = {
+  userId: 1,
+  role: 'admin',
+};
+
+const token = encrypter.encrypt(payload);
+
+const data = encrypter.decrypt(token);
+// { userId: 1, role: 'admin' }
+```
+
+Internally, objects are JSON-serialized automatically.
+
+---
+
+## 🧠 Integration with ArikaJS
+
+### Register as a service (via Foundation)
+
+```ts
+import { Encrypter } from '@arikajs/encryption';
+
+this.app.singleton('encrypter', () => {
+  const key = config('app.key');
+
+  if (!key) {
+    throw new Error('APP_KEY is not defined.');
+  }
+
+  return new Encrypter(key);
+});
+```
+
+### Usage anywhere in the app
+
+```ts
+const encrypter = app.make<Encrypter>('encrypter');
+
+const value = encrypter.encrypt('hello');
+```
+
+---
+
+## 🔒 Security Guarantees
+
+- Uses **AES-256-GCM**
+- Every payload includes:
+  - Random IV (Initialization Vector)
+  - Authentication tag
+- Any tampering → automatic decryption failure
+- No weak or legacy algorithms
+- If data is modified, `decrypt()` will throw.
+
+---
+
+## 🧩 Intended Consumers
+
+This package is a core dependency for:
+
+| Package | Usage |
+| :--- | :--- |
+| `@arikajs/session` | Encrypted sessions |
+| `@arikajs/http` | Encrypted cookies |
+| `@arikajs/queue` | Secure job payloads |
+| `@arikajs/auth` | Token encryption |
+| `@arikajs/mail` | Signed mail data |
+
+---
+
+## 🧠 API Reference
+
+### `new Encrypter(key: string)`
+Creates a new encrypter instance.
+
+### `encrypt(value: string | object): string`
+Encrypts a value and returns a string payload.
+
+### `decrypt(payload: string): any`
+Decrypts a payload and returns the original value.
+
+Throws if:
+- Payload is invalid
+- Payload is tampered
+- Key is incorrect
+
+---
+
+## 🏗 Architecture
+
+```
+encryption/
+├── src/
+│   ├── Encrypter.ts
+│   ├── Contracts/
+│   │   └── Encrypter.ts
+│   ├── Exceptions/
+│   │   └── DecryptionException.ts
+│   └── index.ts
+├── tests/
+├── package.json
+├── tsconfig.json
+├── README.md
+└── LICENSE
+```
+
+---
+
+## 🚧 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."
+
+This package:
+- Enforces strong defaults
+- Centralizes cryptography
+- Avoids configuration sprawl
+- Keeps security boring and safe
+
+---
+
+## 📄 License
+
+`@arikajs/encryption` is open-source software licensed under the **MIT License**.

package/dist/Contracts/Encrypter.d.ts

@@ -0,0 +1,10 @@
+export interface Encrypter {
+    /**
+     * Encrypt the given value.
+     */
+    encrypt(value: any): string;
+    /**
+     * Decrypt the given value.
+     */
+    decrypt(payload: string): any;
+}

package/dist/Contracts/Encrypter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/Encrypter.d.ts

@@ -0,0 +1,26 @@
+import { Encrypter as EncrypterContract } from './Contracts/Encrypter';
+export declare class Encrypter implements EncrypterContract {
+    private readonly key;
+    private readonly cipher;
+    constructor(key: string);
+    /**
+     * Parse the encryption key.
+     */
+    protected parseKey(key: string): Buffer;
+    /**
+     * Encrypt the given value.
+     */
+    encrypt(value: any): string;
+    /**
+     * Decrypt the given value.
+     */
+    decrypt(payload: string): any;
+    /**
+     * Get the JSON payload from the given string.
+     */
+    protected getJsonPayload(payload: string): any;
+    /**
+     * Verify that the encryption payload is valid.
+     */
+    protected validPayload(payload: any): boolean;
+}

package/dist/Encrypter.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Encrypter = void 0;
+const crypto_1 = require("crypto");
+const DecryptionException_1 = require("./Exceptions/DecryptionException");
+class Encrypter {
+    key;
+    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.');
+        }
+    }
+    /**
+     * Parse the encryption key.
+     */
+    parseKey(key) {
+        if (key.startsWith('base64:')) {
+            return Buffer.from(key.substring(7), 'base64');
+        }
+        return Buffer.from(key);
+    }
+    /**
+     * Encrypt the given value.
+     */
+    encrypt(value) {
+        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 tag = cipher.getAuthTag();
+        const payload = {
+            iv: iv.toString('base64'),
+            value: encrypted,
+            tag: tag.toString('base64'),
+        };
+        return Buffer.from(JSON.stringify(payload)).toString('base64');
+    }
+    /**
+     * Decrypt the given value.
+     */
+    decrypt(payload) {
+        const jsonPayload = this.getJsonPayload(payload);
+        const iv = Buffer.from(jsonPayload.iv, 'base64');
+        const tag = Buffer.from(jsonPayload.tag, 'base64');
+        const value = jsonPayload.value;
+        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);
+        }
+        catch (error) {
+            throw new DecryptionException_1.DecryptionException();
+        }
+    }
+    /**
+     * Get the JSON payload from the given string.
+     */
+    getJsonPayload(payload) {
+        try {
+            const decoded = Buffer.from(payload, 'base64').toString('utf8');
+            const data = JSON.parse(decoded);
+            if (!this.validPayload(data)) {
+                throw new DecryptionException_1.DecryptionException();
+            }
+            return data;
+        }
+        catch (error) {
+            throw new DecryptionException_1.DecryptionException();
+        }
+    }
+    /**
+     * Verify that the encryption payload is valid.
+     */
+    validPayload(payload) {
+        return typeof payload === 'object' &&
+            payload !== null &&
+            payload.iv &&
+            payload.value &&
+            payload.tag;
+    }
+}
+exports.Encrypter = Encrypter;

package/dist/Exceptions/DecryptionException.d.ts

@@ -0,0 +1,3 @@
+export declare class DecryptionException extends Error {
+    constructor(message?: string);
+}

package/dist/Exceptions/DecryptionException.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecryptionException = void 0;
+class DecryptionException extends Error {
+    constructor(message = 'The payload is invalid or has been tampered with.') {
+        super(message);
+        this.name = 'DecryptionException';
+    }
+}
+exports.DecryptionException = DecryptionException;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Encrypter } from './Encrypter';
+export { Encrypter as EncrypterContract } from './Contracts/Encrypter';
+export * from './Exceptions/DecryptionException';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Encrypter = void 0;
+var Encrypter_1 = require("./Encrypter");
+Object.defineProperty(exports, "Encrypter", { enumerable: true, get: function () { return Encrypter_1.Encrypter; } });
+__exportStar(require("./Exceptions/DecryptionException"), exports);

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@arikajs/encryption",
+  "version": "0.0.1",
+  "description": "Secure, application-level encryption for the ArikaJS framework.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepare": "echo skip"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3"
+  },
+  "author": "Prakash Tank"
+}