tescmd 0.1.2__py3-none-any.whl

tescmd/protocol/__init__.py

@@ -0,0 +1,23 @@
+"""Vehicle Command Protocol — ECDH sessions + HMAC-signed protobuf commands."""
+
+from tescmd.protocol.commands import (
+    COMMAND_REGISTRY,
+    CommandSpec,
+    get_command_spec,
+    get_domain,
+    requires_signing,
+)
+from tescmd.protocol.protobuf.messages import Domain, MessageFault
+from tescmd.protocol.session import Session, SessionManager
+
+__all__ = [
+    "COMMAND_REGISTRY",
+    "CommandSpec",
+    "Domain",
+    "MessageFault",
+    "Session",
+    "SessionManager",
+    "get_command_spec",
+    "get_domain",
+    "requires_signing",
+]

tescmd/protocol/commands.py

@@ -0,0 +1,175 @@
+"""Command registry: maps REST command names to protocol domain + payload builders.
+
+Each command has a domain (VCSEC, INFOTAINMENT, or UNSIGNED) and a builder
+function that converts the JSON body dict into protobuf payload bytes.
+
+For the Vehicle Command Protocol, the payload is either:
+  - An Infotainment ``Action`` protobuf (for car-server commands)
+  - A VCSEC ``UnsignedMessage`` protobuf (for security commands)
+  - None for unsigned commands (wake_up)
+
+Since we don't have full protobuf generation, the payload is currently
+passed through as JSON-encoded bytes. The ``signed_command`` endpoint
+accepts both protobuf and JSON payloads — the protobuf wrapping in
+RoutableMessage is what matters for authentication.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from tescmd.protocol.protobuf.messages import Domain
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """Specification for a vehicle command."""
+
+    domain: Domain
+    requires_signing: bool = True
+    action_type: str = ""  # Protobuf action type identifier
+
+
+# ---------------------------------------------------------------------------
+# VCSEC commands (security domain)
+# ---------------------------------------------------------------------------
+
+_VCSEC_COMMANDS: dict[str, CommandSpec] = {
+    "door_lock": CommandSpec(Domain.DOMAIN_VEHICLE_SECURITY, action_type="RKE_ACTION_LOCK"),
+    "door_unlock": CommandSpec(Domain.DOMAIN_VEHICLE_SECURITY, action_type="RKE_ACTION_UNLOCK"),
+    "actuate_trunk": CommandSpec(Domain.DOMAIN_VEHICLE_SECURITY),
+    "open_tonneau": CommandSpec(Domain.DOMAIN_VEHICLE_SECURITY),
+    "close_tonneau": CommandSpec(Domain.DOMAIN_VEHICLE_SECURITY),
+    "stop_tonneau": CommandSpec(Domain.DOMAIN_VEHICLE_SECURITY),
+    "remote_start_drive": CommandSpec(Domain.DOMAIN_VEHICLE_SECURITY),
+    "auto_secure_vehicle": CommandSpec(
+        Domain.DOMAIN_VEHICLE_SECURITY, action_type="RKE_ACTION_AUTO_SECURE_VEHICLE"
+    ),
+}
+
+# ---------------------------------------------------------------------------
+# Infotainment commands (car-server domain)
+# ---------------------------------------------------------------------------
+
+_INFOTAINMENT_COMMANDS: dict[str, CommandSpec] = {
+    # Charging
+    "charge_start": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "charge_stop": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "charge_standard": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "charge_max_range": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "charge_port_door_open": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "charge_port_door_close": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_charge_limit": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_charging_amps": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_scheduled_charging": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_scheduled_departure": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "add_precondition_schedule": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remove_precondition_schedule": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "batch_remove_precondition_schedules": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "add_charge_schedule": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remove_charge_schedule": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "batch_remove_charge_schedules": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    # Climate
+    "auto_conditioning_start": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "auto_conditioning_stop": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_temps": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_preconditioning_max": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remote_seat_heater_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remote_seat_cooler_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remote_steering_wheel_heater_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_cabin_overheat_protection": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_climate_keeper_mode": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_cop_temp": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remote_auto_seat_climate_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remote_auto_steering_wheel_heat_climate_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remote_steering_wheel_heat_level_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_bioweapon_mode": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    # Security (infotainment-routed)
+    "set_sentry_mode": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_valet_mode": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "reset_valet_pin": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "speed_limit_activate": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "speed_limit_deactivate": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "speed_limit_set_limit": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "speed_limit_clear_pin": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "reset_pin_to_drive_pin": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "clear_pin_to_drive_admin": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "speed_limit_clear_pin_admin": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "flash_lights": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "honk_horn": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "set_pin_to_drive": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "guest_mode": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "erase_user_data": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "remote_boombox": CommandSpec(Domain.DOMAIN_INFOTAINMENT, requires_signing=False),
+    # Media
+    "media_toggle_playback": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "media_next_track": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "media_prev_track": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "media_next_fav": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "media_prev_fav": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "media_volume_up": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "media_volume_down": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "adjust_volume": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    # Navigation
+    "share": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "navigation_gps_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "navigation_sc_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "trigger_homelink": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "navigation_waypoints_request": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    # Software
+    "schedule_software_update": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "cancel_software_update": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    # Vehicle name / calendar
+    "set_vehicle_name": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "upcoming_calendar_entries": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    # Windows / sunroof
+    "window_control": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "sun_roof_control": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    # Power management
+    "set_low_power_mode": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+    "keep_accessory_power_mode": CommandSpec(Domain.DOMAIN_INFOTAINMENT),
+}
+
+# ---------------------------------------------------------------------------
+# Unsigned commands (no signing required)
+# ---------------------------------------------------------------------------
+
+_UNSIGNED_COMMANDS: dict[str, CommandSpec] = {
+    "wake_up": CommandSpec(Domain.DOMAIN_BROADCAST, requires_signing=False),
+    "set_managed_charge_current_request": CommandSpec(
+        Domain.DOMAIN_BROADCAST, requires_signing=False
+    ),
+    "set_managed_charger_location": CommandSpec(Domain.DOMAIN_BROADCAST, requires_signing=False),
+    "set_managed_scheduled_charging_time": CommandSpec(
+        Domain.DOMAIN_BROADCAST, requires_signing=False
+    ),
+}
+
+# ---------------------------------------------------------------------------
+# Unified registry
+# ---------------------------------------------------------------------------
+
+COMMAND_REGISTRY: dict[str, CommandSpec] = {
+    **_VCSEC_COMMANDS,
+    **_INFOTAINMENT_COMMANDS,
+    **_UNSIGNED_COMMANDS,
+}
+
+
+def get_command_spec(command: str) -> CommandSpec | None:
+    """Look up a command specification by REST command name."""
+    return COMMAND_REGISTRY.get(command)
+
+
+def get_domain(command: str) -> Domain | None:
+    """Return the domain for a command, or None if unknown."""
+    spec = COMMAND_REGISTRY.get(command)
+    return spec.domain if spec else None
+
+
+def requires_signing(command: str) -> bool:
+    """Return True if the command requires a signed channel."""
+    spec = COMMAND_REGISTRY.get(command)
+    if spec is None:
+        return False  # Unknown commands fall through to unsigned path
+    return spec.requires_signing

tescmd/protocol/encoder.py

@@ -0,0 +1,122 @@
+"""RoutableMessage assembly and base64 encoding for the signed_command endpoint."""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+
+from tescmd.protocol.protobuf.messages import (
+    Destination,
+    Domain,
+    HMACPersonalizedData,
+    KeyIdentity,
+    RoutableMessage,
+    SessionInfoRequest,
+    SignatureData,
+)
+
+
+def build_session_info_request(
+    *,
+    domain: Domain,
+    client_public_key: bytes,
+) -> RoutableMessage:
+    """Build a session handshake request message.
+
+    Parameters
+    ----------
+    domain:
+        Target domain (VCSEC or INFOTAINMENT).
+    client_public_key:
+        65-byte uncompressed EC public key (``0x04 || X || Y``).
+
+    Returns
+    -------
+    RoutableMessage
+        Ready to serialize → base64 → POST.
+    """
+    return RoutableMessage(
+        to_destination=Destination(domain=domain),
+        from_destination=Destination(routing_address=client_public_key),
+        session_info_request=SessionInfoRequest(public_key=client_public_key),
+        uuid=os.urandom(16),
+    )
+
+
+def build_signed_command(
+    *,
+    domain: Domain,
+    payload: bytes,
+    client_public_key: bytes,
+    epoch: bytes,
+    counter: int,
+    expires_at: int,
+    hmac_tag: bytes,
+) -> RoutableMessage:
+    """Build a signed command message.
+
+    Parameters
+    ----------
+    domain:
+        Target domain (VCSEC or INFOTAINMENT).
+    payload:
+        Serialized protobuf command (Action or UnsignedMessage).
+    client_public_key:
+        65-byte uncompressed client public key.
+    epoch:
+        Session epoch identifier from handshake.
+    counter:
+        Monotonically increasing counter.
+    expires_at:
+        Command expiration in vehicle epoch-relative seconds.
+    hmac_tag:
+        Computed HMAC-SHA256 tag from :func:`~tescmd.protocol.signer.compute_hmac_tag`.
+
+    Returns
+    -------
+    RoutableMessage
+        Ready to serialize → base64 → POST.
+    """
+    return RoutableMessage(
+        to_destination=Destination(domain=domain),
+        from_destination=Destination(routing_address=client_public_key),
+        protobuf_message_as_bytes=payload,
+        signature_data=SignatureData(
+            signer_identity=KeyIdentity(public_key=client_public_key),
+            hmac_personalized_data=HMACPersonalizedData(
+                epoch=epoch,
+                counter=counter,
+                expires_at=expires_at,
+                tag=hmac_tag,
+            ),
+        ),
+        uuid=os.urandom(16),
+    )
+
+
+def encode_routable_message(msg: RoutableMessage) -> str:
+    """Serialize and base64-encode a RoutableMessage for the API."""
+    return base64.b64encode(msg.serialize()).decode("ascii")
+
+
+def default_expiry(clock_offset: int = 0, ttl_seconds: int = 15) -> int:
+    """Return a command expiry timestamp in the vehicle's epoch-relative time.
+
+    The Go SDK computes ``ExpiresAt = clockTime + elapsed + TTL`` where
+    ``clockTime`` comes from the vehicle's SessionInfo.  Our Session stores
+    ``clock_offset = clockTime - local_time_at_handshake``, so::
+
+        expires_at = now + clock_offset + TTL
+                   = now + (clockTime - handshake_time) + TTL
+                   ≈ clockTime + TTL   (when sent shortly after handshake)
+
+    Parameters
+    ----------
+    clock_offset:
+        ``session.clock_offset`` — the difference between the vehicle's
+        epoch clock and the local wall clock at handshake time.
+    ttl_seconds:
+        Time-to-live in seconds (default 15).
+    """
+    return int(time.time()) + clock_offset + ttl_seconds

tescmd/protocol/metadata.py

@@ -0,0 +1,116 @@
+"""TLV (tag-length-value) metadata serialization for command authentication.
+
+The metadata block is a sequence of TLV entries that are fed into the HMAC
+alongside the payload.  Each entry is ``tag(1B) || length(1B) || value``.
+Tags must appear in ascending order.  A TAG_END (0xFF) entry terminates the
+metadata before the payload.
+
+Tags (from Tesla's vehicle-command ``signatures.proto`` Tag enum):
+  - 0x00: signature_type (1 byte — SignatureType enum value)
+  - 0x01: domain (1 byte — numeric Domain enum value, e.g. 3 for INFOTAINMENT)
+  - 0x02: personalization (variable-length — VIN string)
+  - 0x03: epoch (variable-length bytes from vehicle)
+  - 0x04: expires_at (4 bytes, big-endian uint32 — seconds since Unix epoch)
+  - 0x05: counter (4 bytes, big-endian uint32 — anti-replay)
+  - 0x06: challenge (variable-length — BLE challenge, not used for REST)
+  - 0x07: flags (4 bytes, big-endian uint32)
+  - 0xFF: end (0 bytes — terminates metadata)
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tescmd.protocol.protobuf.messages import Domain
+
+# TLV tag constants (from signatures.proto Tag enum)
+TAG_SIGNATURE_TYPE = 0x00
+TAG_DOMAIN = 0x01
+TAG_PERSONALIZATION = 0x02
+TAG_EPOCH = 0x03
+TAG_EXPIRES_AT = 0x04
+TAG_COUNTER = 0x05
+TAG_CHALLENGE = 0x06
+TAG_FLAGS = 0x07
+TAG_END = 0xFF
+
+# SignatureType values (from signatures.proto SignatureType enum)
+SIGNATURE_TYPE_HMAC_PERSONALIZED = 8
+
+
+def encode_tlv(tag: int, value: bytes) -> bytes:
+    """Encode a single TLV entry: tag(1B) || length(1B) || value."""
+    if len(value) > 255:
+        raise ValueError(f"TLV value too long ({len(value)} bytes, max 255)")
+    return bytes([tag, len(value)]) + value
+
+
+def encode_metadata(
+    *,
+    epoch: bytes,
+    expires_at: int,
+    counter: int,
+    domain: Domain,
+    vin: str,
+    flags: int = 0,
+) -> bytes:
+    """Encode the full metadata block as a sequence of TLV entries.
+
+    The metadata is fed into the HMAC hash alongside the command payload.
+    Tags must appear in ascending order and are terminated by TAG_END.
+
+    Parameters
+    ----------
+    epoch:
+        Session epoch identifier (variable-length bytes from vehicle).
+    expires_at:
+        Command expiration time (seconds since Unix epoch).
+    counter:
+        Monotonically increasing counter for anti-replay.
+    domain:
+        The routing domain (VCSEC or INFOTAINMENT).
+    vin:
+        The vehicle identification number (17 chars).
+    flags:
+        Optional flags (default 0).
+
+    Returns
+    -------
+    bytes
+        Concatenated TLV entries (TAG_END is NOT included — the signer
+        adds a bare 0xFF separator between metadata and payload).
+    """
+    parts = bytearray()
+    parts.extend(encode_tlv(TAG_SIGNATURE_TYPE, bytes([SIGNATURE_TYPE_HMAC_PERSONALIZED])))
+    # Domain is encoded as a single byte (numeric enum value), matching the Go SDK:
+    #   meta.Add(TAG_DOMAIN, []byte{byte(x.Domain)})
+    parts.extend(encode_tlv(TAG_DOMAIN, bytes([int(domain)])))
+    parts.extend(encode_tlv(TAG_PERSONALIZATION, vin.encode()))
+    parts.extend(encode_tlv(TAG_EPOCH, epoch))
+    parts.extend(encode_tlv(TAG_EXPIRES_AT, struct.pack(">I", expires_at)))
+    parts.extend(encode_tlv(TAG_COUNTER, struct.pack(">I", counter)))
+    if flags:
+        parts.extend(encode_tlv(TAG_FLAGS, struct.pack(">I", flags)))
+    # NOTE: TAG_END is NOT included here.  The Go SDK's Checksum() writes a
+    # bare 0xFF byte (no length byte) between metadata and payload when
+    # computing the HMAC.  compute_hmac_tag() handles this separator.
+    return bytes(parts)
+
+
+def decode_metadata(data: bytes) -> dict[int, bytes]:
+    """Decode a TLV metadata block into a {tag: value} dict."""
+    result: dict[int, bytes] = {}
+    pos = 0
+    while pos < len(data):
+        if pos + 2 > len(data):
+            break
+        tag = data[pos]
+        length = data[pos + 1]
+        pos += 2
+        if pos + length > len(data):
+            break
+        result[tag] = data[pos : pos + length]
+        pos += length
+    return result