Skip to main content

Encoding & Crypto Utilities

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

info

Does not rely on Node.js or Web APIs. Works on any JS engine

Imports​

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

UTF-8 Utilities​

utf8ToBytes​

Converts a UTF-8 string to a byte array.

Function Signature​

utf8ToBytes(str: string): Uint8Array
ParameterTypeDescription
strstringThe input string to encode as UTF-8 bytes

Returns: Uint8Array containing the UTF-8 encoded bytes

Examples​

const bytes = utf8ToBytes('Hello 🌍');
// Uint8Array(10) [72, 101, 108, 108, 111, 32, 240, 159, 140, 141]

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
ParameterTypeDescription
bytesUint8ArrayUTF-8 encoded bytes

Returns: Decoded string

Examples​

const bytes = new Uint8Array([72, 101, 108, 108, 111]);
const str = bytesToUtf8(bytes); // 'Hello'

Base64 Utilities​

base64ToBytes​

Decodes a Base64 string to bytes.

Function Signature​

base64ToBytes(str: string): Uint8Array
ParameterTypeDescription
strstringBase64-encoded string

Returns: Uint8Array containing decoded bytes

Examples​

const bytes = base64ToBytes('aGVsbG8=');
// Uint8Array(5) [104, 101, 108, 108, 111]

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
ParameterTypeDescription
bytesUint8ArrayBytes to encode

Returns: Base64-encoded string

Examples​

const bytes = new Uint8Array([104, 101, 108, 108, 111]);
const b64 = bytesToBase64(bytes); // 'aGVsbG8='

Hashing & Crypto Utilities​

sha256Bytes​

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

Function Signature​

sha256Bytes(message: Uint8Array): Uint8Array
ParameterTypeDescription
messageUint8ArrayBytes to hash

Returns: Uint8Array(32) containing SHA-256 hash

Examples​

const bytes = new Uint8Array([104, 101, 108, 108, 111]); // "hello"
const hash = sha256Bytes(bytes);
// Uint8Array(32) [44, 242, 77, 186, ...]

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
ParameterTypeDescription
keyUint8ArraySecret key bytes
messageUint8ArrayMessage bytes

Returns: Uint8Array(32) HMAC-SHA256 tag

Examples​

const key = new TextEncoder().encode('secret');
const msg = new TextEncoder().encode('Hello');
const hmac = hmacSha256(key, msg);

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
ParameterTypeDescription
partsUint8Array[]Arrays to concatenate

Returns: New Uint8Array with all bytes combined

Examples​

const a = new Uint8Array([1, 2]);
const b = new Uint8Array([3, 4]);
const result = concatBytes(a, b);
// Uint8Array(4) [1, 2, 3, 4]

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

uint8To32ArrayBE​

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

Function Signature​

uint8To32ArrayBE(bytes: Uint8Array): Uint32Array
ParameterTypeDescription
bytesUint8ArrayBytes to convert

Returns: Uint32Array of 32-bit words

Examples​

const bytes = new Uint8Array([0x12, 0x34, 0x56, 0x78, 0x9A]);
const words = uint8To32ArrayBE(bytes);
// Uint32Array(2) [0x12345678, 0x9A000000]

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
ParameterTypeDescription
nnumber32-bit integer

Returns: Uint8Array(4) big-endian bytes

Examples​

const bytes = intTo4BytesBE(0x12345678);
// Uint8Array(4) [0x12, 0x34, 0x56, 0x78]

Use Cases​

  • Network protocol headers
  • Cryptographic operations
  • Integer serialization

bytesToHex​

Converts bytes to lowercase hexadecimal string.

Function Signature​

bytesToHex(bytes: Uint8Array): string
ParameterTypeDescription
bytesUint8ArrayBytes to convert

Returns: Lowercase hex string

Examples​

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

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
ParameterTypeDescription
hexstringHexadecimal string to convert

Returns: Uint8Array containing the decoded bytes

Examples​

// Basic conversion
const hex = '12abff00';
const bytes = hexToBytes(hex); // Uint8Array(4) [18, 171, 255, 0]

// With spaces
const spacedHex = '48 65 6c 6c 6f';
const spacedBytes = hexToBytes(spacedHex); // Uint8Array(5) [72, 101, 108, 108, 111]

// Empty input
const emptyBytes = hexToBytes(''); // Uint8Array []

// Invalid input returns empty array
const invalidBytes = hexToBytes('invalid!'); // Uint8Array []
const oddBytes = hexToBytes('123'); // Uint8Array []

// Cryptographic hash decoding
const sha256Hex = '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824';
const hashBytes = hexToBytes(sha256Hex); // Uint8Array(32)

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
// 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​

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