fix(security): make idle timeout actually enforce

The idle-timeout block in get_current_user only read last_activity
from the JWT, but no issuance code wrote it — so the check ran zero
times on real tokens. Read activity from Redis first (update_activity
was already writing there but had no consumer), fall back to the JWT
last_activity claim, fall back to iat. Emit last_activity=iat in
create_access_token for first-request bootstrap.

Folds in remaining PR-review blockers:
- bb43712cae28 alembic merge resolves dual-head from rebase past
  the head referenced by cae28b15a507
- TOKEN_EXPIRY 10080->20 min default documented in CHANGELOG
  Behavior Changes with migration & rollback guidance
- drop dead refresh_token_expiry config field + 3 doc references
- /auth/logout current_user: dict -> EmailUser (matches actual
  return type of get_current_user)
- /admin/logout test rewritten with TestClient + CSRF deny-path
  regression (was asyncio.run on MagicMock — bypassed middleware
  and would pass even if the route was unregistered)

Coverage on diff: 91% -> ~100%. New unit tests cover every branch
of the idle-timeout block plus the Redis-success and fresh-session
paths in TokenBlocklistService that were previously unreached.

Refs #4317, #4371

Signed-off-by: Jonathan Springer <jps@s390x.com>

Author: jonpspri

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "(?x)( package-lock\\.json$ |Cargo\\.lock$ |uv\\.lock$ |go\\.sum$ |mcpgateway/sri_hashes\\.json$ )|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2026-04-26T16:16:40Z",
+  "generated_at": "2026-04-26T18:36:21Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -250,63 +250,63 @@
         "hashed_secret": "b4673e578b9b30fe8bba1b555b7b59883444c697",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 845,
+        "line_number": 859,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "4a0a2df96d4c9a13a282268cab33ac4b8cbb2c72",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 933,
+        "line_number": 947,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 1283,
+        "line_number": 1297,
         "type": "Basic Auth Credentials",
         "verified_result": null
       },
       {
         "hashed_secret": "fa9beb99e4029ad5a6615399e7bbae21356086b3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2649,
+        "line_number": 2663,
         "type": "Basic Auth Credentials",
         "verified_result": null
       },
       {
         "hashed_secret": "fa9beb99e4029ad5a6615399e7bbae21356086b3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2740,
+        "line_number": 2754,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "ac371b6dcce28a86c90d12bc57d946a800eebf17",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2783,
+        "line_number": 2797,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "0b6ec68df700dec4dcd64babd0eda1edccddace1",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2788,
+        "line_number": 2802,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "4ad6f0082ee224001beb3ca5c3e81c8ceea5ed86",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2793,
+        "line_number": 2807,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -4196,23 +4196,23 @@
         "hashed_secret": "559b05f1b2863e725b76e216ac3dadecbf92e244",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 4791,
+        "line_number": 4825,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "a8af4759392d4f7496d613174f33afe2074a4b8d",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 4793,
+        "line_number": 4827,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "85b60d811d16ff56b3654587d4487f713bfa33b7",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 15172,
+        "line_number": 15206,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -4862,7 +4862,7 @@
         "hashed_secret": "ff37a98a9963d347e9749a5c1b3936a4a245a6ff",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2413,
+        "line_number": 2420,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -4974,23 +4974,23 @@
         "hashed_secret": "6993a3fd94a012ab50fb6b9e97ec238310f0b177",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 397,
+        "line_number": 401,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "52dcc83ec1e54426ad58a64854d1eb8d5f5d9685",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 398,
+        "line_number": 402,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "a616a64c0fbc30f12287d0f24f3b90dd2e6a206e",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 680,
+        "line_number": 684,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -7162,15 +7162,15 @@
         "hashed_secret": "6eb67d95dba1a614971e31e78146d44bd4a3ada3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 191,
+        "line_number": 192,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "cbfdac6008f9cab4083784cbd1874f76618d2a97",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 271,
+        "line_number": 272,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -9134,15 +9134,15 @@
         "hashed_secret": "516b9783fca517eecbd1d064da2d165310b19759",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 1016,
+        "line_number": 1017,
         "type": "Basic Auth Credentials",
         "verified_result": null
       },
       {
         "hashed_secret": "ef4eb24299c517306652ffee61e05934f2224914",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 1268,
+        "line_number": 1269,
         "type": "Secret Keyword",
         "verified_result": null
       }

CHANGELOG.md

