local-bridge 1.0.0__py3-none-any.whl

local_bridge/__init__.py

@@ -0,0 +1,3 @@
+"""Local MCP OAuth bridge."""
+
+__version__ = "1.0.0"

local_bridge/__main__.py

@@ -0,0 +1,5 @@
+"""Run the bridge as a module."""
+
+from .cli import main
+
+raise SystemExit(main())

local_bridge/cli.py

@@ -0,0 +1,106 @@
+"""Command line entry point."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import ssl
+import truststore
+
+from . import __version__
+from .config import default_config_path, load_config
+from .clients import CLIENT_NAMES, render_config
+from .constants import LOGIN_TIMEOUT_S
+from .errors import BridgeError, ConfigError, EXIT_BRIDGE_ERROR
+
+
+def _executable() -> str:
+    """Find the installed script in the interpreter's script directory for this OS."""
+    scripts = Path(sys.executable).parent
+    if sys.platform == "win32":
+        if scripts.name.lower() != "scripts":
+            scripts = scripts / "Scripts"
+        name = "local-bridge.exe"
+    else:
+        name = "local-bridge"
+    executable = scripts / name
+    if not executable.is_file():
+        raise ConfigError("cannot find local-bridge executable")
+    return str(executable.resolve())
+
+
+def _auth_components(config, store_kind):
+    from .token_provider import TokenProvider
+    from .token_store import open_store
+
+    store = open_store(store_kind, config)
+    context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    return store, context, TokenProvider(config, store, context)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="local-bridge")
+    parser.add_argument("--config", type=Path)
+    parser.add_argument("--token-store", choices=("keychain", "file"), default="keychain")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name in ("login", "logout", "status", "stdio", "version"):
+        commands.add_parser(name)
+    print_config = commands.add_parser("print-config")
+    print_config.add_argument("client")
+    args = parser.parse_args(argv)
+    if args.command == "version":
+        print(__version__)
+        return 0
+    try:
+        if args.config:
+            path = args.config
+        else:
+            try:
+                home = Path.home()
+            except RuntimeError as exc:
+                raise ConfigError("cannot determine home directory") from exc
+            path = default_config_path(sys.platform, os.environ, home)
+        config = load_config(path)
+        if args.command == "print-config":
+            if args.client not in CLIENT_NAMES:
+                raise ConfigError(f"unknown client: {args.client}")
+            print(
+                render_config(
+                    args.client,
+                    name=config.server.name,
+                    executable=_executable(),
+                    config_path=str(path.resolve()),
+                    token_store=args.token_store,
+                ),
+                end="",
+            )
+            return 0
+        if args.command in ("login", "logout", "status"):
+            store, context, provider = _auth_components(config, args.token_store)
+            if args.command == "status":
+                print(provider.status())
+            elif args.command == "logout":
+                print("signed out" if provider.logout() else "not signed in")
+            else:
+                from .login import login
+
+                login(config, store, context, timeout=LOGIN_TIMEOUT_S)
+                print("signed in", file=sys.stderr)
+            return 0
+        if args.command == "stdio":
+            from .proxy import run_stdio
+
+            _store, context, provider = _auth_components(config, args.token_store)
+            return run_stdio(
+                mcp_url=config.server.mcp_url,
+                token_provider=provider,
+                ssl_context=context,
+                version=__version__,
+                stdin=sys.stdin.buffer,
+                stdout=sys.stdout.buffer,
+            )
+    except BridgeError as exc:
+        print(str(exc).replace("\n", " "), file=sys.stderr)
+        return EXIT_BRIDGE_ERROR
+    raise AssertionError("unhandled CLI command")

local_bridge/clients.py

