Skip to main content
The common operational situations and what the middleware does.

​
Updating scopes or routes

The middleware loads mudraid_scopes.yaml once, on the first request, and holds it in memory. To pick up changes: redeploy, or restart the process. There is no hot-reload in v1. The single-source-of-truth contract is easier to reason about with a restart in the middle.

​
MudraID key rotation

When MudraID rotates its signing key, the middleware:
  1. Receives a token signed under a new kid.
  2. Looks up the kid in its cached JWKS. Not found.
  3. Refetches the JWKS. One in-flight refresh under contention.
  4. Verifies against the new key. Success.
Zero operator action. Covered by integration tests.

​
JWKS endpoint unreachable

Affected requests get 500 JWKS_UNAVAILABLE, logged at WARNING. The cache is not invalidated on a failed fetch. A transient blip doesn’t take down every cached key.

​
Misconfigured YAML

The middleware loads the YAML lazily on the first request. A schema error returns 500 MIDDLEWARE_NOT_READY, logged at ERROR. The failure is not cached. Fix the YAML and the next request succeeds. No restart needed for that case.

​
Diagnostics

import logging
logging.getLogger("mudraid_middleware").setLevel(logging.INFO)
Bootstrap, JWKS fetches, retries, and 500-level events surface at INFO and WARNING.