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.jwt the 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.jwt the 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.
The two branches are written asymmetrically
§8.3.1 introduces the DC API form by naming the Response Mode exactly:
The redirect form is introduced as an open-ended category, and the sentence has two slips in it:
Beyond the duplicated words, "such as … such as
direct_post.jwt" reads as an example of a larger set, whereas thedc_api.jwtsentence reads as the only member. An implementer has to decide which reading is intended.Why the ambiguity is worth closing
session_infois a byte string fed to HPKE as theinfoparameter. 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.jwtandform_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.jwtResponse Modes —direct_post.jwtanddc_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
.jwtmodes are anticipated, mirroring thedc_api.jwtsentence is the simplest fix:If the open category is intended, then saying so explicitly would be better than "such as":
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_urisupplies theresponseUrifield — 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.