fix(carla): keep driver endpoint ids out of the public status

demo/carla/README.md

@@ -98,7 +98,7 @@ A bystander's e-stop, a command the gate refused, or an accepted `respawn`
 ```json
 { "accepted": { "steering": .., "throttle": .., "brake": .., "gear": ".." },
   "autonomy": "autonomous|manual", "estopped": true,
-  "driver": "driver-ab12cd", "estop_by": "driver-ef34gh",
+  "driver": "driver-3eb1bd43", "estop_by": "driver-9c0a7f12",
   "map": "Town10HD_Opt",
   "pose": { "x": 12.35, "y": -78.9, "yaw": 180.1, "speed": 9.88 },
   "measured": { "steering": .., "throttle": .., "brake": .., "gear": ".." },
@@ -149,15 +149,17 @@ The worker's gate (`sim/moq_carla_sim/drive.py`) owns every truck's controls:
   e-stop latched, that has not moved 2 m in 5 minutes of a running world
   returns to a free spawn point under autonomy, its e-stop cleared.
 
-The lease is cooperative. Anonymous drivers share one grant, publish
-`carla/.socket/driver-*`, so anyone can announce an endpoint under the id that
-`status` names as the holder. That never continues the holder's lease, since a
-lease is one session, but it can disrupt it: the relay may route the truck's
-accept of the holder's next session to the impostor. Truck names must not look
-like driver ids, or the same grant would let anyone impersonate a truck; the
-worker refuses one. So the lease stops two honest drivers fighting over a
-truck, not a deliberate disruption. Anything beyond a simulator needs
-per-driver tokens scoped to the driver's own endpoint.
+The lease is cooperative. Anonymous drivers share one grant to publish
+`carla/.socket/driver-*`, so an endpoint id is all it takes to announce in a
+driver's place and win the relay's route to its next dial. Each driver's id is
+therefore 128 random bits, and `status` names the holder and the e-stop's
+sender by a handle instead: `driver-` and 8 hex digits of the SHA-256 of the
+session's secret id, which the driver derives the same way to recognize its
+own lease. Truck names must not look like driver ids, or the same grant would
+let anyone impersonate a truck; the worker refuses one. Anyone may still claim
+a free truck or press its e-stop, so the lease stops two honest drivers
+fighting over a truck, not a deliberate disruption. Anything beyond a simulator
+needs per-driver tokens scoped to the driver's own endpoint.
 
 ## The simulator
 

demo/carla/sim/moq_carla_sim/drive.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import hashlib
 from dataclasses import dataclass, field, replace
 from enum import Enum
 from typing import Literal
@@ -23,6 +24,16 @@ class Gear(str, Enum):
     REVERSE = "reverse"
 
 
+def handle(session: str) -> str:
+    """The name `status` gives the lease or e-stop a session carried.
+
+    A hash of the session id, which only that session's two ends know, so the
+    driver recognizes its own lease while no viewer learns its endpoint id,
+    which anyone could announce to take the route to that driver's next dial.
+    """
+    return "driver-" + hashlib.sha256(session.encode()).hexdigest()[:8]
+
+
 def _clamp(value: float, low: float, high: float) -> float:
     return max(low, min(high, value))
 
@@ -94,11 +105,12 @@ class Command:
     `drive`, `estop`, `reset_estop`, and `respawn` arrive on the wire;
     `driver_left` and `watchdog_expired` are synthesized locally.
 
-    `driver_id` is the driver's socket endpoint id, which `status` echoes.
+    `driver_id` is the driver's socket endpoint id, which stays private.
     `session` is the socket session that carried it, one per lease the player
     takes: the same id on another session is a different driver for the lease.
-    The session id is the secret that keeps a session to its two ends, so it
-    never leaves this process.
+    The session id is the secret that keeps a session to its two ends, so only
+    its `handle` leaves this process. Only a locally synthesized command has
+    none.
     """
 
     kind: CommandKind
@@ -117,12 +129,9 @@ class Drive:
 
     The lease binds to the driver's socket session, so a driver whose session
     ends loses it, and another session claiming the same driver id is another
-    driver. It is still cooperative, not enforced: anonymous drivers share one
-    grant, so anyone can announce an endpoint under the holder's id, which the
-    public `status` track echoes. Their own sessions never continue the
-    holder's lease, but they can disrupt it: a relay may route the truck's
-    accept of the holder's next session to the impostor instead. This stops two
-    honest drivers colliding; it does not stop a deliberate disruption.
+    driver. `driver` and `estop_by` are session handles, never endpoint ids, so
+    the public `status` track gives nobody an id to announce in the holder's
+    place.
     """
 
     def __init__(self) -> None:
@@ -135,7 +144,8 @@ def __init__(self) -> None:
 
     @property
     def driver(self) -> str | None:
-        return self._driver
+        """The lease holder's handle, or None while nobody holds it."""
+        return None if self._session is None else handle(self._session)
 
     @property
     def state(self) -> DriveState:
@@ -147,6 +157,7 @@ def estopped(self) -> bool:
 
     @property
     def estop_by(self) -> str | None:
+        """The handle of the session that latched the e-stop."""
         return self._estop_by
 
     def holds(self, command: Command) -> bool:
@@ -159,7 +170,8 @@ def accepted(self) -> Accepted:
     def apply(self, command: Command) -> bool:
         """Apply a command, returning whether it changed or refreshed state."""
         if command.kind == "drive":
-            if self._estopped or not (self._driver is None or self.holds(command)):
+            # A lease binds to a session, so a command without one cannot hold it.
+            if command.session is None or self._estopped or not (self._driver is None or self.holds(command)):
                 return False
             claiming = self._driver is None
             self._driver = command.driver_id
@@ -187,8 +199,8 @@ def apply(self, command: Command) -> bool:
             # legitimately claimed.
             self._state = DriveState.stopped()
             self._estopped = True
-            if not was_estopped:
-                self._estop_by = command.driver_id
+            if not was_estopped and command.session is not None:
+                self._estop_by = handle(command.session)
 
         elif command.kind == "reset_estop":
             if not self._estopped:

demo/carla/sim/moq_carla_sim/publish.py

@@ -233,7 +233,7 @@ def _parse_timestamps(raw: Any) -> tuple[TimestampEntry, ...]:
     return tuple(entries.values())
 
 
-def parse_command(driver_id: str, message: Any, session: str | None = None) -> Command | None:
+def parse_command(driver_id: str, message: Any, session: str) -> Command | None:
     """Turn one control message from a driver's session into a Command.
 
     Returns None for anything unrecognized. A driver is an untrusted publisher,

demo/carla/sim/tests/test_drive.py

@@ -4,31 +4,32 @@
 
 import pytest
 
-from moq_carla_sim.drive import Command, Drive, DriveState, Gear
+from moq_carla_sim.drive import Command, Drive, DriveState, Gear, handle
 
 
 def drive(driver_id: str, sequence: int, throttle: float) -> Command:
     return Command(
         kind="drive",
         driver_id=driver_id,
+        session=driver_id,
         sequence=sequence,
         state=DriveState(throttle=throttle, brake=0.0),
     )
 
 
 def estop(driver_id: str, sequence: int) -> Command:
-    return Command(kind="estop", driver_id=driver_id, sequence=sequence)
+    return Command(kind="estop", driver_id=driver_id, session=driver_id, sequence=sequence)
 
 
 def reset(driver_id: str, sequence: int) -> Command:
-    return Command(kind="reset_estop", driver_id=driver_id, sequence=sequence)
+    return Command(kind="reset_estop", driver_id=driver_id, session=driver_id, sequence=sequence)
 
 
 def test_first_driver_keeps_control() -> None:
     state = Drive()
     assert state.apply(drive("first", 1, 0.5))
     assert not state.apply(drive("second", 2, 1.0))
-    assert state.driver == "first"
+    assert state.driver == handle("first")
     assert state.state.throttle == 0.0
     assert state.state.brake == 1.0
     assert state.apply(drive("first", 2, 0.6))
@@ -46,14 +47,32 @@ def test_the_lease_belongs_to_one_session_of_a_driver() -> None:
     assert not state.apply(second)
     assert state.state.throttle == 0.5
     assert not state.apply(Command(kind="driver_left", driver_id="abc", session="s2"))
-    assert state.driver == "abc"
+    assert state.driver == handle("s1")
 
     # The first session leaving frees the lease for the second.
     assert state.apply(Command(kind="driver_left", driver_id="abc", session="s1"))
     assert state.driver is None
     assert state.apply(second)
     assert state.holds(second)
-    assert state.driver == "abc"
+    assert state.driver == handle("s2")
+
+
+def test_status_names_sessions_by_a_handle_the_player_derives_too() -> None:
+    """The handle, never the endpoint id, names the holder and the e-stop's sender.
+    `web/src/paths.test.ts` pins the player to the same handle for this session."""
+    state = Drive()
+    session = "0123456789abcdef0123456789abcdef"
+    assert state.apply(Command(kind="drive", driver_id="driver-holder", session=session))
+    assert state.apply(Command(kind="estop", driver_id="driver-holder", session=session))
+    assert state.driver == state.estop_by == "driver-3eb1bd43"
+
+
+def test_a_command_without_a_session_takes_no_lease_but_still_stops() -> None:
+    state = Drive()
+    assert not state.apply(Command(kind="drive", driver_id="driver"))
+    assert state.driver is None
+    assert state.apply(Command(kind="estop", driver_id="driver"))
+    assert state.estopped and state.estop_by is None
 
 
 def test_estop_latches_until_explicit_reset() -> None:
@@ -81,11 +100,11 @@ def test_disconnect_does_not_clear_estop() -> None:
     assert state.apply(drive("driver", 1, 1.0))
     assert state.apply(estop("driver", 2))
     assert state.estopped
-    assert state.driver == "driver"
+    assert state.driver == handle("driver")
 
     # The driver disconnects: the lease releases but the latch must persist, so
     # the truck stays stopped until an explicit reset.
-    assert state.apply(Command(kind="driver_left", driver_id="driver"))
+    assert state.apply(Command(kind="driver_left", driver_id="driver", session="driver"))
     assert state.estopped
     assert state.driver is None
 
@@ -97,33 +116,34 @@ def test_estop_from_a_bystander_latches_without_transferring_the_lease() -> None
     # Anyone may hit the big red button, so the latch must engage...
     assert state.apply(estop("second", 2))
     assert state.estopped
-    assert state.estop_by == "second"
+    assert state.estop_by == handle("second")
 
     # ...but the lease stays with "first".
-    assert state.driver == "first"
+    assert state.driver == handle("first")
 
     # The holder's own e-stop does not replace the actor that originally
     # latched the stop.
     assert state.apply(estop("first", 3))
-    assert state.estop_by == "second"
+    assert state.estop_by == handle("second")
     assert state.holds(estop("first", 3))
 
     # Anyone may clear the global latch, but doing so does not transfer the
     # lease.
     assert state.apply(reset("second", 4))
     assert not state.estopped
     assert state.estop_by is None
-    assert state.driver == "first"
+    assert state.driver == handle("first")
     assert not state.apply(drive("second", 5, 1.0))
 
 
 def test_axes_are_clamped_into_range() -> None:
     state = Drive()
-    assert state.apply(Command(kind="drive", driver_id="driver", sequence=1))
+    assert state.apply(Command(kind="drive", driver_id="driver", session="driver", sequence=1))
     assert state.apply(
         Command(
             kind="drive",
             driver_id="driver",
+            session="driver",
             sequence=2,
             state=DriveState(steering=-4.0, throttle=9.0, brake=-1.0, gear=Gear.FORWARD),
         )
@@ -143,6 +163,7 @@ def test_every_new_lease_resets_pedals_without_changing_steering_or_gear(gear: G
     command = Command(
         kind="drive",
         driver_id="driver",
+        session="driver",
         sequence=1,
         state=DriveState(steering=0.3, throttle=1.0, brake=0.0, gear=gear),
     )
@@ -172,7 +193,12 @@ def test_every_new_lease_resets_pedals_without_changing_steering_or_gear(gear: G
 def test_takeover_brake_allows_a_forward_claim_without_autonomous_feedback() -> None:
     state = Drive()
     assert state.apply(
-        Command(kind="drive", driver_id="driver", state=DriveState(throttle=0.85, brake=0.0, gear=Gear.FORWARD))
+        Command(
+            kind="drive",
+            driver_id="driver",
+            session="driver",
+            state=DriveState(throttle=0.85, brake=0.0, gear=Gear.FORWARD),
+        )
     )
     assert state.state == DriveState(gear=Gear.FORWARD)
 
@@ -185,6 +211,7 @@ def test_gear_change_requires_brake_and_released_throttle() -> None:
         Command(
             kind="drive",
             driver_id="driver",
+            session="driver",
             sequence=1,
             state=DriveState.stopped(),
         )
@@ -194,6 +221,7 @@ def test_gear_change_requires_brake_and_released_throttle() -> None:
         Command(
             kind="drive",
             driver_id="driver",
+            session="driver",
             sequence=2,
             state=DriveState(throttle=0.0, brake=0.0, gear=Gear.FORWARD),
         )
@@ -204,6 +232,7 @@ def test_gear_change_requires_brake_and_released_throttle() -> None:
         Command(
             kind="drive",
             driver_id="driver",
+            session="driver",
             sequence=3,
             state=DriveState(throttle=0.01, brake=0.001, gear=Gear.FORWARD),
         )
@@ -214,6 +243,7 @@ def test_gear_change_requires_brake_and_released_throttle() -> None:
         Command(
             kind="drive",
             driver_id="driver",
+            session="driver",
             sequence=4,
             state=DriveState(throttle=0.02, brake=1.0, gear=Gear.REVERSE),
         )

demo/carla/sim/tests/test_publish.py

@@ -6,7 +6,7 @@
 import pytest
 
 from moq_carla_sim import publish
-from moq_carla_sim.drive import Command, Drive, DriveState, Gear, TimestampEntry
+from moq_carla_sim.drive import Command, Drive, DriveState, Gear, TimestampEntry, handle
 from moq_carla_sim.publish import (
     Collision,
     Motion,
@@ -56,6 +56,7 @@ def test_malformed_timestamp_does_not_drop_driver_command() -> None:
                 {"label": "received", "ts": 12.5},
             ],
         },
+        "s1",
     )
 
     assert command is not None
@@ -69,6 +70,7 @@ def test_only_the_players_pipeline_stages_are_kept() -> None:
     command = parse_command(
         "driver",
         {"type": "drive", "sequence": 1, "timestamps": [*stages, *junk, {"label": "received", "ts": 9.0}]},
+        "s1",
     )
 
     assert command is not None
@@ -79,7 +81,7 @@ def test_only_the_players_pipeline_stages_are_kept() -> None:
 
 
 def test_respawn_command_is_carla_only_control_input() -> None:
-    command = parse_command("driver", {"type": "respawn", "sequence": 8})
+    command = parse_command("driver", {"type": "respawn", "sequence": 8}, "s1")
 
     assert command is not None
     assert command.kind == "respawn"
@@ -287,7 +289,7 @@ async def scenario(endpoint: Endpoint, drivers, commands: asyncio.Queue, gate: D
         session.send(DRIVE)
         command = await next_command(commands, gate)
         assert (command.kind, command.driver_id, command.session) == ("drive", "driver-abc", "s1")
-        assert gate.driver == "driver-abc"
+        assert gate.driver == handle("s1")
 
         session.end()
         left = await next_command(commands, gate)
@@ -352,7 +354,7 @@ async def scenario(endpoint: Endpoint, drivers, commands: asyncio.Queue, gate: D
 
         second.end()
         assert (await next_command(commands, gate)).kind == "driver_left"
-        assert gate.driver == "driver-abc"
+        assert gate.driver == handle("s1")
         assert gate.holds(Command(kind="drive", driver_id="driver-abc", session="s1"))
 
     asyncio.run(serving(scenario, monkeypatch))