Merge pull request #27 from dhensby/pulls/refactor

Maturing the API

Author: dhensby

.github/workflows/nodejs.yml

@@ -17,24 +17,41 @@ jobs:
   lint:
     name: Linting check
     runs-on: ubuntu-latest
+    timeout-minutes: 1
     steps:
       - uses: actions/checkout@v3
         with:
           persist-credentials: false
       - name: Code linting
         uses: actions/setup-node@v2
         with:
-          node-version: 12.x
+          node-version: 14.x
           cache: 'npm'
       - run: npm ci
       - run: npm run lint
-
+#  coverage:
+#    name: Coverage check
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: actions/checkout@v2
+#      - name: Code coverage
+#        uses: actions/setup-node@v2
+#        with:
+#          node-version: 12.x
+#          cache: 'npm'
+#      - run: npm ci
+#      - run: npm run test:coverage
+#      - name: Code Coverage Report
+#        uses: romeovs/lcov-reporter-action@v0.2.11
   tests:
     name: Unit tests
+    needs:
+      - lint
     runs-on: ubuntu-latest
+    timeout-minutes: 1
     strategy:
       matrix:
-        node-version: [12.x, 14.x, 16.x, 18.x]
+        node-version: [14.x, 16.x, 18.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     steps:
       - uses: actions/checkout@v3
@@ -46,4 +63,4 @@ jobs:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
       - run: npm ci
-      - run: npm test
+      - run: npm run test:coverage

.gitignore

@@ -1,2 +1,4 @@
 /lib/
 /node_modules/
+/.nyc_output/
+/coverage/

.nycrc

@@ -0,0 +1,5 @@
+{
+    "all": true,
+    "extension": [".ts"],
+    "include": ["src/**"]
+}

README.md

@@ -9,15 +9,61 @@ of HTTP messages before being sent.
 
 Two specifications are supported by this library:
 
-1. [HTTPBIS](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-06#appendix-B.2)
-2. [Cavage](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12)
+1. [HTTPbis](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures)
+2. [Cavage](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures) and subsequent [RichAnna](https://datatracker.ietf.org/doc/html/draft-richanna-http-message-signatures)
 
 ## Approach
 
-As the cavage specification is now expired and superseded by the HTTPBIS one, this library takes a
-"HTTPBIS-first" approach. This means that most support and maintenance will go into the HTTPBIS
-implementation and syntax. The syntax is then back-ported to the Cavage implementation as much as
-possible.
+As the Cavage/RichAnna specification is now expired and superseded by the HTTPbis one, this library takes a
+"HTTPbis-first" approach. This means that most support and maintenance will go into the HTTPbis
+implementation and syntax. The syntax is then back-ported to the as much as possible.
+
+## Caveats
+
+The Cavage/RichAnna specifications have changed over time, introducing new features. The aim is to support
+the [latest version of the specification](https://datatracker.ietf.org/doc/html/draft-richanna-http-message-signatures)
+and not to try to support each version in isolation.
+
+## Limitations in compliance with the specification
+
+As with many libraries and environments, HTTP Requests and Responses are abstracted away from the
+developer. This fact is noted in the specification. As such (in compliance with the specification),
+consumers of this library should take care to make sure that they are processing signatures that
+only cover fields/components whose values can be reliably resolved. Below is a list of limitations
+that you should be aware of when selecting a list of parameters to sign or accept.
+
+### Derived component limitations
+
+Many of the derived components are expected to be sourced from what are effectively http2 pseudo
+headers. However, if the application is not running in http2 mode or the message being signed is
+not being built as a http2 message, then some of these pseudo headers will not be available to the
+application and must be derived from a URL.
+
+#### @request-target
+
+The [`@request-target`](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures#section-2.2.5)
+component is intended to be the equivalent to the "request target portion of the request line".
+See the specification for examples of what this means. In NodeJS, this line in requests is automatically
+constructed for consumers, so it's not possible to know for certainty what this will be. For incoming
+requests, it is possible to extract, but for simplicity’s sake this library does not process the raw
+headers for the incoming request and, as such, cannot calculate this value with certainty. It is
+recommended that this component is avoided.
+
+### Multiple message component contexts
+
+As described in [section 7.4.4](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures#section-7.4.4)
+it is deemed that complex message context resolution is outside the scope of this library.
+
+This means that it is the responsibility of the consumer of this library to construct the equivalent
+message context for signatures that need to be reinterpreted based on other signer contexts.
+
+
+### Padding attacks
+
+As described in [section 7.5.7](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-13#section-7.5.7)
+it is expected that the NodeJS application has taken steps to ensure that headers are valid and not
+"garbage". For this library to take on that obligation would be to widen the scope of the library to
+a complete HTTP Message validator.
 
 ## Examples