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

* 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.

* style: apply ruff 0.16 formatting to Markdown code blocks

ruff 0.16.0 started formatting Python code blocks inside Markdown
files, so CI (which installs the latest ruff satisfying >=0.8) rejects
the previously formatted docs. Blank-line normalization only, no
content changes.

* 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.

* chore: pin ruff to >=0.16,<0.17 in all dev extras

An unpinned ruff means CI silently adopts each new minor's lint and
formatting behavior mid-development (0.16.0 started formatting Markdown
code blocks, which is what forced the docs reformat on this branch).
Pinning to the current minor keeps patch fixes and makes format checks
reproducible; bumping the minor becomes a deliberate change.

* docs: shorten the unreleased changelog entries

* chore(mcp): raise the mcp ceiling to <1.29.0

mcp 1.27.2, the newest release the previous <1.28.0 ceiling allowed,
carries PYSEC-2026-3483; the fix ships in 1.28.1. Adapter tests pass
against 1.28.1.

* fix(mcp): revert mcp ceiling to <1.28.0; document no-checker warning

The <1.29.0 ceiling let mcp 1.28 resolve, but 1.28 renamed the elicitation
field to snake_case elicitation_id, which the adapter's url_elicitation path
does not handle — every consent-driven exchange would raise a pydantic
ValidationError instead of -32042. Keep the ceiling below 1.28 until the
adapter is migrated (README already documents the <1.28.0 range).

Also document the fail_closed-without-revocation_checker warning in the core
user-guide (the direct client.resource() audience); both adapter guides
already cover it.

* ci(security): ignore PYSEC-2026-3483 pending mcp 1.28 adapter migration

The adapter pins mcp <1.28.0 (1.28 renamed elicitationId -> elicitation_id,
breaking url_elicitation.py), so pip-audit resolves the vulnerable mcp 1.27.2.
Suppress the finding with a comment until the adapter is migrated to 1.28.1.

Author: RobertoIskandarani

.github/workflows/security.yml

@@ -74,6 +74,16 @@ jobs:
         # latest released version, so `pip install --upgrade pip` can't pull
         # a patched build. Drop this ignore once pip >= 26.1 is on PyPI.
         # See https://github.com/pypa/pip/pull/13870.
+        #
+        # PYSEC-2026-3483: affects mcp <= 1.27.2 (fixed in 1.28.1). The
+        # authplane-mcp adapter pins mcp <1.28.0 because 1.28 renamed the
+        # elicitation field elicitationId -> elicitation_id (snake_case),
+        # which breaks url_elicitation.py's ElicitRequestURLParams wire
+        # handling (every consent-driven exchange would raise a pydantic
+        # ValidationError). Accepted risk until the adapter is migrated to
+        # the 1.28 field name and the floor is raised to 1.28.1; drop this
+        # ignore then.
         run: >-
           pip-audit --skip-editable --progress-spinner off
           --ignore-vuln CVE-2026-3219
+          --ignore-vuln PYSEC-2026-3483

CHANGELOG.md

@@ -7,6 +7,10 @@ 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(...)`.
+- `AuthplaneClient.resource(...)` logs a warning when `fail_closed=True` is set without a `revocation_checker`.
+
 ## [0.3.0] - 2026-07-21
 
 ### Added

README.md

@@ -20,6 +20,7 @@ from authplane_fastmcp import authplane_auth
 from fastmcp import FastMCP
 from fastmcp.server.auth import require_scopes
 
+
 async def main() -> None:
     result = await authplane_auth(
         issuer="https://auth.company.com",
@@ -37,6 +38,7 @@ async def main() -> None:
     finally:
         await result.aclose()
 
+
 asyncio.run(main())
 ```
 

authplane-fastmcp/README.md

@@ -32,9 +32,7 @@ async def main():
     )
 
     @mcp.tool(auth=require_scopes("tools/query"))
-    async def query_database(
-        query: str, token: AccessToken = CurrentAccessToken()
-    ) -> str:
+    async def query_database(query: str, token: AccessToken = CurrentAccessToken()) -> str:
         user_id = token.claims.get("sub")
         return f"Query: {query}, User: {user_id}"
 

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

@@ -37,6 +37,7 @@ import asyncio
 from fastmcp import FastMCP
 from authplane_fastmcp import authplane_auth
 
