feat(fastmcp,mcp): expose fail_closed through the adapter auth factories

The core SDK already implements fail_closed on
AuthplaneClient.resource(...), but neither authplane_auth() nor
authplane_mcp_auth() forwarded it, so factory users opting into
revocation checking were locked into fail-open behavior on
introspection/revocation-check outages.

Both factories now accept fail_closed: bool = False and pass it through
at the client.resource(...) boundary. The default preserves today's
fail-open behavior.

Also adds the previously missing core coverage for fail_closed=True
(crashing custom checker and introspection HTTP 500 both reject with
TokenRevokedError), forwarding tests for both adapters, and user-guide
docs covering the availability/security trade-off, the
authenticated-introspection credential requirement, and the
circuit-breaker interaction.

Requested in #20.

Author: RobertoIskandarani

CHANGELOG.md

@@ -7,6 +7,9 @@ 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.
+
 ## [0.3.0] - 2026-07-21
 
 ### Added

authplane-fastmcp/authplane_fastmcp/auth.py

@@ -121,6 +121,7 @@ async def authplane_auth(
     inbound_dpop: InboundDPoPOptions | None = None,
     mcp_path: str = "/mcp",
     revocation_checker: IntrospectionRevocation | RevocationChecker | None = None,
+    fail_closed: bool = False,
 ) -> AuthplaneAuthResult:
     """Build the kwargs to enable Authplane auth on a FastMCP server.
 
@@ -201,10 +202,20 @@ async def authplane_auth(
               ``introspection_endpoint`` (RFC 7662) discovered from AS
               metadata. Raises ``TokenRevokedError`` if ``active=false``.
               Pass ``as_credentials`` for authenticated introspection.
-              Fails open if the endpoint is unavailable.
+              Fails open if the endpoint is unavailable, unless
+              ``fail_closed=True``.
             - async callable: custom checker called with
               ``(VerifiedClaims, raw_token)``; return ``True`` to reject
               the token (raises ``TokenRevokedError``).
+        fail_closed: Policy applied when the configured
+            ``revocation_checker`` itself fails (e.g. the introspection
+            endpoint is unreachable). ``False`` (default) accepts the
+            token — offline signature/claims validation still applies.
+            ``True`` rejects it with ``TokenRevokedError``, trading
+            availability during an AS outage for a hard revocation
+            guarantee. Only consulted when a ``revocation_checker`` is
+            configured; note that once the client's circuit breaker
+            opens, every request is rejected until the cooldown elapses.
 
     Returns:
         ``AuthplaneAuthResult`` with ``auth`` (``RemoteAuthProvider``),
@@ -268,6 +279,7 @@ async def authplane_auth(
         resource=resource,
         scopes=resolved_scopes,
         revocation_checker=revocation_checker,
+        fail_closed=fail_closed,
         **verifier_kwargs,
     )
 

authplane-fastmcp/docs/user-guide.md

@@ -82,6 +82,7 @@ All parameters of `authplane_auth()`:
 | `clock_skew_seconds` | `int` | `30` | Leeway for `exp`/`nbf`/`iat` validation |
 | `dev_mode` | `bool` | `False` | Relaxes SSRF checks for local development |
 | `revocation_checker` | see [below](#token-revocation-checking) | `None` | Token revocation strategy |
+| `fail_closed` | `bool` | `False` | Reject tokens when the revocation check itself fails, instead of accepting them (see [below](#failure-policy-fail-open-vs-fail-closed)) |
 | `fetch_settings` | `FetchSettings` | `None` | Full SSRF / fetch settings applied to both metadata and JWKS fetches (overrides `dev_mode`) |
 | `inbound_dpop` | `InboundDPoPOptions` | `None` | Per-resource inbound DPoP policy (replay store, max proof age, clock skew, accepted proof algorithms, `required`). When set, the resource advertises DPoP support in PRM (RFC 9728 §2). See **Inbound DPoP through the FastMCP adapter** below for current limitations. |
 
@@ -210,9 +211,35 @@ await authplane_auth(
 
 - The introspection endpoint is automatically discovered from AS metadata.
 - If the endpoint returns `active=false`, the token is rejected with `TokenRevokedError`.
-- **Fails open**: if the introspection endpoint is unavailable, the token is accepted (offline validation still applies).
+- **Fails open by default**: if the introspection endpoint is unavailable, the token is accepted (offline validation still applies). Pass `fail_closed=True` to reject instead (see [below](#failure-policy-fail-open-vs-fail-closed)).
 - `as_credentials` enables authenticated introspection (recommended for production).
 
+### Failure Policy: Fail-Open vs Fail-Closed
+
+`fail_closed` controls what happens when the revocation check itself fails — the introspection endpoint is unreachable, returns an error, or a custom checker raises:
+
+```python
+await authplane_auth(
+    issuer="https://auth.company.com",
+    base_url="https://mcp.company.com",
+    revocation_checker=IntrospectionRevocation(),
+    as_credentials=ASCredentials(
+        client_id="my_resource_server",
+        client_secret="secret",
+    ),
+    fail_closed=True,
+)
+```
+
+- `False` (default) accepts the token and logs a warning. Signature and claims validation still apply, so this only skips the *revocation* freshness check — it never admits an otherwise-invalid token.
+- `True` rejects the token with `TokenRevokedError`. Choose this for servers exposing mutation-capable or otherwise high-impact tools, where serving a revoked-but-unverifiable token is worse than downtime.
+
+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.
+
 ### Custom Revocation Checker
 
 Implement your own revocation logic with an async callable:
@@ -474,6 +501,7 @@ async def authplane_auth(
     fetch_settings: FetchSettings | None = None,
     inbound_dpop: InboundDPoPOptions | None = None,
     revocation_checker: IntrospectionRevocation | RevocationChecker | None = None,
+    fail_closed: bool = False,
 ) -> AuthplaneAuthResult
 ```
 

authplane-fastmcp/tests/test_auth_factory.py

@@ -5,7 +5,7 @@
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
-from authplane import DPoPProvider, FetchSettings, VerifiedClaims
+from authplane import DPoPProvider, FetchSettings, IntrospectionRevocation, VerifiedClaims
 
 from authplane_fastmcp import authplane_auth
 from authplane_fastmcp.auth import AuthplaneAuthResult
@@ -147,6 +147,46 @@ async def my_checker(claims: VerifiedClaims, raw_token: str) -> bool:
         assert verifier_kwargs["revocation_checker"] is my_checker
 
 
+@pytest.mark.asyncio
+async def test_authplane_auth_fail_closed_default_is_false():
+    """When fail_closed is not passed, False is forwarded (fail-open behavior)."""
+    mock_client = MagicMock()
+    _mock_resource = MagicMock()
+    _mock_resource.resource = "https://api.example.com/mcp"
+    mock_client.resource = MagicMock(return_value=_mock_resource)
+
+    with patch("authplane_fastmcp.auth.AuthplaneClient") as mock_client_cls:
+        mock_client_cls.create = AsyncMock(return_value=mock_client)
+        await authplane_auth(
+            issuer="https://auth.example.com",
+            base_url="https://api.example.com",
+        )
+
+        verifier_kwargs = mock_client.resource.call_args.kwargs
+        assert verifier_kwargs["fail_closed"] is False
+
+
+@pytest.mark.asyncio
+async def test_authplane_auth_fail_closed_forwarded():
+    """fail_closed=True is forwarded to client.resource()."""
+    mock_client = MagicMock()
+    _mock_resource = MagicMock()
+    _mock_resource.resource = "https://api.example.com/mcp"
+    mock_client.resource = MagicMock(return_value=_mock_resource)
+
+    with patch("authplane_fastmcp.auth.AuthplaneClient") as mock_client_cls:
+        mock_client_cls.create = AsyncMock(return_value=mock_client)
+        await authplane_auth(
+            issuer="https://auth.example.com",
+            base_url="https://api.example.com",
+            revocation_checker=IntrospectionRevocation(),
+            fail_closed=True,
+        )
+
+        verifier_kwargs = mock_client.resource.call_args.kwargs
+        assert verifier_kwargs["fail_closed"] is True
+
+
 @pytest.mark.asyncio
 async def test_authplane_auth_resource_derivation():
     """Verify resource URL construction from base_url and mcp_path."""

authplane-mcp/authplane_mcp/auth.py

@@ -222,6 +222,7 @@ async def authplane_mcp_auth(
     fetch_settings: FetchSettings | None = None,
     inbound_dpop: InboundDPoPOptions | None = None,
     revocation_checker: IntrospectionRevocation | RevocationChecker | None = None,
+    fail_closed: bool = False,
 ) -> AuthplaneAuthResult:
     """Build the kwargs to enable Authplane auth on a FastMCP server.
 
