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

fastapi_m8-3.0.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-3.0.0}/CHANGELOG.md

@@ -5,7 +5,125 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning:
 
 ---
 
-## [Unreleased]
+## [3.0.0] — 2026-06-23 · auth-sdk-m8 2.0.0 alignment — single-mount `/ping` + SDK major floor
+
+> **MAJOR.** Two independent breaking changes, either of which alone forces this bump:
+> (1) `mount_service_meta` single-mounts `/ping` at the effective prefix — callers that
+> relied on a bare root `/ping` when a prefix is configured must switch container/sidecar
+> probes to `{API_PREFIX}/ping`; (2) the **required** `auth-sdk-m8` floor crosses a major
+> (`<2.0.0` → `>=2.0.1,<3.0.0`), which removed deprecated SDK APIs — `pip install -U
+> fastapi-m8` now force-upgrades the SDK across that major. (Supersedes the never-released
+> 2.2.0 label: the same work, correctly versioned as a major.)
+
+### ⚠️ Breaking change — `/ping` is now single-mount
+
+`auth-sdk-m8 2.0.0` removed the dual-mount behaviour introduced in 1.5.0. When `API_PREFIX`
+is set (the normal consumer case), `/ping` is now mounted **only** at `{API_PREFIX}/ping`
+(e.g. `/api/ping`). The root `/ping` no longer exists when a prefix is configured.
+
+- **What was true in 2.1.x:** root `GET /ping` always returned 200 regardless of
+  `API_PREFIX`; additionally `GET {API_PREFIX}/ping` was mounted (schema-hidden copy).
+- **What is true in 3.0.x:** only `GET {API_PREFIX}/ping` exists when a prefix is set;
+  only `GET /ping` (root) when no prefix is set. The single mount is **always in the
+  OpenAPI schema** — it is no longer hidden.
+- **Action required:** update container `livenessProbe` / sidecar healthcheck URLs from
+  `/ping` → `{API_PREFIX}/ping` (e.g. `/api/ping`). No Python code change is needed.
+
+### Changed
+
+- **Requires `auth-sdk-m8 >= 2.0.1, < 3.0.0`** (was `>= 1.5.0, < 2.0.0`). The
+  dependency floor, `COMPAT_MATRIX` `3.0` entry, and `pyproject.toml` pin are updated.
+  auth-sdk-m8 2.0.0 also ships `ConsumerScope` / `ConsumerCredential` /
+  `ConsumerCredentialRegistry` / `make_consumer_authorizer` (Phase 9.1) and the
+  `SECURITY.md` mTLS guidance (Phase 9.2) — available to consumers via the SDK without
+  any fastapi-m8 code change.
+
+### Why the floor is a **major** — auth-sdk-m8 2.0.0 dropped deprecated APIs
+
+auth-sdk-m8 2.0.0 is a major because it **removes** every previously-deprecated
+surface. fastapi-m8 was never coupled to any of them, so no consumer-facing code,
+import, or setting changes here — the full suite is green at 100 % against the SDK
+2.0.0 final. The removals, and why fastapi-m8 is already clear of each:
+
+- **Redis Pub/Sub event bus** (`auth_sdk_m8.redis_events`: `EventBus` /
+  `EventPublisher` / `EventSubscriber`). fastapi-m8 consumes auth events over the
+  **fa-auth SSE bridge** (`auth_sdk_m8.events.AuthEventStreamClient`, re-exported as
+  `build_event_stream_client` / `AuthEventStreamClient` since 1.4.0), never the
+  Redis bus. The retained signing helpers moved to `auth_sdk_m8.events._signing`
+  (wire format unchanged); fastapi-m8 does not import them directly.
+- **`ComSecurityHelper.decode_access_token`** + `LEGACY_ACCESS_TOKEN_VALIDATION_CONFIG`.
+  fastapi-m8 validates tokens through `build_auth_deps()` → `build_access_validator`
+  (`TokenValidator`), the non-deprecated path.
+- **`TOKEN_ALGORITHM`** knob. `ConsumerServiceSettings` exposes `ACCESS_TOKEN_ALGORITHM`
+  directly (RS256 default); the deprecated seeding knob was never surfaced.
+- **Module-level `settings_customise_sources()`**. The `_FILE`/Vault source ordering
+  comes from the retained `CommonSettings.settings_customise_sources` **classmethod**
+  that `ConsumerServiceSettings` inherits — unchanged and still regression-tested.
+
+### Security — floor is `>= 2.0.1` to carry the `pydantic-settings` fix
+
+The required `auth-sdk-m8` floor is **`>= 2.0.1`** (not `2.0.0`). auth-sdk-m8 2.0.1
+raised its `[config]` `pydantic-settings` floor `>= 2.14.1` → `>= 2.14.2`, the patch
+that hardens pydantic-settings' nested-secrets source against symlink escape/loop
+traversal. fastapi-m8 does **not** import `pydantic_settings` directly — it inherits
+`CommonSettings` (a `BaseSettings`) from `auth-sdk-m8[config]`, so the fix arrives
+transitively through this floor bump. No separate `pydantic-settings` pin is added
+here: the SDK's `[config]` extra owns that dependency, and duplicating the pin would
+fork a single source of truth.
+
+---
+
+## [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-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-m8
-Version: 2.0.0
+Version: 3.0.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]<3.0.0,>=2.0.1
 Requires-Dist: fastapi>=0.136.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: packaging>=24.0
