mkctl 0.4.0__py3-none-any.whl

mkctl/oauth.py

@@ -0,0 +1,398 @@
+"""The two flows a native application is allowed to use, and nothing else.
+
+**Authorization code with PKCE over a loopback redirect** (RFC 8252 §7.3, RFC 7636)
+is the default. It is what the OAuth native-app BCP asks for when the machine has a
+browser: the client holds no secret, and the `code_verifier` binds the code to the
+process that asked for it, so a code intercepted on its way back is useless.
+
+**The device authorization grant** (RFC 8628) is the fallback, for the case the
+loopback flow cannot serve: a terminal over SSH, a container, a machine with no
+browser. The human authorizes on a device that does have one.
+
+PKCE applies to the first and not to the second, and that is not an omission. PKCE
+protects a redirect from interception; the device grant has no redirect and no code
+travelling back through the user agent — the `device_code` goes straight to the
+polling client over TLS. There is no `code_challenge` parameter in a device
+authorization request. See ADR 0004 Amendment 2.
+
+Neither flow uses a client secret. A secret shipped inside a CLI is a public value
+with a misleading name (RFC 8252 §8.5).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import secrets
+import socketserver
+import threading
+import time
+import urllib.parse
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+
+# RFC 8628 §3.5. `slow_down` means add at least five seconds to the interval.
+SLOW_DOWN_INCREMENT = 5
+DEFAULT_INTERVAL = 5
+
+
+class AuthorizationError(Exception):
+    """The human did not authorize, or the provider refused."""
+
+
+@dataclass(frozen=True)
+class Tokens:
+    access_token: str
+    refresh_token: str | None
+    expires_at: float
+    scope: str | None = None
+
+    @property
+    def expired(self) -> bool:
+        # A minute of slack: a token that expires mid-request is a failure the user
+        # sees, and refreshing slightly early costs nothing.
+        return time.time() >= self.expires_at - 60
+
+
+@dataclass(frozen=True)
+class Endpoints:
+    """Read from the provider's discovery document rather than configured.
+
+    Hard-coding paths means an IdP change is a code change, which is the coupling
+    ADR 0004 spent an adapter to avoid.
+    """
+
+    issuer: str
+    authorization: str
+    token: str
+    device_authorization: str | None
+    revocation: str | None
+
+    @classmethod
+    def discover(cls, issuer: str, *, client: httpx.Client | None = None) -> Endpoints:
+        http_client = client or httpx.Client(timeout=10)
+        document = (
+            http_client.get(f"{issuer.rstrip('/')}/.well-known/openid-configuration")
+            .raise_for_status()
+            .json()
+        )
+        return cls(
+            issuer=document["issuer"],
+            authorization=document["authorization_endpoint"],
+            token=document["token_endpoint"],
+            device_authorization=document.get("device_authorization_endpoint"),
+            revocation=document.get("revocation_endpoint"),
+        )
+
+
+def _pkce() -> tuple[str, str]:
+    """A verifier and its S256 challenge (RFC 7636 sections 4.1 and 4.2)."""
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    challenge = (
+        base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    )
+    return verifier, challenge
+
+
+def _tokens_from(payload: dict[str, Any]) -> Tokens:
+    return Tokens(
+        access_token=payload["access_token"],
+        refresh_token=payload.get("refresh_token"),
+        expires_at=time.time() + int(payload.get("expires_in", 300)),
+        scope=payload.get("scope"),
+    )
+
+
+class _AuthorizationCallbackServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
+    """Single-use loopback endpoint for the OAuth authorization response (RFC 8252 §7.3).
+
+    Exactly one path is registered as `redirect_uri` (`/callback`). The authorization
+    response is the query on that path (`code` + `state`, or `error`). The server records
+    the first valid response and signals completion; the listen socket is closed by the
+    waiting client after that. Non-callback requests are not an authorization response
+    and must not be treated as one (or as a reason to discard one already received).
+    """
+
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._lock = threading.Lock()
+        self.authorization_response: dict[str, str] | None = None
+        self.completed = threading.Event()
+
+    def accept_authorization_response(self, params: dict[str, str]) -> bool:
+        """Store the first authorization response. Returns whether this call stored it."""
+        with self._lock:
+            if self.authorization_response is not None:
+                return False
+            self.authorization_response = params
+            self.completed.set()
+            return True
+
+
+class _AuthorizationCallbackHandler(http.server.BaseHTTPRequestHandler):
+    """HTTP handler for `redirect_uri` only."""
+
+    server: _AuthorizationCallbackServer
+
+    def do_GET(self) -> None:  # http.server's interface, not our naming
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_error(404, "Not Found")
+            return
+
+        params = {k: v[0] for k, v in urllib.parse.parse_qs(parsed.query).items()}
+        if "code" not in params and "error" not in params:
+            self.send_error(400, "Expected an OAuth authorization response")
+            return
+
+        self.server.accept_authorization_response(params)
+        body = b"<html><body><p>Signed in. You can close this tab.</p></body></html>"
+        self.send_response(200)
+        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: object) -> None:
+        return
+
+
+def login_loopback(
+    endpoints: Endpoints,
+    client_id: str,
+    *,
+    scope: str = "openid profile email offline_access",
+    open_browser: bool = True,
+    timeout: float = 300,
+    client: httpx.Client | None = None,
+) -> Tokens:
+    """Authorization code with PKCE, redirected to a loopback address.
+
+    The listener binds to 127.0.0.1 on a port the OS picks (RFC 8252 §7.3 requires
+    the loopback interface and requires the provider to accept any port). `state` is
+    checked because a redirect is a request anything on this machine could make.
+    """
+    verifier, challenge = _pkce()
+    state = secrets.token_urlsafe(16)
+
+    server = _AuthorizationCallbackServer(("127.0.0.1", 0), _AuthorizationCallbackHandler)
+    redirect_uri = f"http://127.0.0.1:{server.server_port}/callback"
+
+    query = urllib.parse.urlencode(
+        {
+            "client_id": client_id,
+            "response_type": "code",
+            "redirect_uri": redirect_uri,
+            "scope": scope,
+            "state": state,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+        }
+    )
+    url = f"{endpoints.authorization}?{query}"
+
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        if open_browser:
+            webbrowser.open(url)
+        print(f"Opening {url}")
+        print(f"Waiting for authorization redirect to {redirect_uri}")
+        if not server.completed.wait(timeout=timeout):
+            raise AuthorizationError("timed out waiting for the browser to come back")
+    finally:
+        # Always free the port — including when the human hits Ctrl+C mid-wait.
+        server.shutdown()
+        server.server_close()
+
+    result = server.authorization_response
+    if not result:
+        raise AuthorizationError("timed out waiting for the browser to come back")
+    if "error" in result:
+        raise AuthorizationError(result.get("error_description") or result["error"])
+    if result.get("state") != state:
+        # Not a formality: without it any page on this machine could hand us a code.
+        raise AuthorizationError("state did not match the request")
+    if not result.get("code"):
+        raise AuthorizationError("authorization response carried no code")
+
+    print("Exchanging authorization code for tokens")
+    http_client = client or httpx.Client(timeout=30)
+    response = http_client.post(
+        endpoints.token,
+        data={
+            "grant_type": "authorization_code",
+            "code": result["code"],
+            "redirect_uri": redirect_uri,
+            "client_id": client_id,
+            "code_verifier": verifier,
+        },
+    )
+    if response.status_code != 200:
+        raise AuthorizationError(_describe(response))
+    return _tokens_from(response.json())
+
+
+@dataclass(frozen=True)
+class DeviceChallenge:
+    """What the human has to be shown, and how long they have."""
+
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str | None
+    expires_in: int
+
+
+def start_device(
+    endpoints: Endpoints,
+    client_id: str,
+    *,
+    scope: str = "openid profile email offline_access",
+    client: httpx.Client | None = None,
+) -> tuple[str, DeviceChallenge, int]:
+    if not endpoints.device_authorization:
+        raise AuthorizationError(
+            "this provider publishes no device_authorization_endpoint; use the default browser flow"
+        )
+    http_client = client or httpx.Client(timeout=30)
+    response = http_client.post(
+        endpoints.device_authorization, data={"client_id": client_id, "scope": scope}
+    )
+    if response.status_code != 200:
+        raise AuthorizationError(_describe(response))
+    payload = response.json()
+    challenge = DeviceChallenge(
+        user_code=payload["user_code"],
+        verification_uri=payload["verification_uri"],
+        verification_uri_complete=payload.get("verification_uri_complete"),
+        expires_in=int(payload.get("expires_in", 600)),
+    )
+    return payload["device_code"], challenge, int(payload.get("interval", DEFAULT_INTERVAL))
+
+
+def poll_device(
+    endpoints: Endpoints,
+    client_id: str,
+    device_code: str,
+    *,
+    interval: int = DEFAULT_INTERVAL,
+    expires_in: int = 600,
+    client: httpx.Client | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Tokens:
+    """Poll until the human decides, honouring what the provider asks for.
+
+    `slow_down` adds to the interval and is not a retry-immediately (RFC 8628 §3.5);
+    ignoring it is how a client gets rate-limited into failing a flow that would
+    otherwise have worked.
+    """
+    http_client = client or httpx.Client(timeout=30)
+    deadline = time.time() + expires_in
+
+    while True:
+        if time.time() >= deadline:
+            raise AuthorizationError("the device code expired before it was approved")
+        sleep(interval)
+        response = http_client.post(
+            endpoints.token,
+            data={"grant_type": DEVICE_GRANT, "device_code": device_code, "client_id": client_id},
+        )
+        if response.status_code == 200:
+            return _tokens_from(response.json())
+
+        error = _error_of(response)
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += SLOW_DOWN_INCREMENT
+            continue
+        if error == "access_denied":
+            raise AuthorizationError("the request was denied")
+        if error == "expired_token":
+            raise AuthorizationError("the device code expired before it was approved")
+        raise AuthorizationError(_describe(response))
+
+
+def refresh(
+    endpoints: Endpoints,
+    client_id: str,
+    refresh_token: str,
+    *,
+    client: httpx.Client | None = None,
+) -> Tokens:
+    """Exchange a refresh token, and expect a new one back.
+
+    Rotation is the provider's job; ours is to store what comes back rather than
+    keeping the token we sent. A client that keeps the old one turns the provider's
+    single-use enforcement into a login loop the day it is switched on.
+    """
+    http_client = client or httpx.Client(timeout=30)
+    response = http_client.post(
+        endpoints.token,
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+        },
+    )
+    if response.status_code != 200:
+        raise AuthorizationError(_describe(response))
+    payload = response.json()
+    tokens = _tokens_from(payload)
+    if tokens.refresh_token is None:
+        # The provider rotated nothing; keep what still works rather than losing it.
+        tokens = Tokens(
+            access_token=tokens.access_token,
+            refresh_token=refresh_token,
+            expires_at=tokens.expires_at,
+            scope=tokens.scope,
+        )
+    return tokens
+
+
+def revoke(
+    endpoints: Endpoints,
+    client_id: str,
+    token: str,
+    *,
+    client: httpx.Client | None = None,
+) -> bool:
+    """Tell the provider to forget this device's token.
+
+    "Revocable per device" (ADR 0004) is only true if logging out actually revokes.
+    Deleting the local copy would leave a live refresh token behind on a laptop
+    somebody just handed back.
+    """
+    if not endpoints.revocation:
+        return False
+    http_client = client or httpx.Client(timeout=30)
+    response = http_client.post(
+        endpoints.revocation,
+        data={"token": token, "token_type_hint": "refresh_token", "client_id": client_id},
+    )
+    return response.status_code in (200, 204)
+
+
+def _error_of(response: httpx.Response) -> str | None:
+    try:
+        return response.json().get("error")
+    except ValueError:
+        return None
+
+
+def _describe(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+        return payload.get("error_description") or payload.get("error") or response.text
+    except ValueError:
+        return f"HTTP {response.status_code}"

mkctl/session.py

@@ -0,0 +1,104 @@
+"""Holding a login: acquiring, refreshing, and giving it up.
+
+The one rule worth stating: whatever comes back from a refresh is what gets stored.
+Providers rotate refresh tokens and enforce single use, so a client that keeps the
+token it just sent turns that enforcement into a login loop on the day it is switched
+on — and the failure looks like the provider misbehaving.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from . import oauth
+from .oauth import AuthorizationError, Endpoints, Tokens
+from .store import TokenStore
+
+
+@dataclass
+class Session:
+    control_plane: str
+    issuer: str
+    client_id: str
+    store: TokenStore
+    client: httpx.Client | None = None
+
+    def endpoints(self) -> Endpoints:
+        return Endpoints.discover(self.issuer, client=self.client)
+
+    def login(self, *, device: bool = False, open_browser: bool = True) -> Tokens:
+        """Acquire a login and store it.
+
+        The browser flow is the default because it is what the native-app BCP asks
+        for when a browser is present. `device=True` is for when it is not, which is
+        every terminal reached over SSH.
+        """
+        endpoints = self.endpoints()
+        if device:
+            tokens = self._device_login(endpoints)
+        else:
+            tokens = oauth.login_loopback(
+                endpoints,
+                self.client_id,
+                open_browser=open_browser,
+                client=self.client,
+            )
+        self.store.save(tokens)
+        return tokens
+
+    def _device_login(self, endpoints: Endpoints) -> Tokens:
+        device_code, challenge, interval = oauth.start_device(
+            endpoints, self.client_id, client=self.client
+        )
+        target = challenge.verification_uri_complete or challenge.verification_uri
+        print(f"Open {target}")
+        if not challenge.verification_uri_complete:
+            print(f"and enter the code: {challenge.user_code}")
+        return oauth.poll_device(
+            endpoints,
+            self.client_id,
+            device_code,
+            interval=interval,
+            expires_in=challenge.expires_in,
+            client=self.client,
+        )
+
+    def access_token(self) -> str:
+        """A usable access token, refreshed if it is due.
+
+        Raises rather than silently returning nothing: a caller that gets `None` here
+        writes `Authorization: Bearer None`, and the server's answer to that is the
+        same 401 as a real credential failure — a confusing way to learn you are
+        logged out.
+        """
+        tokens = self.store.load()
+        if tokens is None:
+            raise AuthorizationError("not logged in — run `mkctl login`")
+        if not tokens.expired:
+            return tokens.access_token
+        if not tokens.refresh_token:
+            raise AuthorizationError("the session expired and cannot be refreshed — log in again")
+
+        refreshed = oauth.refresh(
+            self.endpoints(), self.client_id, tokens.refresh_token, client=self.client
+        )
+        self.store.save(refreshed)
+        return refreshed.access_token
+
+    def logout(self) -> bool:
+        """Revoke at the provider, then forget locally.
+
+        In that order, and both. Deleting only the local copy leaves a live refresh
+        token on a machine somebody may have just handed back, which is the opposite
+        of "revocable per device".
+        """
+        tokens = self.store.load()
+        revoked = False
+        if tokens and tokens.refresh_token:
+            revoked = oauth.revoke(
+                self.endpoints(), self.client_id, tokens.refresh_token, client=self.client
+            )
+        self.store.clear()
+        return revoked

