@reclaimprotocol/agent 0.1.22 → 0.1.24

package/lib/cdp/capture-engine.js

@@ -56,9 +56,10 @@ export function isStaticAsset(url) {
     return STATIC_ASSET_EXTENSIONS.has(base.slice(dot + 1).toLowerCase());
 }
 /** Response Content-Types for static assets. The URL-extension filter misses
- *  extension-less bundler/CDN URLs (e.g. `/assets/3b8f1c`), so we also drop by
- *  MIME at response time. `text/html`, `application/json`, and `text/plain`
- *  are NOT here — those are the document/API shapes recipes match. */
+ *  extension-less bundler/CDN URLs (for example, `/assets/3b8f1c`), so we also
+ *  drop by MIME at response time. `text/html`, `application/json`, and
+ *  `text/plain` are NOT here — those are the document/API shapes recipes
+ *  match. */
 const STATIC_ASSET_MIME_EXACT = new Set([
     'text/css',
     'application/javascript', 'text/javascript', 'application/x-javascript',
@@ -165,9 +166,9 @@ export function createCaptureEngine(opts) {
     function onResponseReceived(p) {
         const f = inFlight.get(p.requestId);
         if (!f) {
-            // No in-flight entry → the request was skipped (e.g. a static asset)
-            // or never seen. Discard any buffered response extra-info so a skipped
-            // asset can't leave a dangling entry.
+            // No in-flight entry → the request was skipped (for example, a static
+            // asset) or never seen. Discard any buffered response extra-info so a
+            // skipped asset can't leave a dangling entry.
             pendingResponseExtra.delete(p.requestId);
             return;
         }
@@ -225,7 +226,7 @@ export function createCaptureEngine(opts) {
         }
         catch {
             // Body might be unavailable for
-            // some content-types (e.g. websocket). Skip.
+            // some content-types (for example, websocket). Skip.
         }
     }
 }

package/lib/cdp/client.d.ts

@@ -19,6 +19,16 @@ interface CdpTabEventMap {
     'Network.loadingFinished': {
         requestId: string;
     };
+    /** Screencast frames, for the live view (`live/viewer.ts`). Each carries a
+     *  `sessionId` that MUST be acked with `Page.screencastFrameAck`, or CDP
+     *  stops sending. */
+    'Page.screencastFrame': {
+        data: string;
+        sessionId: number;
+        metadata?: {
+            timestamp?: number;
+        };
+    };
 }
 export interface CdpTabClient {
     send: (method: string, params?: object) => Promise<unknown>;

package/lib/cdp/geo.d.ts

@@ -0,0 +1,10 @@
+export interface IpGeolocation {
+    countryCode: string;
+    country?: string;
+    region?: string;
+    city?: string;
+}
+/** Resolve the calling machine's own public-IP country. Never throws — a
+ *  lookup failure just loses the "best guess" convenience, falling back to
+ *  {@link FALLBACK_COUNTRY_CODE} rather than blocking applying a proxy. */
+export declare function suggestCountryFromIp(fetchImpl?: typeof fetch): Promise<IpGeolocation>;

package/lib/cdp/geo.js

@@ -0,0 +1,36 @@
+/**
+ * Country-code suggestion for a country-routed Popcorn browser session, when
+ * the caller doesn't name one explicitly. `attach_browser` returns this as the
+ * suggestion to confirm with the developer — the calling machine's own
+ * public-IP country, resolved the same way reclaim-portal's `ip-geolocation`
+ * util does.
+ */
+import { LOGGER } from "../logger.js";
+const IPINFO_URL = 'https://ipinfo.io/json';
+const FALLBACK_COUNTRY_CODE = 'US';
+/** Resolve the calling machine's own public-IP country. Never throws — a
+ *  lookup failure just loses the "best guess" convenience, falling back to
+ *  {@link FALLBACK_COUNTRY_CODE} rather than blocking applying a proxy. */
+export async function suggestCountryFromIp(fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(IPINFO_URL);
+        if (!res.ok) {
+            throw new Error(`ipinfo.io ${res.status}`);
+        }
+        const data = await res.json();
+        const countryCode = data.country?.toUpperCase();
+        if (!countryCode) {
+            throw new Error('ipinfo.io response had no country');
+        }
+        return {
+            countryCode,
+            country: data.country,
+            region: data.region,
+            city: data.city,
+        };
+    }
+    catch (err) {
+        LOGGER.warn({ err }, 'suggestCountryFromIp failed; using fallback');
+        return { countryCode: FALLBACK_COUNTRY_CODE };
+    }
+}

package/lib/cdp/index.d.ts

@@ -1,3 +1,4 @@
 export * from './capture-engine.ts';
 export { startCapture } from './capture.ts';
 export { BodyStore } from './eviction.ts';
+export * from './geo.ts';

package/lib/cdp/index.js

@@ -4,3 +4,4 @@
 export * from "./capture-engine.js";
 export { startCapture } from "./capture.js";
 export { BodyStore } from "./eviction.js";
+export * from "./geo.js";

package/lib/live/cloudflared.d.ts

@@ -0,0 +1,15 @@
+export interface CloudflaredBinary {
+    /** Path to run. */
+    path: string;
+    /** How it was found — surfaced so the caller can tell the developer when a
+     *  download just happened on their machine. */
+    source: 'env' | 'path' | 'cached' | 'downloaded';
+}
+/**
+ * Resolve a runnable cloudflared, downloading one only if `autoInstall` allows
+ * it and nothing else turned up. Throws with an actionable message when this
+ * platform has no build, or the download fails.
+ */
+export declare function resolveCloudflared({ autoInstall }?: {
+    autoInstall?: boolean;
+}): Promise<CloudflaredBinary>;

package/lib/live/cloudflared.js

@@ -0,0 +1,268 @@
+/**
+ * Finding — and if necessary fetching — the `cloudflared` binary the live view
+ * tunnels through.
+ *
+ * Resolution order, first hit wins:
+ *  1. `RECLAIM_CLOUDFLARED_PATH`, for an air-gapped box or a corporate mirror.
+ *  2. `cloudflared` on PATH — someone who installed it with a package manager
+ *     keeps their own copy, updated their way.
+ *  3. `~/.reclaim/bin/cloudflared`, ours from a previous run.
+ *  4. Download it from Cloudflare's GitHub releases into `~/.reclaim/bin`.
+ *
+ * Step 4 happens on FIRST USE, never at install time. The npm `cloudflared`
+ * package would have done this for us, but its postinstall pulls a ~38 MB
+ * binary on every `npm install` of this package — a cost paid by everyone who
+ * never shares a live view. `run_proof`'s ZK circuits are deferred for exactly
+ * the same reason.
+ *
+ * Every download is SHA-256 verified. Cloudflare publishes a checksum table in
+ * the release notes (not as a release asset), so we read the release metadata
+ * first, take the digest for our asset, and refuse to install anything that
+ * doesn't match. The release TAG from that same response is used to build the
+ * download URL, so the checksum and the bytes always come from one release —
+ * `/latest/download/` could otherwise hand us a newer build than the table we
+ * just read.
+ *
+ * Verification is not optional: this writes an executable to the developer's
+ * machine. If the checksum can't be established, we fail rather than install.
+ * The escape hatch is to install cloudflared yourself — step 2 then wins and
+ * nothing is downloaded.
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { arch, platform } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { gunzipSync } from 'node:zlib';
+import { LOGGER } from "../logger.js";
+import { reclaimHomeDirPath } from "../paths.js";
+const execFileAsync = promisify(execFile);
+/** Release metadata: the tag to pin to, and the checksum table in its notes. */
+const LATEST_RELEASE_API = 'https://api.github.com/repos/cloudflare/cloudflared/releases/latest';
+/** Asset downloads, keyed by the tag we read the checksums from. */
+function releaseDownloadUrl(tag, asset) {
+    return 'https://github.com/cloudflare/cloudflared/releases/download'
+        + `/${tag}/${asset}`;
+}
+/** Give up on a slow or stalled download rather than hanging the tool. */
+const DOWNLOAD_TIMEOUT_MS = 180000;
+/**
+ * The release asset for this machine, or `undefined` when Cloudflare ships no
+ * build for it. macOS assets are gzipped tarballs; everything else is the bare
+ * executable.
+ */
+function assetFor(os, cpu) {
+    if (os === 'darwin') {
+        const suffix = cpu === 'arm64' ? 'arm64' : 'amd64';
+        return { name: `cloudflared-darwin-${suffix}.tgz`, tarball: true };
+    }
+    if (os === 'linux') {
+        const map = {
+            x64: 'amd64',
+            arm64: 'arm64',
+            arm: 'arm',
+            ia32: '386',
+        };
+        const suffix = map[cpu];
+        return suffix
+            ? { name: `cloudflared-linux-${suffix}`, tarball: false }
+            : undefined;
+    }
+    if (os === 'win32') {
+        const suffix = cpu === 'ia32' ? '386' : 'amd64';
+        return { name: `cloudflared-windows-${suffix}.exe`, tarball: false };
+    }
+    return undefined;
+}
+/** Our install location. Kept beside the other `~/.reclaim` caches. */
+function cachedBinaryPath() {
+    const name = platform() === 'win32' ? 'cloudflared.exe' : 'cloudflared';
+    return join(reclaimHomeDirPath(), 'bin', name);
+}
+/** Whether `command` runs. Used both for a PATH probe and to smoke-test a
+ *  freshly downloaded binary before we hand it back. */
+async function runsOk(command) {
+    try {
+        await execFileAsync(command, ['--version'], { timeout: 15000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a runnable cloudflared, downloading one only if `autoInstall` allows
+ * it and nothing else turned up. Throws with an actionable message when this
+ * platform has no build, or the download fails.
+ */
+export async function resolveCloudflared({ autoInstall = true } = {}) {
+    const override = process.env.RECLAIM_CLOUDFLARED_PATH?.trim();
+    if (override) {
+        if (!await runsOk(override)) {
+            throw new Error(`RECLAIM_CLOUDFLARED_PATH is set to "${override}", but that did not `
+                + 'run. Point it at a working cloudflared binary, or unset it to let '
+                + 'the agent find one.');
+        }
+        return { path: override, source: 'env' };
+    }
+    if (await runsOk('cloudflared')) {
+        return { path: 'cloudflared', source: 'path' };
+    }
+    const cached = cachedBinaryPath();
+    if (await exists(cached) && await runsOk(cached)) {
+        return { path: cached, source: 'cached' };
+    }
+    if (!autoInstall) {
+        throw new Error('cloudflared is not installed. Install it (macOS: `brew install '
+            + 'cloudflared`; other platforms: https://developers.cloudflare.com/'
+            + 'cloudflare-one/connections/connect-networks/downloads/), or allow '
+            + 'the agent to fetch it.');
+    }
+    await install(cached);
+    return { path: cached, source: 'downloaded' };
+}
+/** `cloudflared-linux-amd64: <64 hex>` lines inside the notes' fenced block. */
+const CHECKSUM_LINE = /^\s*(\S+):\s*([a-f0-9]{64})\s*$/gim;
+/**
+ * The current release's tag and its published SHA-256 table.
+ *
+ * Both come from one response on purpose: pinning the download to this tag is
+ * what makes the digest meaningful.
+ */
+async function fetchRelease() {
+    const res = await fetch(LATEST_RELEASE_API, {
+        headers: {
+            accept: 'application/vnd.github+json',
+            'user-agent': '@reclaimprotocol/agent',
+        },
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok) {
+        throw new Error(`Could not read cloudflared release metadata: ${res.status} `
+            + `${res.statusText}. Needed to verify the download's checksum. `
+            + 'Install cloudflared yourself, or set RECLAIM_CLOUDFLARED_PATH.');
+    }
+    const release = await res.json();
+    const tag = release.tag_name;
+    if (!tag) {
+        throw new Error('cloudflared release metadata carried no tag.');
+    }
+    const checksums = new Map();
+    for (const match of (release.body ?? '').matchAll(CHECKSUM_LINE)) {
+        checksums.set(match[1], match[2].toLowerCase());
+    }
+    return { tag, checksums };
+}
+/** Download the release asset for this machine to `target`, verified. */
+async function install(target) {
+    const asset = assetFor(platform(), arch());
+    if (!asset) {
+        throw new Error(`Cloudflare publishes no cloudflared build for ${platform()}/${arch()}. `
+            + 'Install it another way and set RECLAIM_CLOUDFLARED_PATH, or use '
+            + '`attach_browser` in builder mode, whose Popcorn browser returns a '
+            + 'hosted liveViewUrl and needs no tunnel.');
+    }
+    // Read the checksum table BEFORE downloading, and pin the download to the
+    // tag it came from.
+    const { tag, checksums } = await fetchRelease();
+    const expected = checksums.get(asset.name);
+    if (!expected) {
+        throw new Error(`cloudflared release ${tag} publishes no SHA-256 for ${asset.name}, so `
+            + 'the download cannot be verified. Refusing to install an unverified '
+            + 'binary. Install cloudflared yourself, or set '
+            + 'RECLAIM_CLOUDFLARED_PATH.');
+    }
+    const url = releaseDownloadUrl(tag, asset.name);
+    LOGGER.info({ url, target, tag }, 'cloudflared: downloading (first use)');
+    const res = await fetch(url, {
+        redirect: 'follow',
+        signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`Downloading cloudflared failed: ${res.status} ${res.statusText} `
+            + `from ${url}. Install it manually and retry, or set `
+            + 'RECLAIM_CLOUDFLARED_PATH.');
+    }
+    const downloaded = Buffer.from(await res.arrayBuffer());
+    // The macOS assets are tarballs, so unpack before hashing. Unpacked
+    // in-process rather than by shelling out to `tar`: that would add a
+    // dependency on something being on PATH, which is exactly the assumption
+    // this module exists to stop making.
+    //
+    // This ordering is not incidental. Cloudflare's table lists a digest for
+    // `cloudflared-darwin-arm64.tgz`, but that digest is of the BINARY INSIDE,
+    // not of the tarball (verified against a real release: the tarball hashes
+    // to something else entirely, and the binary self-reports the published
+    // value as its own checksum). The linux and windows entries, which ship a
+    // bare executable, do match the downloaded file. Hashing the payload we are
+    // about to write covers both, and is the stronger invariant anyway: what
+    // gets verified is what gets executed.
+    const payload = asset.tarball
+        ? readTarEntry(gunzipSync(downloaded), 'cloudflared')
+        : downloaded;
+    const actual = createHash('sha256').update(payload).digest('hex');
+    if (actual !== expected) {
+        // Nothing is written to disk on a mismatch — not even a partial file.
+        throw new Error(`cloudflared checksum mismatch for ${asset.name} (release ${tag}). `
+            + `Expected ${expected}, got ${actual}. The download was discarded. `
+            + 'Retry; if it persists, install cloudflared yourself and set '
+            + 'RECLAIM_CLOUDFLARED_PATH.');
+    }
+    LOGGER.info({ asset: asset.name, tag }, 'cloudflared: checksum verified');
+    // Write beside the target, then rename: a half-written or unverified
+    // binary is never left at a path a later run would trust.
+    await mkdir(join(target, '..'), { recursive: true });
+    const partial = `${target}.download`;
+    await writeFile(partial, payload);
+    await rename(partial, target);
+    if (platform() !== 'win32') {
+        await chmod(target, 0o755);
+    }
+    if (!await runsOk(target)) {
+        await rm(target, { force: true });
+        throw new Error('Downloaded cloudflared, but it did not run. Removed it. Install '
+            + 'cloudflared manually and retry.');
+    }
+    LOGGER.info({ target }, 'cloudflared: installed');
+}
+/** A tar header block is 512 bytes, and so is every data block. */
+const TAR_BLOCK = 512;
+/**
+ * Pull one file out of an uncompressed tar archive.
+ *
+ * Only as much of the format as this needs: walk the 512-byte headers, read
+ * each entry's name and octal size, and return the payload of the first
+ * regular file whose basename matches. Cloudflare's macOS tarball holds a
+ * single binary, so there is nothing more to handle.
+ */
+function readTarEntry(tar, wanted) {
+    let offset = 0;
+    while (offset + TAR_BLOCK <= tar.length) {
+        const header = tar.subarray(offset, offset + TAR_BLOCK);
+        const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+        if (!name) {
+            break; // two zero blocks mark the end of the archive
+        }
+        const size = parseInt(header.subarray(124, 136).toString('utf8').replace(/\0.*$/, '').trim(), 8) || 0;
+        const type = header.subarray(156, 157).toString('utf8');
+        const dataStart = offset + TAR_BLOCK;
+        if ((type === '0' || type === '\0') && name.split('/').pop() === wanted) {
+            return tar.subarray(dataStart, dataStart + size);
+        }
+        // Data is padded up to the next block boundary.
+        offset = dataStart + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+    }
+    throw new Error(`The cloudflared archive did not contain "${wanted}". Cloudflare may `
+        + 'have changed its release layout — install cloudflared manually and '
+        + 'set RECLAIM_CLOUDFLARED_PATH.');
+}

package/lib/live/page.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The live-view page served to whoever opens the tunnel URL.
+ *
+ * Deliberately dependency-free and inline: it is delivered through a throwaway
+ * tunnel, so it cannot rely on a CDN, a bundler, or anything cached.
+ *
+ * Frames arrive as base64 JPEG over Server-Sent Events rather than a
+ * WebSocket. SSE is one plain GET, so it survives tunnels and proxies that
+ * mishandle upgrades, and it reconnects on its own. Input goes the other way
+ * as small POSTs.
+ */
+export interface PageOptions {
+    /** Path prefix that carries the access token, for example `/v/<token>`. */
+    base: string;
+    /** Whether to wire up mouse and keyboard forwarding. */
+    interactive: boolean;
+    /** Shown in the header so a viewer knows which tab they are watching. */
+    title: string;
+}
+export declare function renderViewerPage(opts: PageOptions): string;

package/lib/live/page.js

@@ -0,0 +1,134 @@
+/**
+ * The live-view page served to whoever opens the tunnel URL.
+ *
+ * Deliberately dependency-free and inline: it is delivered through a throwaway
+ * tunnel, so it cannot rely on a CDN, a bundler, or anything cached.
+ *
+ * Frames arrive as base64 JPEG over Server-Sent Events rather than a
+ * WebSocket. SSE is one plain GET, so it survives tunnels and proxies that
+ * mishandle upgrades, and it reconnects on its own. Input goes the other way
+ * as small POSTs.
+ */
+/** Escape a value for embedding in a single-quoted JS string literal. */
+function js(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/</g, '\\x3c');
+}
+export function renderViewerPage(opts) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>Reclaim live view</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: #0b0b0c; color: #e7e7ea; display: flex;
+    flex-direction: column; height: 100vh;
+    font: 14px/1.4 ui-sans-serif, system-ui, sans-serif; }
+  header { display: flex; align-items: center; gap: .75rem;
+    padding: .5rem .75rem; border-bottom: 1px solid #26262b; }
+  .dot { width: .5rem; height: .5rem; border-radius: 50%; background: #f5a524; }
+  .dot.live { background: #17c964; }
+  .title { color: #9a9aa4; overflow: hidden; text-overflow: ellipsis;
+    white-space: nowrap; }
+  .badge { margin-left: auto; font-size: 12px; padding: .15rem .4rem;
+    border: 1px solid #26262b; border-radius: .25rem; color: #9a9aa4; }
+  main { flex: 1; min-height: 0; display: grid; place-items: center;
+    padding: .75rem; }
+  img { max-width: 100%; max-height: 100%; display: block;
+    background: #fff; border-radius: .25rem; }
+  img.interactive { cursor: crosshair; }
+  .msg { color: #9a9aa4; }
+</style>
+</head>
+<body>
+<header>
+  <span class="dot" id="dot"></span>
+  <span class="title" id="title">${js(opts.title)}</span>
+  <span class="badge">${opts.interactive ? 'interactive' : 'view only'}</span>
+</header>
+<main><img id="screen" alt="Live view of the browser tab"><p class="msg"
+  id="msg">Connecting…</p></main>
+<script>
+(function () {
+  var BASE = '${js(opts.base)}';
+  var INTERACTIVE = ${opts.interactive ? 'true' : 'false'};
+  var screen = document.getElementById('screen');
+  var msg = document.getElementById('msg');
+  var dot = document.getElementById('dot');
+  var title = document.getElementById('title');
+
+  var es = new EventSource(BASE + '/stream');
+  es.addEventListener('frame', function (e) {
+    var payload = JSON.parse(e.data);
+    screen.src = 'data:image/jpeg;base64,' + payload.data;
+    if (payload.title) { title.textContent = payload.title; }
+    msg.style.display = 'none';
+    dot.className = 'dot live';
+  });
+  es.onerror = function () {
+    dot.className = 'dot';
+    msg.style.display = '';
+    msg.textContent = 'Reconnecting…';
+  };
+
+  if (!INTERACTIVE) { return; }
+  screen.className = 'interactive';
+
+  // The <img> is letterboxed by object-fit, so a click at some point in the
+  // element maps to page coordinates by the ratio of natural to rendered size.
+  function toPage(ev) {
+    var r = screen.getBoundingClientRect();
+    if (!screen.naturalWidth || !r.width) { return null; }
+    return {
+      x: Math.round((ev.clientX - r.left) * (screen.naturalWidth / r.width)),
+      y: Math.round((ev.clientY - r.top) * (screen.naturalHeight / r.height))
+    };
+  }
+
+  function post(body) {
+    return fetch(BASE + '/input', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body)
+    }).catch(function () {});
+  }
+
+  screen.addEventListener('mousedown', function (ev) {
+    var p = toPage(ev); if (!p) { return; }
+    ev.preventDefault();
+    post({ kind: 'mouse', type: 'mousePressed', x: p.x, y: p.y,
+      button: 'left', clickCount: 1 });
+  });
+  screen.addEventListener('mouseup', function (ev) {
+    var p = toPage(ev); if (!p) { return; }
+    post({ kind: 'mouse', type: 'mouseReleased', x: p.x, y: p.y,
+      button: 'left', clickCount: 1 });
+  });
+  screen.addEventListener('wheel', function (ev) {
+    var p = toPage(ev); if (!p) { return; }
+    ev.preventDefault();
+    post({ kind: 'mouse', type: 'mouseWheel', x: p.x, y: p.y,
+      deltaX: ev.deltaX, deltaY: ev.deltaY });
+  }, { passive: false });
+
+  // Typing goes to the page, so the viewer never needs to focus anything.
+  window.addEventListener('keydown', function (ev) {
+    if (ev.metaKey || ev.ctrlKey) { return; }
+    ev.preventDefault();
+    post({ kind: 'key', type: 'keyDown', key: ev.key, code: ev.code });
+  });
+  window.addEventListener('keyup', function (ev) {
+    if (ev.metaKey || ev.ctrlKey) { return; }
+    post({ kind: 'key', type: 'keyUp', key: ev.key, code: ev.code });
+  });
+})();
+</script>
+</body>
+</html>`;
+}

package/lib/live/tunnel.d.ts

@@ -0,0 +1,23 @@
+import { type CloudflaredBinary } from './cloudflared.ts';
+export interface Tunnel {
+    /** The public HTTPS origin Cloudflare assigned. */
+    url: string;
+    /** Whether the edge answered before {@link READY_TIMEOUT_MS} elapsed. False
+     *  means the tunnel is probably still propagating rather than broken — tell
+     *  the viewer to retry rather than treating the share as failed. */
+    ready: boolean;
+    /** Terminate the tunnel. Safe to call more than once. */
+    stop: () => Promise<void>;
+    /** Which cloudflared ran, and whether we had to fetch it. */
+    binary: CloudflaredBinary;
+}
+/**
+ * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
+ * Cloudflare has assigned a hostname.
+ *
+ * Rejects with an actionable message when `cloudflared` is not installed,
+ * exits early, or never reports a hostname.
+ */
+export declare function startTunnel(port: number, { autoInstall }?: {
+    autoInstall?: boolean;
+}): Promise<Tunnel>;