Reject invalid TCP targets before opening a local forward #5112

User Story

I forward OpenShell services through the CLI and TypeScript SDK. If a target host or port is invalid, I need an error before the local listener is reported ready.

Problem Statement

A client can open a local forward for a target outside the supported loopback addresses. The gateway rejects that target only when the first connection arrives, after the client has already reported readiness.

Impact / Why This Matters

Applications connect to a forward that appears usable and then fail. The delayed error can look like a problem with the sandbox service.

Validate targets before gateway lookup or local binding, while keeping the gateway's own checks authoritative.

Acceptance Criteria

• Invalid hosts and target ports fail before gateway lookup or local binding.
• Valid IPv4 loopback, IPv6 loopback and localhost are normalized consistently with the gateway.
• The gateway remains authoritative, and scoped/mapped IPv6 forms do not escape client error handling.

Reproduction Steps

1. Use an OpenShell deployment with a Ready sandbox and TCP service forwarding enabled.
2. Run openshell forward service NAME --target-host example.com --target-port 8080 --local 0, substituting the sandbox name for NAME.
3. Observe the local readiness result before making a connection, then connect to the reported listener. The non-loopback target is rejected by the gateway only on that connection.
4. Compare with a valid loopback target. An invalid target should fail immediately, while a supported loopback target should retain the normal forwarding workflow.

Suggested UX (if applicable)

openshell forward service NAME --target-host example.com --target-port 8080 --local 0 should return a target-validation error without a local Ready listener. Valid loopback targets such as 127.0.0.1, ::1 and localhost should normalize consistently with gateway validation. The TypeScript SDK should reject invalid targets before returning a listening forward handle.

Environment

• OpenShell source assessed: 42671c2dd2c02b744850e0bda72b99d5509969c1.
• Deployment: gateway with a Ready sandbox and TCP service forwarding enabled.
• Affected callers: CLI forwarding and TypeScript SDK forwarding.

Logs