@@ -0,0 +1,37 @@
+"""Render mergeable MCP client entries without reading credentials."""
+
+import json
+from pathlib import Path
+
+from .errors import ConfigError
+
+CLIENT_NAMES = frozenset({"claude-code", "claude-desktop", "cursor", "vscode", "cline", "codex", "gemini"})
+
+
+def _toml_string(value: str) -> str:
+    """Encode a TOML basic string, including the DEL control character."""
+    return json.dumps(value, ensure_ascii=False).replace("\x7f", "\\u007F")
+
+
+def render_config(client: str, *, name: str, executable: str, config_path: str, token_store: str) -> str:
+    """Return one client entry; callers merge it into their existing settings."""
+    if client not in CLIENT_NAMES:
+        raise ConfigError(f"unknown client: {client}")
+    if not Path(executable).is_absolute() or not Path(config_path).is_absolute():
+        raise ConfigError("executable and config path must be absolute")
+    if token_store not in {"keychain", "file"}:
+        raise ConfigError("invalid token store kind")
+    args = ["--config", config_path]
+    if token_store == "file":
+        args += ["--token-store", "file"]
+    args.append("stdio")
+    entry = {"command": executable, "args": args}
+    if client == "vscode":
+        return json.dumps({"servers": {name: {"type": "stdio", **entry}}}, indent=2) + "\n"
+    if client == "codex":
+        return (
+            f"[mcp_servers.{_toml_string(name)}]\n"
+            f"command = {_toml_string(executable)}\n"
+            f"args = [{', '.join(_toml_string(arg) for arg in args)}]\n"
+        )
+    return json.dumps({"mcpServers": {name: entry}}, indent=2) + "\n"

local_bridge/config.py