@@ -308,13 +308,15 @@ health checks; the framework wires the rest.
 |---|---|
 | JWT validation | `build_auth_deps()` + `auth-sdk-m8` validator |
 | Role-based access control | `AuthDeps.get_current_active_admin / _superuser` |
-| Token revocation (stateful mode) | `RemoteRevocationClient` → `fa-auth-m8` private API |
+| Token revocation (stateful mode) | `RemoteRevocationClient` → `fa-auth-m8` private API (optional short-TTL cache via `REVOCATION_CACHE_TTL_SECONDS`) |
+| Auth event stream (optional) | `build_event_stream_client()` → fa-auth SSE bridge for best-effort cache eviction |
 | CORS | Auto-wired from `settings.ALLOWED_ORIGINS` |
-| Metrics middleware | Optional; toggled via `METRICS_ENABLED` |
+| Metrics middleware + `/metrics` | Optional; toggled via `METRICS_ENABLED`, scrape-gated via `METRICS_SCRAPE_CREDENTIAL` |
+| Response security headers | Tiered hardening from `auth-sdk-m8` (HSTS/CSP express opt-in) |
 | 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 {API_PREFIX}/ping` (fail-closed at boot; single-mount at the effective prefix) |
 | Database lifecycle | `create_db_engine()` wrapping SQLAlchemy |
-| Startup validation | `startup_validators` list runs before app signals ready |
+| Startup validation | Auto-run `check_config_health()` + caller `startup_validators` before app signals ready |
 | Lifespan management | Auth teardown + DB pool dispose on shutdown |
 
 **What it is NOT:**
@@ -556,9 +558,17 @@ 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 {API_PREFIX}/ping` liveness probe (→ `{"status": "ok"}`). `/ping` is
+mounted **once** at the effective prefix (single-mount since auth-sdk-m8 2.0.0): when a prefix is
+set, only `{API_PREFIX}/ping` exists so liveness stays reachable behind a prefix-routing reverse
+proxy (Traefik forwards only `PathPrefix({API_PREFIX})`); when no prefix is set, `/ping` is at the
+root. The single mount always appears in the OpenAPI schema. 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.
+
+> **⚠️ Breaking change (3.0.0 / auth-sdk-m8 2.0.0):** root `GET /ping` no longer exists when
+> `API_PREFIX` is set. Update container `livenessProbe` / sidecar healthcheck URLs from `/ping`
+> to `{API_PREFIX}/ping` (e.g. `/api/ping`).
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
@@ -604,6 +614,8 @@ Required only when `TOKEN_MODE=stateful` and `AUTH_SERVICE_ROLE=consumer`.
 |---|---|---|---|
 | `INTROSPECTION_URL` | Yes | — | `POST` endpoint on auth service for JTI revocation checks, e.g. `http://auth_user_service:8000/user/private/v1/jti-status` |
 | `PRIVATE_API_SECRET` | Yes | — | Shared secret for `X-Internal-Token` header (must match auth service) |
