The best way to control Claude Code, Codex and more from any computer or phone
feat(server): tunnel preview traffic to an environment's loopback ports (#37947)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 18, 2026 at 17:49 UTC
cbae97f620eaa26497679e1574deb91e408e038b
3 files changed
+355
apps/server/src/preview/PreviewTunnel.test.ts
new
+185
@@ -0,0 +1,185 @@
1
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
2
+import * as NodeWS from "@effect/platform-node/NodeWS";
3
+import { expect, it } from "@effect/vitest";
4
+import {
5
+ AuthOrchestrationReadScope,
6
+ AuthSessionId,
7
+ AuthTerminalOperateScope,
8
+} from "@t3tools/contracts";
9
+import * as NodeNet from "node:net";
10
+import * as Context from "effect/Context";
11
+import * as Deferred from "effect/Deferred";
12
+import * as Effect from "effect/Effect";
13
+import * as Layer from "effect/Layer";
14
+import { HttpRouter, HttpServer } from "effect/http";
15
+
16
+import * as EnvironmentAuth from "../auth/EnvironmentAuth.ts";
17
+import * as SessionStore from "../auth/SessionStore.ts";
18
+import * as PreviewTunnel from "./PreviewTunnel.ts";
19
+
20
+const listen = (onConnection: (socket: NodeNet.Socket) => void) =>
21
+ Effect.acquireRelease(
22
+ Effect.promise(
23
+ () =>
24
+ new Promise<{ server: NodeNet.Server; sockets: Set<NodeNet.Socket> }>((resolve) => {
25
+ const sockets = new Set<NodeNet.Socket>();
26
+ const server = NodeNet.createServer((socket) => {
27
+ sockets.add(socket);
28
+ onConnection(socket);
29
+ });
30
+ server.listen(0, "127.0.0.1", () => resolve({ server, sockets }));
31
+ }),
32
+ ),
33
+ ({ server, sockets }) =>
34
+ Effect.promise(
35
+ () =>
36
+ new Promise<void>((resolve) => {
37
+ for (const socket of sockets) socket.destroy();
38
+ server.close(() => resolve());
39
+ }),
40
+ ),
41
+ ).pipe(Effect.map(({ server }) => ({ port: (server.address() as NodeNet.AddressInfo).port })));
42
+
43
+/** Serves the tunnel route; `wsTicket=reader` authenticates without terminal:operate. */
44
+const serveTunnel = (sessionInvalidated: Effect.Effect<void> = Effect.never) =>
45
+ Effect.gen(function* () {
46
+ const services = yield* Layer.build(
47
+ HttpRouter.serve(PreviewTunnel.routeLayer, { disableListenLog: true }).pipe(
48
+ Layer.provideMerge(NodeHttpServer.layerTest),
49
+ Layer.provide(PreviewTunnel.layer),
50
+ Layer.provide(
51
+ Layer.mock(SessionStore.SessionStore, {
52
+ cookieName: "t3_session",
53
+ legacyCookieName: undefined,
54
+ awaitInvalidation: () => sessionInvalidated,
55
+ }),
56
+ ),
57
+ Layer.provide(
58
+ Layer.mock(EnvironmentAuth.EnvironmentAuth, {
59
+ authenticateWebSocketUpgrade: (request) =>
60
+ Effect.succeed({
61
+ sessionId: AuthSessionId.make("tunnel-test"),
62
+ subject: "tunnel-test",
63
+ method: "bearer-access-token",
64
+ scopes: request.url.includes("wsTicket=reader")
65
+ ? [AuthOrchestrationReadScope]
66
+ : [AuthOrchestrationReadScope, AuthTerminalOperateScope],
67
+ }),
68
+ }),
69
+ ),
70
+ ),
71
+ );
72
+ const origin = new URL(
73
+ HttpServer.formatAddress(Context.get(services, HttpServer.HttpServer).address),
74
+ );
75
+ return { origin: `ws://${origin.host}`, port: Number(origin.port) };
76
+ });
77
+
78
+const openTunnel = (url: string) =>
79
+ Effect.acquireRelease(
80
+ Effect.sync(() => new NodeWS.WebSocket(url)),
81
+ (socket) => Effect.sync(() => socket.terminate()),
82
+ );
83
+
84
+/** How the route turned down a tunnel: its status, and whether it marked the port as the reason. */
85
+const refusal = (client: NodeWS.WebSocket) =>
86
+ Effect.promise(
87
+ () =>
88
+ new Promise<{ status: number | undefined; portRefused: boolean }>((resolve, reject) => {
89
+ client.on("unexpected-response", (_request, response) =>
90
+ resolve({
91
+ status: response.statusCode,
92
+ portRefused:
93
+ response.headers[PreviewTunnel.PREVIEW_TUNNEL_PORT_REFUSED_HEADER] !== undefined,
94
+ }),
95
+ );
96
+ client.on("open", () => reject(new Error("tunnel opened")));
97
+ client.on("error", reject);
98
+ }),
99
+ );
100
+
101
+it.effect("pipes bytes both ways between the WebSocket and the loopback port", () =>
102
+ Effect.gen(function* () {
103
+ const upstreamReceived: number[] = [];
104
+ const upstream = yield* listen((socket) => {
105
+ socket.write(Uint8Array.of(0x10, 0x11));
106
+ socket.on("data", (chunk) => {
107
+ upstreamReceived.push(...chunk);
108
+ socket.write(Buffer.concat([Uint8Array.of(0xee), chunk]));
109
+ });
110
+ });
111
+ const tunnel = yield* serveTunnel();
112
+ const client = yield* openTunnel(`${tunnel.origin}/api/preview/tunnel?port=${upstream.port}`);
113
+ const clientReceived: number[] = [];
114
+ const done = Promise.withResolvers<void>();
115
+ client.on("error", done.reject);
116
+ client.on("message", (data: Buffer) => {
117
+ clientReceived.push(...data);
118
+ if (clientReceived.length === 2) client.send(Uint8Array.of(0x01, 0x02, 0x03));
119
+ if (clientReceived.length === 6) done.resolve();
120
+ });
121
+ yield* Effect.promise(() => done.promise);
122
+ expect(upstreamReceived).toEqual([0x01, 0x02, 0x03]);
123
+ expect(clientReceived).toEqual([0x10, 0x11, 0xee, 0x01, 0x02, 0x03]);
124
+ }),
125
+);
126
+
127
+it.effect.each([
128
+ { case: "the server's own port", target: "self", ticket: "operator", portRefused: true },
129
+ {
130
+ case: "a session without terminal:operate",
131
+ target: "listed",
132
+ ticket: "reader",
133
+ portRefused: false,
134
+ },
135
+] as const)("refuses $case with 403 before dialling", ({ target, ticket, portRefused }) =>
136
+ Effect.gen(function* () {
137
+ let dialled = 0;
138
+ const countDial = (socket: NodeNet.Socket) => {
139
+ dialled++;
140
+ socket.destroy();
141
+ };
142
+ const listed = yield* listen(countDial);
143
+ const tunnel = yield* serveTunnel();
144
+ const port = { listed: listed.port, self: tunnel.port }[target];
145
+ const client = yield* openTunnel(
146
+ `${tunnel.origin}/api/preview/tunnel?port=${port}&wsTicket=${ticket}`,
147
+ );
148
+ const response = yield* refusal(client);
149
+ expect(response).toEqual({ status: 403, portRefused });
150
+ expect(dialled).toBe(0);
151
+ }),
152
+);
153
+
154
+it.effect("answers a port nothing listens on with 502, marked as about the port", () =>
155
+ Effect.gen(function* () {
156
+ const closed = yield* Effect.promise(
157
+ () =>
158
+ new Promise<number>((resolve) => {
159
+ const server = NodeNet.createServer();
160
+ server.listen(0, "127.0.0.1", () => {
161
+ const { port } = server.address() as NodeNet.AddressInfo;
162
+ server.close(() => resolve(port));
163
+ });
164
+ }),
165
+ );
166
+ const tunnel = yield* serveTunnel();
167
+ const client = yield* openTunnel(`${tunnel.origin}/api/preview/tunnel?port=${closed}`);
168
+ const response = yield* refusal(client);
169
+ expect(response).toEqual({ status: 502, portRefused: true });
170
+ }),
171
+);
172
+
173
+it.effect("closes an open tunnel when its session is revoked", () =>
174
+ Effect.gen(function* () {
175
+ const upstreamClosed = Promise.withResolvers<void>();
176
+ const upstream = yield* listen((socket) => socket.on("close", () => upstreamClosed.resolve()));
177
+ const revoked = yield* Deferred.make<void>();
178
+ const tunnel = yield* serveTunnel(Deferred.await(revoked));
179
+ const client = yield* openTunnel(`${tunnel.origin}/api/preview/tunnel?port=${upstream.port}`);
180
+ yield* Effect.promise(() => new Promise((resolve) => client.once("open", resolve)));
181
+ const clientClosed = new Promise((resolve) => client.once("close", resolve));
182
+ yield* Deferred.succeed(revoked, undefined);
183
+ yield* Effect.promise(() => Promise.all([clientClosed, upstreamClosed.promise]));
184
+ }),
185
+);
apps/server/src/preview/PreviewTunnel.ts
new
+167
@@ -0,0 +1,167 @@
1
+// Carries a remote desktop's preview traffic to this machine's loopback ports, one TCP
2
+// connection per WebSocket. Raw bytes, so pages keep their own origin, HMR sockets and TLS.
3
+import * as NodeHttpServerRequest from "@effect/platform-node/NodeHttpServerRequest";
4
+import * as NodeSocket from "@effect/platform-node/NodeSocket";
5
+import { AuthTerminalOperateScope } from "@t3tools/contracts";
6
+import type * as NodeNet from "node:net";
7
+import * as Context from "effect/Context";
8
+import * as Effect from "effect/Effect";
9
+import * as Layer from "effect/Layer";
10
+import * as Option from "effect/Option";
11
+import * as Schema from "effect/Schema";
12
+import type * as Scope from "effect/Scope";
13
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
14
+import type * as Socket from "effect/socket/Socket";
15
+
16
+import { authenticateMediaRequest } from "../auth/http.ts";
17
+import * as SessionStore from "../auth/SessionStore.ts";
18
+import { requestUrl } from "../requestUrl.ts";
19
+
20
+const PREVIEW_TUNNEL_ROUTE = "/api/preview/tunnel";
21
+/**
22
+ * Marks a refusal about the port itself, so a client can tell "nothing listens there" from a proxy
23
+ * in front of the environment answering 502 because the environment is down.
24
+ */
25
+export const PREVIEW_TUNNEL_PORT_REFUSED_HEADER = "x-t3-tunnel-port-refused";
26
+
27
+const CONNECT_TIMEOUT = "5 seconds";
28
+
29
+export class PreviewTunnelPortRefusedError extends Schema.TaggedError<PreviewTunnelPortRefusedError>()(
30
+ "PreviewTunnelPortRefusedError",
31
+ { port: Schema.Number },
32
+) {
33
+ override get message(): string {
34
+ return `Port ${this.port} is this T3 Code server's own port.`;
35
+ }
36
+}
37
+
38
+export class PreviewTunnelConnectError extends Schema.TaggedError<PreviewTunnelConnectError>()(
39
+ "PreviewTunnelConnectError",
40
+ { port: Schema.Number, cause: Schema.Defect() },
41
+) {
42
+ override get message(): string {
43
+ return `Nothing accepted a connection on loopback port ${this.port}.`;
44
+ }
45
+}
46
+
47
+export class PreviewTunnel extends Context.Service<
48
+ PreviewTunnel,
49
+ {
50
+ /** Connects to a loopback port. `servedPort` is the port the request arrived on. */
51
+ readonly connect: (input: {
52
+ readonly port: number;
53
+ readonly servedPort: number | undefined;
54
+ }) => Effect.Effect<
55
+ { readonly reader: Socket.Reader; readonly writer: Socket.Writer },
56
+ PreviewTunnelPortRefusedError | PreviewTunnelConnectError,
57
+ Scope.Scope
58
+ >;
59
+ }
60
+>()("t3/preview/PreviewTunnel") {}
61
+
62
+const make = Effect.sync(() => {
63
+ const dial = Effect.fnUntraced(function* (host: string, port: number) {
64
+ const socket = yield* NodeSocket.makeNet({ host, port, openTimeout: CONNECT_TIMEOUT });
65
+ return { reader: yield* socket.reader, writer: yield* socket.writer };
66
+ });
67
+
68
+ const connect: PreviewTunnel["Service"]["connect"] = Effect.fn("PreviewTunnel.connect")(
69
+ function* ({ port, servedPort }) {
70
+ yield* Effect.annotateCurrentSpan({ port });
71
+ // Tunnelling to this server would hand the page an unauthenticated loopback client.
72
+ if (port === servedPort) {
73
+ return yield* new PreviewTunnelPortRefusedError({ port });
74
+ }
75
+ return yield* dial("127.0.0.1", port).pipe(
76
+ Effect.catch(() => dial("::1", port)),
77
+ Effect.mapError((cause) => new PreviewTunnelConnectError({ port, cause })),
78
+ );
79
+ },
80
+ );
81
+
82
+ return PreviewTunnel.of({ connect });
83
+});
84
+
85
+export const layer = Layer.effect(PreviewTunnel, make);
86
+
87
+const SEND_HIGH_WATER_BYTES = 1024 * 1024;
88
+
89
+// Effect's WebSocket writer never waits for its send buffer, so a slow client would queue a
90
+// whole response in memory. `ws` writes its frames to the upgraded TCP socket; wait on that.
91
+const drained = (connection: NodeNet.Socket) =>
92
+ Effect.callback<void>((resume) => {
93
+ if (connection.writableLength <= SEND_HIGH_WATER_BYTES || connection.destroyed) {
94
+ return resume(Effect.void);
95
+ }
96
+ const stopWaiting = () => connection.off("drain", done).off("close", done);
97
+ const done = () => {
98
+ stopWaiting();
99
+ resume(Effect.void);
100
+ };
101
+ connection.on("drain", done).on("close", done);
102
+ return Effect.sync(stopWaiting);
103
+ });
104
+
105
+const pump =
106
+ /* Runs for the life of the connection; a span per direction adds no diagnostic value. */
107
+ Effect.fnUntraced(function* (
108
+ reader: Socket.Reader,
109
+ writer: Socket.Writer,
110
+ backpressure: Effect.Effect<void> = Effect.void,
111
+ ) {
112
+ while (true) {
113
+ yield* writer.writeAll(yield* reader.pull);
114
+ yield* backpressure;
115
+ }
116
+ });
117
+
118
+const handler = Effect.gen(function* () {
119
+ const request = yield* HttpServerRequest.HttpServerRequest;
120
+ const url = requestUrl(request);
121
+ const port = Number(Option.getOrUndefined(url)?.searchParams.get("port") ?? Number.NaN);
122
+ if (
123
+ request.headers.upgrade?.toLowerCase() !== "websocket" ||
124
+ !Number.isInteger(port) ||
125
+ port < 1 ||
126
+ port > 65_535
127
+ ) {
128
+ return HttpServerResponse.text("Bad Request", { status: 400 });
129
+ }
130
+ const session = yield* authenticateMediaRequest(AuthTerminalOperateScope);
131
+ const sessions = yield* SessionStore.SessionStore;
132
+ const tunnel = yield* PreviewTunnel;
133
+ const connection = NodeHttpServerRequest.toIncomingMessage(request).socket;
134
+ const servedPort = connection.localPort;
135
+ return yield* Effect.gen(function* () {
136
+ // Dialled before the upgrade so a dead port fails the handshake instead of an open socket.
137
+ const upstream = yield* tunnel.connect({ port, servedPort });
138
+ const client = yield* request.upgrade;
139
+ const clientReader = yield* client.reader;
140
+ const clientWriter = yield* client.writer;
141
+ // A tunnel is raw TCP into the host, so it closes with its session like the RPC socket.
142
+ yield* Effect.raceFirst(
143
+ Effect.raceFirst(
144
+ pump(upstream.reader, clientWriter, drained(connection)),
145
+ pump(clientReader, upstream.writer),
146
+ ),
147
+ sessions.awaitInvalidation(session.sessionId, session.proofKeyThumbprint),
148
+ ).pipe(Effect.ignoreCause);
149
+ return HttpServerResponse.empty();
150
+ }).pipe(
151
+ Effect.scoped,
152
+ Effect.catchTags({
153
+ PreviewTunnelPortRefusedError: (error) =>
154
+ Effect.succeed(
155
+ HttpServerResponse.text(error.message, { status: 403, headers: PORT_REFUSED_HEADERS }),
156
+ ),
157
+ PreviewTunnelConnectError: (error) =>
158
+ Effect.succeed(
159
+ HttpServerResponse.text(error.message, { status: 502, headers: PORT_REFUSED_HEADERS }),
160
+ ),
161
+ }),
162
+ );
163
+});
164
+
165
+const PORT_REFUSED_HEADERS = { [PREVIEW_TUNNEL_PORT_REFUSED_HEADER]: "1" };
166
+
167
+export const routeLayer = HttpRouter.add("GET", PREVIEW_TUNNEL_ROUTE, handler);
apps/server/src/server.ts
+3
@@ -100,6 +100,7 @@ import * as DeviceService from "./device/DeviceService.ts";
100
import * as DeviceHubProxy from "./device/DeviceHubProxy.ts";
101
import * as PreviewManager from "./preview/Manager.ts";
102
import * as PortScanner from "./preview/PortScanner.ts";
103
+import * as PreviewTunnel from "./preview/PreviewTunnel.ts";
104
import * as ServerBrowser from "./preview/ServerBrowser.ts";
105
import * as PreviewAgentActivity from "./preview/PreviewAgentActivity.ts";
106
import * as DesktopBrowserChannel from "./preview/DesktopBrowserChannel.ts";
@@ -531,6 +532,7 @@ const layerTerminal = TerminalManager.layer(
532
);
533
534
const layerPreview = Layer.empty.pipe(
535
+ Layer.provideMerge(PreviewTunnel.layer),
536
Layer.provideMerge(PreviewManager.layer),
537
Layer.provideMerge(layerPortScanner),
538
);
@@ -854,6 +856,7 @@ const layerMakeRoutes = Layer.mergeAll(
856
GuestHttp.layer,
857
DeviceHubProxy.layer,
858
ServerBrowserStream.routeLayer,
859
+ PreviewTunnel.routeLayer,
860
ServerHttp.layerStaticAndDevRoute,
861
Ws.layer,
862
speechStreamRouteLayer,