@syldel/crypto-utils 1.0.3 → 2.0.0

package/LICENSE.MD

@@ -1,5 +1,5 @@
-Copyright (c) 2026, Syl-Studio Inc. c/o Syl. D.
-
-Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
-
+Copyright (c) 2026, Syl-Studio Inc. c/o Syl. D.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -3,45 +3,73 @@
 A robust, high-performance cryptographic toolkit for Node.js and NestJS applications. This package prioritizes security by leveraging Node's native crypto module (OpenSSL) for maximum protection of sensitive data and private keys.
 
 ## 🚀 Key Features
+
 - **Native Security**: Built on top of Node.js crypto (OpenSSL) for hardware-accelerated encryption.
 
-- **AES-256-GCM**: Industry-standard authenticated encryption (AEAD) to ensure both confidentiality and data integrity.
+- **JWE compact (RFC 7516)**: authenticated encryption with `alg: "dir"` and `enc: "A256GCM"` (AES-256-GCM), bound to a key id and a context, checked against the RFC 7520 test vector.
 
 - **Lightweight JWT**: Pure implementation for signing and verifying tokens without heavy dependencies.
 
-- **Standardized Error Handling**: Harmonized error messages ("Decryption failed") for better security and predictable testing.
+- **Errors that say what is wrong, and nothing more**: configuration and public-format errors are named; anything about the encrypted content is a single `Decryption failed`.
 
 ## 🛠 Usage
 
-### AES-256-GCM (Authenticated Encryption)
-Designed for high-security environments. It automatically handles Initialization Vectors (IV) and Authentication Tags.
+### JWE (Authenticated Encryption) — 2.0.0
 
-```ts
-import { AesGcmUtil } from '@syldel/crypto-utils';
+A value is sealed into a JWE compact string. Its protected header names the key (`kid`) and the
+context it belongs to (`ctx`), and the whole header is authenticated: neither can be rewritten.
 
-const keyHex = "0123456789abcdef..."; // 64 hex characters (32 bytes)
-const message = "Sensitive data";
+```ts
+import { JweUtil } from '@syldel/crypto-utils';
+
+// Sealing: one key, named by its kid, and the context the value belongs to.
+const token = JweUtil.seal(agentPrivateKey, {
+  kid: '2026-11',
+  key: masterKeyHex, // 32 bytes, as a Buffer or 64 hex characters
+  context: `hl-agent-key:${userId}`,
+});
+// eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiMjAyNi0xMSIs... (5 segments, the 2nd empty)
+
+// Opening: every known key by kid, read and checked once at startup.
+const keys = JweUtil.parseKeyring(process.env.AGENT_ENCRYPTION_KEYS); // "2026-11:<hex>,2025-02:<hex>"
+const secret = JweUtil.open(token, { keys, context: `hl-agent-key:${userId}` });
+```
 
-// Encrypt
-const encrypted = AesGcmUtil.encrypt(message, keyHex);
-// Returns: { data: '...', iv: '...', tag: '...' }
+Protected header, byte for byte — no space, this key order, nothing more; anything else is refused:
 
-// Decrypt
-try {
-  const original = AesGcmUtil.decrypt(encrypted, keyHex);
-} catch (error) {
-  // Throws "Decryption failed" if data is tampered or key is wrong
-}
+```text
+{"alg":"dir","enc":"A256GCM","kid":"2026-11","ctx":"hl-agent-key:<userId>","crit":["ctx"]}
 ```
 
+| Error                                                                      | Meaning                                                                    |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `Invalid key …`, `Invalid kid …`, `Invalid context …`, `Invalid keyring …` | configuration of the caller; never quotes a key                            |
+| `Unsupported format: …`                                                    | not a JWE string, e.g. the 1.x `{ data, iv, tag }` object                  |
+| `Invalid JWE: …`                                                           | the public structure or the protected header is not the expected one       |
+| `Unknown key id: "…"`                                                      | no key with that kid in the keyring                                        |
+| `Decryption failed`                                                        | anything about the encrypted content, or the wrong key under the right kid |
+| `Context mismatch: sealed for "…", expected "…"`                           | authenticated, so it states a fact: the value belongs to someone else      |
+
+#### Rotating a key
+
+1. Add the new key to the keyring of every service that opens, and deploy.
+2. Seal again with the new kid.
+3. Remove the old key from the keyring.
+
+#### Migrating from 1.x
+
+`AesGcmUtil.encrypt`/`decrypt` and `EncryptedData` are removed. A 1.x object is refused by name
+(`Unsupported format: { data, iv, tag } is the crypto-utils 1.x format`): seal the value again.
+
 ### Pure JWT Utilities
+
 A lightweight way to handle JWTs in your NestJS guards or services.
 
 ```ts
 import { PureJwtUtil } from '@syldel/crypto-utils';
 
