tescmd 0.1.2__py3-none-any.whl

tescmd/auth/oauth.py

@@ -0,0 +1,312 @@
+"""OAuth2 PKCE helpers, partner registration, and interactive login flow."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+import secrets
+import time
+import webbrowser
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode
+
+import httpx
+
+from tescmd.api.client import REGION_BASE_URLS
+from tescmd.api.errors import AuthError
+from tescmd.auth.server import OAuthCallbackServer
+from tescmd.models.auth import (
+    AUTHORIZE_URL,
+    PARTNER_SCOPES,
+    TOKEN_URL,
+    TokenData,
+    decode_jwt_scopes,
+)
+
+if TYPE_CHECKING:
+    from tescmd.auth.token_store import TokenStore
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# PKCE helpers
+# ---------------------------------------------------------------------------
+
+
+def _generate_code_verifier() -> str:
+    """Return a 128-character base64url code verifier (no padding)."""
+    return secrets.token_urlsafe(96)[:128]
+
+
+def _generate_code_challenge(verifier: str) -> str:
+    """Compute S256 code challenge for the given *verifier*."""
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def build_auth_url(
+    client_id: str,
+    redirect_uri: str,
+    scopes: list[str],
+    code_challenge: str,
+    state: str,
+    *,
+    force_consent: bool = False,
+) -> str:
+    """Build the full Tesla authorization URL.
+
+    When *force_consent* is ``True`` the ``prompt_missing_scopes=true``
+    parameter is added so Tesla prompts the user to approve any scopes
+    that were not granted in a previous consent.  This is Tesla's
+    proprietary parameter (not the standard ``prompt=consent``).
+    """
+    params: dict[str, str] = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "scope": " ".join(scopes),
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    }
+    if force_consent:
+        params["prompt_missing_scopes"] = "true"
+    return f"{AUTHORIZE_URL}?{urlencode(params)}"
+
+
+# ---------------------------------------------------------------------------
+# Token exchange / refresh
+# ---------------------------------------------------------------------------
+
+
+async def exchange_code(
+    code: str,
+    code_verifier: str,
+    client_id: str,
+    client_secret: str | None = None,
+    redirect_uri: str = "http://localhost:8085/callback",
+) -> TokenData:
+    """Exchange an authorization code for tokens."""
+    payload: dict[str, Any] = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "code_verifier": code_verifier,
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+    }
+    if client_secret is not None:
+        payload["client_secret"] = client_secret
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(TOKEN_URL, data=payload)
+    if resp.status_code != 200:
+        raise AuthError(f"Token exchange failed: {resp.text}", status_code=resp.status_code)
+    return TokenData.model_validate(resp.json())
+
+
+async def refresh_access_token(
+    refresh_token: str,
+    client_id: str,
+    client_secret: str | None = None,
+) -> TokenData:
+    """Use a refresh token to obtain new tokens."""
+    payload: dict[str, Any] = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": client_id,
+    }
+    if client_secret is not None:
+        payload["client_secret"] = client_secret
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(TOKEN_URL, data=payload)
+    if resp.status_code != 200:
+        raise AuthError(f"Token refresh failed: {resp.text}", status_code=resp.status_code)
+    return TokenData.model_validate(resp.json())
+
+
+# ---------------------------------------------------------------------------
+# Partner registration (one-time per region)
+# ---------------------------------------------------------------------------
+
+
+async def get_partner_token(
+    client_id: str,
+    client_secret: str,
+    region: str = "na",
+) -> tuple[str, list[str]]:
+    """Obtain a partner token via *client_credentials* grant.
+
+    The ``audience`` parameter tells Tesla which regional endpoint the
+    token is for.
+
+    Returns a ``(token, granted_scopes)`` tuple.  *granted_scopes* are
+    decoded from the JWT ``scp`` claim so callers can verify that the
+    partner registration will cover all requested scopes.
+    """
+    audience = REGION_BASE_URLS.get(region)
+    if audience is None:
+        msg = f"Unknown region {region!r}; expected one of {sorted(REGION_BASE_URLS)}"
+        raise AuthError(msg)
+
+    payload = {
+        "grant_type": "client_credentials",
+        "client_id": client_id,
+        "client_secret": client_secret,
+        "scope": " ".join(PARTNER_SCOPES),
+        "audience": audience,
+    }
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(TOKEN_URL, data=payload)
+    if resp.status_code != 200:
+        raise AuthError(
+            f"Partner token request failed: {resp.text}",
+            status_code=resp.status_code,
+        )
+    data: dict[str, Any] = resp.json()
+    token: str = data["access_token"]
+
+    granted = decode_jwt_scopes(token) or []
+    logger.debug("Partner token scopes: requested=%s, granted=%s", PARTNER_SCOPES, granted)
+
+    return token, granted
+
+
+async def register_partner_account(
+    client_id: str,
+    client_secret: str,
+    domain: str = "localhost",
+    region: str = "na",
+) -> tuple[dict[str, Any], list[str]]:
+    """Register the application with the Tesla Fleet API for *region*.
+
+    This must be called once per region before the Fleet API will accept
+    requests.  It is safe to call more than once (idempotent).
+
+    Returns a ``(response_body, partner_scopes)`` tuple.
+    *partner_scopes* are the scopes actually granted in the partner
+    token, which determines the ceiling for user token scopes.
+    """
+    base_url = REGION_BASE_URLS.get(region)
+    if base_url is None:
+        msg = f"Unknown region {region!r}; expected one of {sorted(REGION_BASE_URLS)}"
+        raise AuthError(msg)
+
+    partner_token, granted_scopes = await get_partner_token(client_id, client_secret, region)
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{base_url}/api/1/partner_accounts",
+            json={"domain": domain},
+            headers={"Authorization": f"Bearer {partner_token}"},
+        )
+
+    if resp.status_code >= 400:
+        raise AuthError(
+            f"Partner registration failed (HTTP {resp.status_code}): {resp.text}",
+            status_code=resp.status_code,
+        )
+    result: dict[str, Any] = resp.json()
+    return result, granted_scopes
+
+
+# ---------------------------------------------------------------------------
+# Scope extraction
+# ---------------------------------------------------------------------------
+
+
+def _extract_granted_scopes(token: TokenData, *, requested: list[str]) -> list[str]:
+    """Return the scopes actually granted in the token response.
+
+    Checks three sources in priority order:
+    1. ``token.scope`` — the ``scope`` field from the OAuth token response
+    2. JWT ``scp`` claim — decoded from the access token payload
+    3. *requested* — falls back to whatever we asked for
+    """
+    if token.scope:
+        return token.scope.split()
+
+    jwt_scopes = decode_jwt_scopes(token.access_token)
+    if jwt_scopes is not None:
+        return jwt_scopes
+
+    return requested
+
+
+# ---------------------------------------------------------------------------
+# Full interactive login flow
+# ---------------------------------------------------------------------------
+
+
+async def login_flow(
+    client_id: str,
+    client_secret: str | None,
+    redirect_uri: str,
+    scopes: list[str],
+    port: int,
+    token_store: TokenStore,
+    region: str = "na",
+    *,
+    force_consent: bool = False,
+) -> TokenData:
+    """Run the full OAuth2 PKCE login flow interactively.
+
+    1. Generate PKCE pair
+    2. Start local callback server
+    3. Open browser to authorization URL
+    4. Wait for redirect with auth code
+    5. Exchange code for tokens
+    6. Persist to *token_store*
+
+    When *force_consent* is ``True`` the authorization URL includes
+    ``prompt_missing_scopes=true`` so Tesla prompts for any new scopes.
+    """
+    verifier = _generate_code_verifier()
+    challenge = _generate_code_challenge(verifier)
+    state = secrets.token_urlsafe(32)
+
+    server = OAuthCallbackServer(port=port)
+    server.start()
+    try:
+        url = build_auth_url(
+            client_id,
+            redirect_uri,
+            scopes,
+            challenge,
+            state,
+            force_consent=force_consent,
+        )
+        webbrowser.open(url)
+
+        code, callback_state = server.wait_for_callback(timeout=120)
+    finally:
+        server.stop()
+
+    if code is None:
+        raise AuthError("OAuth callback timed out or was cancelled")
+
+    if callback_state != state:
+        raise AuthError("OAuth state mismatch — possible CSRF attack")
+
+    token = await exchange_code(
+        code=code,
+        code_verifier=verifier,
+        client_id=client_id,
+        client_secret=client_secret,
+        redirect_uri=redirect_uri,
+    )
+
+    # Determine actually granted scopes — prefer the token response's scope
+    # field, then JWT payload, then fall back to what we requested.
+    granted = _extract_granted_scopes(token, requested=scopes)
+
+    token_store.save(
+        access_token=token.access_token,
+        refresh_token=token.refresh_token or "",
+        expires_at=time.time() + token.expires_in,
+        scopes=granted,
+        region=region,
+    )
+    return token

tescmd/auth/server.py

@@ -0,0 +1,108 @@
+"""Lightweight local HTTP server for the OAuth2 redirect callback."""
+
+from __future__ import annotations
+
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+# ---------------------------------------------------------------------------
+# HTML templates
+# ---------------------------------------------------------------------------
+
+_SUCCESS_HTML = """\
+<!DOCTYPE html>
+<html><head><title>tescmd</title></head>
+<body style="font-family:sans-serif;text-align:center;margin-top:80px">
+<h1>Authentication Successful</h1>
+<p>You can close this window and return to the terminal.</p>
+</body></html>
+"""
+
+_FAILURE_HTML = """\
+<!DOCTYPE html>
+<html><head><title>tescmd</title></head>
+<body style="font-family:sans-serif;text-align:center;margin-top:80px">
+<h1>Authentication Failed</h1>
+<p>{error}</p>
+</body></html>
+"""
+
+
+# ---------------------------------------------------------------------------
+# Request handler
+# ---------------------------------------------------------------------------
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Handle a single GET from the OAuth redirect."""
+
+    server: OAuthCallbackServer
+
+    def do_GET(self) -> None:
+        qs = parse_qs(urlparse(self.path).query)
+
+        error = qs.get("error", [None])[0]
+        if error is not None:
+            self._respond(400, _FAILURE_HTML.format(error=error))
+            self.server.callback_result = (None, None, error)
+            self.server.callback_event.set()
+            return
+
+        code = qs.get("code", [None])[0]
+        state = qs.get("state", [None])[0]
+        self._respond(200, _SUCCESS_HTML)
+        self.server.callback_result = (code, state, None)
+        self.server.callback_event.set()
+
+    def _respond(self, status: int, body: str) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(body.encode())
+
+    # Silence default request logging.
+    def log_message(self, format: str, *args: Any) -> None:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+
+
+class OAuthCallbackServer(HTTPServer):
+    """HTTPServer that waits for a single OAuth redirect callback."""
+
+    def __init__(self, port: int = 8085) -> None:
+        super().__init__(("127.0.0.1", port), _CallbackHandler)
+        self.callback_event = threading.Event()
+        self.callback_result: tuple[str | None, str | None, str | None] = (
+            None,
+            None,
+            None,
+        )
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        """Start serving in a daemon thread."""
+        self._thread = threading.Thread(target=self.serve_forever, daemon=True)
+        self._thread.start()
+
+    def wait_for_callback(self, timeout: float = 120) -> tuple[str | None, str | None]:
+        """Block until the callback is received or *timeout* elapses.
+
+        Returns ``(code, state)`` on success; ``(None, None)`` on timeout or error.
+        """
+        received = self.callback_event.wait(timeout=timeout)
+        if not received:
+            return (None, None)
+        code, state, _error = self.callback_result
+        return (code, state)
+
+    def stop(self) -> None:
+        """Shut down the server and join the daemon thread."""
+        self.shutdown()
+        if self._thread is not None:
+            self._thread.join(timeout=5)

