@lakutata/security 3.0.0-beta.0

package/dist/esm/providers/Crypt.js

@@ -0,0 +1,84 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DTO, Provider } from '@lakutata/core';
+import { Configurable } from '@lakutata/core/decorator/di';
+import { decryptByKey, encryptByKey } from '../functions/Encryption.js';
+/**
+ * The encryption provider: encrypts data with AES-256-GCM (authenticated encryption), with key rotation (the first key
+ * encrypts, every key decrypts). Use it to keep secrets confidential at rest or through a client: tokens stored in a
+ * database, data put in a cookie. The encrypted data is also tamper-proof: changing a byte makes it fail to decrypt.
+ * It is not a password hash: a value that only needs to be checked, never read back, belongs to
+ * {@link PasswordHash}.
+ *
+ * Declare it in the `providers` of the application (`{class: Crypt, keys: [...]}`) and get it with `@Inject` or
+ * `getObject()`; it is scoped, like every provider. Each encryption derives a fresh key from the configured key and a
+ * random salt (HKDF-sha256) and uses a random IV, so encrypting the same data twice gives different outputs. The output
+ * is a base64url string (no padding) of 1 version byte, a 16-byte salt, a 12-byte IV, a 16-byte authentication tag and
+ * the ciphertext (45 bytes more than the data, before base64url), the same format as {@link encryptByKey}.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Crypt, DecryptionFailedException, generateSecret} from 'lakutata/security'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'vault.app',
+ *         name: 'Vault',
+ *         providers: {
+ *             //The keys come from the environment: the new key first, the previous one kept to decrypt
+ *             crypt: {class: Crypt, keys: [process.env.CRYPT_KEY ?? generateSecret(), process.env.CRYPT_PREVIOUS_KEY ?? generateSecret()]}
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const crypt: Crypt = await app.getObject('crypt')
+ *         const encrypted: string = crypt.encrypt('api-token-123')
+ *         try {
+ *             console.log(crypt.decryptString(encrypted))
+ *             console.log(crypt.decrypt(encrypted).length)
+ *         } catch (error) {
+ *             if (error instanceof DecryptionFailedException) console.log('Changed, or encrypted with an unknown key')
+ *         }
+ *     })
+ * ```
+ */
+export class Crypt extends Provider {
+    /**
+     * Encrypt data with the first key.
+     * @param data The data to encrypt: a string (encrypted as its UTF-8 bytes) or bytes.
+     * @returns The encrypted data, base64url encoded without padding.
+     */
+    encrypt(data) {
+        return encryptByKey(data, this.keys[0]);
+    }
+    /**
+     * Decrypt data encrypted by {@link Crypt.encrypt} (or {@link encryptByKey}) with any of the keys, tried in order.
+     * @param encrypted The encrypted data, base64url as {@link Crypt.encrypt} returns it.
+     * @returns The decrypted bytes.
+     * @throws {DecryptionFailedException} When no key decrypts the data, or it was changed, truncated or not produced by
+     * {@link Crypt.encrypt}.
+     */
+    decrypt(encrypted) {
+        return decryptByKey(encrypted, this.keys);
+    }
+    /**
+     * Decrypt data encrypted by {@link Crypt.encrypt} with any of the keys, and decode it as a UTF-8 string.
+     * @param encrypted The encrypted data, base64url as {@link Crypt.encrypt} returns it.
+     * @returns The decrypted string.
+     * @throws {DecryptionFailedException} When no key decrypts the data, or it was changed, truncated or not produced by
+     * {@link Crypt.encrypt}.
+     */
+    decryptString(encrypted) {
+        return this.decrypt(encrypted).toString('utf8');
+    }
+}
+__decorate([
+    Configurable(DTO.Array().items(DTO.String().min(16)).min(1).required()),
+    __metadata("design:type", Array)
+], Crypt.prototype, "keys", void 0);

package/dist/esm/providers/Mac.js