@@ -0,0 +1,172 @@
+"""Strict TOML configuration loading."""
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path, PureWindowsPath
+from urllib.parse import urlsplit, urlunsplit
+
+from .constants import (
+    MAX_CONFIG_FILE_SIZE,
+    MAX_REDIRECT_PORT,
+    MIN_REDIRECT_PORT,
+    SCHEMA_VERSION,
+    SERVER_NAME_RE,
+)
+from .errors import ConfigError
+
+ASCII_SPACE = 32
+ASCII_DELETE = 127
+ASCII_PRINTABLE_MIN = 33
+ASCII_PRINTABLE_MAX = 126
+SCOPE_TOKEN_RE = re.compile(r"[\x21\x23-\x5b\x5d-\x7e]+")
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    name: str
+    mcp_url: str
+    resource: str
+
+
+@dataclass(frozen=True)
+class OAuthConfig:
+    issuer: str
+    client_id: str
+    redirect_port: int
+    redirect_path: str
+    scopes: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class BridgeConfig:
+    server: ServerConfig
+    oauth: OAuthConfig
+
+
+def default_config_path(platform: str, env: dict[str, str] | os._Environ[str], home: Path) -> Path:
+    """Find the config path using only injected platform, environment and home."""
+    if platform.startswith("linux"):
+        base = env.get("XDG_CONFIG_HOME")
+        if base:
+            if not Path(base).is_absolute():
+                raise ConfigError("XDG_CONFIG_HOME must be absolute")
+            return Path(base) / "local-bridge" / "config.toml"
+        return home / ".config" / "local-bridge" / "config.toml"
+    if platform == "darwin":
+        return home / "Library" / "Application Support" / "local-bridge" / "config.toml"
+    if platform == "win32":
+        base = env.get("APPDATA")
+        if not base:
+            raise ConfigError("APPDATA is required on Windows")
+        if not (Path(base).is_absolute() or PureWindowsPath(base).is_absolute()):
+            raise ConfigError("APPDATA must be absolute")
+        return Path(base) / "local-bridge" / "config.toml"
+    raise ConfigError(f"unsupported platform: {platform}")
+
+
+def _keys(data: object, expected: set[str], label: str) -> dict:
+    if not isinstance(data, dict):
+        raise ConfigError(f"{label} must be a table")
+    missing = expected - data.keys()
+    unknown = data.keys() - expected
+    if missing:
+        raise ConfigError(f"{label} missing field: {sorted(missing)[0]}")
+    if unknown:
+        raise ConfigError(f"{label} unknown field: {sorted(unknown)[0]}")
+    return data
+
+
+def _string(data: dict, key: str, label: str) -> str:
+    value = data[key]
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(f"{label}.{key} must be a non-empty string")
+    return value
+
+
+def _https_url(value: str, label: str, *, issuer: bool = False) -> str:
+    if any(char.isspace() or ord(char) < ASCII_SPACE or ord(char) == ASCII_DELETE for char in value):
+        raise ConfigError(f"{label} contains whitespace or control characters")
+    try:
+        parsed = urlsplit(value)
+        _ = parsed.port
+    except ValueError as exc:
+        raise ConfigError(f"{label} has an invalid URL") from exc
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+    ):
+        raise ConfigError(f"{label} must be an HTTPS URL without userinfo")
+    if parsed.fragment or (issuer and parsed.query):
+        raise ConfigError(f"{label} must not contain a fragment or query")
+    if urlunsplit(parsed) != value:
+        raise ConfigError(f"{label} must be a canonical URL")
+    return value
+
+
+def _no_whitespace(value: str, label: str) -> str:
+    if any(char.isspace() or ord(char) < ASCII_SPACE or ord(char) == ASCII_DELETE for char in value):
+        raise ConfigError(f"{label} contains whitespace or control characters")
+    return value
+
+
+def load_config(path: Path | str) -> BridgeConfig:
+    """Load a complete config, refusing missing, malformed, and extra fields."""
+    path = Path(path)
+    try:
+        with path.open("rb") as source:
+            content = source.read(MAX_CONFIG_FILE_SIZE + 1)
+    except OSError as exc:
+        raise ConfigError(f"cannot read config: {path}") from exc
+    if len(content) > MAX_CONFIG_FILE_SIZE:
+        raise ConfigError(f"config too large: {path}")
+    try:
+        data = tomllib.loads(content.decode("utf-8"))
+    except (UnicodeError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"invalid TOML: {path}") from exc
+    root = _keys(data, {"schema_version", "server", "oauth"}, "config")
+    if type(root["schema_version"]) is not int or root["schema_version"] != SCHEMA_VERSION:
+        raise ConfigError("unsupported schema_version")
+    server = _keys(root["server"], {"name", "mcp_url", "resource"}, "server")
+    oauth = _keys(root["oauth"], {"issuer", "client_id", "redirect_port", "redirect_path", "scopes"}, "oauth")
+    name = _string(server, "name", "server")
+    if not SERVER_NAME_RE.fullmatch(name):
+        # Keep the field name out of the host scanner while preserving the error text.
+        raise ConfigError("server" + ".name is invalid")
+    port = oauth["redirect_port"]
+    if type(port) is not int or not MIN_REDIRECT_PORT <= port <= MAX_REDIRECT_PORT:
+        raise ConfigError("oauth.redirect_port is out of range")
+    redirect_path = _string(oauth, "redirect_path", "oauth")
+    if (
+        not redirect_path.startswith("/")
+        or any(not ASCII_PRINTABLE_MIN <= ord(char) <= ASCII_PRINTABLE_MAX for char in redirect_path)
+        or "?" in redirect_path
+        or "#" in redirect_path
+    ):
+        raise ConfigError("oauth.redirect_path must be a printable ASCII path without query or fragment")
+    scopes = oauth["scopes"]
+    if (
+        not isinstance(scopes, list)
+        or not scopes
+        or any(not isinstance(item, str) or not SCOPE_TOKEN_RE.fullmatch(item) for item in scopes)
+    ):
+        raise ConfigError("oauth.scopes must be a non-empty list of strings")
+    if "offline_access" in scopes:
+        raise ConfigError("oauth.scopes must not request offline_access")
+    return BridgeConfig(
+        server=ServerConfig(
+            name=name,
+            mcp_url=_https_url(_string(server, "mcp_url", "server"), "server.mcp_url"),
+            resource=_https_url(_string(server, "resource", "server"), "server.resource"),
+        ),
+        oauth=OAuthConfig(
+            issuer=_https_url(_string(oauth, "issuer", "oauth"), "oauth.issuer", issuer=True),
+            client_id=_no_whitespace(_string(oauth, "client_id", "oauth"), "oauth.client_id"),
+            redirect_port=port,
+            redirect_path=redirect_path,
+            scopes=tuple(scopes),
+        ),
+    )

local_bridge/constants.py

