ducoterra
2e79430ac7
The internal deployment exists (deployments repo, `mirror/`: quadlet, nginx edge, certbot, route53, VM SOP), so the docs that said "the real fix is HTTPS" were describing a future that has arrived from a different direction — TLS terminates in nginx on the service VM, not in this process, and there is no `--https` flag here. SECURITY.md's trust model said "trusted: anyone who can open a TCP connection". With an allow list in production that sentence was simply no longer true, so the table now names the address space, and a new section says what the list is and what it is not: one wall (network/nginx) and one belt (the app, for the path that bypasses nginx at 127.0.0.1:8080), plus the thing neither can do — once two browsers are in the room their media never asks the server again, and it can never tell you *who*, only *where from*. Saying "defence in depth" about that would have been the dishonest version. PLAN.md gains A19 (TLS + admission in production, LOCKED) and A18 becomes deprioritised rather than deleted — standalone `mirror serve --https` is still worth having for offline/ad-hoc use, it just stopped being the thing blocking cross-device sharing, and candidate phase 1 is now share-page resilience. AGENTS.md gains the two rules most likely to be broken by a well-meaning edit: trust XFF only from a trusted proxy, and change the nginx and app lists in the same commit. LLM-Generated: true
8.3 KiB
mirror — security model
mirror has no authentication. That is a design decision, not an oversight. It changes the question from "who is allowed in?" to "where is this allowed to run?". This file answers the second question honestly.
1. Trust model
| Trusted | Anyone inside the address space the server answers — with no allow list configured that is anyone who can open a TCP connection, and in the fleet deployment it is the client LAN (10.2.0.0/22) and nothing else |
| Untrusted | Anyone outside that space — including anything on the LAN that was not named in it (guest Wi-Fi, IoT VLAN, a cafe), and everything on the internet |
| Not a threat model | Malicious JavaScript served from this origin (there is only one origin and you run the server), supply-chain of a machine you already control |
The product promise is "open a URL, share your screen". Every gate we add attacks that promise, so the boundary is drawn at the network instead of the application.
Run it only on a network you control. Do not port-forward it. Do not put it behind a reverse proxy that is reachable from the internet. It has no rate limiting, no accounts, and no audit trail.
2. What an unauthenticated visitor can do
- Mirror any surface their own browser's picker offers them — to everyone else watching.
- Watch any mirror anyone else is sharing.
- Learn which device names and window titles are being shared (window titles can be sensitive: mail, tickets, filenames).
- Consume a sharer's upstream bandwidth (bounded by
MIRROR_MAX_BITRATE, per leg).
3. What they cannot do (enforced and tested)
| Guarantee | Enforcement | Test |
|---|---|---|
| No unsolicited media negotiation. A sharer cannot push an offer to a viewer who did not subscribe; a viewer cannot reach a sharer it never subscribed to | Registry.signal() allows traffic only along an existing subscription, in either direction |
test_sharer_may_not_blindly_push_to_a_stranger, test_viewer_may_not_reach_a_sharer_it_never_subscribed_to, test_signalling_a_peer_that_never_subscribed_is_refused |
| No peer-to-peer chatter between watchers. Viewer↔viewer signaling is refused outright | peer_to_peer refusal |
test_peers_may_not_talk_to_each_other_directly |
| No identity spoofing of the roster. A viewer cannot publish a mirror; a peer cannot claim another's stream | role checks (not_sharer, not_viewer), stream ids are server-assigned |
test_one_peer_cannot_impersonate_another, test_a_viewer_cannot_publish |
| No oversized signaling. Frames above 64 KiB are dropped before parsing | MAX_MESSAGE_BYTES |
test_an_oversized_frame_is_refused |
| No protocol fuzzing into a crash. Bad JSON, non-object frames, unknown types and unknown roles produce an error frame; only fatal ones close the socket | Hub.serve/_dispatch |
TestSignalingSocket |
| No leaked peer connections. Every teardown path notifies every viewer | Registry._drop_stream, leave() |
test_sharer_disconnect_removes_the_mirror, test_unpublish_clears_the_tile_for_every_viewer |
| Nothing leaves the network. No CDN, no remote font, no analytics, no STUN by default | A10/A4 + a build-failing test | test_nothing_is_loaded_from_a_cdn, test_config_does_not_leak_server_secrets |
| The server cannot see your screen. Media is SRTP between peers; the server relays JSON only | A3 | Architectural: no media code exists in Python |
4. Platform realities you should tell users about
Screen capture requires a secure context
getDisplayMedia() exists only in a secure context. http://localhost qualifies;
http://192.168.x.x does not — the browser hides the API entirely. The
/mirror page detects this and prints the three ways forward:
- Share from the machine running the server, via
http://localhost:8055/mirror. - Put TLS in front of it. This is no longer a plan: the fleet deployment
terminates HTTPS in nginx on the service VM (
https://mirror.reeseapps.com), so every device there can share.mirror serve --httpsfor standalone use is still open (A18). - Per-device and explicit:
chrome://flags/#unsafely-treat-insecure-origin-as-securewith the exact origin, then reload.
Option 3 is a deliberate, per-device, user-granted exception. Do not automate it on someone else's machine without telling them what it does: it marks that origin as trusted for powerful APIs, permanently, on that profile.
Access control is an address list, not an account
Because there is nothing to log in with, the source address decides everything. That makes the list strong and also makes it the only thing standing between a stranger and every screen in the building, so treat it as the security boundary it is:
| Layer | Mechanism | Bypass it and you have |
|---|---|---|
| Network | routing / firewall, allow/deny in nginx |
nothing — this is the wall |
| App | MIRROR_ALLOW_CIDRS in the container |
a process already running on the server host |
The app layer exists because a container port can be reached without going
through the proxy (127.0.0.1:8080 on the service VM). It judges the
X-Forwarded-For value only from an address in MIRROR_TRUSTED_PROXIES, and
the proxy must overwrite that header (proxy_set_header X-Forwarded-For $remote_addr) rather than append, so a browser cannot write its own pass. What
the app layer cannot do is resist someone who already has code on the server: at
that height they can forge the header, so it is a second lock on the outside door
and not a host firewall. Say that plainly rather than implying defence in depth
where there is one wall and one belt.
Two things the address list does not do, both inherent to WebRTC:
- Once two browsers are in the room, their media flows directly between them and never consults the server again. Admission to the roster is admission to the stream.
- It cannot tell you who is watching — only where from. Device labels are self-reported and cosmetic; never treat one as an identity.
Wayland asks every time; X11 does not
On X11/Xorg, Chromium uses its native capturer: the picker appears and that is all.
On Wayland (GNOME/KDE), Chromium routes capture through xdg-desktop-portal.
The compositor shows its own permission dialog and, depending on the portal, may
ask for each share rather than remembering. Expect a native prompt — that is
the compositor protecting the user, and mirror must not try to work around it.
/watch is unaffected: receiving never needs permission.
Audio
Sharing tab/window audio is opt-in in the browser's own picker. mirror falls back to silent capture when the source has no audio rather than failing the share, and viewers start muted (autoplay policy) and must tap to unmute — a deliberate, user-initiated action.
5. Operational guidance
- Name the networks, do not just bind.
--allow-cidr 10.2.0.0/22(orMIRROR_ALLOW_CIDRS) is the setting that actually restricts who, whereasMIRROR_HOSTonly restricts which interface.MIRROR_HOST=0.0.0.0with an allow list is the deployment shape;MIRROR_HOST=127.0.0.1is how you keep a dev instance to yourself. - A refusal should explain itself. A refused client gets a 403 naming the networks that are allowed and the address that was judged — because "not allowed" in front of a proxy is undiagnosable otherwise. Keep that behaviour if you touch the gate.
- Firewall the port. Restrict 8055 to the LAN range you actually want:
firewall-cmd --add-rich-rule='rule family=ipv4 source address=192.168.1.0/24 port port=8055 protocol=tcp accept' - Cap the blast radius.
MIRROR_MAX_MIRRORSlimits concurrent mirrors;MIRROR_MAX_BITRATEbounds per-viewer upload. - Egress stays closed. The container image makes no outbound connections; do not add STUN unless you are deliberately bridging VLANs.
- Assume window titles are public. Say so before you mirror a desktop full of private windows.
- Rotating peer ids are not anonymity. Peer ids are random per socket, but a sharer's IP is visible to every watcher on the network by design (that is how peer-to-peer works).
6. Reporting
Treat anything that breaks a guarantee in §3 as a security bug, even if it "only" lets one watcher see a mirror they did not subscribe to. Add a failing test first — the guarantees above are tests, not prose.