@moxxy/plugin-tunnel-proxy 0.27.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @moxxy/plugin-tunnel-proxy
+
+The self-hosted **proxy** tunnel provider — a native-Node replacement for the
+cloudflared/ngrok subprocess providers. It exposes a local port at a stable,
+keypair-derived public URL (`https://<uuid>.proxy.moxxy.ai`) by dialing the
+proxy relay; there is no binary to install, no account, and no login.
+
+## How it works
+
+1. `open({ port, host })` loads the agent's identity key (`@moxxy/e2e/node`,
+   `~/.moxxy/proxy-identity.key`) and dials the relay's control WebSocket
+   (`wss://relay.<host>/control`).
+2. The relay sends a challenge nonce; the provider signs it (proof of key
+   ownership), and the relay derives `uuid = base32(sha256(pubkey))` and binds
+   the subdomain. The provider cross-checks that the relay returned exactly the
+   uuid its own key derives.
+3. For every inbound peer the relay signals, the provider opens a `/data`
+   WebSocket and pipes its raw bytes to `host:port`. It is protocol-agnostic —
+   the bytes may be an (E2E-wrapped) phone WebSocket or a browser's HTTP.
+4. The control connection self-heals with capped exponential backoff. The uuid
+   is stable across reconnects because it derives from the (stable) public key.
+
+The wire protocol is in [`src/protocol.ts`](./src/protocol.ts) — the single
+coupling point with the private relay repo (see its `PROTOCOL.md`).
+
+## Configuration
+
+- `MOXXY_PROXY_HOST` — public base host (default `proxy.moxxy.ai`).
+- `createProxyTunnel({ baseHost, controlUrl, identityPath })` — factory form,
+  used by tests (point `controlUrl` at a local relay) and embedders.
+
+## Security
+
+End-to-end encryption against a malicious relay is **not** in this provider — it
+is a dumb byte pipe. For the mobile path, the phone and a local E2E shim run the
+`@moxxy/e2e` handshake *inside* the tunnel; this provider just carries the
+ciphertext. The browser-preview path has no in-tunnel E2E and relies on the
+relay's wildcard TLS (same posture as cloudflared/ngrok, but self-owned).

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@moxxy/plugin-tunnel-proxy` — the self-hosted `proxy` tunnel provider.
+ *
+ * Registers the `proxy` provider so registry-driven channels (the web/preview
+ * channel) can activate it. The mobile channel imports {@link proxyTunnel} /
+ * {@link createProxyTunnel} directly, mirroring how it used to import the
+ * cloudflared/ngrok providers.
+ */
+import { type Plugin } from '@moxxy/sdk';
+export { createProxyTunnel, proxyTunnel, type ProxyTunnelOptions, type ProxyLogger, } from './provider.js';
+export { PROXY_PROTOCOL_VERSION, DEFAULT_PROXY_HOST, relayControlHost, publicUrl, type ControlServerMsg, type ControlClientMsg, type DataAttachMsg, } from './protocol.js';
+/** The plugin: contributes the `proxy` tunnel provider for auto-discovery. */
+export declare const proxyTunnelPlugin: Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAGvD,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAEvB,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,MAI9B,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@moxxy/plugin-tunnel-proxy` — the self-hosted `proxy` tunnel provider.
+ *
+ * Registers the `proxy` provider so registry-driven channels (the web/preview
+ * channel) can activate it. The mobile channel imports {@link proxyTunnel} /
+ * {@link createProxyTunnel} directly, mirroring how it used to import the
+ * cloudflared/ngrok providers.
+ */
+import { definePlugin } from '@moxxy/sdk';
+import { proxyTunnel } from './provider.js';
+export { createProxyTunnel, proxyTunnel, } from './provider.js';
+export { PROXY_PROTOCOL_VERSION, DEFAULT_PROXY_HOST, relayControlHost, publicUrl, } from './protocol.js';
+/** The plugin: contributes the `proxy` tunnel provider for auto-discovery. */
+export const proxyTunnelPlugin = definePlugin({
+    name: '@moxxy/plugin-tunnel-proxy',
+    version: '0.0.0',
+    tunnelProviders: [proxyTunnel],
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,WAAW,GAGZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,GAIV,MAAM,eAAe,CAAC;AAEvB,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAW,YAAY,CAAC;IACpD,IAAI,EAAE,4BAA4B;IAClC,OAAO,EAAE,OAAO;IAChB,eAAe,EAAE,CAAC,WAAW,CAAC;CAC/B,CAAC,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The proxy client↔relay wire protocol (v1). This is the single coupling point
+ * between this provider (open source) and the private relay repo, which mirrors
+ * these shapes. See PROTOCOL.md in the relay repo for the prose spec.
+ *
+ * Two long-lived agent→relay WebSockets, both to `wss://relay.<baseHost>`:
+ *   - `/control` — registration (keypair proof-of-possession) + "new inbound
+ *     connection" signalling. One per agent.
+ *   - `/data?...` — one per inbound connection; after a one-line `attach`, it
+ *     carries the raw tunnelled bytes as binary frames.
+ *
+ * Public peers (phone, browser) reach the agent at `https://<uuid>.<baseHost>/<target>`;
+ * the relay terminates TLS, routes by the SNI subdomain to the agent, reads the
+ * first path segment as the `target`, and pipes the raw byte stream over a fresh
+ * `/data` connection. The agent maps `target` → a local port (several channels
+ * multiplex under one uuid). The provider is otherwise a dumb byte pipe — it
+ * doesn't parse whether the bytes are WebSocket or HTTP.
+ */
+export declare const PROXY_PROTOCOL_VERSION = 1;
+/** Default public base host; the agent dials `relay.<host>`, peers reach `<uuid>.<host>`. */
+export declare const DEFAULT_PROXY_HOST = "proxy.moxxy.ai";
+/** WebSocket paths on the relay control host. */
+export declare const CONTROL_PATH = "/control";
+export declare const DATA_PATH = "/data";
+/** Relay → agent, on the control connection. */
+export type ControlServerMsg = 
+/** Sent first: a random base64url nonce the agent must sign to prove key ownership. */
+{
+    readonly t: 'challenge';
+    readonly v: number;
+    readonly nonce: string;
+}
+/** Sent after a valid registration: the derived subdomain + the public base host. */
+ | {
+    readonly t: 'registered';
+    readonly uuid: string;
+    readonly host: string;
+}
+/** A new inbound peer connection; the agent must open a `/data` conn with this
+ *  id. `target` is the first path segment of the peer's request (e.g. `mobile`,
+ *  `web`), naming which local service the agent pipes it to. */
+ | {
+    readonly t: 'open';
+    readonly connId: string;
+    readonly target: string;
+}
+/** Fatal: the relay is rejecting/closing the control connection. */
+ | {
+    readonly t: 'error';
+    readonly message: string;
+};
+/** Agent → relay, on the control connection. */
+export type ControlClientMsg = 
+/** Register: present the Ed25519 public key + a signature over the challenge nonce. */
+{
+    readonly t: 'register';
+    readonly v: number;
+    /** base64url(Ed25519 public key). */
+    readonly pubkey: string;
+    /** base64url(Ed25519 signature over the raw nonce bytes). */
+    readonly sig: string;
+};
+/** Agent → relay, the first (text) frame on a `/data` connection. */
+export interface DataAttachMsg {
+    readonly t: 'attach';
+    readonly v: number;
+    /** The single-use capability id the relay sent in the matching `open`. */
+    readonly connId: string;
+}
+/** The host the agent dials for control/data (covered by the `*.<host>` cert). */
+export declare function relayControlHost(baseHost: string): string;
+/** The public URL a peer uses to reach this agent (optionally a routing target). */
+export declare function publicUrl(uuid: string, baseHost: string, target?: string): string;
+export declare function encodeJson(msg: unknown): string;
+export declare function decodeControlServerMsg(raw: string): ControlServerMsg;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD,iDAAiD;AACjD,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB;AAC1B,uFAAuF;AACrF;IAAE,QAAQ,CAAC,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACzE,qFAAqF;GACnF;IAAE,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC5E;;gEAEgE;GAC9D;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC1E,oEAAoE;GAClE;IAAE,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,gDAAgD;AAChD,MAAM,MAAM,gBAAgB;AAC1B,uFAAuF;AACvF;IACE,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAEJ,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC;IACrB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE/C;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAIpE"}

package/dist/protocol.js

@@ -0,0 +1,43 @@
+/**
+ * The proxy client↔relay wire protocol (v1). This is the single coupling point
+ * between this provider (open source) and the private relay repo, which mirrors
+ * these shapes. See PROTOCOL.md in the relay repo for the prose spec.
+ *
+ * Two long-lived agent→relay WebSockets, both to `wss://relay.<baseHost>`:
+ *   - `/control` — registration (keypair proof-of-possession) + "new inbound
+ *     connection" signalling. One per agent.
+ *   - `/data?...` — one per inbound connection; after a one-line `attach`, it
+ *     carries the raw tunnelled bytes as binary frames.
+ *
+ * Public peers (phone, browser) reach the agent at `https://<uuid>.<baseHost>/<target>`;
+ * the relay terminates TLS, routes by the SNI subdomain to the agent, reads the
+ * first path segment as the `target`, and pipes the raw byte stream over a fresh
+ * `/data` connection. The agent maps `target` → a local port (several channels
+ * multiplex under one uuid). The provider is otherwise a dumb byte pipe — it
+ * doesn't parse whether the bytes are WebSocket or HTTP.
+ */
+export const PROXY_PROTOCOL_VERSION = 1;
+/** Default public base host; the agent dials `relay.<host>`, peers reach `<uuid>.<host>`. */
+export const DEFAULT_PROXY_HOST = 'proxy.moxxy.ai';
+/** WebSocket paths on the relay control host. */
+export const CONTROL_PATH = '/control';
+export const DATA_PATH = '/data';
+/** The host the agent dials for control/data (covered by the `*.<host>` cert). */
+export function relayControlHost(baseHost) {
+    return `relay.${baseHost}`;
+}
+/** The public URL a peer uses to reach this agent (optionally a routing target). */
+export function publicUrl(uuid, baseHost, target) {
+    const base = `https://${uuid}.${baseHost}`;
+    return target ? `${base}/${target}` : base;
+}
+export function encodeJson(msg) {
+    return JSON.stringify(msg);
+}
+export function decodeControlServerMsg(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.t !== 'string')
+        throw new Error('proxy: control message missing type');
+    return parsed;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,6FAA6F;AAC7F,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD,iDAAiD;AACjD,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AACvC,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC;AAmCjC,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,SAAS,QAAQ,EAAE,CAAC;AAC7B,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,QAAgB,EAAE,MAAe;IACvE,MAAM,IAAI,GAAG,WAAW,IAAI,IAAI,QAAQ,EAAE,CAAC;IAC3C,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;IAClD,IAAI,OAAO,MAAM,CAAC,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzF,OAAO,MAA0B,CAAC;AACpC,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,19 @@
+import { type TunnelProviderDef } from '@moxxy/sdk';
+export interface ProxyLogger {
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+export interface ProxyTunnelOptions {
+    /** Public base host. Default: `MOXXY_PROXY_HOST` env, else `proxy.moxxy.ai`. */
+    readonly baseHost?: string;
+    /** Override the control/data WS base (e.g. `ws://127.0.0.1:PORT` in tests). */
+    readonly controlUrl?: string;
+    /** Override the identity key path (defaults to `~/.moxxy/proxy-identity.key`). */
+    readonly identityPath?: string;
+    readonly logger?: ProxyLogger;
+}
+/** Build a `proxy` tunnel provider (factory form, for config/tests). */
+export declare function createProxyTunnel(opts?: ProxyTunnelOptions): TunnelProviderDef;
+/** The default `proxy` provider (reads `MOXXY_PROXY_HOST` at open time). */
+export declare const proxyTunnel: TunnelProviderDef;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AA0BA,OAAO,EAA2C,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAe7F,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AA4PD,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,kBAAuB,GAAG,iBAAiB,CAwBlF;AAED,4EAA4E;AAC5E,eAAO,MAAM,WAAW,EAAE,iBAAuC,CAAC"}

package/dist/provider.js

@@ -0,0 +1,301 @@
+/**
+ * The `proxy` tunnel provider — a native-Node replacement for the cloudflared/
+ * ngrok subprocess providers.
+ *
+ * Several channels (the mobile bridge, the web preview, the webhooks listener)
+ * can be exposed at once under ONE keypair-derived subdomain: a process-singleton
+ * {@link ProxyHub} owns a single control connection per identity and a
+ * `target → local port` map. Each `open({ port, host, label })` registers a
+ * target and returns `https://<uuid>.<host>/<label>`. For every inbound peer the
+ * relay signals (`open { connId, target }`), the hub opens a `/data` WebSocket
+ * and pipes its raw bytes to that target's port — protocol-agnostic, so the bytes
+ * may be a phone's (E2E-wrapped) WebSocket or a browser's HTTP.
+ *
+ * The control connection self-heals with capped exponential backoff; because the
+ * uuid derives from the (stable) public key, the public URL never changes.
+ */
+import { connect as netConnect } from 'node:net';
+import { base64urlDecode, base64urlEncode, deriveUuid, fingerprint, sign, } from '@moxxy/e2e';
+import { loadOrCreateIdentity } from '@moxxy/e2e/node';
+import { defineTunnelProvider } from '@moxxy/sdk';
+import { WebSocket } from 'ws';
+import { CONTROL_PATH, DATA_PATH, DEFAULT_PROXY_HOST, PROXY_PROTOCOL_VERSION, decodeControlServerMsg, encodeJson, publicUrl, relayControlHost, } from './protocol.js';
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+function resolveBaseHost(opts) {
+    return (opts.baseHost ?? process.env.MOXXY_PROXY_HOST ?? DEFAULT_PROXY_HOST).trim();
+}
+/** `ws://relay.<host>` / `wss://relay.<host>` unless an explicit controlUrl is given. */
+function resolveControlBase(opts, baseHost) {
+    if (opts.controlUrl)
+        return opts.controlUrl.replace(/\/$/, '');
+    return `wss://${relayControlHost(baseHost)}`;
+}
+/**
+ * One per (controlBase, identity): owns the control connection and the
+ * `target → port` map, multiplexing every channel's exposure under one uuid.
+ */
+class ProxyHub {
+    controlBase;
+    baseHost;
+    identityPath;
+    logger;
+    onEmpty;
+    identity = null;
+    uuid = null;
+    control = null;
+    registering = null;
+    targets = new Map();
+    dataConns = new Set();
+    localSockets = new Set();
+    closed = false;
+    reconnectMs = RECONNECT_MIN_MS;
+    reconnectTimer = null;
+    constructor(controlBase, baseHost, identityPath, logger, onEmpty) {
+        this.controlBase = controlBase;
+        this.baseHost = baseHost;
+        this.identityPath = identityPath;
+        this.logger = logger;
+        this.onEmpty = onEmpty;
+    }
+    /** Register a target and return its public URL + a remove() handle. */
+    async addTarget(label, host, port) {
+        const uuid = await this.ensureRegistered();
+        this.targets.set(label, { host, port });
+        this.logger?.info?.('proxy: target added', { uuid, label, port });
+        return {
+            url: publicUrl(uuid, this.baseHost, label),
+            close: () => {
+                this.removeTarget(label);
+                return Promise.resolve();
+            },
+        };
+    }
+    removeTarget(label) {
+        this.targets.delete(label);
+        if (this.targets.size === 0)
+            this.close();
+    }
+    /** Connect + register once; later callers reuse the resolved uuid. */
+    async ensureRegistered() {
+        if (this.uuid && this.control)
+            return this.uuid;
+        if (this.registering)
+            return this.registering;
+        if (!this.identity)
+            this.identity = await loadOrCreateIdentity(this.identityPath);
+        this.registering = this.connectControl();
+        try {
+            return await this.registering;
+        }
+        finally {
+            this.registering = null;
+        }
+    }
+    connectControl() {
+        const identity = this.identity;
+        const expected = deriveUuid(identity.publicKey);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = new WebSocket(`${this.controlBase}${CONTROL_PATH}`);
+            this.control = ws;
+            ws.on('message', (raw) => {
+                let msg;
+                try {
+                    msg = decodeControlServerMsg(raw.toString());
+                }
+                catch {
+                    return;
+                }
+                switch (msg.t) {
+                    case 'challenge': {
+                        const reply = {
+                            t: 'register',
+                            v: PROXY_PROTOCOL_VERSION,
+                            pubkey: base64urlEncode(identity.publicKey),
+                            sig: base64urlEncode(sign(base64urlDecode(msg.nonce), identity.secretKey)),
+                        };
+                        ws.send(encodeJson(reply));
+                        return;
+                    }
+                    case 'registered': {
+                        if (msg.uuid !== expected) {
+                            // A buggy or hostile relay handed back a uuid our key didn't derive.
+                            if (!settled) {
+                                settled = true;
+                                reject(new Error(`proxy: relay returned uuid '${msg.uuid}', expected '${expected}'`));
+                            }
+                            this.close();
+                            return;
+                        }
+                        this.uuid = msg.uuid;
+                        this.reconnectMs = RECONNECT_MIN_MS;
+                        if (!settled) {
+                            settled = true;
+                            resolve(msg.uuid);
+                        }
+                        return;
+                    }
+                    case 'open':
+                        this.openDataConn(msg.connId, msg.target);
+                        return;
+                    case 'error':
+                        this.logger?.warn?.('proxy: relay error', { message: msg.message });
+                        return;
+                }
+            });
+            ws.on('close', () => {
+                if (this.control === ws)
+                    this.control = null;
+                if (!settled) {
+                    settled = true;
+                    reject(new Error('proxy: control connection closed before registration'));
+                }
+                this.scheduleReconnect();
+            });
+            ws.on('error', (err) => {
+                this.logger?.warn?.('proxy: control connection error', { err: String(err) });
+                // 'close' follows and drives reconnect / rejection.
+            });
+        });
+    }
+    scheduleReconnect() {
+        if (this.closed || this.reconnectTimer || this.targets.size === 0)
+            return;
+        const delay = this.reconnectMs;
+        this.reconnectMs = Math.min(this.reconnectMs * 2, RECONNECT_MAX_MS);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.closed)
+                return;
+            this.connectControl()
+                .then(() => this.logger?.info?.('proxy: control reconnected'))
+                .catch(() => {
+                /* 'close' reschedules */
+            });
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+    /** Pipe one inbound peer (raw bytes over a `/data` WS) to its target's port. */
+    openDataConn(connId, target) {
+        if (this.closed)
+            return;
+        const entry = this.targets.get(target);
+        if (!entry) {
+            this.logger?.warn?.('proxy: open for unknown target; dropping', { target });
+            return; // relay's attach timeout tears down the waiting ingress
+        }
+        const ws = new WebSocket(`${this.controlBase}${DATA_PATH}`);
+        const local = netConnect({ host: entry.host, port: entry.port });
+        this.dataConns.add(ws);
+        this.localSockets.add(local);
+        let attached = false;
+        const localOutbox = [];
+        const cleanup = () => {
+            this.dataConns.delete(ws);
+            this.localSockets.delete(local);
+            try {
+                if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)
+                    ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                local.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        ws.on('open', () => {
+            const attach = { t: 'attach', v: PROXY_PROTOCOL_VERSION, connId };
+            ws.send(encodeJson(attach));
+            attached = true;
+            for (const chunk of localOutbox.splice(0))
+                ws.send(chunk, { binary: true });
+        });
+        ws.on('message', (data, isBinary) => {
+            if (isBinary)
+                local.write(data);
+        });
+        local.on('data', (buf) => {
+            if (attached && ws.readyState === WebSocket.OPEN)
+                ws.send(buf, { binary: true });
+            else
+                localOutbox.push(buf);
+        });
+        ws.on('close', cleanup);
+        ws.on('error', cleanup);
+        local.on('close', cleanup);
+        local.on('error', cleanup);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        for (const ws of this.dataConns) {
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        for (const s of this.localSockets) {
+            try {
+                s.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.dataConns.clear();
+        this.localSockets.clear();
+        this.targets.clear();
+        try {
+            this.control?.close();
+        }
+        catch {
+            /* ignore */
+        }
+        this.control = null;
+        this.onEmpty();
+    }
+}
+/** Process-wide hub registry, so all channels share one control conn per identity. */
+const hubs = new Map();
+function hubKey(controlBase, identityPath) {
+    return `${controlBase}${identityPath ?? ''}`;
+}
+/** Build a `proxy` tunnel provider (factory form, for config/tests). */
+export function createProxyTunnel(opts = {}) {
+    return defineTunnelProvider({
+        name: 'proxy',
+        open: async ({ port, host, label }) => {
+            const baseHost = resolveBaseHost(opts);
+            const controlBase = resolveControlBase(opts, baseHost);
+            const key = hubKey(controlBase, opts.identityPath);
+            let hub = hubs.get(key);
+            if (!hub) {
+                hub = new ProxyHub(controlBase, baseHost, opts.identityPath, opts.logger, () => hubs.delete(key));
+                hubs.set(key, hub);
+            }
+            const handle = await hub.addTarget(label ?? '', host, port);
+            // Surface the pinned fingerprint once per process for the QR/debugging.
+            const identity = await loadOrCreateIdentity(opts.identityPath);
+            opts.logger?.info?.('proxy: exposed', {
+                url: handle.url,
+                fingerprint: fingerprint(identity.publicKey),
+            });
+            return handle;
+        },
+    });
+}
+/** The default `proxy` provider (reads `MOXXY_PROXY_HOST` at open time). */
+export const proxyTunnel = createProxyTunnel();
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@moxxy/plugin-tunnel-proxy",
+  "version": "0.27.0",
+  "description": "Self-hosted tunnel provider for moxxy. Dials the proxy relay over an outbound control WebSocket, proves ownership of a keypair-derived subdomain (uuid.proxy.moxxy.ai), and pipes each inbound connection to a local port — a native-Node replacement for the cloudflared/ngrok subprocess providers.",
+  "keywords": [
+    "moxxy",
+    "tunnel",
+    "proxy",
+    "client"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-tunnel-proxy"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@moxxy/e2e": "0.27.0",
+    "@moxxy/sdk": "0.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@moxxy/plugin-tunnel-proxy` — the self-hosted `proxy` tunnel provider.
+ *
+ * Registers the `proxy` provider so registry-driven channels (the web/preview
+ * channel) can activate it. The mobile channel imports {@link proxyTunnel} /
+ * {@link createProxyTunnel} directly, mirroring how it used to import the
+ * cloudflared/ngrok providers.
+ */
+import { definePlugin, type Plugin } from '@moxxy/sdk';
+import { proxyTunnel } from './provider.js';
+
+export {
+  createProxyTunnel,
+  proxyTunnel,
+  type ProxyTunnelOptions,
+  type ProxyLogger,
+} from './provider.js';
+
+export {
+  PROXY_PROTOCOL_VERSION,
+  DEFAULT_PROXY_HOST,
+  relayControlHost,
+  publicUrl,
+  type ControlServerMsg,
+  type ControlClientMsg,
+  type DataAttachMsg,
+} from './protocol.js';
+
+/** The plugin: contributes the `proxy` tunnel provider for auto-discovery. */
+export const proxyTunnelPlugin: Plugin = definePlugin({
+  name: '@moxxy/plugin-tunnel-proxy',
+  version: '0.0.0',
+  tunnelProviders: [proxyTunnel],
+});

package/src/protocol.ts

@@ -0,0 +1,81 @@
+/**
+ * The proxy client↔relay wire protocol (v1). This is the single coupling point
+ * between this provider (open source) and the private relay repo, which mirrors
+ * these shapes. See PROTOCOL.md in the relay repo for the prose spec.
+ *
+ * Two long-lived agent→relay WebSockets, both to `wss://relay.<baseHost>`:
+ *   - `/control` — registration (keypair proof-of-possession) + "new inbound
+ *     connection" signalling. One per agent.
+ *   - `/data?...` — one per inbound connection; after a one-line `attach`, it
+ *     carries the raw tunnelled bytes as binary frames.
+ *
+ * Public peers (phone, browser) reach the agent at `https://<uuid>.<baseHost>/<target>`;
+ * the relay terminates TLS, routes by the SNI subdomain to the agent, reads the
+ * first path segment as the `target`, and pipes the raw byte stream over a fresh
+ * `/data` connection. The agent maps `target` → a local port (several channels
+ * multiplex under one uuid). The provider is otherwise a dumb byte pipe — it
+ * doesn't parse whether the bytes are WebSocket or HTTP.
+ */
+
+export const PROXY_PROTOCOL_VERSION = 1;
+
+/** Default public base host; the agent dials `relay.<host>`, peers reach `<uuid>.<host>`. */
+export const DEFAULT_PROXY_HOST = 'proxy.moxxy.ai';
+
+/** WebSocket paths on the relay control host. */
+export const CONTROL_PATH = '/control';
+export const DATA_PATH = '/data';
+
+/** Relay → agent, on the control connection. */
+export type ControlServerMsg =
+  /** Sent first: a random base64url nonce the agent must sign to prove key ownership. */
+  | { readonly t: 'challenge'; readonly v: number; readonly nonce: string }
+  /** Sent after a valid registration: the derived subdomain + the public base host. */
+  | { readonly t: 'registered'; readonly uuid: string; readonly host: string }
+  /** A new inbound peer connection; the agent must open a `/data` conn with this
+   *  id. `target` is the first path segment of the peer's request (e.g. `mobile`,
+   *  `web`), naming which local service the agent pipes it to. */
+  | { readonly t: 'open'; readonly connId: string; readonly target: string }
+  /** Fatal: the relay is rejecting/closing the control connection. */
+  | { readonly t: 'error'; readonly message: string };
+
+/** Agent → relay, on the control connection. */
+export type ControlClientMsg =
+  /** Register: present the Ed25519 public key + a signature over the challenge nonce. */
+  {
+    readonly t: 'register';
+    readonly v: number;
+    /** base64url(Ed25519 public key). */
+    readonly pubkey: string;
+    /** base64url(Ed25519 signature over the raw nonce bytes). */
+    readonly sig: string;
+  };
+
+/** Agent → relay, the first (text) frame on a `/data` connection. */
+export interface DataAttachMsg {
+  readonly t: 'attach';
+  readonly v: number;
+  /** The single-use capability id the relay sent in the matching `open`. */
+  readonly connId: string;
+}
+
+/** The host the agent dials for control/data (covered by the `*.<host>` cert). */
+export function relayControlHost(baseHost: string): string {
+  return `relay.${baseHost}`;
+}
+
+/** The public URL a peer uses to reach this agent (optionally a routing target). */
+export function publicUrl(uuid: string, baseHost: string, target?: string): string {
+  const base = `https://${uuid}.${baseHost}`;
+  return target ? `${base}/${target}` : base;
+}
+
+export function encodeJson(msg: unknown): string {
+  return JSON.stringify(msg);
+}
+
+export function decodeControlServerMsg(raw: string): ControlServerMsg {
+  const parsed = JSON.parse(raw) as { t?: unknown };
+  if (typeof parsed.t !== 'string') throw new Error('proxy: control message missing type');
+  return parsed as ControlServerMsg;
+}

package/src/provider.test.ts

@@ -0,0 +1,200 @@
+import { once } from 'node:events';
+import { createServer, type AddressInfo, type Server, type Socket } from 'node:net';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  base64urlDecode,
+  base64urlEncode,
+  deriveUuid,
+  publicKeyFromFingerprint,
+  verify,
+} from '@moxxy/e2e';
+import { WebSocketServer, type WebSocket } from 'ws';
+import { createProxyTunnel } from './provider.js';
+import { encodeJson, PROXY_PROTOCOL_VERSION } from './protocol.js';
+
+/**
+ * A minimal in-process stand-in for the relay: a `ws` server that runs the
+ * challenge/register handshake on `/control` and matches `/data` attaches by
+ * connId. `uuidOverride` lets a test play a hostile/buggy relay.
+ */
+class MockRelay {
+  private wss!: WebSocketServer;
+  private control: WebSocket | null = null;
+  private readonly pendingData = new Map<string, (ws: WebSocket) => void>();
+  lastPubkey: Uint8Array | null = null;
+  port = 0;
+
+  constructor(private readonly opts: { uuidOverride?: string } = {}) {}
+
+  async start(): Promise<void> {
+    this.wss = new WebSocketServer({ host: '127.0.0.1', port: 0 });
+    await once(this.wss, 'listening');
+    this.port = (this.wss.address() as AddressInfo).port;
+    this.wss.on('connection', (ws, req) => {
+      if (req.url?.startsWith('/control')) this.onControl(ws);
+      else if (req.url?.startsWith('/data')) this.onData(ws);
+      else ws.close();
+    });
+  }
+
+  get url(): string {
+    return `ws://127.0.0.1:${this.port}`;
+  }
+
+  private onControl(ws: WebSocket): void {
+    this.control = ws;
+    const nonce = new Uint8Array(16).map((_, i) => (i * 31 + 7) & 0xff);
+    ws.on('message', (raw) => {
+      const msg = JSON.parse(raw.toString()) as {
+        t: string;
+        pubkey?: string;
+        sig?: string;
+      };
+      if (msg.t === 'register' && msg.pubkey && msg.sig) {
+        const pubkey = base64urlDecode(msg.pubkey);
+        const sig = base64urlDecode(msg.sig);
+        this.lastPubkey = pubkey;
+        if (!verify(sig, nonce, pubkey)) {
+          ws.send(encodeJson({ t: 'error', message: 'bad signature' }));
+          ws.close();
+          return;
+        }
+        const uuid = this.opts.uuidOverride ?? deriveUuid(pubkey);
+        ws.send(encodeJson({ t: 'registered', uuid, host: 'proxy.test' }));
+      }
+    });
+    ws.send(encodeJson({ t: 'challenge', v: PROXY_PROTOCOL_VERSION, nonce: base64urlEncode(nonce) }));
+  }
+
+  private onData(ws: WebSocket): void {
+    ws.once('message', (raw) => {
+      const msg = JSON.parse(raw.toString()) as { t: string; connId?: string };
+      if (msg.t === 'attach' && msg.connId) {
+        const waiter = this.pendingData.get(msg.connId);
+        this.pendingData.delete(msg.connId);
+        waiter?.(ws);
+      }
+    });
+  }
+
+  /** Signal a new inbound connection and resolve with its attached data WS. */
+  openConn(connId: string, target = ''): Promise<WebSocket> {
+    const attached = new Promise<WebSocket>((resolve) => this.pendingData.set(connId, resolve));
+    this.control?.send(encodeJson({ t: 'open', connId, target }));
+    return attached;
+  }
+
+  async stop(): Promise<void> {
+    this.wss.close();
+    await once(this.wss, 'close').catch(() => undefined);
+  }
+}
+
+/** A loopback TCP echo server standing in for the local bridge/shim. */
+function startEchoServer(): Promise<{ port: number; close: () => Promise<void> }> {
+  return new Promise((resolve) => {
+    const sockets = new Set<Socket>();
+    const server: Server = createServer((socket) => {
+      sockets.add(socket);
+      socket.on('data', (b) => socket.write(b));
+      socket.on('close', () => sockets.delete(socket));
+      socket.on('error', () => sockets.delete(socket));
+    });
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: (server.address() as AddressInfo).port,
+        close: () =>
+          new Promise<void>((res) => {
+            for (const s of sockets) s.destroy();
+            server.close(() => res());
+          }),
+      });
+    });
+  });
+}
+
+describe('proxy provider', () => {
+  let relay: MockRelay;
+  let echo: { port: number; close: () => Promise<void> };
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'proxy-prov-'));
+    echo = await startEchoServer();
+  });
+  afterEach(async () => {
+    await relay?.stop();
+    await echo.close();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('registers via key proof-of-possession and returns the derived url', async () => {
+    relay = new MockRelay();
+    await relay.start();
+    const provider = createProxyTunnel({
+      baseHost: 'proxy.test',
+      controlUrl: relay.url,
+      identityPath: join(dir, 'id.key'),
+    });
+
+    const handle = await provider.open({ port: echo.port, host: '127.0.0.1' });
+    expect(relay.lastPubkey).not.toBeNull();
+    const expectedUuid = deriveUuid(relay.lastPubkey as Uint8Array);
+    expect(handle.url).toBe(`https://${expectedUuid}.proxy.test`);
+    await handle.close();
+  });
+
+  it('pipes inbound bytes to the local port and back', async () => {
+    relay = new MockRelay();
+    await relay.start();
+    const provider = createProxyTunnel({
+      baseHost: 'proxy.test',
+      controlUrl: relay.url,
+      identityPath: join(dir, 'id.key'),
+    });
+    const handle = await provider.open({ port: echo.port, host: '127.0.0.1' });
+
+    const dataWs = await relay.openConn('conn-1');
+    const echoed = once(dataWs, 'message');
+    dataWs.send(Buffer.from('ping-through-tunnel'), { binary: true });
+
+    const [data] = (await echoed) as [Buffer];
+    expect(data.toString()).toBe('ping-through-tunnel');
+    await handle.close();
+  });
+
+  it('rejects when the relay returns the wrong uuid (hostile/buggy relay)', async () => {
+    relay = new MockRelay({ uuidOverride: 'aaaaaaaaaaaaaaaa' });
+    await relay.start();
+    const provider = createProxyTunnel({
+      baseHost: 'proxy.test',
+      controlUrl: relay.url,
+      identityPath: join(dir, 'id.key'),
+    });
+    await expect(provider.open({ port: echo.port, host: '127.0.0.1' })).rejects.toThrow(
+      /expected/,
+    );
+  });
+
+  it('signs the real challenge so a tampered key would fail verification', async () => {
+    relay = new MockRelay();
+    await relay.start();
+    const provider = createProxyTunnel({
+      baseHost: 'proxy.test',
+      controlUrl: relay.url,
+      identityPath: join(dir, 'id.key'),
+    });
+    const handle = await provider.open({ port: echo.port, host: '127.0.0.1' });
+    // The fingerprint embedded in the url derives from the same key the relay verified.
+    const uuid = deriveUuid(relay.lastPubkey as Uint8Array);
+    expect(handle.url).toContain(uuid);
+    // Sanity: the relay-verified pubkey round-trips through the fingerprint codec.
+    expect([...publicKeyFromFingerprint(base64urlEncode(relay.lastPubkey as Uint8Array))]).toEqual([
+      ...(relay.lastPubkey as Uint8Array),
+    ]);
+    await handle.close();
+  });
+});

