fastapi-m8 3.1.0__tar.gz → 3.2.0__tar.gz

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/CHANGELOG.md

@@ -5,6 +5,35 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning:
 
 ---
 
+## [3.2.0] — 2026-06-28 · ungated `/health` constant liveness body (item 9.4 Design B)
+
+> **MINOR — additive, backward-compatible.** The only behaviour change is in the ungated
+> `/health` response: callers without a valid `HEALTH_DETAIL_CREDENTIAL` now always
+> receive `200 {"status":"ok"}` instead of the real aggregate status. Callers that
+> already present the credential are unaffected — they still get the real status, per-check
+> detail, and the 503 HTTP code when checks fail. `auth-sdk-m8` floor unchanged at
+> `>=2.1.0,<3.0.0`.
+
+### Changed
+
+- **Ungated `/health` body is now a constant liveness response (item 9.4 Design B).**
+  Callers without a valid `HEALTH_DETAIL_CREDENTIAL` (or `detail_public=True`) always
+  receive `200 {"status":"ok"}`, regardless of the real aggregate health. Previously the
+  ungated branch returned `{"status": overall.value}`, which leaked `degraded` — a
+  public attack-timing oracle that signals when fail-open degradation is active.
+
+  Health checks are **not run** for ungated requests (pure liveness, no dependency
+  probing); caching is unaffected for credentialed callers. Credentialed callers
+  (valid `X-Internal-Token` matching `HEALTH_DETAIL_CREDENTIAL`, or `detail_public=True`)
+  continue to receive the real aggregate status, the per-check body, and the correct
+  HTTP status code (200 or 503).
+
+- **README `Health Detail Gating` section updated** to document the constant ungated
+  body and the Design B rationale; the defaults-by-layer table row for
+  `HEALTH_DETAIL_CREDENTIAL` updated accordingly.
+
+---
+
 ## [3.1.0] — 2026-06-24/25 · consumer-side post-1.0 remediation (9.1 / 5.5 / 7.x.1 / 9.2 / 10.1) + event-stream 9.1 follow-on
 
 > **MINOR — additive, backward-compatible.** Default behaviour is unchanged: a consumer

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-m8
-Version: 3.1.0
+Version: 3.2.0
 Summary: FastAPI application framework for m8 consumer microservices.
 Author-email: Eli Serra <e.serra173@gmail.com>
 License:                                  Apache License
@@ -724,11 +724,19 @@ do not connect to Redis directly.
 | `REDIS_PASSWORD` | Redis password |
 | `REDIS_SSL` | Enable TLS (`true`/`false`, default `false`) |
 
-### Health Detail Gating (item 9.3)
+### Health Detail Gating (items 9.3 + 9.4)
 
 | Variable | Default | Description |
 |---|---|---|
-| `HEALTH_DETAIL_CREDENTIAL` | — | Optional credential for the `/health` detail body gate. When **unset**, `/health` returns only `{"status": "ok/fail"}` to all callers (fail-closed). When set, callers must present `X-Internal-Token: <value>` (constant-time match) to receive the full per-check breakdown. **Must not equal `PRIVATE_API_SECRET`** — accidental reuse is a fatal startup misconfiguration. Supports `_FILE` mount: set `HEALTH_DETAIL_CREDENTIAL_FILE=/run/secrets/health_cred.txt`. |
+| `HEALTH_DETAIL_CREDENTIAL` | — | Optional credential for the `/health` detail body gate. When **unset**, `/health` returns a constant `{"status":"ok"}` to all callers (fail-closed liveness response). When set, callers must present `X-Internal-Token: <value>` (constant-time match) to receive the real aggregate status, per-check breakdown, and the correct HTTP code (200 or 503). **Must not equal `PRIVATE_API_SECRET`** — accidental reuse is a fatal startup misconfiguration. Supports `_FILE` mount: set `HEALTH_DETAIL_CREDENTIAL_FILE=/run/secrets/health_cred.txt`. |
+
+> **Constant ungated body (item 9.4 Design B):** ungated callers always receive
+> `200 {"status":"ok"}` regardless of the real aggregate health (including `degraded`
+> or `fail`). This prevents operational-state leakage on public-HTTPS stacks: a
+> `degraded` response is a timing oracle that signals fail-open degradation is active.
+> Only callers presenting a valid `HEALTH_DETAIL_CREDENTIAL` see the real status, the
+> per-check detail, and the 503 HTTP code when checks fail. Liveness probes and
+> `{API_PREFIX}/ping` are unaffected.
 
 > **No-reuse enforcement (item 9.3):** at startup, `create_app` asserts that neither
 > `HEALTH_DETAIL_CREDENTIAL` nor `METRICS_SCRAPE_CREDENTIAL` equals `PRIVATE_API_SECRET`.
