Skip to content
Better Web Token - an iteration of web tokens with a bunch of improvements
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows fix action yml Sep 20, 2019
.appveyor.yml add ci confi Jun 14, 2019
.gitignore update demo and docs Sep 4, 2019
.travis.yml add ci confi Jun 14, 2019
LICENSE license Sep 1, 2019 fix github action badge Sep 20, 2019
keygen.ts doc optional keygen name arg Sep 17, 2019
mod.ts add test action Sep 19, 2019 add test action Sep 19, 2019
test.ts fix test import Sep 17, 2019
usage.ts better demo Sep 4, 2019



Better Web Token

... a web token format, generation, and verification scheme

Powered by Curve25519, ChaCha20 derivatives, and Poly1305

⚠️ Not yet formally reviewed 🚧


What a BWT Looks Like



import * as bwt from "";

const alice = { ...bwt.generateKeyPair(), stringify: null };
const bob = { ...bwt.generateKeyPair(), parse: null };

alice.stringify = bwt.createStringify(alice.secretKey, {
  kid: bob.kid,
  publicKey: bob.publicKey

bob.parse = bwt.createParse(bob.secretKey, {
  kid: alice.kid,
  publicKey: alice.publicKey

const iat =;
const exp = iat + 1000;

const token = alice.stringify(
  { typ: bwt.Typ.BWTv0, kid: alice.kid, iat, exp },
  { info: "jwt sucks" }

console.log("alice seals and gets this token to bob:", token);

const contents = bob.parse(token);

console.log("bob opens it...:", JSON.stringify(contents));



Besides a few constants and interfaces, the module's main exports are two factory functions, createStringify -> stringify and createParse -> parse.

As BWT uses asymmetric keys the module also exports a key generation function: generateKeyPair. More on key management.

Find basic interfaces and constants below.

/** Supported BWT versions. */
export const SUPPORTED_VERSIONS: Set<number> = new Set<number>([0]);

/** Maximum allowed number of characters of a token. */
export const MAX_TOKEN_CHARS: number = 4096;

/** Byte length of a Curve25519 secret key. */
export const SECRET_KEY_BYTES: number = 32;

/** Byte length of a Curve25519 public key. */
export const PUBLIC_KEY_BYTES: number = 32;

/** Byte length of a BWT kid. */
export const KID_BYTES: number = 16;

/** Typ enum indicating a BWT version @ the Header.typ field. */
export const enum Typ {

 * BWT header object.
 * typ must be a supported BWT version, currently that is Typ.BWTv0 only.
 * iat and exp denote the issued-at and expiry ms timestamps of a token.
 * kid is the public key identifier of the issuing peer.
export interface Header {
  typ: Typ;
  iat: number;
  exp: number;
  kid: Uint8Array;

/** BWT body object. */
export interface Body {
  [key: string]: unknown;

/** BWT contents. */
export interface Contents {
  header: Header;
  body: Body;

/** BWT stringify function. */
export interface Stringify {
  (header: Header, body: Body): string;

/** BWT parse function. */
export interface Parse {
  (token: string): Contents;

 * BWT keypair object including a key identifier for the public key.
 * secretKey is the 32-byte secret key.
 * publicKey is the 32-byte public key.
 * kid is a 16-byte key identifier for the public key.
export interface KeyPair {
  secretKey: Uint8Array;
  publicKey: Uint8Array;
  kid: Uint8Array;

 * BWT public key of a peer.
 * publicKey is the 32-byte public key.
 * kid is a 16-byte key identifer for the public key.
 * name can be an arbitrarily encoded string.
export interface PeerPublicKey {
  publicKey: Uint8Array;
  kid: Uint8Array;
  name?: string;

Core Callables

generateKeyPair(): KeyPair

Generates a new keypair.

createStringify(ownSecretKey: Uint8Array, peerPublicKey: PeerPublicKey): Stringify

Creates a stringify function.

ownSecretKey is the secret key of the issuing peer's key pair.

peerPublicKey must be the peer public key object of the peer that the to-be-generated tokens are meant for.

createStringify zeros the secret key buffer after computing the shared secret with the indicated peer. Just be aware that createStringify clears ownSecretKey.

createParse(ownSecretKey: Uint8Array, ...peerPublicKeys: PeerPublicKey[]): Parse

Creates a parse function.

ownSecretKey is the secret key of the keypair of the peer that is going to parse and verify tokens. peerPublicKeys must be a non-empty list of peer public key objects to be used for verification of incoming tokens.

createParse zeros the secret key buffer after deriving the shared key for the indicated peers. Just be aware that createParse clears ownSecretKey.

stringify(header: Header, body: Body): string

Stringifies a token.

header must contain four props:

  • typ set to one of the Typ enum variants, currently that is Typ.BWTv0 only

  • iat a millisecond timestamp indicating the current time

  • exp a millisecond timestamp indicating the expiry of the token, must be greater than iat

  • kid a binary of 16 bytes, the public key identifier of the issuing peer

body must be an object. Apart from that it can contain any type of fields. Nonetheless, make sure not to bloat the body as stringify will return null if a generated token exceeds 4KiB.

In case of invalid inputs or any other exceptions stringify returns null, otherwise a BWT token.

parse(token: string): Contents

Parses a token.

Returns null if the token is malformatted, corrupt, invalid, expired, from an unknown issuer, or if any other exceptions occur while marshalling, such as JSON.parse(body) -> 💥

In case of a valid token parse returns an object containing the token header and body.

This function encapsulates all validation and cryptographic verification of a token. Note that, as BWT requires every token to expire, parse does this basic metadata check.

Additional application-specific metadata checks can be made as parse, besides the main body, returns the token header that contains metadata. Fx, an app could choose to reject all tokens of a certain age by additionally checking the mandatory iat claim of a token header.

Managing Keys

Any peer must own a static key pair and possess its peer's public keys and key identifiers for token generation and verification. Since a shared symmetric key would allow impersonation BWT requires key pairs.

You can generate a key pair and the corresponding peer public key from the terminal by simply running deno run [name of key pair owner].

Make sure to store the key pair somewhere safe (some kind of secret store) so that the included secret key remains private.

Narrow the set of owners of a particular key pair as much as possible. Particularly, any token-issuing peer should own a key pair exclusively. Peers that only parse/verify tokens, fx a set of CRUD endpoints for a specific resource, may share a key pair.

Do renew all key pairs involved in your application setting regularly!

Dear Reviewers

Quick setup:

  1. Install deno:

    curl -fsSL | sh

  2. Get this repo:

    git clone && cd ./bwt && mkdir ./cache

  3. Cache all dependencies and run tests:

    DENO_DIR=./cache $HOME/.deno/bin/deno run --reload ./test.ts

  4. Find all non-dev dependencies in the following two directories:


    curve25519, chacha20, hchacha20, poly1305, chacha20-poly1305, xchacha20-poly1305, std-encoding



Please open an issue for your review findings. Looking forward to your feedback!

Thank you for reviewing!



You can’t perform that action at this time.