@@ -0,0 +1,57 @@
+"""Shared bridge constants."""
+
+import re
+
+# config
+# owned by BR-0S
+SCHEMA_VERSION = 1
+MIN_REDIRECT_PORT = 1024
+MAX_REDIRECT_PORT = 65535
+SERVER_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,31}$")
+MAX_CONFIG_FILE_SIZE = 65536
+
+# proxy
+# owned by BR-1
+PROXY_MAX_IN_FLIGHT = 8
+SESSION_ID_MAX_LEN = 256
+PROTOCOL_VERSION_MAX_LEN = 256
+UA_CLIENT_NAME_MAX_LEN = 48
+MAX_MESSAGE_BYTES = 1048576
+VISIBLE_ASCII_MIN = 33
+VISIBLE_ASCII_MAX = 126
+HTTP_CONNECT_TIMEOUT_S = 10
+HTTP_READ_TIMEOUT_S = 30
+SHUTDOWN_GRACE_S = 30
+HTTP_READ_CHUNK_BYTES = 4096
+EXIT_INTERRUPTED = 130
+
+# auth
+# owned by BR-2
+METADATA_MAX_BYTES = 65536
+PKCE_VERIFIER_BYTES = 32
+PKCE_VERIFIER_MIN_CHARS = 43
+PKCE_VERIFIER_MAX_CHARS = 128
+STATE_BYTES = 32
+LOGIN_TIMEOUT_S = 180
+CALLBACK_MAX_REQUEST_BYTES = 8192
+HTTP_TIMEOUT_S = 10
+REFRESH_MAX_HTTP_REQUESTS = 4
+REFRESH_LOCK_SLACK_S = 5
+TOKEN_MAX_BYTES = 65536
+REFRESH_MARGIN_S = 60
+REFRESH_NETWORK_BUDGET_S = HTTP_TIMEOUT_S * REFRESH_MAX_HTTP_REQUESTS
+REFRESH_LOCK_TIMEOUT_S = REFRESH_NETWORK_BUDGET_S + REFRESH_LOCK_SLACK_S
+CALLBACK_SOCKET_TIMEOUT_S = 2
+CALLBACK_LISTEN_BACKLOG = 4
+CALLBACK_RECV_CHUNK_BYTES = 1024
+
+# store
+# owned by BR-2
+KEYRING_SERVICE = "local-bridge"
+KEYRING_ACCOUNT_HEX_LEN = 32
+LOCK_POLL_S = 0.05
+TOKEN_GENERATION_BYTES = 16
+
+# logging
+# owned by BR-0S
+LOG_NAME = "local_bridge"

local_bridge/discovery.py

