authplane-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

authplane_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-07-21
+
+### Added
+- `TokenCache` is now bounded by a configurable `max_entries` cap (default `10_000`, exposed as `TokenCache.DEFAULT_MAX_ENTRIES` and a read-only `cache.max_entries` property) and evicts the least-recently-used entry on overflow; both `get` and `set` bump the touched key to MRU. Plumbed through `AuthplaneClient.create(cache_max_entries=...)`. Token-exchange cache keys are high-cardinality (the subject token is part of the key), so the cap keeps long-lived clients bounded.
+- `VerifiedClaims.require_scopes(scopes: Iterable[str])` — plural AND-style helper that requires all listed scopes. Empty input is a no-op; on failure the raised `InsufficientScopeError` carries the full requested tuple on `required_scopes` and names every missing scope plus the token's available scopes in the message.
+- `authplane-mcp`: new public surface — `AuthplaneRequestContextMiddleware`, `get_current_request()`, `install_request_context(mcp)` — an ASGI middleware that publishes the active request on a `ContextVar` so the verifier can build a `DPoPRequestContext`.
+- `authplane-fastmcp`, `authplane-mcp`: `AuthplaneTokenVerifier` caches the in-flight verify task per request (keyed by access token on `request.state`), so a repeat `verify_token` within the same HTTP request awaits the same task rather than re-entering the inbound DPoP replay store. Cross-request replay protection is unaffected (distinct requests get distinct caches).
+
+### Fixed
+- `TokenCache.set` now distinguishes a missing `expires_in` from `expires_in: 0`. Both previously collapsed into `default_ttl`. The store now applies `default_ttl` only when `expires_in` is absent (`None`), treats `expires_in: 0` (RFC 6749 §5.1) as already expired and refuses to store it, and honors `n` seconds when positive. `parse_token_response` carries the missing-vs-zero distinction through the parser.
+- `authplane-fastmcp`, `authplane-mcp`: inbound DPoP cardinality (RFC 9449 §4.3 #1) is now enforced. `read_dpop_header` reads the full multi-value `DPoP` header list (and splits on `,` defensively to catch proxies that pre-join duplicate headers) and raises `DPoPMultipleProofsError` when more than one non-empty proof is present. `www_authenticate` maps this error to `error="invalid_dpop_proof"` per RFC 9449 §7.1.
+- `authplane-fastmcp`, `authplane-mcp`: inbound DPoP proof-of-possession is now enforced end-to-end. `AuthplaneTokenVerifier.verify_token` forwards a `DPoPRequestContext` (method + reconstructed `htu` + proof header) to `AuthplaneResource.verify`, so `inbound_dpop=InboundDPoPOptions(required=True)` checks the proof on every request. The `htu` origin is always the operator-configured resource URI, never the inbound `Host` / `X-Forwarded-Proto` headers. Operators using `required=True` with `authplane-mcp` should call `install_request_context(mcp)` after constructing `FastMCP` so the verifier can read the per-request context; if it is not installed the request fails closed (401) rather than skipping the check.
+- `authplane-fastmcp`, `authplane-mcp`: DPoP `htu` reconstruction reads `scope["raw_path"]` to preserve percent-encoding (e.g. `%2F`) on the wire under ASGI, falling back to `request.url.path` when the server omits `raw_path`.
+- `authplane-mcp`: `install_request_context(mcp)` is idempotent — repeated calls on the same `FastMCP` instance are no-ops.
+- `require_scope` (singular) now renders an empty token scope set as `(none)` instead of `[]`, matching the plural helper's output. Logging pipelines keyed on the old `Token has scopes: []` string should be updated.
+- Docs and demos now run adapter setup, the async server entry point (`run_streamable_http_async` / `run_async`), and `aclose()` in a single `asyncio.run(main())`, keeping the client's locks, HTTP pool, and background JWKS/metadata refresh tasks on one event loop.
+
+### Changed
+- **BREAKING (pre-1.0)** `TokenResponse.expires_in` and `CacheEntry.expires_in` are now typed `int | None` (was `int`), so a token response that omits `expires_in` is `None` rather than `0`. **Migration:** typed downstream callers reading `resp.expires_in` directly (arithmetic, comparison, formatting) must guard for `None`; treat `None` as "apply your default" and `0` as "already expired".
+
+## [0.2.0] - 2026-05-20
+
+### Security
+- `www_authenticate()` now sanitizes CR, LF, double-quote, and backslash from every value it interpolates (`realm`, `error_description`, `scope`, `resource_metadata`), closing a header-injection path through attacker-influenced error messages.
+
+### Fixed
+- `DPoPNotSupportedError` now emits `WWW-Authenticate: Bearer` instead of `DPoP`. The resource is bearer-only by configuration, so advertising the DPoP scheme misled clients into retries that would fail the same way.
+- `http_status(CircuitOpenError)` now returns `503` (was `500`). The circuit breaker is structurally identical to other temporary-AS-unavailability errors and should be retryable, not surfaced as an internal error.
+- Outbound `Host` header now preserves non-default ports and brackets IPv6 hostnames, fixing DPoP `htu` validation against authservers on non-standard ports.
+- Packaging issues discovered after the first release.
+- Documentation links and demo references.
+- `authplane-fastmcp` dependency range now correctly requires `fastmcp>=3.2,<4` (was `>=2.0`, which could resolve to a version the adapter can't import).
+
+### Added
+- `www_authenticate()` accepts `resource_metadata_url=` (RFC 9728 §5.1) and `scope=` (RFC 6750 §3) keyword arguments. When the caller does not pass `scope=`, the helper auto-populates it from `InsufficientScopeError.required_scopes`.
+- `InsufficientScopeError` now carries a structured `required_scopes` attribute, populated automatically by `VerifiedClaims.require_scope()` so the wire challenge can advertise the missing scope.
+- `response_headers_for(error, *, realm, resource_metadata_url, scope)` — bundled helper returning `(status, {"WWW-Authenticate": challenge})` in one call.
+- Both adapter verifiers (`authplane-mcp`, `authplane-fastmcp`) now emit a `logging.DEBUG` event `authplane.token_verification_failed` with structured `error_class` and `error` fields before returning `None`. Wire behaviour is unchanged; operators can now distinguish expired tokens from JWKS outages and DPoP replays in logs.
+
+### Changed
+- CI and release workflow improvements from first-release learnings.
+
+## [0.1.0] - 2026-05-11
+
+- Initial release.

{authplane_sdk-0.2.0 → authplane_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authplane-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: Authplane SDK for Python — OAuth 2.1 JWT validation and token operations for protected resources
 Project-URL: Homepage, https://github.com/AuthPlane/python-sdk
 Project-URL: Repository, https://github.com/AuthPlane/python-sdk

{authplane_sdk-0.2.0 → authplane_sdk-0.3.0}/authplane/__init__.py

@@ -11,6 +11,7 @@ except _PackageNotFoundError:  # pragma: no cover - source tree without an insta
 # Client
 # Authentication
 from .auth_provider import AuthProvider, ClientCredentialsProvider
+from .cache import TokenCache
 from .client import AuthplaneClient
 from .credentials import ASCredentials
 from .dpop import (
@@ -34,6 +35,7 @@ from .errors import (
     ConsentRequiredError,
     DPoPBindingMismatchError,
     DPoPError,
+    DPoPMultipleProofsError,
     DPoPNotSupportedError,
     DPoPProofMissingError,
     DPoPReplayDetectedError,
@@ -83,6 +85,7 @@ __all__ = [
     "DPoPBindingMismatchError",
     "DPoPError",
     "DPoPKeyMaterial",
+    "DPoPMultipleProofsError",
     "DPoPNonceStore",
     "DPoPNotSupportedError",
     "DPoPProofMissingError",
@@ -109,6 +112,7 @@ __all__ = [
     "ProtocolError",
     "RevocationChecker",
     "ServerError",
+    "TokenCache",
     "TokenExpiredError",
     "TokenMissingError",
     "TokenRevokedError",

authplane_sdk-0.3.0/authplane/_dpop_adapter.py

@@ -0,0 +1,186 @@
+"""Shared DPoP-context plumbing for the MCP and FastMCP adapters.
+
+The ``authplane-mcp`` and ``authplane-fastmcp`` packages both bridge
+``AuthplaneResource.verify`` to a Starlette-based ``TokenVerifier``.
+They each need the same four pieces of glue:
+
+* a concrete ``DPoPRequestContext`` shape built from the active request,
+* a case-insensitive ``DPoP`` header reader,
+* a path reader that preserves the on-wire percent-encoding (so
+  ``htu`` binds identically against the TS sibling), and
+* a per-request verify-task cache anchored on ``request.state`` so
+  repeated ``verify_token`` invocations within one HTTP request do
+  not re-enter the inbound DPoP replay store.
+
+These live here so the two adapters do not drift. The module is
+underscore-prefixed and intentionally not re-exported from
+``authplane.__init__``; nothing outside the adapter packages should
+import from it.
+
+The core ``authplane-sdk`` wheel does *not* take a runtime dependency
+on Starlette. The helpers below duck-type the few attributes they
+need; the ``_RequestLike`` Protocol pins that contract structurally
+so the adapter packages can pass ``starlette.requests.Request`` and
+type-check without forcing Starlette into the core's import graph.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from .errors import DPoPMultipleProofsError
+
+if TYPE_CHECKING:
+    import asyncio
+
+    from .verifier import VerifiedClaims
+
+
+__all__ = [
+    "BuiltDPoPRequestContext",
+    "VerifyTaskCache",
+    "get_or_create_verify_cache",
+    "raw_request_path",
+    "read_dpop_header",
+]
+
+
+REQ_STATE_KEY = "_authplane_verify_tasks"
+"""Attribute name on ``request.state`` that holds the per-request verify-task cache.
+
+Stringly-typed on purpose: ``request.state`` is shared per ASGI *scope*
+(not per ``Request`` instance), so a ``WeakKeyDictionary[Request, ...]``
+would split the cache across middleware-built and handler-built
+``Request`` objects pointing at the same scope.
+"""
+
+
+VerifyTaskCache = dict[str, "asyncio.Task[VerifiedClaims]"]
+
+
+class _HeadersLike(Protocol):
+    """Minimal slice of ``starlette.datastructures.Headers``."""
+
+    def get(self, key: str, default: str | None = ...) -> str | None: ...
+
+    def getlist(self, key: str) -> list[str]: ...
+
+
+class _URLLike(Protocol):
+    """Minimal slice of ``starlette.datastructures.URL``."""
+
+    @property
+    def path(self) -> str: ...
+
+
+class _RequestLike(Protocol):
+    """Structural subset of ``starlette.requests.Request`` consumed here.
+
+    Defined as a Protocol so this module does not have to import
+    Starlette — keeping it out of the core SDK's dependency graph.
+    The adapters call these helpers with the real
+    ``starlette.requests.Request`` and it satisfies the protocol
+    structurally.
+    """
+
+    @property
+    def headers(self) -> _HeadersLike: ...
+
+    @property
+    def scope(self) -> dict[str, object]: ...
+
+    @property
+    def state(self) -> object: ...
+
+    @property
+    def url(self) -> _URLLike: ...
+
+
+class BuiltDPoPRequestContext:
+    """Concrete ``DPoPRequestContext`` built from the active HTTP request.
+
+    Structural conformance to ``authplane.DPoPRequestContext`` is all
+    the core verifier checks. ``__slots__`` keeps the per-request
+    construction cost negligible.
+    """
+
+    __slots__ = ("method", "proof", "url")
+
+    def __init__(self, method: str, url: str, proof: str | None) -> None:
+        self.method = method
+        self.url = url
+        self.proof = proof
+
+
+def read_dpop_header(request: _RequestLike) -> str | None:
+    """Read the ``DPoP`` request header, enforcing RFC 9449 §4.3 #1.
+
+    Returns the single proof JWT when exactly one non-empty ``DPoP``
+    header value is present, or ``None`` when no ``DPoP`` header is
+    present. Raises :class:`DPoPMultipleProofsError` when the request
+    carries more than one ``DPoP`` header value.
+
+    Two on-wire shapes are rejected:
+
+    1. Multiple ``DPoP`` headers on the request (``headers.getlist``
+       returns ≥ 2 non-empty entries).
+    2. A single ``DPoP`` header value pre-joined with ``,`` by an
+       upstream proxy or framework — RFC 9110 §5.3 permits combining
+       repeated headers this way. JWS compact serialization never
+       contains a literal comma, so split-on-comma is sound.
+
+    Trimming and empty-piece filtering mirror the cross-language
+    cardinality boundary so a request carrying ``"DPoP: "`` (whitespace
+    only) is treated as header-absent rather than as one value.
+    """
+    raw_values = request.headers.getlist("dpop")
+    filtered: list[str] = []
+    for raw in raw_values:
+        trimmed = raw.strip()
+        if not trimmed:
+            continue
+        # ``split(",", 2)`` caps the allocation on an attacker-controlled
+        # header: we only need 0 / 1 / ≥ 2 non-blank pieces, and a third
+        # entry already trips the cardinality guard below.
+        for part in trimmed.split(",", 2):
+            piece = part.strip()
+            if piece:
+                filtered.append(piece)
+    if len(filtered) > 1:
+        raise DPoPMultipleProofsError(
+            f"request carries {len(filtered)} DPoP proofs (RFC 9449 §4.3 forbids it)"
+        )
+    return filtered[0] if filtered else None
+
+
+def raw_request_path(request: _RequestLike) -> str:
+    """Return the request path with percent-encoding preserved.
+
+    ASGI populates ``scope["path"]`` as the percent-decoded path, but
+    the client signed its DPoP ``htu`` over the on-wire (percent-encoded)
+    target. Prefer ``scope["raw_path"]`` (raw bytes) so a path
+    containing e.g. ``%2F`` binds identically here and in the TS
+    sibling, which builds ``htu`` from ``IncomingMessage.url``. Falls
+    back to the decoded path for the rare ASGI server that omits
+    ``raw_path``.
+    """
+    raw = request.scope.get("raw_path")
+    if isinstance(raw, (bytes, bytearray)):
+        return bytes(raw).decode("latin-1")
+    return request.url.path
+
+
+def get_or_create_verify_cache(request: _RequestLike) -> VerifyTaskCache:
+    """Return the per-request verify-task cache, creating it on first access.
+
+    Lives on ``request.state`` so it is scoped to the ASGI request and
+    disappears with it; cross-request replay protection is preserved.
+    The adapters' tests use this accessor to inspect the cache without
+    manipulating ``request.state`` or the stringly-typed slot directly.
+    """
+    state = request.state
+    cache: VerifyTaskCache | None = getattr(state, REQ_STATE_KEY, None)
+    if cache is None:
+        cache = {}
+        setattr(state, REQ_STATE_KEY, cache)
+    return cache

authplane_sdk-0.3.0/authplane/cache.py

@@ -0,0 +1,159 @@
+"""Token cache with TTL buffer and bounded LRU for client_credentials tokens."""
+
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+
+
+@dataclass
+class CacheEntry:
+    """A cached token."""
+
+    access_token: str
+    token_type: str
+    # Mirrors the wire field's tri-state (``None`` = AS omitted it,
+    # positive int = AS-issued lifetime). ``0`` never reaches the cache —
+    # :meth:`TokenCache.set` refuses it — so callers reading from cache
+    # see a sentinel that round-trips to the AS-issued shape.
+    expires_in: int | None
+    scope: str
+    expires_at: float  # monotonic time
+    # DPoP key thumbprint (RFC 9449 §6.1). Persisted so a sender-constrained
+    # token retrieved from cache reports its binding to downstream callers
+    # instead of silently degrading to a bearer-only shape.
+    cnf_jkt: str = ""
+
+
+class TokenCache:
+    """In-memory token cache with TTL buffer and bounded LRU eviction.
+
+    Tokens are evicted ``ttl_buffer_seconds`` before their actual expiry to
+    avoid using tokens that are about to expire.
+
+    The cache is bounded by ``max_entries`` (default 10 000) and evicts the
+    least-recently-used entry on overflow. Token-exchange cache keys are
+    high-cardinality because the subject token is part of the key, so
+    never-re-read keys would otherwise accumulate without bound.
+
+    Recency is tracked via :class:`collections.OrderedDict` — every ``get``
+    that hits an entry calls ``move_to_end`` so the iterator's first key
+    is always the LRU victim.
+    """
+
+    DEFAULT_MAX_ENTRIES = 10_000
+    """Default cap on cached entries."""
+
+    def __init__(
+        self,
+        ttl_buffer_seconds: float = 30.0,
+        default_ttl_seconds: float = 3600.0,
+        max_entries: int = DEFAULT_MAX_ENTRIES,
+    ) -> None:
+        # Strict `type() is int` rather than `isinstance(..., int)` so that
+        # `bool` (a subclass of `int`) is rejected — a stray `True` would
+        # otherwise silently produce a cap-1 cache. Catches runtime-typed
+        # inputs from JSON config that bypass the static type check.
+        if type(max_entries) is not int or max_entries <= 0:
+            raise ValueError(f"max_entries must be a positive integer, got {max_entries!r}")
+        self._ttl_buffer = ttl_buffer_seconds
+        self._default_ttl = default_ttl_seconds
+        self._max_entries = max_entries
+        self._entries: OrderedDict[str, CacheEntry] = OrderedDict()
+
+    def __len__(self) -> int:
+        """Number of stored entries — useful for tests and operator alerts.
+
+        Steady-state size tracking ``max_entries`` signals the cap is too low.
+        """
+        return len(self._entries)
+
+    @property
+    def max_entries(self) -> int:
+        """The configured cap on stored entries.
+
+        Exposed so operators can correlate ``len(cache)`` against the cap
+        without having to re-thread the constructor argument through their
+        own config layer.
+        """
+        return self._max_entries
+
+    def get(self, key: str) -> CacheEntry | None:
+        """Get a cached entry if it exists and hasn't expired.
+
+        On hit, bumps the entry to MRU so the next overflow eviction
+        targets a colder key.
+        """
+        entry = self._entries.get(key)
+        if entry is None:
+            return None
+        if time.monotonic() >= entry.expires_at:
+            del self._entries[key]
+            return None
+        # Bump to MRU.
+        self._entries.move_to_end(key)
+        return entry
+
+    def set(
+        self,
+        key: str,
+        access_token: str,
+        token_type: str,
+        expires_in: int | None = None,
+        scope: str = "",
+        cnf_jkt: str = "",
+    ) -> None:
+        """Cache a token.
+
+        ``expires_in`` is tri-state:
+
+        * ``None`` ⇒ the AS omitted ``expires_in``; apply ``default_ttl``.
+        * ``0`` ⇒ RFC 6749 §5.1 explicit zero (one-shot, born-expired);
+          refuse to store so the next ``get`` is a miss instead of a
+          stale hit.
+        * positive ``n`` ⇒ honor ``n`` seconds.
+
+        The effective TTL (chosen value minus ``ttl_buffer_seconds``) must
+        be > 0; otherwise the entry is not stored.
+        """
+        if expires_in is None:
+            base_ttl = self._default_ttl
+        elif expires_in == 0:
+            return
+        else:
+            base_ttl = expires_in
+        ttl = base_ttl - self._ttl_buffer
+        if ttl <= 0:
+            return
+        # `move_to_end` after insertion in case the key already exists —
+        # a re-set is treated as a touch (the entry the caller just wrote
+        # is by definition the most-recently-used).
+        self._entries[key] = CacheEntry(
+            access_token=access_token,
+            token_type=token_type,
+            expires_in=expires_in,
+            scope=scope,
+            expires_at=time.monotonic() + ttl,
+            cnf_jkt=cnf_jkt,
+        )
+        self._entries.move_to_end(key)
+        # Evict the LRU victim(s) until we're at-or-under the cap. The
+        # constructor pins ``max_entries``, so in practice this trims
+        # exactly one entry on overflow.
+        while len(self._entries) > self._max_entries:
+            self._entries.popitem(last=False)
+
+    def delete(self, key: str) -> None:
+        """Remove a cached entry."""
+        self._entries.pop(key, None)
+
+    @staticmethod
+    def cache_key(scope: str = "", resource: str = "") -> str:
+        """Generate a deterministic cache key from scope and resource.
+
+        Scopes are sorted for consistency.
+        """
+        parts = sorted(scope.split()) if scope else []
+        scope_part = " ".join(parts)
+        if resource:
+            return f"{scope_part}|{resource}" if scope_part else f"|{resource}"
+        return scope_part or "_default"

{authplane_sdk-0.2.0 → authplane_sdk-0.3.0}/authplane/client.py

@@ -92,12 +92,46 @@ class AuthplaneClient:
         metadata_refresh_seconds: int = 3600,
         cache_ttl_buffer_seconds: float = 30.0,
         default_ttl_seconds: float = 3600.0,
+        cache_max_entries: int = TokenCache.DEFAULT_MAX_ENTRIES,
         circuit_breaker_threshold: int = 5,
         circuit_breaker_cooldown_seconds: float = 30.0,
     ) -> Self:
         """Create and initialize the client.
 
         Discovers AS metadata and starts JWKS background refresh.
+
+        Args:
+            issuer: Authorization-server issuer URL (the prefix RFC 8414 metadata
+                is fetched from). Trailing slash is stripped.
+            auth: Client authentication for OAuth endpoints. Accepts either a raw
+                :class:`AuthProvider` or an :class:`ASCredentials` shorthand (which
+                is materialised as :class:`ClientCredentialsProvider`).
+            dpop: Optional :class:`DPoPProvider` for sender-constrained outbound
+                requests against the AS (token / introspection / revocation).
+            dev_mode: When True, relaxes SSRF and HTTPS-only fetch policies for
+                local development. Falls back to the ``AUTHPLANE_DEV_MODE``
+                environment variable when omitted.
+            fetch_settings: Explicit :class:`FetchSettings` override. When None,
+                derived from ``dev_mode``.
+            jwks_refresh_seconds: Background JWKS refresh interval (must be > 0).
+            metadata_refresh_seconds: Background metadata refresh interval
+                (must be > 0).
+            cache_ttl_buffer_seconds: Safety margin subtracted from each token's
+                lifetime before the entry is considered expired. Same shape as
+                java-sdk ``TokenCacheConfig.ttlBufferSeconds`` and ts-sdk
+                ``TokenCache`` ctor. Default 30s.
+            default_ttl_seconds: Fallback lifetime applied when the AS response
+                omits ``expires_in``. Cross-SDK parity with java-sdk
+                ``TokenCacheConfig.defaultTtlSeconds``. Default 3600s.
+            cache_max_entries: Maximum number of cached tokens before
+                least-recently-used eviction kicks in. Default
+                :attr:`TokenCache.DEFAULT_MAX_ENTRIES` (10_000). Must be a
+                positive integer (``bool``/``float`` rejected — see
+                :class:`TokenCache`).
+            circuit_breaker_threshold: Consecutive AS failures before the
+                circuit opens. Default 5.
+            circuit_breaker_cooldown_seconds: Half-open probe interval after the
+                circuit trips. Default 30s.
         """
         client = cls()
         client._issuer = issuer.rstrip("/")
@@ -135,7 +169,11 @@ class AuthplaneClient:
             )
 
         # Resilience
-        client._token_cache = TokenCache(cache_ttl_buffer_seconds, default_ttl_seconds)
+        client._token_cache = TokenCache(
+            cache_ttl_buffer_seconds,
+            default_ttl_seconds,
+            cache_max_entries,
+        )
         client._circuit_breaker = CircuitBreaker(
             circuit_breaker_threshold,
             circuit_breaker_cooldown_seconds,
@@ -270,6 +308,7 @@ class AuthplaneClient:
                 token_type=cached.token_type,
                 expires_in=cached.expires_in,
                 scope=cached.scope,
+                cnf_jkt=cached.cnf_jkt,
             )
 
         token_endpoint = await self._get_token_endpoint()
@@ -289,6 +328,7 @@ class AuthplaneClient:
                 result.token_type,
                 result.expires_in,
                 result.scope,
+                cnf_jkt=result.cnf_jkt,
             )
             return result
         except Exception as exc:

{authplane_sdk-0.2.0 → authplane_sdk-0.3.0}/authplane/errors.py

@@ -122,6 +122,19 @@ class InvalidDPoPProofError(DPoPError):
     pass
 
 
+class DPoPMultipleProofsError(InvalidDPoPProofError):
+    """Raised when the inbound request carries more than one ``DPoP`` header
+    value (RFC 9449 §4.3 #1).
+
+    Surfaces with WWW-Authenticate ``error="invalid_dpop_proof"`` per
+    RFC 9449 §7.1. The other ``DPoPError`` subclasses keep the SDK's
+    historical ``invalid_token`` mapping; only this §4.3 cardinality
+    violation gets the proof-specific error code.
+    """
+
+    pass
+
+
 class DPoPReplayDetectedError(DPoPError):
     """Raised when a DPoP proof `jti` has already been seen."""
 
@@ -253,8 +266,11 @@ def www_authenticate(
 
     Maps SDK errors to the correct error code and authentication scheme:
     - ``InsufficientScopeError`` → ``insufficient_scope``
-    - ``DPoPError`` subclasses (except ``DPoPNotSupportedError``) → ``DPoP``
-      scheme with ``invalid_token``
+    - ``DPoPMultipleProofsError`` → ``DPoP`` scheme with
+      ``invalid_dpop_proof`` (RFC 9449 §7.1 prescribes this code for §4.3
+      cardinality rejections).
+    - Other ``DPoPError`` subclasses (except ``DPoPNotSupportedError``) →
+      ``DPoP`` scheme with ``invalid_token``
     - All other ``AuthplaneError`` → ``Bearer`` scheme with ``invalid_token``
 
     If ``scope`` is provided (or the error is an :class:`InsufficientScopeError`
@@ -272,6 +288,12 @@ def www_authenticate(
     """
     if isinstance(error, InsufficientScopeError):
         error_code = "insufficient_scope"
+    elif isinstance(error, DPoPMultipleProofsError):
+        # RFC 9449 §7.1 prescribes `invalid_dpop_proof` for §4.3
+        # cardinality rejections, not the SDK's historical `invalid_token`
+        # used by the other `DPoPError` shapes. Scoped to this error;
+        # a broader sweep is a separate change.
+        error_code = "invalid_dpop_proof"
     else:
         error_code = "invalid_token"
 

{authplane_sdk-0.2.0 → authplane_sdk-0.3.0}/authplane/oauth/parsing.py

@@ -13,9 +13,14 @@ def _required_string(data: dict[str, Any], key: str) -> str:
     return value
 
 
-def _optional_int(data: dict[str, Any], key: str, *, default: int = 0) -> int:
-    value = data.get(key, default)
-    if value in ("", None):
+def _optional_int(data: dict[str, Any], key: str, *, default: int | None = 0) -> int | None:
+    """Parse an optional integer field. ``default`` is returned for absent
+    or empty-string values; ``None`` is a valid default so callers can
+    distinguish "field omitted on the wire" from "field present and zero".
+    """
+    sentinel = object()
+    value = data.get(key, sentinel)
+    if value is sentinel or value in ("", None):
         return default
     try:
         parsed = int(value)
@@ -74,7 +79,7 @@ def parse_token_response(
     return TokenResponse(
         access_token=access_token,
         token_type=token_type,
-        expires_in=_optional_int(data, "expires_in", default=0),
+        expires_in=_optional_int(data, "expires_in", default=None),
         scope=str(data.get("scope", "")),
         refresh_token=str(data.get("refresh_token", "")),
         issued_token_type=issued_token_type,

{authplane_sdk-0.2.0 → authplane_sdk-0.3.0}/authplane/oauth/types.py

@@ -57,7 +57,12 @@ class TokenResponse:
 
     access_token: str
     token_type: str
-    expires_in: int
+    # ``expires_in`` is tri-state so the wire shape ``expires_in: 0``
+    # (RFC 6749 §5.1 — a deliberately-expired one-shot token) is
+    # distinguishable from the field being absent. Cache callers honor
+    # the AS's intent: ``None`` ⇒ apply the default TTL; ``0`` ⇒ refuse
+    # to store.
+    expires_in: int | None
     scope: str
     refresh_token: str = ""
     issued_token_type: str = ""

{authplane_sdk-0.2.0 → authplane_sdk-0.3.0}/authplane/verifier/claims.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, cast
@@ -55,11 +55,45 @@ class VerifiedClaims:
     def require_scope(self, scope: str) -> None:
         """Raise InsufficientScopeError when the validated token lacks the scope."""
         if not self.has_scope(scope):
+            available = list(self.scopes) if self.scopes else "(none)"
             raise InsufficientScopeError(
-                f"Token missing required scope '{scope}'. Token has scopes: {list(self.scopes)}",
+                f"Token missing required scope '{scope}'. Token has scopes: {available}",
                 required_scopes=(scope,),
             )
 
+    def require_scopes(self, scopes: Iterable[str]) -> None:
+        """Raise InsufficientScopeError unless the token carries every scope in ``scopes``.
+
+        Empty input is a no-op — no required scopes ⇒ always satisfied. A
+        handler that calls ``claims.require_scopes(required)`` doesn't have to
+        special-case empty iterables.
+
+        On failure the raised :class:`InsufficientScopeError` carries the full
+        requested tuple on ``required_scopes`` (not just the missing ones, so
+        adapters that surface ``scope="…"`` in the WWW-Authenticate challenge
+        keep emitting the complete required set), and its message names every
+        missing scope plus the scopes the token carries — rendered verbatim
+        into the RFC 6750 ``error_description``.
+        """
+        # Materialise once: the caller may pass any iterable (generator, set,
+        # frozenset, etc.). We need to iterate twice — once to find missing
+        # entries and once to populate the error's ``required_scopes`` — and
+        # the raised error embeds the requested tuple in its public field,
+        # so the snapshot has to be ordered + indexable.
+        required = tuple(scopes)
+        if not required:
+            return
+        missing = [s for s in required if not self.has_scope(s)]
+        if not missing:
+            return
+        scope_word = "scopes" if len(missing) > 1 else "scope"
+        missing_quoted = ", ".join(repr(s) for s in missing)
+        available = list(self.scopes) if self.scopes else "(none)"
+        raise InsufficientScopeError(
+            f"Token missing required {scope_word} {missing_quoted}. Token has scopes: {available}",
+            required_scopes=required,
+        )
+
     def has_claim(self, key: str, value: Any = _MISSING) -> bool:
         """Check whether a claim exists and optionally matches an expected value."""
         if key not in self.raw:

authplane_sdk-0.2.0/CHANGELOG.md

@@ -1,32 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.2.0] - 2026-05-20
-
-### Security
-- `www_authenticate()` now sanitizes CR, LF, double-quote, and backslash from every value it interpolates (`realm`, `error_description`, `scope`, `resource_metadata`), closing a header-injection path through attacker-influenced error messages.
-
-### Fixed
-- `DPoPNotSupportedError` now emits `WWW-Authenticate: Bearer` instead of `DPoP`. The resource is bearer-only by configuration, so advertising the DPoP scheme misled clients into retries that would fail the same way.
-- `http_status(CircuitOpenError)` now returns `503` (was `500`). The circuit breaker is structurally identical to other temporary-AS-unavailability errors and should be retryable, not surfaced as an internal error.
-- Outbound `Host` header now preserves non-default ports and brackets IPv6 hostnames, fixing DPoP `htu` validation against authservers on non-standard ports.
-- Packaging issues discovered after the first release.
-- Documentation links and demo references.
-- `authplane-fastmcp` dependency range now correctly requires `fastmcp>=3.2,<4` (was `>=2.0`, which could resolve to a version the adapter can't import).
-
-### Added
-- `www_authenticate()` accepts `resource_metadata_url=` (RFC 9728 §5.1) and `scope=` (RFC 6750 §3) keyword arguments. When the caller does not pass `scope=`, the helper auto-populates it from `InsufficientScopeError.required_scopes`.
-- `InsufficientScopeError` now carries a structured `required_scopes` attribute, populated automatically by `VerifiedClaims.require_scope()` so the wire challenge can advertise the missing scope.
-- `response_headers_for(error, *, realm, resource_metadata_url, scope)` — bundled helper returning `(status, {"WWW-Authenticate": challenge})` in one call.
-- Both adapter verifiers (`authplane-mcp`, `authplane-fastmcp`) now emit a `logging.DEBUG` event `authplane.token_verification_failed` with structured `error_class` and `error` fields before returning `None`. Wire behaviour is unchanged; operators can now distinguish expired tokens from JWKS outages and DPoP replays in logs.
-
-### Changed
-- CI and release workflow improvements from first-release learnings.
-
-## [0.1.0] - 2026-05-11
-
-- Initial release.

authplane_sdk-0.2.0/authplane/cache.py

@@ -1,78 +0,0 @@
-"""Token cache with TTL buffer for client_credentials tokens."""
-
-import time
-from dataclasses import dataclass
-
-
-@dataclass
-class CacheEntry:
-    """A cached token."""
-
-    access_token: str
-    token_type: str
-    expires_in: int
-    scope: str
-    expires_at: float  # monotonic time
-
-
-class TokenCache:
-    """In-memory token cache with configurable TTL buffer.
-
-    Tokens are evicted `ttl_buffer_seconds` before their actual expiry
-    to avoid using tokens that are about to expire.
-    """
-
-    def __init__(
-        self,
-        ttl_buffer_seconds: float = 30.0,
-        default_ttl_seconds: float = 3600.0,
-    ) -> None:
-        self._ttl_buffer = ttl_buffer_seconds
-        self._default_ttl = default_ttl_seconds
-        self._entries: dict[str, CacheEntry] = {}
-
-    def get(self, key: str) -> CacheEntry | None:
-        """Get a cached entry if it exists and hasn't expired."""
-        entry = self._entries.get(key)
-        if entry is None:
-            return None
-        if time.monotonic() >= entry.expires_at:
-            del self._entries[key]
-            return None
-        return entry
-
-    def set(
-        self,
-        key: str,
-        access_token: str,
-        token_type: str,
-        expires_in: int = 0,
-        scope: str = "",
-    ) -> None:
-        """Cache a token. Skips caching if effective TTL <= 0."""
-        ttl = (expires_in if expires_in > 0 else self._default_ttl) - self._ttl_buffer
-        if ttl <= 0:
-            return
-        self._entries[key] = CacheEntry(
-            access_token=access_token,
-            token_type=token_type,
-            expires_in=expires_in,
-            scope=scope,
-            expires_at=time.monotonic() + ttl,
-        )
-
-    def delete(self, key: str) -> None:
-        """Remove a cached entry."""
-        self._entries.pop(key, None)
-
-    @staticmethod
-    def cache_key(scope: str = "", resource: str = "") -> str:
-        """Generate a deterministic cache key from scope and resource.
-
-        Scopes are sorted for consistency.
-        """
-        parts = sorted(scope.split()) if scope else []
-        scope_part = " ".join(parts)
-        if resource:
-            return f"{scope_part}|{resource}" if scope_part else f"|{resource}"
-        return scope_part or "_default"