fix(security): enforce management-plane isolation for API tokens, fix team scoping, and fix blocked usage logging

[shoummu1]

Bug-fix PR

Summary

Fixes three security bugs in the API token lifecycle: token management endpoints could be accessed using API tokens (privilege escalation), team membership was not auto-inherited when creating tokens (broken scoping), and blocked/revoked token usage was never logged (invisible audit trail).

---

Related Issue

Closes: #3291

---

Root Cause

Bug 1 — Token Chaining (Privilege Escalation)

_require_authenticated_session() only blocked anonymous (unauthenticated) requests. It did not check auth_method, so an API token bearer could call POST /tokens, GET /tokens, DELETE /tokens/{id}, etc. — allowing an API token to create or revoke other tokens.

Bug 2 — Broken Team Inheritance

create_token() attempted to auto-populate team_id from the caller's team membership using current_user.get("teams"). However, get_current_user_with_permissions() (in rbac.py) injects teams into the user dict under the key token_teams — not teams. The lookup always returned None, so non-admin users who omitted team_id always created globally-scoped tokens regardless of their team membership.

Bug 3a — blocked Flag Always False

token_usage_middleware.py hardcoded blocked=False when logging authenticated API token requests, regardless of the actual HTTP response status code.

Bug 3b — Revoked/Expired Token Attempts Not Logged

When a revoked or expired API token was rejected (HTTP 401/403), the middleware exited early because request.state.auth_method is never set for failed auth. These attempts were silently dropped with no audit trail.

---

Fix Description

mcpgateway/routers/tokens.py

Bug 1: Added an explicit auth_method == "api_token" check inside _require_authenticated_session(), which is called at the top of all 11 token management endpoints:

if auth_method == "api_token":
    raise HTTPException(
        status_code=status.HTTP_403_FORBIDDEN,
        detail=(
            "Token management requires an interactive session (JWT from web login or SSO). "
            "API tokens cannot create, list, or revoke other tokens."
        ),
    )

Bug 2: Replaced the broken .get("teams") lookup with .get("token_teams") and introduced an effective_team_id variable with fallback logic for single-team non-admin users. Admin tokens remain globally scoped (team_id=null).

mcpgateway/middleware/token_usage_middleware.py

Bug 3a: Replaced blocked=False hardcode with blocked = status_code >= 400.

Bug 3b: Added a new elif status_code in (401, 403) branch that uses jwt.decode(..., options={"verify_signature": False}) to identify whether the rejected bearer token was an API token, then logs it with blocked=True and the appropriate block_reason ("revoked_or_expired" for 401, "http_403" for 403).

---

Verification

Bug	Test Method	Expected	Result
1 — Token Chaining	curl -H "Authorization: Bearer <api_token>" POST /tokens	HTTP 403	✅
2 — Team Inheritance	Create token as non-admin without team_id; check response	team_id auto-set to user's team	✅
3a — blocked flag	Create token, use it to make a bad request; check GET /tokens/{id}/stats	blocked_requests > 0	✅
3b — Revoked logging	Revoke token, attempt 3 calls with revoked token; check stats	total_requests >= 3, blocked_requests >= 3	✅

Unit tests: pytest tests/unit/mcpgateway/routers/test_tokens.py tests/unit/mcpgateway/middleware/test_token_usage_middleware.py → 100% pass

Full suite: pytest tests/unit/ → 694 passed, 15 skipped, 1 pre-existing unrelated failure in test_email_auth_service_admin_role_sync (unrelated to changed files).

---

📐 MCP Compliance (if relevant)

• Matches current MCP spec
• No breaking change to MCP clients

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• No secrets/credentials committed

---

[crivetimihai]

Thanks @shoummu1 — critical security fixes for #3291. The token chaining prevention, team inheritance fix, and audit logging improvements are all important. Well-documented root cause analysis. Make sure deny-path regression tests cover unauthenticated and wrong-team scenarios per project security invariants.

[crivetimihai]

Review Summary

Rebased onto main (clean, no conflicts), reviewed all changes, verified all three bugs, and added differential test coverage.

Bug Verification

All three bugs confirmed against main:

