stacklok / toolhive / 41027563081

73%

Build Type

push

github

Committed by web-flow

Commit Message

Define exchange grant authorization details type (#6990)

A confidential client run by an operator, such as an agent broker,
must keep acting for a user after that user's login has ended, for
example in scheduled background work. Its access token is short-lived
and tied to the login, so it cannot do this alone. The planned
mechanism exchanges the user's access token, through RFC 8693, for a
client-bound refresh token. The exchange request has to say what the
grant may produce and for how long, so this defines that request as an
RFC 9396 authorization_details type and the rules applied to it.

The type, https://toolhive.dev/exchange_grant, has three members:
type, issuable_token_types (one ID-JAG or refresh-token URN), and an
optional integer expires_at. Unknown members are refused, and a request
carries exactly one such entry. The lifetime comes from the operator's
policy per client and token type, not from the user's access-token
expiry, because the grant must outlive that token (RFC 8693 section
2.2.1). A missing expires_at takes the cap, and a larger one is cut
down to it (RFC 9396 section 7.1). A child grant cannot be a refresh
token and cannot outlive its parent.

The repeated-parameter error now comes from one constructor shared with
the existing handler, with no change in behaviour. Nothing calls these
rules yet; the handler arrives in a later change.

Known limits: the grant is not yet bound to an audience or resource
(RFC 9700 section 4.14.2, deferred). There is no inactivity expiry,
so only the hard cap applies. Consent is not checked yet; the handler
will require offline_access.

Co-authored-by: Mecatl <noreply@mecatl.dev>

Coverage Stats

134 of 138 new or added lines in 2 files covered. (97.1%)

9 existing lines in 3 files now uncovered.

91145 of 126355 relevant lines covered (72.13%)

131.16 hits per line