@syldel/crypto-utils 1.1.0 → 3.0.0

package/README.md

@@ -3,46 +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) {
-  // "Invalid key: …" if the key is missing, not hex or not 32 bytes (a config error)
-  // "Decryption failed" for anything wrong with the payload, or the wrong key
-}
+```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);
@@ -61,22 +88,41 @@ try {
 
 - **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 will be detected during decryption.
+- **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
 
-- `AesGcmUtil.decrypt` requires a full 16-byte tag and a 12-byte IV. 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 hex input (key, data, IV, tag) is decoded strictly: a stray character fails instead of being silently cut off.
-- `decrypt` refuses a ciphertext above `AesGcmUtil.MAX_CIPHERTEXT_BYTES` (1 MiB) before decoding it.
-- 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. Everything wrong with the payload stays a single generic `Decryption failed`, so an attacker learns nothing about which check failed.
+- `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.
+- Both `sign` and `verify` require a secret of exactly 64 hex characters, the form `crypto.randomBytes(32).toString('hex')` produces: 256 bits of randomness, the HS256 output size (OWASP JWT Cheat Sheet, RFC 8725 §3.5). HMAC happily signs with an empty key or a passphrase, which anyone can guess, and a length alone does not prove randomness. The secret is used as is, its 64 ASCII bytes, not decoded.
 - `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
@@ -85,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 .
@@ -120,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 :
 
 ```
@@ -138,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
@@ -145,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

@@ -94,13 +94,28 @@ 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.
+ * Le secret doit être exactement 64 caractères hexadécimaux : la forme que
+ * produit `crypto.randomBytes(32).toString('hex')`, soit 256 bits d'aléa, la
+ * taille de sortie de HS256 (fiche JWT de l'OWASP, section MAC ; RFC 8725
+ * §3.5, qui interdit un mot de passe comme clé). Ce qui compte, c'est l'aléa,
+ * qu'une longueur seule ne prouve pas : « ceci-est-mon-mot-de-passe-de-prod »
+ * fait 33 octets. 64 caractères hexadécimaux ne se tapent pas à la main.
+ *
+ * Il sert tel quel de clé HMAC (ses 64 octets ASCII), sans être décodé :
+ * le décoder changerait toutes les signatures échangées entre les services.
+ *
+ * Un secret vide est refusé à part : createHmac signe avec une chaîne vide
+ * (mesuré sur le bot le 2026-10-06).
  */
