titan-vault-node 1.0.0 → 2.1.0

package/README.md

@@ -1,66 +1,168 @@
-# 🛡️ Titan Vault (Node.js SDK)
+# Titan Vault (Node.js SDK)
 
-> **Zero-trust, E2E encrypted, drop-in replacement for dotenv.**
+Cliente de la bóveda local. Pide `GET /secret/data/{path}` con una llave RSA-2048 efímera, descifra la respuesta híbrida (RSA-OAEP-SHA256 + AES-256-CFB) y reparte cada campo:
 
-Titan Vault is the easiest way to secure your application secrets. Forget about hardcoded `.env` files that get leaked. Titan Vault acts as a highly secure, encrypted environment variable injector that requires **zero friction** to use.
+- `JWT_SECRET` y el resto de llaves quedan como `crypto.KeyObject`. El SDK no guarda otra copia en string. `getRaw()` sí crea un string, y el JSON descifrado vive en el heap hasta que V8 lo recolecta.
+- `DB_PASSWORD` y las demás contraseñas de base de datos se entregan solo cuando Sequelize o `pg` piden la conexión.
+- `DATABASE_URL`, `REDIS_URL`, `PORT` y el resto se leen con `TitanVault.config.get`. No entran en `process.env`, salvo `NODE_ENV`, `PORT`, `HOST`, `FRONTEND_PORT` y `BACKEND_PORT`.
+- `VAULT_EMERGENCY_RECOVERY_TOKEN` no se puede leer. Si el payload trae el cebo, esa lectura llama a `GET /sys/recovery` con el valor que inyectó la bóveda.
 
-## 🚀 The Problem with `.env`
-If a hacker gets read access to your server (LFI, directory traversal, etc.), they can read your `.env` file and steal all your database passwords and API keys.
+Si la bóveda no responde, o devuelve el secreto en claro después de recibir `x-vault-public-key`, `armParanoiaMode` lanza `VaultConnectionError` y el proceso no debe seguir. El token se lee de `vaultToken`, `VAULT_TOKEN` o `VAULT_APP_TOKEN`.
 
-## 💡 The Titan Vault Solution
-Titan Vault stores your secrets in a centralized, encrypted server. Your app authenticates using a lightweight AppToken, and the Vault dynamically injects the secrets directly into Node.js memory (`process.env`) using **Hybrid E2E Encryption (RSA-OAEP + AES-CFB)**. If the app stops, the secrets disappear.
+---
+
+## ⚡ ¿Por qué `dotenv` y `process.env` son inseguros?
+
+1. **Memory Dumps:** Cualquier vulnerabilidad que permita un volcado de memoria (heapdump, coredump, inspector v8) expone todas las variables de entorno en texto plano.
+2. **Inmutabilidad V8:** En Node.js, `process.env` almacena strings inmutables. El recolector de basura (GC) no puede sobreescribir con ceros esas cadenas en memoria.
+3. **Peligro de Logs:** Un simple `console.log(process.env)` o reporte de error APM filtra todas tus credenciales.
+
+---
+
+## Qué hace el modo paranoia
 
-### 🔥 Killer Features
-- **Zero-Friction SDK:** Replaces `dotenv` with exactly 2 lines of code.
-- **E2E Encryption out-of-the-box:** Secrets are never sent in plain text over the network.
-- **Honeytokens & Webhooks:** Create fake "Honeytoken" secrets. If a hacker tries to use them, the Vault instantly locks down and sends an alert to your **Telegram/Slack**.
-- **Burn-on-read Tokens:** For maximum paranoia, use one-time wrap tokens that self-destruct after your app boots.
+1. **Arranque.** `bootstrap` espera a `armParanoiaMode`. Si esa llamada lanza, no importa el servidor.
+2. **`process.env`.** Un proxy lanza `ParanoiaBlockedError` al leer o escribir un secreto, y lo oculta de `Object.keys` y `console.log(process.env)`.
+3. **`KeyObject`.** `TitanVault.secrets.get('JWT_SECRET')` sirve para `jsonwebtoken` y `crypto`. La búsqueda de strings en el heap de V8 todavía puede encontrar el valor que produjo `JSON.parse` hasta que el recolector lo suelte.
+4. **Base de datos.** `hookSequelize` pone la contraseña en `beforeConnect` y la quita del config en `afterConnect`. `getPgPasswordProvider` la devuelve en cada conexión. El driver conserva el string que necesita el handshake.
+5. **Transit.** `encrypt`, `decrypt`, `sign` y `verify` llaman a `/transit/*` en la bóveda. La llave no sale del servidor.
 
-## 📦 Installation
+---
+
+## 💻 Guía de Integración
+
+### 1. El Patrón Bootstrap (`bootstrap.js` o `src/index.ts`)
+
+Crea un archivo de arranque que cargue el SDK antes de importar el servidor:
+
+```typescript
+// bootstrap.ts
+import { TitanVault } from 'titan-vault-node';
+
+async function main() {
+  // Lanza VaultConnectionError si la bóveda no responde.
+  await TitanVault.armParanoiaMode({
+    vaultUrl: process.env.VAULT_URL || 'http://127.0.0.1:8200',
+    vaultToken: process.env.VAULT_APP_TOKEN,
+    path: 'mi_aplicacion_env',
+  });
+
+  // 2. Importa el servidor dinámicamente UNA VEZ que la memoria está blindada
+  await import('./server.js');
+}
 
-```bash
-npm install titan-vault-node
+main();
 ```
 
-## 💻 Usage
+---
+
+### 2. Firma y Validación de Tokens JWT (C++ `KeyObject`)
+
+Compatible de forma nativa con `jsonwebtoken`, `jose` y el módulo `crypto` de Node.js:
+
+```typescript
+import jwt from 'jsonwebtoken';
+import { TitanVault } from 'titan-vault-node';
 
-Replace your standard `dotenv.config()` with `initVault()`.
+const jwtKey = TitanVault.secrets.get('JWT_SECRET');
 
-### 1. Set your App Token
-In your deployment environment (or a local `.env`), just provide your vault's URL and your App Token:
+// Firmar
+const token = jwt.sign({ userId: 123, role: 'admin' }, jwtKey, {
+  algorithm: 'HS256',
+  expiresIn: '2h',
+});
 
-```env
-VAULT_URL=http://localhost:8200
-VAULT_APP_TOKEN=my-super-secret-app-role-token
+// Verificar
+const payload = jwt.verify(token, jwtKey);
 ```
 
-### 2. Initialize in your code
+---
+
+### 3. Conexión Segura a Base de Datos (JIT)
 
