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

{fastapi_m8-3.1.0 → fastapi_m8-3.3.0}/.github/workflows/CI.yaml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: ["main"]
 
+permissions:
+  contents: read
+
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
@@ -13,10 +16,10 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.14"
           cache: "pip"
@@ -33,10 +36,10 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.14"
           cache: "pip"
@@ -50,10 +53,10 @@ jobs:
   security:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.14"
 
@@ -84,10 +87,10 @@ jobs:
         python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -100,7 +103,7 @@ jobs:
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.11' && github.actor != 'dependabot[bot]'
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage.xml
@@ -112,3 +115,17 @@ jobs:
         with:
           project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
           coverage-reports: coverage.xml
+
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

{fastapi_m8-3.1.0 → fastapi_m8-3.3.0}/.github/workflows/PiPy.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.x"
 
@@ -52,8 +52,6 @@ jobs:
 
       - name: Publish release distributions to PyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
-        with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
 
   sbom:
     name: Generate & attach SBOM
@@ -65,16 +63,16 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.x"
 
       - name: Install package
         run: pip install -e ".[all]"
 
-      - uses: anchore/sbom-action@f325610c9f50a54015d37c8d16cb3b0e2c8f4de0 # v0.18.0
+      - uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
         with:
           artifact-name: fastapi-m8-${{ github.event.release.tag_name }}.sbom.spdx.json
           format: spdx-json

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

@@ -5,6 +5,96 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning:
 
 ---
 
+## [Unreleased]
+
+---
+
+## [3.3.0] — 2026-07-02 · legacy consumer private-auth is development-only (item 11.2b) + supply-chain hardening (11.6/11.7/11.8)
+
+> **MINOR — security remediation, no public API removed.** The only runtime behaviour change
+> is a new fail-closed boot check: a production/strict consumer (`ENVIRONMENT=production` or
+> `STRICT_PRODUCTION_MODE=true`) that still runs legacy single-shared-secret private auth
+> (`INTROSPECTION_URL` set, `INTERNAL_CLIENT_ID` unset) now raises at settings construction.
+> Such a consumer already could not authenticate against a hardened `fa-auth-m8` issuer
+> (item 11.2a retired the shared-secret fallback), so this converts a latent deployment fault
+> into an explicit error rather than changing any working configuration. Local/development is
+> unaffected. `auth-sdk-m8` floor raised to `>=2.1.1,<3.0.0` (carries the SDK's latest
+> dependency/CI maintenance release; no new SDK API is required).
+
+### Security
+
+- **Legacy single-shared-secret private-auth mode is now development-only (OWASP remediation
+  item 11.2b).** `ConsumerServiceSettings` gained a `model_validator` that fails settings
+  construction when a production/strict consumer (`ENVIRONMENT=production` or
+  `STRICT_PRODUCTION_MODE=true`) has `INTROSPECTION_URL` configured but no
+  `INTERNAL_CLIENT_ID`. `fa-auth-m8` has retired the issuer's legacy single-shared-secret
+  private-API fallback (item 11.2a), so a production/strict consumer left in legacy
+  token-only mode is guaranteed to fail against a hardened issuer — this turns that latent
+  deployment fault into an explicit, fail-closed boot error. Legacy mode remains valid for
+  local/development.
+- **Coherent per-consumer private-auth group validation.** The same validator now rejects
+  (in every environment) `SERVICE_TOKEN_EXCHANGE_ENABLED=true` without `INTERNAL_CLIENT_ID`
+  (exchange has no identity to present and would silently downgrade to legacy) and
+  `INTERNAL_CLIENT_ID` set without `PRIVATE_API_SECRET` (per-consumer mode needs its
+  bootstrap secret). No validation message echoes a secret value.
+- **PyPI Trusted Publishing is now the sole publish mechanism (item 11.6).** The long-lived
+  `PYPI_API_TOKEN` secret was removed from `PiPy.yml`; the release job publishes via OIDC
+  (`id-token: write`) into a protected `pypi` environment. No API token is stored in the repo
+  or referenced by any workflow.
+- **CI policy tests (item 11.7).** New `tests/test_ci_policy.py` asserts the supply-chain
+  posture in CI: no `PYPI_API_TOKEN` reference, `id-token: write` present, the protected
+  `pypi` environment is used, the duplicate `ci.yml` is gone, the secret-scan job is present,
+  every action is SHA-pinned in both workflows, and key runtime packages are pinned in
+  `constraints-all.txt`.
+- **Locked dependency constraints (item 11.8).** `constraints.txt` and `constraints-all.txt`
+  are generated via `pip-compile` from public PyPI only (no custom index), giving CI a
+  reproducible, fully-pinned install closure.
+
+### Changed
+
+- CI workflows consolidated — the secret-scan job was absorbed into `CI.yaml` and the
+  duplicate `ci.yml` removed; dependabot SHA bumps for `checkout`, `setup-python`,
+  `sbom-action`, `codecov-action`, and `gitleaks-action` applied across both workflows.
+- `COMPAT_MATRIX` gains a `3.3` entry (`auth-sdk-m8 >=2.1.0,<3.0.0`, unchanged floor).
+
+### Docs
+
+- README *Per-consumer internal auth* section and the defaults-by-layer table now document
+  that legacy mode is development-only and fatal under production/strict; removed wording
+  that implied the issuer still offers a shared-secret fallback. Compatibility table updated
+  with the `3.1.0`–`3.3.0` rows.
+
+---
+
+## [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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-m8
-Version: 3.1.0
+Version: 3.3.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]<3.0.0,>=2.1.0
+Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<3.0.0,>=2.1.1
 Requires-Dist: fastapi>=0.136.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: packaging>=24.0
