zenture 1.0.1__py3-none-any.whl

zenture/__init__.py

@@ -0,0 +1,9 @@
+"""Official Python SDK package for the zenture Public API."""
+
+from __future__ import annotations
+
+from zenture._version import __version__
+from zenture.async_client import AsyncZentureClient
+from zenture.client import ZentureClient
+
+__all__ = ("AsyncZentureClient", "ZentureClient", "__version__")

zenture/_auth/__init__.py

@@ -0,0 +1 @@
+"""Internal native authorization core."""

zenture/_auth/browser.py

@@ -0,0 +1,262 @@
+"""RFC 8252 loopback browser authorization (Authorization Code + PKCE S256)."""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import hashlib
+import hmac
+import secrets
+import select
+import socket
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from urllib.parse import parse_qs, quote, urlsplit
+
+from zenture._auth.errors import AuthUnavailable, LoginCancelled
+from zenture._auth.model import CLIENT_ID, SCOPE
+
+if TYPE_CHECKING:
+    import threading
+
+    from zenture._auth.discovery import Discovery
+
+CALLBACK_PATH = "/oauth/callback"
+LOGIN_TIMEOUT_SECONDS = 600.0
+_MAX_REQUEST_BYTES = 16 * 1024
+_CONNECTION_READ_SECONDS = 0.5
+_REQUEST_READ_TOTAL_SECONDS = 2.0
+_SLICE_SECONDS = 0.2
+_DRAIN_SECONDS = 0.25
+_MAX_DRAIN_BYTES = 64 * 1024
+_PAGE = (
+    b"<!doctype html><html lang=en><meta charset=utf-8><title>zenture</title>"
+    b"<body><p>%s</p></body></html>"
+)
+
+BrowserOpener = Callable[[str], object]
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class CallbackResult:
+    """The validated authorization response; ``code`` is a bearer-like secret."""
+
+    code: str
+    redirect_uri: str
+    verifier: str
+
+    def __repr__(self) -> str:
+        return "CallbackResult()"
+
+
+def bind_loopback() -> tuple[socket.socket, str]:
+    """Listen on 127.0.0.1 (fallback ::1) on an ephemeral port; never a LAN address."""
+
+    last_error: OSError | None = None
+    for family, host, display in (
+        (socket.AF_INET, "127.0.0.1", "127.0.0.1"),
+        (socket.AF_INET6, "::1", "[::1]"),
+    ):
+        try:
+            listener = socket.socket(family, socket.SOCK_STREAM)
+        except OSError as exc:
+            last_error = exc
+            continue
+        try:
+            if sys.platform == "win32":
+                # Windows lets a second local process share a port unless it is claimed exclusively.
+                listener.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
+            listener.bind((host, 0))
+            listener.listen(4)
+        except OSError as exc:
+            listener.close()
+            last_error = exc
+            continue
+        port = listener.getsockname()[1]
+        return listener, f"http://{display}:{port}{CALLBACK_PATH}"
+    raise AuthUnavailable("loopback_unavailable", next_action="use_device_login") from last_error
+
+
+def pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(32)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return verifier, base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def authorization_url(
+    discovery: Discovery, *, redirect_uri: str, state: str, challenge: str
+) -> str:
+    query = {
+        "response_type": "code",
+        "client_id": CLIENT_ID,
+        "redirect_uri": redirect_uri,
+        "scope": SCOPE,
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "resource": discovery.resource,
+    }
+    encoded = "&".join(f"{key}={quote(value, safe='')}" for key, value in query.items())
+    return f"{discovery.authorization_endpoint}?{encoded}"
+
+
+def _read_request(connection: socket.socket) -> tuple[str, str, dict[str, str]] | None:
+    deadline = time.monotonic() + _REQUEST_READ_TOTAL_SECONDS
+    received = bytearray()
+    try:
+        while b"\r\n\r\n" not in received:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            connection.settimeout(min(_CONNECTION_READ_SECONDS, remaining))
+            chunk = connection.recv(4096)
+            if not chunk:
+                return None
+            received.extend(chunk)
+            if len(received) > _MAX_REQUEST_BYTES:
+                return None
+    except OSError:
+        return None
+    head = bytes(received).split(b"\r\n\r\n", 1)[0].decode("latin-1")
+    lines = head.split("\r\n")
+    parts = lines[0].split(" ")
+    if len(parts) != 3:
+        return None
+    headers: dict[str, str] = {}
+    for line in lines[1:]:
+        name, separator, value = line.partition(":")
+        if separator:
+            headers[name.strip().lower()] = value.strip()
+    return parts[0], parts[1], headers
+
+
+def _respond(connection: socket.socket, status: str, message: str) -> None:
+    body = _PAGE % message.encode("ascii")
+    head = (
+        f"HTTP/1.1 {status}\r\nContent-Type: text/html; charset=utf-8\r\n"
+        f"Content-Length: {len(body)}\r\nCache-Control: no-store\r\n"
+        "Referrer-Policy: no-referrer\r\nConnection: close\r\n\r\n"
+    ).encode("ascii")
+    with contextlib.suppress(OSError):
+        connection.sendall(head + body)
+        _drain_before_close(connection)
+
+
+def _drain_before_close(connection: socket.socket) -> None:
+    """Half-close writes and discard bounded unread request bytes before close."""
+
+    connection.shutdown(socket.SHUT_WR)
+    deadline = time.monotonic() + _DRAIN_SECONDS
+    remaining = _MAX_DRAIN_BYTES
+    while remaining > 0:
+        seconds_left = deadline - time.monotonic()
+        if seconds_left <= 0:
+            return
+        connection.settimeout(seconds_left)
+        try:
+            chunk = connection.recv(4096)
+        except TimeoutError:
+            return
+        if not chunk:
+            return
+        remaining -= len(chunk)
+
+
+def _single(query: dict[str, list[str]], key: str) -> str | None:
+    values = query.get(key)
+    if values is None or len(values) != 1 or not values[0]:
+        return None
+    return values[0]
+
+
+def _classify(
+    request: tuple[str, str, dict[str, str]] | None, *, host_header: str, state: str
+) -> dict[str, list[str]] | None:
+    """Return the query of an acceptable callback, else ``None`` (request is ignored)."""
+
+    if request is None:
+        return None
+    method, target, headers = request
+    if method != "GET" or headers.get("host") != host_header:
+        return None
+    try:
+        parsed = urlsplit(target)
+        if parsed.path != CALLBACK_PATH or parsed.fragment:
+            return None
+        query = parse_qs(parsed.query, keep_blank_values=True, max_num_fields=16)
+    except ValueError:
+        return None
+    received_state = _single(query, "state")
+    if (
+        received_state is None
+        or not received_state.isascii()
+        or not hmac.compare_digest(received_state, state)
+    ):
+        return None
+    return query
+
+
+def wait_for_callback(
+    listener: socket.socket,
+    *,
+    redirect_uri: str,
+    state: str,
+    verifier: str,
+    issuer: str,
+    timeout: float = LOGIN_TIMEOUT_SECONDS,
+    cancel: threading.Event | None = None,
+) -> CallbackResult:
+    """Accept exactly one valid callback, then stop listening."""
+
+    host_header = urlsplit(redirect_uri).netloc
+    deadline = time.monotonic() + timeout
+    try:
+        while True:
+            if cancel is not None and cancel.is_set():
+                raise LoginCancelled
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise AuthUnavailable("login_timed_out", next_action="login")
+            ready, _, _ = select.select([listener], [], [], min(_SLICE_SECONDS, remaining))
+            if not ready:
+                continue
+            try:
+                connection, _ = listener.accept()
+            except OSError:
+                continue
+            with connection:
+                query = _classify(_read_request(connection), host_header=host_header, state=state)
+                if query is None:
+                    _respond(connection, "400 Bad Request", "Invalid request.")
+                    continue
+                return _finish(connection, query, issuer, redirect_uri, verifier)
+    finally:
+        listener.close()
+
+
+def _finish(
+    connection: socket.socket,
+    query: dict[str, list[str]],
+    issuer: str,
+    redirect_uri: str,
+    verifier: str,
+) -> CallbackResult:
+    if _single(query, "iss") != issuer:
+        _respond(connection, "400 Bad Request", "Authorization response rejected.")
+        raise AuthUnavailable("authorization_response_invalid")
+    error = _single(query, "error")
+    if error is not None:
+        if error == "access_denied":
+            _respond(connection, "200 OK", "Authorization was cancelled. You can close this tab.")
+            raise LoginCancelled
+        _respond(connection, "200 OK", "Authorization failed. You can close this tab.")
+        raise AuthUnavailable("authorization_failed")
+    code = _single(query, "code")
+    if code is None:
+        _respond(connection, "400 Bad Request", "Authorization response rejected.")
+        raise AuthUnavailable("authorization_response_invalid")
+    _respond(connection, "200 OK", "Authorization received. Return to your terminal.")
+    return CallbackResult(code=code, redirect_uri=redirect_uri, verifier=verifier)

