@hostwebhook/platform-node 0.1.0

package/dist/crypto.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Una llave, o varias.
+ *
+ * Con varias, **la PRIMERA es la que cifra** y las demás sólo sirven para leer
+ * lo que se cifró antes. Existe porque las credenciales van a tener llave
+ * propia —separada de `api.secret`, que cifra otras seis cosas— y no se pueden
+ * re-cifrar todas en el mismo instante en que cambia el código.
+ *
+ * ⚠️ Que funcione depende de que esto sea AES-GCM: el tag de autenticación
+ * hace que descifrar con la llave equivocada FALLE en vez de devolver basura.
+ * Con un cifrado sin autenticar, probar llaves en cadena devolvería un secreto
+ * corrupto que parecería válido. Si algún día se cambia de algoritmo, esto se
+ * cae con él.
+ */
+export type Llaves = string | string[];
+export declare function encrypt(text: string, llaves: Llaves): string;
+/**
+ * Descifra probando cada llave, y con cada una los dos KDF.
+ *
+ * ⚠️ El orden importa para el COSTE, no para la corrección: el tag de GCM
+ * garantiza que sólo una combinación puede acertar. Se prueba primero la que
+ * cifra, que es la que acertará en cuanto la migración haya pasado.
+ */
+export declare function decrypt(encrypted: string, llaves: Llaves): string;

package/dist/crypto.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+const crypto_1 = require("crypto");
+const ALGO = 'aes-256-gcm';
+const KDF_SALT = 'hostwebhook-credential-encryption';
+const KDF_ITERATIONS = 100000;
+/**
+ * Llaves ya derivadas, por secreto.
+ *
+ * `pbkdf2Sync` con 100.000 iteraciones cuesta **28 ms medidos**, y es
+ * SÍNCRONO: bloquea el bucle de eventos entero mientras corre. Se pagaba en
+ * CADA `encrypt`/`decrypt`, o sea en cada nodo que resuelve una credencial —
+ * un pipeline con tres se comía ~84 ms de API parada por evento.
+ *
+ * Y era gasto puro: la derivación depende sólo de la sal (constante) y del
+ * secreto, que es `api.secret` — el mismo durante toda la vida del proceso.
+ * Derivar 100.000 veces lo mismo no protege de nada más; el coste alto de
+ * PBKDF2 defiende contra fuerza bruta sobre la llave, y eso ya lo pagas la
+ * primera vez.
+ *
+ * `Map` y no un solo valor porque hay dos derivaciones (la nueva y la legacy)
+ * y nada impide que se cifre con más de un secreto en el mismo proceso.
+ */
+const llavesDerivadas = new Map();
+function deriveKey(secret) {
+    const cacheada = llavesDerivadas.get(secret);
+    if (cacheada)
+        return cacheada;
+    const key = (0, crypto_1.pbkdf2Sync)(secret, KDF_SALT, KDF_ITERATIONS, 32, 'sha256');
+    llavesDerivadas.set(secret, key);
+    return key;
+}
+/** Legacy key derivation — only for decrypting old credentials */
+function legacyKey(secret) {
+    return Buffer.from(secret.padEnd(32).slice(0, 32));
+}
+/** La que cifra. */
+const paraCifrar = (l) => (Array.isArray(l) ? l[0] : l);
+/** Todas las que pueden descifrar, en orden. */
+const paraDescifrar = (l) => (Array.isArray(l) ? l : [l]);
+function encrypt(text, llaves) {
+    const secret = paraCifrar(llaves);
+    const key = deriveKey(secret);
+    const iv = (0, crypto_1.randomBytes)(16);
+    const cipher = (0, crypto_1.createCipheriv)(ALGO, key, iv);
+    const encrypted = Buffer.concat([
+        cipher.update(text, 'utf8'),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`;
+}
+function conLlave(encrypted, key) {
+    const [ivHex, tagHex, dataHex] = encrypted.split(':');
+    const decipher = (0, crypto_1.createDecipheriv)(ALGO, key, Buffer.from(ivHex, 'hex'));
+    decipher.setAuthTag(Buffer.from(tagHex, 'hex'));
+    return decipher.update(dataHex, 'hex', 'utf8') + decipher.final('utf8');
+}
+/**
+ * Descifra probando cada llave, y con cada una los dos KDF.
+ *
+ * ⚠️ El orden importa para el COSTE, no para la corrección: el tag de GCM
+ * garantiza que sólo una combinación puede acertar. Se prueba primero la que
+ * cifra, que es la que acertará en cuanto la migración haya pasado.
+ */
+function decrypt(encrypted, llaves) {
+    const secretos = paraDescifrar(llaves);
+    let ultimo;
+    for (const secret of secretos) {
+        try {
+            return conLlave(encrypted, deriveKey(secret));
+        }
+        catch (e) {
+            ultimo = e;
+        }
+        try {
+            // Credenciales viejas, cifradas con la derivación anterior.
+            return conLlave(encrypted, legacyKey(secret));
+        }
+        catch (e) {
+            ultimo = e;
+        }
+    }
+    throw ultimo instanceof Error
+        ? ultimo
+        : new Error('no se pudo descifrar con ninguna de las llaves');
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { encrypt, decrypt, type Llaves } from './crypto';

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decrypt = exports.encrypt = void 0;
+var crypto_1 = require("./crypto");
+Object.defineProperty(exports, "encrypt", { enumerable: true, get: function () { return crypto_1.encrypt; } });
+Object.defineProperty(exports, "decrypt", { enumerable: true, get: function () { return crypto_1.decrypt; } });

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@hostwebhook/platform-node",
+  "version": "0.1.0",
+  "description": "Lo que los servicios de HostWebhook comparten del lado de NODE: cifrado y utilidades que no pueden estar escritas dos veces",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hostwebhook",
+    "crypto",
+    "platform"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}