@@ -620,18 +620,27 @@ Required only when `TOKEN_MODE=stateful` and `AUTH_SERVICE_ROLE=consumer`.
 #### Per-consumer internal auth (item 9.1)
 
 By default a consumer authenticates private calls with the single shared
-`PRIVATE_API_SECRET` (legacy mode), which matches fa-auth's fallback when it has no
-`PRIVATE_API_CONSUMERS` registry. Set `INTERNAL_CLIENT_ID` to switch to the
-**per-consumer** model: `PRIVATE_API_SECRET` becomes this service's *bootstrap*
-secret, fa-auth authorizes each private route by the credential's granted scope
-(deny-by-default), and the blast radius collapses from the whole fleet to one
-consumer. Optionally exchange the bootstrap credential for short-TTL `Authorization:
-Bearer` service tokens so rotation comes for free from the token TTL. Selection is
-purely by config — the home lab keeps working untouched.
+`PRIVATE_API_SECRET` (legacy mode). **Legacy mode is development-only.** `fa-auth-m8`
+has retired the issuer's legacy single-shared-secret fallback — its
+`PRIVATE_API_CONSUMERS` registry is required in production/strict (item 11.2a) — so a
+production/strict consumer left in legacy mode is guaranteed to fail against a hardened
+issuer. Set `INTERNAL_CLIENT_ID` to switch to the **per-consumer** model:
+`PRIVATE_API_SECRET` becomes this service's *bootstrap* secret, fa-auth authorizes each
+private route by the credential's granted scope (deny-by-default), and the blast radius
+collapses from the whole fleet to one consumer. Optionally exchange the bootstrap
+credential for short-TTL `Authorization: Bearer` service tokens so rotation comes for
+free from the token TTL. Selection is purely by config — the home lab keeps working
+untouched.
+
+> **Fatal under production/strict (item 11.2b).** When `ENVIRONMENT=production` or
+> `STRICT_PRODUCTION_MODE=true`, settings validation fails at construction if
+> `INTROSPECTION_URL` is set but `INTERNAL_CLIENT_ID` is unset. Two coherence rules
+> apply in every environment: `SERVICE_TOKEN_EXCHANGE_ENABLED=true` requires
+> `INTERNAL_CLIENT_ID`, and setting `INTERNAL_CLIENT_ID` requires `PRIVATE_API_SECRET`.
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `INTERNAL_CLIENT_ID` | No | — | This consumer's `X-Internal-Client` id. Unset = legacy single-secret mode; set = per-consumer bootstrap mode. |
+| `INTERNAL_CLIENT_ID` | No (Yes in prod/strict when `INTROSPECTION_URL` is set) | — | This consumer's `X-Internal-Client` id. Unset = legacy single-secret mode (development-only; rejected under production/strict once `INTROSPECTION_URL` is set); set = per-consumer bootstrap mode. |
 | `SERVICE_TOKEN_EXCHANGE_ENABLED` | No | `false` | Exchange the bootstrap credential for short-TTL Bearer service tokens at `{issuer}/private/v1/service-token` (requires `INTERNAL_CLIENT_ID`). |
 | `SERVICE_TOKEN_SCOPES` | No | `["introspection"]` | Scopes requested when minting a service token; fa-auth narrows to the subset the bootstrap credential was granted. |
 | `SERVICE_TOKEN_REFRESH_LEEWAY_SECONDS` | No | `30` | Refresh a cached service token this many seconds before its `exp` so a call never races expiry. |
