onehouse-python-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

{onehouse_python_sdk-0.2.0 → onehouse_python_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: onehouse-python-sdk
-Version: 0.2.0
+Version: 0.4.0
 Summary: Onehouse Python SDK — modular data-plane clients for LakeBase and beyond
 Project-URL: Homepage, https://github.com/onehouseinc/onehouse-python-sdk
 Project-URL: Repository, https://github.com/onehouseinc/onehouse-python-sdk
@@ -174,7 +174,7 @@ print(result.api_response)      # raw API payload
 Credentials resolve from three sources, in order (highest wins):
 
 1. **Explicit constructor arguments** (shown above).
-2. **Environment variables** — `ONEHOUSE_ACCOUNT_UID`, `ONEHOUSE_PROJECT_UID`, `ONEHOUSE_API_KEY`, `ONEHOUSE_API_SECRET`, `ONEHOUSE_LINK_UID`, `ONEHOUSE_REGION`, `ONEHOUSE_USER_UID`. Optional: `ONEHOUSE_BASE_URL`, `ONEHOUSE_PROFILE`, `ONEHOUSE_CREDENTIALS_FILE`.
+2. **Environment variables** — `ONEHOUSE_ACCOUNT_UID`, `ONEHOUSE_PROJECT_UID`, `ONEHOUSE_API_KEY`, `ONEHOUSE_API_SECRET`, `ONEHOUSE_LINK_UID`, `ONEHOUSE_REGION`, `ONEHOUSE_USER_UID`. Optional: `ONEHOUSE_BASE_URL`, `ONEHOUSE_PROFILE`, `ONEHOUSE_CREDENTIALS_FILE`. `ONEHOUSE_BASE_URL` is the API host (default `https://api.onehouse.ai`); a trailing `/v1` is dropped, since every request adds it.
 3. **INI credentials file** at `~/.onehouse/credentials` (override with `ONEHOUSE_CREDENTIALS_FILE`).
 
 ```ini
@@ -202,6 +202,54 @@ client = OnehouseResources(profile="staging")
 
 Missing fields produce an `AuthError` listing which fields are unset and how to supply them. A world-readable credentials file triggers a warning — `chmod 600 ~/.onehouse/credentials`.
 
+### OAuth sign-in instead of an API key
+
+A person can sign in through the browser instead of holding an API key. external-api runs an OAuth 2.1 authorization server (authorization code + PKCE). Its access token is a Firebase ID token for the signed-in user and lasts an hour. Its refresh token rotates on every use and lasts 30 days. The org must have `enable_external_api_bearer_auth` on.
+
+```python
+from pathlib import Path
+from onehouse_python_sdk._session import FileSessionStore
+from onehouse_python_sdk.resources import oauth
+
+store = FileSessionStore(Path.home() / ".onehouse" / "session.json")
+oauth.login("https://api.onehouse.ai", store)  # opens the browser, catches the code on 127.0.0.1
+
+client = OnehouseResources(
+    account_uid="...", project_uid="...", link_uid="...", region="us-west-2",
+    token_source=oauth.FirebaseRefreshTokenSource("https://api.onehouse.ai", store),
+)
+```
+
+- With a `token_source`, `api_key`, `api_secret` and `user_uid` are not required. Calls send `Authorization: Bearer` and never the key pair or user id: external-api takes the user from the token. `link_uid` and `region` are still required, because statements that reach a data plane need them.
+- The token source refreshes 60 s before expiry and once after a 401. Refresh runs under the store's cross-process lock and re-reads the store first. Concurrent processes therefore share one rotation; presenting a rotated refresh token twice revokes the whole session.
+- `oauth.logout(base_url, store)` revokes the refresh token and deletes the session. An access token already issued stays valid until it expires, at most an hour.
+- `FileSessionStore` writes one `0600` file. The `oh` CLI keeps the refresh token in the OS keychain instead and falls back to this file.
+- The client is the static public client `oh-cli`, registered for `http://127.0.0.1/oauth/callback` on any port.
+
+## AI Gateway tokens
+
+`onehouse_python_sdk.ai_gateway` gets tokens for a data plane's AI Gateway. It uses the standard library only, and `resources` never imports it. Every call needs the VPN or the customer network.
+
+```python
+from onehouse_python_sdk import ai_gateway
+
+gateway = "https://ai-gateway-<id>.dp.onehouse.ai"
+
+# A service principal: client_credentials with its API key pair. 300 s tokens, re-minted.
+source = ai_gateway.ServicePrincipalTokenSource(gateway, api_key, api_secret)
+
+# A person: sign in once on Keycloak's `onehouse-cli` client, then refresh.
+ai_gateway.login(gateway, store)
+source = ai_gateway.KeycloakSessionTokenSource(gateway, store)
+
+token = source.get()            # send as X-Onehouse-Authorization (or Authorization on /mcp)
+token = source.get(force=True)  # after the gateway answers 401
+```
+
+- `ai_gateway.discover(gateway)` follows the gateway's own discovery chain: RFC 9728 protected-resource metadata, then RFC 8414 or OIDC metadata for the issuer it names. It checks that the issuer matches and that the audience is on the gateway's host. Nothing is derived from the hostname or the link id. A gateway with auth off raises `AuthDisabledError`.
+- The human session stores only the refresh token. The access token (7 days on that client) stays in memory and is never written to disk.
+- `ai_gateway.logout(gateway, store)` ends the Keycloak session best effort and always deletes the stored token.
+
 ### Three ways to run a command
 
 ```python
@@ -256,7 +304,91 @@ client.create_flow(
 )
 ```
 
-ACL / privilege / role / group commands aren't exposed as typed helpers yet — use `client.execute("GRANT ...")` until they land in a future release.
+#### `CREATE FLOW` — `WITH` options reference
+
+Source-specific options and advanced configs are passed via the `options` dict. All keys and values are strings.
+
+**Kafka source**
+
+| Key | Description |
+|-----|-------------|
+| `kafka.topic.name` | Name of the source Kafka topic. |
+| `kafka.startingOffsets` | `'earliest'` (default) or `'latest'`. |
+
+**S3 source**
+
+| Key | Description |
+|-----|-------------|
+| `s3.folder.uri` | `s3://bucket/prefix/` folder to ingest from. |
+| `s3.file.format` | `AVRO`, `JSON`, `CSV`, `ORC`, `PARQUET`, or `XML`. |
+| `s3.file.extension` | File extension, e.g. `'.parquet'`, `'.jsonl'`. |
+| `s3.source.bootstrap` | `'TRUE'` or `'FALSE'`. |
+| `s3.source.if_infer_fields_from_source_path` | `'TRUE'` to extract field values from path segments like `field=value`. |
+| `s3.source.fields_to_infer` | Comma-separated field names to extract from the path, e.g. `'schema,table,date'`. |
+| `s3.source.file_path_pattern` | Optional glob applied under `s3.folder.uri`. |
+| `s3.file.csv.header` | `'TRUE'` if the first row is a header. |
+| `s3.file.json.multiline` | `'TRUE'` for single-record-per-file (pretty-printed) JSON. |
+| `s3.file.xml.row.tag` | XML element that delimits one record, e.g. `'Product'`. |
+| `s3.file.xml.value.tag` | Synthetic field name for element text content with attributes (default `'_VALUE'`). |
+| `s3.file.xml.null.value` | String token treated as `null`. |
+| `s3.file.xml.ignore.namespace` | `'TRUE'` to strip namespace prefixes from element names. |
+
+**GCS source** — same as S3 with `gcs.` prefix (e.g. `gcs.folder.uri`, `gcs.file.format`, etc.).
+
+**Onehouse table source**
+
+| Key | Description |
+|-----|-------------|
+| `source.table.name` | Name of the source Onehouse table. |
+| `source.table.database` | Database containing the source table. |
+| `source.table.lake` | Lake containing the source table. |
+
+**Postgres source**
+
+| Key | Description |
+|-----|-------------|
+| `postgres.table.name` | Postgres table to ingest. |
+| `postgres.schema.name` | Postgres schema name. |
+
+**MySQL source**
+
+| Key | Description |
+|-----|-------------|
+| `mysql.table.name` | MySQL table to ingest. |
+
+**Oracle source**
+
+| Key | Description |
+|-----|-------------|
+| `oracle.table.name` | Oracle table to ingest. |
+| `oracle.schema.name` | Oracle schema (owner). |
+
+**Schema registry** (Kafka sources)
+
+| Key | Description |
+|-----|-------------|
+| `schema.registry.type` | `'glue'`, `'confluent'`, `'jar'`, or `'file'`. |
+| `schema.registry.glue.name` | Glue registry name. |
+| `schema.registry.confluent.servers` | Confluent Schema Registry URL. |
+| `schema.registry.confluent.key` | Confluent API key. |
+| `schema.registry.confluent.secret` | Confluent API secret. |
+| `schema.registry.proto.jar.location` | S3 path to the proto schema JAR. |
+| `schema.registry.file.base.path` | Base path for file-based schema registry. |
+| `schema.registry.file.full.path` | Full path to a specific schema file. |
+
+**Cross-source advanced configs**
+
+| Key | Description |
+|-----|-------------|
+| `table.configured.base.path` | Custom storage location for the table (disables Clean & Restart). |
+| `table.partition.style` | `'default'` or `'hive'`. |
+| `flow.delayThreshold.numSyncIntervals` | Multiplied by sync frequency to set the delay threshold. `'0'` disables the Delayed state. |
+| `flow.deduplicationPolicy` | `'none'` (default) or `'drop'` — deduplicates append-only flows by record key. |
+
+```python
+```
+
+Groups, grants, roles and access-control policies have typed helpers too, for example `client.create_group("data_eng")`, `client.grant_privilege("SELECT", on="TABLE", name="lake.db.table", principal_type="GROUP", principal="data_eng")`, `client.grant_member(on="GROUP", name="data_eng", principal_type="USER", principal="a@acme.com")` and `client.show_policies("my_catalog")`. Anything without a helper still works through `client.execute(...)`.
 
 #### `unsafe_raw` escape hatch
 

{onehouse_python_sdk-0.2.0 → onehouse_python_sdk-0.4.0}/README.md

@@ -142,7 +142,7 @@ print(result.api_response)      # raw API payload
 Credentials resolve from three sources, in order (highest wins):
 
 1. **Explicit constructor arguments** (shown above).
-2. **Environment variables** — `ONEHOUSE_ACCOUNT_UID`, `ONEHOUSE_PROJECT_UID`, `ONEHOUSE_API_KEY`, `ONEHOUSE_API_SECRET`, `ONEHOUSE_LINK_UID`, `ONEHOUSE_REGION`, `ONEHOUSE_USER_UID`. Optional: `ONEHOUSE_BASE_URL`, `ONEHOUSE_PROFILE`, `ONEHOUSE_CREDENTIALS_FILE`.
+2. **Environment variables** — `ONEHOUSE_ACCOUNT_UID`, `ONEHOUSE_PROJECT_UID`, `ONEHOUSE_API_KEY`, `ONEHOUSE_API_SECRET`, `ONEHOUSE_LINK_UID`, `ONEHOUSE_REGION`, `ONEHOUSE_USER_UID`. Optional: `ONEHOUSE_BASE_URL`, `ONEHOUSE_PROFILE`, `ONEHOUSE_CREDENTIALS_FILE`. `ONEHOUSE_BASE_URL` is the API host (default `https://api.onehouse.ai`); a trailing `/v1` is dropped, since every request adds it.
 3. **INI credentials file** at `~/.onehouse/credentials` (override with `ONEHOUSE_CREDENTIALS_FILE`).
 
 ```ini
@@ -170,6 +170,54 @@ client = OnehouseResources(profile="staging")
 
 Missing fields produce an `AuthError` listing which fields are unset and how to supply them. A world-readable credentials file triggers a warning — `chmod 600 ~/.onehouse/credentials`.
 
+### OAuth sign-in instead of an API key
+
+A person can sign in through the browser instead of holding an API key. external-api runs an OAuth 2.1 authorization server (authorization code + PKCE). Its access token is a Firebase ID token for the signed-in user and lasts an hour. Its refresh token rotates on every use and lasts 30 days. The org must have `enable_external_api_bearer_auth` on.
+
+```python
+from pathlib import Path
+from onehouse_python_sdk._session import FileSessionStore
+from onehouse_python_sdk.resources import oauth
+
+store = FileSessionStore(Path.home() / ".onehouse" / "session.json")
+oauth.login("https://api.onehouse.ai", store)  # opens the browser, catches the code on 127.0.0.1
+
+client = OnehouseResources(
+    account_uid="...", project_uid="...", link_uid="...", region="us-west-2",
+    token_source=oauth.FirebaseRefreshTokenSource("https://api.onehouse.ai", store),
+)
+```
+
+- With a `token_source`, `api_key`, `api_secret` and `user_uid` are not required. Calls send `Authorization: Bearer` and never the key pair or user id: external-api takes the user from the token. `link_uid` and `region` are still required, because statements that reach a data plane need them.
+- The token source refreshes 60 s before expiry and once after a 401. Refresh runs under the store's cross-process lock and re-reads the store first. Concurrent processes therefore share one rotation; presenting a rotated refresh token twice revokes the whole session.
+- `oauth.logout(base_url, store)` revokes the refresh token and deletes the session. An access token already issued stays valid until it expires, at most an hour.
+- `FileSessionStore` writes one `0600` file. The `oh` CLI keeps the refresh token in the OS keychain instead and falls back to this file.
+- The client is the static public client `oh-cli`, registered for `http://127.0.0.1/oauth/callback` on any port.
+
+## AI Gateway tokens
+
+`onehouse_python_sdk.ai_gateway` gets tokens for a data plane's AI Gateway. It uses the standard library only, and `resources` never imports it. Every call needs the VPN or the customer network.
+
+```python
+from onehouse_python_sdk import ai_gateway
+
+gateway = "https://ai-gateway-<id>.dp.onehouse.ai"
+
+# A service principal: client_credentials with its API key pair. 300 s tokens, re-minted.
+source = ai_gateway.ServicePrincipalTokenSource(gateway, api_key, api_secret)
+
+# A person: sign in once on Keycloak's `onehouse-cli` client, then refresh.
+ai_gateway.login(gateway, store)
+source = ai_gateway.KeycloakSessionTokenSource(gateway, store)
+
+token = source.get()            # send as X-Onehouse-Authorization (or Authorization on /mcp)
+token = source.get(force=True)  # after the gateway answers 401
+```
+
+- `ai_gateway.discover(gateway)` follows the gateway's own discovery chain: RFC 9728 protected-resource metadata, then RFC 8414 or OIDC metadata for the issuer it names. It checks that the issuer matches and that the audience is on the gateway's host. Nothing is derived from the hostname or the link id. A gateway with auth off raises `AuthDisabledError`.
+- The human session stores only the refresh token. The access token (7 days on that client) stays in memory and is never written to disk.
+- `ai_gateway.logout(gateway, store)` ends the Keycloak session best effort and always deletes the stored token.
+
 ### Three ways to run a command
 
 ```python
@@ -224,7 +272,91 @@ client.create_flow(
 )
 ```
 
-ACL / privilege / role / group commands aren't exposed as typed helpers yet — use `client.execute("GRANT ...")` until they land in a future release.
+#### `CREATE FLOW` — `WITH` options reference
+
+Source-specific options and advanced configs are passed via the `options` dict. All keys and values are strings.
+
+**Kafka source**
+
+| Key | Description |
+|-----|-------------|
+| `kafka.topic.name` | Name of the source Kafka topic. |
+| `kafka.startingOffsets` | `'earliest'` (default) or `'latest'`. |
+
+**S3 source**
+
+| Key | Description |
+|-----|-------------|
+| `s3.folder.uri` | `s3://bucket/prefix/` folder to ingest from. |
+| `s3.file.format` | `AVRO`, `JSON`, `CSV`, `ORC`, `PARQUET`, or `XML`. |
+| `s3.file.extension` | File extension, e.g. `'.parquet'`, `'.jsonl'`. |
+| `s3.source.bootstrap` | `'TRUE'` or `'FALSE'`. |
+| `s3.source.if_infer_fields_from_source_path` | `'TRUE'` to extract field values from path segments like `field=value`. |
+| `s3.source.fields_to_infer` | Comma-separated field names to extract from the path, e.g. `'schema,table,date'`. |
+| `s3.source.file_path_pattern` | Optional glob applied under `s3.folder.uri`. |
+| `s3.file.csv.header` | `'TRUE'` if the first row is a header. |
+| `s3.file.json.multiline` | `'TRUE'` for single-record-per-file (pretty-printed) JSON. |
+| `s3.file.xml.row.tag` | XML element that delimits one record, e.g. `'Product'`. |
+| `s3.file.xml.value.tag` | Synthetic field name for element text content with attributes (default `'_VALUE'`). |
+| `s3.file.xml.null.value` | String token treated as `null`. |
+| `s3.file.xml.ignore.namespace` | `'TRUE'` to strip namespace prefixes from element names. |
+
+**GCS source** — same as S3 with `gcs.` prefix (e.g. `gcs.folder.uri`, `gcs.file.format`, etc.).
+
+**Onehouse table source**
+
+| Key | Description |
+|-----|-------------|
+| `source.table.name` | Name of the source Onehouse table. |
+| `source.table.database` | Database containing the source table. |
+| `source.table.lake` | Lake containing the source table. |
+
+**Postgres source**
+
+| Key | Description |
+|-----|-------------|
+| `postgres.table.name` | Postgres table to ingest. |
+| `postgres.schema.name` | Postgres schema name. |
+
+**MySQL source**
+
+| Key | Description |
+|-----|-------------|
+| `mysql.table.name` | MySQL table to ingest. |
+
+**Oracle source**
+
+| Key | Description |
+|-----|-------------|
+| `oracle.table.name` | Oracle table to ingest. |
+| `oracle.schema.name` | Oracle schema (owner). |
+
+**Schema registry** (Kafka sources)
+
+| Key | Description |
+|-----|-------------|
+| `schema.registry.type` | `'glue'`, `'confluent'`, `'jar'`, or `'file'`. |
+| `schema.registry.glue.name` | Glue registry name. |
+| `schema.registry.confluent.servers` | Confluent Schema Registry URL. |
+| `schema.registry.confluent.key` | Confluent API key. |
+| `schema.registry.confluent.secret` | Confluent API secret. |
+| `schema.registry.proto.jar.location` | S3 path to the proto schema JAR. |
+| `schema.registry.file.base.path` | Base path for file-based schema registry. |
+| `schema.registry.file.full.path` | Full path to a specific schema file. |
+
+**Cross-source advanced configs**
+
+| Key | Description |
+|-----|-------------|
+| `table.configured.base.path` | Custom storage location for the table (disables Clean & Restart). |
+| `table.partition.style` | `'default'` or `'hive'`. |
+| `flow.delayThreshold.numSyncIntervals` | Multiplied by sync frequency to set the delay threshold. `'0'` disables the Delayed state. |
+| `flow.deduplicationPolicy` | `'none'` (default) or `'drop'` — deduplicates append-only flows by record key. |
+
+```python
+```
+
+Groups, grants, roles and access-control policies have typed helpers too, for example `client.create_group("data_eng")`, `client.grant_privilege("SELECT", on="TABLE", name="lake.db.table", principal_type="GROUP", principal="data_eng")`, `client.grant_member(on="GROUP", name="data_eng", principal_type="USER", principal="a@acme.com")` and `client.show_policies("my_catalog")`. Anything without a helper still works through `client.execute(...)`.
 
 #### `unsafe_raw` escape hatch
 

{onehouse_python_sdk-0.2.0 → onehouse_python_sdk-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "onehouse-python-sdk"
-version = "0.2.0"
+version = "0.4.0"
 description = "Onehouse Python SDK — modular data-plane clients for LakeBase and beyond"
 readme = "README.md"
 license = { text = "Proprietary" }

{onehouse_python_sdk-0.2.0 → onehouse_python_sdk-0.4.0}/src/onehouse_python_sdk/__init__.py

@@ -6,4 +6,4 @@ from .lakebase.client import LakebaseClient
 from .resources.client import OnehouseResources
 
 __all__ = ["SqlClient", "LakebaseClient", "OnehouseResources", "exceptions"]
-__version__ = "0.1.0"
+__version__ = "0.4.0"

onehouse_python_sdk-0.4.0/src/onehouse_python_sdk/_oauth.py

@@ -0,0 +1,293 @@
+"""Loopback PKCE sign-in and token-endpoint calls, shared by every OAuth login.
+
+Standard library only, and outside every subsystem, so both the control-plane
+login (``resources.oauth``, external-api's OAuth server) and the data-plane
+AI-Gateway login (``ai_gateway``, Keycloak) use it without importing each other.
+
+The browser only ever carries an authorization code, which is worthless
+without the PKCE verifier that never leaves this process (RFC 7636, RFC 8252).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import json
+import secrets
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from dataclasses import dataclass
+from typing import Callable, Mapping, Optional
+
+from .exceptions import OnehouseSdkError
+
+LOGIN_TIMEOUT_SECONDS = 300
+_HTTP_TIMEOUT_SECONDS = 20
+
+_DONE_PAGE = b"""<!doctype html><meta charset="utf-8"><title>Onehouse</title>
+<body style="font:16px system-ui;padding:3rem;max-width:32rem">
+<h2>Signed in</h2><p>You can close this tab and return to your terminal.</p></body>"""
+
+_FAILED_PAGE = b"""<!doctype html><meta charset="utf-8"><title>Onehouse</title>
+<body style="font:16px system-ui;padding:3rem;max-width:32rem">
+<h2>Sign-in did not complete</h2><p>Return to your terminal for the reason.</p></body>"""
+
+
+class OAuthFlowError(OnehouseSdkError):
+    """A sign-in or token-endpoint call did not produce a usable token."""
+
+
+@dataclass(frozen=True)
+class AuthorizationResult:
+    """What the browser step returns: redeem ``code`` with ``verifier`` at the same
+    ``redirect_uri``, byte for byte."""
+
+    code: str
+    redirect_uri: str
+    verifier: str
+    iss: Optional[str] = None
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def new_verifier() -> str:
+    """43 characters of base64url (RFC 7636 4.1)."""
+    return _b64url(secrets.token_bytes(32))
+
+
+def challenge_for(verifier: str) -> str:
+    """S256 only: ``plain`` would put the verifier in the browser's history."""
+    return _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+
+
+def default_ssl_context() -> ssl.SSLContext:
+    """The OS trust store when ``truststore`` is installed, so a TLS-intercepting
+    corporate proxy's CA is trusted; then certifi; then Python's defaults.
+    The same order as ``lakebase.auth._ssl``, which this module may not import."""
+    try:
+        import truststore
+
+        return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    except ImportError:
+        pass
+    try:
+        import certifi
+
+        return ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        return ssl.create_default_context()
+
+
+class _Catcher(http.server.BaseHTTPRequestHandler):
+    """Serves one useful request: the authorization server's redirect back."""
+
+    callback_path = ""
+    expected_state = ""
+    result: dict = {}
+    # A connection that sends nothing (a browser preconnect, a port scan) would
+    # otherwise block handle_request() past the login deadline.
+    timeout = 5
+
+    def do_GET(self) -> None:  # noqa: N802 - name fixed by BaseHTTPRequestHandler
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != type(self).callback_path:
+            self.send_response(404)
+            self.end_headers()
+            return
+        params = urllib.parse.parse_qs(parsed.query)
+        # State before anything else: a callback this process did not start is not
+        # ours to act on, and must not end the wait.
+        got_state = (params.get("state") or [""])[0]
+        if not secrets.compare_digest(got_state, type(self).expected_state):
+            self._respond(400, _FAILED_PAGE)
+            return
+        error = (params.get("error") or [""])[0]
+        if error:
+            description = (params.get("error_description") or [""])[0]
+            type(self).result = {"error": f"{error}: {description}" if description else error}
+            self._respond(400, _FAILED_PAGE)
+            return
+        code = (params.get("code") or [""])[0]
+        if not code:
+            type(self).result = {"error": "the authorization server returned no code"}
+            self._respond(400, _FAILED_PAGE)
+            return
+        type(self).result = {"code": code, "iss": (params.get("iss") or [None])[0]}
+        self._respond(200, _DONE_PAGE)
+
+    def _respond(self, status: int, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *_args) -> None:
+        """The default access log would print the callback URL, code included."""
+
+
+class LoopbackServer:
+    """A one-shot HTTP server on 127.0.0.1, on an OS-chosen port unless one is given.
+
+    127.0.0.1, never ``localhost``: redirect matching is byte for byte, and
+    ``localhost`` resolves through DNS (RFC 8252 7.3, 8.3).
+    """
+
+    def __init__(self, callback_path: str, state: str, port: int = 0) -> None:
+        self._callback_path = callback_path
+        self._handler = type(
+            "_Bound",
+            (_Catcher,),
+            {"callback_path": callback_path, "expected_state": state, "result": {}},
+        )
+        self._httpd = http.server.HTTPServer(("127.0.0.1", port), self._handler)
+        self._httpd.timeout = 0.5
+
+    @property
+    def port(self) -> int:
+        return self._httpd.server_address[1]
+
+    @property
+    def redirect_uri(self) -> str:
+        return f"http://127.0.0.1:{self.port}{self._callback_path}"
+
+    def wait(self, timeout: float) -> dict:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            try:
+                self._httpd.handle_request()
+            except OSError:
+                # A connection that timed out or reset mid-read is not an outcome.
+                continue
+            if self._handler.result:
+                return self._handler.result
+        return {"error": f"timed out after {int(timeout)}s waiting for the browser"}
+
+    def close(self) -> None:
+        self._httpd.server_close()
+
+
+def authorize(
+    authorization_endpoint: str,
+    *,
+    client_id: str,
+    callback_path: str,
+    scope: Optional[str] = None,
+    extra_params: Optional[Mapping[str, str]] = None,
+    open_browser: Callable[[str], object] = webbrowser.open,
+    announce: Callable[[str], None] = print,
+    timeout: float = LOGIN_TIMEOUT_SECONDS,
+    port: int = 0,
+) -> AuthorizationResult:
+    """Run the browser step of an authorization-code + PKCE sign-in.
+
+    ``port`` pins the loopback port, which only an SSH forward needs: the tunnel
+    must name a port before the sign-in starts.
+    """
+    verifier = new_verifier()
+    state = _b64url(secrets.token_bytes(16))
+    try:
+        server = LoopbackServer(callback_path, state, port)
+    except OSError as err:
+        where = f"port {port}" if port else "a local port"
+        raise OAuthFlowError(f"could not bind {where} for the sign-in ({err})") from err
+    try:
+        params = {
+            "response_type": "code",
+            "client_id": client_id,
+            "redirect_uri": server.redirect_uri,
+            "state": state,
+            "code_challenge": challenge_for(verifier),
+            "code_challenge_method": "S256",
+        }
+        if scope:
+            params["scope"] = scope
+        params.update(extra_params or {})
+        separator = "&" if "?" in authorization_endpoint else "?"
+        url = f"{authorization_endpoint}{separator}{urllib.parse.urlencode(params)}"
+        announce(f"Opening your browser to sign in.\nIf it does not open, visit:\n  {url}")
+        open_browser(url)
+        outcome = server.wait(timeout)
+        redirect_uri = server.redirect_uri
+    finally:
+        server.close()
+    if "error" in outcome:
+        raise OAuthFlowError(outcome["error"])
+    return AuthorizationResult(
+        code=outcome["code"], redirect_uri=redirect_uri, verifier=verifier, iss=outcome.get("iss")
+    )
+
+
+@dataclass(frozen=True)
+class HttpResult:
+    status: int
+    body: dict
+
+
+def _read_json(raw: bytes) -> dict:
+    try:
+        parsed = json.loads(raw.decode("utf-8")) if raw else {}
+    except (ValueError, UnicodeDecodeError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _send(request: urllib.request.Request, timeout: float) -> HttpResult:
+    try:
+        with urllib.request.urlopen(
+            request, timeout=timeout, context=default_ssl_context()
+        ) as resp:
+            return HttpResult(resp.status, _read_json(resp.read()))
+    except urllib.error.HTTPError as err:
+        # An OAuth error response is a 4xx with a JSON body worth reading.
+        return HttpResult(err.code, _read_json(err.read()))
+    except (urllib.error.URLError, OSError) as err:
+        raise OAuthFlowError(f"could not reach {request.full_url} ({err})") from err
+
+
+def post_form(url: str, data: Mapping[str, str], timeout: float = _HTTP_TIMEOUT_SECONDS) -> HttpResult:
+    """POST ``application/x-www-form-urlencoded``, as every token endpoint takes it."""
+    request = urllib.request.Request(
+        url,
+        data=urllib.parse.urlencode(dict(data)).encode("ascii"),
+        headers={
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        },
+        method="POST",
+    )
+    return _send(request, timeout)
+
+
+def get_json(url: str, timeout: float = _HTTP_TIMEOUT_SECONDS) -> HttpResult:
+    request = urllib.request.Request(url, headers={"Accept": "application/json"}, method="GET")
+    return _send(request, timeout)
+
+
+def oauth_error(result: HttpResult) -> str:
+    """The RFC 6749 5.2 ``error`` code of a failed call, or its HTTP status."""
+    error = result.body.get("error")
+    return str(error) if error else f"HTTP {result.status}"
+
+
+__all__ = [
+    "LOGIN_TIMEOUT_SECONDS",
+    "AuthorizationResult",
+    "HttpResult",
+    "LoopbackServer",
+    "OAuthFlowError",
+    "authorize",
+    "challenge_for",
+    "default_ssl_context",
+    "get_json",
+    "new_verifier",
+    "oauth_error",
+    "post_form",
+]