@lakutata/security 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @lakutata/security
+
+The security toolkit of the lakutata framework, built on `node:crypto`: password hashing with bcrypt (`PasswordHash`),
+message signatures with HMAC (`Mac`), authenticated encryption with AES-256-GCM (`Crypt`), with key rotation, and the
+functions under them (random keys, constant-time comparison, encryption with a key or a password). The umbrella package
+`lakutata` re-exports it as `lakutata/security`, and `PasswordHash` alone as `lakutata/provider/passwordHash`.
+
+## Installation
+
+```shell
+npm install lakutata
+```
+
+It has no optional dependencies: bcrypt is implemented in JavaScript, the rest uses `node:crypto`.
+
+## Usage
+
+### The providers in an application
+
+Declare the providers in the `providers` of the application, with their keys read from the environment, then get them
+with `getObject()` or `@Inject`. They are scoped, like every provider.
+
+```typescript
+import {Application} from 'lakutata'
+import {Crypt, generateSecret, Mac, PasswordHash} from 'lakutata/security'
+
+Application
+    .run(() => ({
+        id: 'security.app',
+        name: 'Security',
+        providers: {
+            passwordHash: {class: PasswordHash, saltRounds: 12},
+            //The first key signs and encrypts, every key verifies and decrypts
+            mac: {class: Mac, keys: [process.env.MAC_KEY ?? generateSecret()], algorithm: 'sha256'},
+            crypt: {class: Crypt, keys: [process.env.CRYPT_KEY ?? generateSecret(), process.env.CRYPT_PREVIOUS_KEY ?? generateSecret()]}
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const passwordHash: PasswordHash = await app.getObject('passwordHash')
+        const hash: string = await passwordHash.hash('correct horse battery staple')
+        console.log(await passwordHash.validate('correct horse battery staple', hash))
+
+        const mac: Mac = await app.getObject('mac')
+        const token: string = mac.signMessage('user:42')
+        console.log(mac.unsignMessage(token))
+
+        const crypt: Crypt = await app.getObject('crypt')
+        console.log(crypt.decryptString(crypt.encrypt('api-token-123')))
+    })
+```
+
+### Which tool for which secret
+
+| Need | Use | Fit for passwords | Output |
+|---|---|---|---|
+| Store a user password, check it at login | `PasswordHash` (bcrypt) | yes: slow and salted | 60-character bcrypt hash (`$2b$10$...`) |
+| Detect tampering (cookies, links, webhooks) | `Mac`, `hmac()` / `verifyHMAC()` | no: fast, needs a random key | base64url HMAC (43 characters with SHA-256) |
+| Hide and protect data, read it back | `Crypt`, `encryptByKey()` / `decryptByKey()` | no: needs a random key | base64url: version, salt, IV, tag, ciphertext |
+| Encrypt with a passphrase typed by a person | `encryptByPassword()` / `decryptByPassword()` | yes, for encryption (scrypt) | same format, another version |
+| Generate a key or a token | `generateSecret()` | — | base64url random bytes (32 by default) |
+| Compare a secret received with the expected one | `constantTimeEqual()` | no: use `PasswordHash.validate()` | boolean |
+
+- **Passwords**: `PasswordHash.hash()` rejects passwords longer than 72 bytes in UTF-8 (bcrypt ignores the following
+  bytes) with `PasswordTooLongException`, and `validate()` gives `false` for them. Each hash has its own random salt and
+  its cost (`saltRounds`, 4 to 31, 10 by default: each extra round doubles the time); store the hash as is and check it
+  with `validate()`, never with `===`. `validate()` gives `false` for a value which is not a bcrypt hash.
+- **Keys**: the keys of `Mac` and `Crypt` are strings of at least 16 characters, used as their UTF-8 bytes. Generate
+  them with `generateSecret()` (32 random bytes): the key derivations of `Mac`, `Crypt` and `encryptByKey()` are fast, so a
+  password used as a key is open to brute force. The functions refuse an empty key with a `RangeError`, but do not
+  check the key's length otherwise.
+- **Key rotation**: put the new key first and keep the previous ones while the data they signed or encrypted is read;
+  the first key signs and encrypts, every key verifies and decrypts.
+- **Formats**: the signatures and the encrypted data are base64url strings without padding, safe in URLs and cookies.
+  The encrypted data is authenticated: any change makes the decryption fail rather than return altered data.
+
+### The functions
+
+```typescript
+import {
+    decryptByKey,
+    decryptByPassword,
+    encryptByKey,
+    encryptByPassword,
+    generateSecret,
+    hmac,
+    constantTimeEqual,
+    verifyHMAC
+} from 'lakutata/security'
+
+const key: string = generateSecret()
+
+//Signatures: the raw body and its signature, sent in a header
+const body: string = JSON.stringify({order: 42})
+const signature: string = hmac(body, key, 'sha512')
+console.log(verifyHMAC(body, signature, key, 'sha512'))
+
+//Encryption with a random key, decrypted with the current or a previous key
+const encrypted: string = encryptByKey('card ending 4242', key)
+console.log(decryptByKey(encrypted, [key, generateSecret()]).toString('utf8'))
+
+//Encryption with a passphrase (scrypt, asynchronous)
+const backup: string = await encryptByPassword('backup contents', 'a long passphrase')
+console.log((await decryptByPassword(backup, 'a long passphrase')).toString('utf8'))
+
+//Constant-time comparison of a presented token
+console.log(constantTimeEqual('presented-token', process.env.API_TOKEN ?? ''))
+```
+
+## API
+
+| Export | What it is |
+|---|---|
+| `PasswordHash` | Provider hashing passwords with bcrypt: `hash()`, `validate()`; the option `saltRounds` (default 10) |
+| `Mac` | Provider signing with HMAC and key rotation: `sign()`, `verify()`, `signMessage()`, `unsignMessage()`; the options `keys`, `algorithm` (default `'sha256'`) |
+| `Crypt` | Provider encrypting with AES-256-GCM and key rotation: `encrypt()`, `decrypt()`, `decryptString()`; the option `keys` |
+| `hmac`, `verifyHMAC` | Sign data with a key, check a signature in constant time |
+| `HMACAlgorithm` | The hash functions of the signatures: `'sha256'`, `'sha384'`, `'sha512'` |
+| `encryptByKey`, `decryptByKey` | Authenticated encryption with a random key (HKDF-SHA256 per message) |
+| `encryptByPassword`, `decryptByPassword` | Authenticated encryption with a password (scrypt) |
+| `generateSecret` | A random key or token, base64url |
+| `constantTimeEqual` | Compare two secrets in constant time, whatever their lengths |
+| `PasswordTooLongException`, `InvalidSignatureException`, `DecryptionFailedException` | The exceptions |
+
+All are exported by `lakutata/security` and `@lakutata/security`. The typings document each declaration with examples.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `PasswordTooLongException` (`E_PASSWORD_TOO_LONG`) | `PasswordHash.hash()` with a password longer than 72 bytes in UTF-8 |
+| `InvalidSignatureException` (`E_INVALID_SIGNATURE`) | `Mac.unsignMessage()` with a message changed, unsigned or signed by an unknown key |
+| `DecryptionFailedException` (`E_DECRYPTION_FAILED`) | `Crypt.decrypt()`, `decryptString()`, `decryptByKey()`, `decryptByPassword()`: a wrong key or password, changed or truncated data |
+| `InvalidObjectOptionsException` (from `lakutata`) | The application starts with invalid provider options: no key, a key shorter than 16 characters, an unknown algorithm, `saltRounds` outside 4 to 31 (`InvalidValueException` when the provider is created outside the checked options, as in a bare `Container`) |
+| `RangeError` | `generateSecret()` with a negative or too large number of bytes; `hmac()`, `verifyHMAC()`, `encryptByKey()`, `decryptByKey()` with an empty key |
+
+The exceptions have the HTTP status 500 unless the application maps them; `verify()`, `verifyHMAC()` (given a key),
+`validate()` and `constantTimeEqual()` return `false` for a wrong or malformed signature, hash or secret instead of
+throwing.
+
+## See also
+
+- `doc/en/Security.md` of the package `lakutata` (Chinese in `doc/zh`): the guide of the security tools.
+- `@lakutata/core` (`lakutata`): the providers, `Application` and the dependency injection.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,36 @@
+# Third-party notices
+
+Parts of `@lakutata/security` are derived from the third-party projects listed below. They are rewritten in
+TypeScript and modified; the original copyright notices and license terms are reproduced here as required.
+The files derived from these projects refer to "the upstream" in their header; the projects, versions and directories
+are listed in `src/lib/bcrypt/UPSTREAM.md`.
+
+## bcrypt.js (bcryptjs) 3.0.3
+
+Used in `src/lib/bcrypt` (and its ported tests).
+
+Copyright (c) 2012 Nevins Bartolomeo <nevins.bartolomeo@gmail.com>
+Copyright (c) 2012 Shane Girish <shaneGirish@gmail.com>
+Copyright (c) 2025 Daniel Wirtz <dcode@dcode.io>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/cjs/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/cjs/exceptions/DecryptionFailedException.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecryptionFailedException = void 0;
+const core_1 = require("@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.
+ */
+class DecryptionFailedException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_DECRYPTION_FAILED'`.
+         */
+        this.errno = 'E_DECRYPTION_FAILED';
+    }
+}
+exports.DecryptionFailedException = DecryptionFailedException;

