fix(keycardai-starlette): return 401/503 (not 500) for JWKS errors

[Larry-Osakwe]

Python-side of keycardai/typescript-sdk#119.

Problem

KeycardAuthBackend.authenticate() (packages/starlette/src/keycardai/starlette/middleware/bearer.py) caught only InvalidTokenError. JWKS errors are a separate tree — JWKSError/JWKSKeyNotFoundError extend OAuthError(Exception); JWKSDiscoveryError/JWKSUriValidationError extend OAuthServerError(Exception) — none of which is InvalidTokenError or a Starlette AuthenticationError.

So they escaped AuthenticationMiddleware → ServerErrorMiddleware → HTTP 500 with no WWW-Authenticate. A token whose kid is absent from the JWKS (forged, or rotated out), or an unreachable/non-2xx JWKS or discovery endpoint, all returned 500 instead of a clean 401/503.

Fix

Map the JWKS error classes at the auth boundary:

Error	Response
JWKSKeyNotFoundError	401 invalid_token + WWW-Authenticate challenge (client re-runs authorization)
JWKSError / JWKSDiscoveryError / JWKSUriValidationError	503, small body

_build_unauthorized_response now emits a bare 503 body with no WWW-Authenticate header for 5xx — that challenge isn't one a client can satisfy by re-authenticating.

Errors outside these classes are unchanged: they remain genuine unexpected errors and are not swallowed.

Tests

Added to test_provider.py: JWKSKeyNotFoundError → 401 challenge; JWKSFetchError / JWKSDiscoveryError (parametrized) → 503 with no challenge header. 46/46 green.

Parity

Companion PR fixes the TypeScript SDK (keycardai/typescript-sdk#123). The Go SDK is not affected (its verifier funnels all key-resolution failures into InvalidTokenError and the middleware has a catch-all default).

[github-actions]

📦 Release Preview

This analysis shows the expected release impact:

📈 Expected Version Changes

keycardai-starlette: 0.10.0 → 0.11.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-starlette",
    "package_dir": "packages/starlette",
    "has_changes": true,
    "current_version": "0.10.0",
    "next_version": "0.11.0",
    "increment": "MINOR"
  }
]

📝 Changelog Preview

Changelog for keycardai:
## Unreleased

## 0.3.0-keycardai (2026-06-10)


