agent-comms-mcp 0.1.0__py3-none-any.whl

agent_comms_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: agent-comms-mcp
+Version: 0.1.0
+Summary: MCP service for permissioned, structured agent-to-agent communications
+Author-email: Redesign Health <tech@redesignhealth.com>
+License: MIT
+Project-URL: Homepage, https://github.com/redesignhealth/agent-comms-mcp
+Project-URL: Repository, https://github.com/redesignhealth/agent-comms-mcp
+Project-URL: Issues, https://github.com/redesignhealth/agent-comms-mcp/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: alembic==1.18.5
+Requires-Dist: asyncpg==0.31.0
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: greenlet==3.5.4
+Requires-Dist: httpx==0.28.1
+Requires-Dist: py-key-value-aio[filetree]==0.4.5
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: sqlalchemy[asyncio]==2.0.51
+Requires-Dist: structlog==25.5.0
+Dynamic: license-file
+
+# agent-comms-mcp
+
+MCP service for **permissioned, structured agent-to-agent communications**.
+First use case: a user's main agent delegates to a dedicated EA agent, which
+communicates with other people's EA agents to negotiate availability (including
+judgment, not just calendar overlap). Communications are scoped and structured
+— no free text initially. See [`docs/DESIGN.md`](docs/DESIGN.md) for the full
+spec (data model, permission model, message schemas). EA agent logic lives
+elsewhere — this repo is only the comms layer.
+
+## Layout
+
+```
+main.py              # FastMCP server, observability + scope-enforcement middleware
+auth.py              # Okta OIDCProxy (humans) + agent-jwt JWTVerifier (agents) via MultiAuth
+scopes.py            # TOOL_SCOPES catalog + fail-closed scope helpers
+identity.py          # Issuer-gated JWT identity resolution (anti-impersonation guards)
+observability.py     # structlog JSON events (tool_call, scope_denial, auth_flow, ...)
+providers/comms.py   # Comms provider sub-server — the MCP tools (see below)
+models.py            # SQLAlchemy 2.x async ORM models (agents, conversations,
+                      #   participants, messages, audit_log — DESIGN.md §5)
+db.py                # Async engine/session factory (DATABASE_URL, fail-fast)
+schemas.py           # Pydantic message-payload schemas (all registered message types)
+state_machine.py     # Conversation/participant state transitions (DESIGN.md §4, §6)
+service.py           # Domain/service layer: membership rules, uniform denials, audit
+exceptions.py        # Service-layer exception shapes (mapped to ToolError in providers/comms.py)
+migrations/          # Alembic migrations (async env.py); run `alembic upgrade head`
+tests/               # pytest suite (composition, scope fail-closed, domain logic, schema)
+```
+
+## Domain layer
+
+The comms board is five Postgres tables — `agents`, `conversations`,
+`participants`, `messages`, `audit_log` — with `messages` and
+`audit_log` append-only. An agent self-provisions via `comms_register`,
+then either starts a conversation (adding named targets as `invited`) or
+gets invited into one. A target only gains message-history read/write
+access after calling `comms_accept` (`invited → active`); declining
+(`comms_decline_invite`) is terminal and grants nothing. Task coordination
+uses task message types (`task_assign`, `task_report`, `task_complete`,
+`task_decline`, `task_cancel`) within ordinary conversations — task state
+lives on `conversations.state`, not a separate table. Conversation types
+(`open`, `internal`, `asymmetric`) gate admission by ownership; message
+types gate boundary crossing via the `boundary_safe` flag — see
+[`docs/DESIGN.md`](docs/DESIGN.md) §4–§9 for full details.
+
+## MCP tool surface
+
+All tools below are mounted under the `comms` namespace (e.g. `whoami` in
+`providers/comms.py` is exposed as `comms_whoami`) and enrolled in the
+fail-closed `scopes.TOOL_SCOPES` registry. Source of truth:
+`providers/comms.py`.
+
+| Tool | Scope | Purpose |
+|---|---|---|
+| `comms_whoami` | `comms:read` | Return the caller's identity, issuer, caller type, and scopes |
+| `comms_register` | `comms:write` | Idempotently self-provision (or re-bind) the caller's board `Agent` row |
+| `comms_list_agents` | `comms:read` | Paginated board directory |
+| `comms_start_conversation` | `comms:write` | Open a conversation with N target agents and post the seq-1 message |
+| `comms_post_message` | `comms:write` | Post a typed, schema-validated message to an active conversation |
+| `comms_get_conversation` | `comms:read` | Combined read: conversation + participants + messages since a seq; advances the caller's read cursor |
+| `comms_inbox` | `comms:read` | Active conversations with unread messages, plus pending invites |
+| `comms_list_conversations` | `comms:read` | Paginated list, filterable by role/type/state; newest-first |
+| `comms_accept` | `comms:write` | Flip the caller's participant status `invited → active`, granting history read + posting rights |
+| `comms_decline_invite` | `comms:write` | Decline a pending invite — terminal, no access is ever granted |
+| `comms_invite` | `comms:write` | Invite another board agent into an active conversation (as `invited`) |
+| `comms_leave` | `comms:write` | Leave a conversation the caller is currently `active` in |
+
+## Auth model
+
+Both humans and machines POST to the same `/mcp` endpoint; FastMCP
+`MultiAuth` routes them (`/health` is unauthenticated):
+
+- **Humans** (Claude Code / Claude Desktop / browser): Okta OIDC via FastMCP
+  `OIDCProxy`. Identity claims (email) are available to tools via
+  `get_access_token().claims`. Interactive callers bypass per-tool scope
+  checks.
+- **Agents / services**: HS256 Bearer JWT with `iss="agent-jwt"`, `sub`, and
+  `scopes` claims, verified by a `JWTVerifier` keyed to `AGENT_JWT_SECRET`.
+  Every tool call is then gated by the `TOOL_SCOPES` catalog in `scopes.py`
+  — **fail-closed**: a tool without a registry entry rejects every agent
+  call, denial messages are uniform (anti-enumeration), and each denial emits
+  a structured `scope_denial` log event.
+
+When adding a tool, enroll its mounted name (`comms_<tool>`) in
+`TOOL_SCOPES` in the same PR — `tests/test_main.py` fails otherwise.
+
+## Local development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                      # install deps from uv.lock
+
+# Start Postgres, apply migrations, then run the tests (see "Database /
+# migrations" below for why the port is 55432, not 5432)
+docker compose up -d postgres
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head
+uv run pytest                # tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy .                # strict type check
+
+# Run the server (needs real Okta + secret config)
+cp .env.example .env         # fill in values; .env is gitignored
+uv run python main.py        # http://127.0.0.1:8080/mcp
+
+# Or the full stack (server + Postgres) in Docker
+docker compose up --build
+```
+
+Tests never touch the network: the Okta OIDC discovery call is patched out
+in every test module that imports `main` (see `tests/test_main.py`'s
+`_OIDC_PATCH`), so `uv run pytest` needs no real Okta tenant, issuer
+reachability, or credentials — only a reachable Postgres for the
+real-database tests (below), which skip cleanly if it's absent.
+
+### Database / migrations
+
+Postgres is provisioned by `docker-compose.yml`, mapped to **host port
+55432** (container-internal port stays the standard 5432). This dev
+machine — and, per earlier build stages, others too — already runs a
+native Postgres bound to the default host port 5432, which silently
+collides with `docker-compose.yml`'s old `5432:5432` mapping (you'd connect
+to the wrong database with no error). Moving the compose Postgres's
+*host-side* port to 55432 sidesteps this permanently; nothing about the
+container's internal networking changes, so the `agent-comms-mcp`
+service's own `DATABASE_URL` (which reaches `postgres` by service name on
+the internal port 5432) is unaffected.
+
+After starting Postgres, apply migrations before running the service or
+the real-database tests:
+
+```bash
+docker compose up -d postgres      # start Postgres only (host port 55432)
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head        # create/upgrade the 5-table schema
+```
+
+If you still hit a conflict (e.g. something else is bound to 55432), check
+with `lsof -i :55432` and either free the port or change the host-side
+number in `docker-compose.yml`'s `ports:` mapping for the `postgres`
+service (updating `DATABASE_URL` to match) — a single fixed alternate port
+is enough here, so there's no compose-override or env-var indirection.
+
+To generate a new migration after changing `models.py`:
+
+```bash
+uv run alembic revision --autogenerate -m "<description>"
+```
+
+`tests/test_db_models.py` (and the other real-database test modules) run
+against this same real Postgres instance (no mocking, per the RH standard)
+and skip gracefully with a clear reason if they can't connect.
+
+Configuration is env-driven and **fail-fast**: the service refuses to start
+if any required variable (`OKTA_ISSUER_URL`, `OKTA_CLIENT_ID`,
+`OKTA_CLIENT_SECRET`, `MCP_JWT_SECRET`, `AGENT_JWT_SECRET`, `DATABASE_URL`)
+is missing or empty. See `.env.example` for the full list. No secrets are committed
+anywhere in this repo.
+
+## Observability
+
+Structured JSON logs via `structlog` to stdout. Events follow the schema in
+`observability.py` (`tool_call`, `user_active`, `auth_flow`, `auth_rejected`,
+`scope_denial`). Message content and attacker-controlled claim values are
+never logged.
+
+## Deployment
+
+The service is a standard Python HTTP process backed by PostgreSQL. The
+included `Dockerfile` and `docker-compose.yml` cover local and self-hosted
+deployments.
+
+**Quick start (Docker Compose):**
+
+```bash
+cp .env.example .env   # fill in real values
+docker compose up --build
+```
+
+**Required environment variables** (see `.env.example`):
+
+| Variable | Purpose |
+|---|---|
+| `OKTA_ISSUER_URL` | Okta OIDC issuer URL for interactive callers |
+| `OKTA_CLIENT_ID` | Okta app client ID |
+| `OKTA_CLIENT_SECRET` | Okta app client secret |
+| `MCP_JWT_SECRET` | Signing secret for FastMCP's internal OAuth JWTs |
+| `AGENT_JWT_SECRET` | Shared HS256 secret for agent JWT verification |
+| `DATABASE_URL` | PostgreSQL connection string |
+
+`entrypoint.sh` runs `alembic upgrade head` automatically on every container
+start, so migrations apply before the server accepts traffic.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agent_comms_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+auth.py,sha256=hgA0BwQlgbNj4sEM6oXibS0QhtdslG9Ncxpw5X7Whto,15620
+db.py,sha256=OoVCXNc2CcitURxncXs3k14IpsMoXwYXAI2akKYyr3Q,2452
+exceptions.py,sha256=yKxfSkWfGwaUn5IU0lUzOVIGnw8fU5xlq4nZEswylqM,5063
+identity.py,sha256=wcyzDCQIhOoGBXuqboCzzegKMLxmHuED76yTIzpgm20,3803
+main.py,sha256=QxdQihFrZ81JS6b45aSjfx93wcUrnORhbw-MR3q2e68,12047
+models.py,sha256=Uagazi4HXxuN3Hn85goeeTQxNf4oUjbmdZhtSF05yTc,9722
+observability.py,sha256=wHAW1epj83NwBJN4n-1onD4qpd2HzAdAn5Qp5ailEBA,9250
+schemas.py,sha256=neU165FEWvXkkeWIYMuaLKs6ULwb1G75X_LPXpishZE,22218
+scopes.py,sha256=hYjWdI2q4xOi1BtL1Vgf4xt55aceYePyChvoJPTs4nc,6964
+service.py,sha256=Ev4Bb8GIORfG8P1UldTk_TnkyKW7qu8RbHpVjZA_UkI,90360
+state_machine.py,sha256=pLMAOUcI7Z0YOC4J7yq3wqNLqD2n2b8bKs-eSbsG-js,6388
+agent_comms_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=GaHnR5bjXQbO7TqD7vtfQkwoR7xlKYtOHW9ryBtkMkk,1072
+migrations/env.py,sha256=AWZUJ5uaj77kHEk4gAw3iN8PuP61FmxrOPXe_PV5cII,3783
+migrations/versions/15ef34885e30_add_conversations_owner_snapshot.py,sha256=yGGUIYD3-WqcgV2Rlgl-60gcoshZzBI8QxPUv7b1uBs,2682
+migrations/versions/18f2d7735523_rate_limit_indexes_and_display_name_.py,sha256=AbcUz4AOwxxIVgUub2c46tO2li2-a1kT7GplSSiACIE,5575
+migrations/versions/6d2a8e63e469_add_tasks_table.py,sha256=SfbBSBYhBkdk2IMQqIx--G20lpjvocQWZsBat47NQqE,5873
+migrations/versions/da3e1646c44d_drop_tasks_table.py,sha256=hENB-aEAjAytoR3zl8XhLASRjeIqTAxeECHpOxEgR1A,8141
+migrations/versions/e1db7c2e6b70_backfill_accepted_types_for_existing_.py,sha256=URRmhDNrI9uyQ1zbN35IJFc81rUP0sUdam7zzf1r4KU,4548
+migrations/versions/ef8394b37c8d_initial_schema.py,sha256=BnYqb3MjDGHpXNbL-dcspuarH7SJVCWCAi53l29fisk,7136
+providers/__init__.py,sha256=QTIQr_6KA51kiKpI5rjms596Ba93TcNEjB-mlcs_8eo,286
+providers/comms.py,sha256=RKdre3dSGAFW6Cl6_w-jep79-wK0aG9gGsdnrJ1zKds,31430
+agent_comms_mcp-0.1.0.dist-info/METADATA,sha256=dDSyPhB78UwW7vWu6YE5Nqr9ikk5PoAeAKa3JFePHaY,10523
+agent_comms_mcp-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agent_comms_mcp-0.1.0.dist-info/entry_points.txt,sha256=hFM0cDbPbq9MndmdpuIVOKKvZ-BIwrqotMVO9XLdv3M,46
+agent_comms_mcp-0.1.0.dist-info/top_level.txt,sha256=8d1AS-g_iAfdLckXqiIJKwExMLKze4DkRQTRfceZlx8,112
+agent_comms_mcp-0.1.0.dist-info/RECORD,,

agent_comms_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_comms_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-comms-mcp = main:_cli

agent_comms_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Redesign Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_comms_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,13 @@
+auth
+db
+exceptions
+identity
+main
+migrations
+models
+observability
+providers
+schemas
+scopes
+service
+state_machine

auth.py

@@ -0,0 +1,343 @@
+"""Okta OIDC + agent-jwt JWT authentication for agent-comms-mcp.
+
+Auth paths
+----------
+Interactive users (Claude Code, Claude Desktop, browser):
+    Okta OIDC via FastMCP ``OIDCProxy``. Uses ``verify_id_token=True`` so
+    FastMCP validates the Okta id_token (which carries identity claims like
+    ``email`` and ``preferred_username``) and makes those claims available
+    to tools via ``get_access_token().claims``.
+
+Programmatic callers (agents, services, CI jobs):
+    agent-jwt HS256 Bearer token. FastMCP ``MultiAuth`` composes the Okta
+    OIDC provider with a ``JWTVerifier`` keyed to ``AGENT_JWT_SECRET``.
+    Both humans and machines POST to the same ``/mcp`` endpoint.
+
+Health check (``/health``):
+    Unauthenticated — handled by FastMCP before auth middleware runs.
+
+Refresh-token rotation grace (``_ROTATION_*``): FastMCP rotates refresh
+tokens on every use (one-time use). A second concurrent connection
+presenting the just-consumed old token would otherwise fail hard and force
+a full Okta re-auth. We record a short-lived old-token-hash -> new-token
+mapping in the same persistent store on every rotation; a subsequent "miss"
+checks this mapping first and transparently follows it before declaring a
+real miss.
+
+The hop counter is deliberately NOT a parameter of the public
+``load_refresh_token`` override (see that method's own docstring) to close
+a cap-reset weakness in a more permissive design.
+
+Emitting ``refresh_token_miss`` / ``refresh_token_hop_cap_exceeded`` on
+paths that previously logged nothing means a broad ``$.event = "auth_flow"``
+log filter now also counts failed refresh lookups as auth activity — add
+dedicated metric filters as needed (see observability.py's docstring).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from fastmcp.server.auth import MultiAuth
+from fastmcp.server.auth.oidc_proxy import OIDCProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from key_value.aio.protocols import AsyncKeyValue
+from key_value.aio.stores.filetree import (
+    FileTreeStore,
+    FileTreeV1CollectionSanitizationStrategy,
+    FileTreeV1KeySanitizationStrategy,
+)
+from mcp.server.auth.provider import AuthorizationCode, RefreshToken
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+
+from identity import AGENT_JWT_ISSUER
+from observability import log_auth_flow
+
+logger = logging.getLogger(__name__)
+
+# Claims to extract from the Okta ID token into the FastMCP JWT.
+_UPSTREAM_CLAIM_KEYS = ["sub", "email", "preferred_username", "name"]
+
+_DEFAULT_TOKEN_STORAGE_PATH = "/data/fastmcp-tokens"
+
+_ROTATION_GRACE_SECONDS = 5 * 60
+_ROTATION_MAX_HOPS = 3
+_ROTATION_COLLECTION = "mcp-refresh-token-rotations"
+
+
+def _hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+def require_env(name: str) -> str:
+    """Return a required environment variable, failing fast if missing/empty.
+
+    No silent defaults for secrets (RH security standard + the
+    secret-loading-fallback-consistency failure mode): a missing required
+    value must crash at startup, not surface later as a broken auth path.
+    """
+    value = os.environ.get(name)
+    if not value:
+        raise RuntimeError(
+            f"Required environment variable {name} is not set. "
+            "See .env.example for the full list of required configuration."
+        )
+    return value
+
+
+class OktaOIDCProxy(OIDCProxy):
+    """OIDC proxy configured for Okta SSO.
+
+    ``_extract_upstream_claims`` embeds the Okta id_token identity claims in
+    the FastMCP JWT as a fallback for code paths that read from there; with
+    ``verify_id_token=True`` the claims are also available directly. Emits
+    structured ``auth_flow`` observability events.
+    """
+
+    def __init__(self, *, client_storage: AsyncKeyValue, **kwargs: Any) -> None:
+        self._rotation_store = client_storage
+        super().__init__(client_storage=client_storage, **kwargs)
+
+    async def _extract_upstream_claims(self, idp_tokens: dict[str, Any]) -> dict[str, Any] | None:
+        """Decode the Okta ID token and extract identity claims.
+
+        SECURITY (call-ordering dependency): this decodes the id_token
+        payload WITHOUT verifying its signature. That is safe ONLY because
+        the parent ``OIDCProxy`` has already verified the token earlier in
+        the OAuth exchange (this hook runs downstream of that verification,
+        not before it) — if that call ordering ever changes, this becomes a
+        forgeable trust boundary (an attacker-controlled payload would be
+        trusted as identity claims).
+
+        Defense-in-depth only (does not replace the ordering dependency
+        above): reject ``alg: none`` tokens outright rather than extracting
+        claims from them. This protects a misconfigured dev/test
+        environment where the parent-class verification hasn't actually
+        run yet — it is not a substitute for that verification.
+        """
+        id_token = idp_tokens.get("id_token")
+        if not id_token:
+            return None
+        try:
+            header_b64 = id_token.split(".")[0]
+            header_b64 += "=" * (-len(header_b64) % 4)  # base64 padding
+            header = json.loads(base64.urlsafe_b64decode(header_b64))
+            if not isinstance(header, dict):
+                logger.error("Rejecting Okta id_token with non-object header")
+                return None
+            if str(header.get("alg", "")).lower() == "none":
+                logger.error("Rejecting Okta id_token with alg=none")
+                return None
+            # Decode the JWT payload without verification — the upstream
+            # provider already validated the token during the auth flow.
+            payload_b64 = id_token.split(".")[1]
+            payload_b64 += "=" * (-len(payload_b64) % 4)  # base64 padding
+            payload = json.loads(base64.urlsafe_b64decode(payload_b64))
+            if not isinstance(payload, dict):
+                logger.error("Rejecting Okta id_token with non-object payload")
+                return None
+            claims = {k: payload[k] for k in _UPSTREAM_CLAIM_KEYS if k in payload}
+            return claims or None
+        except (IndexError, json.JSONDecodeError, ValueError):
+            logger.error("Failed to decode Okta id_token for upstream claims")
+            return None
+
+    async def exchange_authorization_code(
+        self,
+        client: OAuthClientInformationFull,
+        authorization_code: AuthorizationCode,
+    ) -> OAuthToken:
+        """Exchange authorization code and emit a ``new_auth`` event."""
+        result = await super().exchange_authorization_code(client, authorization_code)
+        log_auth_flow("new_auth")
+        return result
+
+    async def load_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: str,
+    ) -> RefreshToken | None:
+        """Look up a refresh token, following a rotation-grace redirect on miss.
+
+        FastMCP rotates refresh tokens on every use (one-time use). A second
+        concurrent connection presenting the just-consumed old token would
+        otherwise fail hard here and force a full Okta re-auth. Before
+        declaring a real miss, check whether this token was rotated recently
+        and, if so, transparently follow it to its successor (capped at
+        ``_ROTATION_MAX_HOPS`` to bound a pathological chain).
+
+        No hop counter in this signature on purpose: it's the base class's
+        override point (FastMCP calls it positionally), so a public
+        ``_hops`` parameter would let any caller reset the cap. Hop-tracking
+        lives in the name-mangled ``__follow_rotation_grace`` instead.
+        """
+        result = await super().load_refresh_token(client, refresh_token)
+        if result is not None:
+            return result
+        return await self.__follow_rotation_grace(client, refresh_token, hops=0)
+
+    async def __follow_rotation_grace(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: str,
+        *,
+        hops: int,
+    ) -> RefreshToken | None:
+        """Recursive hop-following helper for ``load_refresh_token``.
+
+        Double-underscore (name-mangled to ``_OktaOIDCProxy__follow_rotation_grace``)
+        rather than single, mainly to avoid an accidental same-name collision
+        in a subclass -- NOT an access-control guarantee. Name mangling is
+        trivially bypassable (``self._OktaOIDCProxy__follow_rotation_grace(...,
+        hops=0)`` from a subclass, or simply overriding ``load_refresh_token``
+        itself), so it does not by itself defend against a malicious
+        subclass. The actual hardening that closed the original weakness is
+        that ``hops`` is not a parameter of the PUBLIC ``load_refresh_token``
+        override point FastMCP calls -- an ordinary caller (not a subclass
+        author deliberately reaching for the mangled name) has no way to
+        supply it at all.
+        """
+        entry = await self._rotation_store.get(
+            collection=_ROTATION_COLLECTION, key=_hash_token(refresh_token)
+        )
+        successor = entry.get("new_token") if entry is not None else None
+        if successor and hops < _ROTATION_MAX_HOPS:
+            logger.info("Refresh token reuse detected: redirecting to rotated successor")
+            log_auth_flow("refresh_token_grace_redirect")
+            result = await super().load_refresh_token(client, successor)
+            if result is not None:
+                return result
+            return await self.__follow_rotation_grace(client, successor, hops=hops + 1)
+        if successor:
+            # A dedicated auth_type, not folded into refresh_token_miss:
+            # the chain kept going past the cap, which is a structurally
+            # different condition from "no rotation entry at all" and
+            # needs its own CloudWatch signal for on-call triage. hops is
+            # not sensitive; the token/its hash is deliberately NOT
+            # included here (observability.py's never-log-tokens policy).
+            logger.warning("Refresh token rotation-grace hop cap exceeded", extra={"hops": hops})
+            log_auth_flow("refresh_token_hop_cap_exceeded")
+            return None
+        log_auth_flow("refresh_token_miss")
+        return None
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,
+        scopes: list[str],
+    ) -> OAuthToken:
+        """Exchange refresh token, emit a ``token_refresh`` event, and record
+        the old->new rotation mapping for the grace window."""
+        old_token = refresh_token.token
+        result = await super().exchange_refresh_token(client, refresh_token, scopes)
+        log_auth_flow("token_refresh")
+        if result.refresh_token:
+            # SECURITY: the stored value is the live successor refresh
+            # token in plaintext, not a hash -- the hashed KEY only
+            # prevents reverse-lookup of the just-consumed OLD token, it
+            # does not protect the new one. Accepted posture: this collection
+            # lives in the same EFS-backed, task-role-scoped store as the primary
+            # token store, which already holds live refresh tokens
+            # unencrypted (see build_okta_provider's client_storage). Anyone
+            # who can read one collection can read the other.
+            await self._rotation_store.put(
+                collection=_ROTATION_COLLECTION,
+                key=_hash_token(old_token),
+                value={"new_token": result.refresh_token},
+                ttl=_ROTATION_GRACE_SECONDS,
+            )
+        return result
+
+
+def _build_client_storage(storage_path: str) -> FileTreeStore:
+    """Build a FileTreeStore with standard V1 sanitization for CIMD-safe keys.
+
+    The stock ``FileTreeV1`` strategies hash any key or collection name
+    containing filesystem-unsafe characters, so URL-style client IDs are
+    stored safely on the persistent volume. The directory is created if
+    missing (the sanitization strategies require an existing path).
+    """
+    storage_root = Path(storage_path)
+    storage_root.mkdir(parents=True, exist_ok=True)
+    return FileTreeStore(
+        data_directory=storage_path,
+        key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(storage_root),
+        collection_sanitization_strategy=FileTreeV1CollectionSanitizationStrategy(storage_root),
+    )
+
+
+def build_okta_provider() -> OktaOIDCProxy:
+    """Build an OktaOIDCProxy from environment variables.
+
+    Required environment variables (fail-fast if missing):
+        OKTA_ISSUER_URL: Okta authorization server issuer URL
+        OKTA_CLIENT_ID: Okta application client ID
+        OKTA_CLIENT_SECRET: Okta application client secret
+        MCP_JWT_SECRET: Stable JWT signing secret (provisioned by Terraform,
+            injected via SSM)
+
+    Optional environment variables (non-secret, documented defaults):
+        BASE_URL: Public URL of this MCP server
+            (default: http://localhost:8080, for local dev)
+        MCP_TOKEN_STORAGE_PATH: Directory for persistent OAuth token storage
+            (default: /data/fastmcp-tokens, EFS-backed on ECS)
+    """
+    issuer_url = require_env("OKTA_ISSUER_URL")
+    config_url = f"{issuer_url.rstrip('/')}/.well-known/openid-configuration"
+    storage_path = os.environ.get("MCP_TOKEN_STORAGE_PATH", _DEFAULT_TOKEN_STORAGE_PATH)
+
+    return OktaOIDCProxy(
+        config_url=config_url,
+        client_id=require_env("OKTA_CLIENT_ID"),
+        client_secret=require_env("OKTA_CLIENT_SECRET"),
+        base_url=os.environ.get("BASE_URL", "http://localhost:8080"),
+        # offline_access is required for Okta to issue a refresh_token;
+        # without it clients must do a full re-auth every ~1 hour.
+        required_scopes=["openid", "email", "profile", "offline_access"],
+        jwt_signing_key=require_env("MCP_JWT_SECRET"),
+        client_storage=_build_client_storage(storage_path),
+        verify_id_token=True,
+        # FastMCP's CIMD redirect_uri validation rejects Claude Code's
+        # dynamic-port loopback callbacks.
+        enable_cimd=False,
+    )
+
+
+def build_auth_provider() -> MultiAuth:
+    """Compose Okta OIDC + agent-jwt JWT verification via FastMCP MultiAuth.
+
+    MultiAuth tries the Okta OIDCProxy first (interactive users), then the
+    JWTVerifier (programmatic agent-jwt tokens). The two paths are fully
+    independent.
+
+    Required environment variables:
+        AGENT_JWT_SECRET: Shared HS256 secret for verifying agent-jwt tokens.
+        (Plus everything required by ``build_okta_provider``.)
+    """
+    return MultiAuth(
+        server=build_okta_provider(),
+        verifiers=[
+            JWTVerifier(
+                public_key=require_env("AGENT_JWT_SECRET"),
+                algorithm="HS256",
+                issuer=AGENT_JWT_ISSUER,
+            ),
+        ],
+        # CRITICAL: do NOT inherit the Okta provider's
+        # required_scopes (["openid", "email", "profile", "offline_access"]).
+        # MultiAuth's bearer middleware enforces required_scopes against
+        # EVERY verified token — including agent-jwt M2M JWTs, which never
+        # carry `openid`. Inheriting them silently rejects all agent-jwt
+        # tokens with `insufficient_scope` even after a valid signature.
+        # Authorization for agent-jwt callers is handled per-tool by
+        # ScopeEnforcementMiddleware, so the provider-level gate must be
+        # empty.
+        required_scopes=[],
+    )