Maturing the API + adding verification

[dhensby]

Maturing the API

In my mind the goal of this library is clear: The library should aim to deal with only HTTP Signatures and not deal with other related but not directly part of the signature issues. This means there should be no attempts made to do things like calculate or verify digest headers, nor attempt to worry about validating other parts of HTTP requests/responses except the http signature header(s).

This means there is no longer any need to worry about the body that will be passed to the HTTP request or that comes from the HTTP Response. The only parts of a request that we are concerned with are the headers, absolute url, and method. All components for a request signature can be derived from these parts alone.

At the moment the support for complex headers and components is limited, for example query parameters are not currently supported. The introduction of the structured-headers library should greatly help in this regard as the parsing of headers is not as straightforward as it may seem.

It should also be possible to add request-response binding to signatures.

Verification of signatures

At the moment verification of headers is completely missing from the library. This feature should be added.

Both key lookup and signature verification should be asynchronous.

Verification, like generation, of signatures does not require the full response, just the headers and status code. Further, to enable request-response binding the verifier needs access to the original request as well.

New requirements

Given the need to support request/response binding, it makes sense that there are separate function for signing/verifying requests and responses. At the moment there is an attempt to unify these use-cases in single functions, but that feels like the API is less clear and the code base needs to work in extra checks to be able to infer what is going on.

Therefore we need 4 distinct pieces of functionality:

1. Sign requests
2. Verify requests
3. Sign responses (with request binding)
4. Verify responses (with request binding)

Compatibility

The library aims to be compatible with built in node requests and other popular libraries like axios and should be simple to implement in an express middleware

[adrianhopebailie]

The introduction of the structured-headers library should greatly help in this regard as the parsing of headers is not as straightforward as it may seem.

The latest release of structured-headers is ready to pull in as a dependency now and replace the existing parsing and serialisation logic.

[dhensby]

closed by #27