@tapflowio/relay 0.21.0 → 0.23.0

package/dist/RelayServer.d.ts

@@ -1,3 +1,4 @@
+import { type TunnelRuntime } from './lib/publicUrl.js';
 export declare function isExternalAddress(addr: string): boolean;
 /** Exported for the re-join test, which pins both edges of this window rather than hardcoding 500 —
  *  a test carrying its own copy of the number passes when the constant moves, which is the drift the
@@ -29,6 +30,20 @@ export declare function ownerKeyFor(userId: number | string | undefined, claimed
 export declare class RelayServer {
     private readonly options;
     private httpServer;
+    /**
+     * **The port tunnel clients are pointed at, and the only thing that tells their traffic apart.**
+     * rathole's client and `tailscale serve` run on this machine and connect from loopback on behalf of
+     * someone on the internet or the tailnet; rathole forwards raw TCP, so no header marks it either. On
+     * the main port such a socket is indistinguishable from `tapflow start`'s own agent, which is
+     * unauthenticated by design — so every tunnel visitor was too. Everything accepted here is remote
+     * (`resolveClientAddress`'s `viaTunnel`), whatever its address.
+     *
+     * Loopback-only, because only a tunnel client on this machine has any business here; a remote client
+     * belongs on the main port, where it is classified by address as before. Same handler, same
+     * `WebSocketServer`, same TLS material — rathole carried a TLS relay's own handshake through before
+     * this existed, and still does.
+     */
+    private tunnelServer;
     private wss;
     private sessions;
     private publicDir;
@@ -112,12 +127,17 @@ export declare class RelayServer {
             key: string;
         };
         agentGraceMs?: number;
+        tunnel?: TunnelRuntime;
+        tunnelPort?: number;
     });
     private registerRoutes;
     pushLog(msg: string): void;
     start(): Promise<void>;
+    private listenTunnel;
     stop(): Promise<void>;
     address(): string | import("net").AddressInfo | null;
+    /** The tunnel listener's address, or null when this relay was given no `tunnelPort`. */
+    tunnelAddress(): string | import("net").AddressInfo | null;
     private runHeartbeat;
     /**
      * Has this socket answered recently enough to be treated as present?

package/dist/RelayServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RelayServer.d.ts","sourceRoot":"","sources":["../src/RelayServer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RelayServer.d.ts","sourceRoot":"","sources":["../src/RelayServer.ts"],"names":[],"mappings":"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"}

package/dist/RelayServer.js

@@ -10,11 +10,13 @@ import { directionOf, parseInbound } from '@tapflowio/protocol/validate';
 import { Router, json } from './router.js';
 import { requireViewAuth, requireAuth, getAuth, verifyPat } from './middleware/auth.js';
 import { classifyConnection } from './lib/connectionAuth.js';
-import { resolveClientAddress } from './lib/clientAddress.js';
+import { isTunnelIngress, markTunnelIngress, resolveClientAddress } from './lib/clientAddress.js';
 import { BuildTicketStore } from './lib/buildTickets.js';
 import { resolveCorsHeaders } from './lib/cors.js';
 import { isCsrfBlocked } from './lib/csrf.js';
-import { pickLanAddress } from './lib/lanAddress.js';
+import { pickLanAddress, runningInContainer } from './lib/lanAddress.js';
+import { config } from './lib/config.js';
+import { forTeammates, resolveAgentRelayUrl, resolvePublicBaseUrl } from './lib/publicUrl.js';
 import { createTrailingRequester, systemTimerScheduler } from './lib/trailingRequester.js';
 import { getDb } from './db.js';
 import { handleLogin, handleLogout, handleMe, handleChangePassword, handleInit, handleAuthStatus } from './api/auth.js';
@@ -154,6 +156,20 @@ function describeRejection(failure, suppressed) {
 export class RelayServer {
     options;
     httpServer;
+    /**
+     * **The port tunnel clients are pointed at, and the only thing that tells their traffic apart.**
+     * rathole's client and `tailscale serve` run on this machine and connect from loopback on behalf of
+     * someone on the internet or the tailnet; rathole forwards raw TCP, so no header marks it either. On
+     * the main port such a socket is indistinguishable from `tapflow start`'s own agent, which is
+     * unauthenticated by design — so every tunnel visitor was too. Everything accepted here is remote
+     * (`resolveClientAddress`'s `viaTunnel`), whatever its address.
+     *
+     * Loopback-only, because only a tunnel client on this machine has any business here; a remote client
+     * belongs on the main port, where it is classified by address as before. Same handler, same
+     * `WebSocketServer`, same TLS material — rathole carried a TLS relay's own handshake through before
+     * this existed, and still does.
+     */
+    tunnelServer = null;
     wss;
     sessions;
     publicDir;