@@ -724,11 +733,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,8 +844,8 @@ 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 |
-| `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`) |
+| `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` (items 9.1 + 11.2b) | unset = legacy single `PRIVATE_API_SECRET` (development-only); set = per-consumer bootstrap / service-token auth on private calls (must be coordinated with the issuer's `PRIVATE_API_CONSUMERS`) | **fatal** under production/strict when `INTROSPECTION_URL` is set but `INTERNAL_CLIENT_ID` is unset; also fatal (any env) when `SERVICE_TOKEN_EXCHANGE_ENABLED=true` without `INTERNAL_CLIENT_ID`, or `INTERNAL_CLIENT_ID` set without `PRIVATE_API_SECRET` |
 | `_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) |
 
 ---
@@ -1405,6 +1422,9 @@ async def test_health(client):
 
 | `fastapi-m8` | `auth-sdk-m8` | Python |
 |---|---|---|
+| `3.3.0` | `>=2.1.1, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
+| `3.2.0` | `>=2.1.0, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
+| `3.1.0` | `>=2.1.0, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
 | `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 |

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

@@ -364,18 +364,27 @@ Required only when `TOKEN_MODE=stateful` and `AUTH_SERVICE_ROLE=consumer`.
 #### Per-consumer internal auth (item 9.1)
 
 By default a consumer authenticates private calls with the single shared
-`PRIVATE_API_SECRET` (legacy mode), which matches fa-auth's fallback when it has no
-`PRIVATE_API_CONSUMERS` registry. Set `INTERNAL_CLIENT_ID` to switch to the
-**per-consumer** model: `PRIVATE_API_SECRET` becomes this service's *bootstrap*
-secret, fa-auth authorizes each private route by the credential's granted scope
-(deny-by-default), and the blast radius collapses from the whole fleet to one
-consumer. Optionally exchange the bootstrap credential for short-TTL `Authorization:
-Bearer` service tokens so rotation comes for free from the token TTL. Selection is
-purely by config — the home lab keeps working untouched.
+`PRIVATE_API_SECRET` (legacy mode). **Legacy mode is development-only.** `fa-auth-m8`
+has retired the issuer's legacy single-shared-secret fallback — its
+`PRIVATE_API_CONSUMERS` registry is required in production/strict (item 11.2a) — so a
+production/strict consumer left in legacy mode is guaranteed to fail against a hardened
+issuer. Set `INTERNAL_CLIENT_ID` to switch to the **per-consumer** model:
+`PRIVATE_API_SECRET` becomes this service's *bootstrap* secret, fa-auth authorizes each
+private route by the credential's granted scope (deny-by-default), and the blast radius
+collapses from the whole fleet to one consumer. Optionally exchange the bootstrap
+credential for short-TTL `Authorization: Bearer` service tokens so rotation comes for
+free from the token TTL. Selection is purely by config — the home lab keeps working
+untouched.
+
+> **Fatal under production/strict (item 11.2b).** When `ENVIRONMENT=production` or
+> `STRICT_PRODUCTION_MODE=true`, settings validation fails at construction if
+> `INTROSPECTION_URL` is set but `INTERNAL_CLIENT_ID` is unset. Two coherence rules
+> apply in every environment: `SERVICE_TOKEN_EXCHANGE_ENABLED=true` requires
+> `INTERNAL_CLIENT_ID`, and setting `INTERNAL_CLIENT_ID` requires `PRIVATE_API_SECRET`.
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `INTERNAL_CLIENT_ID` | No | — | This consumer's `X-Internal-Client` id. Unset = legacy single-secret mode; set = per-consumer bootstrap mode. |
+| `INTERNAL_CLIENT_ID` | No (Yes in prod/strict when `INTROSPECTION_URL` is set) | — | This consumer's `X-Internal-Client` id. Unset = legacy single-secret mode (development-only; rejected under production/strict once `INTROSPECTION_URL` is set); set = per-consumer bootstrap mode. |
 | `SERVICE_TOKEN_EXCHANGE_ENABLED` | No | `false` | Exchange the bootstrap credential for short-TTL Bearer service tokens at `{issuer}/private/v1/service-token` (requires `INTERNAL_CLIENT_ID`). |
 | `SERVICE_TOKEN_SCOPES` | No | `["introspection"]` | Scopes requested when minting a service token; fa-auth narrows to the subset the bootstrap credential was granted. |
 | `SERVICE_TOKEN_REFRESH_LEEWAY_SECONDS` | No | `30` | Refresh a cached service token this many seconds before its `exp` so a call never races expiry. |
@@ -468,11 +477,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,8 +588,8 @@ 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 |
-| `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`) |
+| `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` (items 9.1 + 11.2b) | unset = legacy single `PRIVATE_API_SECRET` (development-only); set = per-consumer bootstrap / service-token auth on private calls (must be coordinated with the issuer's `PRIVATE_API_CONSUMERS`) | **fatal** under production/strict when `INTROSPECTION_URL` is set but `INTERNAL_CLIENT_ID` is unset; also fatal (any env) when `SERVICE_TOKEN_EXCHANGE_ENABLED=true` without `INTERNAL_CLIENT_ID`, or `INTERNAL_CLIENT_ID` set without `PRIVATE_API_SECRET` |
 | `_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) |
 
 ---
