Use a Bearer token in an HTTP request to verify identity. This will sign an
integer with the given crypto keypair, suitable for an access-control type
of auth.
The sequence number is an always incrementing integer. It is expected that a server, in addition to checking that the signature is valid, would remember the previous sequence number for this DID / public key, and check that the given number is larger than the previous one, to prevent replay attacks.
You can pass in either an integer or a localStorage instance. If you pass a
localStorage instance, it will read the index '__seq', which should be a
number. If there is not a number stored there, it will start at 0.
This package includes some opinions. I like to use ky,
so this includes an API that will create a ky instance.
npm i -S @substrate-system/requestThis reads and writes to the __seq key in localStorage.
This depends on message to create the signed token.
Create a new ky instance that will add a
signed header to every request, and also set the latest sequence
number in localStorage.
import { EccKeys as Keys } from '@substrate-system/keys/ecc'
import { SignedRequest } from '@substrate-system/request'
import ky from 'ky'
const keys = await Keys.create()
const keypair = {
privateKey: keys.writeKey.privateKey
publicKey: keys.writeKey.publicKey
}
// create a ky instance
// pass in the storage to use, or a sequence number to start with
const request = SignedRequest(ky, keypair, window.localStorage)
const response = await request.get('https://example.com')
// request is sent with headers `{ Authorization: Bearer <credentials> }`Parse the header string, and check the sequence number.
import {
verifyParsed,
parseHeader
} from '@substrate-system/request'
import type { ParsedHeader } from '@substrate-system/request'
const headerString = request.headers.Authorization
const parsedHeader:ParsedHeader = parseHeader(headerString)
const { seq } = parsedHeader
// ...get the previous sequence number somehow...
const isOk = await verifyParsed(parsedHeader) // check signature
const isSequenceOk = (seq > lastSequence) // check sequence numberOr, pass in a sequence number to check that parsedHeader.seq is greater than.
const headerString = request.headers.Authorization
const parsedHeader = parseHeader(headerString)
const isOk = await verifyParsed(parsedHeader, 3) // <-- pass in a seq herePatch a ky instance so it makes all requests with a signed header.
import type { KyInstance } from 'ky/distribution/types/ky'
function SignedRequest (
ky:KyInstance,
keypair:CryptoKeyPair,
startingSeq:number|Storage,
opts?:Record<string, any>
):KyInstanceThe request will have an Authorization header, base64 encoded:
request.headers.get('Authorization')
// => "Bearer eyJzZXEiOjEsIm..."import ky from 'ky-universal'
import { SignedRequest } from '@substrate-system/request'
// `req` is an instance of `ky`
const req = SignedRequest(ky, crypto, 0)
// make a request
await req.get('https://example.com/')
// ... later, on the server ...
const headerObject = parseHeader(request.headers.get('Authorization'))
// => {
// seq: 1,
// author: 'did:key:z13V3Sog2YaUKh...
// signature: 'VyaxQayQdXU7qhcOfcsCq...
// }Create a function that will create header tokens and read and write the
sequence number from localStorage.
function HeaderFactory (
keypair:CryptoKeyPair,
opts?:Record<string, any>,
ls?:Storage
):()=>Promise<`Bearer ${string}`>test('header factory', async t => {
const localStorage = new LocalStorage('./test-storage')
localStorage.setItem('__seq', '0')
const createHeader = HeaderFactory(keypair, {}, localStorage)
const header = await createHeader()
const header2 = await createHeader()
t.ok(header.includes('Bearer'), 'should include "Bearer" text')
const token = parseHeader(header)
const token2 = parseHeader(header2)
t.equal(token.seq, 1, 'should start at 0 sequence')
t.equal(token2.seq, 2, 'should increment the sequence number')
})
/**
* Optionally can pass in a params object and
* a localStorage instance
*/
const createHeaderTwo = HeaderFactory(crypto, { test: 'param' }, localStorage)Create the base64 encoded header string
async function createHeader (
keypair:CryptoKeyPair,
seq:number,
opts?:Record<string, any>,
):Promise<`Bearer ${string}`>This will create a header that looks like this:
`Bearer eyJzZXEiOj...`Check that the signature matches the given public key. Optionally takes a sequence number, and will return false if the header's sequence is not greater than the given sequence.
// take a base64 encoded header string
function verify (header:string, seq?:number):Promise<boolean>import { verify } from '@substrate-system/request'
const isOk = await verify(header)Check the validity of a parsed token. Optionally takes a sequence number. If a
seq number is not passed in, then this will only verify the signature.
import { SignedRequest as SignedMsg } from '@substrate-system/message'
// take a parsed token
function verifyParsed (
msg:SignedMsg<{ seq:number }>,
seq?:number
):Promise<boolean>import { verifyParsed, create as createToken } from '@substrate-system/request'
const token = await createToken(crypto, 1)
const isOk = await verifyParsed(parsedToken)Create a token object. This is the value that is encoded to make a header.
function createToken (
keypair:CryptoKeyPair,
seq:number,
opts?:Record<string, any>
):Promise<Token<typeof opts>>You can pass additional arguments to createToken, which will be added to the
signed token object.
import { createToken } from '@substrate-system/request'
const token = await createToken(crypto, 1, { example: 'testing' })
t.equal(token.example, 'testing', 'should have an additional property')Encode a token object as a base64 string
function encodeToken<T> (token:Token<T>):`Bearer ${string}`import { encodeToken } from '@substrate-system/request'
const encoded = encodeToken(token)In a web browser, pass an instance of ky,
and return an extended instance of ky, that will automatically add a
signature to the header as a Bearer token.
The header is a base64 encoded Bearer token. It looks like
Bearer eyJzZXEiOjE...
import { test } from '@nichoth/tapzero'
import { AuthRequest, parseHeader, verify } from '@substrate-system/request'
import ky from 'ky-universal'
let header:string
// header is a base64 encoded string: `Bearer ${base64string}`
let req:typeof ky
test('create instance', async t => {
req = SignedRequest(ky, keypair, 0)
await req.get('https://example.com/', {
hooks: {
afterResponse: [
(request:Request) => {
const obj = parseHeader(
request.headers.get('Authorization') as string
)
console.log('**header obj**', obj)
t.ok(obj, 'should have an Authorization header in request')
t.equal(obj.seq, 1, 'should have the right sequence')
}
]
}
})
})Check if a given signature matches the given public key. You would probably
call this in server-side code. This only checks that the public key and
signature are ok together. In real life you would need to check that the
public key has meaning to your system in addition to calling verify here.
test('parse header', t => {
const obj = parseHeader(header) // first parse base64, then parse JSON
// {
// seq: 1,
// author: 'did:key:...',
// signature: '123abc'
//}
t.equal(obj.seq, 1, 'should have the right sequence number')
})
test('verify the header', async t => {
t.equal(await verify(header), true, 'should validate a valid token')
// also make sure that the sequence number is greater than the previous
})This is distinct from parsing a "header" because the token does not include the text "Bearer".
import { TokenFactory, parseToken, verifyParsed } from '@substrate-system/request'
test('token factory', async t => {
// this is client-side
const createToken = TokenFactory(crypto)
const token = await createToken()
t.ok(!token.includes('Bearer'),
'should not include "Bearer" text in the token')
// this is server-side
const parsedToken = parseToken(token)
t.equal(parsedToken.seq, 1, 'should include the first sequence number')
t.ok(parsedToken.author, 'should have "author" in the token')
t.ok(parsedToken.signature, 'should have "signature" in the token')
t.ok(verifyParsed(parsedToken), 'should verify a valid token')
// also, check that the `parsedToken.seq` has increased
})Pass in an instance of localStorage, and we will save the sequence number
to __seq on any request.
import { test } from '@nichoth/tapzero'
import ky from 'ky-universal'
import { LocalStorage } from 'node-localstorage'
import { SignedRequest, parseHeader } from '@substrate-system/request'
test('create an instance with localStorage', async t => {
const localStorage = new LocalStorage('./test-storage')
localStorage.setItem('__seq', 3)
const req = SignedRequest(ky, keypair, localStorage)
await req.get('https://example.com', {
hooks: {
afterResponse: [
(request:Request) => {
const obj = parseHeader(
request.headers.get('Authorization') as string
)
t.equal(obj.seq, 4,
'should use localStorage to create the sequence')
}
]
}
})
const seq = localStorage.getItem('__seq')
t.equal(seq, 4, 'should save the sequence number to localStorage')
})