Middleware Execution Ordering¶

ContextForge uses Starlette's ASGI middleware stack to handle cross-cutting concerns like authentication, CSRF protection, logging, and observability. Understanding the execution order is critical when adding new middleware, especially when middleware depends on request state populated by other middleware.

Reverse Registration Rule¶

Starlette/FastAPI executes middleware in reverse registration order. The last app.add_middleware() call registers middleware that runs outermost (processes requests first, responses last). The first add_middleware() call registers middleware that runs innermost (processes requests last, responses first).

Worked Example¶

Suppose your code registers middleware like this:

app.add_middleware(First)    # Registered first
app.add_middleware(Second)   # Registered second
app.add_middleware(Third)    # Registered third (last)

The execution order on an inbound request is:

Request  → Third → Second → First → Handler → First → Second → Third → Response
          (runs)  (runs)  (runs)             (done)  (done)  (done)

Third runs first on the request path (outermost), and First runs last (innermost, closest to the handler). On the response path, the order reverses.

This reverse-registration rule is a Starlette/FastAPI design decision. When a middleware reads request.state values set by another middleware, you must register the producer middleware after the consumer middleware so that the producer runs before (earlier on the request path than) the consumer.

Current Middleware Stack¶

The middleware stack in mcpgateway/main.py (lines ~3265–3501) includes ~26 middleware, plus one outlier registered after route setup. The table below shows them in registration order (top = registered first, bottom = registered last). Per the Reverse Registration Rule above, execution order on the request path is the reverse of this table — deriving an exact per-row execution rank by hand is error-prone (several rows are conditionally registered, which shifts everyone after them), so it is intentionally omitted here; see the prose sections below the table (state dependencies, the outlier) for the orderings that actually matter in practice, worked out and verified against main.py directly:

Row 27 is the one row whose execution position is unambiguous and worth calling out here: it is registered after everything else (see The Outlier below), which per the reverse-registration rule makes it the outermost middleware in the stack — it runs first on the request path, ahead of even CORSMiddleware (row 1).

Rows 18–20 (CSRFMiddleware, PasswordChangeEnforcementMiddleware, AuthContextMiddleware) are registered in that order, so among just those three, AuthContextMiddleware — registered last of the three — is the outermost of the three and runs first among them on the request path, populating request.state.user before CSRFMiddleware or PasswordChangeEnforcementMiddleware execute. That is the intended, correct behavior; see State Dependencies below. Note that AuthContextMiddleware is not registered last in the main block overall — TokenUsageMiddleware, ObservabilityMiddleware, OpenTelemetryRequestMiddleware, BaggageMiddleware, DBQueryLoggingMiddleware, and ClientDisconnectMiddleware (rows 21–26) are all registered after it, so it is not the innermost middleware overall either.

The Outlier: DeprecationHeadersMiddleware¶

Key point: DeprecationHeadersMiddleware is registered outside the main middleware block, after app.include_router(legacy_router) (line ~12882). Because it is registered last, it runs outermost — ahead of everything in the main 3265–3501 registration block, including CORSMiddleware.

If you are adding middleware that depends on early request processing (e.g., extracting headers or setting flags), DeprecationHeadersMiddleware may already have run if legacy_api_enabled=true. If you add middleware after DeprecationHeadersMiddleware, it will run before DeprecationHeadersMiddleware, which is usually not desired.

State Dependencies: The CSRF + Auth Middleware Ordering Bug¶

Critical constraint: CSRFMiddleware must be registered before AuthContextMiddleware so that CSRF runs after auth and request.state.user is already populated.

The Bug (Issue #5780)¶

CSRFMiddleware validates HMAC-bound CSRF tokens using request.state.user.email:

# mcpgateway/middleware/csrf_middleware.py:143–146
if hasattr(request.state, "user") and request.state.user:
    user = request.state.user
    user_id = user.email if hasattr(user, "email") else str(user.id)

AuthContextMiddleware populates request.state.user for all authenticated requests:

# mcpgateway/middleware/auth_middleware.py:189
request.state.user = user

If the middleware registration order is reversed (CSRF registered after auth), then CSRF runs before auth on the request path, and request.state.user is unset. The CSRF middleware then silently falls back to extracting identity from the raw JWT sub claim (the user's ID, not email). But admin.py binds CSRF tokens to the user's email, not ID — resulting in universal 403 "CSRF Token Invalid" errors on all Admin UI writes.

Solution: In main.py, register CSRFMiddleware (line ~3403) before AuthContextMiddleware (line ~3427) so that the reverse-order execution makes auth run first on requests.

Same-Shape Constraint: PasswordChangeEnforcementMiddleware¶

PasswordChangeEnforcementMiddleware has an identical dependency structure to CSRFMiddleware: it reads request.state.user to check the password_change_required flag (line ~96 in password_change_enforcement.py):

user: Optional[EmailUser] = getattr(request.state, "user", None)
if not user:
    return await call_next(request)

For the same reason, PasswordChangeEnforcementMiddleware must be registered before AuthContextMiddleware. In the current codebase, both CSRF and PasswordChangeEnforcement are registered in the same order-dependent block (lines ~3403–3427), with both registered before auth.

If you add another middleware that reads request.state values set by AuthContextMiddleware, ensure it is registered before AuthContextMiddleware to preserve execution order.

Guidance for Adding New Middleware¶

1. Identify producers and consumers. List the request.state attributes your middleware reads and writes. Identify which other middleware or dependencies populate those attributes.

2. Register consumers before producers. Middleware that reads request.state.user, request.state.jti, or other auth context must be registered before (earlier in the registration list than) AuthContextMiddleware.

3. Add a regression test. Write a test similar to test_csrf_middleware_runs_after_auth_context_middleware (in tests/unit/mcpgateway/middleware/test_admin_csrf_binding.py:325) to verify your middleware runs in the expected order:

def test_my_middleware_runs_after_auth_context_middleware():
    from mcpgateway.main import app
    from mcpgateway.middleware.auth_middleware import AuthContextMiddleware
    from mcpgateway.middleware.my_new_middleware import MyNewMiddleware

    middleware_classes = [m.cls for m in app.user_middleware]
    assert AuthContextMiddleware in middleware_classes
    assert MyNewMiddleware in middleware_classes

    auth_index = middleware_classes.index(AuthContextMiddleware)
    my_index = middleware_classes.index(MyNewMiddleware)

    # AuthContextMiddleware must run BEFORE MyNewMiddleware
    # (lower index means earlier in request processing)
    assert auth_index < my_index

1. Consider the reverse-registration rule. add_middleware() calls at the end register middleware that runs first on requests. When adding new middleware, reference this page (docs/docs/architecture/middleware-ordering.md) in the code comment next to your app.add_middleware() call to document your ordering rationale.

2. Avoid brittle line-number references. When documenting middleware order in code or docs, reference the middleware class name and its high-level purpose (e.g., "registered before AuthContextMiddleware") rather than specific line numbers, since the codebase evolves.

See also: - Security Features — overview of ContextForge's security model - Configuration: CSRF Protection — CSRF-specific settings and cookie synchronization risks