Encoding & Crypto Utilities

Low-level encoding, decoding, and cryptographic functions for working with bytes, UTF-8, Base64, and SHA-256.

Imports

import {
   utf8ToBytes, utf8ToBytes, base64ToBytes, bytesToBase64,
   sha256Bytes, hmacSha256, hexToBytes, bytesToHex
   concatBytes, uint8To32ArrayBE, intTo4BytesBE
} from 'toolbox-x/hash';

UTF-8 Utilities

utf8ToBytes

Converts a UTF-8 string to a byte array.

Function Signature

utf8ToBytes(str: string): Uint8Array

Returns: Uint8Array containing the UTF-8 encoded bytes

Examples

Features

• Handles all Unicode code points including supplementary characters
• Follows UTF-8 specification (1-4 byte sequences)
• Silent handling of invalid surrogate pairs

bytesToUtf8

Converts UTF-8 encoded bytes back to a string.

Function Signature

bytesToUtf8(bytes: Uint8Array): string

Returns: Decoded string

Examples

Base64 Utilities

base64ToBytes

Decodes a Base64 string to bytes.

Function Signature

base64ToBytes(str: string): Uint8Array

Returns: Uint8Array containing decoded bytes

Examples

Supports

• Standard Base64 alphabet (A-Z, a-z, 0-9, +, /)
• Padding with '=' characters
• No external dependencies (pure JS)

bytesToBase64

Encodes bytes to a Base64 string.

Function Signature

bytesToBase64(bytes: Uint8Array): string

Returns: Base64-encoded string

Examples

Hashing & Crypto Utilities

sha256Bytes

Computes SHA-256 hash of raw bytes (pure JS implementation).

Function Signature

sha256Bytes(message: Uint8Array): Uint8Array

Returns: Uint8Array(32) containing SHA-256 hash

Examples

Implementation

• Follows FIPS 180-4 specification
• Big-endian byte order
• Processes 512-bit blocks
• No external dependencies

hmacSha256

Computes HMAC-SHA256 for message authentication.

Function Signature

hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array

Returns: Uint8Array(32) HMAC-SHA256 tag

Examples

Algorithm

1. Keys >64 bytes: hashed with SHA-256
2. Keys <64 bytes: padded with zeros
3. Inner hash: SHA-256((key ⊕ 0x36) || message)
4. Outer hash: SHA-256((key ⊕ 0x5C) || inner_hash)

Use Cases

• API authentication tokens
• Message integrity verification
• Key derivation (HKDF)

Binary Conversion Utilities

concatBytes

Concatenates multiple Uint8Arrays into one.

Function Signature

concatBytes(...parts: Uint8Array[]): Uint8Array

Returns: New Uint8Array with all bytes combined

Examples

Performance: Allocates once and uses set() for optimal copying.

uint8To32ArrayBE

Converts bytes to 32-bit integers (big-endian).

Function Signature

uint8To32ArrayBE(bytes: Uint8Array): Uint32Array

Returns: Uint32Array of 32-bit words

Examples

Notes

• Length doesn't need to be multiple of 4
• Missing bytes padded with zeros

intTo4BytesBE

Converts 32-bit integer to 4 bytes (big-endian).

Function Signature

intTo4BytesBE(n: number): Uint8Array

Returns: Uint8Array(4) big-endian bytes

Examples

Use Cases

• Network protocol headers
• Cryptographic operations
• Integer serialization

bytesToHex

Converts bytes to lowercase hexadecimal string.

Function Signature

bytesToHex(bytes: Uint8Array): string

Returns: Lowercase hex string

Examples

Features

• Always lowercase
• Zero-pads single digits (0x0F → "0f")
• No "0x" prefix

Use Cases

• Displaying cryptographic hashes
• Binary data debugging
• JSON serialization of binary data

See Also

• hexToBytes - Reverse conversion from bytes to hex

hexToBytes

Converts a hexadecimal string to a Uint8Array of bytes.

Function Signature

hexToBytes(hex: string): Uint8Array

Returns: Uint8Array containing the decoded bytes

Examples

Features

• Automatic validation - Uses isHexString to validate input
• Flexible formatting - Accepts spaced or un-spaced hex strings
• Case-insensitive - Works with uppercase and lowercase hex characters
• Safe handling - Returns empty array for invalid input instead of throwing
• Efficient - O(n) implementation with direct byte parsing

Input Requirements

• Must contain only hex characters (0-9, a-f, A-F)
• May contain optional spaces between bytes
• Must have even character count after removing spaces
• Does not accept prefixes like 0x or 0X
• Does not accept non-hex characters or odd-length strings

Use Cases

• Decoding cryptographic hashes, signatures, and keys
• Parsing hex-encoded binary payloads in protocols
• Reconstructing binary data from text storage
• Converting hex strings from APIs or databases to binary format
• Working with low-level binary interfaces and hardware protocols

Related Functions

// Validate before conversion
const hex = '12abff';
if (isHexString(hex)) {
  const bytes = hexToBytes(hex);
}

// Reverse conversion
const bytes = new Uint8Array([0x12, 0xAB, 0xFF]);
const hex = bytesToHex(bytes); // '12abff'

Edge Cases

// Mixed case is fine
hexToBytes('AaBbCc'); // Uint8Array(3) [170, 187, 204]

// Extra spaces are normalized
hexToBytes(' 12 ab  ff  '); // Uint8Array(3) [18, 171, 255]

// Non-hex characters return empty array
hexToBytes('0x123abc'); // Uint8Array []
hexToBytes('12g34h');   // Uint8Array []

// Non-string input (type safety)
// hexToBytes(12345); // TypeScript compile error

Performance Notes

• Input validation is integrated (no separate validation step needed)
• Space removal is efficient using regex
• Byte parsing uses native parseInt with base 16
• Memory efficient with single pass processing

See Also

• bytesToHex - Reverse conversion from bytes to hex
• isHexString - Input validation type guard

Common Workflows

String → SHA-256 Hex

const text = 'Hello, world!';
const bytes = utf8ToBytes(text);
const hash = sha256Bytes(bytes);
const hexHash = bytesToHex(hash);
// '315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3'

Base64 → UTF-8 String

const b64 = 'SGVsbG8g8J+MjQ=='; // "Hello 🌍"
const bytes = base64ToBytes(b64);
const text = bytesToUtf8(bytes);
// 'Hello 🌍'

HMAC-SHA256 with String Inputs

const encoder = new TextEncoder();
const key = encoder.encode('my-secret-key');
const message = encoder.encode('data-to-sign');
const hmac = hmacSha256(key, message);
const signature = bytesToHex(hmac);

Concatenating Hashes

const hash1 = sha256Bytes(utf8ToBytes('part1'));
const hash2 = sha256Bytes(utf8ToBytes('part2'));
const combinedHash = sha256Bytes(concatBytes(hash1, hash2));

Performance Notes

• Pure JavaScript: No Node.js crypto or Web APIs or other dependencies
• Optimized: Byte operations use Uint8Array.set() and DataView for performance
• Memory Efficient: Minimal allocations, reuse of buffers where possible
• Tree-shakeable: Individual functions can be imported separately