omp-mobile 0.4.3 → 0.5.1

package/src/relay.mjs

@@ -0,0 +1,368 @@
+/**
+ * The daemon as a DSH Remote Host: it registers with a relay server (by
+ * default the public https://dsh.r2049.cn of ds-harness-remote) through
+ * account-less device pairing, and serves its own HTTP + WebSocket API to
+ * paired phones through that relay, end-to-end encrypted (Noise IK, pinned
+ * keys). The relay only forwards ciphertext; nothing of DSH runs here.
+ *
+ * Over the encrypted channel the phone speaks a small tunnel (`createTunnelRouter`):
+ *   rpc `omp.http.open` {id, method, path, headers?, body? (text)} -> {status, headers}
+ *   rpc `omp.ws.open`   {id, path}                            -> {}
+ *   rpc `omp.ws.send`   {id, text}                            -> {}
+ *   rpc `omp.close`     {id}                                  -> {}
+ *   event `omp.data`    {id, text? (a text body or WebSocket message part), data? (base64 of a binary body),
+ *                        more? (the WebSocket message continues), done?, error?}
+ * Requests go to the daemon's loopback tunnel listener with its token added,
+ * so a paired phone gets exactly what a phone on the tailnet gets.
+ */
+import { request as httpRequest } from "node:http";
+import { StringDecoder } from "node:string_decoder";
+import { WebSocket } from "ws";
+import {
+  ConnectionController,
+  HostPairing,
+  HostServerApi,
+  HostServerConnection,
+  IdentityStore,
+  SafeLogger,
+  ServerCredentialStore,
+  createEvent,
+  createRpcError,
+  createRpcResponse,
+} from "../vendor/dsh-remote-host.mjs";
+
+/** Marks a request that came through the relay tunnel (set by the tunnel, never by the phone). */
+export const RELAY_HEADER = "x-omp-mobile-relay";
+/** Characters per text part and bytes per base64 part (a multiple of 3): well under the 4 MiB secure message cap. */
+const TEXT_CHUNK_CHARS = 1024 * 1024;
+const BINARY_PART_BYTES = 3 * 256 * 1024;
+/** A binary answer (an image) is sent whole: at most this large. */
+const MAX_BINARY_BODY = 32 * 1024 * 1024;
+const MAX_HANDLES = 64;
+const MAX_REQUEST_BODY = 16 * 1024 * 1024;
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+/** Headers the phone may pass on; the token and the relay mark are the tunnel's own. */
+const PASSED_HEADERS = new Set(["accept", "content-type", "x-omp-mobile-probe"]);
+
+class TunnelError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** A daemon path the phone may ask for: absolute, no scheme or host, and never the local `/relay` control. */
+function tunnelPath(value) {
+  if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//") || value.length > 8192 || /[\s\\]/.test(value)) {
+    throw new TunnelError("INVALID_MESSAGE", "Invalid path.");
+  }
+  const url = new URL(value, "http://tunnel");
+  if (url.pathname === "/relay" || url.pathname.startsWith("/relay/")) throw new TunnelError("METHOD_NOT_ALLOWED", "Relay control is local only.");
+  return url;
+}
+
+/**
+ * One phone connection's tunnel to the daemon at 127.0.0.1:`port`.
+ * @param {{port: number, token: string}} target
+ * @param {(message: object) => Promise<void>} send Encrypted delivery to that phone.
+ */
+export function createTunnelRouter(target, send) {
+  /** @type {Map<string, {close(): void, socket?: WebSocket}>} */
+  const handles = new Map();
+  let out = Promise.resolve();
+  /** Events go out in order; a failed send (the phone left) ends the handle. */
+  const emit = (data) => {
+    out = out.then(() => send(createEvent("omp.data", data))).catch(() => handles.get(data.id)?.close());
+    return out;
+  };
+  const claim = (id) => {
+    if (typeof id !== "string" || !ID.test(id)) throw new TunnelError("INVALID_MESSAGE", "Invalid handle id.");
+    if (handles.has(id)) throw new TunnelError("REQUEST_CONFLICT", "Handle already open.");
+    if (handles.size >= MAX_HANDLES) throw new TunnelError("RATE_LIMITED", "Too many open requests.");
+  };
+
+  const openHttp = (params) => {
+    claim(params.id);
+    const { id } = params;
+    const method = typeof params.method === "string" ? params.method.toUpperCase() : "GET";
+    if (!METHODS.has(method)) throw new TunnelError("INVALID_MESSAGE", "Invalid method.");
+    const url = tunnelPath(params.path);
+    const headers = { authorization: `Bearer ${target.token}`, [RELAY_HEADER]: "1" };
+    for (const [key, value] of Object.entries(params.headers ?? {})) {
+      if (PASSED_HEADERS.has(key.toLowerCase()) && typeof value === "string") headers[key.toLowerCase()] = value;
+    }
+    const body = typeof params.body === "string" ? Buffer.from(params.body, "utf8") : undefined;
+    if (body !== undefined && body.length > MAX_REQUEST_BODY) throw new TunnelError("FRAME_TOO_LARGE", "Request body too large.");
+    if (body !== undefined) headers["content-length"] = String(body.length);
+    return new Promise((resolveOpen, rejectOpen) => {
+      let settled = false;
+      const request = httpRequest({ host: "127.0.0.1", port: target.port, method, path: `${url.pathname}${url.search}`, headers, agent: false }, (response) => {
+        settled = true;
+        const type = String(response.headers["content-type"] ?? "");
+        resolveOpen({ status: response.statusCode ?? 502, headers: { "content-type": type } });
+        let ended = false;
+        // Text (JSON, the `/events` stream) goes as text, whole characters only; anything
+        // else (an image from `/blobs`) is collected and sent as base64 in 3-byte-aligned parts,
+        // so the phone can join the parts without decoding them.
+        const text = /^(text\/|application\/json)/.test(type) ? new StringDecoder("utf8") : undefined;
+        const bytes = [];
+        let total = 0;
+        response.on("data", (chunk) => {
+          if (text === undefined) {
+            total += chunk.length;
+            if (total > MAX_BINARY_BODY) request.destroy();
+            else bytes.push(chunk);
+            return;
+          }
+          const part = text.write(chunk);
+          if (part === "") return;
+          response.pause();
+          let sent = Promise.resolve();
+          for (let at = 0; at < part.length; at += TEXT_CHUNK_CHARS) sent = emit({ id, text: part.slice(at, at + TEXT_CHUNK_CHARS) });
+          void sent.then(() => response.resume());
+        });
+        response.on("end", () => {
+          ended = true;
+          handles.delete(id);
+          const rest = text?.end() ?? "";
+          if (rest !== "") void emit({ id, text: rest });
+          const all = Buffer.concat(bytes);
+          for (let at = 0; at < all.length; at += BINARY_PART_BYTES) void emit({ id, data: all.subarray(at, at + BINARY_PART_BYTES).toString("base64") });
+          void emit({ id, done: true });
+        });
+        response.on("close", () => {
+          if (ended || !handles.has(id)) return;
+          handles.delete(id);
+          void emit({ id, done: true, error: "closed" });
+        });
+      });
+      handles.set(id, { close: () => { handles.delete(id); request.destroy(); } });
+      request.on("error", () => {
+        handles.delete(id);
+        if (!settled) rejectOpen(new TunnelError("HARNESS_UNAVAILABLE", "The daemon did not answer."));
+      });
+      request.end(body);
+    });
+  };
+
+  const openWs = (params) => {
+    claim(params.id);
+    const { id } = params;
+    const url = tunnelPath(params.path);
+    url.searchParams.set("token", target.token);
+    return new Promise((resolveOpen, rejectOpen) => {
+      const socket = new WebSocket(`ws://127.0.0.1:${target.port}${url.pathname}${url.search}`, {
+        headers: { [RELAY_HEADER]: "1" },
+        perMessageDeflate: false,
+        maxPayload: 256 * 1024 * 1024,
+      });
+      let opened = false;
+      handles.set(id, { socket, close: () => { handles.delete(id); socket.terminate(); } });
+      socket.on("open", () => {
+        opened = true;
+        resolveOpen({});
+      });
+      socket.on("message", (data, binary) => {
+        if (binary) return;
+        const text = data.toString("utf8");
+        socket.pause();
+        let sent = Promise.resolve();
+        const parts = Math.max(1, Math.ceil(text.length / TEXT_CHUNK_CHARS));
+        for (let index = 0; index < parts; index += 1) {
+          sent = emit({ id, text: text.slice(index * TEXT_CHUNK_CHARS, (index + 1) * TEXT_CHUNK_CHARS), more: index < parts - 1 });
+        }
+        void sent.then(() => socket.resume());
+      });
+      socket.on("close", (code) => {
+        const known = handles.delete(id);
+        if (!opened) rejectOpen(new TunnelError("HARNESS_UNAVAILABLE", `The daemon refused the socket (${code}).`));
+        else if (known) void emit({ id, done: true, code });
+      });
+      socket.on("error", () => undefined);
+    });
+  };
+
+  const call = async (method, params) => {
+    if (params === null || typeof params !== "object") throw new TunnelError("INVALID_MESSAGE", "Missing parameters.");
+    switch (method) {
+      case "omp.http.open":
+        return openHttp(params);
+      case "omp.ws.open":
+        return openWs(params);
+      case "omp.ws.send": {
+        const socket = handles.get(params.id)?.socket;
+        if (socket === undefined || typeof params.text !== "string") throw new TunnelError("CONNECTION_NOT_FOUND", "No such socket.");
+        await new Promise((resolveSend, rejectSend) => socket.send(params.text, (error) => (error ? rejectSend(new TunnelError("CONNECTION_FAILED", "Socket closed.")) : resolveSend())));
+        return {};
+      }
+      case "omp.close":
+        handles.get(params.id)?.close();
+        return {};
+      default:
+        throw new TunnelError("METHOD_NOT_FOUND", `Unknown method ${String(method)}.`);
+    }
+  };
+
+  return {
+    async handle(message) {
+      if (message.type !== "rpc.request") return createRpcError(message.id, "INVALID_MESSAGE", "Only RPC requests are accepted.");
+      const { method, params } = message.payload ?? {};
+      try {
+        return createRpcResponse(message.id, await call(method, params));
+      } catch (error) {
+        const code = error instanceof TunnelError ? error.code : "HARNESS_UNAVAILABLE";
+        return createRpcError(message.id, code, error instanceof Error ? error.message : String(error));
+      }
+    },
+    closePeerStreams() {
+      for (const handle of [...handles.values()]) handle.close();
+    },
+  };
+}
+
+/**
+ * This daemon's Host identity, pairing and relay connection on one server.
+ * State (identity key, device tokens, pinned phones, a pairing in progress)
+ * lives in `dir`, owner-only.
+ */
+export class RelayHost {
+  /**
+   * @param {{serverUrl: string, dir: string, name: string, version: string, port: () => number, token: string, log: (line: string) => void}} options
+   */
+  constructor(options) {
+    this.options = options;
+    this.serverUrl = options.serverUrl.replace(/\/+$/, "");
+    this.pairing = undefined;
+    this.connection = undefined;
+  }
+
+  async start() {
+    const { dir, name, log } = this.options;
+    this.identities = new IdentityStore({ directory: dir });
+    this.identity = await this.identities.loadOrCreate(name);
+    this.api = new HostServerApi(this.serverUrl, new ServerCredentialStore(this.identities.directory));
+    this.api.bindIdentity(this.identity);
+    const write = (level) => (line) => log(`relay ${level}: ${line}`);
+    this.logger = new SafeLogger({ debug() {}, info: write("info"), warn: write("warn"), error: write("error") });
+    this.connections = new ConnectionController(
+      this.identities,
+      (_context, send) => createTunnelRouter({ port: this.options.port(), token: this.options.token }, send),
+      this.logger,
+    );
+    if (await this.api.hasStoredAuthorization()) this.connect();
+  }
+
+  /** Go (back) online with the device tokens a pairing left. */
+  connect() {
+    if (this.connection !== undefined) {
+      this.connection.reconnect();
+      return;
+    }
+    const config = {
+      serverUrl: this.serverUrl,
+      // No WebRTC on the computer: phone traffic always goes through the relay, still end-to-end encrypted.
+      forceRelay: true,
+      rotatePinnedPeerKey: false,
+      reconnect: { enabled: true, initialDelayMs: 2_000, maxDelayMs: 30_000, jitter: 0.2 },
+    };
+    this.connection = new HostServerConnection(config, this.identity, this.identities, this.api, this.connections, this.logger);
+    this.connection.start();
+  }
+
+  /** The pairing workflow; its state survives restarts in `dir`. */
+  hostPairing() {
+    this.pairing ??= new HostPairing(
+      this.serverUrl,
+      this.identities.directory,
+      this.identity,
+      {
+        deviceId: this.identity.deviceId,
+        name: this.identity.name,
+        role: "host",
+        platform: process.platform,
+        identityKey: this.identity.publicKey,
+        clientVersion: `omp-mobile/${this.options.version}`,
+      },
+      async (credentials) => {
+        await this.api.adoptPairing(credentials);
+        this.connect();
+      },
+    );
+    return this.pairing;
+  }
+
+  /** Start a pairing: the view carries `qrPayload`, the link the phone scans. */
+  async pairStart() {
+    // A finished pairing is left on disk, and asking the server about it again can fail
+    // (MEMBERSHIP_REQUIRED once its phone was revoked): drop it; an open one `start` cancels itself.
+    const previous = await this.hostPairing()
+      .status()
+      .catch(() => undefined);
+    if (previous === undefined || !["created", "claimed", "approved"].includes(previous.state)) {
+      await this.pairing.discard();
+      this.pairing = undefined;
+    }
+    return this.hostPairing().start();
+  }
+
+  /** Where the pairing stands (a phone claimed it: `mobile` names it); undefined when none. */
+  pairStatus() {
+    return this.hostPairing().status();
+  }
+
+  /** Approve the phone with the 8-digit code it shows. One attempt: a wrong code ends the pairing. */
+  pairConfirm(sessionId, code) {
+    return this.hostPairing().confirm(sessionId, code);
+  }
+
+  pairCancel(sessionId) {
+    return this.hostPairing().cancel(sessionId);
+  }
+
+  /** Paired phones, as the server lists them, and whether each is connected now. */
+  async phones() {
+    if (!(await this.api.hasStoredAuthorization())) return [];
+    const connected = new Set(this.connections.peerDeviceIds());
+    // `/devices` is for client devices; a host lists its phones through its memberships.
+    const { accessToken } = await this.api.authenticate();
+    const response = await fetch(`${this.serverUrl}/api/v1/device-memberships?limit=100`, { headers: { authorization: `Bearer ${accessToken}` } });
+    if (!response.ok) throw new Error(`The relay refused the phone list (HTTP ${response.status}).`);
+    const { items } = await response.json();
+    return (Array.isArray(items) ? items : []).map(({ peer }) => ({
+      deviceId: peer.deviceId,
+      name: peer.name,
+      platform: peer.platform,
+      connected: connected.has(peer.deviceId),
+    }));
+  }
+
+  /** Revoke one phone: the server ends its membership; its connection closes now. */
+  async revoke(deviceId) {
+    const { accessToken } = await this.api.authenticate();
+    const response = await fetch(`${this.serverUrl}/api/v1/device-memberships/${encodeURIComponent(deviceId)}`, {
+      method: "DELETE",
+      headers: { authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok && response.status !== 403) throw new Error(`The relay refused the revoke (HTTP ${response.status}).`);
+    await this.connections.revoke(deviceId);
+  }
+
+  async status() {
+    // Before `start` finished there is no identity yet: not paired, not online.
+    return {
+      server: this.serverUrl,
+      deviceId: this.identity?.deviceId ?? null,
+      paired: (await this.api?.hasStoredAuthorization()) ?? false,
+      online: this.connection?.isOnline() ?? false,
+      connected: this.connections?.connectionCount() ?? 0,
+    };
+  }
+
+  async close() {
+    await this.connection?.stop().catch(() => undefined);
+    await this.connections?.close().catch(() => undefined);
+    this.pairing?.close();
+    this.api?.close();
+  }
+}

package/src/server.mjs

@@ -21,6 +21,8 @@ import { AttentionTracker, serveEvents } from "./attention.mjs";
 import { listOmpSessions, oneLine, promptTitle, sessionOwners } from "./omp-sessions.mjs";
 import { askOwnerToLeave, forksOf, isOmpCommand, processInfo, sessionBusy, takeoverFarewell, tellTerminal } from "./takeover.mjs";
 import { TranscriptStore, deltaBody, deltaQuery } from "./transcripts.mjs";
+import { RELAY_HEADER, RelayHost } from "./relay.mjs";
+import { DEFAULT_RELAY, runRelayCli } from "./relay-control.mjs";
 
 const { version: VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const PROTOCOL = 1;
@@ -28,6 +30,7 @@ const DEFAULT_PORT = 7390;
 const DEFAULT_TOKEN_FILE = join(homedir(), ".omp-mobile", "token");
 const DEFAULT_REGISTRY_FILE = join(homedir(), ".omp-mobile", "sessions.json");
 const DEFAULT_STATE_FILE = join(homedir(), ".omp-mobile", "daemon.json");
+const DEFAULT_RELAY_DIR = join(homedir(), ".omp-mobile", "relay");
 const DEFAULT_OMP_HOME = join(homedir(), ".omp");
 const MAX_BODY = 256 * 1024;
 /** Terminal sessions listed next to the daemon's own, newest first. */
@@ -58,8 +61,6 @@ const IDLE_SESSION_MS = 30 * 60_000;
 const REAP_INTERVAL_MS = 60_000;
 /** Messages a live session keeps in memory; older ones leave its front (its `base` counts them). */
 const MAX_LIVE_MESSAGES = 5_000;
-/** Events that are a session being used: a turn and what it streams. State and setting echoes are not. */
-const ACTIVITY_EVENT = /^(agent_|turn_|message_|tool_execution_|auto_compaction_|auto_retry_)/;
 /**
  * The fields of a tool result's `details` the app reads: an edit's diff, a
  * read's line count, a command's run time, a screenshot's file. The rest
@@ -148,6 +149,8 @@ function parseArgs(argv) {
     tailscale: "tailscale",
     whois: true,
     qr: true,
+    relay: "",
+    relayDir: DEFAULT_RELAY_DIR,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const flag = argv[i];
@@ -210,6 +213,19 @@ function parseArgs(argv) {
       case "--no-qr":
         options.qr = false;
         break;
+      case "--relay":
+        // The server is optional: `--relay` alone means the public ds-harness-remote relay.
+        if (value !== undefined && !value.startsWith("--")) {
+          options.relay = value;
+          i += 1;
+        } else {
+          options.relay = DEFAULT_RELAY;
+        }
+        break;
+      case "--relay-dir":
+        options.relayDir = resolve(value);
+        i += 1;
+        break;
       case "--help":
       case "-h":
         printHelp();
@@ -247,6 +263,14 @@ Admission: on a non-loopback --host every request and WebSocket upgrade must nam
 this node in Host (421 otherwise) and come from a tailnet device of this node's
 user (403 otherwise), before the token is checked. Loopback hosts skip admission.
   --no-qr                Do not print the pairing QR code at startup
+  --relay [url]          Also serve paired phones through a ds-harness-remote relay (default ${DEFAULT_RELAY}),
+                         end-to-end encrypted; pair with \`omp-mobile relay pair\` or /mobile relay
+  --relay-dir <dir>      Relay identity and device tokens (default ~/.omp-mobile/relay)
+
+Relay commands (talk to the running daemon; same --state-file):
+  omp-mobile relay pair       Show a pairing QR code, then confirm the phone's 8-digit code
+  omp-mobile relay status     Relay server, connection and paired phones
+  omp-mobile relay revoke <phone device id>
 `);
 }
 
@@ -638,8 +662,10 @@ class SessionEntry {
 
   bind() {
     this.rpc.on("event", (event) => {
-      if (typeof event?.type === "string" && ACTIVITY_EVENT.test(event.type)) this.updatedAt = Date.now();
       if (event.type === "message_end" && event.message) {
+        // A new message is what makes a session the most recent one; opening it,
+        // a lifecycle event from a resumed omp, or a state echo are not.
+        this.updatedAt = Date.now();
         this.messages.push(phoneMessage(event.message, this.blobDir));
         if (this.messages.length > MAX_LIVE_MESSAGES) {
           // Indices stay the transcript's: a phone's `since` still lines up after the front is dropped.
@@ -746,6 +772,29 @@ class Daemon {
     // the phone's WebSocket client (OkHttp) asks for permessage-deflate on its own.
     this.wsServer = new WebSocketServer({ noServer: true, perMessageDeflate: { threshold: 1_024 } });
     this.server.on("upgrade", (req, socket, head) => void this.admitUpgrade(req, socket, head));
+    /**
+     * Phones paired through a relay reach the daemon through this loopback-only
+     * listener (`relay.mjs` adds the token): the same API, without the tailnet admission.
+     */
+    this.tunnelServer = undefined;
+    /** @type {RelayHost | undefined} */
+    this.relay = undefined;
+    if (options.relay) {
+      this.tunnelServer = createServer((req, res) => void this.handleHttp(req, res));
+      this.tunnelServer.on("upgrade", (req, socket, head) => {
+        socket.on("error", () => socket.destroy());
+        this.handleUpgrade(req, socket, head);
+      });
+      this.relay = new RelayHost({
+        serverUrl: options.relay,
+        dir: options.relayDir,
+        name: `omp-mobile on ${hostname().replace(/\.local$/, "")}`,
+        version: VERSION,
+        port: () => this.tunnelServer.address().port,
+        token: this.token,
+        log: (line) => this.log(line),
+      });
+    }
   }
 
   baseUrl() {
@@ -828,9 +877,14 @@ class Daemon {
         liveSessions: this.sessions.size,
         eventStreams: this.streams.size,
         lastPhone: this.lastPhone,
+        relay: this.relay === undefined ? null : await this.relay.status(),
       });
       return;
     }
+    if (url.pathname === "/relay" || url.pathname.startsWith("/relay/")) {
+      await this.handleRelay(req, res, url);
+      return;
+    }
     if (url.pathname === "/events" && req.method === "GET") {
       const end = serveEvents(this.attention, req, res);
       this.streams.add(end);
@@ -1125,7 +1179,7 @@ class Daemon {
       const deadline = Date.now() + 3_000;
       while ((await this.owners())?.get(id) === pid && Date.now() < deadline) await new Promise((wait) => setTimeout(wait, 100));
       // Whoever looks at the terminal sees why omp closed.
-      if (info?.tty !== undefined) tellTerminal(info.tty, takeoverFarewell(device));
+      if (info?.tty !== undefined) tellTerminal(info.tty, takeoverFarewell({ device, sessionFile: stored.sessionFile }));
       const forks = forksOf(dirname(stored.sessionFile), id, since);
       if (forks.length > 0) this.log(new Error(`taking over ${id} from pid ${pid} left forked session files: ${forks.join(", ")}`));
       outcome = { pid, via: left.via, waitedMs: left.waitedMs, busy, forks };
@@ -1253,6 +1307,8 @@ class Daemon {
           const text = typeof message.text === "string" ? message.text : "";
           if (text.trim() === "" && images.length === 0) throw new Error("empty prompt");
           await entry.rpc.prompt(text, images);
+          entry.updatedAt = Date.now();
+          entry.onChange?.(entry);
           ws.send(JSON.stringify({ type: "accepted", command: "prompt" }));
           return;
         }
@@ -1284,7 +1340,6 @@ class Daemon {
           }
           const state = await entry.rpc.setModel(message.provider, message.modelId);
           entry.state = state;
-          entry.updatedAt = Date.now();
           entry.onChange?.(entry);
           entry.broadcast({ type: "state", state });
           ws.send(JSON.stringify({ type: "accepted", command: "set_model" }));
@@ -1301,7 +1356,6 @@ class Daemon {
           if (typeof message.level !== "string" || message.level === "") throw new Error("set_thinking_level needs a level");
           const state = await entry.rpc.setThinkingLevel(message.level);
           entry.state = state;
-          entry.updatedAt = Date.now();
           entry.broadcast({ type: "state", state });
           ws.send(JSON.stringify({ type: "accepted", command: "set_thinking_level" }));
           return;
@@ -1328,17 +1382,72 @@ class Daemon {
    */
   noteClient(req) {
     if (req.headers["x-omp-mobile-probe"] !== undefined) return;
-    const address = String(req.socket?.remoteAddress ?? "").replace(/^::ffff:/i, "");
+    // Through the relay every request comes from loopback: name the path instead.
+    const address = req.headers[RELAY_HEADER] !== undefined ? "relay" : String(req.socket?.remoteAddress ?? "").replace(/^::ffff:/i, "");
     this.lastPhone = { address, at: Date.now() };
   }
 
-  listen() {
-    return new Promise((resolveListen) => {
-      this.server.listen(this.options.port, this.options.host, () => {
-        this.startTimers();
-        resolveListen();
-      });
-    });
+  /**
+   * Relay pairing and phones, for `omp-mobile relay` and `/mobile relay` on this
+   * computer; never through the relay itself (a paired phone cannot pair or revoke).
+   */
+  async handleRelay(req, res, url) {
+    if (req.headers[RELAY_HEADER] !== undefined) {
+      sendJson(res, 403, { error: "relay control is local only" });
+      return;
+    }
+    if (this.relay === undefined) {
+      sendJson(res, 409, { error: "the daemon runs without --relay" });
+      return;
+    }
+    try {
+      if (url.pathname === "/relay" && req.method === "GET") {
+        sendJson(res, 200, { ...(await this.relay.status()), phones: await this.relay.phones() });
+        return;
+      }
+      if (url.pathname === "/relay/pair" && req.method === "POST") {
+        sendJson(res, 200, await this.relay.pairStart());
+        return;
+      }
+      if (url.pathname === "/relay/pair" && req.method === "GET") {
+        sendJson(res, 200, { pairing: (await this.relay.pairStatus()) ?? null });
+        return;
+      }
+      if ((url.pathname === "/relay/pair/confirm" || url.pathname === "/relay/pair/cancel") && req.method === "POST") {
+        const body = await readBody(req);
+        if (typeof body.sessionId !== "string") {
+          sendJson(res, 400, { error: "sessionId is required" });
+          return;
+        }
+        const confirm = url.pathname.endsWith("/confirm");
+        if (confirm && (typeof body.code !== "string" || !/^\d{8}$/.test(body.code))) {
+          sendJson(res, 400, { error: "the code is 8 digits" });
+          return;
+        }
+        sendJson(res, 200, confirm ? await this.relay.pairConfirm(body.sessionId, body.code) : await this.relay.pairCancel(body.sessionId));
+        return;
+      }
+      const phone = /^\/relay\/phones\/([^/]+)$/.exec(url.pathname);
+      if (phone !== null && req.method === "DELETE") {
+        await this.relay.revoke(decodeURIComponent(phone[1]));
+        sendJson(res, 200, { ok: true });
+        return;
+      }
+      sendJson(res, 404, { error: "not found" });
+    } catch (error) {
+      // The relay's own refusals carry a code (PAIRING_EXPIRED, PAIRING_ATTEMPT_USED, ...): pass it on.
+      const code = typeof error?.code === "string" ? error.code : undefined;
+      sendJson(res, 502, { error: error instanceof Error ? error.message : String(error), ...(code === undefined ? {} : { code }) });
+    }
+  }
+
+  async listen() {
+    await new Promise((resolveListen) => this.server.listen(this.options.port, this.options.host, () => resolveListen()));
+    if (this.relay !== undefined) {
+      await new Promise((resolveListen) => this.tunnelServer.listen(0, "127.0.0.1", () => resolveListen()));
+      await this.relay.start();
+    }
+    this.startTimers();
   }
 
   /** Keepalive pings and the idle-session reaper, once the daemon listens; old stashed images go. */
@@ -1395,7 +1504,9 @@ class Daemon {
     const outcomes = await Promise.all(closing);
     const stuck = outcomes.filter((outcome) => outcome === "running").length;
     if (stuck > 0) console.error(`omp-mobile: ${stuck} omp process(es) ignored SIGINT and SIGTERM and are still running`);
+    await this.relay?.close();
     this.wsServer.close();
+    this.tunnelServer?.close();
     await new Promise((resolveClose) => this.server.close(() => resolveClose()));
   }
 }
@@ -1473,6 +1584,10 @@ function clearState(path) {
 }
 
 async function main() {
+  if (process.argv[2] === "relay") {
+    await runRelayCli(process.argv.slice(3));
+    return;
+  }
   const options = parseArgs(process.argv.slice(2));
   if (options.host === "tailscale") options.host = await tailscaleHost(options);
   const token = loadToken(options);
@@ -1481,21 +1596,26 @@ async function main() {
   await daemon.listen();
   const url = daemon.baseUrl();
   const pair = `omp-mobile://pair?url=${encodeURIComponent(url)}&token=${encodeURIComponent(token)}`;
-  writeState(options.stateFile, { pid: process.pid, version: VERSION, url, pair, startedAt: daemon.startedAt });
+  writeState(options.stateFile, { pid: process.pid, version: VERSION, url, pair, relay: options.relay || null, startedAt: daemon.startedAt });
   console.log(`omp-mobile daemon ${VERSION}`);
   console.log(`  listening  ${url}`);
   console.log(`  cwd        ${options.cwd}`);
   for (const line of identity.notes) (line.includes("WARNING") ? console.warn : console.log)(line);
   console.log(`  token      ${token}`);
   console.log(`  pair       ${pair}`);
-  if (options.qr) {
+  if (daemon.relay !== undefined) {
+    const relay = await daemon.relay.status();
+    console.log(`  relay      ${relay.server} · ${relay.paired ? "paired" : "no phone paired yet"} · pair a phone: omp-mobile relay pair`);
+  }
+  const tailnet = isTailnetAddress(options.host);
+  if (options.qr && (tailnet || daemon.relay === undefined)) {
     console.log("");
     console.log("  Scan with OMP on your phone (Machines > Scan to pair):");
     console.log(renderQr(pair));
     // The app accepts only tailnet addresses from a code; say so before the user tries.
-    if (!isTailnetAddress(options.host)) {
+    if (!tailnet) {
       console.log(`  note: ${options.host} is not a Tailscale address, so the app will refuse this code.`);
-      console.log("        Start with --host <this computer's Tailscale IP> to pair a phone.");
+      console.log("        Start with --host <this computer's Tailscale IP>, or --relay, to pair a phone.");
     }
   }
   const shutdown = async () => {