CodeNomad/dev-docs/REMOTE_CONTROL.md
Pascal André d045d0357b
fix(server): pin proxy destinations before connecting (#1543)
Pin resolved proxy destinations and refuse connections to backend
listeners, including DNS aliases.
Apply the boundary to preview HTTP/WebSockets, asset fallback and
SideCars; retain ordinary dev-server connections.
Verified: server typecheck; 208 focused tests; CI server glob
concurrency 4: 4444 passed, 25 skipped, 0 failed; 31 help tests.
2026-11-16 05:02:20 +01:00

239 lines
16 KiB
Markdown

# Remote Control
Remote Control reaches CodeNomad from another device without an inbound port.
Keep it independent of direct `--host` access; never fall back between them.
```text
browser ─TLS─▶ OpenTunnel relay (forwards ciphertext) ─▶ OpenTunnel SDK in the backend (TLS ends here)
─TCP─▶ remote-only loopback ingress ─▶ remote gate ─▶ the normal CodeNomad application
```
## Transport
- `packages/remote-tunnel` wraps `@opentunnel/client` behind CodeNomad-owned
types. The server build bundles it with its resolved Effect copy into
`dist/remote-control/tunnel-runtime.js`; never give the published server a
runtime dependency on the private workspace package.
- CodeNomad claims one random route (`codenomad-<hex>`, persisted) on the
device's shared `default` identity. OpenCode's `opencode pair --remote` and
the OpenTunnel CLI use the same identity with their own routes. Stopping
closes CodeNomad's bridge only and never calls `tunnel.remove()`.
- The relay observes hostnames, connection timing and sizes; TLS keeps traffic encrypted.
Impersonating the host requires a misissued certificate for the
tunnel hostname, which would appear in Certificate Transparency logs.
`opentunnel.xyz` is on the Public Suffix List, so other users' tunnels are
cross-site; OpenCode's route on the same device is same-site, so mutations
check `Origin` rather than rely on `SameSite`.
- First use provisions the identity and its certificate (about 30 seconds);
the start request waits up to five minutes.
- Start records the choice in the registry file and only Stop clears it. A
launch after Start reconnects in the background (`manager.resume()`) and
issues no pairing code; shutdown, a fatal tunnel stop and a failed resume keep
the choice, so the next launch retries. Only one backend per config
directory resumes (`remote-control.owner`, live-PID lease replaced after a
crash): OpenTunnel gives a route to one bridge and a contender retries until
it takes over, so a second backend would otherwise silently serve the paired
devices. An explicit Start always proceeds. Settings polls the status only while
the tunnel is (re)connecting, keeps paired devices listed while it is off and
offers Stop after a failed resume.
- Keep OpenTunnel's per-route PROXY protocol off: the ingress expects plain
HTTP.
## Administrator policy
`server/network-policy.ts` reads two variables from the environment the backend
inherits, so machine-wide values reach every desktop launch and the UI cannot
override them. An unknown value refuses startup.
- `CODENOMAD_REMOTE_CONTROL=disabled`: the manager opens no tunnel, skips the
launch resume (keeping the registry's choice), refuses Start and pairing links
(`403`, `code: "remote_control_disabled"`) and authorizes no device. Its status
carries `disabledByAdministrator`; Settings shows that state, hides Start,
pairing and previews, and keeps paired devices listed for revocation.
- `CODENOMAD_LOCKED_HOST=<address>`: the listening address, validated like
`--host`, wins over `--host`, `CLI_HOST` and the desktop listening switch (the
hosts still pass their own `--host`). `ServerMeta.listeningLocked` disables the
switch in Remote Access settings. An intranet address keeps direct access for
colleagues; `127.0.0.1` keeps it on this machine.
## Admission
`server/src/remote-control/`:
- `ingress.ts` marks every accepted socket as remote before any request is
parsed and routes requests into the same Fastify application, with the
local listener's timeouts (no request timeout, 72 s keep-alive). Its only
WebSocket endpoints are web previews: `gate.ts` `admitRemoteUpgrade()` parses
the target as the preview proxy does, then the manager hands the socket to the
application's path-preview upgrade handler, never to the shared upgrade event.
Every other upgrade gets 404.
- `request-origin.ts` is the only authority for local privileges:
`isLocalRequest()` requires a loopback peer **and** a non-ingress socket.
- The direct listener applies the shared host-only paths to every non-local
request, including encoded route targets and SideCar WebSocket upgrades.
Direct password login, its page and logout remain available to LAN clients.
`GET /api/remote-control/status` is available to authenticated clients and
returns `manageable: false` for non-local peers. SideCar registration APIs remain
available to authenticated clients; content and WebSockets require loopback,
except under the host's SideCar opt-in below.
Live preview capabilities retain their scoped admission. `/api/meta` reports
`localRequest` using that same transport authority; the UI hides password changes
and remote-server management unless it is true. `/api/meta` also reports
`sidecarsAllowed` (local, or admitted by the opt-in); the UI shows SideCar opening
and the picker only when it or `localRequest` is true.
- SideCar opt-in over direct HTTPS: the host setting `server.sidecarsOverDirectHttps`
(`config.yaml`, off unless `true`; **Settings → SideCars → Open SideCars over HTTPS**,
shown to local clients only) lifts the host-only gate for `/sidecars/` content and
SideCar WebSocket upgrades, and nothing else, for a direct-listener request from a
verified direct HTTPS origin (`server/sidecar-direct-https.ts`). The origin rule is
`remote-control/direct-https.ts`: the `https:` advertised local/remote URLs, reachable
addresses and `CODENOMAD_ALLOWED_ORIGINS` entries, never loopback or unspecified
hosts; mutations need their own `Origin`; GET/HEAD/OPTIONS use `Origin`, else the
`Referer` origin, else `https://` plus `Host`; ingress sockets never qualify. Plain-HTTP
LAN, loopback-alias and foreign or opaque origins stay refused. Authentication, the
direct source policy, SideCar cookie stripping and WebSocket Origin/Referer checks
still apply. Admission reads the setting from `config.yaml` as it is now
(`SettingsService.serverFlag`, `settings/server-flag-reader.ts`: re-parsed when its stat
signature changes; missing, unreadable or invalid reads as off), never the display cache,
so a host edit applies to the next request. The config routes refuse a change to this key
from non-local requests with 403 (`settings/host-only-settings.ts`), including deleting
the server owner, judged against the authoritative document each write starts from.
- `gate.ts` runs before CORS, authentication and routing. It requires the exact
tunnel `Host` and the public `Origin` on browser mutations, and strips forwarding
headers. It accepts origin-form targets only (no absolute-form, leading `//`
or fragment, which the router would reinterpret) and judges the path the
router routes (`server/routed-path.ts`). It denies host-only paths: login and token
bootstrap, Remote Control management, remote windows/proxy, SideCar content,
previews and the automation bridge. A live `/previews/<token>/…` capability
is admitted without a device cookie or public `Origin` (its sandboxed document
sends neither) while the host's **Web previews** switch is on, the default:
`devices.ts` stores only the opt-out, `PUT /api/remote-control/previews` is
host-only, and turning it off also closes live preview WebSockets. Remote
`/api/meta` reports `previewsUnavailable` while it is off, so the UI hides
its preview entry. Static UI bundle files stay public, as
on local listeners, because browsers fetch the PWA manifest without cookies.
Every other path requires a paired device. Refusals close the connection,
because an unread body would otherwise break the client's next keep-alive
request.
- Server-to-server `POST /api/remote-control/pair` accepts a valid one-use
code with no Origin, Referer or browser fetch metadata. Browser pairing
supplies the exact tunnel Origin. Other tunnel mutations require that Origin.
- A remote `/api/auth/status` without a valid device reports
`pairingRequired`. The recovery dialog then explains how to pair again
instead of offering password login, keeping the page and its drafts.
Pairing from another tab restores it on the next check.
- `devices.ts` issues one five-minute, single-use pairing code. The link carries
it in the fragment, never in the query or a log. It stores SHA-256 hashes of
device credentials and expires devices after 30 days without use.
`__Host-codenomad_device` is `Secure; HttpOnly; SameSite=Lax`. Revocation,
and replacement of the least recently seen device at the 32-device limit,
also destroy that device's open connections. The registry file is written
only once Remote Control is used.
- Remote devices authenticate even with `--dangerously-skip-auth`, and the
local session cookie is never accepted on the ingress.
- A desktop CodeNomad pairs as a device: pasting a pairing link into Add server
saves only the tunnel origin and opens the remote window once on the link
(`lib/remote-pairing-link.ts`). The profile keeps TLS verification on, since
a Tauri TLS-proxy window uses an incognito store without the device cookie.
The code is never stored with the server;
re-pairing a saved server reuses its window storage, which keeps the device
cookie across launches. Covered by `tests/browser/remote-server-pairing.test.ts`.
- `--connect-server` opens a saved server or URL at launch through that same
connect flow ([architecture.md](architecture.md#native-profiles-windows-and-client-state)).
It refuses URLs with user info or a fragment, so a pairing code or password
never travels on a command line; pair from Add server instead.
## Direct listener origins and password sessions
The direct listener grants credentialed CORS to its advertised local and remote
origins, reachable interface addresses and explicit `CODENOMAD_ALLOWED_ORIGINS`.
This environment variable is a comma-separated list of exact HTTP(S) origins,
for example `https://code.example.test,https://ui.example.test:8443`. Paths,
credentials, opaque origins and wildcards fail startup. Configure DNS aliases,
reverse-proxy public origins and separately hosted UIs here, then restart.
Forwarding headers grant neither origins nor local privileges; a proxy connected
over loopback has the privileges of its loopback transport and needs an enforcing
trusted perimeter. The configured UI development origin is admitted for local
requests. A same-origin local request (Origin equal to the targeted Host) also
reaches the listening socket under the loopback names its bind address covers,
with the socket's protocol and port: `localhost` for `127.0.0.1` and `::1`, plus
`127.0.0.1` for `0.0.0.0`, plus `[::1]` for `::`. An alias page targeting another
authority stays cross-origin, since the name can resolve to a sibling listener.
Configured and development origins stay exact; their ports open no loopback
alias. CORS for opaque preview documents is scoped to live preview capabilities.
Preview capability admission requires the matched route's `previewCapability`
configuration; a capability Host on an ordinary application route retains that
route's authentication, origin and host-only checks.
Outbound HTTP proxies and preview/SideCar WebSockets resolve their destination
once and connect only to those pinned answers while retaining the target's HTTP Host
and TLS identity. `server/proxy-destination.ts` refuses any destination address/port
covered by a live backend listener, including sibling HTTP/HTTPS listeners,
remote proxy session HTTPS listeners and the Remote Control ingress. Unspecified
destinations (`0.0.0.0`, `::` and mapped forms) match every local listener on
that port. Wildcard binds cover loopback and the host's current interface
addresses. Other loopback ports and LAN applications remain eligible.
Direct state-changing requests check Origin first, then the origin of Referer
when Origin is absent. Non-local mutations require an allowed source; native
loopback calls may omit both. Read-only methods are GET, HEAD and OPTIONS.
Authentication and the host-only gate also apply with explicitly allowed origins;
`--dangerously-skip-auth` retains the origin and host-only gates.
SideCar WebSocket upgrades apply this same Origin/Referer policy before opening
an upstream connection, alongside their loopback transport (or the host's direct
HTTPS opt-in) and session checks.
Native loopback upgrades may omit both source headers. Preview WebSockets use
their scoped capability admission.
Password sessions expire after 24 hours without an authenticated request and
after seven days from creation. `CODENOMAD_SESSION_IDLE_SECONDS` and
`CODENOMAD_SESSION_ABSOLUTE_SECONDS` configure positive integer lifetimes in
seconds at startup. Logout revokes its current token; a successful persistent
password change revokes every session for that user, including the caller.
A failed password change preserves the existing sessions. Remote Control device
credentials follow their separate registry lifetime and revocation rules.
## Validation
- `remote-surface.test.ts` drives the real `createHttpServer` through the
ingress. It covers unpaired access, pairing, `Origin`/`Host` checks,
host-only paths including encoded ones, loopback privileges, spoofed headers,
upgrades, web previews and their switch, revocation of a live stream, skipped
local auth and tunnel failure.
- `server/preview-proxy-boundary.test.ts` uses simulated DNS and local listeners
to check refusal before upstream contact, password-enabled and skipped-auth
previews, capability hosts, Referer fallback, SideCar HTTP and both WebSocket
proxies, unspecified destinations, bound-interface matching and a pinned
ordinary dev-server connection. `server/__tests__/remote-proxy.test.ts`
checks registration of the remote proxy session's HTTPS listener.
- `direct-listener.test.ts` exercises the real application with LAN and loopback
peers, credentialed CORS, Origin/Referer checks and host-only routes.
`server/__tests__/sidecar-proxy.test.ts` covers SideCar upgrade source checks,
refusal before upstream contact, authenticated and skipped-auth exchanges,
native origin-less calls and logout revocation, and the direct HTTPS opt-in for
content and upgrades. `remote-control/direct-https.test.ts` covers the verified
origin rule, the opt-in's `/api/meta` matrix, the other host-only paths and the
ingress; `routes/settings.test.ts` covers the host-only setting guard and config writes
that start from the file on disk. The SideCar and settings tests use the real settings
service and edit `config.yaml` as the host would, including revocation after the display
cache loaded the opt-in.
`session-manager.test.ts` covers idle/absolute deadlines, configuration and
revocation; `auth-responsiveness.test.ts` covers logout and password replacement
through real auth routes alongside concurrent credential checks.
- `manager.test.ts` covers resuming after a restart, Stop, never-started
installations, failed resumes and backends sharing a configuration;
`owner-lease.test.ts` the lease; `tests/browser/remote-control-settings.test.ts`
the settings panel after a failed, skipped or slow resume and across a reconnect.
- `scripts/remote-control-live.test.ts` (opt-in,
`CODENOMAD_REMOTE_CONTROL_LIVE=1`) repeats the flow through the hosted
relay, using a throwaway profile and data directory, and deletes that tunnel
afterwards. It creates a public, certificate-logged hostname.
- The packaged smoke test imports the packaged server with each host's server
runtime: Tauri's bundled Node, or the Electron executable with
`ELECTRON_RUN_AS_NODE=1` and `ELECTRON_NO_ASAR=1`.
## Agent conventions
- Remote Access settings put Remote Control first. Direct/LAN access (listening mode, server password, reachable addresses) sits in one collapsed disclosure that opens by itself while the server listens beyond localhost. Its texts refer to direct connections only, because Remote Control pairs devices and needs neither a password nor an open port. It uses the shared `.settings-disclosure` (`styles/components/settings-disclosure.css`).
- The tunnel runtime (`build:remote-tunnel`) keeps its own backend-side Effect runtime, separate from OpenCode's native plugin graph. Ingress sockets are remote by membership: grant local privileges only through `isLocalRequest()`/`isLoopbackRequest()`, never peer addresses or headers. The resume lease lives in `owner-lease.ts`; never auto-start an installation that was not started. Run the Validation tests above when changing the transport.