Crystal HTTP::Client and OAuth2 middleware integration for automatic 401 WWW-Authenticate handling

Answer first

Default behavior: HTTP::Client should propagate a 401 Unauthorized with WWW-Authenticate unchanged to the caller and not retry automatically. The stdlib provides no built-in on_auth_challenge callback or token lifecycle hooks. Automatic retry inside the library would be unsafe with the stated constraints around TLS verification and BasicAuth leakage.

Integration point: application-level middleware, not stdlib. Keep the client immutable and shared across fibers. Supply Authorization per request from a fiber-local token provider. Retry once after a 401 only when the connection is TLS verified and the challenge scheme is acceptable.

Confirmed facts

• Crystal stdlib HTTP::Client does not automatically retry on 401 and has no on_auth_challenge callback or token lifecycle hooks in the documented API.
• A 401 with WWW-Authenticate is returned to the caller unchanged after a successful TLS handshake.
• HTTP::Client is commonly shared across fibers. Mutable state on the client instance leaks headers between fibers.

Likely explanation

Automatic retry in stdlib would need to decide when a 401 is transient, which auth scheme to use, and whether the connection is safe for credential resend. Those decisions are application policy, not transport policy. Keeping retry in app code preserves least-privilege scoping and avoids resending BasicAuth over non-TLS.

Least-privilege retry steps for a shared client

1. Do not set Authorization on the client instance. Build headers per request.
2. Execute request with current token from a fiber-local provider.
3. If response is 401 and WWW-Authenticate is present, validate the connection is TLS verified and the scheme is expected, e.g., Bearer.
4. Acquire a fresh token with the minimal scopes required for that specific request path/method from the vault or secret store. Do not promote to a broader scope.
5. Retry the same request once with a new Authorization header, preserving the original HTTP::Client TLS settings and method/body.
6. Do not store the refreshed token on the shared client. Return the final response or error to the caller.

Verification

• Inspect HTTP::Client source and API docs for your Crystal version to confirm absence of automatic 401 retry or auth callbacks.
• Reproduce with a minimal request that returns 401 + WWW-Authenticate and confirm the client returns the response without retry.
• Test concurrent fibers using the same client instance to verify per-request Authorization headers remain isolated.

Assumption and uncertainty: stdlib behavior is version-sensitive. No current verification of a specific Crystal release is available here. Do not assume undocumented auth hooks exist.

One diagnostic detail that changes the recommendation: Is Authorization currently set as a default header on the shared HTTP::Client instance, or is it injected per request? If it is a client default, the client must be refactored to per-request headers before any safe retry logic can be added.