fastapi-m8 2.0.0__tar.gz → 2.1.0__tar.gz

fastapi_m8-2.1.0/.github/FUNDING.yml

@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: eliserra
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/CHANGELOG.md

@@ -5,7 +5,57 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning:
 
 ---
 
-## [Unreleased]
+## [2.1.0] — 2026-06-19 · Security-remediation hardening + proxy-routable `{API_PREFIX}/ping`
+
+> **Requires `auth-sdk-m8 >= 1.5.0`** — `mount_service_meta` dual-mounts `/ping`.
+
+### Added
+
+- **Proxy-routable `/ping`** picked up from `auth-sdk-m8 1.5.0`. `mount_service_meta`
+  now dual-mounts the liveness probe: the unchanged root `GET /ping` **plus** a
+  `GET {API_PREFIX}/ping` copy. `create_app` already passes `prefix=API_PREFIX`, so
+  the prefixed probe appears automatically with **no call-site change** — liveness
+  now resolves behind a prefix-routing reverse proxy (Traefik forwards only
+  `PathPrefix({API_PREFIX})`, so the root-only `/ping` previously 404'd at the
+  gateway while `{API_PREFIX}/meta` resolved). The prefixed copy is
+  `include_in_schema=False`, so OpenAPI still carries a single `ping` operation.
+- **`_FILE` secret mounts for consumers** (security remediation 6.1). Documented and
+  regression-tested that `ConsumerServiceSettings` inherits the Docker/K8s
+  `<FIELD>_FILE` convention from `auth-sdk-m8`'s `CommonSettings` — no consumer code
+  change. Any secret can be mounted from a file via `<FIELD>_FILE` (e.g.
+  `DB_PASSWORD_FILE`, `PRIVATE_API_SECRET_FILE`, `METRICS_SCRAPE_CREDENTIAL_FILE`)
+  pointing under `/run/secrets/*`, so the production overlay keeps plaintext secrets
+  out of env files. The mount outranks plaintext `.env`/env values but not explicit
+  constructor kwargs; a missing file fails closed at construction; file-sourced
+  `SecretStr` values stay masked in `repr`. Coverage spans consumer-declared
+  (`METRICS_SCRAPE_CREDENTIAL`), `ConsumerAuthMixin` (`PRIVATE_API_SECRET`), and
+  `CommonSettings` (`DB_PASSWORD`) fields.
+- **Revocation-cache observability** (security remediation 7.x.2). The consumer-side
+  JTI revocation cache now emits best-effort Prometheus metrics on the shared
+  `auth-sdk-m8[observability]` registry: `revocation_cache_lookups_total{result="hit"|"miss"}`
+  and a `revocation_cache_ttl_seconds` gauge for the configured stale-window TTL. Emission
+  is zero-cost when observability is disabled or the extra is absent. Metrics carry **no
+  JTI, user ID, or secret** as a label or value, and cache construction logs the TTL only
+  (never the introspection URL or secret) — satisfying the "keys/secrets are never logged"
+  acceptance criterion. The SDK owns the event-stream signals (connected/gap/reconnect);
+  this is the consumer cache hit/miss + TTL side.
+- `create_app` now **auto-runs the shared `check_config_health()`** (from
+  `auth_sdk_m8.core.config`) as an internal startup validator, **prepended** to any
+  caller-provided `startup_validators`. It runs inside the lifespan (not at import time),
+  so a fatal misconfiguration (e.g. production `localhost` CORS origins, a wildcard
+  `ALLOWED_HOSTS` under strict mode) aborts startup with `ConfigurationError` **before**
+  user validators run and before the service is marked ready. Consumers now get the same
+  production safety checks the auth service already runs, automatically.
+
+### Changed
+
+- **Requires `auth-sdk-m8 >= 1.5.0`** (was `>= 1.4.0`). The dependency floor and the
+  `COMPAT_MATRIX` `2.1` entry are bumped so the dual-mounted `{API_PREFIX}/ping` is
+  guaranteed present; on `auth-sdk-m8 1.4.0` only the root `/ping` exists.
+- `ALLOWED_HOSTS` is no longer redefined on `ConsumerServiceSettings` — it is inherited
+  from `CommonSettings` (auth-sdk-m8), the single source of truth. The default is now
+  `None` (unset) rather than `[]`; both are falsy, so `TrustedHostMiddleware` is still
+  skipped when unset. Production/strict gating lives in `check_config_health`.
 
 ---
 

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-m8
-Version: 2.0.0
+Version: 2.1.0
 Summary: FastAPI application framework for m8 consumer microservices.
 Author-email: Eli Serra <e.serra173@gmail.com>
 License:                                  Apache License
