godfather-cli 2.1.0__tar.gz → 2.2.0__tar.gz

{godfather_cli-2.1.0/godfather_cli.egg-info → godfather_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godfather-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: Free compute for ASU students: connect to AI Society at ASU GPU pods
 Author-email: AI Society ASU <theaisocietyasu@gmail.com>
 License: MIT
@@ -62,10 +62,13 @@ pip install -e .
 
 1. Run `godfather` with no arguments. On first run you won't be logged in
    yet, so it'll walk you into the login flow.
-2. It opens the AI Society platform's sign-in page in your browser (and
-   prints the link). Sign in with Discord and copy the token shown there.
-3. Paste the token back into the terminal. The CLI checks it with the
-   platform and stores it in `~/.godfather/config.json`.
+2. It opens the sign-in page in your browser and prints the link. Sign in
+   with Discord. The browser sends the login back to the CLI, which checks it
+   and stores the token in `~/.godfather/config.json`.
+3. If the browser cannot reach the CLI (no browser on this computer, an
+   older server, or no sign-in within 5 minutes), the CLI asks you to paste
+   the token that the sign-in page shows. `godfather auth --paste` goes
+   straight to that, for a browser on another computer.
 4. From the menu (or `godfather connect`), pick a pod. The CLI creates an SSH
    key on your machine the first time, asks the server for a 12-hour
    certificate for that pod, and opens the connection.
@@ -81,12 +84,14 @@ Windows 10+ ship it.
 ### Interactive menu
 
 Running `godfather` with no arguments opens a menu. Use the arrow keys to
-choose Connect to a pod, List pods, Status, Log out or Exit, and press Enter.
-Ctrl-C quits.
+choose Connect to a pod, List pods, Sessions, Status, Log out or Exit, and
+press Enter. Ctrl-C quits.
 
 Connect to a pod shows a list of your pods with their status, access and
 pod ID. A pod that is not running shows with the reason and cannot be
 chosen. If only one pod is running, the CLI asks for a yes instead.
+If none of your pods is running, the CLI shows the next session on your
+pods. A pod starts 10 minutes before its session.
 
 When input is not a terminal (for example in a script), the menu and the pod
 list use numbered prompts.
@@ -97,8 +102,11 @@ list use numbered prompts.
 godfather list                    # List pods you can connect to
 godfather connect                 # Connect to a pod, picking from a list
 godfather connect <pod-id>        # Connect to a specific pod
+godfather connect --admin         # Ask for a root shell (officers, when pod admin is on)
+godfather sessions                # Upcoming sessions on your pods, in local time
 godfather status                  # Show server, org, login, token expiry and version
-godfather auth                    # Log in, or refresh an expired session
+godfather auth                    # Log in with Discord in your browser
+godfather auth --paste            # Log in by pasting the token
 godfather logout                  # Clear the stored session
 godfather update                  # Update the CLI to the latest version
 
@@ -141,23 +149,23 @@ another server or org; the ones you last logged in with are remembered.
 ## Development
 
 The code is in `godfather_cli/`: `cli.py` (commands and menu), `picker.py` (arrow-key menu and pod picker), `auth.py`
-(platform sign-in), `pod_manager.py` (API calls), `ssh_connector.py` (keys,
+(platform sign-in), `login_server.py` (the sign-in callback), `pod_manager.py` (API calls), `ssh_connector.py` (keys,
 certificate, running ssh), `update_checker.py` (PyPI version check), `ui.py`
 (shared console styling). Tests are in `tests/`:
 
 ```bash
-pip install -e . pytest
-pytest -q tests
+uv sync --group dev
+uv run pytest -q tests
 ```
 
+`make check-cli` at the repo root runs ruff, the tests and a build, as CI does.
+
 Releases go to PyPI when a version bump is merged to main; see the
 repo README.
 
 ## Contributing
 
-1. Fork the repository.
-2. Create a feature branch (`git checkout -b feature/your-feature`).
-3. Commit your changes and open a Pull Request.
+See [CONTRIBUTING.md](../CONTRIBUTING.md).
 
 ## License
 

{godfather_cli-2.1.0 → godfather_cli-2.2.0}/README.md

@@ -33,10 +33,13 @@ pip install -e .
 
 1. Run `godfather` with no arguments. On first run you won't be logged in
    yet, so it'll walk you into the login flow.
-2. It opens the AI Society platform's sign-in page in your browser (and
-   prints the link). Sign in with Discord and copy the token shown there.
-3. Paste the token back into the terminal. The CLI checks it with the
-   platform and stores it in `~/.godfather/config.json`.
+2. It opens the sign-in page in your browser and prints the link. Sign in
+   with Discord. The browser sends the login back to the CLI, which checks it
+   and stores the token in `~/.godfather/config.json`.
+3. If the browser cannot reach the CLI (no browser on this computer, an
+   older server, or no sign-in within 5 minutes), the CLI asks you to paste
+   the token that the sign-in page shows. `godfather auth --paste` goes
+   straight to that, for a browser on another computer.
 4. From the menu (or `godfather connect`), pick a pod. The CLI creates an SSH
    key on your machine the first time, asks the server for a 12-hour
    certificate for that pod, and opens the connection.
