spaps-server-quickstart 0.6.0__tar.gz → 0.6.1__tar.gz

{spaps_server_quickstart-0.6.0 → spaps_server_quickstart-0.6.1}/CHANGELOG.md

@@ -6,6 +6,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-06-01
+
+### Changed
+
+- Relaxed the FastAPI upper bound to `<0.120` so downstream services can adopt FastAPI 0.119 and Starlette security fixes.
+- Relaxed the `cryptography` upper bound to `<46.0` so downstream services can resolve CVE-fixed releases without local pip-audit ignores.
+
 ## [0.6.0] - 2026-05-29
 
 ### Added

{spaps_server_quickstart-0.6.0 → spaps_server_quickstart-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spaps-server-quickstart
-Version: 0.6.0
+Version: 0.6.1
 Summary: Shared FastAPI/Celery scaffolding for Sweet Potato service backends.
 Project-URL: Homepage, https://api.sweetpotato.dev
 Project-URL: Repository, https://github.com/sweet-potato/spaps
@@ -21,10 +21,10 @@ Requires-Dist: asyncpg<0.31,>=0.30.0
 Requires-Dist: bcrypt<6.0,>=4.0.0
 Requires-Dist: botocore<2.0,>=1.35.0
 Requires-Dist: celery<6.0,>=5.5.3
-Requires-Dist: cryptography<45.0,>=42.0.0
+Requires-Dist: cryptography<46.0,>=42.0.0
 Requires-Dist: email-validator<3.0,>=2.1.0
 Requires-Dist: eth-account<1.0,>=0.13.0
-Requires-Dist: fastapi<0.119,>=0.118.0
+Requires-Dist: fastapi<0.120,>=0.118.0
 Requires-Dist: greenlet<4.0,>=3.0.3
 Requires-Dist: httpx<0.29,>=0.28.1
 Requires-Dist: orjson<4.0,>=3.10.0
@@ -295,7 +295,7 @@ From the repository root: `make pytest`, `make lint`, `make typecheck`, `make py
 ## Metadata
 
 - `package_name`: `spaps-server-quickstart`
-- `latest_version`: `0.5.1`
+- `latest_version`: `0.6.1`
 - `minimum_runtime`: `Python >=3.12`
 - `api_base_url`: `https://api.sweetpotato.dev`
 

{spaps_server_quickstart-0.6.0 → spaps_server_quickstart-0.6.1}/README.md

@@ -216,7 +216,7 @@ From the repository root: `make pytest`, `make lint`, `make typecheck`, `make py
 ## Metadata
 
 - `package_name`: `spaps-server-quickstart`
-- `latest_version`: `0.5.1`
+- `latest_version`: `0.6.1`
 - `minimum_runtime`: `Python >=3.12`
 - `api_base_url`: `https://api.sweetpotato.dev`
 

{spaps_server_quickstart-0.6.0 → spaps_server_quickstart-0.6.1}/docs/UPGRADING.md

@@ -4,6 +4,16 @@ When `spaps-server-quickstart` publishes new releases, dependent services (e.g.
 `consumer_server`, `ingredient_server`) need a predictable upgrade cadence. Follow this
 checklist whenever we cut a release or adopt a newer version downstream.
 
+## 0.6.1
+
+This is a dependency-bound patch release only. It permits FastAPI 0.119.x
+(including compatible Starlette security fixes) and `cryptography` 45.x without
+requiring any SPAPS application-code migration.
+
+Downstream services should refresh their dependency lockfile after bumping
+`spaps-server-quickstart` to 0.6.1, then run their normal lint, typecheck, test,
+and security-audit gates.
+
 ## For the Quickstart Maintainer (Publishing a Release)
 
 1. **Triage changes** – confirm whether the release is a patch, minor, or major bump.

{spaps_server_quickstart-0.6.0 → spaps_server_quickstart-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "spaps-server-quickstart"
-version = "0.6.0"
+version = "0.6.1"
 description = "Shared FastAPI/Celery scaffolding for Sweet Potato service backends."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -23,7 +23,7 @@ classifiers = [
   "Topic :: Internet :: WWW/HTTP",
 ]
 dependencies = [
-  "fastapi>=0.118.0,<0.119",
+  "fastapi>=0.118.0,<0.120",
   "uvicorn[standard]>=0.37.0,<0.38",
   "sqlalchemy>=2.0.30,<3.0",
   "asyncpg>=0.30.0,<0.31",
@@ -55,7 +55,7 @@ dependencies = [
   # Phase 3-4: Stripe + Entitlements
   "stripe>=8.0.0,<12.0",
   # Phase 7: PII Encryption (AES-256-GCM + HKDF-SHA256)
-  "cryptography>=42.0.0,<45.0",
+  "cryptography>=42.0.0,<46.0",
 ]
 
 [project.optional-dependencies]

{spaps_server_quickstart-0.6.0 → spaps_server_quickstart-0.6.1}/src/spaps_server_quickstart/__init__.py

@@ -60,7 +60,7 @@ from .sdk import (
     FeatureContext,
 )
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 
 __all__ = [
     "create_app",

spaps_server_quickstart-0.6.1/src/spaps_server_quickstart/openapi_auth.py

@@ -0,0 +1,229 @@
+"""OpenAPI authentication metadata for the SPAPS route contract."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from copy import deepcopy
+from typing import Any
+
+from fastapi.routing import APIRoute
+
+from .middleware.key_scope import is_endpoint_allowed_for_publishable
+
+OPENAPI_AUTH_EXTENSION = "x-spaps-auth"
+
+SPAPS_SECURITY_SCHEMES: dict[str, dict[str, Any]] = {
+    "SpapsApiKey": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-API-Key",
+        "description": "Generic SPAPS application API key. Prefer the more specific publishable or secret-key schemes when an operation declares them.",
+    },
+    "SpapsPublishableKey": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-API-Key",
+        "description": "Browser-safe SPAPS publishable key (`spaps_pub_*`). Requires an allowed Origin and route/method scope.",
+    },
+    "SpapsSecretKey": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-API-Key",
+        "description": "Server-side SPAPS secret or legacy application key (`spaps_sec_*` or migrated `spaps_*`). Never expose this key in browser code.",
+    },
+    "BearerJWT": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT",
+        "description": "SPAPS user access token carried as `Authorization: Bearer <jwt>`.",
+    },
+    "StripeWebhookSignature": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "stripe-signature",
+        "description": "Stripe webhook signature header verified against the configured Stripe webhook secret.",
+    },
+    "MailgunWebhookSignature": {
+        "type": "http",
+        "scheme": "mailgun-signature",
+        "description": "Mailgun webhook signature payload verified against the configured Mailgun signing key.",
+    },
+}
+
+PROVIDER_SIGNATURE_ROUTES: dict[tuple[str, str], tuple[str, str]] = {
+    ("POST", "/api/stripe/webhooks"): (
+        "StripeWebhookSignature",
+        "stripe_webhook_signature",
+    ),
+    ("POST", "/api/stripe/webhooks/{billing_account_id}"): (
+        "StripeWebhookSignature",
+        "stripe_webhook_signature",
+    ),
+    ("POST", "/api/webhooks/mailgun/events"): (
+        "MailgunWebhookSignature",
+        "mailgun_webhook_signature",
+    ),
+}
+
+
+def dependency_call_names(route: APIRoute) -> set[str]:
+    """Return all dependency call names for a route, including nested dependencies."""
+
+    names: set[str] = set()
+
+    def walk(dependant: Any) -> None:
+        for dependency in getattr(dependant, "dependencies", []):
+            call = getattr(dependency, "call", None)
+            name = getattr(call, "__name__", None)
+            if name:
+                names.add(name)
+            walk(dependency)
+
+    walk(route.dependant)
+    return names
+
+
+def _route_path(route: APIRoute) -> str:
+    return getattr(route, "path_format", route.path)
+
+
+def _route_accepts_publishable_key(route: APIRoute, method: str) -> bool:
+    return is_endpoint_allowed_for_publishable(
+        _route_path(route),
+        None,
+        method=method,
+    )
+
+
+def _application_key_schemes(route: APIRoute, method: str) -> tuple[list[str], str]:
+    if _route_accepts_publishable_key(route, method):
+        return ["SpapsPublishableKey", "SpapsSecretKey"], "publishable_or_secret"
+    return ["SpapsSecretKey"], "secret"
+
+
+def route_auth_metadata(route: APIRoute, method: str) -> dict[str, Any]:
+    """Classify a FastAPI route into machine-readable SPAPS auth metadata."""
+
+    method = method.upper()
+    path = _route_path(route)
+    provider_signature = PROVIDER_SIGNATURE_ROUTES.get((method, path))
+    if provider_signature is not None:
+        scheme, auth_type = provider_signature
+        return {
+            "auth_type": auth_type,
+            "required": True,
+            "schemes": [scheme],
+            "provider_signature": {"required": True, "scheme": scheme},
+            "api_key": {"required": False, "accepted": []},
+            "jwt": {"required": False, "optional": False},
+            "roles": [],
+        }
+
+    dependencies = dependency_call_names(route)
+    if "get_application" not in dependencies:
+        return {
+            "auth_type": "public",
+            "required": False,
+            "schemes": [],
+            "api_key": {"required": False, "accepted": []},
+            "jwt": {"required": False, "optional": False},
+            "roles": [],
+        }
+
+    key_schemes, key_type = _application_key_schemes(route, method)
+    roles: list[str] = []
+    jwt_required = False
+    jwt_optional = False
+    auth_type = "application"
+
+    if "require_super_admin_user" in dependencies:
+        roles = ["super_admin"]
+        jwt_required = True
+        auth_type = "super_admin"
+    elif "require_admin_user" in dependencies:
+        roles = ["admin"]
+        jwt_required = True
+        auth_type = "admin"
+    elif "get_current_user" in dependencies:
+        roles = ["user"]
+        jwt_required = True
+        auth_type = "user"
+    elif "get_optional_user" in dependencies:
+        jwt_optional = True
+        auth_type = "application_optional_user"
+
+    schemes = [*key_schemes]
+    if jwt_required:
+        schemes.append("BearerJWT")
+    return {
+        "auth_type": auth_type,
+        "required": True,
+        "schemes": schemes,
+        "api_key": {
+            "required": True,
+            "accepted": ["publishable", "secret"] if key_type == "publishable_or_secret" else ["secret"],
+        },
+        "jwt": {"required": jwt_required, "optional": jwt_optional},
+        "roles": roles,
+    }
+
+
+def operation_security(metadata: dict[str, Any]) -> list[dict[str, list[Any]]]:
+    """Translate SPAPS auth metadata into OpenAPI security requirements."""
+
+    if not metadata["required"]:
+        return []
+
+    provider_signature = metadata.get("provider_signature")
+    if provider_signature:
+        return [{str(provider_signature["scheme"]): []}]
+
+    api_key = metadata.get("api_key", {})
+    key_types = list(api_key.get("accepted", []))
+    key_schemes = (
+        ["SpapsPublishableKey", "SpapsSecretKey"]
+        if "publishable" in key_types
+        else ["SpapsSecretKey"]
+    )
+
+    requirements: list[dict[str, list[Any]]] = []
+    for scheme in key_schemes:
+        requirement: dict[str, list[Any]] = {scheme: []}
+        if metadata.get("jwt", {}).get("required"):
+            requirement["BearerJWT"] = []
+        requirements.append(requirement)
+    return requirements
+
+
+def _route_methods(route: APIRoute) -> Iterable[str]:
+    for method in sorted(route.methods or []):
+        if method.upper() not in {"HEAD", "OPTIONS"}:
+            yield method.upper()
+
+
+def apply_openapi_auth_metadata(
+    schema: dict[str, Any],
+    routes: Iterable[Any],
+) -> dict[str, Any]:
+    """Attach SPAPS security schemes and operation auth metadata to a schema."""
+
+    components = schema.setdefault("components", {})
+    security_schemes = components.setdefault("securitySchemes", {})
+    for name, scheme in SPAPS_SECURITY_SCHEMES.items():
+        security_schemes[name] = deepcopy(scheme)
+
+    paths = schema.setdefault("paths", {})
+    for route in routes:
+        if not isinstance(route, APIRoute) or not route.include_in_schema:
+            continue
+        path = _route_path(route)
+        operations = paths.get(path, {})
+        for method in _route_methods(route):
+            operation = operations.get(method.lower())
+            if operation is None:
+                continue
+            metadata = route_auth_metadata(route, method)
+            operation["security"] = operation_security(metadata)
+            operation[OPENAPI_AUTH_EXTENSION] = metadata
+
+    return schema

{spaps_server_quickstart-0.6.0 → spaps_server_quickstart-0.6.1}/src/spaps_server_quickstart/spaps_app.py

@@ -16,6 +16,7 @@ from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
 from fastapi.responses import ORJSONResponse
 from sqlalchemy import text
 
@@ -111,12 +112,36 @@ from .middleware.envelope import ResponseEnvelopeMiddleware
 from .middleware.error_handler import install_error_handlers
 from .middleware.rate_limiting import RateLimitMiddleware
 from .middleware.security_headers import SecurityHeadersMiddleware
+from .openapi_auth import apply_openapi_auth_metadata
 from .spaps_settings import SpapsSettings, get_spaps_settings
 from .startup import startup_checks
 
 logger = logging.getLogger(__name__)
 
 
+def _install_openapi_auth_metadata(app: FastAPI) -> None:
+    """Generate OpenAPI once, then attach SPAPS auth metadata from route dependencies."""
+
+    def custom_openapi() -> dict:
+        if app.openapi_schema:
+            return app.openapi_schema
+
+        schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            openapi_version=app.openapi_version,
+            summary=app.summary,
+            description=app.description,
+            routes=app.routes,
+            tags=app.openapi_tags,
+            servers=app.servers,
+        )
+        app.openapi_schema = apply_openapi_auth_metadata(schema, app.routes)
+        return app.openapi_schema
+
+    app.openapi = custom_openapi  # type: ignore[method-assign]
+
+
 async def _validate_tm013_pii_startup_invariant(
     settings: SpapsSettings,
     db_resources: DatabaseResources,
@@ -365,6 +390,7 @@ def create_spaps_app(
 
     # Include routers
     app.include_router(api_router)
+    _install_openapi_auth_metadata(app)
 
     # Store references on app.state for health checks and dependency injection
     app.state.db_resources = db_resources

spaps_server_quickstart-0.6.1/tests/contracts/test_manifest_fastapi_script.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_script() -> ModuleType:
+    repo_root = Path(__file__).resolve().parents[4]
+    script_path = repo_root / "scripts" / "validate_manifest_fastapi.py"
+    spec = importlib.util.spec_from_file_location("validate_manifest_fastapi", script_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+SCRIPT = _load_script()
+
+
+def test_non_manifest_app_routes_fail_closed_except_framework_allowlist() -> None:
+    realtime_source = SCRIPT.REPO_ROOT / "packages/python-server-quickstart/src/spaps_server_quickstart/domains/realtime/router.py"
+    app_routes = {
+        ("GET", "/docs"): SCRIPT.AppRoute(method="GET", path="/docs"),
+        ("POST", "/api/realtime/ws-ticket"): SCRIPT.AppRoute(
+            method="POST",
+            path="/api/realtime/ws-ticket",
+            file=realtime_source,
+            line=18,
+        ),
+    }
+
+    missing = SCRIPT._non_manifest_app_routes(app_routes, manifest_pairs=set())
+
+    assert [route.method + " " + route.path for route in missing] == ["POST /api/realtime/ws-ticket"]
+    assert missing[0].source_label() == (
+        "packages/python-server-quickstart/src/spaps_server_quickstart/domains/realtime/router.py:18"
+    )
+
+
+def test_manifest_path_normalization_matches_fastapi_parameters() -> None:
+    assert SCRIPT._normalize_path("/api/items/{itemId}") == "/api/items/{item_id}"
+    assert SCRIPT._normalize_path("/api/items/{item_id:int}/") == "/api/items/{item_id}"
+
+
+def test_main_fails_on_duplicate_manifest_endpoints(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(
+        SCRIPT,
+        "_load_manifest_endpoint_entries",
+        lambda: (2, [("GET", "/api/items"), ("GET", "/api/items")]),
+    )
+    monkeypatch.setattr(
+        SCRIPT,
+        "_extract_app_routes",
+        lambda: {("GET", "/api/items"): SCRIPT.AppRoute(method="GET", path="/api/items")},
+    )
+
+    assert SCRIPT.main() == 1
+    assert "Duplicate endpoints in manifest" in capsys.readouterr().out
+
+
+def test_main_fails_on_framework_routes_declared_in_manifest(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(SCRIPT, "_load_manifest_endpoint_entries", lambda: (1, [("GET", "/docs")]))
+    monkeypatch.setattr(
+        SCRIPT,
+        "_extract_app_routes",
+        lambda: {("GET", "/docs"): SCRIPT.AppRoute(method="GET", path="/docs")},
+    )
+
+    assert SCRIPT.main() == 1
+    assert "Framework-only routes should not be listed in manifest" in capsys.readouterr().out

spaps_server_quickstart-0.6.1/tests/contracts/test_openapi_auth_metadata.py

@@ -0,0 +1,189 @@
+"""Contract tests for SPAPS OpenAPI authentication metadata."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from copy import deepcopy
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from spaps_server_quickstart.openapi_auth import (
+    SPAPS_SECURITY_SCHEMES,
+    apply_openapi_auth_metadata,
+)
+from spaps_server_quickstart.spaps_app import create_spaps_app
+
+
+def _load_validator_script() -> ModuleType:
+    repo_root = Path(__file__).resolve().parents[4]
+    script_path = repo_root / "scripts" / "validate_openapi_auth_metadata.py"
+    spec = importlib.util.spec_from_file_location(
+        "validate_openapi_auth_metadata",
+        script_path,
+    )
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+VALIDATOR_SCRIPT = _load_validator_script()
+
+
+@pytest.fixture(scope="module")
+def _openapi_schema() -> dict[str, Any]:
+    os.environ["SPAPS_ENV"] = "test"
+    with patch("spaps_server_quickstart.spaps_app.DatabaseResources") as mock_db:
+        mock_db.return_value = MagicMock()
+        return create_spaps_app().openapi()
+
+
+def _operation(schema: dict[str, Any], method: str, path: str) -> dict[str, Any]:
+    return schema["paths"][path][method.lower()]
+
+
+def _validator_issues(schema: dict[str, Any]) -> list[str]:
+    return VALIDATOR_SCRIPT.validate_schema(schema, VALIDATOR_SCRIPT._build_app_routes())
+
+
+def test_openapi_declares_spaps_security_schemes(_openapi_schema: dict[str, Any]) -> None:
+    schema = _openapi_schema
+    security_schemes = schema["components"]["securitySchemes"]
+    assert "SpapsApiKey" in security_schemes
+    assert security_schemes["SpapsApiKey"]["name"] == "X-API-Key"
+    assert "SpapsPublishableKey" in security_schemes
+    assert "SpapsSecretKey" in security_schemes
+    assert "BearerJWT" in security_schemes
+    assert "StripeWebhookSignature" in security_schemes
+    assert "MailgunWebhookSignature" in security_schemes
+
+
+def test_apply_openapi_auth_metadata_overwrites_stale_security_schemes() -> None:
+    schema: dict[str, Any] = {
+        "components": {
+            "securitySchemes": {
+                "SpapsSecretKey": {"type": "apiKey", "in": "header", "name": "X-WRONG"}
+            }
+        },
+        "paths": {},
+    }
+
+    apply_openapi_auth_metadata(schema, routes=[])
+
+    secret_key_scheme = schema["components"]["securitySchemes"]["SpapsSecretKey"]
+    assert secret_key_scheme == SPAPS_SECURITY_SCHEMES["SpapsSecretKey"]
+    assert secret_key_scheme is not SPAPS_SECURITY_SCHEMES["SpapsSecretKey"]
+
+
+def test_app_openapi_cache_preserves_auth_metadata() -> None:
+    os.environ["SPAPS_ENV"] = "test"
+    with patch("spaps_server_quickstart.spaps_app.DatabaseResources") as mock_db:
+        mock_db.return_value = MagicMock()
+        app = create_spaps_app()
+
+    first_schema = app.openapi()
+    second_schema = app.openapi()
+
+    assert second_schema is first_schema
+    assert _operation(second_schema, "GET", "/health")["x-spaps-auth"]["auth_type"] == "public"
+    assert _operation(second_schema, "POST", "/api/auth/login")["security"] == [
+        {"SpapsPublishableKey": []},
+        {"SpapsSecretKey": []},
+    ]
+
+
+def test_validator_rejects_security_scheme_drift(_openapi_schema: dict[str, Any]) -> None:
+    schema = deepcopy(_openapi_schema)
+    schema["components"]["securitySchemes"]["SpapsSecretKey"]["name"] = "X-WRONG"
+
+    issues = _validator_issues(schema)
+
+    assert any("SpapsSecretKey security scheme=" in issue for issue in issues)
+
+
+def test_validator_rejects_nested_auth_metadata_drift(_openapi_schema: dict[str, Any]) -> None:
+    schema = deepcopy(_openapi_schema)
+    operation = _operation(schema, "GET", "/api/auth/user")
+    operation["x-spaps-auth"]["roles"] = []
+
+    issues = _validator_issues(schema)
+
+    assert any(
+        "GET /api/auth/user x-spaps-auth=" in issue and "'roles': ['user']" in issue
+        for issue in issues
+    )
+
+
+def test_public_routes_are_explicitly_marked_public(_openapi_schema: dict[str, Any]) -> None:
+    schema = _openapi_schema
+    operation = _operation(schema, "GET", "/health")
+
+    assert operation["security"] == []
+    assert operation["x-spaps-auth"]["auth_type"] == "public"
+    assert operation["x-spaps-auth"]["required"] is False
+
+
+def test_publishable_application_route_exposes_key_options(_openapi_schema: dict[str, Any]) -> None:
+    schema = _openapi_schema
+    operation = _operation(schema, "POST", "/api/auth/login")
+
+    assert operation["security"] == [
+        {"SpapsPublishableKey": []},
+        {"SpapsSecretKey": []},
+    ]
+    assert operation["x-spaps-auth"]["auth_type"] == "application"
+    assert operation["x-spaps-auth"]["api_key"]["accepted"] == ["publishable", "secret"]
+    assert operation["x-spaps-auth"]["jwt"] == {"required": False, "optional": False}
+
+
+def test_user_route_requires_key_and_bearer_jwt(_openapi_schema: dict[str, Any]) -> None:
+    schema = _openapi_schema
+    operation = _operation(schema, "GET", "/api/auth/user")
+
+    assert operation["security"] == [
+        {"SpapsPublishableKey": [], "BearerJWT": []},
+        {"SpapsSecretKey": [], "BearerJWT": []},
+    ]
+    assert operation["x-spaps-auth"]["auth_type"] == "user"
+    assert operation["x-spaps-auth"]["roles"] == ["user"]
+    assert operation["x-spaps-auth"]["jwt"]["required"] is True
+
+
+def test_admin_and_super_admin_routes_expose_role_metadata(
+    _openapi_schema: dict[str, Any],
+) -> None:
+    schema = _openapi_schema
+    admin_operation = _operation(schema, "GET", "/api/admin/billing/verify")
+    super_admin_operation = _operation(schema, "POST", "/api/admin/billing/attach")
+
+    assert admin_operation["security"] == [{"SpapsSecretKey": [], "BearerJWT": []}]
+    assert admin_operation["x-spaps-auth"]["auth_type"] == "admin"
+    assert admin_operation["x-spaps-auth"]["roles"] == ["admin"]
+
+    assert super_admin_operation["security"] == [{"SpapsSecretKey": [], "BearerJWT": []}]
+    assert super_admin_operation["x-spaps-auth"]["auth_type"] == "super_admin"
+    assert super_admin_operation["x-spaps-auth"]["roles"] == ["super_admin"]
+
+
+def test_provider_webhook_routes_expose_signature_metadata(
+    _openapi_schema: dict[str, Any],
+) -> None:
+    schema = _openapi_schema
+    stripe_operation = _operation(schema, "POST", "/api/stripe/webhooks")
+    mailgun_operation = _operation(schema, "POST", "/api/webhooks/mailgun/events")
+
+    assert stripe_operation["security"] == [{"StripeWebhookSignature": []}]
+    assert stripe_operation["x-spaps-auth"]["auth_type"] == "stripe_webhook_signature"
+    assert stripe_operation["x-spaps-auth"]["provider_signature"]["required"] is True
+
+    assert mailgun_operation["security"] == [{"MailgunWebhookSignature": []}]
+    assert mailgun_operation["x-spaps-auth"]["auth_type"] == "mailgun_webhook_signature"
+    assert mailgun_operation["x-spaps-auth"]["provider_signature"]["required"] is True