feat(keycardai-fastmcp): grant-as-dependency typed injection (deprecate get_state)

[Larry-Osakwe]

Implements ECO-133 (SDK Framework Support Expansion): moves FastMCP tools off the ctx.get_state("keycardai") magic string onto typed dependency injection, using FastMCP 3's own fastmcp.dependencies extension point.

What changed

Grant as a dependency. auth_provider.grant(...) now returns a GrantDependency (a fastmcp.dependencies.Dependency subclass). Declared as a parameter default, FastMCP resolves it per request: it reads the caller token via get_access_token(), performs the RFC 8693 exchanges, and injects the populated AccessContext. Errors are recorded on the context, never raised, preserving the existing error-capture contract.

@mcp.tool()
async def get_github_user(
    access: AccessContext = auth_provider.grant("https://api.github.com"),
) -> dict:
    ...

The same object still works as a decorator (@auth_provider.grant(...)), so both idioms share one entry point. The parameter is excluded from the generated tool input schema.

Deprecation path. The decorator spelling without a declared AccessContext parameter emits a DeprecationWarning at decoration time (once per tool) and keeps dual-writing set_state("keycardai", ...). Tools that declare the parameter get it injected with no warning.

_has_context fix. The identity check on ctx: Context annotations broke under from __future__ import annotations and ctx: Context | None. Replaced with get_type_hints-based resolution that handles string annotations, unions, and Annotated.

Escape hatch. AccessContext.from_context(ctx) for helpers called from inside tools; returns the stored context or an error-carrying AccessContext, never raises.

Public testing seam. New override_access_context(...) context manager in keycardai.fastmcp.testing. mock_access_context now installs a real preloaded AccessContext through it instead of patching module internals, with the same signature and matching error behavior (un-granted resources raise ResourceAccessError, as the real AccessContext and the old mock both did).

Public surface stays two nouns. The concepts a developer learns remain grant and AccessContext (per FRAMEWORK-INTEGRATIONS.md principle 2). GrantDependency is exported for type annotations only and documented as the return type of grant(), never constructed directly. The testing seam lives in .testing only, not the package root.

Compatibility note: fastmcp floor raised to >=3.1.0

The Dependency base class is exported from fastmcp.dependencies starting 3.1.0; on 3.0.x only Depends exists and the import fails, so the floor raise is unavoidable for this feature (package and both examples, manifests not just the lock). Consumers pinned to fastmcp 3.0.x must bump fastmcp when taking this minor; everything else is backward compatible (the decorator form keeps working and dual-writes set_state).

One second-order effect worth knowing (flagged in review): the DeprecationWarning fires at decoration time, i.e. module import. Setups that escalate warnings to errors (-W error, pytest filterwarnings = ["error"]) will fail at import for tools still on the bare decorator form. The README migration section documents this and shows the targeted filterwarnings allow-rule.

Review follow-ups applied

From an independent review pass: documented the all-or-nothing multi-resource grant contract (pre-existing behavior, now stated on GrantDependency and in the README), documented that the mock's bare-token form serves any resource and steered strict tests to resource_tokens, added a B008 per-file-ignore example for downstream linters, and commented the narrow false-positive window of the string-annotation fallback. Deliberately not changed: decoration-time warning stays (specced in ECO-133, once per tool, filterable), the mock's default-token behavior stays (pre-PR documented contract), and all-or-nothing stays (changing it is a cross-SDK contract decision, not a PR nit).

Docs. README quick start, docstrings, and the delegated_access example flipped to the injected-parameter form, plus new sections on error capture, from_context, and testing.

Deprecation timeline

v0.5.0 supports both forms and warns on the untyped decorator path; the set_state write is removed in v0.7.0 or 1.0.

Testing

85 tests pass in packages/fastmcp (24 new: injected happy path, end-to-end through a real FastMCP server via the in-memory client, decorator compatibility and once-per-tool warning, dual-write, exchange-failure capture, from_context, override seam, string and union ctx annotations). Bridge (packages/mcp-fastmcp, 5) and packages/mcp (542) suites green. just check clean.

Known gap, left for a follow-up to stay in scope: the justfile's test targets do not include packages/fastmcp, so CI does not run this package's suite today.

🤖 Generated with Claude Code

[github-actions]

📦 Release Preview

This analysis shows the expected release impact:

