fix(server): treat forwarded loopback ports as loopback

isLoopbackRequestHost() required the Host header's port to equal the
proxy's own port, so a proxy reached through `ssh -L 20100:localhost:10100`
arrived as `Host: localhost:20100` and was refused. That gate sits in
front of the whole data plane — /v1/models, /v1/responses, /v1/messages,
/v1/chat/completions, /v1/live and the Responses WebSocket upgrade — not
just CORS, and it fires with no Origin header at all, so Codex CLI,
Claude Code and curl all saw a proxy that looked completely dead rather
than one with a CORS problem.

Loopback is a trust boundary by hostname, not by port. The sibling
isLoopbackOriginValue() dropped its own port check for exactly this
reason in e4e0612. Port equality was never the rebinding defense
either: a rebinding browser connects to the real port and sends it
verbatim, so the hostname check is what rejected it before and still
does. Verified against 40 Host forms — localhost.attacker.com,
127.0.0.1.nip.io, localtest.me, 0.0.0.0, 127.0.0.2, [::ffff:127.0.0.1]
and a Cyrillic homograph all stay refused.

Also accepts the FQDN form `localhost.`, which curl sends verbatim and
which was refused for the same class of reason.

The predicate had no test coverage at all. The new file pins both
directions, including a characterization test for the pre-existing
fail-open on an unparseable Host so tightening it later needs a
deliberate failing test.

Docs: forwarding is now documented, with the caveats that a forwarded
loopback is unauthenticated (ssh -g / container publishing expose it),
that the client base URL must be set by hand, and that provider OAuth
login needs its own forward.

Author: lidge-jun

docs-site/src/content/docs/reference/configuration.md

@@ -167,6 +167,39 @@ Binding to `0.0.0.0` exposes your proxy — and all configured provider credenti
 network. Only do this on trusted networks, and always set a strong `OPENCODEX_API_AUTH_TOKEN`.
 :::
 
+### SSH port forwarding
+
+You do not need a non-loopback bind to use a proxy on another machine. Forward the port
+over SSH and leave `hostname` at its `127.0.0.1` default:
+
+```bash
+ssh -L 20100:localhost:10100 you@remote
+```
+
+The local port does not have to match the remote one. opencodex treats any request whose
+`Host` resolves to `localhost`, `127.0.0.1`, or `::1` as loopback regardless of port, so
+`http://localhost:20100/v1` works for Codex CLI, Claude Code, the dashboard, and `curl`.
+
+Point the client at the forwarded port yourself — `ocx` only ever writes `127.0.0.1` with the
+local default port into client config, so a forwarded setup needs the base URL set by hand.
+
+Provider OAuth login is the one flow a single forward does not cover: the login callback
+listens on a fixed port on the *remote* machine. Either run `ocx login <provider>` there, or
+forward that port too:
+
+```bash
+ssh -L 20100:localhost:10100 -L 1455:localhost:1455 you@remote
+```
+
+:::caution[Forwarded loopback is unauthenticated]
+A loopback bind has no token authentication — that is what makes the default setup usable
+without configuration. A plain `ssh -L` keeps the listener on your own loopback interface, so
+nothing else can reach it. But `ssh -g -L`, container port publishing, and some devcontainer
+or Codespaces forwarding modes bind the *client* side to `0.0.0.0`, which exposes both the
+management API and the data plane to that network with no credential. Use `-L` without `-g`,
+or bind the forward explicitly to loopback (`ssh -L 127.0.0.1:20100:localhost:10100`).
+:::
+
 ## Providers (`OcxProviderConfig`)
 
 | Field | Type | Meaning |

src/server/auth-cors.ts

@@ -18,6 +18,7 @@ import { openRouterRoutingConfigError } from "../providers/openrouter-routing";
 
 let _corsOrigin = "http://localhost:10100";
 export function setCorsOrigin(port: number): void { _corsOrigin = `http://localhost:${port}`; }
+/** The proxy's own listening port. No admission check uses it: both loopback predicates key on hostname alone. */
 export function configuredPort(): string {
   try { return new URL(_corsOrigin).port; } catch { return "10100"; }
 }
