induscode 0.1.0__py3-none-any.whl

induscode/launch/oauth.py

@@ -0,0 +1,808 @@
+"""OAuth integration — the browser-sign-in counterpart to the api-key flow.
+
+**THE adapter** (port plan gap #1). The TS build leaned on the framework's
+provider-object registry: each ``OAuthProviderInterface`` owned a whole
+``login(callbacks)`` choreography, ``registerOAuthProvider`` populated a
+registry at import time, and ``startOAuthLogin`` drove ``provider.login`` and
+persisted the result. The Python framework ships no provider objects — its
+OAuth surface is transport primitives
+(:mod:`indusagi.llmgateway.credentials.oauth`:
+:data:`~indusagi.llmgateway.credentials.oauth.OAUTH_PROVIDERS` /
+:func:`~indusagi.llmgateway.credentials.oauth.oauth_config_for` /
+:func:`~indusagi.llmgateway.credentials.oauth.build_auth_url` /
+:func:`~indusagi.llmgateway.credentials.oauth.exchange_code` /
+:func:`~indusagi.llmgateway.credentials.oauth.refresh_token`) plus PKCE
+(:mod:`indusagi.llmgateway.credentials.pkce`). This module re-choreographs the
+TS ``provider.login(callbacks)`` flow over those primitives:
+
+1. mint a PKCE pair and a CSRF ``state``;
+2. build the authorization URL and surface it through ``callbacks.on_auth``
+   (the credential command opens it via :func:`open_login_url`);
+3. read the pasted authorization code (or full redirect URL) back through
+   ``callbacks.on_prompt`` — the paste choreography, exactly as the framework
+   ``auth_cli`` does it: no local callback HTTP server exists anywhere in this
+   lineage;
+4. exchange the code for tokens and map the framework
+   :class:`~indusagi.llmgateway.credentials.oauth.OAuthTokens` into the app's
+   vault-stored :class:`~.contract.OAuthCredentials` shape;
+5. persist through the injected :class:`~.contract.AuthVault` Protocol — the
+   vault (the boot layer's disk implementation) stays the single
+   ``auth.json`` writer.
+
+On top of the flow it offers what the credential command needs:
+
+- :func:`register_built_in_oauth_providers` — populates the adapter registry
+  from the framework's :data:`OAUTH_PROVIDERS` config table. **Explicitly** —
+  there is deliberately no import-time registration (the TS module registered
+  on import; the port plan forbids import-time side effects). The boot layer
+  primes the registry as a stage; tests prime it in a fixture.
+- :func:`list_login_providers` — the merged sign-in directory, every entry
+  tagged with whether it authenticates by browser sign-in or by api key.
+- :func:`start_oauth_login` — drives the re-choreographed login flow and
+  persists the resulting credentials through the vault.
+- :func:`refresh_oauth_credentials` — the refresh seam (the TS
+  ``ensureFreshOAuthCredentials`` analogue) the boot vault calls when a stored
+  browser token has expired.
+- :func:`open_login_url` — a default-browser launcher
+  (:mod:`webbrowser`-backed; the TS per-platform ``launchAttempts`` spawn
+  table collapses into the stdlib, which encodes the same fallbacks).
+
+Adaptation notes
+----------------
+- The framework's :data:`OAUTH_PROVIDERS` table carries **two** providers —
+  ``anthropic`` and ``openai`` — and its ``ProviderId`` literal does not admit
+  a ``github-copilot`` id, so a Copilot config cannot live framework-side
+  without widening that type. The TS build registered three provider objects
+  (``anthropic``, ``openai-codex``, ``github-copilot``); the first two map to
+  the framework's authorization-code (PKCE) configs, but **GitHub Copilot uses
+  the OAuth device-authorization grant** (RFC 8628) — a flow the framework has
+  no primitive for. So the Copilot provider is registered **app-side** here,
+  with its own device-flow login/refresh driver ported from the TS
+  ``githubCopilotOAuthProvider``. The built-in set is therefore the two
+  framework configs *plus* the app's ``github-copilot`` adapter, and the tests
+  pin *that* set.
+- A provider's login choreography is its adapter's
+  :attr:`OAuthProviderAdapter.driver`. The default driver is the
+  authorization-code (PKCE) flow the two framework configs run; Copilot
+  supplies the device-flow driver. ``start_oauth_login`` always drives through
+  the adapter's driver, so adding a new flow is a per-adapter change, not a
+  fork in the command path.
+- ``callbacks.on_auth`` may return an awaitable; the driver awaits it. (TS
+  fired the browser-open as a dangling ``void`` promise; awaiting keeps the
+  print ordering deterministic without changing the callback shape tests
+  drive.)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Final, Literal, TypeAlias
+from urllib.parse import parse_qs, urlsplit
+
+from indusagi.llmgateway.credentials.oauth import (
+    OAUTH_PROVIDERS,
+    AuthUrlInputs,
+    OAuthConfig,
+    build_auth_url,
+    exchange_code,
+    refresh_token,
+)
+from indusagi.llmgateway.credentials.pkce import create_pkce_pair
+
+from .contract import AuthVault, OAuthCredentials
+
+__all__ = [
+    "AuthKind",
+    "LoginDriver",
+    "LoginProvider",
+    "OAuthAuthorization",
+    "OAuthLoginCallbacks",
+    "OAuthLoginError",
+    "OAuthLoginResult",
+    "OAuthPrompt",
+    "OAuthProviderAdapter",
+    "RefreshDriver",
+    "get_oauth_provider",
+    "get_oauth_providers",
+    "github_copilot_adapter",
+    "list_login_providers",
+    "open_login_url",
+    "refresh_oauth_credentials",
+    "register_built_in_oauth_providers",
+    "register_oauth_provider",
+    "start_oauth_login",
+]
+
+
+# ---------------------------------------------------------------------------
+# Login callbacks (the TS OAuthLoginCallbacks shape, app-owned in the port)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthAuthorization:
+    """What ``on_auth`` receives: the consent URL the user must visit, plus
+    optional human-facing instructions."""
+
+    url: str
+    instructions: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthPrompt:
+    """What ``on_prompt`` receives: the question the flow needs answered (the
+    pasted authorization code)."""
+
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthLoginCallbacks:
+    """The interactive seams the login flow drives. ``on_auth`` surfaces the
+    consent URL (and may return an awaitable, which is awaited); ``on_prompt``
+    reads one line of user input; ``on_progress`` relays status lines."""
+
+    on_auth: Callable[[OAuthAuthorization], None | Awaitable[None]]
+    on_prompt: Callable[[OAuthPrompt], Awaitable[str]]
+    on_progress: Callable[[str], None] | None = None
+
+
+class OAuthLoginError(RuntimeError):
+    """A browser sign-in failure (unknown provider, aborted paste, or a
+    failed exchange wrapped by the gateway)."""
+
+
+# ---------------------------------------------------------------------------
+# Provider registry (the adapter's own — the framework has none to prime)
+# ---------------------------------------------------------------------------
+
+
+#: A provider's login choreography: drive the callbacks and return the
+#: vault-shaped credentials. The default is the authorization-code (PKCE)
+#: flow; a provider whose sign-in differs (GitHub Copilot's device grant)
+#: supplies its own.
+LoginDriver: TypeAlias = Callable[
+    ["OAuthProviderAdapter", "OAuthLoginCallbacks"], Awaitable[OAuthCredentials]
+]
+
+#: A provider's refresh choreography: mint fresh credentials from a stored
+#: refresh token. The default trades a refresh token at the framework token
+#: endpoint; a device-flow provider re-derives a short-lived token instead.
+RefreshDriver: TypeAlias = Callable[
+    ["OAuthProviderAdapter", OAuthCredentials], Awaitable[OAuthCredentials]
+]
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthProviderAdapter:
+    """One registered browser-sign-in provider: its stable id, a human name,
+    the framework :class:`OAuthConfig` the flow runs over, and the
+    login/refresh drivers that choreograph it.
+
+    ``driver`` / ``refresh_driver`` default to ``None``, which selects the
+    built-in authorization-code (PKCE) flow the two framework configs use. A
+    provider with a different sign-in shape — GitHub Copilot's device grant —
+    supplies its own drivers; ``config`` then carries only what that driver
+    reads (Copilot reads none of it, so a placeholder config stands in)."""
+
+    # Stable provider id (the registry key).
+    id: str
+    # Human-facing provider name (the directory fallback label).
+    name: str
+    # The framework endpoint + client configuration the default flow drives.
+    config: OAuthConfig
+    # The login choreography; None selects the default PKCE flow.
+    driver: LoginDriver | None = None
+    # The refresh choreography; None selects the default token-endpoint refresh.
+    refresh_driver: RefreshDriver | None = None
+
+
+#: Human labels for the provider ids this app supplies one for. Covers both
+#: the Python framework's config ids and the TS lineage's provider-object ids
+#: so the merged directory reads well whichever the table grows to carry.
+_OAUTH_LABELS: Final[dict[str, str]] = {
+    "anthropic": "Anthropic (Claude sign-in)",
+    "openai": "OpenAI (ChatGPT sign-in)",
+    "openai-codex": "OpenAI (ChatGPT sign-in)",
+    "github-copilot": "GitHub Copilot",
+}
+
+#: The adapter registry. Module-held like the TS framework registry was, but
+#: populated only by the explicit prime below — never at import time.
+_REGISTRY: dict[str, OAuthProviderAdapter] = {}
+
+
+def register_oauth_provider(provider: OAuthProviderAdapter) -> None:
+    """Register (or replace) one browser-sign-in provider."""
+    _REGISTRY[provider.id] = provider
+
+
+def get_oauth_provider(provider_id: str) -> OAuthProviderAdapter | None:
+    """Look up a registered provider by id, or ``None``."""
+    return _REGISTRY.get(provider_id)
+
+
+def get_oauth_providers() -> list[OAuthProviderAdapter]:
+    """Every registered provider, in registration order."""
+    return list(_REGISTRY.values())
+
+
+def _reset_oauth_providers_for_tests() -> None:
+    """Test hook: empty the registry so suites stay hermetic."""
+    _REGISTRY.clear()
+
+
+def register_built_in_oauth_providers() -> list[str]:
+    """Register the built-in sign-in providers, idempotently.
+
+    Walks the framework :data:`OAUTH_PROVIDERS` config table and registers an
+    adapter for each authorization-code provider (``anthropic``, ``openai``)
+    not already present, then registers the **app-side**
+    :func:`github_copilot_adapter` whose device-flow driver has no framework
+    config (see the module docstring). Repeated calls leave the registry
+    unchanged. Returns the ids that are registered after the call, for callers
+    that want to confirm the set.
+
+    This is the **explicit prime** the boot layer runs as a stage; nothing
+    runs it at import time.
+    """
+    for provider_id, config in OAUTH_PROVIDERS.items():
+        if get_oauth_provider(provider_id) is None:
+            register_oauth_provider(
+                OAuthProviderAdapter(
+                    id=str(provider_id),
+                    name=_OAUTH_LABELS.get(str(provider_id), str(provider_id)),
+                    config=config,
+                )
+            )
+    if get_oauth_provider("github-copilot") is None:
+        register_oauth_provider(github_copilot_adapter())
+    return [provider.id for provider in get_oauth_providers()]
+
+
+# ---------------------------------------------------------------------------
+# Merged sign-in directory
+# ---------------------------------------------------------------------------
+
+#: How a provider authenticates in the merged sign-in directory.
+AuthKind: TypeAlias = Literal["oauth", "apiKey"]
+
+
+@dataclass(frozen=True, slots=True)
+class LoginProvider:
+    """One row of the merged sign-in directory."""
+
+    # Stable provider id (adapter registry id or api-key directory id).
+    id: str
+    # Human-facing label for menus and prompts.
+    label: str
+    # Whether this entry signs in via the browser or stores an api key.
+    auth_kind: AuthKind
+
+
+def list_login_providers() -> list[LoginProvider]:
+    """The merged sign-in directory: every registered browser-sign-in provider
+    plus every api-key provider the app knows, each tagged with its auth kind.
+
+    Browser-sign-in providers lead the list (they are the preferred path for
+    the providers that support them); an api-key provider that shares an id
+    with a registered sign-in provider is still listed, so a user can choose
+    either path for the same underlying account.
+    """
+    # Imported lazily: credentials.py imports this module at the top level
+    # (the same cycle the TS pair had; one side must defer in Python).
+    from .credentials import PROVIDER_DIRECTORY
+
+    oauth_rows = [
+        LoginProvider(
+            id=provider.id,
+            label=_OAUTH_LABELS.get(provider.id, provider.name),
+            auth_kind="oauth",
+        )
+        for provider in get_oauth_providers()
+    ]
+    api_key_rows = [
+        LoginProvider(id=entry.id, label=entry.label, auth_kind="apiKey")
+        for entry in PROVIDER_DIRECTORY
+    ]
+    return [*oauth_rows, *api_key_rows]
+
+
+# ---------------------------------------------------------------------------
+# Browser launcher
+# ---------------------------------------------------------------------------
+
+
+def _is_web_url(url: str) -> bool:
+    """Accept only ``http``/``https`` urls; anything else is refused before
+    launch."""
+    try:
+        split = urlsplit(url)
+    except ValueError:
+        return False
+    return split.scheme in ("http", "https") and bool(split.netloc)
+
+
+async def open_login_url(url: str) -> bool:
+    """Open a sign-in url in the user's default browser.
+
+    Refuses anything that is not an ``http``/``https`` url and resolves
+    ``False``, so a provider that hands back a non-web redirect never spawns a
+    process. The launch itself goes through :func:`webbrowser.open`, which
+    encodes the per-platform default-browser fallbacks the TS spawn table
+    spelled out by hand. Resolves ``True`` if a browser was launched,
+    ``False`` otherwise.
+    """
+    if not _is_web_url(url):
+        return False
+    import asyncio
+    import webbrowser
+
+    try:
+        return bool(await asyncio.to_thread(webbrowser.open, url))
+    except Exception:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Login flow
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthLoginResult:
+    """The outcome of :func:`start_oauth_login`: the provider and account the
+    credentials were stored under, and whether this account became the
+    default."""
+
+    # The provider id the sign-in completed for.
+    provider: str
+    # The account name the credentials were stored under.
+    account: str
+    # Whether the new account was stored as the provider default.
+    made_default: bool
+
+
+def _extract_code(pasted: str) -> str:
+    """Pull an authorization code out of whatever the user pasted. They may
+    paste the bare code, or the whole redirect URL — in the latter case the
+    ``code`` query parameter is read. A ``code#state`` fragment (some
+    providers append the state) is trimmed to the code half."""
+    if len(pasted) == 0:
+        return ""
+    if "://" in pasted or pasted.startswith("http"):
+        try:
+            split = urlsplit(pasted)
+        except ValueError:
+            split = None
+        if split is not None and split.scheme and (split.netloc or split.path):
+            from_query = parse_qs(split.query).get("code", [])
+            if from_query and from_query[0]:
+                return from_query[0]
+    hash_index = pasted.find("#")
+    return pasted if hash_index == -1 else pasted[:hash_index]
+
+
+def _to_credentials(
+    tokens: object, *, prior_refresh: str | None = None
+) -> OAuthCredentials:
+    """Map a framework ``OAuthTokens`` record into the vault's
+    :class:`~.contract.OAuthCredentials` shape, carrying a prior refresh token
+    forward when the server did not rotate one."""
+    access = getattr(tokens, "access_token", "")
+    refresh = getattr(tokens, "refresh_token", None)
+    expires = getattr(tokens, "expires_at", None)
+    return OAuthCredentials(
+        access=str(access),
+        refresh=refresh if isinstance(refresh, str) else prior_refresh,
+        expires=expires if isinstance(expires, int) else None,
+    )
+
+
+async def _drive_login(
+    adapter: OAuthProviderAdapter,
+    callbacks: OAuthLoginCallbacks,
+) -> OAuthCredentials:
+    """The re-choreographed ``provider.login(callbacks)``: PKCE + auth URL →
+    ``on_auth`` → pasted code via ``on_prompt`` → ``exchange_code`` →
+    credentials. Raises :class:`OAuthLoginError` when the user pastes nothing;
+    a failed exchange propagates the gateway error."""
+    pkce = create_pkce_pair()
+    state = str(uuid.uuid4())
+    url = build_auth_url(adapter.config, AuthUrlInputs(state=state, pkce=pkce))
+
+    handled = callbacks.on_auth(
+        OAuthAuthorization(
+            url=url,
+            instructions=(
+                "Approve access, then paste the authorization code "
+                "(or the full redirect URL) back here."
+            ),
+        )
+    )
+    if inspect.isawaitable(handled):
+        await handled
+
+    pasted = (
+        await callbacks.on_prompt(OAuthPrompt(message="Paste the authorization code:"))
+    ).strip()
+    code = _extract_code(pasted)
+    if len(code) == 0:
+        raise OAuthLoginError("No authorization code was entered.")
+
+    if callbacks.on_progress is not None:
+        callbacks.on_progress("Exchanging the authorization code for tokens...")
+    tokens = await exchange_code(adapter.config, code, pkce.verifier)
+    return _to_credentials(tokens)
+
+
+async def start_oauth_login(
+    provider_id: str,
+    callbacks: OAuthLoginCallbacks,
+    vault: AuthVault,
+    account: str = "default",
+) -> OAuthLoginResult:
+    """Drive a provider's browser sign-in and persist the result.
+
+    Looks the provider up in the (primed) adapter registry, runs the
+    re-choreographed login flow with the supplied callbacks, and writes the
+    returned credentials into the vault under ``account``. The first account
+    stored for a provider becomes its default. Raises when the provider id is
+    not registered or the login flow fails.
+
+    :param provider_id: the registered sign-in provider id
+    :param callbacks: the login callbacks (url surface, prompt, progress)
+    :param vault: the credential store the result is persisted through
+    :param account: the account name to store under (defaults to "default")
+    """
+    adapter = get_oauth_provider(provider_id)
+    if adapter is None:
+        raise OAuthLoginError(
+            f'No browser sign-in is available for "{provider_id}".'
+        )
+
+    # Each adapter chooses its own login choreography; the default is the
+    # authorization-code (PKCE) flow.
+    drive = adapter.driver if adapter.driver is not None else _drive_login
+    credentials = await drive(adapter, callbacks)
+
+    existing = await vault.list_accounts(provider_id)
+    made_default = len(existing) == 0
+    await vault.put_oauth(provider_id, account, credentials, made_default)
+
+    return OAuthLoginResult(
+        provider=provider_id, account=account, made_default=made_default
+    )
+
+
+# ---------------------------------------------------------------------------
+# Refresh seam (the TS ensureFreshOAuthCredentials analogue)
+# ---------------------------------------------------------------------------
+
+
+async def refresh_oauth_credentials(
+    provider_id: str,
+    credentials: OAuthCredentials,
+) -> OAuthCredentials:
+    """Mint fresh credentials from a stored refresh token.
+
+    The seam the boot layer's disk vault calls from ``read_usable_key`` when a
+    stored browser token has expired (it persists whatever this returns).
+    Carries the prior refresh token forward when the server does not rotate
+    one. Raises :class:`OAuthLoginError` when the provider is unknown or the
+    record has no refresh token; a failed wire refresh propagates the gateway
+    error.
+    """
+    adapter = get_oauth_provider(provider_id)
+    if adapter is None:
+        raise OAuthLoginError(
+            f'No browser sign-in is available for "{provider_id}".'
+        )
+    if credentials.refresh is None:
+        raise OAuthLoginError(
+            f"Stored {provider_id} credentials have no refresh token."
+        )
+    # A provider with a custom login flow (device grant) refreshes its own way.
+    if adapter.refresh_driver is not None:
+        return await adapter.refresh_driver(adapter, credentials)
+    tokens = await refresh_token(adapter.config, credentials.refresh)
+    return _to_credentials(tokens, prior_refresh=credentials.refresh)
+
+
+# ---------------------------------------------------------------------------
+# GitHub Copilot — the OAuth device-authorization grant (RFC 8628)
+# ---------------------------------------------------------------------------
+#
+# Ported from the TS ``githubCopilotOAuthProvider``
+# (indus-rebuild/src/facade/ml/kit/auth/github-copilot.ts). Copilot signs in
+# with the *device* grant, not the authorization-code flow the framework
+# configs use: the CLI shows the user a verification URL and a short code, the
+# user enters the code in a browser, and the CLI polls GitHub until the grant
+# is approved. The GitHub access token is then traded at Copilot's token
+# endpoint for the short-lived bearer the model API consumes — that bearer is
+# the stored ``access`` and the GitHub token is the stored ``refresh``.
+
+#: OAuth client id GitHub recognises for the device flow. A real deployment
+#: registers its own GitHub OAuth app and exports its id; the placeholder
+#: mirrors the TS default (the flow runs but GitHub rejects an unregistered
+#: client, exactly as in the TS build).
+_COPILOT_CLIENT_ID: Final[str] = os.environ.get(
+    "INDUSAGI_GITHUB_COPILOT_CLIENT_ID", "<UNREGISTERED-COPILOT-APP>"
+)
+
+#: Headers GitHub's Copilot backend expects from a recognised editor
+#: integration (identical to the TS request headers).
+_COPILOT_HEADERS: Final[dict[str, str]] = {
+    "User-Agent": "GitHubCopilotChat/0.35.0",
+    "Editor-Version": "vscode/1.107.0",
+    "Editor-Plugin-Version": "copilot-chat/0.35.0",
+    "Copilot-Integration-Id": "vscode-chat",
+}
+
+#: The scope the device-code request asks for (TS ``"read:user"``).
+_COPILOT_SCOPE: Final[str] = "read:user"
+
+#: A placeholder framework config so the adapter dataclass stays well-formed;
+#: the device-flow driver reads none of it (GitHub's endpoints are derived
+#: from the host below, not this config).
+_COPILOT_CONFIG: Final[OAuthConfig] = OAuthConfig(
+    provider="anthropic",  # type: ignore[arg-type]  # placeholder; unused by the device driver
+    authorize_url="https://github.com/login/device",
+    token_url="https://github.com/login/oauth/access_token",
+    client_id=_COPILOT_CLIENT_ID,
+    redirect_uri="",
+    scopes=(_COPILOT_SCOPE,),
+)
+
+
+def _copilot_endpoints(domain: str) -> tuple[str, str, str]:
+    """The three GitHub endpoints the device flow uses for a host (TS
+    ``buildEndpoints``): device-code, access-token, copilot-token."""
+    return (
+        f"https://{domain}/login/device/code",
+        f"https://{domain}/login/oauth/access_token",
+        f"https://api.{domain}/copilot_internal/v2/token",
+    )
+
+
+async def _copilot_post_json(
+    url: str, body: dict[str, Any], *, extra_headers: dict[str, str] | None = None
+) -> dict[str, Any]:
+    """POST a JSON body and return the parsed JSON object, raising
+    :class:`OAuthLoginError` on a non-2xx status (TS ``request``)."""
+    import httpx
+
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "GitHubCopilotChat/0.35.0",
+    }
+    if extra_headers is not None:
+        headers.update(extra_headers)
+    async with httpx.AsyncClient(timeout=None) as client:
+        response = await client.post(url, json=body, headers=headers)
+    if not response.is_success:
+        detail = ""
+        try:
+            detail = response.text
+        except Exception:
+            detail = ""
+        raise OAuthLoginError(
+            f"GitHub returned {response.status_code}{f': {detail}' if detail else ''}."
+        )
+    parsed = response.json()
+    if not isinstance(parsed, dict):
+        raise OAuthLoginError("GitHub returned an unexpected (non-object) response.")
+    return parsed
+
+
+async def _copilot_get_json(
+    url: str, *, headers: dict[str, str]
+) -> dict[str, Any]:
+    """GET a JSON object from the Copilot token endpoint, raising on a non-2xx
+    status (TS ``request`` over a GET)."""
+    import httpx
+
+    async with httpx.AsyncClient(timeout=None) as client:
+        response = await client.get(url, headers=headers)
+    if not response.is_success:
+        detail = ""
+        try:
+            detail = response.text
+        except Exception:
+            detail = ""
+        raise OAuthLoginError(
+            f"Copilot token endpoint returned {response.status_code}"
+            f"{f': {detail}' if detail else ''}."
+        )
+    parsed = response.json()
+    if not isinstance(parsed, dict):
+        raise OAuthLoginError("Copilot token endpoint returned a non-object response.")
+    return parsed
+
+
+async def _copilot_poll_access_token(
+    domain: str, device_code: str, interval_seconds: float, expires_in: float
+) -> str:
+    """Poll GitHub for the device-grant access token until it is granted,
+    rejected, or the deadline passes (TS ``pollAccessToken``). Honours the
+    ``authorization_pending`` / ``slow_down`` back-off signals."""
+    _, access_token_url, _ = _copilot_endpoints(domain)
+    deadline = time.time() + expires_in
+    interval = max(1.0, float(interval_seconds))
+
+    while time.time() < deadline:
+        raw = await _copilot_post_json(
+            access_token_url,
+            {
+                "client_id": _COPILOT_CLIENT_ID,
+                "device_code": device_code,
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+            },
+        )
+        access = raw.get("access_token")
+        if isinstance(access, str) and access:
+            return access
+        error = raw.get("error")
+        if isinstance(error, str):
+            if error == "authorization_pending":
+                await asyncio.sleep(interval)
+                continue
+            if error == "slow_down":
+                interval += 5.0
+                await asyncio.sleep(interval)
+                continue
+            raise OAuthLoginError(
+                f"The device-authorization grant was rejected ({error})."
+            )
+        await asyncio.sleep(interval)
+
+    raise OAuthLoginError(
+        "Timed out waiting for the device authorization to be approved."
+    )
+
+
+async def _copilot_token_from_github(
+    github_access_token: str, domain: str
+) -> OAuthCredentials:
+    """Trade a GitHub access token for a short-lived Copilot bearer (TS
+    ``refreshToken``). The Copilot bearer is the stored ``access``; the GitHub
+    token is kept as ``refresh`` so it can be re-traded when the bearer
+    expires."""
+    _, _, copilot_token_url = _copilot_endpoints(domain)
+    raw = await _copilot_get_json(
+        copilot_token_url,
+        headers={
+            "Accept": "application/json",
+            "Authorization": f"Bearer {github_access_token}",
+            **_COPILOT_HEADERS,
+        },
+    )
+    token = raw.get("token")
+    expires_at = raw.get("expires_at")
+    if not isinstance(token, str) or not isinstance(expires_at, (int, float)):
+        raise OAuthLoginError(
+            "Copilot token response was missing or had malformed fields."
+        )
+    # TS subtracts a 5-minute safety margin and stores epoch-ms.
+    expires_ms = int(expires_at) * 1000 - 5 * 60 * 1000
+    return OAuthCredentials(
+        access=token, refresh=github_access_token, expires=expires_ms
+    )
+
+
+def _normalize_copilot_domain(raw: str) -> str | None:
+    """Reduce a user-entered GitHub Enterprise host to a bare hostname, or
+    ``None`` when unusable (TS ``normalizeDomain``)."""
+    cleaned = raw.strip()
+    if not cleaned:
+        return None
+    with_scheme = cleaned if cleaned.startswith("http") else f"https://{cleaned}"
+    try:
+        host = urlsplit(with_scheme).hostname
+    except ValueError:
+        return None
+    return host or None
+
+
+async def _drive_github_copilot_login(
+    adapter: OAuthProviderAdapter,
+    callbacks: OAuthLoginCallbacks,
+) -> OAuthCredentials:
+    """The GitHub Copilot device-flow login (TS ``CopilotAuthFlow.login``).
+
+    Prompts for an optional Enterprise host (blank → ``github.com``), starts
+    the device-authorization grant, surfaces the verification URL and user
+    code through ``on_auth``, polls GitHub until the grant is approved, and
+    trades the resulting GitHub token for a Copilot bearer."""
+    del adapter  # the device flow derives its endpoints from the host below
+
+    entered = await callbacks.on_prompt(
+        OAuthPrompt(
+            message=(
+                "Your GitHub Enterprise host (leave empty to use github.com):"
+            )
+        )
+    )
+    trimmed = entered.strip()
+    enterprise = _normalize_copilot_domain(trimmed) if trimmed else None
+    if trimmed and enterprise is None:
+        raise OAuthLoginError("That GitHub Enterprise host could not be parsed.")
+    domain = enterprise if enterprise is not None else "github.com"
+
+    device_code_url, _, _ = _copilot_endpoints(domain)
+    init = await _copilot_post_json(
+        device_code_url,
+        {"client_id": _COPILOT_CLIENT_ID, "scope": _COPILOT_SCOPE},
+    )
+    device_code = init.get("device_code")
+    user_code = init.get("user_code")
+    verification_uri = init.get("verification_uri")
+    interval = init.get("interval")
+    expires_in = init.get("expires_in")
+    if (
+        not isinstance(device_code, str)
+        or not isinstance(user_code, str)
+        or not isinstance(verification_uri, str)
+        or not isinstance(interval, (int, float))
+        or not isinstance(expires_in, (int, float))
+    ):
+        raise OAuthLoginError(
+            "Device authorization response was missing or had malformed fields."
+        )
+
+    handled = callbacks.on_auth(
+        OAuthAuthorization(
+            url=verification_uri,
+            instructions=f"Type this code when prompted: {user_code}",
+        )
+    )
+    if inspect.isawaitable(handled):
+        await handled
+
+    if callbacks.on_progress is not None:
+        callbacks.on_progress("Waiting for the device authorization to be approved...")
+
+    github_access_token = await _copilot_poll_access_token(
+        domain, device_code, float(interval), float(expires_in)
+    )
+
+    if callbacks.on_progress is not None:
+        callbacks.on_progress("Exchanging the GitHub token for a Copilot token...")
+    return await _copilot_token_from_github(github_access_token, domain)
+
+
+async def _refresh_github_copilot(
+    adapter: OAuthProviderAdapter,
+    credentials: OAuthCredentials,
+) -> OAuthCredentials:
+    """Re-derive a Copilot bearer from the stored GitHub token (TS
+    ``githubCopilotOAuthProvider.refreshToken``). The stored ``refresh`` is the
+    GitHub access token; it is re-traded against ``github.com`` (the default
+    host)."""
+    del adapter
+    if credentials.refresh is None:  # pragma: no cover - guarded by the caller
+        raise OAuthLoginError("Stored github-copilot credentials have no refresh token.")
+    return await _copilot_token_from_github(credentials.refresh, "github.com")
+
+
+def github_copilot_adapter() -> OAuthProviderAdapter:
+    """Build the app-side GitHub Copilot sign-in adapter, wired to the
+    device-flow login and refresh drivers. Registered by
+    :func:`register_built_in_oauth_providers` so ``pindus signin --provider
+    github-copilot`` drives the device grant — the framework has no
+    ``github-copilot`` config or device-code primitive (see the module
+    docstring), so this provider is owned entirely here."""
+    return OAuthProviderAdapter(
+        id="github-copilot",
+        name=_OAUTH_LABELS["github-copilot"],
+        config=_COPILOT_CONFIG,
+        driver=_drive_github_copilot_login,
+        refresh_driver=_refresh_github_copilot,
+    )