+| `ACCESS_REVOCATION_FAILURE_MODE` | No | `fail_closed` | `fail_closed` (default, secure — reject tokens when the check is unverifiable) or `fail_open` (accept on network/HTTP error). |
+| `REVOCATION_CACHE_TTL_SECONDS` | No | `0` | Short-TTL positive validation cache. `0` (default) disables it — every request calls fa-auth. Set to e.g. `30` to trust an `active=True` result for 30 s, skipping the HTTP round-trip; stream events (`session-revoked`/`user-deleted`) evict affected entries and an unresumable gap flushes all (requires the event-stream client). |
 
 ### Auth Event Stream (fa-auth SSE bridge)
 
@@ -692,8 +704,17 @@ do not connect to Redis directly.
 
 | Variable | Default | Description |
 |---|---|---|
-| `METRICS_ENABLED` | `false` | Enable Prometheus metrics middleware |
+| `METRICS_ENABLED` | `false` | Enable Prometheus metrics middleware and the `/metrics` route |
 | `METRICS_GROUPS` | — | Comma-separated groups: `traffic`, `performance`, `reliability`, `health`, `auth`, or `all` |
+| `METRICS_SCRAPE_CREDENTIAL` | — | Optional static bearer credential for the `/metrics` scrape endpoint. When set, requests must present `Authorization: Bearer <value>` (constant-time match). When unset, `/metrics` relies on network isolation only. |
+
+> **`/metrics` route:** when `METRICS_ENABLED=true`, `create_app` also registers a
+> `GET /metrics` endpoint (hidden from the schema) rendering the Prometheus registry.
+> Set `METRICS_SCRAPE_CREDENTIAL` to gate scrapes with a bearer credential — configure
+> Prometheus `scrape_configs.authorization.credentials` to match. The revocation cache
+> (when enabled) also emits `revocation_cache_lookups_total{result="hit"|"miss"}` and a
+> `revocation_cache_ttl_seconds` gauge on the same registry; no JTI, user ID, or secret
+> is ever used as a label or value.
 
 ### OpenAPI / Docs
 
@@ -811,7 +832,11 @@ app = create_app(
 
 **Lifespan sequence:**
 
-1. Run `lifecycle.startup_validators` — raise any exception to prevent ready signal.
+1. Run the auto-prepended `check_config_health()` validator (from `auth-sdk-m8`),
+   then `lifecycle.startup_validators` — raise any exception to prevent the ready
+   signal. The config-health check runs first, so a fatal misconfiguration (e.g.
+   production `localhost` CORS origins, a wildcard `ALLOWED_HOSTS` under strict mode)
+   aborts startup with `ConfigurationError` before any caller validators run.
 2. Enter `lifecycle.lifespan_extras` context (if provided).
 3. Set `app.state.service_ready = True`.
 4. *(app serves traffic)*
@@ -876,6 +901,7 @@ Returns a frozen dataclass with everything needed for route protection.
 | `is_active` | `bool` | Account active flag |
 | `is_superuser` | `bool` | Superuser flag |
 | `email_verified` | `bool` | Email verification status |
+| `tenant_id` | `uuid.UUID \| None` | Tenant claim (populated when the token carries `tenant_id`; `None` for untenanted/legacy tokens). Requires `auth-sdk-m8 ≥ 1.3.0`. |
 
 ---
 
@@ -1074,8 +1100,8 @@ HTTP 200
   ],
   "service": "Item Service",
   "version": "1.0.0",