package/dist/cjs/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/cjs/exceptions/InvalidSignatureException.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidSignatureException = void 0;
+const core_1 = require("@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.
+ */
+class InvalidSignatureException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_INVALID_SIGNATURE'`.
+         */
+        this.errno = 'E_INVALID_SIGNATURE';
+    }
+}
+exports.InvalidSignatureException = InvalidSignatureException;

package/dist/cjs/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/cjs/exceptions/PasswordTooLongException.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PasswordTooLongException = void 0;
+const core_1 = require("@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.
+ */
+class PasswordTooLongException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_PASSWORD_TOO_LONG'`.
+         */
+        this.errno = 'E_PASSWORD_TOO_LONG';
+    }
+}
+exports.PasswordTooLongException = PasswordTooLongException;

package/dist/cjs/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/cjs/exports/Security.js

@@ -0,0 +1,38 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Providers
+ */
+__exportStar(require("../providers/PasswordHash.js"), exports);
+__exportStar(require("../providers/Mac.js"), exports);
+__exportStar(require("../providers/Crypt.js"), exports);
+/**
+ * Functions
+ */
+__exportStar(require("../functions/TimingSafeEqual.js"), exports);
+__exportStar(require("../functions/GenerateSecret.js"), exports);
+__exportStar(require("../functions/HMAC.js"), exports);
+__exportStar(require("../functions/Encryption.js"), exports);
+/**
+ * Exceptions
+ */
+__exportStar(require("../exceptions/PasswordTooLongException.js"), exports);
+__exportStar(require("../exceptions/InvalidSignatureException.js"), exports);
+__exportStar(require("../exceptions/DecryptionFailedException.js"), exports);
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

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