@@ -827,7 +835,7 @@ inherited from `auth-sdk-m8`, and made *fatal* only when pointed at production.
 | `ALLOWED_HOSTS` | inherited from `CommonSettings`; unset = no host check (dev) | unset under `STRICT_PRODUCTION_MODE` (strict fatal); wildcard `*` under strict |
 | `EVENT_SIGNING_ENABLED` / `EVENT_SIGNING_ACCEPT_UNSIGNED` | inherited secure defaults (signing on, unsigned rejected); the gate fires through the consumer's auto-run config-health (item 7.x.1) | `ENABLED=false` under strict; `ACCEPT_UNSIGNED=true` under production or strict |
 | `METRICS_SCRAPE_CREDENTIAL` | unset = `/metrics` relies on network isolation only; set = constant-time `Authorization: Bearer` gate. **Must not equal `PRIVATE_API_SECRET`** (fatal reuse check at startup). | never fatal (network-isolation is a valid posture); reuse of `PRIVATE_API_SECRET` is fatal |
-| `HEALTH_DETAIL_CREDENTIAL` (item 9.3) | unset = `/health` returns only shallow status to all callers (fail-closed, detail never shown); set = `X-Internal-Token` must match to receive the full per-check breakdown. **Must not equal `PRIVATE_API_SECRET`** (fatal reuse check at startup). | never fatal (no credential = no detail, which is a valid posture); reuse of `PRIVATE_API_SECRET` is fatal |
+| `HEALTH_DETAIL_CREDENTIAL` (items 9.3 + 9.4) | unset = `/health` returns a constant `{"status":"ok"}` to all callers (fail-closed liveness; real status never leaked); set = `X-Internal-Token` must match to receive the real aggregate status, per-check breakdown, and correct HTTP code. **Must not equal `PRIVATE_API_SECRET`** (fatal reuse check at startup). | never fatal (no credential = constant liveness response, which is a valid posture); reuse of `PRIVATE_API_SECRET` is fatal |
 | `INTERNAL_CLIENT_ID` (item 9.1) | unset = legacy single `PRIVATE_API_SECRET`; set = per-consumer bootstrap / service-token auth on private calls | never fatal (must be coordinated with the issuer's `PRIVATE_API_CONSUMERS`) |
 | `_FILE` secret mounts | **inherited** from `CommonSettings` — every secret (`PRIVATE_API_SECRET_FILE`, `DB_PASSWORD_FILE`, `METRICS_SCRAPE_CREDENTIAL_FILE`, `HEALTH_DETAIL_CREDENTIAL_FILE`, …) can be sourced from `/run/secrets/*` with no code change | a referenced `<FIELD>_FILE` path is missing (fails closed at construction) |
 

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/README.md

@@ -468,11 +468,19 @@ do not connect to Redis directly.
 | `REDIS_PASSWORD` | Redis password |
 | `REDIS_SSL` | Enable TLS (`true`/`false`, default `false`) |
 
-### Health Detail Gating (item 9.3)
+### Health Detail Gating (items 9.3 + 9.4)
 
 | Variable | Default | Description |
 |---|---|---|
-| `HEALTH_DETAIL_CREDENTIAL` | — | Optional credential for the `/health` detail body gate. When **unset**, `/health` returns only `{"status": "ok/fail"}` to all callers (fail-closed). When set, callers must present `X-Internal-Token: <value>` (constant-time match) to receive the full per-check breakdown. **Must not equal `PRIVATE_API_SECRET`** — accidental reuse is a fatal startup misconfiguration. Supports `_FILE` mount: set `HEALTH_DETAIL_CREDENTIAL_FILE=/run/secrets/health_cred.txt`. |
+| `HEALTH_DETAIL_CREDENTIAL` | — | Optional credential for the `/health` detail body gate. When **unset**, `/health` returns a constant `{"status":"ok"}` to all callers (fail-closed liveness response). When set, callers must present `X-Internal-Token: <value>` (constant-time match) to receive the real aggregate status, per-check breakdown, and the correct HTTP code (200 or 503). **Must not equal `PRIVATE_API_SECRET`** — accidental reuse is a fatal startup misconfiguration. Supports `_FILE` mount: set `HEALTH_DETAIL_CREDENTIAL_FILE=/run/secrets/health_cred.txt`. |
+
+> **Constant ungated body (item 9.4 Design B):** ungated callers always receive
+> `200 {"status":"ok"}` regardless of the real aggregate health (including `degraded`
+> or `fail`). This prevents operational-state leakage on public-HTTPS stacks: a
+> `degraded` response is a timing oracle that signals fail-open degradation is active.
+> Only callers presenting a valid `HEALTH_DETAIL_CREDENTIAL` see the real status, the
+> per-check detail, and the 503 HTTP code when checks fail. Liveness probes and
+> `{API_PREFIX}/ping` are unaffected.
 
 > **No-reuse enforcement (item 9.3):** at startup, `create_app` asserts that neither
 > `HEALTH_DETAIL_CREDENTIAL` nor `METRICS_SCRAPE_CREDENTIAL` equals `PRIVATE_API_SECRET`.
@@ -571,7 +579,7 @@ inherited from `auth-sdk-m8`, and made *fatal* only when pointed at production.
 | `ALLOWED_HOSTS` | inherited from `CommonSettings`; unset = no host check (dev) | unset under `STRICT_PRODUCTION_MODE` (strict fatal); wildcard `*` under strict |
 | `EVENT_SIGNING_ENABLED` / `EVENT_SIGNING_ACCEPT_UNSIGNED` | inherited secure defaults (signing on, unsigned rejected); the gate fires through the consumer's auto-run config-health (item 7.x.1) | `ENABLED=false` under strict; `ACCEPT_UNSIGNED=true` under production or strict |
 | `METRICS_SCRAPE_CREDENTIAL` | unset = `/metrics` relies on network isolation only; set = constant-time `Authorization: Bearer` gate. **Must not equal `PRIVATE_API_SECRET`** (fatal reuse check at startup). | never fatal (network-isolation is a valid posture); reuse of `PRIVATE_API_SECRET` is fatal |
-| `HEALTH_DETAIL_CREDENTIAL` (item 9.3) | unset = `/health` returns only shallow status to all callers (fail-closed, detail never shown); set = `X-Internal-Token` must match to receive the full per-check breakdown. **Must not equal `PRIVATE_API_SECRET`** (fatal reuse check at startup). | never fatal (no credential = no detail, which is a valid posture); reuse of `PRIVATE_API_SECRET` is fatal |
+| `HEALTH_DETAIL_CREDENTIAL` (items 9.3 + 9.4) | unset = `/health` returns a constant `{"status":"ok"}` to all callers (fail-closed liveness; real status never leaked); set = `X-Internal-Token` must match to receive the real aggregate status, per-check breakdown, and correct HTTP code. **Must not equal `PRIVATE_API_SECRET`** (fatal reuse check at startup). | never fatal (no credential = constant liveness response, which is a valid posture); reuse of `PRIVATE_API_SECRET` is fatal |
 | `INTERNAL_CLIENT_ID` (item 9.1) | unset = legacy single `PRIVATE_API_SECRET`; set = per-consumer bootstrap / service-token auth on private calls | never fatal (must be coordinated with the issuer's `PRIVATE_API_CONSUMERS`) |
 | `_FILE` secret mounts | **inherited** from `CommonSettings` — every secret (`PRIVATE_API_SECRET_FILE`, `DB_PASSWORD_FILE`, `METRICS_SCRAPE_CREDENTIAL_FILE`, `HEALTH_DETAIL_CREDENTIAL_FILE`, …) can be sourced from `/run/secrets/*` with no code change | a referenced `<FIELD>_FILE` path is missing (fails closed at construction) |
 

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/fastapi_m8/_app.py

@@ -368,14 +368,15 @@ def _register_health_route(
             return JSONResponse(
                 {"status": "initializing", "ready": False}, status_code=503
             )
-        results, overall, code = await _gather_health_results(
-            app, checks, config.timeout, config.policy, config.cache_ttl
-        )
-        logger.debug("health: %s (%d checks)", overall.value, len(results))
-        body: dict[str, Any] = {"status": overall.value}
         if config.detail_public or await _is_authorized(request):
+            results, overall, code = await _gather_health_results(
+                app, checks, config.timeout, config.policy, config.cache_ttl
+            )
+            logger.debug("health: %s (%d checks)", overall.value, len(results))
+            body: dict[str, Any] = {"status": overall.value}
             body |= _build_health_body(results, service_name, service_version)
-        return JSONResponse(body, status_code=code)
+            return JSONResponse(body, status_code=code)
+        return JSONResponse({"status": "ok"})
 
 
 def _register_meta_routes(app: FastAPI, settings: ConsumerServiceSettings) -> None:

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/fastapi_m8/_compat.py

@@ -68,6 +68,12 @@ COMPAT_MATRIX: dict[str, dict[str, str]] = {
     # consumer-side 5.5 / 7.x.1 test+observability and 9.2/10.1 docs. The post-1.0
     # breaking-removal majors stay deferred (see CHANGELOG). See CHANGELOG.
     "3.1": {"auth-sdk-m8": ">=2.1.0,<3.0.0"},
+    # 3.2 (MINOR) hardens the ungated /health branch to a constant liveness response
+    # (item 9.4 Design B): ungated callers always receive 200 {"status":"ok"};
+    # only credentialed callers (HEALTH_DETAIL_CREDENTIAL) see the real aggregate
+    # status, per-check detail, and the 503 HTTP code on FAIL. No SDK change required;
+    # auth-sdk-m8 floor stays at >=2.1.0. See CHANGELOG.
+    "3.2": {"auth-sdk-m8": ">=2.1.0,<3.0.0"},
 }
 
 _EXTRAS = "[config,security,fastapi,observability]"

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/fastapi_m8/_version.py

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

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-m8"
-version = "3.1.0"
+version = "3.2.0"
 description = "FastAPI application framework for m8 consumer microservices."
 readme = "README.md"
 license = { file = "LICENSE" }

{fastapi_m8-3.1.0 → fastapi_m8-3.2.0}/tests/test_app.py

@@ -202,18 +202,117 @@ async def test_distinct_credentials_do_not_raise(test_router: APIRouter) -> None
     assert a.state.service_ready is True
 
 
+# ── Health Design B — ungated constant liveness (item 9.4) ───────────────────
+
+
+@pytest.mark.anyio
+async def test_ungated_body_constant_ok_when_degraded(test_router: APIRouter) -> None:
+    """Ungated /health always returns 200 ok even when a check is DEGRADED (9.4)."""
+
+    async def degraded() -> HealthCheckResult:
+        return HealthCheckResult(name="cache", status=HealthStatus.DEGRADED)
+
+    a = create_app(
+        make_settings(**_BASE),
+        test_router,
+        health=HealthConfig(checks=[degraded]),
+    )
+    async with live_client(a) as client:
+        resp = await client.get("/api/health/")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "ok"}
+
+
+@pytest.mark.anyio
+async def test_ungated_body_constant_ok_when_fail(test_router: APIRouter) -> None:
+    """Ungated /health always returns 200 ok even when a check is FAIL — no 503 leak (9.4)."""
+
+    async def bad() -> HealthCheckResult:
+        return HealthCheckResult(name="db", status=HealthStatus.FAIL)
+
+    a = create_app(
+        make_settings(**_BASE),
+        test_router,
+        health=HealthConfig(checks=[bad]),
+    )
+    async with live_client(a) as client:
+        resp = await client.get("/api/health/")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "ok"}
+
+
+@pytest.mark.anyio
+async def test_ungated_no_detail_keys_when_fail(test_router: APIRouter) -> None:
+    """Ungated FAIL response: only constant body, no checks/version keys leak (9.4)."""
+
+    async def bad() -> HealthCheckResult:
+        return HealthCheckResult(name="db", status=HealthStatus.FAIL)
+
+    a = create_app(
+        make_settings(**_BASE),
+        test_router,
+        health=HealthConfig(checks=[bad]),
+    )
+    async with live_client(a) as client:
+        resp = await client.get("/api/health/")
+    body = resp.json()
+    assert "checks" not in body
+    assert "fastapi_m8" not in body
+    assert body.get("status") == "ok"
+
+
+@pytest.mark.anyio
+async def test_gated_fail_returns_503_with_real_status(test_router: APIRouter) -> None:
+    """Credentialed /health with a FAIL check returns 503 and status=fail (9.4)."""
+
+    async def bad() -> HealthCheckResult:
+        return HealthCheckResult(name="db", status=HealthStatus.FAIL)
+
+    a = create_app(
+        make_settings(**_BASE, HEALTH_DETAIL_CREDENTIAL="health-cred"),
+        test_router,
+        health=HealthConfig(checks=[bad]),
+    )
+    async with live_client(a, headers={"X-Internal-Token": "health-cred"}) as client:
+        resp = await client.get("/api/health/")
+    assert resp.status_code == 503
+    body = resp.json()
+    assert body["status"] == "fail"
+    assert "checks" in body
+
+
+@pytest.mark.anyio
+async def test_gated_degraded_returns_real_status(test_router: APIRouter) -> None:
+    """Credentialed /health with a DEGRADED check shows the real status (9.4)."""
+
+    async def degraded() -> HealthCheckResult:
+        return HealthCheckResult(name="cache", status=HealthStatus.DEGRADED)
+
+    a = create_app(
+        make_settings(**_BASE, HEALTH_DETAIL_CREDENTIAL="health-cred"),
+        test_router,
+        health=HealthConfig(checks=[degraded], policy=HealthAggregatePolicy.LENIENT),
+    )
+    async with live_client(a, headers={"X-Internal-Token": "health-cred"}) as client:
+        resp = await client.get("/api/health/")
+    assert resp.status_code == 200
+    assert resp.json()["status"] == "degraded"
+
+
 # ── Health checks ─────────────────────────────────────────────────────────────
 
 
 @pytest.mark.anyio
-async def test_failing_check_returns_503(test_router: APIRouter) -> None:
-    """A FAIL check drives the aggregate to 503."""
+async def test_failing_check_gated_returns_503(test_router: APIRouter) -> None:
+    """A FAIL check drives the aggregate to 503 for credentialed (detail_public) callers."""
 
     async def bad() -> HealthCheckResult:
         return HealthCheckResult(name="db", status=HealthStatus.FAIL)
 
     a = create_app(
-        make_settings(**_BASE), test_router, health=HealthConfig(checks=[bad])
+        make_settings(**_BASE),
+        test_router,
+        health=HealthConfig(checks=[bad], detail_public=True),
     )
     async with live_client(a) as client:
         resp = await client.get("/api/health/")
@@ -222,8 +321,8 @@ async def test_failing_check_returns_503(test_router: APIRouter) -> None:
 
 
 @pytest.mark.anyio
-async def test_degraded_check_lenient_returns_200(test_router: APIRouter) -> None:
-    """A DEGRADED check stays at 200 under LENIENT policy."""
+async def test_degraded_check_lenient_gated_returns_200(test_router: APIRouter) -> None:
+    """A DEGRADED check stays at 200 under LENIENT policy for credentialed callers."""
 
     async def degraded() -> HealthCheckResult:
         return HealthCheckResult(name="minio", status=HealthStatus.DEGRADED)
@@ -234,6 +333,7 @@ async def test_degraded_check_lenient_returns_200(test_router: APIRouter) -> Non
         health=HealthConfig(
             checks=[degraded],
             policy=HealthAggregatePolicy.LENIENT,
+            detail_public=True,
         ),
     )
     async with live_client(a) as client:
@@ -264,7 +364,7 @@ async def test_health_detail_public_exposes_checks(test_router: APIRouter) -> No
 
 @pytest.mark.anyio
 async def test_health_cache_prevents_double_invocation(test_router: APIRouter) -> None:
-    """Within health_cache_ttl a second probe reuses cached results."""
+    """Within health_cache_ttl a second probe reuses cached results (detail_public path)."""
     call_count = 0
 
     async def counted() -> HealthCheckResult:
@@ -275,7 +375,7 @@ async def test_health_cache_prevents_double_invocation(test_router: APIRouter) -
     a = create_app(
         make_settings(**_BASE),
         test_router,
-        health=HealthConfig(checks=[counted], cache_ttl=10.0),
+        health=HealthConfig(checks=[counted], cache_ttl=10.0, detail_public=True),
     )
     async with live_client(a) as client:
         await client.get("/api/health/")