+#### Con Sequelize:
 ```typescript
-import { initVault } from 'titan-vault-node';
+import { Sequelize } from 'sequelize';
+import { TitanVault } from 'titan-vault-node';
+
+export const sequelize = new Sequelize({
+  dialect: 'postgres',
+  host: TitanVault.config.get('DB_HOST'),
+  database: TitanVault.config.get('DB_NAME'),
+  username: TitanVault.config.get('DB_USER'),
+  // No pongas password aquí
+});
+
+// Registra el inyector JIT
+TitanVault.databases.hookSequelize(sequelize, {
+  credentialKey: 'DB_PASSWORD',
+});
+```
 
-async function startServer() {
-  // Magically connects to Titan Vault, decrypts the E2E payload, 
-  // and injects everything into process.env!
-  await initVault();
+#### Con `pg` (node-postgres):
+```typescript
+import pg from 'pg';
+import { TitanVault } from 'titan-vault-node';
+
+export const pool = new pg.Pool({
+  host: TitanVault.config.get('DB_HOST'),
+  user: TitanVault.config.get('DB_USER'),
+  database: TitanVault.config.get('DB_NAME'),
+  // Inyección JIT asíncrona por conexión
+  password: TitanVault.databases.getPgPasswordProvider('DB_PASSWORD'),
+});
+```
 
-  console.log("My secure DB password is:", process.env.DB_PASSWORD);
-  
-  // Start your Express/NestJS/HTTP server...
-}
+---
+
+### 4. Criptografía como Servicio (Transit Engine / CaaS)
+
+Para máxima seguridad, puedes delegar el cifrado y la firma directamente a Titan Vault (cero llaves en tu app):
+
+```typescript
+import { TitanVault } from 'titan-vault-node';
+
+// Cifrar datos con AES-256-GCM en el Vault
+const ciphertext = await TitanVault.transit.encrypt('mi-llave', 'Texto Ultra Confidencial');
 
-startServer();
+// Descifrar en el Vault
+const plaintext = await TitanVault.transit.decrypt('mi-llave', ciphertext);
+
+// Firmar datos con HMAC-SHA256 en el Vault
+const signature = await TitanVault.transit.sign('mi-firma-jwt', 'payload.a.firmar');
+
+// Verificar firma en el Vault
+const isValid = await TitanVault.transit.verify('mi-firma-jwt', 'payload.a.firmar', signature);
 ```
 
-## 🚨 Telegram Webhook Setup (Server-side)
-Want to be notified if someone touches your Honeytoken? Run your Titan Vault server with Telegram variables:
+---
+
+### 5. Configuración
+
+`DATABASE_URL` y `REDIS_URL` salen de aquí. No son contraseñas y no se copian a `process.env`.
 