-  "fastapi_m8": "1.3.0",
-  "auth_sdk_m8": "1.1.x"
+  "fastapi_m8": "3.0.0",
+  "auth_sdk_m8": "2.0.x"
 }
 ```
 
@@ -1326,6 +1352,12 @@ async def test_health(client):
 
 | `fastapi-m8` | `auth-sdk-m8` | Python |
 |---|---|---|
+| `3.0.0` | `>=2.0.1, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
+| `2.1.0` | `>=1.5.0, <2.0.0` | 3.11, 3.12, 3.13 |
+| `2.0.0` | `>=1.4.0, <2.0.0` | 3.11, 3.12, 3.13 |
+| `1.6.0` | `>=1.3.0, <2.0.0` | 3.11, 3.12, 3.13 |
+| `1.5.0` | `>=1.2.1, <2.0.0` | 3.11, 3.12, 3.13 |
+| `1.4.0` | `>=1.2.0, <2.0.0` | 3.11, 3.12, 3.13 |
 | `1.3.0` | `>=1.1.0, <2.0.0` | 3.11, 3.12, 3.13 |
 | `1.2.0` | `>=1.0.0, <2.0.0` | 3.11, 3.12, 3.13 |
 | `1.1.4` | `>=0.7.3, <0.8.0` | 3.11, 3.12, 3.13 |
@@ -1341,9 +1373,11 @@ Check at runtime:
 ```python
 from fastapi_m8 import CAPABILITIES, __version__
 
-print(__version__)          # "1.3.0"
-print(CAPABILITIES)         # {"async": False, "db_optional": True, ...}
+print(__version__)          # "3.0.0"
+print(CAPABILITIES)         # {"async": False, "plugin_system": False,
+                            #  "trace_context": False, "db_optional": True,
+                            #  "health_detail_gating": True}
 ```
 
-`create_async_app()` is a planned API stub for v2.0. Calling it raises
-`NotImplementedError`.
+`create_async_app()` is a reserved stub for a future async app surface. Calling it
+raises `NotImplementedError`; check `CAPABILITIES["async"]` before using it.

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

@@ -52,13 +52,15 @@ health checks; the framework wires the rest.
 |---|---|
 | JWT validation | `build_auth_deps()` + `auth-sdk-m8` validator |
 | Role-based access control | `AuthDeps.get_current_active_admin / _superuser` |
-| Token revocation (stateful mode) | `RemoteRevocationClient` → `fa-auth-m8` private API |
+| Token revocation (stateful mode) | `RemoteRevocationClient` → `fa-auth-m8` private API (optional short-TTL cache via `REVOCATION_CACHE_TTL_SECONDS`) |
+| Auth event stream (optional) | `build_event_stream_client()` → fa-auth SSE bridge for best-effort cache eviction |
 | CORS | Auto-wired from `settings.ALLOWED_ORIGINS` |
