sahra-shared 0.2.2__py3-none-any.whl

sahra_shared/auth/__init__.py

@@ -0,0 +1,53 @@
+from sahra_shared.auth.capabilities import (
+    FOREIGN_VOCABULARY,
+    ROLE_CAPABILITIES,
+    Capability,
+    RoleName,
+    capabilities_for_roles,
+)
+from sahra_shared.auth.claims import TokenClaims
+from sahra_shared.auth.coverage import (
+    RouteDeclaration,
+    UndeclaredRouteError,
+    assert_capability_coverage,
+    describe_routes,
+    enforce_capability_coverage,
+)
+from sahra_shared.auth.dependencies import (
+    ForeignVocabularyError,
+    make_auth_dependency,
+    require_role,
+)
+from sahra_shared.auth.guards import (
+    CapabilityGuards,
+    CapabilityRequirement,
+    declared_capabilities,
+    internal_endpoint,
+    internal_reason,
+    public_endpoint,
+    public_reason,
+)
+
+__all__ = [
+    "FOREIGN_VOCABULARY",
+    "ROLE_CAPABILITIES",
+    "Capability",
+    "CapabilityGuards",
+    "CapabilityRequirement",
+    "ForeignVocabularyError",
+    "RoleName",
+    "RouteDeclaration",
+    "TokenClaims",
+    "UndeclaredRouteError",
+    "assert_capability_coverage",
+    "capabilities_for_roles",
+    "declared_capabilities",
+    "describe_routes",
+    "enforce_capability_coverage",
+    "internal_endpoint",
+    "internal_reason",
+    "make_auth_dependency",
+    "public_endpoint",
+    "public_reason",
+    "require_role",
+]

sahra_shared/auth/capabilities.py

