v0.5.0

Released commit: b082846d71d5aaa4c01d58c354e454e81c680b3d

Versioning: This entry contains breaking changes. The project is pre-1.0 (0.x); per SemVer, breaking changes on the 0.x line ship in the next minor (targeting 0.5.0), not a major bump. RELEASE_POLICY.md's "major bump for breaking changes" rule takes effect once the project reaches 1.0.0.

Added

• AuthplaneClient.resource(...), authplane_auth() and authplane_mcp_auth() accept resource_metadata_url=, the RFC 9728 §5.1 URL to advertise when the PRM document is AS-hosted; read it back with AuthplaneResource.resource_metadata_url(), which falls back to prm_url().
• AuthplaneClient.resource(...) logs at INFO when a revocation_checker is configured with the fail-open default, so the posture shows in startup output.
• read_dpop_header_from_scope, raw_request_path_from_scope and get_or_create_verify_cache_from_scope are exported from the package root: raw-ASGI counterparts of the adapter helpers, for middleware that cannot run under Starlette's BaseHTTPMiddleware with long-lived text/event-stream bodies.
• validate_prm_resource_identifier, validate_issuer_identifier and validate_resource_metadata_url are exported from the package root, so configuration can be checked before construction without importing authplane.internal.
• www_authenticate_challenges(error, *, schemes=None, algs=(), ...) returns one WWW-Authenticate value per scheme, so a resource can advertise both Bearer and DPoP (RFC 9449 §7.1) with algs.
• AccessDeniedError (403) and InvalidTargetError (400, RFC 8707 §2.2) for the token-exchange answers authserver 0.2.0 gives; neither counts toward the circuit breaker.
• AuthplaneClient.resource(...) warns when IntrospectionRevocation is configured on a client created without auth=: authserver ≥ 0.1.2 answers active: false to unauthenticated introspection, so every token would be rejected.
• AuthplaneResource warns once per resource when introspection answers active: false for a locally valid token, naming the runtime-client requirement.

Deprecated

• VerifiedClaims.may_act — now emits DeprecationWarning; authserver 0.2.0 no longer issues may_act; removed in the next minor.

Security

• www_authenticate() no longer copies the exception message into error_description; it sends a fixed sentence per RFC 6750 error code. Pass verbose_description=True to www_authenticate() / response_headers_for() to restore the message in development.

Fixed

• AS metadata is re-read on the verify path, so metadata_refresh_seconds now applies to verify-only deployments and a rotated jwks_uri is followed. The re-read happens after header checks, so malformed tokens trigger no network I/O.
• jwks_uri is resolved from metadata on every key-set fetch, so a rotation takes effect on the next fetch even without a new kid. Impact: keys left out of the new location stop verifying once the rotation is observed.
• A failed JWKS or metadata refresh backs off for max(1, min(30, refresh_seconds)) seconds instead of retrying on the next read. Impact: a blip at a newly rotated jwks_uri can reject the new key for up to that window.
• A fetched AS metadata document is validated before it is cached; one that fails the issuer check or names a bad endpoint is discarded and the previous one keeps serving.
• InvalidResourceError / InvalidIssuerError messages echo only the components the input actually has (still userinfo-redacted), instead of a fixed template that invented the missing parts.
• authplane-fastmcp, authplane-mcp: authplane_auth(...) / authplane_mcp_auth(...) close the client they created when configuration fails before returning.
• authplane-fastmcp, authplane-mcp: the path used to build the DPoP htu drops the query, matching RFC 9449 §4.2. No verification behaviour changes.

Changed

• Docs: introspection now leads with the fail-open consequence and the confidential / runtime-client requirement; token exchange explains access_denied vs consent_required, invalid_target and the exchange allowlist; the README states authserver compatibility.
• scripts/manual-e2e-setup.sh no longer sets AUTHPLANE_CLIENT_CREDENTIALS_ENABLED and accepts AUTHSERVER_REF; scripts/manual-e2e-smoke.sh no longer calls POST /admin/scopes, which authserver 0.2.0 does not serve.
• BREAKING (pre-1.0) ASCredentials raises ValueError when client_id or client_secret is empty. Migration: pass the real secret, or omit ASCredentials.
• BREAKING (pre-1.0) A resource identifier must be an absolute URL with a scheme and host, with no userinfo, whitespace or control characters, " or \ in the host, or malformed port; anything else raises InvalidResourceError at construction. Migration: configure the full URL clients use, e.g. https://api.example.com/mcp.
• BREAKING (pre-1.0) An issuer must be an absolute URL with a scheme and host, with no userinfo, whitespace or control characters; AuthplaneClient.create(...), build_metadata_url(...) and build_prm(...) raise InvalidIssuerError otherwise. Migration: fix the configured issuer.
• BREAKING (pre-1.0) build_prm(...) applies the same resource-identifier gate as AuthplaneResource. Migration: pass the identifier you configure on AuthplaneClient.resource(...).
• Construction-gate messages say resource identifier instead of resource indicator. Code matching on the old text must be updated.
• BREAKING (pre-1.0) The on_change argument of DocumentCache / MetadataCache and the DocumentChangeCallback alias are removed from authplane.internal. Migration: none expected; passing on_change= is now a TypeError.