Skip to content

feat(keycardai-oauth): refresh with a credential - #431

Merged
cmars merged 3 commits into
casey/eco-486-client-authfrom
casey/eco-486-refresh
Nov 17, 2026
Merged

cmars merged 3 commits into
casey/eco-486-client-authfrom
casey/eco-486-refresh

Conversation

@cmars

@cmars cmars commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Adds credential= to the refresh step in Authorization Code with PKCE (spec-version 5), on AsyncClient.refresh_token_grant and refresh_authorization. A device uses it to get a token for one of the resources the device grant issued. Linear: ECO-486.

The credential's client_authentication is called with the token endpoint. Its headers and form fields replace the client's auth strategy and the body client_id. The issuer passed to the credential has no trailing slash in every entry mode, so a multi-zone ClientSecret finds its zone.

Errors

Failure Error
credential with client_id, or (on refresh_authorization) with client_secret ConfigError, before discovery or any request
A credential without client authentication, or a WebIdentity without client_id ConfigError, before discovery or any request
Neither credential nor a non-empty client_id on refresh_authorization ConfigError, before any request
The credential's client authentication fails, such as an unknown zone That error, as is. No token request is sent.
metadata on refresh_authorization without token_endpoint, or with an empty one ConfigError, before any request. It was ValueError, and an empty value fell through to a convention-derived endpoint.
OAuth error response RefreshGrantError with the response's status_code. A 429 or 5xx is retryable whatever the code (base spec, Retryability). Otherwise invalid_grant is not retryable.

test_status_decides_retryable_first (operations/test_authorize.py) and test_refresh_rejects_metadata_without_token_endpoint (pkce/test_web.py) cover the last two rows.

The sync Client does not take a credential, because Python credentials are async only.

Spec unit test rows covered

Authorization Code with PKCE row 16, in tests/keycardai/oauth/test_refresh_with_credential.py. Each test runs on AsyncClient and on refresh_authorization with issuer=, metadata=, and www_authenticate_header=, with discovery on.

Test Checks
test_row_16_refresh_with_credential the exact form body and headers, and the credential's (issuer, endpoint)
test_row_16_client_secret_sends_basic_and_no_client_id single-zone and multi-zone Basic headers
test_unknown_zone_sends_no_token_request ConfigError, no POST
test_misconfigured_refresh_sends_no_request each configuration error, with no discovery or resource metadata request

Stack

Replaces #427. Merge in order:

  1. fix(keycardai-oauth): percent-encode the client ID and secret in HTTP Basic #429
  2. feat(keycardai-oauth): client authentication on credentials #430
  3. feat(keycardai-oauth): refresh with a credential #431 (this PR)
  4. feat(keycardai-oauth): device authorization request and single poll #432
  5. feat(keycardai-oauth): poll until done for the device grant #433

The PR workflow runs only on pull requests to main, so #430 to #433 show no CI until their base merges. just check, just typecheck, just test-coverage, just test-release-tooling, and just validate-commits pass locally on each branch.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Release preview

keycardai-oauth 0.35.2 → 0.36.0 (minor)

  • fix(keycardai-oauth): a token response classifies by status first
  • Authorization-code exchange and refresh now classify a token endpoint
    response the way the device grant does. A 2xx is a success and must
    have access_token, so a 2xx with an error member is invalid_response.
    Any other status is an error: the grant's OAuth error class when the
    body is an OAuth error (RFC 6749 Section 5.2), OAuthHttpError
    otherwise. A 3xx was parsed as a success before.
  • fix(keycardai-oauth): refresh classifies by status first and never guesses the token endpoint
    • RefreshGrantError keeps the response's status_code. A 429 or 5xx is
      retryable whatever the code, as base.md Retryability requires.
      Otherwise invalid_grant is not retryable, and every other code
      follows OAuthProtocolError.
  • refresh_authorization with metadata whose token_endpoint is absent or
    empty raises ConfigError before any request. An empty value no longer
    falls through to a convention-derived endpoint. It raised ValueError
    for an absent value before.
  • The discovered-metadata check that discovery already enforces is
    removed, and the docstrings name the errors raised: discovery
    failures, and ConfigError for an unknown ClientSecret zone.
  • feat(keycardai-oauth): refresh with a credential
  • Adds the credential option to the refresh step in Authorization Code
    with PKCE (spec-version 5). AsyncClient.refresh_token_grant and
    refresh_authorization take credential=. The credential's client
    authentication is called with the token endpoint, and its headers and
    form fields go on the request in place of the client's auth strategy
    and the body client_id.
  • credential together with client_id (or client_secret on
    refresh_authorization), or a credential without client authentication,
    raises ConfigError before any request. refresh_authorization's client_id
    is optional and required only without credential.
  • The sync Client does not take a credential, because credentials are
    async only.
  • fix(keycardai-oauth): ClientAuthentication repr leaves out its secrets
  • headers and form_fields hold a Basic header or a client assertion.
    repr() printed both, so a traceback that captures locals showed the
    client secret. Both fields now use field(repr=False).
  • feat(keycardai-oauth): client authentication on credentials
  • Adds the client-authentication operation from the base spec's
    Credential operations section. ClientSecret, WebIdentity, and
    WorkloadIdentity implement ClientAuthenticator:
    • client_authentication(issuer=, endpoint=) returns a
      ClientAuthentication with the headers and form fields that
      authenticate one request. It never includes a grant parameter.
  • ClientSecret returns the Basic header for the issuer's zone. A
    multi-zone credential raises KeyError for an unknown zone.
  • WebIdentity signs a new assertion per call, with aud set to the
    endpoint and iss and sub set to the new client_id option.
    audience_config does not apply. Without client_id it raises
    ConfigError.
  • WorkloadIdentity returns the source's token, and client_id when
    configured.
  • ClientAuthenticator is a runtime-checkable Protocol separate from
    ApplicationCredential, so credentials implemented outside the SDK keep
    working. require_client_authenticator raises ConfigError for a
    credential without it.
  • WebIdentity token exchange and set_client_config use the auth
    context's resource_client_id when present, and the client_id option
    otherwise.
  • fix(keycardai-oauth): percent-encode the client ID and secret in HTTP Basic
  • RFC 6749 Section 2.3.1 requires the client ID and secret to be encoded
    before they go into the HTTP Basic credential. BasicAuth.apply_headers
    encodes each one with urllib.parse.quote(value, safe=""). A space
    becomes %20, which form decoders and decodeURIComponent both read as a
    space.
  • Keycard zones percent-decode each half (svc-sts
    packages/w3/src/auth/basic.js), so a client ID with a colon or a secret
    with a percent sign now authenticates. A server that does not decode
    the Basic credential rejects a client ID or secret with a character
    outside A-Z a-z 0-9 - . _ ~.
  • Every Basic header in the SDK comes from BasicAuth, including
    MultiZoneBasicAuth, ClientSecret, and the PKCE helpers.
  • Follows typescript-sdk bump: keycardai-oauth → 0.32.0 #338 and go-sdk docs(mcp,mcp-fastmcp): add hello world server examples #59. ECO-486.

