@netnodeag/kraftwerk 0.70.0 → 0.71.1

package/README.md

@@ -108,6 +108,15 @@ The phone now sees your workspaces, each at `/w/<slug>/` on that address,
 and the workspace menu switches between them. One pairing covers all of them
 (see [Inspector on your phone](#inspector-on-your-phone-paired-devices)).
 
+**From anywhere** (mobile data, another Wi-Fi), with no port opened:
+
+1. `kraftwerk remote on`. The daemon connects to the kraftwerk relay.
+2. `kraftwerk remote pair`, or settings → devices → pair a device, which shows
+   a QR code. Open the link (scan the code) on the phone and tap *Pair*.
+
+The phone runs the same web UI, end to end encrypted through the relay
+(see [From anywhere: the relay](#from-anywhere-the-relay)).
+
 **What to do first in the inspector.** Talk to **Ralv**, the workspace's
 general chat, in plain words: it knows what is in the workspace and helps
 set up the rest. From there:
@@ -239,6 +248,7 @@ kraftwerk daemon                        # one kraftwerk for every open workspace
 kraftwerk daemon install                # start the daemon at login (macOS LaunchAgent); --lan, --port; `daemon uninstall` removes it
 kraftwerk workspaces                    # every workspace on this machine; workspaces start|stop|forget <ref>
 kraftwerk devices                       # paired devices (a phone, another computer); devices pair|revoke
+kraftwerk remote on|off|pair            # reach this machine from anywhere through the relay, end to end encrypted
 kraftwerk projects                      # goal-scoped project folders; projects create|show|link|log|remove
 kraftwerk trash                         # what was deleted; trash restore|purge <id>, trash empty
 kraftwerk journal <agent> ["<entry>"]   # an agent's memory across sessions: print it, add a line (--kind)
@@ -417,6 +427,35 @@ Behind a reverse proxy on the same machine, the proxy must send
 other device. If it cannot, set `KRAFTWERK_UI_REQUIRE_PAIRING=1`, which
 makes every request pair, this machine's own included.
 
+### From anywhere: the relay
+
+`kraftwerk remote on` makes the daemon hold a connection to the kraftwerk
+relay (kraftwerk cloud; `--url` for another one). A paired device reaches the
+machine through it from any network: no port forwarding, no tunnel, and the
+machine needs no public address. `kraftwerk remote pair` (or settings →
+devices → pair a device, with a QR code) gives a link to the cloud's remote
+page. It carries this machine's key and a one-time code in its `#` part,
+which never reaches a server. The phone pairs, then runs the whole web UI
+through the relay. `kraftwerk remote off` disconnects, `kraftwerk remote`
+shows the state, and settings → devices has the same switch.
+
+Everything between the phone and the machine is end to end encrypted:
+
+- X25519 key agreement on the machine's long-lived key plus a fresh key on
+  each side per connection, then AES-256-GCM with counters as nonces.
+- The relay sees which machine, when and how much, never what. It cannot
+  forge or replay a message.
+- The phone checks the machine's key (the fingerprint `kraftwerk remote` shows
+  is on the pairing page), so nobody else can answer in its place.
+- Through the relay, a request counts as a network device's: it needs the
+  device's pairing like on your Wi-Fi, and unpairing ends it at once.
+- One trust remains: the remote page's code comes from the cloud that serves
+  it. A native app will remove that.
+
+The machine's key and its relay secret live in `~/.kraftwerk/relay.json`
+(owner only). The daemon must run (`kraftwerk daemon install`), and the Mac
+must be awake.
+
 For a client of your own, `@netnodeag/kraftwerk/client` takes the token:
 `createClient({ baseUrl, token })`.
 

package/dist/cli/daemon.js

@@ -2,7 +2,9 @@ import chalk from "chalk";
 import { DAEMON_PORT, findDaemon, lastOpenRoots, writeDaemonFile } from "../core/daemon.js";
 import { tildify } from "../core/instances.js";
 import { networkUrls } from "../server/bind.js";
+import { applyRelay } from "../server/relay.js";
 import { startHub } from "../server/server.js";
+import { getPkgVersion } from "../server/version.js";
 import { ensureBuilt, supervise } from "./ui.js";
 import { installDaemon, uninstallDaemon } from "./daemon-login.js";
 /**
@@ -45,6 +47,10 @@ export async function runDaemon(opts) {
         console.log(`  ${chalk.cyan(o.url)} ${chalk.dim(o.name)}${o.aliasPort ? chalk.dim(` · also :${o.aliasPort}`) : ""}`);
     if (!hub.list().length)
         console.log(chalk.dim("  no workspace open yet — `kraftwerk ui` in a workspace folder opens it here"));
+    // The relay (`kraftwerk remote on`): devices reach this machine from anywhere, end to end encrypted.
+    const relay = await applyRelay(hub.port, await getPkgVersion(), (line) => console.log(chalk.dim(line)));
+    if (relay.state !== "off")
+        console.log(`${chalk.green("✔")} Reachable from anywhere through ${chalk.cyan(relay.url ?? "")} ${chalk.dim("(`kraftwerk remote pair` pairs a device)")}`);
     const lan = networkUrls(hub.port);
     if (lan.length)
         console.log(`${chalk.green("✔")} On your network: ${lan.map((u) => chalk.cyan(u)).join(", ")} ${chalk.dim("(add /w/<slug>/; devices pair first)")}`);

package/dist/cli/doctor.js

@@ -11,6 +11,7 @@ import { listDevices } from "../core/devices.js";
 import { slugClashes } from "../core/instances.js";
 import { findDaemon } from "../core/daemon.js";
 import { daemonLoginItem } from "./daemon-login.js";
+import { readRelaySettings } from "../server/relay.js";
 const ICONS = {
     ok: chalk.green("✔"),
     warn: chalk.yellow("⚠"),
@@ -222,6 +223,8 @@ export async function runDoctor(cwd) {
             : daemon
                 ? undefined
                 : "`kraftwerk daemon` serves every workspace in one process");
+    const relay = await readRelaySettings();
+    report("info", relay?.enabled ? `remote access on through ${relay.url}` : "remote access off", relay?.enabled ? (daemon ? "`kraftwerk remote` shows whether the daemon is connected" : "the daemon connects it once it runs") : "`kraftwerk remote on` reaches this machine from anywhere, end to end encrypted");
     // Legacy: what older versions left behind, and what still runs or is installed at one.
     for (const f of await legacyFindings(project, pkg.version))
         report(f.level, f.label, f.detail);

package/dist/cli/kraftwerk.js

@@ -19,6 +19,7 @@ import { registerVibeableCommands } from "./vibeables.js";
 import { registerTrashCommands } from "./trash.js";
 import { registerDevicesCommands } from "./devices.js";
 import { registerDaemonCommand } from "./daemon.js";
+import { registerRemoteCommand } from "./remote.js";
 import { registerJournalCommands } from "./journal.js";
 import { applyDotenv } from "../dotenv.js";
 import { resolveWorkspace } from "../config.js";
@@ -295,6 +296,7 @@ registerVibeableCommands(program);
 registerTrashCommands(program);
 registerDevicesCommands(program);
 registerDaemonCommand(program);
+registerRemoteCommand(program);
 registerJournalCommands(program);
 program
     .command("ui")

package/dist/cli/remote.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerRemoteCommand(program: Command): void;

package/dist/cli/remote.js

@@ -0,0 +1,89 @@
+import chalk from "chalk";
+import { createPairCode, PAIR_CODE_TTL_MS } from "../core/devices.js";
+import { findDaemon } from "../core/daemon.js";
+import { keyFingerprint, readRelaySettings, relayEndpoint, remoteLink, setRelay } from "../server/relay.js";
+/** Ask the running daemon (this machine: local trust). */
+async function daemonRelay(method, body) {
+    const d = await findDaemon();
+    if (!d)
+        return null;
+    const r = await fetch(`http://127.0.0.1:${d.port}/api/devices/relay`, {
+        method,
+        headers: body ? { "content-type": "application/json" } : {},
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(20_000),
+    });
+    return r.ok ? (await r.json()) : null;
+}
+const describe = (s) => {
+    if (!s)
+        return chalk.yellow("the daemon is not running — `kraftwerk daemon` (or `kraftwerk daemon install`) connects it");
+    if (s.state === "connected")
+        return `${chalk.green("connected")}${s.clients ? chalk.dim(` · ${s.clients} device${s.clients === 1 ? "" : "s"} connected now`) : ""}`;
+    if (s.state === "connecting")
+        return chalk.yellow("connecting…");
+    if (s.state === "error")
+        return chalk.red(`not connected: ${s.error ?? "unknown error"}`);
+    return chalk.dim("off");
+};
+/** Wait briefly for the daemon's link to come up, so `remote on` says whether it worked. */
+async function settle() {
+    let s = await daemonRelay("GET").catch(() => null);
+    for (let i = 0; i < 20 && s?.state === "connecting"; i++) {
+        await new Promise((r) => setTimeout(r, 250));
+        s = await daemonRelay("GET").catch(() => null);
+    }
+    return s;
+}
+export function registerRemoteCommand(program) {
+    const remote = program
+        .command("remote")
+        .description("Reach this machine from anywhere through the relay, end to end encrypted: on, off, pair a device")
+        .action(async () => {
+        const s = await readRelaySettings();
+        if (!s?.enabled)
+            return void console.log(`${chalk.dim("Remote access is off.")} ${chalk.dim("`kraftwerk remote on` turns it on.")}`);
+        console.log(`Remote access ${chalk.bold("on")} through ${chalk.cyan(s.url)} ${chalk.dim(`(machine key ${keyFingerprint(s.publicKey)})`)}`);
+        console.log(`  ${describe(await daemonRelay("GET").catch(() => null))}`);
+    });
+    remote
+        .command("on")
+        .description("Turn remote access on: the daemon connects to the relay")
+        .option("--url <url>", "The cloud whose relay to use (default: the kraftwerk cloud)")
+        .action(async (opts) => {
+        if (opts.url && !/^https?:\/\//.test(opts.url)) {
+            console.error(chalk.red("✖ --url is the cloud's address, e.g. https://srv.kraftwerk-cloud.netnode.cloud"));
+            process.exit(2);
+        }
+        const s = await setRelay(true, opts.url);
+        // The daemon reads the file again and connects; without one running, it does when it starts.
+        await daemonRelay("POST", { enabled: true, ...(opts.url ? { url: opts.url } : {}) }).catch(() => null);
+        const status = await settle();
+        console.log(`${chalk.green("✔")} remote access on through ${chalk.cyan(s.url)} ${chalk.dim(`(${relayEndpoint(s.url, "server")})`)}`);
+        console.log(`  ${describe(status)}`);
+        console.log(chalk.dim("  `kraftwerk remote pair` makes a link that pairs a device"));
+    });
+    remote
+        .command("off")
+        .description("Turn remote access off: the daemon leaves the relay")
+        .action(async () => {
+        await setRelay(false);
+        await daemonRelay("POST", { enabled: false }).catch(() => null);
+        console.log(`${chalk.green("✔")} remote access off ${chalk.dim("(paired devices keep their pairing; `kraftwerk devices revoke` unpairs one)")}`);
+    });
+    remote
+        .command("pair")
+        .description(`A link that pairs a device from anywhere, valid ${PAIR_CODE_TTL_MS / 60_000} minutes, once`)
+        .action(async () => {
+        const s = await readRelaySettings();
+        if (!s?.enabled) {
+            console.error(chalk.red("✖ remote access is off — `kraftwerk remote on` first"));
+            process.exit(1);
+        }
+        const { code } = await createPairCode();
+        console.log(`${chalk.green("✔")} open this on the device ${chalk.dim(`— valid ${PAIR_CODE_TTL_MS / 60_000} minutes, once`)}`);
+        console.log(`  ${chalk.cyan(remoteLink(s.url, s.publicKey, code))}`);
+        console.log(chalk.dim(`  The link carries this machine's key and the code ${code}; treat it like a password.`));
+        console.log(chalk.dim("  Or scan its QR code under Settings → Devices in the web UI."));
+    });
+}

package/dist/client/relay.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The relay: reaching a machine's kraftwerk from anywhere, end to end
+ * encrypted. The daemon holds an outgoing socket to a relay (kraftwerk
+ * cloud); a client — a phone's browser, an app — opens a socket to the same
+ * relay naming the machine, and the relay pipes the two together. The relay
+ * sees who talks to which machine, when, and how much; never what.
+ *
+ * This module is both ends of the encryption and the client's half of the
+ * tunnel. It runs wherever WebCrypto does (Node 20+, browsers, service
+ * workers), so the daemon, the CLI and the phone share one implementation.
+ *
+ * Keys. The daemon has a long-lived X25519 key; its public half is the
+ * pairing link's trust anchor (`#k=…`), and the relay knows the machine by
+ * its hash (`relayId`). Each connection:
+ *
+ *   client → daemon   {t:"hello", v:1, key: e_c}                  plaintext
+ *   daemon → client   {t:"ready", key: e_d, box: seal("ready")}   plaintext + sealed proof
+ *
+ * Both derive two AES-256-GCM keys (one per direction) with HKDF-SHA256 from
+ * DH(e_c, S_d) ‖ DH(e_c, e_d), salted with e_c ‖ S_d ‖ e_d. Only the holder
+ * of S_d can open the client's traffic or produce "ready" (the client knows
+ * it reached the right machine); e_d makes every connection's keys fresh, so
+ * a recorded session cannot be replayed to the daemon. Nonces are message
+ * counters per direction, so a dropped, repeated or reordered message
+ * breaks the channel instead of slipping through.
+ *
+ * The client is not authenticated by the handshake: inside the channel it
+ * presents a paired device's token like any network caller, and the daemon
+ * applies the same trust rules (src/server/trust.ts). Anyone holding the
+ * pairing link still needs a pairing code or a token.
+ */
+export declare const RELAY_PROTOCOL = 1;
+export declare function toBase64(bytes: Uint8Array): string;
+export declare function fromBase64(text: string): Uint8Array;
+export declare const toBase64Url: (bytes: Uint8Array) => string;
+export declare const fromBase64Url: (text: string) => Uint8Array;
+export interface KeyPair {
+    privateKey: CryptoKey;
+    /** The raw 32-byte public key. */
+    publicKey: Uint8Array;
+}
+export declare function generateKeyPair(): Promise<KeyPair>;
+/** A key pair as JSON (the private half as a JWK) — what the daemon keeps on disk. */
+export declare function exportKeyPair(pair: KeyPair): Promise<{
+    publicKey: string;
+    privateKey: JsonWebKey;
+}>;
+export declare function importKeyPair(saved: {
+    publicKey: string;
+    privateKey: JsonWebKey;
+}): Promise<KeyPair>;
+/** How the relay knows a machine: the hash of its public key, so the pairing link alone finds it. */
+export declare function relayId(publicKey: Uint8Array): Promise<string>;
+/** One connection's two directions: seal what goes out, open what comes in, each in strict order. */
+export interface Channel {
+    seal(plaintext: string): Promise<string>;
+    open(sealed: string): Promise<string>;
+}
+export interface Hello {
+    t: "hello";
+    v: number;
+    key: string;
+}
+export interface Ready {
+    t: "ready";
+    key: string;
+    box: string;
+}
+/** The client's side: a hello to send, and `finish` to check the daemon's ready and get the channel. */
+export declare function clientHandshake(daemonPublicKey: Uint8Array): Promise<{
+    hello: Hello;
+    finish(ready: Ready): Promise<Channel>;
+}>;
+/** The daemon's side: answer a client's hello with a ready, and get the channel. */
+export declare function daemonHandshake(own: KeyPair, hello: Hello): Promise<{
+    ready: Ready;
+    channel: Channel;
+}>;
+/**
+ * Inside the channel, the client sends requests and the daemon answers them
+ * from its own server, streaming the body (event streams stay open):
+ *
+ *   → {t:"req", id, method, url, headers, body?}     body base64
+ *   ← {t:"res", id, status, headers}
+ *   ← {t:"data", id, chunk}                           base64, any number
+ *   ← {t:"end", id} | {t:"fail", id, error}
+ *   → {t:"abort", id}                                 the client stopped reading
+ */
+export type TunnelToDaemon = {
+    t: "req";
+    id: number;
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+} | {
+    t: "abort";
+    id: number;
+};
+export type TunnelToClient = {
+    t: "res";
+    id: number;
+    status: number;
+    headers: Record<string, string>;
+} | {
+    t: "data";
+    id: number;
+    chunk: string;
+} | {
+    t: "end";
+    id: number;
+} | {
+    t: "fail";
+    id: number;
+    error: string;
+};
+/** The socket the client talks over — the browser's WebSocket and Node's global one both fit. */
+export interface RelaySocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "message", fn: (ev: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", fn: (ev: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: "open" | "error", fn: () => void): void;
+    readonly readyState: number;
+}
+export interface Tunnel {
+    /** `fetch` through the machine: paths are the daemon's (`/w/<slug>/api/…`); hand it to createClient({fetch}). */
+    fetch: typeof fetch;
+    close(): void;
+    /** Resolves when the connection ends, with why. */
+    readonly closed: Promise<string>;
+}
+export interface ConnectOptions {
+    /** The relay's client endpoint, e.g. wss://srv.kraftwerk-cloud.netnode.cloud/api/relay/client */
+    relayUrl: string;
+    /** The machine's public key, from its pairing link. */
+    publicKey: Uint8Array;
+    /** Opens the socket (default: the global WebSocket). */
+    connect?: (url: string) => RelaySocket;
+    /** Abort the handshake after this long (default 15 s). */
+    timeoutMs?: number;
+}
+/** Connect to a machine through the relay: the handshake, then a `fetch` that goes through it. */
+export declare function connectTunnel(opts: ConnectOptions): Promise<Tunnel>;

package/dist/client/relay.js

@@ -0,0 +1,318 @@
+/**
+ * The relay: reaching a machine's kraftwerk from anywhere, end to end
+ * encrypted. The daemon holds an outgoing socket to a relay (kraftwerk
+ * cloud); a client — a phone's browser, an app — opens a socket to the same
+ * relay naming the machine, and the relay pipes the two together. The relay
+ * sees who talks to which machine, when, and how much; never what.
+ *
+ * This module is both ends of the encryption and the client's half of the
+ * tunnel. It runs wherever WebCrypto does (Node 20+, browsers, service
+ * workers), so the daemon, the CLI and the phone share one implementation.
+ *
+ * Keys. The daemon has a long-lived X25519 key; its public half is the
+ * pairing link's trust anchor (`#k=…`), and the relay knows the machine by
+ * its hash (`relayId`). Each connection:
+ *
+ *   client → daemon   {t:"hello", v:1, key: e_c}                  plaintext
+ *   daemon → client   {t:"ready", key: e_d, box: seal("ready")}   plaintext + sealed proof
+ *
+ * Both derive two AES-256-GCM keys (one per direction) with HKDF-SHA256 from
+ * DH(e_c, S_d) ‖ DH(e_c, e_d), salted with e_c ‖ S_d ‖ e_d. Only the holder
+ * of S_d can open the client's traffic or produce "ready" (the client knows
+ * it reached the right machine); e_d makes every connection's keys fresh, so
+ * a recorded session cannot be replayed to the daemon. Nonces are message
+ * counters per direction, so a dropped, repeated or reordered message
+ * breaks the channel instead of slipping through.
+ *
+ * The client is not authenticated by the handshake: inside the channel it
+ * presents a paired device's token like any network caller, and the daemon
+ * applies the same trust rules (src/server/trust.ts). Anyone holding the
+ * pairing link still needs a pairing code or a token.
+ */
+const subtle = () => globalThis.crypto.subtle;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+export const RELAY_PROTOCOL = 1;
+/* ---------- encoding ---------- */
+export function toBase64(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+export function fromBase64(text) {
+    const s = atob(text);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+export const toBase64Url = (bytes) => toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+export const fromBase64Url = (text) => fromBase64(text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4));
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+};
+export async function generateKeyPair() {
+    const pair = (await subtle().generateKey({ name: "X25519" }, true, ["deriveBits"]));
+    return { privateKey: pair.privateKey, publicKey: new Uint8Array(await subtle().exportKey("raw", pair.publicKey)) };
+}
+/** A key pair as JSON (the private half as a JWK) — what the daemon keeps on disk. */
+export async function exportKeyPair(pair) {
+    return { publicKey: toBase64Url(pair.publicKey), privateKey: await subtle().exportKey("jwk", pair.privateKey) };
+}
+export async function importKeyPair(saved) {
+    const privateKey = await subtle().importKey("jwk", saved.privateKey, { name: "X25519" }, true, ["deriveBits"]);
+    return { privateKey, publicKey: fromBase64Url(saved.publicKey) };
+}
+const importPublic = (raw) => {
+    if (raw.length !== 32)
+        throw new Error("invalid public key");
+    return subtle().importKey("raw", raw, { name: "X25519" }, false, []);
+};
+/** X25519; WebCrypto refuses a low-order peer key (an all-zero secret). */
+const dh = async (own, peer) => new Uint8Array(await subtle().deriveBits({ name: "X25519", public: await importPublic(peer) }, own, 256));
+/** How the relay knows a machine: the hash of its public key, so the pairing link alone finds it. */
+export async function relayId(publicKey) {
+    const digest = new Uint8Array(await subtle().digest("SHA-256", publicKey));
+    return toBase64Url(digest.subarray(0, 16));
+}
+async function channelKeys(ikm, salt) {
+    const base = await subtle().importKey("raw", ikm, "HKDF", false, ["deriveKey"]);
+    const derive = (info) => subtle().deriveKey({ name: "HKDF", hash: "SHA-256", salt: salt, info: enc.encode(`kraftwerk-relay-v1 ${info}`) }, base, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+    return { toDaemon: await derive("to-daemon"), toClient: await derive("to-client") };
+}
+const nonce = (n) => {
+    const iv = new Uint8Array(12);
+    new DataView(iv.buffer).setBigUint64(4, BigInt(n));
+    return iv;
+};
+function makeChannel(out, inn) {
+    let sent = 0;
+    let received = 0;
+    // Sealing is async: queue it so messages keep their counter order however callers interleave.
+    let sealing = Promise.resolve();
+    let opening = Promise.resolve();
+    return {
+        seal(plaintext) {
+            const run = sealing.then(async () => {
+                const iv = nonce(sent++);
+                return toBase64(new Uint8Array(await subtle().encrypt({ name: "AES-GCM", iv: iv }, out, enc.encode(plaintext))));
+            });
+            sealing = run.catch(() => { });
+            return run;
+        },
+        open(sealed) {
+            const run = opening.then(async () => {
+                const iv = nonce(received++);
+                try {
+                    return dec.decode(await subtle().decrypt({ name: "AES-GCM", iv: iv }, inn, fromBase64(sealed)));
+                }
+                catch {
+                    throw new Error("relay message failed to decrypt — tampered, replayed or out of order");
+                }
+            });
+            opening = run.catch(() => { });
+            return run;
+        },
+    };
+}
+/** The client's side: a hello to send, and `finish` to check the daemon's ready and get the channel. */
+export async function clientHandshake(daemonPublicKey) {
+    const eph = await generateKeyPair();
+    return {
+        hello: { t: "hello", v: RELAY_PROTOCOL, key: toBase64(eph.publicKey) },
+        async finish(ready) {
+            if (ready?.t !== "ready" || typeof ready.key !== "string" || typeof ready.box !== "string")
+                throw new Error("not a relay handshake answer");
+            const daemonEph = fromBase64(ready.key);
+            const ikm = concat(await dh(eph.privateKey, daemonPublicKey), await dh(eph.privateKey, daemonEph));
+            const keys = await channelKeys(ikm, concat(eph.publicKey, daemonPublicKey, daemonEph));
+            const channel = makeChannel(keys.toDaemon, keys.toClient);
+            if ((await channel.open(ready.box).catch(() => "")) !== "ready")
+                throw new Error("the machine did not prove its key — wrong pairing link, or not the machine you paired with");
+            return channel;
+        },
+    };
+}
+/** The daemon's side: answer a client's hello with a ready, and get the channel. */
+export async function daemonHandshake(own, hello) {
+    if (hello?.t !== "hello" || typeof hello.key !== "string")
+        throw new Error("not a relay hello");
+    if (hello.v !== RELAY_PROTOCOL)
+        throw new Error(`relay protocol ${hello.v} is not supported (this kraftwerk speaks ${RELAY_PROTOCOL})`);
+    const clientEph = fromBase64(hello.key);
+    const eph = await generateKeyPair();
+    const ikm = concat(await dh(own.privateKey, clientEph), await dh(eph.privateKey, clientEph));
+    const keys = await channelKeys(ikm, concat(clientEph, own.publicKey, eph.publicKey));
+    const channel = makeChannel(keys.toClient, keys.toDaemon);
+    return { ready: { t: "ready", key: toBase64(eph.publicKey), box: await channel.seal("ready") }, channel };
+}
+const OPEN = 1;
+/** Connect to a machine through the relay: the handshake, then a `fetch` that goes through it. */
+export async function connectTunnel(opts) {
+    const id = await relayId(opts.publicKey);
+    const url = `${opts.relayUrl}${opts.relayUrl.includes("?") ? "&" : "?"}id=${encodeURIComponent(id)}`;
+    // The keys first: once the socket exists, its events may fire at any await — the listeners below must already be there.
+    const hs = await clientHandshake(opts.publicKey);
+    const ws = opts.connect ? opts.connect(url) : new WebSocket(url);
+    let channel = null;
+    let closedWhy = "";
+    let resolveClosed;
+    const closed = new Promise((r) => (resolveClosed = r));
+    const pending = new Map();
+    let nextId = 1;
+    const finish = (why) => {
+        if (closedWhy)
+            return;
+        closedWhy = why || "the connection closed";
+        for (const p of pending.values()) {
+            p.reject(new Error(closedWhy));
+            try {
+                p.stream?.error(new Error(closedWhy));
+            }
+            catch { }
+        }
+        pending.clear();
+        resolveClosed(closedWhy);
+    };
+    const ready = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error("the machine did not answer through the relay"));
+            ws.close();
+        }, opts.timeoutMs ?? 15_000);
+        ws.addEventListener("open", () => ws.send(JSON.stringify(hs.hello)));
+        ws.addEventListener("close", (ev) => {
+            clearTimeout(timer);
+            const why = ev.reason || (ev.code === 4404 ? "the machine is not connected to the relay" : "the relay closed the connection");
+            reject(new Error(why));
+            finish(why);
+        });
+        ws.addEventListener("error", () => { });
+        let first = true;
+        // Messages are opened one after another (the channel counts them); a promise chain keeps the order.
+        let queue = Promise.resolve();
+        ws.addEventListener("message", (ev) => {
+            const text = typeof ev.data === "string" ? ev.data : dec.decode(ev.data);
+            queue = queue.then(async () => {
+                if (first) {
+                    first = false;
+                    try {
+                        channel = await hs.finish(JSON.parse(text));
+                        clearTimeout(timer);
+                        resolve(channel);
+                    }
+                    catch (err) {
+                        clearTimeout(timer);
+                        reject(err);
+                        ws.close(4400, "handshake failed");
+                    }
+                    return;
+                }
+                if (!channel)
+                    return;
+                let msg;
+                try {
+                    msg = JSON.parse(await channel.open(text));
+                }
+                catch (err) {
+                    ws.close(4400, "bad message");
+                    finish(err.message);
+                    return;
+                }
+                receive(msg);
+            });
+        });
+    });
+    const receive = (msg) => {
+        const p = pending.get(msg.id);
+        if (!p)
+            return;
+        if (msg.t === "res") {
+            const body = new ReadableStream({
+                start: (c) => {
+                    p.stream = c;
+                },
+                cancel: () => {
+                    pending.delete(msg.id);
+                    void send({ t: "abort", id: msg.id });
+                },
+            });
+            const status = msg.status;
+            // A Response cannot carry a body for these; the stream stays unused.
+            const noBody = status === 204 || status === 304 || (status >= 100 && status < 200);
+            p.resolve(new Response(noBody ? null : body, { status, headers: msg.headers }));
+        }
+        else if (msg.t === "data") {
+            try {
+                p.stream?.enqueue(fromBase64(msg.chunk));
+            }
+            catch { }
+        }
+        else if (msg.t === "end") {
+            pending.delete(msg.id);
+            try {
+                p.stream?.close();
+            }
+            catch { }
+        }
+        else if (msg.t === "fail") {
+            pending.delete(msg.id);
+            const err = new Error(msg.error);
+            p.reject(err);
+            try {
+                p.stream?.error(err);
+            }
+            catch { }
+        }
+    };
+    const send = async (msg) => {
+        if (!channel || ws.readyState !== OPEN)
+            return;
+        ws.send(await channel.seal(JSON.stringify(msg)));
+    };
+    await ready;
+    const tunnelFetch = async (input, init) => {
+        if (closedWhy)
+            throw new Error(closedWhy);
+        const req = new Request(typeof input === "string" && input.startsWith("/") ? `http://relay${input}` : input, init);
+        const u = new URL(req.url);
+        const headers = {};
+        req.headers.forEach((v, k) => (headers[k] = v));
+        const body = req.method === "GET" || req.method === "HEAD" ? undefined : new Uint8Array(await req.arrayBuffer());
+        const id = nextId++;
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject, signal: req.signal });
+            req.signal?.addEventListener("abort", () => {
+                const p = pending.get(id);
+                if (!p)
+                    return;
+                pending.delete(id);
+                const err = new DOMException("aborted", "AbortError");
+                p.reject(err);
+                try {
+                    p.stream?.error(err);
+                }
+                catch { }
+                void send({ t: "abort", id });
+            });
+            send({ t: "req", id, method: req.method, url: u.pathname + u.search, headers, ...(body?.length ? { body: toBase64(body) } : {}) }).catch((err) => {
+                pending.delete(id);
+                reject(err);
+            });
+        });
+    };
+    return {
+        fetch: tunnelFetch,
+        close: () => {
+            ws.close(1000, "bye");
+            finish("closed");
+        },
+        closed,
+    };
+}