docs(specs): the token request reveals its headers, and the verifier checks them

[xgreenx]

Based on main, deliberately — see the note at the end.

The problem

The token request's headers were hidden, and for GitHub that was normative rather than ambiguous:

REQ-PLAT-43D: The GitHub Token Service MUST reveal no range outside the seven rows marked yes above.

…the transcript holds the authority only in a Host header this table hides…

That leaves a region of the request the Platform Verifier cannot read, in the one direction it has to reason about. It reads grant_type, client_id and code_verifier out of the body with a form-encoding reading — while common REQ-COMMON-21B fixes the media type precisely because it "selects the platform's request parser".

A media type the verifier cannot see is a value the profile pins and nothing checks. The platform may have parsed those bytes into fields other than the ones read, and every revealed byte would still look correct.

The change

The request line and every request header are revealed, and REQ-PLAT-56A has the verifier compare them against a fixed list, byte for byte and in order.

Both halves are load-bearing. Revealing without comparing would leave the bytes public and unconstrained — neither private nor checked, which is roughly where the contract is today. Both profiles' requests are now enumerated the way §5.3 and §6.5 already enumerate the identity request's headers; that precedent is what this follows.

Why this discloses nothing

The request is composed byte for byte by the implementation and driven over a raw MPC-TLS session — not the browser's HTTP stack, so there is no cookie jar and no ambient credential attachment. The headers are four profile constants (host, content-type, accept, connection).

Concealment would not have protected a user in any case: the implementation is what would have put anything private there, so hiding it hides it from review, not from the party that inserted it. Enumeration is the protection — nothing outside the fixed list can be present, because the verifier rejects it.

The response direction is unchanged and still hides its status line and headers: those are the platform's own bytes and nothing reads them. That asymmetry is now stated rather than inferred.

Two things deliberately preserved

• The Host argument. A revealed Host header is still not the authority — it is prover-composed text — so the authority still reaches the verifier as the authenticated TLS server identity. The prose keeps that reasoning and adds why revealing it changes nothing about it.
• client_secret: still committed, still ordered last by REQ-COMMON-22 so the revealed run stays contiguous.

Verification

lint_spec.py reports 3 errors, 9 warnings — identical to main, all pre-existing. My first draft added two W4 warnings (two MUSTs in one sentence); those are split.

Base branch

Not stacked on #19 (docs/ceremony-terminology), even though it rewrites these exact table rows to rename Platform Verifier → LOPPV. That PR is a draft, last updated 2026-09-03, already CONFLICTING with main, and part of a sweeping rename (Consumer → Identity Integration, Chain Profile → Ledger Profile) that will have to redo its diff regardless. Stacking a small correctness fix on it would strand the fix behind a large pending decision. When #19 is refreshed, its rename sweep absorbs these rows like every other.

In flight alongside this

• libid-contracts: the verifier-side header comparison REQ-PLAT-56A requires.
• A security audit of whether comparing the header set is sufficient, or whether more about the token request needs checking. If it returns findings, this PR may need another requirement before it lands.
• libid: the browser draft on feat/ceremony-rebuild-plan currently selects per-field body ranges and commits the headers; its selectTokenReveals becomes a single range under this.

JSON whitespace (REQ-COMMON-19F, TEST-COMMON-10A). GitHub pretty-prints /user for the pinned media type. The Platform Verifier removes the JSON whitespace that touches a structural byte before it matches, counts and reads (what libid-org/libid-contracts#37 does); the Implementation reveals a member as the wire carried it, whitespace inside, and never commits it with a bearer; the compact spellings in this specification name the member after removal. REQ-PLAT-51 judges the GitHub terminator after that removal; REQ-PLAT-60 keeps the whitespace in the reveal. Carries the vectors of #32.

[Wondertan]

I compared this revision with the ceremony implementation and current verifier. The main implementation findings are covered. These details remain:

1. Make the JSON extraction boundary explicit in REQ-COMMON-19F.

   The verifier deliberately distinguishes reading from counting: it extracts a complete field from one contiguous revealed range, but counts duplicate delimiters across all revealed ranges, including delimiters split across ranges.

   The updated requirement specifies normalization without retaining that distinction explicitly. Please state that normalization applies within a range for extraction, and that concatenation used for duplicate detection cannot construct a field value. This matches the existing verifier.

   Restore the corresponding TEST-COMMON-10A negatives: disjoint fragments assembled into a field, a duplicate delimiter split across reveals, and hidden bearer-prefix whitespace. The existing HTTP-chunk-boundary case does not cover these attestation-range cases. Relevant requirements.

2. Describe whitespace removal in terms of complete runs.

   “Every whitespace byte that touches a structural byte” is ambiguous for several consecutive whitespace bytes. The verifier removes an entire contiguous run when either adjacent byte is structural.

   Suggested wording: “Remove each maximal run of JSON whitespace when the byte immediately before or after that run is structural.” This agrees with the mixed-whitespace vectors already listed.

3. Add conformance coverage for the new header requirements.

   REQ-COMMON-39A/39B and REQ-PLAT-56A/56B/56C have no linked tests. Whole-suite lint introduces five corresponding E10 findings.

   Extend the existing test entries, retaining their IDs, to cover:

   • Additional permitted headers and required/forbidden header normalization.
   • A second Authorization header using a different scheme.
   • Bare CR/LF, folded headers and malformed header lines.
   • Missing, duplicate, padded or mismatched Content-Length.
   • Request/body boundaries, including GitHub’s committed secret suffix.

4. Resolve the remaining header prose contradictions.

   • REQ-PLAT-56A says to ignore every other header, but 56B requires checking Content-Length. Explicitly exempt that check.
   • The X token explanation still says its Host header is hidden, contradicting the updated disclosure table.
   • The PR description and GitHub rationale still describe a fixed header list, although the final requirements permit additional headers. Relevant section.