cipher-kit 2.1.3 → 3.0.0

package/dist/validate-lkJAHCeJ.d.ts

@@ -1,399 +0,0 @@
-import nodeCrypto, { webcrypto } from 'node:crypto';
-
-/**
- * Standardized error object for the `Result` type.
- * Always has a brief `message` and a more detailed `description`.
- */
-interface ErrorStruct {
-    readonly message: string;
-    readonly description: string;
-}
-type ReservedWords<Obj extends object> = "success" extends keyof Obj ? never : "error" extends keyof Obj ? never : Obj;
-type OkType<T> = {
-    readonly success: true;
-    readonly error?: undefined;
-} & (T extends object ? ReservedWords<{
-    readonly [K in keyof T]: T[K];
-}> : {
-    readonly result: T;
-});
-type ErrType<T> = {
-    readonly success: false;
-    readonly error: ErrorStruct;
-} & (T extends object ? ReservedWords<{
-    readonly [K in keyof T]?: undefined;
-}> : {
-    readonly result?: undefined;
-});
-/**
- * Discriminated union for functions that can succeed or fail.
- *
- * - On **success**:
- *   - If `T` is an object - properties of `T` are **spread** into the result
- *     along with `success: true`.
- *   - Otherwise - `{ success: true, result: T }`.
- * - On **failure**: `{ success: false, error: E }`.
- *
- * @example
- * ```ts
- * // Primitive result
- * function getNum(): Result<number> {
- *   return $ok(42);
- * }
- * const r1 = getNum();
- * if (r1.success) console.log(r1.result); // 42
- *
- * // Object result (spread)
- * function getObject(): Result<{ name: string; age: number }> {
- *   return $ok({ name: 'Alice', age: 30 });
- * }
- * const r2 = getObject();
- * if (r2.success) console.log(r2.name, r2.age); // 'Alice' 30
- * ```
- */
-type Result<T> = OkType<T> | ErrType<T>;
-
-declare const ENCODING: readonly ["base64", "base64url", "hex", "utf8", "latin1"];
-declare const CIPHER_ENCODING: readonly ["base64", "base64url", "hex"];
-declare const DIGEST_ALGORITHMS: Readonly<{
-    readonly sha256: {
-        readonly node: "sha256";
-        readonly web: "SHA-256";
-    };
-    readonly sha384: {
-        readonly node: "sha384";
-        readonly web: "SHA-384";
-    };
-    readonly sha512: {
-        readonly node: "sha512";
-        readonly web: "SHA-512";
-    };
-}>;
-declare const ENCRYPTION_ALGORITHMS: Readonly<{
-    readonly aes256gcm: {
-        readonly keyBytes: 32;
-        readonly ivLength: 12;
-        readonly node: "aes-256-gcm";
-        readonly web: "AES-GCM";
-    };
-    readonly aes192gcm: {
-        readonly keyBytes: 24;
-        readonly ivLength: 12;
-        readonly node: "aes-192-gcm";
-        readonly web: "AES-GCM";
-    };
-    readonly aes128gcm: {
-        readonly keyBytes: 16;
-        readonly ivLength: 12;
-        readonly node: "aes-128-gcm";
-        readonly web: "AES-GCM";
-    };
-}>;
-
-declare const __brand: unique symbol;
-type Brand<T> = {
-    readonly [__brand]: T;
-};
-type SecretKey<Platform extends "web" | "node"> = {
-    /** The platform the key is for ('web' or 'node'). */
-    readonly platform: Platform;
-    /** The digest algorithm used for HKDF (e.g. 'sha256'). */
-    readonly digest: keyof typeof DIGEST_ALGORITHMS;
-    /** The encryption algorithm used (e.g. 'aes256gcm'). */
-    readonly algorithm: keyof typeof ENCRYPTION_ALGORITHMS;
-    /** The actual secret key object (CryptoKey for web, KeyObject for node). */
-    readonly key: Platform extends "web" ? webcrypto.CryptoKey : nodeCrypto.KeyObject;
-} & Brand<`secretKey-${Platform}`>;
-/** A secret key for Node.js platform. */
-type NodeSecretKey = SecretKey<"node">;
-/** A secret key for Web platform. */
-type WebSecretKey = SecretKey<"web">;
-/** Supported **cipher text** encodings for encrypted/hash outputs. */
-type CipherEncoding = (typeof CIPHER_ENCODING)[number];
-/** Supported data encodings for **plain text/bytes** conversions. */
-type Encoding = (typeof ENCODING)[number];
-/** Supported symmetric encryption algorithms */
-type EncryptionAlgorithm = keyof typeof ENCRYPTION_ALGORITHMS;
-/** Supported digest algorithms for hashing */
-type DigestAlgorithm = keyof typeof DIGEST_ALGORITHMS;
-/**
- * Options for creating a `SecretKey`
- *
- * ### 🍼 Explain Like I'm Five
- * You want to create a special key to lock your treasure box.
- * You can choose how strong the lock is (algorithm), how to make the key (digest),
- * and add some extra secret stuff (salt and info) to make your key unique.
- *
- * - `algorithm`: Encryption algorithm to use (default: `'aes256gcm'`)
- * - `digest`: Digest algorithm for HKDF (default: `'sha256'`)
- * - `salt`: Salt for HKDF (default: `'cipher-kit-salt'`, must be ≥ 8 chars)
- * - `info`: Added context for HKDF (default: `'cipher-kit'`)
- */
-interface CreateSecretKeyOptions {
-    /** Encryption algorithm to use (default: `'aes256gcm'`). */
-    algorithm?: EncryptionAlgorithm;
-    /** Digest algorithm for HKDF (default: `'sha256'`). */
-    digest?: DigestAlgorithm;
-    /** Optional salt for HKDF (default: `'cipher-kit-salt'`, must be ≥ 8 characters). */
-    salt?: string;
-    /** Optional context info for HKDF (default: `'cipher-kit'`). */
-    info?: string;
-}
-/**
- * Options for encryption.
- *
- * ### 🍼 Explain Like I'm Five
- * After locking your message, how should we write the locked message down?
- *
- * - `outputEncoding`: Output ciphertext encoding (`'base64' | 'base64url' | 'hex'`) (default: `'base64url'`)
- */
-interface EncryptOptions {
-    /** Encoding format for the output ciphertext (default: `'base64url'`). */
-    outputEncoding?: CipherEncoding;
-}
-/**
- * Options for decryption.
- *
- * ### 🍼 Explain Like I'm Five
- * To unlock the message, we must know how it was written down.
- *
- * - `inputEncoding`: Input ciphertext encoding (`'base64' | 'base64url' | 'hex'`) (default: `'base64url'`)
- */
-interface DecryptOptions {
-    /** Encoding format for the input ciphertext (default: `'base64url'`). */
-    inputEncoding?: CipherEncoding;
-}
-/**
- * Options for hashing arbitrary data.
- *
- * ### 🍼 Explain Like I'm Five
- * You want to create a unique fingerprint (hash) of your data.
- * You can choose how to create the fingerprint (digest) and how to write it down (encoding).
- *
- * - `digest`: `'sha256' | 'sha384' | 'sha512'` (default: `'sha256'`)
- * - `outputEncoding`: Output ciphertext encoding for the hash (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`)
- */
-interface HashOptions {
-    /** Digest algorithm to use (default: `'sha256'`). */
-    digest?: DigestAlgorithm;
-    /** Encoding format for the output hash (default: `'base64url'`). */
-    outputEncoding?: CipherEncoding;
-}
-/**
- * Options for password hashing (PBKDF2).
- *
- * ### 🍼 Explain Like I'm Five
- * We turn your password into a strong secret by mixing it with salt,
- * stirring many times (iterations), and making a long result (keyLength).
- *
- * - `digest`: `'sha256' | 'sha384' | 'sha512'` (default: `'sha512'`)
- * - `outputEncoding`: Output ciphertext encoding for the hash (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`)
- * - `saltLength`: Size of the random salt in bytes (default: `16` bytes)
- * - `iterations`: Number of iterations (default: `320000`)
- * - `keyLength`: Length of the derived key in bytes (default: `64` bytes)
- */
-interface HashPasswordOptions {
-    /** Digest algorithm to use (default: `'sha512'`). */
-    digest?: DigestAlgorithm;
-    /** Encoding format for the output hash (default: `'base64url'`). */
-    outputEncoding?: CipherEncoding;
-    /** Length of the salt in bytes (default: `16` bytes, min: `8` bytes). */
-    saltLength?: number;
-    /** Number of iterations for key derivation (default: `320000`, min: `1000`). */
-    iterations?: number;
-    /** Length of the derived key in bytes (default: `64` bytes, min: `16` bytes). */
-    keyLength?: number;
-}
-/**
- * Options for verifying a password hash (PBKDF2) (must match the parameters used to hash).
- *
- * ### 🍼 Explain Like I'm Five
- * To check a password, we must use the same recipe—same mixer, same number of stirs,
- * same size—so the new result matches the old one.
- *
- * - `digest`: `'sha256' | 'sha384' | 'sha512'` (default: `'sha512'`)
- * - `inputEncoding`: Input ciphertext encoding for the hash (`'base64' | 'base64url' | 'hex'`; default: `'base64url'`)
- * - `iterations`: Number of iterations (default: `320000`)
- * - `keyLength`: Length of the derived key in bytes (default: `64` bytes)
- */
-interface VerifyPasswordOptions {
-    /** Digest algorithm to use (default: `'sha512'`). */
-    digest?: DigestAlgorithm;
-    /** Encoding format of the input hash (default: `'base64url'`). */
-    inputEncoding?: CipherEncoding;
-    /** Number of iterations for key derivation (default: `320000`). */
-    iterations?: number;
-    /** Length of the derived key in bytes (default: `64` bytes). */
-    keyLength?: number;
-}
-
-/**
- * Safely serializes a plain object to JSON without throwing.
- *
- * Wraps `JSON.stringify` and returns a `Result` containing the JSON string or an error.
- * Only plain objects (POJOs) are accepted. Class instances, Maps, Sets, etc. are rejected.
- *
- * ### 🍼 Explain Like I'm Five
- * You have a box of toys (your object) and take a photo of it (a JSON string)
- * so you can send it to a friend.
- *
- * @template T - Plain object type to serialize.
- * @param obj - The object to stringify (must be a plain object).
- * @returns A `Result` with the JSON string on success, or an error.
- *
- * @example
- * ```ts
- * const { result, error, success } = tryStringifyObj({ a: 1 });
- *
- * if (success) console.log(result); // "{\"a\":1}"
- * else console.error(error); // { message: "...", description: "..." }
- * ```
- */
-declare function tryStringifyObj<T extends object = Record<string, unknown>>(obj: T): Result<string>;
-/**
- * Serializes a plain object to JSON (throwing).
- *
- * Wraps `JSON.stringify` and returns the result or throws an error.
- * Only plain objects (POJOs) are accepted. Class instances, Maps, Sets, etc. are rejected.
- *
- * ### 🍼 Explain Like I'm Five
- * You have a box of toys (your object) and take a photo of it (a JSON string)
- * so you can send it to a friend.
- *
- * @template T - Plain object type to serialize.
- * @param obj - The object to stringify (must be a plain object).
- * @returns JSON string representation of the object.
- * @throws {Error} If `obj` is not a plain object or serialization fails.
- *
- * @example
- * ```ts
- * const json = stringifyObj({ a: 1 }); // "{\"a\":1}"
- * ```
- */
-declare function stringifyObj<T extends object = Record<string, unknown>>(obj: T): string;
-/**
- * Safely parses a JSON string to a plain object (non-throwing).
- *
- * Wraps `JSON.parse` and returns a `Result` containing the parsed object, or an error.
- *
- * ### 🍼 Explain Like I'm Five
- * You rebuild your toy box (an object) from a photo you took (a JSON string).
- *
- * @template T - The expected object type.
- * @param str - The JSON string to parse.
- * @returns A `Result` with the parsed object on success, or an error.
- *
- * @example
- * ```ts
- * const {result, error, success} = tryParseToObj<{ a: number }>('{"a":1}');
- *
- * if (success) console.log(result); // { a: 1 }
- * else console.error(error) // { message: "...", description: "..." }
- * ```
- */
-declare function tryParseToObj<T extends object = Record<string, unknown>>(str: string): Result<{
-    result: T;
-}>;
-/**
- * Parses a JSON string to a plain object (throwing).
- *
- * Wraps `JSON.parse` and returns the parsed object, or throws on failure.
- *
- * ### 🍼 Explain Like I'm Five
- * You rebuild your toy box (an object) from a photo you took (a JSON string).
- *
- * @template T - The expected object type.
- * @param str - The JSON string to parse.
- * @returns The parsed plain object.
- * @throws {Error} If the string can’t be parsed or doesn’t represent a plain object.
- *
- * @example
- * ```ts
- * const obj = parseToObj<{ a: number }>('{"a":1}'); // obj.a === 1
- * ```
- */
-declare function parseToObj<T extends object = Record<string, unknown>>(str: string): T;
-
-/**
- * Type guard to check if the provided value is a SecretKey object for Node.js environment.
- *
- * ### 🍼 Explain Like I'm Five
- * Checking if the key in your hand is the right kind of key for the lock.
- *
- * @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 NodeSecretKey;
-/**
- * Type guard to check if the provided value is a SecretKey object for Web (Deno, Bun, Cloudflare included) environment.
- *
- * ### 🍼 Explain Like I'm Five
- * Checking if the key in your hand is the right kind of key for the lock.
- *
- * @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 WebSecretKey;
-/**
- * Regular expressions for encrypted data patterns.
- *
- * - **node**: `"iv.cipher.tag."` (three dot-separated parts plus a trailing dot)
- * - **web**: `"iv.cipherWithTag."` (two parts plus a trailing dot)
- * - **general**: accepts both shapes (2 or 3 parts) with a trailing dot
- *
- * Each part is any non-empty string without dots.
- *
- * ### 🍼 Explain Like I'm Five
- * You have a secret code you want to check. Before you check it,
- * you make sure it looks how a secret code should look.
- */
-declare const ENCRYPTED_REGEX: Readonly<{
-    node: RegExp;
-    web: RegExp;
-    general: RegExp;
-}>;
-/**
- * Checks if a string matches an expected encrypted payload shape.
- *
- * - **node**: `"iv.cipher.tag."` (three dot-separated parts plus a trailing dot)
- * - **web**: `"iv.cipherWithTag."` (two parts plus a trailing dot)
- * - **general**: accepts both shapes (2 or 3 parts) with a trailing dot
- *
- * Each part is any non-empty string without dots.
- *
- * This validates only the **shape**, not whether content is valid base64/hex, etc.
- *
- * ### 🍼 Explain Like I'm Five
- * You have a secret code you want to check. Before you check it,
- * you make sure it looks how a secret code should look.
- *
- * @param data - The string to test.
- * @param format - Which layout to check: `'node'`, `'web'`, or `'general'`.
- * @returns `true` if the string matches the pattern; otherwise `false`.
- * @throws {Error} If an unknown `format` is provided.
- *
- * @example
- * ```ts
- * matchEncryptedPattern("abc.def.ghi.", "node");    // true
- * matchEncryptedPattern("abc.def.", "web");         // true
- * matchEncryptedPattern("abc.def.", "node");        // false
- * matchEncryptedPattern("abc.def.ghi.", "general"); // true
- * ```
- */
-declare function matchEncryptedPattern(data: string, format: "node" | "web" | "general"): boolean;
-
-export { type CipherEncoding as C, type DigestAlgorithm as D, ENCRYPTED_REGEX as E, type HashOptions as H, type NodeSecretKey as N, type Result as R, type VerifyPasswordOptions as V, type WebSecretKey as W, tryStringifyObj as a, isWebSecretKey as b, type Encoding as c, type EncryptionAlgorithm as d, type CreateSecretKeyOptions as e, type EncryptOptions as f, type DecryptOptions as g, type HashPasswordOptions as h, isNodeSecretKey as i, matchEncryptedPattern as m, parseToObj as p, stringifyObj as s, tryParseToObj as t };