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

{fastapi_m8-3.0.0 → fastapi_m8-3.2.0}/.codacy.yml

@@ -23,3 +23,7 @@ exclude_paths:
   - "*.egg-info/**"
   - ".pytest_cache/**"
   - "**/__pycache__/**"
+  # SECURITY.md is kept markdownlint-clean by hand; excluded here because
+  # Codacy's prose analyzer misclassifies a security policy doc (flags standard
+  # security acronyms such as CA/TTL/JTI as "undefined" on every revision).
+  - "SECURITY.md"

fastapi_m8-3.2.0/.dockerignore

@@ -0,0 +1,20 @@
+.git/
+.github/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.vscode/
+.tmp/
+dist/
+build/
+tmp*/
+
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+
+.coverage
+coverage.xml
+tests/

{fastapi_m8-3.0.0 → fastapi_m8-3.2.0}/.env.example

@@ -68,8 +68,13 @@ TOKEN_AUDIENCE=my-service
 # is required at boot unless signing is disabled. Must match the value set on fa-auth.
 # DEV-ONLY placeholder — replace in staging/production.
 EVENT_SIGNING_KEY=DEV-ONLY-do-not-use-event-signing-key-Aa1!
-# EVENT_SIGNING_ENABLED=false           # disable signing entirely (opt-out)
-# EVENT_SIGNING_ACCEPT_UNSIGNED=false   # transitional: accept signed AND unsigned
+# The two rollout flags below feed the shared check_config_health gate that
+# create_app auto-runs at startup (item 7.x.1). Under STRICT_PRODUCTION_MODE
+# both misconfigurations are FATAL (the app refuses to boot); EVENT_SIGNING_
+# ACCEPT_UNSIGNED is also fatal under ENVIRONMENT=production. Leave both at the
+# secure defaults (signing on, unsigned rejected) for any real deployment.
+# EVENT_SIGNING_ENABLED=false           # disable signing entirely (opt-out) — fatal under strict
+# EVENT_SIGNING_ACCEPT_UNSIGNED=false   # transitional: accept signed AND unsigned — fatal in prod/strict
 
 # ── Auth event stream (fa-auth SSE bridge) ────────────────────────────────────
 # Optional: start AuthEventStreamClient in lifespan for best-effort cache
@@ -85,7 +90,25 @@ EVENT_SIGNING_KEY=DEV-ONLY-do-not-use-event-signing-key-Aa1!
 # PRIVATE_API_SECRET=change-me-shared-internal-secret
 
 # Revocation failure mode: fail_closed (default, secure) or fail_open (availability).
+# A fail_open opt-out is logged loudly and counted (revocation_check_failures_total
+# {mode="fail_open"}) on every swallowed failure — item 5.5.
 # ACCESS_REVOCATION_FAILURE_MODE=fail_closed
+# Positive validation cache for JTI checks: 0 (default) = always call fa-auth;
+# >0 caches active=True for N seconds (stream events evict). e.g. 30.
+# REVOCATION_CACHE_TTL_SECONDS=0
+
+# ── Per-consumer internal auth (item 9.1) ────────────────────────────────────
+# Unset (default) = legacy mode: PRIVATE_API_SECRET is sent as X-Internal-Token,
+# matching fa-auth's fallback when it has no PRIVATE_API_CONSUMERS registry.
+# Set INTERNAL_CLIENT_ID to this service's registered consumer id to switch to
+# the per-consumer model — PRIVATE_API_SECRET then carries THIS consumer's
+# bootstrap secret and fa-auth gates each private route by granted scope.
+# INTERNAL_CLIENT_ID=my-service
+# Opt into exchanging the bootstrap credential for short-TTL Bearer service
+# tokens at {issuer}/private/v1/service-token (rotation comes from the short TTL):
+# SERVICE_TOKEN_EXCHANGE_ENABLED=false
+# SERVICE_TOKEN_SCOPES=introspection           # comma/space list; default introspection
+# SERVICE_TOKEN_REFRESH_LEEWAY_SECONDS=30      # refresh this many seconds before exp
 
 # ── Database ──────────────────────────────────────────────────────────────────
 SELECTED_DB=Mysql             # Mysql | Postgres
