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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(live-links): the security hardening — address bar, timed lock, sealed unlock, names, poll
reviewadfd15037c72
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 inone FIFO gate of 2; `timingSafeEqual`). Host throttles: 1 attempt per 2 s per viewer, 3 wrong end theconnection, 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 NEVERundone by a failed or hung write — the brake must not fail open; the owner is told `'unsaved'` (holdsuntil 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, neverindexed as the node's session; an older host means refused, never an ordinary attach). Where localdiff --git a/docs/live-links.md b/docs/live-links.mdindex 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 andunlocks 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 computeidentical bytes:@@ -106,17 +113,25 @@ The viewer protocol's namespace is **`watch:`**, never `watchLink:`. The owner'swhich `relay-host` refuses from every peer as host-only BEFORE any policy runs, so a viewer cast in thatnamespace 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 pointbefore 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, andinput is accepted only from a viewer that unlocked a Control link** (the paste-framing contract iswritten 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 to64 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 anapp restart resets neither (a file written before the count existed reads as 0). The lock demotesevery 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 controlmeanwhile (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 to30 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 naOn a grant the terminal takes the keyboard, the header says "You can type" with **Release**, and inputgoes out batched per animation frame. Errors say what happened (wrong password; too many wrongpasswords, 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, movesfocus 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 notasked; `failed`; `unsupported`), a success included. The confirm names the timing: this machine'sviewers 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 noreplacement 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. Aserver-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 eitherends 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 thepassword 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 astext inside fixed nodeterm chrome, marked as sharer-set; terminal output cannot draw over thechrome 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, andnames 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 andtyping, by their own word", not identity.- **What stays out of reach** (host-enforced): the canvas, other terminals and other sessions (panedelivery: 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 saysits 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.