-const secret = "your-secure-secret";
-const payload = { sub: "user_123", role: "admin" };
+const secret = 'your-secure-secret';
+const payload = { sub: 'user_123', role: 'admin' };
 
 // Sign a token
 const token = PureJwtUtil.sign(payload, secret);
@@ -58,14 +86,43 @@ try {
 
 - **Zero External Crypto Libs**: By using native Node.js APIs, this package minimizes the attack surface and dependency supply chain risks.
 
-- **Side-Channel Protection**: Leverages OpenSSL's C++ implementation to protect against timing attacks.
+- **Side-Channel Protection**: JWT signatures are compared with `crypto.timingSafeEqual`, in constant time.
+
+- **GCM Integrity**: Unlike AES-CTR or CBC, AES-GCM ensures that any single-bit modification to the encrypted data, the IV or the protected header will be detected during decryption.
+
+### ⚠️ What is refused, and why
 
-- **GCM Integrity**: Unlike AES-CTR or CBC, AES-GCM ensures that any single-bit modification to the encrypted data will be detected during decryption.
+- `JweUtil.open` requires a 12-byte IV and a full 16-byte tag (RFC 7518 §5.3). Without this, Node accepts tags down to 4 bytes, and a random forged tag would pass with a 1 in 2^32 chance instead of 2^128.
+- Every base64url segment and every hex key is decoded strictly and canonically: a stray character fails instead of being silently skipped.
+- The protected header must be byte for byte the one `seal` writes: no extra field (`zip`, `jku`…), no duplicated field (which `JSON.parse` would silently overwrite), no token without a context.
+- The key is chosen by its kid, never by trying every key: AES-GCM does not commit to its key, so one ciphertext can open under two keys.
+- A kid is looked up as an own property only: `constructor` is not a key.
+- `open` refuses a token above 2 MiB, `seal` a plaintext above `JweUtil.MAX_PLAINTEXT_BYTES` (1 MiB), before any decoding.
+- A missing, non-hex or wrongly sized key throws `Invalid key: …`, never `Decryption failed`: it is a configuration error, and blaming the payload sent the search the wrong way. The message never quotes the key.
+- `PureJwtUtil.verify` only accepts `alg: "HS256"`, a JSON object payload, a numeric `exp`, and the canonical base64url spelling of the signature.
+- Both `sign` and `verify` refuse an empty or missing secret: HMAC happily signs with an empty key, which anyone can guess.
+- `nbf`, `iat`, `aud` and `iss` are **not** checked: callers that rely on them must check them themselves.
 
+### ⚠️ Known limit: the master key lives in plain text
+
+Tink advises against keeping keys in plain text and recommends a key encryption key in a KMS
+(Google Cloud KMS, AWS KMS, HashiCorp Vault). Here the keyring is an environment variable of each
+service: whoever reads that environment reads the keys. A KMS is out of scope for now.
+
+### Sources, read raw on 2026-11-02
+
+- RFC 7516 (JWE) §5.1 step 14: the AAD is the ASCII of the encoded protected header; §4.1.6 `kid`.
+- RFC 7518 (JWA) §4.5 `dir`, §5.3 AES-GCM (96-bit IV required, 128-bit tag), §8.4 at most 2^32 encryptions per key.
+- RFC 7515 (JWS) §4.1.11 `crit`, which RFC 7516 §4.1.13 applies to JWE.
+- RFC 7520 §5.6, the `dir` + AES-GCM test vector the tests reproduce in both directions.
+- Tink, _Keysets_: rotation order (add, deploy, then make primary); the key-id prefix is not authenticated, only a hint.
+- Tink, _AEAD_: a user id as associated data stops a value from moving to another user; AES-GCM is not key-committing.
+- Tink, _Key management_: keys should not be stored in plain text (see the known limit above).
+- AWS Encryption SDK specification, `framework/structures.md`: the encryption context is non-secret, canonically serialized, and authenticated.
 
 ## 🧪 Testing
 
-Full test suite with 100% coverage on core crypto logic.
+Full test suite with 100% coverage, including the RFC 7520 §5.6 vector and a reproducible fuzz of 3000 tampered tokens.
 
 ```bash
 npm run test
@@ -74,18 +131,23 @@ npm run test
 ## 👨‍💻 Développement
 
 ### Installation des dépendances
+
 ```bash
 npm install
 ```
 
 ### Compilation
+
 Génère le dossier `dist/` contenant les fichiers JavaScript et les déclarations de types (`.d.ts`).
+
 ```bash
 npm run build
 ```
 
 ### Qualité du code
+
 Le projet utilise **ESLint** pour la logique et **Prettier** pour le formatage.
+
 ```bash
 # Vérifier les erreurs
 npx eslint .
@@ -109,17 +171,21 @@ Pour utiliser ce package dans tes autres projets sans le publier sur NPM :
 Le projet utilise des **Granular Access Tokens** pour la publication afin de contourner la double authentification (2FA) manuelle tout en maintenant une sécurité maximale.
 
 ### Configuration du Token
+
 1. Générer un token sur NPM avec les permissions `Read and Write`.
 2. Restreindre l'accès au package `@syldel/crypto-utils` uniquement.
 3. Utiliser l'option `Bypass 2FA` pour permettre l'automatisation.
 
 ### Commande de publication rapide
+
 Si tu n'utilises pas de fichier `.npmrc`, tu peux publier en passant le token directement :
+
 ```bash
 npm publish --access public --//registry.npmjs.org/:_authToken=TON_TOKEN_ICI
 ```
 
 ### Configuration de la publication
+
 Créez un fichier .npmrc à la racine (ignoré par Git) pour l'authentification :
 
 ```
@@ -127,6 +193,7 @@ Créez un fichier .npmrc à la racine (ignoré par Git) pour l'authentification
 ```
 
 ### Publier une nouvelle version
+
 La commande suivante automatise le build, l'incrémentation de version et l'envoi vers NPM :
 
 ```bash
@@ -134,6 +201,7 @@ npm run release
 ```
 
 ### Pousse le commit ET le tag sur GitHub
+
 ```bash
 git push origin main --follow-tags
 ```

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export * from './jwt.util';
-export * from './aes-gcm.util';
+export * from './jwe.util';

package/dist/index.js

@@ -15,4 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./jwt.util"), exports);
-__exportStar(require("./aes-gcm.util"), exports);
+__exportStar(require("./jwe.util"), exports);

package/dist/jwe-compact.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cœur JWE (RFC 7516), sérialisation compacte, algorithme `dir` uniquement :
+ * la clé partagée sert directement de clé de contenu (RFC 7518 §4.5), la clé
+ * chiffrée est donc vide. Ce module ne décide d'aucune politique (quel en-tête,
+ * quelle clé, quel contexte) : c'est le rôle de `JweUtil`. Il est séparé pour
+ * être éprouvé tel quel contre le vecteur de la RFC 7520 §5.6, qui utilise
+ * A128GCM. Il n'est pas exporté par le paquet.
+ */
+export type ContentEncryption = 'A128GCM' | 'A256GCM';
+/** RFC 7518 §5.3 : `enc` est fixé par la taille de la clé, jamais lu seul. */
+export declare const ENC_BY_KEY_BYTES: Readonly<Record<number, ContentEncryption>>;
+/** RFC 7518 §5.3 : IV de 96 bits REQUIS, tag de 128 bits quelle que soit la clé. */
+export declare const IV_BYTES = 12;
+export declare const TAG_BYTES = 16;
+export interface CompactParts {
+    /** Le segment d'en-tête tel que reçu : c'est lui, et non une re-sérialisation, qui fait l'AAD. */
+    protectedHeader: string;
+    /** Le JSON de l'en-tête, décodé mais pas encore authentifié. */
+    headerJson: string;
+    header: Record<string, unknown>;
+    iv: string;
+    ciphertext: string;
+    tag: string;
+}
+/**
+ * base64url strict et canonique. `Buffer.from(s, 'base64url')` saute les
+ * caractères invalides sans rien dire et accepte des bits de remplissage non
+ * nuls : deux écritures différentes donnaient le même octet, et un segment
+ * abîmé était lu à moitié.
+ */
+export declare function base64urlDecode(segment: string): Buffer;
+/**
+ * Découpe et lit la structure, et lève `Invalid JWE: …`. Tout ce qui est
+ * vérifié ici est public :
+ * l'en-tête n'est pas chiffré, et rien de ce qui échoue ici ne dit quoi que
+ * ce soit sur la clé ou le clair.
+ */
+export declare function parseCompact(token: string): CompactParts;
+/**
+ * Chiffre `plaintext` sous `header` (RFC 7516 §5.1). L'IV n'est passé que par
+ * les tests, pour reproduire le vecteur de la RFC 7520 ; partout ailleurs il
+ * est tiré au hasard.
+ */
+export declare function encryptDir(plaintext: string, key: Buffer, header: Readonly<Record<string, unknown>>, iv?: Buffer): string;
+/**
+ * Déchiffre des segments déjà découpés. Toute erreur ici concerne le contenu
+ * chiffré : l'appelant la rend sous un message unique.
+ */
+export declare function decryptDir(parts: CompactParts, key: Buffer): string;

