cipher-kit 2.0.0 → 2.1.0

package/dist/{export-CQNsJFh_.d.cts → export-BF9wW56f.d.ts}

@@ -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.cjs';
+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.js';
 import { Buffer } from 'node:buffer';
 
 /**
@@ -9,6 +9,13 @@ import { Buffer } from 'node:buffer';
  *
  * @param x - The value to check.
  * @returns True if the value is a SecretKey object for Node.js, false otherwise.
+ *
+ * @example
+ * ```ts
+ * isNodeSecretKey(nodeKey); // true
+ * isNodeSecretKey(webKey);  // false
+ * isNodeSecretKey({}); // false
+ * ```
  */
 declare function isNodeSecretKey(x: unknown): x is SecretKey<"node">;
 /**
@@ -19,6 +26,14 @@ declare function isNodeSecretKey(x: unknown): x is SecretKey<"node">;
  * 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>;
 /**
@@ -30,6 +45,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;
 /**
@@ -41,12 +61,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` containing the derived `SecretKey` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryCreateSecretKey("my-secret");
+ *
+ * if (success) console.log(result); // SecretKey object
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryCreateSecretKey(secret: string, options?: CreateSecretKeyOptions): Result<{
     result: SecretKey<"node">;
@@ -60,13 +88,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 The derived `SecretKey`.
  * @throws {Error} If key derivation fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret"); // SecretKey object
+ * ```
  */
 declare function createSecretKey(secret: string, options?: CreateSecretKeyOptions): SecretKey<"node">;
 /**
@@ -80,8 +113,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` containing the encrypted string in the specified format or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const {result, error, success} = tryEncrypt("Hello, World!", secretKey);
+ *
+ * if (success) console.log(result); // "iv.cipher.tag." (Encrypted string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryEncrypt(data: string, secretKey: SecretKey<"node">, options?: EncryptOptions): Result<string>;
 /**
@@ -95,9 +137,15 @@ declare function tryEncrypt(data: string, secretKey: SecretKey<"node">, 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 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 = createSecretKey("my-secret");
+ * const encrypted = encrypt("Hello, World!", secretKey); // "iv.cipher.tag." (Encrypted string)
+ * ```
  */
 declare function encrypt(data: string, secretKey: SecretKey<"node">, options?: EncryptOptions): string;
 /**
@@ -111,8 +159,18 @@ declare function encrypt(data: string, secretKey: SecretKey<"node">, options?: E
  *
  * @param encrypted - The input string to decrypt, in the format "iv.cipher.tag.".
  * @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` containing the decrypted UTF-8 string or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const encrypted = encrypt("Hello, World!", secretKey);
+ * const {result, error, success} = tryDecrypt(encrypted, secretKey);
+ *
+ * if (success) console.log(result); // "Hello, World!" (Decrypted string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryDecrypt(encrypted: string, secretKey: SecretKey<"node">, options?: DecryptOptions): Result<string>;
 /**
@@ -126,9 +184,16 @@ declare function tryDecrypt(encrypted: string, secretKey: SecretKey<"node">, opt
  *
  * @param encrypted - The input string to decrypt, in the format "iv.cipher.tag.".
  * @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 The decrypted UTF-8 string.
  * @throws {Error} If the input data or key is invalid, or if decryption fails.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const encrypted = encrypt("Hello, World!", secretKey);
+ * const decrypted = decrypt(encrypted, secretKey); // "Hello, World!" (Decrypted string)
+ * ```
  */
 declare function decrypt(encrypted: string, secretKey: SecretKey<"node">, options?: DecryptOptions): string;
 /**
@@ -143,10 +208,20 @@ declare function decrypt(encrypted: string, secretKey: SecretKey<"node">, option
  * 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` containing the encrypted string in the specified format or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const {result, error, success} = tryEncryptObj({ a: 1 }, secretKey);
+ *
+ * if (success) console.log(result); // "iv.cipher.tag." (Encrypted string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryEncryptObj<T extends object = Record<string, unknown>>(data: T, secretKey: SecretKey<"node">, options?: EncryptOptions): Result<string>;
 /**
@@ -161,11 +236,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 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 = createSecretKey("my-secret");
+ * const encrypted = encryptObj({ a: 1 }, secretKey); // "iv.cipher.tag." (Encrypted string)
+ * ```
  */
 declare function encryptObj<T extends object = Record<string, unknown>>(data: T, secretKey: SecretKey<"node">, options?: EncryptOptions): string;
 /**
@@ -180,8 +262,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.cipher.tag."`).
  * @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` with the decrypted object on success, or an error.
+ *
+ * @example
+ * ```ts
+ * const secretKey = createSecretKey("my-secret");
+ * const encrypted = encryptObj({ a: 1 }, secretKey);
+ * const {result, error, success} = tryDecryptObj<{ a: number }>(encrypted, secretKey);
+ *
+ * if (success) console.log(result); // { a: 1 } (Decrypted object)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryDecryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: SecretKey<"node">, options?: DecryptOptions): Result<{
     result: T;
@@ -198,9 +290,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.cipher.tag."`).
  * @param secretKey - The `SecretKey` used for decryption.
- * @param options.encoding - Input ciphertext encoding (default: `'base64url'`).
+ * @param options.inputEncoding - Input ciphertext encoding (default: `'base64url'`).
  * @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
+ * ```
  */
 declare function decryptObj<T extends object = Record<string, unknown>>(encrypted: string, secretKey: SecretKey<"node">, options?: DecryptOptions): T;
 /**
@@ -215,8 +314,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` with the hash string or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryHash("my data");
+ *
+ * if (success) console.log(result); // "..." (Hashed string)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryHash(data: string, options?: HashOptions): Result<string>;
 /**
@@ -231,9 +338,14 @@ declare function tryHash(data: string, options?: HashOptions): Result<string>;
  *
  * @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 The hashed string.
  * @throws {Error} If input is invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const hash = hash("my data"); // "..." (Hashed string)
+ * ```
  */
 declare function hash(data: string, options?: HashOptions): string;
 /**
@@ -248,14 +360,22 @@ declare function hash(data: string, options?: HashOptions): 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` with `{ hash, salt }` or an error.
+ * @returns A `Result` with `{ result, salt }` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, salt, error, success} = tryHashPassword("my-password");
+ *
+ * if (success) console.log(result, salt); // "..." (Hashed password string), "..." (salt)
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryHashPassword(password: string, options?: HashPasswordOptions): Result<{
-    hash: string;
+    result: string;
     salt: string;
 }>;
 /**
@@ -270,15 +390,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 `{ hash, salt }` for storage.
+ * @returns `{ result, salt }` for storage.
  * @throws {Error} If inputs are invalid or hashing fails.
+ *
+ * @example
+ * ```ts
+ * const { result, salt } = hashPassword("my-password"); // "..." (Hashed password string), "..." (salt)
+ * ```
  */
 declare function hashPassword(password: string, options?: HashPasswordOptions): {
-    hash: string;
+    result: string;
     salt: string;
 };
 /**
@@ -294,10 +419,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 `true` if the password matches, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * const { result, salt } = hashPassword("my-password");
+ *
+ * verifyPassword("my-password", result, salt); // true
+ * verifyPassword("wrong-password", result, salt); // false
+ * ```
  */
 declare function verifyPassword(password: string, hashedPassword: string, salt: string, options?: VerifyPasswordOptions): boolean;
 /**
@@ -311,6 +444,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: Buffer }` or an error.
+ *
+ * @example
+ * ```ts
+ * const {result, error, success} = tryConvertStrToBytes("Hello", "utf8");
+ *
+ * if (success) console.log(result); // <Buffer ...>
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): Result<{
     result: Buffer;
@@ -327,6 +468,11 @@ declare function tryConvertStrToBytes(data: string, inputEncoding?: Encoding): R
  * @param inputEncoding - The encoding of the input string (default: `'utf8'`).
  * @returns A `Buffer` containing the bytes.
  * @throws {Error} If input is invalid or conversion fails.
+ *
+ * @example
+ * ```ts
+ * const bytes = convertStrToBytes("Hello", "utf8"); // <Buffer ...>
+ * ```
  */
 declare function convertStrToBytes(data: string, inputEncoding?: Encoding): Buffer;
 /**
@@ -340,6 +486,15 @@ declare function convertStrToBytes(data: string, inputEncoding?: Encoding): Buff
  * @param data - The `Buffer` 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"); // <Buffer ...>
+ * const {result, error, success} = tryConvertBytesToStr(bytes, "utf8");
+ *
+ * if (success) console.log(result); // "Hello"
+ * else console.error(error); // { message: "...", description: "..." }
+ * ```
  */
 declare function tryConvertBytesToStr(data: Buffer, outputEncoding?: Encoding): Result<string>;
 /**
@@ -354,6 +509,12 @@ declare function tryConvertBytesToStr(data: Buffer, outputEncoding?: Encoding):
  * @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"); // <Buffer ...>
+ * const str = convertBytesToStr(bytes, "utf8"); // "Hello"
+ * ```
  */
 declare function convertBytesToStr(data: Buffer, outputEncoding?: Encoding): string;
 /**
@@ -368,6 +529,14 @@ declare function convertBytesToStr(data: Buffer, outputEncoding?: Encoding): str
  * @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>;
 /**
@@ -383,6 +552,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 encoded = convertEncoding("Hello", "utf8", "base64url"); // "..." (Base64url encoded string)
+ * ```
  */
 declare function convertEncoding(data: string, from: Encoding, to: Encoding): string;