nhb-toolbox
Version:
A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.
46 lines (45 loc) • 1.76 kB
TypeScript
/**
* @class Lightweight stream-cipher–style encryption utility using `HMAC-SHA256` for keystream generation and authentication.
* - The class derives separate encryption and MAC keys from the provided secret.
*
* @remarks
* - **The encryption scheme is:**
* - keystream = `HMAC(encKey, iv || counter)`
* - ciphertext = `plaintext XOR keystream`
* - tag = `HMAC(macKey, iv || ciphertext)`
* - This is a custom construction and should not be used for production-grade cryptographic security.
* - `Cipher` class is a pure JS implementation. It does not rely on `crypto` or Web APIs.
*/
export declare class Cipher {
#private;
/**
* * Creates a new `Cipher` instance using the provided secret.
*
* @param secret - The secret string used to derive encryption and MAC keys.
* Must be a non-empty string.
*/
constructor(secret: string);
/**
* * Encrypts a UTF-8 string.
* - The output format is: `base64( iv || ciphertext || tag )`
*
* @param text - The plaintext string to encrypt.
* @returns A base64-encoded encrypted token.
*/
encrypt(text: string): string;
/**
* * Checks if a token is structurally valid and contains a matching MAC using the same secret.
*
* @param token - The base64-encoded encrypted blob to validate.
* @returns `true` if the MAC is valid, `false` otherwise.
*/
isValid(token: string): boolean;
/**
* * Decrypts a previously encrypted token.
* - Throws an error if the tag does not match or the token is malformed.
*
* @param token - The base64-encoded token produced by `encrypt`.
* @returns The decrypted plaintext string.
*/
decrypt(token: string): string;
}