@@ -216,7 +216,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Requires-Dist: anyio>=4.0
-Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<2.0.0,>=1.4.0
+Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<2.0.0,>=1.5.0
 Requires-Dist: fastapi>=0.136.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: packaging>=24.0
@@ -312,7 +312,7 @@ health checks; the framework wires the rest.
 | CORS | Auto-wired from `settings.ALLOWED_ORIGINS` |
 | Metrics middleware | Optional; toggled via `METRICS_ENABLED` |
 | Health endpoint | `GET {API_PREFIX}/health/` with optional detail gating |
-| Service meta + liveness | Auto-mounted `GET {API_PREFIX}/meta` + `GET /ping` (fail-closed at boot) |
+| Service meta + liveness | Auto-mounted `GET {API_PREFIX}/meta` + `GET /ping` (also `GET {API_PREFIX}/ping`; fail-closed at boot) |
 | Database lifecycle | `create_db_engine()` wrapping SQLAlchemy |
 | Startup validation | `startup_validators` list runs before app signals ready |
 | Lifespan management | Auth teardown + DB pool dispose on shutdown |
@@ -556,9 +556,14 @@ environment variable.
 
 `create_app` auto-mounts the shared service triad from `auth-sdk-m8`: `GET {API_PREFIX}/meta`
 (cacheable service/version/contract identity, read by clients pre-auth to assert compatibility)
