@lakutata/security 3.0.0-beta.0

package/dist/types/lib/bcrypt/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * A progress callback: the ratio of the rounds done (0 to 1), at most once per 100 ms
+ */
+export type ProgressCallback = (progress: number) => void;
+/**
+ * Bytes: an array of byte values, or a typed array
+ */
+type Bytes = ArrayLike<number>;
+/**
+ * Synchronously generates a salt.
+ * @param rounds Number of rounds to use, defaults to 10 if omitted (from 4 to 31)
+ * @returns Resulting salt
+ */
+export declare function genSaltSync(rounds?: number): string;
+/**
+ * Asynchronously generates a salt.
+ * @param rounds Number of rounds to use, defaults to 10 if omitted
+ * @returns Resulting salt
+ */
+export declare function genSalt(rounds?: number): Promise<string>;
+/**
+ * Synchronously generates a hash for the given password.
+ * @param password Password to hash
+ * @param salt Salt length to generate or salt to use, default to 10
+ * @returns Resulting hash
+ */
+export declare function hashSync(password: string, salt?: number | string): string;
+/**
+ * Asynchronously generates a hash for the given password.
+ * @param password Password to hash
+ * @param salt Salt length to generate or salt to use
+ * @param progressCallback Callback successively called with the percentage of rounds completed (0.0 - 1.0), maximally
+ *  once per `MAX_EXECUTION_TIME = 100` ms.
+ * @returns Resulting hash
+ */
+export declare function hash(password: string, salt: number | string, progressCallback?: ProgressCallback): Promise<string>;
+/**
+ * Synchronously tests a password against a hash.
+ * @param password Password to compare
+ * @param hash Hash to test against
+ * @returns true if matching, otherwise false
+ */
+export declare function compareSync(password: string, hash: string): boolean;
+/**
+ * Asynchronously tests a password against a hash.
+ * @param password Password to compare
+ * @param hashValue Hash to test against
+ * @param progressCallback Callback successively called with the percentage of rounds completed (0.0 - 1.0), maximally
+ *  once per `MAX_EXECUTION_TIME = 100` ms.
+ * @returns true if matching, otherwise false
+ */
+export declare function compare(password: string, hashValue: string, progressCallback?: ProgressCallback): Promise<boolean>;
+/**
+ * Gets the number of rounds used to encrypt the specified hash.
+ * @param hash Hash to extract the used number of rounds from
+ * @returns Number of rounds used
+ */
+export declare function getRounds(hash: string): number;
+/**
+ * Gets the salt portion from a hash. Does not validate the hash.
+ * @param hash Hash to extract the salt from
+ * @returns Extracted salt part
+ */
+export declare function getSalt(hash: string): string;
+/**
+ * Tests if a password will be truncated when hashed, that is its length is greater than 72 bytes when converted to
+ * UTF-8.
+ * @param password The password to test
+ * @returns `true` if truncated, otherwise `false`
+ */
+export declare function truncates(password: string): boolean;
+/**
+ * Encodes a byte array to base64 with up to len bytes of input, using the custom bcrypt alphabet.
+ * @param bytes Byte array
+ * @param length Maximum input length
+ */
+export declare function encodeBase64(bytes: Bytes, length: number): string;
+/**
+ * Decodes a base64 encoded string to up to len bytes of output, using the custom bcrypt alphabet.
+ * @param string String to decode
+ * @param length Maximum output length
+ */
+export declare function decodeBase64(string: string, length: number): number[];
+export {};

package/dist/types/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/types/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/types/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/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@lakutata/security",
+  "version": "3.0.0-beta.0",
+  "description": "Security providers and functions of the lakutata framework (password hashing, signatures, encryption).",
+  "type": "module",
+  "main": "./dist/cjs/exports/Security.js",
+  "types": "./dist/cjs/exports/Security.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/exports/Security.d.ts",
+        "default": "./dist/esm/exports/Security.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Security.d.ts",
+        "default": "./dist/cjs/exports/Security.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs-pkg": "node ../../scripts/package-build/cjs-package.mjs",
+    "build:js": "npm run build:cjs && npm run build:esm && npm run build:cjs-pkg",
+    "rebuild": "npm run clean && npm run build:js",
+    "compile": "npm run rebuild",
+    "test:unit": "npm run compile && node --test \"dist/esm/tests/*.spec.js\""
+  },
+  "peerDependencies": {
+    "@lakutata/core": "3.0.0-beta.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "!dist/*/tests",
+    "*.md",
+    "LICENSE",
+    "package.json",
+    "THIRD_PARTY_NOTICES.md"
+  ]
+}