fix: stop normalising resource and issuer identifiers

RFC 8414 §3.3 and RFC 9728 §3.3 require the advertised issuer/resource
to be identical to the configured value — a simple string comparison —
and both well-known URLs are formed by inserting the well-known path
segment into the identifier verbatim (RFC 8414 §3 / RFC 9728 §3). The
SDK instead stripped slashes in five places:

- AuthplaneClient.create rewrote the configured issuer with rstrip("/").
  The rewritten value became the verifier's expected iss claim, so an
  AS whose issuer identifier legitimately ends in "/" had every token
  rejected (RFC 9068 requires iss to carry the slash).
- build_prm_url and build_metadata_url used path.strip("/"), dropping
  the trailing slash the insertion rule requires be preserved; both are
  now pure insertion of the parsed path.
- MetadataCache rstripped both sides of the issuer comparison,
  weakening the §3.3 identical-match MUST that defeats metadata
  substitution.

Identifiers are now validated at construction instead (absolute
http(s) URL with an authority, no fragment — RFC 8707 §2) via the new
internal validate_identifier helper, and never transformed.

Conformance: extends the rfc9728 well-known-path case with the
trailing-slash resource datum and adds two issuer variants — metadata
issuer differing only by a trailing slash is rejected, and a token
whose iss matches a configured trailing-slash issuer verifies end to
end (discovery at the trailing-slash well-known URL included).

Migration: if a configured issuer or resource differs from the
authorization server's actual identifier by a trailing slash, correct
the config — the SDK no longer silently reconciles them.

Author: RobertoIskandarani

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Resource and issuer identifiers are never rewritten (RFC 8414 §3.3 / RFC 9728 §3.3 require the advertised value to be *identical* to the configured one). `build_prm_url` and `build_metadata_url` are formed by pure insertion, preserving the identifier's path exactly — including any trailing slash — and AS-metadata issuer comparison is now an exact string match. Identifiers are validated at construction (absolute http(s) URL with an authority and no fragment) and raise `ValueError` otherwise; trailing slashes, host case, and explicit ports are legal and preserved. **Migration**: if your configured issuer or resource differs from your authorization server's actual identifier by a trailing slash, correct the config — the SDK no longer silently reconciles them.
+
+### Fixed
+- A configured issuer whose identifier legitimately ends in `/` no longer has every token rejected. The trailing slash was silently stripped at client creation and the stripped value compared against the token's `iss`, which RFC 9068 requires to carry the slash; discovery now also resolves the RFC 8414 well-known URL for such issuers correctly.
+
 ## [0.3.0] - 2026-07-21
 
 ### Added

authplane/client.py

@@ -17,6 +17,7 @@
     JWKSCache,
     MetadataCache,
     build_metadata_url,
+    validate_identifier,
 )
 from .net import FetchSettings
 from .net.ssrf import SSRFError
