docs: publish the claim-level provider↔verifier claims contract - #14
Merged
Conversation
The JWT contract between auth.provider and auth.policy-verifier was mapped only at signature mechanics (alg/key symmetry); the claim half — which claims cross, who writes and reads each, what each side means by them — existed only as comments scattered across both repos and two provider CHANGELOG asides. docs/claims-contract.md consolidates that correspondence as an index over the existing mapping statements: seven crossing claims (scope, sub, azp, aud, iss, typ, exp/iat), two deliberately non-crossing ones (jti, groups), the E2E tests that pin rows executable, and the two-repo change protocol. Rows are anchored to stable names (collector classes, config keys) with file paths as secondary hints. Linked from architecture.md's Auth Flow and the README, with .ja.md twins per docs convention. Closes #13 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds an umbrella-repo documentation “index” for the claim-level JWT contract between auth.provider and auth.policy-verifier, and links it from the existing architecture/README docs (both English and Japanese) so readers can find the cross-repo mapping in one place.
Changes:
- Introduces
docs/claims-contract.md(+docs/claims-contract.ja.md) documenting which JWT claims cross the provider→verifier boundary and what they mean on each side. - Links the new contract doc from
docs/architecture.md/.ja.mdandREADME.md/.ja.md.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds link to the new claim-level contract doc. |
| README.ja.md | Adds link to the Japanese claim-level contract doc. |
| docs/claims-contract.md | New English claim-level provider↔verifier JWT contract documentation. |
| docs/claims-contract.ja.md | New Japanese translation of the claims contract doc. |
| docs/architecture.md | Links the new contract doc from the Auth Flow section. |
| docs/architecture.ja.md | Links the new Japanese contract doc from the Auth Flow section. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…elling The boundary-object paragraph cited packages/... paths without saying which sibling repo owns them — ambiguous in an umbrella doc where both siblings have a packages/core. Paths are now repo-qualified and the tables carry an explicit path convention. Also 'builtins collectors' → 'built-in collectors (its packages/builtins)', and 'id_tokens' → 'ID tokens (wire name id_token)'. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #13 (parent: #11).
What
docs/claims-contract.md(+.ja.mdtwin): the claim half of the provider↔verifier JWT contract — seven crossing claims (scope/sub/azp/aud/iss/typ/exp+iat), two deliberately non-crossing ones (jti,groups), the E2E tests that pin rows executable, and the two-repo change protocol.docs/architecture.md's Auth Flow section and the README (both languages).Why an index, not a new truth
Every row consolidates mapping statements that already exist as comments in the two sibling repos and this repo's E2E suites; the doc states explicitly that where a row and the cited code disagree, the code and its tests win. Rows are anchored to stable names (collector classes, config keys) so they rot slower than line numbers.
Verification
All rows were re-verified against the current siblings before writing (provider:
generateTokenclaim assembly, CP-12 scope normalization, D-6azp,claimFiltergroups gating; verifier:tokenAuthenticatoriss/aud/typ pins + requiredexp,PayloadScopeCollectorstring-split,RequestContextAttributeCollectorcontext channel). Docs-only change — no code or config touched.Follow-ups (tracked in the sub-issues of #11)
resourcehomonym and duplicated issuer/audience literals #12 will point the umbrella's seam comments at this doc (merge this first so links resolve).docs/design-vocabulary.md, auth.policy-verifier README) ride along in their own repos' sessions.🤖 Generated with Claude Code