fix(ble): use False, not None, to disable command signing

An explicit `private_key=None` used to fall through to the parent's key and
raise `ValueError("No private key.")` when there was none. The sentinel
design in this PR changed that: `None` became the opt-out, so a caller who
wrote `private_key=None` meaning "I haven't got one" silently got a vehicle
that could not sign instead of the error that told them so. That is a
behaviour change on a published, security-adjacent library, not an additive
one.

Drop `KeyOmitted`/`KEY_OMITTED` and restore `None` as the default. `False` is
now the explicit "signing is disabled" value - a value no current caller can
already be passing, so opting out has to be deliberate, and `None` keeps its
existing meaning for both omitted and explicit-`None` callers.

Because `False` and `None` are both falsy, the constructor branches on
identity (`is False` / `is not None`); a truthiness check would collapse the
two states and reintroduce the bug in a new form.

`Vehicles.createBluetooth` had no `key` parameter at all, so the opt-out was
unreachable from the Fleet-parented factory; it gains one as keyword-only
(no positional shift), with the matching `NotImplementedError` overrides in
Teslemetry/Tessie kept in step with their "parameters match the Fleet API
Bluetooth factory" contract.

The `SigningDisabled` guards at `_handshake` and in `pair()`'s fast path are
unchanged.

Author: Bre77

AGENTS.md

