@devries-cameron20 / t3code Mirror · read-only / commits / cbae97f620
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 07:15 UTC

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,