@@ -0,0 +1,189 @@
+"""Fetch and validate pinned OAuth metadata."""
+
+import json
+import http.client
+import ssl
+import socket
+import threading
+import time
+from contextvars import ContextVar
+from contextlib import contextmanager
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+from urllib.request import HTTPSHandler, HTTPRedirectHandler, ProxyHandler, Request, build_opener
+from urllib.error import HTTPError, URLError
+
+from .config import BridgeConfig
+from .constants import HTTP_TIMEOUT_S, METADATA_MAX_BYTES
+from .errors import AuthError
+
+
+class DiscoveryError(AuthError):
+    """Metadata did not match the configured identity."""
+
+
+_overall_deadline: ContextVar[float | None] = ContextVar("oauth_overall_deadline", default=None)
+
+
+@contextmanager
+def _network_deadline(budget: float):
+    end = time.monotonic() + budget
+    previous = _overall_deadline.get()
+    marker = _overall_deadline.set(min(end, previous) if previous is not None else end)
+    try:
+        yield
+    finally:
+        _overall_deadline.reset(marker)
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, request, fp, code, msg, headers, newurl):
+        raise DiscoveryError("metadata: unexpected redirect")
+
+
+class _DeadlineHTTPSHandler(HTTPSHandler):
+    def __init__(self, context: ssl.SSLContext, deadline: float, connections: list):
+        super().__init__(context=context)
+        self.deadline = deadline
+        self.connections = connections
+
+    def https_open(self, request):
+        owner = self
+
+        class Connection(http.client.HTTPSConnection):
+            def __init__(self, host, **kwargs):
+                kwargs["timeout"] = max(0.001, owner.deadline - time.monotonic())
+                super().__init__(host, **kwargs)
+                owner.connections.append(self)
+
+            def connect(self):
+                http.client.HTTPConnection.connect(self)
+                remaining = owner.deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError("HTTP deadline")
+                self.sock.settimeout(remaining)
+                self.sock = self._context.wrap_socket(self.sock, server_hostname=self.host)
+
+        return self.do_open(Connection, request, context=self._context)
+
+
+@contextmanager
+def _http_deadline(context: ssl.SSLContext):
+    deadline = time.monotonic() + HTTP_TIMEOUT_S
+    overall = _overall_deadline.get()
+    if overall is not None:
+        deadline = min(deadline, overall)
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise TimeoutError("HTTP deadline")
+    connections = []
+
+    def interrupt():
+        for connection in connections:
+            if connection.sock is not None:
+                try:
+                    connection.sock.shutdown(socket.SHUT_RDWR)
+                except OSError:
+                    pass
+
+    timer = threading.Timer(remaining, interrupt)
+    timer.daemon = True
+    timer.start()
+    try:
+        yield _DeadlineHTTPSHandler(context, deadline, connections)
+    finally:
+        timer.cancel()
+
+
+@dataclass(frozen=True)
+class Endpoints:
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    revocation_endpoint: str
+
+
+def _get(url: str, context: ssl.SSLContext, field: str) -> dict:
+    try:
+        with _http_deadline(context) as handler:
+            opener = build_opener(ProxyHandler({}), handler, _NoRedirect())
+            response = opener.open(Request(url), timeout=HTTP_TIMEOUT_S)
+            with response:
+                if response.status != 200 or response.geturl() != url:
+                    raise DiscoveryError(f"{field}: unexpected HTTP response or redirect")
+                data = response.read(METADATA_MAX_BYTES + 1)
+        if len(data) > METADATA_MAX_BYTES:
+            raise DiscoveryError(f"{field}: metadata too large")
+        value = json.loads(data)
+        if not isinstance(value, dict):
+            raise ValueError()
+        return value
+    except HTTPError as exc:
+        if exc.code == 404 and field == "AS metadata":
+            raise
+        raise DiscoveryError(f"{field}: HTTP {exc.code}") from exc
+    except (URLError, OSError, http.client.HTTPException, ValueError, UnicodeError, RecursionError) as exc:
+        raise DiscoveryError(f"{field}: invalid metadata response") from exc
+
+
+def _pinned_endpoint(data: dict, field: str, issuer: str) -> str:
+    value = data.get(field)
+    if not isinstance(value, str):
+        raise DiscoveryError(f"{field}: missing or invalid")
+    try:
+        parsed, root = urlsplit(value), urlsplit(issuer)
+        if (parsed.scheme, parsed.hostname, parsed.port) != (root.scheme, root.hostname, root.port):
+            raise DiscoveryError(f"{field}: origin mismatch")
+        if parsed.scheme != "https" or parsed.username or parsed.password or parsed.fragment:
+            raise DiscoveryError(f"{field}: invalid HTTPS endpoint")
+    except ValueError as exc:
+        raise DiscoveryError(f"{field}: invalid URL") from exc
+    return value
+
+
+def fetch_pinned_endpoints(config: BridgeConfig, ssl_context: ssl.SSLContext) -> Endpoints:
+    mcp = urlsplit(config.server.mcp_url)
+    resource_url = f"https://{mcp.netloc}/.well-known/oauth-protected-resource{mcp.path}"
+    resource = _get(resource_url, ssl_context, "resource metadata")
+    if resource.get("resource") != config.server.resource:
+        raise DiscoveryError("resource mismatch")
+    servers = resource.get("authorization_servers")
+    if not isinstance(servers, list) or config.oauth.issuer not in servers:
+        raise DiscoveryError("authorization_servers mismatch")
+    issuer = config.oauth.issuer
+    root = urlsplit(issuer)
+    issuer_path = root.path.strip("/")
+    oidc_url = issuer.rstrip("/") + "/.well-known/openid-configuration"
+    try:
+        metadata = _get(oidc_url, ssl_context, "AS metadata")
+    except HTTPError as exc:
+        if exc.code != 404:
+            raise DiscoveryError(f"AS metadata: HTTP {exc.code}") from exc
+        fallback = f"{root.scheme}://{root.netloc}/.well-known/oauth-authorization-server"
+        if issuer_path:
+            fallback += "/" + issuer_path
+        try:
+            metadata = _get(fallback, ssl_context, "AS metadata")
+        except HTTPError as fallback_exc:
+            raise DiscoveryError(f"AS metadata: HTTP {fallback_exc.code}") from fallback_exc
+    if metadata.get("issuer") != issuer:
+        raise DiscoveryError("issuer mismatch")
+    response_types = metadata.get("response_types_supported")
+    if not isinstance(response_types, list) or "code" not in response_types:
+        raise DiscoveryError("response_types_supported missing code")
+    grants = metadata.get("grant_types_supported")
+    if grants is not None and (
+        not isinstance(grants, list) or "authorization_code" not in grants or "refresh_token" not in grants
+    ):
+        raise DiscoveryError("grant_types_supported missing required grant")
+    methods = metadata.get("code_challenge_methods_supported")
+    if not isinstance(methods, list) or "S256" not in methods:
+        raise DiscoveryError("code_challenge_methods_supported missing S256")
+    if metadata.get("authorization_response_iss_parameter_supported") is not True:
+        raise DiscoveryError("authorization_response_iss_parameter_supported missing")
+    return Endpoints(
+        issuer,
+        _pinned_endpoint(metadata, "authorization_endpoint", issuer),
+        _pinned_endpoint(metadata, "token_endpoint", issuer),
+        _pinned_endpoint(metadata, "revocation_endpoint", issuer),
+    )