package/src/provider.ts

@@ -0,0 +1,335 @@
+/**
+ * The `proxy` tunnel provider — a native-Node replacement for the cloudflared/
+ * ngrok subprocess providers.
+ *
+ * Several channels (the mobile bridge, the web preview, the webhooks listener)
+ * can be exposed at once under ONE keypair-derived subdomain: a process-singleton
+ * {@link ProxyHub} owns a single control connection per identity and a
+ * `target → local port` map. Each `open({ port, host, label })` registers a
+ * target and returns `https://<uuid>.<host>/<label>`. For every inbound peer the
+ * relay signals (`open { connId, target }`), the hub opens a `/data` WebSocket
+ * and pipes its raw bytes to that target's port — protocol-agnostic, so the bytes
+ * may be a phone's (E2E-wrapped) WebSocket or a browser's HTTP.
+ *
+ * The control connection self-heals with capped exponential backoff; because the
+ * uuid derives from the (stable) public key, the public URL never changes.
+ */
+import { connect as netConnect, type Socket } from 'node:net';
+import {
+  base64urlDecode,
+  base64urlEncode,
+  deriveUuid,
+  fingerprint,
+  sign,
+  type Identity,
+} from '@moxxy/e2e';
+import { loadOrCreateIdentity } from '@moxxy/e2e/node';
+import { defineTunnelProvider, type TunnelHandle, type TunnelProviderDef } from '@moxxy/sdk';
+import { WebSocket } from 'ws';
+import {
+  CONTROL_PATH,
+  DATA_PATH,
+  DEFAULT_PROXY_HOST,
+  PROXY_PROTOCOL_VERSION,
+  decodeControlServerMsg,
+  encodeJson,
+  publicUrl,
+  relayControlHost,
+  type ControlClientMsg,
+  type DataAttachMsg,
+} from './protocol.js';
+
+export interface ProxyLogger {
+  info?(msg: string, meta?: Record<string, unknown>): void;
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface ProxyTunnelOptions {
+  /** Public base host. Default: `MOXXY_PROXY_HOST` env, else `proxy.moxxy.ai`. */
+  readonly baseHost?: string;
+  /** Override the control/data WS base (e.g. `ws://127.0.0.1:PORT` in tests). */
+  readonly controlUrl?: string;
+  /** Override the identity key path (defaults to `~/.moxxy/proxy-identity.key`). */
+  readonly identityPath?: string;
+  readonly logger?: ProxyLogger;
+}
+
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+
+function resolveBaseHost(opts: ProxyTunnelOptions): string {
+  return (opts.baseHost ?? process.env.MOXXY_PROXY_HOST ?? DEFAULT_PROXY_HOST).trim();
+}
+
+/** `ws://relay.<host>` / `wss://relay.<host>` unless an explicit controlUrl is given. */
+function resolveControlBase(opts: ProxyTunnelOptions, baseHost: string): string {
+  if (opts.controlUrl) return opts.controlUrl.replace(/\/$/, '');
+  return `wss://${relayControlHost(baseHost)}`;
+}
+
+interface TargetEntry {
+  readonly host: string;
+  readonly port: number;
+}
+
+/**
+ * One per (controlBase, identity): owns the control connection and the
+ * `target → port` map, multiplexing every channel's exposure under one uuid.
+ */
+class ProxyHub {
+  private identity: Identity | null = null;
+  private uuid: string | null = null;
+  private control: WebSocket | null = null;
+  private registering: Promise<string> | null = null;
+  private readonly targets = new Map<string, TargetEntry>();
+  private readonly dataConns = new Set<WebSocket>();
+  private readonly localSockets = new Set<Socket>();
+  private closed = false;
+  private reconnectMs = RECONNECT_MIN_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly controlBase: string,
+    private readonly baseHost: string,
+    private readonly identityPath: string | undefined,
+    private readonly logger: ProxyLogger | undefined,
+    private readonly onEmpty: () => void,
+  ) {}
+
+  /** Register a target and return its public URL + a remove() handle. */
+  async addTarget(label: string, host: string, port: number): Promise<TunnelHandle> {
+    const uuid = await this.ensureRegistered();
+    this.targets.set(label, { host, port });
+    this.logger?.info?.('proxy: target added', { uuid, label, port });
+    return {
+      url: publicUrl(uuid, this.baseHost, label),
+      close: () => {
+        this.removeTarget(label);
+        return Promise.resolve();
+      },
+    };
+  }
+
+  private removeTarget(label: string): void {
+    this.targets.delete(label);
+    if (this.targets.size === 0) this.close();
+  }
+
+  /** Connect + register once; later callers reuse the resolved uuid. */
+  private async ensureRegistered(): Promise<string> {
+    if (this.uuid && this.control) return this.uuid;
+    if (this.registering) return this.registering;
+    if (!this.identity) this.identity = await loadOrCreateIdentity(this.identityPath);
+    this.registering = this.connectControl();
+    try {
+      return await this.registering;
+    } finally {
+      this.registering = null;
+    }
+  }
+
+  private connectControl(): Promise<string> {
+    const identity = this.identity as Identity;
+    const expected = deriveUuid(identity.publicKey);
+    return new Promise<string>((resolve, reject) => {
+      let settled = false;
+      const ws = new WebSocket(`${this.controlBase}${CONTROL_PATH}`);
+      this.control = ws;
+
+      ws.on('message', (raw) => {
+        let msg;
+        try {
+          msg = decodeControlServerMsg(raw.toString());
+        } catch {
+          return;
+        }
+        switch (msg.t) {
+          case 'challenge': {
+            const reply: ControlClientMsg = {
+              t: 'register',
+              v: PROXY_PROTOCOL_VERSION,
+              pubkey: base64urlEncode(identity.publicKey),
+              sig: base64urlEncode(sign(base64urlDecode(msg.nonce), identity.secretKey)),
+            };
+            ws.send(encodeJson(reply));
+            return;
+          }
+          case 'registered': {
+            if (msg.uuid !== expected) {
+              // A buggy or hostile relay handed back a uuid our key didn't derive.
+              if (!settled) {
+                settled = true;
+                reject(
+                  new Error(`proxy: relay returned uuid '${msg.uuid}', expected '${expected}'`),
+                );
+              }
+              this.close();
+              return;
+            }
+            this.uuid = msg.uuid;
+            this.reconnectMs = RECONNECT_MIN_MS;
+            if (!settled) {
+              settled = true;
+              resolve(msg.uuid);
+            }
+            return;
+          }
+          case 'open':
+            this.openDataConn(msg.connId, msg.target);
+            return;
+          case 'error':
+            this.logger?.warn?.('proxy: relay error', { message: msg.message });
+            return;
+        }
+      });
+
+      ws.on('close', () => {
+        if (this.control === ws) this.control = null;
+        if (!settled) {
+          settled = true;
+          reject(new Error('proxy: control connection closed before registration'));
+        }
+        this.scheduleReconnect();
+      });
+      ws.on('error', (err) => {
+        this.logger?.warn?.('proxy: control connection error', { err: String(err) });
+        // 'close' follows and drives reconnect / rejection.
+      });
+    });
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed || this.reconnectTimer || this.targets.size === 0) return;
+    const delay = this.reconnectMs;
+    this.reconnectMs = Math.min(this.reconnectMs * 2, RECONNECT_MAX_MS);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.closed) return;
+      this.connectControl()
+        .then(() => this.logger?.info?.('proxy: control reconnected'))
+        .catch(() => {
+          /* 'close' reschedules */
+        });
+    }, delay);
+    this.reconnectTimer.unref?.();
+  }
+
+  /** Pipe one inbound peer (raw bytes over a `/data` WS) to its target's port. */
+  private openDataConn(connId: string, target: string): void {
+    if (this.closed) return;
+    const entry = this.targets.get(target);
+    if (!entry) {
+      this.logger?.warn?.('proxy: open for unknown target; dropping', { target });
+      return; // relay's attach timeout tears down the waiting ingress
+    }
+    const ws = new WebSocket(`${this.controlBase}${DATA_PATH}`);
+    const local = netConnect({ host: entry.host, port: entry.port });
+    this.dataConns.add(ws);
+    this.localSockets.add(local);
+
+    let attached = false;
+    const localOutbox: Uint8Array[] = [];
+    const cleanup = (): void => {
+      this.dataConns.delete(ws);
+      this.localSockets.delete(local);
+      try {
+        if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) ws.close();
+      } catch {
+        /* ignore */
+      }
+      try {
+        local.destroy();
+      } catch {
+        /* ignore */
+      }
+    };
+
+    ws.on('open', () => {
+      const attach: DataAttachMsg = { t: 'attach', v: PROXY_PROTOCOL_VERSION, connId };
+      ws.send(encodeJson(attach));
+      attached = true;
+      for (const chunk of localOutbox.splice(0)) ws.send(chunk, { binary: true });
+    });
+    ws.on('message', (data, isBinary) => {
+      if (isBinary) local.write(data as Buffer);
+    });
+    local.on('data', (buf: Buffer) => {
+      if (attached && ws.readyState === WebSocket.OPEN) ws.send(buf, { binary: true });
+      else localOutbox.push(buf);
+    });
+    ws.on('close', cleanup);
+    ws.on('error', cleanup);
+    local.on('close', cleanup);
+    local.on('error', cleanup);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    for (const ws of this.dataConns) {
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+    }
+    for (const s of this.localSockets) {
+      try {
+        s.destroy();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.dataConns.clear();
+    this.localSockets.clear();
+    this.targets.clear();
+    try {
+      this.control?.close();
+    } catch {
+      /* ignore */
+    }
+    this.control = null;
+    this.onEmpty();
+  }
+}
+
+/** Process-wide hub registry, so all channels share one control conn per identity. */
+const hubs = new Map<string, ProxyHub>();
+
+function hubKey(controlBase: string, identityPath: string | undefined): string {
+  return `${controlBase}${identityPath ?? ''}`;
+}
+
+/** Build a `proxy` tunnel provider (factory form, for config/tests). */
+export function createProxyTunnel(opts: ProxyTunnelOptions = {}): TunnelProviderDef {
+  return defineTunnelProvider({
+    name: 'proxy',
+    open: async ({ port, host, label }): Promise<TunnelHandle> => {
+      const baseHost = resolveBaseHost(opts);
+      const controlBase = resolveControlBase(opts, baseHost);
+      const key = hubKey(controlBase, opts.identityPath);
+      let hub = hubs.get(key);
+      if (!hub) {
+        hub = new ProxyHub(controlBase, baseHost, opts.identityPath, opts.logger, () =>
+          hubs.delete(key),
+        );
+        hubs.set(key, hub);
+      }
+      const handle = await hub.addTarget(label ?? '', host, port);
+      // Surface the pinned fingerprint once per process for the QR/debugging.
+      const identity = await loadOrCreateIdentity(opts.identityPath);
+      opts.logger?.info?.('proxy: exposed', {
+        url: handle.url,
+        fingerprint: fingerprint(identity.publicKey),
+      });
+      return handle;
+    },
+  });
+}
+
+/** The default `proxy` provider (reads `MOXXY_PROXY_HOST` at open time). */
+export const proxyTunnel: TunnelProviderDef = createProxyTunnel();