@@ -52,12 +55,14 @@ Windows 10+ ship it.
 ### Interactive menu
 
 Running `godfather` with no arguments opens a menu. Use the arrow keys to
-choose Connect to a pod, List pods, Status, Log out or Exit, and press Enter.
-Ctrl-C quits.
+choose Connect to a pod, List pods, Sessions, Status, Log out or Exit, and
+press Enter. Ctrl-C quits.
 
 Connect to a pod shows a list of your pods with their status, access and
 pod ID. A pod that is not running shows with the reason and cannot be
 chosen. If only one pod is running, the CLI asks for a yes instead.
+If none of your pods is running, the CLI shows the next session on your
+pods. A pod starts 10 minutes before its session.
 
 When input is not a terminal (for example in a script), the menu and the pod
 list use numbered prompts.
@@ -68,8 +73,11 @@ list use numbered prompts.
 godfather list                    # List pods you can connect to
 godfather connect                 # Connect to a pod, picking from a list
 godfather connect <pod-id>        # Connect to a specific pod
+godfather connect --admin         # Ask for a root shell (officers, when pod admin is on)
+godfather sessions                # Upcoming sessions on your pods, in local time
 godfather status                  # Show server, org, login, token expiry and version
-godfather auth                    # Log in, or refresh an expired session
+godfather auth                    # Log in with Discord in your browser
+godfather auth --paste            # Log in by pasting the token
 godfather logout                  # Clear the stored session
 godfather update                  # Update the CLI to the latest version
 
@@ -112,23 +120,23 @@ another server or org; the ones you last logged in with are remembered.
 ## Development
 
 The code is in `godfather_cli/`: `cli.py` (commands and menu), `picker.py` (arrow-key menu and pod picker), `auth.py`
