@simple-ssi/simple-cesr

simple-cesr

simple-cesr is a simple, limited, true-to-spec implementation of Composable Event Streaming Representation (CESR). It is compatible with Node.js and major browsers. It has a simple API for encoding and transforming primitives across three domain representations (Raw, Text, and Binary), as discussed in the spec. It conspicuously adheres to terminology from the spec and carefully avoids introducing outside concepts.

For now, we have only implemented a selected subset of primitives from the small fixed raw size and large fixed raw size tables:

Code	Description
A	Seed of Ed25519 private key
B	Ed25519 non-transferable prefix public verification key
C	X25519 public encryption key
D	Ed25519 public verification key
E	Blake3-256 Digest
F	Blake2b-256 Digest
G	Blake2s-256 Digest
H	SHA3-256 Digest
I	SHA2-256 Digest
J	Seed of ECDSA secp256k1 private key
M	Short number 2 byte base-2
N	Big number 8 byte base-2
O	X25519 private decryption key
0A	Random salt, seed, private key, or sequence number of length 128 bits
0B	Ed25519 signature
0C	ECDSA secp256k1 signature
0D	Blake3-512 Digest
0E	Blake2b-512 Digest
0F	SHA3-512 Digest
0G	SHA2-512 Digest
0H	Long number 4 byte base-2
1AAA	ECDSA secp256k1 non-transferable prefix public verification key
1AAB	ECDSA secp256k1 public verification or encryption key
1AAC	Ed448 non-transferable prefix public verification key
1AAD	Ed448 public verification key
1AAE	Ed448 signature
1AAF	Tag Base64 4 chars or 3 byte base-2 number

You can find the complete list of all the primitives supported by the CESR protocol in the spec.

This implementation is consistent with the 1.0 spec housed at IETF. We have not considered the soon-to-be-finished CESR 2.0 spec from the Trust Over IP Foundation but plan to do so in upcoming releases.

Usage

npm install @simple-ssi/simple-cesr

then:

const cesr = require('@simple-ssi/simple-cesr')

or

import * as cesr from '@simple-ssi/simple-cesr'

API

The API has three encode functions and three transform functions.

Encode

Encode functions are in the form function (code, raw).

• code is the text code, as a string, for the primitive you are encoding.
• raw is the raw primitive as a Uint8Array.

Encode Functions:

• raw(code, raw) - returns an object functionally equivalent to a tuple, {code, raw}.

  • code is the text code as a string.
  • raw is the raw primitive as a byte array.

• text(code, raw) - returns the primitive as a CESR-encoded text string.

• binary(code, raw) - returns the primitive as a CESR-encoded byte array.

Transform

Transform functions are in the form function (rawOrTextOrBinary).

• rawOrTextOrBinary is the primitive you want to transform in its current domain representation.

Transform Functions:

• toRaw(textOrBinary) - takes a primitive encoded as Text or Binary and transforms it into Raw.
• toText(rawOrBinary) - takes a primitive encoded as Raw or Binary and transforms it into Text.
• toBinary(rawOrText) - takes a primitive encoded as Raw or Text and transforms it into Binary.

Development

Run unit tests.

npm test

Run a high-level sanity test suite to verify the consistency of simple-cesr's output with another prominent CESR implementation, the matter class from signify-ts.

npm run standards-test

Run both test suites.

npm run all-tests

Run all tests, format the code, transpile for ECMAScript and CommonJS, and write the output to the dist directory at the project's root.

npm run full-build