zenture/_auth/device.py

@@ -0,0 +1,224 @@
+"""RFC 8628 device authorization: present a code, poll the token endpoint, verify tokens."""
+
+from __future__ import annotations
+
+import re
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import httpx
+
+from zenture._auth.errors import AuthorizationRequired, AuthUnavailable, LoginCancelled
+from zenture._auth.http import PRE_SEND_ERRORS, JsonResponse, request_json
+from zenture._auth.model import CLIENT_ID, SCOPE, is_secure_origin, origin
+from zenture._auth.tokens import KeyCache, TokenRejected, TokenSet, parse_token_response
+
+if TYPE_CHECKING:
+    import threading
+
+    from zenture._auth.discovery import Discovery
+
+DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+DEVICE_TIMEOUT_SECONDS = 600.0
+_DEFAULT_INTERVAL = 5.0
+_MAX_INTERVAL = 60.0
+_SLOW_DOWN_STEP = 5.0
+_USER_CODE = re.compile(r"^[A-Za-z0-9]{8}$")
+_MAX_FIELD = 2048
+_WAIT_SLICE = 1.0
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class DevicePrompt:
+    """What the user must see: the plain verification URI and the code as ``XXXX-XXXX``."""
+
+    verification_uri: str
+    user_code: str
+
+    def __repr__(self) -> str:
+        return "DevicePrompt()"
+
+
+Presenter = Callable[[DevicePrompt], None]
+Clock = Callable[[], float]
+Sleep = Callable[[float], None]
+
+
+def terminal_presenter(prompt: DevicePrompt) -> None:
+    """Show the prompt on the terminal only (never through logging)."""
+
+    print(
+        f"To authorize this device, open {prompt.verification_uri}\n"
+        f"and enter the code {prompt.user_code}",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class _Authorization:
+    device_code: str
+    prompt: DevicePrompt
+    expires_in: float
+    interval: float
+
+    def __repr__(self) -> str:
+        return "_Authorization()"
+
+
+def _invalid() -> AuthUnavailable:
+    return AuthUnavailable("device_authorization_invalid", next_action="retry_later")
+
+
+def _is_plain_text(value: str) -> bool:
+    """Printable and free of whitespace: nothing that could rewrite the terminal."""
+
+    return value.isprintable() and not any(ch.isspace() for ch in value)
+
+
+def _positive(value: object) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, int | float) or value <= 0:
+        return None
+    return float(value)
+
+
+def _start(client: httpx.Client, discovery: Discovery) -> _Authorization:
+    endpoint = discovery.device_authorization_endpoint
+    if endpoint is None:
+        raise AuthUnavailable("device_login_unsupported", next_action="check_endpoint")
+    form = {"client_id": CLIENT_ID, "scope": SCOPE, "resource": discovery.resource}
+    try:
+        response = request_json(client, "POST", endpoint, form=form)
+    except httpx.HTTPError as exc:
+        raise AuthUnavailable("device_authorization_unreachable") from exc
+    body = response.body
+    if response.status != 200 or body is None:
+        raise _invalid()
+    device_code = body.get("device_code")
+    user_code = body.get("user_code")
+    verification_uri = body.get("verification_uri")
+    expires_in = _positive(body.get("expires_in"))
+    interval = _positive(body.get("interval", _DEFAULT_INTERVAL))
+    if not (
+        isinstance(device_code, str)
+        and device_code
+        and len(device_code) <= _MAX_FIELD
+        and isinstance(user_code, str)
+        and _USER_CODE.fullmatch(user_code.replace("-", ""))
+        and isinstance(verification_uri, str)
+        and len(verification_uri) <= _MAX_FIELD
+        and _is_plain_text(verification_uri)
+        and is_secure_origin(verification_uri)
+        and origin(verification_uri) == origin(discovery.issuer)
+        and expires_in is not None
+        and interval is not None
+    ):
+        raise _invalid()
+    code = user_code.replace("-", "").upper()
+    return _Authorization(
+        device_code=device_code,
+        prompt=DevicePrompt(verification_uri, f"{code[:4]}-{code[4:]}"),
+        expires_in=expires_in,
+        interval=min(interval, _MAX_INTERVAL),
+    )
+
+
+def _poll_error(response: JsonResponse) -> str | None:
+    if response.status == 400 and response.body is not None:
+        error = response.body.get("error")
+        if isinstance(error, str):
+            return error
+    return None
+
+
+def _unknown_outcome() -> AuthorizationRequired:
+    return AuthorizationRequired("device_outcome_unknown", next_action="login")
+
+
+def run_device_login(
+    client: httpx.Client,
+    discovery: Discovery,
+    keys: KeyCache,
+    *,
+    present: Presenter,
+    clock: Clock = time.monotonic,
+    sleep: Sleep = time.sleep,
+    cancel: threading.Event | None = None,
+) -> TokenSet:
+    """Authorize through the device grant; nothing persists before token verification."""
+
+    authorization = _start(client, discovery)
+    deadline = clock() + min(authorization.expires_in, DEVICE_TIMEOUT_SECONDS)
+    present(authorization.prompt)
+    interval = authorization.interval
+    form = {
+        "grant_type": DEVICE_GRANT,
+        "device_code": authorization.device_code,
+        "client_id": CLIENT_ID,
+        "resource": discovery.resource,
+    }
+    try:
+        while True:
+            _wait(interval, sleep, clock, deadline, cancel)
+            if cancel is not None and cancel.is_set():
+                raise LoginCancelled("device_login_interrupted")
+            if clock() >= deadline:
+                raise AuthorizationRequired("device_code_expired", next_action="login")
+            response = _poll(client, discovery, form)
+            if response.status == 200:
+                return _tokens(response, discovery, keys, client)
+            error = _poll_error(response)
+            if error == "authorization_pending":
+                continue
+            if error == "slow_down":
+                interval = min(interval + _SLOW_DOWN_STEP, _MAX_INTERVAL)
+            elif error == "access_denied":
+                raise LoginCancelled
+            elif error == "expired_token":
+                raise AuthorizationRequired("device_code_expired", next_action="login")
+            elif error == "invalid_grant":
+                raise AuthorizationRequired("device_code_invalid", next_action="login")
+            else:
+                # The code may already be consumed: never poll it again.
+                raise _unknown_outcome()
+    except KeyboardInterrupt:
+        raise LoginCancelled("device_login_interrupted") from None
+
+
+def _wait(
+    interval: float,
+    sleep: Sleep,
+    clock: Clock,
+    deadline: float,
+    cancel: threading.Event | None,
+) -> None:
+    """Wait in short slices so a cancellation or the deadline stops polling within a second."""
+
+    remaining = interval
+    while remaining > 0:
+        step = min(_WAIT_SLICE, remaining)
+        sleep(step)
+        remaining -= step
+        if (cancel is not None and cancel.is_set()) or clock() >= deadline:
+            return
+
+
+def _poll(client: httpx.Client, discovery: Discovery, form: dict[str, str]) -> JsonResponse:
+    try:
+        return request_json(client, "POST", discovery.token_endpoint, form=form)
+    except PRE_SEND_ERRORS as exc:
+        raise AuthUnavailable("token_endpoint_unreachable") from exc
+    except httpx.HTTPError as exc:
+        raise _unknown_outcome() from exc
+
+
+def _tokens(
+    response: JsonResponse, discovery: Discovery, keys: KeyCache, client: httpx.Client
+) -> TokenSet:
+    try:
+        return parse_token_response(response, discovery=discovery, keys=keys, client=client)
+    except TokenRejected as exc:
+        raise _unknown_outcome() from exc

