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

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

@@ -27,3 +27,5 @@ exclude_paths:
   # 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"
+  - "AGENTS.md"
+  - "CLAUDE.md"

{fastapi_m8-3.2.0 → fastapi_m8-4.0.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.2.0 → fastapi_m8-4.0.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.2.0 → fastapi_m8-4.0.0}/.gitignore

@@ -215,7 +215,4 @@ marimo/_lsp/
 __marimo__/
 
 # Streamlit
-.streamlit/secrets.toml
-
-Claude.md
-Agents.md
+.streamlit/secrets.toml

fastapi_m8-4.0.0/.gitleaks.toml

@@ -0,0 +1,15 @@
+title = "fastapi-m8 gitleaks config"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Project-wide allowlist"
+paths = [
+  # Test fixtures may contain deterministic low-entropy test values
+  '''tests/''',
+]
+# Add SHAs of any prior accidental secret commits here after rotation:
+# commits = [
+#   "abc123def456",  # description of what was rotated and when
+# ]

fastapi_m8-4.0.0/AGENTS.md

@@ -0,0 +1,27 @@
+# fastapi-m8
+
+## Layer
+Platform (FastAPI application framework)
+
+---
+
+## Purpose
+Application factory wiring `auth-sdk-m8` into FastAPI services using `fa-auth-m8`.
+
+---
+
+## Rules
+- No business logic
+- Only reusable service scaffolding
+- Must remain minimal and reusable across services
+- No coupling to fa-auth-m8 or any domain service
+
+---
+
+## Workspace integration
+
+When nested in a workspace, locate the nearest ancestor containing
+`.workspace/policy.index.json` and apply its `python` policy.
+
+If no workspace policy exists, use this file, `pyproject.toml`, repository
+documentation and existing CI as the authoritative local context.`

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

@@ -5,6 +5,195 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning:
 
 ---
 
+## [4.0.0] — 2026-07-17 · auth-sdk-m8 3.0.0 alignment — canonical role/flag invariant + JTI-status v2 + remote API-key principal
+
+> **MAJOR — coordinated release with `auth-sdk-m8 3.0.0`.** `fastapi-m8` raises the SDK
+> floor to `>=3.0.0,<4.0.0` to consume the canonical role/flag authorization invariant
+> (`has_superuser_privileges()` and `has_minimum_role()`), the subject-bound JTI-status v2
+> introspection contract, and the API-key principal/introspection schemas. All role guards
+> now delegate to the shared SDK policy helpers, and the new remote API-key principal
+> dependencies (`get_current_api_key_reader`/`_writer` and `require_api_key_role(...)`)
+> resolve a key to its owner's **current** authority through the issuer's introspection
+> endpoint, with no administrative or superuser capability surface. The API-key path is
+> inherently fail-closed, never caches a positive principal, and never retries after
+> transmission — ensuring a role downgrade lands on the key's very next request.
+
+### Added
+
+- **JTI-status v2 (subject-bound, generation-tagged)** — `RemoteRevocationClient`
+  now speaks the v2 introspection contract: the request asserts the subject read
+  from the token (`{jti, expected_user_id, schema_version}`), and an active reply
+  carries the owner's `auth_generation`, which tags the cache entry it produces.
+  As defense in depth an active reply naming a different subject is refused and
+  never cached. **The v2 decision never falls open:** a reply this release cannot
+  interpret — malformed, unknown `schema_version`, or a pre-2.0 issuer's bare
+  `{"active": true}` with no generation — raises the new `RevocationDecisionError`
+  (a `RevocationCheckError`, so dependencies still answer `503`) regardless of
+  `ACCESS_REVOCATION_FAILURE_MODE`, which remains a transport-outage escape only.
+- **`AuthDeps.handle_auth_event(event)`** — the supported `on_event` handler for
+  `build_event_stream_client`, so no service re-derives the eviction rules
+  locally. Accepts **both v1 and v2** `session-revoked` events for the rollout
+  interval in which the issuer emits v2 before every consumer has upgraded, and
+  routes `user-deleted` as before. v2 events apply the exact `<`/`==`/`>`
+  watermark rule per user, deduplicated on the durable `event_id` (never the SSE
+  transport id, which resets on issuer restart), so a replay is idempotent while
+  sibling JTI events at one generation stay distinguishable. A user-wide event
+  evicts the user's entries older than the revoking generation and spares
+  sessions minted after it. A v1 event carries no generation to compare, so it
+  evicts the whole user; an unusable payload flushes the cache.
+- **Remote API-key principal dependencies** — `AuthDeps` gains
+  `get_current_api_key_principal`, the `require_api_key_role(...)` factory, and its
+  `get_current_api_key_reader`/`_writer` specializations, built by the same single
+  `build_auth_deps()` call as the JWT guards. A key presented on `X-API-Key` is
+  resolved to its **owner's current authority** through the issuer's
+  `POST /private/v1/api-keys/introspect`, then authorized with the same shared SDK
+  predicate the JWT guards use. The key itself carries no role, so a
+  `writer → reader` downgrade denies the key's very next request in every token
+  mode. Effective authority is an intersection that can only narrow: the owner's
+  live role ∩ the key's immutable `access_mode` ∩ the matching audience ∩ the route
+  policy. The members are `None` unless `API_KEY_INTROSPECTION_ENABLED=true`.
+- **`ApiKeyIntrospectionClient`** — the issuer introspection client, alongside
+  `RemoteRevocationClient` and following the same split (the SDK owns the schemas,
+  the transport lives here). Bounded connection pool and concurrency semaphore,
+  redirects disabled, a hard response-size cap enforced mid-read, a consecutive-
+  failure circuit breaker, and pool-timeout-bounded load shedding.
+- **Dedicated API-key configuration group** — `API_KEY_INTROSPECTION_ENABLED`,
+  `API_KEY_INTROSPECTION_URL` (or derived from `INTROSPECTION_URL`),
+  `_SCHEMA_VERSION`, `_CONNECT_TIMEOUT`, `_READ_TIMEOUT`, `_POOL_TIMEOUT`,
+  `_MAX_CONCURRENCY`, `_MAX_RESPONSE_BYTES`, `_CIRCUIT_FAILURE_THRESHOLD`, and
+  `_CIRCUIT_RESET_SECONDS`. Enabling the feature without an endpoint,
+  `INTERNAL_CLIENT_ID`, `PRIVATE_API_SECRET`, or with a schema version this SDK
+  release cannot speak **fails at startup**, so a half-configured guard never
+  serves traffic.
+- **Public exports** — `API_KEY_HEADER`, `ApiKeyIntrospectionError`,
+  `ApiKeyQuotaExceededError`, and `derive_api_key_introspection_url`.
+- **`AuthDeps.get_current_active_writer`** — the JWT writer dependency, built by the
+  single `build_auth_deps()` call alongside the existing authenticated/admin/superuser
+  members. Requires a minimum role of `WRITER`, so `WRITER`/`ADMIN`/`SUPERADMIN` pass
+  and `USER`/`READER` receive the unchanged `403 "The user doesn't have enough
+  privileges"` response.
+- **`audit_api_key_routes(app, bare_dependency=..., exempt_paths=...)`** — walks a
+  built `FastAPI` app's routes and reports any that depend directly on the bare
+  `get_current_api_key_principal` instead of a role-capped dependency
+  (`require_api_key_role(...)`'s output). Depending on the bare dependency alone
+  grants no capability, but a route wired to it directly is a wiring mistake this
+  catches at test time (§3.3.1). Returns `BareApiKeyDependency(path, methods)`
+  findings; an explicit `exempt_paths` allowlist covers intentional read-only
+  routes (e.g. a `/verify`-style endpoint).
+
+### Changed
+
+- **All JWT role guards now authorize through the `auth-sdk-m8` policy helpers.**
+  `get_current_active_writer`/`_admin` delegate the hierarchy to
+  `has_minimum_role()` (replacing the local `RoleType.is_valid_role_auth()` call), so
+  the role ordering exists only in the SDK and the two guards cannot drift.
+
+### Security
+
+- **`get_current_active_writer`/`_admin`/`_superuser` never answer from the positive
+  revocation cache (`REV-CACHE-01`, 3.5.4).** They now resolve the token through a
+  dedicated fresh-only path (`RemoteRevocationClient.is_revoked(..., bypass_cache=True)`)
+  instead of the shared `get_current_user` dependency, so the first role-sensitive
+  request after a revocation commits always observes the new state. The short-TTL
+  positive cache (`REVOCATION_CACHE_TTL_SECONDS`) now serves only the general
+  authenticated tier (`CurrentUser`/`get_current_user`); a bypassed lookup still
+  refreshes the shared cache entry so the general tier benefits from it too.
+- **`get_current_active_superuser` now requires canonical dual evidence.** It delegates
+  to the SDK's `has_superuser_privileges()`, which demands `role == SUPERADMIN` **and**
+  `is_superuser=True` together. Previously the guard checked the `is_superuser` flag and
+  the role in two separate steps; the flag is no longer sufficient evidence on its own at
+  any step. A token whose claims disagree (e.g. `is_superuser=true` with a lower role) is
+  already rejected at validation by the SDK 3.0.0 model invariant — this guard-level check
+  is defense in depth for a principal that reaches the dependency inconsistent.
+- **No role guard consults `is_superuser` for a role threshold.** The writer and admin
+  dependencies are pure role checks, so a stray `is_superuser=true` can never bypass them.
+- **An API key never grants administrative or superuser authority.** No
+  `get_current_api_key_admin`/`_superuser` dependency exists and no setting creates
+  one — `require_api_key_role()` raises `ApiKeyCapabilityCeilingError` at wiring time
+  for any role above `WRITER`. An owner's `ADMIN`/`SUPERADMIN` role grants an API-key
+  request nothing beyond writer-level capability, and `is_superuser` on the principal
+  is evidence about the owner's record, never authority. (Earlier drafts of this work
+  described a remote `_superuser` specialization disabled behind a per-deployment
+  opt-in; it is **removed**, not disabled-by-default.)
+- **The API-key path is fail-closed with no configurable escape.** It never reads
+  `ACCESS_REVOCATION_FAILURE_MODE`, whose `fail_open` value must not exist here: an
+  issuer outage, timeout, open circuit, shed request, oversized/malformed response,
+  unknown schema version, or an audience mismatch always denies with `503`. There is
+  no fallback to a cached principal, a locally stored role, or bare key validity.
+- **No positive principal caching.** Every capability-bearing request introspects the
+  issuer; only HTTP connection pooling is reused. `auth_generation` on the response is
+  evidence for the current decision, never authorization to reuse the principal later.
+- **No post-transmission retries.** Introspection consumes the key's quota, so only a
+  failure known to precede transmission (connection establishment) is retried once. A
+  read timeout or `5xx` is never replayed, since that could double-charge the owner.
+- **The raw key is confined to the outbound payload.** It is a `SecretStr` in every
+  model, and the request body is built explicitly at the transmission point rather
+  than serialized generically (which would send the mask). It never appears in the
+  URL, query, logs, traces, metrics, exception text, or model `repr`. Redirects are
+  disabled so the key cannot be replayed to an unauthenticated host.
+- **Denials carry no owner-state oracle.** An unknown, revoked, or expired key and
+  every missing/inactive/inconsistent-owner cause share the single generic
+  `401 Invalid or expired API key`, identical to the response for no key at all.
+
+---
+
+## [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

fastapi_m8-4.0.0/CLAUDE.md

@@ -0,0 +1,27 @@
+# fastapi-m8
+
+## Layer
+Platform (FastAPI application framework)
+
+---
+
+## Purpose
+Application factory wiring `auth-sdk-m8` into FastAPI services using `fa-auth-m8`.
+
+---
+
+## Rules
+- No business logic
+- Only reusable service scaffolding
+- Must remain minimal and reusable across services
+- No coupling to fa-auth-m8 or any domain service
+
+---
+
+## Workspace integration
+
+When nested in a workspace, locate the nearest ancestor containing
+`.workspace/policy.index.json` and apply its `python` policy.
+
+If no workspace policy exists, use this file, `pyproject.toml`, repository
+documentation and existing CI as the authoritative local context.