No other package releases.


This comment was automatically generated by the release preview workflow.

@cmars
cmars marked this pull request as ready for review November 16, 2026 23:16

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

I reviewed this PR and didn't find any bugs. It changes how the refresh-token grant authenticates the client at the token endpoint, so a human should still look at it.

What was reviewed:

  • The credential= path in AsyncClient.refresh_token_grant: it rejects client_id, swaps in NoneAuth, and the credential's headers and form fields are merged in build_refresh_token_http_request. Combined with NoneAuth, nothing from the client's own auth strategy gets into the request.
  • The removed pre-request token_endpoint check in refresh_authorization: discovery in AsyncClient still raises AuthorizationServerDiscoveryError when token_endpoint is missing, which matches the docstring.
  • RefreshGrantError.status_code is passed in through functools.partial, and 429/5xx are now checked before invalid_grant in retryable.
Extended reasoning...

The change adds credential-based client authentication (ClientSecret, WebIdentity, WorkloadIdentity) to the refresh-token grant in keycardai-oauth, in client.py, operations/_authorize.py and pkce/web.py. It also changes how refresh errors are classified as retryable, and adds about 260 lines of tests. The security-sensitive part is the token-endpoint client authentication: the credential's headers and form fields replace the client's auth strategy. Because it changes an auth path and the API (credential is async-only, unlike the sync Client), I'm deferring to a human instead of approving, even though no bugs were found.

cmars and others added 3 commits November 17, 2026 11:42
Adds the credential option to the refresh step in Authorization Code
with PKCE (spec-version 5). AsyncClient.refresh_token_grant and
refresh_authorization take credential=. The credential's client
authentication is called with the token endpoint, and its headers and
form fields go on the request in place of the client's auth strategy
and the body client_id.

credential together with client_id (or client_secret on
refresh_authorization), or a credential without client authentication,
raises ConfigError before any request. refresh_authorization's client_id
is optional and required only without credential.

The sync Client does not take a credential, because credentials are
async only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…esses the token endpoint

- RefreshGrantError keeps the response's status_code. A 429 or 5xx is
  retryable whatever the code, as base.md Retryability requires.
  Otherwise invalid_grant is not retryable, and every other code
  follows OAuthProtocolError.
- refresh_authorization with metadata whose token_endpoint is absent or
  empty raises ConfigError before any request. An empty value no longer
  falls through to a convention-derived endpoint. It raised ValueError
  for an absent value before.
- The discovered-metadata check that discovery already enforces is
  removed, and the docstrings name the errors raised: discovery
  failures, and ConfigError for an unknown ClientSecret zone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Authorization-code exchange and refresh now classify a token endpoint
response the way the device grant does. A 2xx is a success and must
have access_token, so a 2xx with an error member is invalid_response.
Any other status is an error: the grant's OAuth error class when the
body is an OAuth error (RFC 6749 Section 5.2), OAuthHttpError
otherwise. A 3xx was parsed as a success before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cmars
cmars force-pushed the casey/eco-486-refresh branch from 4e5f6c9 to 3663350 Compare November 17, 2026 18:30

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted. Nothing in this review needs a push before merging.

@Larry-Osakwe Larry-Osakwe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Classifier looks right. Two things inline: one compat break and one README gap I think people will hit.

if metadata.token_endpoint is None:
raise ValueError(
"Authorization server metadata is missing token_endpoint"
if not metadata.token_endpoint:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This was a ValueError in 0.33.0 and ConfigError isn't one, so a caller doing except ValueError stops catching it under a plain feat. Could it subclass ValueError the way WebIdentityConfigurationError does?

Comment thread packages/oauth/README.md
The same grant is available on `AsyncClient` and `Client` as
`refresh_token_grant(refresh_token=..., client_id=..., resources=..., scopes=...)`.

To refresh with an application credential (`ClientSecret`, `WebIdentity`, or

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Existing WebIdentity setups don't pass client_id= because they relied on resource_client_id from the auth context. The first refresh with one of those raises ConfigError. A line here saying refresh needs client_id= would save a support round trip.

@cmars
cmars merged commit 8b2f677 into main Nov 17, 2026
29 checks passed
@cmars
cmars deleted the casey/eco-486-refresh branch November 17, 2026 23:32
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.

2 participants