timebasedcipher/dist/index.d.ts

Time-based key generation and AES encryption/decryption SDK

/**
 * Generate a time-based rotating key (SHA256 hash of sharedSecret + current interval).
 *
 * The key is derived from:
 *   SHA256(`${secretInput}:${timeSlot}`)
 * where:
 *   timeSlot = floor(Date.now() / (interval * 1000) + 1000)
 *
 * When `isJwt` is true:
 *   - `sharedSecretOrJwt` is treated as a JWT string
 *   - The JWT payload is decoded
 *   - The `exp` claim (if present) is checked against current time
 *   - If the JWT is expired, an error is thrown and no key is generated
 *   - The *raw JWT string* is still used as the secret input for key derivation
 *
 * @param sharedSecretOrJwt - A pre-shared secret string, or a JWT when `isJwt` is true.
 * @param interval - The rotation interval in seconds. The timeSlot calculation
 *                   is based on this value, so both sides must use the same interval.
 * @param isJwt - Optional flag (default: false). When true, `sharedSecretOrJwt` is
 *                treated as a JWT and its `exp` is validated before deriving the key.
 * @returns A 64-character hexadecimal SHA-256 hash string to be used as an AES-256 key.
 * @throws If `isJwt` is true and the JWT is malformed or expired.
 */
export declare const generateKey: (sharedSecretOrJwt: string, interval: number, isJwt?: boolean) => string;
/**
 * Encrypt an arbitrary JavaScript value using AES-256-CBC with a random IV.
 *
 * The function:
 *   - JSON stringifies the input `data`
 *   - Uses the provided hex-encoded key as AES-256 key material
 *   - Generates a random 16-byte IV
 *   - Encrypts using AES-256-CBC
 *   - Returns a concatenated string in the format: "cipherHex:ivHex"
 *
 * @param data - Any serializable JavaScript value (e.g. object, array, string) to encrypt.
 * @param encryptionKeyHex - A 64-character hex string representing a 32-byte key
 *                           (typically the output of {@link generateKey}).
 * @returns A string in the format `"cipherHex:ivHex"` where both parts are hex-encoded.
 * @throws If encryption fails or JSON serialization fails.
 */
export declare const encrypt: (data: any, encryptionKeyHex: string) => string;
/**
 * Decrypt an AES-256-CBC ciphertext string produced by {@link encrypt}.
 *
 * The function expects the input to be in the format:
 *   "cipherHex:ivHex"
 * where:
 *   - cipherHex is the hex-encoded ciphertext
 *   - ivHex is the hex-encoded 16-byte IV
 *
 * It will:
 *   - Split and parse the hex components
 *   - Decrypt using AES-256-CBC with the provided key
 *   - Parse the resulting UTF-8 JSON back into the original JavaScript value
 *
 * @param cipherText - The ciphertext string in the format `"cipherHex:ivHex"`.
 * @param encryptionKeyHex - A 64-character hex string representing a 32-byte key
 *                           (must match the key used for encryption).
 * @returns The decrypted JavaScript value (e.g. object, array, string).
 * @throws If the format is invalid, decryption fails, or the decrypted output is empty/invalid JSON.
 */
export declare const decrypt: (cipherText: string, encryptionKeyHex: string) => unknown;