-| Metrics middleware | Optional; toggled via `METRICS_ENABLED` |
+| Metrics middleware + `/metrics` | Optional; toggled via `METRICS_ENABLED`, scrape-gated via `METRICS_SCRAPE_CREDENTIAL` |
+| Response security headers | Tiered hardening from `auth-sdk-m8` (HSTS/CSP express opt-in) |
 | 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 {API_PREFIX}/ping` (fail-closed at boot; single-mount at the effective prefix) |
 | Database lifecycle | `create_db_engine()` wrapping SQLAlchemy |
-| Startup validation | `startup_validators` list runs before app signals ready |
+| Startup validation | Auto-run `check_config_health()` + caller `startup_validators` before app signals ready |
 | Lifespan management | Auth teardown + DB pool dispose on shutdown |
 
 **What it is NOT:**
@@ -300,9 +302,17 @@ 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 {API_PREFIX}/ping` liveness probe (→ `{"status": "ok"}`). `/ping` is
+mounted **once** at the effective prefix (single-mount since auth-sdk-m8 2.0.0): when a prefix is
+set, only `{API_PREFIX}/ping` exists so liveness stays reachable behind a prefix-routing reverse
+proxy (Traefik forwards only `PathPrefix({API_PREFIX})`); when no prefix is set, `/ping` is at the
+root. The single mount always appears in the OpenAPI schema. 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.
+
+> **⚠️ Breaking change (3.0.0 / auth-sdk-m8 2.0.0):** root `GET /ping` no longer exists when
+> `API_PREFIX` is set. Update container `livenessProbe` / sidecar healthcheck URLs from `/ping`
+> to `{API_PREFIX}/ping` (e.g. `/api/ping`).
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
@@ -348,6 +358,8 @@ Required only when `TOKEN_MODE=stateful` and `AUTH_SERVICE_ROLE=consumer`.
 |---|---|---|---|
 | `INTROSPECTION_URL` | Yes | — | `POST` endpoint on auth service for JTI revocation checks, e.g. `http://auth_user_service:8000/user/private/v1/jti-status` |
 | `PRIVATE_API_SECRET` | Yes | — | Shared secret for `X-Internal-Token` header (must match auth service) |
+| `ACCESS_REVOCATION_FAILURE_MODE` | No | `fail_closed` | `fail_closed` (default, secure — reject tokens when the check is unverifiable) or `fail_open` (accept on network/HTTP error). |
+| `REVOCATION_CACHE_TTL_SECONDS` | No | `0` | Short-TTL positive validation cache. `0` (default) disables it — every request calls fa-auth. Set to e.g. `30` to trust an `active=True` result for 30 s, skipping the HTTP round-trip; stream events (`session-revoked`/`user-deleted`) evict affected entries and an unresumable gap flushes all (requires the event-stream client). |
 
 ### Auth Event Stream (fa-auth SSE bridge)
 
@@ -436,8 +448,17 @@ do not connect to Redis directly.
 
 | Variable | Default | Description |
 |---|---|---|
-| `METRICS_ENABLED` | `false` | Enable Prometheus metrics middleware |
+| `METRICS_ENABLED` | `false` | Enable Prometheus metrics middleware and the `/metrics` route |
 | `METRICS_GROUPS` | — | Comma-separated groups: `traffic`, `performance`, `reliability`, `health`, `auth`, or `all` |
+| `METRICS_SCRAPE_CREDENTIAL` | — | Optional static bearer credential for the `/metrics` scrape endpoint. When set, requests must present `Authorization: Bearer <value>` (constant-time match). When unset, `/metrics` relies on network isolation only. |
+
+> **`/metrics` route:** when `METRICS_ENABLED=true`, `create_app` also registers a
+> `GET /metrics` endpoint (hidden from the schema) rendering the Prometheus registry.
+> Set `METRICS_SCRAPE_CREDENTIAL` to gate scrapes with a bearer credential — configure
+> Prometheus `scrape_configs.authorization.credentials` to match. The revocation cache
+> (when enabled) also emits `revocation_cache_lookups_total{result="hit"|"miss"}` and a
+> `revocation_cache_ttl_seconds` gauge on the same registry; no JTI, user ID, or secret
+> is ever used as a label or value.
 
 ### OpenAPI / Docs
 
@@ -555,7 +576,11 @@ app = create_app(
 
 **Lifespan sequence:**
 
-1. Run `lifecycle.startup_validators` — raise any exception to prevent ready signal.
+1. Run the auto-prepended `check_config_health()` validator (from `auth-sdk-m8`),
+   then `lifecycle.startup_validators` — raise any exception to prevent the ready
+   signal. The config-health check runs first, so a fatal misconfiguration (e.g.
+   production `localhost` CORS origins, a wildcard `ALLOWED_HOSTS` under strict mode)
+   aborts startup with `ConfigurationError` before any caller validators run.
 2. Enter `lifecycle.lifespan_extras` context (if provided).
 3. Set `app.state.service_ready = True`.
 4. *(app serves traffic)*
@@ -620,6 +645,7 @@ Returns a frozen dataclass with everything needed for route protection.
 | `is_active` | `bool` | Account active flag |
 | `is_superuser` | `bool` | Superuser flag |
 | `email_verified` | `bool` | Email verification status |
+| `tenant_id` | `uuid.UUID \| None` | Tenant claim (populated when the token carries `tenant_id`; `None` for untenanted/legacy tokens). Requires `auth-sdk-m8 ≥ 1.3.0`. |
 
 ---
 
@@ -818,8 +844,8 @@ HTTP 200
   ],
   "service": "Item Service",
   "version": "1.0.0",
