Skip to content

feat(keycardai-oauth): add the device authorization grant (RFC 8628) - #427

Closed
cmars wants to merge 2 commits into
mainfrom
casey/eco-486-python-sdk-support-for-device-code-flow
Closed

cmars wants to merge 2 commits into
mainfrom
casey/eco-486-python-sdk-support-for-device-code-flow

Conversation

@cmars

@cmars cmars commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Adds the OAuth 2.0 device authorization grant (RFC 8628) to keycardai-oauth, per the Device Authorization Grant spec and its follow-up change (keycard-sdk-spec 43165b4, branch casey/eco-480-device-grant-spec-followups). Linear: ECO-486 (parent ECO-480).

What it adds

  • AsyncClient.request_device_authorization, poll_device_token, and wait_for_device_token. Async only, per the spec's Python divergence row.
    • Client authentication is exactly one of credential= or a public client_id=. The client's auth strategy is not used.
    • wait_for_device_token waits through the client's clock before every poll, adds 5 seconds on slow_down, and raises expired_token without sending when the next poll would start after expires_at.
    • A network error, a 5xx, or a 429 stops the loop with DevicePollError. This includes a 5xx or 429 with an OAuth error body. Its interval resumes the loop. The original error is __cause__. retryable follows the cause.
    • Any other failure returns as is, without interval: a 4xx without an OAuth error body, or an error from the credential's client authentication.
    • Task cancellation ends the wait or the request in flight. No request follows.
    • Each request uses the client's timeout. A caller deadline around the whole loop does not replace it.
    • A response interval that is not a positive integer is invalid_response.
    • TokenResponse.raw keeps the server's resource field as received.
    • Pre-discovered metadata= skips discovery.
  • DeviceAuthorization (pydantic model, expires_at is a timezone-aware datetime), DeviceAuthorizationError (invalid_grant not retryable), DevicePollError.
  • Clock protocol and SystemClock. AsyncClient(clock=...).
  • ClientAuthenticator protocol and ClientAuthentication (headers and form fields). This is a separate optional capability. ApplicationCredential is unchanged. A credential without it is a ConfigError before any request.
    • ClientSecret: Basic header for the issuer's zone. An unknown zone raises KeyError.
    • WebIdentity: a new assertion per call, aud is the endpoint, iss/sub are the new client_id option. audience_config does not apply.
    • WorkloadIdentity: the source's token, plus client_id when configured.
  • WebIdentity(client_id=...). Token exchange uses the auth context's resource_client_id when present and this option otherwise. set_client_config falls back to it too.
  • refresh_token_grant(credential=...) and refresh_authorization(credential=...). credential with client_id (or client_secret) is a ConfigError. refresh_authorization's client_id is now optional, and required only without credential.
  • AuthorizationServerMetadata.device_authorization_endpoint, parsed from discovery.
  • expired_token in PERMANENT_ERROR_CODES, with a test that the set and the typed classification agree on every protocol error code.

Spec unit test rows covered

  • Device Authorization Grant: rows 1 to 28 (tests/keycardai/oauth/test_device_authorization.py, test names start with the row).
  • Authorization Server Discovery: rows 9 and 10.
  • Authorization Code with PKCE: row 16, on both AsyncClient.refresh_token_grant and refresh_authorization.
  • WebIdentity: rows 7 to 10. ClientSecret: row 7. Workload Identity: row 4b (tests/keycardai/oauth/server/test_client_authentication.py).

Integration rows are not covered. They need a live zone.

just check, just typecheck, and just test-coverage pass locally (oauth 791 passed, 90% coverage).

Open questions

  1. WebIdentity token exchange without any client id still raises ValueError, as before. Client authentication without client_id raises ConfigError. The spec calls both a configuration error. Changing the exchange path's exception type would break callers that catch ValueError.
  2. Clock scope. The injected clock covers expires_at and the poll waits. The discovery cache still reads time.time(). The base spec names token expiry and waits only.

Notes

  • credential is typed ClientAuthenticator | ApplicationCredential, so the result of discover_credential() type-checks. The capability is checked at run time.

Not changed

  • keycardai-temporal (_client_auth_fields) and keycardai.oauth.server.agent_grant still lift client-auth fields from a prepared token-exchange request for the client-credentials grant. Both could call client_authentication instead. Left for a follow-up, because it changes how WebIdentity resolves its client id on those paths.
  • The spec's Divergences rows for Python move to Resolved after this merges. That is a spec repo change.

🤖 Generated with Claude Code

cmars and others added 2 commits November 6, 2026 08:41
AsyncClient gains request_device_authorization, poll_device_token, and
wait_for_device_token. Each request authenticates with a credential's
client authentication or a public client_id. The loop waits through an
injected clock, honors task cancellation, adds 5 seconds on slow_down,
and stops on a network error, a 5xx, or a 429 with DevicePollError, whose
interval resumes the loop.

ClientSecret, WebIdentity, and WorkloadIdentity implement the new optional
ClientAuthenticator protocol. WebIdentity takes a client_id option.
refresh_token_grant and refresh_authorization accept a credential.
AuthorizationServerMetadata types device_authorization_endpoint.
PERMANENT_ERROR_CODES includes expired_token.

ECO-486.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ng as is

The credential's client authentication runs outside the transport call, so
an error it raises, including a NetworkError, is not wrapped in
DevicePollError. Adds tests for device authorization spec rows 25 to 28:
a malformed interval, a 5xx or 429 with an OAuth error body, a credential
failure on a poll, and the request timeout under a longer caller deadline.

ECO-486.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Release preview

keycardai-oauth 0.35.2 → 0.36.0 (minor)

  • fix(keycardai-oauth): return a credential failure during device polling as is
  • The credential's client authentication runs outside the transport call, so
    an error it raises, including a NetworkError, is not wrapped in
    DevicePollError. Adds tests for device authorization spec rows 25 to 28:
    a malformed interval, a 5xx or 429 with an OAuth error body, a credential
    failure on a poll, and the request timeout under a longer caller deadline.
  • ECO-486.
  • feat(keycardai-oauth): add the device authorization grant (RFC 8628)
  • AsyncClient gains request_device_authorization, poll_device_token, and
    wait_for_device_token. Each request authenticates with a credential's
    client authentication or a public client_id. The loop waits through an
    injected clock, honors task cancellation, adds 5 seconds on slow_down,
    and stops on a network error, a 5xx, or a 429 with DevicePollError, whose
    interval resumes the loop.
  • ClientSecret, WebIdentity, and WorkloadIdentity implement the new optional
    ClientAuthenticator protocol. WebIdentity takes a client_id option.
    refresh_token_grant and refresh_authorization accept a credential.
    AuthorizationServerMetadata types device_authorization_endpoint.
    PERMANENT_ERROR_CODES includes expired_token.
  • ECO-486.

No other package releases.


This comment was automatically generated by the release preview workflow.

@cmars

cmars commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Replaced by the stack #429, #430, #431, #432, #433. Merge in that order.

@cmars cmars closed this Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant