Security model

A process that mirrors your microphone, watches your screen and injects keystrokes is a remote-takeover primitive the moment it is reachable. Everything below is default-on and not configurable in the loosening direction.

Loopback only

Every listener — control port and every media port — binds 127.0.0.1, never 0.0.0.0. This is enforced at net.Listen time, in code, not by a config flag someone can flip.

No token, no start

serve and start refuse to run without a token. There is no anonymous mode and no development bypass.

device-bridge serve --port 9330

refusing to start without a token: pass --token or set WINDOWCTL_TOKEN

The token comes from --token or the WINDOWCTL_TOKEN environment variable.

Prefer the environment variable

A token in argv is visible to every process on the machine via ps. The environment variable is the safer path. (Its name still says WINDOWCTL — this product was extracted from windowctl and the variable has not been renamed.)

Token on the control handshake

The first message on the control port must be a hello carrying the token. The comparison is constant-time; a mismatch closes the connection. No retry budget, no error detail that helps an attacker.

One-time tickets on the media ports

When the control plane starts a stream it mints a ticket for that stream and returns it with the allocated port. The media port rejects any connection that does not present it. So compromising a media port number gets you nothing: the port is allocated on demand, and the ticket is single-use.

On the standalone path (start <stream> --port N) there is no control connection to mint against, so the media port is gated by the token directly as a query parameter.

Privileged operations are explicit verbs

Installing the virtual audio driver copies a bundle into /Library/Audio/Plug-Ins/HAL and restarts coreaudiod. That needs sudo and it changes the machine for every user. It is therefore its own verb — device-bridge install audio — never something a stream start does implicitly.

OS permissions are gates, not suggestions

• Accessibility gates keyboard and mouse injection.
• Screen Recording gates ScreenCaptureKit.
• System audio capture gates non-silent speaker loopback.

A missing grant produces an explicit error. The one exception is macOS’s own behaviour on system-audio capture, which returns silence rather than an error — documented on the status page precisely because it is the failure mode that looks like success.

Remote exposure

If this is ever reachable from outside the machine, that must be a deliberate, short-lived tunnel that is torn down afterwards — never a standing unauthenticated listener. This organisation has already been burned by exactly that pattern: an unauthenticated bridge left running for days behind a public tunnel. It is written into ADR 0008 so it is not rediscovered the hard way.

Full decision record

ADR 0008 in the repository, including the negative tests spike S6 asserts: that a non-loopback bind never happens, that a media connection without a valid ticket or token is refused, and that a bad or absent control token is refused.