-(platform sign-in), `pod_manager.py` (API calls), `ssh_connector.py` (keys,
+(platform sign-in), `login_server.py` (the sign-in callback), `pod_manager.py` (API calls), `ssh_connector.py` (keys,
 certificate, running ssh), `update_checker.py` (PyPI version check), `ui.py`
 (shared console styling). Tests are in `tests/`:
 
 ```bash
-pip install -e . pytest
-pytest -q tests
+uv sync --group dev
+uv run pytest -q tests
 ```
 
+`make check-cli` at the repo root runs ruff, the tests and a build, as CI does.
+
 Releases go to PyPI when a version bump is merged to main; see the
 repo README.
 
 ## Contributing
 
-1. Fork the repository.
-2. Create a feature branch (`git checkout -b feature/your-feature`).
-3. Commit your changes and open a Pull Request.
+See [CONTRIBUTING.md](../CONTRIBUTING.md).
 
 ## License
 

{godfather_cli-2.1.0 → godfather_cli-2.2.0}/godfather_cli/__init__.py

@@ -2,6 +2,6 @@
 Godfather CLI package
 """
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 __author__ = "AI Society ASU"
 __email__ = "admin@ais-asu.com"

{godfather_cli-2.1.0 → godfather_cli-2.2.0}/godfather_cli/auth.py

@@ -1,21 +1,30 @@
 """CLI authentication: token storage, login flow, and token verification."""
 
+import base64
 import datetime
+import hashlib
 import json
 import os
-import requests
+import secrets
 import webbrowser
 from pathlib import Path
 from typing import Dict, Optional
+from urllib.parse import urlencode
+
+import requests
 from rich.panel import Panel
 from rich.prompt import Prompt
 
-from .ui import console, success, error, warning, spinner, BOX, BORDER
+from .login_server import LoopbackReceiver
+from .ui import BORDER, BOX, console, error, spinner, success, warning
 
 TOKEN_PREFIX = 'plat_'
 # The platform issues CLI tokens for 90 days.
 TOKEN_DAYS = 90
 
+# How long the CLI waits for the browser sign-in.
+LOGIN_WAIT_SECONDS = 300
+
 # Token states that check_token returns.
 TOKEN_OK = 'ok'
 TOKEN_MISSING = 'missing'
@@ -24,6 +33,17 @@ TOKEN_UNREACHABLE = 'unreachable'
 TOKEN_REFUSED = 'refused'
 
 
+def make_verifier() -> str:
+    """A PKCE code verifier (RFC 7636): 64 URL-safe characters."""
+    return secrets.token_urlsafe(48)
+
+
+def challenge_for(verifier: str) -> str:
+    """The S256 code challenge of a verifier: base64url SHA-256 without padding."""
+    digest = hashlib.sha256(verifier.encode('ascii')).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b'=').decode('ascii')
+
+
 class CLIAuthenticator:
     """Handle CLI authentication."""
 
@@ -61,8 +81,84 @@ class CLIAuthenticator:
         """URL of a platform compute route for the configured org."""
         return f"{self.api_base}/api/compute/{self.org}{path}"
 
-    def authenticate(self) -> bool:
-        """Walk the user through signing in with Discord and pasting the token it shows."""
+    def authenticate(self, paste: bool = False) -> bool:
+        """Sign in with Discord. The browser hands the token back; the paste flow is the fallback."""
+        if not paste:
+            if self.supports_loopback():
+                token = self._browser_login()
+                if token:
+                    return self._verify_and_save(token)
+            else:
+                console.print("[dim]This server does not support browser sign-in yet. Paste the token instead.[/dim]")
+        return self._paste_login()
+
+    def supports_loopback(self) -> bool:
+        """True when the server has the cli/token route. It answers 400 to an empty body."""
+        try:
+            response = requests.post(self.compute_url('/cli/token'), json={}, timeout=10)
+        except requests.RequestException:
+            return False
+        return response.status_code == 400
+
+    def _browser_login(self) -> Optional[str]:
+        """The token from the localhost callback with PKCE, or None after printing why not."""
+        state = secrets.token_urlsafe(16)
+        verifier = make_verifier()
+        try:
+            receiver = LoopbackReceiver(state)
+        except OSError:
+            console.print("[dim]Could not listen on 127.0.0.1. Paste the token instead.[/dim]")
+            return None
+        try:
+            query = urlencode(
+                {
+                    'port': receiver.port,
+                    'state': state,
+                    'code_challenge': challenge_for(verifier),
+                    'code_challenge_method': 'S256',
+                }
+            )
+            login_url = f"{self.compute_url('/cli/login')}?{query}"
+            try:
+                opened = webbrowser.open(login_url)
+            except webbrowser.Error:
+                opened = False
+            if not opened:
+                console.print("[dim]No browser opened on this computer. Paste the token instead.[/dim]")
+                return None
+            console.print(f"Sign in with Discord in your browser. If it did not open, go to:\n{login_url}")
+            try:
+                with spinner("Waiting for the browser sign-in..."):
+                    code = receiver.wait(LOGIN_WAIT_SECONDS)
+            except KeyboardInterrupt:
+                console.print("[dim]Cancelled[/dim]")
+                return None
+        finally:
+            receiver.close()
+        if not code:
+            console.print("[dim]The browser sign-in did not finish in time. Paste the token instead.[/dim]")
+            return None
+        return self._redeem(code, verifier)
+
+    def _redeem(self, code: str, verifier: str) -> Optional[str]:
+        """Exchange the one-time code and the PKCE verifier for a token."""
+        try:
+            with spinner("Getting your token..."):
+                response = requests.post(
+                    self.compute_url('/cli/token'),
+                    json={'code': code, 'code_verifier': verifier},
+                    timeout=10,
+                )
+            token = str(response.json().get('token') or '') if response.status_code == 200 else ''
+        except (requests.RequestException, ValueError, AttributeError):
+            token = ''
+        if not token.startswith(TOKEN_PREFIX):
+            console.print("[dim]The server did not return a token. Paste the token instead.[/dim]")
+            return None
+        return token
+
+    def _paste_login(self) -> bool:
+        """Open the sign-in page and take the token the member pastes."""
         login_url = self.compute_url('/cli/login')
         panel = Panel(
             f"[bold]1.[/bold] Open [bold]{login_url}[/bold] and sign in with Discord\n"
@@ -91,13 +187,14 @@ class CLIAuthenticator:
             error("That doesn't look like a valid Godfather token")
             console.print(f"[dim]Tokens start with {TOKEN_PREFIX}. Get a fresh one from {login_url}[/dim]")
             return False
+        return self._verify_and_save(token)
 
+    def _verify_and_save(self, token: str) -> bool:
+        """Check the token with GET /me/pods, then save it with the server and org."""
         try:
             with spinner("Verifying token..."):
                 response = requests.get(
-                    self.compute_url('/me/pods'),
-                    headers={'Authorization': f'Bearer {token}'},
-                    timeout=10
+                    self.compute_url('/me/pods'), headers={'Authorization': f'Bearer {token}'}, timeout=10
                 )
         except requests.ConnectionError:
             error(f"Couldn't reach {self.api_base}")
@@ -153,11 +250,7 @@ class CLIAuthenticator:
             return TOKEN_MISSING
 
         try:
-            response = requests.get(
-                self.compute_url('/me/pods'),
-                headers=self.auth_headers(),
-                timeout=5
-            )
+            response = requests.get(self.compute_url('/me/pods'), headers=self.auth_headers(), timeout=5)
         except requests.RequestException:
             return TOKEN_UNREACHABLE
         if response.status_code == 200:

{godfather_cli-2.1.0 → godfather_cli-2.2.0}/godfather_cli/cli.py

@@ -8,19 +8,24 @@ from pathlib import Path
 from typing import Dict, List, Optional
 
 from rich.panel import Panel
-from rich.table import Table
 from rich.prompt import Prompt
+from rich.table import Table
 
-from . import picker
+from . import __version__, picker
 from .auth import (
-    CLIAuthenticator, TOKEN_DAYS, TOKEN_EXPIRED, TOKEN_MISSING, TOKEN_OK, TOKEN_REFUSED, TOKEN_UNREACHABLE,
+    TOKEN_DAYS,
+    TOKEN_EXPIRED,
+    TOKEN_MISSING,
+    TOKEN_OK,
+    TOKEN_REFUSED,
+    TOKEN_UNREACHABLE,
+    CLIAuthenticator,
 )
 from .picker import ask_menu, ask_pod, ask_yes, connectable, is_interactive
-from .pod_manager import ApiError, EXPIRED, PodManager, report
+from .pod_manager import EXPIRED, ApiError, PodManager, report
 from .ssh_connector import SSHConnector
-from .update_checker import check_for_updates, show_update_warning, perform_update
-from .ui import console, error, warning, info, spinner, BOX, BORDER, PURPLE
-from . import __version__
+from .ui import BORDER, BOX, PURPLE, console, error, info, spinner, warning
+from .update_checker import check_for_updates, perform_update, show_update_warning
 
 # The AI Society platform API and org. Override with --api-url/--org or GODFATHER_API_URL/GODFATHER_ORG.
 DEFAULT_API_URL = 'https://zs6k5wi0boaaax-8000.proxy.runpod.net'
@@ -60,7 +65,8 @@ class GodfatherCLI:
 
     def print_banner(self):
         banner = Panel.fit(
-            f"[bold {PURPLE}]Godfather CLI[/bold {PURPLE}]\n[dim]Free compute from AI Society at ASU v{__version__}[/dim]",
+            f"[bold {PURPLE}]Godfather CLI[/bold {PURPLE}]\n"
+            f"[dim]Free compute from AI Society at ASU v{__version__}[/dim]",
             border_style=BORDER,
             box=BOX,
         )
@@ -126,6 +132,36 @@ class GodfatherCLI:
         pods = self.load_pods()
         if pods is not None:
             self.pod_manager.show_pods(pods)
+            if not pods:
+                self.print_next_session()
+
+    def list_sessions(self):
+        """Print the upcoming sessions on the member's pods."""
+        if not self.ensure_authenticated():
+            return
+        try:
+            with spinner("Fetching sessions..."):
+                sessions = self.pod_manager.fetch_sessions()
+        except ApiError as e:
+            report(e)
+            return
+        if sessions is None:
+            info("This server does not list sessions yet.")
+        elif not sessions:
+            info("No upcoming sessions on your pods.")
+        else:
+            console.print(self.pod_manager.sessions_table(sessions))
+            console.print("[dim]A pod starts 10 minutes before its session.[/dim]")
+
+    def print_next_session(self) -> None:
+        """Print the soonest session on the member's pods. Prints nothing when there is none or on an error."""
+        try:
+            sessions = self.pod_manager.fetch_sessions()
+        except ApiError:
+            return
+        line = self.pod_manager.next_session_line(sessions or [])
+        if line:
+            console.print(line)
 
     def choose_pod(self) -> Optional[str]:
         """Fetch pods and let the user pick one. None when there is none or the user cancels."""
@@ -134,12 +170,14 @@ class GodfatherCLI:
             return None
         if not pods:
             self.pod_manager.show_no_pods()
+            self.print_next_session()
             return None
         if not is_interactive():
             return self.pod_manager.prompt_pod_number(pods)
         if not connectable(pods):
             error("None of your pods are running.")
             console.print("[dim]Ask an officer to start one, then run 'godfather connect' again.[/dim]")
+            self.print_next_session()
             return None
         try:
             return ask_pod(pods)
@@ -147,7 +185,7 @@ class GodfatherCLI:
             console.print("[dim]Cancelled[/dim]")
             return None
 
-    def connect_to_pod(self, pod_id: str = None):
+    def connect_to_pod(self, pod_id: str = None, admin: bool = False):
         if not self.ensure_authenticated():
             return
 
@@ -164,7 +202,7 @@ class GodfatherCLI:
         for attempt in range(2):
             try:
                 with spinner(f"Getting a certificate for pod {pod_id[:12]}..."):
-                    ssh_info = self.pod_manager.fetch_connection_info(pod_id, public_key)
+                    ssh_info = self.pod_manager.fetch_connection_info(pod_id, public_key, admin=admin)
                 break
             except ApiError as e:
                 if e.kind == EXPIRED and attempt == 0:
@@ -178,6 +216,8 @@ class GodfatherCLI:
 
         if not self.ssh_connector.save_certificate(ssh_info.get('certificate', '')):
             return
+        if admin and not ssh_info.get('is_admin'):
+            warning("The server gave you a member shell, not root.")
 
         self.ssh_connector.connect(ssh_info)
 
@@ -231,8 +271,8 @@ class GodfatherCLI:
     def logout(self):
         self.authenticator.logout()
 
-    def authenticate(self):
-        self.authenticator.authenticate()
+    def authenticate(self, paste: bool = False):
+        self.authenticator.authenticate(paste=paste)
 
     def update(self):
         perform_update()
@@ -243,6 +283,8 @@ class GodfatherCLI:
             self.connect_to_pod()
         elif action == picker.LIST:
             self.list_pods()
+        elif action == picker.SESSIONS:
+            self.list_sessions()
         elif action == picker.STATUS:
             self.status()
         elif action == picker.LOGIN:
@@ -272,7 +314,14 @@ class GodfatherCLI:
 
     def plain_menu(self):
         """The numbered menu for input that is not a terminal."""
-        actions = {'1': picker.LIST, '2': picker.CONNECT, '3': picker.STATUS, '4': picker.LOGOUT, '5': picker.EXIT}
+        actions = {
+            '1': picker.LIST,
+            '2': picker.CONNECT,
+            '3': picker.STATUS,
+            '4': picker.LOGOUT,
+            '5': picker.SESSIONS,
+            '6': picker.EXIT,
+        }
         while True:
             console.print()
             menu = Table.grid(padding=(0, 2))
@@ -282,7 +331,8 @@ class GodfatherCLI:
             menu.add_row("2.", "Connect to a pod")
             menu.add_row("3.", "Show status")
             menu.add_row("4.", "Log out")
-            menu.add_row("5.", "Exit")
+            menu.add_row("5.", "Show sessions")
+            menu.add_row("6.", "Exit")
             console.print(Panel(menu, title="What would you like to do?", border_style=BORDER, box=BOX))
 
             try:
@@ -318,36 +368,35 @@ Examples:
   godfather list                List available pods
   godfather connect             Connect to a pod, picking from a list
   godfather connect <pod-id>    Connect to a specific pod
+  godfather connect --admin     Connect as root (officers, on a pod with pod admin on)
+  godfather sessions            Show upcoming sessions on your pods
   godfather status              Show login and configuration status
-  godfather auth                Log in or refresh your session
+  godfather auth                Log in with Discord in your browser
+  godfather auth --paste        Log in by pasting the token (browser on another computer)
   godfather logout              Clear the stored session
   godfather update              Update the CLI to the latest version
 
 Questions or issues: https://discord.gg/fXWXwz6fEG
-        """
+        """,
     )
 
     parser.add_argument(
         'command',
         nargs='?',
-        choices=['list', 'connect', 'status', 'logout', 'auth', 'update'],
-        help='Command to run (omit to open the interactive menu)'
-    )
-    parser.add_argument(
-        'pod_id',
-        nargs='?',
-        help='Pod ID to connect to (only used with "connect")'
-    )
-    parser.add_argument(
-        '--api-url',
-        help='Use a specific platform API URL instead of the default'
-    )
-    parser.add_argument(
-        '--org',
-        help='Organization prefix on the platform (default: ais)'
+        choices=['list', 'connect', 'sessions', 'status', 'logout', 'auth', 'update'],
+        help='Command to run (omit to open the interactive menu)',
     )
