Sidewinder Token
Type Safe Json Web Token
[
](https://www.npmjs.com/package/@sidewinder/token)
## Overview
Sidewinder Token is a type safe Json Web Token library used to sign and verify claims exchanged between services over a network. This library is built upon the [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) package but provides additional type checking for claims data for both signer and verifier. This package supports asymmetric signing only.
Licence MIT
## Contents
- [Overview](#Overview)
- [Example](#Example)
- [TokenEncoder](#TokenEncoder)
- [TokenDecoder](#TokenDecoder)
- [Generate Keys](#Generate-Keys)
## Example
The following shows general usage
```typescript
import { Generate, TokenEncoder, TokenDecoder } from '@sidewinder/token'
import { Type } from '@sidewinder/type'
// ----------------------------------------------------------------------
// Generate private and public key pair
// ----------------------------------------------------------------------
const [privateKey, publicKey] = Generate.KeyPair()
// ----------------------------------------------------------------------
// Create create a token type schematic
// ----------------------------------------------------------------------
const Token = Type.Object({
username: Type.String(),
roles: Type.Array(Type.String()),
})
// ----------------------------------------------------------------------
// Create a TokenEncoder and encode token
// ----------------------------------------------------------------------
const encoder = new TokenEncoder(Token, privateKey)
const token = encoder.encode({ username: 'dave', roles: ['admin', 'moderator'] })
// ----------------------------------------------------------------------
// Create a TokenDecoder and decode token
// ----------------------------------------------------------------------
const decoder = new TokenDecoder(Token, public)
const claims = decoder.decode(token)
```
## TokenEncoder
The TokenEncoder is responsible for encoding a claims object intended to be sent to a remote system over the network. The TokenEncoder accepts the type of the claims as it's first constructor argument, followed by a valid RSA private key kept secret to the encoding process. The TokenEncoder will throw an error if the data being encoded is not of the correct type.
```typescript
import { TokenEncoder } from '@sidewinder/token'
import { Type } from '@sidewinder/type'
const privateKey = '....' // Note: Private Keys are of type string.
const encoder = new TokenEncoder(
Type.Object({
username: Type.String(),
roles: Type.Array(Type.String()),
}),
privateKey,
)
const encoded = encoder.encode({
// Note: Data must conform to the structure
username: 'dave', // given on the encoders constructor
roles: ['admin', 'moderator'], // or an error is thrown.
})
// send 'encoded' to remote process
```
## TokenDecoder
The TokenEncoder is responsible for decoding a claims object received from a remote system over the network. The TokenEncoder accepts the type of the claims as it's first constructor argument, followed by a valid RSA `publicKey` given to the decoding process via some user defined mechanism. The TokenEncoder will throw an error if the data being decoded is not of the correct type.
```typescript
import { TokenDecoder } from '@sidewinder/token'
import { Type } from '@sidewinder/type'
const token = '...' // Note: Token is received via some network mechanism
const publicKey = '...' // Note: Public Keys are of type string.
const decoder = new TokenDecoder(
Type.Object({
username: Type.String(),
roles: Type.Array(Type.String()),
}),
publicKey,
)
const token = decoder.decode(encoded) // Note: The decode() function will throw
// if the given encoded data cannot
// be verified with the configured
// publicKey, or if the type of the
// claims data does not match that
// of the configured schema.
```