-```bash
-export TELEGRAM_BOT_TOKEN="your_bot_token"
-export TELEGRAM_CHAT_ID="your_chat_id"
-# Start your vault...
+```typescript
+const databaseUrl = TitanVault.config.get('DATABASE_URL');
+const port = TitanVault.config.get('PORT', '3000');
+const host = TitanVault.config.get('HOST', '0.0.0.0');
 ```
-If your Honeytoken is triggered, the Vault seals itself and sends a red alert to your phone instantly.
 
 ---
-**Built for the paranoid, designed for the developer.**
+
+### 6. Reporte de runtime
+
+`verifyRuntimeHardening()` dice si el proceso es root, si `NODE_ENV` es `production`, si el límite blando de core dumps es 0 (`/proc/self/limits`) y si el modo paranoia llegó a armarse. No cambia esos límites.
+
+```typescript
+TitanVault.verifyRuntimeHardening();
+```
+
+---
+
+## Honeytoken
+
+En la bóveda, la trampa está apagada hasta definir `TITAN_INJECT_HONEYTOKEN=1` y `TITAN_HONEYTOKEN_VALUE`. El campo por defecto es `VAULT_EMERGENCY_RECOVERY_TOKEN` (`TITAN_HONEYTOKEN_FIELD` lo cambia en los dos lados).
+
+Leer `process.env.VAULT_EMERGENCY_RECOVERY_TOKEN` lanza `ParanoiaBlockedError`. Si el payload traía el cebo, el SDK llama a `GET /sys/recovery` con ese valor en `x-vault-token`. La bóveda sella cuando el header coincide. Sin cebo en el payload, la lectura se bloquea y la bóveda sigue abierta.
+
+`TitanVault.flushTripwire()` espera a que esa petición termine.

package/dist/core/classify.d.ts

@@ -0,0 +1,9 @@
+import { VaultOptions } from '../types';
+/** Same default field the vault injects (`TITAN_HONEYTOKEN_FIELD`). */
+export declare const HONEYTOKEN_FIELD = "VAULT_EMERGENCY_RECOVERY_TOKEN";
+export type SecretClass = 'honeytoken' | 'crypto' | 'database' | 'config';
+/**
+ * Classification shared with the vault.
+ * `DATABASE_URL` is configuration the app reads. Only password fields go to the JIT store.
+ */
+export declare function classifyKey(key: string, tag: string | undefined, options?: VaultOptions): SecretClass;

package/dist/core/classify.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HONEYTOKEN_FIELD = void 0;
+exports.classifyKey = classifyKey;
+/** Same default field the vault injects (`TITAN_HONEYTOKEN_FIELD`). */
+exports.HONEYTOKEN_FIELD = 'VAULT_EMERGENCY_RECOVERY_TOKEN';
+// Keep in sync with titan_vault/core.py `_classify_key`.
+const DB_PASSWORD_RE = /(DB_PASS|POSTGRES_PASS|MYSQL_PASS|DB_PASSWORD|POSTGRES_PASSWORD|MYSQL_PASSWORD)/i;
+const CRYPTO_RE = /(JWT|SECRET|KEY|PRIVATE|TOKEN|SALT)/i;
+/**
+ * Classification shared with the vault.
+ * `DATABASE_URL` is configuration the app reads. Only password fields go to the JIT store.
+ */
+function classifyKey(key, tag, options = {}) {
+    const honeyField = options.honeytokenField || exports.HONEYTOKEN_FIELD;
+    if (tag === 'honeytoken' || key === honeyField)
+        return 'honeytoken';
+    if ((options.cryptoKeys || []).includes(key) || tag === 'crypto')
+        return 'crypto';
+    if ((options.dbKeys || []).includes(key) || tag === 'database' || DB_PASSWORD_RE.test(key)) {
+        return 'database';
+    }
+    if (CRYPTO_RE.test(key))
+        return 'crypto';
+    return 'config';
+}

package/dist/core/crypto-store.d.ts

@@ -0,0 +1,18 @@
+import crypto from 'crypto';
+export declare class CryptoStore {
+    private keyObjects;
+    /**
+     * Store the secret as a KeyObject and drop the temporary byte buffer.
+     * The original JavaScript string from JSON.parse is immutable and stays
+     * until V8 collects it. This store does not keep a second copy.
+     */
+    register(name: string, rawSecret: string): void;
+    get(name: string): crypto.KeyObject;
+    /**
+     * Materialize the secret as a string. That string lives on the V8 heap
+     * until it is collected. Prefer `get()` when the library accepts a KeyObject.
+     */
+    getRaw(name: string): string;
+    has(name: string): boolean;
+    keys(): string[];
+}

package/dist/core/crypto-store.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CryptoStore = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+class CryptoStore {
+    keyObjects = new Map();
+    /**
+     * Store the secret as a KeyObject and drop the temporary byte buffer.
+     * The original JavaScript string from JSON.parse is immutable and stays
+     * until V8 collects it. This store does not keep a second copy.
+     */
+    register(name, rawSecret) {
+        if (!rawSecret)
+            return;
+        const buffer = Buffer.from(rawSecret, 'utf-8');
+        try {
+            if (rawSecret.includes('-----BEGIN PRIVATE KEY-----') || rawSecret.includes('-----BEGIN RSA PRIVATE KEY-----')) {
+                this.keyObjects.set(name, crypto_1.default.createPrivateKey({ key: rawSecret, format: 'pem' }));
+            }
+            else if (rawSecret.includes('-----BEGIN PUBLIC KEY-----')) {
+                this.keyObjects.set(name, crypto_1.default.createPublicKey({ key: rawSecret, format: 'pem' }));
+            }
+            else {
+                this.keyObjects.set(name, crypto_1.default.createSecretKey(buffer));
+            }
+        }
+        finally {
+            buffer.fill(0);
+        }
+    }
+    get(name) {
+        const key = this.keyObjects.get(name);
+        if (!key) {
+            throw new Error(`[Titan Vault] Llave criptográfica '${name}' no encontrada en el almacén seguro.`);
+        }
+        return key;
+    }
+    /**
+     * Materialize the secret as a string. That string lives on the V8 heap
+     * until it is collected. Prefer `get()` when the library accepts a KeyObject.
+     */
+    getRaw(name) {
+        const key = this.get(name);
+        console.warn(`⚠️ [Titan Vault] '${name}' se materializó como texto. ` +
+            `Ese string queda en el heap de V8 hasta que el recolector lo libere. ` +
+            `Usa get() cuando la librería acepte un KeyObject.`);
+        if (key.type === 'secret') {
+            const exported = key.export();
+            return Buffer.isBuffer(exported) ? exported.toString('utf8') : Buffer.from(exported).toString('utf8');
+        }
+        const exported = key.export({
+            type: key.type === 'private' ? 'pkcs8' : 'spki',
+            format: 'pem',
+        });
+        return typeof exported === 'string' ? exported : exported.toString('utf8');
+    }
+    has(name) {
+        return this.keyObjects.has(name);
+    }
+    keys() {
+        return Array.from(this.keyObjects.keys());
+    }
+}
+exports.CryptoStore = CryptoStore;

package/dist/core/database-hooks.d.ts

@@ -0,0 +1,17 @@
+export declare class DatabaseHooks {
+    private credentials;
+    register(key: string, value: string): void;
+    getJitCredential(key: string): string;
+    /**
+     * Inject the password on `beforeConnect` and clear `config.password` after.
+     * The driver still receives a JavaScript string for the handshake.
+     */
+    hookSequelize(sequelize: any, options?: {
+        credentialKey?: string;
+    }): void;
+    /**
+     * Password function for `pg.Pool`. node-postgres calls it per connection.
+     */
+    getPgPasswordProvider(keyName?: string): () => Promise<string>;
+    private materialize;
+}

package/dist/core/database-hooks.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseHooks = void 0;
+class DatabaseHooks {
+    credentials = new Map();
+    register(key, value) {
+        if (!key || !value)
+            return;
+        const existing = this.credentials.get(key);
+        if (existing)
+            existing.fill(0);
+        this.credentials.set(key, Buffer.from(value, 'utf8'));
+    }
+    getJitCredential(key) {
+        return this.materialize(key);
+    }
+    /**
+     * Inject the password on `beforeConnect` and clear `config.password` after.
+     * The driver still receives a JavaScript string for the handshake.
+     */
+    hookSequelize(sequelize, options = {}) {
+        const credKey = options.credentialKey || 'DB_PASSWORD';
+        if (!sequelize || typeof sequelize.addHook !== 'function') {
+            console.warn('⚠️ [Titan Vault] La instancia provista no parece ser un objeto Sequelize válido.');
+            return;
+        }
+        sequelize.addHook('beforeConnect', async (config) => {
+            config.password = this.materialize(credKey);
+        });
+        sequelize.addHook('afterConnect', async (_connection, config) => {
+            if (config && 'password' in config) {
+                config.password = null;
+            }
+        });
+        console.log(`🛡️ [Titan Vault] Hook Sequelize JIT activado para '${credKey}'.`);
+    }
+    /**
+     * Password function for `pg.Pool`. node-postgres calls it per connection.
+     */
+    getPgPasswordProvider(keyName = 'DB_PASSWORD') {
+        return async () => this.materialize(keyName);
+    }
+    materialize(key) {
+        const buf = this.credentials.get(key);
+        if (!buf) {
+            throw new Error(`[Titan Vault - JIT DB] Credencial '${key}' no encontrada en el almacén JIT.`);
+        }
+        return buf.toString('utf8');
+    }
+}
+exports.DatabaseHooks = DatabaseHooks;

package/dist/core/hardening.d.ts

@@ -0,0 +1,2 @@
+import { HardeningReport } from '../types';
+export declare function verifyRuntimeHardening(paranoiaArmed: boolean): HardeningReport;

package/dist/core/hardening.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyRuntimeHardening = verifyRuntimeHardening;
+const fs_1 = __importDefault(require("fs"));
+function readCoreDumpSoftLimit() {
+    try {
+        const text = fs_1.default.readFileSync('/proc/self/limits', 'utf8');
+        const line = text.split('\n').find((entry) => entry.toLowerCase().startsWith('max core file size'));
+        if (!line)
+            return null;
+        const cols = line.split(/\s{2,}/).map((part) => part.trim());
+        if (!cols[1])
+            return null;
+        return cols[1] === '0';
+    }
+    catch {
+        return null;
+    }
+}
+function verifyRuntimeHardening(paranoiaArmed) {
+    const recommendations = [];
+    const nodeEnv = process.env.NODE_ENV || 'development';
+    let runningAsRoot = false;
+    try {
+        if (typeof process.getuid === 'function') {
+            runningAsRoot = process.getuid() === 0;
+        }
+    }
+    catch {
+        // Windows or a restricted environment.
+    }
+    const coreDumpsDisabled = readCoreDumpSoftLimit();
+    if (runningAsRoot) {
+        recommendations.push('El proceso corre como root (UID 0). En producción usa un usuario sin privilegios.');
+    }
+    if (nodeEnv !== 'production') {
+        recommendations.push('NODE_ENV no es "production".');
+    }
+    if (coreDumpsDisabled === null) {
+        recommendations.push('No se pudo leer el límite de core dumps. En Linux revisa /proc/self/limits (Max core file size).');
+    }
+    else if (!coreDumpsDisabled) {
+        recommendations.push('Los core dumps están permitidos. Un ulimit -c 0 evita que un volcado escriba la memoria a disco.');
+    }
+    if (!paranoiaArmed) {
+        recommendations.push('El modo paranoia no está armado. Los secretos no pasaron por el proxy de process.env.');
+    }
+    const isHardened = !runningAsRoot && nodeEnv === 'production' && coreDumpsDisabled === true && paranoiaArmed;
+    console.log('\n🛡️ [Titan Vault] Reporte de hardening:');
+    console.log(`  - Entorno: ${nodeEnv}`);
+    console.log(`  - Usuario root: ${runningAsRoot ? 'sí' : 'no'}`);
+    console.log(`  - Core dumps desactivados: ${coreDumpsDisabled === null ? 'desconocido' : coreDumpsDisabled ? 'sí' : 'no'}`);
+    console.log(`  - Modo paranoia armado: ${paranoiaArmed ? 'sí' : 'no'}`);
+    for (const rec of recommendations) {
+        console.log(`    ${rec}`);
+    }
+    console.log('');
+    return {
+        isHardened,
+        nodeEnv,
+        coreDumpsDisabled: coreDumpsDisabled === true,
+        coreDumpLimitKnown: coreDumpsDisabled !== null,
+        runningAsRoot,
+        paranoiaArmed,
+        recommendations,
+    };
+}

package/dist/core/poison.d.ts

@@ -0,0 +1,5 @@
+export declare class ParanoiaBlockedError extends Error {
+    readonly key: string;
+    constructor(key: string, reason?: string);
+}
+export declare function poisonProcessEnv(secretKeys: string[], honeytokenKey?: string, onHoneytokenDetonated?: (key: string) => void): void;

package/dist/core/poison.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParanoiaBlockedError = void 0;
+exports.poisonProcessEnv = poisonProcessEnv;
+class ParanoiaBlockedError extends Error {
+    key;
+    constructor(key, reason) {
+        super(`🚨 [Titan Vault - Modo Paranoia] Acceso bloqueado a 'process.env.${key}'. ` +
+            (reason ||
+                `Esta variable fue clasificada como secreto crítico y ha sido envenenada para prevenir Memory Dumps / Heap Dumps. ` +
+                    `Usa 'TitanVault.secrets.get("${key}")' (KeyObject) o hooks JIT de Base de Datos.`));
+        this.name = 'ParanoiaBlockedError';
+        this.key = key;
+        Object.setPrototypeOf(this, ParanoiaBlockedError.prototype);
+    }
+}
+exports.ParanoiaBlockedError = ParanoiaBlockedError;
+function poisonProcessEnv(secretKeys, honeytokenKey, onHoneytokenDetonated) {
+    const poisonedSet = new Set(secretKeys);
+    const honeyKey = honeytokenKey || 'VAULT_EMERGENCY_RECOVERY_TOKEN';
+    // 1. Delete existing raw values from underlying process.env
+    for (const key of secretKeys) {
+        try {
+            delete process.env[key];
+        }
+        catch {
+            // ignore
+        }
+    }
+    // 2. Wrap process.env in a Proxy
+    const targetEnv = process.env;
+    const envProxy = new Proxy(targetEnv, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string') {
+                if (prop === honeyKey) {
+                    if (onHoneytokenDetonated) {
+                        try {
+                            onHoneytokenDetonated(prop);
+                        }
+                        catch {
+                            // ignore
+                        }
+                    }
+                    throw new ParanoiaBlockedError(prop, `HONEYTOKEN DETONADO. Intento de acceso a '${prop}' detectado. Alerta de intrusión emitida.`);
+                }
+                if (poisonedSet.has(prop)) {
+                    throw new ParanoiaBlockedError(prop);
+                }
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+        set(target, prop, value, receiver) {
+            if (typeof prop === 'string' && (prop === honeyKey || poisonedSet.has(prop))) {
+                throw new ParanoiaBlockedError(prop, `No se permite mutar 'process.env.${prop}' en Modo Paranoia.`);
+            }
+            return Reflect.set(target, prop, value, receiver);
+        },
+        has(target, prop) {
+            if (typeof prop === 'string' && (prop === honeyKey || poisonedSet.has(prop))) {
+                return false;
+            }
+            return Reflect.has(target, prop);
+        },
+        ownKeys(target) {
+            return Reflect.ownKeys(target).filter((k) => typeof k !== 'string' || (k !== honeyKey && !poisonedSet.has(k)));
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (typeof prop === 'string' && (prop === honeyKey || poisonedSet.has(prop))) {
+                return undefined;
+            }
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+    });
+    process.env = envProxy;
+}

package/dist/core/transit-client.d.ts

@@ -0,0 +1,13 @@
+import { TransitKeyInfo } from '../types';
+export declare class TransitClient {
+    private getBaseUrl;
+    private getToken;
+    constructor(getBaseUrl: () => string, getToken: () => string | undefined);
+    private getHeaders;
+    createKey(name: string, keyType?: 'aes-gcm' | 'hmac-sha256'): Promise<TransitKeyInfo>;
+    listKeys(): Promise<TransitKeyInfo[]>;
+    encrypt(name: string, plaintext: string): Promise<string>;
+    decrypt(name: string, ciphertext: string): Promise<string>;
+    sign(name: string, data: string): Promise<string>;
+    verify(name: string, data: string, signature: string): Promise<boolean>;
+}

package/dist/core/transit-client.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransitClient = void 0;
+class TransitClient {
+    getBaseUrl;
+    getToken;
+    constructor(getBaseUrl, getToken) {
+        this.getBaseUrl = getBaseUrl;
+        this.getToken = getToken;
+    }
+    getHeaders() {
+        const token = this.getToken();
+        if (!token) {
+            throw new Error('[Titan Vault - Transit] Token de Vault no configurado.');
+        }
+        return {
+            'Content-Type': 'application/json',
+            'x-vault-token': token,
+        };
+    }
+    async createKey(name, keyType = 'aes-gcm') {
+        const url = `${this.getBaseUrl()}/transit/keys/${encodeURIComponent(name)}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ key_type: keyType }),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`[Titan Vault - Transit] Error creando llave '${name}': ${err}`);
+        }
+        return res.json();
+    }
+    async listKeys() {
+        const url = `${this.getBaseUrl()}/transit/keys`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`[Titan Vault - Transit] Error listando llaves: ${err}`);
+        }
+        return res.json();
+    }
+    async encrypt(name, plaintext) {
+        const url = `${this.getBaseUrl()}/transit/encrypt/${encodeURIComponent(name)}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ plaintext }),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`[Titan Vault - Transit] Error cifrando con '${name}': ${err}`);
+        }
+        const json = (await res.json());
+        return json.ciphertext;
+    }
+    async decrypt(name, ciphertext) {
+        const url = `${this.getBaseUrl()}/transit/decrypt/${encodeURIComponent(name)}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ ciphertext }),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`[Titan Vault - Transit] Error descifrando con '${name}': ${err}`);
+        }
+        const json = (await res.json());
+        return json.plaintext;
+    }
+    async sign(name, data) {
+        const url = `${this.getBaseUrl()}/transit/sign/${encodeURIComponent(name)}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ data }),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`[Titan Vault - Transit] Error firmando con '${name}': ${err}`);
+        }
+        const json = (await res.json());
+        return json.signature;
+    }
+    async verify(name, data, signature) {
+        const url = `${this.getBaseUrl()}/transit/verify/${encodeURIComponent(name)}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ data, signature }),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`[Titan Vault - Transit] Error verificando firma con '${name}': ${err}`);
+        }
+        const json = (await res.json());
+        return json.valid;
+    }
+}
+exports.TransitClient = TransitClient;

