server: bind loopback by default, name the address, and refuse a bad PF_HOST (#1527) #1639

Merged
jaylouisw merged 1 commit from fix/1116-0835 into main 2026-11-16 08:58:28 +00:00
Owner

Part of #1527 (item 1: the bind; item 2, the WebSocket Origin check, landed in #1629; item 3, the bearer token, is deliberately not here - there is no credential store to protect yet, see docs/plans/server-exposure.md), so the issue stays open.

What was wrong

server/index.js called server.listen(PORT) with no host, so Node bound 0.0.0.0/:: - every interface. The banner said Local: http://localhost:8000 regardless, so nothing in the log disagreed with a reader who assumed the server was local. A simulator on a cafe network, or one behind a reverse proxy, was reachable from anything that could route to it.

What changed

  • PF_HOST, default 127.0.0.1. Exposure is now something an operator asks for: PF_HOST=0.0.0.0 npm start. The Dockerfile sets PF_HOST=0.0.0.0, because a published port has to be reachable from the host - docker run -p 8000:8000 keeps working.
  • The banner prints the address that was bound, from server.address() rather than a hard-coded localhost, and says whether that is this machine only or reachable from other hosts.
  • A bad PF_HOST is refused in words. EADDRNOTAVAIL/ENOTFOUND now exit 1 with a message naming the address and PF_HOST, an IPv6 literal is bracketed, and PF_HOST=127.0.0.1:8000 (a host:port copied out of a URL) is named as that specific mistake. The old text blamed PORT and advised leaving it "unset to listen on all interfaces" - false on both counts, and it now says what is actually wrong.
  • test/server-bind.test.js (23 assertions) spawns the real server four ways: default answers on 127.0.0.1 and nothing accepts on the machine's first non-loopback IPv4; PF_HOST=0.0.0.0 does answer there and the banner stops claiming local-only; PF_HOST=192.0.2.123 (TEST-NET-1) exits 1 naming it with no stack trace; PF_HOST=127.0.0.1:<port> reports where the port belongs. The off-loopback half is skipped on a host with no non-loopback address.
  • Docs: SECURITY.md scope, README.md quick start (source and Docker), a paragraph in docs/ARCHITECTURE.md "The server", a CHANGELOG entry, and docs/plans/server-exposure.md step 1 marked landed.

Notes for the merge

  • The public demo is deployed from outside this repo. The image sets PF_HOST=0.0.0.0, so a container started from this Dockerfile keeps answering on its published port, but a host-side docker run that mounts the sources without the image's env needs PF_HOST=0.0.0.0 explicitly. Worth one check on that host after merge.
  • scripts/cf-access-bypass.js already reads a PF_HOST of its own for the forge hostname (git.jayw.uk). The collision is harmless in a fresh shell, and a shell that carries it now gets a clear refusal naming the value, but the script would be better off renaming its variable - not done here to keep this PR to one subject.

Tests

  • node scripts/syntax-check.js - 346 files, all OK.
  • test/server-bind.test.js - 23 passed, 0 failed.
  • test/startup-error.test.js - 25 passed, 0 failed.
  • test/ws-origin.test.js - 16 passed, 0 failed; scripts/smoke-http.js - clean; test/server-persistence.test.js - 13 passed.
  • npm test at the committed tree - 276 suites, 9873 assertions, 0 failed.
  • node scripts/check-doc-citations.js - same 7 pre-existing suspects, no new ones; check-dockerfile.js and check-control-bytes.js pass.
Part of #1527 (item 1: the bind; item 2, the WebSocket `Origin` check, landed in #1629; item 3, the bearer token, is deliberately not here - there is no credential store to protect yet, see `docs/plans/server-exposure.md`), so the issue stays open. ## What was wrong `server/index.js` called `server.listen(PORT)` with no host, so Node bound `0.0.0.0`/`::` - every interface. The banner said `Local: http://localhost:8000` regardless, so nothing in the log disagreed with a reader who assumed the server was local. A simulator on a cafe network, or one behind a reverse proxy, was reachable from anything that could route to it. ## What changed - **`PF_HOST`, default `127.0.0.1`.** Exposure is now something an operator asks for: `PF_HOST=0.0.0.0 npm start`. The `Dockerfile` sets `PF_HOST=0.0.0.0`, because a published port has to be reachable from the host - `docker run -p 8000:8000` keeps working. - **The banner prints the address that was bound**, from `server.address()` rather than a hard-coded `localhost`, and says whether that is this machine only or reachable from other hosts. - **A bad `PF_HOST` is refused in words.** `EADDRNOTAVAIL`/`ENOTFOUND` now exit `1` with a message naming the address and `PF_HOST`, an IPv6 literal is bracketed, and `PF_HOST=127.0.0.1:8000` (a `host:port` copied out of a URL) is named as that specific mistake. The old text blamed `PORT` and advised leaving it "unset to listen on all interfaces" - false on both counts, and it now says what is actually wrong. - **`test/server-bind.test.js`** (23 assertions) spawns the real server four ways: default answers on `127.0.0.1` and nothing accepts on the machine's first non-loopback IPv4; `PF_HOST=0.0.0.0` does answer there and the banner stops claiming local-only; `PF_HOST=192.0.2.123` (TEST-NET-1) exits 1 naming it with no stack trace; `PF_HOST=127.0.0.1:<port>` reports where the port belongs. The off-loopback half is skipped on a host with no non-loopback address. - Docs: `SECURITY.md` scope, `README.md` quick start (source and Docker), a paragraph in `docs/ARCHITECTURE.md` "The server", a CHANGELOG entry, and `docs/plans/server-exposure.md` step 1 marked landed. ## Notes for the merge - The public demo is deployed from outside this repo. The image sets `PF_HOST=0.0.0.0`, so a container started from this Dockerfile keeps answering on its published port, but a **host-side** `docker run` that mounts the sources without the image's env needs `PF_HOST=0.0.0.0` explicitly. Worth one check on that host after merge. - `scripts/cf-access-bypass.js` already reads a `PF_HOST` of its own for the forge hostname (`git.jayw.uk`). The collision is harmless in a fresh shell, and a shell that carries it now gets a clear refusal naming the value, but the script would be better off renaming its variable - not done here to keep this PR to one subject. ## Tests - `node scripts/syntax-check.js` - 346 files, all OK. - `test/server-bind.test.js` - 23 passed, 0 failed. - `test/startup-error.test.js` - 25 passed, 0 failed. - `test/ws-origin.test.js` - 16 passed, 0 failed; `scripts/smoke-http.js` - clean; `test/server-persistence.test.js` - 13 passed. - `npm test` at the committed tree - **276 suites, 9873 assertions, 0 failed**. - `node scripts/check-doc-citations.js` - same 7 pre-existing suspects, no new ones; `check-dockerfile.js` and `check-control-bytes.js` pass.
server: bind loopback by default, name the address, and refuse a bad PF_HOST (#1527)
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Server smoke test (pull_request) Successful in 22s
CI / Docker build (pull_request) Successful in 37s
CI / Test (Node 20) (pull_request) Successful in 1m22s
CI / Test (Node 18) (pull_request) Successful in 1m35s
CI / Test (Node 22) (pull_request) Successful in 1m38s
64e2fa8671
`server.listen(PORT)` with no host binds every interface, so a simulator started on a laptop in a
cafe - or behind a reverse proxy - was reachable from anything that could route to it. The banner
printed `localhost` either way, so nothing in the log disagreed with the reader's assumption. The
WebSocket upgrade has been Origin-checked since #1629; this is the other half of the same posture.

- `PF_HOST` names the address and defaults to 127.0.0.1. `PF_HOST=0.0.0.0` is how the container and
  the lab box ask to be reachable, and the Docker image sets it (a published port has to be reachable
  from the host) so `docker run -p 8000:8000` keeps working.
- The banner prints what `server.address()` actually reports, plus whether the socket is on this
  machine only or reachable from other hosts, instead of a hard-coded `localhost`.
- A `PF_HOST` this machine does not own (EADDRNOTAVAIL/ENOTFOUND) exits 1 naming that value and the
  variable, and a `host:port` copied out of a URL is named as that mistake. The old EADDRNOTAVAIL text
  blamed `PORT` and told the reader to leave it "unset to listen on all interfaces" - false on both
  counts, and it now says what is actually wrong.
- `test/server-bind.test.js` asserts the default answers on 127.0.0.1 and not on the machine's first
  non-loopback address, that 0.0.0.0 does answer there, that the banner says which it is, and the two
  refusal messages. docs/plans/server-exposure.md step 1 is marked landed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-16 08:58:17 +00:00
jaylouisw force-pushed fix/1116-0835 from 64e2fa8671
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Server smoke test (pull_request) Successful in 22s
CI / Docker build (pull_request) Successful in 37s
CI / Test (Node 20) (pull_request) Successful in 1m22s
CI / Test (Node 18) (pull_request) Successful in 1m35s
CI / Test (Node 22) (pull_request) Successful in 1m38s
to 04498b960d
All checks were successful
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 12s
CI / Test (Node 18) (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Has been skipped
CI / Test (Node 22) (pull_request) Has been skipped
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
2026-11-16 08:58:20 +00:00
Compare
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1639
No description provided.