-and a prefix-independent `GET /ping` (dependency-free liveness → `{"status": "ok"}`). The `/meta`
-values are sourced from these settings, so a consumer **fails closed at boot** if it doesn't
-declare its identity. Keep both separate from a dependency-aware `/health` readiness probe.
+and a dependency-free `GET /ping` liveness probe (→ `{"status": "ok"}`). `/ping` is mounted at
+**both** the root (so direct container/sidecar probes stay independent of the app's prefix config)
+and at `{API_PREFIX}/ping` (so liveness stays reachable behind a prefix-routing reverse proxy such
+as Traefik, which forwards only `PathPrefix({API_PREFIX})` — a root-only `/ping` would 404 at the
+gateway). The prefixed copy is hidden from the schema, so OpenAPI still lists a single `ping`
+operation. The `/meta` values are sourced from these settings, so a consumer **fails closed at
+boot** if it doesn't declare its identity. Keep both separate from a dependency-aware `/health`
+readiness probe.
 
 | Variable | Required | Default | Description |
 |---|---|---|---|

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/README.md

@@ -56,7 +56,7 @@ health checks; the framework wires the rest.
 | CORS | Auto-wired from `settings.ALLOWED_ORIGINS` |
 | Metrics middleware | Optional; toggled via `METRICS_ENABLED` |
 | Health endpoint | `GET {API_PREFIX}/health/` with optional detail gating |
-| Service meta + liveness | Auto-mounted `GET {API_PREFIX}/meta` + `GET /ping` (fail-closed at boot) |
+| Service meta + liveness | Auto-mounted `GET {API_PREFIX}/meta` + `GET /ping` (also `GET {API_PREFIX}/ping`; fail-closed at boot) |
 | Database lifecycle | `create_db_engine()` wrapping SQLAlchemy |
 | Startup validation | `startup_validators` list runs before app signals ready |
 | Lifespan management | Auth teardown + DB pool dispose on shutdown |
@@ -300,9 +300,14 @@ environment variable.
 
 `create_app` auto-mounts the shared service triad from `auth-sdk-m8`: `GET {API_PREFIX}/meta`
 (cacheable service/version/contract identity, read by clients pre-auth to assert compatibility)
-and a prefix-independent `GET /ping` (dependency-free liveness → `{"status": "ok"}`). The `/meta`
-values are sourced from these settings, so a consumer **fails closed at boot** if it doesn't
-declare its identity. Keep both separate from a dependency-aware `/health` readiness probe.
+and a dependency-free `GET /ping` liveness probe (→ `{"status": "ok"}`). `/ping` is mounted at
+**both** the root (so direct container/sidecar probes stay independent of the app's prefix config)
+and at `{API_PREFIX}/ping` (so liveness stays reachable behind a prefix-routing reverse proxy such
+as Traefik, which forwards only `PathPrefix({API_PREFIX})` — a root-only `/ping` would 404 at the
+gateway). The prefixed copy is hidden from the schema, so OpenAPI still lists a single `ping`
+operation. The `/meta` values are sourced from these settings, so a consumer **fails closed at
+boot** if it doesn't declare its identity. Keep both separate from a dependency-aware `/health`
+readiness probe.
 
 | Variable | Required | Default | Description |
 |---|---|---|---|

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/fastapi_m8/_app.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 
 import inspect
 import logging
-import secrets
 import time
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from contextlib import asynccontextmanager
@@ -18,10 +17,15 @@ from typing import TYPE_CHECKING, Any
 
 import anyio
 from auth_sdk_m8.controllers.meta import mount_service_meta
+from auth_sdk_m8.core.config import check_config_health
+from auth_sdk_m8.security.guards import (
+    make_internal_token_authorizer,
+    make_scrape_credential_guard,
+)
 from auth_sdk_m8.security.headers import add_security_headers_middleware
-from fastapi import APIRouter, FastAPI, Request
+from fastapi import APIRouter, Depends, FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
+from fastapi.responses import JSONResponse, Response
 from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from fastapi_m8._compat import _COMPAT_STATE, _assert_compat
@@ -146,6 +150,23 @@ def _build_lifespan(
     return lifespan
 
 
+def _build_config_health_validator(
+    settings: ConsumerServiceSettings,
+) -> StartupValidator:
+    """
+    Return a startup validator running the shared ``check_config_health``.
+
+    The validator runs inside the lifespan (not at import time) and raises
+    ``ConfigurationError`` on fatal misconfiguration, aborting startup before
+    any caller-provided validators run.
+    """
+
+    async def _validate_config_health() -> None:
+        check_config_health(settings, logger)
+
+    return _validate_config_health
+
+
 def _add_metrics_middleware(app: FastAPI, settings: ConsumerServiceSettings) -> None:
     if not settings.METRICS_ENABLED:
         return
@@ -172,16 +193,37 @@ def _build_default_authorizer(
 ) -> Callable[[Request], bool]:
     """Return a token authorizer closed over the private API secret."""
     sec = settings.PRIVATE_API_SECRET
+    return make_internal_token_authorizer(sec.get_secret_value() if sec else None)
+
 
-    def _authorizer(request: Request) -> bool:
-        if not sec:
-            return False
-        return secrets.compare_digest(
-            request.headers.get("X-Internal-Token", ""),
-            sec.get_secret_value(),
+def _register_metrics_route(app: FastAPI, settings: ConsumerServiceSettings) -> None:
+    """
+    Register ``/metrics`` with an optional scrape-credential guard (1.4).
+
+    The route is only wired when ``METRICS_ENABLED=True``.  When
+    ``METRICS_SCRAPE_CREDENTIAL`` is unset the guard is a no-op and the network
+    boundary (internal entrypoint) remains the sole control.  When set, requests
+    must present ``Authorization: Bearer <credential>`` (constant-time match).
+    """
+    if not settings.METRICS_ENABLED:
+        return
+    cred_field = settings.METRICS_SCRAPE_CREDENTIAL
+    guard = make_scrape_credential_guard(
+        cred_field.get_secret_value() if cred_field else None
+    )
+    try:
+        from auth_sdk_m8.observability import metrics as _obs  # noqa: PLC0415
+    except ImportError:  # pragma: no cover
+        logger.warning(
+            "METRICS_ENABLED but auth-sdk-m8[observability] missing; "
+            "skipping /metrics route"
         )
+        return
 
-    return _authorizer
+    @app.get("/metrics", include_in_schema=False, dependencies=[Depends(guard)])
+    def _metrics_endpoint() -> Response:
+        data, content_type = _obs.render()
+        return Response(content=data, media_type=content_type)
 
 
 async def _gather_health_results(
@@ -360,9 +402,13 @@ def create_app(
     h = health or HealthConfig()
     lc = lifecycle or AppLifecycle()
     checks = list(h.checks or [])
+    startup_validators = [
+        _build_config_health_validator(settings),
+        *(lc.startup_validators or []),
+    ]
     app = FastAPI(
         lifespan=_build_lifespan(
-            lc.auth_deps, lc.db_engine, lc.startup_validators, lc.lifespan_extras
+            lc.auth_deps, lc.db_engine, startup_validators, lc.lifespan_extras
         ),
         **_openapi_config(settings, service_name, service_version),
     )
@@ -371,6 +417,7 @@ def create_app(
     _add_trusted_host_middleware(app, settings)
     add_security_headers_middleware(app, settings)
     _add_metrics_middleware(app, settings)
+    _register_metrics_route(app, settings)
     authorize = h.detail_authorizer or _build_default_authorizer(settings)
     _register_health_route(
         app, settings.API_PREFIX, checks, h, authorize, service_name, service_version

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/fastapi_m8/_compat.py

@@ -42,6 +42,13 @@ COMPAT_MATRIX: dict[str, dict[str, str]] = {
     # at boot). Requires auth-sdk-m8 1.4.0, which ships mount_service_meta +
     # ServiceMeta — see CHANGELOG. BREAKING: consumers must declare their meta.
     "2.0": {"auth-sdk-m8": ">=1.4.0,<2.0.0"},
+    # 2.1 requires auth-sdk-m8 1.5.0, where mount_service_meta dual-mounts /ping:
+    # the unchanged root /ping plus a {API_PREFIX}/ping copy so liveness stays
+    # reachable behind a prefix-routing reverse proxy (Traefik forwards only
+    # PathPrefix({API_PREFIX}), so a root-only /ping 404s at the gateway). The
+    # create_app call site is unchanged — it already passes prefix=API_PREFIX — so
+    # the prefixed probe is picked up automatically on upgrade. See CHANGELOG.
+    "2.1": {"auth-sdk-m8": ">=1.5.0,<2.0.0"},
 }
 
 _EXTRAS = "[config,security,fastapi,observability]"

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/fastapi_m8/_revocation.py

@@ -5,6 +5,8 @@ Checks JTI status via the auth service private introspection endpoint.
 Instantiated only by ``build_auth_deps``; never import directly.
 """
 
+from __future__ import annotations
+
 import logging
 import time
 
@@ -13,6 +15,75 @@ import httpx
 _logger = logging.getLogger(__name__)
 
 
+def _get_obs():
+    """
+    Return the auth-sdk-m8 observability ``metrics`` module, or ``None``.
+
+    Observability is an optional extra (``auth-sdk-m8[observability]``); the
+    revocation cache must keep working without it, so the import is guarded and
+    metric emission is best-effort. Never raises.
+    """
+    try:
+        from auth_sdk_m8.observability import metrics as obs  # noqa: PLC0415
+    except ImportError:  # pragma: no cover — observability extra always installed
+        return None
+    return obs
+
+
+class _CacheMetrics:
+    """
+    Consumer-side revocation-cache metrics, registered on the SDK registry.
+
+    Carries no JTI, user ID, or secret as a label or value — only the
+    ``result`` (``hit``/``miss``) dimension and the configured TTL — so the
+    acceptance criterion "keys/secrets are never logged" holds for metrics too.
+    """
+
+    def __init__(self, lookups, ttl_seconds) -> None:  # noqa: ANN001
+        self.lookups = lookups
+        self.ttl_seconds = ttl_seconds
+
+
+# (registry, metrics) — rebuilt when the SDK swaps its registry (tests do this).
+# Holding the registry object (not its id) prevents id-reuse aliasing after GC.
+_cache_metrics: tuple[object, _CacheMetrics] | None = None
+
+
+def _get_cache_metrics() -> _CacheMetrics | None:
+    """
+    Return the revocation-cache metrics, registering them once on demand.
+
+    Returns ``None`` when observability is unavailable (extra not installed) or
+    disabled (``METRICS_ENABLED=false``) — so the cache has zero metric cost in
+    that case, mirroring the SDK's best-effort emission. Never raises.
+    """
+    obs = _get_obs()
+    if obs is None or obs.get() is None:
+        return None
+    registry = obs.REGISTRY
+    global _cache_metrics
+    if _cache_metrics is not None and _cache_metrics[0] is registry:
+        return _cache_metrics[1]
+    from prometheus_client import Counter, Gauge  # noqa: PLC0415
+
+    metrics = _CacheMetrics(
+        lookups=Counter(
+            "revocation_cache_lookups_total",
+            "JTI revocation-cache lookups by outcome (result: hit | miss)",
+            ["result"],
+            registry=registry,
+        ),
+        ttl_seconds=Gauge(
+            "revocation_cache_ttl_seconds",
+            "Configured revocation-cache stale-window TTL in seconds "
+            "(0 = caching disabled)",
+            registry=registry,
+        ),
+    )
+    _cache_metrics = (registry, metrics)
+    return metrics
+
+
 class RevocationCheckError(Exception):
     """Raised when the revocation check fails in fail-closed mode."""
 
@@ -93,9 +164,13 @@ class RemoteRevocationClient:
         """Initialise the HTTP client with auth headers and timeouts."""
         self._url = introspection_url
         self._fail_closed = fail_closed
+        self._cache_ttl = cache_ttl
         self._cache: JtiRevocationCache | None = (
             JtiRevocationCache(cache_ttl) if cache_ttl > 0 else None
         )
+        if self._cache is not None:
+            # TTL only — never the introspection URL host or any secret.
+            _logger.info("revocation.cache enabled ttl_seconds=%d", cache_ttl)
         self._client = httpx.AsyncClient(
             headers={"X-Internal-Token": private_api_secret},
             timeout=httpx.Timeout(
@@ -121,7 +196,9 @@ class RemoteRevocationClient:
         if self._cache is not None:
             cached = self._cache.get(jti)
             if cached is not None:
+                self._record_lookup("hit")
                 return cached  # False = not revoked (active cached)
+            self._record_lookup("miss")
         try:
             response = await self._client.post(self._url, json={"jti": jti})
             response.raise_for_status()
@@ -135,6 +212,21 @@ class RemoteRevocationClient:
                 raise RevocationCheckError(str(exc)) from exc
             return False
 
+    def _record_lookup(self, result: str) -> None:
+        """
+        Record a cache lookup outcome (``hit``/``miss``); best-effort.
+
+        Also (idempotently) publishes the configured stale-window TTL gauge —
+        done here rather than in ``__init__`` because metrics setup runs after
+        ``build_auth_deps``, so the gauge would otherwise be a no-op at boot.
+        No JTI, user ID, or secret is ever passed as a label or value.
+        """
+        cache_metrics = _get_cache_metrics()
+        if cache_metrics is None:
+            return
+        cache_metrics.lookups.labels(result=result).inc()
+        cache_metrics.ttl_seconds.set(self._cache_ttl)
+
     def evict_jti(self, jti: str) -> None:
         """Remove one JTI from the cache (no-op when cache is disabled)."""
         if self._cache is not None:

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/fastapi_m8/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/fastapi_m8/config.py

@@ -23,7 +23,7 @@ from auth_sdk_m8.core.config import CommonSettings
 from auth_sdk_m8.core.consumer import ConsumerAuthMixin
 from auth_sdk_m8.observability.settings import ObservabilitySettingsMixin
 from auth_sdk_m8.schemas.meta import ServiceContract, ServiceMeta
-from pydantic import Field, field_validator
+from pydantic import Field, SecretStr
 
 
 class ConsumerServiceSettings(
@@ -37,14 +37,25 @@ class ConsumerServiceSettings(
     ``PRIVATE_API_SECRET`` from ``ConsumerAuthMixin``, and all common
     fields (``SECRET_KEY``, ``TOKEN_MODE``, ``ALLOWED_ORIGINS``,
     ``SQLALCHEMY_DATABASE_URI``, ``API_PREFIX``, …) from ``CommonSettings``.
+
+    **Secret files (`_FILE` mounts).** ``settings_customise_sources`` is inherited
+    from ``CommonSettings``, so every secret field — including consumer-declared
+    ones like ``METRICS_SCRAPE_CREDENTIAL`` — can be sourced from a mounted file by
+    setting ``<FIELD>_FILE`` (e.g. ``DB_PASSWORD_FILE``, ``PRIVATE_API_SECRET_FILE``,
+    ``METRICS_SCRAPE_CREDENTIAL_FILE``) to a path under ``/run/secrets/*``. The file
+    mount outranks plaintext ``.env``/env values but not explicit constructor
+    kwargs, and a missing file fails closed at construction. This lets the
+    production overlay keep plaintext secrets out of env files with no consumer
+    code change (security remediation 6.1).
     """
 
     AUTH_PREFIX: str = "/auth"
     TABLES_PREFIX: str = "app"
-    # Explicit host allowlist for TrustedHostMiddleware.
-    # Empty (default) = middleware not registered (permissive, safe for dev).
-    # In production set to your public hostname(s), e.g. "api.example.com".
-    ALLOWED_HOSTS: list[str] = []
+    # ``ALLOWED_HOSTS`` (host allowlist for TrustedHostMiddleware) is owned by
+    # ``CommonSettings`` (auth-sdk-m8) — the single source of truth. Unset/empty
+    # (default ``None``) = middleware not registered (permissive, safe for dev);
+    # in production set your public hostname(s), e.g. "api.example.com". Its
+    # production/strict gating lives in ``check_config_health``.
 
     # Response security-header knobs (SECURITY_HEADERS_ENABLED, HSTS_ENABLED,
     # HSTS_MAX_AGE, HSTS_INCLUDE_SUBDOMAINS, CONTENT_SECURITY_POLICY_ENABLED,
@@ -66,6 +77,20 @@ class ConsumerServiceSettings(
     # by JTI/user, an unresumable gap flushes all (requires event stream client).
     REVOCATION_CACHE_TTL_SECONDS: int = Field(0, ge=0)
 
+    # Metrics scrape credential for the ``/metrics`` endpoint (auth-sdk-m8 guard 1.4).
+    # Unset (default) = network-isolation only; ``/metrics`` answers without auth.
+    # Set to a long-lived static secret and configure Prometheus
+    # ``scrape_configs.authorization.credentials`` to match — guards are
+    # constant-time via ``auth_sdk_m8.security.guards.make_scrape_credential_guard``.
+    METRICS_SCRAPE_CREDENTIAL: SecretStr | None = Field(
+        None,
+        description=(
+            "Optional static bearer credential for the /metrics scrape endpoint. "
+            "When set, requests must present Authorization: Bearer <value>. "
+            "When unset, /metrics relies on network isolation only."
+        ),
+    )
+
     # Service/contract metadata served at ``{API_PREFIX}/meta`` (see
     # auth_sdk_m8.controllers.meta). These are **required** so every consumer
     # fails closed at boot if it doesn't declare its identity — clients read
@@ -100,11 +125,3 @@ class ConsumerServiceSettings(
                 range=self.CONTRACT_RANGE,
             ),
         )
-
-    @field_validator("ALLOWED_HOSTS", mode="before")
-    @classmethod
-    def _parse_allowed_hosts(cls, v: object) -> list[str]:
-        """Accept a comma-separated string or list from the environment."""
-        if isinstance(v, str):
-            return [h.strip() for h in v.split(",") if h.strip()]
-        return list(v) if v else []  # type: ignore[call-overload]

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-m8"
-version = "2.0.0"
+version = "2.1.0"
 description = "FastAPI application framework for m8 consumer microservices."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -27,7 +27,7 @@ dependencies = [
     "httpx>=0.27.0",
     "packaging>=24.0",
     "anyio>=4.0",
-    "auth-sdk-m8[config,security,fastapi,observability,events]>=1.4.0,<2.0.0",
+    "auth-sdk-m8[config,security,fastapi,observability,events]>=1.5.0,<2.0.0",
 ]
 
 [project.optional-dependencies]

{fastapi_m8-2.0.0 → fastapi_m8-2.1.0}/tests/test_app.py

@@ -8,6 +8,7 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 from asgi_lifespan import LifespanManager
+from auth_sdk_m8.core.exceptions import ConfigurationError
 from fastapi import APIRouter
 from httpx import ASGITransport, AsyncClient
 
@@ -234,6 +235,93 @@ async def test_startup_validator_fail_prevents_ready(test_router: APIRouter) ->
     assert a.state.service_ready is False
 
 
+# ── Auto config-health (item 1.1) ─────────────────────────────────────────────
+
+
+@pytest.mark.anyio
+async def test_config_health_blocks_lifespan_on_production_localhost_cors(
+    test_router: APIRouter,
+) -> None:
+    """Production localhost CORS origins fail config-health during lifespan."""
+    a = create_app(
+        make_settings(
+            **_BASE, ENVIRONMENT="production", ALLOWED_HOSTS=["api.example.com"]
+        ),
+        test_router,
+    )
+    with pytest.raises(ConfigurationError):
+        async with a.router.lifespan_context(a):
+            pass
+    assert a.state.service_ready is False
+
+
+@pytest.mark.anyio
+async def test_config_health_blocks_lifespan_on_strict_wildcard_hosts(
+    test_router: APIRouter,
+) -> None:
+    """A wildcard ALLOWED_HOSTS under strict mode fails config-health."""
+    a = create_app(
+        make_settings(
+            **_BASE,
+            ENVIRONMENT="production",
+            STRICT_PRODUCTION_MODE=True,
+            ALLOWED_HOSTS=["*"],
+            BACKEND_CORS_ORIGINS="https://app.example.com",
+            FRONTEND_HOST="https://app.example.com",
+        ),
+        test_router,
+    )
+    with pytest.raises(ConfigurationError):
+        async with a.router.lifespan_context(a):
+            pass
+    assert a.state.service_ready is False
+
+
+@pytest.mark.anyio
+async def test_user_validators_skipped_when_config_health_fails(
+    test_router: APIRouter,
+) -> None:
+    """A caller validator never runs when config-health fails first."""
+    ran: list[str] = []
+
+    async def user_validator() -> None:
+        ran.append("user")
+
+    a = create_app(
+        make_settings(
+            **_BASE, ENVIRONMENT="production", ALLOWED_HOSTS=["api.example.com"]
+        ),
+        test_router,
+        lifecycle=AppLifecycle(startup_validators=[user_validator]),
+    )
+    with pytest.raises(ConfigurationError):
+        async with a.router.lifespan_context(a):
+            pass
+    assert ran == []
+
+
+@pytest.mark.anyio
+async def test_config_health_runs_before_user_validators(
+    test_router: APIRouter,
+) -> None:
+    """Config-health is prepended: it runs, then caller validators, in order."""
+    order: list[str] = []
+
+    async def user_validator() -> None:
+        # service_ready is still False — startup has not completed yet.
+        order.append("user")
+
+    a = create_app(
+        make_settings(**_BASE),
+        test_router,
+        lifecycle=AppLifecycle(startup_validators=[user_validator]),
+    )
+    async with a.router.lifespan_context(a):
+        order.append("ready")
+    assert order == ["user", "ready"]
+    assert a.state.service_ready is True
+
+
 # ── Lifespan teardown ─────────────────────────────────────────────────────────