@@ -0,0 +1,110 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DTO, Provider } from '@lakutata/core';
+import { Configurable } from '@lakutata/core/decorator/di';
+import { hmac, verifyHMAC } from '../functions/HMAC.js';
+import { InvalidSignatureException } from '../exceptions/InvalidSignatureException.js';
+/**
+ * The message signing provider: signs data with an HMAC (SHA-256 by default) and verifies the signatures, with key
+ * rotation (the first key signs, every key verifies). Use it to detect tampering with the data that goes through a
+ * client: signed cookies, links, webhook payloads, tokens. A signature proves the data was signed by a holder of a key;
+ * it does not hide the data (use {@link Crypt}) and is not a password hash (use {@link PasswordHash}).
+ *
+ * Declare it in the `providers` of the application (`{class: Mac, keys: [...]}`) and get it with `@Inject` or
+ * `getObject()`; it is scoped, like every provider. The signatures are base64url strings without padding (43
+ * characters with SHA-256, 64 with SHA-384, 86 with SHA-512) and never expire by themselves: put a time in the signed
+ * data to limit their validity. Verification takes a constant time and tries every key, so it does not reveal which
+ * key failed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {generateSecret, InvalidSignatureException, Mac} from 'lakutata/security'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'links.app',
+ *         name: 'Links',
+ *         providers: {
+ *             //The keys come from the environment: the new key first, the previous one kept to verify
+ *             mac: {class: Mac, keys: [process.env.MAC_KEY ?? generateSecret(), process.env.MAC_PREVIOUS_KEY ?? generateSecret()]}
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const mac: Mac = await app.getObject('mac')
+ *         //'user:42.<signature>'
+ *         const token: string = mac.signMessage('user:42')
+ *         try {
+ *             console.log(mac.unsignMessage(token))
+ *         } catch (error) {
+ *             if (error instanceof InvalidSignatureException) console.log('Tampered token')
+ *         }
+ *         //A detached signature, sent alongside the body
+ *         const signature: string = mac.sign('{"order":42}')
+ *         console.log(mac.verify('{"order":42}', signature))
+ *     })
+ * ```
+ */
+export class Mac extends Provider {
+    /**
+     * Sign data with the first key.
+     * @param data The data to sign: a string (signed as its UTF-8 bytes) or bytes.
+     * @returns The HMAC of the data, base64url encoded without padding.
+     */
+    sign(data) {
+        return hmac(data, this.keys[0], this.algorithm);
+    }
+    /**
+     * Check a detached signature made by {@link Mac.sign} with any of the keys, in a time that does not depend on the
+     * signature or on the key that matches.
+     * @param data The signed data, exactly as it was signed (same string or same bytes).
+     * @param signature The signature to check, base64url as {@link Mac.sign} returns it.
+     * @returns `true` when one of the keys signed the data; `false` otherwise (never throws on a malformed signature).
+     */
+    verify(data, signature) {
+        //Every key is tried, to not reveal which one signed
+        let valid = false;
+        for (const key of this.keys)
+            valid = verifyHMAC(data, signature, key, this.algorithm) || valid;
+        return valid;
+    }
+    /**
+     * Sign a message and append the signature: `<message>.<signature>`. The message is not encrypted: anyone can read
+     * it, only a key holder can change it.
+     * @param message The message to sign; it may contain dots (the signature follows the last one).
+     * @returns The signed message, to read back with {@link Mac.unsignMessage}.
+     */
+    signMessage(message) {
+        return `${message}.${this.sign(message)}`;
+    }
+    /**
+     * Check a message signed by {@link Mac.signMessage} with any of the keys, and return it without its signature.
+     * @param signedMessage The signed message, `<message>.<signature>`.
+     * @returns The original message.
+     * @throws {InvalidSignatureException} When the signed message has no dot, or its signature is not valid (the message
+     * or the signature was changed, or none of the keys signed it).
+     */
+    unsignMessage(signedMessage) {
+        const index = signedMessage.lastIndexOf('.');
+        if (index >= 0) {
+            const message = signedMessage.slice(0, index);
+            if (this.verify(message, signedMessage.slice(index + 1)))
+                return message;
+        }
+        throw new InvalidSignatureException('The signature of the message is not valid');
+    }
+}
+__decorate([
+    Configurable(DTO.Array().items(DTO.String().min(16)).min(1).required()),
+    __metadata("design:type", Array)
+], Mac.prototype, "keys", void 0);
+__decorate([
+    Configurable(DTO.String().valid('sha256', 'sha384', 'sha512').optional().default('sha256')),
+    __metadata("design:type", String)
+], Mac.prototype, "algorithm", void 0);

package/dist/esm/providers/PasswordHash.js

