@ssc-half-light/request

request

Use a Bearer token in an HTTP request to verify identity. This will sign an integer with the given odd instance, suitable for an access-control type of auth.

The sequence number is an always incrementing integer. It is expected that a server would remember the previous sequence number for this DID (public key), and check that the given sequence is larger than the previous sequence. Also it would check that the signature is valid.

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, we will start at 0.

install

npm i -S @ssc-half-light/request

globals

This reads and writes to __seq key in localStorage.

example

Create a new ky instance that will add a signed header to every request, and set the latest sequence number in localStorage.

clientside

import { program as createProgram } from '@oddjs/odd'
import { SignedRequest } from '@ssc-half-light/request'
import ky from 'ky'

// ...get a `program` from `odd`

const crypto = program.components.crypto

// we read and write to '__seq' key in `localStorage`
const request = SignedRequest(ky, crypto, winodw.localStorage)
// `request` is an extended version of `ky`
const response = await request.get('https://example.com')
// request is sent with headers `{ Authorization: Bearer <credentials> }`

serverside

Parse the header string, and check the sequence number

import {
    verifyParsed,
    parseHeader
} from '@ssc-half-light/request'

const headerString = request.headers.Authorization
const 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 number

Or, pass in a sequence number to check that header.seq is greater than

const headerString = request.headers.Authorization
const parsedHeader = parseHeader(headerString)
const isOk = await verifyParsed(parsedHeader, 3)  // <-- pass in a seq here

---

dependencies

This should be ergonomic to use with the existing odd crypto library.

We also depend the library ky for requests.

---

API

Exported functions:

---

SignedRequest

---

Patch a ky instance so it makes all requests with a signed header.

import { KyInstance } from 'ky/distribution/types/ky'

function SignedRequest (
    ky:KyInstance,
    crypto:Implementation,
    startingSeq:number|Storage
):KyInstance

The request will have an Authorization header, base64 encoded:

request.headers.get('Authorization')
// => "Bearer eyJzZXEiOjEsIm..."

example

import ky from 'ky-universal'
import { program as createProgram } from '@oddjs/odd'
import { SignedRequest, } from '@ssc-half-light/request'

const program = await createProgram({
    namespace: { creator: 'identity', name: 'example' }
})
const { crypto } = program.components

// `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...
// }

---

HeaderFactory

---

Create a function that will create header tokens and read and write the sequence number from localStorage.

function HeaderFactory (
    crypto:Implementation,
    opts?:Record<string, any>,
    ls?:Storage
):()=>Promise<`Bearer ${string}`>

example

import { program as createProgram } from '@oddjs/odd'
import { HeaderFactory } from '@ssc-half-light/request'

const program = await createProgram(
    namespace: { creator: 'test', name: 'testing' },
})
const { crypto } = program.components

const createHeader = HeaderFactory(crypto)
const header = createHeader()  // read & update the seq in localStorage

/**
 * Optionally can pass in a params object and
 * a localStorage instance
 */
const createHeaderTwo = HeaderFactory(crypto, { test: 'param' }, localStorage)

---

createHeader

---

Create the base64 encoded header string

import { Implementation } from '@oddjs/odd/components/crypto/implementation'
async function createHeader (crypto:Implementation, seq:number)

This will create a header that looks like this:

`Bearer eyJzZXEiOj...`

---

verify

---

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>

example

import { verify } from '@ssc-half-light/request'

const isOk = await verify(header)

---

verifyParsed

---

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 '@ssc-half-light/message'
// take a parsed token
function verifyParsed (
    msg:SignedMsg<{ seq:number }>,
    seq?:number
):Promise<boolean>

example

import { verifyParsed, create as createToken } from '@ssc-half-light/request'

const token = await createToken(crypto, 1)
const isOk = await verifyParsed(parsedToken)

---

createToken

---

Create a token object. This is the value that is encoded to make a header.

function createToken (
    crypto:Implementation,
    seq:number,
    opts?:Record<string, any>
):Promise<Token<typeof opts>>

example

You can pass additional arguments to createToken, which will be added to the signed token object.

import { createToken } from '@ssc-half-light/request'

const token = await createToken(crypto, 1, { example: 'testing' })
t.equal(token.example, 'testing', 'should have an additional property')

---

encodeToken

---

Encode a token object as a base64 string

function encodeToken<T> (token:Token<T>):`Bearer ${string}`

example

import { encodeToken } from '@ssc-half-light/request'
const encoded = encodeToken(token)

---

more examples

create an instance

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 '@ssc-half-light/request'
import ky from 'ky-universal'

let header:string
// header is a base64 encoded string: `Bearer ${base64string}`

test('create instance', async t => {
    // `crypto` here is from `odd` -- `program.components.crypto`
    const req = AuthRequest(ky, crypto, 0)

    await req.get('https://example.com/', {
        hooks: {
            afterResponse: [
                (request:Request) => {
                    header = request.headers.get('Authorization')
                    const obj = parseHeader(
                        request.headers.get('Authorization') as string
                    )
                    t.ok(obj, 'should have an Authorization header in request')
                    t.equal(obj.seq, 1, 'should have the right sequence')
                }
            ]
        }
    })
})

verify a token

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 is something valid in your system as well as 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
})

use localStorage for the sequence number

Pass in an instance of localStorage, and we will save the sequence number to __seq on any request.

import { test } from '@nichoth/tapzero'
import { assemble } from '@oddjs/odd'
import { components } from '@ssc-hermes/node-components'
import ky from 'ky-universal'
import { LocalStorage } from 'node-localstorage'
import { SignedRequest, parseHeader } from '@ssc-half-light/request'

test('create an instance with localStorage', async t => {
    const program = await assemble({
        namespace: { creator: 'test', name: 'testing' },
        debug: false
    }, components)
    const crypto = program.components.crypto

    const localStorage = new LocalStorage('./test-storage')
    localStorage.setItem('__seq', 3)
    const req = SignedRequest(ky, crypto, 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')
})

Changelog

v0.5.5 - 2024-02-07

Merged

• Bump esbuild from 0.19.12 to 0.20.0 #4
• Bump actions/setup-node from 3 to 4 #2
• Bump @typescript-eslint/parser from 5.62.0 to 6.17.0 #3
• Bump actions/checkout from 3 to 4 #1

Commits

• add dependabot config 3db71c1
• better docs 16d7800
• better docs 94f8e8c