{"id":"http-tunnel","repo":"lyhu/paseo-plugin-tunnel","url":"https://github.com/lyhu/paseo-plugin-tunnel","package":"paseo-plugin-tunnel","npm":{"package":"paseo-plugin-tunnel","version":"0.3.2","integrity":"sha512-y+L4gbLnYE8qCA3BQEr2sPlVk3+zcAqSRPs6skY6lHzF5gLMaFINLJSod+4zzTTyHp0sNcJodk0G7QsHDb8+Qw==","publishedAt":"2026-10-06T07:26:21.820Z","downloadsLast30Days":0},"name":"http-tunnel","description":"Controlled, end-to-end encrypted HTTP service connections for trusted Paseo hosts","categories":["productivity","other"],"platforms":[],"caveats":["Requires Paseo 0.8 or newer on every managed host.","Only forwards HTTP and HTTPS; no raw TCP, UDP, CONNECT, or WebSocket upgrade.","Egress listens on plaintext HTTP; terminate TLS at a reverse proxy for internet-facing use.","Requires Git, Node.js 22+, and npm on the daemon host with registry access.","iOS and Android UI flows are unverified; desktop and browser are tested"],"images":[],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-10-06T07:39:03.898Z","addedAt":"2026-10-06T07:35:33Z","npmSecurity":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-10-06T07:38:51.780Z","version":"0.3.2","integrity":"sha512-y+L4gbLnYE8qCA3BQEr2sPlVk3+zcAqSRPs6skY6lHzF5gLMaFINLJSod+4zzTTyHp0sNcJodk0G7QsHDb8+Qw=="},"version":"0.3.2","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-10-06T07:38:51.780Z","commit":"65d165c02ae6c03138e3a479d0e4607cb9b20996"},"author":"lyhu (https://github.com/lyhu)","license":"NOASSERTION","paseoVersionRequirement":">=0.8.0","descriptionNodes":[{"type":"text","text":"Controlled, end-to-end encrypted HTTP service connections for trusted Paseo hosts"}],"caveatNodes":[[{"type":"text","text":"Requires Paseo 0.8 or newer on every managed host."}],[{"type":"text","text":"Only forwards HTTP and HTTPS; no raw TCP, UDP, CONNECT, or WebSocket upgrade."}],[{"type":"text","text":"Egress listens on plaintext HTTP; terminate TLS at a reverse proxy for internet-facing use."}],[{"type":"text","text":"Requires Git, Node.js 22+, and npm on the daemon host with registry access."}],[{"type":"text","text":"iOS and Android UI flows are unverified; desktop and browser are tested"}]],"manifest":{"id":"http-tunnel","requirements":{"paseo":">=0.8.0"},"build":[["npm","ci","--omit=dev","--ignore-scripts","--no-audit","--no-fund"]]},"repoMeta":{"stars":2,"defaultBranch":"main","pushedAt":"2026-10-06T07:25:15Z"},"owner":{"login":"lyhu","avatarUrl":"https://avatars.githubusercontent.com/u/6790020?v=4"},"installNotesHtml":"

On each Ingress and Egress host, use the bundled Paseo CLI and daemon 0.8.0 or newer, matching the manifest's requirements.paseo. The host must support Git plugin sources, manifest build commands, and the v0.8 runtime entries (index.server.ts / index.client.tsx). Git, Node.js 22+, and npm must be available to the daemon process, with access to GitHub and the npm registry. If installation stops after the trust notice, see network troubleshooting.

\n

Paseo 0.9 and newer install from npm:

\n
paseo plugin install npm:paseo-plugin-tunnel\npaseo plugin ls\npaseo plugin status http-tunnel --json\n
\n

Paseo 0.8 installs from GitHub:

\n
paseo plugin install lyhu/paseo-plugin-tunnel\n
\n

The community source lyhu/paseo-plugin-tunnel expands to this GitHub repository and follows its default branch, currently main. To select a branch explicitly, use the full URL as an alternative:

\n
paseo plugin install https://github.com/lyhu/paseo-plugin-tunnel --ref main\n
\n

Both Git source forms accept --ref <branch-or-tag-or-commit>; npm sources do not, because the published package version already pins the revision. The official-plugin shorthand tunnel does not identify this community repository.

\n

Confirm source in the status output: \"npm\" for npm installs, \"git\" with ref: \"main\" for Git installs. A running plugin installed from a local checkout is a directory source, even if that checkout contains .git; `paseo …