@@ -0,0 +1,109 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import * as bcrypt from '../lib/bcrypt/index.js';
+import { DTO, Provider } from '@lakutata/core';
+import { Configurable } from '@lakutata/core/decorator/di';
+import { PasswordTooLongException } from '../exceptions/PasswordTooLongException.js';
+/**
+ * The largest password bcrypt hashes entirely, in UTF-8 bytes (it ignores the following bytes)
+ */
+const MAX_PASSWORD_BYTES = 72;
+/**
+ * A bcrypt hash: its variant, its cost (4 to 31), then its salt and its digest in bcrypt's base64 alphabet
+ */
+const BCRYPT_HASH = /^\$2[aby]\$(0[4-9]|[12]\d|3[01])\$[./A-Za-z0-9]{53}$/;
+/**
+ * The password hashing provider: hashes passwords with bcrypt (a new random 16-byte salt per hash, the `$2b$` variant)
+ * and checks a password against a stored hash. Use it for user passwords: bcrypt is deliberately slow, so a stolen hash
+ * is costly to brute-force. Do not use it to hash tokens or keys (use {@link hmac}) or to encrypt (use {@link Crypt}).
+ *
+ * Declare it in the `providers` of the application (`{class: PasswordHash, saltRounds: 12}`) and get it with `@Inject`
+ * or `getObject()`; it is scoped, like every provider. A hash is a 60-character string (`$2b$10$` then the salt and the
+ * digest) holding its own salt and cost, so it is stored as is, in one column, and {@link PasswordHash.validate} needs
+ * nothing else; hashes of another cost (or the `$2a$`/`$2y$` variants of other bcrypt libraries) still validate.
+ *
+ * bcrypt only reads the first 72 bytes of a password (UTF-8): {@link PasswordHash.hash} rejects a longer password with
+ * {@link PasswordTooLongException} rather than hashing its prefix, and {@link PasswordHash.validate} gives `false` for
+ * it. bcrypt runs in JavaScript on the main thread, in
+ * slices of at most 100 ms between which the other requests proceed; a hash or a validation costs about 60 ms of CPU
+ * at cost 10 on a current CPU, doubling with each extra round.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {PasswordHash, PasswordTooLongException} from 'lakutata/provider/passwordHash'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'auth.app',
+ *         name: 'Auth',
+ *         providers: {
+ *             //Each extra round doubles the cost of a hash
+ *             passwordHash: {class: PasswordHash, saltRounds: 12}
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const passwordHash: PasswordHash = await app.getObject('passwordHash')
+ *         try {
+ *             //Stored as is: the hash holds its salt and its cost
+ *             const hash: string = await passwordHash.hash('correct horse battery staple')
+ *             console.log(await passwordHash.validate('correct horse battery staple', hash))
+ *             console.log(await passwordHash.validate('wrong password', hash))
+ *         } catch (error) {
+ *             if (error instanceof PasswordTooLongException) console.log('Choose a password of 72 bytes at most')
+ *         }
+ *     })
+ * ```
+ */
+export class PasswordHash extends Provider {
+    /**
+     * A new random bcrypt salt with the configured cost (`$2b$10$` and 22 characters), different at each read.
+     * @deprecated Not needed: {@link PasswordHash.hash} generates a salt for each hash, and the hash holds it for
+     * {@link PasswordHash.validate}.
+     */
+    get salt() {
+        return bcrypt.genSaltSync(this.saltRounds);
+    }
+    /**
+     * Hash a password with bcrypt, a new random salt and the configured {@link PasswordHash.saltRounds}. Two hashes of
+     * the same password differ: compare them with {@link PasswordHash.validate}, never with `===`.
+     * @param password The password, as typed by the user: at most 72 bytes once encoded in UTF-8 (72 ASCII
+     * characters, fewer with accented letters or emoji). An empty password is hashed too: reject it beforehand if needed.
+     * @returns The 60-character bcrypt hash (`$2b$<cost>$<salt><digest>`, bcrypt's own base64 alphabet), to store as is.
+     * @throws {PasswordTooLongException} When the password is longer than 72 bytes in UTF-8.
+     */
+    async hash(password) {
+        //bcrypt ignores the bytes beyond the 72nd: a longer password would match any password sharing its 72 first bytes
+        if (bcrypt.truncates(password))
+            throw new PasswordTooLongException('The password is longer than {max} bytes', { max: MAX_PASSWORD_BYTES });
+        return await bcrypt.hash(password, this.saltRounds);
+    }
+    /**
+     * Check a password against a hash made by {@link PasswordHash.hash} (or by another bcrypt library: `$2a$`, `$2b$`,
+     * `$2y$`), with the salt and the cost the hash holds; the final comparison takes a constant time.
+     * @param password The password to check. A password longer than 72 bytes in UTF-8 gives `false`:
+     * {@link PasswordHash.hash} refuses it, so no hash can be its own.
+     * @param hash The stored bcrypt hash. A value which is not a bcrypt hash (not 60 characters long, a wrong prefix,
+     * cost or alphabet) gives `false`.
+     * @returns `true` when the password matches the hash.
+     */
+    async validate(password, hash) {
+        //Never thrown on a malformed hash: a hash is data read from storage
+        if (typeof hash !== 'string' || !BCRYPT_HASH.test(hash))
+            return false;
+        //bcrypt would compare the first 72 bytes only: a longer password matches no hash made by hash()
+        if (bcrypt.truncates(password))
+            return false;
+        return await bcrypt.compare(password, hash);
+    }
+}
+__decorate([
+    Configurable(DTO.Number().integer().min(4).max(31).optional().default(10)),
+    __metadata("design:type", Number)
+], PasswordHash.prototype, "saltRounds", void 0);