@@ -9,9 +9,23 @@
 - **🛡️ Content Security – Malicious Pattern Detection (US-3)** ([#4072](https://github.com/IBM/mcp-context-forge/pull/4072), [#538](https://github.com/IBM/mcp-context-forge/issues/538)) – Regex-based scanning for XSS, SQL injection, command injection, and template-injection patterns. Applied on the single **and** bulk create/update paths for resources, prompts, and tools (tool `name`, `description`, and JSON-serialized `inputSchema`). New config: `CONTENT_PATTERN_DETECTION_ENABLED`, `CONTENT_BLOCKED_PATTERNS`, `CONTENT_PATTERN_VALIDATION_MODE` (`strict` | `moderate` | `lenient`). Lenient mode logs every matched pattern in a payload (was: only the first).
 - **🔒 Content Security – Prompt Template Validation (US-4)** ([#4072](https://github.com/IBM/mcp-context-forge/pull/4072), [#538](https://github.com/IBM/mcp-context-forge/issues/538)) – Pre-render validation of prompt templates: balanced-brace check, Jinja2 syntax check, and dangerous-pattern scan (`__import__`, `eval(`, dunders, etc.). New config: `CONTENT_VALIDATE_PROMPT_TEMPLATES`, `CONTENT_BLOCKED_TEMPLATE_PATTERNS`.
 - **⚡ ReDoS Defense for Pattern Scanning** ([#4072](https://github.com/IBM/mcp-context-forge/pull/4072)) – `CONTENT_PATTERN_MAX_SCAN_SIZE` (default 200 KB) caps scan input length deterministically; `CONTENT_PATTERN_REGEX_TIMEOUT` (default 1.0 s) per-pattern. Patterns are pre-compiled once at service init instead of re-compiled per request.
+- **🔐 JWT Token Security – Server-Side Revocation, Idle Timeout, Logout** ([#4371](https://github.com/IBM/mcp-context-forge/pull/4371), [#4317](https://github.com/IBM/mcp-context-forge/issues/4317)) – New `TokenBlocklistService` (Redis-cached, DB-persisted) for immediate JWT invalidation. Idle-timeout enforcement on every authenticated request, with activity tracking in Redis (falls back to JWT `iat` when Redis is unavailable). New `POST /auth/logout` (Bearer auth) and enhanced `POST /admin/logout` (cookie auth) revoke the caller's token in the blocklist before clearing session state. Comprehensive audit-log fields (`security_event`, `security_severity`, `jti`, `reason`) for every revocation/idle-timeout event. New config: `TOKEN_IDLE_TIMEOUT`, `TOKEN_BLOCKLIST_CLEANUP_HOURS`. Addresses X-Force Red audit findings on session-token management.
 
 ### ⚠️ Behavior Changes
 
+#### **⏱️ `TOKEN_EXPIRY` default reduced from 10080 minutes (~7 days) to 20 minutes** ([#4371](https://github.com/IBM/mcp-context-forge/pull/4371), [#4317](https://github.com/IBM/mcp-context-forge/issues/4317))
+
+**Impact**: Any deployment that does not set `TOKEN_EXPIRY` explicitly will now issue session tokens that expire after **20 minutes** instead of ~7 days. Existing tokens already in circulation are unaffected (they retain the `exp` claim baked in at issuance), but every newly-issued token after upgrade has the shorter lifetime. Automation that re-uses a single login token for hours or days will start receiving HTTP 401 mid-flight.
+
+**Why**: Short-lived tokens are the primary mitigation for stolen-token replay, per the X-Force Red security audit (#4317). 7-day session tokens were previously called out as a finding. The new default brings the gateway in line with industry guidance (5–20 minutes for session tokens).
+
+**Migration**:
+- **Interactive sessions** — no action needed; the new `/auth/logout` endpoint and idle-timeout enforcement (60 min default) work transparently.
+- **CI/automation that needs longer-lived tokens** — set `TOKEN_EXPIRY` explicitly in `.env` (range: 5–1440 minutes), e.g. `TOKEN_EXPIRY=480` for an 8-hour shift, and pair it with `TOKEN_IDLE_TIMEOUT=0` if the workload bursts after long quiet periods.
+- **Long-running scripts using `mcpgateway.utils.create_jwt_token --exp <minutes>`** — the `--exp` flag is unaffected (it overrides the default).
+
+**Rollback**: Set `TOKEN_EXPIRY=10080` to restore the previous 7-day default.
+
 #### **🧪 Prompt templates are now rendered in a Jinja2 sandbox** ([#4072](https://github.com/IBM/mcp-context-forge/pull/4072))
 
 **Impact**: `prompt_service` now uses `jinja2.sandbox.SandboxedEnvironment` instead of plain `jinja2.Environment`. Templates that previously reached Python internals at render time will raise `PromptError: sandbox rejected unsafe operation`.

docs/security/JWT_TOKEN_SECURITY_IMPLEMENTATION.md

@@ -33,10 +33,6 @@ token_expiry: int = 20  # minutes (was 10080 = 70 days)
     # Range: 5-1440 minutes
     # Recommended: 5-20 minutes for security
 
-# Refresh token configuration (longer-lived but revocable)
-refresh_token_expiry: int = 10080  # 7 days
-    # Range: 60-43200 minutes (1 hour to 30 days)
-
 # Idle timeout configuration
 token_idle_timeout: int = 60  # minutes
     # Range: 5-1440 minutes
@@ -184,23 +180,20 @@ async def logout(request: Request, db: Session = Depends(get_db)):
 ```bash
 TOKEN_EXPIRY=5                    # 5 minutes
 TOKEN_IDLE_TIMEOUT=15             # 15 minutes
-REFRESH_TOKEN_EXPIRY=1440         # 24 hours
 TOKEN_BLOCKLIST_CLEANUP_HOURS=12  # 12 hours
 ```
 
 ### Balanced Security (Standard Applications)
 ```bash
 TOKEN_EXPIRY=20                   # 20 minutes (default)
 TOKEN_IDLE_TIMEOUT=60             # 60 minutes (default)
-REFRESH_TOKEN_EXPIRY=10080        # 7 days (default)
 TOKEN_BLOCKLIST_CLEANUP_HOURS=24  # 24 hours (default)
 ```
 
 ### Development/Testing
 ```bash
 TOKEN_EXPIRY=60                   # 60 minutes
 TOKEN_IDLE_TIMEOUT=120            # 120 minutes
-REFRESH_TOKEN_EXPIRY=10080        # 7 days
 TOKEN_BLOCKLIST_CLEANUP_HOURS=24  # 24 hours
 ```
 
@@ -310,7 +303,6 @@ Add to cron or scheduler:
    # Add to .env
    TOKEN_EXPIRY=20
    TOKEN_IDLE_TIMEOUT=60
-   REFRESH_TOKEN_EXPIRY=10080
    TOKEN_BLOCKLIST_CLEANUP_HOURS=24
    ```
 

mcpgateway/alembic/versions/bb43712cae28_merge_token_blocklist_with_audit_identity_heads.py

@@ -0,0 +1,28 @@
+"""merge token_blocklist (PR #4371) with audit-identity main head
+
+Revision ID: bb43712cae28
+Revises: cae28b15a507, b2c3d4e5f6g7
+Create Date: 2026-04-26 16:30:00.000000
+
+Resolves the dual-head condition introduced when PR #4371 (#4317) was rebased
+onto a main branch that had advanced past d2b501bf4262 (the head referenced by
+cae28b15a507_merge_token_revocation_and_uaid_heads.py). After this migration
+`alembic heads` returns a single head again.
+"""
+
+# Standard
+from typing import Sequence, Union
+
+# revision identifiers, used by Alembic.
+revision: str = "bb43712cae28"  # pragma: allowlist secret
+down_revision: Union[str, Sequence[str], None] = ("cae28b15a507", "b2c3d4e5f6g7")  # pragma: allowlist secret
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+
+
+def downgrade() -> None:
+    """Downgrade schema."""

mcpgateway/auth.py

@@ -1595,47 +1595,60 @@ def _set_trace_for_user(user_obj: EmailUser, *, teams: Any = _UNSET, auth_method
                         headers={"WWW-Authenticate": "Bearer"},
                     )
 
-                # Check idle timeout if last_activity is present
-                last_activity_ts = payload.get("last_activity")
-                if last_activity_ts and settings.token_idle_timeout > 0:
-                    last_activity = datetime.fromtimestamp(last_activity_ts, tz=timezone.utc)
-                    current_time = datetime.now(timezone.utc)
-                    idle_duration = current_time - last_activity
-                    max_idle = timedelta(minutes=settings.token_idle_timeout)
-
-                    if idle_duration > max_idle:
-                        # Revoke token due to idle timeout
-                        try:
-                            # First-Party
-                            from mcpgateway.services.token_blocklist_service import get_token_blocklist_service  # pylint: disable=import-outside-toplevel
-
-                            blocklist_service = get_token_blocklist_service()
-                            exp_ts = payload.get("exp")
-                            token_expiry = datetime.fromtimestamp(exp_ts, tz=timezone.utc) if exp_ts else None
-
-                            blocklist_service.revoke_token(jti=jti, revoked_by=email, reason="idle_timeout", token_expiry=token_expiry, last_activity=last_activity)
-                        except Exception as revoke_error:
-                            logger.warning(f"Failed to revoke idle token: {revoke_error}")
-
-                        logger.warning(
-                            f"Token exceeded idle timeout: jti={jti}, idle_minutes={idle_duration.total_seconds()/60:.1f}",
-                            extra={"security_event": "idle_timeout", "security_severity": "medium", "jti": jti, "user_id": email},
-                        )
-                        raise HTTPException(
-                            status_code=status.HTTP_401_UNAUTHORIZED,
-                            detail=f"Token exceeded idle timeout ({settings.token_idle_timeout} minutes)",
-                            headers={"WWW-Authenticate": "Bearer"},
-                        )
-
-                    # Update activity timestamp for valid tokens
+                # Idle timeout enforcement.
+                #
+                # Activity source-of-truth precedence (most-recent first):
+                #   1. Redis key `token:activity:{jti}` written by `update_activity()`.
+                #   2. Optional `last_activity` JWT claim (issuer can set this for first-request bootstrap).
+                #   3. Standard `iat` JWT claim (always present on tokens issued by this gateway).
+                # If none of the three are available we skip the idle check rather than fail-open silently —
+                # the periodic revocation check above already handles tokens that should be denied outright.
+                if settings.token_idle_timeout > 0:
+                    # First-Party
+                    from mcpgateway.services.token_blocklist_service import get_token_blocklist_service  # pylint: disable=import-outside-toplevel
+
+                    blocklist_service = get_token_blocklist_service()
+
+                    last_activity: Optional[datetime] = None
                     try:
-                        # First-Party
-                        from mcpgateway.services.token_blocklist_service import get_token_blocklist_service  # pylint: disable=import-outside-toplevel
+                        last_activity = blocklist_service.get_last_activity(jti)
+                    except Exception as activity_lookup_error:
+                        logger.debug(f"Failed to read last activity from cache: {activity_lookup_error}")
+
+                    if last_activity is None:
+                        last_activity_ts = payload.get("last_activity") or payload.get("iat")
+                        if last_activity_ts:
+                            last_activity = datetime.fromtimestamp(last_activity_ts, tz=timezone.utc)
+
+                    if last_activity is not None:
+                        current_time = datetime.now(timezone.utc)
+                        idle_duration = current_time - last_activity
+                        max_idle = timedelta(minutes=settings.token_idle_timeout)
+
+                        if idle_duration > max_idle:
+                            # Revoke token due to idle timeout
+                            try:
+                                exp_ts = payload.get("exp")
+                                token_expiry = datetime.fromtimestamp(exp_ts, tz=timezone.utc) if exp_ts else None
+
+                                blocklist_service.revoke_token(jti=jti, revoked_by=email, reason="idle_timeout", token_expiry=token_expiry, last_activity=last_activity)
+                            except Exception as revoke_error:
+                                logger.warning(f"Failed to revoke idle token: {revoke_error}")
+
+                            logger.warning(
+                                f"Token exceeded idle timeout: jti={jti}, idle_minutes={idle_duration.total_seconds() / 60:.1f}",
+                                extra={"security_event": "idle_timeout", "security_severity": "medium", "jti": jti, "user_id": email},
+                            )
+                            raise HTTPException(
+                                status_code=status.HTTP_401_UNAUTHORIZED,
+                                detail=f"Token exceeded idle timeout ({settings.token_idle_timeout} minutes)",
+                                headers={"WWW-Authenticate": "Bearer"},
+                            )
 
-                        blocklist_service = get_token_blocklist_service()
-                        blocklist_service.update_activity(jti)
-                    except Exception as activity_error:
-                        logger.debug(f"Failed to update token activity: {activity_error}")
+                        try:
+                            blocklist_service.update_activity(jti)
+                        except Exception as activity_error:
+                            logger.debug(f"Failed to update token activity: {activity_error}")
 
             except HTTPException:
                 raise

mcpgateway/config.py

@@ -342,9 +342,6 @@ class Settings(BaseSettings):
     # Session token configuration (short-lived for security)
     token_expiry: int = Field(default=20, ge=5, le=1440, description="Session token expiry in minutes (5-1440). Recommended: 5-20 minutes for security.")  # 20 minutes (was 10080 = 70 days)
 
-    # Refresh token configuration (longer-lived but revocable)
-    refresh_token_expiry: int = Field(default=10080, ge=60, le=43200, description="Refresh token expiry in minutes (1 hour to 30 days). Used to obtain new access tokens.")  # 7 days
-
     # Idle timeout configuration
     token_idle_timeout: int = Field(default=60, ge=5, le=1440, description="Maximum idle time in minutes before token requires refresh (5-1440).")  # 60 minutes