portpreview 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +74 -251
  2. package/package.json +9 -5
package/README.md CHANGED
@@ -1,278 +1,101 @@
1
1
  # PortPreview CLI
2
2
 
3
- Open-source client for [PortPreview](https://portpreview.com) — expose a local port through a public URL for webhook debugging, OAuth callbacks, and dev previews.
3
+ [![npm](https://img.shields.io/npm/v/portpreview)](https://www.npmjs.com/package/portpreview)
4
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
4
5
 
5
- ## Usage
6
-
7
- ```bash
8
- npx portpreview 3000
9
- ```
10
-
11
- That connects to the PortPreview gateway and forwards public traffic to `http://127.0.0.1:3000`.
12
-
13
- ## Install in this repo
14
-
15
- From the project root:
6
+ Open-source localhost tunnel client for [PortPreview](https://portpreview.com).
7
+ One command gives a local HTTP server a public HTTPS URL on `*.portpreview.dev`
8
+ for webhook debugging, OAuth callbacks, and client or mobile previews — without
9
+ deploying to staging.
16
10
 
17
11
  ```bash
18
- npm install
19
12
  npx portpreview 3000
20
13
  ```
21
14
 
22
- `npx` picks up the local CLI from `node_modules/.bin` before hitting the npm registry.
23
-
24
- ## Publish to npm
25
-
26
- ```bash
27
- cd cli
28
- npm login
29
- npm publish
30
- ```
31
-
32
- After the current package version is published to npm, `npx portpreview 3000` works from any directory without cloning this repo.
33
-
34
- ## Standalone Windows x64
35
-
36
- The standalone executable includes Node.js and the same CLI used by npm. On a
37
- verified release, download the versioned `.exe` and its `.sha256` file, check the
38
- hash with `Get-FileHash`, then run in PowerShell:
39
-
40
- ```powershell
41
- .\portpreview-0.2.0-windows-x64.exe --help
42
- .\portpreview-0.2.0-windows-x64.exe 3000
43
- .\portpreview-0.2.0-windows-x64.exe config set-token pp_live_...
44
- ```
45
-
46
- No Node.js or npm installation is needed to run the executable. Windows tokens
47
- are stored in `%LOCALAPPDATA%\portpreview\config.json` by default. Current builds
48
- are unsigned. Download availability depends on successful Windows verification;
49
- a cross-built artifact alone is not a verified release. See
50
- [Windows packaging and release checks](packaging/README.md).
51
-
52
- ## Local development (no production gateway)
53
-
54
- ```bash
55
- # Terminal 1 — dev gateway
56
- npm run gateway --prefix cli
57
-
58
- # Terminal 2 — your app
59
- python3 -m http.server 3000
60
-
61
- # Terminal 3 — tunnel
62
- npx portpreview 3000 \
63
- --gateway ws://127.0.0.1:4040/tunnel \
64
- --domain localhost:4040
65
15
  ```
66
-
67
- ## Options
68
-
69
- | Flag | Description |
70
- |------|-------------|
71
- | `--host` | Local address to forward to (default `127.0.0.1`) |
72
- | `--subdomain` | Use a name reserved in your dashboard |
73
- | `--token` | Authenticate with a dashboard CLI token |
74
- | `--inspect` / `--no-inspect` | Turn the local request inspector on or off (default: on, off with `--quiet`) |
75
- | `--inspect-port <n>` | Inspector port on `127.0.0.1` (default `4041`) |
76
- | `-q, --quiet` | Print only the public URL |
77
- | `-h, --help` | Show help |
78
- | `-v, --version` | Show version |
79
-
80
- ## Environment
81
-
82
- | Variable | Description |
83
- |----------|-------------|
84
- | `PORTPREVIEW_TOKEN` | CLI token used for reserved subdomains |
85
- | `PORTPREVIEW_CONFIG` | Override local config file path |
86
- | `PORTPREVIEW_INSPECT` | `1` or `0` to turn the request inspector on or off |
87
- | `PORTPREVIEW_INSPECT_PORT` | Request inspector port (default `4041`) |
88
-
89
- See **Local development** below for `--gateway`, `--domain`, and related env vars.
90
-
91
- ## TCP tunnels (paid plans)
92
-
93
- ```bash
94
- npx portpreview config set-token pp_live_...
95
- npx portpreview tcp 5432
96
- ```
97
-
98
- ```
99
- URL: tcp://tcp.portpreview.dev:20017
100
- Target: 127.0.0.1:5432
101
- ```
102
-
103
- Raw TCP for databases, SSH and other non-HTTP services. Available on Pro, Ultra and Team; each
104
- account has one stable port, so the address is the same on every run and one TCP tunnel can run at
105
- a time. Up to 50 concurrent connections, at most 10 from one source address; a connection with no
106
- traffic for 30 minutes is closed.
107
- Each closed connection is logged with its duration and byte counts.
108
-
109
- PortPreview adds no TLS and no password on the public side of a TCP tunnel: anyone who knows the
110
- address can connect, so expose only services that authenticate and encrypt connections themselves.
111
- There is no UDP, and the request inspector does not apply to TCP tunnels.
112
-
113
- Self-hosted gateways enable TCP tunnels with `PORTPREVIEW_TCP_PORTS=20000-20099` (the public port
114
- range), optionally `PORTPREVIEW_TCP_HOST` and `PORTPREVIEW_TCP_PUBLIC_HOST`.
115
-
116
- ## Local request inspector
117
-
118
- While the tunnel runs, the CLI serves a local web UI that lists every request that
119
- reached it, with headers and bodies, and can replay a request against your app:
120
-
121
- ```text
122
- Connected
123
- URL: https://abc12.portpreview.dev
124
- Inspect: http://127.0.0.1:4041
16
+ URL: https://jjm5s.portpreview.dev
125
17
  Target: http://127.0.0.1:3000
126
18
  ```
127
19
 
128
- - **What it shows:** method, path, status, duration and size; request and response
129
- headers (response headers in the app's original casing); bodies as pretty JSON or
130
- form fields, raw text, or hex (first 4 KiB), plus a raw download. Gzip, deflate and
131
- Brotli bodies are decoded for display. WebSocket connections are listed with frame
132
- and byte counts and the close code (frame contents are not recorded yet). Filters:
133
- method, status class, path substring, hide static assets.
134
- - **Replay** sends the captured request again, straight to the local app (not through
135
- the gateway, so it also works while the tunnel reconnects). Method, path, headers
136
- and body are exactly what the app received the first time, including
137
- `X-Forwarded-*`; only `Host`, `Connection` and `Content-Length` are regenerated, and
138
- no marker header is added. The replayed request appears as a new entry linked to the
139
- original, and the terminal logs it with a `(replay)` suffix. Requests whose body was
140
- only partly captured, that are still in flight, or WebSockets cannot be replayed.
141
- Webhook signatures with a timestamp (Stripe, Slack, Svix/Clerk) are usually rejected
142
- after about five minutes; GitHub and Shopify signatures have no timestamp.
143
- - **Edit & replay** opens the captured request in an editor: method (GET, HEAD, POST,
144
- PUT, PATCH, DELETE, OPTIONS), path and query, headers as `name: value` lines (secret
145
- headers are shown in full here, since you are editing them), and the body as text.
146
- A body that is not UTF-8 text (images, protobuf, gzip) is kept byte for byte unless
147
- you choose to edit it as text, and an untouched text body is also sent as the
148
- captured bytes, so CRLF line endings survive. Requests whose body was only partly
149
- captured can be edited too; the editor says the body is partial and asks you to
150
- confirm it or replace it. The edited request goes straight to the local app, appears
151
- as a new entry marked `edited` and linked to the original, and the terminal logs it
152
- with a `(replay, edited)` suffix. `Host`, `Connection`, `Content-Length` and
153
- `Transfer-Encoding` are always regenerated, whatever the editor contains. Limits:
154
- 1 MiB body, 200 headers and 64 KiB of headers in total, 8 KiB path.
155
- - **Copy as cURL** builds a command for the local target or the public URL. It
156
- contains the captured header values, so treat it as a secret.
157
- - **Limits:** the newest 200 entries, 1 MiB per request body, 256 KiB per response
158
- body and 32 MiB in total; larger bodies are marked truncated (the app and the
159
- visitor still get every byte). Data lives only in the CLI's memory and is gone when
160
- it exits. Only requests that reached this CLI appear; requests the gateway rejects
161
- (body too large, preview password, IP allowlist, tunnel offline) do not.
162
- - **Port:** `4041` by default. If it is busy the CLI tries 4042–4050 and then a random
163
- free port, and prints the one it got. A port set with `--inspect-port` or
164
- `PORTPREVIEW_INSPECT_PORT` is used as is: if it is busy the CLI prints a warning
165
- and runs without the inspector. The inspector never stops or delays the tunnel.
166
- - **On by default** for interactive runs. `--quiet` turns it off unless you also pass
167
- `--inspect` (the `Inspect:` line then goes to stderr, so stdout stays just the URL).
168
- Library callers of `openTunnel` get no inspector unless they pass one (see below).
20
+ No signup and no config file. Requires Node.js 18 or newer.
21
+
22
+ ## What you get
23
+
24
+ - **Public HTTPS URL** that forwards to `http://127.0.0.1:<port>`; visitors see
25
+ your app directly, with no warning or interstitial page.
26
+ - **Live request log** in the terminal: method, path, status, and response time
27
+ of every request, e.g. `POST /webhooks/stripe 200 19ms`.
28
+ - **Local request inspector** at `http://127.0.0.1:4041` while the CLI runs: headers,
29
+ bodies, copy as cURL, replay, and edit-and-replay against your app. No account;
30
+ nothing leaves your machine.
31
+ - **Webhook-safe forwarding**: raw bodies and headers reach your app unchanged,
32
+ so Stripe and GitHub signature checks pass. `Host` is rewritten to
33
+ `127.0.0.1:<port>`, so Vite and similar dev servers need no `allowedHosts` change.
34
+ - **WebSocket, Server-Sent Events, and HMR** through the tunnel.
35
+ - **Streaming bodies** with no total size limit, and automatic reconnect with
36
+ backoff after network loss.
37
+ - **No session time limit** on any plan.
38
+
39
+ With a free account you also get a reserved subdomain, request history in the web
40
+ dashboard, and password or IP allowlist protection for previews. Paid plans add raw
41
+ TCP tunnels: `npx portpreview tcp 5432` gives `tcp.portpreview.dev:<port>`. See
42
+ [pricing](https://portpreview.com/pricing).
169
43
 
170
- **Security.** The inspector listens on `127.0.0.1` only and has no login, like ngrok's
171
- local inspector: any program on this machine can read it. It rejects requests whose
172
- `Host` is not `127.0.0.1:<port>`, `localhost:<port>` or `[::1]:<port>` (DNS
173
- rebinding), never sends CORS headers, and accepts replay, edited replay and clear only
174
- with an `X-PortPreview-Inspector: 1` header, `Content-Type: application/json` and a
175
- matching `Origin`, so other websites cannot trigger them. Pages use a nonce-based CSP and
176
- render captured data as text only; raw bodies download as attachments. The values of
177
- `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie` and `X-API-Key` are
178
- hidden on screen until clicked; they are stored unmodified because replay needs them.
179
- On a shared machine where you do not trust other local users, run with `--no-inspect`.
180
-
181
- **Edited replay from a script.** The editor uses `POST /api/replay`, which answers
182
- `{ "id": <new entry id> }`:
183
-
184
- ```bash
185
- curl http://127.0.0.1:4041/api/replay \
186
- -H 'X-PortPreview-Inspector: 1' -H 'Content-Type: application/json' \
187
- -d '{"replayOf":12,"method":"POST","path":"/webhooks/stripe",
188
- "headers":[["Content-Type","application/json"],["X-Dup","a"],["X-Dup","b"]],
189
- "body":"{\"type\":\"invoice.paid\"}"}'
190
- ```
191
-
192
- `headers` is a list of `[name, value]` pairs (repeated names are sent as separate
193
- lines) or an object; `body` is UTF-8 text, or base64 with `"bodyEncoding": "base64"`;
194
- `replayOf` is optional. Invalid input gets `400` with a message (method outside the
195
- list, a path that does not start with a single `/` or contains a backslash, spaces or
196
- control characters, a header name that is not an HTTP token, CR/LF/NUL in a value,
197
- unknown fields); a body over 1 MiB, or a request over 3 MiB, gets `413`.
198
-
199
- Library use:
200
-
201
- ```js
202
- import { openTunnel, createInspectorStore, startInspectorServer } from 'portpreview'
203
-
204
- const store = createInspectorStore()
205
- const tunnel = await openTunnel({ port: 3000, host: '127.0.0.1', gatewayUrl, tunnelDomain, quiet: true, inspector: store })
206
- const inspector = await startInspectorServer({ store, target: { host: '127.0.0.1', port: 3000 }, port: 4041 })
207
- console.log(inspector.url)
208
- await tunnel.closed
209
- await inspector.close()
210
- ```
211
-
212
- The server does not keep the process alive on its own.
213
-
214
- ## Persistent token (recommended)
44
+ ## Usage
215
45
 
216
46
  ```bash
217
- npx portpreview config set-token pp_live_...
218
- npx portpreview 3000
219
- npx portpreview config check
47
+ npx portpreview 3000 # random subdomain
48
+ npx portpreview config set-token pp_live_... # save a CLI token from the dashboard
49
+ npx portpreview 3000 --subdomain my-app # reserved subdomain
50
+ npx portpreview tcp 5432 # raw TCP tunnel (paid plans)
220
51
  ```
221
52
 
222
- Default config file: `~/.config/portpreview/config.json` on Linux.
223
-
224
- Gateway deployments also require `GATEWAY_API_SECRET` (shared with the website) and may set
225
- `PORTPREVIEW_ACCOUNT_API_URL`, `PORTPREVIEW_MAX_TUNNELS`, and
226
- `PORTPREVIEW_MAX_REQUEST_BODY_BYTES`.
53
+ | Option | Description |
54
+ |---|---|
55
+ | `--host <addr>` | Local address to forward to (default `127.0.0.1`) |
56
+ | `--subdomain <name>` | Use a subdomain reserved by your account |
57
+ | `--token <token>` | Authenticate with a CLI token |
58
+ | `--gateway <url>` | Gateway WebSocket URL (default `wss://gateway.portpreview.dev/tunnel`) |
59
+ | `--domain <domain>` | Public tunnel domain (default `portpreview.dev`) |
60
+ | `--no-inspect` / `--inspect-port <n>` | Turn the local inspector off, or choose its port (default `4041`) |
61
+ | `-q, --quiet` | Print only the public URL |
62
+ | `-h, --help` / `-v, --version` | Help and version |
227
63
 
228
- ## Tests
64
+ | Environment variable | Description |
65
+ |---|---|
66
+ | `PORTPREVIEW_TOKEN` | CLI token |
67
+ | `PORTPREVIEW_CONFIG` | Config file path (default `~/.config/portpreview/config.json` on Linux) |
68
+ | `PORTPREVIEW_GATEWAY_URL` | Gateway WebSocket URL |
69
+ | `PORTPREVIEW_TUNNEL_DOMAIN` | Public tunnel domain |
229
70
 
230
- ```bash
231
- npm test --prefix cli
71
+ If your server listens only on IPv6 `::1` (default Vite), start it with
72
+ `--host 127.0.0.1` or pass `--host ::1` to the CLI.
232
73
 
233
- # Opt-in: generated >5 GiB upload and download, checksums, bounded memory; no disk body
234
- RUN_LARGE_STREAM_TEST=1 node --test --test-concurrency=1 cli/test/streaming.test.mjs
74
+ ## Limits
235
75
 
236
- # Opt-in: real wall-clock session for 2 hours + 90 seconds
237
- node cli/test/tunnel-soak.mjs
238
- ```
76
+ - HTTP and WebSocket on every plan; raw TCP on paid plans; no UDP.
77
+ - WebSocket messages up to 1 MiB each.
78
+ - Streams with no progress for 120 seconds are closed.
79
+ - One gateway region (Tokyo, Japan).
80
+ - The local inspector keeps the last 200 requests in memory; the dashboard stores
81
+ the first 64 KiB of each body.
82
+ - A tunnel URL is not a secret: its TLS certificate is listed in public Certificate
83
+ Transparency logs, so scanners usually find a new URL within minutes. Do not expose
84
+ debug endpoints; protect reserved previews with a password or an IP allowlist.
239
85
 
240
- ## Tunnel sessions and request history
86
+ Full reference: [portpreview.com/docs](https://portpreview.com/docs).
241
87
 
242
- Free accounts and anonymous visitors can run one active tunnel at a time.
243
- Tunnel sessions have no duration limit on any plan. Self-hosted gateways older
244
- than 0.2.0 can retain their previous session limits until they are upgraded.
88
+ ## What is open source
245
89
 
246
- The 0.2.0 client negotiates protocol v3 with a 0.2.0 gateway. HTTP
247
- request and response bodies stream without a total byte, traffic, or active
248
- transfer duration limit. Each direction uses 64 KiB chunks and a 256 KiB credit
249
- window; the hosted dashboard captures only the first 64 KiB and marks incomplete previews.
250
- Range, If-Range, ETag, Content-Range and original Content-Length are preserved,
251
- including 206/416 and HEAD. Streams with no progress for 120 seconds are
252
- cancelled; active slow streams may continue indefinitely. Tunnel transport
253
- heartbeats detect dead connections. After transient network loss, the CLI
254
- reconnects automatically with exponential backoff and jitter, from 500 ms up to
255
- 30 seconds. Anonymous tunnels may receive a new URL, which the command announces;
256
- reserved tunnels retry with the same subdomain and token. Access revocation and
257
- permanent registration or authentication errors stop retries. Ctrl+C cancels
258
- pending connection attempts and retry timers.
90
+ This repository contains the CLI client published to npm as
91
+ [`portpreview`](https://www.npmjs.com/package/portpreview). The hosted gateway,
92
+ dashboard, request history, and billing are not open source.
259
93
 
260
- Interrupted HTTP transfers are cancelled and must be retried by the application;
261
- reconnecting does not replay requests or resume their bytes. Applications can
262
- resume downloads with Range and If-Range when the upstream supports them. Library
263
- callers can observe the current URL through the returned `url` getter or an
264
- `onReconnect` callback.
94
+ `npm test` here covers argument parsing, the wire protocol, the token store and a
95
+ tunnel against a small fixture gateway. The streaming, reconnect, inspector and TCP
96
+ suites need the hosted gateway code and run in the private repository before each
97
+ release.
265
98
 
266
- Clients older than 0.2.0 and fallback to older v2 gateways retain the legacy
267
- 1 MiB HTTP body cap; both ends need upgrading for streaming. WebSocket messages
268
- retain an explicit 1 MiB per-message limit; oversized messages close rather than
269
- silently truncate. Requests made by automated agents and webhooks are included
270
- in request history.
99
+ ## License
271
100
 
272
- Protect reserved preview domains with a password or IP/CIDR allowlist in the
273
- dashboard (all plans). A password uses HTTP Basic authentication; enter any
274
- username and your preview password. This credential is consumed by the gateway
275
- and is not forwarded to localhost. Application HTTP Basic authentication cannot
276
- share the same Authorization header, so use an application session cookie or a
277
- bearer token route without preview password protection. Policy changes and token
278
- revocations take effect within 30 seconds on connected gateways.
101
+ [Apache-2.0](LICENSE) © 2026 ElemOps
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "portpreview",
3
- "version": "0.3.1",
3
+ "version": "0.3.2",
4
4
  "description": "Instant secure previews for localhost apps — expose a local port through a public HTTPS URL.",
5
5
  "type": "module",
6
6
  "main": "./lib/index.mjs",
@@ -35,8 +35,6 @@
35
35
  "scripts": {
36
36
  "prepublishOnly": "npm test",
37
37
  "start": "node bin/portpreview.mjs",
38
- "gateway": "node bin/gateway.mjs",
39
- "telegram-daemon": "node bin/telegram-daemon.mjs",
40
38
  "test": "node --test test/*.test.mjs"
41
39
  },
42
40
  "keywords": [
@@ -45,7 +43,10 @@
45
43
  "preview",
46
44
  "webhook",
47
45
  "devtools",
48
- "cli"
46
+ "cli",
47
+ "ngrok",
48
+ "localtunnel",
49
+ "tcp-tunnel"
49
50
  ],
50
51
  "engines": {
51
52
  "node": ">=18"
@@ -60,7 +61,10 @@
60
61
  "url": "https://github.com/elemops/portpreview/issues"
61
62
  },
62
63
  "dependencies": {
63
- "node-telegram-bot-api": "^1.2.0",
64
64
  "ws": "^8.19.0"
65
+ },
66
+ "publishConfig": {
67
+ "access": "public",
68
+ "registry": "https://registry.npmjs.org/"
65
69
  }
66
70
  }