@hahahhh/sshx 0.0.6 → 0.0.7-rc.1

package/README.md

@@ -1,15 +1,35 @@
 # sshx
 
+**English** · [简体中文](README_zh.md) · [Website](https://xiaot623.github.io/sshx/)
+
 > Transparent SSH enhancement — add remote-to-local commands, auto port forwarding, and local domains to your SSH workflow. Zero side effects when you don't need them.
 
 **sshx** is a drop-in wrapper around OpenSSH. Wrap it as `alias ssh=sshx` and your existing SSH workflow works exactly as before — every flag, config, and connection passes through verbatim. But when you connect to a host (or Docker container) with sshx-aware features enabled, you unlock a connection-scoped shared remote server that gives you:
 
+![sshx animated terminal demo](docs/assets/sshx-demo.svg)
+
 - 🔄 **Reverse command bridge** — run `sshx local <cmd>` *on the remote* to execute commands on your local machine, with stdout, stderr, exit code, and stdin all propagated.
 - 📁 **Bidirectional workspace mount** — direct CLI sessions can use remote tools on local files, and local tools on remote files.
 - 🔌 **Automatic port forwarding** — remote local listeners (loopback `127.0.0.1` and wildcard `0.0.0.0`; e.g., a dev server on `0.0.0.0:8080` or `localhost:8080`) are automatically detected and forwarded to your local machine.
 - 🌐 **Local domain binding** — access forwarded ports as `<host>.<your-user>.sshx:<port>` in your local browser, no manual `-L` flags needed.
+- 🛡️ **Remote egress proxy** — opt in to route proxy-aware remote tools through the local client's proxy or TUN-backed network stack.
 - 🐳 **Docker container support** — target running containers by name or ID: `sshx my-container`. Command bridge support works inside containers via `docker exec`.
 
+## Table of Contents
+
+- [Why sshx?](#why-sshx)
+- [Architecture](#architecture)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration Reference](#configuration-reference)
+- [How It Works](#how-it-works)
+- [Safety & Bypass](#safety--bypass)
+- [Platform Support](#platform-support)
+- [Project Structure](#project-structure)
+- [Roadmap](#roadmap)
+- [License](#license)
+
 ## Why sshx?
 
 | Without sshx | With sshx |
@@ -80,7 +100,7 @@ Set `features.remoteFs: true` to expose the command initiator's workspace throug
 - VS Code/Cursor Remote-SSH integration sidecars stay remote-to-local only: those application sessions do not export a local workspace to the remote host.
 - With RemoteFS disabled, the command runs from the local home and receives `SSHX_REMOTE_CWD` plus `SSHX_REMOTE_FS=0`.
 
-Mounted trees permit reads, writes, and creation, but block file/directory deletion and rename in both directions. They can include sensitive files such as shell configuration and SSH credentials, so enable `remoteFs` only for targets you trust.
+Mounted trees permit reads, writes, and creation. Deletion (unlink/rmdir) is blocked; same-directory rename is allowed so editors can atomic-save; cross-directory rename remains blocked. They can include sensitive files such as shell configuration and SSH credentials, so enable `remoteFs` only for targets you trust.
 
 Set `FS_READ_ONLY=1` on the client when starting sshx to make the session mounts read-only:
 
@@ -144,6 +164,22 @@ ls /dev/macfuse*
 
 Absolute source paths are preserved as a hierarchy below sshx's private session directory, but absolute command arguments are not rewritten. RemoteFS does not expose special files/xattrs/ACLs or support Docker targets, FUSE-T, or FSKit. It is optimized for source trees and small files rather than large-file throughput.
 
+### 🛡️ Remote Egress Proxy (opt-in)
+
+Set `features.proxy: true` or run with `SSHX_USE_PROXY=1` to give the remote session an OpenSSH remote dynamic SOCKS endpoint. Traffic exits the laptop:
+
+```sh
+SSHX_USE_PROXY=1 sshx remote
+```
+
+sshx asks the existing ControlMaster to allocate a remote SOCKS listener with `ssh -O forward -R 127.0.0.1:0` (no local destination). OpenSSH then acts as a SOCKS server on the remote, and connections leave through the client. sshx overrides uppercase and lowercase `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY` inside the remote session to `socks5h://127.0.0.1:<port>` so curl, Git, and other tools that only look at `HTTP_PROXY` still work. Existing `NO_PROXY` values are preserved and extended with remote loopback addresses.
+
+There is no custom local HTTP/SOCKS process, no per-session credentials, and no `SSHX_PROXY_URL` chain-through. DNS names sent through `socks5h://` are resolved on the laptop. A local TUN proxy naturally captures that laptop egress.
+
+The remote listener is bound only to `127.0.0.1` and uses a dynamically allocated port.
+
+This feature covers TCP applications that honor proxy environment variables, including tools such as curl, Git, and many package managers. It does not provide a remote TUN device, UDP/ICMP forwarding, PAC/system-GUI proxy discovery, or Docker target support.
+
 ### 🔌 Automatic Port Detection & Forwarding
 
 When a process on the remote starts listening on `127.0.0.1` or `0.0.0.0` (e.g., `npm run dev` on port 3000), sshx detects it and:
@@ -321,6 +357,10 @@ features:
   # Requires FUSE on each machine receiving a mount.
   remoteFs: false
 
+  # Route proxy-aware remote TCP applications through the local client.
+  # Default: false. SSHX_USE_PROXY=0|1 overrides this value.
+  proxy: false
+
 commands:
   # Commands blocked from bridge execution.
   deny: []
@@ -347,7 +387,7 @@ commands:
 1. **Connection**: `sshx remote` opens a normal SSH session and starts a compatible runtime under `~/.sshx_server/runtimes/<RuntimeHomeID>`.
 2. **Sidecar channel**: One hidden SSH channel multiplexes command, port, heartbeat, and optional RemoteFS traffic. ContextID routes VS Code/Cursor terminals to a healthy live session.
 3. **Port sniffing**: The server reads `/proc/net/tcp*` (Linux) to detect loopback (`127.0.0.1` / `::1`) and wildcard (`0.0.0.0` / `::`) listeners.
-4. **Forwarding**: Detected ports are forwarded through a single shared local daemon using `ssh -W`.
+4. **Forwarding**: Detected ports are forwarded through a single shared local daemon using OpenSSH `ssh -O forward -L`.
 5. **Domains**: The local DNS responder maps `<target>.<suffix>` → localhost. The browser's URL port selects the local forwarded port.
 
 When `sshx` is invoked for a **non-matching host** (no sshx config, or host not in scope), it first checks if the target resolves to a running Docker container. If neither SSH nor Docker matches, it `exec`s the real `ssh` directly — no daemon, no installation, no overhead.
@@ -361,6 +401,7 @@ When `sshx` is invoked for a **non-matching host** (no sshx config, or host not
 - `sshx local ...` on a **client** (not inside a remote session) — errors immediately with a clear message. `local` is globally reserved.
 - `remoteFs` never silently falls back to an unmounted command. A failed FUSE mount fails the invocation.
 - Remote exports are anchored with Go's `os.Root`; path traversal and symlink escapes are rejected.
+- The remote egress proxy is OpenSSH remote dynamic SOCKS bound only to loopback.
 - Docker containers that aren't running or can't be reached are pure passthrough — sshx falls back to raw `ssh` with no side effects.
 - Unmatched hosts are pure passthrough — no files created, no processes started.
 

package/bin/sshx.js

@@ -9,7 +9,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -38,13 +38,11 @@ if (!platform || !arch) {
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
 const version = packageJson.version;
-const binaryName = `sshx-${platform}-${arch}${platform === "windows" ? ".exe" : ""}`;
+const binaryName = `sshx-${platform}-${arch}`;
 const cacheRoot =
   process.env.SSHX_CACHE_DIR ||
   process.env.XDG_CACHE_HOME ||
-  (process.platform === "win32"
-    ? join(process.env.LOCALAPPDATA || tmpdir(), "sshx")
-    : join(homedir(), ".cache", "sshx"));
+  join(homedir(), ".cache", "sshx");
 const binaryPath = join(cacheRoot, version, binaryName);
 const refreshOnly =
   process.argv.length === 3 && process.argv[2] === npmRefreshArgument;
@@ -95,7 +93,7 @@ function findNpmIntegrationsToRefresh() {
     const descriptor = readIntegrationDescriptor(profileRoot);
     const isMarked = existsSync(markerPath);
     const isLegacyNpmIntegration =
-      descriptor !== null && pathIsInside(descriptor.driverPath, cacheRoot);
+      descriptor !== null && pathIsInside(descriptor, cacheRoot);
 
     if (!isMarked && !isLegacyNpmIntegration) {
       continue;
@@ -103,7 +101,7 @@ function findNpmIntegrationsToRefresh() {
     if (
       isMarked &&
       descriptor !== null &&
-      samePath(descriptor.driverPath, binaryPath)
+      samePath(descriptor, binaryPath)
     ) {
       continue;
     }
@@ -141,7 +139,7 @@ function readIntegrationDescriptor(profileRoot) {
       readFileSync(join(profileRoot, "integration.json"), "utf8"),
     );
     if (typeof value.driverPath === "string" && value.driverPath.length > 0) {
-      return value;
+      return value.driverPath;
     }
   } catch {
     // A marker without a readable descriptor is repaired by the native installer.
@@ -183,10 +181,6 @@ async function downloadBinary(destination) {
   }
 
   writeFileSync(tmpPath, Buffer.from(await response.arrayBuffer()));
-
-  if (platform !== "windows") {
-    chmodSync(tmpPath, 0o755);
-  }
-
+  chmodSync(tmpPath, 0o755);
   renameSync(tmpPath, destination);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hahahhh/sshx",
-  "version": "0.0.6",
+  "version": "0.0.7-rc.1",
   "type": "module",
   "description": "Transparent SSH enhancement wrapper for OpenSSH",
   "repository": {
@@ -22,6 +22,9 @@
   "scripts": {
     "build": "node scripts/build-native.js",
     "build:go": "go build -trimpath -ldflags \"-X github.com/xiaot623/sshx/internal/version.Version=${npm_package_version}\" -o sshx ./cmd/sshx",
+    "site": "npm --prefix docs install --no-audit --no-fund && npm --prefix docs run site",
+    "site:dev": "npm --prefix docs install --no-audit --no-fund && npm --prefix docs run dev",
+    "site:preview": "npm --prefix docs run preview",
     "check": "go vet ./...",
     "test": "go test ./... && node --test test/*.test.js",
     "postinstall": "node ./bin/sshx.js --npm-refresh-integrations",