cipher-kit 2.1.3 → 3.0.0

package/dist/export-B-3CCZIO.d.cts

@@ -0,0 +1,389 @@
+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.cjs';
+
+declare const __brand: unique symbol;
+type WebSecretKey = {
+    readonly platform: "web";
+    readonly digest: keyof typeof DIGEST_ALGORITHMS;
+    readonly algorithm: keyof typeof ENCRYPTION_ALGORITHMS;
+    readonly key: CryptoKey;
+    readonly injected: (typeof ENCRYPTION_ALGORITHMS)[keyof typeof ENCRYPTION_ALGORITHMS];
+} & {
+    readonly [__brand]: "secretKey-web";
+};
+
+/**
+ * Checks whether a value is a `WebSecretKey` for the Web Crypto platform.
+ *
+ * @param x - The value to check.
+ * @returns `true` if `x` is a `WebSecretKey`.
+ *
+ * @example
+ * ```ts
+ * isWebSecretKey(webKey); // true
+ * isWebSecretKey({});     // false
+ * ```
+ */
+declare function isWebSecretKey(x: unknown): x is WebSecretKey;
+/**
+ * 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 `WebSecretKey` from a high-entropy secret (non-throwing).
+ *
+ * @returns `Promise<Result<{ result: WebSecretKey }>>` with the derived key or error.
+ * @see {@link createSecretKey} For full parameter/behavior docs.
+ */
+declare function tryCreateSecretKey(secret: string, options?: CreateSecretKeyOptions): Promise<Result<{
+    result: WebSecretKey;
+}>>;
+/**
+ * Derives a `WebSecretKey` from a high-entropy secret for encryption/decryption.
+ *
+ * @remarks
+ * Uses HKDF via the Web Crypto API 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 `WebSecretKey`.
+ * @throws {Error} If key derivation fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-32-char-high-entropy-secret!!");
+ * ```
+ *
+ * @see {@link tryCreateSecretKey} Non-throwing variant returning `Result`.
+ */
+declare function createSecretKey(secret: string, options?: CreateSecretKeyOptions): Promise<WebSecretKey>;
+/**
+ * Encrypts a UTF-8 string (non-throwing).
+ *
+ * @returns `Promise<Result<string>>` with the ciphertext or error.
+ * @see {@link encrypt} For full parameter/behavior docs.
+ */
+declare function tryEncrypt(data: string, secretKey: WebSecretKey, options?: EncryptOptions): Promise<Result<string>>;
+/**
+ * Encrypts a UTF-8 string using the provided `WebSecretKey`.
+ *
+ * @remarks
+ * Output format: `"iv.cipher.tag."` (three dot-separated base64url segments plus trailing dot).
+ * Cross-platform compatible — data encrypted on Web can be decrypted on Node 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 `WebSecretKey` 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 = await createSecretKey("my-secret");
+ * const encrypted = await encrypt("Hello, World!", secretKey);
+ * ```
+ *
+ * @see {@link tryEncrypt} Non-throwing variant returning `Result<string>`.
+ */
+declare function encrypt(data: string, secretKey: WebSecretKey, options?: EncryptOptions): Promise<string>;
+/**
+ * Decrypts a ciphertext string (non-throwing).
+ *
+ * @returns `Promise<Result<string>>` with the plaintext or error.
+ * @see {@link decrypt} For full parameter/behavior docs.
+ */
+declare function tryDecrypt(encrypted: string, secretKey: WebSecretKey, options?: DecryptOptions): Promise<Result<string>>;
+/**
+ * Decrypts a ciphertext string using the provided `WebSecretKey`.
+ *
+ * @remarks
+ * Expects input in the format `"iv.cipher.tag."`.
+ * Cross-platform compatible — data encrypted on Node can be decrypted on Web and vice versa.
+ *
+ * @param encrypted - The encrypted string to decrypt.
+ * @param secretKey - The `WebSecretKey` 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 = await createSecretKey("my-secret");
+ * const encrypted = await encrypt("Hello, World!", secretKey);
+ * const decrypted = await decrypt(encrypted, secretKey); // "Hello, World!"
+ * ```
+ *
+ * @see {@link tryDecrypt} Non-throwing variant returning `Result<string>`.
+ */
+declare function decrypt(encrypted: string, secretKey: WebSecretKey, options?: DecryptOptions): Promise<string>;
+/**
+ * Encrypts a plain object (non-throwing).
+ *
+ * @returns `Promise<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: WebSecretKey, options?: EncryptOptions): Promise<Result<string>>;
+/**
+ * Encrypts a plain object using the provided `WebSecretKey`.
+ *
+ * @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 `WebSecretKey` 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 = await createSecretKey("my-secret");
+ * const encrypted = await 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: WebSecretKey, options?: EncryptOptions): Promise<string>;
+/**
+ * Decrypts an encrypted JSON string into a plain object (non-throwing).
+ *
+ * @returns `Promise<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: WebSecretKey, options?: DecryptOptions): Promise<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 `WebSecretKey` used for decryption.
+ * @param options - Decryption options.
+ * @returns The decrypted object.
+ * @throws {Error} If decryption or JSON parsing fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encryptObj({ a: 1 }, secretKey);
+ * const obj = await 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: WebSecretKey, options?: DecryptOptions): Promise<T>;
+/**
+ * Hashes a UTF-8 string (non-throwing).
+ *
+ * @returns `Promise<Result<string>>` with the hash or error.
+ * @see {@link hash} For full parameter/behavior docs.
+ */
+declare function tryHash(data: string, options?: HashOptions): Promise<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 = await hash("my data");
+ * ```
+ *
+ * @see {@link tryHash} Non-throwing variant returning `Result<string>`.
+ */
+declare function hash(data: string, options?: HashOptions): Promise<string>;
+/**
+ * Hashes a password using PBKDF2 (non-throwing).
+ *
+ * @returns `Promise<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): Promise<Result<{
+    result: string;
+    salt: string;
+}>>;
+/**
+ * Hashes a password using PBKDF2.
+ *
+ * @remarks
+ * Defaults: `sha512`, 320 000 iterations, 64-byte key, 16-byte random salt.
+ *
+ * @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 } = await hashPassword("my-password");
+ * ```
+ *
+ * @see {@link tryHashPassword} Non-throwing variant returning `Result`.
+ */
+declare function hashPassword(password: string, options?: HashPasswordOptions): Promise<{
+    result: string;
+    salt: string;
+}>;
+/**
+ * Verifies a password against a stored PBKDF2 hash (non-throwing).
+ *
+ * @returns `Promise<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): Promise<Result<boolean>>;
+/**
+ * Verifies a password against a stored PBKDF2 hash.
+ *
+ * @remarks
+ * Re-derives the key with the same parameters and compares using a full-loop XOR pattern.
+ * This is best-effort constant-time; JS JIT optimization may introduce timing variation.
+ * The Web Crypto API does not expose a `timingSafeEqual` equivalent.
+ * For timing-critical deployments, prefer the Node implementation which uses `crypto.timingSafeEqual`.
+ * Throws for invalid inputs/options (bad encoding, wrong parameters, non-decodable salt/hash).
+ * Returns `false` for password mismatch or length-mismatched hash.
+ *
+ * @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 } = await hashPassword("my-password");
+ * await verifyPassword("my-password", result, salt);    // true
+ * await 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): Promise<boolean>;
+/**
+ * Converts a string to a `Uint8Array` (non-throwing).
+ *
+ * @returns `Result<{ result: Uint8Array<ArrayBuffer> }>` with the bytes or error.
+ * @see {@link convertStrToBytes} For full parameter/behavior docs.
+ */
+declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): Result<{
+    result: Uint8Array<ArrayBuffer>;
+}>;
+/**
+ * Converts a string to a `Uint8Array` using the specified encoding.
+ *
+ * @param data - The input string to convert.
+ * @param inputEncoding - Source encoding (default: `'utf8'`).
+ * @returns A `Uint8Array` 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): Uint8Array<ArrayBuffer>;
+/**
+ * Converts a `Uint8Array` or `ArrayBuffer` 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: Uint8Array | ArrayBuffer, outputEncoding?: Encoding): Result<string>;
+/**
+ * Converts a `Uint8Array` or `ArrayBuffer` to a string using the specified encoding.
+ *
+ * @param data - The bytes 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: Uint8Array | ArrayBuffer, 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 webCryptoKit_convertBytesToStr: typeof convertBytesToStr;
+declare const webCryptoKit_convertEncoding: typeof convertEncoding;
+declare const webCryptoKit_convertStrToBytes: typeof convertStrToBytes;
+declare const webCryptoKit_createSecretKey: typeof createSecretKey;
+declare const webCryptoKit_decrypt: typeof decrypt;
+declare const webCryptoKit_decryptObj: typeof decryptObj;
+declare const webCryptoKit_encrypt: typeof encrypt;
+declare const webCryptoKit_encryptObj: typeof encryptObj;
+declare const webCryptoKit_generateUuid: typeof generateUuid;
+declare const webCryptoKit_hash: typeof hash;
+declare const webCryptoKit_hashPassword: typeof hashPassword;
+declare const webCryptoKit_isWebSecretKey: typeof isWebSecretKey;
+declare const webCryptoKit_tryConvertBytesToStr: typeof tryConvertBytesToStr;
+declare const webCryptoKit_tryConvertEncoding: typeof tryConvertEncoding;
+declare const webCryptoKit_tryConvertStrToBytes: typeof tryConvertStrToBytes;
+declare const webCryptoKit_tryCreateSecretKey: typeof tryCreateSecretKey;
+declare const webCryptoKit_tryDecrypt: typeof tryDecrypt;
+declare const webCryptoKit_tryDecryptObj: typeof tryDecryptObj;
+declare const webCryptoKit_tryEncrypt: typeof tryEncrypt;
+declare const webCryptoKit_tryEncryptObj: typeof tryEncryptObj;
+declare const webCryptoKit_tryGenerateUuid: typeof tryGenerateUuid;
+declare const webCryptoKit_tryHash: typeof tryHash;
+declare const webCryptoKit_tryHashPassword: typeof tryHashPassword;
+declare const webCryptoKit_tryVerifyPassword: typeof tryVerifyPassword;
+declare const webCryptoKit_verifyPassword: typeof verifyPassword;
+declare namespace webCryptoKit {
+  export { webCryptoKit_convertBytesToStr as convertBytesToStr, webCryptoKit_convertEncoding as convertEncoding, webCryptoKit_convertStrToBytes as convertStrToBytes, webCryptoKit_createSecretKey as createSecretKey, webCryptoKit_decrypt as decrypt, webCryptoKit_decryptObj as decryptObj, webCryptoKit_encrypt as encrypt, webCryptoKit_encryptObj as encryptObj, webCryptoKit_generateUuid as generateUuid, webCryptoKit_hash as hash, webCryptoKit_hashPassword as hashPassword, webCryptoKit_isWebSecretKey as isWebSecretKey, webCryptoKit_tryConvertBytesToStr as tryConvertBytesToStr, webCryptoKit_tryConvertEncoding as tryConvertEncoding, webCryptoKit_tryConvertStrToBytes as tryConvertStrToBytes, webCryptoKit_tryCreateSecretKey as tryCreateSecretKey, webCryptoKit_tryDecrypt as tryDecrypt, webCryptoKit_tryDecryptObj as tryDecryptObj, webCryptoKit_tryEncrypt as tryEncrypt, webCryptoKit_tryEncryptObj as tryEncryptObj, webCryptoKit_tryGenerateUuid as tryGenerateUuid, webCryptoKit_tryHash as tryHash, webCryptoKit_tryHashPassword as tryHashPassword, webCryptoKit_tryVerifyPassword as tryVerifyPassword, webCryptoKit_verifyPassword as verifyPassword };
+}
+
+export { type WebSecretKey as W, 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, isWebSecretKey as l, tryConvertEncoding as m, tryConvertStrToBytes as n, tryCreateSecretKey as o, tryDecrypt as p, tryDecryptObj as q, tryEncrypt as r, tryEncryptObj as s, tryConvertBytesToStr as t, tryGenerateUuid as u, tryHash as v, webCryptoKit as w, tryHashPassword as x, tryVerifyPassword as y, verifyPassword as z };