Skip to content

fix(keycardai-oauth): percent-encode the client ID and secret in HTTP Basic - #429

Merged
cmars merged 1 commit into
mainfrom
casey/eco-486-basic-auth
Nov 17, 2026
Merged

cmars merged 1 commit into
mainfrom
casey/eco-486-basic-auth

Conversation

@cmars

@cmars cmars commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

RFC 6749 section 2.3.1 requires the client ID and secret to be encoded before they go into the HTTP Basic credential. HTTP.basic_authorization sent them as is, so a client ID with a colon split in the wrong place on the server, and a secret with % decoded to a different value on a Keycard zone.

Each value is now percent-encoded. ASCII letters, digits, and -._~ stay as they are, a space becomes %20, and every other UTF-8 byte becomes %HH. Keycard zones decode each half with decodeURIComponent (svc-sts packages/w3/src/auth/basic.js), and a form decoder reads the same value back.

Every Basic header in the gems goes through HTTP.basic_authorization: ClientSecret, TokenExchangeClient, ClientCredentialsClient, exchange_authorization_code, and refresh_authorization.

Compatibility

A client ID or secret with a character outside A-Z a-z 0-9 - . _ ~ goes on the wire percent-encoded. A server that does not decode the Basic credential, contrary to RFC 6749, rejects such a client.

Spec unit test rows covered

Spec Row Test
client-secret.md (spec-version 3) 8 client_secret_spec.rb, "8: HTTP Basic percent-encodes ...": the spec's vector on each of the five operations, and a round trip through a percent decoder and a form decoder for a colon, base64 characters, a space, %41, !*'(), and non-Latin-1 text

Linear: ECO-487.

STACK

Stack

Replaces #427. Merge in order:

  1. fix(keycardai-oauth): percent-encode the client ID and secret in HTTP Basic #429 (this PR)
  2. feat(keycardai-oauth): client authentication on credentials #430
  3. feat(keycardai-oauth): refresh with a credential #431
  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

Copy link
Copy Markdown
Contributor

Release preview

keycardai-oauth 0.35.2 → 0.35.3 (patch)

  • 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 added this pull request to stack #434 November 16, 2026 22:52
@cmars
cmars marked this pull request as ready for review November 16, 2026 23:02
Comment on lines +83 to +85
client_id = quote(self.client_id, safe="")
client_secret = quote(self.client_secret, safe="")
credentials = f"{client_id}:{client_secret}"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔴 Clients whose secret contains +, /, =, : or % will fail to authenticate against non-Keycard servers that do not percent-decode Basic credentials. The same happens to callers who already pre-encode their secrets. apply_headers now always runs quote(..., safe="") on both halves, and nothing turns this off. This follows from the stated purpose, but BasicAuth is the generic client auth for any issuer. Fix: keep encoding as the default and add a constructor option (for example percent_encode=False) that sends credentials raw. Document it in the README's BasicAuth section.

Why this was flagged

Trigger: a caller uses BasicAuth(client_id, client_secret) or MultiZoneBasicAuth, through Client/AsyncClient or the pkce helpers. The secret contains a reserved character, such as a base64-style secret with +, / or =, and the authorization server compares the raw Basic credential without decoding it. Many deployed servers do this, and the README's own example points at a generic https://oauth.example.com. At auth.py:83-85, the new code sends ab%2B%2Fc%3D where the base branch sent ab+/c=. Those servers now return invalid_client for every token request (client credentials, token exchange, authorization code, refresh) that worked on the base branch. A caller who worked around this by pre-encoding gets double-encoded (%25..) values. The PR description treats non-decoding servers as an accepted compatibility cost. But the class has no flag, subclass hook or other escape hatch, so affected users can only pin the old version or reimplement the auth strategy.

Verification: In packages/oauth/src/keycardai/oauth/http/auth.py:83-85 the encoding runs unconditionally. The constructor takes no flag to turn it off. On the base branch, the line was credentials = f"{self.client_id}:{self.client_secret}". Users whose secrets contain reserved characters and whose server does not decode the credential will get invalid_client errors after upgrading.

… 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 #338 and go-sdk #59. ECO-486.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cmars
cmars force-pushed the casey/eco-486-basic-auth branch from 226d7a1 to 654b79b Compare November 16, 2026 23:07

@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.

Code review found no new issues

No new issues were found in this update; 1 finding from earlier reviews is still open above.

Still open from earlier reviews (1):

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.

@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.

Encoding matches Java and Go, and svc-sts decodes each half, so all four SDKs land on the same secret.

@cmars
cmars merged commit 279049d into main Nov 17, 2026
16 checks passed
@cmars
cmars deleted the casey/eco-486-basic-auth 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