@nodesuite/crypto/dist/index.d.ts

Encryption and decryption library.

import { webcrypto } from 'node:crypto';

/**
 * Return type from an encryption call.
 *
 * @public
 */
interface Encrypted {
    iv: Uint8Array;
    key: CryptoKey;
    data: BufferSource;
}
/**
 * Return type from a decryption call.
 *
 * @public
 */
interface Decrypted<T> {
    iv: Uint8Array;
    key: CryptoKey;
    data: T;
}
/**
 * Params for an encryption call.
 *
 * @public
 */
interface Encrypt {
    iv?: Uint8Array;
    key: CryptoKey;
    data: string | object | Uint8Array;
}
/**
 * Type guard to test if a value is a valid buffer.
 *
 * @param value - Unknown value to test.
 *
 * @internal
 */
declare const isBuffer: (value: unknown) => value is Uint8Array;
/**
 * Node `webcrypto` AesGcmParams type.
 *
 * @see https://nodejs.org/api/webcrypto.html
 *
 * @public
 */
type AesGcmParams = webcrypto.AesGcmParams;
/**
 * Node `webcrypto` CryptoKey type.
 *
 * @see https://nodejs.org/api/webcrypto.html
 *
 * @public
 */
type CryptoKey = webcrypto.CryptoKey;
/**
 * Node `webcrypto` BufferSource type.
 *
 * @see https://nodejs.org/api/webcrypto.html
 *
 * @public
 */
type BufferSource = webcrypto.BufferSource;
/**
 * Node `webcrypto` AesKeyAlgorithm type.
 *
 * @see https://nodejs.org/api/webcrypto.html
 *
 * @public
 */
type AesKeyAlgorithm = webcrypto.AesKeyAlgorithm;
/**
 * Node `webcrypto` JsonWebKey type.
 *
 * @see https://nodejs.org/api/webcrypto.html
 *
 * @public
 */
type JsonWebKey = webcrypto.JsonWebKey;

/**
 * Encrypts a data payload.
 *
 * @remarks
 * Always generate a new iv every time, recommended 12-byte length.
 * Tag length options are 32, 64, 96, 104, 112, 120, 128 (default).
 *
 * @param data - Payload to encrypt. Recommend object, but will accept simple strings as well.
 * @param key - Private key to use for encryption.
 * @param iv - Unique initialization vector.
 *
 * @public
 */
declare const encrypt: ({ key, iv, data }: Encrypt) => Promise<Encrypted>;
/**
 * Decrypts a message payload.
 *
 * @remarks
 * Always generate a new iv every time, recommended 12-byte length.
 * Tag length options are 32, 64, 96, 104, 112, 120, 128 (default).
 *
 * @param data - Payload to decrypt.
 * @param key - Private key to use for encryption.
 * @param iv - Unique initialization vector.
 *
 * @public
 */
declare const decrypt: <T>({ key, iv, data }: Encrypted) => Promise<Decrypted<T>>;

/**
 * Encodes data to Unit8Array for encryption.
 *
 * @remarks
 * If value is already encoded, will return original.
 *
 * @param data - Payload to encode.
 *
 * @public
 */
declare const encode: (data: object | string | Uint8Array) => Uint8Array;
/**
 * Decodes data from Unit8Array payload produced by decryption.
 *
 * @param data - Uint8Array payload to decode.
 *
 * @public
 */
declare const decode: <T>(data: Uint8Array | ArrayBuffer) => T;

/**
 * Generates a random IV for cases requiring regular AES security.
 *
 * @param length - Length of uint8 array to generate, recommend 12-byte length.
 *
 * @public
 */
declare const generateSecureIv: (length?: number) => Uint8Array;
/**
 * Generates a consistent IV using a persistent seed.
 *
 * @remarks
 * In normal circumstances you would never reuse and IV.
 * However, in this case we do not require high security, just easy reversibility.
 *
 * @param seed - Persistent token to produce iv from.
 * @param length - Length of desired uint8 array.
 *
 * @public
 */
declare const generateInsecureIv: (seed: string, length?: number) => Uint8Array;

/**
 * Generates a private key object.
 *
 * @internal
 */
declare const generateKey: () => Promise<CryptoKey>;
/**
 * Generates a private key and exports as json web key.
 *
 * @internal
 */
declare const generateJsonWebKey: () => Promise<JsonWebKey>;
/**
 * Loads existing private key.
 *
 * @remarks
 * Key can be provided as a full json web key, or alternatively the unique `k` value.
 *
 * @param privateKey - One-time generated private encryption key.
 *
 * @internal
 */
declare const importJsonWebKey: (privateKey: string | JsonWebKey) => Promise<CryptoKey>;

export { AesGcmParams, AesKeyAlgorithm, BufferSource, CryptoKey, Decrypted, Encrypt, Encrypted, JsonWebKey, decode, decrypt, encode, encrypt, generateInsecureIv, generateJsonWebKey, generateKey, generateSecureIv, importJsonWebKey, isBuffer };