tessl/npm-scure--base

Secure, audited & 0-dep implementation of base encoding algorithms

—

Pending

Overview

Eval results

Files

Base Encodings

Name: tessl/npm-scure--base
Author: tessl

Standard RFC 4648 compliant base encodings including base16 (hexadecimal), base32 variants, and base64 variants. All implementations are secure, audited, and use built-in browser APIs when available for optimal performance.

Capabilities

Base16 (Hexadecimal)

RFC 4648 base16 encoding using uppercase hexadecimal alphabet.

/**
 * base16 encoding from RFC 4648
 * Uses uppercase hexadecimal (0-9, A-F)
 */
const base16: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base16 } from "@scure/base";

const data = new Uint8Array([0x12, 0xab, 0xff]);
const encoded = base16.encode(data);    // "12ABFF"
const decoded = base16.decode("12ABFF"); // Uint8Array([0x12, 0xab, 0xff])

Base32 Standard

RFC 4648 base32 encoding with padding using standard alphabet.

/**
 * base32 encoding from RFC 4648 with padding
 * Uses alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
 * Use base32nopad for unpadded version
 */
const base32: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base32 } from "@scure/base";

const data = new Uint8Array([0x12, 0xab]);
const encoded = base32.encode(data);    // "CKVQ===="
const decoded = base32.decode("CKVQ===="); // Uint8Array([0x12, 0xab])

Base32 No Padding

RFC 4648 base32 encoding without padding.

/**
 * base32 encoding from RFC 4648 without padding
 * Same alphabet as base32 but no padding characters
 */
const base32nopad: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base32nopad } from "@scure/base";

const data = new Uint8Array([0x12, 0xab]);
const encoded = base32nopad.encode(data);    // "CKVQ"
const decoded = base32nopad.decode("CKVQ");  // Uint8Array([0x12, 0xab])

Base32 Hex

RFC 4648 base32hex encoding with padding using extended hex alphabet.

/**
 * base32hex encoding from RFC 4648 with padding
 * Uses alphabet: 0123456789ABCDEFGHIJKLMNOPQRSTUV
 * Use base32hexnopad for unpadded version
 */
const base32hex: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base32hex } from "@scure/base";

const data = new Uint8Array([0x12, 0xab]);
const encoded = base32hex.encode(data);    // "2ALG===="
const decoded = base32hex.decode("2ALG===="); // Uint8Array([0x12, 0xab])

Base32 Hex No Padding

RFC 4648 base32hex encoding without padding.

/**
 * base32hex encoding from RFC 4648 without padding
 * Same extended hex alphabet as base32hex but no padding
 */
const base32hexnopad: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Base32 Crockford

Doug Crockford's base32 variant with case-insensitive decoding and character normalization.

/**
 * base32 encoding using Crockford's variant
 * Uses alphabet: 0123456789ABCDEFGHJKMNPQRSTVWXYZ
 * Normalizes O->0, I/L->1 during decoding for error resilience
 */
const base32crockford: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base32crockford } from "@scure/base";

const data = new Uint8Array([0x12, 0xab]);
const encoded = base32crockford.encode(data);  // "2ANG"
const decoded = base32crockford.decode("2ANG"); // Uint8Array([0x12, 0xab])

// Case insensitive and normalizes ambiguous characters
const normalized = base32crockford.decode("2ang"); // Same result
const withSubs = base32crockford.decode("2AI0");   // Treats I as 1, O as 0

Base64 Standard

RFC 4648 base64 encoding with padding. Uses built-in browser APIs when available.

/**
 * base64 encoding from RFC 4648 with padding
 * Uses alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
 * Falls back to built-in browser functions when available
 */
const base64: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base64 } from "@scure/base";

const data = new Uint8Array([0x12, 0xab]);
const encoded = base64.encode(data);   // "Eqs="
const decoded = base64.decode("Eqs="); // Uint8Array([0x12, 0xab])

Base64 No Padding

RFC 4648 base64 encoding without padding.

/**
 * base64 encoding from RFC 4648 without padding
 * Same alphabet as base64 but no padding characters
 */
const base64nopad: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Base64 URL-Safe

RFC 4648 base64url encoding with padding using URL-safe alphabet.

/**
 * base64url encoding from RFC 4648 with padding
 * Uses URL-safe alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
 * Falls back to built-in browser functions when available
 */
const base64url: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base64url } from "@scure/base";

const data = new Uint8Array([0x12, 0xab]);
const encoded = base64url.encode(data);   // "Eqs="
const decoded = base64url.decode("Eqs="); // Uint8Array([0x12, 0xab])

Base64 URL-Safe No Padding

RFC 4648 base64url encoding without padding.

/**
 * base64url encoding from RFC 4648 without padding
 * Same URL-safe alphabet as base64url but no padding
 */
const base64urlnopad: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

Usage Examples:

import { base64urlnopad } from "@scure/base";

const data = new Uint8Array([0x12, 0xab]);
const encoded = base64urlnopad.encode(data);  // "Eqs"
const decoded = base64urlnopad.decode("Eqs"); // Uint8Array([0x12, 0xab])

Hex Encoding

Lowercase hexadecimal encoding. Uses built-in browser APIs when available.

/**
 * Hexadecimal encoding with lowercase output
 * Falls back to built-in browser functions when available
 * Accepts both uppercase and lowercase input during decoding
 */
const hex: BytesCoder = {
  encode: (data: Uint8Array) => string;  // Always lowercase output
  decode: (str: string) => Uint8Array;   // Accepts upper/lowercase input
};

Usage Examples:

import { hex } from "@scure/base";

const data = new Uint8Array([0x01, 0x02, 0xff]);
const encoded = hex.encode(data);        // "0102ff" (lowercase)
const decoded = hex.decode("0102FF");    // Uint8Array([0x01, 0x02, 0xff]) - accepts uppercase
const decoded2 = hex.decode("0102ff");   // Same result - accepts lowercase

UTF-8 Encoding

UTF-8 string to bytes conversion using built-in TextEncoder/TextDecoder.

/**
 * UTF-8 string to bytes encoder using built-in TextEncoder/TextDecoder
 * encode: converts bytes to UTF-8 string
 * decode: converts UTF-8 string to bytes
 */
const utf8: BytesCoder = {
  encode: (data: Uint8Array) => string;  // bytes to UTF-8 string
  decode: (str: string) => Uint8Array;   // UTF-8 string to bytes
};

Usage Examples:

import { utf8 } from "@scure/base";

const text = "Hello, 世界! 🚀";
const bytes = utf8.decode(text);    // Convert string to bytes
const restored = utf8.encode(bytes); // Convert bytes back to string
console.log(restored === text);     // true

Error Handling

All encoders validate input and throw descriptive errors:

Invalid characters for the encoding alphabet
Incorrect padding for padded variants
Invalid input types (non-Uint8Array for encode, non-string for decode)
Invalid string length for fixed-length requirements

import { base64, hex } from "@scure/base";

try {
  base64.decode("Invalid!Characters"); // Throws error
} catch (error) {
  console.log(error.message); // "invalid base64"
}

try {
  hex.decode("xyz"); // Throws error - invalid hex
} catch (error) {
  console.log(error.message); // Invalid hex characters
}

Install with Tessl CLI