WFJSL Utility Classes and Functions

WFJSL Documentation Home

WFJSL TypeDoc Reference

Whiteflag Specification

Overview

The @whiteflagprotocol/util package provides common utilities for other Whiteflag packages. These utilities include common data conversions, generic helper functions, etc. for other Whiteflag packages. It should normally not be necessary to add this package as a dependency, but its functionality might be useful for other purposes.

This description provides a generic overview of the Whiteflag utility package. Please refer to the TypeDoc documentation for a detailed description of all classes and functions.

BinaryBuffer class

The binary module of the Whiteflag utility package provides the BinaryBuffer class. Objects of this class represent a binary encoded piece of data, e.g. a Whiteflag message, that can be manipulated at bit level.

Static methods to create a binary buffer:

• BinaryBuffer.empty(): creates an empty binary buffer
• BinaryBuffer.from(...): creates a binary buffer from another binary buffer
• BinaryBuffer.fromBytes(...): creates a binary buffer from bytes in a number array
• BinaryBuffer.fromHex(...): creates a binary buffer from a hexadecimal string
• BinaryBuffer.fromU8a(...): creates a binary buffer from a Uint8Array

Public methods to manipulate a binary buffer:

• BinaryBuffer.append(...): appends another binary buffer to the end of the binary buffer
• BinaryBuffer.crop(...): shortens the binary buffer to the length of the specified bits
• BinaryBuffer.extract(...): extracts the specified bits from the binary buffer
• BinaryBuffer.insert(...): inserts another binary buffer at the start of the binary buffer
• BinaryBuffer.shiftLeft(...): shifts bits in the buffer to the left, shrinking the buffer
• BinaryBuffer.shiftRight(...): shifts bits in the buffer to the right, enlarging the buffer

Some of these functions have an equivalent that allow to use a different binary representation, e.g. appendHex(...) or insertU8a(...).

Data conversions

The encoding module provides generic functions to convert data from one encoding to another.

Encoding	Description	Converts to
Base64	a string with a 64-character binary-to-text encoding	Base64url
Base64url	a string with a URL-safe 64-character binary-to-text encoding	Base64, Hexadecimal, String, UInt8Array
Hexadecimal	a string with a hexadecimal representation of a binary	Base64url, String, UInt8Array
Object	a plain JavaScript object	Base64url
Text	a string with UTF-8 characters	Base64url, Hexadecimal, UInt8Array
UInt8Array	an array of bytes representing a binary encoding	Base64url, Hexadecimal, String

For example hexToB64u(...) creates a base64url encoded string from a hexadecimal string. The module also provides some additional helper functions for different data encodings:

• isObject(...) checks if something is an object
• isString(...) checks if something is a string
• isBase64(...) checks if a string is base64 encoded
• isBase64u(...) checks if a string is base64url encoded
• isHex(...) checks if a string is hexadecimal encoded
• noHexPrefix(...) removes the ‘0x’ hex prefix if present

JSON Web Signature (JWS)

Whiteflag uses JSON Web Signatures (JWS). To create, sign and convert JWSs the jws module provides a common Jws class to other Whiteflag packages.