Cryptographic Operations

/**
 * Hash function supporting multiple algorithms
 * @param method - Hash method (md5, sha1, sha256, sha512, etc.)
 * @param s - Input value to hash
 * @param format - Output format (hex, base64, etc.)
 * @returns Hash string in specified format
 */
function hash(method: string, s: HashInput, format?: BinaryToTextEncoding): string;

type HashInput = string | Buffer | ArrayBuffer | DataView | object;

import { hash } from "utility";

// String input with hex output (default)
const hexHash = hash('sha256', 'hello world');
// Result: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"

// Buffer input with base64 output
const buffer = Buffer.from('hello world');
const base64Hash = hash('md5', buffer, 'base64');

// Object input (automatically JSON.stringify'd and sorted)
const objectHash = hash('sha1', { name: 'test', value: 123 });

/**
 * MD5 hash function
 * @param s - Input value to hash
 * @param format - Output format (hex or base64), defaults to hex
 * @returns MD5 hash string
 */
function md5(s: HashInput, format?: BinaryToTextEncoding): string;

import { md5 } from "utility";

// Basic string hashing
const hash1 = md5("hello world");
// Result: "5d41402abc4b2a76b9719d911017c592"

// Base64 output
const hash2 = md5("hello world", "base64");
// Result: "XUFAKrxLKna5cZ2REBfFkg=="

// Buffer input
const hash3 = md5(Buffer.from("hello world"));

// Object input
const hash4 = md5({ key: "value", number: 42 });

/**
 * SHA1 hash function
 * @param s - Input value to hash
 * @param format - Output format (hex or base64), defaults to hex
 * @returns SHA1 hash string
 */
function sha1(s: HashInput, format?: BinaryToTextEncoding): string;

/**
 * SHA256 hash function
 * @param s - Input value to hash
 * @param format - Output format (hex or base64), defaults to hex
 * @returns SHA256 hash string
 */
function sha256(s: HashInput, format?: BinaryToTextEncoding): string;

/**
 * SHA512 hash function
 * @param s - Input value to hash
 * @param format - Output format (hex or base64), defaults to hex
 * @returns SHA512 hash string
 */
function sha512(s: HashInput, format?: BinaryToTextEncoding): string;

/**
 * HMAC algorithm implementation
 * @param algorithm - Hash algorithm (sha1, md5, sha256, sha512, etc.)
 * @param key - HMAC key to be used
 * @param data - Content string or buffer
 * @param encoding - Output encoding, defaults to base64
 * @returns HMAC digest string
 */
function hmac(algorithm: string, key: string, data: string | Buffer, encoding?: BinaryToTextEncoding): string;

import { hmac } from "utility";

// Basic HMAC with SHA256
const signature = hmac('sha256', 'secret-key', 'message to sign');
// Result: base64-encoded HMAC

// HMAC with hex encoding
const hexSignature = hmac('sha1', 'my-key', 'data', 'hex');

// HMAC with buffer data
const bufferSignature = hmac('md5', 'key', Buffer.from('binary data'));

// Equivalent to bash command:
// echo -n "message" | openssl dgst -binary -sha256 -hmac "secret-key" | openssl base64

/**
 * Base64 encode string or buffer
 * @param s - Input string or buffer
 * @param urlSafe - Use URL-safe alphabet (- instead of +, _ instead of /)
 * @returns Base64 encoded string
 */
function base64encode(s: string | Buffer, urlSafe?: boolean): string;

import { base64encode } from "utility";

// Basic encoding
const encoded = base64encode("hello world");
// Result: "aGVsbG8gd29ybGQ="

// URL-safe encoding
const urlSafe = base64encode("hello world", true);
// Result: "aGVsbG8gd29ybGQ=" (no difference in this case)

// Buffer encoding
const bufferEncoded = base64encode(Buffer.from("binary data"));

// URL-safe with special characters
const specialChars = base64encode("???", true);
// Uses - and _ instead of + and /

/**
 * Base64 decode string to string or buffer
 * @param encodeStr - Base64 encoded string
 * @param urlSafe - Decode URL-safe alphabet
 * @param encoding - Output encoding ('utf8', 'buffer', etc.), defaults to utf8
 * @returns Decoded string or buffer
 */
function base64decode(encodeStr: string, urlSafe?: boolean, encoding?: BufferEncoding | 'buffer'): string | Buffer;

import { base64decode } from "utility";

// Basic decoding
const decoded = base64decode("aGVsbG8gd29ybGQ=");
// Result: "hello world"

// URL-safe decoding
const urlDecoded = base64decode("aGVsbG8gd29ybGQ=", true);

// Return as buffer
const buffer = base64decode("aGVsbG8gd29ybGQ=", false, 'buffer') as Buffer;

// Specific encoding
const latin1 = base64decode("encoded-string", false, 'latin1');