Skip to content

docs(identity-linking): repair the garbled JWT grant single-use bullet - #731

Open
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/identity-linking-jti-bullet
Open

docs(identity-linking): repair the garbled JWT grant single-use bullet#731
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/identity-linking-jti-bullet

Conversation

@vishkaty

Copy link
Copy Markdown
Contributor

The JWT grant single-use bullet in Security Considerations reads as a broken sentence: an explanatory clause was inserted mid-sentence, leaving the requirement itself split across a full stop.

Currently:

Businesses MUST enforce single-use JWT;
a short exp narrows the replay window, but only jti tracking closes it.
authorization grants by tracking the jti claim within the grant's
validity window.

This PR restores the requirement as one sentence and keeps the explanation after it, with exp and jti in code formatting to match their use in the neighbouring bullets. No normative change: the MUST, the mechanism, and the window are the same.

@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage documentation Improvements or additions to documentation status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 14, 2026
@westonale

Copy link
Copy Markdown

Confirming this reads correctly now. The original had the clause boundary in the wrong place: "MUST enforce single-use JWT" ran into the exp aside, and then "authorization grants by tracking the jti claim" resumed a sentence that had already been closed, so the normative requirement was split across a parenthetical and lost its object.

The rewrite restores it to one requirement ("MUST enforce single-use JWT authorization grants by tracking the jti claim within the grant's validity window") and demotes the exp versus jti point to its own sentence, which is where it belongs: it is rationale, not a second MUST. Backticking exp and jti matches the surrounding bullets.

Worth saying that the rationale sentence is the part doing the work for implementers. A short exp feels like replay protection and is not, and that is a genuinely common mistake to make when reading quickly. Keeping it as a standalone sentence after the requirement is the right ordering.

@vishkaty
vishkaty force-pushed the fix/identity-linking-jti-bullet branch from e9c31cb to d3a35b9 Compare August 21, 2026 17:54

@niranjanmanjunath niranjanmanjunath left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a clean, non-normative documentation fix that repairs a spliced sentence in the
Security Considerations section.

@westonale

Copy link
Copy Markdown

Worth flagging that this is no longer only a docs nit: the garbled bullet is now inside the v2026-08-25 tag at docs/specification/common/identity-linking/index.md lines 1021 to 1023, so implementers pinning to the release read a normative replay-protection MUST with a rationale clause spliced through the middle of it and an orphaned fragment after the semicolon.

Two independent contributors have now filed the same +3/-3 fix in nine days (this PR and #764, which was self-closed as a duplicate), which is a reasonable signal that the sentence is actively confusing readers rather than merely untidy. Checks here are green and it only needs a maintainer.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants