fix(dpop,mcp,fastmcp): keep the ;params segment in the htu binding, make the PRM hook public

`urlparse` peels an RFC 3986 `;params` segment off the last path segment, so a
request to `/orders;v=2` bound an `htu` of `/orders` — a proof computed over a
different resource than the one being accessed, and RFC 3986 §3.3 puts `;params`
squarely in the path. The htu construction uses `urlsplit`, which does not split
it off, and the round-trip no longer has to fill `urlunparse`'s params slot.

`VerbatimPRMRemoteAuthProvider` is now public (was `_VerbatimPRMRemoteAuthProvider`)
and `rewrite_prm_routes_verbatim` is exported: building a `RemoteAuthProvider` by
hand is a documented FastMCP pattern, and doing so silently lost the verbatim PRM.
`install_request_context(mcp)` now detects a verifier carrying no verbatim
identifiers and warns instead of skipping the rewrite in silence — a verifier
built through the public `AuthplaneTokenVerifier(verifier)` constructor has none,
so the previous `is None` check never fired for it and the served document kept
advertising slash-normalized identifiers that this SDK's own byte-for-byte
comparison rejects. `AuthplaneTokenVerifier.verbatim_identifiers()` exposes the
pair without cross-module private attribute reads.

`install_request_context` also stops touching `mcp.sse_app` unguarded: SSE is not
on the streamable-HTTP path, so a future `mcp` 1.x that drops the attribute would
have taken down servers that never touch SSE.

Author: RobertoIskandarani

authplane-fastmcp/README.md

@@ -48,6 +48,40 @@ asyncio.run(main())
 
 `authplane_auth()` holds background JWKS and metadata refresh tasks; call `aclose()` on the returned `client` during server shutdown.
 