@@ -103,6 +126,15 @@ REDIS_USER=redisuser
 REDIS_PASSWORD=change-me
 REDIS_SSL=false
 
+# ── Health detail gating (item 9.3) ──────────────────────────────────────────
+# Dedicated credential for the deep-/health detail body gate (X-Internal-Token).
+# Unset (default) = detail body never shown — only {"status": "ok/fail"} is
+# returned to unauthenticated callers (fail-closed).  Set to a long-lived secret
+# and present it as X-Internal-Token to receive the full per-check breakdown.
+# MUST NOT equal PRIVATE_API_SECRET — a fatal startup error is raised on reuse.
+# Supports _FILE mount: set HEALTH_DETAIL_CREDENTIAL_FILE=/run/secrets/health_cred.txt
+# HEALTH_DETAIL_CREDENTIAL=change-me-health-detail-credential
+
 # ── Observability ─────────────────────────────────────────────────────────────
 METRICS_ENABLED=false
 # METRICS_GROUPS=traffic,performance,reliability,health,auth

{fastapi_m8-3.0.0 → fastapi_m8-3.2.0}/.github/workflows/PiPy.yml

@@ -54,3 +54,28 @@ jobs:
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
+
+  sbom:
+    name: Generate & attach SBOM
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.x"
+
+      - name: Install package
+        run: pip install -e ".[all]"
+
+      - uses: anchore/sbom-action@f325610c9f50a54015d37c8d16cb3b0e2c8f4de0 # v0.18.0
+        with:
+          artifact-name: fastapi-m8-${{ github.event.release.tag_name }}.sbom.spdx.json
+          format: spdx-json
+          upload-release-assets: true

fastapi_m8-3.2.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test & lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Type check (mypy)
+        run: mypy fastapi_m8
+
+      - name: Security scan (bandit)
+        run: bandit -r fastapi_m8 -x tests
+
+      - name: Test (pytest)
+        run: pytest
+
+      - name: Dependency audit (pip-audit)
+        run: pip-audit
+
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@1938557f6a58837331b99822ab17b8e536e7bef9 # v2.3.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

{fastapi_m8-3.0.0 → fastapi_m8-3.2.0}/.gitignore

@@ -216,3 +216,6 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+Claude.md
+Agents.md

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

