konklav-fastapi 1.5.0__tar.gz

konklav_fastapi-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albin Skott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

konklav_fastapi-1.5.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: konklav-fastapi
+Version: 1.5.0
+Summary: Konklav route policies for FastAPI: declare requirements on routes and routers, decided by the relying core
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Dist: konklav-relying==1.5.0
+Requires-Dist: fastapi>=0.143,<0.163
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/cstruct/konklav/releases
+Project-URL: Documentation, https://github.com/cstruct/konklav/tree/main/items/py-fastapi
+Project-URL: Issues, https://github.com/cstruct/konklav/issues
+Project-URL: Repository, https://github.com/cstruct/konklav
+Description-Content-Type: text/markdown
+
+# konklav-fastapi
+
+[Konklav](https://github.com/cstruct/konklav) route policies for FastAPI.
+
+Declare an operation's requirements as a `RoutePolicy` on routes, routers
+and `include_router`; install `KonklavRoutes` once with your started
+`RelyingClient` from [`konklav-relying`](https://pypi.org/project/konklav-relying/),
+and every request is decided by the relying core with one call.
+
+```python
+from fastapi import APIRouter
+from konklav_fastapi import KonklavRoutes, RoutePolicy, TenantToken
+
+router = APIRouter(dependencies=[RoutePolicy(tenant_actions={"project:read"})])
+
+
+@router.get("/projects/{project}", dependencies=[RoutePolicy(scope_actions={"project": {"document:read"}})])
+async def read_project(project: str, token: TenantToken) -> dict[str, str]:
+    return {"project": project, "subject": token.sub}
+```
+
+Startup validation refuses routes without a policy, policies that can't be
+decided, and token dependencies the policy doesn't match. Each operation's
+merged policy is published in OpenAPI as `x-konklav-policy`.
+
+## Versions
+
+The package has the same version as the Konklav server it was released
+with, and requires `konklav-relying` of that version. It is supported only
+against a server of the same version.

konklav_fastapi-1.5.0/PYPI.md

@@ -0,0 +1,30 @@
+# konklav-fastapi
+
+[Konklav](https://github.com/cstruct/konklav) route policies for FastAPI.
+
+Declare an operation's requirements as a `RoutePolicy` on routes, routers
+and `include_router`; install `KonklavRoutes` once with your started
+`RelyingClient` from [`konklav-relying`](https://pypi.org/project/konklav-relying/),
+and every request is decided by the relying core with one call.
+
+```python
+from fastapi import APIRouter
+from konklav_fastapi import KonklavRoutes, RoutePolicy, TenantToken
+
+router = APIRouter(dependencies=[RoutePolicy(tenant_actions={"project:read"})])
+
+
+@router.get("/projects/{project}", dependencies=[RoutePolicy(scope_actions={"project": {"document:read"}})])
+async def read_project(project: str, token: TenantToken) -> dict[str, str]:
+    return {"project": project, "subject": token.sub}
+```
+
+Startup validation refuses routes without a policy, policies that can't be
+decided, and token dependencies the policy doesn't match. Each operation's
+merged policy is published in OpenAPI as `x-konklav-policy`.
+
+## Versions
+
+The package has the same version as the Konklav server it was released
+with, and requires `konklav-relying` of that version. It is supported only
+against a server of the same version.

konklav_fastapi-1.5.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["uv_build>=0.8.24,<0.9"]
+build-backend = "uv_build"
+
+[project]
+name = "konklav-fastapi"
+# Set by `mise run release:bump`, with the rest of the release, as is the
+# exact requirement on konklav-relying.
+version = "1.5.0"
+description = "Konklav route policies for FastAPI: declare requirements on routes and routers, decided by the relying core"
+readme = "PYPI.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+# The FastAPI range is tested at both ends in CI: this package reads how
+# FastAPI keeps the routes of included routers (see _routing.py).
+dependencies = ["konklav-relying==1.5.0", "fastapi>=0.143,<0.163"]
+classifiers = [
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/cstruct/konklav"
+Documentation = "https://github.com/cstruct/konklav/tree/main/items/py-fastapi"
+Changelog = "https://github.com/cstruct/konklav/releases"
+Issues = "https://github.com/cstruct/konklav/issues"
+
+[dependency-groups]
+dev = [
+    "cryptography>=45",
+    "httpx>=0.28",
+    "konklav-control-plane",
+    "mypy==1.20.2",
+    "pytest>=8",
+]
+
+[tool.uv.sources]
+konklav-relying = { path = "../py" }
+konklav-control-plane = { path = "../py-control-plane" }
+
+[tool.mypy]
+files = ["src"]
+strict = true
+python_version = "3.12"

konklav_fastapi-1.5.0/src/konklav_fastapi/__init__.py

@@ -0,0 +1,91 @@
+"""
+Konklav route policies for FastAPI.
+
+`RoutePolicy` is a `konklav_relying.Policy` you declare as a FastAPI
+dependency on routes, routers and `include_router`. `KonklavRoutes`, which
+an application installs once, holds the started `RelyingClient` and what
+only the application knows: how to find each scope kind's id, the tenant a
+route addresses, and hooks for every verified token.
+
+```python
+from fastapi import APIRouter, FastAPI
+from konklav_fastapi import KonklavRoutes, RoutePolicy, TenantToken
+
+router = APIRouter(dependencies=[RoutePolicy(tenant_actions={"project:read"})])
+
+
+@router.get("/projects/{project}", dependencies=[RoutePolicy(scope_actions={"project": {"document:read"}})])
+async def read_project(project: str, token: TenantToken) -> dict[str, str]:
+    return {"project": project, "subject": token.sub}
+
+
+routes = KonklavRoutes()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    routes.client = RelyingClient(...)
+    await routes.client.start()
+    yield
+    await routes.client.stop()
+
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(router)
+routes.install(app)
+```
+
+Each request makes one decision with the route's merged policy; denials
+raise `KonklavDenied` subclasses (`konklav_fastapi.errors`), answered with
+401, 403 or 503 unless the application handles them itself.
+"""
+
+import importlib.metadata
+
+from konklav_fastapi.errors import (
+    Forbidden,
+    KonklavDenied,
+    KonklavUnavailable,
+    RoutePolicyError,
+    StepUpRequired,
+    Unauthenticated,
+    handle_denied,
+)
+from konklav_fastapi.routes import (
+    CurrentToken,
+    IdentityToken,
+    KonklavRoutes,
+    OptionalToken,
+    ResolvedScope,
+    RoutePolicy,
+    RouteTenantResolver,
+    ScopeResolver,
+    TenantToken,
+    TokenHook,
+)
+
+# r[impl item.py-fastapi.pure-python]
+# r[impl item.py-fastapi.same-version]
+# The release sets the version and the exact requirement on konklav-relying
+# in pyproject.toml; this package is plain Python.
+__version__ = importlib.metadata.version("konklav-fastapi")
+
+__all__ = [
+    "CurrentToken",
+    "Forbidden",
+    "IdentityToken",
+    "KonklavDenied",
+    "KonklavRoutes",
+    "KonklavUnavailable",
+    "OptionalToken",
+    "ResolvedScope",
+    "RoutePolicy",
+    "RoutePolicyError",
+    "RouteTenantResolver",
+    "ScopeResolver",
+    "StepUpRequired",
+    "TenantToken",
+    "TokenHook",
+    "Unauthenticated",
+    "handle_denied",
+]

konklav_fastapi-1.5.0/src/konklav_fastapi/_routing.py

@@ -0,0 +1,132 @@
+"""
+How FastAPI keeps the routes of included routers, read in one place.
+
+Since 0.140, `include_router` no longer copies routes. The application's
+routes hold the included router itself, and FastAPI derives a context per
+inclusion with the combined dependencies:
+
+- an included HTTP route stays the router's own `APIRoute`; the request's
+  `scope["fastapi"]["effective_route_context"]` carries that inclusion's
+  combined dependencies, and `scope["route"]` is the original route;
+- an included websocket route is rebuilt as a new `APIWebSocketRoute` with
+  the combined dependencies, which is the request's `scope["route"]`, and
+  the context's own list stays empty.
+
+`APIRouter.add_api_route` copies the router's own dependencies in front of
+the route's, so a route's own dependencies are what follows them.
+"""
+
+# r[impl item.py-fastapi.fastapi-range]
+# What this module reads is why pyproject.toml bounds the FastAPI versions.
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.dependencies.models import Dependant
+from fastapi.params import Depends
+from fastapi.requests import HTTPConnection
+from fastapi.routing import APIRoute, APIRouter, APIWebSocketRoute, iter_route_contexts
+from starlette.routing import BaseRoute
+
+_SCOPE_KEY = "fastapi"
+_CONTEXT_KEY = "effective_route_context"
+
+
+@dataclass(frozen=True)
+class ServedRoute:
+    """One route as FastAPI serves it, once per inclusion."""
+
+    original: APIRoute | APIWebSocketRoute
+    """The route as its router declared it."""
+    dependencies: Sequence[Depends]
+    """Every layer's, outermost first."""
+    own_dependencies: Sequence[Depends]
+    """The route's own, without its router's."""
+    path_format: str
+    methods: frozenset[str]
+    """Empty for a websocket."""
+    path_parameters: frozenset[str]
+    dependant: Dependant | None
+
+    @property
+    def is_websocket(self) -> bool:
+        return isinstance(self.original, APIWebSocketRoute)
+
+    @property
+    def label(self) -> str:
+        return f"{','.join(sorted(self.methods)) or 'WEBSOCKET'} {self.path_format}"
+
+
+def owners(router: APIRouter) -> dict[int, tuple[BaseRoute, APIRouter]]:
+    """Each API and websocket route by `id`, with the router that declared it."""
+    found: dict[int, tuple[BaseRoute, APIRouter]] = {}
+    for route in router.routes:
+        included = getattr(route, "original_router", None)
+        if isinstance(included, APIRouter):
+            found.update(owners(included))
+        elif isinstance(route, APIRoute | APIWebSocketRoute):
+            found[id(route)] = (route, router)
+    return found
+
+
+def own_dependencies(route: APIRoute | APIWebSocketRoute, router: APIRouter | None) -> Sequence[Depends]:
+    declared = list(route.dependencies)
+    inherited = list(router.dependencies) if router is not None else []
+    if declared[: len(inherited)] == inherited:
+        return declared[len(inherited) :]
+    # The router's dependencies changed after the route was added: nothing
+    # can be told apart, so nothing counts as the route's own.
+    return []
+
+
+def served_routes(app: FastAPI) -> Iterator[ServedRoute]:
+    """Every API and websocket route of `app`, once per inclusion."""
+    owner = owners(app.router)
+    for context in iter_route_contexts(app.routes):
+        original = context.original_route
+        if not isinstance(original, APIRoute | APIWebSocketRoute):
+            continue
+        served: Any = context
+        if isinstance(original, APIWebSocketRoute):
+            # 0.143 forwards to the inclusion's context, later versions to
+            # the rebuilt route.
+            rebuilt = getattr(context, "starlette_route", None)
+            if isinstance(rebuilt, APIWebSocketRoute):
+                served = rebuilt
+        _, router = owner.get(id(original), (original, None))
+        yield ServedRoute(
+            original=original,
+            dependencies=list(served.dependencies),
+            own_dependencies=own_dependencies(original, router),
+            path_format=served.path_format,
+            methods=frozenset(getattr(served, "methods", None) or ()) if isinstance(original, APIRoute) else frozenset(),
+            path_parameters=frozenset(served.param_convertors),
+            dependant=getattr(served, "dependant", None) or original.dependant,
+        )
+
+
+def requested(connection: HTTPConnection) -> tuple[APIRoute | APIWebSocketRoute, Sequence[Depends]] | None:
+    """The original route serving `connection` and its combined dependencies."""
+    scope = connection.scope
+    route = scope.get("route")
+    context: Any = scope.get(_SCOPE_KEY, {}).get(_CONTEXT_KEY)
+    if isinstance(route, APIWebSocketRoute):
+        original = context.original_route if context is not None and context.starlette_route is route else route
+        return (original, route.dependencies) if isinstance(original, APIWebSocketRoute) else None
+    if isinstance(route, APIRoute):
+        if context is not None and context.original_route is route:
+            return route, context.dependencies
+        return route, route.dependencies
+    return None
+
+
+def dependency_calls(dependant: Dependant | None) -> Iterator[Callable[..., Any]]:
+    if dependant is None:
+        return
+    if dependant.call is not None:
+        yield dependant.call
+    for dependency in dependant.dependencies:
+        yield from dependency_calls(dependency)

konklav_fastapi-1.5.0/src/konklav_fastapi/errors.py

@@ -0,0 +1,144 @@
+"""
+What evaluating a route's policy can end in, other than an allow.
+
+Each outcome is an exception, a subclass of `KonklavDenied`.
+`KonklavRoutes.install` registers `handle_denied` for them, which answers
+HTTP requests with the status and a JSON body and closes websockets with
+code 1008. To answer differently, register your own handler for
+`KonklavDenied` (or a subclass) after installing:
+
+```python
+routes.install(app)
+app.add_exception_handler(Forbidden, my_forbidden_handler)
+```
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from fastapi.requests import HTTPConnection
+from fastapi.responses import JSONResponse
+from fastapi.websockets import WebSocket
+from konklav_relying import DenyReason, StepUp
+
+__all__ = [
+    "Forbidden",
+    "KonklavDenied",
+    "KonklavUnavailable",
+    "RoutePolicyError",
+    "StepUpRequired",
+    "Unauthenticated",
+    "handle_denied",
+]
+
+
+class RoutePolicyError(ValueError):
+    """Routes whose policies can't be evaluated, found by startup validation."""
+
+
+# r[impl item.py-fastapi.outcomes]
+class KonklavDenied(Exception):
+    """A request the route's policy doesn't allow."""
+
+    status_code: ClassVar[int] = 403
+    code: str
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+        self.code = code
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {}
+
+    def body(self) -> dict[str, Any]:
+        return {"error": {"code": self.code}}
+
+
+class Unauthenticated(KonklavDenied):
+    """
+    No usable token: `missing_token`, `invalid_token` or
+    `invalid_dpop_proof`, with a `WWW-Authenticate` challenge. A refused
+    token is challenged in the scheme it was presented with (`scheme`, `DPoP`
+    or `Bearer`), a refused proof always with `DPoP`, and a missing token
+    with both.
+    """
+
+    status_code = 401
+
+    def __init__(self, code: str, scheme: str | None = None) -> None:
+        super().__init__(code)
+        self.scheme = scheme
+
+    @property
+    def headers(self) -> dict[str, str]:
+        if self.code == "invalid_dpop_proof":
+            return {"WWW-Authenticate": 'DPoP error="invalid_dpop_proof"'}
+        if self.scheme is None:
+            return {"WWW-Authenticate": "Bearer, DPoP"}
+        return {"WWW-Authenticate": f'{self.scheme} error="{self.code}"'}
+
+
+class Forbidden(KonklavDenied):
+    """
+    A deny: `reason` is the decision's, or `token_tenant` when the route's
+    tenant isn't the token's.
+    """
+
+    status_code = 403
+
+    def __init__(self, reason: DenyReason) -> None:
+        super().__init__(reason.code)
+        self.reason = reason
+
+    def body(self) -> dict[str, Any]:
+        # As Konklav writes deny reasons: a bare code, or the code with its fields.
+        details = dict(self.reason.details)
+        reason: Any = {self.reason.code: details} if details else self.reason.code
+        return {"error": {"code": "forbidden", "reason": reason}}
+
+
+class StepUpRequired(KonklavDenied):
+    """
+    Fresher or stronger authentication would allow the request: `step_up`
+    says what. Challenged in the token's `scheme` with
+    `error="insufficient_user_authentication"` (RFC 9470), and `max_age` when
+    the requirement has one. The methods it needs are `amr` values, which the
+    challenge's `acr_values` can't carry, so they are only in the body.
+    """
+
+    status_code = 401
+
+    def __init__(self, step_up: StepUp, scheme: str = "Bearer") -> None:
+        super().__init__("step_up")
+        self.step_up = step_up
+        self.scheme = scheme
+
+    @property
+    def headers(self) -> dict[str, str]:
+        challenge = f'{self.scheme} error="insufficient_user_authentication"'
+        if self.step_up.max_age_seconds is not None:
+            challenge += f", max_age={self.step_up.max_age_seconds}"
+        return {"WWW-Authenticate": challenge}
+
+    def body(self) -> dict[str, Any]:
+        return {"error": {"code": "step_up", "requirement": self.step_up.to_json()}}
+
+
+class KonklavUnavailable(KonklavDenied):
+    """No decision could be reached, so the request is denied (fails closed)."""
+
+    status_code = 503
+
+    def __init__(self) -> None:
+        super().__init__("konklav_unavailable")
+
+
+async def handle_denied(connection: HTTPConnection, error: Exception) -> JSONResponse | None:
+    """The default handler: a JSON answer, or for a websocket, a close with 1008."""
+    assert isinstance(error, KonklavDenied)
+    if isinstance(connection, WebSocket):
+        await connection.close(code=1008, reason=error.code)
+        return None
+    return JSONResponse(error.body(), status_code=error.status_code, headers=error.headers)

konklav_fastapi-1.5.0/src/konklav_fastapi/routes.py

@@ -0,0 +1,504 @@
+"""
+Route policies on FastAPI routes, evaluated by the relying core.
+
+Declare a `RoutePolicy` on routes, routers or `include_router`, and install
+one `KonklavRoutes` on the application:
+
+```python
+router = APIRouter(dependencies=[RoutePolicy(tenant_actions={"project:read"})])
+
+@router.post("/projects/{project}", dependencies=[RoutePolicy(scope_actions={"project": {"project:write"}})])
+async def update_project(project: str, token: TenantToken) -> ...: ...
+
+routes = KonklavRoutes(scope_resolvers={"project": project_resolver})
+routes.install(app)
+```
+
+Per request, the route's policies merge, outermost first; scope ids come
+from the scope resolvers (or the path parameter of each kind's name); and
+the token is verified once (`accept_request`) and one `decide_accepted_typed`
+call decides.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field, replace
+from functools import cache
+from typing import Annotated, Any, ClassVar, Literal, cast
+
+from fastapi import FastAPI
+from fastapi.params import Depends
+from fastapi.requests import HTTPConnection
+from fastapi.websockets import WebSocket
+from konklav_relying import (
+    AcceptedRequest,
+    AccessToken,
+    DenyReason,
+    InvalidDpopProof,
+    KonklavError,
+    Policy,
+    PolicyError,
+    RelyingClient,
+)
+
+from konklav_fastapi import _routing
+from konklav_fastapi.errors import (
+    Forbidden,
+    KonklavDenied,
+    KonklavUnavailable,
+    RoutePolicyError,
+    StepUpRequired,
+    Unauthenticated,
+    handle_denied,
+)
+
+__all__ = [
+    "CurrentToken",
+    "IdentityToken",
+    "KonklavRoutes",
+    "OptionalToken",
+    "ResolvedScope",
+    "RouteTenantResolver",
+    "RoutePolicy",
+    "ScopeResolver",
+    "TenantToken",
+    "TokenHook",
+]
+
+TOKEN_KINDS = frozenset({"partial", "identity", "tenant", "reset_password", "invite"})
+"""Every token kind Konklav issues."""
+DEFAULT_TOKEN_KINDS = frozenset({"tenant"})
+"""What a policy without `token_kinds` admits, as Konklav decides."""
+
+_SCOPE_KEY = "konklav_fastapi"
+
+
+@dataclass(frozen=True)
+class ResolvedScope:
+    """
+    A scope a resolver found: its `id`, and optionally the scope `kind` the
+    decision uses, when the policy's kind stands for several, and the
+    scope's owner `tenant`, when it is another tenant's (then only shares
+    allow it).
+    """
+
+    id: str
+    kind: str | None = None
+    tenant: str | None = None
+
+
+type ScopeResolver = Callable[[HTTPConnection, AccessToken], Awaitable[str | ResolvedScope]]
+"""Finds the id of one scope kind's scope for a request, given its verified token."""
+
+type RouteTenantResolver = Callable[[HTTPConnection, AccessToken], Awaitable[str | None]]
+"""The tenant a request addresses on its own, such as from its path, or `None`."""
+
+type TokenHook = Callable[[HTTPConnection, AccessToken], Awaitable[None]]
+"""Runs on every verified token, before handlers receive it; refuses it by raising."""
+
+
+@dataclass(frozen=True)
+class _Presented:
+    authorization: str
+    dpop: str | None
+    token: str
+
+    @property
+    def scheme(self) -> str:
+        """The scheme to challenge a refused token in."""
+        return "DPoP" if self.authorization.partition(" ")[0].lower() == "dpop" else "Bearer"
+
+
+@dataclass(frozen=True)
+class _Outcome:
+    public: bool
+    token: AccessToken | None = None
+
+
+# r[impl item.py-fastapi.shared-dependency]
+async def _evaluate(connection: HTTPConnection) -> None:
+    """The one dependency every `RoutePolicy` declares."""
+    if _SCOPE_KEY in connection.scope:
+        return
+    routes = KonklavRoutes.of(connection)
+    connection.scope[_SCOPE_KEY] = await routes._evaluate(connection)
+
+
+# r[impl item.py-fastapi.route-policy]
+@dataclass(frozen=True, kw_only=True)
+class RoutePolicy(Policy, Depends):
+    """
+    A route policy (`konklav_relying.policy.Policy`) to declare as a FastAPI
+    dependency, on a route, a router, `include_router` or the application.
+
+    Restrictive flags are admitted only by the policies declared on the
+    route itself: they intersect when merged, so a router can't admit one
+    for every route under it.
+    """
+
+    # A factory: a function as a plain default would read back as a bound method.
+    dependency: Callable[..., Any] | None = field(default_factory=lambda: _evaluate, init=False, repr=False)
+    use_cache: bool = field(default=True, init=False, repr=False)
+    scope: Literal["function", "request"] | None = field(default=None, init=False, repr=False)
+    __hash__ = Policy.__hash__
+
+
+# r[impl item.py-fastapi.merge-order]
+# r[impl item.py-fastapi.admit-flags-operation]
+@cache
+def _merged(layers: tuple[RoutePolicy, ...], own: tuple[RoutePolicy, ...]) -> Policy:
+    """`layers` merged outermost first, admitting only the flags `own` admits."""
+    merged = Policy.merge(*layers)
+    if merged.is_public:
+        return merged
+    operation = Policy.merge(*own)
+    return replace(merged, admit_flags=None if operation.is_public else operation.admit_flags)
+
+
+def _policies(dependencies: Sequence[Depends]) -> tuple[RoutePolicy, ...]:
+    return tuple(dependency for dependency in dependencies if isinstance(dependency, RoutePolicy))
+
+
+def _method(connection: HTTPConnection) -> str:
+    # A websocket opens with a GET.
+    return "GET" if isinstance(connection, WebSocket) else str(connection.scope["method"])
+
+
+def _url(connection: HTTPConnection) -> str:
+    url = connection.url
+    if url.scheme in ("ws", "wss"):
+        url = url.replace(scheme="https" if url.scheme == "wss" else "http")
+    return str(url)
+
+
+@dataclass(kw_only=True)
+class KonklavRoutes:
+    """
+    What evaluating route policies needs from the application. Install it
+    once with `install`; set `client` to the started `RelyingClient`, such
+    as in the application's lifespan, before serving requests.
+    """
+
+    client: RelyingClient | None = None
+    scope_resolvers: Mapping[str, ScopeResolver] = field(default_factory=dict)
+    """One per scope kind; a kind without one takes the path parameter of its name."""
+    route_tenant: RouteTenantResolver | None = None
+    """When set, a route tenant that isn't the token's `tid` is denied before deciding."""
+    on_verified: Sequence[TokenHook] = ()
+    """Run in order on every verified token."""
+    cookie: Callable[[HTTPConnection], str | None] | None = None
+    """Reads the token from a cookie, for requests without an `Authorization` header."""
+    public_url: Callable[[HTTPConnection], str] | None = None
+    """The URL the client addressed, behind a proxy; DPoP proofs are checked against it."""
+
+    _owners: dict[int, tuple[Any, Any]] = field(default_factory=dict, init=False, repr=False)
+
+    STATE_ATTRIBUTE: ClassVar[str] = "konklav_routes"
+
+    # -- installing -------------------------------------------------------
+
+    def install(self, app: FastAPI) -> None:
+        """
+        Makes `app`'s routes use this configuration, validates them when the
+        application starts, publishes each operation's policy in OpenAPI and
+        handles `KonklavDenied` with `handle_denied`.
+        """
+        setattr(app.state, self.STATE_ATTRIBUTE, self)
+        # Starlette types handlers per connection kind; this one takes both.
+        app.add_exception_handler(KonklavDenied, cast(Any, handle_denied))
+
+        # r[impl item.py-fastapi.validation]
+        lifespan = app.router.lifespan_context
+
+        @asynccontextmanager
+        async def validated(application: Any) -> Any:
+            self.validate(app)
+            async with lifespan(application) as state:
+                yield state
+
+        app.router.lifespan_context = validated
+
+        # r[impl item.py-fastapi.openapi]
+        openapi = app.openapi
+
+        def described() -> dict[str, Any]:
+            if app.openapi_schema:
+                return app.openapi_schema
+            schema = openapi()
+            for served in _routing.served_routes(app):
+                operations = schema.get("paths", {}).get(served.path_format, {})
+                for method in served.methods:
+                    if (operation := operations.get(method.lower())) is not None:
+                        try:
+                            operation["x-konklav-policy"] = self.describe(served)
+                        except PolicyError:
+                            pass
+            return schema
+
+        cast(Any, app).openapi = described
+
+    @classmethod
+    def of(cls, connection: HTTPConnection) -> KonklavRoutes:
+        """The configuration installed on the application serving `connection`."""
+        routes = getattr(connection.app.state, cls.STATE_ATTRIBUTE, None)
+        if not isinstance(routes, KonklavRoutes):
+            raise RuntimeError("route policies need KonklavRoutes(...).install(app)")
+        return routes
+
+    # -- startup validation ---------------------------------------------
+
+    def validate(self, app: FastAPI) -> None:
+        """
+        Checks every API and websocket route's policy.
+
+        Raises:
+            RoutePolicyError: listing every route that fails, and why.
+        """
+        self._owners = _routing.owners(app.router)
+        errors = [
+            f"{served.label}: {problem}"
+            for served in _routing.served_routes(app)
+            if (problem := self._problem(served)) is not None
+        ]
+        if errors:
+            raise RoutePolicyError("Routes without a valid route policy:\n" + "\n".join(errors))
+
+    def _problem(self, served: _routing.ServedRoute) -> str | None:
+        layers = _policies(served.dependencies)
+        own = _policies(served.own_dependencies)
+        if not layers:
+            return "declares no RoutePolicy; declare one, or RoutePolicy.public()"
+        inherited = layers[: len(layers) - len(own)]
+        if any(policy.admit_flags is not None for policy in inherited):
+            return "admit_flags set outside the route; only the route's own RoutePolicy can admit flags"
+        try:
+            policy = _merged(layers, own)
+        except PolicyError as error:
+            return str(error)
+        injected = [_INJECTED[call] for call in _routing.dependency_calls(served.dependant) if call in _INJECTED]
+        if policy.is_public:
+            for name, _ in injected:
+                if name != "OptionalToken":
+                    return f"injects {name}, but its policy is public; use OptionalToken"
+            return None
+        if policy.token_kinds == frozenset():
+            return "merged policies admit no token kind"
+        if policy.step_up is not None and policy.step_up.allowed_methods == frozenset():
+            return "merged policies allow no step-up method"
+        for kind in sorted(policy.scope_kinds):
+            if kind not in self.scope_resolvers and kind not in served.path_parameters:
+                return f"needs a `{kind}` scope: configure a scope resolver or add a `{kind}` path parameter"
+        admitted = policy.token_kinds if policy.token_kinds is not None else DEFAULT_TOKEN_KINDS
+        for name, accepted in injected:
+            if not admitted <= accepted:
+                return (
+                    f"injects {name}, which takes {', '.join(sorted(accepted))} tokens, "
+                    f"but its policy admits {', '.join(sorted(admitted))}"
+                )
+        return None
+
+    # -- OpenAPI ------------------------------------------------------------
+
+    def describe(self, served: _routing.ServedRoute) -> dict[str, Any]:
+        """The route's merged policy as published in `x-konklav-policy`."""
+        policy = _merged(_policies(served.dependencies), _policies(served.own_dependencies))
+        if policy.is_public:
+            return {"public": True}
+        requirements: dict[str, Any] = dict(policy.requirements({kind: "" for kind in policy.scope_kinds}))
+        if "scopes" in requirements:
+            requirements["scopes"] = [
+                {"kind": scope["kind"], "actions": scope["actions"]} for scope in requirements["scopes"]
+            ]
+        return {"public": False, **requirements}
+
+    # -- evaluation -------------------------------------------------------
+
+    def _policy(self, connection: HTTPConnection) -> Policy:
+        found = _routing.requested(connection)
+        if found is None:
+            raise RoutePolicyError("route policies only apply to API and websocket routes")
+        route, dependencies = found
+        layers = _policies(dependencies)
+        if not layers:
+            raise RoutePolicyError(f"{connection.url.path} declares no RoutePolicy")
+        if id(route) not in self._owners:
+            # Added after startup validation, or never validated.
+            self._owners = _routing.owners(connection.app.router)
+        _, router = self._owners.get(id(route), (route, None))
+        own = _routing.own_dependencies(route, router) if router is not None else []
+        return _merged(layers, _policies(own))
+
+    # r[impl item.py-fastapi.token-extraction]
+    def _presented(self, connection: HTTPConnection) -> _Presented | None:
+        dpop = connection.headers.get("dpop")
+        if authorization := connection.headers.get("authorization"):
+            return _Presented(authorization, dpop, authorization.partition(" ")[2].strip())
+        token = self.cookie(connection) if self.cookie is not None else None
+        if not token and isinstance(connection, WebSocket):
+            token = connection.query_params.get("token")
+        if not token:
+            return None
+        return _Presented(f"{'DPoP' if dpop else 'Bearer'} {token}", dpop, token)
+
+    def _url(self, connection: HTTPConnection) -> str:
+        return self.public_url(connection) if self.public_url is not None else _url(connection)
+
+    def _client(self) -> RelyingClient:
+        if self.client is None:
+            # Not started yet: fail closed.
+            raise KonklavUnavailable()
+        return self.client
+
+    async def _evaluate(self, connection: HTTPConnection) -> _Outcome:
+        policy = self._policy(connection)
+        # r[impl item.py-fastapi.public]
+        if policy.is_public:
+            return _Outcome(public=True)
+        presented = self._presented(connection)
+        if presented is None:
+            raise Unauthenticated("missing_token")
+        # r[impl item.py-fastapi.verify-then-decide]
+        accepted = await self._accept(connection, presented)
+        token = accepted.token
+        await self._verified(connection, token)
+
+        # r[impl item.py-fastapi.token-tenant]
+        # r[depends item.py.policy.token-tenant]
+        if self.route_tenant is not None:
+            tenant = await self.route_tenant(connection, token)
+            if tenant is not None and tenant != token.tid:
+                raise Forbidden(DenyReason(code="token_tenant"))
+
+        # r[impl item.py-fastapi.scope-resolvers]
+        ids: dict[str, str] = {}
+        owners: dict[str, str] = {}
+        kinds: dict[str, str] = {}
+        for kind in sorted(policy.scope_kinds):
+            resolver = self.scope_resolvers.get(kind)
+            if resolver is None:
+                ids[kind] = str(connection.path_params[kind])
+                continue
+            resolved = await resolver(connection, token)
+            if isinstance(resolved, str):
+                resolved = ResolvedScope(resolved)
+            ids[kind] = resolved.id
+            if resolved.tenant is not None:
+                owners[kind] = resolved.tenant
+            if resolved.kind is not None:
+                kinds[kind] = resolved.kind
+        requirements = policy.requirements(ids, scope_tenants=owners)
+        for scope in requirements.get("scopes", ()):
+            scope["kind"] = kinds.get(scope["kind"], scope["kind"])
+
+        # r[impl item.py-fastapi.single-decision]
+        try:
+            decision = await self._client().decide_accepted_typed(accepted, requirements)
+        except KonklavError:
+            raise KonklavUnavailable() from None
+        match decision.decision:
+            case "allow":
+                return _Outcome(public=False, token=token)
+            case "step_up":
+                assert decision.step_up is not None
+                raise StepUpRequired(decision.step_up, presented.scheme)
+            case _:
+                assert decision.reason is not None
+                if decision.reason.code in ("invalid_token", "invalid_dpop_proof"):
+                    raise Unauthenticated(decision.reason.code, presented.scheme)
+                raise Forbidden(decision.reason)
+
+    async def _accept(self, connection: HTTPConnection, presented: _Presented) -> AcceptedRequest:
+        """The presented token, its session and its DPoP proof, verified once."""
+        try:
+            accepted = await self._client().accept_request(
+                authorization=presented.authorization,
+                dpop=presented.dpop,
+                method=_method(connection),
+                url=self._url(connection),
+            )
+        except InvalidDpopProof:
+            raise Unauthenticated("invalid_dpop_proof") from None
+        except KonklavError:
+            raise KonklavUnavailable() from None
+        if accepted is None:
+            raise Unauthenticated("invalid_token", presented.scheme)
+        return accepted
+
+    # r[impl item.py-fastapi.hooks]
+    async def _verified(self, connection: HTTPConnection, token: AccessToken) -> None:
+        for hook in self.on_verified:
+            await hook(connection, token)
+
+    async def _verify(self, connection: HTTPConnection) -> AccessToken | None:
+        """For public routes, which make no decision: a presented token, verified."""
+        presented = self._presented(connection)
+        if presented is None:
+            return None
+        try:
+            token = await self._client().verify_request_typed(
+                authorization=presented.authorization,
+                dpop=presented.dpop,
+                method=_method(connection),
+                url=self._url(connection),
+            )
+        except InvalidDpopProof:
+            raise Unauthenticated("invalid_dpop_proof") from None
+        except KonklavError:
+            raise KonklavUnavailable() from None
+        if token is None:
+            raise Unauthenticated("invalid_token", presented.scheme)
+        await self._verified(connection, token)
+        return token
+
+
+# -- injected tokens ----------------------------------------------------------
+
+_Evaluated = Annotated[None, Depends(_evaluate)]
+
+
+# r[impl item.py-fastapi.injected-tokens]
+async def _optional_token(connection: HTTPConnection, _: _Evaluated) -> AccessToken | None:
+    outcome: _Outcome = connection.scope[_SCOPE_KEY]
+    if outcome.public:
+        outcome = _Outcome(public=True, token=await KonklavRoutes.of(connection)._verify(connection))
+        connection.scope[_SCOPE_KEY] = replace(outcome, public=False)
+    return outcome.token
+
+
+async def _current_token(token: Annotated[AccessToken | None, Depends(_optional_token)]) -> AccessToken:
+    if token is None:
+        raise Unauthenticated("missing_token")
+    return token
+
+
+def _of_kind(kind: str) -> Callable[..., Awaitable[AccessToken]]:
+    async def token_of_kind(token: Annotated[AccessToken, Depends(_current_token)]) -> AccessToken:
+        if token.knd != kind:
+            raise Forbidden(DenyReason(code="token_kind"))
+        return token
+
+    token_of_kind.__name__ = f"_{kind}_token"
+    return token_of_kind
+
+
+_identity_token = _of_kind("identity")
+_tenant_token = _of_kind("tenant")
+
+CurrentToken = Annotated[AccessToken, Depends(_current_token)]
+"""The request's verified token, of any kind the route's policy admits."""
+OptionalToken = Annotated[AccessToken | None, Depends(_optional_token)]
+"""The request's verified token, or `None` on a public route without one."""
+IdentityToken = Annotated[AccessToken, Depends(_identity_token)]
+"""The request's verified `identity` token."""
+TenantToken = Annotated[AccessToken, Depends(_tenant_token)]
+"""The request's verified `tenant` token."""
+
+# r[impl item.py-fastapi.injected-kinds]
+_INJECTED: dict[Callable[..., Any], tuple[str, frozenset[str]]] = {
+    _optional_token: ("OptionalToken", TOKEN_KINDS),
+    _current_token: ("CurrentToken", TOKEN_KINDS),
+    _identity_token: ("IdentityToken", frozenset({"identity"})),
+    _tenant_token: ("TenantToken", frozenset({"tenant"})),
+}