@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/control-plane-tasks.js

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Control-plane work-queue poller (E2/E4 node side).
+ *
+ * The hosted control plane is the inbound front door: a GitHub issue webhook
+ * (E2) or a Slack command (E4) enqueues a WORK ITEM there. The node dials
+ * outbound only (invariant #4), so the control plane notifies it over the
+ * already-open relay socket when possible and it falls back to POLLING the
+ * control plane for pending items. It claims one (atomically — only one node
+ * wins), runs it on its own machine with its own token, then marks it done.
+ * Content never reaches the control plane; only the branch + PR go to GitHub.
+ *
+ * This complements the legacy direct GitHub polling in github-tasks.ts: that
+ * path is for a single self-hosted repo; this path lets the hosted service route
+ * issues (and Slack) across many repos/nodes. Pure HTTP + claim/loop logic lives
+ * here; the actual run is injected so the daemon keeps the agent wiring.
+ */
+/**
+ * Build config from the relay enrollment + node label. Returns null if disabled.
+ *
+ * `nodeName` is the node's own registered name (identity.name). The control plane
+ * routes targeted work to `bivy/<name>` — a `bivy/<node>` label, an `@bot on
+ * <node>` directive, or the account's default-node setting all resolve to the
+ * node's *name*. So the node automatically serves `bivy/<its-name>` without any
+ * manual `--node-label`/`BIVY_NODE_LABEL`; that env var stays supported as an
+ * extra/override for serving a different label.
+ */
+export function resolveControlPlaneTaskConfig(relay, env = process.env, nodeName) {
+    // Enrollment opts the node into the hosted work queue. This cannot be gated
+    // on GitHub configuration: Slack, signed webhooks, schedules, and manually
+    // dispatched runs use the same queue and may be the only integration enabled.
+    if (!relay?.controlPlaneUrl || !relay.enrollmentToken)
+        return null;
+    const base = (env.BIVY_GITHUB_LABEL?.trim() || "bivy");
+    // The label the node serves for its own name, e.g. name "hetzner" → "bivy/hetzner".
+    const nameLabel = nodeName?.trim() ? `${base}/${nodeName.trim()}` : undefined;
+    // BIVY_NODE_LABEL may be a full label ("bivy/x") or a bare suffix ("x").
+    const rawEnvLabel = env.BIVY_NODE_LABEL?.trim();
+    const envLabel = rawEnvLabel ? (rawEnvLabel.includes("/") ? rawEnvLabel : `${base}/${rawEnvLabel}`) : undefined;
+    const labels = Array.from(new Set([base, nameLabel, envLabel].filter(Boolean)));
+    return {
+        controlPlaneUrl: relay.controlPlaneUrl.replace(/\/$/, ""),
+        enrollmentToken: relay.enrollmentToken,
+        labels: labels.length ? labels : ["bivy"],
+        pollMs: Math.max(Number(env.BIVY_GITHUB_POLL_MS) || 60_000, 10_000),
+    };
+}
+async function cp(cfg, method, path) {
+    return fetch(`${cfg.controlPlaneUrl}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${cfg.enrollmentToken}` },
+    });
+}
+async function transitionWork(cfg, id, action) {
+    await cp(cfg, "POST", `/node/work/${encodeURIComponent(id)}/${action}`).catch(() => { });
+}
+export async function fetchPendingWork(cfg) {
+    const res = await cp(cfg, "GET", `/node/work?labels=${encodeURIComponent(cfg.labels.join(","))}`);
+    if (!res.ok)
+        return [];
+    const data = (await res.json().catch(() => ({})));
+    return Array.isArray(data.items) ? data.items : [];
+}
+/** Atomically claim an item. Returns true only if THIS node won the claim. */
+export async function claimWork(cfg, id) {
+    const res = await cp(cfg, "POST", `/node/work/${encodeURIComponent(id)}/claim`);
+    return res.ok;
+}
+export async function completeWork(cfg, id) {
+    await transitionWork(cfg, id, "complete");
+}
+export async function failWork(cfg, id) {
+    await transitionWork(cfg, id, "fail");
+}
+/** Park a run for a human (dormant `needs_attention` status). Best-effort. */
+export async function needsAttentionWork(cfg, id) {
+    await transitionWork(cfg, id, "needs-attention");
+}
+/** Report privacy-safe run evidence (issue #153) — routing reason, output refs
+ *  (branch/PR/checkpoint/commit/...), check results, and new timeline events.
+ *  Best-effort: a dropped report loses one evidence update, never the run
+ *  itself, so failures here are swallowed like the other transition calls. */
+export async function reportEvidence(cfg, id, patch) {
+    await fetch(`${cfg.controlPlaneUrl}/node/work/${encodeURIComponent(id)}/evidence`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${cfg.enrollmentToken}`, "content-type": "application/json" },
+        body: JSON.stringify(patch),
+    }).catch(() => { });
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class ControlPlaneTaskPoller {
+    cfg;
+    runItem;
+    maxConcurrent;
+    timer;
+    inFlight = new Set();
+    policy;
+    sleep;
+    constructor(cfg, runItem, 
+    /** Node's cap on concurrently-running queue sessions (0/undefined = unlimited).
+     *  Read fresh each tick so the Settings → Nodes value takes effect live. */
+    maxConcurrent, options = {}) {
+        this.cfg = cfg;
+        this.runItem = runItem;
+        this.maxConcurrent = maxConcurrent;
+        this.policy = options.policy;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    start() {
+        void this.tick();
+        this.timer = setInterval(() => void this.tick(), this.cfg.pollMs);
+        this.timer.unref?.();
+        console.log(`[control-plane-tasks] watching hosted queue for labels [${this.cfg.labels.join(", ")}] (relay push + ${Math.round(this.cfg.pollMs / 1000)}s fallback poll)`);
+    }
+    /** Trigger an immediate fetch after a relay push says work may be available. */
+    poke() {
+        void this.tick();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+    }
+    async tick() {
+        let items;
+        try {
+            items = await fetchPendingWork(this.cfg);
+        }
+        catch {
+            return;
+        }
+        const max = this.maxConcurrent?.() ?? 0;
+        const running = [];
+        for (const item of items) {
+            if (this.inFlight.has(item.id))
+                continue;
+            // Honor the node's concurrency cap: leave the rest in the queue for a later
+            // tick (or an idle node) to claim when a slot frees.
+            if (max > 0 && this.inFlight.size >= max)
+                break;
+            // Reserve the slot synchronously (no `await` since the last check) so a
+            // later item considered in this same loop sees an accurate
+            // `inFlight.size` — then kick it off without awaiting it here (only
+            // collecting the promise to await below). Awaiting an item to completion
+            // before starting the next one meant the cap was never really exercised
+            // within a single tick: items ran one at a time regardless of `max`, and
+            // only overlapping `setInterval` ticks happened to run more than one
+            // concurrently.
+            this.inFlight.add(item.id);
+            running.push(this.runOne(item));
+        }
+        await Promise.all(running);
+    }
+    async runOne(item) {
+        try {
+            // Claim first so only one node runs it; skip if another node won (no
+            // claim → not ours → don't run or complete it).
+            if (!(await claimWork(this.cfg, item.id)))
+                return;
+            const report = (patch) => reportEvidence(this.cfg, item.id, patch);
+            await transitionWork(this.cfg, item.id, "running");
+            console.log(`[control-plane-tasks] running ${item.source} item ${item.id}: ${item.title}`);
+            // routingReason is a coarse baseline — a manual "Run…" override picked
+            // this agent/model explicitly; otherwise it's whatever the queue label
+            // routed to. runWorkItem/runIssueTask may layer a more specific reason
+            // (e.g. a fallback after an error) on top via the same `report` hook.
+            await report({ routingReason: item.runtimeId || item.model ? "manual override" : "queue label" });
+            await this.runWithPolicy(item, report);
+        }
+        finally {
+            this.inFlight.delete(item.id);
+        }
+    }
+    /**
+     * Run one item under the run policy: on failure, classify → decide → retry /
+     * reroute (rewrite routing for the next attempt) / park (needs_attention) /
+     * give_up (fail). Reroute happens only at ATTEMPT BOUNDARIES — the failed
+     * attempt is fully unwound before the next one starts — so there's no partial-
+     * work/idempotency hazard. Every decision is recorded as a bounded, privacy-
+     * safe evidence event. With no policy injected this is the historical path:
+     * one attempt, any throw fails the run.
+     */
+    async runWithPolicy(item, report) {
+        let current = item;
+        let attempt = 1;
+        let rerouteCount = 0;
+        for (;;) {
+            try {
+                await this.runItem(current, report);
+                await completeWork(this.cfg, item.id);
+                return;
+            }
+            catch (error) {
+                const decision = this.policy?.decide({
+                    routing: { runtimeId: current.runtimeId, model: current.model },
+                    error,
+                    attempt,
+                    rerouteCount,
+                }) ?? { action: "give_up", condition: "unknown" };
+                if (decision.action === "retry" || decision.action === "reroute") {
+                    attempt += 1;
+                    const kind = decision.action === "retry" ? "retry" : "fallback";
+                    console.warn(`[control-plane-tasks] item ${item.id} ${kind} (${decision.condition}): ${decision.summary}`);
+                    await report({
+                        events: [
+                            {
+                                at: new Date().toISOString(),
+                                kind,
+                                summary: decision.summary,
+                                attempt,
+                                ...(decision.action === "reroute" ? { ref: decision.ref } : {}),
+                            },
+                        ],
+                    });
+                    if (decision.action === "reroute") {
+                        current = { ...current, runtimeId: decision.routing.runtimeId, model: decision.routing.model };
+                        rerouteCount = decision.rerouteCount;
+                        await report({ routingReason: `fallback: ${decision.ref}` });
+                    }
+                    if (decision.delayMs > 0)
+                        await this.sleep(decision.delayMs);
+                    continue;
+                }
+                if (decision.action === "park") {
+                    console.warn(`[control-plane-tasks] item ${item.id} needs attention (${decision.condition}): ${decision.summary}`);
+                    await report({ events: [{ at: new Date().toISOString(), kind: "needs_attention", summary: decision.summary }] });
+                    await needsAttentionWork(this.cfg, item.id);
+                    return;
+                }
+                console.warn(`[control-plane-tasks] item ${item.id} failed:`, error);
+                await failWork(this.cfg, item.id);
+                return;
+            }
+        }
+    }
+}

package/dist/data-dir.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Single source of truth for the Bivy data directory.
+//
+// Several modules independently derived this default and DISAGREED: the daemon
+// (src/server.ts) used <install>/.bivy, the git credential helper and the secret
+// vault fell back to ~/.bivy, and the agent service to <cwd>/.bivy. A process
+// that never sets BIVY_DATA_DIR explicitly could therefore point its git
+// credential helper and its secret vault at different roots — the drift behind
+// issue #1's test-isolation failure. Everyone resolves the data dir HERE now.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// This module ships at src/ (dist/ in a release build), so its parent directory
+// is the package root — the same <install>/.bivy the daemon uses. Because the
+// path is resolved relative to THIS file, every importer agrees regardless of
+// its own location (e.g. src/runtime/*) or the process's cwd.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+/**
+ * The Bivy data directory: `BIVY_DATA_DIR` if set (resolved to an absolute path),
+ * otherwise `<install>/.bivy`. This is the one function that decides the default.
+ */
+export function defaultDataDir() {
+    const env = process.env.BIVY_DATA_DIR;
+    return env ? path.resolve(env) : path.join(packageRoot, ".bivy");
+}

package/dist/device-registry.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { generatePairingKeypair, generateRoomKey, generatePairSecret, deriveWrapKey, verifyPairingProof, wrapRoomKey, } from "./pairing-crypto.js";
+import { seal, open } from "./e2e.js";
+const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
+export class PairingStore {
+    filePath;
+    data;
+    pendingSecrets = new Map(); // secret -> expiry (ms)
+    constructor(filePath, data) {
+        this.filePath = filePath;
+        this.data = data;
+    }
+    /**
+     * Load (or create) the pairing state. A fresh state gets a randomly generated
+     * room key; devices receive it (and every later rotation) over the X25519
+     * pairing handshake, so there is no static seed to carry forward.
+     */
+    static load(appDir) {
+        const filePath = path.join(appDir, "pairing.json");
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, "utf8");
+        }
+        catch (error) {
+            // Only a missing file means "never paired yet". Any other read failure
+            // (permission denied, I/O error, etc.) must not mint a fresh identity.
+            if (error?.code !== "ENOENT")
+                throw error;
+        }
+        if (raw !== undefined) {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // The file exists but is corrupt/truncated. Minting a fresh keypair and
+                // room key here would silently invalidate every paired device, so fail
+                // loudly instead and let the operator decide how to recover.
+                throw new Error(`Pairing state file at ${filePath} is corrupt and could not be parsed. Refusing to generate a ` +
+                    `new keypair/room key (this would invalidate every paired device). Restore it from a backup, ` +
+                    `or remove the file manually if you intend to start fresh.`);
+            }
+            if (!parsed.nodeKeypair?.publicKeyB64 || !parsed.roomKeyB64) {
+                throw new Error(`Pairing state file at ${filePath} is missing required fields (nodeKeypair/roomKeyB64). Refusing ` +
+                    `to generate a new keypair/room key (this would invalidate every paired device). Restore it ` +
+                    `from a backup, or remove the file manually if you intend to start fresh.`);
+            }
+            return new PairingStore(filePath, {
+                nodeKeypair: parsed.nodeKeypair,
+                roomKeyB64: parsed.roomKeyB64,
+                devices: Array.isArray(parsed.devices) ? parsed.devices : [],
+            });
+        }
+        const data = {
+            nodeKeypair: generatePairingKeypair(),
+            roomKeyB64: generateRoomKey().toString("base64"),
+            devices: [],
+        };
+        const store = new PairingStore(filePath, data);
+        store.persist();
+        return store;
+    }
+    persist() {
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+        // Atomic write: write to a tmp file in the same directory, then rename over
+        // the target, so readers never observe a partially-written/truncated file.
+        const tmp = `${this.filePath}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(this.data, null, 2)}\n`, { mode: 0o600 });
+        try {
+            fs.chmodSync(tmp, 0o600);
+        }
+        catch {
+            // best effort on platforms without chmod
+        }
+        fs.renameSync(tmp, this.filePath);
+        try {
+            fs.chmodSync(this.filePath, 0o600);
+        }
+        catch {
+            // best effort on platforms without chmod
+        }
+    }
+    nodePublicKeyB64() {
+        return this.data.nodeKeypair.publicKeyB64;
+    }
+    wrapForNodePublicKey(nodePublicKeyB64, plaintextB64, purpose = "model-auth-vault") {
+        const wrapKey = deriveWrapKey(this.data.nodeKeypair.privateKeyB64, nodePublicKeyB64, purpose);
+        return seal(wrapKey, plaintextB64);
+    }
+    unwrapFromNodePublicKey(nodePublicKeyB64, wrapped, purpose = "model-auth-vault") {
+        const wrapKey = deriveWrapKey(this.data.nodeKeypair.privateKeyB64, nodePublicKeyB64, purpose);
+        return open(wrapKey, wrapped);
+    }
+    roomKey() {
+        return Buffer.from(this.data.roomKeyB64, "base64");
+    }
+    /** Issue a single-use, expiring pairing secret to embed in a linking QR. */
+    issuePairSecret(ttlMs = DEFAULT_PAIR_TTL_MS) {
+        this.sweepSecrets();
+        const secret = generatePairSecret();
+        this.pendingSecrets.set(secret, Date.now() + ttlMs);
+        return secret;
+    }
+    welcomeForTrustedDevice(input) {
+        const { devicePublicKeyB64 } = input;
+        if (!devicePublicKeyB64)
+            return null;
+        const existing = this.data.devices.find((d) => d.publicKeyB64 === devicePublicKeyB64);
+        const device = existing ?? {
+            id: `lnkdev_${randomUUID()}`,
+            publicKeyB64: devicePublicKeyB64,
+            label: (input.label ?? "Device").toString().slice(0, 60) || "Device",
+            createdAt: new Date().toISOString(),
+            lastSeenAt: new Date().toISOString(),
+        };
+        if (existing)
+            existing.lastSeenAt = new Date().toISOString();
+        else
+            this.data.devices.push(device);
+        this.persist();
+        const wrapKey = deriveWrapKey(this.data.nodeKeypair.privateKeyB64, devicePublicKeyB64, "pair");
+        return {
+            deviceId: device.id,
+            nodePublicKeyB64: this.data.nodeKeypair.publicKeyB64,
+            wrapped: wrapRoomKey(wrapKey, this.roomKey()),
+        };
+    }
+    /**
+     * Handle a device's `pair.hello`. The device sends its public key and a proof
+     * (HMAC over its public key keyed by the QR's pairing secret) — never the
+     * secret itself. We match the proof against outstanding secrets; a relay that
+     * never saw the QR cannot produce a valid proof. On success the device is
+     * registered and the room key is wrapped for it. Returns null on failure.
+     */
+    handleHello(input) {
+        this.sweepSecrets();
+        const { devicePublicKeyB64, proofB64 } = input;
+        if (!devicePublicKeyB64 || !proofB64)
+            return null;
+        let matched = null;
+        for (const secret of this.pendingSecrets.keys()) {
+            if (verifyPairingProof(secret, devicePublicKeyB64, proofB64)) {
+                matched = secret;
+                break;
+            }
+        }
+        if (!matched)
+            return null;
+        this.pendingSecrets.delete(matched); // single use
+        return this.welcomeForTrustedDevice(input);
+    }
+    /** Trust a device that was authorized by the control plane account session. */
+    trustDevice(input) {
+        return this.welcomeForTrustedDevice(input);
+    }
+    listDevices() {
+        return this.data.devices.map((d) => ({ ...d }));
+    }
+    touchDevice(deviceId) {
+        const device = this.data.devices.find((d) => d.id === deviceId);
+        if (device) {
+            device.lastSeenAt = new Date().toISOString();
+            this.persist();
+        }
+    }
+    /**
+     * Revoke a device: drop it, rotate the room key, and re-wrap the NEW room key
+     * for every remaining device (using the "rotate" context). The revoked device
+     * never receives the new key and its old key is now dead. Returns the per-device
+     * wrapped deliveries for the caller to push over the relay, or null if the
+     * device was not found.
+     */
+    revokeDevice(deviceId) {
+        const before = this.data.devices.length;
+        this.data.devices = this.data.devices.filter((d) => d.id !== deviceId);
+        if (this.data.devices.length === before)
+            return null;
+        return this.rotateRoomKey();
+    }
+    /** Rotate the room key and re-wrap it for all current devices. */
+    rotateRoomKey() {
+        this.data.roomKeyB64 = generateRoomKey().toString("base64");
+        this.persist();
+        const roomKey = this.roomKey();
+        return this.data.devices.map((device) => ({
+            deviceId: device.id,
+            wrapped: wrapRoomKey(deriveWrapKey(this.data.nodeKeypair.privateKeyB64, device.publicKeyB64, "rotate"), roomKey),
+        }));
+    }
+    sweepSecrets() {
+        const now = Date.now();
+        for (const [secret, expiry] of this.pendingSecrets) {
+            if (expiry < now)
+                this.pendingSecrets.delete(secret);
+        }
+    }
+}

package/dist/e2e.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { randomBytes, createCipheriv, createDecipheriv } from "node:crypto";
+import { IV_BYTES, SEALED_HEADER_BYTES, FRAME_VERSION, FRAME_NONCE_BYTES, REPLAY_WINDOW_MS, MAX_SEEN_NONCES, } from "./wire-format.js";
+/**
+ * End-to-end encryption envelope (AES-256-GCM).
+ *
+ * The 32-byte key is established during device pairing and shared only between
+ * the node and its paired clients. The relay never has it, so it can route but
+ * not read frames.
+ *
+ * Wire format (base64): [ 12-byte IV | 16-byte GCM tag | ciphertext ].
+ */
+export function seal(key, plaintext) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, ct]).toString("base64");
+}
+export function open(key, payload) {
+    const buf = Buffer.from(payload, "base64");
+    const iv = buf.subarray(0, IV_BYTES);
+    const tag = buf.subarray(IV_BYTES, SEALED_HEADER_BYTES);
+    const ct = buf.subarray(SEALED_HEADER_BYTES);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+}
+export function sealFrame(key, data) {
+    const frame = { v: FRAME_VERSION, ts: Date.now(), nonce: randomBytes(FRAME_NONCE_BYTES).toString("base64"), data };
+    return seal(key, JSON.stringify(frame));
+}
+export function openFrame(key, payload) {
+    const env = JSON.parse(open(key, payload));
+    if (!env || typeof env !== "object" || typeof env.ts !== "number" || typeof env.nonce !== "string") {
+        throw new Error("Malformed frame");
+    }
+    return { ts: env.ts, nonce: env.nonce, data: env.data };
+}
+/**
+ * Rejects stale (outside the freshness window) or duplicate (nonce already
+ * seen) frames. A bounded seen-nonce cache handles multiple senders sharing the
+ * key without per-sender sequence state.
+ */
+export class ReplayGuard {
+    windowMs;
+    seen = new Map(); // nonce -> expiry (ms)
+    constructor(windowMs = REPLAY_WINDOW_MS) {
+        this.windowMs = windowMs;
+    }
+    /** Returns true if the frame is fresh and previously unseen. */
+    accept(frame) {
+        const now = Date.now();
+        if (Math.abs(now - frame.ts) > this.windowMs)
+            return false;
+        if (this.seen.has(frame.nonce))
+            return false;
+        this.seen.set(frame.nonce, now + this.windowMs);
+        if (this.seen.size > MAX_SEEN_NONCES)
+            this.prune(now);
+        return true;
+    }
+    prune(now) {
+        for (const [nonce, expiry] of this.seen) {
+            if (expiry <= now)
+                this.seen.delete(nonce);
+        }
+    }
+}

package/dist/ephemeral-exec.js

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Ephemeral provisioning proxy (node-broker path).
+//
+// A remote device that holds the user's cloud token asks this node to make ONE
+// allowlisted HTTPS request to a provider (Fly/Hetzner/AWS/...) on its behalf —
+// the browser can't call those APIs directly (no CORS). The token/credentials
+// ride in the request headers and are used transiently; nothing is persisted
+// here, so the provisioning stays end-to-end (the control plane never sees
+// it). The host allowlist is the SSRF guard and must be kept in lock-step with
+// the two other copies: `ALLOWED_HOSTS` in packages/core/src/ephemeral.ts
+// (the browser-side adapter) and the control-plane's cold-start relay in
+// services/control-plane/src/index.ts.
+export const EPHEMERAL_ALLOWED_HOSTS = new Set([
+    "api.hetzner.cloud",
+    "api.machines.dev",
+    "api.fly.io",
+    "api.sprites.dev",
+    "ec2.us-east-1.amazonaws.com",
+    "ec2.us-west-2.amazonaws.com",
+    "ec2.eu-west-1.amazonaws.com",
+    "ec2.eu-central-1.amazonaws.com",
+    "ec2.ap-southeast-1.amazonaws.com",
+    "ec2.ap-northeast-1.amazonaws.com",
+    "ssm.us-east-1.amazonaws.com",
+    "ssm.us-west-2.amazonaws.com",
+    "ssm.eu-west-1.amazonaws.com",
+    "ssm.eu-central-1.amazonaws.com",
+    "ssm.ap-southeast-1.amazonaws.com",
+    "ssm.ap-northeast-1.amazonaws.com",
+]);
+/** Hard cap on redirect hops, so a provider (or a MITM) can't wedge us in a loop. */
+const MAX_REDIRECTS = 5;
+function checkAllowedHost(url) {
+    let host;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        throw new Error(`Bad provider URL: ${url}`);
+    }
+    if (!EPHEMERAL_ALLOWED_HOSTS.has(host))
+        throw new Error(`Refusing to proxy to non-provider host: ${host}`);
+    return host;
+}
+/**
+ * How a redirect changes the follow-up request, mirroring the WHATWG fetch spec's
+ * own `redirect: "follow"` behavior (which we're replicating manually below so we
+ * can re-validate the target host on every hop): 303 always downgrades to a
+ * bodyless GET; 301/302 do the same but only for a non-GET/HEAD method; 307/308
+ * preserve the original method and body.
+ */
+function nextHopRequest(status, method, payload) {
+    if (status === 303 || ((status === 301 || status === 302) && method !== "GET" && method !== "HEAD")) {
+        return { method: "GET", payload: undefined };
+    }
+    return { method, payload };
+}
+/**
+ * Perform one allowlisted provider request for a remote device. Rejects any
+ * non-provider host — including a redirect target: the allowlist check ran only
+ * on the *initial* URL, but a plain `fetch` follows redirects transparently, so a
+ * provider response (or anyone able to influence it) could 302 us — Authorization
+ * header and all — to an arbitrary host. `redirect: "manual"` disables that
+ * auto-follow so every hop's Location is re-checked against the same allowlist
+ * before it's requested.
+ */
+export async function execEphemeralRequest(request, fetchImpl = fetch) {
+    let url = String(request?.url ?? "");
+    let method = String(request?.method ?? "GET").toUpperCase();
+    const headers = { ...(request?.headers ?? {}) };
+    let payload;
+    if (request?.body !== undefined && request?.body !== null && method !== "GET" && method !== "HEAD") {
+        payload = typeof request.body === "string" ? request.body : JSON.stringify(request.body);
+        if (!Object.keys(headers).some((h) => h.toLowerCase() === "content-type"))
+            headers["content-type"] = "application/json";
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        for (let hop = 0;; hop++) {
+            const host = checkAllowedHost(url);
+            const res = await fetchImpl(url, { method, headers, body: payload, signal: controller.signal, redirect: "manual" });
+            if (res.status >= 300 && res.status < 400 && res.status !== 304) {
+                if (hop >= MAX_REDIRECTS)
+                    throw new Error(`Too many redirects proxying to ${host}`);
+                const location = res.headers.get("location");
+                if (!location)
+                    throw new Error(`Redirect from ${host} (${res.status}) had no Location header`);
+                // Resolve relative to the current hop; the loop's next iteration
+                // re-validates this new host before it's ever requested — the whole
+                // point of this loop.
+                url = new URL(location, url).toString();
+                ({ method, payload } = nextHopRequest(res.status, method, payload));
+                continue;
+            }
+            const text = await res.text();
+            let body = text;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch { /* non-JSON provider response */ }
+            return { status: res.status, body };
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}