@lakutata/security 3.0.0-beta.0

package/dist/cjs/providers/Crypt.d.ts

@@ -0,0 +1,71 @@
+import { Provider } from '@lakutata/core';
+/**
+ * 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 declare class Crypt extends Provider {
+    /**
+     * The secret keys, at least one, each a string of at least 16 characters used as its UTF-8 bytes (it is not decoded
+     * from base64). The first key encrypts, every key decrypts: to rotate, put the new key first and keep the previous
+     * ones while data encrypted with them is still read. Use random keys, such as the output of {@link generateSecret}: the
+     * key derivation is fast, so a low-entropy key (a password) is open to brute force; to encrypt with a password, use
+     * {@link encryptByPassword}. Required.
+     */
+    readonly keys: string[];
+    /**
+     * 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: string | Uint8Array): string;
+    /**
+     * 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: string): Buffer;
+    /**
+     * 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: string): string;
+}

package/dist/cjs/providers/Crypt.js

@@ -0,0 +1,88 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Crypt = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const Encryption_js_1 = require("../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')
+ *         }
+ *     })
+ * ```
+ */
+class Crypt extends core_1.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 (0, Encryption_js_1.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 (0, Encryption_js_1.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');
+    }
+}
+exports.Crypt = Crypt;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array().items(core_1.DTO.String().min(16)).min(1).required()),
+    __metadata("design:type", Array)
+], Crypt.prototype, "keys", void 0);

package/dist/cjs/providers/Mac.d.ts

@@ -0,0 +1,86 @@
+import { Provider } from '@lakutata/core';
+import { type HMACAlgorithm } from '../functions/HMAC.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 declare class Mac extends Provider {
+    /**
+     * The secret keys, at least one, each a string of at least 16 characters used as its UTF-8 bytes (it is not decoded
+     * from base64). The first key signs, every key verifies: to rotate, put the new key first and keep the previous ones
+     * while their signatures are still presented. Use random keys, such as the output of {@link generateSecret}, not
+     * passwords. Required.
+     */
+    readonly keys: string[];
+    /**
+     * The hash function of the HMAC: `'sha256'`, `'sha384'` or `'sha512'`. Changing it invalidates every signature made
+     * before.
+     * @default 'sha256'
+     */
+    readonly algorithm: HMACAlgorithm;
+    /**
+     * 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: string | Uint8Array): string;
+    /**
+     * 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: string | Uint8Array, signature: string): boolean;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string): string;
+}

package/dist/cjs/providers/Mac.js

@@ -0,0 +1,114 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mac = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const HMAC_js_1 = require("../functions/HMAC.js");
+const InvalidSignatureException_js_1 = require("../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))
+ *     })
+ * ```
+ */
+class Mac extends core_1.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 (0, HMAC_js_1.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 = (0, HMAC_js_1.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_js_1.InvalidSignatureException('The signature of the message is not valid');
+    }
+}
+exports.Mac = Mac;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array().items(core_1.DTO.String().min(16)).min(1).required()),
+    __metadata("design:type", Array)
+], Mac.prototype, "keys", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().valid('sha256', 'sha384', 'sha512').optional().default('sha256')),
+    __metadata("design:type", String)
+], Mac.prototype, "algorithm", void 0);

package/dist/cjs/providers/PasswordHash.d.ts

@@ -0,0 +1,78 @@
+import { Provider } from '@lakutata/core';
+/**
+ * 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 declare class PasswordHash extends Provider {
+    /**
+     * The bcrypt cost of the new hashes, as a base-2 logarithm: a hash runs 2^saltRounds iterations, so each extra round
+     * doubles the time of {@link PasswordHash.hash} (and of {@link PasswordHash.validate} on the hashes it makes). An
+     * integer from 4 (bcrypt's minimum) to 31. Raise it as far as the login latency allows (12 is a common choice); the
+     * existing hashes keep the cost they were made with.
+     * @default 10
+     */
+    readonly saltRounds: number;
+    /**
+     * 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(): string;
+    /**
+     * 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.
+     */
+    hash(password: string): Promise<string>;
+    /**
+     * 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.
+     */
+    validate(password: string, hash: string): Promise<boolean>;
+}

package/dist/cjs/providers/PasswordHash.js

@@ -0,0 +1,146 @@
+"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 __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 __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;
+    };
+})();
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PasswordHash = void 0;
+const bcrypt = __importStar(require("../lib/bcrypt/index.js"));
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const PasswordTooLongException_js_1 = require("../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')
+ *         }
+ *     })
+ * ```
+ */
+class PasswordHash extends core_1.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_js_1.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);
+    }
+}
+exports.PasswordHash = PasswordHash;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().min(4).max(31).optional().default(10)),
+    __metadata("design:type", Number)
+], PasswordHash.prototype, "saltRounds", void 0);

package/dist/esm/exceptions/DecryptionFailedException.js

@@ -0,0 +1,16 @@
+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 class DecryptionFailedException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_DECRYPTION_FAILED'`.
+         */
+        this.errno = 'E_DECRYPTION_FAILED';
+    }
+}

package/dist/esm/exceptions/InvalidSignatureException.js

@@ -0,0 +1,16 @@
+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 class InvalidSignatureException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_INVALID_SIGNATURE'`.
+         */
+        this.errno = 'E_INVALID_SIGNATURE';
+    }
+}

package/dist/esm/exceptions/PasswordTooLongException.js

@@ -0,0 +1,15 @@
+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 class PasswordTooLongException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_PASSWORD_TOO_LONG'`.
+         */
+        this.errno = 'E_PASSWORD_TOO_LONG';
+    }
+}

package/dist/esm/exports/Security.js

@@ -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';