cipher-kit 2.1.3 → 3.0.0

package/dist/export-C0_UEEg8.d.ts

@@ -0,0 +1,396 @@
+import { i as DIGEST_ALGORITHMS, j as ENCRYPTION_ALGORITHMS, c as Encoding, a as CreateSecretKeyOptions, D as DecryptOptions, d as EncryptOptions, H as HashOptions, g as HashPasswordOptions, R as Result, V as VerifyPasswordOptions } from './validate-vDTesb-X.js';
+import { Buffer } from 'node:buffer';
+import nodeCrypto from 'node:crypto';
+
+declare const __brand: unique symbol;
+type NodeSecretKey = {
+    readonly platform: "node";
+    readonly digest: keyof typeof DIGEST_ALGORITHMS;
+    readonly algorithm: keyof typeof ENCRYPTION_ALGORITHMS;
+    readonly key: nodeCrypto.KeyObject;
+    readonly injected: (typeof ENCRYPTION_ALGORITHMS)[keyof typeof ENCRYPTION_ALGORITHMS];
+} & {
+    readonly [__brand]: "secretKey-node";
+};
+
+/**
+ * Checks whether a value is a `NodeSecretKey` for the Node.js platform.
+ *
+ * @param x - The value to check.
+ * @returns `true` if `x` is a `NodeSecretKey`.
+ *
+ * @example
+ * ```ts
+ * isNodeSecretKey(nodeKey); // true
+ * isNodeSecretKey({});      // false
+ * ```
+ */
+declare function isNodeSecretKey(x: unknown): x is NodeSecretKey;
+/**
+ * Generates a UUID (v4) (non-throwing).
+ *
+ * @returns `Result<string>` with the UUID or error.
+ * @see {@link generateUuid} For full parameter/behavior docs.
+ */
+declare function tryGenerateUuid(): Result<string>;
+/**
+ * Generates a cryptographically random UUID (v4).
+ *
+ * @returns A UUID string.
+ * @throws {Error} If UUID generation fails.
+ *
+ * @example
+ * ```ts
+ * const uuid = generateUuid();
+ * ```
+ *
+ * @see {@link tryGenerateUuid} Non-throwing variant returning `Result<string>`.
+ */
+declare function generateUuid(): string;
+/**
+ * Derives a `NodeSecretKey` from a high-entropy secret (non-throwing).
+ *
+ * @returns `Result<{ result: NodeSecretKey }>` with the derived key or error.
+ * @see {@link createSecretKey} For full parameter/behavior docs.
+ */
+declare function tryCreateSecretKey(secret: string, options?: CreateSecretKeyOptions): Result<{
+    result: NodeSecretKey;
+}>;
+/**
+ * Derives a `NodeSecretKey` from a high-entropy secret for encryption/decryption.
+ *
+ * @remarks
+ * Uses HKDF to derive a symmetric key from the input string.
+ *
+ * @param secret - High-entropy secret (min 8 chars). For human-chosen passwords, use {@link hashPassword} instead.
+ * @param options - Key derivation options.
+ * @returns The derived `NodeSecretKey`.
+ * @throws {Error} If key derivation fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-32-char-high-entropy-secret!!");
+ * ```
+ *
+ * @see {@link tryCreateSecretKey} Non-throwing variant returning `Result`.
+ */
+declare function createSecretKey(secret: string, options?: CreateSecretKeyOptions): NodeSecretKey;
+/**
+ * Encrypts a UTF-8 string (non-throwing).
+ *
+ * @returns `Result<string>` with the ciphertext or error.
+ * @see {@link encrypt} For full parameter/behavior docs.
+ */
+declare function tryEncrypt(data: string, secretKey: NodeSecretKey, options?: EncryptOptions): Result<string>;
+/**
+ * Encrypts a UTF-8 string using the provided `NodeSecretKey`.
+ *
+ * @remarks
+ * Output format: `"iv.cipher.tag."` (three dot-separated base64url segments plus trailing dot).
+ * Cross-platform compatible — data encrypted on Node can be decrypted on Web and vice versa.
+ * AES-GCM uses random 96-bit IVs. Rotate keys before ~2^32 encryptions with the same key to avoid nonce collision.
+ *
+ * @param data - UTF-8 string to encrypt. Must be a non-empty string (whitespace-only strings are rejected).
+ * @param secretKey - The `NodeSecretKey` used for encryption.
+ * @param options - Encryption options.
+ * @returns The encrypted string.
+ * @throws {Error} If the input or key is invalid, or encryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const encrypted = encrypt("Hello, World!", secretKey);
+ * ```
+ *
+ * @see {@link tryEncrypt} Non-throwing variant returning `Result<string>`.
+ */
+declare function encrypt(data: string, secretKey: NodeSecretKey, options?: EncryptOptions): string;
+/**
+ * Decrypts a ciphertext string (non-throwing).
+ *
+ * @returns `Result<string>` with the plaintext or error.
+ * @see {@link decrypt} For full parameter/behavior docs.
+ */
+declare function tryDecrypt(encrypted: string, secretKey: NodeSecretKey, options?: DecryptOptions): Result<string>;
+/**
+ * Decrypts a ciphertext string using the provided `NodeSecretKey`.
+ *
+ * @remarks
+ * Expects input in the format `"iv.cipher.tag."`.
+ * Cross-platform compatible — data encrypted on Web can be decrypted on Node and vice versa.
+ *
+ * @param encrypted - The encrypted string to decrypt.
+ * @param secretKey - The `NodeSecretKey` used for decryption.
+ * @param options - Decryption options.
+ * @returns The decrypted UTF-8 string.
+ * @throws {Error} If the input or key is invalid, or decryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const encrypted = encrypt("Hello, World!", secretKey);
+ * const decrypted = decrypt(encrypted, secretKey); // "Hello, World!"
+ * ```
+ *
+ * @see {@link tryDecrypt} Non-throwing variant returning `Result<string>`.
+ */
+declare function decrypt(encrypted: string, secretKey: NodeSecretKey, options?: DecryptOptions): string;
+/**
+ * Encrypts a plain object (non-throwing).
+ *
+ * @returns `Result<string>` with the ciphertext or error.
+ * @see {@link encryptObj} For full parameter/behavior docs.
+ */
+declare function tryEncryptObj<T extends object = Record<string, unknown>>(obj: T, secretKey: NodeSecretKey, options?: EncryptOptions): Result<string>;
+/**
+ * Encrypts a plain object using the provided `NodeSecretKey`.
+ *
+ * @remarks
+ * Only plain objects (POJOs) are accepted; class instances, Maps, Sets, etc. are rejected.
+ * Output format: `"iv.cipher.tag."`.
+ *
+ * @param obj - Plain object to encrypt.
+ * @param secretKey - The `NodeSecretKey` used for encryption.
+ * @param options - Encryption options.
+ * @returns The encrypted string.
+ * @throws {Error} If the input or key is invalid, or encryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const encrypted = encryptObj({ a: 1 }, secretKey);
+ * ```
+ *
+ * @see {@link tryEncryptObj} Non-throwing variant returning `Result<string>`.
+ */
+declare function encryptObj<T extends object = Record<string, unknown>>(obj: T, secretKey: NodeSecretKey, options?: EncryptOptions): string;
+/**
+ * Decrypts an encrypted JSON string into a plain object (non-throwing).
+ *
+ * @returns `Result<{ result: T }>` with the object or error.
+ * @see {@link decryptObj} For full parameter/behavior docs.
+ */
+declare function tryDecryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: NodeSecretKey, options?: DecryptOptions): Result<{
+    result: T;
+}>;
+/**
+ * Decrypts an encrypted JSON string into a plain object.
+ *
+ * @remarks
+ * Expects input in the format `"iv.cipher.tag."`.
+ *
+ * @param encrypted - The encrypted string.
+ * @param secretKey - The `NodeSecretKey` used for decryption.
+ * @param options - Decryption options.
+ * @returns The decrypted object.
+ * @throws {Error} If decryption or JSON parsing fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const encrypted = encryptObj({ a: 1 }, secretKey);
+ * const obj = decryptObj<{ a: number }>(encrypted, secretKey); // obj.a === 1
+ * ```
+ *
+ * @see {@link tryDecryptObj} Non-throwing variant returning `Result`.
+ */
+declare function decryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: NodeSecretKey, options?: DecryptOptions): T;
+/**
+ * Hashes a UTF-8 string (non-throwing).
+ *
+ * @returns `Result<string>` with the hash or error.
+ * @see {@link hash} For full parameter/behavior docs.
+ */
+declare function tryHash(data: string, options?: HashOptions): Result<string>;
+/**
+ * Hashes a UTF-8 string using the specified digest algorithm.
+ *
+ * @param data - The input string to hash.
+ * @param options - Hash options.
+ * @returns The hashed string.
+ * @throws {Error} If input is invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const hashed = hash("my data");
+ * ```
+ *
+ * @see {@link tryHash} Non-throwing variant returning `Result<string>`.
+ */
+declare function hash(data: string, options?: HashOptions): string;
+/**
+ * Hashes a password using PBKDF2 (non-throwing).
+ *
+ * @returns `Result<{ result: string; salt: string }>` with the hash/salt or error.
+ * @see {@link hashPassword} For full parameter/behavior docs.
+ */
+declare function tryHashPassword(password: string, options?: HashPasswordOptions): Result<{
+    result: string;
+    salt: string;
+}>;
+/**
+ * Hashes a password using PBKDF2.
+ *
+ * @remarks
+ * Defaults: `sha512`, 320 000 iterations, 64-byte key, 16-byte random salt.
+ *
+ * **Performance note:** Uses synchronous `pbkdf2Sync` which blocks the event loop
+ * (~100-300 ms at default iterations). For server-side use under load, prefer the
+ * Web Crypto API (async) via `webKit.hashPassword` instead.
+ *
+ * @param password - The password to hash.
+ * @param options - Password hashing options.
+ * @returns `{ result, salt }` for storage.
+ * @throws {Error} If inputs are invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const { result, salt } = hashPassword("my-password");
+ * ```
+ *
+ * @see {@link tryHashPassword} Non-throwing variant returning `Result`.
+ */
+declare function hashPassword(password: string, options?: HashPasswordOptions): {
+    result: string;
+    salt: string;
+};
+/**
+ * Verifies a password against a stored PBKDF2 hash (non-throwing).
+ *
+ * @returns `Result<boolean>` — `true` if the password matches, `false` if not, or an error for invalid inputs/options.
+ * @see {@link verifyPassword} For full parameter/behavior docs.
+ */
+declare function tryVerifyPassword(password: string, hashedPassword: string, salt: string, options?: VerifyPasswordOptions): Result<boolean>;
+/**
+ * Verifies a password against a stored PBKDF2 hash.
+ *
+ * @remarks
+ * Re-derives the key with the same parameters and compares in constant time to prevent timing attacks.
+ * Throws for invalid inputs/options (bad encoding, wrong parameters, non-decodable salt/hash).
+ * Returns `false` for password mismatch or length-mismatched hash.
+ *
+ * **Performance note:** Uses synchronous `pbkdf2Sync` which blocks the event loop
+ * (~100-300 ms at default iterations). For server-side use under load, prefer the
+ * Web Crypto API (async) via `webKit.verifyPassword` instead.
+ *
+ * @param password - The plain password to verify.
+ * @param hashedPassword - The stored hash (encoded).
+ * @param salt - The stored salt (encoded).
+ * @param options - Verification options (must match the parameters used to hash).
+ * @returns `true` if the password matches, otherwise `false`.
+ * @throws {Error} If verification input/options are invalid.
+ *
+ * @example
+ * ```ts
+ * const { result, salt } = hashPassword("my-password");
+ * verifyPassword("my-password", result, salt);    // true
+ * verifyPassword("wrong-password", result, salt); // false
+ * ```
+ *
+ * @see {@link tryVerifyPassword} Non-throwing variant returning `Result<boolean>`.
+ */
+declare function verifyPassword(password: string, hashedPassword: string, salt: string, options?: VerifyPasswordOptions): boolean;
+/**
+ * Converts a string to a `Buffer` (non-throwing).
+ *
+ * @returns `Result<{ result: Buffer }>` with the buffer or error.
+ * @see {@link convertStrToBytes} For full parameter/behavior docs.
+ */
+declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): Result<{
+    result: Buffer;
+}>;
+/**
+ * Converts a string to a Node.js `Buffer` using the specified encoding.
+ *
+ * @param data - The input string to convert.
+ * @param inputEncoding - Source encoding (default: `'utf8'`).
+ * @returns A `Buffer` containing the bytes.
+ * @throws {Error} If input is invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8");
+ * ```
+ *
+ * @see {@link tryConvertStrToBytes} Non-throwing variant returning `Result`.
+ */
+declare function convertStrToBytes(data: string, inputEncoding?: Encoding): Buffer;
+/**
+ * Converts a `Buffer` to a string (non-throwing).
+ *
+ * @returns `Result<string>` with the encoded string or error.
+ * @see {@link convertBytesToStr} For full parameter/behavior docs.
+ */
+declare function tryConvertBytesToStr(data: Buffer, outputEncoding?: Encoding): Result<string>;
+/**
+ * Converts a Node.js `Buffer` to a string using the specified encoding.
+ *
+ * @param data - The `Buffer` to convert.
+ * @param outputEncoding - Target encoding (default: `'utf8'`).
+ * @returns The encoded string.
+ * @throws {Error} If input is invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8");
+ * const str = convertBytesToStr(bytes, "utf8"); // "Hello"
+ * ```
+ *
+ * @see {@link tryConvertBytesToStr} Non-throwing variant returning `Result<string>`.
+ */
+declare function convertBytesToStr(data: Buffer, outputEncoding?: Encoding): string;
+/**
+ * Converts text between encodings (non-throwing).
+ *
+ * @returns `Result<string>` with the re-encoded string or error.
+ * @see {@link convertEncoding} For full parameter/behavior docs.
+ */
+declare function tryConvertEncoding(data: string, from: Encoding, to: Encoding): Result<string>;
+/**
+ * Converts text between encodings.
+ *
+ * @param data - The input string.
+ * @param from - Current encoding of `data`.
+ * @param to - Target encoding.
+ * @returns The re-encoded string.
+ * @throws {Error} If encodings are invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const encoded = convertEncoding("Hello", "utf8", "base64url");
+ * ```
+ *
+ * @see {@link tryConvertEncoding} Non-throwing variant returning `Result<string>`.
+ */
+declare function convertEncoding(data: string, from: Encoding, to: Encoding): string;
+
+declare const nodeCryptoKit_convertBytesToStr: typeof convertBytesToStr;
+declare const nodeCryptoKit_convertEncoding: typeof convertEncoding;
+declare const nodeCryptoKit_convertStrToBytes: typeof convertStrToBytes;
+declare const nodeCryptoKit_createSecretKey: typeof createSecretKey;
+declare const nodeCryptoKit_decrypt: typeof decrypt;
+declare const nodeCryptoKit_decryptObj: typeof decryptObj;
+declare const nodeCryptoKit_encrypt: typeof encrypt;
+declare const nodeCryptoKit_encryptObj: typeof encryptObj;
+declare const nodeCryptoKit_generateUuid: typeof generateUuid;
+declare const nodeCryptoKit_hash: typeof hash;
+declare const nodeCryptoKit_hashPassword: typeof hashPassword;
+declare const nodeCryptoKit_isNodeSecretKey: typeof isNodeSecretKey;
+declare const nodeCryptoKit_tryConvertBytesToStr: typeof tryConvertBytesToStr;
+declare const nodeCryptoKit_tryConvertEncoding: typeof tryConvertEncoding;
+declare const nodeCryptoKit_tryConvertStrToBytes: typeof tryConvertStrToBytes;
+declare const nodeCryptoKit_tryCreateSecretKey: typeof tryCreateSecretKey;
+declare const nodeCryptoKit_tryDecrypt: typeof tryDecrypt;
+declare const nodeCryptoKit_tryDecryptObj: typeof tryDecryptObj;
+declare const nodeCryptoKit_tryEncrypt: typeof tryEncrypt;
+declare const nodeCryptoKit_tryEncryptObj: typeof tryEncryptObj;
+declare const nodeCryptoKit_tryGenerateUuid: typeof tryGenerateUuid;
+declare const nodeCryptoKit_tryHash: typeof tryHash;
+declare const nodeCryptoKit_tryHashPassword: typeof tryHashPassword;
+declare const nodeCryptoKit_tryVerifyPassword: typeof tryVerifyPassword;
+declare const nodeCryptoKit_verifyPassword: typeof verifyPassword;
+declare namespace nodeCryptoKit {
+  export { nodeCryptoKit_convertBytesToStr as convertBytesToStr, nodeCryptoKit_convertEncoding as convertEncoding, nodeCryptoKit_convertStrToBytes as convertStrToBytes, nodeCryptoKit_createSecretKey as createSecretKey, nodeCryptoKit_decrypt as decrypt, nodeCryptoKit_decryptObj as decryptObj, nodeCryptoKit_encrypt as encrypt, nodeCryptoKit_encryptObj as encryptObj, nodeCryptoKit_generateUuid as generateUuid, nodeCryptoKit_hash as hash, nodeCryptoKit_hashPassword as hashPassword, nodeCryptoKit_isNodeSecretKey as isNodeSecretKey, nodeCryptoKit_tryConvertBytesToStr as tryConvertBytesToStr, nodeCryptoKit_tryConvertEncoding as tryConvertEncoding, nodeCryptoKit_tryConvertStrToBytes as tryConvertStrToBytes, nodeCryptoKit_tryCreateSecretKey as tryCreateSecretKey, nodeCryptoKit_tryDecrypt as tryDecrypt, nodeCryptoKit_tryDecryptObj as tryDecryptObj, nodeCryptoKit_tryEncrypt as tryEncrypt, nodeCryptoKit_tryEncryptObj as tryEncryptObj, nodeCryptoKit_tryGenerateUuid as tryGenerateUuid, nodeCryptoKit_tryHash as tryHash, nodeCryptoKit_tryHashPassword as tryHashPassword, nodeCryptoKit_tryVerifyPassword as tryVerifyPassword, nodeCryptoKit_verifyPassword as verifyPassword };
+}
+
+export { type NodeSecretKey as N, convertEncoding as a, convertStrToBytes as b, convertBytesToStr as c, createSecretKey as d, decrypt as e, decryptObj as f, encrypt as g, encryptObj as h, generateUuid as i, hash as j, hashPassword as k, isNodeSecretKey as l, tryConvertEncoding as m, nodeCryptoKit as n, tryConvertStrToBytes as o, tryCreateSecretKey as p, tryDecrypt as q, tryDecryptObj as r, tryEncrypt as s, tryConvertBytesToStr as t, tryEncryptObj as u, tryGenerateUuid as v, tryHash as w, tryHashPassword as x, tryVerifyPassword as y, verifyPassword as z };