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

{fastapi_m8-3.3.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.3.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.3.0 → fastapi_m8-4.0.0}/CHANGELOG.md

@@ -5,7 +5,135 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · Versioning:
 
 ---
 
-## [Unreleased]
+## [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.
 
 ---
 

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.

{fastapi_m8-3.3.0 → fastapi_m8-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-m8
-Version: 3.3.0
+Version: 4.0.0
 Summary: FastAPI application framework for m8 consumer microservices.
 Author-email: Eli Serra <e.serra173@gmail.com>
 License:                                  Apache License
@@ -216,7 +216,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Requires-Dist: anyio>=4.0
-Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<3.0.0,>=2.1.1
+Requires-Dist: auth-sdk-m8[config,events,fastapi,observability,security]<4.0.0,>=3.0.0
 Requires-Dist: fastapi>=0.136.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: packaging>=24.0
@@ -235,7 +235,9 @@ Requires-Dist: alembic; extra == 'dev'
 Requires-Dist: anyio[trio]>=4.0; extra == 'dev'
 Requires-Dist: asgi-lifespan>=2.0; extra == 'dev'
 Requires-Dist: bandit>=1.8.0; extra == 'dev'
+Requires-Dist: build>=1.2.2; extra == 'dev'
 Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: hatchling>=1.27.0; extra == 'dev'
 Requires-Dist: httpx; extra == 'dev'
 Requires-Dist: mypy>=1.14.0; extra == 'dev'
 Requires-Dist: pip-audit>=2.7.3; extra == 'dev'
@@ -287,6 +289,7 @@ boilerplate from every consumer service.
    - [Token Modes](#token-modes)
    - [Role System](#role-system)
    - [Protecting Routes](#protecting-routes)
+   - [API-key routes (remote principal)](#api-key-routes-remote-principal)
 8. [Health Endpoint](#health-endpoint)
 9. [Database Integration](#database-integration)
 10. [Pre-Start Script](#pre-start-script)
@@ -307,7 +310,8 @@ health checks; the framework wires the rest.
 | Capability | How |
 |---|---|
 | JWT validation | `build_auth_deps()` + `auth-sdk-m8` validator |
-| Role-based access control | `AuthDeps.get_current_active_admin / _superuser` |
+| Role-based access control | `AuthDeps.get_current_active_writer / _admin / _superuser` |
+| API-key routes (optional) | `AuthDeps.get_current_api_key_reader / _writer` → live owner-role resolution via `fa-auth-m8` introspection; never admin/superuser |
 | Token revocation (stateful mode) | `RemoteRevocationClient` → `fa-auth-m8` private API (optional short-TTL cache via `REVOCATION_CACHE_TTL_SECONDS`) |
 | Auth event stream (optional) | `build_event_stream_client()` → fa-auth SSE bridge for best-effort cache eviction |
 | CORS | Auto-wired from `settings.ALLOWED_ORIGINS` |
@@ -615,7 +619,7 @@ Required only when `TOKEN_MODE=stateful` and `AUTH_SERVICE_ROLE=consumer`.
 | `INTROSPECTION_URL` | Yes | — | `POST` endpoint on auth service for JTI revocation checks, e.g. `http://auth_user_service:8000/user/private/v1/jti-status` |
 | `PRIVATE_API_SECRET` | Yes | — | 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). |
+| `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. Entries are tagged with the `auth_generation` fa-auth returned; stream events (`session-revoked`/`user-deleted`) evict affected entries and an unresumable gap flushes all (requires the event-stream client). This TTL is the staleness ceiling — the stream is an accelerator, not the guarantee. |
 
 #### Per-consumer internal auth (item 9.1)
 
@@ -645,6 +649,53 @@ untouched.
 | `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. |
 
+### Remote API-Key Principal
+
+Resolves a user API key presented by an external client to its owner's current
+authority through the issuer's private introspection endpoint. Off by default;
+see [API-key routes](#api-key-routes-remote-principal) for the route surface.
+
+This group is **deliberately self-contained and has no fail-open option**. It
+never consults `ACCESS_REVOCATION_FAILURE_MODE` — that knob's `fail_open` value
+must not reach this path, because an unconfirmable API-key principal is always a
+denial rather than a downgrade to bare key validity.
+
+> **Startup fails, not the first request.** When `API_KEY_INTROSPECTION_ENABLED=true`,
+> settings validation fails at construction if there is no endpoint (neither
+> `API_KEY_INTROSPECTION_URL` nor `INTROSPECTION_URL` to derive one from), no
+> `INTERNAL_CLIENT_ID`, no `PRIVATE_API_SECRET`, or a schema version this
+> `auth-sdk-m8` release cannot speak. A half-configured guard never serves traffic.
+
+The consumer's registered identity (`INTERNAL_CLIENT_ID`) is what fixes the
+**audience** the issuer evaluates — it is derived from your credential, never from
+the request — and the issuer echoes it back so the client can verify it. An active
+principal carrying a different audience means the registry mapping or the
+credential is wrong: that is a `503`, never a `401`.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `API_KEY_INTROSPECTION_ENABLED` | No | `false` | Enable the remote API-key principal dependencies. Requires `INTERNAL_CLIENT_ID`, `PRIVATE_API_SECRET`, and an endpoint. |
+| `API_KEY_INTROSPECTION_URL` | No | derived | `POST` endpoint, e.g. `http://auth_user_service:8000/user/private/v1/api-keys/introspect`. Unset = derived from `INTROSPECTION_URL`. |
+| `API_KEY_INTROSPECTION_SCHEMA_VERSION` | No | `"1"` | The contract version this consumer speaks. An unknown version fails at startup; a response declaring one fails closed (`503`). |
+| `API_KEY_INTROSPECTION_CONNECT_TIMEOUT` | No | `2.0` | Connection-establishment timeout, seconds. |
+| `API_KEY_INTROSPECTION_READ_TIMEOUT` | No | `3.0` | Response-read timeout, seconds. |
+| `API_KEY_INTROSPECTION_POOL_TIMEOUT` | No | `2.0` | How long a request waits for concurrency capacity before being **shed** with a `503` instead of queueing onto a saturated issuer. |
+| `API_KEY_INTROSPECTION_MAX_CONCURRENCY` | No | `20` | Ceiling on in-flight introspection calls. |
+| `API_KEY_INTROSPECTION_MAX_RESPONSE_BYTES` | No | `8192` | Hard cap on the issuer response body; a larger reply is abandoned mid-read. |
+| `API_KEY_INTROSPECTION_CIRCUIT_FAILURE_THRESHOLD` | No | `5` | Consecutive issuer failures that open the circuit. |
+| `API_KEY_INTROSPECTION_CIRCUIT_RESET_SECONDS` | No | `30.0` | How long the circuit stays open before one trial call is admitted. |
+
+The issuer must grant this consumer the dedicated `api-key-introspection` scope.
+It is deliberately separate from `introspection`, so a consumer that checks JTI
+status is not implicitly able to introspect user API keys — grant it explicitly.
+
+**The key is never cached and never retried after transmission.** Every
+capability-bearing request introspects the issuer (connection pooling is the only
+reuse), so a downgrade lands immediately and a transport failure can never be
+answered from a stale success. Because introspection consumes the key's quota,
+only a failure known to have occurred *before* transmission (connection
+establishment) is retried; a read timeout or `5xx` is never replayed.
+
 ### Auth Event Stream (fa-auth SSE bridge)
 
 An **optional, best-effort accelerator** for cache eviction. `fa-auth-m8` bridges its
@@ -666,28 +717,28 @@ therefore **a single config knob** shared with JTI introspection: legacy
 token, selected by `INTERNAL_CLIENT_ID` / `SERVICE_TOKEN_EXCHANGE_ENABLED` (see
 *Per-consumer internal auth* above).
 
+Pass `auth.handle_auth_event` as `on_event`: it applies each event to the validation
+cache under the rules below, so your service never re-derives them.
+
 ```python
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
-from fastapi_m8 import build_event_stream_client, AuthStreamEvent
+from fastapi_m8 import build_event_stream_client
 
-
-async def on_auth_event(event: AuthStreamEvent) -> None:
-    # session-revoked / user-deleted → evict the affected entry from local caches.
-    ...
+from app.core.deps import auth  # your single build_auth_deps(...) result
 
 
 async def on_gap() -> None:
     # Unresumable stream (fa-auth restarted / buffer evicted) → flush ALL caches.
-    ...
+    auth.flush_cache()
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     client = build_event_stream_client(
         settings,
-        on_event=on_auth_event,
+        on_event=auth.handle_auth_event,
         on_gap=on_gap,
     )
     client.start()
@@ -697,6 +748,24 @@ async def lifespan(app: FastAPI):
         await client.stop()
 ```
 
+`handle_auth_event` accepts **both v1 and v2** `session-revoked` events, so it keeps
+working across the interval where the issuer already emits v2 and consumers have not
+all upgraded. A v2 event carries the owner's `auth_generation` and a durable
+`event_id`, which together make replay and reorder safe:
+
+| Event generation vs. the user's watermark | Outcome |
+|---|---|
+| Lower | Already superseded — ignored. |
+| Equal | Applied, unless that exact `event_id` was already applied at this generation. |
+| Higher | Applied; the watermark advances. |
+
+A user-wide v2 event (no `jti`) evicts only the entries older than the revoking
+generation, so a session minted by a login that has already re-authenticated
+survives. A v1 event carries no generation to compare against and therefore evicts
+the whole user; an unusable payload flushes the cache. The durable `event_id` — not
+the SSE transport id, which resets when fa-auth restarts — is the dedup key, so
+several JTI events sharing one generation stay distinguishable.
+
 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` is set.
@@ -956,9 +1025,18 @@ Returns a frozen dataclass with everything needed for route protection.
 |---|---|---|
 | `auth.CurrentUser` | `Annotated[UserModel, Depends(...)]` | Inject authenticated user into routes |
 | `auth.get_current_user` | `async Callable` | FastAPI dependency; validates JWT, checks revocation |
+| `auth.get_current_active_writer` | `Callable` | Raises 403 unless user has WRITER, ADMIN or SUPERADMIN role |
 | `auth.get_current_active_admin` | `Callable` | Raises 403 unless user has ADMIN or SUPERADMIN role |
-| `auth.get_current_active_superuser` | `Callable` | Raises 403 unless user has SUPERADMIN role and `is_superuser=True` |
+| `auth.get_current_active_superuser` | `Callable` | Raises 403 unless user has SUPERADMIN role **and** `is_superuser=True` (both are required; neither claim grants privilege on its own) |
 | `auth.revocation_client` | `RemoteRevocationClient \| None` | Present only in stateful mode |
+| `auth.handle_auth_event` | `Callable` | Pass as `on_event` to `build_event_stream_client`; applies v1/v2 `session-revoked` and `user-deleted` events to the validation cache |
+| `auth.get_current_api_key_principal` | `async Callable \| None` | Resolves an `X-API-Key` to its owner's **current** authority via the issuer. Proves a live owner only — never writer capability |
+| `auth.require_api_key_role` | `Callable \| None` | Factory: `require_api_key_role(RoleType.WRITER)` builds a capability dependency. Rejects any role above `WRITER` |
+| `auth.get_current_api_key_reader` | `async Callable \| None` | Raises 403 unless the key's owner is at least READER |
+| `auth.get_current_api_key_writer` | `async Callable \| None` | Raises 403 unless the key's owner is at least WRITER **and** the key is `read_write` |
+| `auth.api_key_client` | `ApiKeyIntrospectionClient \| None` | Present only when `API_KEY_INTROSPECTION_ENABLED` |
+
+The four API-key members are `None` unless `API_KEY_INTROSPECTION_ENABLED=true`.
 
 **`UserModel` fields available in routes:**
 
@@ -1121,6 +1199,13 @@ router = APIRouter()
 async def get_profile(user: auth.CurrentUser):
     return {"id": user.id, "email": user.email, "role": user.role}
 
+# WRITER, ADMIN or SUPERADMIN
+@router.post("/items")
+async def create_item(
+    writer: Annotated[UserModel, Depends(auth.get_current_active_writer)],
+):
+    ...
+
 # ADMIN or SUPERADMIN
 @router.delete("/users/{user_id}")
 async def delete_user(
@@ -1144,6 +1229,67 @@ Unauthorized requests receive:
 
 ---
 
+### API-key routes (remote principal)
+
+An API key is an opaque pointer to its **owner**, not a credential with
+capabilities of its own — it stores no role. A downstream service does not share
+the issuer's database, so it resolves the owner's **current** role by calling the
+issuer on every capability-bearing request. That is what makes a role downgrade
+take effect on the key's next request, in every token mode.
+
+Enable it with `API_KEY_INTROSPECTION_ENABLED=true` (see
+[Remote API-Key Principal](#remote-api-key-principal)); the dependencies are
+`None` until you do. The key travels on the `X-API-Key` header — the same header
+the issuer reads, so a key behaves identically at either end.
+
+```python
+# Reads only — the owner must be at least READER.
+@router.get("/items")
+async def list_items(
+    principal: Annotated[ApiKeyPrincipal, Depends(auth.get_current_api_key_reader)],
+):
+    ...
+
+# Writes — the owner must be at least WRITER *and* the key must be read_write.
+@router.post("/items")
+async def create_item(
+    principal: Annotated[ApiKeyPrincipal, Depends(auth.get_current_api_key_writer)],
+):
+    ...
+```
+
+Effective authority is an intersection, and every dimension can only narrow it:
+
+```text
+owner's current role  ∩  key access_mode  ∩  matching audience  ∩  route policy
+```
+
+So a `read_only` key owned by a writer cannot write; a `read_write` key owned by
+a reader cannot write; and deactivating an owner denies every key they hold.
+
+**API keys never carry administrative or superuser authority** — not from the
+owner's role, not from `is_superuser`, and not by configuration. There is no
+`get_current_api_key_admin`/`_superuser` dependency and no setting that creates
+one; `require_api_key_role()` raises `ApiKeyCapabilityCeilingError` at wiring
+time for anything above `WRITER`. Keep those operations on the JWT guards.
+
+> **Depending on `get_current_api_key_principal` never implies write
+> capability.** It proves only that the key resolves to a live owner. Every
+> capability-bearing route must use a role dependency.
+
+Responses:
+
+- `401 Invalid or expired API key` — one generic denial covering an unknown,
+  revoked, or expired key *and* every owner-state cause, so a caller cannot probe
+  another account's state
+- `403 Forbidden` — the owner's role or the key's access mode is insufficient
+- `429` — the key's quota is exhausted; the issuer's `Retry-After` is relayed
+- `503` — the principal could not be confirmed (issuer outage, timeout, open
+  circuit, shed load, or a response this release cannot interpret). **Always a
+  denial** — there is no fallback to a cached principal or to bare key validity
+
+---
+
 ## Health Endpoint
 
 Mounted automatically at `GET {API_PREFIX}/health/` (e.g. `/api/health/`).
@@ -1422,6 +1568,7 @@ async def test_health(client):
 
 | `fastapi-m8` | `auth-sdk-m8` | Python |
 |---|---|---|
+| `4.0.0` | `>=3.0.0, <4.0.0` | 3.11, 3.12, 3.13, 3.14 |
 | `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 |