@@ -0,0 +1,299 @@
+"""Closed capability vocabulary for Sahra Trans authorization.
+
+Why capabilities and not roles
+------------------------------
+Authorization used to be expressed by string-matching whatever the caller
+believed the token's ``roles`` claim contained. That produced a platform-wide
+defect: guards were written as ``require_role(url, "CARRIER_MANAGER",
+"PLATFORM_ADMIN")`` — those are ``UserType`` values, while the JWT's ``roles``
+claim is populated from ``user_roles.role_type`` (``RoleType`` values). The two
+vocabularies never intersect, so every such guard evaluated to ``False`` and
+returned 403 to everybody, forever, silently.
+
+The fix is not "use the right strings". The fix is to stop letting a guard name
+a value from another bounded context at all. Routes declare **capabilities**;
+capabilities are granted to **role names**; the role names are the only place
+the identity domain's vocabulary is referenced, and that place is a single
+audited table in this module.
+
+Why ``StrEnum`` and not ``Literal`` or a frozen set
+--------------------------------------------------
+The brief's requirement is that an unknown capability is a **Pyright error**,
+not a runtime 403. All three candidates satisfy that requirement, so the tie is
+broken on the other requirements:
+
+* ``Literal["fleet:vehicle.read", ...]`` — strongest string checking, but the
+  closed set exists only in the type system. The route-coverage test, the
+  ``/authz/capabilities`` introspection endpoint and the OpenAPI description
+  generator all need to *enumerate* the vocabulary at runtime, which a
+  ``Literal`` alias cannot do without a hand-maintained duplicate list. Two
+  lists that must agree is exactly the failure mode we are removing.
+* ``frozenset[str]`` — enumerable, but a typo is a runtime membership miss, not
+  a type error. That is the defect we are fixing, reintroduced.
+* ``StrEnum`` — enumerable at runtime (``list(Capability)``), and a typo is
+  caught **twice**: ``Capability.FLEET_VEHICLE_RAED`` is a Pyright
+  ``reportAttributeAccessIssue`` *and* an ``AttributeError`` at import time,
+  so a mistyped guard crashes the service at startup rather than 403-ing at
+  request time. Passing a foreign vocabulary value —
+  ``requires("CARRIER_MANAGER")`` or ``requires(RoleType.SUPER_ADMIN)`` — is a
+  Pyright ``reportArgumentType`` error, because ``str`` and a *different* enum
+  are both unassignable to ``Capability``.
+
+``StrEnum`` therefore wins: it is the only option that makes the vocabulary
+both machine-enumerable and typo-fatal-at-import.
+
+Extending the vocabulary
+------------------------
+This set is deliberately closed. Adding a member is a reviewed change to this
+file: it is the platform's authorization contract, not a per-service detail.
+Do not invent capability strings at a call site — there is nowhere to put one.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+
+class Capability(StrEnum):
+    """The complete, closed set of things a principal may be permitted to do.
+
+    Wire format is ``domain:object.action``. The value is what appears in logs
+    and in OpenAPI descriptions; the member name is what code references.
+
+    Two capabilities are special and are called out explicitly rather than
+    being inferred from a role name:
+
+    * :attr:`PLATFORM_TENANT_BYPASS` — the *only* thing that lets a request read
+      or write outside its own organization. Tenant scoping keys off this and
+      nothing else.
+    * :attr:`PLATFORM_ADMINISTER` — platform back-office access. Held alongside
+      the bypass by platform staff, but separate so that a future
+      read-only-auditor role can bypass tenancy without gaining write access.
+    """
+
+    # ── Platform / cross-tenant ──────────────────────────────────────────────
+    PLATFORM_TENANT_BYPASS = "platform:tenant.bypass"
+    PLATFORM_ADMINISTER = "platform:administer"
+    PLATFORM_ORG_APPROVE = "platform:org.approve"
+    PLATFORM_ORG_SUSPEND = "platform:org.suspend"
+    PLATFORM_REFERENCE_DATA_WRITE = "platform:reference_data.write"
+    PLATFORM_CARRIER_APPLICATION_REVIEW = "platform:carrier_application.review"
+
+    # ── Own organization ─────────────────────────────────────────────────────
+    ORG_READ = "org:profile.read"
+    ORG_UPDATE = "org:profile.update"
+    ORG_BRANCH_READ = "org:branch.read"
+    ORG_BRANCH_WRITE = "org:branch.write"
+
+    # ── Users within the organization ────────────────────────────────────────
+    ORG_USER_READ = "org:user.read"
+    ORG_USER_INVITE = "org:user.invite"
+    ORG_USER_UPDATE = "org:user.update"
+    ORG_USER_SUSPEND = "org:user.suspend"
+    ORG_ROLE_ASSIGN = "org:role.assign"
+
+    # ── Fleet (master data) ──────────────────────────────────────────────────
+    FLEET_VEHICLE_READ = "fleet:vehicle.read"
+    FLEET_VEHICLE_WRITE = "fleet:vehicle.write"
+    FLEET_DRIVER_READ = "fleet:driver.read"
+    FLEET_DRIVER_WRITE = "fleet:driver.write"
+
+    # ── Compliance & commercial (master data) ────────────────────────────────
+    COMPLIANCE_PROFILE_READ = "compliance:profile.read"
+    COMPLIANCE_PROFILE_WRITE = "compliance:profile.write"
+    SUBSCRIPTION_READ = "subscription:plan.read"
+    SUBSCRIPTION_MANAGE = "subscription:plan.manage"
+    CONSIGNEE_READ = "consignee:record.read"
+    CONSIGNEE_WRITE = "consignee:record.write"
+    WAREHOUSE_READ = "warehouse:site.read"
+    WAREHOUSE_WRITE = "warehouse:site.write"
+
+    # ── Marketplace & operations ─────────────────────────────────────────────
+    BOOKING_READ = "booking:record.read"
+    BOOKING_CREATE = "booking:record.create"
+    BOOKING_CANCEL = "booking:record.cancel"
+    SHIPMENT_READ = "shipment:record.read"
+    SHIPMENT_STATUS_UPDATE = "shipment:record.status_update"
+
+    # ── Finance ──────────────────────────────────────────────────────────────
+    FINANCE_INVOICE_READ = "finance:invoice.read"
+    FINANCE_PAYMENT_MANAGE = "finance:payment.manage"
+
+    # ── Self-service (every authenticated principal) ─────────────────────────
+    SELF_PROFILE_READ = "self:profile.read"
+    SELF_PROFILE_UPDATE = "self:profile.update"
+
+
+class RoleName(StrEnum):
+    """The identity domain's ``RoleType`` values, mirrored deliberately.
+
+    This is the **single** place in the shared kernel that names a value from
+    the identity bounded context. It mirrors
+    ``identity-svc/app/schemas/enums.py::RoleType`` exactly, because that enum's
+    ``.value`` is what ``identity-svc`` puts in the JWT ``roles`` claim
+    (``app/services/auth_service.py``: ``roles = [r.role_type.value for r in
+    roles_objs]``).
+
+    It is mirrored rather than imported because the shared kernel must not
+    depend on any service (rule: no cross-service imports). The mirror is
+    guarded by a test that fails if the two drift.
+
+    Note the trap this replaces: ``UserType`` (``SHIPPER_USER``,
+    ``CARRIER_MANAGER``, ``CARRIER_DRIVER``, ``CONSIGNEE``, ``PLATFORM_ADMIN``)
+    is a *different* enum and never reaches the ``roles`` claim. No member of it
+    appears below, and none ever should.
+    """
+
+    ORG_OWNER = "ORG_OWNER"
+    OPERATIONS_MANAGER = "OPERATIONS_MANAGER"
+    BOOKING_AGENT = "BOOKING_AGENT"
+    FLEET_MANAGER = "FLEET_MANAGER"
+    DISPATCHER = "DISPATCHER"
+    FINANCE_USER = "FINANCE_USER"
+    VIEWER = "VIEWER"
+    DRIVER = "DRIVER"
+    BUSINESS_ADMIN = "BUSINESS_ADMIN"
+    SUPER_ADMIN = "SUPER_ADMIN"
+
+
+# Values that are NOT role names and must never be accepted as one. These are
+# `UserType` members plus the lowercase legacy spellings that were used in the
+# broken helpers. `require_role` rejects them loudly instead of returning a
+# permanent 403 (see `sahra_shared.auth.dependencies`).
+FOREIGN_VOCABULARY: Final[frozenset[str]] = frozenset(
+    {
+        # identity-svc UserType — the source of the always-False guard defect.
+        "SHIPPER_USER",
+        "CARRIER_MANAGER",
+        "CARRIER_DRIVER",
+        "CONSIGNEE",
+        "PLATFORM_ADMIN",
+        # Lowercase legacy spellings that no mint path ever produces.
+        "platform_admin",
+        "shipper_user",
+        "carrier_manager",
+        "carrier_driver",
+        "consignee",
+    }
+)
+
+
+_SELF_SERVICE: Final[frozenset[Capability]] = frozenset(
+    {
+        Capability.SELF_PROFILE_READ,
+        Capability.SELF_PROFILE_UPDATE,
+        Capability.ORG_READ,
+    }
+)
+
+_VIEWER: Final[frozenset[Capability]] = _SELF_SERVICE | {
+    Capability.ORG_BRANCH_READ,
+    Capability.ORG_USER_READ,
+    Capability.FLEET_VEHICLE_READ,
+    Capability.FLEET_DRIVER_READ,
+    Capability.COMPLIANCE_PROFILE_READ,
+    Capability.SUBSCRIPTION_READ,
+    Capability.CONSIGNEE_READ,
+    Capability.WAREHOUSE_READ,
+    Capability.BOOKING_READ,
+    Capability.SHIPMENT_READ,
+}
+
+_OPERATIONS: Final[frozenset[Capability]] = _VIEWER | {
+    Capability.CONSIGNEE_WRITE,
+    Capability.WAREHOUSE_WRITE,
+    Capability.BOOKING_CREATE,
+    Capability.BOOKING_CANCEL,
+    Capability.SHIPMENT_STATUS_UPDATE,
+}
+
+_FLEET: Final[frozenset[Capability]] = _VIEWER | {
+    Capability.FLEET_VEHICLE_WRITE,
+    Capability.FLEET_DRIVER_WRITE,
+    Capability.COMPLIANCE_PROFILE_WRITE,
+}
+
+_ORG_OWNER: Final[frozenset[Capability]] = (
+    _OPERATIONS
+    | _FLEET
+    | {
+        Capability.ORG_UPDATE,
+        Capability.ORG_BRANCH_WRITE,
+        Capability.ORG_USER_INVITE,
+        Capability.ORG_USER_UPDATE,
+        Capability.ORG_USER_SUSPEND,
+        Capability.ORG_ROLE_ASSIGN,
+        Capability.SUBSCRIPTION_MANAGE,
+        Capability.FINANCE_INVOICE_READ,
+        Capability.FINANCE_PAYMENT_MANAGE,
+    }
+)
+
+# Platform staff. `PLATFORM_TENANT_BYPASS` is granted here and NOWHERE else —
+# it is the single switch that permits cross-organization access, so it is
+# trivial to audit by grepping this file.
+_SUPER_ADMIN: Final[frozenset[Capability]] = frozenset(Capability)
+
+_BUSINESS_ADMIN: Final[frozenset[Capability]] = _ORG_OWNER | {
+    Capability.PLATFORM_ADMINISTER,
+    Capability.PLATFORM_ORG_APPROVE,
+    Capability.PLATFORM_ORG_SUSPEND,
+    Capability.PLATFORM_REFERENCE_DATA_WRITE,
+    Capability.PLATFORM_CARRIER_APPLICATION_REVIEW,
+    Capability.PLATFORM_TENANT_BYPASS,
+}
+
+ROLE_CAPABILITIES: Final[dict[RoleName, frozenset[Capability]]] = {
+    RoleName.SUPER_ADMIN: _SUPER_ADMIN,
+    RoleName.BUSINESS_ADMIN: _BUSINESS_ADMIN,
+    RoleName.ORG_OWNER: _ORG_OWNER,
+    RoleName.OPERATIONS_MANAGER: _OPERATIONS,
+    RoleName.FLEET_MANAGER: _FLEET,
+    RoleName.BOOKING_AGENT: _VIEWER
+    | {
+        Capability.BOOKING_CREATE,
+        Capability.BOOKING_CANCEL,
+        Capability.CONSIGNEE_WRITE,
+    },
+    RoleName.DISPATCHER: _VIEWER | {Capability.SHIPMENT_STATUS_UPDATE},
+    RoleName.FINANCE_USER: _VIEWER
+    | {
+        Capability.FINANCE_INVOICE_READ,
+        Capability.FINANCE_PAYMENT_MANAGE,
+        Capability.SUBSCRIPTION_READ,
+    },
+    RoleName.VIEWER: _VIEWER,
+    RoleName.DRIVER: _SELF_SERVICE
+    | {
+        Capability.SHIPMENT_READ,
+        Capability.SHIPMENT_STATUS_UPDATE,
+    },
+}
+
+
+def capabilities_for_roles(roles: object) -> frozenset[Capability]:
+    """Resolve a JWT ``roles`` claim to the capabilities it grants.
+
+    Unknown role strings are **ignored, not rejected**: a token minted by a
+    newer ``identity-svc`` that has grown an eleventh role must not 500 an older
+    service. Ignoring is safe because it can only ever *reduce* the granted set
+    — the failure mode is a 403, which is the correct direction to fail.
+
+    ``roles`` is typed ``object`` because it arrives from a decoded JWT and is
+    only as trustworthy as the signature; anything that is not a list of
+    strings resolves to no capabilities at all.
+    """
+    if not isinstance(roles, list):
+        return frozenset()
+
+    granted: set[Capability] = set()
+    for raw in roles:  # pyright: ignore[reportUnknownVariableType]
+        if not isinstance(raw, str):
+            continue
+        try:
+            role = RoleName(raw)
+        except ValueError:
+            continue
+        granted |= ROLE_CAPABILITIES.get(role, frozenset())
+    return frozenset(granted)

sahra_shared/auth/claims.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Final
+
+from pydantic import BaseModel
+
+from sahra_shared.auth.capabilities import Capability, capabilities_for_roles
+
+# Legacy spelling kept ONLY so the pre-existing contract test in
+# `tests/test_auth.py` (which asserts `roles=["driver", "platform_admin"]` is a
+# platform admin) keeps passing unchanged. It is unreachable from any real mint
+# path: `identity-svc/app/services/auth_service.py` populates `roles` from
+# `RoleType.value`, which is always UPPERCASE, and `platform_admin` is a
+# lowercased `UserType` value that no signer ever emits. Scheduled for removal
+# once that test is rewritten against `RoleName.SUPER_ADMIN` by the repo owner.
+_LEGACY_PLATFORM_ADMIN_ALIASES: Final[frozenset[str]] = frozenset({"platform_admin"})
+
+# `org_type` reaches the token lowercased — `identity-svc` does
+# `org.org_type.value.lower()` at `app/services/auth_service.py` and
+# `app/api/internal.py`. The comparisons below are casefolded anyway so that a
+# future signer emitting the raw `OrgType` value ("CARRIER") does not silently
+# turn every carrier check into False.
+_CARRIER_ORG_TYPES: Final[frozenset[str]] = frozenset({"carrier", "dual"})
+_SHIPPER_ORG_TYPES: Final[frozenset[str]] = frozenset({"shipper", "dual"})
+
+
+class TokenClaims(BaseModel):
+    sub: str
+    org_id: str
+    org_type: str
+    roles: list[str]
+    branch_id: str | None
+    session_id: str
+    jti: str
+    exp: int
+    iat: int
+
+    @cached_property
+    def capabilities(self) -> frozenset[Capability]:
+        """Capabilities granted by this token's roles.
+
+        This is the only sanctioned way to ask what a principal may do. It is
+        derived, never carried on the wire, so widening a role's grants does not
+        require reissuing outstanding tokens.
+        """
+        return capabilities_for_roles(self.roles)
+
+    def has_capability(self, capability: Capability) -> bool:
+        """True if this principal holds ``capability``.
+
+        The parameter is typed ``Capability``, so ``has_capability("org:read")``
+        and ``has_capability(RoleType.SUPER_ADMIN)`` are both Pyright errors.
+        """
+        return capability in self.capabilities
+
+    def has_role(self, role: str) -> bool:
+        """Raw membership test against the ``roles`` claim.
+
+        Prefer :meth:`has_capability`. This remains only for callers that must
+        inspect the identity domain's vocabulary directly.
+        """
+        return role in self.roles
+
+    def is_platform_admin(self) -> bool:
+        """True for platform staff, i.e. principals permitted to leave their tenant.
+
+        Previously this was ``has_role("platform_admin")``, which was always
+        False: ``platform_admin`` is a lowercased ``UserType`` value, while the
+        ``roles`` claim carries ``RoleType`` values (the seeded platform admin
+        carries ``["SUPER_ADMIN"]``). Every caller of this helper —
+        ``master-data-svc``'s ``_assert_org_scope`` and all six guards in
+        ``operator-svc/app/api/carrier_applications.py`` — was therefore dead.
+        """
+        if Capability.PLATFORM_TENANT_BYPASS in self.capabilities:
+            return True
+        return any(alias in self.roles for alias in _LEGACY_PLATFORM_ADMIN_ALIASES)
+
+    def is_carrier(self) -> bool:
+        """True if the principal's organization operates as a carrier.
+
+        Casefolded, and ``DUAL`` organizations count as both carrier and
+        shipper — ``OrgType`` has four members (``SHIPPER``, ``CARRIER``,
+        ``DUAL``, ``PLATFORM``) and a ``DUAL`` org previously matched neither.
+        """
+        return self.org_type.casefold() in _CARRIER_ORG_TYPES
+
+    def is_shipper(self) -> bool:
+        """True if the principal's organization operates as a shipper (see :meth:`is_carrier`)."""
+        return self.org_type.casefold() in _SHIPPER_ORG_TYPES

