Security

This document describes the security architecture Duplex implements today, the threats it was designed around, and the gaps that remain. It does not promise more than the code does. To report a vulnerability, see SECURITY.md.

Principles

1. Capability, not identity. There are no accounts. Possessing a room link is the only credential for entering a room.
2. Least data on the server. The server relays negotiation and routes helper messages. It never receives media, file contents, or pointer/keyboard payloads meant for the peer.
3. Consent before power. Remote control needs an explicit, temporary, scoped Allow from the person being controlled.
4. Every layer re-validates. The Worker, the browsers and the native helper each validate what they receive; none trusts another's checks.
5. No unattended access. There is no background start, saved room credential, persistent pairing, "always allow" or trusted-contact list.

Rooms

TURN credentials

• The long-lived Cloudflare TURN key ID and API token live only in Worker secrets. They are never in the web bundle, .env files consumed by the web build, room links or signaling messages.
• The Worker calls Cloudflare's credential API and sends only the generated short-lived ICE username and credential (12-hour TTL, refreshed an hour before expiry through the joined WebSocket, at most once a minute per participant) to joined participants.
• The response is validated: only Cloudflare STUN and turn(s):turn.cloudflare.com URLs with credentials are accepted; anything else degrades to STUN-only.
• Failures are logged without the token or any credential (covered by a test).

Helper pairing

Control sessions

A control session is created only after the peer's control-request and the controlled user's explicit Allow.

• Surface-bound. Each shared screen has a cryptographically random surface ID. A grant names one surface; a new share is a new surface and any previous grant is dead.
• controlSessionId. Every grant has its own random ID. The helper rejects input for any other ID (WrongSession).
• Scoped permissions. Scopes are pointer, keyboard and clipboard; none implies another. The macOS helper advertises only what it can execute right now, the controller can request only advertised scopes, and the controlled browser never grants more than that. The sharer sees each requested scope and must explicitly Allow it.
• Expiry. A grant expires automatically (maximum CONTROL_SESSION_MAX_AGE_MS, 10 minutes); an unanswered request times out after 30 seconds.
• Revocation. The session ends on: either browser releasing, the helper's own Stop control button, expiry, the shared screen ending or changing, loss of Accessibility or the selected display, peer disconnect, or helper disconnect.
• Native hold safety. Ending a session, quitting the helper, or a revoke calls release_all, which releases every held mouse button and key. A failed release is not retried; held state is cleared as the session ends.

Helper independent validation

The helper is the last line of defense and does not trust the browser or the room server. Before posting any event it checks, in this order: message size and shape (is_valid), active session, controlSessionId, surfaceId, expiry, the matching pointer or keyboard scope, strictly increasing sequence, macOS Accessibility trust (re-checked on a short interval), a selected display, and a rate limit (240 events/s; button-up and key-up releases are exempt so a release is never dropped). Pointer coordinates are normalized 0..1 and mapped to the selected display only at the last step. Keyboard events accept only an explicit physical-key allowlist; system and application shortcuts are blocked except common text-editing shortcuts. Accessibility is required, and the helper never prompts for it on launch or pairing — only from an explicit button.

Clipboard text

Clipboard sync is an independent scope with its own checks at every layer.

• Consent. The controller must name clipboard in the request. The sharer's dialog describes it and starts it unticked; ControlService.allow() with no explicit choice never includes it. Pointer or keyboard grants cannot authorize it, and a clipboard grant cannot move the pointer or press a key (tested in the browser and in Rust).
• Per-operation checks, controlled browser. Active controlled session, matching session and surface IDs, unexpired, clipboard in the granted scopes, helper connected, local capability still advertised, strictly increasing sequence, a transfer ID not seen before, and a 500 ms minimum interval with one operation in flight.
• Per-operation checks, helper. is_valid (UUIDs, size, text rules), active session, session, surface, expiry, clipboard scope, backend support, a transfer ID not seen in this session (64 remembered) and a minimum interval. A read is also re-authorized after the OS call returns, so a stop during the call returns no text.
• Reading the sharer's clipboard additionally needs the sharer's click on Share once, every time. An unanswered request is declined after 30 seconds.
• Bounded, text-only payload. 4096 UTF-8 bytes, no control characters except tab/CR/LF, well-formed Unicode. The same rules are enforced by the shared Zod schema, the browser service and the Rust parser.
• Transport. Controller ↔ sharer travels over the reliable duplex-input DataChannel (frames ≤ 16 KiB). The sharer's browser hands the text to its own helper through the Worker, which only relays it (≤ 16 KiB, only to the owner's helper, only the helper's answer back to the owner) and never stores, logs or forwards it to the peer. The text never enters analytics; there is none.
• No content in status. Status replies (delivered, declined, denied, …) carry no clipboard content. The sharer's UI shows lengths, never text.
• Lifecycle. Revocation, expiry, a changed share, a closed channel or a peer change clear pending requests, approvals and any received-but-not-copied text, and reset the sequence and replay windows.
• Capability. The helper advertises clipboard only where a backend exists (macOS). Other platforms never advertise it, and a request for it is rejected.

