@danneillouven/remote-workspace 0.0.0-stage → 0.1.0

package/docs/architecture.md

@@ -0,0 +1,311 @@
+# Architecture
+
+## Overview
+
+```text
+Desktop / mobile browser
+  React 19 · TanStack Router/Query · Zustand · CodeMirror 6 · xterm.js
+        │  HTTPS (REST, cookie session)         WebSocket /ws/terminal (one per terminal)
+        ▼
+Fastify backend (Node 24, TypeScript run natively)
+  auth guards ─ routes ─ services ─ adapters
+        │  SSH control connection (SFTP + exec)   one SSH connection per terminal (PTY)
+        ▼
+Development machines (any number): project folders · git · login shell · claude · codex
+```
+
+A single npm package holds both halves. The frontend keeps the boilerplate's layout (`src/app`, `src/features`,
+`src/schema`, `src/store`, ...). The backend lives in `server/src` and imports the same Zod schemas from `src/schema`,
+so HTTP and WebSocket contracts are defined once and validated on both sides.
+
+## Backend
+
+Route handlers are thin: they validate input with Zod (`parseInput`) and call a service. Services hold the logic and
+depend on small interfaces, wired in `server/src/services.ts`:
+
+| Interface          | Implementations                                   | Used by                 |
+| ------------------ | ------------------------------------------------- | ----------------------- |
+| `FileSystemDriver` | `SftpFileSystemDriver`, `LocalFileSystemDriver`   | `WorkspaceFileService`  |
+| `CommandRunner`    | `SshCommandRunner`, `LocalCommandRunner`          | SSH Git / local AI CLI            |
+| `PtyProvider`      | `SshPtyProvider` (tests: `FakePtyProvider`)       | `TerminalManager`       |
+
+### Hosts, projects, and persistent state
+
+Hosts and project records live in the store; administrator workspace-root policy lives in the environment. `AppStore` (`modules/store`) persists everything
+in `DATA_DIR` with atomic, owner-only writes: `state.json` (password hash, hosts, projects, hashed session records)
+and `keys/<hostId>` (private keys generated or imported in the UI; never in `state.json`
+and never returned by the API).
+
+- `HostService` (`modules/hosts`) manages SSH hosts: validates and stores credentials (generated ed25519 key, imported
+  unencrypted key, key file on the server, or ssh-agent), the user-trusted host key, and one `SshConnectionManager`
+  per host. Editing or removing a host drops its connection.
+- `WorkspaceRegistry` (`modules/workspace`) manages projects (a folder on a host, or on the server machine for files
+  only). Each project lazily gets its own `WorkspaceFileService` and `GitService`, sharing its host's control
+  connection; terminals get a `PtyProvider` that starts the login shell in the project folder. Removing a project
+  terminates its terminals; removing a host removes its projects.
+- `TerminalManager` is global (the session cap applies across projects) and tags every session with its project.
+
+### First-run setup
+
+While no password exists, `AuthService` generates a random setup token, prints a `/setup#token=…` link on stdout and
+writes it to `DATA_DIR/setup-token` (0600). `POST /api/auth/setup` requires that token (constant-time compare,
+rate-limited), stores the scrypt hash, deletes the token, and signs the user in. Afterwards setup returns 409. The
+token travels in the URL fragment, so it never appears in request logs or `Referer` headers.
+
+### Adding a host
+
+1. `POST /api/hosts/probe` opens a handshake and captures the host key inside the host-key callback, which then
+   rejects the connection: no credentials are ever offered to an unverified server. The response contains the key,
+   its SHA256 fingerprint, and what the server's `known_hosts` says (`trusted` / `unknown` / `mismatch` / `revoked`).
+2. The UI shows the fingerprint (and how to check it on the machine). `mismatch`/`revoked` cannot be trusted.
+3. `POST /api/hosts` stores the explicitly trusted key with the credentials. From then on every connection uses a
+   **pinned verifier** that accepts exactly that key (and only offers its algorithm). A changed key fails closed;
+   re-trusting goes through the same probe/review flow.
+   With `auth: {type: 'password'}`, the server first signs in once with the password (pinned host key, so it is never
+   offered to an unverified server), installs a freshly generated key in `authorized_keys`
+   (`hosts/key-installer.ts`, ssh-copy-id style), and stores only that key. The password exists only for that call.
+4. `POST /api/hosts/:id/test` opens a fresh control connection and reports authentication problems.
+
+### SSH connections
+
+- `SshConnectionManager` owns one lazily opened **control connection** shared by SFTP (one channel) and short-lived
+  exec channels for Git (at most 4 concurrently, below OpenSSH's default `MaxSessions` of 10). It reconnects on the
+  next request after a drop, with exponential backoff (1 s → 30 s) after failures so a down host is not hammered.
+- Each **terminal gets its own SSH connection**, so a hung shell or a dropped terminal never affects file or Git access
+  or other terminals.
+- Every connection verifies the host key (`host-key-verifier.ts`) against the key the user trusted for that host.
+  Mismatched keys fail closed with an explicit message; trust is only ever granted by an explicit user decision after
+  seeing the fingerprint, and there is no opt-out.
+- Transport errors are mapped to safe, actionable messages (authentication failed, host unreachable, timeout, ...).
+
+### Filesystem
+
+`WorkspaceFileService` enforces the workspace boundary for every request:
+
+1. normalize the client path (`normalizeWorkspacePath`): relative POSIX path, no NUL, no `..` escape;
+2. resolve it to a **canonical path with symlinks resolved** (`realpath`, done by sftp-server over SSH);
+3. check containment with `path.relative` against the canonical root (not a string prefix — `/srv/app-old` is not
+   inside `/srv/app`).
+
+Symlinks inside the workspace work; symlinks pointing outside are listed but refuse to open. Directories are listed
+lazily (one level per request) and sorted directories-first with natural ordering. Files larger than `MAX_FILE_BYTES`
+are not read; files with NUL bytes in the first 8000 bytes are reported as binary; invalid UTF-8 is decoded with
+replacement characters and flagged; FIFOs and devices are refused (reading a FIFO would block).
+
+### Git
+
+`GitService` runs the native Git CLI with argv vectors only:
+
+- `git rev-parse --show-toplevel --show-prefix` finds the repository and maps repo paths to workspace paths (the
+  workspace may be a subdirectory of the repository).
+- `git status --porcelain=v2 --branch -z --untracked-files=all` provides branch, upstream, ahead/behind, and every
+  change in one machine-readable call. (Porcelain v2 is used instead of v1 because it carries branch metadata and
+  rename sources in the same output.) `git diff [--cached] --numstat -z` adds line counts.
+- **Nested repositories** (clones inside the project, submodules, worktrees): `find . -maxdepth 7 ( -name node_modules
+  -o … ) -prune -o -name .git -print0 -prune` lists `.git` entries below the project folder (symlinks are never
+  followed; dependency/build folders are skipped; at most 30 repositories; cached for 15 s). Each candidate must pass
+  `git rev-parse --show-toplevel` == that exact directory — Git silently falls back to a parent repository when a
+  `.git` is invalid — and then gets its own status. The UI shows one section per repository; the parent's untracked
+  entry for a nested clone is dropped. A repository that cannot be read reports its error without hiding the others.
+  Diff requests carry the repository path (`repo`) and are verified the same way before Git runs there.
+- Diffs: `git diff` (unstaged), `git diff --cached -M` (staged, with the rename source), `git diff --no-index -- /dev/null
+  <file>` (untracked).
+- Global flags: `--literal-pathspecs` (names are never globs), `--no-ext-diff --no-textconv` (never run
+  repository-configured programs), `--no-pager`, `GIT_OPTIONAL_LOCKS=0` (status never contends with Git running in a
+  terminal). Paths always follow `--`.
+- Over SSH the argv is single-quoted for the remote login shell (`quoteShellArg`, tested by round-tripping hostile
+  strings through `/bin/sh`).
+
+- **History graph**: `git log -z --topo-order --decorate=full --format=…` for `HEAD` and its upstream (or
+  `--branches --remotes --tags HEAD` with "all"), paged 50 at a time. Commit ids from the browser must be hex and are
+  resolved with `git rev-list --parents -n 1 <id>^{commit}` before use; commit details come from `git diff-tree -M
+  --name-status/--numstat` against the first parent (`--root` for root commits), file diffs from `git diff <parent>
+  <commit>` (or `git show` for root commits).
+- The graph itself (`src/features/git/utils/history-graph.ts`) is a port of VS Code's
+  `scmHistory.ts`: the same swimlane assignment (`toISCMHistoryItemViewModelArray`), SVG geometry (22 px rows, 11 px
+  lanes, 5 px curves), node shapes (HEAD ring, merge double circle), lane palette (`scmGraph.foreground1-5`), and ref
+  colours (current branch blue, its upstream purple, other refs follow their lane). Ref pills follow VS Code's default
+  `scm.graph.badges: "filter"`. Clicking a commit opens a tab with every changed file and its diff (VS Code's
+  multi-diff editor).
+
+Output is bounded (`MAX_DIFF_BYTES`, 16 MiB for status) and truncation is reported to the UI.
+
+### Terminals
+
+```text
+TerminalManager ── TerminalSession ── PtyProcess (SSH exec + PTY, own connection)
+                        │ OutputBuffer (bounded replay)
+                        └── TerminalClient (the currently attached WebSocket, or none)
+```
+
+- A session's lifetime is independent of any WebSocket. Sockets **attach** and **detach**; only an explicit
+  `terminate` (closing the tab), the orphan timeout, process exit + cleanup, or server shutdown ends it.
+- Output is appended to a bounded `OutputBuffer` (`TERMINAL_REPLAY_BUFFER_BYTES`). On re-attach the buffer is replayed
+  starting at a line boundary.
+- **Backpressure**: while more than 1 MiB is queued on the WebSocket, the PTY channel is paused (the remote program
+  blocks on write) and resumed below 256 KiB. While detached, output keeps draining into the bounded buffer.
+- **Orphans**: a session with no attached socket for `TERMINAL_ORPHAN_TIMEOUT_MINUTES` is terminated (`0`, the default,
+  keeps running shells until their tab is closed; an exited shell without a client is reaped after 10 minutes). Any
+  browser that opens the app adopts live sessions it has no tab for, so shells resume on other devices too. A server-side
+  ping every 30 s detects half-open mobile connections; the same heartbeat re-verifies the login cookie and closes
+  sockets whose session was revoked or expired. Push revocation closes sockets immediately, every message checks authorization, and an expiry timer enforces the idle/absolute deadline.
+- One client per session: a second attach takes over and the first socket receives `detached`.
+- Shells start as `cd -- '<root>'; exec "$SHELL" -l` with a PTY, i.e. a normal interactive login shell in the
+  workspace.
+
+#### WebSocket protocol (`src/schema/terminal.ts`)
+
+Client → server (JSON text frames):
+
+| Message                                   | Meaning                                                |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `{type:"create", cols, rows}`             | Start a new shell (must be the first message)          |
+| `{type:"attach", sessionId, cols, rows}`  | Re-attach to an existing session (first message)       |
+| `{type:"input", data}`                    | Keystrokes / paste (≤ 64 KiB per message)              |
+| `{type:"resize", cols, rows}`             | PTY window change                                      |
+| `{type:"terminate"}`                      | Kill the shell (tab closed)                            |
+
+Server → client: raw **binary frames** for terminal output, plus JSON `ready {sessionId, replay}`, `exit {exitCode,
+signal}`, `error {code, message}`, `detached`. Application close codes: 4000 protocol error, 4004 unknown session,
+4009 replaced, 4010 terminated, 4401 login expired. Upgrades without a valid session cookie or with a disallowed
+`Origin` are refused with HTTP 401/403 before any session exists.
+
+### HTTP API
+
+| Method & path                  | Purpose                                     |
+| ------------------------------ | ------------------------------------------- |
+| `GET /api/health`              | Liveness (public)                           |
+| `GET /api/auth/session`        | `{authenticated, setupRequired}` (public)   |
+| `POST /api/auth/setup`         | First password, with the setup token (public, one-time) |
+| `POST /api/auth/login`         | Password login → `HttpOnly` session cookie  |
+| `POST /api/auth/logout`        | Revoke the session                          |
+| `POST /api/auth/activity`      | Record explicit browser interaction; polling does not count |
+| `POST /api/auth/logout-all`    | Password-confirmed session revocation and terminal termination |
+| `POST /api/auth/password`      | Change password; signs out other sessions   |
+| `GET /api/hosts`               | Hosts (public keys and fingerprints only)   |
+| `POST /api/hosts/probe`        | Fetch a server's host key for review        |
+| `POST /api/hosts`, `PATCH/DELETE /api/hosts/:id` | Manage hosts              |
+| `POST /api/hosts/:id/test`     | Fresh connection test                       |
+| `GET /api/browse?host=&path=`  | Directories on a host (folder picker)       |
+| `GET/POST /api/workspaces`, `PATCH/DELETE /api/workspaces/:id` | Manage projects |
+| `GET /api/workspaces/:id`      | Name, root, host, connection status         |
+| `POST /api/workspaces/:id/reconnect` | Force a new SSH control connection    |
+| `GET /api/workspaces/:id/tree?path=` | One directory level                   |
+| `GET /api/workspaces/:id/file?path=` | File content (text / binary / too-large) |
+| `PUT /api/workspaces/:id/file` | Save a text file (mtime precondition)       |
+| `GET /api/workspaces/:id/file/raw?path=&download=` | Media bytes for the viewer (byte ranges), or any file as a download |
+| `POST /api/workspaces/:id/entries[/copy\|/move\|/rename\|/delete]` | Explorer file operations |
+| `GET /api/workspaces/:id/git/status` | Branch and changes                    |
+| `GET /api/workspaces/:id/git/diff?path=&area=&origPath=` | Diff for one change |
+| `GET /api/workspaces/:id/git/refs?repo=` | Branches, remotes (URLs without credentials), tags, stashes |
+| `POST /api/workspaces/:id/git/operation` | One "..." menu action (`op`: pull, push, sync, publish, fetch, checkout, branch, merge, rebase, stash, tag, remote, ...); fixed argv per `op`, names validated by Zod and Git |
+| `GET /api/terminals`           | Live sessions                               |
+| `DELETE /api/terminals/:id`    | Terminate a session                         |
+| `WS /ws/terminal`              | Terminal protocol above                     |
+
+Errors always have the shape `{"error": {"code": "...", "message": "..."}}`. Only `AppError` messages reach the
+browser; anything else becomes a generic `INTERNAL` error and is logged server-side.
+
+## Frontend
+
+- **Routing**: `/setup` (only while setup is pending), `/login`, `/projects`, `/hosts/new` and `/hosts/:id` (the
+  connect-a-machine wizard), `/hosts/:id/add-project` (folder picker), `/settings`, and `/w/:workspaceId` (the
+  workspace). `/` reopens the last project. Guards redirect to setup or login as needed; any 401 sends the user to login.
+- **Projects**: query keys are scoped by project (`['workspace', id, ...]`). The tabs store keeps one tab strip per
+  project (`tabs` for the open one, `saved` for the others) and switches before the workspace renders. Terminal tabs
+  carry their project id; the terminal registry keeps controllers of background projects connected, and only
+  terminates a shell when its tab disappears from every project.
+- **Server state** lives in TanStack Query (`src/api/queries.ts`): directory listings (30 s stale time, cancellable),
+  file contents (refetched on focus, so files edited by an agent refresh), Git status and diffs (invalidated by the
+  refresh button and ~1.5 s after a command is submitted in any terminal).
+- **Client state** lives in small Zustand stores: `tabs` (persisted: open tabs, order, active tab, terminal session
+  ids), `layout` (persisted: sidebar visibility/widths, word wrap; drawer state is not persisted), `explorer`
+  (expanded folders, hidden files), `git` panel selection.
+- **Terminals** never go through React state. `TerminalController` owns the xterm.js instance, its DOM element, and its
+  WebSocket; `terminal-registry` creates one per tab and terminates it exactly when the tab disappears from the tab
+  store. React only mounts the controller's element into the active tab, so switching tabs, resizing across the
+  desktop/mobile breakpoint, or re-rendering never touches the connection. Scrollback is bounded (5000 lines).
+  Controllers reconnect with backoff, re-attach after reloads, and suppress xterm's automatic replies to terminal
+  queries contained in replayed history (otherwise those replies would be typed into the live shell).
+- **Viewer**: one `CodeViewer` (CodeMirror 6, read-only) for files and diffs. Languages load on demand via
+  `@codemirror/language-data`. Scroll positions survive unmounting via `scrollSnapshot()`. On touch devices the
+  content is non-editable so tapping code never raises the keyboard; search is a toolbar button.
+- **Diffs** are parsed into lines with old/new numbers; prefixes are stripped so the code is highlighted as its own
+  language, with line backgrounds and a dual line-number gutter as CodeMirror decorations (virtualized, so large diffs
+  stay fast).
+- **Layout**: ≥ 1024 px shows resizable, collapsible sidebars; below that, explorer and Git become independent
+  slide-over drawers (swipe, backdrop tap, or Esc to close) that never reset the center tab. The app frame follows
+  `visualViewport`, so the terminal shrinks above the on-screen keyboard and the PTY is resized when the cell grid
+  changes. Safe-area insets are respected.
+
+## Security model
+
+Single trusted user, defence in depth:
+
+| Concern                    | Measure                                                                                       |
+| -------------------------- | --------------------------------------------------------------------------------------------- |
+| Exposure                   | Binds to 127.0.0.1; published via `tailscale serve` (HTTPS, tailnet only); Funnel not used.   |
+| Setup takeover             | First password requires a one-time token printed on the server console.                       |
+| Authentication             | scrypt (N=32768, r=8, p=3); persistent opaque hashed sessions; `HttpOnly`, `SameSite=Strict`, `Secure` (over HTTPS) cookie. |
+| Brute force                | Per-IP exponential lockout after 5 failures plus a global cap.                                |
+| CSRF / socket hijacking    | State-changing requests and WebSocket upgrades must be same-origin on a loopback, IP, or `*.ts.net` host (DNS-rebinding names fail), or listed in `ALLOWED_ORIGINS`; `Sec-Fetch-Site: cross-site` rejected. |
+| Revocation                 | Logout revokes the token; open terminal sockets are closed on the next heartbeat.             |
+| Credentials                | Private keys stay in `DATA_DIR/keys` (0600); responses carry public keys only; never logged.  |
+| MITM                       | Host key reviewed and explicitly trusted once (known_hosts consulted), then pinned; probes send no credentials. |
+| Path traversal / symlinks  | Normalization + canonical-path containment.                                                    |
+| Command injection          | Argv only; single-quoted for the remote shell; `--` before paths; literal pathspecs; no ext diff/textconv. |
+| Workspace access          | Administrator-configured local/SSH roots; protected backend paths; local Git execution disabled. |
+| Resource exhaustion        | Size limits for files, diffs, listings, status; bounded replay buffers; session cap; backpressure; orphan reaping. |
+| Browser hardening          | CSP (`script-src 'self'`), `X-Frame-Options: DENY`, `nosniff`, `no-referrer`, `no-store` on API responses. |
+| Logging                    | Structured pino logs; cookies redacted; terminal input and file contents never logged.        |
+
+Not covered: multi-user isolation (everyone who knows the password is the same user, with that user's shell),
+TOCTOU between the containment check and the read (a process on the dev machine racing symlink swaps), and the remote
+user's own permissions (the terminal is a full shell by design).
+
+## Extensions (future)
+
+A VS Code extension host is out of scope: CodeMirror cannot run VS Code extensions, and supporting them would mean
+embedding a VS Code workbench (e.g. openvscode-server) — a separate architectural decision.
+
+The codebase is shaped for small internal integrations instead:
+
+- **Git actions** (e.g. an AI-generated commit message): add a `GitService` method + route (it already has a safe
+  argv runner and repository detection), a schema in `src/schema/git.ts`, and a button in `GitPanel`. A commit-message
+  helper could call a CLI already installed on the remote (`claude -p`, `codex exec`) through `CommandRunner`, keeping
+  API keys out of this application.
+- **Workspace commands**: a server-side registry of named argv templates executed via `CommandRunner`, exposed as a
+  command palette.
+- **Sidebar panels / viewer actions**: panels are plain feature components composed by `WorkspaceScreen`; viewer
+  actions are extra buttons in `ViewHeader` or CodeMirror extensions passed through `CodeViewer`.
+- **Language services**: would require a per-language LSP process on the remote and a CodeMirror LSP client; not
+  planned.
+
+No plugin loader was built: with one user and a handful of planned helpers, direct composition is simpler and safer
+than a dynamic plugin API.
+
+## Limitations
+
+- Viewer is read-only (editing/saving is a planned follow-up; the API and tab model leave room for it).
+- Single user: one password; everyone who knows it is the same user on every connected host.
+- Private keys at rest are protected by file permissions, not encrypted (like `~/.ssh`). Passphrase-protected keys
+  cannot be imported; use ssh-agent for those.
+- Terminal sessions live in the server process: a backend restart ends them (use `tmux` on the remote for
+  restart-proof sessions).
+- Replayed terminal history is re-rendered at the current width, so a re-attached terminal may show wrapped lines or
+  zsh's `%` end-of-line markers from output produced at a different width. Full-screen programs redraw normally.
+- Remote exec commands assume a POSIX-compatible login shell (bash, zsh, dash, ksh); fish as login shell may break
+  Git commands with unusual file names.
+- SSH certificate host keys (`@cert-authority`) are not supported. SSH passwords are only used once, to install a
+  key; hosts that refuse public-key logins entirely cannot be used.
+- No local PTY: projects on "this server" support file operations only. Git and terminals require SSH under a separate workspace account.
+- File names that are not valid UTF-8 are displayed with replacement characters and cannot be opened.
+- Directory listings beyond `MAX_DIR_ENTRIES` are truncated; there is no file search across the tree yet.
+
+## Security upgrade behavior
+
+See [security-upgrade.md](security-upgrade.md) for deployment migration and manual checks. Sessions use random opaque tokens with only SHA-256 token hashes persisted in state. Logout remains effective across restart. Old signed cookies are rejected. Idle/absolute limits default to 30 minutes/eight hours; activity persistence is coalesced to 15 seconds. Password changes and sign-out-all stop app-managed terminals.
+
+Filesystem primitives are wrapped in administrator policy checks, so creation, legacy project access, browsing, reads, downloads, and mutations enforce canonical permitted roots. Backend state, the deployment directory, `.ssh` and configured local key-file paths are excluded. Git and terminals are SSH-only to avoid running repository programs as the backend account. Shell permissions still require OS account isolation; workspace roots are not a shell sandbox.
+
+AI commit generation is off by default. Enabling it permits text-only Claude with tools, MCP servers, hooks/discovery, and persistence disabled. Prompts go through stdin, never process arguments. Unrestricted fallbacks are unsupported; raw CLI errors are neither logged nor returned.

package/docs/configuration.md

@@ -0,0 +1,141 @@
+# Configuration
+
+The app can start without settings, but administrator-configured roots are required before opening projects. Machines, keys, projects, and the password are set up in the
+browser and stored in `DATA_DIR`. Environment variables (an optional `.env` next to `package.json`, loaded with Node's
+`--env-file-if-exists`) define process-level defaults and workspace access policy. Nothing is exposed to the browser bundle — there are no
+`VITE_` variables. Invalid values stop the server with a list of every problem.
+
+Start from [`.env.example`](../.env.example) if you need overrides.
+
+## First run
+
+`npm start` (or `npm run dev`) prints a one-time link such as:
+
+```text
+  First-time setup — open this one-time link to create your password:
+  ➜ http://localhost:4280/setup#token=…
+```
+
+The token is also written to `DATA_DIR/setup-token`, which is useful when the server runs as a service
+(`cat data/setup-token`). It stops working once the password exists. Opening `/setup` without the link asks for the
+token.
+
+Forgot the password? Stop the server, run `npm run reset-password`, and start it again. A new setup link is printed;
+machines and projects are kept, and every session is signed out.
+
+## Data directory
+
+| Path                   | Contents                                                     |
+| ---------------------- | ------------------------------------------------------------ |
+| `state.json`           | Password hash (scrypt), hosts, projects, hashed login sessions |
+| `keys/<hostId>`        | Private keys generated or imported in the UI                 |
+| `setup-token`          | Only until setup is complete                                 |
+
+The directory is created `0700` and files `0600`; looser permissions on an existing directory are tightened at
+start. It is gitignored. Back it up like you would `~/.ssh`. Changing the password revokes prior sessions; the initiating browser gets a fresh cookie. Legacy `session-secret` files are ignored.
+
+## Environment variables
+
+### HTTP server
+
+| Variable          | Default     | Notes                                                                                                   |
+| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
+| `HOST`            | `127.0.0.1` | Only `127.0.0.1` or `::1`; publish through `tailscale serve`.    |
+| `PORT`            | `4280`      | Also used by the Vite dev proxy.                                                                        |
+| `LOG_LEVEL`       | `info`      | `fatal` … `trace`, or `silent`. Logs are structured JSON (pino).                                        |
+| `TRUST_PROXY`     | `true`      | Trusts `X-Forwarded-*` **from loopback only** (`tailscale serve`), for the real host, scheme, and client IP. |
+| `ALLOWED_ORIGINS` | —           | Extra origins for state-changing requests and WebSockets, comma-separated. Not needed for `localhost`, IP addresses, or `*.ts.net` names (same-origin requests there are accepted automatically). Only localhost and `*.ts.net` origins are accepted. |
+| `PUBLIC_URL`      | —           | Public `https://` address behind a Cloudflare Tunnel. Always an allowed origin; the setup link is also printed with it. |
+| `CLOUDFLARE_TUNNEL_TOKEN` | — | Used only by `npm run start:tunnel` (passed to `cloudflared`, never to the app server). See [deployment.md](deployment.md#cloudflare-tunnel). |
+| `STATIC_DIR`      | `dist` if built | Directory with the built frontend.                                                                  |
+| `DATA_DIR`        | `./data`    | See above. `~` expands.                                                                                 |
+
+### Sessions
+
+| Variable            | Default | Notes                                                                          |
+| ------------------- | ------- | ------------------------------------------------------------------------------ |
+| `SESSION_TTL_HOURS` | `8`   | Absolute session lifetime; maximum 24 hours.                                                              |
+| `SESSION_IDLE_MINUTES` | `30` | Inactivity timeout; maximum 120 minutes. Polls, output and ping/pong do not extend it. |
+| `COOKIE_SECURE`     | `auto`  | `auto` = `Secure` over HTTPS; `false` is rejected in production. |
+
+### Workspace policy and AI
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `LOCAL_WORKSPACE_ROOTS` | `[]` | JSON array of absolute local paths. Local workspaces support files only. |
+| `SSH_WORKSPACE_ROOTS` | `[]` | JSON array of absolute paths on SSH hosts; applies across all configured hosts. |
+| `AI_COMMIT_ENABLED` | `false` | Opt in to sending diffs to an AI CLI for commit messages: the first of `codex` or `claude` in OpenCodeCommit's `backend-order` (`~/.config/opencodecommit/config.toml`). Codex runs `exec` with a read-only sandbox and no user config; Claude runs text-only with tools disabled. Each uses the server user's own CLI login. |
+
+Example: `SSH_WORKSPACE_ROOTS='["/home/dev/projects"]'`. Browser requests cannot change this policy. The picker starts at these roots. Backend state, deployment files, standard credential directories, configured key-file paths, and OS pseudo-filesystems are protected locally. Project roots are not shell sandboxes; use separate OS accounts and permissions. See [deployment](deployment.md).
+
+### SSH
+
+| Variable                    | Default              | Notes                                                                   |
+| --------------------------- | -------------------- | ----------------------------------------------------------------------- |
+| `SSH_KNOWN_HOSTS_PATH`      | `~/.ssh/known_hosts` | Consulted when adding a host: matching keys are recognized as trusted, conflicting ones are refused. |
+| `SSH_READY_TIMEOUT_MS`      | `20000`              | Handshake timeout.                                                      |
+| `SSH_KEEPALIVE_INTERVAL_MS` | `15000`              | SSH keepalives; 3 missed keepalives drop the connection.                |
+| `SSH_AUTH_SOCK`             | (inherited)          | Enables "Use ssh-agent" in the UI.                                      |
+
+### Terminals and limits
+
+| Variable                          | Default          | Notes                                                       |
+| --------------------------------- | ---------------- | ----------------------------------------------------------- |
+| `TERMINAL_TERM`                   | `xterm-256color` | `$TERM` for remote shells.                                  |
+| `TERMINAL_MAX_SESSIONS`           | `10`             | Concurrent shells across all projects (one SSH connection each). |
+| `TERMINAL_REPLAY_BUFFER_BYTES`    | `524288`         | Recent output kept per session for re-attaching browsers.  |
+| `TERMINAL_ORPHAN_TIMEOUT_MINUTES` | `0`              | A session with no connected browser for this long is terminated. `0` keeps running shells until their tab is closed (exited ones are still cleaned up after 10 minutes). |
+| `MAX_FILE_BYTES`                  | `2097152`        | Larger files are not loaded into the editor (also the save limit). |
+| `MAX_IMAGE_BYTES`                 | `20971520`       | Larger images are not shown in the image viewer (downloads and video are not limited). |
+| `MAX_DIFF_BYTES`                  | `4194304`        | Diffs are truncated beyond this (and flagged in the UI).   |
+| `MAX_DIR_ENTRIES`                 | `5000`           | Directory listings are truncated beyond this.              |
+
+Variables from earlier versions (`AUTH_PASSWORD_HASH`, `SESSION_SECRET`, `WORKSPACE_*`, `SSH_HOST`, `SSH_USERNAME`,
+`SSH_PRIVATE_KEY_PATH`, …) are ignored; set those things up in the UI.
+
+## Connecting a machine
+
+**Projects → Connect a machine** walks through four steps:
+
+1. **Machine** — host name, MagicDNS name, or IP; SSH port; username.
+2. **Verify** — the server fetches the host key (without sending any credentials) and shows its SHA256 fingerprint.
+   If `known_hosts` on the server already trusts it, that is shown. Otherwise compare it on the machine itself:
+   ```sh
+   ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
+   ```
+   A key that conflicts with `known_hosts` cannot be trusted. Once trusted, the key is pinned: a different key later
+   is refused until you re-verify it under the host's settings.
+3. **Sign in**:
+   - *Password* (default): type your SSH password once. Over the already-verified connection, Remote Workspace signs
+     in (password or keyboard-interactive, as macOS uses), generates a dedicated ed25519 key, appends its public half
+     to `~/.ssh/authorized_keys` (creating `~/.ssh` 0700 / the file 0600 if needed, never duplicating it), and from
+     then on connects with that key. The password is used only for that one connection: it is never stored, logged,
+     or sent back to the browser. The host must allow public-key logins (OpenSSH does by default).
+
+   Under "Use an SSH key instead":
+   - *Generate a key, add it myself*: a dedicated ed25519 key; the next step shows the one-line command that adds
+     the public key to `~/.ssh/authorized_keys`. For hosts that do not accept passwords.
+   - *Paste an existing private key*: stored in `DATA_DIR/keys`, never shown again. Passphrase-protected keys are not
+     supported.
+   - *Key file on the server*: e.g. `~/.ssh/id_ed25519` of the user running Remote Workspace (read at connect time).
+   - *ssh-agent*: the agent available to the server process.
+4. **Connect** — tests a real connection and reports authentication or network problems.
+
+Then pick a project folder. Add more projects on the same machine with **Add project** on its card.
+
+Tip: restrict a generated key on the machine by prefixing its `authorized_keys` line with
+`from="<server's Tailscale IP>"`.
+
+### What runs on the remote machine
+
+- **Files**: the SFTP subsystem (enabled by default in OpenSSH).
+- **Git**: `git` must be on the `PATH` of non-interactive SSH commands. Commands run through your login shell as
+  `cd -- '<root>' && exec env GIT_OPTIONAL_LOCKS=0 git ...` with every argument single-quoted, which assumes a
+  POSIX-compatible login shell (bash, zsh, dash, ksh).
+- **Terminals**: each terminal is its own SSH connection running `cd -- '<root>'; exec "$SHELL" -l` with a PTY
+  (`TERMINAL_TERM`), i.e. a normal interactive login shell started in the project folder. Tools such as `claude` and
+  `codex` use whatever is installed and configured for that user.
+
+### Projects on the server itself
+
+"Open a folder on this server" supports file operations inside `LOCAL_WORKSPACE_ROOTS`. For Git and terminals, add an SSH host using a separate OS account that cannot access backend secrets. Repository programs must never run under the backend service account.

package/docs/deployment.md

@@ -0,0 +1,117 @@
+# Deployment
+
+Remote Workspace is a single-user remote shell application. Deploy it privately through Tailscale Serve:
+
+```text
+phone/laptop → Tailscale access policy → Serve HTTPS → 127.0.0.1:4280 → SSH as a workspace user
+```
+
+Tailscale checks who can reach the application. The app password checks who can operate it. File APIs check administrator-configured project roots. The SSH account's OS permissions control the shell; project roots are not a shell sandbox.
+
+## Account and directory separation
+
+Run the backend under a dedicated account, such as `rw`, with no sudo privileges. SSH hosts must use a different workspace account, such as `dev`, which cannot read the backend's `DATA_DIR`, deployment configuration, or credentials. Use this separation even when SSH targets the same physical machine. Do not SSH back into the backend's service account.
+
+Keep application code/configuration outside project roots, owned by the deployment administrator and not writable by workspace users. Use managed, dedicated SSH keys. Do not attach a general-purpose personal SSH agent to the service. Restrict the backend's tailnet access to the SSH hosts it needs.
+
+Local projects support files only. Git and terminals require SSH: repository hooks, filters, and helpers must not execute with the backend's identity. OS isolation also protects against filesystem races and hard links, which path checks alone cannot make into a complete sandbox against a hostile local process.
+
+## Configure and build
+
+Requirements: Node.js 24+, npm, Tailscale on the server and clients, HTTPS enabled for the tailnet, and SSH/SFTP/Git on workspace hosts.
+
+Create a private `.env` beside `package.json`:
+
+```dotenv
+HOST=127.0.0.1
+PORT=4280
+DATA_DIR=/var/lib/remote-workspace
+SSH_WORKSPACE_ROOTS='["/home/dev/projects"]'
+LOCAL_WORKSPACE_ROOTS='[]'
+SESSION_TTL_HOURS=8
+SESSION_IDLE_MINUTES=30
+```
+
+The root arrays are administrator policy, not browser-editable settings. Paths in `SSH_WORKSPACE_ROOTS` apply on every SSH host. Choose dedicated project directories; no roots are allowed by default. `DATA_DIR`, the application deployment directory, `.ssh` directories, and configured backend key-file paths cannot be opened through local file APIs.
+
+```sh
+npm ci
+npm run build
+npm run serve
+```
+
+Open the one-time setup link printed on the server to set the app password. The setup token is also saved at `DATA_DIR/setup-token`; do not share it. Connect a host, verify its key fingerprint, and choose a permitted folder.
+
+## Run as a service on Linux
+
+Create the service account and directories through your system administration process. The `rw` account needs read access to the deployment and write access to its private state directory.
+
+Example `/etc/systemd/system/remote-workspace.service`:
+
+```ini
+[Unit]
+Description=Remote Workspace
+After=network-online.target tailscaled.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=rw
+WorkingDirectory=/opt/remote-workspace
+Environment=NODE_ENV=production
+Environment=DATA_DIR=/var/lib/remote-workspace
+StateDirectory=remote-workspace
+StateDirectoryMode=0700
+ExecStart=/usr/bin/node --env-file-if-exists=/opt/remote-workspace/.env server/src/main.ts
+Restart=on-failure
+RestartSec=3
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadOnlyPaths=/opt/remote-workspace
+UMask=0077
+
+[Install]
+WantedBy=multi-user.target
+```
+
+`StateDirectory` remains writable. This example uses SSH projects; explicitly grant narrowly scoped filesystem access if enabling local projects. Keep the SSH workspace account separate from `rw`. On macOS use a service/LaunchDaemon with a dedicated service identity; a LaunchAgent under your everyday account does not provide account isolation.
+
+## Publish privately
+
+```sh
+tailscale serve --bg 4280
+tailscale serve status
+```
+
+Restrict access to this machine's HTTPS port to your identity/devices in the tailnet policy. Open the private `https://<machine>.<tailnet>.ts.net` URL from a permitted Tailscale device. Serve supports WebSockets.
+
+Do not enable Funnel or port forwarding. `HOST` rejects wildcard/external binds, so the only ways in are Tailscale Serve and the optional Cloudflare Tunnel below.
+
+## Cloudflare Tunnel
+
+To also reach the app from devices outside the tailnet, publish it through a Cloudflare Tunnel. In Cloudflare Zero Trust, create a tunnel whose public hostname maps to `http://localhost:4280`, then add to `.env`:
+
+```dotenv
+PUBLIC_URL=https://remote.example.com
+CLOUDFLARE_TUNNEL_TOKEN=...
+```
+
+`npm run start:tunnel` builds, starts the server, waits until it is healthy, then runs `cloudflared` (the token is never passed to the app server or put on a command line). Tailscale Serve keeps working alongside it.
+
+The tunnel hostname is on the public internet, so the app password would be its only gate. Put a **Cloudflare Access** application with an allow policy for your identity (email OTP or SSO) in front of the hostname, so requests are rejected at Cloudflare's edge before they reach the app.
+
+A `*.ts.net` Host header is not proof of Tailscale identity. The network boundary comes from the deployed Serve configuration and access policy, not header matching.
+
+## Sessions and shutdown
+
+Run a single backend process per `DATA_DIR`; do not share the JSON store between replicas.
+
+Sessions expire after eight hours or 30 minutes of inactivity by default. Pointer/keyboard activity, authenticated mutations and terminal input extend inactivity; background polling, output and ping/pong do not. Session activity writes are coalesced to 15 seconds, so a restart can shorten the idle window by up to 15 seconds.
+
+Logout disconnects that login's sockets immediately. Detached shells remain available for the configured reconnect window (30 minutes by default). Password changes and **Sign out all devices** revoke sessions and terminate app-managed terminals. Detached or independently launched processes may continue and require OS-level management.
+
+A backend restart ends terminal sessions. Valid login sessions persist; revoked sessions remain revoked. Stop the server before `npm run reset-password`; the command clears all login sessions and keeps hosts/projects.
+
+For migration and verification, see [Security upgrade](security-upgrade.md).

package/docs/security-upgrade.md

@@ -0,0 +1,35 @@
+# Security upgrade
+
+## Before restarting an existing installation
+
+1. Back up `DATA_DIR` securely. Stop the old backend and any public tunnel. Remove its Cloudflare public route, Tailscale Funnel exposure, and port forwarding if present. The application cannot remove external hosting configuration for you.
+2. Run the backend under a dedicated OS account. Move its state/configuration outside workspace directories and ensure SSH users cannot read or write them. SSH back to the same machine only using a different, unprivileged workspace account. Do not give workspace users sudo access to backend secrets.
+3. Remove `PUBLIC_URL` and tunnel tokens from the service environment. Set `HOST=127.0.0.1`, `SESSION_TTL_HOURS=8`, and `SESSION_IDLE_MINUTES=30`. Custom public origins and non-loopback binds are rejected. Remove old `SESSION_TTL_HOURS=168` overrides.
+4. Set `SSH_WORKSPACE_ROOTS` and/or `LOCAL_WORKSPACE_ROOTS` to JSON arrays of absolute project directories. Empty arrays deny access. SSH roots apply across configured hosts. Local projects are now file-only; add an SSH connection under the workspace account for Git and terminals.
+5. Build/restart, configure Tailscale Serve, and restrict its access policy to your identity/devices. Verify outside-tailnet access fails. Existing hosts/projects remain stored, but projects outside current policy cannot be used. The picker now starts at permitted roots.
+6. Existing signed cookies are rejected on upgrade; sign in again. Successful login upgrades legacy scrypt hashes automatically. The obsolete `session-secret` file is ignored and may be removed after migration. Never restore an old state backup over a running deployment: backups can contain previously valid session records. After restoring state, reset the password to clear sessions before exposing the service.
+7. AI generation is disabled by default. If required, enable `AI_COMMIT_ENABLED=true` and install/authenticate a Claude CLI supporting the shipped restrictive flags. Enabling it is the consent: the sparkle button then sends the diff without a further prompt. Codex/OpenCode fallbacks are disabled; unsupported Claude versions fail closed. Provider configuration and the CLI binary are trusted deployment components.
+
+If compromise is suspected, revoke/replace the SSH keys on every destination host, not just in the UI. Deleting a host in the UI does not remove its authorized key from that host. Also rotate other credentials readable by the old backend/SSH accounts. A password change cannot recover an already stolen SSH key.
+
+## Automated checks
+
+```sh
+npm run build
+npm test
+```
+
+Regression coverage includes local credential retrieval, protected symlinks across file operations, legacy project roots, revoked-cookie replay after restart, idle/absolute session expiry, push WebSocket revocation, post-revocation input, concurrent authentication limits, legacy hash upgrades, and restricted AI invocation without prompts in process arguments.
+
+Real SSH adapter tests remain opt-in using `scripts/test-sshd.sh`; see the README.
+
+## Manual checks
+
+- From a permitted Tailscale device, sign in, connect an SSH host, and open a project inside its configured root. Read/edit files and use Git/terminals. With local projects, confirm Source Control explains that SSH is required.
+- Open the folder picker: only permitted roots are shown. Enter an unapproved path, the deployment directory, DATA_DIR, or an alias to one of them; access must fail. Attempts to change an existing project to a protected root must also fail.
+- Sign in on two browsers. Log out on one; its open terminal sockets must disconnect immediately while the other login remains valid. Restart the backend and confirm the logged-out browser remains signed out.
+- In Settings, submit an incorrect password to **Sign out all devices**; nothing should be revoked. Submit the correct password; both browsers must lose access, and app-managed terminals must stop.
+- Change the password while another browser is connected. The other browser loses access and existing app-managed terminals stop. The initiating browser receives a fresh session cookie.
+- For timeout checks in a temporary installation, set `SESSION_IDLE_MINUTES=1` and a short fractional `SESSION_TTL_HOURS`. Background polls and continuous terminal output must not keep a login alive. Real user input should extend idle time, but cannot extend the absolute deadline.
+- If AI is enabled, verify Generate sends only the selected repository's diff. Inspect the restricted invocation using a test/stub CLI rather than sending private code during testing. Failed CLI output must not reveal prompts or secrets in HTTP errors or logs.
+- Disconnect Tailscale on a separate client and try the remote URL. Verify access fails. This deployment check cannot be replaced by unit tests.