@bb301/simple-encryption-util/dist/lib.d.ts

A simple Node.js library (written in TypeScript) and accompanying CLI tool for encrypting and decrypting data using the AES-256 CBC algorithm.

/// <reference types="node" />
/**
 * A utility function that takes a {@link Buffer} as argument and checks whether
 * it is of size 32 bytes (i.e., 256 bits). If it is 32 bytes, it clones it and
 * returns it. If it is less than 32 bytes, it clones it and pads it to the
 * right with zeros to make it 32 bytes. If it is more than 32 bytes, it makes
 * a clone of the first 32 bytes and returns it.
 *
 * @param key A {@link Buffer} instance (used as a password in this context).
 *
 * @returns A 256-bit {@link Buffer} instance containing the first 32 bytes of `key` if
 * `key` is 32-bytes or more, else a copy of `key`'s bytes with extra zeros to the right.
 *
 * @note This function is used internally by {@link encrypt}, {@link encryptAsync},
 * {@link decrypt}, and {@link decryptAsync} to prepare the password before encrypting
 * and decrypting.
 */
export declare const prepareKey: (key: Buffer) => Buffer;
/**
 * A function that can be used to encrypt arbitrary data using the `AES-256-CBC` algorithm.
 *
 * @param data The {@link Buffer} instance or {@link String} containing the data to
 * be encrypted.
 *
 * @param key A {@link Buffer} instance containing the key to be used by the `AES-256-CBC` algorithm
 * for encrypting `data`. Ideally, that buffer would be of size 32 bytes, but, internally, this function will
 * prepare the `key` with {@link prepareKey} in order to make it 32 bytes. This allows for passwords of
 * arbitrary sizes, even if shorter passwords are less secure.
 *
 * @returns A {@link Buffer} instance containing the encrypted data, prepended by an internally randomly
 * generated 128-bit (i.e., 16 bytes) initialization vector.
 *
 * @note Internally, this function uses {@link https://nodejs.org/docs/latest-v20.x/api/crypto.html#class-cipher | Node's crypto.Cipher class}
 * to perform encryption.
 *
 * @remark Encrypting the same data twice using the same password will yield different outputs, as the
 * initialization vector is randomly generated on each call.
 *
 * @see {@link encryptAsync}
 */
export declare const encrypt: (data: string | Buffer, key: Buffer) => Buffer;
/**
 * Similar to {@link encrypt}, but asynchronous, this is a function that can be used
 * to encrypt arbitrary data using the `AES-256-CBC` algorithm.
 *
 * @param data The {@link Buffer} instance or {@link String} containing the data to
 * be encrypted.
 *
 * @param key A {@link Buffer} instance containing the key to be used by the `AES-256-CBC` algorithm
 * for encrypting `data`. Ideally, that buffer would be of size 32 bytes, but, internally, this function will
 * prepare the `key` with {@link prepareKey} in order to make it 32 bytes. This allows for passwords of
 * arbitrary sizes, even if shorter passwords are less secure.
 *
 * @returns A {@link Promise} that resolves to a {@link Buffer} instance containing the encrypted data,
 * prepended by an internally randomly generated 128-bit (i.e., 16 bytes) initialization vector.
 *
 * @note Internally, this function uses {@link https://nodejs.org/docs/latest-v20.x/api/crypto.html#class-cipher | Node's crypto.Cipher class}
 * to perform encryption.
 *
 * @remark Encrypting the same data twice using the same password will yield different outputs, as the
 * initialization vector is randomly generated on each call.
 *
 * @see {@link encrypt}
 */
export declare const encryptAsync: (data: string | Buffer, key: Buffer) => Promise<Buffer>;
/**
 * A function that can be used to decrypt data that has been encrypted using this library's
 * {@link encrypt} or {@link encryptAsync} function, both of which are based on the `AES-256-CBC`
 * algorithm.
 *
 * @param encryptedData The {@link Buffer} instance containing the encrypted data.
 *
 * @param key A {@link Buffer} instance containing the same key that was used when encrypting the data
 * using {@link encrypt} or {@link encryptAsync}.
 *
 * @returns A {@link Buffer} instance containing the decrypted data.
 *
 * @note Internally, this function uses {@link https://nodejs.org/docs/latest-v20.x/api/crypto.html#class-decipher | Node's crypto.Decipher class}
 * to perform decryption.
 *
 * @note This function assumes that the encrypted data has been generated using either {@link encrypt} or
 * {@link encryptAsync}, which two functions randomly generate a 128-bit initialization vector used for
 * encrypting, and then prepend that initialization vector to the encrypted data before returning
 * everything into a {@link Buffer}.
 *
 * @see {@link decryptAsync}
 */
export declare const decrypt: (encryptedData: Buffer, key: Buffer) => Buffer;
/**
 * Similar to {@link decrypt}, but asynchronous, this is a function that can be used to decrypt
 * data that has been encrypted using this library's {@link encrypt} or {@link encryptAsync} function,
 * both of which are based on the `AES-256-CBC` algorithm.
 *
 * @param encryptedData The {@link Buffer} instance containing the encrypted data.
 *
 * @param key A {@link Buffer} instance containing the same key that was used when encrypting the data
 * using {@link encrypt} or {@link encryptAsync}.
 *
 * @returns A {@link Promise} that resolves to a {@link Buffer} instance containing the decrypted data.
 *
 * @note Internally, this function uses {@link https://nodejs.org/docs/latest-v20.x/api/crypto.html#class-decipher | Node's crypto.Decipher class}
 * to perform decryption.
 *
 * @note This function assumes that the encrypted data has been generated using either {@link encrypt} or
 * {@link encryptAsync}, which two functions randomly generate a 128-bit initialization vector used for
 * encrypting, and then prepend that initialization vector to the encrypted data before returning
 * everything into a {@link Buffer}.
 *
 * @see {@link decrypt}
 */
export declare const decryptAsync: (encryptedData: Buffer, key: Buffer) => Promise<Buffer>;
/**
 * A function that can be used to prompt the user for a password in the terminal. The
 * input will be hidden as the user type (i.e., the input will be `TTY`).
 *
 * @param prompt An optional text message to show as prompt for the user's input.
 *
 * @note This function uses the {@link https://github.com/npm/read | read} package internally.
 *
 * @returns A {@link Promise} that resolves to a string containing the user's input.
 */
export declare const requestPassword: (prompt?: string) => Promise<string>;
/**
 * A function that can be used to prompt the user for an arbitrary text input.
 *
 * @param prompt An optional text message to show as prompt for the user's input.
 *
 * @note This function uses the {@link https://github.com/npm/read | read} package internally.
 *
 * @returns A {@link Promise} that resolves to a string containing the user's input.
 */
export declare const requestInput: (prompt?: string) => Promise<string>;
/**
 * A function that can be used to prompt the user for a confirmation.
 *
 * @param prompt A string containing the question to be asked to the user.
 *
 * @param yes An optional array of strings containing values that will be treated as a 'yes'.
 * If none provided, `["yes", "y"]` will be used as default.
 *
 * @returns A {@link Promise} that resolves to a boolean value indicating whether the
 * user accepted or declined.
 *
 * @note For convenience, the values in `yes` as well as the user input will be
 * converted to lowercase before the condition gets evaluated. For instance, if the
 * user input is 'OUI', but `yes = ['oui']`, a positive result will still be
 * obtained.
 *
 * @note This function uses the {@link https://github.com/npm/read | read} package internally.
 */
export declare const askQuestion: (prompt: string, yes?: string[]) => Promise<boolean>;