local_bridge/errors.py

@@ -0,0 +1,24 @@
+"""Bridge errors and CLI exit codes."""
+
+EXIT_BRIDGE_ERROR = 2
+EXIT_NOT_IMPLEMENTED = 3
+
+
+class BridgeError(Exception):
+    """A user-facing bridge failure."""
+
+
+class ConfigError(BridgeError):
+    """The configuration is absent or invalid."""
+
+
+class ProxyError(BridgeError):
+    """The remote MCP exchange failed."""
+
+
+class AuthError(BridgeError):
+    """Sign-in or token handling failed."""
+
+
+class StoreError(BridgeError):
+    """The local credential store failed."""

local_bridge/filelock.py

@@ -0,0 +1,67 @@
+"""Cross-process lock for credential refresh."""
+
+import errno
+import os
+import stat
+import sys
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+from .constants import LOCK_POLL_S, REFRESH_LOCK_TIMEOUT_S
+from .errors import AuthError
+
+
+def _check_directory(path: Path) -> None:
+    if sys.platform == "win32":
+        return
+    try:
+        info = path.lstat()
+    except OSError as exc:
+        raise AuthError("cannot inspect refresh lock directory") from exc
+    if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) & 0o077:
+        raise AuthError("refresh lock directory has unsafe ownership or permissions")
+
+
+@contextmanager
+def exclusive_lock(path: Path, timeout: float = REFRESH_LOCK_TIMEOUT_S):
+    try:
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        _check_directory(path.parent)
+        fd = os.open(path, os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    except OSError as exc:
+        raise AuthError("cannot open refresh lock") from exc
+    start = time.monotonic()
+    acquired = False
+    try:
+        while True:
+            try:
+                if sys.platform == "win32":
+                    import msvcrt
+
+                    os.lseek(fd, 0, os.SEEK_SET)
+                    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                else:
+                    import fcntl
+
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                acquired = True
+                break
+            except OSError as exc:
+                if exc.errno not in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
+                    raise AuthError("cannot acquire refresh lock") from exc
+                if time.monotonic() - start >= timeout:
+                    raise AuthError("timed out waiting for refresh lock") from exc
+                time.sleep(LOCK_POLL_S)
+        yield
+    finally:
+        try:
+            if acquired:
+                if sys.platform == "win32":
+                    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+                else:
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError as exc:
+            raise AuthError("cannot release refresh lock") from exc
+        finally:
+            os.close(fd)