zenture/_auth/discovery.py

@@ -0,0 +1,93 @@
+"""Protected-resource and authorization-server discovery with exact-match checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+import httpx
+
+from zenture._auth.errors import AuthUnavailable
+from zenture._auth.http import request_json
+from zenture._auth.model import Target, is_secure_origin, origin
+
+_PRM_PATH = "/.well-known/oauth-protected-resource"
+_AS_PATH = "/.well-known/oauth-authorization-server"
+
+
+@dataclass(frozen=True, slots=True)
+class Discovery:
+    """Verified endpoints of the issuer that protects one MCP resource."""
+
+    resource: str
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    jwks_uri: str
+    device_authorization_endpoint: str | None
+
+
+def _contract_error() -> AuthUnavailable:
+    return AuthUnavailable("discovery_contract_violation", next_action="check_endpoint")
+
+
+def _endpoint(metadata: dict[str, object], key: str, issuer: str, *, required: bool) -> str | None:
+    value = metadata.get(key)
+    if value is None and not required:
+        return None
+    if not isinstance(value, str) or not is_secure_origin(value) or origin(value) != issuer:
+        raise _contract_error()
+    if urlsplit(value).query:
+        raise _contract_error()
+    return value
+
+
+def _issuer_metadata_url(issuer: str) -> str:
+    parsed = urlsplit(issuer)
+    path = parsed.path.rstrip("/")
+    return f"{origin(issuer)}{_AS_PATH}{path}"
+
+
+def discover(client: httpx.Client, target: Target) -> Discovery:
+    """Discover and verify the issuer; raises before any browser can open."""
+
+    resource = target.resource
+    try:
+        prm = request_json(client, "GET", f"{resource}{_PRM_PATH}")
+        if prm.status != 200 or prm.body is None:
+            raise _contract_error()
+        if prm.body.get("resource") != resource:
+            raise _contract_error()
+        servers = prm.body.get("authorization_servers")
+        if not isinstance(servers, list) or not servers or not isinstance(servers[0], str):
+            raise _contract_error()
+        issuer = servers[0]
+        if not is_secure_origin(issuer) or urlsplit(issuer).query or issuer.endswith("/"):
+            raise _contract_error()
+        meta = request_json(client, "GET", _issuer_metadata_url(issuer))
+    except httpx.HTTPError as exc:
+        raise AuthUnavailable("discovery_unreachable") from exc
+    if meta.status != 200 or meta.body is None:
+        raise _contract_error()
+    metadata = meta.body
+    if metadata.get("issuer") != issuer:
+        raise _contract_error()
+    methods = metadata.get("code_challenge_methods_supported")
+    if not isinstance(methods, list) or "S256" not in methods:
+        raise _contract_error()
+    if metadata.get("authorization_response_iss_parameter_supported") is not True:
+        raise _contract_error()
+    authorization = _endpoint(metadata, "authorization_endpoint", origin(issuer), required=True)
+    token = _endpoint(metadata, "token_endpoint", origin(issuer), required=True)
+    jwks = _endpoint(metadata, "jwks_uri", origin(issuer), required=True)
+    device = _endpoint(metadata, "device_authorization_endpoint", origin(issuer), required=False)
+    if authorization is None or token is None or jwks is None:
+        raise _contract_error()
+    return Discovery(
+        resource=resource,
+        issuer=issuer,
+        authorization_endpoint=authorization,
+        token_endpoint=token,
+        jwks_uri=jwks,
+        device_authorization_endpoint=device,
+    )

zenture/_auth/errors.py

@@ -0,0 +1,59 @@
+"""Public error taxonomy of the native authorization core."""
+
+from __future__ import annotations
+
+from zenture.errors import ZentureError
+
+
+class AuthError(ZentureError):
+    """Base class for native authorization failures.
+
+    Messages carry a fixed machine code only; they never contain tokens,
+    authorization codes, state values or server response bodies.
+    """
+
+    default_code = "auth_error"
+    default_action = "check_request"
+
+    def __init__(
+        self, code: str | None = None, *, next_action: str | None = None, hint: str | None = None
+    ) -> None:
+        self.code = code or self.default_code
+        self.next_action = next_action or self.default_action
+        message = f"{type(self).__name__}: {self.code}"
+        super().__init__(f"{message} ({hint})" if hint else message)
+
+
+class AuthorizationRequired(AuthError):
+    """The stored or presented authorization can no longer be used; log in again."""
+
+    default_code = "authorization_required"
+    default_action = "login"
+
+
+class AuthUnavailable(AuthError):
+    """Authorization could not be completed now; the stored authorization is unchanged."""
+
+    default_code = "auth_unavailable"
+    default_action = "retry_later"
+
+
+class SecureStoreUnavailable(AuthError):
+    """No protected native credential store is usable; session-only login is possible."""
+
+    default_code = "secure_store_unavailable"
+    default_action = "use_session_only"
+
+
+class LoginCancelled(AuthError):
+    """The user declined or cancelled the browser authorization."""
+
+    default_code = "login_cancelled"
+    default_action = "none"
+
+
+class PermissionDenied(AuthError):
+    """The server refused the request for the authorized client (HTTP 403); no scope uplift."""
+
+    default_code = "permission_denied"
+    default_action = "contact_owner"