tescmd 0.1.2__py3-none-any.whl

tescmd/crypto/__init__.py

@@ -0,0 +1,19 @@
+"""EC key management for Tesla Fleet API command signing."""
+
+from tescmd.crypto.keys import (
+    generate_ec_key_pair,
+    get_key_fingerprint,
+    get_public_key_path,
+    has_key_pair,
+    load_private_key,
+    load_public_key_pem,
+)
+
+__all__ = [
+    "generate_ec_key_pair",
+    "get_key_fingerprint",
+    "get_public_key_path",
+    "has_key_pair",
+    "load_private_key",
+    "load_public_key_pem",
+]

tescmd/crypto/ecdh.py

@@ -0,0 +1,46 @@
+"""ECDH key exchange for Tesla Vehicle Command Protocol sessions."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+
+def derive_session_key(
+    private_key: ec.EllipticCurvePrivateKey,
+    vehicle_public_key_bytes: bytes,
+) -> bytes:
+    """Derive a 16-byte session key via ECDH + SHA-1 truncation.
+
+    Parameters
+    ----------
+    private_key:
+        The client's EC P-256 private key.
+    vehicle_public_key_bytes:
+        The vehicle's public key as an uncompressed 65-byte point
+        (``0x04 || X || Y``) received in the SessionInfo response.
+
+    Returns
+    -------
+    bytes
+        A 16-byte session key: ``SHA1(shared_secret)[:16]``.
+    """
+    vehicle_pub = ec.EllipticCurvePublicKey.from_encoded_point(
+        ec.SECP256R1(), vehicle_public_key_bytes
+    )
+    shared_secret = private_key.exchange(ec.ECDH(), vehicle_pub)
+    return hashlib.sha1(shared_secret).digest()[:16]
+
+
+def get_uncompressed_public_key(private_key: ec.EllipticCurvePrivateKey) -> bytes:
+    """Return the uncompressed 65-byte public key point (0x04 || X || Y)."""
+    from cryptography.hazmat.primitives.serialization import (
+        Encoding,
+        PublicFormat,
+    )
+
+    return private_key.public_key().public_bytes(
+        encoding=Encoding.X962,
+        format=PublicFormat.UncompressedPoint,
+    )

tescmd/crypto/keys.py

@@ -0,0 +1,122 @@
+"""EC P-256 key generation and loading for Tesla Fleet API command signing."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+DEFAULT_KEY_DIR = "~/.config/tescmd/keys"
+PRIVATE_KEY_FILE = "private_key.pem"
+PUBLIC_KEY_FILE = "public_key.pem"
+
+
+def generate_ec_key_pair(
+    key_dir: Path | str | None = None,
+    *,
+    overwrite: bool = False,
+) -> tuple[Path, Path]:
+    """Generate an EC P-256 key pair and write PEM files.
+
+    Returns the (private_key_path, public_key_path) tuple.
+    """
+    resolved = _resolve_key_dir(key_dir)
+    resolved.mkdir(parents=True, exist_ok=True)
+
+    priv_path = resolved / PRIVATE_KEY_FILE
+    pub_path = resolved / PUBLIC_KEY_FILE
+
+    if priv_path.exists() and not overwrite:
+        raise FileExistsError(
+            f"Key pair already exists at {resolved}. Use overwrite=True to replace."
+        )
+
+    private_key = ec.generate_private_key(ec.SECP256R1())
+
+    # Write private key — PEM, no encryption
+    priv_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    priv_path.write_bytes(priv_pem)
+
+    from tescmd._internal.permissions import secure_file
+
+    secure_file(priv_path)
+
+    # Write public key — PEM
+    pub_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    pub_path.write_bytes(pub_pem)
+
+    return (priv_path, pub_path)
+
+
+def load_private_key(key_dir: Path | str | None = None) -> ec.EllipticCurvePrivateKey:
+    """Load the private key from disk."""
+    resolved = _resolve_key_dir(key_dir)
+    priv_path = resolved / PRIVATE_KEY_FILE
+
+    if not priv_path.exists():
+        raise FileNotFoundError(
+            f"Private key not found at {priv_path}. Run 'tescmd key generate' first."
+        )
+
+    key = serialization.load_pem_private_key(priv_path.read_bytes(), password=None)
+    if not isinstance(key, ec.EllipticCurvePrivateKey):
+        raise TypeError(f"Expected EC private key, got {type(key).__name__}")
+    return key
+
+
+def load_public_key_pem(key_dir: Path | str | None = None) -> str:
+    """Load the public key PEM as a string (for deployment)."""
+    resolved = _resolve_key_dir(key_dir)
+    pub_path = resolved / PUBLIC_KEY_FILE
+
+    if not pub_path.exists():
+        raise FileNotFoundError(
+            f"Public key not found at {pub_path}. Run 'tescmd key generate' first."
+        )
+
+    return pub_path.read_text()
+
+
+def get_public_key_path(key_dir: Path | str | None = None) -> Path:
+    """Return the resolved path to the public key file."""
+    return _resolve_key_dir(key_dir) / PUBLIC_KEY_FILE
+
+
+def has_key_pair(key_dir: Path | str | None = None) -> bool:
+    """Return True if both private and public key files exist."""
+    resolved = _resolve_key_dir(key_dir)
+    return (resolved / PRIVATE_KEY_FILE).exists() and (resolved / PUBLIC_KEY_FILE).exists()
+
+
+def get_key_fingerprint(key_dir: Path | str | None = None) -> str:
+    """Return the SHA-256 hex fingerprint of the public key (DER-encoded)."""
+    resolved = _resolve_key_dir(key_dir)
+    pub_path = resolved / PUBLIC_KEY_FILE
+
+    if not pub_path.exists():
+        raise FileNotFoundError(
+            f"Public key not found at {pub_path}. Run 'tescmd key generate' first."
+        )
+
+    key = serialization.load_pem_public_key(pub_path.read_bytes())
+    der = key.public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return hashlib.sha256(der).hexdigest()
+
+
+def _resolve_key_dir(key_dir: Path | str | None) -> Path:
+    """Resolve the key directory, expanding ~ and defaulting if None."""
+    if key_dir is None:
+        return Path(DEFAULT_KEY_DIR).expanduser()
+    return Path(key_dir).expanduser()