@@ -1149,6 +1166,9 @@ async def test_health(client):
 
 | `fastapi-m8` | `auth-sdk-m8` | Python |
 |---|---|---|
+| `3.3.0` | `>=2.1.1, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
+| `3.2.0` | `>=2.1.0, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
+| `3.1.0` | `>=2.1.0, <3.0.0` | 3.11, 3.12, 3.13, 3.14 |
 | `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 |

fastapi_m8-3.3.0/constraints-all.txt

@@ -0,0 +1,237 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --extra=all --extra=dev --no-emit-index-url --output-file=constraints-all.txt pyproject.toml
+#
+alembic==1.18.5
+    # via fastapi-m8
+annotated-doc==0.0.4
+    # via fastapi
+annotated-types==0.7.0
+    # via pydantic
+anyio[trio]==4.14.1
+    # via
+    #   fastapi-m8
+    #   fastapi-m8 (pyproject.toml)
+    #   httpx
+    #   pytest-anyio
+    #   starlette
+asgi-lifespan==2.1.0
+    # via fastapi-m8 (pyproject.toml)
+ast-serialize==0.6.0
+    # via mypy
+attrs==26.1.0
+    # via
+    #   outcome
+    #   trio
+auth-sdk-m8[config,events,fastapi,observability,security]==2.1.1
+    # via
+    #   fastapi-m8
+    #   fastapi-m8 (pyproject.toml)
+bandit==1.9.4
+    # via fastapi-m8 (pyproject.toml)
+boolean-py==5.0
+    # via license-expression
+cachecontrol[filecache]==0.14.4
+    # via
+    #   cachecontrol
+    #   pip-audit
+certifi==2026.6.17
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+cffi==2.0.0
+    # via cryptography
+charset-normalizer==3.4.7
+    # via requests
+coverage[toml]==7.14.3
+    # via
+    #   fastapi-m8 (pyproject.toml)
+    #   pytest-cov
+cryptography==49.0.0
+    # via auth-sdk-m8
+cyclonedx-python-lib==11.11.0
+    # via pip-audit
+defusedxml==0.7.1
+    # via py-serializable
+dnspython==2.8.0
+    # via email-validator
+email-validator==2.3.0
+    # via auth-sdk-m8
+fastapi==0.139.0
+    # via
+    #   auth-sdk-m8
+    #   fastapi-m8
+    #   fastapi-m8 (pyproject.toml)
+fastapi-m8[all,db,mysql,postgres] @ file:///workspace/fastapi-m8
+    # via fastapi-m8 (pyproject.toml)
+filelock==3.29.4
+    # via cachecontrol
+greenlet==3.5.3
+    # via sqlalchemy
+h11==0.16.0
+    # via httpcore
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   auth-sdk-m8
+    #   fastapi-m8
+    #   fastapi-m8 (pyproject.toml)
+idna==3.18
+    # via
+    #   anyio
+    #   email-validator
+    #   httpx
+    #   requests
+    #   trio
+iniconfig==2.3.0
+    # via pytest
+librt==0.12.0
+    # via mypy
+license-expression==30.4.4
+    # via cyclonedx-python-lib
+mako==1.3.12
+    # via alembic
+markdown-it-py==4.2.0
+    # via rich
+markupsafe==3.0.3
+    # via mako
+mdurl==0.1.2
+    # via markdown-it-py
+msgpack==1.2.1
+    # via cachecontrol
+mypy==2.1.0
+    # via fastapi-m8 (pyproject.toml)
+mypy-extensions==1.1.0
+    # via mypy
+outcome==1.3.0.post0
+    # via trio
+packageurl-python==0.17.6
+    # via cyclonedx-python-lib
+packaging==26.2
+    # via
+    #   fastapi-m8
+    #   fastapi-m8 (pyproject.toml)
+    #   pip-audit
+    #   pip-requirements-parser
+    #   pytest
+pathspec==1.1.1
+    # via mypy
+pip-api==0.0.34
+    # via pip-audit
+pip-audit==2.10.1
+    # via fastapi-m8 (pyproject.toml)
+pip-requirements-parser==32.0.1
+    # via pip-audit
+platformdirs==4.10.0
+    # via pip-audit
+pluggy==1.6.0
+    # via
+    #   pytest
+    #   pytest-cov
+prometheus-client==0.25.0
+    # via auth-sdk-m8
+psycopg2-binary==2.9.12
+    # via fastapi-m8
+py-serializable==2.1.0
+    # via cyclonedx-python-lib
+pycparser==3.0
+    # via cffi
+pydantic==2.13.4
+    # via
+    #   auth-sdk-m8
+    #   fastapi
+    #   pydantic-settings
+    #   sqlmodel
+pydantic-core==2.46.4
+    # via pydantic
+pydantic-settings==2.14.2
+    # via auth-sdk-m8
+pygments==2.20.0
+    # via
+    #   pytest
+    #   rich
+pyjwt==2.13.0
+    # via auth-sdk-m8
+pymysql==1.2.0
+    # via fastapi-m8
+pyparsing==3.3.2
+    # via pip-requirements-parser
+pytest==9.1.1
+    # via
+    #   fastapi-m8 (pyproject.toml)
+    #   pytest-anyio
+    #   pytest-cov
+pytest-anyio==0.0.0
+    # via fastapi-m8 (pyproject.toml)
+pytest-cov==7.1.0
+    # via fastapi-m8 (pyproject.toml)
+python-dotenv==1.2.2
+    # via pydantic-settings
+pyyaml==6.0.3
+    # via bandit
+requests==2.34.2
+    # via
+    #   cachecontrol
+    #   pip-audit
+rich==15.0.0
+    # via
+    #   bandit
+    #   pip-audit
+ruff==0.15.20
+    # via fastapi-m8 (pyproject.toml)
+sniffio==1.3.1
+    # via
+    #   asgi-lifespan
+    #   trio
+sortedcontainers==2.4.0
+    # via
+    #   cyclonedx-python-lib
+    #   trio
+sqlalchemy==2.0.51
+    # via
+    #   alembic
+    #   fastapi-m8
+    #   sqlmodel
+sqlmodel==0.0.39
+    # via fastapi-m8
+starlette==1.3.1
+    # via
+    #   auth-sdk-m8
+    #   fastapi
+stevedore==5.8.0
+    # via bandit
+tenacity==9.1.4
+    # via fastapi-m8 (pyproject.toml)
+tomli==2.4.1
+    # via pip-audit
+tomli-w==1.2.0
+    # via pip-audit
+trio==0.33.0
+    # via anyio
+typing-extensions==4.16.0
+    # via
+    #   alembic
+    #   anyio
+    #   cyclonedx-python-lib
+    #   fastapi
+    #   mypy
+    #   pydantic
+    #   pydantic-core
+    #   sqlalchemy
+    #   sqlmodel
+    #   starlette
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+    #   pydantic-settings
+urllib3==2.7.0
+    # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip