nehoid
Version:
NehoID is a high-performance TypeScript library designed for generating, validating, and managing unique identifiers in enterprise-grade applications.
86 lines • 3.6 kB
TypeScript
/**
* Checksum and hash utilities for NehoID.
*
* This module provides various checksum and hashing algorithms
* for ID validation, integrity checking, and data fingerprinting.
*
* Security notes:
* - All algorithms here are NON-cryptographic (fast checksums).
* Do NOT use for passwords, signatures, or security-critical hashing.
* - `validate` / `tryValidate` use constant-time comparison to prevent
* timing-based side-channel attacks.
* - Inputs are normalised to UTF-8 bytes before hashing, ensuring
* consistent results across environments (Node.js, browsers, Deno…).
*/
export type ChecksumAlgorithm = "djb2" | "crc32" | "adler32" | "fnv1a" | "murmur3";
/** Accepted input types (string or raw bytes). */
export type ChecksumInput = string | Uint8Array;
export declare class ChecksumError extends Error {
constructor(message: string);
}
/**
* Encodes a string to a UTF-8 Uint8Array.
* Falls back gracefully when TextEncoder is unavailable (very old runtimes).
*/
export declare function toBytes(input: ChecksumInput): Uint8Array;
export declare class Checksum {
static readonly MAX_INPUT_BYTES = 1048576;
static readonly MIN_LENGTH = 1;
static readonly MAX_LENGTH = 16;
static readonly ALGORITHMS: readonly ChecksumAlgorithm[];
private constructor();
private static validateInput;
private static computeHash;
/**
* Generates a checksum using the specified algorithm.
*
* @param input - String or Uint8Array to hash.
* @param algorithm - Checksum algorithm (default: `"djb2"`).
* @param length - Output length in base-36 characters, 1–16 (default: 4).
* @returns Lowercase base-36 checksum of exactly `length` characters.
* @throws {ChecksumError} On invalid parameters.
*
* @example
* ```ts
* Checksum.generate("hello world"); // e.g. "2a3b"
* Checksum.generate("data", "crc32", 8); // 8-char CRC32 checksum
* Checksum.generate(new Uint8Array([1,2,3])); // works with raw bytes
* ```
*/
static generate(input: ChecksumInput, algorithm?: ChecksumAlgorithm, length?: number): string;
/**
* Validates a checksum against input data using constant-time comparison.
*
* The comparison is timing-safe: it does not short-circuit on mismatch,
* preventing timing-based side-channel leakage.
*
* @param input - Original input (string or Uint8Array).
* @param checksum - Checksum to validate.
* @param algorithm - Algorithm used when generating (default: `"djb2"`).
* @param length - Length used when generating (default: 4).
* @returns `true` if the checksum matches.
* @throws {ChecksumError} On invalid parameters.
*
* @example
* ```ts
* const cs = Checksum.generate("important-data");
* Checksum.validate("important-data", cs); // true
* ```
*/
static validate(input: ChecksumInput, checksum: string, algorithm?: ChecksumAlgorithm, length?: number): boolean;
/**
* Like `generate`, but returns `null` instead of throwing.
*
* @example
* ```ts
* const cs = Checksum.tryGenerate(userInput);
* if (cs === null) { /* handle error *\/ }
* ```
*/
static tryGenerate(input: ChecksumInput, algorithm?: ChecksumAlgorithm, length?: number): string | null;
/**
* Like `validate`, but returns `false` instead of throwing.
*/
static tryValidate(input: ChecksumInput, checksum: string, algorithm?: ChecksumAlgorithm, length?: number): boolean;
}
//# sourceMappingURL=checksum.d.ts.map