+## Hand-rolling the auth provider
+
+`authplane_auth()` returns a `VerbatimPRMRemoteAuthProvider`, a `RemoteAuthProvider`
+subclass that serves the Protected Resource Metadata identifiers byte-for-byte.
+It matters: upstream builds the PRM from `pydantic.AnyHttpUrl` fields, which append
+a trailing slash to an empty-path authority, and the core SDK compares identifiers
+verbatim — so a client that follows the advertised value literally is rejected.
+
+If you build a `RemoteAuthProvider` yourself instead of calling `authplane_auth()`
+— a documented FastMCP pattern — use the subclass rather than the base class:
+
+```python
+from authplane_fastmcp import VerbatimPRMRemoteAuthProvider
+from pydantic import AnyHttpUrl
+
+provider = VerbatimPRMRemoteAuthProvider(
+    token_verifier=token_verifier,
+    authorization_servers=[AnyHttpUrl(issuer)],
+    base_url=AnyHttpUrl(base_url),
+    scopes_supported=scopes,
+    # The two that make it verbatim. Pass the identifiers exactly as configured,
+    # not the AnyHttpUrl forms above — that is the whole point: those normalize.
+    verbatim_issuer=issuer,
+    verbatim_resource=resource,
+)
+```
+
+`base_url` is the server's base URL and `verbatim_resource` is the full resource
+identifier; they are not the same value when the MCP server is mounted under a
+path.
+
+If you cannot subclass, `rewrite_prm_routes_verbatim(routes, issuer=..., resource=...)`
+is exported as a supported hook — apply it to the route list your provider returns.
+
 ## Documentation
 
 PRM behavior, dev mode, revocation checking, manual setup, scope enforcement semantics, claim access, the full `authplane_auth` / `AuthplaneTokenVerifier` API, and error handling: **[User Guide](https://github.com/AuthPlane/python-sdk/blob/main/authplane-fastmcp/docs/user-guide.md)**.

authplane-fastmcp/authplane_fastmcp/__init__.py

@@ -16,14 +16,21 @@
 except _PackageNotFoundError:  # pragma: no cover - source tree without an install
     __version__ = "0.0.0+unknown"
 
-from .auth import AuthplaneAuthResult, authplane_auth
+from ._prm import rewrite_prm_routes_verbatim
+from .auth import (
+    AuthplaneAuthResult,
+    VerbatimPRMRemoteAuthProvider,
+    authplane_auth,
+)
 from .url_elicitation import to_url_elicitation_required_error
 from .verifier import AuthplaneTokenVerifier
 
 __all__ = [
     "AuthplaneAuthResult",
     "AuthplaneTokenVerifier",
+    "VerbatimPRMRemoteAuthProvider",
     "__version__",
     "authplane_auth",
+    "rewrite_prm_routes_verbatim",
     "to_url_elicitation_required_error",
 ]

authplane-fastmcp/authplane_fastmcp/_prm.py

@@ -13,11 +13,18 @@
 This module post-processes the served PRM response so the two identifier fields
 carry exactly the operator-configured strings, without touching any other field
 (scopes, bearer methods, cache headers, CORS) the upstream route emits.
+
+NOTE: this module is mirrored byte-for-byte in
+``authplane-mcp/authplane_mcp/_prm.py``. It is the larger and subtler of
+the two duplicated modules — the rewrite gating below is easy to get wrong in one
+copy only. Any fix here must be applied to both.
 """
 
 import json
-from collections.abc import Awaitable, Callable, MutableSequence
+import warnings
+from collections.abc import Awaitable, Callable, Iterable
 from typing import Any
+from urllib.parse import urlsplit
 
 from starlette.routing import BaseRoute, Route
 
@@ -37,7 +44,8 @@ def _rewrite_body(body: bytes, *, issuer: str, resource: str) -> bytes:
     trailing-slash normalization: in ``authorization_servers`` the element equal
     to ``issuer`` or ``issuer + "/"`` is swapped for the verbatim ``issuer`` and
     every other entry is left in place, so a multi-AS advertisement keeps its
-    extra entries. ``resource`` is set verbatim.
+    extra entries. ``resource`` is replaced outright: the caller only routes this
+    function at the document belonging to the configured resource.
 
     Any body that is not a JSON object (e.g. a CORS preflight with an empty
     body) is returned unchanged.
@@ -55,7 +63,13 @@ def _rewrite_body(body: bytes, *, issuer: str, resource: str) -> bytes:
         if rewritten != servers:
             doc["authorization_servers"] = rewritten
             changed = True
-    if "resource" in doc and doc["resource"] != resource:
+    # Unconditional: which document this is was already decided by route
+    # matching in rewrite_prm_routes_verbatim, so anything served here belongs to
+    # the configured resource. Gating on the value instead would only cover the
+    # trailing-slash normalization and silently skip every other one the URL
+    # layer can apply (host case, an explicit default port, a doubled slash, a
+    # dot segment) — which is precisely the mismatch this module exists to fix.
+    if doc.get("resource") != resource:
         doc["resource"] = resource
         changed = True
     if not changed:
@@ -113,17 +127,64 @@ async def capture(message: _Message) -> None:
     return app
 
 
-def rewrite_prm_routes_verbatim(
-    routes: MutableSequence[BaseRoute], *, issuer: str, resource: str
-) -> None:
-    """Wrap, in place, every Protected Resource Metadata route in ``routes``.
+def rewrite_prm_routes_verbatim(routes: Iterable[BaseRoute], *, issuer: str, resource: str) -> None:
+    """Wrap, in place, the Protected Resource Metadata route for ``resource``.
+
+    Selects by route path, not by document contents: RFC 9728 §3.1 derives the
+    well-known path *from* the resource identifier, so the path is what says
+    which resource a document describes. An app serving PRM for several
+    resources registers one route each, and only the matching one is wrapped.
+
+    Matching on the path rather than on the served ``resource`` value is what
+    keeps full normalization coverage. The served value has been through the
+    URL layer and can differ from the configured string by more than a trailing
+    slash; the path has not.
 
-    Matches routes registered under ``/.well-known/oauth-protected-resource``
-    (RFC 9728 §3) and swaps their ASGI app for one that advertises ``issuer``
-    and ``resource`` verbatim.
+    Emits a ``RuntimeWarning`` when routes exist under the well-known prefix but
+    none is the derivation of ``resource`` — that means the rewrite did nothing,
+    and a silent no-op here ships a PRM advertising identifiers the core SDK's
+    byte-for-byte comparison rejects.
     """
+    target = _PRM_PATH_PREFIX + urlsplit(resource).path.rstrip("/")
+    seen_prefix = False
+    wrapped = False
     for route in routes:
-        if isinstance(route, Route) and (
-            route.path == _PRM_PATH_PREFIX or route.path.startswith(_PRM_PATH_PREFIX + "/")
-        ):
-            route.app = _wrap_app(route.app, issuer=issuer, resource=resource)
+        if not isinstance(route, Route):
+            continue
+        if route.path == _PRM_PATH_PREFIX or route.path.startswith(_PRM_PATH_PREFIX + "/"):
+            seen_prefix = True
+            # Compare right-stripped: upstream keeps a trailing path slash when
+            # deriving the well-known path (its rule is "the path unless it is
+            # exactly /"), while `target` strips it. Everything else agrees. Left
+            # as an equality check, a resource configured as `/mcp/` matched no
+            # route — and skipping the wrap skips the *issuer* rewrite too, so
+            # `authorization_servers` kept the slash-normalized form the core
+            # SDK rejects. The prefix match this replaced covered that shape.
+            #
+            # What it trades away: an application serving `/mcp` and `/mcp/` as
+            # two distinct resources has both routes wrapped, which is the
+            # sibling clobber that route selection exists to prevent. Two
+            # identifiers differing only by a trailing slash collapse to one
+            # document under *this* SDK's derivation, and under the TS
+            # sibling's, which documents the same choice (`core/prm.ts`:
+            # "Trailing slashes on the resource path are dropped"). RFC 9728
+            # §3.1 does not settle the case — it says to insert the well-known
+            # segment between the host and the path, and says nothing about
+            # normalizing a terminating slash — and upstream keeps it, deriving
+            # two documents. That divergence is where the trailing-slash bug
+            # came from, and it is why this comparison is right-stripped at
+            # all. Given our derivation, the pair is pathological rather than a
+            # case to support.
+            if route.path.rstrip("/") == target:
+                route.app = _wrap_app(route.app, issuer=issuer, resource=resource)
+                wrapped = True
+    if seen_prefix and not wrapped:
+        warnings.warn(
+            f"no Protected Resource Metadata route matches {target!r} (the RFC 9728 "
+            f"§3.1 derivation of {resource!r}), so the served document keeps the "
+            "slash-normalized identifiers the core SDK's byte-for-byte comparison "
+            "rejects. Routes under the well-known prefix were found, so the "
+            "derivation and the registered path disagree.",
+            RuntimeWarning,
+            stacklevel=2,
+        )

authplane-fastmcp/authplane_fastmcp/auth.py

@@ -20,14 +20,14 @@
 from authplane.oauth import TokenExchangeOptions, TokenResponse
 from fastmcp.server.auth import RemoteAuthProvider
 from pydantic import AnyHttpUrl
-from starlette.routing import Route
+from starlette.routing import BaseRoute
 
 from ._prm import rewrite_prm_routes_verbatim
 from .url_elicitation import to_url_elicitation_required_error
 from .verifier import AuthplaneTokenVerifier
 
 
-class _VerbatimPRMRemoteAuthProvider(RemoteAuthProvider):
+class VerbatimPRMRemoteAuthProvider(RemoteAuthProvider):
     """``RemoteAuthProvider`` that advertises identifiers verbatim in the PRM.
 
     Upstream builds the Protected Resource Metadata document from
@@ -51,7 +51,7 @@ def __init__(
         self._verbatim_issuer = verbatim_issuer
         self._verbatim_resource = verbatim_resource
 
-    def get_routes(self, *args: Any, **kwargs: Any) -> list[Route]:
+    def get_routes(self, *args: Any, **kwargs: Any) -> list[BaseRoute]:
         # Forward whatever positional/keyword args the framework passes so a
         # future signature change in the base ``get_routes`` cannot TypeError
         # at app-build time; only the verbatim PRM rewrite below is ours.
@@ -64,6 +64,18 @@ def get_routes(self, *args: Any, **kwargs: Any) -> list[Route]:
         return routes
 
 
+def _derive_resource_url(base_url: str, mcp_path: str) -> str:
+    """Compose the canonical resource identifier (= JWT audience) from the mount.
+
+    This must match exactly what ``RemoteAuthProvider`` advertises in the PRM,
+    which FastMCP computes as ``base_url`` joined with the transport mount path
+    via ``_get_resource_url()``. That agreement is pinned directly against
+    upstream's function by ``test_derive_resource_url_matches_fastmcp``, so it
+    is checked rather than only asserted here.
+    """
+    return base_url.rstrip("/") + "/" + mcp_path.lstrip("/")
+
+
 def _wrap_client_for_elicitation(client: AuthplaneClient) -> AuthplaneClient:
     """Translate ``client.exchange`` consent errors into MCP ``-32042``.
 
@@ -227,7 +239,15 @@ async def authplane_auth(
         mcp_path: Mount path of the MCP endpoint (default ``"/mcp"``).
             The JWT audience (resource) is derived as
             ``base_url + mcp_path``. Only set this if you changed
-            FastMCP's default HTTP mount path.
+            FastMCP's default HTTP mount path. Pass a real mount path — an
+            empty string is not one. Against a ``base_url`` that carries a
+            path, ``""`` derives an identifier FastMCP does not serve:
+            upstream short-circuits a falsy path and returns the base URL
+            untouched, while this join appends a slash. Accepted rather than
+            rejected, since raising would be a behaviour change to a public
+            factory for an input nothing passes; the divergence itself is
+            pinned by
+            ``test_derive_resource_url_diverges_from_fastmcp_on_an_empty_mount_path``.
         as_credentials: Client credentials for authenticating to the AS.
             Shared by introspection (RFC 7662) and token exchange (RFC 8693).
             Required when using ``IntrospectionRevocation`` for authenticated
@@ -270,10 +290,7 @@ async def authplane_auth(
     """
     resolved_scopes = scopes or []
 
-    # Derive the canonical resource URL (= JWT audience) from base_url + mcp_path.
-    # This must match exactly what RemoteAuthProvider advertises in the PRM, which
-    # FastMCP computes as base_url + mcp_path via _get_resource_url().
-    resource = base_url.rstrip("/") + "/" + mcp_path.lstrip("/")
+    resource = _derive_resource_url(base_url, mcp_path)
 
     # Prepare client-level kwargs, filtering out None to use SDK defaults
     client_kwargs_raw: dict[str, Any] = {
@@ -332,11 +349,11 @@ async def authplane_auth(
     # upstream framework requires the URL type internally. That construction
     # normalizes an empty-path authority with a trailing slash, so the served
     # PRM would otherwise advertise ``https://auth.example.com/`` for an issuer
-    # configured as ``https://auth.example.com``. ``_VerbatimPRMRemoteAuthProvider``
+    # configured as ``https://auth.example.com``. ``VerbatimPRMRemoteAuthProvider``
     # rewrites the served ``authorization_servers`` / ``resource`` back to the
     # verbatim configured strings so they match the core SDK's byte-for-byte
     # comparison (RFC 8414 §3.3, RFC 9728 §3.3).
-    auth_provider = _VerbatimPRMRemoteAuthProvider(
+    auth_provider = VerbatimPRMRemoteAuthProvider(
         token_verifier=token_verifier,
         authorization_servers=[AnyHttpUrl(issuer)],
         base_url=AnyHttpUrl(base_url),

authplane-fastmcp/authplane_fastmcp/url_elicitation.py

@@ -70,7 +70,12 @@ def _resolve_elicitation_id_kwarg(model: type[BaseModel]) -> str:
     # with no id). The ``mcp<2`` ceiling means this branch can only be reached
     # inside mcp 1.x, so a third spelling is an unexpected schema change: fail
     # loudly rather than emit a malformed elicitation.
-    raise ImportError(
+    # RuntimeError, not ImportError: this resolver runs both at import time (where
+    # ImportError is the right shape) and lazily from
+    # ``_build_url_elicitation_params``, where the installed package imported
+    # fine and the failure is a runtime schema mismatch. ImportError from a
+    # non-import call site sends the reader looking for a missing dependency.
+    raise RuntimeError(
         f"authplane-fastmcp cannot resolve the elicitation-id field on {model.__name__!r}: "
         "none of the known spellings (elicitationId, elicitation_id) is a declared "
         "field. The installed mcp is not compatible; require mcp>=1.28.1,<2."
@@ -79,9 +84,17 @@ def _resolve_elicitation_id_kwarg(model: type[BaseModel]) -> str:
 
 # Fail fast at import: the installed mcp must expose a known elicitation-id
 # spelling. Resolution is otherwise lazy (see _build_url_elicitation_params) so
-# tests can patch the model without re-triggering this. The bare call exists
-# only for its import-time validation side effect; no name is bound.
-_resolve_elicitation_id_kwarg(ElicitRequestURLParams)
+# tests can patch the model without re-triggering this. The name below is never
+# read — it is bound only so this validation runs as an import-time side effect.
+#
+# The resolver raises RuntimeError because it is also called lazily, where the
+# package imported fine and the failure is a runtime schema mismatch. At *this*
+# call site the failure really is "the installed distribution is unusable", so
+# translate it to the shape a reader expects from a failing import.
+try:
+    _ELICITATION_ID_KWARG = _resolve_elicitation_id_kwarg(ElicitRequestURLParams)
+except RuntimeError as exc:  # pragma: no cover - exercised via importlib.reload
+    raise ImportError(str(exc)) from exc
 
 
 def _build_url_elicitation_params(

authplane-fastmcp/docs/user-guide.md

@@ -244,7 +244,7 @@ Trade-offs to understand before enabling `fail_closed=True`:
 
 - **Availability**: an authorization server or introspection outage makes every request fail with 401 until the outage resolves. Once the client's circuit breaker opens, checks fail fast and all tokens are rejected until the cooldown elapses.
 - **Credentials**: authorization servers commonly require authenticated introspection; without valid `as_credentials` the introspection call fails, which under `fail_closed=True` means every token is rejected. Verify credentials as part of deployment, not just at rollout.
-- **Metadata**: an AS whose metadata document does not advertise `introspection_endpoint` fails every introspection attempt. Under the default that check is silently skipped; under `fail_closed=True` every token is rejected — and unlike an outage this never self-recovers, because the missing endpoint is a permanent property of the AS configuration. Confirm the endpoint is present in AS metadata before enabling.
+- **Metadata**: an AS whose metadata document does not advertise `introspection_endpoint` fails every introspection attempt. Under the default that check is skipped and every request logs a `Revocation check failed (fail-open)` warning — for a missing endpoint that is every request, permanently, since the condition never clears; under `fail_closed=True` every token is rejected — and unlike an outage this never self-recovers, because the missing endpoint is a permanent property of the AS configuration. Confirm the endpoint is present in AS metadata before enabling.
 - `fail_closed` has no effect when `revocation_checker` is `None` — the flag is only consulted when a revocation check actually runs. The SDK logs a warning at resource construction when it detects this misconfiguration.
 
 ### Custom Revocation Checker
@@ -529,10 +529,36 @@ Returned by `authplane_auth()`. Supports `**` unpacking into `FastMCP()` — the
 
 | Attribute | Type | Description |
 |-----------|------|-------------|
-| `auth` | `RemoteAuthProvider` | Auth provider for FastMCP |
+| `auth` | `RemoteAuthProvider` (a `VerbatimPRMRemoteAuthProvider` in practice) | Auth provider for FastMCP. `authplane_auth()` always constructs the subclass — see below — but the attribute is typed as the base class, so a checker will not offer subclass members without a narrowing check |
 | `token_verifier` | `AuthplaneTokenVerifier` | Token verifier (for advanced / manual setup) |
 | `client` | `AuthplaneClient` | Underlying SDK client (use `client.exchange()` for RFC 8693) |
 
+### `VerbatimPRMRemoteAuthProvider`
+
+`RemoteAuthProvider` subclass that serves the Protected Resource Metadata identifiers
+byte-for-byte. Upstream builds the PRM from `pydantic.AnyHttpUrl` fields, which append a
+trailing slash to an empty-path authority; the core SDK compares identifiers verbatim, so a
+client following the advertised value literally is rejected.
+
+`authplane_auth()` returns one already configured. Construct it directly only when you build
+the provider yourself — a documented FastMCP pattern — since using the base class instead
+loses the verbatim PRM silently.
+
+| Constructor argument | Description |
+|---|---|
+| `verbatim_issuer` | The issuer exactly as configured, not the `AnyHttpUrl` form |
+| `verbatim_resource` | The resource identifier exactly as configured |
+
+Everything else is forwarded to `RemoteAuthProvider` — note `base_url` is the server base,
+which is not the same value as `verbatim_resource` when the server is mounted under a path.
+
+### `rewrite_prm_routes_verbatim(routes, *, issuer, resource)`
+
+The rewrite itself, exported for the case where you cannot subclass. Apply it to the route
+list your provider returns. It wraps the single route whose path is the RFC 9728 §3.1
+derivation of `resource`, and emits a `RuntimeWarning` when routes exist under the well-known
+prefix but none is that derivation — meaning the rewrite did nothing.
+
 ### `AuthplaneTokenVerifier`
 
 FastMCP `TokenVerifier` implementation.