@lakutata/security 3.0.0-beta.0

package/dist/cjs/functions/Encryption.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptByKey = encryptByKey;
+exports.decryptByKey = decryptByKey;
+exports.encryptByPassword = encryptByPassword;
+exports.decryptByPassword = decryptByPassword;
+const node_crypto_1 = require("node:crypto");
+const DecryptionFailedException_js_1 = require("../exceptions/DecryptionFailedException.js");
+const AssertKey_js_1 = require("../lib/AssertKey.js");
+/**
+ * The versions of the encrypted data: the key derivation (the cipher is AES-256-GCM)
+ */
+const KEY_VERSION = 1;
+const PASSWORD_VERSION = 2;
+const SALT_LENGTH = 16;
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+const HEADER_LENGTH = 1 + SALT_LENGTH + IV_LENGTH;
+const KEY_LENGTH = 32;
+/**
+ * The scrypt parameters of the password version (about 16 MB and a few tens of milliseconds)
+ */
+const SCRYPT_OPTIONS = { N: 16384, r: 8, p: 1 };
+/**
+ * The key of a message: derived from the key with the salt of the message (HKDF-sha256)
+ * @param key
+ * @param salt
+ */
+function deriveKey(key, salt) {
+    return Buffer.from((0, node_crypto_1.hkdfSync)('sha256', key, salt, 'lakutata-encryption', KEY_LENGTH));
+}
+/**
+ * The key of a message: derived from the password with the salt of the message (scrypt)
+ * @param password
+ * @param salt
+ */
+function derivePasswordKey(password, salt) {
+    return new Promise((resolve, reject) => (0, node_crypto_1.scrypt)(password, salt, KEY_LENGTH, SCRYPT_OPTIONS, (error, key) => error ? reject(error) : resolve(key)));
+}
+/**
+ * Encrypt with a key: version, salt, iv, tag and ciphertext, base64url encoded
+ * @param version
+ * @param salt
+ * @param key
+ * @param data
+ */
+function seal(version, salt, key, data) {
+    const iv = (0, node_crypto_1.randomBytes)(IV_LENGTH);
+    const header = Buffer.concat([Buffer.from([version]), salt, iv]);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+    //The header is authenticated too
+    cipher.setAAD(header);
+    const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
+    return Buffer.concat([header, cipher.getAuthTag(), ciphertext]).toString('base64url');
+}
+/**
+ * The parts of encrypted data (undefined: not encrypted data of the version)
+ * @param encrypted
+ * @param version
+ */
+function parts(encrypted, version) {
+    const buffer = Buffer.from(encrypted, 'base64url');
+    if (buffer.length < HEADER_LENGTH + TAG_LENGTH || buffer[0] !== version)
+        return undefined;
+    return {
+        header: buffer.subarray(0, HEADER_LENGTH),
+        salt: buffer.subarray(1, 1 + SALT_LENGTH),
+        iv: buffer.subarray(1 + SALT_LENGTH, HEADER_LENGTH),
+        tag: buffer.subarray(HEADER_LENGTH, HEADER_LENGTH + TAG_LENGTH),
+        ciphertext: buffer.subarray(HEADER_LENGTH + TAG_LENGTH)
+    };
+}
+/**
+ * Decrypt the parts with a key (undefined: the key does not decrypt them, or they were changed)
+ * @param part
+ * @param key
+ */
+function open(part, key) {
+    try {
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, part.iv);
+        decipher.setAAD(part.header);
+        decipher.setAuthTag(part.tag);
+        return Buffer.concat([decipher.update(part.ciphertext), decipher.final()]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Encrypt data with a secret key, using AES-256-GCM (authenticated encryption): the output is confidential and
+ * tamper-proof. Each call derives a fresh key from the key and a random 16-byte salt (HKDF-sha256) and uses a random
+ * 12-byte IV, so encrypting the same data twice gives different outputs. The {@link Crypt} provider does the same with
+ * configured keys and key rotation.
+ *
+ * The key must be random (see {@link generateSecret}): its derivation is fast, so a password used as a key is open to
+ * brute force; use {@link encryptByPassword} for passwords. The function refuses an empty key, but does not check
+ * the key's length or strength otherwise.
+ * @param data The data to encrypt: a string (encrypted as its UTF-8 bytes) or bytes.
+ * @param key The secret key: a string (used as its UTF-8 bytes, not decoded from base64) or bytes, not empty; 32
+ * random bytes recommended.
+ * @returns The encrypted data, base64url encoded without padding: 1 version byte, the salt, the IV, a 16-byte
+ * authentication tag and the ciphertext (45 bytes more than the data, before base64url).
+ * @throws {RangeError} When the key is empty.
+ * @example
+ * ```typescript
+ * import {decryptByKey, encryptByKey, generateSecret} from 'lakutata/security'
+ *
+ * const key: string = process.env.CRYPT_KEY ?? generateSecret()
+ * const encrypted: string = encryptByKey('card ending 4242', key)
+ * console.log(decryptByKey(encrypted, key).toString('utf8'))
+ * ```
+ */
+function encryptByKey(data, key) {
+    (0, AssertKey_js_1.assertKey)(key);
+    const salt = (0, node_crypto_1.randomBytes)(SALT_LENGTH);
+    return seal(KEY_VERSION, salt, deriveKey(key, salt), data);
+}
+/**
+ * Decrypt data encrypted by {@link encryptByKey} (or {@link Crypt.encrypt}) with one of the keys, tried in order: list
+ * the current key and the previous ones during a key rotation. The authentication tag is checked before anything is
+ * returned, so changed data is never decrypted.
+ * @param encrypted The encrypted data, base64url as {@link encryptByKey} returns it.
+ * @param keys The key, or the keys to try: strings (used as their UTF-8 bytes) or bytes, none empty.
+ * @returns The decrypted bytes (call `.toString('utf8')` for a string).
+ * @throws {DecryptionFailedException} When no key decrypts the data, or it was changed, truncated or not produced by
+ * {@link encryptByKey} (data encrypted by {@link encryptByPassword} included).
+ * @throws {RangeError} When a key is empty.
+ * @example
+ * ```typescript
+ * import {decryptByKey, DecryptionFailedException} from 'lakutata/security'
+ *
+ * declare const encrypted: string
+ * declare const currentKey: string
+ * declare const previousKey: string
+ *
+ * try {
+ *     //The new key first, the previous one while old data remains
+ *     const secret: string = decryptByKey(encrypted, [currentKey, previousKey]).toString('utf8')
+ *     console.log(secret)
+ * } catch (error) {
+ *     if (error instanceof DecryptionFailedException) console.log('Changed, or encrypted with an unknown key')
+ * }
+ * ```
+ */
+function decryptByKey(encrypted, keys) {
+    const candidates = Array.isArray(keys) ? keys : [keys];
+    candidates.forEach(AssertKey_js_1.assertKey);
+    const part = parts(encrypted, KEY_VERSION);
+    if (part) {
+        for (const key of candidates) {
+            const decrypted = open(part, deriveKey(key, part.salt));
+            if (decrypted)
+                return decrypted;
+        }
+    }
+    throw new DecryptionFailedException_js_1.DecryptionFailedException('The data cannot be decrypted');
+}
+/**
+ * Encrypt data with a password chosen by a person, using AES-256-GCM (authenticated encryption) with a key derived
+ * from the password and a random 16-byte salt by scrypt (N = 16384, r = 8, p = 1: about 16 MB of memory and a few
+ * tens of milliseconds per call, off the main thread). The slow derivation makes guessing the password costly; a
+ * strong password still matters. For a random key, {@link encryptByKey} is faster. To check a login password, use
+ * {@link PasswordHash} instead.
+ * @param data The data to encrypt: a string (encrypted as its UTF-8 bytes) or bytes.
+ * @param password The password: a string (used as its UTF-8 bytes) or bytes. Its length is not checked.
+ * @returns The encrypted data, base64url encoded without padding, in the format of {@link encryptByKey} with another
+ * version byte: the two are not interchangeable.
+ * @example
+ * ```typescript
+ * import {decryptByPassword, encryptByPassword} from 'lakutata/security'
+ *
+ * const encrypted: string = await encryptByPassword('backup contents', 'a long passphrase of the user')
+ * console.log((await decryptByPassword(encrypted, 'a long passphrase of the user')).toString('utf8'))
+ * ```
+ */
+async function encryptByPassword(data, password) {
+    const salt = (0, node_crypto_1.randomBytes)(SALT_LENGTH);
+    return seal(PASSWORD_VERSION, salt, await derivePasswordKey(password, salt), data);
+}
+/**
+ * Decrypt data encrypted by {@link encryptByPassword}, deriving the key from the password and the salt stored in the
+ * data (the same scrypt cost).
+ * @param encrypted The encrypted data, base64url as {@link encryptByPassword} returns it.
+ * @param password The password it was encrypted with: a string (used as its UTF-8 bytes) or bytes.
+ * @returns The decrypted bytes (call `.toString('utf8')` for a string).
+ * @throws {DecryptionFailedException} When the password is wrong, or the data was changed, truncated or not produced
+ * by {@link encryptByPassword} (data encrypted by {@link encryptByKey} included).
+ * @example
+ * ```typescript
+ * import {decryptByPassword, DecryptionFailedException} from 'lakutata/security'
+ *
+ * declare const encrypted: string
+ * declare const passphrase: string
+ *
+ * try {
+ *     console.log((await decryptByPassword(encrypted, passphrase)).toString('utf8'))
+ * } catch (error) {
+ *     if (error instanceof DecryptionFailedException) console.log('Wrong passphrase, or changed data')
+ * }
+ * ```
+ */
+async function decryptByPassword(encrypted, password) {
+    const part = parts(encrypted, PASSWORD_VERSION);
+    const decrypted = part ? open(part, await derivePasswordKey(password, part.salt)) : undefined;
+    if (decrypted)
+        return decrypted;
+    throw new DecryptionFailedException_js_1.DecryptionFailedException('The data cannot be decrypted');
+}

package/dist/cjs/functions/GenerateSecret.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generate a random secret key from the operating system's cryptographically secure generator (`crypto.randomBytes`),
+ * suited to the keys of {@link Mac} and {@link Crypt}, {@link hmac} and {@link encryptByKey}, and to random tokens
+ * (session IDs, reset links). It is not a password and should be stored as a secret (an environment variable, a vault).
+ * @param bytes The number of random bytes; 32 (256 bits) by default, at least 16 for a secret (0 gives an empty
+ * string). The keys of {@link Mac} and {@link Crypt} need 12 bytes or more to reach their 16-character minimum.
+ * @returns The random bytes, base64url encoded without padding: 43 characters for 32 bytes, 22 for 16.
+ * @throws {RangeError} When `bytes` is negative or larger than 2^31 - 1.
+ * @example
+ * ```typescript
+ * import {generateSecret} from 'lakutata/security'
+ *
+ * //A 256-bit key, for MAC_KEY or CRYPT_KEY
+ * console.log(generateSecret())
+ * //A 128-bit token
+ * const token: string = generateSecret(16)
+ * console.log(token)
+ * ```
+ */
+export declare function generateSecret(bytes?: number): string;

package/dist/cjs/functions/GenerateSecret.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSecret = generateSecret;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Generate a random secret key from the operating system's cryptographically secure generator (`crypto.randomBytes`),
+ * suited to the keys of {@link Mac} and {@link Crypt}, {@link hmac} and {@link encryptByKey}, and to random tokens
+ * (session IDs, reset links). It is not a password and should be stored as a secret (an environment variable, a vault).
+ * @param bytes The number of random bytes; 32 (256 bits) by default, at least 16 for a secret (0 gives an empty
+ * string). The keys of {@link Mac} and {@link Crypt} need 12 bytes or more to reach their 16-character minimum.
+ * @returns The random bytes, base64url encoded without padding: 43 characters for 32 bytes, 22 for 16.
+ * @throws {RangeError} When `bytes` is negative or larger than 2^31 - 1.
+ * @example
+ * ```typescript
+ * import {generateSecret} from 'lakutata/security'
+ *
+ * //A 256-bit key, for MAC_KEY or CRYPT_KEY
+ * console.log(generateSecret())
+ * //A 128-bit token
+ * const token: string = generateSecret(16)
+ * console.log(token)
+ * ```
+ */
+function generateSecret(bytes = 32) {
+    return (0, node_crypto_1.randomBytes)(bytes).toString('base64url');
+}

package/dist/cjs/functions/HMAC.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The hash functions of the HMAC signatures: `'sha256'` (43-character signatures), `'sha384'` (64) or `'sha512'` (86).
+ */
+export type HMACAlgorithm = 'sha256' | 'sha384' | 'sha512';
+/**
+ * Sign data with a key: compute its hmac, a keyed hash that only a holder of the key can produce. Use it to detect
+ * tampering (webhooks, signed links); it does not hide the data, and is not a password hash. The {@link Mac} provider
+ * does the same with configured keys and key rotation.
+ * @param data The data to sign: a string (signed as its UTF-8 bytes) or bytes.
+ * @param key The secret key: a string (used as its UTF-8 bytes, not decoded) or bytes, not empty. Use a random key of
+ * 32 bytes, such as {@link generateSecret} returns.
+ * @param algorithm The hash function; `'sha256'` by default.
+ * @returns The hmac, base64url encoded without padding.
+ * @throws {RangeError} When the key is empty.
+ * @example
+ * ```typescript
+ * import {generateSecret, hmac, verifyHMAC} from 'lakutata/security'
+ *
+ * const key: string = process.env.WEBHOOK_KEY ?? generateSecret()
+ * const body: string = JSON.stringify({order: 42, status: 'paid'})
+ * //Sent in a header along with the body
+ * const signature: string = hmac(body, key, 'sha256')
+ * console.log(verifyHMAC(body, signature, key, 'sha256'))
+ * ```
+ */
+export declare function hmac(data: string | Uint8Array, key: string | Uint8Array, algorithm?: HMACAlgorithm): string;
+/**
+ * Check that a signature is the HMAC of data with a key, in a time that does not depend on the signature (see
+ * {@link constantTimeEqual}).
+ * @param data The signed data, exactly as it was signed (the raw request body, not a re-serialized copy).
+ * @param signature The signature to check, base64url encoded without padding as {@link hmac} returns it; a hex or
+ * padded signature does not match.
+ * @param key The secret key the data was signed with: a string (used as its UTF-8 bytes) or bytes, not empty.
+ * @param algorithm The hash function the data was signed with; `'sha256'` by default.
+ * @returns `true` when the signature matches.
+ * @throws {RangeError} When the key is empty.
+ * @example
+ * ```typescript
+ * import {InvalidSignatureException, verifyHMAC} from 'lakutata/security'
+ *
+ * declare const rawBody: string
+ * declare const signatureHeader: string
+ * declare const webhookKey: string
+ *
+ * if (!verifyHMAC(rawBody, signatureHeader, webhookKey)) {
+ *     throw new InvalidSignatureException('The signature of the webhook is not valid')
+ * }
+ * ```
+ */
+export declare function verifyHMAC(data: string | Uint8Array, signature: string, key: string | Uint8Array, algorithm?: HMACAlgorithm): boolean;

package/dist/cjs/functions/HMAC.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hmac = hmac;
+exports.verifyHMAC = verifyHMAC;
+const node_crypto_1 = require("node:crypto");
+const TimingSafeEqual_js_1 = require("./TimingSafeEqual.js");
+const AssertKey_js_1 = require("../lib/AssertKey.js");
+/**
+ * Sign data with a key: compute its hmac, a keyed hash that only a holder of the key can produce. Use it to detect
+ * tampering (webhooks, signed links); it does not hide the data, and is not a password hash. The {@link Mac} provider
+ * does the same with configured keys and key rotation.
+ * @param data The data to sign: a string (signed as its UTF-8 bytes) or bytes.
+ * @param key The secret key: a string (used as its UTF-8 bytes, not decoded) or bytes, not empty. Use a random key of
+ * 32 bytes, such as {@link generateSecret} returns.
+ * @param algorithm The hash function; `'sha256'` by default.
+ * @returns The hmac, base64url encoded without padding.
+ * @throws {RangeError} When the key is empty.
+ * @example
+ * ```typescript
+ * import {generateSecret, hmac, verifyHMAC} from 'lakutata/security'
+ *
+ * const key: string = process.env.WEBHOOK_KEY ?? generateSecret()
+ * const body: string = JSON.stringify({order: 42, status: 'paid'})
+ * //Sent in a header along with the body
+ * const signature: string = hmac(body, key, 'sha256')
+ * console.log(verifyHMAC(body, signature, key, 'sha256'))
+ * ```
+ */
+function hmac(data, key, algorithm = 'sha256') {
+    (0, AssertKey_js_1.assertKey)(key);
+    return (0, node_crypto_1.createHmac)(algorithm, key).update(data).digest('base64url');
+}
+/**
+ * Check that a signature is the HMAC of data with a key, in a time that does not depend on the signature (see
+ * {@link constantTimeEqual}).
+ * @param data The signed data, exactly as it was signed (the raw request body, not a re-serialized copy).
+ * @param signature The signature to check, base64url encoded without padding as {@link hmac} returns it; a hex or
+ * padded signature does not match.
+ * @param key The secret key the data was signed with: a string (used as its UTF-8 bytes) or bytes, not empty.
+ * @param algorithm The hash function the data was signed with; `'sha256'` by default.
+ * @returns `true` when the signature matches.
+ * @throws {RangeError} When the key is empty.
+ * @example
+ * ```typescript
+ * import {InvalidSignatureException, verifyHMAC} from 'lakutata/security'
+ *
+ * declare const rawBody: string
+ * declare const signatureHeader: string
+ * declare const webhookKey: string
+ *
+ * if (!verifyHMAC(rawBody, signatureHeader, webhookKey)) {
+ *     throw new InvalidSignatureException('The signature of the webhook is not valid')
+ * }
+ * ```
+ */
+function verifyHMAC(data, signature, key, algorithm = 'sha256') {
+    return (0, TimingSafeEqual_js_1.constantTimeEqual)(hmac(data, key, algorithm), signature);
+}

package/dist/cjs/functions/TimingSafeEqual.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compare two secrets (signatures, tokens, API keys) in a time that does not depend on their content or their lengths,
+ * so an attacker cannot guess a secret by timing the comparisons. Values of different lengths are compared too, and
+ * are unequal. Use it instead of `===` whenever one side is a secret; to check a password, use
+ * {@link PasswordHash.validate} instead.
+ * @param a The first value: a string (compared as its UTF-8 bytes) or bytes.
+ * @param b The second value: a string (compared as its UTF-8 bytes) or bytes.
+ * @returns `true` when both values hold the same bytes.
+ * @example
+ * ```typescript
+ * import {constantTimeEqual} from 'lakutata/security'
+ *
+ * declare const presentedApiKey: string
+ *
+ * if (!constantTimeEqual(presentedApiKey, process.env.API_KEY ?? '')) throw new Error('Unauthorized')
+ * ```
+ */
+export declare function constantTimeEqual(a: string | Uint8Array, b: string | Uint8Array): boolean;

package/dist/cjs/functions/TimingSafeEqual.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constantTimeEqual = constantTimeEqual;
+const node_crypto_1 = require("node:crypto");
+/**
+ * A random key of the process: the compared values are digested with it, so the comparison does not reveal their length
+ */
+const COMPARISON_KEY = (0, node_crypto_1.randomBytes)(32);
+/**
+ * Compare two secrets (signatures, tokens, API keys) in a time that does not depend on their content or their lengths,
+ * so an attacker cannot guess a secret by timing the comparisons. Values of different lengths are compared too, and
+ * are unequal. Use it instead of `===` whenever one side is a secret; to check a password, use
+ * {@link PasswordHash.validate} instead.
+ * @param a The first value: a string (compared as its UTF-8 bytes) or bytes.
+ * @param b The second value: a string (compared as its UTF-8 bytes) or bytes.
+ * @returns `true` when both values hold the same bytes.
+ * @example
+ * ```typescript
+ * import {constantTimeEqual} from 'lakutata/security'
+ *
+ * declare const presentedApiKey: string
+ *
+ * if (!constantTimeEqual(presentedApiKey, process.env.API_KEY ?? '')) throw new Error('Unauthorized')
+ * ```
+ */
+function constantTimeEqual(a, b) {
+    const digestA = (0, node_crypto_1.createHmac)('sha256', COMPARISON_KEY).update(a).digest();
+    const digestB = (0, node_crypto_1.createHmac)('sha256', COMPARISON_KEY).update(b).digest();
+    return (0, node_crypto_1.timingSafeEqual)(digestA, digestB);
+}

package/dist/cjs/lib/AssertKey.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Refuse an empty key: HMAC and HKDF accept it, but data signed or encrypted with it is open to anyone
+ * @param key
+ */
+export declare function assertKey(key: string | Uint8Array): void;

package/dist/cjs/lib/AssertKey.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertKey = assertKey;
+/**
+ * Refuse an empty key: HMAC and HKDF accept it, but data signed or encrypted with it is open to anyone
+ * @param key
+ */
+function assertKey(key) {
+    if (key.length === 0)
+        throw new RangeError('The key is empty');
+}

package/dist/cjs/lib/bcrypt/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Derived from the upstream index.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+declare const BASE64_CODE: readonly string[];
+declare const BASE64_INDEX: readonly number[];
+declare const BCRYPT_SALT_LEN: number;
+declare const GENSALT_DEFAULT_LOG2_ROUNDS: number;
+declare const BLOWFISH_NUM_ROUNDS: number;
+declare const MAX_EXECUTION_TIME: number;
+declare const P_ORIG: readonly number[];
+declare const S_ORIG: readonly number[];
+declare const C_ORIG: readonly number[];
+export { BASE64_CODE, BASE64_INDEX, BCRYPT_SALT_LEN, GENSALT_DEFAULT_LOG2_ROUNDS, BLOWFISH_NUM_ROUNDS, MAX_EXECUTION_TIME, P_ORIG, S_ORIG, C_ORIG };