- build(keycardai): take examples out of the uv workspace (#151)
- Examples are globbed in as workspace members via packages/*/examples/*, so
every root uv operation generates their package metadata. uv 0.11.20 (released
2026-06-10, pulled in by CI's unpinned setup-uv) fails that generation on
Linux during the nested `uv run cz changelog`, breaking the Merge to Main
detect-changes job even though `uv sync` and the PR checks pass. Examples ship
their own lockfiles and only pin their parent package, so they are standalone
projects: exclude them from the workspace and keep their path sources. Root
operations now resolve only the workspace packages.
- Also send changelog.py error output to stderr so a failed detect-changes shows
in the CI log instead of being captured into $(just detect-changes).
- Co-authored-by: GitHub Action <action@github.com>
- build(keycardai): use workspace sources for keycard deps in examples (#150)
- uv 0.11.20 rejects a workspace member overriding a workspace source with a
path. Each example declared keycardai-<pkg> = { path = "../../", editable =
true } while the root workspace already declares { workspace = true }. Switch
the examples to { workspace = true } (uv 0.11.20 guidance). No uv pin; no
lockfile change. Unblocks lint-and-test / validate-commits for all PRs.
- Co-authored-by: GitHub Action <action@github.com>

## 0.2.0-keycardai (2025-09-10)

## 0.1.0-keycardai (2025-09-07)


- feat(keycardai): initial release
Changelog for keycardai-oauth:
## Unreleased

## 0.21.0-keycardai-oauth (2026-07-15)


- feat(keycardai-oauth): add WorkloadIdentity credential with pluggable subject token sources (#191)
- * feat(keycardai-oauth): add WorkloadIdentity credential with pluggable subject token sources
- One generic WorkloadIdentity credential owns the exchange contract
(jwt-bearer client assertion, no basic auth, fresh fetch per exchange,
no caching). A one-method SubjectTokenSource protocol is the only
per-platform code: FileTokenSource (EKS, AKS, Kubernetes projected
tokens), GCPMetadataTokenSource (GKE, GCE, Cloud Run), FlyTokenSource
(Fly Machines), or any bare callable.
- The optional client_id constructor argument is sent as the client_id
form parameter alongside the assertion; token-federation application
credentials (KEP 108) are resolved by it.
- EKSWorkloadIdentity becomes a deprecated subclass wrapping its existing
discovery and read logic as a source, with unchanged signature,
EKS-only env discovery, and unchanged error types, which are now
subclasses of the new WorkloadIdentity{Configuration,Runtime}Error.
- Implements the workload-identity spec (keycard-sdk-spec#39). ECO-110.
- * refactor(keycardai-oauth): rename IdentityTokenSource from SubjectTokenSource
- The source returns the platform-issued OIDC identity token, which the
credential attaches as the client assertion. Naming it a subject token
collided with TokenExchangeRequest.subject_token, which carries the
inbound user token on the RFC 8693 exchange.
- * docs(keycardai-oauth): note that sync identity token sources must not block
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.20.0-keycardai-oauth (2026-06-15)


- feat(keycardai-oauth)!: key multi-zone credentials by issuer and add a per-call issuer selector
- Multi-zone ClientSecret dicts and MultiZoneBasicAuth are now keyed by
the zone issuer URL (trailing slashes normalized), with accessors
has_issuer, get_configured_issuers, and get_auth_for_issuer.
AuthStrategy.apply_headers accepts an optional issuer selector:
single-zone strategies ignore it, MultiZoneBasicAuth resolves that
issuer fail-closed and raises when called without one. The selector
threads through the HTTP context and all operation builders, defaulting
to the client issuer, and exchange_token / client_credentials_grant
accept a per-call issuer keyword.
- BREAKING CHANGE: multi-zone credential maps are keyed by issuer URL
instead of zone id; zone-keyed accessors are renamed to issuer terms and
get_headers_for_zone is removed.
- feat(keycardai-oauth): add issuer-direct entry to the PKCE authenticate flow (#171)
- authenticate accepts either issuer (used directly, no metadata fetch) or
www_authenticate_header (the RFC 9728 challenge-driven path); exactly
one must be provided. resource_url is now optional overall and required
only in challenge mode. The challenge-to-issuer resolution is exposed as
resolve_issuer_from_challenge in keycardai.oauth.pkce.
- Co-authored-by: GitHub Action <action@github.com>

## 0.19.0-keycardai-oauth (2026-06-12)


- feat(keycardai-oauth): add client_credentials_grant operation (#166)
- Adds an RFC 6749 section 4.4 client credentials grant to the general
client. New ClientCredentialsRequest model (resource, scope,
client_assertion, client_assertion_type), a client_credentials operation
module mirroring the token-exchange transport contract, and a
client_credentials_grant method on both Client and AsyncClient that
accepts a request object or keyword arguments and authenticates via the
client's configured credential. ECO-43.
- Co-authored-by: GitHub Action <action@github.com>

## 0.18.2-keycardai-oauth (2026-06-12)


- fix(keycardai-oauth): discover KEYCARD_EKS_WORKLOAD_IDENTITY_TOKEN_FILE in EKS workload identity (#164)
- EKSWorkloadIdentity documents KEYCARD_EKS_WORKLOAD_IDENTITY_TOKEN_FILE
as the first env var checked during token-file discovery, but the
default list only contained the two AWS variables. The variable is now
searched first, matching the docstring and the TS and Go SDKs. ECO-40.
- Co-authored-by: GitHub Action <action@github.com>

## 0.18.1-keycardai-oauth (2026-06-12)


- fix(keycardai-oauth): add client_assertion kwargs to sync exchange_token overload (#162)
- * fix(keycardai-oauth): add client_assertion kwargs to sync exchange_token overload
- The sync exchange_token kwargs overload was missing the client_assertion
and client_assertion_type parameters that the async overload declares.
The runtime path already accepted them via **token_exchange_args; this
aligns the typed surface so type checkers and IDEs accept the kwargs on
the sync client too. ECO-41.
- * fix(keycardai-oauth): make subject_token_type optional in exchange_token kwargs overloads
- TokenExchangeRequest defaults subject_token_type to the access-token
type, but both kwargs overloads declared it required. The overloads now
mark it optional so the typed surface matches the model default.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.18.0-keycardai-oauth (2026-06-11)


- feat(keycardai-oauth): expose get_client_jwks_url on the WebIdentity credential (#160)
- WebIdentity exposed only get_jwks(); the client JWKS URL helper lived on the
internal key manager, not the credential. Add get_client_jwks_url(resource_server_url)
to the credential, delegating to the key manager, so the public JWKS getter and
the JWKS-URL helper are both on the credential, matching the TS getClientJwksUrl
and Go ClientJWKSURL accessors.
- Part of the web-identity spec JWKS-accessor-surface row (ECO-39).
- Co-authored-by: GitHub Action <action@github.com>

## 0.17.0-keycardai-oauth (2026-06-11)


- feat(keycardai-oauth)!: RFC-minimal client registration and typed registration errors (#156)
- ClientRegistrationRequest no longer injects opinionated defaults
(token_endpoint_auth_method, redirect_uris, grant_types, response_types,
scope) and no longer requires client_name. Per RFC 7591 all client metadata
is optional, so the request sends only the fields the caller sets, matching
the RFC-minimal TypeScript registerClient.
- Registration errors are now typed: on an RFC 7591 section 3.2.2 error (HTTP
4xx with a JSON error body) registration raises OAuthProtocolError carrying
the error code so a caller can branch on it, instead of an opaque
OAuthHttpError with only the raw body. A non-structured 4xx still raises
OAuthHttpError.
- Resolves the request-defaults, client_name-requiredness, and error-surfacing
rows of the dynamic-client-registration spec (ECO-44).
- Co-authored-by: GitHub Action <action@github.com>

## 0.16.0-keycardai-oauth (2026-06-11)


- feat(keycardai-oauth)!: raise typed InvalidTokenError and enforce issuer allowlist before key resolution (#154)
- * feat(keycardai-oauth)!: raise typed InvalidTokenError and enforce issuer allowlist before key resolution
- The verify surface is now fail-closed and typed. `verify_token` and
`verify_token_for_zone` return an `AccessToken` and raise the new
`InvalidTokenError` (RFC 6750 `invalid_token`) on any verification failure;
they no longer return `None`.
- Cheap policy checks (trusted issuer, expiration) now run on the unverified
payload before any network key resolution, so a token with an untrusted `iss`
is rejected without triggering JWKS discovery or fetch. The issuer is checked
against a trusted allowlist: `issuer` now accepts `str | list[str]`. JWKS keys
are cached per `(issuer, kid)` so distinct issuers cannot collide on a shared
`kid`, and discovery resolves keys for the validated token issuer.
- Infra failures (JWKS discovery/fetch) now propagate as their typed errors
instead of being collapsed into a generic failure, so a JWKS outage surfaces
as a server error rather than a misleading invalid-token result.
- Resolves the verify-contract, ordering, and issuer-allowlist rows of the
jwt-signing-and-verification spec (ECO-36).
- * fix(keycardai-starlette): catch InvalidTokenError from token verification
- The bearer backend relied on `verify_token` returning `None` on failure. The
verifier now raises `InvalidTokenError`, so the backend catches it and maps it
to the RFC 6750 `invalid_token` 401 challenge. JWKS infrastructure errors are
no longer caught here, so a key-resolution outage surfaces as a server error
rather than a 401.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.3-keycardai-oauth (2026-06-10)


- fix(keycardai-oauth): expose ResourceAccessError context attributes (#149)
- ResourceAccessError now stores resource / error_type / available_resources /
error_details as direct instance attributes, alongside the existing details
dict, so handlers can inspect the error context without unpacking details.
AccessContext.get_errors is annotated dict[str, Any] since it always returns a
dict, never None.
- Closes the access-context net-new gaps surfaced by the parity verification.
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.2-keycardai-oauth (2026-06-10)


- fix(keycardai-oauth): raise typed JWKS errors from get_jwks_key (#147)
- get_jwks_key raised bare ValueError, and its outer except flattened every
failure into one generic "Failed to fetch JWKS" ValueError. It now raises
typed, catchable errors: JWKSFetchError (endpoint unreachable or non-2xx)
and JWKSKeyNotFoundError (kid absent from the set), under a JWKSError base
in keycardai.oauth.exceptions (exported from the package root). Unexpected
errors are wrapped as JWKSFetchError; typed errors propagate unchanged.
- Defined in the top-level exceptions module so the utils layer can import
them without the server-package circular import. Matches the canonical
error model and the TS typed JWKS errors.
- Part of the SDK parity effort (ECO-35 / ECO-32).
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.1-keycardai-oauth (2026-06-09)


- fix(keycardai-oauth): evict oldest JWKS key on overflow instead of clearing the cache (#145)
- The key cache cleared all entries when it hit max_size (10), so a verifier
serving more than 10 kids would thrash. It now evicts the single oldest entry
and the bound is raised to 256. Closes the remaining mechanical ECO-35 row on
key-cache eviction (bounded plus partial eviction; exact order is
implementation-defined per the spec).
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.0-keycardai-oauth (2026-06-09)


- feat(keycardai-oauth): converge JWKS caching to spec (discovery TTL, fetch timeout, inflight de-dup) (#143)
- Converges TokenVerifier JWKS caching to specs/jwt-jwks/jwks-caching.md (ECO-35):
- - discovery_ttl knob (default 1h): the discovered jwks_uri is cached with a
  TTL and re-discovered after expiry, not for the verifier lifetime.
- fetch_timeout knob (default 10s): bounds discovery and JWKS fetches;
  get_jwks_key gained an optional timeout argument.
- inflight de-duplication: concurrent cold-cache lookups for the same
  (zone, kid) share one discovery and one JWKS fetch.
- key_ttl: per-key TTL knob renamed to the canonical key_ttl; cache_ttl
  kept as a deprecated keyword alias.
- Key-cache eviction policy and error taxonomy (the remaining ECO-35 rows)
need a canonical decision and are left for a follow-up.
- Co-authored-by: GitHub Action <action@github.com>

## 0.14.0-keycardai-oauth (2026-06-02)


- test(keycardai-oauth): use generic scope in exchange request_scopes tests
- Replace the databricks-specific scope with a generic "read".
- feat(keycardai-oauth): add request_scopes to exchange_tokens_for_resources
- Accept an optional per-resource OAuth scope and apply it across all three
exchange paths: impersonation (client.impersonate(scope=...)), the
application-credential request, and the basic RFC 8693 request. Accepts a
str, list[str], or per-resource dict.

## 0.13.1-keycardai-oauth (2026-06-02)


- fix(keycardai-oauth): require kid in TokenVerifier, matching the TypeScript verifier (#132)
- The TS verifier rejects any token without a kid header; Python silently fell
back to the single JWKS key. For cross-SDK parity (and since Keycard always
issues a kid), Python now rejects a missing kid with TokenValidationError
before key resolution. Removes the optional-in-one / required-in-the-other
surprise.
- Part of ECO-35.
- Co-authored-by: GitHub Action <action@github.com>

## 0.13.0-keycardai-oauth (2026-06-02)


- fix(keycardai-oauth): enforce jwks_uri same-origin with issuer in TokenVerifier (#131)
- A discovered jwks_uri must share the issuer origin before any key is fetched,
matching the TypeScript keyring (assertSameOrigin). This guards against a
tampered or misconfigured discovery document pointing key resolution at an
attacker-controlled origin. Explicit jwks_uri (trusted config) is unaffected.
- Adds JWKSUriValidationError, raised on mismatch.
- Closes ECO-34.
- Co-authored-by: GitHub Action <action@github.com>

## 0.12.0-keycardai-oauth (2026-05-07)


- feat(keycardai-oauth)!: pass error context through AccessContext.access(), rename to get_resource_error (#114)
- * feat(keycardai-oauth)!: pass error context through AccessContext.access(), rename to get_resource_error
---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.11.0-keycardai-oauth (2026-04-28)


- feat(keycardai-oauth): add high-level PKCE user-login flow (ACC-229) (#101)
- * feat(keycardai-oauth): add high-level PKCE flow client (ACC-229)
- First step of the keycardai-agents decomposition (ACC-229..232). Per the
revised KEP, the OAuth PKCE user-login flow is generic OAuth code with no
agents-specific concerns and belongs in keycardai-oauth next to the rest
of the OAuth client primitives.
- New module keycardai.oauth.pkce:
- - PKCEClient orchestrates the full authorization-code-with-PKCE flow:
  parse the WWW-Authenticate challenge (RFC 9728), fetch protected resource
  and authorization server metadata (RFC 8414), open the browser at the
  authorize endpoint, capture the redirect via a local callback server,
  and exchange the code at the token endpoint. Returns the token endpoint
  response dict directly.
- OAuthCallbackServer is the loopback redirect catcher (RFC 8252) used by
  PKCEClient; exported separately so callers running their own flow on top
  of the lower-level PKCEGenerator + build_authorize_url primitives can
  reuse the callback machinery.
- 7 new tests cover header parsing, discovery error paths, the happy-path
  flow, and confidential vs public client auth on the token endpoint.
- keycardai-agents changes:
- - AgentClient now composes PKCEClient instead of carrying its own copy of
  the auth flow. AgentClient.authenticate(...) is preserved as a thin shim
  that returns the access_token string and updates the per-service token
  cache, so existing /invoke retry-on-401 behavior is unchanged.
- AgentClient drops ~370 lines of duplicated PKCE/discovery/callback code.
- keycardai.agents.client.oauth re-exports OAuthCallbackServer through a
  module __getattr__ that emits a DeprecationWarning pointing at the new
  canonical import path.
- Stale tests in test_agent_client_oauth.py that exercised AgentClient
  private methods (_extract_resource_metadata_url, _fetch_resource_metadata,
  _fetch_authorization_server_metadata) removed; equivalent contracts now
  live in the keycardai-oauth PKCE test suite.
- Verified: oauth 215/215 (was 208 + 7 new), agents 81/81 (was 85 - 4 removed
implementation tests), mcp 560/560, starlette 49/49, ruff clean.
- Stacked on #100 (ACC-236 a2a-sdk pin) so the agents test suite can run
during validation.
- * fix(keycardai-oauth): address review findings on PKCE move
- Three small fixes from the review of #101:
- 1. PKCEClient now accepts an optional injected httpx.AsyncClient. AgentClient
   passes its existing http_client through, so a single connection pool covers
   both the agent service calls and the OAuth flow. close() only closes the
   client it owns. Restores the one-pool-per-AgentClient behavior from main.
- 2. Drop the no-op rstrip("/") + "/" round-trip in PKCEClient.authenticate
   when building the authorization server discovery URL.
- 3. Assert the discovery URL path in test_authenticate_completes_full_flow.
   The previous test stubbed http_mock.get with side_effects but never
   verified what URLs were passed; a typo from oauth-authorization-server
   to openid-configuration would have gone unnoticed.
- * refactor(keycardai-oauth): collapse PKCEClient into a flow function on AsyncClient
- Per Kamil review feedback (#101): a separate PKCEClient sitting next to
AsyncClient invited "which client do I use?" The OAuth-server-facing
operations belong on the existing AsyncClient.
- Changes:
- - keycardai.oauth.pkce.PKCEClient (class) -> keycardai.oauth.pkce.authenticate
  (module-level async function). One-shot per user login, no state worth
  preserving across calls.
- The function uses AsyncClient internally for server metadata discovery
  (RFC 8414) and code exchange. AsyncClient is now the only thing in
  keycardai.oauth that talks to OAuth servers as a client.
- AsyncClient.exchange_authorization_code (and Client + the underlying
  operations._authorize helpers) gain an optional resource= parameter so
  RFC 8707 tokens still work through the canonical path.
- The pkce module retains the user-flow concerns: RFC 9728 challenge
  parsing, resource metadata fetch (paired with the protected resource,
  not the OAuth server), browser launch, and the loopback callback server
  (RFC 8252).
- AgentClient drops the cached _pkce instance and just calls the function
  per /invoke retry, passing its own httpx.AsyncClient through for the
  resource metadata fetch.
- Tests rewritten for the function shape: 7/7 passing, same coverage
  (header parsing, discovery error paths, happy path with resource
  indicator, public vs confidential auth on the token endpoint).
- Verified: oauth 215/215, agents 81/81, mcp 560/560, starlette 49/49.
ruff clean.

## 0.10.0-keycardai-oauth (2026-04-24)


- fix(keycardai-oauth): fall back to legacy ./mcp_keys dir with deprecation warning
- Switch WebIdentity default storage_dir back to ./server_keys (aligning
with the protocol-agnostic naming from this PR), but transparently fall
back to ./mcp_keys when no storage_dir is passed, ./server_keys does not
exist, and ./mcp_keys does. The fallback emits a DeprecationWarning
pointing at the explicit configuration or migration paths.
- This preserves zero-config upgrades for existing keycardai-mcp services
(they keep finding their existing keys) while giving new installs the
new default. The fallback will be removed in a future release.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- fix(keycardai-oauth): preserve mcp storage defaults, move server tests
- Address PR #95 review comments from cmars:
- 1. Revert WebIdentity default storage_dir to "./mcp_keys" and key_id
   prefix to "mcp-server-". Changing these would silently break existing
   keycardai-mcp services on upgrade: they would look for keys in a new
   empty directory and regenerate identity, losing their registered client
   identity with Keycard.
- 2. Move oauth-server-specific tests (test_verifier, test_cache,
   test_application_identity -> test_credentials) from packages/mcp/tests
   to packages/oauth/tests/keycardai/oauth/server/ so coverage lives
   with the canonical oauth.server modules.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- fix(keycardai-oauth): address PR review findings
- - Add token_exchange module with exchange_tokens_for_resources()
  orchestration (KEP Tier 1 gap)
- Rename WebIdentity param mcp_server_name -> server_name with
  backward-compatible alias; default storage dir ./mcp_keys -> ./server_keys
- Add mcp_server_url/missing_mcp_server_url backward-compat aliases
  to AuthProviderConfigurationError (prevents breaking fastmcp callers)
- Fix _get_kid_and_algorithm returning list instead of tuple
- feat(keycardai-oauth): add server subpackage with framework-free primitives
- Extract protocol-agnostic server components from keycardai-mcp into
keycardai.oauth.server per the Protocol-Agnostic SDK KEP (Tier 1).
- New keycardai.oauth.server modules:
- access_context: AccessContext for non-throwing token access
- credentials: ApplicationCredential, ClientSecret, WebIdentity, EKSWorkloadIdentity
- verifier: TokenVerifier with local AccessToken model (no MCP dependency)
- exceptions: OAuthServerError base + all framework-free exceptions
- _cache: JWKSCache/JWKSKey for JWKS key caching
- client_factory: ClientFactory protocol + DefaultClientFactory
- private_key: PrivateKeyManager, FilePrivateKeyStorage
- keycardai-mcp changes:
- Server auth modules now re-export from keycardai.oauth.server
- MCPServerError is an alias for OAuthServerError
- MissingContextError stays MCP-specific (references FastMCP Context)
- All existing imports continue to work (no breaking changes)
- Tests updated to patch canonical module paths

## 0.9.0-keycardai-oauth (2026-04-02)


- feat(keycardai-oauth): support for impersonation token exchange
- - Add substitute-user token type and unsigned JWT builder
- Add impersonate method to Client and AsyncClient
- Add user_identifier callback to MCP grant decorator
- Add impersonation token exchange example

## 0.8.0-keycardai-oauth (2026-04-02)


- feat(keycardai-oauth): add authorization code exchange and PKCE support
- - Implement PKCE code verifier, challenge generation, and validation
- Add authorization code exchange operation (sync and async)
- Add build_authorize_url for constructing OAuth authorize URLs
- Add exchange_authorization_code to Client and AsyncClient
- Add get_endpoints/endpoints property to expose resolved endpoints
- Add id_token field to TokenResponse

## 0.7.0-keycardai-oauth (2026-03-06)


- fix(keycardai-oauth): update test to expect OAuthProtocolError for structured error bodies
- feat(keycardai-oauth)!: detailed error reporting
- BREAKING CHANGE: Token exchange HTTP 4xx errors with structured JSON bodies now raise OAuthProtocolError instead of OAuthHttpError. Callers catching OAuthHttpError for these responses must update to catch OAuthProtocolError.

## 0.6.0-keycardai-oauth (2025-11-17)


- feat(keycardai-oauth): client metadata updates

## 0.5.0-keycardai-oauth (2025-09-22)


- feat(keycardai-oauth): client assertion support
- feat(keycardai-oauth): JWKS type support

## 0.4.1-keycardai-oauth (2025-09-17)


- fix(keycardai-oauth): audience checks

## 0.4.0-keycardai-oauth (2025-09-16)


- feat(keycardai-oauth): multi-zone authentication strategy
- feat(keycardai-oauth): jwt capabilities

## 0.2.0-keycardai-oauth (2025-09-10)


- feat(keycardai-oauth): remove the impersonation logic

## 0.1.0-keycardai-oauth (2025-09-07)


- feat(keycardai-oauth): initial release
Changelog for keycardai-starlette:
## Unreleased


- fix(keycardai-starlette): return 401/503 (not 500) for JWKS errors
- KeycardAuthBackend.authenticate() caught only InvalidTokenError. JWKS
errors are a separate tree (JWKSError/JWKSKeyNotFoundError extend
OAuthError(Exception); JWKSDiscoveryError/JWKSUriValidationError extend
OAuthServerError(Exception)), none of which is InvalidTokenError or a
Starlette AuthenticationError. They escaped AuthenticationMiddleware to
ServerErrorMiddleware, yielding HTTP 500 with no WWW-Authenticate.
- So a token whose kid is absent from the JWKS (forged, or rotated out),
or an unreachable/non-2xx JWKS or discovery endpoint, returned 500
instead of a 401 (client should re-auth) or 503 (transient). This is the
Python-side of the same bug reported against the TypeScript SDK (#119).
- Map the JWKS error classes at the auth boundary:
- JWKSKeyNotFoundError -> KeycardAuthError invalid_token (401 + challenge)
- JWKSError / JWKSDiscoveryError / JWKSUriValidationError -> 503
- _build_unauthorized_response now emits a bare 503 body with no
WWW-Authenticate header for 5xx, since that challenge is not one a client
can satisfy by re-authenticating.
- Refs keycardai/typescript-sdk#119

## 0.10.0-keycardai-starlette (2026-06-15)


- feat(keycardai-starlette): infer multi-zone from the application credential
- enable_multi_zone defaults to None and is inferred from a multi-zone
ClientSecret; an explicit value overrides. Per-zone credential lookup
uses the zone-scoped issuer URL.

## 0.9.0-keycardai-starlette (2026-06-12)


- fix(keycardai-starlette): return 502 when the upstream AS metadata fetch fails (#170)
- * fix(keycardai-starlette): return 502 when the upstream AS metadata fetch fails
- The authorization-server metadata proxy previously passed the upstream
HTTP status through and mapped connect/timeout errors to 503. All
upstream failures (HTTP error status or any transport error) now respond
502 Bad Gateway with an upstream_error body. Unexpected exceptions still
map to 500.
- * test(keycardai-a2a): expect 502 from the AS metadata proxy on upstream failure
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.8.0-keycardai-starlette (2026-06-12)


- feat(keycardai-starlette)!: align metadata endpoints with the RFC 9728 contract (#168)
- The protected-resource document no longer carries the OAuth client
registration fields (client_id, client_name, token_endpoint_auth_method,
grant_types); it now exposes the standard optional inputs
scopes_supported, resource_name, and resource_documentation, and emits
jwks_uri only when a JWKS is configured. The authorization-server proxy
appends resource=<origin> to the upstream authorization_endpoint.
Metadata and JWKS responses carry Access-Control-Allow-Origin: * and
answer OPTIONS preflight. The upstream metadata fetch timeout is
configurable (as_metadata_timeout, default 10s; was fixed 5s).
- BREAKING CHANGE: the protected-resource document drops the four client
registration fields and jwks_uri is conditional on a configured JWKS.
- Co-authored-by: GitHub Action <action@github.com>

## 0.7.0-keycardai-starlette (2026-06-11)


- fix(keycardai-starlette): emit RFC 6750 insufficient_scope challenge from requires (#158)
- The `requires` decorator raised a bare HTTPException(403) on scope failure,
with no WWW-Authenticate header. It now returns a 403 carrying an RFC 6750
`Bearer error="insufficient_scope"` challenge with the resource_metadata URL
(RFC 9728), matching the 401 anonymous path and the TS/Go route gates. The
status_code argument still controls the failure status (default 403).
- Resolves the scope-failure response-shape row of the route-level-auth-gating
spec (ECO-78).
- Co-authored-by: GitHub Action <action@github.com>

## 0.6.0-keycardai-starlette (2026-06-03)


- feat(keycardai-starlette): add require_authentication to protected_router

## 0.5.0-keycardai-starlette (2026-06-02)


- build(keycardai-starlette): require keycardai-oauth>=0.13.0 for request_scopes
- The grant() decorator now passes request_scopes to
exchange_tokens_for_resources, a parameter added in keycardai-oauth
0.13.0, so raise the dependency floor accordingly.
- feat(keycardai-starlette): thread request_scopes through grant()
- Expose request_scopes on the grant decorator and pass it to
exchange_tokens_for_resources so scope-gated delegation works for
Starlette/FastAPI endpoints.

## 0.4.0-keycardai-starlette (2026-05-01)


- refactor(keycardai-starlette)!: remove deprecated BearerAuthMiddleware shims (ACC-237) (#109)
- Removed deprecated BearerAuthMiddleware shims after all consumers migrated to AuthenticationMiddleware + KeycardAuthBackend, eliminating unused auth code. This is a breaking change—imports for BearerAuthMiddleware and verify_bearer_token now fail.

## 0.3.0-keycardai-starlette (2026-04-27)


- feat(keycardai-starlette): emit DeprecationWarning from BearerAuthMiddleware and verify_bearer_token (#99)
- Closes ACC-234. PR #97 retained the legacy bearer surface as docstring-only deprecated shims so keycardai-mcp and keycardai-agents keep working until they migrate (ACC-235, ACC-229..232). Without a runtime signal, non-MCP downstream users importing these symbols get no notice before the symbols disappear.
- Changes:
- BearerAuthMiddleware.__init__ emits DeprecationWarning pointing at AuthenticationMiddleware + KeycardAuthBackend
- verify_bearer_token emits DeprecationWarning pointing at KeycardAuthBackend
- BearerAuthMiddleware.dispatch passes _from_middleware=True so a single middleware instantiation fires exactly one warning total, not one per request
- New tests: warning fires on init, warning fires on direct verify_bearer_token call, dispatch path does not double-warn
- _create_auth_challenge_response is intentionally not warned: it is underscored, not in __all__, and not re-exported by the keycardai-mcp shims, so no external caller can plausibly hit it directly.
- Verified mcp tests still pass (560/560). Agents tests fail on a pre-existing a2a-sdk import error unrelated to this change.

## 0.2.0-keycardai-starlette (2026-04-26)


- feat(keycardai-starlette): new package for Starlette/FastAPI Keycard integration (#97)
- * feat(keycardai-starlette-oauth): new package for Starlette/FastAPI OAuth middleware
- Implements Tier 2 of the Protocol-Agnostic SDK KEP: a new
keycardai-starlette-oauth package that provides Starlette-specific
middleware and route builders without any MCP dependency.
- New package (packages/starlette-oauth/):
- middleware/bearer.py: BearerAuthMiddleware
- handlers/metadata.py: RFC 9728 + RFC 8414 metadata with local
  ProtectedResourceMetadata model (no mcp.shared.auth dependency)
- handlers/jwks.py: JWKS endpoint handler
- routers/metadata.py: Route builders + protected_router()
- provider.py: AuthProvider with install() and @protect() decorator
- shared/starlette.py: Proxy-aware URL helpers
- keycardai-mcp changes:
- Now depends on keycardai-starlette-oauth (starlette removed from
  direct deps since it comes transitively)
- Server middleware/handlers/routers replaced with re-export shims
- protected_mcp_router wraps protected_router with mcp_app kwarg compat
- All existing imports continue to work
- * refactor(keycardai-starlette): rename from keycardai-starlette-oauth
- Per revised KEP naming decisions: drop the OAuth suffix from the
customer-facing package since it will cover more than just OAuth
(token exchange, policy enforcement, vaulted creds, etc.). The
keycardai-oauth package stays as an internal building block.
- Renames:
- packages/starlette-oauth/ → packages/starlette/
- src/keycardai/starlette_oauth/ → src/keycardai/starlette/
- keycardai-starlette-oauth → keycardai-starlette (PyPI name)
- keycardai.starlette_oauth → keycardai.starlette (import path)
- Updated workspace source, MCP dependency, and all MCP shim imports.
Backward-compat shims in keycardai-mcp continue to work.
- * feat(keycardai-starlette): add smoke tests and fix .well-known middleware bypass
- - Add 22 smoke tests covering metadata routes, AuthProvider install/config,
  and a guarantee that keycardai.starlette has no keycardai.mcp imports.
- Fix BearerAuthMiddleware to skip /.well-known/* paths. Without this,
  AuthProvider.install() (which adds the middleware globally) blocked the
  OAuth discovery endpoints it had just registered — clients got 401 trying
  to learn how to authenticate. Metadata discovery per RFC 9728 §2 must
  remain publicly reachable.
- Add fastapi and httpx to the starlette package test extras.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * chore: adjust coverage thresholds after starlette extraction
- - Add keycardai-starlette to test-coverage and test recipes
- Lower mcp threshold from 65% to 60%: the well-tested server auth code
  moved to keycardai-oauth / keycardai-starlette, leaving a higher
  proportion of under-tested client integrations (CrewAI/LangChain/OpenAI
  adapters at 14-25%) in the denominator. Absolute coverage of the
  remaining code is unchanged; the ratio is what shifted.
- Set starlette threshold to 55% (smoke tests cover the surface area;
  provider.py @protect() decorator and async client init are the main
  gap, tracked as a follow-up)
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * fix(scripts): pass --yes to cz bump in version_preview for new packages
- Commitizen prompts "Is this the first tag created?" when it cannot find an
existing tag matching a package's tag_format. For brand-new packages like
keycardai-starlette that have no tag yet, this prompt EOFs in non-TTY CI
runs and causes release-preview to report an error instead of a version
delta.
- --yes auto-confirms the prompt. Existing packages with prior tags never
see the prompt, so their output is unchanged.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * chore: regenerate uv.lock with uv >= 0.9 format
- Older lock file (generated with uv 0.8.x) failed to parse on CI's newer
uv with "Dependency `pytokens` has missing `source` field but has more
than one matching package". The lock format tightened in 0.9+ to require
explicit source annotations when multiple resolution markers are in play.
- Regenerated with uv 0.11.7. Resolution now succeeds under setup-uv@v4
(unpinned, tracks latest). All package test suites still pass
(oauth 208, starlette 22, mcp 560, mcp-fastmcp 51).
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * ci: wire keycardai-starlette into release workflow tag filter
- The release workflow only triggers on tag patterns explicitly listed in
on.push.tags. Without adding *-keycardai-starlette, tags created by
commitizen for the new package (e.g. 0.1.0-keycardai-starlette) would
not trigger the release job, so nothing would publish to PyPI even if a
Trusted Publisher were configured.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * chore: minimize uv.lock diff to just the keycardai-starlette addition
- The previous regeneration pass rebuilt the lock wholesale and produced
a 5-marker resolution format (splitting python_full_version >= '3.14'
into '3.15' and '3.14.*'). CI's uv 0.11.7 could not parse that,
failing with "pytokens has missing source field but has more than one
matching package" during uv sync --all-extras.
- Revert to origin/main's lock and re-run `uv lock --no-upgrade`, which
adds only the keycardai-starlette workspace member (34-line diff) and
leaves the resolution-markers block identical to main. CI parses it
cleanly; all package test suites pass.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * style: trim verbose comments added during review
- Condense the justfile coverage-threshold note and version_preview.py
--yes flag comment to one sentence each.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * fix(keycardai-starlette): address PR review feedback from cmars
- Seven correctness and style fixes:
- 1. bearer.py: tighten the auth-bypass path match. The previous
   `path.startswith("/.well-known/")` exempted ALL well-known URIs (e.g.
   `/.well-known/change-password`, `assetlinks.json`) from bearer auth.
   Replace with an explicit allowlist of OAuth metadata endpoints
   (`oauth-protected-resource`, `oauth-authorization-server`, `jwks.json`),
   matched as exact paths or delimited subpaths. Cite RFC 9728 §2 / RFC
   8414 §3 as the spec basis.
- 2. provider.py `_get_or_create_client`: the parameter was annotated
   `dict[str, str] | None = None` but every line dereferenced it
   unguarded. Drop the Optional from the signature; callers always pass
   a non-None dict.
- 3. provider.py `__init__`: construct `_init_lock = asyncio.Lock()`
   eagerly instead of lazily. The previous `if self._init_lock is None:
   self._init_lock = asyncio.Lock()` was technically safe in pure
   asyncio (no await between check and assign) but reads as a race
   smell. Eager init removes the question. asyncio.Lock can be created
   outside an event loop in Python 3.10+.
- 4. provider.py docstring: rephrase the AuthProvider class docstring to
   describe what the class does instead of what it lacks ("without any
   MCP dependency").
- 5. handlers/metadata.py `protected_resource_metadata`: return
   `JSONResponse(content=dict)` instead of `Response(content=json_string)`.
   The previous implementation served `Content-Type: text/plain`.
- 6. handlers/metadata.py `authorization_server_metadata`: pass an explicit
   `timeout=httpx.Timeout(5.0)` to `httpx.Client` so a slow upstream
   cannot pin a Starlette threadpool worker indefinitely. Switch the
   error responses to JSONResponse for the same Content-Type reason.
- 7. shared/starlette.py `get_base_url`: guard against `None` port. When
   `request_base_url.port` is None (proxy stripped it, missing from
   pydantic parsing), the previous code interpolated `:None` into the
   URL string. Now treat None like the default ports (omit).
- Adds regression tests:
- `/.well-known/change-password` returns 401 (path-specific bypass)
- `/.well-known/oauth-protected-resource/zone-id/path` returns 200
- `_init_lock` is an asyncio.Lock after `__init__`
- `Content-Type` is `application/json` on the metadata response
- `httpx.Client` is constructed with an explicit `timeout=` kwarg
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * refactor(keycardai-starlette): make install() per-route opt-in instead of whole-app lockdown
- The previous install() shape added BearerAuthMiddleware globally so every
route in the FastAPI/Starlette app required a bearer token. A /health or
/version endpoint returned 401, which contradicts the framing in the
Protect Any API guide ("an API that knows which agent is calling") and the
existing per-subtree code patterns the docs already show
(BearerAuthMiddleware on a Mount, protected_mcp_router(...)).
- After this change:
- install(app) adds OAuth metadata routes only (.well-known/oauth-*).
  No global middleware. Routes are public by default.
- @auth.protect() (no args) verifies the bearer token, returns 401 on
  missing/invalid. No delegation, no AccessContext required.
- @auth.protect("resource") verifies + runs delegated token exchange and
  populates an AccessContext as before.
- protected_router() is unchanged. Still the right pattern for protecting
  a whole subtree (MCP transport, internal admin app, etc.).
- Implementation:
- Extract the verification body of BearerAuthMiddleware.dispatch() into a
  free verify_bearer_token(request, verifier) helper that returns either an
  auth_info dict on success or an RFC 6750 challenge Response on failure.
  Both the middleware and the decorator call it.
- The decorator reuses request.state.keycardai_auth_info if the middleware
  already populated it (e.g. inside a protected_router() mount), otherwise
  calls verify_bearer_token itself and returns the 401 directly on failure.
- AccessContext lookup and injection only run when resources is set.
- Test changes:
- Removed test_install_rejects_requests_without_bearer_token (old contract).
- Removed test_install_does_not_bypass_unrelated_well_known_paths (without
  global middleware, /.well-known/change-password is now a 404, which the
  framework provides; nothing for us to assert here).
- Added test_install_does_not_block_unprotected_routes: /health stays 200.
- Added test_install_does_not_add_global_middleware: BearerAuthMiddleware
  is NOT in app.user_middleware after install().
- Added TestProtectDecorator class:
  - no-args form returns 401 without bearer
  - resource form returns 401 without bearer
  - no-args form does not require AccessContext on the function signature
  - decorator reuses request.state when middleware preset it (verify_token
    asserts if called)
- README and module docstrings rewritten to show the new model with three
distinct patterns (decorator no-args, decorator with resource, protected_router).
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * style(keycardai-starlette): drop temporal/historical comments and tighten test names
- The previous refactor commit shipped a few comments framed against the
prior code shape ("Reuse middleware-set auth info if BearerAuthMiddleware
ran ... otherwise verify the bearer token here") and a couple of
section-header style comments restating what the code does. Drop them.
Move the "two-call-sites" framing out of the verify_bearer_token
docstring; describe the present contract.
- Rename test_install_does_not_add_global_middleware to
test_install_leaves_user_middleware_stack_empty and
test_install_does_not_block_unprotected_routes to
test_routes_without_protect_decorator_stay_public for clearer positive
framing.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * Kamil/starlette auth model (#98)
- * align keycardai-starlette with starlette authentication framework
- * add protected_resource_server example for keycardai-starlette
- * prevent transitive load_dotenv from polluting mcp test environment
- * fix(lint): resolve ruff B026 and I001 errors after merging #98
- Three errors flagged by `just check` after the #98 merge:
- - packages/mcp/tests/conftest.py: B026 star-arg unpacking after keyword
  argument. Forward dotenv_path/stream positionally to the real load_dotenv.
- packages/starlette/src/keycardai/starlette/authorization.py: I001 import
  ordering (auto-fixed).
- packages/starlette/src/keycardai/starlette/provider.py: I001 import
  ordering (auto-fixed).
- All test suites still pass: starlette 42, mcp 560, oauth 208, mcp-fastmcp 51.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * refactor(keycardai-starlette): tighten review findings before merge
- - mcp.server.routers re-exports the protected_mcp_router wrapper so the
  mcp_app= kwarg keeps working through the package-level import
- consolidate the RFC 6750 challenge response into one helper shared by
  keycard_on_error and the @requires/@auth.grant decorators
- drop KeycardUser.resource_client_id (was always equal to
  resource_server_url); grant.wrapper reads resource_server_url for both
  auth_info dict keys
- type _get_or_create_client auth_info as dict[str, str | None] so
  zone_id is no longer mistyped as str
- replace test that asserted staticmethod identity with regression tests
  for the well-known bypass: OAuth metadata paths short-circuit, sibling
  paths (change-password, security.txt, oauth-protected-resource-fake,
  openid-configuration) still raise KeycardAuthError
- rewrite test_no_auth_header_returns_none to call the backend directly
  instead of building a FastAPI app and patching middleware kwargs
- ---------
- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Kamil <kamil@keycard.ai>
Changelog for keycardai-mcp:
## Unreleased

## 0.26.0-keycardai-mcp (2026-06-15)


- feat(keycardai-mcp): resolve multi-zone credentials by zone issuer URL
- The provider looks up per-zone credentials with the zone-scoped issuer
URL it already constructs for the zone client.

## 0.25.0-keycardai-mcp (2026-06-03)


- fix(keycardai-mcp)!: enforce authentication on the MCP mount
- build(keycardai-mcp): require keycardai-starlette>=0.6.0 for require_authentication
- fix(keycardai-mcp): read delegated auth info from request.user

## 0.24.0-keycardai-mcp (2026-06-02)


- test(keycardai-mcp): use generic scope in grant request_scopes tests
- Replace the databricks-specific scope with a generic "read".
- feat(keycardai-mcp): add request_scopes to grant()
- Forward an optional per-resource OAuth scope into the token exchange,
including the impersonation branch (client.impersonate(scope=...)) plus
the application-credential and basic branches. Accepts a str, list[str],
or per-resource dict; distinct from inbound required_scopes.

## 0.23.0-keycardai-mcp (2026-04-28)


- refactor(keycardai-mcp): drop deprecated bearer middleware shims (ACC-235) (#104)
- Removes the keycardai.mcp.server.middleware re-export shims that pointed
at the deprecated BearerAuthMiddleware in keycardai-starlette. Anyone
importing BearerAuthMiddleware should switch to AuthenticationMiddleware
with backend=KeycardAuthBackend(verifier) and on_error=keycard_on_error.
The deprecated symbols themselves stay in keycardai-starlette and come
out in ACC-237.
- keycardai-agents repointed at keycardai.starlette.middleware.bearer so
it keeps building. It still emits the DeprecationWarning shipped in
keycardai-starlette 0.3.0; that goes away when ACC-232 archives the
package.
- Bearer-helper unit tests (_get_bearer_token, _get_oauth_protected_resource_url)
moved from packages/mcp/tests to packages/starlette/tests where the
helpers live.

## 0.22.0-keycardai-mcp (2026-04-24)


- fix(keycardai-mcp): resolve ruff lint errors in provider and test imports

## 0.21.0-keycardai-mcp (2026-03-06)


- build(keycardai-mcp): bump keycardai-oauth dependency to >=0.7.0
- refactor(keycardai-mcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.20.1-keycardai-mcp (2026-02-06)


- fix(keycardai-mcp): return prm for resources dynamically

## 0.20.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Adds PydanticAI integration for MCP frameworks
- - Adds PaydanticAI adapter to client integrations directory
- Support for PydanticAI agents with secure MCP tool access
- Follows established pattern with LangChain and OpenAI integrations
- Adds tests for PydanticAI integration imports

## 0.19.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Add greater control over OAuth metadata location
- - Refactors `auth_metadata_mount` into it's component parts
- Exposes mounts for individual metadata
- Allows the user to specify exactly where their OAuth metadata is
exposed
- NOTE: This is only for advanced use cases where you know you need
something non-standard. Otherwise, follow the OAuth spec.

## 0.18.0-keycardai-mcp (2025-12-04)


- feat(keycardai-mcp): add CrewAI integration for agent frameworks
- - Add CrewAI adapter to client integrations directory
- Support for CrewAI agents with secure MCP tool access
- No token passing - agents never receive raw API tokens
- Fresh token fetched per API call through Keycard
- Follows established pattern with LangChain and OpenAI integrations
- Deleted separate packages/agents package (not needed)
- Added optional dependencies: crewai and agents extras
- Added tests for CrewAI integration imports

## 0.17.0-keycardai-mcp (2025-11-18)


- feat(keycardai-mcp): session callback notification
- feat(keycardai-mcp): session lifecycle management

## 0.16.0-keycardai-mcp (2025-11-17)


- feat(keycardai-mcp): headless clients
- feat(keycardai-mcp): update oauth deps
- feat(keycardai-mcp): client implementation

## 0.15.0-keycardai-mcp (2025-11-07)


- feat(keycardai-mcp): enable web token eks env

## 0.14.0-keycardai-mcp (2025-11-06)


- feat(keycardai-mcp): configure mcp url via env

## 0.13.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): zone settings via env

## 0.12.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): automatic app cred discovery
- feat(keycardai-mcp): default eks env

## 0.11.0-keycardai-mcp (2025-10-29)


- feat(keycardai-mcp): release latest version
- Release current version of workload identity implementation

## 0.10.0-keycardai-mcp (2025-10-27)


- feat(keycardai-mcp): cach the application credentials
- feat(keycardai-mcp): app credential grant flow

## 0.9.0-keycardai-mcp (2025-10-20)


- refactor(keycardai-mcp): align credential names
- feat(keycardai-mcp): eks workload identity support
- feat(keycardai-mcp): add application authentication

## 0.8.1-keycardai-mcp (2025-10-10)


- fix(keycardai-mcp): wrong base url in auth metadata

## 0.8.0-keycardai-mcp (2025-10-07)


- refactor(keycardai-mcp): improve error messages
- refactor(keycardai-mcp): improves the error messages to provide useful debug information

## 0.7.1-keycardai-mcp (2025-09-29)


- fix(keycardai-mcp): set audience for client assertions

## 0.7.0-keycardai-mcp (2025-09-27)


- feat(keycardai-mcp): lowlevel support for RequestContext

## 0.6.0-keycardai-mcp (2025-09-23)


- feat(keycardai-mcp): enable custom middleware injection

## 0.5.1-keycardai-mcp (2025-09-22)


- fix(keycardai-mcp): support x-forwarded-port header

## 0.5.0-keycardai-mcp (2025-09-22)


- feat(keycardai-mcp): dcr can be toggled on/off
- feat(keycardai-mcp): private key jwt support with global key
- feat(keycardai-mcp): grant decorator exception handling
- feat(keycardai-mcp): private key manager protocol

## 0.4.1-keycardai-mcp (2025-09-18)


- fix(keycardai-mcp): support both sync and async tool calls

## 0.4.0-keycardai-mcp (2025-09-18)


- feat(keycardai-mcp): default domain handling

## 0.3.1-keycardai-mcp (2025-09-17)


- fix(keycardai-mcp): check audience when configured

## 0.3.0-keycardai-mcp (2025-09-16)


- feat(keycardai-mcp): multi-zone mcp routing
- feat(keycardai-mcp): advanced server handlers
- feat(keycardai-mcp): auth provider implementation

## 0.1.0-keycardai-mcp (2025-09-10)
Changelog for keycardai-mcp-fastmcp:
## Unreleased

## 0.21.0-keycardai-mcp-fastmcp (2026-04-27)


- feat(keycardai-mcp-fastmcp): release deprecation bridge for keycardai-fastmcp (#103)
- Empty commit to trigger the auto-bump pipeline for keycardai-mcp-fastmcp.
- The actual bridge code (depends on keycardai-fastmcp, re-exports every
public symbol at the original keycardai.mcp.integrations.fastmcp.* paths,
emits DeprecationWarning on top-level import) shipped in #102. That PR
landed scoped (keycardai-fastmcp), so cz only bumped the new package and
keycardai-mcp-fastmcp on PyPI is still the pre-rename version. This
commit gives cz a (keycardai-mcp-fastmcp)-scoped feat to recognize so
the bridge ships as the next published version and customers on the
old name see the deprecation warning.

## 0.20.0-keycardai-mcp-fastmcp (2026-04-01)


- feat(keycardai-mcp-fastmcp): upgrade to FastMCP 3.0
- Upgrade keycardai-mcp-fastmcp from fastmcp>=2.14.0,<3.0.0 to fastmcp>=3.0.0.
- Key changes:
- ctx.get_state()/ctx.set_state() are now async (FastMCP 3.0 breaking change)
- grant decorator uses await ctx.set_state(..., serializable=False)
- All examples, docs, and tests updated for async state access
- Test mocks updated to use async functions for get_state/set_state

## 0.19.0-keycardai-mcp-fastmcp (2026-03-06)


- refactor(keycardai-mcp-fastmcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.18.1-keycardai-mcp-fastmcp (2025-11-23)


- fix(keycardai-mcp-fastmcp): include subject in debug

## 0.18.0-keycardai-mcp-fastmcp (2025-11-20)


- feat(keycardai-mcp-fastmcp): debug information for exchange

## 0.17.0-keycardai-mcp-fastmcp (2025-11-17)


- feat(keycardai-mcp-fastmcp): update oauth deps

## 0.16.0-keycardai-mcp-fastmcp (2025-11-07)


- feat(keycardai-mcp-fastmcp): enable web token eks env

## 0.15.0-keycardai-mcp-fastmcp (2025-11-06)


- feat(keycardai-mcp-fastmcp): configure mcp url via env

## 0.14.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): configure zone setting via env

## 0.13.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): automatic app cred discovery

## 0.12.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): support fastmcp 2.13

## 0.11.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): keycardai mcp dep update
- Reverts the eks workload identity changes

## 0.10.0-keycardai-mcp-fastmcp (2025-10-27)


- feat(keycardai-mcp-fastmcp): use application cred cache

## 0.9.0-keycardai-mcp-fastmcp (2025-10-20)


- feat(keycardai-mcp-fastmcp): EKS workload identity

## 0.8.1-keycardai-mcp-fastmcp (2025-10-07)


- refactor(keycardai-mcp-fastmcp): improve error message with debug context

## 0.8.0-keycardai-mcp-fastmcp (2025-10-01)


- feat(keycardai-mcp-fastmcp): ability to mock internal access context for testing

## 0.7.0-keycardai-mcp-fastmcp (2025-09-27)


- refactor(keycardai-mcp-fastmcp): remove the error codes from AccessContext

## 0.6.0-keycardai-mcp-fastmcp (2025-09-22)


- feat(keycardai-mcp-fastmcp): unify exceptions with keycardai-mcp package

## 0.5.0-keycardai-mcp-fastmcp (2025-09-21)


- feat(keycardai-mcp-fastmcp): client factory and base url update

## 0.4.1-keycardai-mcp-fastmcp (2025-09-19)


- fix(keycardai-mcp-fastmcp): lock the oauth dependency

## 0.4.0-keycardai-mcp-fastmcp (2025-09-18)


- feat(keycardai-mcp-fastmcp): refactor API for the provider

## 0.3.0-keycardai-mcp-fastmcp (2025-09-15)


- feat(keycardai-mcp-fastmcp): unify client arguments

## 0.2.0-keycardai-mcp-fastmcp (2025-09-10)


- fix(keycardai-mcp-fastmcp): pin fastmcp for compatibiity
- feat(keycardai-mcp-fastmcp): allowed to override the client

## 0.1.0-keycardai-mcp-fastmcp (2025-09-07)
Changelog for keycardai-fastmcp:
## Unreleased

## 0.4.0-keycardai-fastmcp (2026-06-02)


- refactor(keycardai-fastmcp): use generic scope in request_scopes examples
- Replace the databricks-specific scope with a generic "read" in the
grant() docstring and tests so the example is not tied to one provider.
- feat(keycardai-fastmcp): add request_scopes to grant()
- Forward an optional per-resource OAuth scope into the RFC 8693 token
exchange so scope-gated Keycard delegation policies can match. Accepts a
str, list[str], or per-resource dict; distinct from inbound
required_scopes. Sets scope on the request in both the application
credential and basic branches.

## 0.3.0-keycardai-fastmcp (2026-05-20)


- fix(keycardai-fastmcp): trigger version bump for audience and wif key_id fixes

## 0.2.0-keycardai-fastmcp (2026-04-27)


- feat(keycardai-fastmcp): rename keycardai-mcp-fastmcp via bridge package (ACC-233) (#102)
- * feat(keycardai-fastmcp): rename keycardai-mcp-fastmcp via bridge package (ACC-233)
- The current name carries a redundant -mcp suffix (FastMCP only speaks MCP,
so the protocol tag adds no information). Renames to keycardai-fastmcp per
the revised KEP, with keycardai-mcp-fastmcp preserved as a deprecation
bridge so the customer in production on the old name keeps working
indefinitely.
- What ships:
- * New keycardai-fastmcp package at packages/fastmcp/, full implementation
  under the keycardai.fastmcp namespace. Tests, examples, README move with
  the source. Wired into the workspace and the release.yml tag filter.
* Deprecated keycardai-mcp-fastmcp now depends only on keycardai-fastmcp
  and re-exports every public symbol at the original
  keycardai.mcp.integrations.fastmcp.* paths. Importing the top-level
  module emits a DeprecationWarning pointing at the canonical name.
* Bridge contract test (test_bridge.py, 4 tests) asserts the
  DeprecationWarning fires and that bridge symbols are identity-equal to
  the canonical ones. The full behavioral suite lives in keycardai-fastmcp
  going forward.
- Customer impact: pip install keycardai-mcp-fastmcp keeps working; the
package transitively pulls keycardai-fastmcp. No forced removal timeline,
the bridge ships until every known caller migrates.
- Verified: ruff clean. fastmcp 51/51, mcp-fastmcp bridge 4/4, mcp 560/560,
oauth 208/208, starlette 49/49.
- Supersedes the canceled ACC-195 (which used the now-rejected
keycardai-fastmcp-mcp name).
- * fix(keycardai-fastmcp): bridge re-exports the full canonical surface
- Review caught that the bridge provider.py only re-exported a hand-enumerated
subset of the canonical surface, dropping documented public symbols
(get_token_debug_info, introspect, INTROSPECT, AuthProviderConfigurationError,
AuthProviderInternalError, AuthProviderRemoteError). Importing any of those
from keycardai.mcp.integrations.fastmcp.provider raised ImportError, breaking
the bridge contract for downstream callers using less common symbols.
- Fixes:
- - Add __all__ to keycardai.fastmcp.provider listing the 28-name public
  surface. Stdlib/typing helpers (logging, os, urlparse, wraps, Any,
  Callable, etc.) are deliberately excluded.
- Replace the bridge provider.py hand-enumeration with
  ``from keycardai.fastmcp.provider import *``, plus a re-export of __all__
  so future symbol additions to the canonical module flow through
  automatically.
- Add test_bridge_provider_exposes_full_public_surface: iterates the
  canonical __all__, asserts every symbol is present at the bridge path
  and identity-equal to the canonical reference. Regression test for the
  symbol-drop class of bug.
- Scrub em dashes from the renamed example READMEs (pre-existing prose,
  but new file paths shipping under our review).
- Verified: fastmcp 51/51, mcp-fastmcp bridge 5/5 (was 4 + 1 new). Smoke:
the six previously-missing symbols now import cleanly from the old path.
- * ci: pin extractions/setup-just version
- The action stopped resolving "latest" sometime today and started failing
with `no release for just matching version specifier`. Pinning unblocks
PR validation and the post-merge bump-and-publish pipeline.
- 1.50.0 is the current stable just release (April 2026).
- * ci: replace extractions/setup-just with the upstream install script
- extractions/setup-just@v2 is currently broken for both unpinned and
explicit-version requests ("no release for just matching version
specifier"). Pinning to 1.50.0 did not help because the action regression
is in its release lookup, not its version resolution.
- Switch to the just.systems install script (the project owners ship and
maintain it). Runs as a plain bash step with no third-party action
dependency and is unaffected by setup-just regressions.
Changelog for keycardai-a2a:
## Unreleased

## 0.3.0-keycardai-a2a (2026-05-01)


- fix(keycardai-a2a)!: align DelegationClient with a2a-sdk 1.x JSONRPC dispatcher (ACC-231) (#107)
- DelegationClient was still speaking 0.x JSON-RPC (“message/send”, old envelope, no A2A-Version), so every call was rejected by real 1.x dispatchers before execution—breaking the entire keycardai-crewai delegation path. Fixed by upgrading to the 1.x contract (SendMessage, proper envelope + headers, new response shape) and adding a real dispatcher test to catch drift.

## 0.2.0-keycardai-a2a (2026-04-29)


- feat(keycardai-a2a): new package split from keycardai-agents (ACC-230) (#105)
- * feat(keycardai-a2a)!: new package split from keycardai-agents (ACC-230)
- Per the KEP "Decompose keycardai-agents", the A2A delegation surface moves
out of keycardai-agents into a new keycardai-a2a package, structurally
analogous to keycardai-mcp. Symbols available at the new namespace:
- - AgentServer, create_agent_card_server, serve_agent
- DelegationClient, DelegationClientSync
- AgentExecutor, SimpleExecutor, LambdaExecutor
- KeycardToA2AExecutorBridge
- ServiceDiscovery
- AgentServiceConfig
- The bearer middleware in server/app.py also migrates from the deprecated
BearerAuthMiddleware to the canonical KeycardAuthBackend +
AuthenticationMiddleware pattern from keycardai-starlette. The
keycardai-mcp dependency drops from this code path.
- Hard cut, no transitional bridge: ACC-232 confirms no known production
users of keycardai.agents.* paths.
- The PKCE user-login client (AgentClient) is dropped entirely. Its
capability already lives in keycardai-oauth as
keycardai.oauth.pkce.authenticate (ACC-229 / #101). The duplicate in
keycardai-agents is removed.
- What stays in keycardai-agents: the CrewAI integration only, with its
imports repointed at keycardai.a2a. ACC-231 will move it to a dedicated
keycardai-crewai; ACC-232 will archive the now-stub source directory.
- BREAKING:
- from keycardai.agents import AgentServer, DelegationClient, ...
  becomes from keycardai.a2a import ... .
- from keycardai.agents.client import AgentClient is gone; use
  keycardai.oauth.pkce.authenticate.
- keycardai-agents 0.3.0 ships with the dependency set reduced to
  keycardai-a2a + pydantic, mirroring its now-CrewAI-only scope.
- * fix(keycardai-a2a): apply migration edits to moved files (ACC-230)
- The first commit on this branch did the git mv's but staged the new
files only; the Edit-tool modifications to the moved files (import
rewrites, server/app.py bearer-wiring migration to KeycardAuthBackend +
AuthenticationMiddleware, example pyproject swap from keycardai-agents
to keycardai-a2a, conftest/tests import repoints, agents/__init__.py
trim, agents/pyproject dep set, crewai integration repoint, top-level
workspace sources, justfile test recipe, uv.lock refresh) all sat
uncommitted. CI rejected the prior commit because the example pyproject
still claimed keycardai-agents at packages/a2a/, conflicting with the
real keycardai-agents at packages/agents/ in the workspace graph.
- This commit lands the actual migration content. Tests pass locally:
keycardai-a2a 60/60, keycardai-agents 16/16, no regression in oauth /
starlette / mcp / mcp-fastmcp / fastmcp; ruff workspace check clean.
- * refactor(keycardai-a2a)!: wrap a2a-sdk 1.x, drop parallel surface (ACC-230)
- Aligns keycardai-a2a with the wrap-do-not-reinvent pattern used in
keycardai-mcp and keycardai-starlette: customers implement a2a-sdk native
async AgentExecutor directly; this package contributes only Keycard auth
wiring, OAuth metadata discovery, and convenience composition.
- Drops the parallel-protocol surface inherited from the keycardai-agents
move:
- AgentExecutor protocol (sync execute(task, inputs)) and SimpleExecutor /
  LambdaExecutor implementations
- KeycardToA2AExecutorBridge (the sync->async adapter that existed only to
  bridge our protocol to a2a-sdk)
- Custom POST /invoke endpoint with bespoke InvokeRequest / InvokeResponse
  Pydantic models alongside the standard A2A JSONRPC interface
- AgentServiceConfig.invoke_url (replaced by jsonrpc_url) and
  AgentServiceConfig.to_agent_card() (the 0.x dict-shape constructor)
- Migrates from a2a-sdk 0.x to 1.x natively:
- pyproject pin a2a-sdk[http-server]>=1.0
- Server composition uses route factories (create_jsonrpc_routes,
  create_agent_card_routes) instead of the gone A2AStarletteApplication
- Request handler is DefaultRequestHandlerV2 (alias DefaultRequestHandler)
- AgentCard built from 1.x protobuf schema (supported_interfaces,
  AgentCapabilities streaming/push_notifications/extended_agent_card)
- Example main.py uses a2a-sdk 1.x Client via create_client + A2ACardResolver
- Adds a KeycardServerCallContextBuilder that subclasses a2a-sdk default
builder and stashes the verified KeycardUser plus access_token into
ServerCallContext.state so AgentExecutor implementations can read the
bearer token from context.call_context.state["access_token"] for
downstream delegated token exchange.
- Tests:
- a2a 44/44 pass
- agents 16/16 pass with crewai extra
- ruff clean
- Note: the high-level @auth.grant decorator parity with keycardai-mcp is
not yet shipped here. Customers use DelegationClient (already in this
package) for explicit server-to-server delegation. The decorator port is
a follow-up.
- * fix(keycardai-a2a): address review findings on PR #105
- Three blockers caught in fresh-eyes review:
- 1. release.yml tag-trigger list was hardcoded; *-keycardai-a2a was missing,
   so the post-merge auto-bump would push the tag but the publish workflow
   would never trigger. Trusted Publisher being registered would have been
   moot.
- 2. DelegationClient.invoke_service hardcoded service_url + /invoke. The
   wrap-aligned server only exposes /a2a/jsonrpc; calling invoke_service
   against any 1.x server returned 404. The CrewAI delegation tool runs
   through this code path. Both async and sync variants now build a
   message/send JSONRPC envelope, POST it to /a2a/jsonrpc, and unwrap the
   result to preserve the legacy {result, delegation_chain} shape so the
   CrewAI integration keeps working unchanged.
- 3. discover_service in both DelegationClient and ServiceDiscovery validated
   the 0.x card shape (required_fields = [name, endpoints, auth]). The 1.x
   protobuf-derived JSON has none of endpoints / auth. Discovery against
   any 1.x server raised ValueError. Validation now requires only "name";
   transport / auth specifics live under supportedInterfaces and the OAuth
   metadata routes.
- Plus four important findings:
- 4. Test mocks across conftest.py, test_a2a_client.py, test_discovery.py,
   and test_crewai_a2a.py used the old shape (endpoints/auth keys). Tests
   passed because the validator wrongly accepted them. Mocks now use the
   1.x JSON shape (supportedInterfaces, capabilities object, skills with
   id/name).
- 5. A2AServiceClient and A2AServiceClientSync backward-compat aliases at
   the bottom of delegation.py contradicted the "hard cut, no transitional
   bridge" stance in the PR description. Removed.
- 6. TestJsonRpcAuthGate.test_jsonrpc_requires_authorization asserted
   status_code in (400, 401). 400 means the JSONRPC dispatcher saw the
   request and bailed on the body shape, not that the auth gate caught
   it. Pinned to == 401 with a WWW-Authenticate header check so the gate
   contract is enforced.
- 7. Zero coverage existed for _KeycardServerCallContextBuilder propagating
   the verified KeycardUser plus access_token into ServerCallContext.state.
   Added two unit tests that build the context directly: one with a
   KeycardUser asserting state["access_token"] is set, one with an
   UnauthenticatedUser asserting state["access_token"] is absent (so an
   executor reading it sees None rather than a stale token).
- Tests:
- a2a 47/47 (was 44; +3 new wrap-coverage tests)
- agents 16/16 with crewai extra
- ruff clean
- * refactor(keycardai-a2a)!: ship primitives, not a server abstraction (ACC-230)
- Per Kamil's review on PR #105: AgentServer / create_agent_card_server /
serve_agent presupposed customers want a fresh Starlette app dedicated to
the agent service. The wrap-don't-reinvent stance, taken seriously,
says: customers already have an a2a-sdk app in their head; we ship
primitives that slot Keycard auth into THAT, not a parallel server.
- Public surface change:
- Dropped:
  AgentServer, create_agent_card_server, serve_agent
Promoted to public (renamed off the underscore prefix):
  EagerKeycardAuthBackend
  KeycardServerCallContextBuilder
  build_agent_card_from_config
- AgentServiceConfig trimmed: dropped agent_executor (DefaultRequestHandler
takes its own), port and host (uvicorn's job), status_url (no /status
in the primitives layer).
- The composed-server flow moves to a runnable example at
packages/a2a/examples/keycard_protected_server/. README quickstart
rewritten to show primitive composition into an existing app; greenfield
users follow the example.
- Tests:
  a2a 44/44 (was 47; net -3 from dropping the /status endpoint tests
            and the port-validation test)
  agents 16/16 with crewai extra
  ruff clean
- This change is breaking, but the package is 0.1.0-pre-publish so no
customer is on these names yet.
- * fix(keycardai-a2a): ruff import-organization auto-fix
- * refactor(keycardai-starlette,keycardai-a2a): collapse EagerKeycardAuthBackend into KeycardAuthBackend kwarg (ACC-230)
- Per Kamil's second review observation on PR #105: with keycardai-a2a
now depending on keycardai-starlette, the question of WHERE these
primitives live matters. EagerKeycardAuthBackend was a 5-line subclass
that flipped one branch of KeycardAuthBackend.authenticate to raise on
missing Authorization, with no a2a-sdk specifics. The behavior is a
policy choice ("this mount requires auth"), not a different kind of
backend.
- Collapsed to a kwarg on the existing class:
-   KeycardAuthBackend(verifier)                              # default,
                                                            # mixed-route
  KeycardAuthBackend(verifier, require_authentication=True) # all-paths-protected
- The OAuth metadata bypass (RFC 9728 §2 / RFC 8414 §3) takes precedence
over the kwarg: even with require_authentication=True, requests to
/.well-known/oauth-* and /.well-known/jwks.json still pass through
anonymously per spec. New parametrized test asserts this.
- Net effect:
- One class instead of two; existing KeycardAuthBackend(verifier) callers
  unchanged.
- keycardai-a2a no longer ships EagerKeycardAuthBackend; the kwarg is
  used directly in tests, the example, and the README quickstart.
- Migration story is zero churn for existing users; new behavior is
  opt-in via the kwarg.
- Tests:
  starlette 40 passed (+2 new tests for the kwarg semantics)
  a2a 44 passed
  agents 16 passed
  ruff clean

---

This comment was automatically generated by the release preview workflow.

[github-actions]

📦 Release Preview

This analysis shows the expected release impact:

📈 Expected Version Changes

keycardai-starlette: 0.10.0 → 0.11.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-starlette",
    "package_dir": "packages/starlette",
    "has_changes": true,
    "current_version": "0.10.0",
    "next_version": "0.11.0",
    "increment": "MINOR"
  }
]

📝 Changelog Preview

Changelog for keycardai:
## Unreleased

## 0.3.0-keycardai (2026-06-10)


- build(keycardai): take examples out of the uv workspace (#151)
- Examples are globbed in as workspace members via packages/*/examples/*, so
every root uv operation generates their package metadata. uv 0.11.20 (released
2026-06-10, pulled in by CI's unpinned setup-uv) fails that generation on
Linux during the nested `uv run cz changelog`, breaking the Merge to Main
detect-changes job even though `uv sync` and the PR checks pass. Examples ship
their own lockfiles and only pin their parent package, so they are standalone
projects: exclude them from the workspace and keep their path sources. Root
operations now resolve only the workspace packages.
- Also send changelog.py error output to stderr so a failed detect-changes shows
in the CI log instead of being captured into $(just detect-changes).
- Co-authored-by: GitHub Action <action@github.com>
- build(keycardai): use workspace sources for keycard deps in examples (#150)
- uv 0.11.20 rejects a workspace member overriding a workspace source with a
path. Each example declared keycardai-<pkg> = { path = "../../", editable =
true } while the root workspace already declares { workspace = true }. Switch
the examples to { workspace = true } (uv 0.11.20 guidance). No uv pin; no
lockfile change. Unblocks lint-and-test / validate-commits for all PRs.
- Co-authored-by: GitHub Action <action@github.com>

## 0.2.0-keycardai (2025-09-10)

## 0.1.0-keycardai (2025-09-07)


- feat(keycardai): initial release
Changelog for keycardai-oauth:
## Unreleased

## 0.21.0-keycardai-oauth (2026-07-15)


- feat(keycardai-oauth): add WorkloadIdentity credential with pluggable subject token sources (#191)
- * feat(keycardai-oauth): add WorkloadIdentity credential with pluggable subject token sources
- One generic WorkloadIdentity credential owns the exchange contract
(jwt-bearer client assertion, no basic auth, fresh fetch per exchange,
no caching). A one-method SubjectTokenSource protocol is the only
per-platform code: FileTokenSource (EKS, AKS, Kubernetes projected
tokens), GCPMetadataTokenSource (GKE, GCE, Cloud Run), FlyTokenSource
(Fly Machines), or any bare callable.
- The optional client_id constructor argument is sent as the client_id
form parameter alongside the assertion; token-federation application
credentials (KEP 108) are resolved by it.
- EKSWorkloadIdentity becomes a deprecated subclass wrapping its existing
discovery and read logic as a source, with unchanged signature,
EKS-only env discovery, and unchanged error types, which are now
subclasses of the new WorkloadIdentity{Configuration,Runtime}Error.
- Implements the workload-identity spec (keycard-sdk-spec#39). ECO-110.
- * refactor(keycardai-oauth): rename IdentityTokenSource from SubjectTokenSource
- The source returns the platform-issued OIDC identity token, which the
credential attaches as the client assertion. Naming it a subject token
collided with TokenExchangeRequest.subject_token, which carries the
inbound user token on the RFC 8693 exchange.
- * docs(keycardai-oauth): note that sync identity token sources must not block
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.20.0-keycardai-oauth (2026-06-15)


- feat(keycardai-oauth)!: key multi-zone credentials by issuer and add a per-call issuer selector
- Multi-zone ClientSecret dicts and MultiZoneBasicAuth are now keyed by
the zone issuer URL (trailing slashes normalized), with accessors
has_issuer, get_configured_issuers, and get_auth_for_issuer.
AuthStrategy.apply_headers accepts an optional issuer selector:
single-zone strategies ignore it, MultiZoneBasicAuth resolves that
issuer fail-closed and raises when called without one. The selector
threads through the HTTP context and all operation builders, defaulting
to the client issuer, and exchange_token / client_credentials_grant
accept a per-call issuer keyword.
- BREAKING CHANGE: multi-zone credential maps are keyed by issuer URL
instead of zone id; zone-keyed accessors are renamed to issuer terms and
get_headers_for_zone is removed.
- feat(keycardai-oauth): add issuer-direct entry to the PKCE authenticate flow (#171)
- authenticate accepts either issuer (used directly, no metadata fetch) or
www_authenticate_header (the RFC 9728 challenge-driven path); exactly
one must be provided. resource_url is now optional overall and required
only in challenge mode. The challenge-to-issuer resolution is exposed as
resolve_issuer_from_challenge in keycardai.oauth.pkce.
- Co-authored-by: GitHub Action <action@github.com>

## 0.19.0-keycardai-oauth (2026-06-12)


- feat(keycardai-oauth): add client_credentials_grant operation (#166)
- Adds an RFC 6749 section 4.4 client credentials grant to the general
client. New ClientCredentialsRequest model (resource, scope,
client_assertion, client_assertion_type), a client_credentials operation
module mirroring the token-exchange transport contract, and a
client_credentials_grant method on both Client and AsyncClient that
accepts a request object or keyword arguments and authenticates via the
client's configured credential. ECO-43.
- Co-authored-by: GitHub Action <action@github.com>

## 0.18.2-keycardai-oauth (2026-06-12)


- fix(keycardai-oauth): discover KEYCARD_EKS_WORKLOAD_IDENTITY_TOKEN_FILE in EKS workload identity (#164)
- EKSWorkloadIdentity documents KEYCARD_EKS_WORKLOAD_IDENTITY_TOKEN_FILE
as the first env var checked during token-file discovery, but the
default list only contained the two AWS variables. The variable is now
searched first, matching the docstring and the TS and Go SDKs. ECO-40.
- Co-authored-by: GitHub Action <action@github.com>

## 0.18.1-keycardai-oauth (2026-06-12)


- fix(keycardai-oauth): add client_assertion kwargs to sync exchange_token overload (#162)
- * fix(keycardai-oauth): add client_assertion kwargs to sync exchange_token overload
- The sync exchange_token kwargs overload was missing the client_assertion
and client_assertion_type parameters that the async overload declares.
The runtime path already accepted them via **token_exchange_args; this
aligns the typed surface so type checkers and IDEs accept the kwargs on
the sync client too. ECO-41.
- * fix(keycardai-oauth): make subject_token_type optional in exchange_token kwargs overloads
- TokenExchangeRequest defaults subject_token_type to the access-token
type, but both kwargs overloads declared it required. The overloads now
mark it optional so the typed surface matches the model default.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.18.0-keycardai-oauth (2026-06-11)


- feat(keycardai-oauth): expose get_client_jwks_url on the WebIdentity credential (#160)
- WebIdentity exposed only get_jwks(); the client JWKS URL helper lived on the
internal key manager, not the credential. Add get_client_jwks_url(resource_server_url)
to the credential, delegating to the key manager, so the public JWKS getter and
the JWKS-URL helper are both on the credential, matching the TS getClientJwksUrl
and Go ClientJWKSURL accessors.
- Part of the web-identity spec JWKS-accessor-surface row (ECO-39).
- Co-authored-by: GitHub Action <action@github.com>

## 0.17.0-keycardai-oauth (2026-06-11)


- feat(keycardai-oauth)!: RFC-minimal client registration and typed registration errors (#156)
- ClientRegistrationRequest no longer injects opinionated defaults
(token_endpoint_auth_method, redirect_uris, grant_types, response_types,
scope) and no longer requires client_name. Per RFC 7591 all client metadata
is optional, so the request sends only the fields the caller sets, matching
the RFC-minimal TypeScript registerClient.
- Registration errors are now typed: on an RFC 7591 section 3.2.2 error (HTTP
4xx with a JSON error body) registration raises OAuthProtocolError carrying
the error code so a caller can branch on it, instead of an opaque
OAuthHttpError with only the raw body. A non-structured 4xx still raises
OAuthHttpError.
- Resolves the request-defaults, client_name-requiredness, and error-surfacing
rows of the dynamic-client-registration spec (ECO-44).
- Co-authored-by: GitHub Action <action@github.com>

## 0.16.0-keycardai-oauth (2026-06-11)


- feat(keycardai-oauth)!: raise typed InvalidTokenError and enforce issuer allowlist before key resolution (#154)
- * feat(keycardai-oauth)!: raise typed InvalidTokenError and enforce issuer allowlist before key resolution
- The verify surface is now fail-closed and typed. `verify_token` and
`verify_token_for_zone` return an `AccessToken` and raise the new
`InvalidTokenError` (RFC 6750 `invalid_token`) on any verification failure;
they no longer return `None`.
- Cheap policy checks (trusted issuer, expiration) now run on the unverified
payload before any network key resolution, so a token with an untrusted `iss`
is rejected without triggering JWKS discovery or fetch. The issuer is checked
against a trusted allowlist: `issuer` now accepts `str | list[str]`. JWKS keys
are cached per `(issuer, kid)` so distinct issuers cannot collide on a shared
`kid`, and discovery resolves keys for the validated token issuer.
- Infra failures (JWKS discovery/fetch) now propagate as their typed errors
instead of being collapsed into a generic failure, so a JWKS outage surfaces
as a server error rather than a misleading invalid-token result.
- Resolves the verify-contract, ordering, and issuer-allowlist rows of the
jwt-signing-and-verification spec (ECO-36).
- * fix(keycardai-starlette): catch InvalidTokenError from token verification
- The bearer backend relied on `verify_token` returning `None` on failure. The
verifier now raises `InvalidTokenError`, so the backend catches it and maps it
to the RFC 6750 `invalid_token` 401 challenge. JWKS infrastructure errors are
no longer caught here, so a key-resolution outage surfaces as a server error
rather than a 401.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.3-keycardai-oauth (2026-06-10)


- fix(keycardai-oauth): expose ResourceAccessError context attributes (#149)
- ResourceAccessError now stores resource / error_type / available_resources /
error_details as direct instance attributes, alongside the existing details
dict, so handlers can inspect the error context without unpacking details.
AccessContext.get_errors is annotated dict[str, Any] since it always returns a
dict, never None.
- Closes the access-context net-new gaps surfaced by the parity verification.
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.2-keycardai-oauth (2026-06-10)


- fix(keycardai-oauth): raise typed JWKS errors from get_jwks_key (#147)
- get_jwks_key raised bare ValueError, and its outer except flattened every
failure into one generic "Failed to fetch JWKS" ValueError. It now raises
typed, catchable errors: JWKSFetchError (endpoint unreachable or non-2xx)
and JWKSKeyNotFoundError (kid absent from the set), under a JWKSError base
in keycardai.oauth.exceptions (exported from the package root). Unexpected
errors are wrapped as JWKSFetchError; typed errors propagate unchanged.
- Defined in the top-level exceptions module so the utils layer can import
them without the server-package circular import. Matches the canonical
error model and the TS typed JWKS errors.
- Part of the SDK parity effort (ECO-35 / ECO-32).
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.1-keycardai-oauth (2026-06-09)


- fix(keycardai-oauth): evict oldest JWKS key on overflow instead of clearing the cache (#145)
- The key cache cleared all entries when it hit max_size (10), so a verifier
serving more than 10 kids would thrash. It now evicts the single oldest entry
and the bound is raised to 256. Closes the remaining mechanical ECO-35 row on
key-cache eviction (bounded plus partial eviction; exact order is
implementation-defined per the spec).
- Co-authored-by: GitHub Action <action@github.com>

## 0.15.0-keycardai-oauth (2026-06-09)


- feat(keycardai-oauth): converge JWKS caching to spec (discovery TTL, fetch timeout, inflight de-dup) (#143)
- Converges TokenVerifier JWKS caching to specs/jwt-jwks/jwks-caching.md (ECO-35):
- - discovery_ttl knob (default 1h): the discovered jwks_uri is cached with a
  TTL and re-discovered after expiry, not for the verifier lifetime.
- fetch_timeout knob (default 10s): bounds discovery and JWKS fetches;
  get_jwks_key gained an optional timeout argument.
- inflight de-duplication: concurrent cold-cache lookups for the same
  (zone, kid) share one discovery and one JWKS fetch.
- key_ttl: per-key TTL knob renamed to the canonical key_ttl; cache_ttl
  kept as a deprecated keyword alias.
- Key-cache eviction policy and error taxonomy (the remaining ECO-35 rows)
need a canonical decision and are left for a follow-up.
- Co-authored-by: GitHub Action <action@github.com>

## 0.14.0-keycardai-oauth (2026-06-02)


- test(keycardai-oauth): use generic scope in exchange request_scopes tests
- Replace the databricks-specific scope with a generic "read".
- feat(keycardai-oauth): add request_scopes to exchange_tokens_for_resources
- Accept an optional per-resource OAuth scope and apply it across all three
exchange paths: impersonation (client.impersonate(scope=...)), the
application-credential request, and the basic RFC 8693 request. Accepts a
str, list[str], or per-resource dict.

## 0.13.1-keycardai-oauth (2026-06-02)


- fix(keycardai-oauth): require kid in TokenVerifier, matching the TypeScript verifier (#132)
- The TS verifier rejects any token without a kid header; Python silently fell
back to the single JWKS key. For cross-SDK parity (and since Keycard always
issues a kid), Python now rejects a missing kid with TokenValidationError
before key resolution. Removes the optional-in-one / required-in-the-other
surprise.
- Part of ECO-35.
- Co-authored-by: GitHub Action <action@github.com>

## 0.13.0-keycardai-oauth (2026-06-02)


- fix(keycardai-oauth): enforce jwks_uri same-origin with issuer in TokenVerifier (#131)
- A discovered jwks_uri must share the issuer origin before any key is fetched,
matching the TypeScript keyring (assertSameOrigin). This guards against a
tampered or misconfigured discovery document pointing key resolution at an
attacker-controlled origin. Explicit jwks_uri (trusted config) is unaffected.
- Adds JWKSUriValidationError, raised on mismatch.
- Closes ECO-34.
- Co-authored-by: GitHub Action <action@github.com>

## 0.12.0-keycardai-oauth (2026-05-07)


- feat(keycardai-oauth)!: pass error context through AccessContext.access(), rename to get_resource_error (#114)
- * feat(keycardai-oauth)!: pass error context through AccessContext.access(), rename to get_resource_error
---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.11.0-keycardai-oauth (2026-04-28)


- feat(keycardai-oauth): add high-level PKCE user-login flow (ACC-229) (#101)
- * feat(keycardai-oauth): add high-level PKCE flow client (ACC-229)
- First step of the keycardai-agents decomposition (ACC-229..232). Per the
revised KEP, the OAuth PKCE user-login flow is generic OAuth code with no
agents-specific concerns and belongs in keycardai-oauth next to the rest
of the OAuth client primitives.
- New module keycardai.oauth.pkce:
- - PKCEClient orchestrates the full authorization-code-with-PKCE flow:
  parse the WWW-Authenticate challenge (RFC 9728), fetch protected resource
  and authorization server metadata (RFC 8414), open the browser at the
  authorize endpoint, capture the redirect via a local callback server,
  and exchange the code at the token endpoint. Returns the token endpoint
  response dict directly.
- OAuthCallbackServer is the loopback redirect catcher (RFC 8252) used by
  PKCEClient; exported separately so callers running their own flow on top
  of the lower-level PKCEGenerator + build_authorize_url primitives can
  reuse the callback machinery.
- 7 new tests cover header parsing, discovery error paths, the happy-path
  flow, and confidential vs public client auth on the token endpoint.
- keycardai-agents changes:
- - AgentClient now composes PKCEClient instead of carrying its own copy of
  the auth flow. AgentClient.authenticate(...) is preserved as a thin shim
  that returns the access_token string and updates the per-service token
  cache, so existing /invoke retry-on-401 behavior is unchanged.
- AgentClient drops ~370 lines of duplicated PKCE/discovery/callback code.
- keycardai.agents.client.oauth re-exports OAuthCallbackServer through a
  module __getattr__ that emits a DeprecationWarning pointing at the new
  canonical import path.
- Stale tests in test_agent_client_oauth.py that exercised AgentClient
  private methods (_extract_resource_metadata_url, _fetch_resource_metadata,
  _fetch_authorization_server_metadata) removed; equivalent contracts now
  live in the keycardai-oauth PKCE test suite.
- Verified: oauth 215/215 (was 208 + 7 new), agents 81/81 (was 85 - 4 removed
implementation tests), mcp 560/560, starlette 49/49, ruff clean.
- Stacked on #100 (ACC-236 a2a-sdk pin) so the agents test suite can run
during validation.
- * fix(keycardai-oauth): address review findings on PKCE move
- Three small fixes from the review of #101:
- 1. PKCEClient now accepts an optional injected httpx.AsyncClient. AgentClient
   passes its existing http_client through, so a single connection pool covers
   both the agent service calls and the OAuth flow. close() only closes the
   client it owns. Restores the one-pool-per-AgentClient behavior from main.
- 2. Drop the no-op rstrip("/") + "/" round-trip in PKCEClient.authenticate
   when building the authorization server discovery URL.
- 3. Assert the discovery URL path in test_authenticate_completes_full_flow.
   The previous test stubbed http_mock.get with side_effects but never
   verified what URLs were passed; a typo from oauth-authorization-server
   to openid-configuration would have gone unnoticed.
- * refactor(keycardai-oauth): collapse PKCEClient into a flow function on AsyncClient
- Per Kamil review feedback (#101): a separate PKCEClient sitting next to
AsyncClient invited "which client do I use?" The OAuth-server-facing
operations belong on the existing AsyncClient.
- Changes:
- - keycardai.oauth.pkce.PKCEClient (class) -> keycardai.oauth.pkce.authenticate
  (module-level async function). One-shot per user login, no state worth
  preserving across calls.
- The function uses AsyncClient internally for server metadata discovery
  (RFC 8414) and code exchange. AsyncClient is now the only thing in
  keycardai.oauth that talks to OAuth servers as a client.
- AsyncClient.exchange_authorization_code (and Client + the underlying
  operations._authorize helpers) gain an optional resource= parameter so
  RFC 8707 tokens still work through the canonical path.
- The pkce module retains the user-flow concerns: RFC 9728 challenge
  parsing, resource metadata fetch (paired with the protected resource,
  not the OAuth server), browser launch, and the loopback callback server
  (RFC 8252).
- AgentClient drops the cached _pkce instance and just calls the function
  per /invoke retry, passing its own httpx.AsyncClient through for the
  resource metadata fetch.
- Tests rewritten for the function shape: 7/7 passing, same coverage
  (header parsing, discovery error paths, happy path with resource
  indicator, public vs confidential auth on the token endpoint).
- Verified: oauth 215/215, agents 81/81, mcp 560/560, starlette 49/49.
ruff clean.

## 0.10.0-keycardai-oauth (2026-04-24)


- fix(keycardai-oauth): fall back to legacy ./mcp_keys dir with deprecation warning
- Switch WebIdentity default storage_dir back to ./server_keys (aligning
with the protocol-agnostic naming from this PR), but transparently fall
back to ./mcp_keys when no storage_dir is passed, ./server_keys does not
exist, and ./mcp_keys does. The fallback emits a DeprecationWarning
pointing at the explicit configuration or migration paths.
- This preserves zero-config upgrades for existing keycardai-mcp services
(they keep finding their existing keys) while giving new installs the
new default. The fallback will be removed in a future release.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- fix(keycardai-oauth): preserve mcp storage defaults, move server tests
- Address PR #95 review comments from cmars:
- 1. Revert WebIdentity default storage_dir to "./mcp_keys" and key_id
   prefix to "mcp-server-". Changing these would silently break existing
   keycardai-mcp services on upgrade: they would look for keys in a new
   empty directory and regenerate identity, losing their registered client
   identity with Keycard.
- 2. Move oauth-server-specific tests (test_verifier, test_cache,
   test_application_identity -> test_credentials) from packages/mcp/tests
   to packages/oauth/tests/keycardai/oauth/server/ so coverage lives
   with the canonical oauth.server modules.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- fix(keycardai-oauth): address PR review findings
- - Add token_exchange module with exchange_tokens_for_resources()
  orchestration (KEP Tier 1 gap)
- Rename WebIdentity param mcp_server_name -> server_name with
  backward-compatible alias; default storage dir ./mcp_keys -> ./server_keys
- Add mcp_server_url/missing_mcp_server_url backward-compat aliases
  to AuthProviderConfigurationError (prevents breaking fastmcp callers)
- Fix _get_kid_and_algorithm returning list instead of tuple
- feat(keycardai-oauth): add server subpackage with framework-free primitives
- Extract protocol-agnostic server components from keycardai-mcp into
keycardai.oauth.server per the Protocol-Agnostic SDK KEP (Tier 1).
- New keycardai.oauth.server modules:
- access_context: AccessContext for non-throwing token access
- credentials: ApplicationCredential, ClientSecret, WebIdentity, EKSWorkloadIdentity
- verifier: TokenVerifier with local AccessToken model (no MCP dependency)
- exceptions: OAuthServerError base + all framework-free exceptions
- _cache: JWKSCache/JWKSKey for JWKS key caching
- client_factory: ClientFactory protocol + DefaultClientFactory
- private_key: PrivateKeyManager, FilePrivateKeyStorage
- keycardai-mcp changes:
- Server auth modules now re-export from keycardai.oauth.server
- MCPServerError is an alias for OAuthServerError
- MissingContextError stays MCP-specific (references FastMCP Context)
- All existing imports continue to work (no breaking changes)
- Tests updated to patch canonical module paths

## 0.9.0-keycardai-oauth (2026-04-02)


- feat(keycardai-oauth): support for impersonation token exchange
- - Add substitute-user token type and unsigned JWT builder
- Add impersonate method to Client and AsyncClient
- Add user_identifier callback to MCP grant decorator
- Add impersonation token exchange example

## 0.8.0-keycardai-oauth (2026-04-02)


- feat(keycardai-oauth): add authorization code exchange and PKCE support
- - Implement PKCE code verifier, challenge generation, and validation
- Add authorization code exchange operation (sync and async)
- Add build_authorize_url for constructing OAuth authorize URLs
- Add exchange_authorization_code to Client and AsyncClient
- Add get_endpoints/endpoints property to expose resolved endpoints
- Add id_token field to TokenResponse

## 0.7.0-keycardai-oauth (2026-03-06)


- fix(keycardai-oauth): update test to expect OAuthProtocolError for structured error bodies
- feat(keycardai-oauth)!: detailed error reporting
- BREAKING CHANGE: Token exchange HTTP 4xx errors with structured JSON bodies now raise OAuthProtocolError instead of OAuthHttpError. Callers catching OAuthHttpError for these responses must update to catch OAuthProtocolError.

## 0.6.0-keycardai-oauth (2025-11-17)


- feat(keycardai-oauth): client metadata updates

## 0.5.0-keycardai-oauth (2025-09-22)


- feat(keycardai-oauth): client assertion support
- feat(keycardai-oauth): JWKS type support

## 0.4.1-keycardai-oauth (2025-09-17)


- fix(keycardai-oauth): audience checks

## 0.4.0-keycardai-oauth (2025-09-16)


- feat(keycardai-oauth): multi-zone authentication strategy
- feat(keycardai-oauth): jwt capabilities

## 0.2.0-keycardai-oauth (2025-09-10)


- feat(keycardai-oauth): remove the impersonation logic

## 0.1.0-keycardai-oauth (2025-09-07)


- feat(keycardai-oauth): initial release
Changelog for keycardai-starlette:
## Unreleased


- fix(keycardai-starlette): return 401/503 (not 500) for JWKS errors
- KeycardAuthBackend.authenticate() caught only InvalidTokenError. JWKS
errors are a separate tree (JWKSError/JWKSKeyNotFoundError extend
OAuthError(Exception); JWKSDiscoveryError/JWKSUriValidationError extend
OAuthServerError(Exception)), none of which is InvalidTokenError or a
Starlette AuthenticationError. They escaped AuthenticationMiddleware to
ServerErrorMiddleware, yielding HTTP 500 with no WWW-Authenticate.
- So a token whose kid is absent from the JWKS (forged, or rotated out),
or an unreachable/non-2xx JWKS or discovery endpoint, returned 500
instead of a 401 (client should re-auth) or 503 (transient). This is the
Python-side of the same bug reported against the TypeScript SDK (#119).
- Map the JWKS error classes at the auth boundary:
- JWKSKeyNotFoundError -> KeycardAuthError invalid_token (401 + challenge)
- JWKSError / JWKSDiscoveryError / JWKSUriValidationError -> 503
- _build_unauthorized_response now emits a bare 503 body with no
WWW-Authenticate header for 5xx, since that challenge is not one a client
can satisfy by re-authenticating.
- Refs keycardai/typescript-sdk#119

## 0.10.0-keycardai-starlette (2026-06-15)


- feat(keycardai-starlette): infer multi-zone from the application credential
- enable_multi_zone defaults to None and is inferred from a multi-zone
ClientSecret; an explicit value overrides. Per-zone credential lookup
uses the zone-scoped issuer URL.

## 0.9.0-keycardai-starlette (2026-06-12)


- fix(keycardai-starlette): return 502 when the upstream AS metadata fetch fails (#170)
- * fix(keycardai-starlette): return 502 when the upstream AS metadata fetch fails
- The authorization-server metadata proxy previously passed the upstream
HTTP status through and mapped connect/timeout errors to 503. All
upstream failures (HTTP error status or any transport error) now respond
502 Bad Gateway with an upstream_error body. Unexpected exceptions still
map to 500.
- * test(keycardai-a2a): expect 502 from the AS metadata proxy on upstream failure
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 0.8.0-keycardai-starlette (2026-06-12)


- feat(keycardai-starlette)!: align metadata endpoints with the RFC 9728 contract (#168)
- The protected-resource document no longer carries the OAuth client
registration fields (client_id, client_name, token_endpoint_auth_method,
grant_types); it now exposes the standard optional inputs
scopes_supported, resource_name, and resource_documentation, and emits
jwks_uri only when a JWKS is configured. The authorization-server proxy
appends resource=<origin> to the upstream authorization_endpoint.
Metadata and JWKS responses carry Access-Control-Allow-Origin: * and
answer OPTIONS preflight. The upstream metadata fetch timeout is
configurable (as_metadata_timeout, default 10s; was fixed 5s).
- BREAKING CHANGE: the protected-resource document drops the four client
registration fields and jwks_uri is conditional on a configured JWKS.
- Co-authored-by: GitHub Action <action@github.com>

## 0.7.0-keycardai-starlette (2026-06-11)


- fix(keycardai-starlette): emit RFC 6750 insufficient_scope challenge from requires (#158)
- The `requires` decorator raised a bare HTTPException(403) on scope failure,
with no WWW-Authenticate header. It now returns a 403 carrying an RFC 6750
`Bearer error="insufficient_scope"` challenge with the resource_metadata URL
(RFC 9728), matching the 401 anonymous path and the TS/Go route gates. The
status_code argument still controls the failure status (default 403).
- Resolves the scope-failure response-shape row of the route-level-auth-gating
spec (ECO-78).
- Co-authored-by: GitHub Action <action@github.com>

## 0.6.0-keycardai-starlette (2026-06-03)


- feat(keycardai-starlette): add require_authentication to protected_router

## 0.5.0-keycardai-starlette (2026-06-02)


- build(keycardai-starlette): require keycardai-oauth>=0.13.0 for request_scopes
- The grant() decorator now passes request_scopes to
exchange_tokens_for_resources, a parameter added in keycardai-oauth
0.13.0, so raise the dependency floor accordingly.
- feat(keycardai-starlette): thread request_scopes through grant()
- Expose request_scopes on the grant decorator and pass it to
exchange_tokens_for_resources so scope-gated delegation works for
Starlette/FastAPI endpoints.

## 0.4.0-keycardai-starlette (2026-05-01)


- refactor(keycardai-starlette)!: remove deprecated BearerAuthMiddleware shims (ACC-237) (#109)
- Removed deprecated BearerAuthMiddleware shims after all consumers migrated to AuthenticationMiddleware + KeycardAuthBackend, eliminating unused auth code. This is a breaking change—imports for BearerAuthMiddleware and verify_bearer_token now fail.

## 0.3.0-keycardai-starlette (2026-04-27)


- feat(keycardai-starlette): emit DeprecationWarning from BearerAuthMiddleware and verify_bearer_token (#99)
- Closes ACC-234. PR #97 retained the legacy bearer surface as docstring-only deprecated shims so keycardai-mcp and keycardai-agents keep working until they migrate (ACC-235, ACC-229..232). Without a runtime signal, non-MCP downstream users importing these symbols get no notice before the symbols disappear.
- Changes:
- BearerAuthMiddleware.__init__ emits DeprecationWarning pointing at AuthenticationMiddleware + KeycardAuthBackend
- verify_bearer_token emits DeprecationWarning pointing at KeycardAuthBackend
- BearerAuthMiddleware.dispatch passes _from_middleware=True so a single middleware instantiation fires exactly one warning total, not one per request
- New tests: warning fires on init, warning fires on direct verify_bearer_token call, dispatch path does not double-warn
- _create_auth_challenge_response is intentionally not warned: it is underscored, not in __all__, and not re-exported by the keycardai-mcp shims, so no external caller can plausibly hit it directly.
- Verified mcp tests still pass (560/560). Agents tests fail on a pre-existing a2a-sdk import error unrelated to this change.

## 0.2.0-keycardai-starlette (2026-04-26)


- feat(keycardai-starlette): new package for Starlette/FastAPI Keycard integration (#97)
- * feat(keycardai-starlette-oauth): new package for Starlette/FastAPI OAuth middleware
- Implements Tier 2 of the Protocol-Agnostic SDK KEP: a new
keycardai-starlette-oauth package that provides Starlette-specific
middleware and route builders without any MCP dependency.
- New package (packages/starlette-oauth/):
- middleware/bearer.py: BearerAuthMiddleware
- handlers/metadata.py: RFC 9728 + RFC 8414 metadata with local
  ProtectedResourceMetadata model (no mcp.shared.auth dependency)
- handlers/jwks.py: JWKS endpoint handler
- routers/metadata.py: Route builders + protected_router()
- provider.py: AuthProvider with install() and @protect() decorator
- shared/starlette.py: Proxy-aware URL helpers
- keycardai-mcp changes:
- Now depends on keycardai-starlette-oauth (starlette removed from
  direct deps since it comes transitively)
- Server middleware/handlers/routers replaced with re-export shims
- protected_mcp_router wraps protected_router with mcp_app kwarg compat
- All existing imports continue to work
- * refactor(keycardai-starlette): rename from keycardai-starlette-oauth
- Per revised KEP naming decisions: drop the OAuth suffix from the
customer-facing package since it will cover more than just OAuth
(token exchange, policy enforcement, vaulted creds, etc.). The
keycardai-oauth package stays as an internal building block.
- Renames:
- packages/starlette-oauth/ → packages/starlette/
- src/keycardai/starlette_oauth/ → src/keycardai/starlette/
- keycardai-starlette-oauth → keycardai-starlette (PyPI name)
- keycardai.starlette_oauth → keycardai.starlette (import path)
- Updated workspace source, MCP dependency, and all MCP shim imports.
Backward-compat shims in keycardai-mcp continue to work.
- * feat(keycardai-starlette): add smoke tests and fix .well-known middleware bypass
- - Add 22 smoke tests covering metadata routes, AuthProvider install/config,
  and a guarantee that keycardai.starlette has no keycardai.mcp imports.
- Fix BearerAuthMiddleware to skip /.well-known/* paths. Without this,
  AuthProvider.install() (which adds the middleware globally) blocked the
  OAuth discovery endpoints it had just registered — clients got 401 trying
  to learn how to authenticate. Metadata discovery per RFC 9728 §2 must
  remain publicly reachable.
- Add fastapi and httpx to the starlette package test extras.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * chore: adjust coverage thresholds after starlette extraction
- - Add keycardai-starlette to test-coverage and test recipes
- Lower mcp threshold from 65% to 60%: the well-tested server auth code
  moved to keycardai-oauth / keycardai-starlette, leaving a higher
  proportion of under-tested client integrations (CrewAI/LangChain/OpenAI
  adapters at 14-25%) in the denominator. Absolute coverage of the
  remaining code is unchanged; the ratio is what shifted.
- Set starlette threshold to 55% (smoke tests cover the surface area;
  provider.py @protect() decorator and async client init are the main
  gap, tracked as a follow-up)
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * fix(scripts): pass --yes to cz bump in version_preview for new packages
- Commitizen prompts "Is this the first tag created?" when it cannot find an
existing tag matching a package's tag_format. For brand-new packages like
keycardai-starlette that have no tag yet, this prompt EOFs in non-TTY CI
runs and causes release-preview to report an error instead of a version
delta.
- --yes auto-confirms the prompt. Existing packages with prior tags never
see the prompt, so their output is unchanged.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * chore: regenerate uv.lock with uv >= 0.9 format
- Older lock file (generated with uv 0.8.x) failed to parse on CI's newer
uv with "Dependency `pytokens` has missing `source` field but has more
than one matching package". The lock format tightened in 0.9+ to require
explicit source annotations when multiple resolution markers are in play.
- Regenerated with uv 0.11.7. Resolution now succeeds under setup-uv@v4
(unpinned, tracks latest). All package test suites still pass
(oauth 208, starlette 22, mcp 560, mcp-fastmcp 51).
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * ci: wire keycardai-starlette into release workflow tag filter
- The release workflow only triggers on tag patterns explicitly listed in
on.push.tags. Without adding *-keycardai-starlette, tags created by
commitizen for the new package (e.g. 0.1.0-keycardai-starlette) would
not trigger the release job, so nothing would publish to PyPI even if a
Trusted Publisher were configured.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * chore: minimize uv.lock diff to just the keycardai-starlette addition
- The previous regeneration pass rebuilt the lock wholesale and produced
a 5-marker resolution format (splitting python_full_version >= '3.14'
into '3.15' and '3.14.*'). CI's uv 0.11.7 could not parse that,
failing with "pytokens has missing source field but has more than one
matching package" during uv sync --all-extras.
- Revert to origin/main's lock and re-run `uv lock --no-upgrade`, which
adds only the keycardai-starlette workspace member (34-line diff) and
leaves the resolution-markers block identical to main. CI parses it
cleanly; all package test suites pass.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * style: trim verbose comments added during review
- Condense the justfile coverage-threshold note and version_preview.py
--yes flag comment to one sentence each.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * fix(keycardai-starlette): address PR review feedback from cmars
- Seven correctness and style fixes:
- 1. bearer.py: tighten the auth-bypass path match. The previous
   `path.startswith("/.well-known/")` exempted ALL well-known URIs (e.g.
   `/.well-known/change-password`, `assetlinks.json`) from bearer auth.
   Replace with an explicit allowlist of OAuth metadata endpoints
   (`oauth-protected-resource`, `oauth-authorization-server`, `jwks.json`),
   matched as exact paths or delimited subpaths. Cite RFC 9728 §2 / RFC
   8414 §3 as the spec basis.
- 2. provider.py `_get_or_create_client`: the parameter was annotated
   `dict[str, str] | None = None` but every line dereferenced it
   unguarded. Drop the Optional from the signature; callers always pass
   a non-None dict.
- 3. provider.py `__init__`: construct `_init_lock = asyncio.Lock()`
   eagerly instead of lazily. The previous `if self._init_lock is None:
   self._init_lock = asyncio.Lock()` was technically safe in pure
   asyncio (no await between check and assign) but reads as a race
   smell. Eager init removes the question. asyncio.Lock can be created
   outside an event loop in Python 3.10+.
- 4. provider.py docstring: rephrase the AuthProvider class docstring to
   describe what the class does instead of what it lacks ("without any
   MCP dependency").
- 5. handlers/metadata.py `protected_resource_metadata`: return
   `JSONResponse(content=dict)` instead of `Response(content=json_string)`.
   The previous implementation served `Content-Type: text/plain`.
- 6. handlers/metadata.py `authorization_server_metadata`: pass an explicit
   `timeout=httpx.Timeout(5.0)` to `httpx.Client` so a slow upstream
   cannot pin a Starlette threadpool worker indefinitely. Switch the
   error responses to JSONResponse for the same Content-Type reason.
- 7. shared/starlette.py `get_base_url`: guard against `None` port. When
   `request_base_url.port` is None (proxy stripped it, missing from
   pydantic parsing), the previous code interpolated `:None` into the
   URL string. Now treat None like the default ports (omit).
- Adds regression tests:
- `/.well-known/change-password` returns 401 (path-specific bypass)
- `/.well-known/oauth-protected-resource/zone-id/path` returns 200
- `_init_lock` is an asyncio.Lock after `__init__`
- `Content-Type` is `application/json` on the metadata response
- `httpx.Client` is constructed with an explicit `timeout=` kwarg
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * refactor(keycardai-starlette): make install() per-route opt-in instead of whole-app lockdown
- The previous install() shape added BearerAuthMiddleware globally so every
route in the FastAPI/Starlette app required a bearer token. A /health or
/version endpoint returned 401, which contradicts the framing in the
Protect Any API guide ("an API that knows which agent is calling") and the
existing per-subtree code patterns the docs already show
(BearerAuthMiddleware on a Mount, protected_mcp_router(...)).
- After this change:
- install(app) adds OAuth metadata routes only (.well-known/oauth-*).
  No global middleware. Routes are public by default.
- @auth.protect() (no args) verifies the bearer token, returns 401 on
  missing/invalid. No delegation, no AccessContext required.
- @auth.protect("resource") verifies + runs delegated token exchange and
  populates an AccessContext as before.
- protected_router() is unchanged. Still the right pattern for protecting
  a whole subtree (MCP transport, internal admin app, etc.).
- Implementation:
- Extract the verification body of BearerAuthMiddleware.dispatch() into a
  free verify_bearer_token(request, verifier) helper that returns either an
  auth_info dict on success or an RFC 6750 challenge Response on failure.
  Both the middleware and the decorator call it.
- The decorator reuses request.state.keycardai_auth_info if the middleware
  already populated it (e.g. inside a protected_router() mount), otherwise
  calls verify_bearer_token itself and returns the 401 directly on failure.
- AccessContext lookup and injection only run when resources is set.
- Test changes:
- Removed test_install_rejects_requests_without_bearer_token (old contract).
- Removed test_install_does_not_bypass_unrelated_well_known_paths (without
  global middleware, /.well-known/change-password is now a 404, which the
  framework provides; nothing for us to assert here).
- Added test_install_does_not_block_unprotected_routes: /health stays 200.
- Added test_install_does_not_add_global_middleware: BearerAuthMiddleware
  is NOT in app.user_middleware after install().
- Added TestProtectDecorator class:
  - no-args form returns 401 without bearer
  - resource form returns 401 without bearer
  - no-args form does not require AccessContext on the function signature
  - decorator reuses request.state when middleware preset it (verify_token
    asserts if called)
- README and module docstrings rewritten to show the new model with three
distinct patterns (decorator no-args, decorator with resource, protected_router).
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * style(keycardai-starlette): drop temporal/historical comments and tighten test names
- The previous refactor commit shipped a few comments framed against the
prior code shape ("Reuse middleware-set auth info if BearerAuthMiddleware
ran ... otherwise verify the bearer token here") and a couple of
section-header style comments restating what the code does. Drop them.
Move the "two-call-sites" framing out of the verify_bearer_token
docstring; describe the present contract.
- Rename test_install_does_not_add_global_middleware to
test_install_leaves_user_middleware_stack_empty and
test_install_does_not_block_unprotected_routes to
test_routes_without_protect_decorator_stay_public for clearer positive
framing.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * Kamil/starlette auth model (#98)
- * align keycardai-starlette with starlette authentication framework
- * add protected_resource_server example for keycardai-starlette
- * prevent transitive load_dotenv from polluting mcp test environment
- * fix(lint): resolve ruff B026 and I001 errors after merging #98
- Three errors flagged by `just check` after the #98 merge:
- - packages/mcp/tests/conftest.py: B026 star-arg unpacking after keyword
  argument. Forward dotenv_path/stream positionally to the real load_dotenv.
- packages/starlette/src/keycardai/starlette/authorization.py: I001 import
  ordering (auto-fixed).
- packages/starlette/src/keycardai/starlette/provider.py: I001 import
  ordering (auto-fixed).
- All test suites still pass: starlette 42, mcp 560, oauth 208, mcp-fastmcp 51.
- Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- * refactor(keycardai-starlette): tighten review findings before merge
- - mcp.server.routers re-exports the protected_mcp_router wrapper so the
  mcp_app= kwarg keeps working through the package-level import
- consolidate the RFC 6750 challenge response into one helper shared by
  keycard_on_error and the @requires/@auth.grant decorators
- drop KeycardUser.resource_client_id (was always equal to
  resource_server_url); grant.wrapper reads resource_server_url for both
  auth_info dict keys
- type _get_or_create_client auth_info as dict[str, str | None] so
  zone_id is no longer mistyped as str
- replace test that asserted staticmethod identity with regression tests
  for the well-known bypass: OAuth metadata paths short-circuit, sibling
  paths (change-password, security.txt, oauth-protected-resource-fake,
  openid-configuration) still raise KeycardAuthError
- rewrite test_no_auth_header_returns_none to call the backend directly
  instead of building a FastAPI app and patching middleware kwargs
- ---------
- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Kamil <kamil@keycard.ai>
Changelog for keycardai-mcp:
## Unreleased

## 0.26.0-keycardai-mcp (2026-06-15)


- feat(keycardai-mcp): resolve multi-zone credentials by zone issuer URL
- The provider looks up per-zone credentials with the zone-scoped issuer
URL it already constructs for the zone client.

## 0.25.0-keycardai-mcp (2026-06-03)


- fix(keycardai-mcp)!: enforce authentication on the MCP mount
- build(keycardai-mcp): require keycardai-starlette>=0.6.0 for require_authentication
- fix(keycardai-mcp): read delegated auth info from request.user

## 0.24.0-keycardai-mcp (2026-06-02)


- test(keycardai-mcp): use generic scope in grant request_scopes tests
- Replace the databricks-specific scope with a generic "read".
- feat(keycardai-mcp): add request_scopes to grant()
- Forward an optional per-resource OAuth scope into the token exchange,
including the impersonation branch (client.impersonate(scope=...)) plus
the application-credential and basic branches. Accepts a str, list[str],
or per-resource dict; distinct from inbound required_scopes.

## 0.23.0-keycardai-mcp (2026-04-28)


- refactor(keycardai-mcp): drop deprecated bearer middleware shims (ACC-235) (#104)
- Removes the keycardai.mcp.server.middleware re-export shims that pointed
at the deprecated BearerAuthMiddleware in keycardai-starlette. Anyone
importing BearerAuthMiddleware should switch to AuthenticationMiddleware
with backend=KeycardAuthBackend(verifier) and on_error=keycard_on_error.
The deprecated symbols themselves stay in keycardai-starlette and come
out in ACC-237.
- keycardai-agents repointed at keycardai.starlette.middleware.bearer so
it keeps building. It still emits the DeprecationWarning shipped in
keycardai-starlette 0.3.0; that goes away when ACC-232 archives the
package.
- Bearer-helper unit tests (_get_bearer_token, _get_oauth_protected_resource_url)
moved from packages/mcp/tests to packages/starlette/tests where the
helpers live.

## 0.22.0-keycardai-mcp (2026-04-24)


- fix(keycardai-mcp): resolve ruff lint errors in provider and test imports

## 0.21.0-keycardai-mcp (2026-03-06)


- build(keycardai-mcp): bump keycardai-oauth dependency to >=0.7.0
- refactor(keycardai-mcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.20.1-keycardai-mcp (2026-02-06)


- fix(keycardai-mcp): return prm for resources dynamically

## 0.20.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Adds PydanticAI integration for MCP frameworks
- - Adds PaydanticAI adapter to client integrations directory
- Support for PydanticAI agents with secure MCP tool access
- Follows established pattern with LangChain and OpenAI integrations
- Adds tests for PydanticAI integration imports

## 0.19.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Add greater control over OAuth metadata location
- - Refactors `auth_metadata_mount` into it's component parts
- Exposes mounts for individual metadata
- Allows the user to specify exactly where their OAuth metadata is
exposed
- NOTE: This is only for advanced use cases where you know you need
something non-standard. Otherwise, follow the OAuth spec.

## 0.18.0-keycardai-mcp (2025-12-04)


- feat(keycardai-mcp): add CrewAI integration for agent frameworks
- - Add CrewAI adapter to client integrations directory
- Support for CrewAI agents with secure MCP tool access
- No token passing - agents never receive raw API tokens
- Fresh token fetched per API call through Keycard
- Follows established pattern with LangChain and OpenAI integrations
- Deleted separate packages/agents package (not needed)
- Added optional dependencies: crewai and agents extras
- Added tests for CrewAI integration imports

## 0.17.0-keycardai-mcp (2025-11-18)


- feat(keycardai-mcp): session callback notification
- feat(keycardai-mcp): session lifecycle management

## 0.16.0-keycardai-mcp (2025-11-17)


- feat(keycardai-mcp): headless clients
- feat(keycardai-mcp): update oauth deps
- feat(keycardai-mcp): client implementation

## 0.15.0-keycardai-mcp (2025-11-07)


- feat(keycardai-mcp): enable web token eks env

## 0.14.0-keycardai-mcp (2025-11-06)


- feat(keycardai-mcp): configure mcp url via env

## 0.13.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): zone settings via env

## 0.12.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): automatic app cred discovery
- feat(keycardai-mcp): default eks env

## 0.11.0-keycardai-mcp (2025-10-29)


- feat(keycardai-mcp): release latest version
- Release current version of workload identity implementation

## 0.10.0-keycardai-mcp (2025-10-27)


- feat(keycardai-mcp): cach the application credentials
- feat(keycardai-mcp): app credential grant flow

## 0.9.0-keycardai-mcp (2025-10-20)


- refactor(keycardai-mcp): align credential names
- feat(keycardai-mcp): eks workload identity support
- feat(keycardai-mcp): add application authentication

## 0.8.1-keycardai-mcp (2025-10-10)


- fix(keycardai-mcp): wrong base url in auth metadata

## 0.8.0-keycardai-mcp (2025-10-07)


- refactor(keycardai-mcp): improve error messages
- refactor(keycardai-mcp): improves the error messages to provide useful debug information

## 0.7.1-keycardai-mcp (2025-09-29)


- fix(keycardai-mcp): set audience for client assertions

## 0.7.0-keycardai-mcp (2025-09-27)


- feat(keycardai-mcp): lowlevel support for RequestContext

## 0.6.0-keycardai-mcp (2025-09-23)


- feat(keycardai-mcp): enable custom middleware injection

## 0.5.1-keycardai-mcp (2025-09-22)


- fix(keycardai-mcp): support x-forwarded-port header

## 0.5.0-keycardai-mcp (2025-09-22)


- feat(keycardai-mcp): dcr can be toggled on/off
- feat(keycardai-mcp): private key jwt support with global key
- feat(keycardai-mcp): grant decorator exception handling
- feat(keycardai-mcp): private key manager protocol

## 0.4.1-keycardai-mcp (2025-09-18)


- fix(keycardai-mcp): support both sync and async tool calls

## 0.4.0-keycardai-mcp (2025-09-18)


- feat(keycardai-mcp): default domain handling

## 0.3.1-keycardai-mcp (2025-09-17)


- fix(keycardai-mcp): check audience when configured

## 0.3.0-keycardai-mcp (2025-09-16)


- feat(keycardai-mcp): multi-zone mcp routing
- feat(keycardai-mcp): advanced server handlers
- feat(keycardai-mcp): auth provider implementation

## 0.1.0-keycardai-mcp (2025-09-10)
Changelog for keycardai-mcp-fastmcp:
## Unreleased

## 0.21.0-keycardai-mcp-fastmcp (2026-04-27)


- feat(keycardai-mcp-fastmcp): release deprecation bridge for keycardai-fastmcp (#103)
- Empty commit to trigger the auto-bump pipeline for keycardai-mcp-fastmcp.
- The actual bridge code (depends on keycardai-fastmcp, re-exports every
public symbol at the original keycardai.mcp.integrations.fastmcp.* paths,
emits DeprecationWarning on top-level import) shipped in #102. That PR
landed scoped (keycardai-fastmcp), so cz only bumped the new package and
keycardai-mcp-fastmcp on PyPI is still the pre-rename version. This
commit gives cz a (keycardai-mcp-fastmcp)-scoped feat to recognize so
the bridge ships as the next published version and customers on the
old name see the deprecation warning.

## 0.20.0-keycardai-mcp-fastmcp (2026-04-01)


- feat(keycardai-mcp-fastmcp): upgrade to FastMCP 3.0
- Upgrade keycardai-mcp-fastmcp from fastmcp>=2.14.0,<3.0.0 to fastmcp>=3.0.0.
- Key changes:
- ctx.get_state()/ctx.set_state() are now async (FastMCP 3.0 breaking change)
- grant decorator uses await ctx.set_state(..., serializable=False)
- All examples, docs, and tests updated for async state access
- Test mocks updated to use async functions for get_state/set_state

## 0.19.0-keycardai-mcp-fastmcp (2026-03-06)


- refactor(keycardai-mcp-fastmcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.18.1-keycardai-mcp-fastmcp (2025-11-23)


- fix(keycardai-mcp-fastmcp): include subject in debug

## 0.18.0-keycardai-mcp-fastmcp (2025-11-20)


- feat(keycardai-mcp-fastmcp): debug information for exchange

## 0.17.0-keycardai-mcp-fastmcp (2025-11-17)


- feat(keycardai-mcp-fastmcp): update oauth deps

## 0.16.0-keycardai-mcp-fastmcp (2025-11-07)


- feat(keycardai-mcp-fastmcp): enable web token eks env

## 0.15.0-keycardai-mcp-fastmcp (2025-11-06)


- feat(keycardai-mcp-fastmcp): configure mcp url via env

## 0.14.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): configure zone setting via env

## 0.13.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): automatic app cred discovery

## 0.12.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): support fastmcp 2.13

## 0.11.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): keycardai mcp dep update
- Reverts the eks workload identity changes

## 0.10.0-keycardai-mcp-fastmcp (2025-10-27)


- feat(keycardai-mcp-fastmcp): use application cred cache

## 0.9.0-keycardai-mcp-fastmcp (2025-10-20)


- feat(keycardai-mcp-fastmcp): EKS workload identity

## 0.8.1-keycardai-mcp-fastmcp (2025-10-07)


- refactor(keycardai-mcp-fastmcp): improve error message with debug context

## 0.8.0-keycardai-mcp-fastmcp (2025-10-01)


- feat(keycardai-mcp-fastmcp): ability to mock internal access context for testing

## 0.7.0-keycardai-mcp-fastmcp (2025-09-27)


- refactor(keycardai-mcp-fastmcp): remove the error codes from AccessContext

## 0.6.0-keycardai-mcp-fastmcp (2025-09-22)


- feat(keycardai-mcp-fastmcp): unify exceptions with keycardai-mcp package

## 0.5.0-keycardai-mcp-fastmcp (2025-09-21)


- feat(keycardai-mcp-fastmcp): client factory and base url update

## 0.4.1-keycardai-mcp-fastmcp (2025-09-19)


- fix(keycardai-mcp-fastmcp): lock the oauth dependency

## 0.4.0-keycardai-mcp-fastmcp (2025-09-18)


- feat(keycardai-mcp-fastmcp): refactor API for the provider

## 0.3.0-keycardai-mcp-fastmcp (2025-09-15)


- feat(keycardai-mcp-fastmcp): unify client arguments

## 0.2.0-keycardai-mcp-fastmcp (2025-09-10)


- fix(keycardai-mcp-fastmcp): pin fastmcp for compatibiity
- feat(keycardai-mcp-fastmcp): allowed to override the client

## 0.1.0-keycardai-mcp-fastmcp (2025-09-07)
Changelog for keycardai-fastmcp:
## Unreleased

## 0.4.0-keycardai-fastmcp (2026-06-02)


- refactor(keycardai-fastmcp): use generic scope in request_scopes examples
- Replace the databricks-specific scope with a generic "read" in the
grant() docstring and tests so the example is not tied to one provider.
- feat(keycardai-fastmcp): add request_scopes to grant()
- Forward an optional per-resource OAuth scope into the RFC 8693 token
exchange so scope-gated Keycard delegation policies can match. Accepts a
str, list[str], or per-resource dict; distinct from inbound
required_scopes. Sets scope on the request in both the application
credential and basic branches.

## 0.3.0-keycardai-fastmcp (2026-05-20)


- fix(keycardai-fastmcp): trigger version bump for audience and wif key_id fixes

## 0.2.0-keycardai-fastmcp (2026-04-27)


- feat(keycardai-fastmcp): rename keycardai-mcp-fastmcp via bridge package (ACC-233) (#102)
- * feat(keycardai-fastmcp): rename keycardai-mcp-fastmcp via bridge package (ACC-233)
- The current name carries a redundant -mcp suffix (FastMCP only speaks MCP,
so the protocol tag adds no information). Renames to keycardai-fastmcp per
the revised KEP, with keycardai-mcp-fastmcp preserved as a deprecation
bridge so the customer in production on the old name keeps working
indefinitely.
- What ships:
- * New keycardai-fastmcp package at packages/fastmcp/, full implementation
  under the keycardai.fastmcp namespace. Tests, examples, README move with
  the source. Wired into the workspace and the release.yml tag filter.
* Deprecated keycardai-mcp-fastmcp now depends only on keycardai-fastmcp
  and re-exports every public symbol at the original
  keycardai.mcp.integrations.fastmcp.* paths. Importing the top-level
  module emits a DeprecationWarning pointing at the canonical name.
* Bridge contract test (test_bridge.py, 4 tests) asserts the
  DeprecationWarning fires and that bridge symbols are identity-equal to
  the canonical ones. The full behavioral suite lives in keycardai-fastmcp
  going forward.
- Customer impact: pip install keycardai-mcp-fastmcp keeps working; the
package transitively pulls keycardai-fastmcp. No forced removal timeline,
the bridge ships until every known caller migrates.
- Verified: ruff clean. fastmcp 51/51, mcp-fastmcp bridge 4/4, mcp 560/560,
oauth 208/208, starlette 49/49.
- Supersedes the canceled ACC-195 (which used the now-rejected
keycardai-fastmcp-mcp name).
- * fix(keycardai-fastmcp): bridge re-exports the full canonical surface
- Review caught that the bridge provider.py only re-exported a hand-enumerated
subset of the canonical surface, dropping documented public symbols
(get_token_debug_info, introspect, INTROSPECT, AuthProviderConfigurationError,
AuthProviderInternalError, AuthProviderRemoteError). Importing any of those
from keycardai.mcp.integrations.fastmcp.provider raised ImportError, breaking
the bridge contract for downstream callers using less common symbols.
- Fixes:
- - Add __all__ to keycardai.fastmcp.provider listing the 28-name public
  surface. Stdlib/typing helpers (logging, os, urlparse, wraps, Any,
  Callable, etc.) are deliberately excluded.
- Replace the bridge provider.py hand-enumeration with
  ``from keycardai.fastmcp.provider import *``, plus a re-export of __all__
  so future symbol additions to the canonical module flow through
  automatically.
- Add test_bridge_provider_exposes_full_public_surface: iterates the
  canonical __all__, asserts every symbol is present at the bridge path
  and identity-equal to the canonical reference. Regression test for the
  symbol-drop class of bug.
- Scrub em dashes from the renamed example READMEs (pre-existing prose,
  but new file paths shipping under our review).
- Verified: fastmcp 51/51, mcp-fastmcp bridge 5/5 (was 4 + 1 new). Smoke:
the six previously-missing symbols now import cleanly from the old path.
- * ci: pin extractions/setup-just version
- The action stopped resolving "latest" sometime today and started failing
with `no release for just matching version specifier`. Pinning unblocks
PR validation and the post-merge bump-and-publish pipeline.
- 1.50.0 is the current stable just release (April 2026).
- * ci: replace extractions/setup-just with the upstream install script
- extractions/setup-just@v2 is currently broken for both unpinned and
explicit-version requests ("no release for just matching version
specifier"). Pinning to 1.50.0 did not help because the action regression
is in its release lookup, not its version resolution.
- Switch to the just.systems install script (the project owners ship and
maintain it). Runs as a plain bash step with no third-party action
dependency and is unaffected by setup-just regressions.
Changelog for keycardai-a2a:
## Unreleased

## 0.3.0-keycardai-a2a (2026-05-01)


- fix(keycardai-a2a)!: align DelegationClient with a2a-sdk 1.x JSONRPC dispatcher (ACC-231) (#107)
- DelegationClient was still speaking 0.x JSON-RPC (“message/send”, old envelope, no A2A-Version), so every call was rejected by real 1.x dispatchers before execution—breaking the entire keycardai-crewai delegation path. Fixed by upgrading to the 1.x contract (SendMessage, proper envelope + headers, new response shape) and adding a real dispatcher test to catch drift.

## 0.2.0-keycardai-a2a (2026-04-29)


- feat(keycardai-a2a): new package split from keycardai-agents (ACC-230) (#105)
- * feat(keycardai-a2a)!: new package split from keycardai-agents (ACC-230)
- Per the KEP "Decompose keycardai-agents", the A2A delegation surface moves
out of keycardai-agents into a new keycardai-a2a package, structurally
analogous to keycardai-mcp. Symbols available at the new namespace:
- - AgentServer, create_agent_card_server, serve_agent
- DelegationClient, DelegationClientSync
- AgentExecutor, SimpleExecutor, LambdaExecutor
- KeycardToA2AExecutorBridge
- ServiceDiscovery
- AgentServiceConfig
- The bearer middleware in server/app.py also migrates from the deprecated
BearerAuthMiddleware to the canonical KeycardAuthBackend +
AuthenticationMiddleware pattern from keycardai-starlette. The
keycardai-mcp dependency drops from this code path.
- Hard cut, no transitional bridge: ACC-232 confirms no known production
users of keycardai.agents.* paths.
- The PKCE user-login client (AgentClient) is dropped entirely. Its
capability already lives in keycardai-oauth as
keycardai.oauth.pkce.authenticate (ACC-229 / #101). The duplicate in
keycardai-agents is removed.
- What stays in keycardai-agents: the CrewAI integration only, with its
imports repointed at keycardai.a2a. ACC-231 will move it to a dedicated
keycardai-crewai; ACC-232 will archive the now-stub source directory.
- BREAKING:
- from keycardai.agents import AgentServer, DelegationClient, ...
  becomes from keycardai.a2a import ... .
- from keycardai.agents.client import AgentClient is gone; use
  keycardai.oauth.pkce.authenticate.
- keycardai-agents 0.3.0 ships with the dependency set reduced to
  keycardai-a2a + pydantic, mirroring its now-CrewAI-only scope.
- * fix(keycardai-a2a): apply migration edits to moved files (ACC-230)
- The first commit on this branch did the git mv's but staged the new
files only; the Edit-tool modifications to the moved files (import
rewrites, server/app.py bearer-wiring migration to KeycardAuthBackend +
AuthenticationMiddleware, example pyproject swap from keycardai-agents
to keycardai-a2a, conftest/tests import repoints, agents/__init__.py
trim, agents/pyproject dep set, crewai integration repoint, top-level
workspace sources, justfile test recipe, uv.lock refresh) all sat
uncommitted. CI rejected the prior commit because the example pyproject
still claimed keycardai-agents at packages/a2a/, conflicting with the
real keycardai-agents at packages/agents/ in the workspace graph.
- This commit lands the actual migration content. Tests pass locally:
keycardai-a2a 60/60, keycardai-agents 16/16, no regression in oauth /
starlette / mcp / mcp-fastmcp / fastmcp; ruff workspace check clean.
- * refactor(keycardai-a2a)!: wrap a2a-sdk 1.x, drop parallel surface (ACC-230)
- Aligns keycardai-a2a with the wrap-do-not-reinvent pattern used in
keycardai-mcp and keycardai-starlette: customers implement a2a-sdk native
async AgentExecutor directly; this package contributes only Keycard auth
wiring, OAuth metadata discovery, and convenience composition.
- Drops the parallel-protocol surface inherited from the keycardai-agents
move:
- AgentExecutor protocol (sync execute(task, inputs)) and SimpleExecutor /
  LambdaExecutor implementations
- KeycardToA2AExecutorBridge (the sync->async adapter that existed only to
  bridge our protocol to a2a-sdk)
- Custom POST /invoke endpoint with bespoke InvokeRequest / InvokeResponse
  Pydantic models alongside the standard A2A JSONRPC interface
- AgentServiceConfig.invoke_url (replaced by jsonrpc_url) and
  AgentServiceConfig.to_agent_card() (the 0.x dict-shape constructor)
- Migrates from a2a-sdk 0.x to 1.x natively:
- pyproject pin a2a-sdk[http-server]>=1.0
- Server composition uses route factories (create_jsonrpc_routes,
  create_agent_card_routes) instead of the gone A2AStarletteApplication
- Request handler is DefaultRequestHandlerV2 (alias DefaultRequestHandler)
- AgentCard built from 1.x protobuf schema (supported_interfaces,
  AgentCapabilities streaming/push_notifications/extended_agent_card)
- Example main.py uses a2a-sdk 1.x Client via create_client + A2ACardResolver
- Adds a KeycardServerCallContextBuilder that subclasses a2a-sdk default
builder and stashes the verified KeycardUser plus access_token into
ServerCallContext.state so AgentExecutor implementations can read the
bearer token from context.call_context.state["access_token"] for
downstream delegated token exchange.
- Tests:
- a2a 44/44 pass
- agents 16/16 pass with crewai extra
- ruff clean
- Note: the high-level @auth.grant decorator parity with keycardai-mcp is
not yet shipped here. Customers use DelegationClient (already in this
package) for explicit server-to-server delegation. The decorator port is
a follow-up.
- * fix(keycardai-a2a): address review findings on PR #105
- Three blockers caught in fresh-eyes review:
- 1. release.yml tag-trigger list was hardcoded; *-keycardai-a2a was missing,
   so the post-merge auto-bump would push the tag but the publish workflow
   would never trigger. Trusted Publisher being registered would have been
   moot.
- 2. DelegationClient.invoke_service hardcoded service_url + /invoke. The
   wrap-aligned server only exposes /a2a/jsonrpc; calling invoke_service
   against any 1.x server returned 404. The CrewAI delegation tool runs
   through this code path. Both async and sync variants now build a
   message/send JSONRPC envelope, POST it to /a2a/jsonrpc, and unwrap the
   result to preserve the legacy {result, delegation_chain} shape so the
   CrewAI integration keeps working unchanged.
- 3. discover_service in both DelegationClient and ServiceDiscovery validated
   the 0.x card shape (required_fields = [name, endpoints, auth]). The 1.x
   protobuf-derived JSON has none of endpoints / auth. Discovery against
   any 1.x server raised ValueError. Validation now requires only "name";
   transport / auth specifics live under supportedInterfaces and the OAuth
   metadata routes.
- Plus four important findings:
- 4. Test mocks across conftest.py, test_a2a_client.py, test_discovery.py,
   and test_crewai_a2a.py used the old shape (endpoints/auth keys). Tests
   passed because the validator wrongly accepted them. Mocks now use the
   1.x JSON shape (supportedInterfaces, capabilities object, skills with
   id/name).
- 5. A2AServiceClient and A2AServiceClientSync backward-compat aliases at
   the bottom of delegation.py contradicted the "hard cut, no transitional
   bridge" stance in the PR description. Removed.
- 6. TestJsonRpcAuthGate.test_jsonrpc_requires_authorization asserted
   status_code in (400, 401). 400 means the JSONRPC dispatcher saw the
   request and bailed on the body shape, not that the auth gate caught
   it. Pinned to == 401 with a WWW-Authenticate header check so the gate
   contract is enforced.
- 7. Zero coverage existed for _KeycardServerCallContextBuilder propagating
   the verified KeycardUser plus access_token into ServerCallContext.state.
   Added two unit tests that build the context directly: one with a
   KeycardUser asserting state["access_token"] is set, one with an
   UnauthenticatedUser asserting state["access_token"] is absent (so an
   executor reading it sees None rather than a stale token).
- Tests:
- a2a 47/47 (was 44; +3 new wrap-coverage tests)
- agents 16/16 with crewai extra
- ruff clean
- * refactor(keycardai-a2a)!: ship primitives, not a server abstraction (ACC-230)
- Per Kamil's review on PR #105: AgentServer / create_agent_card_server /
serve_agent presupposed customers want a fresh Starlette app dedicated to
the agent service. The wrap-don't-reinvent stance, taken seriously,
says: customers already have an a2a-sdk app in their head; we ship
primitives that slot Keycard auth into THAT, not a parallel server.
- Public surface change:
- Dropped:
  AgentServer, create_agent_card_server, serve_agent
Promoted to public (renamed off the underscore prefix):
  EagerKeycardAuthBackend
  KeycardServerCallContextBuilder
  build_agent_card_from_config
- AgentServiceConfig trimmed: dropped agent_executor (DefaultRequestHandler
takes its own), port and host (uvicorn's job), status_url (no /status
in the primitives layer).
- The composed-server flow moves to a runnable example at
packages/a2a/examples/keycard_protected_server/. README quickstart
rewritten to show primitive composition into an existing app; greenfield
users follow the example.
- Tests:
  a2a 44/44 (was 47; net -3 from dropping the /status endpoint tests
            and the port-validation test)
  agents 16/16 with crewai extra
  ruff clean
- This change is breaking, but the package is 0.1.0-pre-publish so no
customer is on these names yet.
- * fix(keycardai-a2a): ruff import-organization auto-fix
- * refactor(keycardai-starlette,keycardai-a2a): collapse EagerKeycardAuthBackend into KeycardAuthBackend kwarg (ACC-230)
- Per Kamil's second review observation on PR #105: with keycardai-a2a
now depending on keycardai-starlette, the question of WHERE these
primitives live matters. EagerKeycardAuthBackend was a 5-line subclass
that flipped one branch of KeycardAuthBackend.authenticate to raise on
missing Authorization, with no a2a-sdk specifics. The behavior is a
policy choice ("this mount requires auth"), not a different kind of
backend.
- Collapsed to a kwarg on the existing class:
-   KeycardAuthBackend(verifier)                              # default,
                                                            # mixed-route
  KeycardAuthBackend(verifier, require_authentication=True) # all-paths-protected
- The OAuth metadata bypass (RFC 9728 §2 / RFC 8414 §3) takes precedence
over the kwarg: even with require_authentication=True, requests to
/.well-known/oauth-* and /.well-known/jwks.json still pass through
anonymously per spec. New parametrized test asserts this.
- Net effect:
- One class instead of two; existing KeycardAuthBackend(verifier) callers
  unchanged.
- keycardai-a2a no longer ships EagerKeycardAuthBackend; the kwarg is
  used directly in tests, the example, and the README quickstart.
- Migration story is zero churn for existing users; new behavior is
  opt-in via the kwarg.
- Tests:
  starlette 40 passed (+2 new tests for the kwarg semantics)
  a2a 44 passed
  agents 16 passed
  ruff clean

---

This comment was automatically generated by the release preview workflow.