sahra_shared/auth/coverage.py

@@ -0,0 +1,248 @@
+"""Route-coverage enforcement: fail on any route that declares no authorization.
+
+The premise is that authorization you can forget is authorization you will
+forget. FastAPI's default for a route with no security dependency is *open*, so
+the omission is invisible: nothing 500s, nothing logs, the endpoint simply
+serves everyone. This module inverts that default by making the omission a
+**test failure** (and optionally a **startup failure**).
+
+Usage in a service's test suite — one line::
+
+    from sahra_shared.auth import assert_capability_coverage
+    from app.main import app
+
+    def test_every_route_declares_authorization() -> None:
+        assert_capability_coverage(app)
+
+Walking the routes
+------------------
+FastAPI 0.140+ no longer flattens ``include_router()`` into ``app.routes``: an
+included router appears as a single lazy ``_IncludedRouter`` object and its
+routes are materialised on demand. Iterating ``app.routes`` and filtering for
+``APIRoute`` therefore finds **nothing** in any real service, which would make
+this helper pass vacuously — the worst possible failure for a test whose entire
+job is to catch omissions.
+
+We use ``fastapi.routing.iter_route_contexts``, the same public helper FastAPI's
+own OpenAPI generator uses, and fall back to a flat walk on older versions. A
+test asserts that a router-included route really is discovered, so a future
+FastAPI change cannot quietly re-open the hole.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.routing import APIRoute, APIWebSocketRoute
+
+from sahra_shared.auth.capabilities import Capability
+from sahra_shared.auth.guards import declared_capabilities, internal_reason, public_reason
+
+try:  # FastAPI >= 0.140
+    from fastapi.routing import iter_route_contexts as _iter_route_contexts
+except ImportError:  # pragma: no cover  # older FastAPI keeps a flat route list
+    _iter_route_contexts = None
+
+#: Paths FastAPI itself mounts. They are documentation surfaces, not application
+#: routes, and a service cannot attach dependencies to them without replacing
+#: them wholesale. Everything else that is not an ``APIRoute`` is reported.
+FRAMEWORK_PATHS: frozenset[str] = frozenset(
+    {
+        "/openapi.json",
+        "/docs",
+        "/docs/oauth2-redirect",
+        "/redoc",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RouteDeclaration:
+    """What one route declares about its own authorization."""
+
+    methods: tuple[str, ...]
+    path: str
+    name: str
+    capabilities: frozenset[Capability]
+    public_reason: str | None
+    kind: str = "APIRoute"
+    internal_reason: str | None = None
+
+    @property
+    def is_declared(self) -> bool:
+        return bool(self.capabilities) or self.public_reason is not None or self.internal_reason is not None
+
+    def __str__(self) -> str:
+        methods = ",".join(self.methods) or "WS"
+        return f"{methods} {self.path} (endpoint={self.name}, {self.kind})"
+
+
+class UndeclaredRouteError(AssertionError):
+    """Raised when at least one route declares no authorization.
+
+    Subclasses ``AssertionError`` so it reads naturally as a test failure while
+    still being catchable by type at startup.
+    """
+
+    def __init__(self, undeclared: Sequence[RouteDeclaration]) -> None:
+        self.undeclared: tuple[RouteDeclaration, ...] = tuple(undeclared)
+        listing = "\n".join(f"  - {route}" for route in undeclared)
+        super().__init__(
+            f"{len(undeclared)} route(s) declare no authorization.\n"
+            f"{listing}\n\n"
+            "Every route must declare one of: Depends(guards.requires(Capability...)), "
+            "Depends(public_endpoint('reason')), or Depends(internal_endpoint('reason')). "
+            "A route with none of them is not public — it is undeclared, and "
+            "deny-by-default treats that as a failure."
+        )
+
+
+def _walk_dependants(dependant: Any) -> Iterator[Any]:
+    """Yield every dependency callable reachable from ``dependant``, depth-first.
+
+    Walking the resolved dependant tree (rather than the endpoint signature) is
+    what makes a declaration discoverable no matter where it was attached: the
+    endpoint signature, ``APIRouter(dependencies=[...])``,
+    ``include_router(..., dependencies=[...])`` and
+    ``FastAPI(dependencies=[...])`` all converge on the same tree.
+    """
+    if dependant is None:
+        return
+    call = getattr(dependant, "call", None)
+    if call is not None:
+        yield call
+    for sub in getattr(dependant, "dependencies", None) or ():
+        yield from _walk_dependants(sub)
+
+
+@dataclass(frozen=True, slots=True)
+class _RawRoute:
+    route: Any
+    path: str
+    methods: tuple[str, ...]
+    name: str
+    dependant: Any
+
+
+def _iter_raw_routes(app: FastAPI) -> Iterator[_RawRoute]:
+    if _iter_route_contexts is not None:
+        for ctx in _iter_route_contexts(app.routes):
+            yield _RawRoute(
+                route=ctx.original_route,
+                path=ctx.path or "",
+                methods=tuple(sorted(ctx.methods or ())),
+                name=ctx.name or "",
+                dependant=getattr(ctx, "dependant", None),
+            )
+        return
+    for route in app.routes:  # pragma: no cover  # legacy FastAPI path
+        yield _RawRoute(
+            route=route,
+            path=str(getattr(route, "path", "")),
+            methods=tuple(sorted(getattr(route, "methods", None) or ())),
+            name=str(getattr(route, "name", "")),
+            dependant=getattr(route, "dependant", None),
+        )
+
+
+def _describe(raw: _RawRoute) -> RouteDeclaration:
+    capabilities: set[Capability] = set()
+    reason: str | None = None
+    internal: str | None = None
+    for call in _walk_dependants(raw.dependant):
+        declared = declared_capabilities(call)
+        if declared:
+            capabilities |= declared
+        if reason is None:
+            reason = public_reason(call)
+        if internal is None:
+            internal = internal_reason(call)
+
+    return RouteDeclaration(
+        methods=raw.methods,
+        path=raw.path,
+        name=raw.name,
+        capabilities=frozenset(capabilities),
+        public_reason=reason,
+        kind=type(raw.route).__name__,
+        internal_reason=internal,
+    )
+
+
+def describe_routes(app: FastAPI) -> list[RouteDeclaration]:
+    """Return the authorization declaration of every application route in ``app``.
+
+    FastAPI's own documentation routes are excluded; anything else that is not
+    an ``APIRoute``/``APIWebSocketRoute`` — a raw Starlette ``Route``, a
+    ``Mount``, a sub-application — is included and will read as undeclared,
+    because the kernel cannot see inside it and therefore cannot vouch for it.
+    """
+    declarations: list[RouteDeclaration] = []
+    for raw in _iter_raw_routes(app):
+        if not isinstance(raw.route, APIRoute | APIWebSocketRoute) and raw.path in FRAMEWORK_PATHS:
+            continue
+        declarations.append(_describe(raw))
+    return declarations
+
+
+def assert_capability_coverage(
+    app: FastAPI,
+    *,
+    allow_undeclared: Iterable[str] = (),
+) -> list[RouteDeclaration]:
+    """Fail unless every route in ``app`` declares its authorization.
+
+    ``allow_undeclared`` is an escape hatch of last resort, spelled as
+    ``"METHOD /path"`` (e.g. ``"GET /health"``). It is deliberately awkward:
+
+    * every entry must match a real undeclared route, so the list cannot rot
+      into a permanent, meaningless allowlist;
+    * it appears in the service's own test file, in the diff, in review.
+
+    Prefer ``Depends(public_endpoint(reason))`` on the route itself.
+
+    Returns every declaration, so callers can make further assertions — for
+    example that no route outside ``/internal`` demands
+    ``Capability.PLATFORM_TENANT_BYPASS``.
+    """
+    declarations = describe_routes(app)
+    if not declarations:
+        raise AssertionError(
+            "No routes were discovered on this app, so nothing was verified. "
+            "A coverage assertion that inspects zero routes is worse than none — "
+            "check that routers are included before this is called."
+        )
+
+    allowed = set(allow_undeclared)
+    undeclared: list[RouteDeclaration] = []
+    matched: set[str] = set()
+    for declaration in declarations:
+        if declaration.is_declared:
+            continue
+        keys = {f"{method} {declaration.path}" for method in declaration.methods} or {f"WS {declaration.path}"}
+        hit = keys & allowed
+        if hit:
+            matched |= hit
+            continue
+        undeclared.append(declaration)
+
+    stale = allowed - matched
+    if stale:
+        raise AssertionError(f"allow_undeclared contains entries that match no undeclared route: {sorted(stale)}. Remove them — a stale allowlist hides the next real gap.")
+
+    if undeclared:
+        raise UndeclaredRouteError(undeclared)
+    return declarations
+
+
+def enforce_capability_coverage(app: FastAPI, *, allow_undeclared: Iterable[str] = ()) -> None:
+    """Startup-time equivalent of :func:`assert_capability_coverage`.
+
+    Call it at the end of app construction. It raises before the service can
+    accept traffic, which is the correct place to fail: an undeclared route is a
+    deployment defect, not a per-request authorization decision.
+    """
+    assert_capability_coverage(app, allow_undeclared=allow_undeclared)