terminal-commands 0.1.3 → 0.2.0

package/README.md

@@ -16,15 +16,42 @@ approval prompts are enabled.
 - Passes only a small environment allowlist to child processes, excluding API keys and other secrets.
 - Restricts dedicated filesystem tools to the approved roots.
 
+File reads, bounded directory listings and writes use a bundled native helper
+with Go's handle-based `os.Root` API. Approved roots are pinned and checked
+against their original file identities; a concurrent parent-directory or root
+symlink swap cannot redirect an operation into another directory. File writes
+truncate only an already safely opened regular file. The helper is required:
+missing, crashed or unsupported helpers refuse file IO, with no path-string
+fallback. Relative paths and the originally configured root aliases remain
+supported. Roots should be ordinary directories on a trusted local filesystem;
+this boundary does not prevent privileged mount changes or hard-link aliases.
+
+Process working directories use the same checked root identities and native
+directory handles during startup. Unix wrappers use `fchdir` followed by `exec`,
+preserving the supervised PID/process group. Windows holds canonical ancestors
+against rename through process creation; existing `taskkill /T` supervision
+includes the wrapper's child. An approved executable still has the user's
+ordinary OS permissions; the directory boundary is not a process sandbox.
+
+See [Go's traversal-resistant APIs](https://go.dev/blog/osroot) for the native
+filesystem boundary and its mount/hard-link limitations.
+
 Command-line programs still execute with your operating-system user permissions. A program can access more than the dedicated filesystem tools, so review every command approval carefully.
 
-The MCP command surface exposes process lifecycle operations separately: `start_process` starts
-an approved executable and returns a session ID, `read_process_output` reads bounded output,
-`list_processes` lists sessions, and `terminate_process` stops a session. This keeps terminal
-workflows available while making each model-callable operation explicit.
+The local MCP server exposes the low-level process supervisor (`start_process`,
+`read_process_output`, `list_processes`, and `terminate_process`) **only to the local
+companion**. The public gateway exposes `submit_process` and `get_process_task`, which
+return immediately with a task ID and then retrieve task status and bounded output.
+There is no legacy public direct-execution API.
 
 ## Run
 
+Building from source requires Node.js 20+ and Go 1.27.2+. `npm test` builds the
+host's helper, while `npm pack` builds all six supported release targets. The
+published package includes them, so installed users need only Node.js. Helpers
+are built from the reviewed `native/fs-helper` source without CGO or downloaded
+runtime executables. Unsupported OS/architecture combinations fail closed.
+
 ```bash
 npm install
 npm run build
@@ -133,3 +160,73 @@ Point the client's remote MCP server configuration at the same `http://127.0.0.1
 it registers remote MCP servers; the connection and tool-discovery steps are otherwise identical.
 
 For a published or independently hosted server, deploy a stable public HTTPS `/mcp` endpoint and implement OAuth 2.1. Do not expose this local server directly to the internet.
+
+## Protocol-v2 production companion
+
+The protocol-v2 companion is released as `terminal-commands@0.2.0`. Upgrade
+and reconnect paired machines before deploying gateway v0.2.0; the gateway
+intentionally rejects older protocol handshakes.
+
+A local process is always approval-gated, and a repeated task ID returns its
+existing session instead of spawning a duplicate. The supervisor enforces a
+bounded process limit (32 running and 512 retained by default) and removes old
+completed sessions after one hour. Task-ID tombstones remain in the live
+companion to prevent replay after session history expires.
+
+The local supervisor is currently memory-backed. If the local server itself
+restarts, an already-running OS process may become unsupervised; a gateway task
+will remain `unknown` until it can be reconciled, never automatically rerun.
+
+## Local approval boundary and replay safety
+
+The CLI generates a fresh 256-bit `MACHINE_TERMINAL_LOCAL_AGENT_TOKEN` for its local
+MCP child and gateway companion. Only the approved companion can use destructive
+tools over HTTP. Direct HTTP clients (including tunnels) are **denied by default**, even for
+reads; stdio clients are **read-only by default**. Never expose the
+local agent token in logs or shell arguments. Trusted local stdio administrators
+can explicitly set `MACHINE_TERMINAL_TRUST_STDIO=1`; this grants local execution
+without per-call companion confirmation and must not be enabled for untrusted clients.
+
+The CLI also creates a private, persistent `device-secret` paired with the device ID.
+The gateway stores only its hash, requires the matching secret on reconnect, and closes
+device WebSockets when their OAuth access token expires. Losing the secret requires an
+explicit re-pair: remove the server-side device registration with authorized
+administrative access, then connect with a new secret. Signing out alone does not
+rotate the device identity.
+
+Process startup writes replay-resistant task receipts **before** executing commands.
+The CLI saves them in `task-receipts.json` under its private config directory.
+Receipts survive local-service restarts, expire after 30 days, and are bounded to
+20,000 recent task IDs. The gateway retains idempotency metadata beyond output
+retention, so old cloud requests still cannot be silently dispatched again.
+
+On Unix the process supervisor runs commands in their own process groups; termination
+sends SIGTERM and escalates to SIGKILL after a short grace period. On Windows it
+uses process termination plus taskkill /T /F for forced descendant cleanup.
+Programs that create independent/detached processes may still escape group cleanup;
+Terminal Commands is not a full OS sandbox.
+
+## Revoke a lost or compromised device
+
+From a trusted terminal running the v0.2.0 CLI, use:
+
+```bash
+terminal-commands revoke-device --device-id <paired-device-id>
+```
+
+The command requires an interactive confirmation and a **fresh Auth0 device login**
+with the separate `terminal:devices:revoke` permission. It never saves the
+elevated management token. The Auth0 API and device-code client must first be
+configured to grant this permission to authorized account owners.
+
+Revocation persists on the gateway, closes the current WebSocket and rejects
+future connections using the revoked **device ID** even with its original
+secret. Revocation cannot terminate processes already running on the machine,
+revoke stolen Auth0 tokens, or block registration under another ID. Immediately
+also revoke compromised Auth0 credentials and investigate the host. Restoring
+the same ID requires a reviewed administrative reset, not a fresh login.
+
+Use `terminal-commands paired-devices` to list paired device IDs even when
+machines are offline, including revoked status. The CLI fetches paginated,
+owner-scoped metadata with the same fresh elevated OAuth permission; secrets
+and pairing credential hashes are never returned.