@@ -35,8 +36,18 @@ export function parseHttpHost(value: string | null): { hostname: string; port: s
 export function isLoopbackRequestHost(value: string | null): boolean {
   const parsed = parseHttpHost(value);
   if (!parsed) return true;
-  if (!isLoopbackHostname(parsed.hostname)) return false;
-  return parsed.port === "" || parsed.port === configuredPort();
+  // Loopback is a trust boundary by hostname, not by port. `ssh -L 20100:localhost:10100`
+  // legitimately arrives as `Host: localhost:20100`, and refusing it took the whole /v1/*
+  // data plane down with it, not just CORS. The sibling isLoopbackOriginValue() dropped its
+  // own port check for the same reason in e4e06125b ("same-trust-boundary"). Port equality
+  // was never the rebinding defense: a rebinding browser connects to the real port and sends
+  // it verbatim, so the hostname check below is what rejected it then and now.
+  //
+  // Scope of that guarantee: it holds for Hosts `parseHttpHost` can parse. An unparseable
+  // Host still returns true above — pre-existing behavior, not browser-reachable (a browser
+  // composes Host from its own connection), and pinned by a characterization test in
+  // tests/server-loopback-host-gate.test.ts. Tightening it is separate work.
+  return isLoopbackHostname(parsed.hostname);
 }
 
 export function isLoopbackOriginValue(value: string): boolean {
@@ -115,7 +126,9 @@ export function configuredApiAuthToken(_config: OcxConfig): string | undefined {
 }
 
 export function isLoopbackHostname(hostname: string | undefined): boolean {
-  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase();
+  // A fully-qualified "localhost." is the same host as "localhost": curl and some clients
+  // send the trailing dot verbatim, and refusing it 403s a legitimate loopback caller.
+  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase().replace(/\.$/, "");
   return normalized === "" || normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
 }
 

tests/server-loopback-host-gate.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { isAllowedRequestOrigin, isLoopbackRequestHost } from "../src/server/auth-cors";
+import type { OcxConfig } from "../src/types";
+
+// A loopback bind: isApiAuthRequired() is false, so admission runs through the
+// Host/Origin branch these tests exercise.
+const loopbackConfig = { hostname: "127.0.0.1" } as OcxConfig;
+
+function request(host: string, origin?: string): Request {
+  const headers: Record<string, string> = { Host: host };
+  if (origin) headers.Origin = origin;
+  return new Request("http://x/v1/models", { headers });
+}
+
+describe("isLoopbackRequestHost", () => {
+  test("a forwarded loopback port is still loopback (ssh -L 20100:localhost:10100)", () => {
+    // Regression: coupling loopback identity to port equality 403'd the entire /v1/*
+    // data plane whenever the client reached the proxy through a forwarded port.
+    expect(isLoopbackRequestHost("localhost:20100")).toBe(true);
+    expect(isLoopbackRequestHost("127.0.0.1:20100")).toBe(true);
+    expect(isLoopbackRequestHost("[::1]:20100")).toBe(true);
+  });
+
+  test("the proxy's own port, a bare host, and a missing Host stay allowed", () => {
+    expect(isLoopbackRequestHost("localhost:10100")).toBe(true);
+    expect(isLoopbackRequestHost("localhost")).toBe(true);
+    expect(isLoopbackRequestHost("127.0.0.1")).toBe(true);
+    expect(isLoopbackRequestHost(null)).toBe(true);
+  });
+
+  test("a non-loopback hostname is refused on every port", () => {
+    // The hostname check is the real DNS-rebinding boundary; it must not depend on
+    // which port the attacker names.
+    expect(isLoopbackRequestHost("attacker.test:10100")).toBe(false);
+    expect(isLoopbackRequestHost("attacker.test:20100")).toBe(false);
+    expect(isLoopbackRequestHost("192.168.1.5:10100")).toBe(false);
+    expect(isLoopbackRequestHost("example.com")).toBe(false);
+  });
+
+  test("names that merely look loopback are refused", () => {
+    // These are the DNS-rebinding shapes that matter: a hostname the attacker controls
+    // which either embeds "localhost"/"127.0.0.1" as a label or resolves to loopback.
+    expect(isLoopbackRequestHost("localhost.attacker.com")).toBe(false);
+    expect(isLoopbackRequestHost("127.0.0.1.attacker.com")).toBe(false);
+    expect(isLoopbackRequestHost("127.0.0.1.nip.io")).toBe(false);
+    expect(isLoopbackRequestHost("localtest.me")).toBe(false);
+    // Cyrillic "о" in "lоcalhost" — the URL parser punycodes it, so it must not match.
+    expect(isLoopbackRequestHost("l\u043Ecalhost:20100")).toBe(false);
+    // Not loopback despite the shape.
+    expect(isLoopbackRequestHost("0.0.0.0:20100")).toBe(false);
+    expect(isLoopbackRequestHost("127.0.0.2:20100")).toBe(false);
+  });
+
+  test("alternative spellings of real loopback are accepted (URL normalization)", () => {
+    expect(isLoopbackRequestHost("127.1:20100")).toBe(true);
+    expect(isLoopbackRequestHost("2130706433:20100")).toBe(true);
+    expect(isLoopbackRequestHost("LOCALHOST:20100")).toBe(true);
+    // `curl http://localhost.:20100/` sends the FQDN form; it is the same host.
+    expect(isLoopbackRequestHost("localhost.:20100")).toBe(true);
+    expect(isLoopbackRequestHost("localhost.")).toBe(true);
+  });
+
+  test("characterization: an unparseable Host still fails open", () => {
+    // Pre-existing behavior of `if (!parsed) return true`, unchanged by the port-check
+    // removal and not browser-reachable (a browser composes Host from its own connection).
+    // Pinned here so tightening it is a deliberate change with a failing test, not a
+    // silent drift. See the scope note in isLoopbackRequestHost.
+    expect(isLoopbackRequestHost("attacker.test:99999")).toBe(true);
+    expect(isLoopbackRequestHost("attacker test:80")).toBe(true);
+  });
+});
+
+describe("isAllowedRequestOrigin over a forwarded port", () => {
+  test("a CLI with no Origin reaches the data plane through the forward", () => {
+    // Codex CLI, Claude Code and curl send no Origin at all, so this path — not CORS —
+    // is what made a forwarded proxy look completely dead.
+    expect(isAllowedRequestOrigin(request("localhost:20100"), loopbackConfig)).toBe(true);
+  });
+
+  test("a browser Origin on the forwarded port is allowed", () => {
+    expect(
+      isAllowedRequestOrigin(request("localhost:20100", "http://localhost:20100"), loopbackConfig),
+    ).toBe(true);
+  });
+
+  test("a non-loopback Host is still refused with and without an Origin", () => {
+    expect(isAllowedRequestOrigin(request("attacker.test:20100"), loopbackConfig)).toBe(false);
+    expect(
+      isAllowedRequestOrigin(request("attacker.test:20100", "http://attacker.test:20100"), loopbackConfig),
+    ).toBe(false);
+  });
+
+  test("a loopback Host with a non-loopback Origin is still refused", () => {
+    expect(
+      isAllowedRequestOrigin(request("localhost:20100", "http://attacker.test"), loopbackConfig),
+    ).toBe(false);
+  });
+});