capability-token

Stability: 1 - Experimental

Contributors

@tristanls

Contents

• Overview
• Installation
• Tests
• Usage
• Documentation
• Releases

Overview

This module documents the capability token format and provides a reference implementation.

Capability token format

capability_token = "CPBLTY" version "-" base64url

Example:

CPBLTY1-IbwNerN4Dw4BYlpYc4Az-pNBWen_WsdrTrpb-HmMiJOEHvCv1xHKBn2Q

The string CPBLTY is a well-known string to facilitate searches for leaked capabilities. version is the numeric version of the capability token. base64url is URL-safe base64 encoded bytes of the specified capability.

Installation

npm install capability-token

Tests

npm test

Usage

const cryto = require("crypto");
const CapabilityToken = require("capability-token");
 
const token1 = CapabilityToken.parse("CPBLTY1-IbwNerN4Dw4BYlpYc4Az-pNBWen_WsdrTrpb-HmMiJOEHvCv1xHKBn2Q");
 
console.log(token1.serialize() == "CPBLTY1-IbwNerN4Dw4BYlpYc4Az-pNBWen_WsdrTrpb-HmMiJOEHvCv1xHKBn2Q")
 
const token2 = new CapabilityToken(
    {
        body: crypto.randomBytes(64).toString("base64")
    }
);
 
console.log(token2.serialize());
 
const token3 = new CapabilityToken();
console.log(token3.serialize());
 
const token4 = new CapabilityToken(
    {
        body: crypto.randomBytes(64)
    }
);
 
console.log(token4.serialize());

Documentation

CapabilityToken

Public API

• CapabilityToken.parse(token)
• new CapabilityToken(config)
• capabilityToken.serialize()

CapabilityToken.parse(token)

• token: String String in capability token format.
• Return: CapabilityToken Version 1 capability token.

Parses token string and returns a version 1 CapabilityToken.

new CapabilityToken(config)

• config: Object Configuration.
  • version: Number (Default: 1) Version number to use.
  • body: Buffer|String (Default: crypto.randomBytes(64)) Buffer or String in base64 or base64url format to use for token body.
• Return: CapabilityToken Capability token with specified version and body.

Creates a new CapabilityToken with the specified version and body.

capabilityToken.serialize()

• Return: String String in capability token format.

Serializes capabilityToken into a string in capability token format.

Releases

Current releases.

Policy

We follow the semantic versioning policy (semver.org) with a caveat:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

caveat: Major version zero is a special case indicating development version that may make incompatible API changes without incrementing MAJOR version.