fix(client): warn on fail_closed without a checker; pin outage edge cases

- AuthplaneClient.resource() logs a warning when fail_closed=True is
  combined with revocation_checker=None. The flag is a security-relevant
  no-op in that combination, and the misconfiguration should be
  observable in production, not only documented. The warning lives in
  the core factory rather than the adapters so direct resource() users
  get it too.
- New core tests pin two fail-closed failure modes that were emergent:
  AS metadata without introspection_endpoint rejects every token
  (permanently, since it is a configuration property rather than an
  outage), and an open circuit breaker rejects all traffic without
  further HTTP calls (TokenRevokedError with CircuitOpenError as cause).
- Both user guides gain the metadata trade-off bullet and note the new
  warning.

Author: RobertoIskandarani

CHANGELOG.md

@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- `authplane-fastmcp`, `authplane-mcp`: `authplane_auth()` and `authplane_mcp_auth()` accept `fail_closed: bool = False` and forward it to `AuthplaneClient.resource(...)`, so factory users can opt into rejecting tokens (`TokenRevokedError`) when the configured `revocation_checker` itself fails — e.g. an unreachable introspection endpoint — instead of the default fail-open acceptance. The flag is only consulted when a `revocation_checker` is configured. Both user guides document the availability/security trade-off, the authenticated-introspection credential requirement, and the circuit-breaker interaction.
+- `authplane-fastmcp`, `authplane-mcp`: `authplane_auth()` and `authplane_mcp_auth()` accept `fail_closed: bool = False` and forward it to `AuthplaneClient.resource(...)`, so factory users can opt into rejecting tokens (`TokenRevokedError`) when the configured `revocation_checker` itself fails — e.g. an unreachable introspection endpoint — instead of the default fail-open acceptance. The flag is only consulted when a `revocation_checker` is configured; `AuthplaneClient.resource(...)` now logs a warning when `fail_closed=True` is set without one, since that combination runs no revocation check at all. Both user guides document the availability/security trade-off, the authenticated-introspection credential requirement, the circuit-breaker interaction, and the permanent rejection that results from AS metadata lacking `introspection_endpoint`.
 
 ## [0.3.0] - 2026-07-21
 

authplane-fastmcp/docs/user-guide.md

@@ -244,7 +244,8 @@ 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.
-- `fail_closed` has no effect when `revocation_checker` is `None` — the flag is only consulted when a revocation check actually runs.
+- **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.
+- `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
 

authplane-mcp/docs/user-guide.md

@@ -232,7 +232,8 @@ 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.
-- `fail_closed` has no effect when `revocation_checker` is `None` — the flag is only consulted when a revocation check actually runs.
+- **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.
+- `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
 

authplane/client.py

@@ -422,6 +422,16 @@ def resource(
         """
         from .verifier import AuthplaneResource
 
+        # fail_closed is only consulted when a revocation check runs; setting
+        # it without a checker means no revocation check happens at all, which
+        # is the opposite of what the operator asked for — make it observable.
+        if fail_closed and revocation_checker is None:
+            logger.warning(
+                "fail_closed=True has no effect without a revocation_checker: "
+                "no revocation check will run",
+                extra={"resource": resource},
+            )
+
         return AuthplaneResource(
             client=self,
             resource=resource,

tests/verifier/test_revocation.py

@@ -272,6 +272,96 @@ async def test_introspection_no_endpoint_in_metadata_skips(
         await c.aclose()
 
 
+async def test_introspection_no_endpoint_in_metadata_fail_closed_rejects(
+    mock_jwks: Route,  # metadata without introspection_endpoint
+    token_factory: Any,
+) -> None:
+    """fail_closed=True + metadata without introspection_endpoint -> every token rejected.
+
+    Unlike an outage this never recovers on its own: the missing endpoint is a
+    permanent property of the AS configuration, not a transient failure.
+    """
+    c = await AuthplaneClient.create(
+        issuer=ISSUER,
+        fetch_settings=FetchSettings(ssrf_protection=False),
+    )
+    v = c.resource(
+        resource=RESOURCE,
+        scopes=["read:data"],
+        revocation_checker=IntrospectionRevocation(),
+        fail_closed=True,
+    )
+    try:
+        token = token_factory()
+        with pytest.raises(TokenRevokedError):
+            await v.verify(token)
+    finally:
+        await c.aclose()
+
+
+async def test_introspection_open_circuit_fail_closed_rejects(
+    mock_jwks_with_introspection: None,
+    token_factory: Any,
+) -> None:
+    """fail_closed=True + open circuit breaker -> all tokens rejected until cooldown.
+
+    With threshold=1 a single introspection 500 opens the breaker; the next
+    verify() is rejected before any HTTP call (CircuitOpenError -> TokenRevokedError).
+    """
+    from authplane.errors import CircuitOpenError
+
+    c = await AuthplaneClient.create(
+        issuer=ISSUER,
+        fetch_settings=FetchSettings(ssrf_protection=False),
+        circuit_breaker_threshold=1,
+    )
+    v = c.resource(
+        resource=RESOURCE,
+        scopes=["read:data"],
+        revocation_checker=IntrospectionRevocation(),
+        fail_closed=True,
+    )
+    try:
+        introspection_route = respx.post(INTROSPECTION_URL).mock(
+            return_value=respx.MockResponse(500, json={"error": "server_error"})
+        )
+        token = token_factory()
+
+        # First verify: the 500 rejects the token and trips the breaker.
+        with pytest.raises(TokenRevokedError):
+            await v.verify(token)
+        first_call_count = introspection_route.call_count
+
+        # Second verify: rejected by the open breaker, no HTTP call made.
+        with pytest.raises(TokenRevokedError) as exc_info:
+            await v.verify(token)
+        assert isinstance(exc_info.value.__cause__, CircuitOpenError)
+        assert introspection_route.call_count == first_call_count
+    finally:
+        await c.aclose()
+
+
+async def test_fail_closed_without_checker_warns(
+    mock_jwks: Route,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """fail_closed=True with revocation_checker=None is a no-op -> logged warning."""
+    c = await AuthplaneClient.create(
+        issuer=ISSUER,
+        fetch_settings=FetchSettings(ssrf_protection=False),
+    )
+    try:
+        with caplog.at_level("WARNING", logger="authplane.client"):
+            c.resource(
+                resource=RESOURCE,
+                scopes=["read:data"],
+                fail_closed=True,
+            )
+        assert any("fail_closed=True has no effect" in record.message for record in caplog.records)
+    finally:
+        await c.aclose()
+
+
 async def test_introspection_sends_correct_token(
     verifier_with_introspection: AuthplaneResource,
     token_factory: Any,