Class _OidcRefresher

python/openshell/sandbox.py:932–1313

Thread-safe in-process OAuth2 refresh for a gateway's `oidc_token.json`. Mirrors the lazy-refresh pattern used by `google-auth`'s `Credentials` and `botocore`'s `SSOTokenProvider`. Uses `httpx` for transport so we can pin `follow_redirects=False` and the TLS verification policy expl

class _OidcRefresher:
    """Thread-safe in-process OAuth2 refresh for a gateway's `oidc_token.json`.

    Mirrors the lazy-refresh pattern used by `google-auth`'s `Credentials`
    and `botocore`'s `SSOTokenProvider`. Uses `httpx` for transport so
    we can pin `follow_redirects=False` and the TLS verification policy
    explicitly — same posture as the Rust CLI's use of `reqwest` with
    `Policy::none()` and an opt-in `danger_accept_invalid_certs` (see
    `crates/openshell-cli/src/oidc_auth.rs::http_client`). The OAuth2
    refresh-token grant itself (RFC 6749 §6) is a single form-encoded
    POST, handled inline rather than via an OAuth2 library.

    Properties:

    - **Lazy**: check expiry on every RPC; refresh only when stale.
    - **Lock-coordinated**: concurrent RPCs share a single refresh, not
      one per call. Plain `threading.Lock` (no separate worker thread,
      unlike `google-auth`'s `RefreshThreadManager` — sufficient for
      our use case).
    - **Disk-aware**: before refreshing, re-read `oidc_token.json` —
      the CLI or another process may have already rotated the bundle.
    - **Discovery-validated**: fetches the OIDC discovery document
      from `<issuer>/.well-known/openid-configuration`, rejects
      responses whose `issuer` field doesn&#x27;t match the configured one
      (preventing SSRF / misdirection of the refresh_token to an
      attacker-controlled endpoint). Mirrors the Rust CLI&#x27;s
      `discover()` function.
    - **Redirect-hardened**: `follow_redirects=False` on the underlying
      `httpx.Client` so a 3xx during discovery or refresh is treated
      as a failure rather than silently chasing the redirect to an
      arbitrary host.
    - **Write-back by default**: when `auto_refresh=True`, refreshed
      bundles are atomically persisted to `oidc_token.json` at mode
      0600 so other processes (Rust CLI, TUI, other Python clients)
      see the rotated `refresh_token`. Required for IdPs that
      invalidate the old `refresh_token` on rotation (Keycloak with
      rotation enabled, Entra in strict mode); without write-back, a
      second process would `invalid_grant` on next refresh.
    - **`insecure=True` flag** disables TLS certificate verification
      for the discovery and refresh calls. Matches the Rust CLI&#x27;s
      `--insecure` plumbing for OIDC issuers behind self-signed certs.
    - **Refresh failures** surface as `SandboxError` with a
      "re-authenticate with: openshell gateway login" hint.
    """

    def __init__(
        self,
        gateway_dir: pathlib.Path,
        cluster_name: str,
        *,
        write_back: bool = True,
        insecure: bool = False,
    ) -> None:
        self._gateway_dir = gateway_dir
        self._cluster_name = cluster_name
        self._write_back = write_back
        self._lock = threading.Lock()
        self._bundle: dict | None = None