package/dist/types/exceptions/DecryptionFailedException.d.ts

@@ -0,0 +1,13 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link Crypt.decrypt}, {@link Crypt.decryptString}, {@link decryptByKey} and {@link decryptByPassword}
+ * when the data cannot be decrypted: a wrong key or password, data changed or truncated, or data not produced by the
+ * matching encryption function. The message does not tell these cases apart, on purpose. Its `errno` is
+ * `'E_DECRYPTION_FAILED'`; its HTTP status is 500 unless the application handles it.
+ */
+export declare class DecryptionFailedException extends Exception {
+    /**
+     * `'E_DECRYPTION_FAILED'`.
+     */
+    errno: string | number;
+}

package/dist/types/exceptions/InvalidSignatureException.d.ts

@@ -0,0 +1,13 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link Mac.unsignMessage} when the signed message has no signature or its signature is not valid (the
+ * message or the signature was changed, or none of the configured keys signed it); applications may throw it too
+ * after {@link verifyHMAC} fails. Its `errno` is `'E_INVALID_SIGNATURE'`; its HTTP status is 500 unless the application
+ * handles it.
+ */
+export declare class InvalidSignatureException extends Exception {
+    /**
+     * `'E_INVALID_SIGNATURE'`.
+     */
+    errno: string | number;
+}

package/dist/types/exceptions/PasswordTooLongException.d.ts

@@ -0,0 +1,12 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link PasswordHash.hash} when the password is longer than 72 bytes once encoded in UTF-8, the most bcrypt
+ * reads: hashing only its prefix would let any password sharing those 72 bytes match. Ask the user for a shorter
+ * password. Its `errno` is `'E_PASSWORD_TOO_LONG'`; its HTTP status is 500 unless the application handles it.
+ */
+export declare class PasswordTooLongException extends Exception {
+    /**
+     * `'E_PASSWORD_TOO_LONG'`.
+     */
+    errno: string | number;
+}

package/dist/types/exports/Security.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Providers
+ */
+export * from '../providers/PasswordHash.js';
+export * from '../providers/Mac.js';
+export * from '../providers/Crypt.js';
+/**
+ * Functions
+ */
+export * from '../functions/TimingSafeEqual.js';
+export * from '../functions/GenerateSecret.js';
+export * from '../functions/HMAC.js';
+export * from '../functions/Encryption.js';
+/**
+ * Exceptions
+ */
+export * from '../exceptions/PasswordTooLongException.js';
+export * from '../exceptions/InvalidSignatureException.js';
+export * from '../exceptions/DecryptionFailedException.js';

package/dist/types/functions/Encryption.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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'))
+ * ```
+ */
+export declare function encryptByKey(data: string | Uint8Array, key: string | Uint8Array): string;
+/**
+ * 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')
+ * }
+ * ```
+ */
+export declare function decryptByKey(encrypted: string, keys: string | Uint8Array | (string | Uint8Array)[]): Buffer;
+/**
+ * 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'))
+ * ```
+ */
+export declare function encryptByPassword(data: string | Uint8Array, password: string | Uint8Array): Promise<string>;
+/**
+ * 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')
+ * }
+ * ```
+ */
+export declare function decryptByPassword(encrypted: string, password: string | Uint8Array): Promise<Buffer>;

package/dist/types/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/types/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/types/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/types/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/types/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 };