PR #84008: fix(cli): reject out-of-range port numbers in parsePort (#83900)

• Repository: openclaw/openclaw
• Author: hclsys
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/84008

Description (problem / solution / changelog)

Fixes #83900.

parsePort (src/cli/shared/parse-port.ts) delegated to parseStrictPositiveInteger, which only enforces positivity. Any value above 65535 — the 16-bit TCP/UDP maximum — was returned as-is and reached the gateway-cli / node-cli / daemon-cli bind paths. The OS then surfaced the error at bind/connect time instead of the CLI rejecting it cleanly at parse time. The function's documented contract (number | null) implied a valid port, but the implementation didn't enforce the upper bound.

Changes

• src/cli/shared/parse-port.ts: introduce a MAX_TCP_PORT = 65_535 constant and reject any parseStrictPositiveInteger result above it by returning null (the same shape callers already handle for zero, negative, NaN, and non-integer inputs).
• src/cli/shared/parse-port.test.ts: new file. 5 regression cases covering nullish inputs, zero/negative (already-enforced), the valid range including the inclusive 65535 boundary, the issue's exact 99999 and 100000 repros, and non-integer / non-finite / NaN inputs.

Diff stat: 2 files, +48 / -1.

Real behavior proof

• Behavior or issue addressed: Sanitized issue evidence — parsePort('99999') returned 99999, which then reached gateway-cli/run.ts:531 (portOverride = parsePort(opts.port)) and node-cli/daemon.ts:82 as a "valid" override. The OS-level bind error surfaces downstream instead of a clean CLI-level rejection.

• Real environment tested: Local Node 22.x. Probe at /tmp/probe_83900.mjs (a) parses the patched parse-port.ts and verifies the MAX_TCP_PORT constant + the guard shape (parsed === undefined || parsed > MAX_TCP_PORT) + the preserved nullish early-return, and (b) replays both the patched and pre-fix shapes against 11 fixtures: valid 1 / 8080 / 65535, the issue's exact 99999, the boundary 65536, zero, negative, nullish undefined/null, string-form valid "3000", and string-form out-of-range "100000". Confirms patched returns null for out-of-range and the buggy shape returned the raw out-of-range integer that would have reached bind/connect.

• Exact steps or command run after this patch: node /tmp/probe_83900.mjs

• Evidence after fix:

PASS: MAX_TCP_PORT constant declared (16-bit boundary)
PASS: guard rejects undefined OR values above MAX_TCP_PORT
PASS: nullish-input early-return preserved
PASS: replay: all 11 fixtures (in-range / out-of-range / nullish / string-form) match patched and buggy shapes correctly
PASS: issue repro: buggy(99999)=99999 (would reach bind/connect), patched(99999)=null (clean rejection)

ALL CASES PASS

• Observed result after fix: openclaw gateway run --port 99999 (or any other CLI surface that pipes through parsePort) now treats out-of-range port input identically to other invalid inputs: parsePort returns null, and the caller's existing ?? defaultPort / null-check path applies. No OS-level bind error from invalid 16-bit input.

• What was not tested: Live openclaw gateway run --port 99999 smoke against an actual build — that requires pnpm build. The probe replays the predicate end-to-end against the issue's exact fixture, and the vitest regression test exercises the public parsePort contract directly.

Audit (per CLAUDE rules — all 5 steps)

• Existing-helper check: Reuses the existing parseStrictPositiveInteger import; the new constant MAX_TCP_PORT is a single magic-number replacement for a well-known IANA value. No new helper. PASS
• Shared-helper caller check: parsePort has 4 production callers — gateway-cli/run.ts:531, node-cli/daemon.ts:82, node-cli/register.ts:19, daemon-cli/install.ts. All four read the result as number | null and apply a default-or-error fallback for null. Adding the upper bound strengthens the existing null contract; no caller signature change. PASS
• Broader-fix rival scan: gh pr list --search '83900 in:title,body' and gh pr list --search 'parsePort in:title,body' return no open PRs. PASS
• Recent-merge audit: git log --oneline -5 -- src/cli/shared/parse-port.ts shows e1061a8b46 test(live): tolerate provider drift in release checks — unrelated. PASS
• Prototype-pollution scan: N/A — single numeric comparison, no external-input key copying.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/cli/shared/parse-port.test.ts (added, +37/-0)
• src/cli/shared/parse-port.ts (modified, +11/-1)