@@ -5,6 +5,101 @@ 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
+> with none of the new settings set keeps the legacy single `PRIVATE_API_SECRET`
+> (`X-Internal-Token`) posture and the existing fail-closed revocation path. The post-1.0
+> breaking removals (retiring the shared `PRIVATE_API_SECRET` model) remain **deferred** —
+> `fastapi-m8 3.0.0` / `auth-sdk-m8 2.0.1` are not yet consumed by any live issuer/consumer
+> stack, so this remediation wave folds into a minor rather than forcing a new major.
+> Requires `auth-sdk-m8 >= 2.1.0, < 3.0.0` (floor raised from 2.0.1 by the event-stream
+> follow-on item — `auth_provider` on `AuthEventStreamClient` landed in SDK 2.1.0).
+
+### Added
+
+- **Per-consumer credentials & short-TTL service tokens — consumer side (item 9.1).** New
+  `fastapi_m8._internal_auth` with `build_internal_auth(settings)` selecting one of three
+  modes purely by config:
+  - **legacy** (`INTERNAL_CLIENT_ID` unset) — single `X-Internal-Token`, as before;
+  - **bootstrap** (`INTERNAL_CLIENT_ID` set) — per-consumer `X-Internal-Client` +
+    `X-Internal-Token` on every private call;
+  - **service token** (`+ SERVICE_TOKEN_EXCHANGE_ENABLED`) — exchange the bootstrap
+    credential at `{issuer}/private/v1/service-token` for a short-TTL `Authorization:
+    Bearer` token, refreshed before `exp` and re-exchanged once on a `401`.
+
+  `RemoteRevocationClient` now attaches the provider's headers per request (with a single
+  401 re-exchange retry) instead of baking `X-Internal-Token` in at construction. New
+  public exports: `build_internal_auth`, `InternalAuthProvider`,
+  `ServiceTokenInternalAuth`, `derive_service_token_url`. New settings:
+  `INTERNAL_CLIENT_ID`, `SERVICE_TOKEN_EXCHANGE_ENABLED`, `SERVICE_TOKEN_SCOPES`,
+  `SERVICE_TOKEN_REFRESH_LEEWAY_SECONDS`.
+- **Revocation degradation observability (item 5.5).** New
+  `revocation_check_failures_total{mode}` counter and a loud `security.revocation_fail_open`
+  log line: a `fail_open` opt-out is now surfaced as a conscious availability-over-safety
+  decision, never silent. Consumer-side degradation matrix tested end-to-end
+  (`fail_closed` → 503, `fail_open` → token accepted) through `get_current_user`.
+- **`SECURITY.md` (item 9.2).** New consumer-scoped security doc cross-referencing
+  `auth-sdk-m8`'s canonical "Service identity and mTLS" pattern for multi-host deployments,
+  plus a vulnerability-reporting section.
+
+### Changed
+
+- **`build_event_stream_client` routes through `build_internal_auth` (item 9.1 event-stream
+  follow-on, 2026-06-25).** The SSE stream now authenticates via the same
+  `InternalAuthProvider` the revocation client uses, selected purely by config (legacy /
+  bootstrap / service-token). The factory always passes `auth_provider` to
+  `AuthEventStreamClient`, which owns the provider lifecycle and closes it on `stop()`.
+  Consumer settings are unchanged; the only external requirement change is the SDK floor
+  bump to `>=2.1.0`.
+- **`auth-sdk-m8` floor raised to `>=2.1.0`** (was `>=2.0.1`). `2.1.0` ships the
+  `auth_provider` parameter on `AuthEventStreamClient` and the framework-agnostic
+  `auth_sdk_m8.security.internal_auth` module. The `<3.0.0` ceiling is unchanged.
+- **README (item 10.1).** New *Per-consumer internal auth* subsection and a *Defaults by
+  layer (consumer)* table documenting the consumer column (auto-run config-health,
+  `ALLOWED_HOSTS` inheritance, `METRICS_SCRAPE_CREDENTIAL`, `_FILE` inheritance,
+  `ACCESS_REVOCATION_FAILURE_MODE`). Event-stream section updated to note the shared
+  credential provider.
+- **Event-signing rollout flags surfaced for consumers (item 7.x.1).** `.env.example`
+  documents `EVENT_SIGNING_ENABLED` / `EVENT_SIGNING_ACCEPT_UNSIGNED` and their strict
+  config-health gate (fatal under `STRICT_PRODUCTION_MODE`; `ACCEPT_UNSIGNED` also fatal
+  under `ENVIRONMENT=production`). The gate is auto-run via `create_app`; a consumer-side
+  test asserts it fires. `.env.example` also gains the new 9.1 vars and
+  `REVOCATION_CACHE_TTL_SECONDS`.
+- `COMPAT_MATRIX` `3.1` entry updated to `auth-sdk-m8 >=2.1.0,<3.0.0` (reflects the
+  event-stream `auth_provider` requirement).
+
+---
+
 ## [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:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-m8
-Version: 3.0.0
+Version: 3.2.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.0.1
+Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<3.0.0,>=2.1.0
 Requires-Dist: fastapi>=0.136.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: packaging>=24.0
@@ -613,10 +613,29 @@ Required only when `TOKEN_MODE=stateful` and `AUTH_SERVICE_ROLE=consumer`.
 | Variable | Required | Default | Description |
 |---|---|---|---|
 | `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). |
+| `PRIVATE_API_SECRET` | Yes | — | The credential for private calls. In **legacy** mode it is the single shared secret sent as `X-Internal-Token` (must match auth service); in **per-consumer** mode (see below) it carries *this* consumer's bootstrap secret. |
+| `ACCESS_REVOCATION_FAILURE_MODE` | No | `fail_closed` | `fail_closed` (default, secure — reject tokens when the check is unverifiable, returning **503**) or `fail_open` (accept on network/HTTP error — the opt-out is logged loudly and counted as `revocation_check_failures_total{mode="fail_open"}`). |
 | `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). |
 