@@ -134,7 +135,10 @@ async def create(
                 circuit trips. Default 30s.
         """
         client = cls()
-        client._issuer = issuer.rstrip("/")
+        # RFC 8414 Section 3.3 — the issuer is an opaque identifier compared
+        # with simple string equality (against metadata and token iss); it is
+        # validated but never rewritten.
+        client._issuer = validate_identifier(issuer, "issuer")
 
         # Dev mode
         resolved_dev_mode = (

authplane/internal/__init__.py

@@ -9,6 +9,7 @@
 )
 from .document_fetcher import DocumentFetcher
 from .fetch_result import FetchResult
+from .identifiers import validate_identifier
 from .metadata import MetadataCache
 from .urls import build_metadata_url, build_prm_url
 
@@ -23,4 +24,5 @@
     "build_metadata_url",
     "build_prm_url",
     "parse_expires_at",
+    "validate_identifier",
 ]

authplane/internal/identifiers.py

@@ -0,0 +1,33 @@
+"""Validation for resource and issuer identifiers.
+
+RFC 8414 Section 3.3 and RFC 9728 Section 3.3 require the advertised
+issuer/resource to be identical to the configured value — a simple string
+comparison, not RFC 3986 equivalence. The SDK therefore never rewrites an
+identifier: well-known URLs are formed by inserting the well-known path
+segment between the authority and the identifier's path (RFC 8414 Section 3 /
+RFC 9728 Section 3), and validation rejects structurally unusable identifiers
+instead of repairing them.
+"""
+
+from urllib.parse import urlparse
+
+
+def validate_identifier(value: str, label: str) -> str:
+    """Validate that *value* is an absolute http(s) URL identifier.
+
+    The identifier must have an http or https scheme, an authority, and no
+    fragment (RFC 8707 Section 2 forbids fragments in resource identifiers).
+    Returns *value* unchanged — trailing slashes, host case, and explicit
+    ports are all legal identifier variations and are preserved verbatim.
+
+    Raises:
+        ValueError: When the identifier is structurally invalid.
+    """
+    parsed = urlparse(value)
+    if parsed.scheme not in ("https", "http"):
+        raise ValueError(f"{label} must be an absolute http or https URL: {value!r}")
+    if not parsed.netloc:
+        raise ValueError(f"{label} must include an authority: {value!r}")
+    if "#" in value:
+        raise ValueError(f"{label} must not contain a fragment: {value!r}")
+    return value

authplane/internal/metadata.py

@@ -30,7 +30,7 @@ def __init__(
             on_change=on_change,
             error_factory=lambda msg: MetadataFetchError(msg),
         )
-        self._expected_issuer = expected_issuer.rstrip("/")
+        self._expected_issuer = expected_issuer
         self._allow_http = allow_http
 
     def _validate_endpoint_url(self, field: str, value: str) -> None:
@@ -50,9 +50,11 @@ def _validate_endpoint_url(self, field: str, value: str) -> None:
             )
 
     def _validate_metadata(self, metadata: dict[str, Any]) -> dict[str, Any]:
-        issuer = str(metadata.get("issuer", "")).rstrip("/")
+        issuer = str(metadata.get("issuer", ""))
         if not issuer:
             raise MetadataFetchError("AS metadata missing required 'issuer' field")
+        # RFC 8414 Section 3.3 — the returned issuer MUST be identical to the
+        # configured one; simple string comparison, no normalisation.
         if self._expected_issuer and issuer != self._expected_issuer:
             raise MetadataFetchError(
                 f"AS metadata issuer mismatch: expected {self._expected_issuer!r}, got {issuer!r}"

authplane/internal/urls.py

@@ -12,6 +12,9 @@ def build_prm_url(resource: str) -> str:
     RFC 9728 Section 3:
         https://{host}/.well-known/oauth-protected-resource/{path}
 
+    The insertion is a pure string operation: the resource's path is preserved
+    exactly, including any trailing slash.
+
     Examples:
         >>> build_prm_url("https://api.example.com")
         'https://api.example.com/.well-known/oauth-protected-resource'
@@ -22,19 +25,17 @@ def build_prm_url(resource: str) -> str:
         >>> build_prm_url("https://api.example.com/v2/mcp")
         'https://api.example.com/.well-known/oauth-protected-resource/v2/mcp'
 
+        >>> build_prm_url("https://api.example.com/mcp/")
+        'https://api.example.com/.well-known/oauth-protected-resource/mcp/'
+
     Args:
         resource: The resource server URI.
 
     Returns:
         The fully constructed PRM discovery URL.
     """
     parsed = urlparse(resource)
-    path = parsed.path.strip("/")
-
-    if path:
-        well_known_path = f"/.well-known/oauth-protected-resource/{path}"
-    else:
-        well_known_path = "/.well-known/oauth-protected-resource"
+    well_known_path = "/.well-known/oauth-protected-resource" + parsed.path
 
     return urlunparse(
         (
@@ -57,6 +58,9 @@ def build_metadata_url(issuer: str) -> str:
     RFC 8414 Section 3:
         https://{host}/.well-known/oauth-authorization-server/{path}
 
+    The insertion is a pure string operation: the issuer's path is preserved
+    exactly, including any trailing slash.
+
     Examples:
         >>> build_metadata_url("https://auth.example.com")
         'https://auth.example.com/.well-known/oauth-authorization-server'
@@ -67,21 +71,17 @@ def build_metadata_url(issuer: str) -> str:
         >>> build_metadata_url("https://auth.example.com/org/tenant1")
         'https://auth.example.com/.well-known/oauth-authorization-server/org/tenant1'
 
+        >>> build_metadata_url("https://auth.example.com/tenant1/")
+        'https://auth.example.com/.well-known/oauth-authorization-server/tenant1/'
+
     Args:
         issuer: The OAuth 2.1 authorization server issuer URL.
 
     Returns:
         The fully constructed metadata discovery URL.
     """
     parsed = urlparse(issuer)
-
-    # Strip leading/trailing slashes from the path to normalize
-    path = parsed.path.strip("/")
-
-    if path:
-        well_known_path = f"/.well-known/oauth-authorization-server/{path}"
-    else:
-        well_known_path = "/.well-known/oauth-authorization-server"
+    well_known_path = "/.well-known/oauth-authorization-server" + parsed.path
 
     return urlunparse(
         (

authplane/verifier/verifier.py

@@ -35,6 +35,7 @@
     TokenRevokedError,
     VerifierRuntimeError,
 )
+from ..internal.identifiers import validate_identifier
 from ..internal.jwt import decode_jwt_header
 from ..internal.urls import build_prm_url
 from ..oauth.prm import build_prm
@@ -71,7 +72,10 @@ def __init__(
             )
 
         self._client = client
-        self._resource = resource
+        # RFC 8707 Section 2 — the resource identifier is opaque; validated for
+        # structure, never rewritten (it is compared verbatim against aud and
+        # advertised verbatim in PRM).
+        self._resource = validate_identifier(resource, "resource")
         self._scopes = tuple(scopes)
         self._allowed_algorithms = allowed_algorithms
         self._clock_skew_seconds = clock_skew_seconds

conformance-tests/test_jwt_and_dpop_conformance.py

@@ -166,10 +166,42 @@ async def test_rfc9068_typ_must_be_at_jwt(verifier: Any, token_factory: Any) ->
 
 
 @pytest.mark.conformance("rfc9068-issuer-must-match")
-async def test_rfc9068_issuer_must_match(verifier: Any, token_factory: Any) -> None:
+async def test_rfc9068_issuer_must_match(
+    verifier: Any, token_factory: Any, jwks_keypair: dict[str, Any]
+) -> None:
     with pytest.raises(InvalidClaimsError):
         await verifier.verify(token_factory(iss="https://wrong-issuer.com"))
 
+    # Variant: a token whose iss is identical to a configured trailing-slash
+    # issuer must verify — the issuer is never rewritten, end to end:
+    # discovery resolves the trailing-slash well-known URL (RFC 8414 §3), the
+    # advertised issuer matches exactly (§3.3), and the token's iss matches
+    # exactly (RFC 9068 §4).
+    slash_issuer = "https://auth.example.com/"
+    with respx.mock:
+        respx.get("https://auth.example.com/.well-known/oauth-authorization-server/").mock(
+            return_value=respx.MockResponse(
+                200,
+                json={
+                    "issuer": slash_issuer,
+                    "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
+                },
+            )
+        )
+        respx.get("https://auth.example.com/.well-known/jwks.json").mock(
+            return_value=respx.MockResponse(200, json=jwks_keypair["jwks"])
+        )
+
+        client = await AuthplaneClient.create(issuer=slash_issuer, fetch_settings=_NO_SSRF)
+        try:
+            slash_verifier = client.resource(
+                resource="https://api.example.com", scopes=["read:data"]
+            )
+            claims = await slash_verifier.verify(token_factory(iss=slash_issuer))
+            assert claims.issuer == slash_issuer
+        finally:
+            await client.aclose()
+
 
 @pytest.mark.conformance("rfc9068-audience-must-match-resource")
 async def test_rfc9068_audience_must_match_resource(verifier: Any, token_factory: Any) -> None:
@@ -1113,6 +1145,11 @@ async def test_rfc9728_well_known_path_must_derive_from_resource_uri() -> None:
         build_prm_url("https://api.example.com/v2/mcp")
         == "https://api.example.com/.well-known/oauth-protected-resource/v2/mcp"
     )
+    # RFC 9728 §3 insertion preserves the path exactly, including a trailing slash.
+    assert (
+        build_prm_url("https://api.example.com/mcp/")
+        == "https://api.example.com/.well-known/oauth-protected-resource/mcp/"
+    )
 
 
 @pytest.mark.conformance("rfc9728-prm-must-contain-required-fields")

conformance-tests/test_rfc8414_conformance.py

@@ -38,6 +38,29 @@ async def test_rfc8414_metadata_issuer_must_match_configured_issuer(
                 fetch_settings=_NO_SSRF,
             )
 
+    # Variant: a trailing-slash difference is equivalent per RFC 3986 §6.2.3
+    # but not identical — RFC 8414 §3.3 requires identity, so it must be
+    # rejected.
+    with respx.mock:
+        respx.get("https://auth.example.com/.well-known/oauth-authorization-server").mock(
+            return_value=respx.MockResponse(
+                200,
+                json={
+                    "issuer": "https://auth.example.com/",
+                    "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
+                },
+            )
+        )
+        respx.get("https://auth.example.com/.well-known/jwks.json").mock(
+            return_value=respx.MockResponse(200, json=jwks_keypair["jwks"])
+        )
+
+        with pytest.raises(MetadataFetchError, match="issuer mismatch"):
+            await AuthplaneClient.create(
+                issuer="https://auth.example.com",
+                fetch_settings=_NO_SSRF,
+            )
+
 
 @pytest.mark.conformance("rfc8414-jwks-uri-required-for-jwt-validation")
 async def test_rfc8414_jwks_uri_required_for_jwt_validation() -> None:

tests/internal/test_metadata.py

@@ -88,17 +88,19 @@ async def test_get_jwks_uri_missing_field() -> None:
         await cache.get_jwks_uri()
 
 
-async def test_expected_issuer_trailing_slash_is_normalized() -> None:
+async def test_expected_issuer_trailing_slash_mismatch_raises() -> None:
+    # RFC 8414 §3.3 — the returned issuer must be identical to the configured
+    # one. A trailing-slash difference is equivalent per RFC 3986 §6.2.3 but
+    # not identical.
     fetcher = TrackingFetcher(metadata=SAMPLE_METADATA)
     cache = MetadataCache(
         fetcher,
         expected_issuer="https://auth.example.com/",
         document_type="metadata",
     )
 
-    metadata = await cache.get()
-
-    assert metadata["issuer"] == "https://auth.example.com"
+    with pytest.raises(MetadataFetchError, match="issuer mismatch"):
+        await cache.get()
 
 
 # ---------------------------------------------------------------------------