Skip to main content

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, 
   concatBytes, uint8To32ArrayBE, intTo4BytesBE, bytesToHex
} 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

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