feat(validator): parse and expose On-Behalf-Of Token Exchange claims (RFC 8693)

[developerkunal]

📝 Checklist

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

🔧 Changes

Adds first-class validation support for access tokens issued through On-Behalf-Of / Token Exchange (RFC 8693), for example when an MCP server exchanges an incoming user token for one scoped to a downstream API. This SDK validates and inspects such tokens; performing the exchange itself is done by the authorization server, not this middleware.

These claims are now parsed automatically during validation, so no extra configuration is required.

validator.RegisteredClaims (new fields, additive)

• Act *Actor — the act (actor) claim chain per RFC 8693 §4.1
• AuthorizedParty string — the azp claim
• OrgID string — the org_id claim
• OrgName string — the org_name claim

New validator.Actor type

Models the nested act claim: Subject (sub), optional Issuer (iss), and a nested Act *Actor for the prior actor.

New helpers on validator.ValidatedClaims

• CurrentActor() string — the current actor (outermost act.sub), the client that performed the most recent exchange. Per RFC 8693 §4.1, this is the only actor value that may be used for access-control decisions.
• DelegationChain() []string — the full actor chain ordered from current to original, intended for audit and logging only.
• HasActor() bool

The API is shaped so the safe call (CurrentActor) is the obvious one, and DelegationChain is explicitly documented as audit-only, matching the RFC 8693 §4.1 guidance that nested actors must not drive authorization.

Delegation chains are limited to 5 levels; a token whose act claim nests more than 5 actors is rejected as an invalid_claims validation error.

All changes are additive. No existing fields, signatures, or behavior changed, and no new dependencies or network calls are introduced. Extraction of act, azp, org_id, and org_name is folded into the existing single payload decode alongside the cnf claim.

📚 References

• RFC 8693 — OAuth 2.0 Token Exchange, in particular §4.1 (the act claim)

🔬 Testing

• Unit tests for the CurrentActor, DelegationChain, and HasActor helpers cover the no-actor, empty-subject, single-exchange, and chained-exchange cases (validator/claims_test.go).
• Extraction tests cover a plain Bearer token (all new fields empty), a single-exchange token, organization claims, a chain at the maximum depth of 5 (accepted), a chain of 6 (rejected as invalid_claims), and a malformed token (validator/validator_test.go).
• Full suite passes: go test ./... (865 tests), go vet ./... clean, gofmt clean.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 91.66667% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.38%. Comparing base (ccef9da) to head (9375ca4).

Files with missing lines	Patch %	Lines
validator/validator.go	88.57%	3 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #407      +/-   ##
==========================================
- Coverage   94.42%   94.38%   -0.05%     
==========================================
  Files          25       25              
  Lines        2154     2190      +36     
==========================================
+ Hits         2034     2067      +33     
- Misses         81       83       +2     
- Partials       39       40       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.