sequenceDiagram
  autonumber
  actor Client
  participant Authn as Authn.Authenticate
  participant Cache as Key Cache
  participant JWKS as JWKS Manager
  participant HTTP as HTTP Client
  participant OIDC as OIDC Provider

  Client->>Authn: Authenticate(ctx, token)
  Authn->>Cache: Get(keyID)
  alt Key hit
    Cache-->>Authn: Public Key
    Authn-->>Client: Verify token and return result
  else Key miss
    Authn->>JWKS: getKeyWithRetry(ctx, keyID)
    rect rgba(200,230,255,0.3)
      note right of JWKS: Retry/backoff loop with ctx cancellation
      JWKS->>Cache: Check/refresh state (single-refresh)
      opt Needs refresh
        JWKS->>HTTP: GET /.well-known/openid-configuration
        HTTP-->>JWKS: OIDC config
        JWKS->>HTTP: GET jwks_uri
        HTTP-->>JWKS: JWKS document
        JWKS->>Cache: Update keys
      end
      JWKS-->>Authn: Key or error
    end
    alt Key found
      Authn-->>Client: Verify token and return result
    else Error
      Authn-->>Client: Context-aware error
    end
  end