package/dist/jwe-compact.js

@@ -0,0 +1,153 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAG_BYTES = exports.IV_BYTES = exports.ENC_BY_KEY_BYTES = void 0;
+exports.base64urlDecode = base64urlDecode;
+exports.parseCompact = parseCompact;
+exports.encryptDir = encryptDir;
+exports.decryptDir = decryptDir;
+const crypto = __importStar(require("crypto"));
+/** RFC 7518 §5.3 : `enc` est fixé par la taille de la clé, jamais lu seul. */
+exports.ENC_BY_KEY_BYTES = {
+    16: 'A128GCM',
+    32: 'A256GCM',
+};
+/** RFC 7518 §5.3 : IV de 96 bits REQUIS, tag de 128 bits quelle que soit la clé. */
+exports.IV_BYTES = 12;
+exports.TAG_BYTES = 16;
+/**
+ * base64url strict et canonique. `Buffer.from(s, 'base64url')` saute les
+ * caractères invalides sans rien dire et accepte des bits de remplissage non
+ * nuls : deux écritures différentes donnaient le même octet, et un segment
+ * abîmé était lu à moitié.
+ */
+function base64urlDecode(segment) {
+    if (!/^[A-Za-z0-9_-]*$/.test(segment)) {
+        throw new Error('not base64url');
+    }
+    const bytes = Buffer.from(segment, 'base64url');
+    if (bytes.toString('base64url') !== segment) {
+        throw new Error('not canonical base64url');
+    }
+    return bytes;
+}
+/**
+ * Découpe et lit la structure, et lève `Invalid JWE: …`. Tout ce qui est
+ * vérifié ici est public :
+ * l'en-tête n'est pas chiffré, et rien de ce qui échoue ici ne dit quoi que
+ * ce soit sur la clé ou le clair.
+ */
+function parseCompact(token) {
+    const segments = token.split('.');
+    if (segments.length !== 5) {
+        throw new Error(`Invalid JWE: expected 5 segments, got ${segments.length}`);
+    }
+    const [protectedHeader, encryptedKey, iv, ciphertext, tag] = segments;
+    if (encryptedKey !== '') {
+        throw new Error('Invalid JWE: the encrypted key must be empty with alg "dir"');
+    }
+    let headerJson;
+    let header;
+    try {
+        headerJson = base64urlDecode(protectedHeader).toString('utf8');
+        header = JSON.parse(headerJson);
+    }
+    catch {
+        throw new Error('Invalid JWE: unreadable protected header');
+    }
+    if (typeof header !== 'object' || header === null || Array.isArray(header)) {
+        throw new Error('Invalid JWE: the protected header is not a JSON object');
+    }
+    return {
+        protectedHeader,
+        headerJson,
+        header: header,
+        iv,
+        ciphertext,
+        tag,
+    };
+}
+/**
+ * Chiffre `plaintext` sous `header` (RFC 7516 §5.1). L'IV n'est passé que par
+ * les tests, pour reproduire le vecteur de la RFC 7520 ; partout ailleurs il
+ * est tiré au hasard.
+ */
+function encryptDir(plaintext, key, header, iv = crypto.randomBytes(exports.IV_BYTES)) {
+    const enc = exports.ENC_BY_KEY_BYTES[key.length];
+    if (header.alg !== 'dir' || enc === undefined || header.enc !== enc) {
+        throw new Error('header and key do not match alg "dir" with A128GCM or A256GCM');
+    }
+    if (iv.length !== exports.IV_BYTES) {
+        throw new Error(`the IV must be ${exports.IV_BYTES} bytes`);
+    }
+    const protectedHeader = Buffer.from(JSON.stringify(header), 'utf8').toString('base64url');
+    const cipher = crypto.createCipheriv(enc === 'A128GCM' ? 'aes-128-gcm' : 'aes-256-gcm', key, iv, {
+        authTagLength: exports.TAG_BYTES,
+    });
+    // RFC 7516 §5.1 étape 14 : l'AAD est l'ASCII du segment d'en-tête encodé.
+    cipher.setAAD(Buffer.from(protectedHeader, 'ascii'));
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return [
+        protectedHeader,
+        '',
+        iv.toString('base64url'),
+        ciphertext.toString('base64url'),
+        cipher.getAuthTag().toString('base64url'),
+    ].join('.');
+}
+/**
+ * Déchiffre des segments déjà découpés. Toute erreur ici concerne le contenu
+ * chiffré : l'appelant la rend sous un message unique.
+ */
+function decryptDir(parts, key) {
+    const enc = exports.ENC_BY_KEY_BYTES[key.length];
+    if (parts.header.alg !== 'dir' || enc === undefined || parts.header.enc !== enc) {
+        throw new Error('header and key do not match');
+    }
+    const iv = base64urlDecode(parts.iv);
+    const tag = base64urlDecode(parts.tag);
+    const ciphertext = base64urlDecode(parts.ciphertext);
+    // Sans ces deux contrôles et `authTagLength`, Node accepte un tag de 4 à 16
+    // octets : mesuré sur crypto-utils 1.0.3, un tag tronqué déchiffrait.
+    if (iv.length !== exports.IV_BYTES || tag.length !== exports.TAG_BYTES) {
+        throw new Error('wrong IV or tag length');
+    }
+    const decipher = crypto.createDecipheriv(enc === 'A128GCM' ? 'aes-128-gcm' : 'aes-256-gcm', key, iv, {
+        authTagLength: exports.TAG_BYTES,
+    });
+    decipher.setAAD(Buffer.from(parts.protectedHeader, 'ascii'));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}