tescmd/auth/token_store.py

@@ -0,0 +1,273 @@
+"""Token persistence with keyring and file-based backends."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+import warnings
+from pathlib import Path
+from typing import Any, Protocol
+
+SERVICE_NAME = "tescmd"
+
+# Module-level flag so the file-fallback warning fires at most once.
+_warned = False
+
+
+# ---------------------------------------------------------------------------
+# Backend protocol
+# ---------------------------------------------------------------------------
+
+
+class _TokenBackend(Protocol):
+    """Minimal interface for reading/writing credential entries."""
+
+    @property
+    def backend_name(self) -> str: ...
+    def get(self, key: str) -> str | None: ...
+    def set(self, key: str, value: str) -> None: ...
+    def delete(self, key: str) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Keyring backend (delegates to the OS keyring)
+# ---------------------------------------------------------------------------
+
+
+class _KeyringBackend:
+    """Wraps the ``keyring`` library."""
+
+    @property
+    def backend_name(self) -> str:
+        return "keyring"
+
+    def get(self, key: str) -> str | None:
+        import keyring as _kr
+
+        return _kr.get_password(SERVICE_NAME, key)
+
+    def set(self, key: str, value: str) -> None:
+        import keyring as _kr
+
+        _kr.set_password(SERVICE_NAME, key, value)
+
+    def delete(self, key: str) -> None:
+        import keyring as _kr
+        from keyring.errors import PasswordDeleteError
+
+        with contextlib.suppress(PasswordDeleteError):
+            _kr.delete_password(SERVICE_NAME, key)
+
+
+# ---------------------------------------------------------------------------
+# File backend (JSON file with atomic writes)
+# ---------------------------------------------------------------------------
+
+
+class _FileBackend:
+    """Stores credentials in a JSON file at *path*.
+
+    The file is written atomically (write-to-temp + rename) and
+    permissions are restricted to the current user.
+    """
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+
+    @property
+    def backend_name(self) -> str:
+        return f"file ({self._path})"
+
+    # -- helpers -------------------------------------------------------------
+
+    def _read_store(self) -> dict[str, str]:
+        if not self._path.exists():
+            return {}
+        try:
+            data: dict[str, str] = json.loads(self._path.read_text("utf-8"))
+            return data
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    def _write_store(self, data: dict[str, str]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+        from tescmd._internal.permissions import secure_file
+
+        # Atomic write: temp file in the same directory → rename
+        fd, tmp = tempfile.mkstemp(dir=str(self._path.parent), suffix=".tmp", prefix=".tokens_")
+        try:
+            os.write(fd, json.dumps(data, indent=2).encode("utf-8"))
+            os.close(fd)
+            fd = -1  # mark as closed
+            Path(tmp).replace(self._path)
+        except BaseException:
+            if fd != -1:
+                os.close(fd)
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise
+
+        secure_file(self._path)
+
+    # -- interface -----------------------------------------------------------
+
+    def get(self, key: str) -> str | None:
+        return self._read_store().get(key)
+
+    def set(self, key: str, value: str) -> None:
+        store = self._read_store()
+        store[key] = value
+        self._write_store(store)
+
+    def delete(self, key: str) -> None:
+        store = self._read_store()
+        store.pop(key, None)
+        self._write_store(store)
+
+
+# ---------------------------------------------------------------------------
+# Backend resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_backend(
+    token_file: str | None = None,
+    config_dir: str | None = None,
+) -> _TokenBackend:
+    """Choose the best available backend.
+
+    1. Explicit *token_file* → file backend (no keyring probe).
+    2. Keyring probe succeeds → keyring backend.
+    3. Keyring probe fails → file backend at ``{config_dir}/tokens.json``
+       with a one-time warning.
+    """
+    # 1. Explicit token file — skip keyring entirely
+    if token_file:
+        return _FileBackend(Path(token_file).expanduser())
+
+    # 2. Probe keyring
+    try:
+        import keyring as _kr
+
+        _kr.get_password(SERVICE_NAME, "__probe__")
+        return _KeyringBackend()
+    except Exception:
+        # NoKeyringError, RuntimeError, or any other keyring failure
+        pass
+
+    # 3. Fall back to file
+    global _warned
+    resolved_dir = Path(config_dir or "~/.config/tescmd").expanduser()
+    fallback_path = resolved_dir / "tokens.json"
+    if not _warned:
+        _warned = True
+        warnings.warn(
+            f"OS keyring unavailable — storing tokens in {fallback_path} "
+            "(plaintext with restricted permissions). "
+            "Set TESLA_TOKEN_FILE to choose a different path.",
+            UserWarning,
+            stacklevel=3,
+        )
+    return _FileBackend(fallback_path)
+
+
+# ---------------------------------------------------------------------------
+# Public API (unchanged surface)
+# ---------------------------------------------------------------------------
+
+
+class TokenStore:
+    """Read / write OAuth tokens via the OS keyring or a file fallback."""
+
+    def __init__(
+        self,
+        profile: str = "default",
+        *,
+        token_file: str | None = None,
+        config_dir: str | None = None,
+    ) -> None:
+        self._profile = profile
+        self._backend: _TokenBackend = _resolve_backend(token_file, config_dir)
+
+    # -- key helpers ---------------------------------------------------------
+
+    def _key(self, name: str) -> str:
+        return f"{self._profile}/{name}"
+
+    # -- diagnostics ---------------------------------------------------------
+
+    @property
+    def backend_name(self) -> str:
+        """Return a human-readable description of the active backend."""
+        return self._backend.backend_name
+
+    # -- properties ----------------------------------------------------------
+
+    @property
+    def access_token(self) -> str | None:
+        """Return the stored access token, or *None*."""
+        return self._backend.get(self._key("access_token"))
+
+    @property
+    def refresh_token(self) -> str | None:
+        """Return the stored refresh token, or *None*."""
+        return self._backend.get(self._key("refresh_token"))
+
+    @property
+    def has_token(self) -> bool:
+        """Return *True* if an access token is stored."""
+        return self.access_token is not None
+
+    @property
+    def metadata(self) -> dict[str, Any] | None:
+        """Return the parsed metadata dict, or *None*."""
+        raw = self._backend.get(self._key("metadata"))
+        if raw is None:
+            return None
+        result: dict[str, Any] = json.loads(raw)
+        return result
+
+    # -- mutators ------------------------------------------------------------
+
+    def save(
+        self,
+        access_token: str,
+        refresh_token: str,
+        expires_at: float,
+        scopes: list[str],
+        region: str,
+    ) -> None:
+        """Persist all three entries."""
+        self._backend.set(self._key("access_token"), access_token)
+        self._backend.set(self._key("refresh_token"), refresh_token)
+        meta = json.dumps({"expires_at": expires_at, "scopes": scopes, "region": region})
+        self._backend.set(self._key("metadata"), meta)
+
+    def clear(self) -> None:
+        """Delete all stored credentials."""
+        for name in ("access_token", "refresh_token", "metadata"):
+            self._backend.delete(self._key(name))
+
+    # -- import / export -----------------------------------------------------
+
+    def export_dict(self) -> dict[str, Any]:
+        """Return a plain dict of all stored values (for ``auth export``)."""
+        return {
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "metadata": self.metadata,
+        }
+
+    def import_dict(self, data: dict[str, Any]) -> None:
+        """Restore tokens from a previously exported dict."""
+        meta: dict[str, Any] = data.get("metadata") or {}
+        self.save(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            expires_at=meta.get("expires_at", 0.0),
+            scopes=meta.get("scopes", []),
+            region=meta.get("region", "na"),
+        )

tescmd/cache/__init__.py

@@ -0,0 +1,6 @@
+"""Disk-based response cache for reducing Tesla Fleet API costs."""
+
+from tescmd.cache.keys import generic_cache_key
+from tescmd.cache.response_cache import CacheResult, ResponseCache
+
+__all__ = ["CacheResult", "ResponseCache", "generic_cache_key"]