`session_info`: is the redirect form limited to `direct_post.jwt`?
Nobody has claimed this yet.
- Dominant language
- Shell
- Stars
- 112
- Forks
- 38
- Avg merge
- 12d 19h
- Merged PRs (30d)
- 4
Description
The two branches are written asymmetrically
§8.3.1 introduces the DC API form by naming the Response Mode exactly:
When the response mode is
dc_api.jwtthe encoding is as follows:
The redirect form is introduced as an open-ended category, and the sentence has two slips in it:
When the the presentation is invoked via redirects, such as Response Mode such as
direct_post.jwt, the encoding is as follows:
Beyond the duplicated words, "such as … such as direct_post.jwt" reads as an example of a larger set, whereas the dc_api.jwt sentence reads as the only member. An implementer has to decide which reading is intended.
Why the ambiguity is worth closing
session_info is a byte string fed to HPKE as the info parameter. Two implementations that resolve this differently do not degrade gracefully — the AEAD simply fails, and the failure surfaces as "decryption failed" with nothing pointing at the cause. It is a hard interop break with a poor diagnostic.
The doubt is not hypothetical. JARM defines query.jwt, fragment.jwt and form_post.jwt, so a reader arriving from that direction reasonably wonders whether the open phrasing is anticipating them. As far as I can tell, 1.1 defines exactly two .jwt Response Modes — direct_post.jwt and dc_api.jwt — so today the "category" has one member.
We implemented it as "dc_api.jwt → DC API form, everything else → redirect form", but that was a guess about intent rather than something the text settles.
Suggested wording
If no further redirect-based .jwt modes are anticipated, mirroring the dc_api.jwt sentence is the simplest fix:
When the response mode is
direct_post.jwtthe encoding is as follows:
If the open category is intended, then saying so explicitly would be better than "such as":
When the presentation is invoked via redirects — that is, for any Response Mode other than
dc_api.jwt— the encoding is as follows:
Either way the duplicated "the the" and "such as … such as" want fixing.
Related
There is a second ambiguity in the same structure that I have raised on #666, about which of redirect_uri / response_uri supplies the responseUri field — including the case where §5.9.3 permits both to be omitted from the request.
Context
Found while implementing §8.3 / §8.3.1 end to end — a Go wallet encrypting and a TypeScript verifier
decrypting, checked against the byte-level examples in §8.3.1.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with §8.3.1 and compare the dc_api.jwt and redirect-form wording, including the Response Mode definitions and byte-level examples. Update the text to remove the duplicated words and make the redirect-mode scope explicit; done when the session_info encoding rules have one unambiguous interpretation.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100