-  "fastapi_m8": "1.3.0",
-  "auth_sdk_m8": "1.1.x"
+  "fastapi_m8": "3.0.0",
+  "auth_sdk_m8": "2.0.x"
 }
 ```
 
@@ -1070,6 +1096,12 @@ async def test_health(client):
 
 | `fastapi-m8` | `auth-sdk-m8` | Python |
 |---|---|---|
+| `3.0.0` | `>=2.0.1, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
+| `2.1.0` | `>=1.5.0, <2.0.0` | 3.11, 3.12, 3.13 |
+| `2.0.0` | `>=1.4.0, <2.0.0` | 3.11, 3.12, 3.13 |
+| `1.6.0` | `>=1.3.0, <2.0.0` | 3.11, 3.12, 3.13 |
+| `1.5.0` | `>=1.2.1, <2.0.0` | 3.11, 3.12, 3.13 |
+| `1.4.0` | `>=1.2.0, <2.0.0` | 3.11, 3.12, 3.13 |
 | `1.3.0` | `>=1.1.0, <2.0.0` | 3.11, 3.12, 3.13 |
 | `1.2.0` | `>=1.0.0, <2.0.0` | 3.11, 3.12, 3.13 |
 | `1.1.4` | `>=0.7.3, <0.8.0` | 3.11, 3.12, 3.13 |
@@ -1085,9 +1117,11 @@ Check at runtime:
 ```python
 from fastapi_m8 import CAPABILITIES, __version__
 
-print(__version__)          # "1.3.0"
-print(CAPABILITIES)         # {"async": False, "db_optional": True, ...}
+print(__version__)          # "3.0.0"
+print(CAPABILITIES)         # {"async": False, "plugin_system": False,
+                            #  "trace_context": False, "db_optional": True,
+                            #  "health_detail_gating": True}
 ```
 
-`create_async_app()` is a planned API stub for v2.0. Calling it raises
-`NotImplementedError`.
+`create_async_app()` is a reserved stub for a future async app surface. Calling it
+raises `NotImplementedError`; check `CAPABILITIES["async"]` before using it.

{fastapi_m8-2.0.0 → fastapi_m8-3.0.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-3.0.0}/fastapi_m8/_compat.py

@@ -42,6 +42,24 @@ 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"},
+    # 3.0 (MAJOR) aligns with auth-sdk-m8 2.0.0 on two breaking fronts: (1) /ping
+    # collapses to a single mount — when a prefix is set it lives only at
+    # {prefix}/ping (no root copy), always in the OpenAPI schema, so consumers
+    # that relied on root /ping behind a prefix must switch to {API_PREFIX}/ping;
+    # (2) the required auth-sdk-m8 floor crosses a major (<2.0.0 → >=2.0.1), which
+    # removed deprecated SDK APIs (Redis bus, decode_access_token, TOKEN_ALGORITHM,
+    # module-level settings_customise_sources). Either alone forces this major bump.
+    # Floor is >=2.0.1 (not 2.0.0) so the transitive pydantic-settings dep is
+    # >=2.14.2, carrying the SDK 2.0.1 nested-secrets symlink-traversal fix. See
+    # CHANGELOG.
+    "3.0": {"auth-sdk-m8": ">=2.0.1,<3.0.0"},
 }
 
 _EXTRAS = "[config,security,fastapi,observability]"