+const SECRET_PATTERN = /^[0-9a-fA-F]{64}$/;
 function assertSecret(secret) {
     if (typeof secret !== 'string' || secret.length === 0) {
         throw new Error('Invalid secret: a non-empty string is required');
     }
+    if (!SECRET_PATTERN.test(secret)) {
+        const allHex = /^[0-9a-fA-F]*$/.test(secret);
+        throw new Error(`Invalid secret: 64 hex characters required, got ${secret.length} characters${allHex ? '' : ', not all hex'} (generate it with crypto.randomBytes(32).toString('hex'))`);
+    }
 }
 function parseJsonObject(segment, error) {
     let value;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@syldel/crypto-utils",
-  "version": "1.1.0",
-  "description": "Lightweight JWT and AES-256-GCM utilities",
+  "version": "3.0.0",
+  "description": "Lightweight JWT and JWE (AES-256-GCM) utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {
@@ -30,6 +30,7 @@
   },
   "keywords": [
     "jwt",
+    "jwe",
     "aes",
     "crypto",
     "security",
@@ -40,7 +41,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/jest": "^30.0.0",
-    "@types/node": "^20.19.43",
+    "@types/node": "^24.19.2",
     "eslint": "^10.0.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsonc": "^3.0.0",

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

@@ -1,39 +0,0 @@
-export interface EncryptedData {
-    data: string;
-    iv: string;
-    tag: string;
-}
-export declare class AesGcmUtil {
-    private static readonly ALGORITHM;
-    private static readonly KEY_BYTES;
-    private static readonly IV_BYTES;
-    private static readonly TAG_BYTES;
-    /**
-     * Largest ciphertext `decrypt` accepts, in bytes (1 MiB). Checked on the hex
-     * string before any decoding: without it, a payload of hundreds of MB was
-     * decoded in full before GCM refused it. Our largest real payload is an
-     * agent key, 66 characters.
-     */
-    static readonly MAX_CIPHERTEXT_BYTES: number;
-    /**
-     * Une clé invalide est une erreur de configuration de l'appelant, pas une
-     * entrée d'attaquant : elle se nomme au lieu de se fondre dans « Decryption
-     * failed », qui accusait le chiffré quand le secret manquait dans l'env.
-     * Le message ne cite jamais la clé.
-     */
-    private static validateKey;
-    /**
-     * Strict hex decoding. Buffer.from(hex) stops at the first invalid character
-     * without a word: a damaged field was read half-way, and a key followed by
-     * junk ("<64 hex>zz") was accepted as its first 32 bytes.
-     */
-    private static hexToBuffer;
-    /**
-     * 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,137 +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 {
-    /**
-     * Une clé invalide est une erreur de configuration de l'appelant, pas une
-     * entrée d'attaquant : elle se nomme au lieu de se fondre dans « Decryption
-     * failed », qui accusait le chiffré quand le secret manquait dans l'env.
-     * Le message ne cite jamais la clé.
-     */
-    static validateKey(key) {
-        if (key === undefined || key === null || key.length === 0) {
-            throw new Error('Invalid key: missing or empty (is the secret configured?)');
-        }
-        let encryptionKey;
-        try {
-            encryptionKey = typeof key === 'string' ? this.hexToBuffer(key) : key;
-        }
-        catch {
-            throw new Error('Invalid key: not a hex string');
-        }
-        if (!Buffer.isBuffer(encryptionKey) || encryptionKey.length !== this.KEY_BYTES) {
-            throw new Error('Invalid key: must be 32 bytes (64 hex characters)');
-        }
-        return encryptionKey;
-    }
-    /**
-     * Strict hex decoding. Buffer.from(hex) stops at the first invalid character
-     * without a word: a damaged field was read half-way, and a key followed by
-     * junk ("<64 hex>zz") was accepted as its first 32 bytes.
-     */
-    static hexToBuffer(hex, expectedBytes) {
-        if (typeof hex !== 'string' || hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) {
-            throw new Error('Invalid hex string');
-        }
-        const buffer = Buffer.from(hex, 'hex');
-        if (expectedBytes !== undefined && buffer.length !== expectedBytes) {
-            throw new Error(`Expected ${expectedBytes} bytes, got ${buffer.length}`);
-        }
-        return buffer;
-    }
-    /**
-     * Encrypts text using native Node.js crypto (AES-256-GCM)
-     */
-    static encrypt(text, key) {
-        const encryptionKey = this.validateKey(key);
-        try {
-            const iv = crypto.randomBytes(this.IV_BYTES);
-            const cipher = crypto.createCipheriv(this.ALGORITHM, encryptionKey, iv, {
-                authTagLength: this.TAG_BYTES,
-            });
-            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) {
-        const encryptionKey = this.validateKey(key);
-        try {
-            if (typeof payload.data !== 'string' || payload.data.length > 2 * this.MAX_CIPHERTEXT_BYTES) {
-                throw new Error('Ciphertext missing or above the size limit');
-            }
-            const iv = this.hexToBuffer(payload.iv, this.IV_BYTES);
-            const tag = this.hexToBuffer(payload.tag, this.TAG_BYTES);
-            const data = this.hexToBuffer(payload.data);
-            // Sans `authTagLength`, Node accepte un tag de 4 à 16 octets : mesuré sur
-            // la 1.0.3, un tag tronqué à 4 octets déchiffrait, et un tag forgé au
-            // hasard passait avec une chance sur 2^32 au lieu de 2^128.
-            const decipher = crypto.createDecipheriv(this.ALGORITHM, encryptionKey, iv, {
-                authTagLength: this.TAG_BYTES,
-            });
-            decipher.setAuthTag(tag);
-            let decrypted = decipher.update(data, undefined, 'utf8');
-            decrypted += decipher.final('utf8');
-            return decrypted;
-        }
-        catch {
-            throw new Error('Decryption failed');
-        }
-    }
-}
-exports.AesGcmUtil = AesGcmUtil;
-AesGcmUtil.ALGORITHM = 'aes-256-gcm';
-AesGcmUtil.KEY_BYTES = 32;
-AesGcmUtil.IV_BYTES = 12;
-AesGcmUtil.TAG_BYTES = 16;
-/**
- * Largest ciphertext `decrypt` accepts, in bytes (1 MiB). Checked on the hex
- * string before any decoding: without it, a payload of hundreds of MB was
- * decoded in full before GCM refused it. Our largest real payload is an
- * agent key, 66 characters.
- */
-AesGcmUtil.MAX_CIPHERTEXT_BYTES = 1024 * 1024;