1. Token Chaining (Privilege Escalation) — _require_authenticated_session() only blocked None and "anonymous", allowing API tokens to manage other tokens. Fix correctly adds api_token denial.
2. Team Auto-Inheritance — main had no team auto-inheritance; tokens created without team_id got public-only scope silently. Fix adds auto-inheritance using token_teams (correct key per rbac.py), only for single-team non-admin users.
3. Blocked Usage Logging — main hardcoded blocked=False and exited early for revoked tokens. Fix correctly derives blocked status from HTTP status code and adds a 401/403 handler for revoked/expired token logging.

Security

• jwt.decode(verify_signature=False) usage is appropriate — identification-only, no auth decisions, wrapped in try/except.
• _require_authenticated_session changes are strictly more restrictive (safe direction).
• Auth method values (api_token, jwt, anonymous) consistent with auth.py and rbac.py.
• No new attack surfaces.

Test Coverage

• token_usage_middleware.py: 100% coverage (added 3 edge-case tests for 401/403 paths)
• tokens.py: 98% (4 uncovered lines are pre-existing, not from this PR)
• Added missing list_team_tokens API-token-blocked test
• 86 tests pass for changed files; 13,390 unit tests pass full suite

Commits Added During Review

• test(security): add differential coverage for 401/403 middleware paths and list_team_tokens — 4 new tests
• style: apply linter formatting to tokens.py — linter auto-format

[crivetimihai]

Review Summary

Rebased onto main (clean, no conflicts), reviewed all changes, verified all three bugs, and added differential test coverage.

Bug Verification

All three bugs confirmed against main:

1. Token Chaining (Privilege Escalation) — _require_authenticated_session() only blocked None and anonymous, allowing API tokens to manage other tokens. Fix correctly adds api_token denial.
2. Team Auto-Inheritance — main had no team auto-inheritance; tokens created without team_id got public-only scope silently. Fix adds auto-inheritance using token_teams (correct key per rbac.py), only for single-team non-admin users.
3. Blocked Usage Logging — main hardcoded blocked=False and exited early for revoked tokens. Fix correctly derives blocked status from HTTP status code and adds a 401/403 handler for revoked/expired token logging.

Security

• jwt.decode(verify_signature=False) usage is appropriate — identification-only, no auth decisions, wrapped in try/except.
• _require_authenticated_session changes are strictly more restrictive (safe direction).
• Auth method values (api_token, jwt, anonymous) consistent with auth.py and rbac.py.
• No new attack surfaces.

Test Coverage

• token_usage_middleware.py: 100% coverage (added 3 edge-case tests for 401/403 paths)
• tokens.py: 98% (4 uncovered lines are pre-existing, not from this PR)
• Added missing list_team_tokens API-token-blocked test
• 86 tests pass for changed files; 13,390 unit tests pass full suite

Commits Added During Review

• test(security): add differential coverage for 401/403 middleware paths and list_team_tokens — 4 new tests
• style: apply linter formatting to tokens.py — linter auto-format

[crivetimihai]

Review Commits Added

After initial review and approval, discovered and fixed additional security issues during live testing on a 3-worker deployment behind nginx.

Commits added during review

Commit	Description
84e065a	4 tests for 100% differential coverage on middleware + missing list_team_tokens test
748fbac	Linter formatting
cf1a93d	Fix: revoked tokens bypassed rejection — AuthContextMiddleware swallowed 401 HTTPExceptions and continued as anonymous; fallback revocation check was fail-open; cache invalidation used fire-and-forget create_task
8becc27	Fix: cross-worker revocation — in multi-worker deployments, non-revoking workers served stale L1 cache. Added Redis EXISTS check on the revocation marker before L1
497e74c	Fix: 3 Codex review findings — (1) forged JWT audit-log poisoning: verify JTI exists in DB before logging; (2) browser redirect broken by JSON 401: detect HTMX/browser and let RBAC redirect; (3) 5xx folded into blocked metrics: scope to 4xx only
f74bf59	Import ordering fix

Verified on live 3-worker deployment (localhost:8080)

• Login: 200
• Data plane (tools/prompts/resources/servers/gateways): all 200
• Bug 1 — API token management blocked: 403
• Bug 3a — Blocked usage tracked: confirmed
• Bug 4 — Revoked token rejected on all 3 workers: 401
• Admin UI (overview/tools/tokens via HTMX cookie auth): all 200