@@ -238,6 +254,10 @@ export class RelayServer {
     pendingUITrees = new Map();
     constructor(options) {
         this.options = options;
+        // 0 on both sides is two ephemeral ports, which is what the tests ask for.
+        if (options.tunnelPort !== undefined && options.tunnelPort !== 0 && options.tunnelPort === options.port) {
+            throw new Error(`The tunnel port (${options.tunnelPort}) must differ from the relay port. Set TAPFLOW_TUNNEL_PORT to another port.`);
+        }
         this.backpressureBytes = options.wsBackpressureBytes ?? DEFAULT_BACKPRESSURE_BYTES;
         this.screenshotTimeoutMs = options.screenshotTimeoutMs ?? 10_000;
         // Longer than the screenshot default: the Android agent's device-side dump
@@ -278,6 +298,24 @@ export class RelayServer {
         this.wss = new WebSocketServer({ server: this.httpServer });
         this.wss.on('connection', (ws, request) => this.handleConnection(ws, request));
         this.wss.on('error', () => { });
+        if (options.tunnelPort !== undefined) {
+            // Marked before anything reads it: the router hands this same request object to `handleInit`, and
+            // `handleUpgrade` passes it on to the `connection` event.
+            const tunnelHandler = (req, res) => {
+                markTunnelIngress(req);
+                return handler(req, res);
+            };
+            const tunnelServer = options.tls
+                ? https.createServer({ cert: options.tls.cert, key: options.tls.key }, tunnelHandler)
+                : http.createServer(tunnelHandler);
+            tunnelServer.on('connection', (socket) => socket.setNoDelay(true));
+            // `handleUpgrade` adds the socket to `wss.clients`, so the heartbeat and `stop()` cover it.
+            tunnelServer.on('upgrade', (req, socket, head) => {
+                markTunnelIngress(req);
+                this.wss.handleUpgrade(req, socket, head, (ws) => this.wss.emit('connection', ws, req));
+            });
+            this.tunnelServer = tunnelServer;
+        }
     }
     registerRoutes() {
         const u = this.uploadsDir;
@@ -322,10 +360,10 @@ export class RelayServer {
         this.router.delete('/api/v1/comments/:id', handleDeleteComment);
         // team
         this.router.get('/api/v1/team/members', handleListMembers);
-        this.router.post('/api/v1/team/invite', handleInvite);
+        this.router.post('/api/v1/team/invite', (req, res) => handleInvite(req, res, this.options.tunnel));
         this.router.patch('/api/v1/team/members/:id', handleUpdateMember);
         this.router.delete('/api/v1/team/members/:id', handleDeleteMember);
-        this.router.post('/api/v1/team/members/:id/send-reset', handleSendMemberReset);
+        this.router.post('/api/v1/team/members/:id/send-reset', (req, res, params) => handleSendMemberReset(req, res, params, this.options.tunnel));
         // tokens
         this.router.get('/api/v1/tokens', handleListTokens);
         this.router.post('/api/v1/tokens', handleCreateToken);
@@ -346,14 +384,22 @@ export class RelayServer {
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify(this.logBuffer.slice(-lines)));
         });
-        // relay host — 대시보드가 agent 실행 커맨드에 박을 LAN 주소 (뷰어가 localhost로 접속한 경우의 치환용, #271)
+        // What the dashboard needs to build an address for someone else (#271, #788): a link base for a
+        // teammate's browser and an agent address, reported separately because they come from different
+        // settings (see lib/publicUrl.ts). Config comes from the singleton, as in the team handlers; whether a
+        // tunnel actually came up is known only to the entry point that started it, hence the `tunnel` option.
         this.router.get('/api/v1/relay/host', (req, res) => {
             if (!requireAuth(req, res))
                 return;
             const addr = this.httpServer.address();
             const port = typeof addr === 'object' && addr !== null ? addr.port : this.options.port;
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ lanHost: pickLanAddress(os.networkInterfaces()), port }));
+            res.end(JSON.stringify({
+                lanHost: runningInContainer() ? null : pickLanAddress(os.networkInterfaces()),
+                port,
+                publicBaseUrl: forTeammates(resolvePublicBaseUrl(config, this.options.tunnel)),
+                agentRelayUrl: forTeammates(resolveAgentRelayUrl(config)),
+            }));
         });
         // agent resources
         this.router.get('/api/v1/agents', handleListAgents);