+    parser.add_argument('pod_id', nargs='?', help='Pod ID to connect to (only used with "connect")')
+    parser.add_argument('--api-url', help='Use a specific platform API URL instead of the default')
+    parser.add_argument('--org', help='Organization prefix on the platform (default: ais)')
+    parser.add_argument('--paste', action='store_true', help='With "auth": paste the token, no browser sign-in')
+    parser.add_argument('--admin', action='store_true', help='With "connect": ask for a root shell')
 
     args = parser.parse_args()
+    if args.paste and args.command != 'auth':
+        parser.error('--paste works only with "auth"')
+    if args.admin and args.command != 'connect':
+        parser.error('--admin works only with "connect"')
 
     if args.api_url:
         os.environ['GODFATHER_API_URL'] = args.api_url
@@ -370,13 +419,15 @@ Questions or issues: https://discord.gg/fXWXwz6fEG
     if args.command == 'list':
         cli.list_pods()
     elif args.command == 'connect':
-        cli.connect_to_pod(args.pod_id)
+        cli.connect_to_pod(args.pod_id, admin=args.admin)
+    elif args.command == 'sessions':
+        cli.list_sessions()
     elif args.command == 'status':
         cli.status()
     elif args.command == 'logout':
         cli.logout()
     elif args.command == 'auth':
