tessl/npm-scure--base

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@scure/base

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

@scure/base is a secure, audited & 0-dep implementation of base encoding algorithms including base64, bech32, base58, base32 & base16. Designed with security as a priority and zero-dependency principles, it provides tree-shakeable, composable functions written in functional style that match relevant specifications.

Package Information

Package Name: @scure/base
Package Type: npm
Language: TypeScript
Installation: npm install @scure/base

Core Imports

import { base64, base58, base32, base16, hex, utf8 } from "@scure/base";
import { bech32, bech32m } from "@scure/base";
import { createBase58check, utils } from "@scure/base";

For CommonJS:

const { base64, base58, base32, base16, hex, utf8 } = require("@scure/base");
const { bech32, bech32m } = require("@scure/base");
const { createBase58check, utils } = require("@scure/base");

Basic Usage

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

// Convert string to bytes first
const data = utf8.decode("hello world");

// Encode to different formats
const b64 = base64.encode(data);    // "aGVsbG8gd29ybGQ="
const b58 = base58.encode(data);    // "StV1zBwJvKJ6JGa"
const hexStr = hex.encode(data);    // "68656c6c6f20776f726c64"

// Decode back to bytes
const decoded = base64.decode(b64);
const original = utf8.encode(decoded); // "hello world"

// All encoders have the same API: encode(bytes) -> string, decode(string) -> bytes

Architecture

@scure/base is built around several key components:

BytesCoder Interface: Common interface for all encoders with encode(Uint8Array) -> string and decode(string) -> Uint8Array
Functional Composition: Encoders built from small composable functions using utils.chain()
Built-in Optimizations: Uses native browser APIs when available (base64, hex)
RFC Compliance: Matches RFC 4648 for base encodings, BIP 173/350 for bech32
Security First: Audited implementation with input validation and error handling

Capabilities

Base Encodings

Standard RFC 4648 compliant base encodings including base16 (hex), base32 variants, and base64 variants with optional padding.

// Base16 (hex)
const base16: BytesCoder = {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
};

// Base32 variants  
const base32: BytesCoder;
const base32nopad: BytesCoder;
const base32hex: BytesCoder;
const base32hexnopad: BytesCoder;
const base32crockford: BytesCoder;

// Base64 variants
const base64: BytesCoder;
const base64nopad: BytesCoder;
const base64url: BytesCoder;
const base64urlnopad: BytesCoder;

Base Encodings

Base58 Encodings

Base58 encodings designed for cryptocurrency applications, including Bitcoin's base58, base58check with checksum validation, and variants like XMR and XRP.

const base58: BytesCoder;
const base58flickr: BytesCoder;
const base58xrp: BytesCoder;
const base58xmr: BytesCoder;

function createBase58check(
  sha256: (data: Uint8Array) => Uint8Array
): BytesCoder;

Base58 Encodings

Bech32 Encodings

Bitcoin BIP 173/350 compliant bech32 and bech32m encodings with typed prefix support and word-based operations for Bitcoin addresses and Lightning invoices.

interface Bech32 {
  encode<Prefix extends string>(
    prefix: Prefix,
    words: number[] | Uint8Array,
    limit?: number | false
  ): `${Lowercase<Prefix>}1${string}`;
  decode<Prefix extends string>(
    str: `${Prefix}1${string}`,
    limit?: number | false
  ): Bech32Decoded<Prefix>;
  encodeFromBytes(prefix: string, bytes: Uint8Array): string;
  decodeToBytes(str: string): Bech32DecodedWithArray;
  decodeUnsafe(str: string, limit?: number | false): void | Bech32Decoded<string>;
  fromWords(to: number[]): Uint8Array;
  fromWordsUnsafe(to: number[]): void | Uint8Array;
  toWords(from: Uint8Array): number[];
}

const bech32: Bech32;
const bech32m: Bech32;

Bech32 Encodings

Additional Encoders

UTF-8 and hexadecimal encoders for common text and binary data operations.

const utf8: BytesCoder = {
  encode: (data: Uint8Array) => string;  // bytes to UTF-8 string
  decode: (str: string) => Uint8Array;   // UTF-8 string to bytes
};

const hex: BytesCoder = {
  encode: (data: Uint8Array) => string;  // bytes to lowercase hex
  decode: (str: string) => Uint8Array;   // hex string to bytes
};

Utility Functions

Low-level utility functions for building custom encoders using functional composition, including radix conversion, alphabet mapping, and checksum validation.

const utils: {
  alphabet: (letters: string | string[]) => Coder<number[], string[]>;
  chain: <T extends Chain>(...args: T) => Coder<Input<First<T>>, Output<Last<T>>>;
  checksum: (len: number, fn: (data: Uint8Array) => Uint8Array) => Coder<Uint8Array, Uint8Array>;
  radix: (num: number) => Coder<Uint8Array, number[]>;
  radix2: (bits: number, revPadding?: boolean) => Coder<Uint8Array, number[]>;
  join: (separator?: string) => Coder<string[], string>;
  padding: (bits: number, chr?: string) => Coder<string[], string[]>;
};

Utility Functions

Types

interface BytesCoder {
  encode: (data: Uint8Array) => string;
  decode: (str: string) => Uint8Array;
}

interface Coder<F, T> {
  encode(from: F): T;
  decode(to: T): F;
}

interface Bech32Decoded<Prefix extends string = string> {
  prefix: Prefix;
  words: number[];
}

interface Bech32DecodedWithArray<Prefix extends string = string> {
  prefix: Prefix;
  words: number[];
  bytes: Uint8Array;
}

type CoderType = 'utf8' | 'hex' | 'base16' | 'base32' | 'base64' | 'base64url' | 'base58' | 'base58xmr';

interface SomeCoders {
  utf8: BytesCoder;
  hex: BytesCoder;
  base16: BytesCoder;
  base32: BytesCoder;
  base64: BytesCoder;
  base64url: BytesCoder;
  base58: BytesCoder;
  base58xmr: BytesCoder;
}

Deprecated Functions

The following functions are deprecated but still available for backwards compatibility:

/** @deprecated Use individual encoders directly instead */
function bytesToString(type: CoderType, bytes: Uint8Array): string;

/** @deprecated Alias for bytesToString */
const str: (type: CoderType, bytes: Uint8Array) => string;

/** @deprecated Use individual encoders directly instead */  
function stringToBytes(type: CoderType, str: string): Uint8Array;

/** @deprecated Alias for stringToBytes */
const bytes: (type: CoderType, str: string) => Uint8Array;