package/dist/jwe.util.d.ts

@@ -0,0 +1,53 @@
+/** Une clé de 32 octets, en Buffer ou en 64 caractères hexadécimaux. */
+export type JweKey = Buffer | string;
+/** Les clés connues, par identifiant (`kid`). */
+export type JweKeyring = Readonly<Record<string, JweKey>>;
+export interface SealOptions {
+    /** Identifiant de la clé, écrit dans l'en-tête : `2026-11`, `session`. */
+    kid: string;
+    key: JweKey;
+    /** Ce à quoi le clair est lié, par exemple `hl-agent-key:<userId>`. Non secret. */
+    context: string;
+}
+export interface OpenOptions {
+    keys: JweKeyring;
+    /** Le contexte attendu : un JWE scellé pour un autre est refusé. */
+    context: string;
+}
+/**
+ * Chiffrement authentifié au format JWE compact (RFC 7516), `alg: "dir"` et
+ * `enc: "A256GCM"` (RFC 7518), sans dépendance.
+ *
+ * L'en-tête protégé porte le `kid` et le contexte (`ctx`), déclaré critique
+ * (`crit`, RFC 7515 §4.1.11) : une bibliothèque JOSE qui ne le connaît pas doit
+ * refuser le jeton au lieu d'ignorer le contrôle. L'en-tête entier est l'AAD,
+ * donc ni le `kid` ni le contexte ne se réécrivent sans casser le tag —
+ * contrairement au préfixe de clé de Tink, que sa doc dit non authentifié.
+ *
+ * Erreurs : ce qui concerne la configuration (`Invalid key`, `Invalid kid`,
+ * `Invalid context`, `Invalid keyring`) et la structure publique du jeton
+ * (`Invalid JWE`, `Unsupported format`, `Unknown key id`) se nomme. Tout ce
+ * qui touche au contenu chiffré reste un seul `Decryption failed`. Un contexte
+ * différent ne se signale qu'après authentification : le message dit alors un
+ * fait vérifié, pas ce que prétend un en-tête forgé.
+ */
+export declare class JweUtil {
+    /** Plus grand clair accepté (1 Mio), et donc plus grand jeton lu, avant tout décodage. */
+    static readonly MAX_PLAINTEXT_BYTES: number;
+    static seal(plaintext: string, { kid, key, context }: SealOptions): string;
+    static open(token: string, { keys, context }: OpenOptions): string;
+    /**
+     * Lit un trousseau écrit `kid:hex,kid:hex` (une variable d'environnement) et
+     * le valide entièrement : à appeler au démarrage, pour qu'un trousseau
+     * absent ou abîmé arrête le service au lieu du premier déchiffrement.
+     */
+    static parseKeyring(raw: string | undefined): JweKeyring;
+    private static header;
+    private static assertKid;
+    private static assertContext;
+    /**
+     * Une clé de 32 octets, en Buffer ou en hexadécimal strict. Le message ne
+     * cite jamais la clé.
+     */
+    private static toKey;
+}

