cipher-kit 2.0.0 → 2.1.0

package/dist/{export-llM6c7Do.d.ts → export-DVERZibl.d.cts}

@@ -1,4 +1,4 @@
-import { S as SecretKey, R as Result, d as CreateSecretKeyOptions, e as EncryptOptions, f as DecryptOptions, H as HashOptions, g as HashPasswordOptions, V as VerifyPasswordOptions, b as Encoding } from './validate-EHuJC5QQ.js';
+import { S as SecretKey, R as Result, d as CreateSecretKeyOptions, e as EncryptOptions, f as DecryptOptions, H as HashOptions, g as HashPasswordOptions, V as VerifyPasswordOptions, b as Encoding } from './validate-B3uHoP8n.cjs';
 
 /**
  * Type guard to check if the provided value is a SecretKey object for Web (Deno, Bun, Cloudflare included) environment.
@@ -8,6 +8,13 @@ import { S as SecretKey, R as Result, d as CreateSecretKeyOptions, e as EncryptO
  *
  * @param x - The value to check.
  * @returns True if the value is a SecretKey object for Web, false otherwise.
+ *
+ * @example
+ * ```ts
+ * isWebSecretKey(webKey); // true
+ * isWebSecretKey(nodeKey); // false
+ * isWebSecretKey({}); // false
+ * ```
  */
 declare function isWebSecretKey(x: unknown): x is SecretKey<"web">;
 /**
@@ -18,6 +25,14 @@ declare function isWebSecretKey(x: unknown): x is SecretKey<"web">;
  * The chance of two pets getting the same name tag is practically zero, and it's very hard to guess!
  *
  * @returns A `Result` containing the UUID string or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryGenerateUuid();
+ *
+ * if (success) console.log(result); // "..." (a UUID string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryGenerateUuid(): Result<string>;
 /**
@@ -29,6 +44,11 @@ declare function tryGenerateUuid(): Result<string>;
  *
  * @returns A UUID string.
  * @throws {Error} If UUID generation fails.
+ *
+ * @example
+ * ```ts
+ * const uuid = generateUuid(); // "..." (a UUID string)
+ * ```
  */
 declare function generateUuid(): string;
 /**
@@ -40,12 +60,20 @@ declare function generateUuid(): string;
  * Imagine you want to create a special key for future use to lock your treasure box (data).
  * So, you stir in some secret ingredients (like salt and info) to make sure your key is one-of-a-kind.
  *
- * @param secret - The input string to derive the `SecretKey` from.
+ * @param secret - The input string to derive the `SecretKey` from, must be at least 8 characters.
  * @param options.algorithm - The encryption algorithm to use (default: `'aes256gcm'`).
  * @param options.digest - The hash algorithm for HKDF (default: `'sha256'`).
  * @param options.salt - A salt string (default: `'cipher-kit-salt'`, must be ≥ 8 chars).
  * @param options.info - An info string (default: `'cipher-kit'`).
  * @returns A `Result` promise containing the derived `SecretKey` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = await tryCreateSecretKey("my-secret");
+ *
+ * if (success) console.log(result); // SecretKey object
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryCreateSecretKey(secret: string, options?: CreateSecretKeyOptions): Promise<Result<{
     result: SecretKey<"web">;
@@ -59,13 +87,18 @@ declare function tryCreateSecretKey(secret: string, options?: CreateSecretKeyOpt
  * Imagine you want to create a special key for future use to lock your treasure box (data).
  * So, you stir in some secret ingredients (like salt and info) to make sure your key is one-of-a-kind.
  *
- * @param secret - The input string to derive the `SecretKey` from.
+ * @param secret - The input string to derive the `SecretKey` from, must be at least 8 characters.
  * @param options.algorithm - The encryption algorithm to use (default: `'aes256gcm'`).
  * @param options.digest - The hash algorithm for HKDF (default: `'sha256'`).
  * @param options.salt - A salt string (default: `'cipher-kit-salt'`, must be ≥ 8 chars).
  * @param options.info - An info string (default: `'cipher-kit'`).
  * @returns A promise of the derived `SecretKey`.
  * @throws {Error} If key derivation fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret"); // SecretKey object
+ * ```
  */
 declare function createSecretKey(secret: string, options?: CreateSecretKeyOptions): Promise<SecretKey<"web">>;
 /**
@@ -79,8 +112,17 @@ declare function createSecretKey(secret: string, options?: CreateSecretKeyOption
  *
  * @param data - A UTF-8 string to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A `Result` promise containing the encrypted string in the specified format or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const {result, error, success} = await tryEncrypt("Hello, World!", secretKey);
+ *
+ * if (success) console.log(result); // "iv.cipherWithTag." (Encrypted string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryEncrypt(data: string, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<Result<string>>;
 /**
@@ -94,9 +136,15 @@ declare function tryEncrypt(data: string, secretKey: SecretKey<"web">, options?:
  *
  * @param data - A UTF-8 string to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A promise with the encrypted string in the specified format.
  * @throws {Error} If the input data or key is invalid, or if encryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encrypt("Hello, World!", secretKey); // "iv.cipherWithTag." (Encrypted string)
+ * ```
  */
 declare function encrypt(data: string, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<string>;
 /**
@@ -110,8 +158,18 @@ declare function encrypt(data: string, secretKey: SecretKey<"web">, options?: En
  *
  * @param encrypted - The input string to decrypt, in the format "iv.cipherWithTag.".
  * @param secretKey - The `SecretKey` object used for decryption.
- * @param options.encoding - The encoding format for the input ciphertext (default: `'base64url'`).
+ * @param options.inputEncoding - The encoding format for the input ciphertext (default: `'base64url'`).
  * @returns A `Result` promise containing the decrypted UTF-8 string or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encrypt("Hello, World!", secretKey);
+ * const {result, error, success} = await tryDecrypt(encrypted, secretKey);
+ *
+ * if (success) console.log(result); // "Hello, World!"
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryDecrypt(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<Result<string>>;
 /**
@@ -125,9 +183,16 @@ declare function tryDecrypt(encrypted: string, secretKey: SecretKey<"web">, opti
  *
  * @param encrypted - The input string to decrypt, in the format "iv.cipherWithTag.".
  * @param secretKey - The `SecretKey` object used for decryption.
- * @param options.encoding - The encoding format for the input ciphertext (default: `'base64url'`).
+ * @param options.inputEncoding - The encoding format for the input ciphertext (default: `'base64url'`).
  * @returns A promise with the decrypted UTF-8 string.
  * @throws {Error} If the input data or key is invalid, or if 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!"
+ * ```
  */
 declare function decrypt(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<string>;
 /**
@@ -142,10 +207,20 @@ declare function decrypt(encrypted: string, secretKey: SecretKey<"web">, options
  * So, you take a picture of your toy box (convert it to JSON), and scramble that with
  * your special key, creating a jumbled code that only someone with the right key can read.
  *
+ * @template T - The type of the plain object to encrypt.
  * @param data - A plain object to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A `Result` promise containing the encrypted string in the specified format or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const {result, error, success} = await tryEncryptObj({ a: 1 }, secretKey);
+ *
+ * if (success) console.log(result); // "iv.cipherWithTag." (Encrypted string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryEncryptObj<T extends object = Record<string, unknown>>(data: T, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<Result<string>>;
 /**
@@ -160,11 +235,18 @@ declare function tryEncryptObj<T extends object = Record<string, unknown>>(data:
  * So, you take a picture of your toy box (convert it to JSON), and scramble that with
  * your special key, creating a jumbled code that only someone with the right key can read.
  *
+ * @template T - The type of the plain object to encrypt.
  * @param data - A plain object to encrypt.
  * @param secretKey - The `SecretKey` object used for encryption.
- * @param options.encoding - The encoding format for the output ciphertext (default: `'base64url'`).
+ * @param options.outputEncoding - The encoding format for the output ciphertext (default: `'base64url'`).
  * @returns A promise with the encrypted string in the specified format.
  * @throws {Error} If the input data or key is invalid, or if encryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encryptObj({ a: 1 }, secretKey); // "iv.cipherWithTag." (Encrypted string)
+ * ```
  */
 declare function encryptObj<T extends object = Record<string, unknown>>(data: T, secretKey: SecretKey<"web">, options?: EncryptOptions): Promise<string>;
 /**
@@ -179,8 +261,18 @@ declare function encryptObj<T extends object = Record<string, unknown>>(data: T,
  * @template T - The expected shape of the decrypted object.
  * @param encrypted - The encrypted string (format: `"iv.cipherWithTag."`).
  * @param secretKey - The `SecretKey` used for decryption.
- * @param options.encoding - Input ciphertext encoding (default: `'base64url'`).
+ * @param options.inputEncoding - Input ciphertext encoding (default: `'base64url'`).
  * @returns A `Result` promise with the decrypted object on success, or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = await createSecretKey("my-secret");
+ * const encrypted = await encryptObj({ a: 1 }, secretKey);
+ * const {result, error, success} = await tryDecryptObj<{ a: number }>(encrypted, secretKey);
+ *
+ * if (success) console.log(result); // { a: 1 }
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryDecryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<Result<{
     result: T;
@@ -197,9 +289,16 @@ declare function tryDecryptObj<T extends object = Record<string, unknown>>(encry
  * @template T - The expected shape of the decrypted object.
  * @param encrypted - The encrypted string (format: `"iv.cipherWithTag."`).
  * @param secretKey - The `SecretKey` used for decryption.
- * @param options.encoding - Input ciphertext encoding (default: `'base64url'`).
+ * @param options.inputEncoding - Input ciphertext encoding (default: `'base64url'`).
  * @returns A promise with 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
+ * ```
  */
 declare function decryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: SecretKey<"web">, options?: DecryptOptions): Promise<T>;
 /**
@@ -214,8 +313,16 @@ declare function decryptObj<T extends object = Record<string, unknown>>(encrypte
  *
  * @param data - The input string to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`, default: `'sha256'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
  * @returns A `Result` promise with the hash string or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = await tryHash("my data");
+ *
+ * if (success) console.log(result); // "..." (Hashed string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryHash(data: string, options?: HashOptions): Promise<Result<string>>;
 /**
@@ -230,9 +337,14 @@ declare function tryHash(data: string, options?: HashOptions): Promise<Result<st
  *
  * @param data - The input string to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`, default: `'sha256'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`, default: `'base64url'`).
  * @returns A promise of the hashed string.
  * @throws {Error} If input is invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const hashed = await hash("my data"); // "..." (Hashed string)
+ * ```
  */
 declare function hash(data: string, options?: HashOptions): Promise<string>;
 /**
@@ -247,14 +359,22 @@ declare function hash(data: string, options?: HashOptions): Promise<string>;
  *
  * @param password - The password to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`; default: `'sha512'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
  * @param options.saltLength - Length of the random salt in bytes (default: `16` bytes, min: `8` bytes).
  * @param options.iterations - Number of iterations (default: `320000`, min: `1000`).
  * @param options.keyLength - Length of the derived key in bytes (default: `64` bytes, min: `16` bytes).
- * @returns A `Result` promise with `{ hash, salt }` or an error.
+ * @returns A `Result` promise with `{ result, salt }` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = await tryHashPassword("my-password");
+ *
+ * if (success) console.log(result, salt); // "..." (hashed password), "..." (salt)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryHashPassword(password: string, options?: HashPasswordOptions): Promise<Result<{
-    hash: string;
+    result: string;
     salt: string;
 }>>;
 /**
@@ -269,15 +389,20 @@ declare function tryHashPassword(password: string, options?: HashPasswordOptions
  *
  * @param password - The password to hash.
  * @param options.digest - Hash algorithm (`'sha256' | 'sha384' | 'sha512'`; default: `'sha512'`).
- * @param options.encoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
+ * @param options.outputEncoding - Output encoding (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
  * @param options.saltLength - Length of the random salt in bytes (default: `16` bytes, min: `8` bytes).
  * @param options.iterations - Number of iterations (default: `320000`, min: `1000`).
  * @param options.keyLength - Length of the derived key in bytes (default: `64` bytes, min: `16` bytes).
- * @returns A promise with `{ hash, salt }` for storage.
+ * @returns A promise with `{ result, salt }` for storage.
  * @throws {Error} If inputs are invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const {result, salt} = await hashPassword("my-password"); // "..." (hashed password), "..." (salt)
+ * ```
  */
 declare function hashPassword(password: string, options?: HashPasswordOptions): Promise<{
-    hash: string;
+    result: string;
     salt: string;
 }>;
 /**
@@ -293,10 +418,18 @@ declare function hashPassword(password: string, options?: HashPasswordOptions):
  * @param hashedPassword - The stored hash (encoded).
  * @param salt - The stored salt (encoded).
  * @param options.digest - Hash algorithm used during hashing (`'sha256' | 'sha384' | 'sha512'`; default: `'sha512'`).
- * @param options.encoding - Encoding of the stored hash and salt (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
+ * @param options.inputEncoding - Encoding of the stored hash and salt (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`).
  * @param options.iterations - Number of iterations used during hashing (default: `320000`).
  * @param options.keyLength - Length of the derived key in bytes used during hashing (default: `64` bytes).
  * @returns A promise of boolean, `true` if the password matches, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * const {result, salt} = await hashPassword("my-password");
+ *
+ * await verifyPassword("my-password", result, salt); // true
+ * await verifyPassword("wrong-password", result, salt); // false
+ * ```
  */
 declare function verifyPassword(password: string, hashedPassword: string, salt: string, options?: VerifyPasswordOptions): Promise<boolean>;
 /**
@@ -310,6 +443,14 @@ declare function verifyPassword(password: string, hashedPassword: string, salt:
  * @param data - The input string to convert.
  * @param inputEncoding - The encoding of the input string (default: `'utf8'`).
  * @returns A `Result` with `{ result: Uint8Array }` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryConvertStrToBytes("Hello", "utf8");
+ *
+ * if (success) console.log(result); // Uint8Array([...])
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): Result<{
     result: Uint8Array<ArrayBuffer>;
@@ -326,6 +467,11 @@ declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): R
  * @param inputEncoding - The encoding of the input string (default: `'utf8'`).
  * @returns A `Uint8Array` containing the bytes.
  * @throws {Error} If input is invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8"); // Uint8Array([...])
+ * ```
  */
 declare function convertStrToBytes(data: string, inputEncoding?: Encoding): Uint8Array<ArrayBuffer>;
 /**
@@ -339,6 +485,15 @@ declare function convertStrToBytes(data: string, inputEncoding?: Encoding): Uint
  * @param data - The `Uint8Array` or `ArrayBuffer` to convert.
  * @param outputEncoding - The output encoding (default: `'utf8'`).
  * @returns A `Result` with the string or an error.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8"); // Uint8Array([...])
+ * const {result, error, success} = tryConvertBytesToStr(bytes, "utf8");
+ *
+ * if (success) console.log(result); // "Hello"
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertBytesToStr(data: Uint8Array | ArrayBuffer, outputEncoding?: Encoding): Result<string>;
 /**
@@ -353,6 +508,12 @@ declare function tryConvertBytesToStr(data: Uint8Array | ArrayBuffer, outputEnco
  * @param outputEncoding - The output encoding (default: `'utf8'`).
  * @returns The encoded string.
  * @throws {Error} If input is invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8"); // Uint8Array([...])
+ * const str = convertBytesToStr(bytes, "utf8"); // "Hello"
+ * ```
  */
 declare function convertBytesToStr(data: Uint8Array | ArrayBuffer, outputEncoding?: Encoding): string;
 /**
@@ -367,6 +528,14 @@ declare function convertBytesToStr(data: Uint8Array | ArrayBuffer, outputEncodin
  * @param from - The current encoding of `data`.
  * @param to - The target encoding for `data`.
  * @returns A `Result` with a string or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryConvertEncoding("Hello", "utf8", "base64url");
+ *
+ * if (success) console.log(result); // "..." (Base64url encoded string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertEncoding(data: string, from: Encoding, to: Encoding): Result<string>;
 /**
@@ -382,6 +551,11 @@ declare function tryConvertEncoding(data: string, from: Encoding, to: Encoding):
  * @param to - The target encoding for `data`.
  * @returns The converted string.
  * @throws {Error} If encodings are invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const base64url = convertEncoding("Hello", "utf8", "base64url"); // "..." (Base64url encoded string)
+ * ```
  */
 declare function convertEncoding(data: string, from: Encoding, to: Encoding): string;