+
 async def main() -> None:
     result = await authplane_auth(
         issuer="https://auth.company.com",
@@ -55,6 +56,7 @@ async def main() -> None:
     finally:
         await result.aclose()
 
+
 asyncio.run(main())
 ```
 
@@ -82,6 +84,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. |
 
@@ -98,11 +101,13 @@ Use FastMCP's built-in `require_scopes` decorator to enforce per-tool scope requ
 ```python
 from fastmcp.server.auth import require_scopes
 
+
 @mcp.tool(auth=require_scopes("tools/query"))
 def query(sql: str) -> str:
     """Requires the tools/query scope."""
     return f"Ran: {sql}"  # replace with your real handler
 
+
 @mcp.tool(auth=require_scopes("tools/admin", "tools/delete"))
 def delete_all() -> str:
     """Requires BOTH tools/admin AND tools/delete scopes."""
@@ -119,21 +124,22 @@ FastMCP enforces scopes **before** the handler runs by **filtering tools the cal
 from fastmcp.dependencies import CurrentAccessToken
 from fastmcp.server.auth import AccessToken
 
+
 @mcp.tool()
 async def my_tool(data: str, token: AccessToken = CurrentAccessToken()) -> str:
     # Standard JWT claims
-    sub = token.claims.get("sub")         # Subject (user ID)
-    jti = token.claims.get("jti")         # JWT ID
-    iss = token.claims.get("iss")         # Issuer
-    aud = token.claims.get("aud")         # Audience
-    exp = token.claims.get("exp")         # Expiration (Unix timestamp)
-    nbf = token.claims.get("nbf")         # Not before
-    iat = token.claims.get("iat")         # Issued at
+    sub = token.claims.get("sub")  # Subject (user ID)
+    jti = token.claims.get("jti")  # JWT ID
+    iss = token.claims.get("iss")  # Issuer
+    aud = token.claims.get("aud")  # Audience
+    exp = token.claims.get("exp")  # Expiration (Unix timestamp)
+    nbf = token.claims.get("nbf")  # Not before
+    iat = token.claims.get("iat")  # Issued at
 
     # OAuth claims
-    client_id = token.client_id           # Client ID
-    scopes = token.scopes                 # List of granted scopes
-    expires_at = token.expires_at         # Expiration (Unix timestamp)
+    client_id = token.client_id  # Client ID
+    scopes = token.scopes  # List of granted scopes
+    expires_at = token.expires_at  # Expiration (Unix timestamp)
 
     # Custom claims
     tenant = token.claims.get("tenant_id")
@@ -149,6 +155,7 @@ The `claims` dict contains the **full JWT payload** including all standard and c
 ```python
 from fastmcp.server.dependencies import get_access_token
 
+
 @mcp.tool()
 async def my_tool(data: str) -> str:
     token = get_access_token()  # Returns None if unauthenticated
@@ -210,20 +217,49 @@ 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.
+- **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
 
 Implement your own revocation logic with an async callable:
 
 ```python
 from authplane import VerifiedClaims
 
+
 async def check_blocklist(claims: VerifiedClaims, raw_token: str) -> bool:
     """Return True to reject the token (it is revoked)."""
     return await redis_client.sismember("revoked_tokens", claims.jti)
 
+
 await authplane_auth(
     issuer="https://auth.company.com",
     base_url="https://mcp.company.com",
@@ -253,8 +289,8 @@ result = await authplane_auth(
 downstream = await result.client.exchange(
     TokenExchangeOptions(
         subject_token=inbound_token,
-        scope="tools/add",                           # narrow to the minimum
-        resources=("https://downstream.example",),   # RFC 8707 audience binding
+        scope="tools/add",  # narrow to the minimum
+        resources=("https://downstream.example",),  # RFC 8707 audience binding
     )
 )
 
@@ -287,6 +323,7 @@ from authplane import ConsentRequiredError
 from authplane.oauth import TokenExchangeOptions
 from mcp.shared.exceptions import UrlElicitationRequiredError
 
+
 @mcp.tool(auth=require_scopes("tools/call_downstream"))
 async def call_downstream(payload: str) -> str:
     try:
@@ -379,6 +416,7 @@ When `fetch_settings` is provided, `dev_mode` is ignored for both metadata and J
 ```python
 import asyncio
 
+
 async def main() -> None:
     result = await authplane_auth(...)
     try:
@@ -387,6 +425,7 @@ async def main() -> None:
     finally:
         await result.aclose()
 
+
 asyncio.run(main())
 ```
 
@@ -474,6 +513,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/pyproject.toml

@@ -47,7 +47,7 @@ dev = [
     "respx>=0.21",
     "cryptography>=42",
     "coverage>=7",
-    "ruff>=0.8",
+    "ruff>=0.16,<0.17",
 ]
 
 [tool.pytest.ini_options]

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,
     )