+#### 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.
+
+| 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. |
+| `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. |
+
 ### Auth Event Stream (fa-auth SSE bridge)
 
 An **optional, best-effort accelerator** for cache eviction. `fa-auth-m8` bridges its
@@ -631,7 +650,12 @@ No second Redis, no broker: consumers speak HTTPS to fa-auth, which they already
 > HTTP authority path alone.
 
 Wire it in your lifespan with `build_event_stream_client`, which constructs the SDK's
-`AuthEventStreamClient` from your settings (no SDK internals needed):
+`AuthEventStreamClient` from your settings (no SDK internals needed). The factory uses
+the same internal-auth provider as the revocation client — the stream credential is
+therefore **a single config knob** shared with JTI introspection: legacy
+`X-Internal-Token`, per-consumer bootstrap, or short-TTL `Authorization: Bearer` service
+token, selected by `INTERNAL_CLIENT_ID` / `SERVICE_TOKEN_EXCHANGE_ENABLED` (see
+*Per-consumer internal auth* above).
 
 ```python
 from contextlib import asynccontextmanager
@@ -666,9 +690,9 @@ async def lifespan(app: FastAPI):
 
 The client verifies every payload's HMAC signature with `EVENT_SIGNING_KEY` (must match
 fa-auth), auto-reconnects with jittered backoff, resumes via `Last-Event-ID`, and **never
-raises into the host app**. Requires `TOKEN_MODE=stateful` so `INTROSPECTION_URL` and
-`PRIVATE_API_SECRET` are present. Behind a reverse proxy, disable response buffering on
-the stream endpoint so events and heartbeats pass through promptly.
+raises into the host app**. Requires `TOKEN_MODE=stateful` so `INTROSPECTION_URL` is set.
+Behind a reverse proxy, disable response buffering on the stream endpoint so events and
+heartbeats pass through promptly.
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
@@ -700,13 +724,32 @@ do not connect to Redis directly.
 | `REDIS_PASSWORD` | Redis password |
 | `REDIS_SSL` | Enable TLS (`true`/`false`, default `false`) |
 
+### 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 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`.
+> This ensures each credential is independently rotatable — exposing one value cannot open
+> multiple surfaces. The check raises `ConfigurationError` (fail-closed), aborting startup.
+
 ### Observability
 
 | Variable | Default | Description |
 |---|---|---|
 | `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_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. **Must not equal `PRIVATE_API_SECRET`**. |
 
 > **`/metrics` route:** when `METRICS_ENABLED=true`, `create_app` also registers a
 > `GET /metrics` endpoint (hidden from the schema) rendering the Prometheus registry.
@@ -778,6 +821,24 @@ locally before deploy).
 > These knobs are inherited from `CommonSettings`; consumer services do not redeclare
 > them. The same layer is shared by `fa-auth-m8` and every consumer.
 
+### Defaults by layer (consumer)
+
+How the security-critical settings behave specifically in the **fastapi-m8 consumer**
+layer. This is the consumer column of the fleet-wide defaults-by-layer table (the SDK and
+fa-auth-m8 READMEs hold the issuer/SDK columns). The throughline: secure-by-default,
+inherited from `auth-sdk-m8`, and made *fatal* only when pointed at production.
+
+| Control | Consumer behaviour | Becomes fatal when |
+|---|---|---|
+| Config-health gate | `create_app` **auto-runs** `check_config_health` in its lifespan before the app signals ready — no manual wiring | any fatal check trips (raises `ConfigurationError`, app refuses to boot) |
+| `ACCESS_REVOCATION_FAILURE_MODE` | `fail_closed` by default — an unverifiable revocation check returns **503**; `fail_open` is a conscious opt-out, logged loudly and counted (`revocation_check_failures_total{mode="fail_open"}`) | never fatal (it *is* the degradation policy) |
+| `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` (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) |
+
 ---
 
 ## API Reference

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

@@ -357,10 +357,29 @@ Required only when `TOKEN_MODE=stateful` and `AUTH_SERVICE_ROLE=consumer`.
 | Variable | Required | Default | Description |
 |---|---|---|---|
 | `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). |