package/dist/jwe.util.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JweUtil = void 0;
+const jwe_compact_1 = require("./jwe-compact");
+const KEY_BYTES = 32;
+const KID_PATTERN = /^[a-z0-9-]{1,32}$/;
+const MAX_CONTEXT_LENGTH = 256;
+/**
+ * Chiffrement authentifié au format JWE compact (RFC 7516), `alg: "dir"` et
+ * `enc: "A256GCM"` (RFC 7518), sans dépendance.
+ *
+ * L'en-tête protégé porte le `kid` et le contexte (`ctx`), déclaré critique
+ * (`crit`, RFC 7515 §4.1.11) : une bibliothèque JOSE qui ne le connaît pas doit
+ * refuser le jeton au lieu d'ignorer le contrôle. L'en-tête entier est l'AAD,
+ * donc ni le `kid` ni le contexte ne se réécrivent sans casser le tag —
+ * contrairement au préfixe de clé de Tink, que sa doc dit non authentifié.
+ *
+ * Erreurs : ce qui concerne la configuration (`Invalid key`, `Invalid kid`,
+ * `Invalid context`, `Invalid keyring`) et la structure publique du jeton
+ * (`Invalid JWE`, `Unsupported format`, `Unknown key id`) se nomme. Tout ce
+ * qui touche au contenu chiffré reste un seul `Decryption failed`. Un contexte
+ * différent ne se signale qu'après authentification : le message dit alors un
+ * fait vérifié, pas ce que prétend un en-tête forgé.
+ */
+class JweUtil {
+    static seal(plaintext, { kid, key, context }) {
+        this.assertKid(kid);
+        this.assertContext(context);
+        const contentKey = this.toKey(key, 'Invalid key');
+        if (typeof plaintext !== 'string') {
+            throw new Error('Invalid plaintext: a string is required');
+        }
+        if (Buffer.byteLength(plaintext, 'utf8') > this.MAX_PLAINTEXT_BYTES) {
+            throw new Error('Invalid plaintext: above the size limit');
+        }
+        return (0, jwe_compact_1.encryptDir)(plaintext, contentKey, this.header(kid, context));
+    }
+    static open(token, { keys, context }) {
+        this.assertContext(context);
+        if (typeof token !== 'string') {
+            // Le format 1.x était un objet { data, iv, tag } : il se refuse en le
+            // nommant, pour que la cause se lise sans ouvrir le code.
+            const legacy = typeof token === 'object' && token !== null && 'data' in token && 'iv' in token;
+            throw new Error(legacy
+                ? 'Unsupported format: { data, iv, tag } is the crypto-utils 1.x format; seal the value again'
+                : 'Unsupported format: a JWE compact string is required');
+        }
+        // base64url grossit de 4/3 : deux fois la limite couvre l'en-tête et la marge.
+        if (token.length > 2 * this.MAX_PLAINTEXT_BYTES) {
+            throw new Error('Invalid JWE: above the size limit');
+        }
+        const parts = (0, jwe_compact_1.parseCompact)(token);
+        // L'en-tête doit être exactement celui que `seal` écrit, octet pour octet :
+        // ni champ en plus (`zip`, `jku`…), ni doublon que JSON.parse aurait
+        // écrasé en silence, ni autre ordre ou espace.
+        const { kid, ctx } = parts.header;
+        if (typeof kid !== 'string' ||
+            typeof ctx !== 'string' ||
+            parts.headerJson !== JSON.stringify(this.header(kid, ctx))) {
+            throw new Error('Invalid JWE: the protected header must be exactly {alg:"dir", enc:"A256GCM", kid, ctx, crit:["ctx"]}');
+        }
+        // Une clé se choisit par son `kid`, jamais en les essayant toutes : GCM
+        // n'engage pas la clé, un chiffré peut s'ouvrir sous deux clés (Tink, page AEAD).
+        if (!Object.prototype.hasOwnProperty.call(keys, kid)) {
+            throw new Error(`Unknown key id: ${JSON.stringify(kid.slice(0, 64))}`);
+        }
+        const contentKey = this.toKey(keys[kid], `Invalid key ${JSON.stringify(kid)}`);
+        let plaintext;
+        try {
+            plaintext = (0, jwe_compact_1.decryptDir)(parts, contentKey);
+        }
+        catch {
+            throw new Error('Decryption failed');
+        }
+        if (ctx !== context) {
+            throw new Error(`Context mismatch: sealed for ${JSON.stringify(ctx)}, expected ${JSON.stringify(context)}`);
+        }
+        return plaintext;
+    }
+    /**
+     * Lit un trousseau écrit `kid:hex,kid:hex` (une variable d'environnement) et
+     * le valide entièrement : à appeler au démarrage, pour qu'un trousseau
+     * absent ou abîmé arrête le service au lieu du premier déchiffrement.
+     */
+    static parseKeyring(raw) {
+        if (typeof raw !== 'string' || raw.trim() === '') {
+            throw new Error('Invalid keyring: missing or empty (is the secret configured?)');
+        }
+        const keyring = Object.create(null);
+        for (const entry of raw.split(',')) {
+            const separator = entry.indexOf(':');
+            const kid = separator === -1 ? '' : entry.slice(0, separator).trim();
+            if (!KID_PATTERN.test(kid)) {
+                throw new Error('Invalid keyring: each entry must read kid:hex, kid matching [a-z0-9-]{1,32}');
+            }
+            if (kid in keyring) {
+                throw new Error(`Invalid keyring: key id ${JSON.stringify(kid)} appears twice`);
+            }
+            keyring[kid] = this.toKey(entry.slice(separator + 1).trim(), `Invalid keyring: key ${JSON.stringify(kid)}`);
+        }
+        return Object.freeze(keyring);
+    }
+    static header(kid, ctx) {
+        return { alg: 'dir', enc: 'A256GCM', kid, ctx, crit: ['ctx'] };
+    }
+    static assertKid(kid) {
+        if (typeof kid !== 'string' || !KID_PATTERN.test(kid)) {
+            throw new Error('Invalid kid: it must match [a-z0-9-]{1,32}');
+        }
+    }
+    static assertContext(context) {
+        if (typeof context !== 'string' ||
+            context.length === 0 ||
+            context.length > MAX_CONTEXT_LENGTH) {
+            throw new Error(`Invalid context: a non-empty string of at most ${MAX_CONTEXT_LENGTH} characters is required`);
+        }
+    }
+    /**
+     * Une clé de 32 octets, en Buffer ou en hexadécimal strict. Le message ne
+     * cite jamais la clé.
+     */
+    static toKey(key, label) {
+        if (key === undefined || key === null || key.length === 0) {
+            throw new Error(`${label}: missing or empty (is the secret configured?)`);
+        }
+        if (typeof key === 'string' && (key.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(key))) {
+            throw new Error(`${label}: not a hex string`);
+        }
+        const bytes = typeof key === 'string' ? Buffer.from(key, 'hex') : key;
+        if (!Buffer.isBuffer(bytes) || bytes.length !== KEY_BYTES) {
+            throw new Error(`${label}: must be 32 bytes (64 hex characters)`);
+        }
+        return bytes;
+    }
+}
+exports.JweUtil = JweUtil;
+/** Plus grand clair accepté (1 Mio), et donc plus grand jeton lu, avant tout décodage. */
+JweUtil.MAX_PLAINTEXT_BYTES = 1024 * 1024;

package/dist/jwt.util.js

@@ -40,22 +40,37 @@ class PureJwtUtil {
      * Verifies a JWT's signature and expiration, then returns the decoded payload.
      */
     static verify(token, secret) {
+        assertSecret(secret);
         const parts = token.split('.');
         if (parts.length !== 3)
             throw new Error('Invalid token format');
         const [headerB64, payloadB64, signatureB64] = parts;
         const dataToVerify = `${headerB64}.${payloadB64}`;
-        const expectedSignature = crypto
-            .createHmac('sha256', secret)
-            .update(dataToVerify)
-            .digest('base64url');
-        if (signatureB64 !== expectedSignature) {
+        const expected = crypto.createHmac('sha256', secret).update(dataToVerify).digest();
+        const received = Buffer.from(signatureB64, 'base64url');
+        // Comparaison en temps constant : `!==` s'arrête au premier caractère
+        // différent, et le temps de réponse renseigne sur la signature attendue.
+        // timingSafeEqual lance sur deux longueurs différentes, d'où le test avant.
+        // Le décodage base64url est tolérant : plusieurs écritures donnent les mêmes
+        // octets. Seule la forme canonique est admise, comme avec l'ancien `!==`.
+        if (received.toString('base64url') !== signatureB64 ||
+            received.length !== expected.length ||
+            !crypto.timingSafeEqual(received, expected)) {
             throw new Error('Invalid signature');
         }
-        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
-        const payloadRecord = payload;
-        if (typeof payloadRecord.exp === 'number') {
-            if (Date.now() >= payloadRecord.exp * 1000) {
+        // L'en-tête n'était jamais lu : un jeton annonçant « none » ou un autre
+        // algorithme passait du moment que sa signature HS256 était juste.
+        const header = parseJsonObject(headerB64, 'Invalid token header');
+        if (header.alg !== 'HS256') {
+            throw new Error('Unsupported algorithm');
+        }
+        const payload = parseJsonObject(payloadB64, 'Invalid token payload');
+        // Un `exp` non numérique était ignoré : le jeton n'expirait jamais.
+        if (payload.exp !== undefined) {
+            if (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp)) {
+                throw new Error('Invalid token payload');
+            }
+            if (Date.now() >= payload.exp * 1000) {
                 throw new Error('Token expired');
             }
         }
@@ -65,6 +80,7 @@ class PureJwtUtil {
      * Signs a payload and returns a compact JWT string.
      */
     static sign(payload, secret) {
+        assertSecret(secret);
         const header = { alg: 'HS256', typ: 'JWT' };
         const encode = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
         const encodedHeader = encode(header);
@@ -77,3 +93,25 @@ class PureJwtUtil {
     }
 }
 exports.PureJwtUtil = PureJwtUtil;
+/**
+ * createHmac signe avec une chaîne vide (mesuré sur le bot le 2026-10-06) : la
+ * signature attendue devient calculable par quiconque devine le secret vide.
+ */
+function assertSecret(secret) {
+    if (typeof secret !== 'string' || secret.length === 0) {
+        throw new Error('Invalid secret: a non-empty string is required');
+    }
+}
+function parseJsonObject(segment, error) {
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error(error);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(error);
+    }
+    return value;
+}

package/package.json

@@ -1,49 +1,59 @@
-{
-  "name": "@syldel/crypto-utils",
-  "version": "1.0.3",
-  "description": "Lightweight JWT and AES-256-GCM utilities",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "clean": "rm -rf dist",
-    "build": "npm run lint && npm run clean && tsc -p tsconfig.json",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "prepublishOnly": "npm run build",
-    "release": "npm run build && npm version patch && npm publish"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "jwt",
-    "aes",
-    "crypto",
-    "security",
-    "nestjs"
-  ],
-  "author": "Syl. D.",
-  "license": "ISC",
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/jest": "^30.0.0",
-    "eslint": "^10.0.1",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsonc": "^3.0.0",
-    "eslint-plugin-prettier": "^5.5.5",
-    "jest": "^30.2.0",
-    "jsonc-eslint-parser": "^3.1.0",
-    "prettier": "^3.8.1",
-    "ts-jest": "^29.4.6",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.0"
-  },
-  "overrides": {
-    "minimatch": "^10.2.1"
-  }
-}
+{
+  "name": "@syldel/crypto-utils",
+  "version": "2.0.0",
+  "description": "Lightweight JWT and JWE (AES-256-GCM) utilities",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syldel/crypto-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Syldel/crypto-utils/issues"
+  },
+  "homepage": "https://github.com/Syldel/crypto-utils#readme",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "clean": "rm -rf dist",
+    "build": "npm run lint && npm run clean && tsc -p tsconfig.json",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "npm run build",
+    "release": "npm run build && npm version patch && npm publish"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "jwt",
+    "jwe",
+    "aes",
+    "crypto",
+    "security",
+    "nestjs"
+  ],
+  "author": "Syl. D.",
+  "license": "ISC",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.19.2",
+    "eslint": "^10.0.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsonc": "^3.0.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jest": "^30.2.0",
+    "jsonc-eslint-parser": "^3.1.0",
+    "prettier": "^3.8.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0"
+  },
+  "overrides": {
+    "minimatch": "^10.2.1"
+  }
+}