-        cli.authenticate()
+        cli.authenticate(paste=args.paste)
     elif args.command == 'update':
         cli.update()
 

godfather_cli-2.2.0/godfather_cli/login_server.py

@@ -0,0 +1,72 @@
+"""One-request HTTP server on 127.0.0.1 that receives the sign-in code from the browser."""
+
+import hmac
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Optional
+from urllib.parse import parse_qs, urlparse
+
+DONE_PAGE = (
+    b'<!doctype html><meta charset="utf-8"><title>Godfather</title>'
+    b'<p>Signed in. You can close this tab and go back to the terminal.</p>'
+)
+
+
+class _Handler(BaseHTTPRequestHandler):
+    server: '_Server'
+
+    def do_GET(self) -> None:
+        url = urlparse(self.path)
+        if url.path != '/callback':
+            self._answer(404, b'Not found')
+            return
+        query = parse_qs(url.query)
+        state = (query.get('state') or [''])[0]
+        code = (query.get('code') or [''])[0]
+        if not code or not hmac.compare_digest(state.encode(), self.server.expected_state.encode()):
+            self._answer(400, b'This sign-in link is not for this terminal.')
+            return
+        self.server.code = code
+        self._answer(200, DONE_PAGE, 'text/html; charset=utf-8')
+
+    def _answer(self, status: int, body: bytes, content_type: str = 'text/plain; charset=utf-8') -> None:
+        self.send_response(status)
+        self.send_header('Content-Type', content_type)
+        self.send_header('Content-Length', str(len(body)))
+        self.send_header('Cache-Control', 'no-store')
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format: str, *args) -> None:
+        """Request lines carry the code, so nothing is logged."""
+
+
+class _Server(HTTPServer):
+    expected_state = ''
+    code: Optional[str] = None
+
+
+class LoopbackReceiver:
+    """Listens on 127.0.0.1 on a port the OS picks and keeps the code from GET /callback."""
+
+    def __init__(self, state: str):
+        self._server = _Server(('127.0.0.1', 0), _Handler)
+        self._server.expected_state = state
+
+    @property
+    def port(self) -> int:
+        return self._server.server_address[1]
+
+    def wait(self, timeout: float) -> Optional[str]:
+        """The code from the browser, or None when timeout seconds pass first."""
+        deadline = time.monotonic() + timeout
+        while self._server.code is None:
+            left = deadline - time.monotonic()
+            if left <= 0:
+                return None
+            self._server.timeout = min(left, 1.0)
+            self._server.handle_request()
+        return self._server.code
+
+    def close(self) -> None:
+        self._server.server_close()