@@ -78,7 +78,7 @@ Commands (vehicle/commands.py) - protobuf-based signed command implementation (A
 `Vehicles` (vehicle/vehicles.py) is a `dict[str, Vehicle]` with factory methods:
 - `createFleet(vin)` → `VehicleFleet`
 - `createSigned(vin)` → `VehicleSigned`
-- `createBluetooth(vin, confirmation="ack", keepalive_interval=..., raise_unconfirmed=False, *, verify_commands=None, optimistic=None)` → `VehicleBluetooth`
+- `createBluetooth(vin, confirmation="ack", keepalive_interval=..., raise_unconfirmed=False, *, verify_commands=None, optimistic=None, key=None)` → `VehicleBluetooth`
 
 Teslemetry/Tessie override `Vehicles` with their own vehicle classes (`TeslemetryVehicle`, `TessieVehicle`) extending `VehicleFleet` with service-specific commands (e.g., `closure()`, `seat_heater()` for Teslemetry; `wake()`, `lock()` for Tessie).
 
@@ -153,7 +153,7 @@ Keep the `tesla-protocol` floor at `>=0.5.0`; earlier releases have generated `.
 - **`VehicleAction`/`GetVehicleData` proto coverage is locked by test, not just by convention**: `tests/test_proto_coverage_lock.py` walks both descriptors and fails if any field has no wrapper (`commands.py`) or reader (`bluetooth.py`) and isn't on one of its two small, reasoned allowlists — keep that test in sync with any future `tesla-protocol` bump rather than special-casing new fields elsewhere. The only fields deliberately left unwrapped today are the 7-field push-style subscription/streaming family (`createStreamSession`/`streamMessage`/`vehicleDataSubscription`/`vehicleDataAck`/`vitalsSubscription`/`vitalsAck`/`cancelVehicleDataSubscription`, which need a public lifecycle/iterator API atop the private `_stream_sinks` routing above) and `getVehicleImageState` (needs chunked binary-transfer paging). CarServer's `GetVehicleState` sub-state is exposed as `legacy_vehicle_state()` (`bluetooth.py`), matching the `VehicleData.legacy_vehicle_state` reply field name, to avoid confusion with `vehicle_state()` (VCSEC `VehicleStatus`, a different message/domain). `set_rate_tariff`/`add_managed_charging_site` (`commands.py`) take `tesla_protocol` message types directly for their deeply-nested arguments rather than a parallel flattened dataclass API.
 - **Energy-gateway authorized-client pairing has security- and protocol-specific constraints**: use RSA for LAN TEDapi v1r, treat `PENDING_VERIFICATION_TIMEOUT` as terminal, and account for presence-free key removal. The authoritative pairing, retry, encoding, and removal guidance is in `docs/energy_local_control.md`; enum values and API contracts live in `const.py` and the relevant method docstrings.
 - **`register_client()` (`teslemetry/teslemetry.py`) is Teslemetry-only OAuth Dynamic Client Registration (RFC 7591)**: a module-level function, not a `Teslemetry` instance method, since registration precedes having a `client_id` or access token — callers pass a bare `aiohttp.ClientSession`. It always registers a new client (no dedup/caching) and raises `TeslemetryRegistrationError` (`exceptions.py`) on transport failure, a non-2xx response, a non-JSON body, or a response missing a usable `client_id`; a non-dict-but-valid-JSON body (list/scalar) is treated as the same malformed-response error rather than raising an uncaught `AttributeError`. Fleet API and Tessie have no equivalent — don't add one speculatively. See `docs/teslemetry.md`'s "OAuth Dynamic Client Registration" section and `tests/test_teslemetry_register_client.py`.
-- **`Commands.__init__`'s `private_key` (and `VehicleBluetooth`/`vehicles.create*`'s `key`) distinguishes omitted from explicit `None` via a sentinel default (`KEY_OMITTED`/`KeyOmitted` in `commands.py`)**: omitting the argument keeps falling back to the parent's key, raising `ValueError("No private key.")` if it has none; passing `None` explicitly disables signing for a passive BLE listener that only observes broadcasts. `self.private_key` is therefore `EllipticCurvePrivateKey | None` — `_handshake` (reached by `_command`, i.e. every signed command, and by `_ensure_handshake`, used by signed reads) raises `SigningDisabled` (`exceptions.py`) up front rather than failing deep in the signing/crypto path. `pair()`'s fast path never calls `_handshake` (it builds and sends its own whitelist request directly), so it carries its own identical guard at the top instead — `_handshake` is not a single choke point every signed-session entry point routes through; each entry point that doesn't call it needs its own `self.private_key is None` check. Tests: `tests/test_ble_null_key.py`.
+- **`False`, not `None`, is the "signing is disabled" value for `Commands.__init__`'s `private_key` (and `VehicleBluetooth.__init__`/`Vehicles.createBluetooth`/`VehiclesBluetooth.create`/`createBluetooth`'s `key`)**: `None` — the default and an explicit `None` — keeps its long-standing meaning of falling back to the parent's key, raising `ValueError("No private key.")` if it has none; `False` disables signing for a passive BLE listener that only observes broadcasts. `None` is deliberately *not* the opt-out: a caller already passing `private_key=None` to mean "I haven't got one" must keep getting that `ValueError`, not a silently unsignable vehicle. Because `False` and `None` are both falsy, every branch on this argument must test **identity** (`is False`/`is not None`) — a truthiness check (`if private_key:`) collapses the two states and reintroduces the bug. `self.private_key` is `EllipticCurvePrivateKey | None`, its `None` meaning signing-disabled — `_handshake` (reached by `_command`, i.e. every signed command, and by `_ensure_handshake`, used by signed reads) raises `SigningDisabled` (`exceptions.py`) up front rather than failing deep in the signing/crypto path. `pair()`'s fast path never calls `_handshake` (it builds and sends its own whitelist request directly), so it carries its own identical guard at the top instead — `_handshake` is not a single choke point every signed-session entry point routes through; each entry point that doesn't call it needs its own `self.private_key is None` check. Tests: `tests/test_ble_null_key.py`.
 
 ## Maintaining this file
 

docs/bluetooth_vehicles.md

@@ -577,18 +577,22 @@ message routing; `KeyboardInterrupt` and `SystemExit` still propagate.
 ### Passive listening without a private key
 
 A vehicle that only decodes broadcasts and never sends a command has no
-reason to hold a signing key. Pass `key=None` explicitly to `vehicles.create`
-(or `VehicleBluetooth` directly) to construct without one:
+reason to hold a signing key. Pass `key=False` to `vehicles.create` (or
+`VehicleBluetooth` directly) to construct without one:
 
 ```python
-vehicle = tesla_bluetooth.vehicles.create("<vin>", key=None)
+vehicle = tesla_bluetooth.vehicles.create("<vin>", key=False)
 ```
 
-Omitting `key` still falls back to the parent's private key as before -
-`key=None` must be passed explicitly to disable signing. Reads and listeners
-that don't need a signed session still work; any command that does raises
-`SigningDisabled` naming that signing was explicitly disabled for this
-vehicle.
+`key=None` - the default, and an explicit `None` - still falls back to the
+parent's private key exactly as before, raising `ValueError("No private
+key.")` if the parent has none. Only `False` disables signing, so a caller
+already passing `key=None` to mean "I haven't got one" keeps getting that
+error rather than silently ending up with a vehicle that cannot sign.
+
+Reads and listeners that don't need a signed session still work; any command
+that does raises `SigningDisabled` naming that signing was explicitly disabled
+for this vehicle.
 
 ### Connection-status events
 

tesla_fleet_api/exceptions.py

@@ -411,14 +411,14 @@ class LibraryError(Exception):
 class SigningDisabled(LibraryError):
     """A signed operation was attempted on a vehicle constructed with signing explicitly disabled.
 
-    Pass ``private_key=None`` explicitly only for a passive listener that
-    never sends a command; construct with a real key (or omit the argument to
+    Pass ``private_key=False`` only for a passive listener that never sends a
+    command; construct with a real key (or leave the argument at ``None`` to
     inherit the parent's) to issue signed commands.
     """
 
     def __init__(self) -> None:
         super().__init__(
-            "This vehicle was constructed with private_key=None, explicitly "
+            "This vehicle was constructed with private_key=False, explicitly "
             "disabling command signing. It can only observe unsolicited "
             "broadcasts (the listen_* methods); any signed command or read "
             "needs a real private_key."

tesla_fleet_api/tesla/vehicle/bluetooth.py

@@ -7,7 +7,7 @@
 import warnings
 from collections import deque
 from random import randbytes
-from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, TypeVar
 
 import bleak
 from bleak.backends.characteristic import BleakGATTCharacteristic
@@ -30,9 +30,7 @@
 )
 from tesla_fleet_api.tesla.vehicle.broadcast import BroadcastListeners, Unsubscribe
 from tesla_fleet_api.tesla.vehicle.commands import (
-    KEY_OMITTED,
     Commands,
-    KeyOmitted,
     infotainment_command_name,
     vcsec_command_name,
 )
@@ -515,7 +513,7 @@ def __init__(
         self,
         parent: BluetoothParentT,
         vin: str,
-        key: ec.EllipticCurvePrivateKey | None | KeyOmitted = KEY_OMITTED,
+        key: ec.EllipticCurvePrivateKey | Literal[False] | None = None,
         device: BLEDevice | None = None,
         confirmation: BluetoothConfirmation | bool = "ack",
         keepalive_interval: float | None = DEFAULT_KEEPALIVE_INTERVAL,
@@ -533,10 +531,10 @@ def __init__(
         ``optimistic`` wins over a ``True`` ``verify_commands`` if both are
         somehow passed, matching the old dominance order).
 
-        Passing ``key=None`` explicitly disables command signing, for a
+        Passing ``key=False`` explicitly disables command signing, for a
         passive listener that only observes broadcasts via the ``listen_*``
-        methods and never sends a command. Omitting ``key`` keeps the usual
-        fallback to the parent's key.
+        methods and never sends a command. ``key=None`` (the default, and an
+        explicit ``None``) keeps the usual fallback to the parent's key.
         """
         super().__init__(parent, vin, key)
         if isinstance(confirmation, bool):

tesla_fleet_api/tesla/vehicle/commands.py

@@ -426,15 +426,6 @@ def aes_gcm_personalized(self) -> AES_GCM_Personalized_Signature_Data:
         )
 
 
-class KeyOmitted:
-    """Sentinel distinguishing an omitted ``private_key`` argument from an explicit ``None``."""
-
-
-# Distinct from ``None`` so a caller can explicitly pass ``private_key=None`` to
-# disable signing, rather than that meaning "use the parent's key".
-KEY_OMITTED = KeyOmitted()
-
-
 class Commands(ABC, Vehicle[CommandParentT], Generic[CommandParentT]):
     """Class describing the Tesla Fleet API vehicle endpoints and commands for a specific vehicle with command signing."""
 
@@ -450,15 +441,18 @@ def __init__(
         self,
         parent: CommandParentT,
         vin: str,
-        private_key: ec.EllipticCurvePrivateKey | None | KeyOmitted = KEY_OMITTED,
+        private_key: ec.EllipticCurvePrivateKey | Literal[False] | None = None,
         public_key: bytes | None = None,
     ):
-        """Initialize with a signing key, or ``private_key=None`` to disable signing.
-
-        Omitting ``private_key`` falls back to the parent's key (raising if it
-        has none, same as always). Passing ``private_key=None`` explicitly
-        disables signing for this vehicle - for a passive BLE listener that
-        only observes broadcasts and never sends a command.
+        """Initialize with a signing key, or ``private_key=False`` to disable signing.
+
+        ``None`` (the default, and an explicit ``None``) keeps the long-standing
+        behaviour: fall back to the parent's key, raising ``ValueError`` if it
+        has none. Passing ``private_key=False`` explicitly disables signing for
+        this vehicle - for a passive BLE listener that only observes broadcasts
+        and never sends a command. ``False`` is used rather than ``None`` so
+        that no caller who already passes ``private_key=None`` meaning "I
+        haven't got one" silently gets a vehicle that cannot sign.
         """
         super().__init__(parent, vin)
 
@@ -470,13 +464,17 @@ def __init__(
             Domain.DOMAIN_INFOTAINMENT: Session(self, Domain.DOMAIN_INFOTAINMENT),
         }
 
-        if isinstance(private_key, KeyOmitted):
-            if parent.private_key:
-                self.private_key = parent.private_key
-            else:
-                raise ValueError("No private key.")
-        else:
+        # Identity checks, not truthiness: ``False`` and ``None`` are both
+        # falsy, and collapsing them would make an explicit ``None`` silently
+        # disable signing instead of falling back to the parent's key.
+        if private_key is False:
+            self.private_key = None
+        elif private_key is not None:
             self.private_key = private_key
+        elif parent.private_key is not None:
+            self.private_key = parent.private_key
+        else:
+            raise ValueError("No private key.")
 
         self._public_key = public_key or (
             self.private_key.public_key().public_bytes(

tesla_fleet_api/tesla/vehicle/vehicles.py

@@ -1,11 +1,10 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar
 
 from bleak.backends.device import BLEDevice
 from cryptography.hazmat.primitives.asymmetric import ec
 
 from tesla_fleet_api.const import BluetoothConfirmation
-from tesla_fleet_api.tesla.vehicle.commands import KEY_OMITTED, KeyOmitted
 from tesla_fleet_api.tesla.vehicle.signed import VehicleSigned
 from tesla_fleet_api.tesla.vehicle.bluetooth import (
     DEFAULT_KEEPALIVE_INTERVAL,
@@ -54,6 +53,7 @@ def createBluetooth(
         raise_unconfirmed: bool = False,
         *,
         verify_commands: bool | None = None,
+        key: ec.EllipticCurvePrivateKey | Literal[False] | None = None,
     ) -> VehicleBluetooth[FleetParentT]:
         """Creates a bluetooth vehicle that uses command protocol.
 
@@ -68,10 +68,13 @@ def createBluetooth(
         success. ``verify_commands``/``optimistic`` are deprecated aliases for
         ``confirmation="verify"``/``confirmation="optimistic"``. See
         ``VehicleBluetooth``'s docstring for the full ladder.
+        ``key=False`` explicitly disables signing, for a passive listener;
+        ``key=None`` (the default) keeps the usual parent-key fallback.
         """
         vehicle = self.Bluetooth(
             self._parent,
             vin,
+            key,
             confirmation=confirmation,
             keepalive_interval=keepalive_interval,
             optimistic=optimistic,
@@ -102,7 +105,7 @@ def __init__(self, parent: BluetoothClientT):
     def create(
         self,
         vin: str,
-        key: ec.EllipticCurvePrivateKey | None | KeyOmitted = KEY_OMITTED,
+        key: ec.EllipticCurvePrivateKey | Literal[False] | None = None,
         device: BLEDevice | None = None,
         confirmation: BluetoothConfirmation | bool = "ack",
         keepalive_interval: float | None = DEFAULT_KEEPALIVE_INTERVAL,
@@ -124,8 +127,8 @@ def create(
         success. ``verify_commands``/``optimistic`` are deprecated aliases for
         ``confirmation="verify"``/``confirmation="optimistic"``. See
         ``VehicleBluetooth``'s docstring for the full ladder.
-        ``key=None`` explicitly disables signing, for a passive listener;
-        omitting ``key`` keeps the usual parent-key fallback.
+        ``key=False`` explicitly disables signing, for a passive listener;
+        ``key=None`` (the default) keeps the usual parent-key fallback.
         """
         return self.createBluetooth(
             vin,
@@ -141,7 +144,7 @@ def create(
     def createBluetooth(
         self,
         vin: str,
-        key: ec.EllipticCurvePrivateKey | None | KeyOmitted = KEY_OMITTED,
+        key: ec.EllipticCurvePrivateKey | Literal[False] | None = None,
         device: BLEDevice | None = None,
         confirmation: BluetoothConfirmation | bool = "ack",
         keepalive_interval: float | None = DEFAULT_KEEPALIVE_INTERVAL,
@@ -163,8 +166,8 @@ def createBluetooth(
         success. ``verify_commands``/``optimistic`` are deprecated aliases for
         ``confirmation="verify"``/``confirmation="optimistic"``. See
         ``VehicleBluetooth``'s docstring for the full ladder.
-        ``key=None`` explicitly disables signing, for a passive listener;
-        omitting ``key`` keeps the usual parent-key fallback.
+        ``key=False`` explicitly disables signing, for a passive listener;
+        ``key=None`` (the default) keeps the usual parent-key fallback.
         """
         vehicle = self.Bluetooth(
             self._parent,

tesla_fleet_api/teslemetry/vehicle.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
+
+from cryptography.hazmat.primitives.asymmetric import ec
 
 from tesla_fleet_api.const import (
     BluetoothConfirmation,
@@ -673,6 +675,7 @@ def createBluetooth(
         raise_unconfirmed: bool = False,
         *,
         verify_commands: bool | None = None,
+        key: ec.EllipticCurvePrivateKey | Literal[False] | None = None,
     ) -> Any:
         """Not supported; parameters match the Fleet API Bluetooth factory."""
         raise NotImplementedError("Teslemetry cannot use local Bluetooth")

tesla_fleet_api/tessie/vehicle.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
+
+from cryptography.hazmat.primitives.asymmetric import ec
 
 from tesla_fleet_api.const import BluetoothConfirmation, Method
 from tesla_fleet_api.tesla.vehicle.vehicles import Vehicles
@@ -1222,6 +1224,7 @@ def createBluetooth(
         raise_unconfirmed: bool = False,
         *,
         verify_commands: bool | None = None,
+        key: ec.EllipticCurvePrivateKey | Literal[False] | None = None,
     ) -> Any:
         """Not supported; parameters match the Fleet API Bluetooth factory."""
         raise NotImplementedError("Tessie cannot use local Bluetooth")