The helper reads and writes the pasteboard with /usr/bin/pbpaste and /usr/bin/pbcopy by absolute path, with a cleared environment, a 3-second timeout and a size cap on reads. Nothing watches the clipboard, keeps history or logs content.

Server-directed and peer-directed messages

A helper can send only helper-ready, helper-capabilities, helper-stop-control and helper-clipboard-result (text only with a successful read); anything else (including attempts to inject participant traffic) closes it. Messages are size-limited (128 KiB for participants, 4 KiB for helpers, 1 KiB for helper-input, 512 B for input envelopes, 16 KiB for clipboard frames).

Threat model

Web security headers

Production responses (SSR and static assets) ship:

• Content-Security-Policy — default-src 'self', no remote scripts, object-src 'none', base-uri 'self', frame-ancestors 'none', and connect-src limited to the app and the configured signaling origin (HTTP and WS forms).
• Permissions-Policy — camera, microphone and display capture only for the app itself; geolocation, payment and USB denied. Clipboard read and write are allowed for the app itself only because the manual clipboard actions need them; browsers still prompt, and nothing reads the clipboard outside a click.
• Strict-Transport-Security, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer.

These are exercised by pnpm e2e:production, which builds the real Worker output and runs a full call (hydration, signaling WebSocket, microphone, WebRTC, screen share) failing on any CSP violation. The protocol package runs Zod with code generation disabled so the policy needs no 'unsafe-eval'.

Script CSP: hashes, no 'unsafe-inline'

script-src is 'self' plus SHA-256 hashes, never 'unsafe-inline' or 'unsafe-eval'. Angular's renderer emits two inline executable scripts (the event-replay contract and the window.__jsaction_bootstrap(...) call that registers event types); the hydration state is a non-executable application/json block that CSP does not apply to.

• Why hashes, not a nonce. The landing page is prerendered and served by Cloudflare static assets without running the Worker, so it cannot carry a per-response nonce. A static nonce would be reusable and therefore worthless. Hashes cover prerendered and SSR pages with one mechanism.
• SSR responses: a Nitro plugin (apps/web/src/server/plugins/csp-script-hashes.ts) hashes the scripts in the rendered HTML and appends them to that response's Content-Security-Policy.
• Prerendered pages: scripts/apply-static-csp.mjs runs after the build and writes the hashes of every prerendered page into _headers.
• Only Angular's scripts are hashed. The extractor accepts exactly the contract script (by its id) and a strictly shaped bootstrap call. Any other inline script, including one injected into the markup, is not hashed and the browser blocks it (verified in pnpm e2e:production).
• style-src still allows 'unsafe-inline' because Angular applies component styles inline. That is a separate, weaker gap: it cannot execute script.

Worker message rate limiting

Each WebSocket gets in-memory token buckets inside the CallRoom Durable Object (apps/worker/src/rate-limit.ts). Nothing is stored, shared between connections, keyed by address or user, or logged beyond which kind of connection hit which limit. State is dropped when the socket closes; hibernation resets a bucket to full, which only happens to idle sockets.

Rejection is predictable: a message over its category budget is dropped; 25 consecutive drops, or any frame past the frame bucket, closes the connection with code 4008 (Rate limit exceeded). Closing a participant also closes its helper and notifies the peer; closing a helper tells its owner (helper-disconnected), so a flood always ends with control revoked, never left running. Revocation, leave and the helper's Stop have their own buckets that bulk traffic cannot drain, and a legitimate ICE gathering fits inside the signaling burst. Malformed and unknown messages already closed the socket and are additionally charged to the frame bucket. No protocol change: clients see an ordinary close.

Tauri helper boundary

The helper window has a single capability granting exactly ten permissions: core:event:allow-listen, core:event:allow-unlisten (the UI only listens for state pushes) and allow-* for its eight own commands. It no longer inherits core:default, so the page cannot call window, webview, app, path, menu, tray, resource or image APIs. There are no shell, filesystem, process, HTTP, opener or other plugins, no remote capabilities and no global Tauri object; its CSP forbids eval, unsafe-inline scripts, remote origins, connect-src, framing and form posts. pnpm check:tauri audits this (including the command lists in build.rs and lib.rs) and its tests in scripts/check-tauri-security.test.mjs prove each loosening is rejected. CI compiles the crate on Linux and macOS, which validates the capability against the real command manifest; it cannot prove the packaged UI works with the narrower grant, and that still needs the manual macOS check in docs/testing.md.

Known gaps

• Rate limits are per connection, not per room or per client: someone who reconnects gets a fresh budget. The Worker still bounds frame size, room capacity and join admission.
• No room lock or admission prompt: whoever arrives first with the link takes a free seat.
• Pairing tokens are visible in the sharer's browser for up to two minutes.
• Native control is macOS-only and has not been audited by a third party.
• Clipboard text moves through the Worker (transiently, to the owner's own helper) between the sharer's browser and helper; it is not stored, but it is not end-to-end encrypted beyond TLS on that hop.
• The macOS clipboard backend has not been verified on hardware.