tescmd/deploy/github_pages.py

@@ -0,0 +1,268 @@
+"""GitHub Pages deployment helpers for Tesla Fleet API public keys.
+
+All Git/GitHub operations go through ``_run_gh`` and ``_run_git`` helpers
+so that tests can mock subprocess calls cleanly.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+import httpx
+
+WELL_KNOWN_PATH = ".well-known/appspecific/com.tesla.3p.public-key.pem"
+
+# Timeout and polling for GitHub Pages deployment
+DEFAULT_DEPLOY_TIMEOUT = 180  # seconds
+POLL_INTERVAL = 5  # seconds
+
+
+# ---------------------------------------------------------------------------
+# Subprocess helpers
+# ---------------------------------------------------------------------------
+
+
+def _run_gh(args: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run a ``gh`` CLI command and return the result."""
+    return subprocess.run(
+        ["gh", *args],
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+def _run_git(
+    args: list[str],
+    *,
+    cwd: Path | str | None = None,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Run a ``git`` command and return the result."""
+    return subprocess.run(
+        ["git", *args],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+        check=check,
+    )
+
+
+# ---------------------------------------------------------------------------
+# GitHub CLI queries
+# ---------------------------------------------------------------------------
+
+
+def is_gh_available() -> bool:
+    """Return True if the ``gh`` CLI is installed on PATH."""
+    return shutil.which("gh") is not None
+
+
+def is_gh_authenticated() -> bool:
+    """Return True if ``gh`` is authenticated with GitHub."""
+    if not is_gh_available():
+        return False
+    result = _run_gh(["auth", "status"], check=False)
+    return result.returncode == 0
+
+
+def get_gh_username() -> str:
+    """Return the authenticated GitHub username.
+
+    Raises ``RuntimeError`` if ``gh`` is not authenticated.
+    """
+    result = _run_gh(["api", "user", "--jq", ".login"])
+    username = result.stdout.strip()
+    if not username:
+        raise RuntimeError("Could not determine GitHub username from 'gh api user'.")
+    return username
+
+
+def repo_exists(repo_name: str) -> bool:
+    """Return True if the given ``owner/repo`` exists on GitHub."""
+    result = _run_gh(["repo", "view", repo_name], check=False)
+    return result.returncode == 0
+
+
+# ---------------------------------------------------------------------------
+# Repository creation and key deployment
+# ---------------------------------------------------------------------------
+
+
+def create_pages_repo(username: str) -> str:
+    """Create ``<username>.github.io`` if it doesn't exist.
+
+    Returns the full repo name (``username/username.github.io``).
+    """
+    repo_name = f"{username}/{username}.github.io"
+
+    if repo_exists(repo_name):
+        return repo_name
+
+    _run_gh(
+        [
+            "repo",
+            "create",
+            repo_name,
+            "--public",
+            "--description",
+            "GitHub Pages site for Tesla Fleet API key hosting",
+        ]
+    )
+
+    return repo_name
+
+
+def deploy_public_key(public_key_pem: str, repo_name: str) -> None:
+    """Clone *repo_name*, add the Tesla public key, and push.
+
+    Handles:
+    - Empty repos (no initial commit)
+    - Existing ``_config.yml`` (merges ``include`` directive)
+    - Already-deployed key (skips commit if no changes)
+    """
+    with tempfile.TemporaryDirectory() as tmpdir:
+        clone_dir = Path(tmpdir) / "repo"
+        _clone_or_init(repo_name, clone_dir)
+
+        # Ensure .well-known directory structure
+        key_path = clone_dir / WELL_KNOWN_PATH
+        key_path.parent.mkdir(parents=True, exist_ok=True)
+        key_path.write_text(public_key_pem)
+
+        # Ensure _config.yml includes .well-known
+        _ensure_jekyll_config(clone_dir)
+
+        # Ensure .nojekyll exists
+        nojekyll = clone_dir / ".nojekyll"
+        if not nojekyll.exists():
+            nojekyll.touch()
+
+        # Create minimal index.html if repo is empty
+        index = clone_dir / "index.html"
+        if not index.exists():
+            index.write_text(
+                "<!DOCTYPE html>\n"
+                "<html><head><title>Tesla Fleet API</title></head>\n"
+                "<body><p>Tesla Fleet API key host.</p></body></html>\n"
+            )
+
+        # Stage all changes
+        _run_git(["add", "-A"], cwd=clone_dir)
+
+        # Check if there are changes to commit
+        status = _run_git(["status", "--porcelain"], cwd=clone_dir)
+        if not status.stdout.strip():
+            return  # Nothing to commit — key already deployed
+
+        _run_git(
+            ["commit", "-m", "Deploy Tesla Fleet API public key"],
+            cwd=clone_dir,
+        )
+        _run_git(["push", "origin", "HEAD"], cwd=clone_dir)
+
+
+def _clone_or_init(repo_name: str, clone_dir: Path) -> None:
+    """Clone the repo, handling the empty-repo case."""
+    result = _run_gh(
+        ["repo", "clone", repo_name, str(clone_dir), "--", "--depth=1"],
+        check=False,
+    )
+
+    if result.returncode == 0:
+        return
+
+    # Empty repo: gh clone fails — manually init + add remote
+    clone_dir.mkdir(parents=True, exist_ok=True)
+    _run_git(["init"], cwd=clone_dir)
+    _run_git(
+        ["remote", "add", "origin", f"https://github.com/{repo_name}.git"],
+        cwd=clone_dir,
+    )
+    # Set default branch to main
+    _run_git(["checkout", "-b", "main"], cwd=clone_dir)
+
+
+def _ensure_jekyll_config(clone_dir: Path) -> None:
+    """Ensure ``_config.yml`` includes ``.well-known`` in its ``include`` list."""
+    config_path = clone_dir / "_config.yml"
+
+    if config_path.exists():
+        content = config_path.read_text()
+        if ".well-known" in content:
+            return  # Already configured
+        # Append include directive
+        content = content.rstrip("\n") + "\n\ninclude:\n  - .well-known\n"
+        config_path.write_text(content)
+    else:
+        config_path.write_text('include:\n  - ".well-known"\n')
+
+
+# ---------------------------------------------------------------------------
+# Deployment validation
+# ---------------------------------------------------------------------------
+
+
+def get_key_url(domain: str) -> str:
+    """Return the full URL where the public key should be served."""
+    return f"https://{domain}/{WELL_KNOWN_PATH}"
+
+
+def validate_key_url(domain: str) -> bool:
+    """Return True if the public key is accessible at the expected URL."""
+    url = get_key_url(domain)
+    try:
+        resp = httpx.get(url, follow_redirects=True, timeout=10)
+        return resp.status_code == 200 and "BEGIN PUBLIC KEY" in resp.text
+    except httpx.HTTPError:
+        return False
+
+
+def wait_for_pages_deployment(
+    domain: str,
+    *,
+    timeout: int = DEFAULT_DEPLOY_TIMEOUT,
+) -> bool:
+    """Poll the key URL until it responds successfully or *timeout* elapses.
+
+    Returns True if the key became accessible, False on timeout.
+    """
+    deadline = time.monotonic() + timeout
+
+    while time.monotonic() < deadline:
+        if validate_key_url(domain):
+            return True
+        time.sleep(POLL_INTERVAL)
+
+    return False
+
+
+def get_pages_domain(repo_name: str) -> str:
+    """Infer the GitHub Pages domain from a repo name.
+
+    For ``user/user.github.io`` → ``user.github.io``.
+    For ``user/other-repo`` → ``user.github.io/other-repo`` (project page).
+
+    The result is always lowercased because the Tesla Fleet API rejects
+    domains with uppercase characters.
+    """
+    parts = repo_name.split("/", 1)
+    if len(parts) != 2:
+        raise ValueError(f"Invalid repo name: {repo_name!r}")
+
+    owner, name = parts
+    if name.lower() == f"{owner.lower()}.github.io":
+        return name.lower()
+    return f"{owner.lower()}.github.io/{name.lower()}"
+
+
+def get_repo_info(repo_name: str) -> dict[str, str]:
+    """Return basic repo metadata from the GitHub API."""
+    result = _run_gh(["repo", "view", repo_name, "--json", "name,owner,url"])
+    data: dict[str, str] = json.loads(result.stdout)
+    return data

tescmd/models/__init__.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from tescmd.models.auth import (
+    AUTH_BASE_URL,
+    AUTHORIZE_URL,
+    DEFAULT_PORT,
+    DEFAULT_REDIRECT_URI,
+    DEFAULT_SCOPES,
+    ENERGY_SCOPES,
+    PARTNER_SCOPES,
+    TOKEN_URL,
+    USER_SCOPES,
+    VEHICLE_SCOPES,
+    AuthConfig,
+    TokenData,
+    TokenMeta,
+)
+from tescmd.models.command import CommandResponse, CommandResult
+from tescmd.models.config import AppSettings, Profile
+from tescmd.models.energy import (
+    CalendarHistory,
+    EnergySite,
+    GridImportExportConfig,
+    LiveStatus,
+    SiteInfo,
+)
+from tescmd.models.sharing import ShareDriverInfo, ShareInvite
+from tescmd.models.user import FeatureConfig, UserInfo, UserRegion, VehicleOrder
+from tescmd.models.vehicle import (
+    ChargeState,
+    ClimateState,
+    DestChargerInfo,
+    DriveState,
+    GuiSettings,
+    NearbyChargingSites,
+    SoftwareUpdateInfo,
+    SuperchargerInfo,
+    Vehicle,
+    VehicleConfig,
+    VehicleData,
+    VehicleState,
+)
+
+__all__ = [
+    "AUTHORIZE_URL",
+    "AUTH_BASE_URL",
+    "DEFAULT_PORT",
+    "DEFAULT_REDIRECT_URI",
+    "DEFAULT_SCOPES",
+    "ENERGY_SCOPES",
+    "PARTNER_SCOPES",
+    "TOKEN_URL",
+    "USER_SCOPES",
+    "VEHICLE_SCOPES",
+    "AppSettings",
+    "AuthConfig",
+    "CalendarHistory",
+    "ChargeState",
+    "ClimateState",
+    "CommandResponse",
+    "CommandResult",
+    "DestChargerInfo",
+    "DriveState",
+    "EnergySite",
+    "FeatureConfig",
+    "GridImportExportConfig",
+    "GuiSettings",
+    "LiveStatus",
+    "NearbyChargingSites",
+    "Profile",
+    "ShareDriverInfo",
+    "ShareInvite",
+    "SiteInfo",
+    "SoftwareUpdateInfo",
+    "SuperchargerInfo",
+    "TokenData",
+    "TokenMeta",
+    "UserInfo",
+    "UserRegion",
+    "Vehicle",
+    "VehicleConfig",
+    "VehicleData",
+    "VehicleOrder",
+    "VehicleState",
+]

tescmd/models/auth.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import Any
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Scope constants
+# ---------------------------------------------------------------------------
+
+VEHICLE_SCOPES: list[str] = [
+    "vehicle_device_data",
+    "vehicle_cmds",
+    "vehicle_charging_cmds",
+]
+
+ENERGY_SCOPES: list[str] = [
+    "energy_device_data",
+    "energy_cmds",
+]
+
+USER_SCOPES: list[str] = [
+    "user_data",
+]
+
+PARTNER_SCOPES: list[str] = [
+    "openid",
+    *VEHICLE_SCOPES,
+    *ENERGY_SCOPES,
+    *USER_SCOPES,
+]
+
+DEFAULT_SCOPES: list[str] = [
+    "openid",
+    "offline_access",
+    *VEHICLE_SCOPES,
+    *ENERGY_SCOPES,
+    *USER_SCOPES,
+]
+
+DEFAULT_PORT: int = 8085
+DEFAULT_REDIRECT_URI: str = f"http://localhost:{DEFAULT_PORT}/callback"
+
+AUTH_BASE_URL: str = "https://auth.tesla.com"
+AUTHORIZE_URL: str = f"{AUTH_BASE_URL}/oauth2/v3/authorize"
+TOKEN_URL: str = f"{AUTH_BASE_URL}/oauth2/v3/token"
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+
+class TokenData(BaseModel, extra="allow"):
+    """Raw token response from the Tesla OAuth endpoint."""
+
+    access_token: str
+    token_type: str
+    expires_in: int
+    refresh_token: str | None = None
+    id_token: str | None = None
+    scope: str | None = None  # space-separated granted scopes (if returned by server)
+
+
+class TokenMeta(BaseModel):
+    """Metadata stored alongside the persisted token."""
+
+    expires_at: float
+    scopes: list[str]
+    region: str
+
+
+def decode_jwt_scopes(token: str) -> list[str] | None:
+    """Extract scopes from a JWT access token without verifying the signature.
+
+    Tesla access tokens are JWTs with an ``scp`` claim containing the
+    granted scopes.  Returns ``None`` if the token isn't a JWT or the
+    ``scp`` claim is absent.
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        return None
+    try:
+        # JWT uses base64url encoding; add padding for stdlib decoder
+        payload_b64 = parts[1] + "=" * (-len(parts[1]) % 4)
+        payload_bytes = base64.urlsafe_b64decode(payload_b64)
+        payload: dict[str, Any] = json.loads(payload_bytes)
+    except (ValueError, json.JSONDecodeError):
+        logger.debug("Failed to decode JWT payload")
+        return None
+
+    scp = payload.get("scp")
+    if isinstance(scp, list):
+        return [str(s) for s in scp]
+    return None
+
+
+class AuthConfig(BaseModel):
+    """Configuration needed to start an OAuth flow."""
+
+    client_id: str
+    client_secret: str | None = None
+    redirect_uri: str = DEFAULT_REDIRECT_URI
+    scopes: list[str] = DEFAULT_SCOPES

tescmd/models/command.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CommandResult(BaseModel):
+    """The inner result payload of a vehicle command."""
+
+    result: bool
+    reason: str = ""
+
+
+class CommandResponse(BaseModel):
+    """Envelope returned by the Fleet API for command endpoints."""
+
+    model_config = ConfigDict(extra="allow")
+
+    response: CommandResult