@@ -397,7 +443,30 @@ export class RelayServer {
             });
             // Bind dual-stack (IPv4 + IPv6). A bare listen(port) binds IPv6-only on some
             // macOS/node setups, so LAN agents connecting over IPv4 (ws://<ipv4>:port) time out.
-            this.httpServer.listen({ port: this.options.port, host: '::', ipv6Only: false }, resolve);
+            this.httpServer.listen({ port: this.options.port, host: '::', ipv6Only: false }, () => resolve());
+        }).then(() => this.listenTunnel());
+    }
+    listenTunnel() {
+        const tunnelServer = this.tunnelServer;
+        if (!tunnelServer)
+            return Promise.resolve();
+        const port = this.options.tunnelPort ?? 0;
+        return new Promise((resolve, reject) => {
+            tunnelServer.once('error', (err) => reject(err.code === 'EADDRINUSE'
+                ? new Error(`Tunnel port ${port} is already in use. Stop the process holding it, or set TAPFLOW_TUNNEL_PORT to a free port.`)
+                : err));
+            // 127.0.0.1, not `localhost`: rathole's client dials that address literally, and `tailscale serve
+            // <port>` proxies to it.
+            tunnelServer.listen({ port, host: '127.0.0.1' }, () => {
+                // The main server's later errors reach `wss`, which swallows them; nothing forwards this one's.
+                tunnelServer.on('error', (err) => logger.error(`tunnel listener error: ${String(err)}`));
+                resolve();
+            });
+        }).catch(async (err) => {
+            // A relay whose tunnel port failed must not keep serving on the main one: the caller treats this
+            // as a failed start and moves on, and the port would stay held by a server nobody stops.
+            await this.stop().catch(() => { });
+            throw err;
         });
     }
     stop() {
@@ -435,16 +504,27 @@ export class RelayServer {
         for (const requester of this.networkStateRequesters.values())
             requester.dispose();
         this.networkStateRequesters.clear();
-        return new Promise((resolve, reject) => {
+        const closeTunnel = new Promise((resolve, reject) => {
+            // Not listening means `start()` never reached it, or its listen failed; `close()` would reject.
+            if (!this.tunnelServer?.listening)
+                return resolve();
+            this.tunnelServer.close((err) => (err ? reject(err) : resolve()));
+        });
+        const closeMain = new Promise((resolve, reject) => {
             this.wss.clients.forEach((ws) => ws.terminate());
             this.wss.close(() => {
                 this.httpServer.close((err) => (err ? reject(err) : resolve()));
             });
         });
+        return Promise.all([closeMain, closeTunnel]).then(() => undefined);
     }
     address() {
         return this.httpServer.address();
     }
+    /** The tunnel listener's address, or null when this relay was given no `tunnelPort`. */
+    tunnelAddress() {
+        return this.tunnelServer?.address() ?? null;
+    }
     // Terminate sockets that missed the previous pong; ping the rest. Covers all roles via wss.clients.
     runHeartbeat(clients = this.wss.clients) {
         for (const ws of clients) {
@@ -478,8 +558,10 @@ export class RelayServer {
     }
     // 갱신된 cert를 재시작 없이 핫스왑한다(https 종단일 때만 의미 있음).
     updateTlsContext(material) {
-        if (this.httpServer instanceof https.Server) {
-            this.httpServer.setSecureContext({ cert: material.cert, key: material.key });
+        for (const server of [this.httpServer, this.tunnelServer]) {
+            if (server instanceof https.Server) {
+                server.setSecureContext({ cert: material.cert, key: material.key });
+            }
         }
     }
     /**
@@ -594,8 +676,9 @@ export class RelayServer {
         const a = socketAddr.replace(/^::ffff:/, '');
         if (a === '::1' || a.startsWith('127.')) {
             logger.warn('Received X-Forwarded-For from a loopback connection but TAPFLOW_TRUSTED_PROXIES is unset. ' +
-                'If the relay runs behind a same-host reverse proxy, set TAPFLOW_TRUSTED_PROXIES so the real ' +
-                'client IP is used — otherwise every proxied client is treated as localhost (unauthenticated).');
+                'If a same-host reverse proxy or `tailscale serve` forwards to this port, every client it forwards is ' +
+                'treated as localhost (unauthenticated). Point it at the tunnel port instead (TAPFLOW_TUNNEL_PORT, ' +
+                'default 4001), or set TAPFLOW_TRUSTED_PROXIES so the real client IP is used.');
             this.warnedProxyMisconfig = true;
         }
     }
@@ -603,11 +686,15 @@ export class RelayServer {
         const socketAddr = this.remoteAddressOf(request);
         const xff = request.headers['x-forwarded-for'];
         const forwardedFor = Array.isArray(xff) ? xff[0] : xff;
-        this.warnProxyMisconfigOnce(socketAddr, forwardedFor);
+        const viaTunnel = isTunnelIngress(request);
+        // A proxy in front of the tunnel port adds the header too, and there it changes nothing about auth.
+        if (!viaTunnel)
+            this.warnProxyMisconfigOnce(socketAddr, forwardedFor);
         const { addr, isLocal } = resolveClientAddress({
             socketAddr,
             forwardedFor,
             trustedProxies: this.options.trustedProxies ?? [],
+            viaTunnel,
         });
         const hasCookieAuth = getAuth(request) !== null;
         // DB lookup — only when the connection can't be classified without it (remote, no cookie).
@@ -954,15 +1041,32 @@ export class RelayServer {
                 // two-member union** while `AgentRegister.platform` is `string`, open so that a third-party
                 // platform can register through `AgentRegistry.register()` (root AGENTS.md, OCP). Validating
                 // this would refuse a platform the repo promises to support — and refusing costs more than a
-                // dropped frame, because the message arrives once per boot and skipping `setChromeData` also
-                // empties what the re-join replay reads. The relay never looks inside; the viewer does, and it
-                // is where the variants are already told apart.
+                // dropped frame: skipping `setChromeData` also
+                // empties what the re-join replay reads. It is no longer true that this arrives once per boot,
+                // either — a foldable re-sends it when the screen changes under the session — so the cost of
+                // a refusal is a viewer stuck with the previous screen's bezel rather than one frame.
+                // The relay never looks inside; the viewer does, and it is where the variants are already
+                // told apart.
                 this.sessions.setChromeData(session.id, raw['payload']);
                 if (session.browserSocket?.readyState === WebSocket.OPEN) {
                     session.browserSocket.send(JSON.stringify(raw));
                 }
                 break;
             }
+            case 'device:postures': {
+                const session = this.sessions.get(msg.sessionId);
+                if (!session)
+                    break;
+                // Cached for the same reason `session:chrome` is: a viewer that re-joins (a tab reload, a
+                // socket blip) gets the session's state replayed, and without this the posture control would
+                // simply be missing until the device was rebooted — with the picture still fine, which is
+                // the hardest kind of gap to diagnose.
+                this.sessions.setPostures(session.id, raw['payload']);
+                if (session.browserSocket?.readyState === WebSocket.OPEN) {
+                    session.browserSocket.send(JSON.stringify(raw));
+                }
+                break;
+            }
             case 'session:deviceInfo': {
                 const session = this.sessions.get(msg.sessionId);
                 if (!session)
@@ -1218,6 +1322,7 @@ export class RelayServer {
             case 'input:pinch:start':
             case 'input:pinch:move':
             case 'input:rotate':
+            case 'input:posture':
             case 'input:keyboard:toggle': {
                 // No ack, so no correlator to check and nothing to answer. An unowned frame is dropped rather
                 // than refused for the same reason: there is no waiter to tell.
@@ -1617,6 +1722,9 @@ export class RelayServer {
         if (session.deviceInfo) {
             this.sendTo(ws, { type: 'session:deviceInfo', sessionId: session.id, payload: session.deviceInfo });
         }
+        if (session.postures) {
+            this.sendTo(ws, { type: 'device:postures', sessionId: session.id, payload: session.postures });
+        }
         // Replay device:ready only if this session actually announced one (browser WS blip reconnect).
         // Not `deviceStatus`: that starts from the agent's `simctl list` snapshot, so a session for a
         // simulator that was already running would fire this before the agent had done anything —