📈 Expected Version Changes

keycardai-fastmcp: 0.4.0 → 0.5.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-fastmcp",
    "package_dir": "packages/fastmcp",
    "has_changes": true,
    "current_version": "0.4.0",
    "next_version": "0.5.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.1-keycardai-oauth (2026-07-20)


- fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc (#195)
- * fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc
- authlib.jose is deprecated and emits an AuthlibDeprecationWarning on
import, surfacing to every SDK user. Migrate JWT signing/verification and
JWK handling to joserfc (authlib 's recommended replacement, already in
the dependency tree).
- - decode_and_verify_jwt: import key via joserfc, decode with explicit
  algorithms, return .claims
- get_jwks_key: return import_key(jwk).as_pem()
- create_client_assertion / key export: joserfc encode + import_key
- derive key type from the JWS algorithm so PEM imports do not emit
  joserfc's implicit-key SecurityWarning
- drop the direct authlib dependency (remains transitively via fastmcp)
- * fix(keycardai-oauth): reject unknown JWT algorithms; minimize lockfile diff
- Address review feedback on the joserfc migration:
- _key_type_for_algorithm now raises on an unrecognized algorithm instead
  of silently defaulting to RSA (a genuine mismatch previously failed later
  at key import / the algorithms=[...] gate; now it fails explicitly).
- Hand-restore uv.lock to a minimal authlib->joserfc swap. Regenerating
  under a newer uv had added unrelated python_full_version markers to
  transitive deps (aiologic, onnxruntime deps, sympy). joserfc was already
  present transitively, so only the oauth entry changes. Verified
  consistent with uv sync --frozen.
- * fix(keycardai-oauth): pin joserfc>=1.6.8 to clear GHSA advisories
- This PR promotes joserfc to a first-class dependency, so it must not ship
on a vulnerable floor. joserfc 1.6.4 is affected by:
- GHSA-gg9x-qcx2-xmrh (HIGH): HS256/384/512 verify accepts empty/nil HMAC key
- GHSA-wphv-vfrh-23q5 (MODERATE): b64=false RFC7797 JWS payload-size bypass
- 1.6.8 fixes both (superset of the two Socket bot PRs #189/#190, which
target 1.6.7 and 1.6.8). Root uv.lock resolves to 1.6.8; tests pass.
Neither advisory affects our own code path (we verify RS256), but a
correct floor matters for downstream consumers.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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

## 0.11.0-keycardai-starlette (2026-07-20)


- fix(keycardai-starlette): return 401/503 (not 500) for JWKS errors (#196)
- * 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
- * docs(keycardai-starlette): note the 503 bucket is intentionally narrow
- The 503 except clause lists the named JWKS discovery/fetch classes rather
than the OAuthServerError base on purpose: config and cache faults
(VerifierConfigError, CacheError) are not per-request failures and must
stay on the unexpected-error path (500), not be advertised as a
transient 503.
- Comment only, no behavior change.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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


- test(keycardai-fastmcp): end-to-end grant injection through a real FastMCP server
- Adds a round trip through FastMCP's in-memory client verifying the
injected AccessContext parameter is resolved per request and excluded
from the tool input schema. Ignores flake8-bugbear B008 in tests and
examples: auth_provider.grant(...) in a parameter default is the
intended injection spelling, matching how FastAPI treats Depends().
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- build(keycardai-fastmcp): raise fastmcp floor to >=3.1.0 for the Dependency extension point
- GrantDependency subclasses fastmcp.dependencies.Dependency. The
fastmcp.dependencies module exists since 3.0.0, but it only exports the
Dependency base class (via the uncalled-for DI engine) starting with
fastmcp 3.1.0; on 3.0.x the module exports Depends only, so
keycardai-fastmcp would fail to import. Raise the manifest floor in the
package and both examples accordingly (verified against the published
3.0.0/3.0.2 vs 3.1.0 wheels on PyPI).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- refactor(keycardai-fastmcp): move mock_access_context onto the public override seam
- mock_access_context previously patched module internals
(keycardai.fastmcp.provider.AccessContext and get_access_token). It now
builds a real AccessContext, preloaded with the requested tokens or error
state, and installs it through the public override_access_context() seam,
so grant resolution short-circuits on both the injected-parameter and
decorator paths without any patching.
- The yielded object is now a real AccessContext (subclassed only to serve a
default token for arbitrary resources), so assertions exercise the same
error paths as production code. override_access_context is re-exported
from keycardai.fastmcp.testing for tests that want to build the
AccessContext themselves.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- feat(keycardai-fastmcp): grant-as-dependency typed injection via fastmcp.dependencies
- AuthProvider.grant() now returns a GrantDependency, a fastmcp.dependencies
Dependency subclass. Declared as a typed parameter default
(access: AccessContext = auth_provider.grant(...)), FastMCP resolves it per
request: __aenter__ reads the caller token, performs the RFC 8693 exchanges,
and injects the populated AccessContext, hidden from the tool input schema.
Errors are recorded on the AccessContext, never raised, preserving the
existing error-capture contract.
- GrantDependency.__call__ keeps the @auth_provider.grant(...) decorator
spelling working from the same object. The decorator now injects into a
declared AccessContext parameter (hidden from the wrapper signature) and
emits a decoration-time DeprecationWarning, once per tool, when no
AccessContext parameter is declared; it keeps dual-writing
set_state("keycardai") during the deprecation window.
- Also:
- AccessContext.from_context(ctx) escape hatch for helpers called from
  inside tools that only hold the FastMCP Context.
- Fix the Context parameter check: resolve string annotations via
  get_type_hints and match Context inside unions (Context | None) and
  Annotated forms; a declared AccessContext parameter removes the
  ctx: Context requirement entirely.
- override_access_context(): public seam that forces grant resolution to a
  caller-supplied AccessContext (used by the testing utilities).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

## 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-fastmcp: 0.4.0 → 0.5.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-fastmcp",
    "package_dir": "packages/fastmcp",
    "has_changes": true,
    "current_version": "0.4.0",
    "next_version": "0.5.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.1-keycardai-oauth (2026-07-20)


- fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc (#195)
- * fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc
- authlib.jose is deprecated and emits an AuthlibDeprecationWarning on
import, surfacing to every SDK user. Migrate JWT signing/verification and
JWK handling to joserfc (authlib 's recommended replacement, already in
the dependency tree).
- - decode_and_verify_jwt: import key via joserfc, decode with explicit
  algorithms, return .claims
- get_jwks_key: return import_key(jwk).as_pem()
- create_client_assertion / key export: joserfc encode + import_key
- derive key type from the JWS algorithm so PEM imports do not emit
  joserfc's implicit-key SecurityWarning
- drop the direct authlib dependency (remains transitively via fastmcp)
- * fix(keycardai-oauth): reject unknown JWT algorithms; minimize lockfile diff
- Address review feedback on the joserfc migration:
- _key_type_for_algorithm now raises on an unrecognized algorithm instead
  of silently defaulting to RSA (a genuine mismatch previously failed later
  at key import / the algorithms=[...] gate; now it fails explicitly).
- Hand-restore uv.lock to a minimal authlib->joserfc swap. Regenerating
  under a newer uv had added unrelated python_full_version markers to
  transitive deps (aiologic, onnxruntime deps, sympy). joserfc was already
  present transitively, so only the oauth entry changes. Verified
  consistent with uv sync --frozen.
- * fix(keycardai-oauth): pin joserfc>=1.6.8 to clear GHSA advisories
- This PR promotes joserfc to a first-class dependency, so it must not ship
on a vulnerable floor. joserfc 1.6.4 is affected by:
- GHSA-gg9x-qcx2-xmrh (HIGH): HS256/384/512 verify accepts empty/nil HMAC key
- GHSA-wphv-vfrh-23q5 (MODERATE): b64=false RFC7797 JWS payload-size bypass
- 1.6.8 fixes both (superset of the two Socket bot PRs #189/#190, which
target 1.6.7 and 1.6.8). Root uv.lock resolves to 1.6.8; tests pass.
Neither advisory affects our own code path (we verify RS256), but a
correct floor matters for downstream consumers.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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

## 0.11.0-keycardai-starlette (2026-07-20)


- fix(keycardai-starlette): return 401/503 (not 500) for JWKS errors (#196)
- * 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
- * docs(keycardai-starlette): note the 503 bucket is intentionally narrow
- The 503 except clause lists the named JWKS discovery/fetch classes rather
than the OAuthServerError base on purpose: config and cache faults
(VerifierConfigError, CacheError) are not per-request failures and must
stay on the unexpected-error path (500), not be advertised as a
transient 503.
- Comment only, no behavior change.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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


- refactor(keycardai-fastmcp): keep grant and AccessContext as the only primary nouns
- GrantDependency stays exported for type annotations but is documented as
the return type of AuthProvider.grant(), not a concept to learn.
override_access_context moves out of the package root: it is a testing
seam and lives in keycardai.fastmcp.testing only.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- test(keycardai-fastmcp): end-to-end grant injection through a real FastMCP server
- Adds a round trip through FastMCP's in-memory client verifying the
injected AccessContext parameter is resolved per request and excluded
from the tool input schema. Ignores flake8-bugbear B008 in tests and
examples: auth_provider.grant(...) in a parameter default is the
intended injection spelling, matching how FastAPI treats Depends().
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- build(keycardai-fastmcp): raise fastmcp floor to >=3.1.0 for the Dependency extension point
- GrantDependency subclasses fastmcp.dependencies.Dependency. The
fastmcp.dependencies module exists since 3.0.0, but it only exports the
Dependency base class (via the uncalled-for DI engine) starting with
fastmcp 3.1.0; on 3.0.x the module exports Depends only, so
keycardai-fastmcp would fail to import. Raise the manifest floor in the
package and both examples accordingly (verified against the published
3.0.0/3.0.2 vs 3.1.0 wheels on PyPI).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- refactor(keycardai-fastmcp): move mock_access_context onto the public override seam
- mock_access_context previously patched module internals
(keycardai.fastmcp.provider.AccessContext and get_access_token). It now
builds a real AccessContext, preloaded with the requested tokens or error
state, and installs it through the public override_access_context() seam,
so grant resolution short-circuits on both the injected-parameter and
decorator paths without any patching.
- The yielded object is now a real AccessContext (subclassed only to serve a
default token for arbitrary resources), so assertions exercise the same
error paths as production code. override_access_context is re-exported
from keycardai.fastmcp.testing for tests that want to build the
AccessContext themselves.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- feat(keycardai-fastmcp): grant-as-dependency typed injection via fastmcp.dependencies
- AuthProvider.grant() now returns a GrantDependency, a fastmcp.dependencies
Dependency subclass. Declared as a typed parameter default
(access: AccessContext = auth_provider.grant(...)), FastMCP resolves it per
request: __aenter__ reads the caller token, performs the RFC 8693 exchanges,
and injects the populated AccessContext, hidden from the tool input schema.
Errors are recorded on the AccessContext, never raised, preserving the
existing error-capture contract.
- GrantDependency.__call__ keeps the @auth_provider.grant(...) decorator
spelling working from the same object. The decorator now injects into a
declared AccessContext parameter (hidden from the wrapper signature) and
emits a decoration-time DeprecationWarning, once per tool, when no
AccessContext parameter is declared; it keeps dual-writing
set_state("keycardai") during the deprecation window.
- Also:
- AccessContext.from_context(ctx) escape hatch for helpers called from
  inside tools that only hold the FastMCP Context.
- Fix the Context parameter check: resolve string annotations via
  get_type_hints and match Context inside unions (Context | None) and
  Annotated forms; a declared AccessContext parameter removes the
  ctx: Context requirement entirely.
- override_access_context(): public seam that forces grant resolution to a
  caller-supplied AccessContext (used by the testing utilities).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

## 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-fastmcp: 0.4.0 → 0.5.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-fastmcp",
    "package_dir": "packages/fastmcp",
    "has_changes": true,
    "current_version": "0.4.0",
    "next_version": "0.5.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.1-keycardai-oauth (2026-07-20)


- fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc (#195)
- * fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc
- authlib.jose is deprecated and emits an AuthlibDeprecationWarning on
import, surfacing to every SDK user. Migrate JWT signing/verification and
JWK handling to joserfc (authlib 's recommended replacement, already in
the dependency tree).
- - decode_and_verify_jwt: import key via joserfc, decode with explicit
  algorithms, return .claims
- get_jwks_key: return import_key(jwk).as_pem()
- create_client_assertion / key export: joserfc encode + import_key
- derive key type from the JWS algorithm so PEM imports do not emit
  joserfc's implicit-key SecurityWarning
- drop the direct authlib dependency (remains transitively via fastmcp)
- * fix(keycardai-oauth): reject unknown JWT algorithms; minimize lockfile diff
- Address review feedback on the joserfc migration:
- _key_type_for_algorithm now raises on an unrecognized algorithm instead
  of silently defaulting to RSA (a genuine mismatch previously failed later
  at key import / the algorithms=[...] gate; now it fails explicitly).
- Hand-restore uv.lock to a minimal authlib->joserfc swap. Regenerating
  under a newer uv had added unrelated python_full_version markers to
  transitive deps (aiologic, onnxruntime deps, sympy). joserfc was already
  present transitively, so only the oauth entry changes. Verified
  consistent with uv sync --frozen.
- * fix(keycardai-oauth): pin joserfc>=1.6.8 to clear GHSA advisories
- This PR promotes joserfc to a first-class dependency, so it must not ship
on a vulnerable floor. joserfc 1.6.4 is affected by:
- GHSA-gg9x-qcx2-xmrh (HIGH): HS256/384/512 verify accepts empty/nil HMAC key
- GHSA-wphv-vfrh-23q5 (MODERATE): b64=false RFC7797 JWS payload-size bypass
- 1.6.8 fixes both (superset of the two Socket bot PRs #189/#190, which
target 1.6.7 and 1.6.8). Root uv.lock resolves to 1.6.8; tests pass.
Neither advisory affects our own code path (we verify RS256), but a
correct floor matters for downstream consumers.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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

## 0.11.0-keycardai-starlette (2026-07-20)


- fix(keycardai-starlette): return 401/503 (not 500) for JWKS errors (#196)
- * 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
- * docs(keycardai-starlette): note the 503 bucket is intentionally narrow
- The 503 except clause lists the named JWKS discovery/fetch classes rather
than the OAuthServerError base on purpose: config and cache faults
(VerifierConfigError, CacheError) are not per-request failures and must
stay on the unexpected-error path (500), not be advertised as a
transient 503.
- Comment only, no behavior change.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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


- refactor(keycardai-fastmcp): keep grant and AccessContext as the only primary nouns
- GrantDependency stays exported for type annotations but is documented as
the return type of AuthProvider.grant(), not a concept to learn.
override_access_context moves out of the package root: it is a testing
seam and lives in keycardai.fastmcp.testing only.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- test(keycardai-fastmcp): end-to-end grant injection through a real FastMCP server
- Adds a round trip through FastMCP's in-memory client verifying the
injected AccessContext parameter is resolved per request and excluded
from the tool input schema. Ignores flake8-bugbear B008 in tests and
examples: auth_provider.grant(...) in a parameter default is the
intended injection spelling, matching how FastAPI treats Depends().
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- build(keycardai-fastmcp): raise fastmcp floor to >=3.1.0 for the Dependency extension point
- GrantDependency subclasses fastmcp.dependencies.Dependency. The
fastmcp.dependencies module exists since 3.0.0, but it only exports the
Dependency base class (via the uncalled-for DI engine) starting with
fastmcp 3.1.0; on 3.0.x the module exports Depends only, so
keycardai-fastmcp would fail to import. Raise the manifest floor in the
package and both examples accordingly (verified against the published
3.0.0/3.0.2 vs 3.1.0 wheels on PyPI).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- refactor(keycardai-fastmcp): move mock_access_context onto the public override seam
- mock_access_context previously patched module internals
(keycardai.fastmcp.provider.AccessContext and get_access_token). It now
builds a real AccessContext, preloaded with the requested tokens or error
state, and installs it through the public override_access_context() seam,
so grant resolution short-circuits on both the injected-parameter and
decorator paths without any patching.
- The yielded object is now a real AccessContext (subclassed only to serve a
default token for arbitrary resources), so assertions exercise the same
error paths as production code. override_access_context is re-exported
from keycardai.fastmcp.testing for tests that want to build the
AccessContext themselves.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- feat(keycardai-fastmcp): grant-as-dependency typed injection via fastmcp.dependencies
- AuthProvider.grant() now returns a GrantDependency, a fastmcp.dependencies
Dependency subclass. Declared as a typed parameter default
(access: AccessContext = auth_provider.grant(...)), FastMCP resolves it per
request: __aenter__ reads the caller token, performs the RFC 8693 exchanges,
and injects the populated AccessContext, hidden from the tool input schema.
Errors are recorded on the AccessContext, never raised, preserving the
existing error-capture contract.
- GrantDependency.__call__ keeps the @auth_provider.grant(...) decorator
spelling working from the same object. The decorator now injects into a
declared AccessContext parameter (hidden from the wrapper signature) and
emits a decoration-time DeprecationWarning, once per tool, when no
AccessContext parameter is declared; it keeps dual-writing
set_state("keycardai") during the deprecation window.
- Also:
- AccessContext.from_context(ctx) escape hatch for helpers called from
  inside tools that only hold the FastMCP Context.
- Fix the Context parameter check: resolve string annotations via
  get_type_hints and match Context inside unions (Context | None) and
  Annotated forms; a declared AccessContext parameter removes the
  ctx: Context requirement entirely.
- override_access_context(): public seam that forces grant resolution to a
  caller-supplied AccessContext (used by the testing utilities).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

[cmars]

LGTM with a question about type signatures. I think type checking might be turned off but could be a latent issue if/when it's turned on (or is it supposed to be on?)

[cmars]

Should this cast to AccessContext? That seems to be how it is used in the examples.

Suggested change

	) -> GrantDependency:
	) -> AccessContext:

[Larry-Osakwe]

good catch. the bigger problem is that the current annotation also makes the param default form fail type checking (mypy flags the default as incompatible). annotating AccessContext fixes that but breaks the decorator form since AccessContext is not callable. changed it to Any in 96021d2, which is what FastAPI Depends() and fastmcp own DI do. the param annotation carries the type for the injected form, and we can narrow to AccessContext once the decorator path is gone.

re type checking: CI does not run a checker on this package and none of our packages ship py.typed, so consumer checkers see everything as untyped anyway. filed ECO-171 to fix both.

[github-actions]

📦 Release Preview

This analysis shows the expected release impact:

📈 Expected Version Changes

keycardai-fastmcp: 0.4.0 → 0.5.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-fastmcp",
    "package_dir": "packages/fastmcp",
    "has_changes": true,
    "current_version": "0.4.0",
    "next_version": "0.5.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.1-keycardai-oauth (2026-07-20)


- fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc (#195)
- * fix(keycardai-oauth): migrate JOSE handling from authlib to joserfc
- authlib.jose is deprecated and emits an AuthlibDeprecationWarning on
import, surfacing to every SDK user. Migrate JWT signing/verification and
JWK handling to joserfc (authlib 's recommended replacement, already in
the dependency tree).
- - decode_and_verify_jwt: import key via joserfc, decode with explicit
  algorithms, return .claims
- get_jwks_key: return import_key(jwk).as_pem()
- create_client_assertion / key export: joserfc encode + import_key
- derive key type from the JWS algorithm so PEM imports do not emit
  joserfc's implicit-key SecurityWarning
- drop the direct authlib dependency (remains transitively via fastmcp)
- * fix(keycardai-oauth): reject unknown JWT algorithms; minimize lockfile diff
- Address review feedback on the joserfc migration:
- _key_type_for_algorithm now raises on an unrecognized algorithm instead
  of silently defaulting to RSA (a genuine mismatch previously failed later
  at key import / the algorithms=[...] gate; now it fails explicitly).
- Hand-restore uv.lock to a minimal authlib->joserfc swap. Regenerating
  under a newer uv had added unrelated python_full_version markers to
  transitive deps (aiologic, onnxruntime deps, sympy). joserfc was already
  present transitively, so only the oauth entry changes. Verified
  consistent with uv sync --frozen.
- * fix(keycardai-oauth): pin joserfc>=1.6.8 to clear GHSA advisories
- This PR promotes joserfc to a first-class dependency, so it must not ship
on a vulnerable floor. joserfc 1.6.4 is affected by:
- GHSA-gg9x-qcx2-xmrh (HIGH): HS256/384/512 verify accepts empty/nil HMAC key
- GHSA-wphv-vfrh-23q5 (MODERATE): b64=false RFC7797 JWS payload-size bypass
- 1.6.8 fixes both (superset of the two Socket bot PRs #189/#190, which
target 1.6.7 and 1.6.8). Root uv.lock resolves to 1.6.8; tests pass.
Neither advisory affects our own code path (we verify RS256), but a
correct floor matters for downstream consumers.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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

## 0.11.0-keycardai-starlette (2026-07-20)


- fix(keycardai-starlette): return 401/503 (not 500) for JWKS errors (#196)
- * 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
- * docs(keycardai-starlette): note the 503 bucket is intentionally narrow
- The 503 except clause lists the named JWKS discovery/fetch classes rather
than the OAuthServerError base on purpose: config and cache faults
(VerifierConfigError, CacheError) are not per-request failures and must
stay on the unexpected-error path (500), not be advertised as a
transient 503.
- Comment only, no behavior change.
- ---------
- Co-authored-by: GitHub Action <action@github.com>

## 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


- fix(keycardai-fastmcp): type grant() as Any so both call idioms type-check
- A GrantDependency return annotation makes the documented parameter
default (access: AccessContext = auth_provider.grant(...)) fail type
checking, and AccessContext breaks the still-supported decorator form.
Any is the FastAPI Depends() convention: the parameter annotation
carries the type for the injected form and the decorator form stays
callable. Narrow to AccessContext when the decorator path is removed.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- refactor(keycardai-fastmcp): keep grant and AccessContext as the only primary nouns
- GrantDependency stays exported for type annotations but is documented as
the return type of AuthProvider.grant(), not a concept to learn.
override_access_context moves out of the package root: it is a testing
seam and lives in keycardai.fastmcp.testing only.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- test(keycardai-fastmcp): end-to-end grant injection through a real FastMCP server
- Adds a round trip through FastMCP's in-memory client verifying the
injected AccessContext parameter is resolved per request and excluded
from the tool input schema. Ignores flake8-bugbear B008 in tests and
examples: auth_provider.grant(...) in a parameter default is the
intended injection spelling, matching how FastAPI treats Depends().
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- build(keycardai-fastmcp): raise fastmcp floor to >=3.1.0 for the Dependency extension point
- GrantDependency subclasses fastmcp.dependencies.Dependency. The
fastmcp.dependencies module exists since 3.0.0, but it only exports the
Dependency base class (via the uncalled-for DI engine) starting with
fastmcp 3.1.0; on 3.0.x the module exports Depends only, so
keycardai-fastmcp would fail to import. Raise the manifest floor in the
package and both examples accordingly (verified against the published
3.0.0/3.0.2 vs 3.1.0 wheels on PyPI).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- refactor(keycardai-fastmcp): move mock_access_context onto the public override seam
- mock_access_context previously patched module internals
(keycardai.fastmcp.provider.AccessContext and get_access_token). It now
builds a real AccessContext, preloaded with the requested tokens or error
state, and installs it through the public override_access_context() seam,
so grant resolution short-circuits on both the injected-parameter and
decorator paths without any patching.
- The yielded object is now a real AccessContext (subclassed only to serve a
default token for arbitrary resources), so assertions exercise the same
error paths as production code. override_access_context is re-exported
from keycardai.fastmcp.testing for tests that want to build the
AccessContext themselves.
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- feat(keycardai-fastmcp): grant-as-dependency typed injection via fastmcp.dependencies
- AuthProvider.grant() now returns a GrantDependency, a fastmcp.dependencies
Dependency subclass. Declared as a typed parameter default
(access: AccessContext = auth_provider.grant(...)), FastMCP resolves it per
request: __aenter__ reads the caller token, performs the RFC 8693 exchanges,
and injects the populated AccessContext, hidden from the tool input schema.
Errors are recorded on the AccessContext, never raised, preserving the
existing error-capture contract.
- GrantDependency.__call__ keeps the @auth_provider.grant(...) decorator
spelling working from the same object. The decorator now injects into a
declared AccessContext parameter (hidden from the wrapper signature) and
emits a decoration-time DeprecationWarning, once per tool, when no
AccessContext parameter is declared; it keeps dual-writing
set_state("keycardai") during the deprecation window.
- Also:
- AccessContext.from_context(ctx) escape hatch for helpers called from
  inside tools that only hold the FastMCP Context.
- Fix the Context parameter check: resolve string annotations via
  get_type_hints and match Context inside unions (Context | None) and
  Annotated forms; a declared AccessContext parameter removes the
  ctx: Context requirement entirely.
- override_access_context(): public seam that forces grant resolution to a
  caller-supplied AccessContext (used by the testing utilities).
- Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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