@@ -323,10 +324,20 @@ async def authplane_mcp_auth(
               ``introspection_endpoint`` (RFC 7662) discovered from AS
               metadata. Raises ``TokenRevokedError`` if ``active=false``.
               Pass ``as_credentials`` for authenticated introspection.
-              Fails open if the endpoint is unavailable.
+              Fails open if the endpoint is unavailable, unless
+              ``fail_closed=True``.
             - async callable: custom checker called with
               ``(VerifiedClaims, raw_token)``; return ``True`` to reject
               the token (raises ``TokenRevokedError``).
+        fail_closed: Policy applied when the configured
+            ``revocation_checker`` itself fails (e.g. the introspection
+            endpoint is unreachable). ``False`` (default) accepts the
+            token — offline signature/claims validation still applies.
+            ``True`` rejects it with ``TokenRevokedError``, trading
+            availability during an AS outage for a hard revocation
+            guarantee. Only consulted when a ``revocation_checker`` is
+            configured; note that once the client's circuit breaker
+            opens, every request is rejected until the cooldown elapses.
 
     Returns:
         ``AuthplaneAuthResult`` with ``token_verifier`` (``AuthplaneTokenVerifier``),
@@ -384,6 +395,7 @@ async def authplane_mcp_auth(
         resource=resource,
         scopes=resolved_scopes,
         revocation_checker=revocation_checker,
+        fail_closed=fail_closed,
         **verifier_kwargs,
     )
 

authplane-mcp/docs/user-guide.md

@@ -85,6 +85,7 @@ All parameters of `authplane_mcp_auth()`:
 | `clock_skew_seconds` | `int` | `30` | Leeway for `exp`/`nbf`/`iat` validation |
 | `dev_mode` | `bool` | `False` | Relaxes SSRF checks for local development |
 | `revocation_checker` | see [below](#token-revocation-checking) | `None` | Token revocation strategy |
+| `fail_closed` | `bool` | `False` | Reject tokens when the revocation check itself fails, instead of accepting them (see [below](#failure-policy-fail-open-vs-fail-closed)) |
 | `fetch_settings` | `FetchSettings` | `None` | Full SSRF / fetch settings applied to both metadata and JWKS fetches (overrides `dev_mode`) |
 | `inbound_dpop` | `InboundDPoPOptions` | `None` | Per-resource inbound DPoP policy (replay store, max proof age, clock skew, accepted proof algorithms, `required`). When set, the resource advertises DPoP support in PRM (RFC 9728 §2). See **Inbound DPoP through the MCP adapter** below for current limitations. |
 
@@ -201,9 +202,35 @@ await authplane_mcp_auth(
 
 - The introspection endpoint is automatically discovered from AS metadata.
 - If the endpoint returns `active=false`, the token is rejected with `TokenRevokedError`.
-- **Fails open**: if the introspection endpoint is unavailable, the token is accepted (offline validation still applies).
+- **Fails open by default**: if the introspection endpoint is unavailable, the token is accepted (offline validation still applies). Pass `fail_closed=True` to reject instead (see [below](#failure-policy-fail-open-vs-fail-closed)).
 - `as_credentials` enables authenticated introspection (recommended for production).
 
+### Failure Policy: Fail-Open vs Fail-Closed
+
+`fail_closed` controls what happens when the revocation check itself fails — the introspection endpoint is unreachable, returns an error, or a custom checker raises:
+
+```python
+await authplane_mcp_auth(
+    issuer="https://auth.company.com",
+    resource="https://mcp.company.com",
+    revocation_checker=IntrospectionRevocation(),
+    as_credentials=ASCredentials(
+        client_id="my_resource_server",
+        client_secret="secret",
+    ),
+    fail_closed=True,
+)
+```
+
+- `False` (default) accepts the token and logs a warning. Signature and claims validation still apply, so this only skips the *revocation* freshness check — it never admits an otherwise-invalid token.
+- `True` rejects the token with `TokenRevokedError`. Choose this for servers exposing mutation-capable or otherwise high-impact tools, where serving a revoked-but-unverifiable token is worse than downtime.
+
+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.
+
 ### Custom Revocation Checker
 
 Implement your own revocation logic with an async callable:
@@ -476,6 +503,7 @@ async def authplane_mcp_auth(
     fetch_settings: FetchSettings | None = None,
     inbound_dpop: InboundDPoPOptions | None = None,
     revocation_checker: IntrospectionRevocation | RevocationChecker | None = None,
+    fail_closed: bool = False,
 ) -> AuthplaneAuthResult
 ```
 

authplane-mcp/tests/test_auth.py

@@ -5,7 +5,7 @@
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
-from authplane import DPoPProvider, FetchSettings, VerifiedClaims
+from authplane import DPoPProvider, FetchSettings, IntrospectionRevocation, VerifiedClaims
 from mcp.server.auth.provider import AccessToken
 from mcp.server.auth.settings import AuthSettings
 
@@ -225,6 +225,42 @@ async def my_checker(claims: VerifiedClaims, raw_token: str) -> bool:
         assert verifier_kwargs["revocation_checker"] is my_checker
 
 
+@pytest.mark.asyncio
+async def test_authplane_mcp_auth_fail_closed_default_is_false():
+    """When fail_closed is not passed, False is forwarded (fail-open behavior)."""
+    mock_client = MagicMock()
+    mock_client.resource = MagicMock(return_value=MagicMock(resource="https://api.example.com"))
+
+    with patch("authplane_mcp.auth.AuthplaneClient") as mock_client_cls:
+        mock_client_cls.create = AsyncMock(return_value=mock_client)
+        await authplane_mcp_auth(
+            issuer="https://auth.example.com",
+            resource="https://api.example.com",
+        )
+
+        verifier_kwargs = mock_client.resource.call_args.kwargs
+        assert verifier_kwargs["fail_closed"] is False
+
+
+@pytest.mark.asyncio
+async def test_authplane_mcp_auth_fail_closed_forwarded():
+    """fail_closed=True is forwarded to client.resource()."""
+    mock_client = MagicMock()
+    mock_client.resource = MagicMock(return_value=MagicMock(resource="https://api.example.com"))
+
+    with patch("authplane_mcp.auth.AuthplaneClient") as mock_client_cls:
+        mock_client_cls.create = AsyncMock(return_value=mock_client)
+        await authplane_mcp_auth(
+            issuer="https://auth.example.com",
+            resource="https://api.example.com",
+            revocation_checker=IntrospectionRevocation(),
+            fail_closed=True,
+        )
+
+        verifier_kwargs = mock_client.resource.call_args.kwargs
+        assert verifier_kwargs["fail_closed"] is True
+
+
 @pytest.mark.asyncio
 async def test_authplane_mcp_auth_as_credentials_passthrough():
     """as_credentials is forwarded to AuthplaneClient.create as auth."""

tests/verifier/test_revocation.py

@@ -161,6 +161,33 @@ async def crashing_checker(claims: Any, raw_token: str) -> bool:
         await c.aclose()
 
 
+async def test_custom_revocation_checker_error_fail_closed_rejects(
+    mock_jwks: Route,
+    token_factory: Any,
+) -> None:
+    """fail_closed=True -> a crashing revocation checker rejects the token."""
+
+    async def crashing_checker(claims: Any, raw_token: str) -> bool:
+        raise RuntimeError("revocation backend unavailable")
+
+    c = await AuthplaneClient.create(
+        issuer=ISSUER,
+        fetch_settings=FetchSettings(ssrf_protection=False),
+    )
+    v = c.resource(
+        resource=RESOURCE,
+        scopes=["read:data"],
+        revocation_checker=crashing_checker,
+        fail_closed=True,
+    )
+    try:
+        token = token_factory()
+        with pytest.raises(TokenRevokedError):
+            await v.verify(token)
+    finally:
+        await c.aclose()
+
+
 # ---------------------------------------------------------------------------
 # Built-in introspection tests
 # ---------------------------------------------------------------------------
@@ -204,6 +231,25 @@ async def test_introspection_http_error_fails_open(
     assert claims.sub == "user123"
 
 
+async def test_introspection_http_error_fail_closed_rejects(
+    client_with_introspection: AuthplaneClient,
+    token_factory: Any,
+) -> None:
+    """fail_closed=True -> introspection endpoint outage (HTTP 500) rejects the token."""
+    v = client_with_introspection.resource(
+        resource=RESOURCE,
+        scopes=["read:data"],
+        revocation_checker=IntrospectionRevocation(),
+        fail_closed=True,
+    )
+    respx.post(INTROSPECTION_URL).mock(
+        return_value=respx.MockResponse(500, json={"error": "server_error"})
+    )
+    token = token_factory()
+    with pytest.raises(TokenRevokedError):
+        await v.verify(token)
+
+
 async def test_introspection_no_endpoint_in_metadata_skips(
     mock_jwks: Route,  # metadata without introspection_endpoint
     token_factory: Any,