package/dist/aes-gcm.util.d.ts

@@ -1,17 +0,0 @@
-export interface EncryptedData {
-    data: string;
-    iv: string;
-    tag: string;
-}
-export declare class AesGcmUtil {
-    private static readonly ALGORITHM;
-    private static validateKey;
-    /**
-     * Encrypts text using native Node.js crypto (AES-256-GCM)
-     */
-    static encrypt(text: string, key: Buffer | string): EncryptedData;
-    /**
-     * Decrypts a payload using native Node.js crypto (AES-256-GCM)
-     */
-    static decrypt(payload: EncryptedData, key: Buffer | string): string;
-}

package/dist/aes-gcm.util.js

@@ -1,84 +0,0 @@
-"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AesGcmUtil = void 0;
-const crypto = __importStar(require("crypto"));
-class AesGcmUtil {
-    static validateKey(key) {
-        const encryptionKey = typeof key === 'string' ? Buffer.from(key, 'hex') : key;
-        if (encryptionKey.length !== 32) {
-            throw new Error('Invalid Key: Key must be 32 bytes (64 hex characters)');
-        }
-        return encryptionKey;
-    }
-    /**
-     * Encrypts text using native Node.js crypto (AES-256-GCM)
-     */
-    static encrypt(text, key) {
-        try {
-            const encryptionKey = this.validateKey(key);
-            const iv = crypto.randomBytes(12);
-            const cipher = crypto.createCipheriv(this.ALGORITHM, encryptionKey, iv);
-            let encrypted = cipher.update(text, 'utf8', 'hex');
-            encrypted += cipher.final('hex');
-            return {
-                data: encrypted,
-                iv: iv.toString('hex'),
-                tag: cipher.getAuthTag().toString('hex'),
-            };
-        }
-        catch {
-            throw new Error('Encryption failed');
-        }
-    }
-    /**
-     * Decrypts a payload using native Node.js crypto (AES-256-GCM)
-     */
-    static decrypt(payload, key) {
-        try {
-            const encryptionKey = this.validateKey(key);
-            const decipher = crypto.createDecipheriv(this.ALGORITHM, encryptionKey, Buffer.from(payload.iv, 'hex'));
-            decipher.setAuthTag(Buffer.from(payload.tag, 'hex'));
-            let decrypted = decipher.update(payload.data, 'hex', 'utf8');
-            decrypted += decipher.final('utf8');
-            return decrypted;
-        }
-        catch {
-            throw new Error('Decryption failed');
-        }
-    }
-}
-exports.AesGcmUtil = AesGcmUtil;
-AesGcmUtil.ALGORITHM = 'aes-256-gcm';