Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs(live-links): the security hardening — address bar, timed lock, sealed unlock, names, poll

reviewadfd15037c72
diff --git a/CLAUDE.md b/CLAUDE.md
index 9f77920eb..e89eb9e0c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6828,7 +6828,17 @@ one is Pro and the backend is the gate. Reference: **`docs/live-links.md`**. Inv
- The Control password is a scrypt hash only (no plaintext kept or logged anywhere; every scrypt run in
one FIFO gate of 2; `timingSafeEqual`). Host throttles: 1 attempt per 2 s per viewer, 3 wrong end the
connection, 10 wrong across the link lock it (lock AND count persisted in the record, so a restart
- resets neither; only Allow control again clears the lock; it and a new password reset the count).
+ resets neither; it and a new password reset the count). The lock LIFTS BY ITSELF (L2: any link
+ holder could otherwise lock control for everyone for good): 15 min for the first since the owner last
+ allowed control, doubling per lock, capped at 24 h; `lockedUntil` and `lockStep` are persisted (a
+ restart neither lifts it early nor makes it permanent; a lapsed one is lifted at launch BEFORE the host
+ is built; a lock written without `lockedUntil` still waits for the owner). Allow control again lifts
+ it at once and resets the count AND the backoff. Viewers are told `lockedForMs`; the owner's notice
+ names who tipped it (a claim). The unlock is SEALED to a per-connection X25519 key pair offered in that
+ connection's meta (`unlockKey`, `shared/watch-link/unlock-seal.ts`, L3), because every link holder can
+ derive the tunnel's keys; the client seals by itself and never sends the password in the clear on a
+ connection that offered a key; a plain unlock (an older page) is still accepted, except on a
+ connection that already sealed one. Typed input is NOT sealed (residual, docs).
Owner changes go by direction: narrowing (typing off, a new password) applies at once and is NEVER
undone by a failed or hung write — the brake must not fail open; the owner is told `'unsaved'` (holds
until a restart unless a later write lands; Stop ends it for good) — widening (typing on, allow again)
@@ -6863,7 +6873,12 @@ one is Pro and the backend is the gate. Reference: **`docs/live-links.md`**. Inv
`unsupported` until it has a license layer (`src/main/watch-link-wiring.test.ts`).
- `src/shared/watch-link/` is vendored byte for byte into nodeterm-web: siblings and `tweetnacl` only,
no Node API, type imports spelled `import type` (`isomorphism.guard.test.ts`); a change there owes the
- web repo a re-vendor. Chat text is stripped of controls AND bidi controls there, capped by code point.
+ web repo a re-vendor. Chat text is stripped of controls AND bidi controls there, capped by code point;
+ a NAME also loses every format character (`\p{Cf}`) and the blank letters, so look-alike names are
+ equal (L4); chat TEXT keeps only ZWJ and ZWNJ of the format characters (emoji, Persian/Indic).
+- The viewer page strips the secret fragment from the address bar after reading it (L1): kept in the
+ tab's `sessionStorage` (`nodeterm.watchLink.<linkId>`) for a reload, a Copy link button rebuilds it;
+ where storage cannot be written the fragment stays. A full link's status poll is 60 s (L6).
- Never silent about what a viewer gets. The session host's read-only client is a negotiated
`watch-attach` attachment (no claim, no pause ticket, host refuses its writes, never spawns, never
indexed as the node's session; an older host means refused, never an ordinary attach). Where local
diff --git a/docs/live-links.md b/docs/live-links.md
index a44c2af6e..9f49f4020 100644
--- a/docs/live-links.md
+++ b/docs/live-links.md
@@ -73,7 +73,14 @@ hosted scheduler and the REAL browser client `connectWatchClient` over an in-pro
`linkId` is 16 random bytes chosen by the **server** (base64url, 22 chars): it names a link and
unlocks nothing. `S` is 32 random bytes chosen by the **host** (base64url, 43 chars), carried in the
**fragment**, so it never reaches an HTTP request, a server log or a referrer. `1.` versions the
-fragment format. The fragment is not removed from the address bar (the link must stay copyable).
+fragment format. **The viewer page takes the fragment out of the address bar** once it has read it
+(finding L1): it keeps the fragment in `sessionStorage` under `nodeterm.watchLink.<linkId>` and
+`history.replaceState`s the URL to the bare path, so a browser's history (and the history it syncs to
+other devices) holds `/s/<linkId>`, which unlocks nothing. A reload in that tab restores the link from
+`sessionStorage`; a **Copy link** button rebuilds the full link from memory, because the address bar no
+longer holds it. Where `sessionStorage` cannot be written (blocked storage), the fragment stays in the
+address bar as before: a reload must keep working. A bare `/s/<linkId>` opened in a new tab says the
+link is incomplete and how to get the whole one.
Everything is derived from `S` (`keys.ts`), hash-based and synchronous so Node and the browser compute
identical bytes:
@@ -106,17 +113,25 @@ The viewer protocol's namespace is **`watch:`**, never `watchLink:`. The owner's
which `relay-host` refuses from every peer as host-only BEFORE any policy runs, so a viewer cast in that
namespace could never arrive.
-Host → viewer: `ev watch:meta {v, role, label, title, expiresAt, cols, rows, control?}` (after EVERY
-join, not only the first: the page leaves "waiting" on a meta; `expiresAt` is `null` for an Unlimited
-link; `control`, this viewer's control state, only on a Control link), pty output as binary
+Host → viewer: `ev watch:meta {v, role, label, title, expiresAt, cols, rows, control?, history?,
+unlockKey?}` (after EVERY join, not only the first: the page leaves "waiting" on a meta; `expiresAt` is
+`null` for an Unlimited link; `control`, this viewer's control state, and `unlockKey`, the connection's
+unlock key (see "The password"), only on a Control link), pty output as binary
`encodePtyData` frames, `ev pty:size:<sid>`, `ev watch:keyframe {sessionId, screen, altScreen,
cursor?}`, `ev watch:chat`, `ev watch:waiting {}`, `ev watch:end {reason}`, and on a Control link
-`ev watch:control {state, reason?}` (to ONE viewer: the answer to its unlock, or a change under it)
+`ev watch:control {state, reason?, lockedForMs?}` (to ONE viewer: the answer to its unlock, or a change
+under it; `lockedForMs` beside `locked` says when a timed lock lifts)
and `ev watch:typing {names}` (to every joined viewer). Viewer → host: `cast watch:chat {name, text}`
(Commenter and Control; `sanitizeChatText` / `sanitizeChatName` bound the raw value by code point
before cleaning, drop C0/C1 controls and the bidi controls, and cap at 500 / 32 UTF-16 units without
-splitting a surrogate pair — the same functions the viewer page runs), and on a Control link only
-`cast watch:unlock {name, password}`, `cast watch:input {data}` and `cast watch:release`, plus
+splitting a surrogate pair — the same functions the viewer page runs. A NAME also loses every other
+invisible character, all of Unicode's format characters (Cf: zero-width space and joiners, word joiner,
+soft hyphen, tag characters) and the letters that draw as blank space (the Hangul fillers, the Braille
+blank, the combining grapheme joiner), so two names that look alike are alike (finding L4). Chat TEXT
+loses the same format characters but the two joiners writing needs: U+200D holds emoji sequences
+together and U+200C spells Persian and the Indic scripts), and on a Control link only
+`cast watch:unlock {sealed: {key, nonce, box}}` (or, from a page older than sealing,
+`{name, password}`), `cast watch:input {data}` and `cast watch:release`, plus
`trust:confirm` and keepalives. **There is no resize, mouse or flow message in the protocol, and
input is accepted only from a viewer that unlocked a Control link** (the paste-framing contract is
written beside `WATCH_INPUT_CAST` in `protocol.ts`). Every addition is additive, so
@@ -406,6 +421,25 @@ Control is per CONNECTION, never per session or per person: a reconnect unlocks
~82 ms on libuv's 4-thread pool (Node's default `maxmem` refuses these parameters; it is raised to
64 MiB). A run waits for a slot; it is never refused.
- **The password never leaves the E2E tunnel**: the relay and the API never see it.
+- **It is sealed to the connection, not only to the tunnel** (finding L3, `unlock-seal.ts`). The
+ tunnel's keys are not secret from a link holder: both key pairs derive from `S`, and the session key
+ from those and two nonces sent in the clear, so a holder of the link AND a recording of the relay
+ traffic could read every connection of it. So the host makes a fresh X25519 key pair for each viewer
+ connection of a Control link (`nacl.box.keyPair()`, derived from nothing, zeroed when the connection
+ ends) and offers its public half in that connection's every meta (`unlockKey`); the page seals
+ `{name, password}` with `nacl.box` from a fresh key pair of its own and sends that pair's public key,
+ the nonce and the box (`{sealed: {key, nonce, box}}`). Neither secret key leaves its end, so a
+ recording opens nothing. The vendored client does it by itself: once a meta on the connection offered
+ a key it seals every unlock, and never sends one in the clear on that connection again, even if a
+ later meta offers none. **Compatibility**: a page from before sealing sends `{name, password}` in the
+ clear, and the host still accepts it (an old cached page keeps working); a new page facing a host
+ from before sealing (no `unlockKey`) sends it in the clear as before. A connection that sent a sealed
+ unlock is latched: a plain one after it is refused as malformed (counted, never verified). A sealed
+ unlock that does not open with the connection's key (sealed to another connection's, malformed, over
+ 4096 base64 characters) is malformed too. **What it does not cover**: an ACTIVE attacker holding the
+ link who sits on the relay can still answer the page as the host (the host's key pair derives from
+ `S`) and offer a key of its own; and what a controller TYPES after unlocking rides the tunnel as
+ before, readable to a link holder with a recording.
### Unlocking
@@ -428,8 +462,21 @@ reason?}`. In order:
on the record and writes — at most 10 writes per link, the 10th riding the lock's own write — so an
app restart resets neither (a file written before the count existed reads as 0). The lock demotes
every controller and tells every viewer; the 11th attempt is answered `locked` unverified. The link
- keeps working as a Commenter link. Only the owner's **Allow control again** clears the lock, and it
- resets the count; a **new password** resets the count too.
+ keeps working as a Commenter link. **The lock lifts by itself** (finding L2: any link holder could
+ otherwise lock control for everyone, for good): 15 minutes for the first lock since the owner last
+ allowed control, doubling with each later one (30 min, 1 h, … 16 h), never past 24 h
+ (`controlLockMs`, `CONTROL_LOCK_MAX_MS`). When it lifts the count starts over and every viewer is
+ told `available`; the backoff (`control.lockStep`) does not reset, so a griefer who keeps locking it
+ gets 10 guesses per 24 h at most. When it lifts is persisted (`control.lockedUntil`, this machine's
+ clock), so a restart neither lifts it early nor makes it permanent: a lift time that passed while
+ nodeterm was closed is lifted at launch BEFORE the host is built (it starts from a count of 0), and
+ one further off than 24 h (the clock went back, a hand edit) is brought in to 24 h from now. A lock
+ written before timed locks (`locked` with no `lockedUntil`) keeps its meaning: it waits for the
+ owner. The owner's **Allow control again** lifts it at once and resets the count AND the backoff; a
+ **new password** resets the count (not the lock, not the backoff). Every viewer is told how long a
+ timed lock lasts (`lockedForMs`, from when the host sent it, in the lock event, in an unlock refused
+ `locked`, and in a later meta); the page says when control can be asked for again. The owner's notice
+ names who tipped it (see "The owner's controls").
6. A check is re-checked after its await. An ended viewer, a stopped host, or any change to control
meanwhile (typing off, a new password, the lock: the control epoch) voids it, uncounted (`too-soon`,
or the new state).
@@ -656,9 +703,14 @@ everything.
password** was pressed (it holds the only copy of the password); Escape and Done still close it.
- A password save in flight holds the popover open (an outside click and Escape do nothing) for up to
30 s; after that the owner sees "Couldn't confirm the new password. Check the link before sharing it."
-- The lock is set on the record synchronously when the host asks for it, written, and never undone by
- a failed write. The owner gets the sticky `control-locked` notice ("Control of api-server was locked
- after 10 wrong passwords. Allow it again from the LIVE chip.").
+- The lock is set on the record synchronously when the host asks for it, with its lift time, written,
+ and never undone by a failed write (it still lifts at its time). The owner gets the sticky
+ `control-locked` notice, which says until when and who tipped it — the name the 10th attempt gave
+ itself, else the chat name of the connection that sent it, as a claim, else "a viewer" — so a kick and
+ a new password are obvious: "Control of api-server is locked until 14:47 after 10 wrong passwords; the
+ last came from a viewer using the name “Mert”. Allow it again from the LIVE chip." The popover's and
+ the drawer's locked line reads "Control locked after 10 wrong passwords, until 14:47." (a lock from
+ before timed locks keeps the old sentences).
### The create dialog
@@ -710,8 +762,10 @@ A **Take control** button opens a small form: a name (prefilled from the chat na
On a grant the terminal takes the keyboard, the header says "You can type" with **Release**, and input
goes out batched per animation frame. Errors say what happened (wrong password; too many wrong
passwords, the sharer has to allow control again; the sharer turned typing off; wait a moment and try
-again; this terminal can't be typed in from a link). A password change shows "Control ended. Take
-control again to type.". While typing:
+again; this terminal can't be typed in from a link). A timed lock says when control can be asked for
+again: "Too many wrong passwords. You can ask for control again at 14:47, or sooner if the sharer allows
+it." (a lock from a host older than timed locks keeps "The sharer has to allow control again."). A
+password change shows "Control ended. Take control again to type.". While typing:
- **The keyboard exit chord**: Ctrl+Shift+. (⇧⌘. on a Mac), matched on the physical Period key, moves
focus from the terminal to Release. It is never sent to the pane. Without it, the terminal would be a
@@ -905,7 +959,7 @@ launch); never in the Server Edition. This machine's links stop at once; then th
**awaited** and its answer reported (`RevokeAllOutcome`: `stopped`; `no-entitlement`, the server was not
asked; `failed`; `unsupported`), a success included. The confirm names the timing: this machine's
viewers at once, other machines' links within a few minutes (their next mint, ≤ ~90 s, or a full link's
-status poll, ≤ 5 min).
+status poll, ≤ 1 min).
**The listener pool.** One hosted scheduler per link with `maxBridged: 10`: at 10 bridged viewers no
replacement listener opens, so the broker closes an 11th client ("no host waiting"). The scheduler's
@@ -916,7 +970,8 @@ the broker's exp + 30 s close of an unbridged listener), backoff reset only on p
**Server 410.** The relay checks a token only at join and cannot cut a bridge; the host does. A
server-side revoke reaches the host through its next mint (≤ ~90 s) — or, while the link is FULL (no
-idle listener, so no mint), through a status poll every 5 min (`FULL_STATUS_POLL_MS`). A 410 from either
+idle listener, so no mint), through a status poll every 60 s (`FULL_STATUS_POLL_MS`; it was 5 min,
+finding L6 — it runs only while the link is full, one request per minute). A 410 from either
ends the link locally with the reason it names and tells the owner.
**Entitlement re-arm** (R41). A host never mints with an empty entitlement (the API would answer 400,
@@ -1038,7 +1093,13 @@ From the spec, verbatim:
link a kicked controller can reconnect and unlock again: to take typing from a person, change the
password or turn typing off.
- **Residual — the fragment lives in browser history** and can be synced by the browser to the
- viewer's other devices. Answered by the short default expiry and Stop.
+ viewer's other devices. **Closed by the viewer page** (finding L1): it moves the fragment into the
+ tab's `sessionStorage` and strips it from the address bar, so history keeps only `/s/<linkId>`. What
+ remains: the moment between the page loading and the strip (the history entry is replaced, not
+ added); a browser that restores a closed tab or a crashed session also restores its
+ `sessionStorage`, so session-restore files still hold the fragment while that tab can be restored;
+ every page of nodeterm.dev opened later in the same tab can read it (our own scripts only — no
+ third-party script runs on the site); and a browser that blocks storage keeps the old behaviour.
- **Residual — the owner-supplied label and node title are shown to viewers.** They are rendered as
text inside fixed nodeterm chrome, marked as sharer-set; terminal output cannot draw over the
chrome and has no clickable links.
@@ -1100,10 +1161,24 @@ From the Control spec (§6), in substance:
terminal, for as long as the link lives, which with Unlimited is until Stop. The dialog says so, and
names the machine. The password is the second factor: the link alone grants watching and chat.
- **Brute force needs the link first**, then runs into the host-side throttles: 1 attempt per 2 s per
- viewer, 3 wrong per connection, 10 wrong per link before control locks (persisted; only the owner
- clears it). The hash is scrypt, and only a person who can already read the owner's userData has it.
+ viewer, 3 wrong per connection, 10 wrong per link before control locks (persisted; it lifts by itself
+ after 15 minutes, doubling per lock to 24 h, and the owner can lift it sooner). Over a day that is at
+ most a few dozen guesses at first and 10 per day once the backoff reaches 24 h. The hash is scrypt,
+ and only a person who can already read the owner's userData has it.
+- **Any link holder can still lock control for a while** (finding L2): 10 wrong attempts lock it for
+ everyone. It used to be until the owner acted; now it lifts by itself, and the owner's notice names the
+ name the attempt that tipped it gave. The host cannot see a viewer's address (the relay hides it), so
+ nothing counts per person. The same holder can still fill the link's 10 viewer slots or spend its
+ host-token budget by reconnecting (the backend's per-link limits); Stop and a new link end that.
+- **The unlock is sealed per connection, the typing is not** (finding L3): a holder of the link with a
+ recording of the relay traffic cannot read a password a controller typed (it is sealed to a key pair
+ derived from nothing), but CAN read everything that controller typed after unlocking, and everything
+ the terminal showed (the tunnel's keys derive from the link). An active attacker on the relay holding
+ the link can answer as the host and read the password too. A page or host from before sealing sends
+ and accepts the password in the clear, as before.
- **Named controllers are not authenticated.** A name is a claim, like a chat name, and is shown quoted
- as one. Everyone who unlocked holds the same password. Accountability is "who was connected and
+ as one. It cannot hide an invisible character (finding L4), so two names that look alike are the same
+ name; look-alike letters from other scripts (a Cyrillic "а") still pass. Everyone who unlocked holds the same password. Accountability is "who was connected and
typing, by their own word", not identity.
- **What stays out of reach** (host-enforced): the canvas, other terminals and other sessions (pane
delivery: the tmux prefix never reaches tmux), files and git; resizing; the owner's IPC
@@ -1451,3 +1526,33 @@ Read-back (`watch:history`):
101. **Plain terminal / grok:** a plain terminal's link shows no Scroll back button; a grok node's says
its conversation records no times.
102. **Phone:** Scroll back on a phone opens a panel tall enough to read and scrolls inside it.
+
+Security hardening (findings L1–L6):
+
+103. **Address bar (L1):** open a link in Chrome, Safari and Firefox. Expect: once the page has loaded the
+ address bar shows `/s/<id>` with no `#…`; the history menu and a synced device's history show no
+ fragment; Reload keeps watching; **Copy link** copies the full link, which opens in a new window; a
+ bare `/s/<id>` pasted into a new tab says the link is incomplete; pasting a different link into the
+ same tab loads that link. With site data blocked (Chrome "Block third-party cookies" is not enough —
+ block all site data for nodeterm.dev) the fragment stays in the address bar and Reload still works.
+104. **Session restore (L1):** close the viewer tab and reopen it (⇧⌘T), then quit the browser and
+ restore the session. Note whether the tab watches again (the browser restored `sessionStorage`) —
+ expected yes in Chrome and Firefox; it is the residual the doc names.
+105. **Timed lock (L2):** from browsers, 10 wrong passwords on a Control link. Expect: the owner's sticky
+ strip "Control of … is locked until HH:MM after 10 wrong passwords; the last came from a viewer using
+ the name “…”."; the popover reads "Control locked after 10 wrong passwords, until HH:MM."; the viewer
+ page reads "Too many wrong passwords. You can ask for control again at HH:MM, or sooner if the sharer
+ allows it." 15 minutes later every viewer's Take control is enabled again, the strip's popover line
+ is gone, and the right password works; the next lock lasts 30 minutes; Allow control again lifts it
+ at once and the lock after that lasts 15 minutes again.
+106. **A lock across a restart (L2):** lock a link, quit nodeterm, start it again within 15 minutes:
+ still locked, lifting at the same time. Lock again, quit for longer than the lock: at launch the link
+ is unlocked and the right password works at once.
+107. **Sealed unlock (L3):** unlock with the new page against the new desktop (works); with the new page
+ against a desktop build from before this change (works, in the clear, as before); with a page cached
+ from before this change against the new desktop (works). A wrong password still counts in all three.
+108. **Invisible names (L4):** chat as "Sharer" followed by a zero-width space (paste it): the name shows
+ and is announced as "Sharer", identical to a plain "Sharer"; an emoji with a ZWJ (👩‍💻) in a chat
+ MESSAGE survives, in a NAME it becomes 👩💻.
+109. **Stop all reaches a full link (L6):** fill a link's 10 viewer slots, then Stop all from another
+ machine. Expect: the viewers see "The sharer stopped this live link." within about a minute.