httpsig 2.1.0: one RFC 8941 parser, and two signature verification bugs it found

[dickhardt]

Signature-Input is a Dictionary of Inner Lists with parameters — the hardest
shape RFC 8941 defines. It was hand-parsed here with regexes and split(), as
were Signature, Signature-Key, Signature-Error and the Accept-Signature
family. This replaces all of it with one vendored RFC 8941 implementation, and
exports that implementation so consumers stop writing a fourth one.

This ships on its own schedule. It fixes two real verification bugs for
existing consumers today. Nothing downstream is a precondition.

Two verification bugs fixed

These are the headline; the refactor is how they were found.

1. @signature-params is re-serialized from the parsed Inner List instead of
rebuilt from extracted parts. The old code reconstructed the signature base
line by pasting the pieces back together, and quoted every non-numeric
parameter. So a signer sending ;alg=hmac-sha256 — a Token, which is what RFC
9421 §2.3 specifies — had it turned into the String ;alg="hmac-sha256" in the
signature base. Different base, different digest, signature fails. It presented
as an unexplained bad signature from an entirely conformant peer.

2. Covered components carrying parameters are refused instead of silently
signed over as bare header names. ;req, ;bs, ;sf and ;key each change
what the component value is and how its signature base line is written. The
old parser dropped them and signed over the bare header name, producing a base
the signer never computed. This implementation does not produce those
parameters, so it now says so rather than guessing.

Does this change any signature base?

That is the first question to ask about a parser replacement inside signature
verification, and it is checkable from one function's arguments:

function buildSignatureParams(components: string[], created: number): InnerList {
    const items: Item[] = components.map((c) => [c, new Map() as Parameters])
    return [items, new Map([['created', created]]) as Parameters]
}

generateSignatureParams(components, created) emits only component
identifiers and created. No alg, no tag, no Token-valued parameter of any
kind — alg is deliberately never emitted on the signing path (RFC 9421 §3.3.7:
"the explicit alg signature parameter is not used at all when using JOSE
signing algorithms"). The alg parameter appears in exactly one place in this
package, generateAcceptSignatureHeader, which builds the Accept-Signature
hint header and never enters a signature base.

So httpsig has never signed over a Token-valued parameter. Strings were quoted
before and are quoted now; created is an Integer, which the old "quote every
non-numeric" rule already left alone. The @signature-params fix cannot change
the signature base for anything httpsig itself signs. The bug was entirely on
the verify side, against conformant third-party signers.

The tightenings hold up the same way. Covered component identifiers must be
Strings; created must be an Integer; Signature members must be Byte
Sequences; Signature-Key parameters must be Strings or Tokens; covered
components must carry no parameters. Every one rejects a shape this package
never emitted, so the only peers affected were already non-conformant. All
fail-closed.

Vendored, not depended on

structured-headers v1.0.1, MIT, copied into src/vendor/structured-headers/.

Zero dependencies is a deliberate security property of this package. It verifies
HTTP message signatures, so every package in its dependency closure is a package
that can silently change how a signature is checked. The same reasoning produced
the hand-written JWT verification in src/utils/ — written by reading jose
rather than importing it. A copy that is read, reviewed and pinned is a
different risk than a version range resolved at install time.

structured-headers is itself zero-dependency and MIT, so copying costs nothing
in licence terms and removes the supply chain entirely. src/vendor/ is listed
in the package's files, so the MIT licence text travels with every published
copy, as the licence requires.

The copy is byte-identical to upstream src/ once this repository's Prettier
config and .js import specifiers are applied — formatting only; no logic, no
control flow, no error messages, no exported names changed. That claim is
checkable, and the command is in
src/vendor/structured-headers/README.md:

mkdir -p /tmp/sh && cp node_modules/structured-headers/src/*.ts /tmp/sh/
npx prettier --tab-width 4 --no-semi --single-quote --trailing-comma all \
    --write '/tmp/sh/*.ts'
for f in parser serializer types token util index; do
    sed '1,5d' httpsig/src/vendor/structured-headers/$f.ts \
        | sed "s/\.js'/'/g" \
        | diff -u /tmp/sh/$f.ts - || echo "DIVERGED: $f"
done

The whole grammar was taken rather than a subset, because Signature-Input
already exercises nearly every production RFC 8941 defines, and a partial copy
covering "just the Dictionary bits" is how a divergent implementation gets
written.

Version 2.1.0

Additive. The new export is a new subpath, and every behaviour change either
fixes a verification failure or rejects a shape this package never produced.

@hellocoop/httpsig/structured-fields is a new export: parseDictionary,
parseList, parseItem, the matching serializers, Token, ByteSequence,
isInnerList, and a bareItemToString helper. It is a separate subpath so a
consumer can take the parser without pulling in verify() and the crypto at
import time.

Consumer

aauth-dev/packages-js#16
has @aauth/protocol import @hellocoop/httpsig/structured-fields and delete
its own hand-rolled structured-field helper. That PR is the reason the parser
got its own subpath, but it is a consequence of this one, not a precondition:
this merges and publishes first, then that side picks up ^2.1.0.

Context only, not a dependency: that PR is part of the AAuth -11 wave
(draft-hardt-oauth-aauth-protocol-11), which is where the second and third
hand-rolled copies of this grammar were found.

Testing

npm test --workspace=httpsig: 174 pass, 0 fail. npm run lint clean.
tests/test-structured-fields.ts covers the shapes this package depends on,
including the ones naive parsers get wrong.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FmiCqDjRUSx6zb1N4gZPXE

[dickhardt]

Note on commit history: 8aa5eab's message says "No version bump — this ships alongside a coordinated AAuth wave." That predates the decision to ship this independently, and is superseded by 645bd34 (the 2.1.0 bump) and by this PR description — 2.1.0 is backwards compatible and not gated on the AAuth work. Left the commit message as-is rather than force-pushing an open PR.