","readmeText":"# Paseo HTTP Tunnel\n\n[中文文档](docs/README.zh-CN.md) · [Architecture](docs/design.md) · [Installation details](docs/installation.md) · [Changelog](CHANGLOG.md)\n\nConnect an HTTP or HTTPS service you manage to another trusted Paseo host through the Paseo Relay and end-to-end encryption. Manage each connection from the **HTTP Tunnel** entry in Paseo's sidebar.\n\n```text\nClient → Egress → Encrypted relay connection → Ingress → HTTP / HTTPS service\n```\n\nIngress runs on the host that can reach your service. Egress provides a controlled access point on another host you manage. A **Route Offer** connects the two installations without requiring both hosts to be open in the UI at the same time.\n\nBuilt for [Paseo](https://paseo.sh/) · [Official Paseo repository](https://github.com/getpaseo/paseo)\n\n## Capabilities\n\n- Stream HTTP requests, responses, binary bodies, and server-sent events (SSE).\n- Choose local-only access or authenticate callers with an Access Token or Bearer Token; preserve upstream API authentication in Access Token mode.\n- Manage listeners, rotate credentials, and import or replace Route Offers per host.\n- Generate copyable curl commands and test requests from the Egress host.\n- Follow Paseo's theme and language settings across nine supported languages.\n\nThe plugin runs in a dedicated Node.js subprocess. Traffic continues while the Paseo app is closed, as long as the host daemon remains running.\n\n## Install\n\nOn each Ingress and Egress host, use the bundled Paseo CLI and daemon **0.8.0 or newer**, matching the manifest's `requirements.paseo`. The host must support **Git plugin sources, manifest build commands, and the v0.8 runtime entries** (`index.server.ts` / `index.client.tsx`). Git, Node.js 22+, and npm must be available to the daemon process, with access to GitHub and the npm registry. If installation stops after the trust notice, see [network troubleshooting](docs/installation.md#troubleshooting).\n\nPaseo 0.9 and newer install from npm:\n\n```bash\npaseo plugin install npm:paseo-plugin-tunnel\npaseo plugin ls\npaseo plugin status http-tunnel --json\n```\n\nPaseo 0.8 installs from GitHub:\n\n```bash\npaseo plugin install lyhu/paseo-plugin-tunnel\n```\n\nThe community source `lyhu/paseo-plugin-tunnel` expands to this GitHub repository and follows its default branch, currently `main`. To select a branch explicitly, use the full URL as an alternative:\n\n```bash\npaseo plugin install https://github.com/lyhu/paseo-plugin-tunnel --ref main\n```\n\nBoth Git source forms accept `--ref `; npm sources do not, because the published package version already pins the revision. The official-plugin shorthand `tunnel` does not identify this community repository.\n\nConfirm `source` in the status output: `\"npm\"` for npm installs, `\"git\"` with `ref: \"main\"` for Git installs. A running plugin installed from a local checkout is a directory source, even if that checkout contains `.git`; `paseo plugin update` cannot update directory sources.\n\nEnable plugins in **Settings → Plugins** if needed. Paseo loads plugins as trusted host extensions: backend code and installation commands run with the daemon user's permissions, and the UI runs inside Paseo. Review the source and install it only on hosts you administer. Private repositories require Git credentials on the daemon host.\n\n**No precompiled release asset is required.** Paseo installs the source, runs the manifest's dependency installation command, then compiles the server from `index.server.ts` and the client UI from `index.client.tsx`. You do not need to run `npm run build`, upload `dist`, or download a release asset. Runtime dependencies are pinned by the committed `npm-shrinkwrap.json`, which npm also ships inside the published package so that installs stay reproducible. See [installation details](docs/installation.md) for pinned revisions and local development.\n\n## Use HTTP Tunnel\n\nUse your local Paseo UI to manage connected hosts, including remote hosts running only the daemon. Install and enable `http-tunnel` on each host first.\n\nThe **Host picker is in the upper-right corner of the HTTP Tunnel page**. When multiple connected hosts have the plugin installed, open this picker to switch the host currently being managed. The Ingresses, Egresses, forms, status checks, and quick tests shown on the page all belong to the selected host. Switching the Host picker changes the RPC destination; it does not copy rules between hosts. If the picker contains only one host, verify that the other host is connected and has `http-tunnel` installed and running. After upgrading to Paseo 0.8, every managed host must run HTTP Tunnel **0.3.1 or later** — a host still on the pre-0.8 plugin is rejected by Paseo 0.8 and drops out of the picker. See [remote host setup](docs/installation.md#remote-hosts).\n\n1. **Step 1 (Select Service Host)**: Open **HTTP Tunnel** from Paseo's left sidebar. In the **upper-right Host picker**, select the machine that can reach the private service.\n2. **Step 2 (Add Ingress)**: Select **Add ingress**. Enter a name and an origin reachable from the selected host, such as `http://127.0.0.1:3000` (where `127.0.0.1` refers to the selected host). An origin contains only a scheme, hostname, and optional port.\n3. **Step 3 (Copy Route Offer)**: Select **Copy Route Offer** to copy the complete JSON configuration (preview is masked). Share this sensitive connection configuration securely with the target Egress host administrator.\n4. **Step 4 (Import to Egress)**: Switch the **upper-right Host picker** to the Egress machine. Select **Add egress**, paste the offer, and configure the listener binding and authentication mode. When using authentication, save the Access Token shown once after creation.\n5. **Step 5 (Verify & Invoke)**: Expand **curl / Quick test** under the Egress to copy the generated command or verify the route directly from the selected Egress host.\n\nListeners default to `127.0.0.1`, which keeps access on the Egress host. Choose **All network interfaces** only for an approved network where other clients need access, and apply the host firewall and access policy you normally use for that service. For an Internet-facing endpoint, terminate HTTPS at a reverse proxy in front of Egress.\n\n### Authentication\n\n| Mode | Caller credential | Forwarding behavior |\n| --- | --- | --- |\n| None — default | No plugin credential | Access is governed by the listener binding and surrounding network controls. |\n| Header | `X-Paseo-Access-Token: ` | Removes the tunnel token; preserves the API's `Authorization` header. |\n| Bearer | `Authorization: Bearer ` | Removes `Authorization` after validating the tunnel token. |\n\nUse Header mode when the private API requires its own Bearer Token:\n\n```bash\ncurl 'https://egress.example.com/api/health' \\\n --header 'X-Paseo-Access-Token: ' \\\n --header 'Authorization: Bearer '\n```\n\nRoute Offers and Access Tokens are independent credentials. Rotating an Ingress secret invalidates every existing offer for that route; distribute a new offer to each Egress. Rotating an Egress token requires callers to update their token.\n\n## Connection status\n\nEach rule has a status dot. **Green** means HTTP reachability was verified; **yellow** means offline, disabled, or still checking.\n\n- Ingress requires an active Relay connection and an HTTP response from its target origin.\n- Egress requires a running listener and an HTTP response through Relay, E2EE, and the imported Route Offer.\n\nWhile a page is polling the host, checks send `HEAD /` without API credentials approximately every 15 seconds. Checks time out after 8 seconds, do not follow redirects, and stop at response headers. Results are shared between viewers, with at most four checks in flight. Changes invalidate old results; host failures and stale results cannot remain green.\n\nAny upstream HTTP response, including 401, 404, or 5xx, proves connectivity. The displayed HTTP status is not a claim that API authentication or business operations succeed. Public DNS, inbound firewall rules, and the external reverse proxy are outside this check; use the request panel to test an API operation.\n\n## Verify requests\n\nOpen **curl / Quick test** under an Egress. Choose GET or POST, set the path and query, and provide a JSON body when needed. The panel generates a POSIX-shell curl command with the headers required by the selected authentication mode.\n\nNewly generated tokens are available in the current page's memory. For an existing rule, paste the token or rotate it. Without a token, curl contains an `` placeholder and the test action is disabled.\n\n**Send test request** calls the listener through loopback on the Egress host and reports the HTTP status, duration, content type, and response preview. It does not test public DNS, firewall rules, or an external HTTPS reverse proxy. The request origin field affects the curl command only.\n\nTests time out after 10 seconds, do not follow redirects, and retain at most 8 KiB of response data. SSE previews stop after the first data chunk. Input tokens echoed verbatim by the service are redacted from the preview.\n\n## Operate and update\n\n```bash\npaseo plugin status http-tunnel\npaseo plugin update http-tunnel\npaseo plugin logs http-tunnel\n```\n\nGit installations following `main` receive updates through `plugin update`. Use `--ref ` at installation to pin a reviewed revision. `plugin reload http-tunnel` reloads the installed source without fetching Git changes. Reloading or updating can interrupt active tunnel requests; neither requires restarting the main Paseo daemon.\n\nConfiguration is stored independently in `$PASEO_HOME/tunnel/config.json`, or `~/.paseo/tunnel/config.json` when `PASEO_HOME` is unset. Access Tokens are stored as hashes; the file contains private route credentials and must remain private. The default Relay is `relay.paseo.sh:443` over TLS. For a self-hosted Relay, see [Relay configuration](docs/installation.md#relay-configuration).\n\n## Install with an agent\n\nCopy this prompt into an agent running on the intended Paseo host:\n\n```text\nInstall and enable the trusted plugin `lyhu/paseo-plugin-tunnel` on this Paseo host (authorized to run with daemon permissions).\n\n### Execution Instructions\n1. **Pre-flight Checks**:\n - Check Paseo CLI, target daemon, Git, Node.js 22+, npm, and GitHub/npm connectivity.\n - Confirm Git source and --ref support; read README and paseo-plugin.json before installation.\n - Inspect existing plugins: if already installed, retain existing rules/credentials and report current status without overwriting.\n2. **Installation**:\n - Enable plugin support through the target host’s Settings → Plugins if needed.\n - Run: `paseo plugin install lyhu/paseo-plugin-tunnel`\n - Must install directly via the Git source (owner/repo). Do not clone locally, register directory sources, or patch lockfiles.\n - If installation or dependency setup fails, report the redacted error and stop; do not fallback to directory installation.\n3. **Verification** (all must pass):\n - `paseo plugin ls --json`: reports `http-tunnel` as `running`.\n - `paseo plugin status http-tunnel --json`: verify `source=git`, `ref=main`, expected repository, and `currentCommit`.\n - `paseo plugin update http-tunnel`: update check succeeds.\n4. **Guardrails & Reporting**:\n - Inspect `paseo plugin logs http-tunnel` for troubleshooting; never expose credentials.\n - Do not restart the main daemon, create tunnel rules, bind public ports, or build/publish artifacts.\n - Ask only if host access or credentials are fundamentally missing. Report host, source, ref, installed commit, and update check result upon completion.\n```\n\n## Intended use and technical scope\n\nHTTP Tunnel is designed for development services, internal APIs, dashboards, model endpoints, and other approved operational workflows between trusted Paseo hosts. Deploy it only with hosts, services, networks, and data you own or are authorized to administer.\n\n### ✅ Supported Capabilities\n- **HTTP/1.1 Forwarding**: Supports standard HTTP methods, paths, query strings, repeated response headers, streaming upload/download, and Server-Sent Events (SSE).\n- **Target HTTPS**: Upstream target services support HTTPS with strict public/custom CA certificate validation.\n- **Auto Recovery**: Ingress automatically reconnects if the Relay connection drops; reloads restore persisted rules automatically.\n\n### ❌ Unsupported Capabilities\n- **Non-HTTP Traffic**: No arbitrary TCP port forwarding, UDP forwarding, or raw socket proxying.\n- **Protocol Extensions**: No `CONNECT` tunneling, `WebSocket Upgrade`, or HTTP trailers.\n- **Complex Routing**: No multi-target path/host routing on a single listener, load balancing, or automatic request retries.\n\n### 🛡️ Guardrails and Resource Limits\n- **Flow Control**: Bidirectional $8 \\times 64\\text{ KiB}$ sliding window; advances upon oldest block ACK to avoid transfer pauses.\n- **Resource Quotas**: Up to 128 active data channels per runtime; up to 256 concurrent HTTP sockets per Egress with a 10s header timeout.\n- **Security Boundary**: Egress provides a plaintext HTTP listener, bound to loopback by default. For Internet-facing endpoints, terminate HTTPS at an external reverse proxy (Nginx, Caddy, etc.); end-to-end encryption secures the transport between Egress and Ingress.\n\nFor development, clone the repository, run `npm ci`, then use `npm run typecheck`, `npm run lint`, and `npm run build`. Run tests by file with `npm run test:file -- `. See [benchmark methodology and results](docs/benchmark.md), [architecture](docs/design.md) and [verification coverage](VERIFICATION.md). Desktop and browser workflows are verified; iOS and Android require device validation.\n\n## License\n\n[AGPL-3.0-only](LICENSE). Includes HTTP tunnel components derived from Paseo.\n"}