package/dist/index.d.ts

@@ -1,9 +1,47 @@
-interface VaultOptions {
-    vaultUrl?: string;
-    vaultToken?: string;
-    path?: string;
-    maxRetries?: number;
-    retryDelayMs?: number;
+import { VaultOptions, HardeningReport } from './types';
+import { CryptoStore } from './core/crypto-store';
+import { DatabaseHooks } from './core/database-hooks';
+import { TransitClient } from './core/transit-client';
+export * from './types';
+export * from './core/poison';
+export * from './core/crypto-store';
+export * from './core/database-hooks';
+export * from './core/transit-client';
+export * from './core/hardening';
+export * from './core/classify';
+export declare class VaultConnectionError extends Error {
+    constructor(message: string);
 }
+export declare class TitanVault {
+    private static instance;
+    static readonly secrets: CryptoStore;
+    static readonly databases: DatabaseHooks;
+    private static rawConfig;
+    private static vaultUrl;
+    private static vaultToken?;
+    private static isArmed;
+    private static baitValues;
+    private static tripwireInflight;
+    static readonly transit: TransitClient;
+    static readonly config: {
+        get(key: string, defaultValue?: string): string;
+        has(key: string): boolean;
+        getAll(): Record<string, string>;
+    };
+    /**
+     * Fetch the app path with an ephemeral RSA-2048 key, decrypt the hybrid
+     * payload, and block secret reads on process.env.
+     * Throws if the token is missing or the vault does not return ciphertext.
+     */
+    static armParanoiaMode(options?: VaultOptions): Promise<void>;
+    /** Resolves when the in-flight honeytoken alert has finished or failed. */
+    static flushTripwire(): Promise<void>;
+    static bootstrap(serverFn: () => Promise<any>, options?: VaultOptions): Promise<void>;
+    static verifyRuntimeHardening(): HardeningReport;
+}
+/**
+ * Classic mode (`paranoiaMode: false`) copies string values into process.env.
+ * The default calls armParanoiaMode and throws if the vault is unreachable.
+ */
 export declare function initVault(options?: VaultOptions): Promise<void>;
-export {};
+export default TitanVault;

package/dist/index.js

@@ -1,84 +1,292 @@
 "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);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TitanVault = exports.VaultConnectionError = void 0;
 exports.initVault = initVault;
 const dotenv_1 = __importDefault(require("dotenv"));
 const crypto_1 = __importDefault(require("crypto"));
-async function initVault(options = {}) {
-    // Load local .env first to get base configs (like VAULT_URL or VAULT_TOKEN)
-    dotenv_1.default.config();
-    const VAULT_URL = options.vaultUrl || process.env.VAULT_URL || 'http://127.0.0.1:8200';
-    const VAULT_TOKEN = options.vaultToken || process.env.VAULT_TOKEN;
-    const SECRET_PATH = options.path || 'backend_env';
-    const MAX_RETRIES = options.maxRetries || 5;
-    const RETRY_DELAY = options.retryDelayMs || 5000;
-    if (!VAULT_TOKEN) {
-        console.warn("⚠️ [Titan Vault] No VAULT_TOKEN found. Using local .env fallback.");
-        return;
+const poison_1 = require("./core/poison");
+const crypto_store_1 = require("./core/crypto-store");
+const database_hooks_1 = require("./core/database-hooks");
+const transit_client_1 = require("./core/transit-client");
+const hardening_1 = require("./core/hardening");
+const classify_1 = require("./core/classify");
+__exportStar(require("./types"), exports);
+__exportStar(require("./core/poison"), exports);
+__exportStar(require("./core/crypto-store"), exports);
+__exportStar(require("./core/database-hooks"), exports);
+__exportStar(require("./core/transit-client"), exports);
+__exportStar(require("./core/hardening"), exports);
+__exportStar(require("./core/classify"), exports);
+class VaultConnectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VaultConnectionError';
+        Object.setPrototypeOf(this, VaultConnectionError.prototype);
     }
-    console.log(`\n🔒 [Titan Vault] Conectando a ${VAULT_URL}...`);
-    // E2E Encryption: Generate ephemeral RSA keypair
-    const { publicKey, privateKey } = crypto_1.default.generateKeyPairSync('rsa', {
-        modulusLength: 2048,
-        publicKeyEncoding: { type: 'spki', format: 'pem' },
-        privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
-    });
-    const pubBase64 = Buffer.from(publicKey).toString('base64');
-    let attempt = 0;
-    while (attempt < MAX_RETRIES) {
-        attempt++;
-        try {
-            const res = await fetch(`${VAULT_URL}/secret/data/${SECRET_PATH}`, {
-                headers: {
-                    "x-vault-token": VAULT_TOKEN,
-                    "x-vault-public-key": pubBase64
+}
+exports.VaultConnectionError = VaultConnectionError;
+function resolveToken(explicit) {
+    return explicit || process.env.VAULT_TOKEN || process.env.VAULT_APP_TOKEN;
+}
+function resolveUrl(explicit) {
+    return explicit || process.env.VAULT_URL || 'http://127.0.0.1:8200';
+}
+function decryptHybrid(privateKey, payloadB64) {
+    const buffer = Buffer.from(payloadB64, 'base64');
+    const modulusLength = privateKey.asymmetricKeyDetails?.modulusLength;
+    if (!modulusLength) {
+        throw new VaultConnectionError('No se pudo leer el tamaño de la llave RSA efímera.');
+    }
+    const keyBytes = modulusLength / 8;
+    if (buffer.length < keyBytes + 16) {
+        throw new VaultConnectionError('El payload cifrado es más corto que una respuesta RSA-OAEP + AES-256-CFB.');
+    }
+    const encAesKey = buffer.subarray(0, keyBytes);
+    const iv = buffer.subarray(keyBytes, keyBytes + 16);
+    const ciphertext = buffer.subarray(keyBytes + 16);
+    const aesKey = crypto_1.default.privateDecrypt({
+        key: privateKey,
+        padding: crypto_1.default.constants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: 'sha256',
+    }, encAesKey);
+    try {
+        const decipher = crypto_1.default.createDecipheriv('aes-256-cfb', aesKey, iv);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return decrypted.toString('utf8');
+    }
+    finally {
+        aesKey.fill(0);
+    }
+}
+class TitanVault {
+    static instance;
+    static secrets = new crypto_store_1.CryptoStore();
+    static databases = new database_hooks_1.DatabaseHooks();
+    static rawConfig = new Map();
+    static vaultUrl = 'http://127.0.0.1:8200';
+    static vaultToken;
+    static isArmed = false;
+    static baitValues = new Map();
+    static tripwireInflight = Promise.resolve();
+    static transit = new transit_client_1.TransitClient(() => TitanVault.vaultUrl, () => TitanVault.vaultToken);
+    static config = {
+        get(key, defaultValue) {
+            if (TitanVault.rawConfig.has(key)) {
+                return TitanVault.rawConfig.get(key);
+            }
+            let envVal;
+            try {
+                envVal = process.env[key];
+            }
+            catch (err) {
+                if (err instanceof Error && err.name === 'ParanoiaBlockedError') {
+                    throw new Error(`[Titan Vault] '${key}' es un secreto. Usa TitanVault.secrets, TitanVault.databases o el campo de configuración correspondiente.`);
                 }
-            });
-            if (res.ok) {
-                const json = await res.json();
-                let finalSecretStr = "";
-                if (json.data && json.data.is_encrypted) {
-                    console.log("🔐 [Titan Vault] Descifrando payload E2E híbrido (RSA-OAEP + AES-CFB)...");
-                    const buffer = Buffer.from(json.data.value, 'base64');
-                    const encAesKey = buffer.subarray(0, 256);
-                    const iv = buffer.subarray(256, 256 + 16);
-                    const ciphertext = buffer.subarray(256 + 16);
-                    const aesKey = crypto_1.default.privateDecrypt({
-                        key: privateKey,
-                        padding: crypto_1.default.constants.RSA_PKCS1_OAEP_PADDING,
-                        oaepHash: "sha256"
-                    }, encAesKey);
-                    const decipher = crypto_1.default.createDecipheriv('aes-256-cfb', aesKey, iv);
-                    let decrypted = decipher.update(ciphertext, undefined, 'utf8');
-                    decrypted += decipher.final('utf8');
-                    finalSecretStr = decrypted;
+                throw err;
+            }
+            if (envVal !== undefined)
+                return envVal;
+            if (defaultValue !== undefined)
+                return defaultValue;
+            throw new Error(`[Titan Vault] Configuración '${key}' no encontrada.`);
+        },
+        has(key) {
+            return TitanVault.rawConfig.has(key) || key in process.env;
+        },
+        getAll() {
+            const res = {};
+            for (const [k, v] of TitanVault.rawConfig.entries()) {
+                res[k] = v;
+            }
+            return res;
+        }
+    };
+    /**
+     * Fetch the app path with an ephemeral RSA-2048 key, decrypt the hybrid
+     * payload, and block secret reads on process.env.
+     * Throws if the token is missing or the vault does not return ciphertext.
+     */
+    static async armParanoiaMode(options = {}) {
+        if (this.isArmed) {
+            console.log('🛡️ [Titan Vault] Modo paranoia ya está armado.');
+            return;
+        }
+        dotenv_1.default.config();
+        this.vaultUrl = resolveUrl(options.vaultUrl);
+        this.vaultToken = resolveToken(options.vaultToken);
+        const secretPath = options.path || 'backend_env';
+        const maxRetries = options.maxRetries ?? 5;
+        const retryDelay = options.retryDelayMs ?? 5000;
+        const honeyField = options.honeytokenField || classify_1.HONEYTOKEN_FIELD;
+        if (!this.vaultToken) {
+            throw new VaultConnectionError('Falta el token. Pasa vaultToken o define VAULT_TOKEN / VAULT_APP_TOKEN. El proceso no arranca sin la bóveda.');
+        }
+        console.log(`\n🛡️ [Titan Vault] Conectando a ${this.vaultUrl}...`);
+        const { publicKey, privateKey } = crypto_1.default.generateKeyPairSync('rsa', {
+            modulusLength: 2048,
+        });
+        const pubPem = publicKey.export({ type: 'spki', format: 'pem' });
+        const pubBase64 = Buffer.from(pubPem).toString('base64');
+        let rawSecrets = null;
+        let lastError = 'sin respuesta';
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                const res = await fetch(`${this.vaultUrl}/secret/data/${secretPath}`, {
+                    headers: {
+                        'x-vault-token': this.vaultToken,
+                        'x-vault-public-key': pubBase64,
+                    },
+                });
+                if (!res.ok) {
+                    lastError = `HTTP ${res.status}: ${await res.text()}`;
+                    console.warn(`[Titan Vault] ${lastError}. Reintento ${attempt}/${maxRetries}.`);
                 }
                 else {
-                    finalSecretStr = json.data.value;
+                    const json = await res.json();
+                    if (!json.data?.is_encrypted || typeof json.data.value !== 'string') {
+                        throw new VaultConnectionError('La bóveda devolvió el secreto en claro después de recibir x-vault-public-key.');
+                    }
+                    console.log('🔐 [Titan Vault] Descifrando payload híbrido (RSA-OAEP-SHA256 + AES-256-CFB)...');
+                    rawSecrets = JSON.parse(decryptHybrid(privateKey, json.data.value));
+                    break;
                 }
-                const secrets = JSON.parse(finalSecretStr);
-                // Inject into process.env
-                let injectedCount = 0;
-                for (const [key, value] of Object.entries(secrets)) {
-                    process.env[key] = value;
-                    injectedCount++;
-                }
-                console.log(`✅ [Titan Vault] ${injectedCount} secretos inyectados en memoria (Zero-Trust).`);
-                return; // Success!
             }
-            else {
-                const errText = await res.text();
-                console.warn(`[Titan Vault] Vault sellado o token inválido (HTTP ${res.status}): ${errText}. Reintentando en ${RETRY_DELAY / 1000}s...`);
+            catch (err) {
+                if (err instanceof VaultConnectionError)
+                    throw err;
+                lastError = err?.message || String(err);
+                console.warn(`❌ [Titan Vault] ${lastError}. Reintento ${attempt}/${maxRetries}.`);
             }
+            if (attempt < maxRetries) {
+                await new Promise((resolve) => setTimeout(resolve, retryDelay));
+            }
+        }
+        if (!rawSecrets) {
+            throw new VaultConnectionError(`No se pudieron leer los secretos de '${secretPath}' en ${this.vaultUrl}. ${lastError}`);
         }
-        catch (err) {
-            console.warn(`❌ [Titan Vault] Error de conexión (${err.message}). Reintentando en ${RETRY_DELAY / 1000}s...`);
+        const classification = rawSecrets['__titan_classification__'] || {};
+        delete rawSecrets['__titan_classification__'];
+        const allowedEnvList = new Set(options.allowedEnvKeys || ['NODE_ENV', 'PORT', 'HOST', 'FRONTEND_PORT', 'BACKEND_PORT']);
+        const poisonedKeys = [];
+        this.baitValues = new Map();
+        let cryptoCount = 0;
+        let dbCount = 0;
+        let configCount = 0;
+        for (const [key, value] of Object.entries(rawSecrets)) {
+            if (typeof value !== 'string')
+                continue;
+            const kind = (0, classify_1.classifyKey)(key, classification[key], options);
+            if (kind === 'honeytoken') {
+                this.baitValues.set(key, value);
+                poisonedKeys.push(key);
+            }
+            else if (kind === 'crypto') {
+                this.secrets.register(key, value);
+                poisonedKeys.push(key);
+                cryptoCount++;
+            }
+            else if (kind === 'database') {
+                this.databases.register(key, value);
+                poisonedKeys.push(key);
+                dbCount++;
+            }
+            else {
+                this.rawConfig.set(key, value);
+                if (allowedEnvList.has(key)) {
+                    process.env[key] = value;
+                }
+                configCount++;
+            }
         }
-        if (attempt < MAX_RETRIES) {
-            await new Promise(resolve => setTimeout(resolve, RETRY_DELAY));
+        if (!poisonedKeys.includes(honeyField)) {
+            poisonedKeys.push(honeyField);
         }
+        const onDetonate = (tokenKey) => {
+            console.error(`\n🚨 [Titan Vault] Honeytoken '${tokenKey}' leído desde process.env.`);
+            const bait = this.baitValues.get(tokenKey);
+            if (bait) {
+                this.tripwireInflight = fetch(`${this.vaultUrl}/sys/recovery`, {
+                    headers: { 'x-vault-token': bait },
+                }).then(() => undefined, () => undefined);
+            }
+            options.onHoneytokenDetonated?.(tokenKey);
+        };
+        (0, poison_1.poisonProcessEnv)(poisonedKeys, honeyField, onDetonate);
+        this.isArmed = true;
+        console.log('🛡️ [Titan Vault] Modo paranoia armado:');
+        console.log(`   - ${cryptoCount} llaves en KeyObject (sin copia string en el SDK)`);
+        console.log(`   - ${dbCount} contraseñas de base de datos para hooks JIT`);
+        console.log(`   - ${configCount} valores de configuración, fuera de process.env salvo la lista permitida`);
+        console.log(`   - ${poisonedKeys.length} nombres bloqueados en process.env`);
+        console.log(this.baitValues.size
+            ? '   - trampa armada: leerla llama a GET /sys/recovery con el valor inyectado por la bóveda'
+            : '   - trampa local activa, sin cebo en el payload (la bóveda no se sella)');
+    }
+    /** Resolves when the in-flight honeytoken alert has finished or failed. */
+    static flushTripwire() {
+        return this.tripwireInflight;
+    }
+    static async bootstrap(serverFn, options = {}) {
+        await this.armParanoiaMode(options);
+        console.log('🚀 [Titan Vault] Secretos cargados. Arrancando servidor...');
+        await serverFn();
+    }
+    static verifyRuntimeHardening() {
+        return (0, hardening_1.verifyRuntimeHardening)(this.isArmed);
+    }
+}
+exports.TitanVault = TitanVault;
+/**
+ * Classic mode (`paranoiaMode: false`) copies string values into process.env.
+ * The default calls armParanoiaMode and throws if the vault is unreachable.
+ */
+async function initVault(options = {}) {
+    if (options.paranoiaMode !== false) {
+        await TitanVault.armParanoiaMode(options);
+        return;
+    }
+    dotenv_1.default.config();
+    const vaultUrl = resolveUrl(options.vaultUrl);
+    const vaultToken = resolveToken(options.vaultToken);
+    const secretPath = options.path || 'backend_env';
+    const honeyField = options.honeytokenField || classify_1.HONEYTOKEN_FIELD;
+    if (!vaultToken) {
+        console.warn('⚠️ [Titan Vault] Sin token. Se mantienen las variables de .env.');
+        return;
+    }
+    const res = await fetch(`${vaultUrl}/secret/data/${secretPath}`, {
+        headers: { 'x-vault-token': vaultToken },
+    });
+    if (!res.ok) {
+        throw new VaultConnectionError(`Modo clásico: la bóveda respondió HTTP ${res.status} al leer '${secretPath}'.`);
+    }
+    const json = await res.json();
+    const secrets = typeof json.data?.value === 'string' ? JSON.parse(json.data.value) : json.data?.value || {};
+    const classification = secrets['__titan_classification__'] || {};
+    for (const [key, value] of Object.entries(secrets)) {
+        if (key === '__titan_classification__' || typeof value !== 'string')
+            continue;
+        if ((0, classify_1.classifyKey)(key, classification[key], options) === 'honeytoken' || key === honeyField)
+            continue;
+        process.env[key] = value;
     }
-    console.error("🚨 [Titan Vault] No se pudo conectar al vault tras múltiples intentos. Iniciando con secretos locales si existen.");
+    console.log('✅ [Titan Vault] Secretos copiados a process.env (modo clásico).');
 }
+exports.default = TitanVault;

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+export type SecretType = 'crypto' | 'database' | 'config' | 'honeytoken';
+export interface VaultOptions {
+    vaultUrl?: string;
+    vaultToken?: string;
+    path?: string;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    /**
+     * If true, activates Paranoia Mode (process.env poisoning, C++ KeyObject storage, JIT DB credentials).
+     * Defaults to true in armParanoiaMode().
+     */
+    paranoiaMode?: boolean;
+    /**
+     * Keys explicitly marked as cryptographic secrets (instantiated as C++ KeyObjects).
+     */
+    cryptoKeys?: string[];
+    /**
+     * Keys explicitly marked as database credentials (accessible only via JIT DB hooks).
+     */
+    dbKeys?: string[];
+    /**
+     * Keys that are safe to expose in process.env (e.g. PORT, NODE_ENV).
+     */
+    allowedEnvKeys?: string[];
+    /**
+     * Field the vault injects when `TITAN_HONEYTOKEN_FIELD` is set.
+     * Defaults to `VAULT_EMERGENCY_RECOVERY_TOKEN`.
+     */
+    honeytokenField?: string;
+    /**
+     * Custom callback triggered if a honeytoken is accessed in process.env.
+     */
+    onHoneytokenDetonated?: (tokenName: string) => void;
+}
+export interface TransitKeyInfo {
+    name: string;
+    key_type: 'aes-gcm' | 'hmac-sha256' | string;
+    created_at: string | null;
+    status?: string;
+}
+export interface TransitEncryptResult {
+    ciphertext: string;
+    name: string;
+}
+export interface TransitDecryptResult {
+    plaintext: string;
+    name: string;
+}
+export interface TransitSignResult {
+    signature: string;
+    name: string;
+}
+export interface TransitVerifyResult {
+    valid: boolean;
+    name: string;
+}
+export interface HardeningReport {
+    isHardened: boolean;
+    nodeEnv: string;
+    /** True only when the soft core limit was read and is 0. */
+    coreDumpsDisabled: boolean;
+    /** False when `/proc/self/limits` could not be read. */
+    coreDumpLimitKnown: boolean;
+    runningAsRoot: boolean;
+    paranoiaArmed: boolean;
+    recommendations: string[];
+}

package/dist/types.js

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

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "titan-vault-node",
-  "version": "1.0.0",
-  "description": "Zero-trust, E2E encrypted, drop-in replacement for dotenv.",
+  "version": "2.1.0",
+  "description": "Client for Titan Vault. Decrypts the hybrid secret payload, blocks secret reads on process.env, and calls transit on the vault.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test test/harmony.test.mjs"
   },
   "keywords": [
     "vault",

package/src/index.ts

@@ -1,101 +0,0 @@
-import dotenv from 'dotenv';
-import crypto from 'crypto';
-
-interface VaultOptions {
-  vaultUrl?: string;
-  vaultToken?: string;
-  path?: string;
-  maxRetries?: number;
-  retryDelayMs?: number;
-}
-
-export async function initVault(options: VaultOptions = {}) {
-  // Load local .env first to get base configs (like VAULT_URL or VAULT_TOKEN)
-  dotenv.config();
-
-  const VAULT_URL = options.vaultUrl || process.env.VAULT_URL || 'http://127.0.0.1:8200';
-  const VAULT_TOKEN = options.vaultToken || process.env.VAULT_TOKEN;
-  const SECRET_PATH = options.path || 'backend_env';
-  const MAX_RETRIES = options.maxRetries || 5;
-  const RETRY_DELAY = options.retryDelayMs || 5000;
-
-  if (!VAULT_TOKEN) {
-    console.warn("⚠️ [Titan Vault] No VAULT_TOKEN found. Using local .env fallback.");
-    return;
-  }
-
-  console.log(`\n🔒 [Titan Vault] Conectando a ${VAULT_URL}...`);
-  
-  // E2E Encryption: Generate ephemeral RSA keypair
-  const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
-    modulusLength: 2048,
-    publicKeyEncoding: { type: 'spki', format: 'pem' },
-    privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
-  });
-  
-  const pubBase64 = Buffer.from(publicKey).toString('base64');
-  let attempt = 0;
-
-  while (attempt < MAX_RETRIES) {
-    attempt++;
-    try {
-      const res = await fetch(`${VAULT_URL}/secret/data/${SECRET_PATH}`, {
-        headers: { 
-          "x-vault-token": VAULT_TOKEN,
-          "x-vault-public-key": pubBase64
-        }
-      });
-      
-      if (res.ok) {
-        const json = await res.json();
-        let finalSecretStr = "";
-        
-        if (json.data && json.data.is_encrypted) {
-          console.log("🔐 [Titan Vault] Descifrando payload E2E híbrido (RSA-OAEP + AES-CFB)...");
-          const buffer = Buffer.from(json.data.value, 'base64');
-          
-          const encAesKey = buffer.subarray(0, 256);
-          const iv = buffer.subarray(256, 256 + 16);
-          const ciphertext = buffer.subarray(256 + 16);
-
-          const aesKey = crypto.privateDecrypt({
-              key: privateKey,
-              padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
-              oaepHash: "sha256"
-          }, encAesKey);
-
-          const decipher = crypto.createDecipheriv('aes-256-cfb', aesKey, iv);
-          let decrypted = decipher.update(ciphertext, undefined, 'utf8');
-          decrypted += decipher.final('utf8');
-          
-          finalSecretStr = decrypted;
-        } else {
-          finalSecretStr = json.data.value;
-        }
-
-        const secrets = JSON.parse(finalSecretStr);
-        
-        // Inject into process.env
-        let injectedCount = 0;
-        for (const [key, value] of Object.entries(secrets)) {
-          process.env[key] = value as string;
-          injectedCount++;
-        }
-        
-        console.log(`✅ [Titan Vault] ${injectedCount} secretos inyectados en memoria (Zero-Trust).`);
-        return; // Success!
-      } else {
-        const errText = await res.text();
-        console.warn(`[Titan Vault] Vault sellado o token inválido (HTTP ${res.status}): ${errText}. Reintentando en ${RETRY_DELAY/1000}s...`);
-      }
-    } catch (err: any) {
-      console.warn(`❌ [Titan Vault] Error de conexión (${err.message}). Reintentando en ${RETRY_DELAY/1000}s...`);
-    }
-    
-    if (attempt < MAX_RETRIES) {
-      await new Promise(resolve => setTimeout(resolve, RETRY_DELAY));
-    }
-  }
-  
-  console.error("🚨 [Titan Vault] No se pudo conectar al vault tras múltiples intentos. Iniciando con secretos locales si existen.");
-}

package/tsconfig.json

@@ -1,14 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "CommonJS",
-    "moduleResolution": "node",
-    "declaration": true,
-    "outDir": "./dist",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src/**/*"]
-}