mkctl/store.py

@@ -0,0 +1,90 @@
+"""Where the tokens live.
+
+> Tokens in the OS keyring — ADR 0004
+
+So: the OS keyring, and no second place. If there is no secure backend, this raises
+and says what to do about it rather than quietly writing a file. A CLI that degrades
+to plaintext when the keyring is missing is `nate`'s `TOKEN_ENCRYPTION_KEY` again —
+the safe path must not be the one that happens to be configured.
+
+One entry per control plane, keyed by its URL, so a laptop that talks to production
+and to a local stack does not have one token overwrite the other.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Protocol
+
+from .oauth import Tokens
+
+SERVICE = "mkctl"
+
+
+class KeyringBackend(Protocol):
+    # Positional-only, because the real keyring backend decorates `set_password`
+    # into a wrapper whose parameter names are not the interface's.
+    def get_password(self, service: str, username: str, /) -> str | None: ...
+    def set_password(self, service: str, username: str, password: str, /) -> None: ...
+    def delete_password(self, service: str, username: str, /) -> None: ...
+
+
+class StoreUnavailable(Exception):
+    """There is no secure place to put a token on this machine."""
+
+
+@dataclass
+class TokenStore:
+    control_plane: str
+    backend: KeyringBackend | None = None
+
+    def _keyring(self) -> KeyringBackend:
+        if self.backend is not None:
+            return self.backend
+        import keyring
+        from keyring.backends.fail import Keyring as FailKeyring
+
+        backend = keyring.get_keyring()
+        if isinstance(backend, FailKeyring):
+            raise StoreUnavailable(
+                "no OS keyring is available on this machine, and mkctl does not write "
+                "tokens to disk (ADR 0004). Install and start a Secret Service provider "
+                "— gnome-keyring or kwallet on Linux — and try again"
+            )
+        return backend
+
+    def load(self) -> Tokens | None:
+        raw = self._keyring().get_password(SERVICE, self.control_plane)
+        if not raw:
+            return None
+        payload = json.loads(raw)
+        return Tokens(
+            access_token=payload["access_token"],
+            refresh_token=payload.get("refresh_token"),
+            expires_at=payload["expires_at"],
+            scope=payload.get("scope"),
+        )
+
+    def save(self, tokens: Tokens) -> None:
+        self._keyring().set_password(
+            SERVICE,
+            self.control_plane,
+            json.dumps(
+                {
+                    "access_token": tokens.access_token,
+                    "refresh_token": tokens.refresh_token,
+                    "expires_at": tokens.expires_at,
+                    "scope": tokens.scope,
+                }
+            ),
+        )
+
+    def clear(self) -> None:
+        # Broad on purpose: backends raise different things for "no such entry", and
+        # for a logout that is success. The only outcome that matters is that nothing
+        # is left behind.
+        try:
+            self._keyring().delete_password(SERVICE, self.control_plane)
+        except Exception:
+            return

mkctl-0.4.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: mkctl
+Version: 0.4.0
+Summary: The command line for the control plane (ADR 0004)
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: <3.14,>=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: mkp-contracts>=0.2.0

mkctl-0.4.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+mkctl/__init__.py,sha256=NJPyKC8AaLjOktbJ-9kQgXY8u8xKve4fUscqEyHVONo,305
+mkctl/cli.py,sha256=5rjpDuSP1KAwYIt35nf2ZXKIXJWa4ITRAu0DVID3Zts,20212
+mkctl/client.py,sha256=uCsfjRK9p3tbtoSmvowC7iIlSEuj0NYpxshUqZ1nErI,5219
+mkctl/commands.py,sha256=RjFcBootuUzL4iNvJ2_f7pZGs5pGZMpmMlfg7m44CY4,21040
+mkctl/config.py,sha256=84wZRwn9w2In_zFtPytyPy3p_mDUYjyxo4qgjRsiQRQ,2251
+mkctl/oauth.py,sha256=CTnsaTp0HOrLZ-kiomzJqcMZDlNK4st_On1K-7bj9bY,14078
+mkctl/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkctl/session.py,sha256=J4sj2T1nNw_0DDK5HMuo8-KUYb5YZpxz5oArIJsFnTk,3724
+mkctl/store.py,sha256=Gsrw4nrI3cCKpv3ylluY-YyQUMIN6bPnOr-i5Yc67nY,3138
+mkctl-0.4.0.dist-info/METADATA,sha256=qUB3k2iRzHGilcGyOGeo2AsEPQcGJyTV733pyMZ3K-8,283
+mkctl-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mkctl-0.4.0.dist-info/entry_points.txt,sha256=6eZOnaohy6orNkfGb_1ZjQyrOkZjJ4Y-pfYkX3yNjv4,41
+mkctl-0.4.0.dist-info/licenses/LICENSE,sha256=OomESGL67ZXotKqNbTv84ga2xAp3zho0QQH_kjVDTxQ,11338
+mkctl-0.4.0.dist-info/RECORD,,

mkctl-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mkctl-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mkctl = mkctl.cli:main