+| `PRIVATE_API_SECRET` | Yes | — | The credential for private calls. In **legacy** mode it is the single shared secret sent as `X-Internal-Token` (must match auth service); in **per-consumer** mode (see below) it carries *this* consumer's bootstrap secret. |
+| `ACCESS_REVOCATION_FAILURE_MODE` | No | `fail_closed` | `fail_closed` (default, secure — reject tokens when the check is unverifiable, returning **503**) or `fail_open` (accept on network/HTTP error — the opt-out is logged loudly and counted as `revocation_check_failures_total{mode="fail_open"}`). |
 | `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). |
 
+#### 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.
+
+| 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. |
+| `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. |
+
 ### Auth Event Stream (fa-auth SSE bridge)
 
 An **optional, best-effort accelerator** for cache eviction. `fa-auth-m8` bridges its
@@ -375,7 +394,12 @@ No second Redis, no broker: consumers speak HTTPS to fa-auth, which they already
 > HTTP authority path alone.
 
 Wire it in your lifespan with `build_event_stream_client`, which constructs the SDK's
-`AuthEventStreamClient` from your settings (no SDK internals needed):
+`AuthEventStreamClient` from your settings (no SDK internals needed). The factory uses
+the same internal-auth provider as the revocation client — the stream credential is
+therefore **a single config knob** shared with JTI introspection: legacy
+`X-Internal-Token`, per-consumer bootstrap, or short-TTL `Authorization: Bearer` service
+token, selected by `INTERNAL_CLIENT_ID` / `SERVICE_TOKEN_EXCHANGE_ENABLED` (see
+*Per-consumer internal auth* above).
 
 ```python
 from contextlib import asynccontextmanager
@@ -410,9 +434,9 @@ async def lifespan(app: FastAPI):
 
 The client verifies every payload's HMAC signature with `EVENT_SIGNING_KEY` (must match
 fa-auth), auto-reconnects with jittered backoff, resumes via `Last-Event-ID`, and **never
-raises into the host app**. Requires `TOKEN_MODE=stateful` so `INTROSPECTION_URL` and
-`PRIVATE_API_SECRET` are present. Behind a reverse proxy, disable response buffering on
-the stream endpoint so events and heartbeats pass through promptly.
+raises into the host app**. Requires `TOKEN_MODE=stateful` so `INTROSPECTION_URL` is set.
+Behind a reverse proxy, disable response buffering on the stream endpoint so events and
+heartbeats pass through promptly.
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
@@ -444,13 +468,32 @@ do not connect to Redis directly.
 | `REDIS_PASSWORD` | Redis password |
 | `REDIS_SSL` | Enable TLS (`true`/`false`, default `false`) |
 
+### 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 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`.
+> This ensures each credential is independently rotatable — exposing one value cannot open
+> multiple surfaces. The check raises `ConfigurationError` (fail-closed), aborting startup.
+
 ### Observability
 
 | Variable | Default | Description |
 |---|---|---|
 | `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_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. **Must not equal `PRIVATE_API_SECRET`**. |
 
 > **`/metrics` route:** when `METRICS_ENABLED=true`, `create_app` also registers a
 > `GET /metrics` endpoint (hidden from the schema) rendering the Prometheus registry.
@@ -522,6 +565,24 @@ locally before deploy).
 > These knobs are inherited from `CommonSettings`; consumer services do not redeclare
 > them. The same layer is shared by `fa-auth-m8` and every consumer.
 
+### Defaults by layer (consumer)
+
+How the security-critical settings behave specifically in the **fastapi-m8 consumer**
+layer. This is the consumer column of the fleet-wide defaults-by-layer table (the SDK and
+fa-auth-m8 READMEs hold the issuer/SDK columns). The throughline: secure-by-default,
+inherited from `auth-sdk-m8`, and made *fatal* only when pointed at production.
+
+| Control | Consumer behaviour | Becomes fatal when |
+|---|---|---|
+| Config-health gate | `create_app` **auto-runs** `check_config_health` in its lifespan before the app signals ready — no manual wiring | any fatal check trips (raises `ConfigurationError`, app refuses to boot) |
+| `ACCESS_REVOCATION_FAILURE_MODE` | `fail_closed` by default — an unverifiable revocation check returns **503**; `fail_open` is a conscious opt-out, logged loudly and counted (`revocation_check_failures_total{mode="fail_open"}`) | never fatal (it *is* the degradation policy) |
+| `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` (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) |
+
 ---
 
 ## API Reference

fastapi_m8-3.2.0/SECURITY.md

@@ -0,0 +1,50 @@
+# Security
+
+`fastapi-m8` is the FastAPI **consumer** framework for the m8 stack. Its runtime
+security posture is inherited from `auth-sdk-m8` (RS256 + strict `iss`/`aud`
+validation, signed events, fail-closed revocation, the response-hardening layer)
+and wired in by `create_app` / `build_auth_deps`. This file documents only the
+consumer-specific transport guidance; the canonical, fleet-wide controls live in
+the **[`auth-sdk-m8` `SECURITY.md`](https://github.com/mano8/auth-sdk-m8/blob/main/SECURITY.md)**.
+
+## Private calls a consumer makes
+
+A `fastapi-m8` consumer reaches `fa-auth-m8` over the **private API** only:
+
+- JTI-status / revocation introspection (`{issuer}/private/v1/jti-status`),
+- the optional auth event stream (`{issuer}/private/v1/events/stream`),
+- the optional short-TTL service-token exchange (`{issuer}/private/v1/service-token`).
+
+These are authenticated at the **app layer** by the per-consumer credential model
+(item 9.1): `X-Internal-Client` + `X-Internal-Token`, or an exchanged
+`Authorization: Bearer` service token, with a legacy single `PRIVATE_API_SECRET`
+fallback. See the README's *Per-consumer internal auth* section.
+
+## Service identity and mTLS (multi-host deployments)
+
+The app-layer token/credential check is always the **primary** control. For the
+transport beneath it, follow the canonical
+[**"Service identity and mTLS"**](https://github.com/mano8/auth-sdk-m8/blob/main/SECURITY.md#service-identity-and-mtls-multi-host-deployments)
+section of `auth-sdk-m8`'s `SECURITY.md` — it carries the Traefik internal-entrypoint
+client-cert reference config, the CA/cert generation steps, and the service-mesh
+alternative. From the **consumer** side:
+
+- **Single trusted Docker host.** Internal `http://` between the consumer and
+  `fa-auth-m8` is acceptable — the Docker network is the isolation boundary. This is
+  warned, not blocked, in production (`ALLOW_INTERNAL_HTTP`); `local` is unrestricted.
+- **Multi-host / untrusted network.** The container network no longer provides
+  kernel isolation, so add **mTLS** on the path to the issuer's private entrypoint:
+  the consumer presents a client certificate that Traefik (or a service-mesh sidecar)
+  verifies (`RequireAndVerifyClientCert`). Mount the consumer's client cert/key and
+  the CA into the container per the auth-sdk-m8 reference config.
+- **Defense in depth, not a replacement.** Keep the `X-Internal-Token` /
+  `X-Internal-Client` / service-token app-layer check enabled alongside mTLS: if cert
+  rotation lapses the token check still gates access, and if a token leaks over an
+  unencrypted hop mTLS encrypts the channel. Internal HTTPS is **not** a blanket
+  mandate — mTLS is the *multi-host* transport control.
+
+## Reporting a vulnerability
+
+Report security vulnerabilities privately through GitHub's **Security** tab on this repository —
+**"Report a vulnerability"** — which opens a private security advisory visible only to the
+maintainers. Do not open a public GitHub issue for vulnerabilities. Expected response within 48 h.

{fastapi_m8-3.0.0 → fastapi_m8-3.2.0}/fastapi_m8/__init__.py

@@ -50,6 +50,14 @@ from fastapi_m8._health import (
     HealthCheckResult,
     HealthStatus,
 )
+
+# Tier 1 — per-consumer internal-auth for private calls (Phase 9.1)
+from fastapi_m8._internal_auth import (
+    InternalAuthProvider,
+    ServiceTokenInternalAuth,
+    build_internal_auth,
+    derive_service_token_url,
+)
 from fastapi_m8._version import __version__
 from fastapi_m8.config import ConsumerServiceSettings
 
@@ -64,6 +72,11 @@ __all__ = [
     "create_db_engine",
     "DbEngine",
     "ConsumerServiceSettings",
+    # Tier 1 — per-consumer internal-auth
+    "build_internal_auth",
+    "InternalAuthProvider",
+    "ServiceTokenInternalAuth",
+    "derive_service_token_url",
     # Tier 1 — auth event stream
     "build_event_stream_client",
     "AuthEventStreamClient",