@spinabot/brigade 1.7.0 → 1.9.0

package/dist/core/tunnel/providers/cloudflared.js

@@ -0,0 +1,179 @@
+/**
+ * Cloudflare provider — anonymous TryCloudflare quick tunnel.
+ *
+ * The default `brigade expose` backend. No account, no signup: cloudflared
+ * dials Cloudflare's edge and we get a random `https://<x>.trycloudflare.com`
+ * URL that terminates TLS at the edge and proxies straight to our local
+ * auth-proxy. WebSockets work by default (the gateway is WS-first).
+ *
+ * The `cloudflared` binary (Apache-2.0) is NOT a hard npm dependency — that
+ * would add a ~30 MB download to every Brigade install. Instead we resolve it
+ * lazily at expose time:
+ *   1. `$BRIGADE_CLOUDFLARED_BIN`
+ *   2. `cloudflared` on PATH (system install)
+ *   3. a Brigade-managed copy in the OS cache dir
+ *   4. download the official release into the cache dir (once)
+ *
+ * Caveat (documented in the research): TryCloudflare quick tunnels don't
+ * support SSE and cap in-flight requests; that's fine for a personal WS
+ * gateway. For a stable URL the operator can point a self-host provider at
+ * their own relay instead.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as fsAsync from "node:fs/promises";
+import * as path from "node:path";
+import { resolveOsCacheDir } from "../../../config/paths.js";
+const QUICK_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+const URL_WAIT_MS = 30_000;
+function cloudflaredAssetName() {
+    const arch = process.arch === "x64"
+        ? "amd64"
+        : process.arch === "arm64"
+            ? "arm64"
+            : process.arch === "ia32"
+                ? "386"
+                : process.arch === "arm"
+                    ? "arm"
+                    : "amd64";
+    if (process.platform === "win32")
+        return `cloudflared-windows-${arch === "arm64" ? "amd64" : arch}.exe`;
+    if (process.platform === "darwin")
+        return `cloudflared-darwin-${arch}.tgz`;
+    return `cloudflared-linux-${arch}`;
+}
+function managedBinPath() {
+    const name = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
+    return path.join(resolveOsCacheDir(), "cloudflared", name);
+}
+/** First binary that exists across env → PATH → managed copy. */
+function findExistingBinary() {
+    const envBin = process.env.BRIGADE_CLOUDFLARED_BIN?.trim();
+    if (envBin && fs.existsSync(envBin))
+        return envBin;
+    const probe = process.platform === "win32" ? "where" : "which";
+    try {
+        const res = spawnSync(probe, ["cloudflared"], { encoding: "utf8" });
+        if (res.status === 0) {
+            const first = res.stdout.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+            if (first && fs.existsSync(first))
+                return first;
+        }
+    }
+    catch {
+        // probe tool missing — fall through to managed copy
+    }
+    const managed = managedBinPath();
+    if (fs.existsSync(managed))
+        return managed;
+    return undefined;
+}
+/** Download the official cloudflared release into the cache dir. */
+async function downloadBinary(onLog) {
+    const asset = cloudflaredAssetName();
+    const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset}`;
+    const dest = managedBinPath();
+    await fsAsync.mkdir(path.dirname(dest), { recursive: true });
+    onLog?.(`downloading cloudflared (${asset})…`);
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok || !res.body) {
+        throw new Error(`cloudflared download failed (HTTP ${res.status}) from ${url}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (asset.endsWith(".tgz")) {
+        // macOS ships a gzipped tarball containing the `cloudflared` binary.
+        const tmpTgz = `${dest}.tgz`;
+        await fsAsync.writeFile(tmpTgz, buf);
+        const tar = await import("tar");
+        await tar.x({ file: tmpTgz, cwd: path.dirname(dest) });
+        await fsAsync.rm(tmpTgz, { force: true });
+        // The tarball extracts a file literally named `cloudflared`.
+        const extracted = path.join(path.dirname(dest), "cloudflared");
+        if (extracted !== dest && fs.existsSync(extracted)) {
+            await fsAsync.rename(extracted, dest);
+        }
+    }
+    else {
+        await fsAsync.writeFile(dest, buf);
+    }
+    if (process.platform !== "win32")
+        await fsAsync.chmod(dest, 0o755);
+    onLog?.(`cloudflared ready at ${dest}`);
+    return dest;
+}
+async function resolveBinary(onLog) {
+    return findExistingBinary() ?? (await downloadBinary(onLog));
+}
+export const cloudflareProvider = {
+    name: "cloudflare",
+    label: "Cloudflare (anonymous TryCloudflare quick tunnel)",
+    async isAvailable() {
+        // Always available — the binary is auto-downloaded on first use. We only
+        // surface a soft note when there's no pre-existing copy.
+        return { ok: true };
+    },
+    async start(opts) {
+        const bin = await resolveBinary(opts.onLog);
+        const target = `http://${opts.localHost}:${opts.localPort}`;
+        const args = ["tunnel", "--no-autoupdate", "--url", target];
+        const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const url = await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    child.kill();
+                }
+                catch { /* ignore */ }
+                reject(new Error(`cloudflared did not produce a public URL within ${URL_WAIT_MS / 1000}s`));
+            }, URL_WAIT_MS);
+            const scan = (chunk) => {
+                const text = chunk.toString();
+                for (const line of text.split(/\r?\n/)) {
+                    if (line.trim())
+                        opts.onLog?.(line.trim());
+                }
+                const m = text.match(QUICK_URL_RE);
+                if (m && !settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(m[0]);
+                }
+            };
+            // cloudflared logs the URL to stderr; scan both to be safe.
+            child.stdout?.on("data", scan);
+            child.stderr?.on("data", scan);
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+            });
+            child.on("exit", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(`cloudflared exited (code ${code ?? "?"}) before publishing a URL`));
+            });
+        });
+        let stopped = false;
+        return {
+            provider: "cloudflare",
+            url,
+            async stop() {
+                if (stopped)
+                    return;
+                stopped = true;
+                try {
+                    child.kill();
+                }
+                catch { /* ignore */ }
+            },
+        };
+    },
+};
+//# sourceMappingURL=cloudflared.js.map

package/dist/core/tunnel/providers/cloudflared.js.map

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

package/dist/core/tunnel/providers/custom.d.ts

@@ -0,0 +1,21 @@
+/**
+ * custom provider — run any tunnel command and scrape its public URL.
+ *
+ * The "bring your own OSS tunnel" escape hatch: frp, sish, chisel, zrok,
+ * localhost.run / ssh -R, pinggy, … anything that prints a public URL to
+ * stdout/stderr. The operator supplies a command template via `--command`
+ * (or `cfg.gateway.tunnel.command`); `{port}` is replaced with the local
+ * auth-proxy port.
+ *
+ * Examples:
+ *   --command "ssh -R 80:localhost:{port} nokey@localhost.run"
+ *   --command "sish-client ... -R {port}"
+ *   --command "frpc http --local-port {port} --server-addr my.relay --sd brigade"
+ *
+ * We parse the first `http(s)://…` URL the command emits. If a custom tool
+ * uses a different scheme/format, set `--relay` to override the printed URL
+ * outright (we then skip URL detection and just keep the process alive).
+ */
+import type { TunnelProvider } from "../types.js";
+export declare const customProvider: TunnelProvider;
+//# sourceMappingURL=custom.d.ts.map

package/dist/core/tunnel/providers/custom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../../../src/core/tunnel/providers/custom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAoC,cAAc,EAAsB,MAAM,aAAa,CAAC;AAcxG,eAAO,MAAM,cAAc,EAAE,cAmF5B,CAAC"}

package/dist/core/tunnel/providers/custom.js

@@ -0,0 +1,124 @@
+/**
+ * custom provider — run any tunnel command and scrape its public URL.
+ *
+ * The "bring your own OSS tunnel" escape hatch: frp, sish, chisel, zrok,
+ * localhost.run / ssh -R, pinggy, … anything that prints a public URL to
+ * stdout/stderr. The operator supplies a command template via `--command`
+ * (or `cfg.gateway.tunnel.command`); `{port}` is replaced with the local
+ * auth-proxy port.
+ *
+ * Examples:
+ *   --command "ssh -R 80:localhost:{port} nokey@localhost.run"
+ *   --command "sish-client ... -R {port}"
+ *   --command "frpc http --local-port {port} --server-addr my.relay --sd brigade"
+ *
+ * We parse the first `http(s)://…` URL the command emits. If a custom tool
+ * uses a different scheme/format, set `--relay` to override the printed URL
+ * outright (we then skip URL detection and just keep the process alive).
+ */
+import { spawn } from "node:child_process";
+const ANY_URL_RE = /\bhttps?:\/\/[^\s'"]+/i;
+const URL_WAIT_MS = 30_000;
+/** Split a command string into argv, honouring simple double-quotes. */
+function tokenize(cmd) {
+    const out = [];
+    const re = /"([^"]*)"|(\S+)/g;
+    let m;
+    while ((m = re.exec(cmd)) !== null)
+        out.push(m[1] ?? m[2] ?? "");
+    return out;
+}
+export const customProvider = {
+    name: "custom",
+    label: "custom (user-supplied tunnel command)",
+    async isAvailable(opts) {
+        if (opts?.command && opts.command.trim())
+            return { ok: true };
+        return {
+            ok: false,
+            reason: "the custom provider needs a command — pass --command \"…{port}…\" or set cfg.gateway.tunnel.command.",
+        };
+    },
+    async start(opts) {
+        const template = opts.command?.trim();
+        if (!template)
+            throw new Error("custom provider requires --command");
+        const rendered = template.replaceAll("{port}", String(opts.localPort));
+        const argv = tokenize(rendered);
+        if (argv.length === 0)
+            throw new Error("custom provider command is empty");
+        const child = spawn(argv[0], argv.slice(1), {
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: false,
+        });
+        // If the operator pre-declares the public URL via --relay, trust it and
+        // skip detection (covers tools that don't print a parseable URL).
+        const forced = opts.relay?.trim();
+        const url = await new Promise((resolve, reject) => {
+            let settled = false;
+            const done = (u) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(u);
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    child.kill();
+                }
+                catch { /* ignore */ }
+                reject(new Error(`custom tunnel did not emit a URL within ${URL_WAIT_MS / 1000}s (use --relay to set it explicitly)`));
+            }, URL_WAIT_MS);
+            const scan = (chunk) => {
+                const text = chunk.toString();
+                for (const line of text.split(/\r?\n/)) {
+                    if (line.trim())
+                        opts.onLog?.(line.trim());
+                }
+                if (!forced) {
+                    const m = text.match(ANY_URL_RE);
+                    if (m)
+                        done(m[0]);
+                }
+            };
+            child.stdout?.on("data", scan);
+            child.stderr?.on("data", scan);
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+            });
+            child.on("exit", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(`custom tunnel exited (code ${code ?? "?"}) before emitting a URL`));
+            });
+            // Forced URL: resolve as soon as the process is spawned (give it a tick).
+            if (forced)
+                setTimeout(() => done(forced), 250);
+        });
+        let stopped = false;
+        return {
+            provider: "custom",
+            url,
+            async stop() {
+                if (stopped)
+                    return;
+                stopped = true;
+                try {
+                    child.kill();
+                }
+                catch { /* ignore */ }
+            },
+        };
+    },
+};
+//# sourceMappingURL=custom.js.map

package/dist/core/tunnel/providers/custom.js.map

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

package/dist/core/tunnel/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tunnel provider registry — maps a provider name to its implementation.
+ *
+ * `cloudflare` is the default (zero-config, anonymous, auto-managed binary).
+ * Add a provider by importing it here and listing it in `PROVIDERS`; the CLI's
+ * `--provider` flag and `cfg.gateway.tunnel.provider` both resolve through this.
+ */
+import type { TunnelProvider } from "./types.js";
+/** The default provider used when none is configured. */
+export declare const DEFAULT_PROVIDER = "cloudflare";
+/** All known provider names, in display order. */
+export declare function listProviderNames(): string[];
+/** Resolve a provider by name. Throws with a helpful message on unknown names. */
+export declare function getProvider(name: string): TunnelProvider;
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/tunnel/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/tunnel/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAI7C,kDAAkD;AAClD,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAQxD"}

package/dist/core/tunnel/registry.js

@@ -0,0 +1,26 @@
+/**
+ * Tunnel provider registry — maps a provider name to its implementation.
+ *
+ * `cloudflare` is the default (zero-config, anonymous, auto-managed binary).
+ * Add a provider by importing it here and listing it in `PROVIDERS`; the CLI's
+ * `--provider` flag and `cfg.gateway.tunnel.provider` both resolve through this.
+ */
+import { boreProvider } from "./providers/bore.js";
+import { cloudflareProvider } from "./providers/cloudflared.js";
+import { customProvider } from "./providers/custom.js";
+/** The default provider used when none is configured. */
+export const DEFAULT_PROVIDER = "cloudflare";
+const PROVIDERS = [cloudflareProvider, boreProvider, customProvider];
+/** All known provider names, in display order. */
+export function listProviderNames() {
+    return PROVIDERS.map((p) => p.name);
+}
+/** Resolve a provider by name. Throws with a helpful message on unknown names. */
+export function getProvider(name) {
+    const found = PROVIDERS.find((p) => p.name === name);
+    if (!found) {
+        throw new Error(`unknown tunnel provider "${name}". Known providers: ${listProviderNames().join(", ")}.`);
+    }
+    return found;
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/tunnel/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/core/tunnel/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE7C,MAAM,SAAS,GAA8B,CAAC,kBAAkB,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC;AAEhG,kDAAkD;AAClD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACrD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,4BAA4B,IAAI,uBAAuB,iBAAiB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACzF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/tunnel/state.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tunnel runtime state — lets `brigade expose status` / `stop` (separate
+ * short-lived processes) find a tunnel started by a long-running
+ * `brigade expose`.
+ *
+ * Stored in the OS cache dir (NOT under ~/.brigade) because it is ephemeral
+ * machine-local coordination — the same reasoning `resolveOsCacheDir` uses for
+ * the gateway lock in convex mode, and it keeps `~/.brigade` clean under the
+ * strict-zero guard. The file is unlinked on clean shutdown; a stale file is
+ * reconciled by the pid liveness check in `readTunnelState`.
+ */
+export interface TunnelState {
+    /** Public URL without the token. */
+    url: string;
+    /** Public URL with `?token=` appended (when token-gated). */
+    urlWithToken: string;
+    /** Provider name. */
+    provider: string;
+    /** PID of the owning `brigade expose` process. */
+    pid: number;
+    /** Local auth-proxy port. */
+    proxyPort: number;
+    /** Gateway port being exposed. */
+    gatewayPort: number;
+    /** Whether a token gate is active. */
+    secured: boolean;
+    /** Epoch ms when the tunnel came up. */
+    startedAt: number;
+}
+/** Atomically persist tunnel state (tempfile + rename). */
+export declare function writeTunnelState(state: TunnelState): Promise<void>;
+/**
+ * Read tunnel state. Returns `undefined` when missing/unparseable. Does NOT
+ * verify liveness — callers that care use `isProcessAlive(state.pid)`.
+ */
+export declare function readTunnelState(): TunnelState | undefined;
+/** Remove the state file. Silent on missing file. */
+export declare function clearTunnelState(): Promise<void>;
+//# sourceMappingURL=state.d.ts.map

package/dist/core/tunnel/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/core/tunnel/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,2DAA2D;AAC3D,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAMxE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,WAAW,GAAG,SAAS,CAgBzD;AAED,qDAAqD;AACrD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAMtD"}

package/dist/core/tunnel/state.js

@@ -0,0 +1,57 @@
+/**
+ * Tunnel runtime state — lets `brigade expose status` / `stop` (separate
+ * short-lived processes) find a tunnel started by a long-running
+ * `brigade expose`.
+ *
+ * Stored in the OS cache dir (NOT under ~/.brigade) because it is ephemeral
+ * machine-local coordination — the same reasoning `resolveOsCacheDir` uses for
+ * the gateway lock in convex mode, and it keeps `~/.brigade` clean under the
+ * strict-zero guard. The file is unlinked on clean shutdown; a stale file is
+ * reconciled by the pid liveness check in `readTunnelState`.
+ */
+import * as fs from "node:fs";
+import * as fsAsync from "node:fs/promises";
+import * as path from "node:path";
+import { resolveOsCacheDir } from "../../config/paths.js";
+function tunnelStatePath() {
+    return path.join(resolveOsCacheDir(), "gateway-tunnel.json");
+}
+/** Atomically persist tunnel state (tempfile + rename). */
+export async function writeTunnelState(state) {
+    const file = tunnelStatePath();
+    await fsAsync.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await fsAsync.writeFile(tmp, JSON.stringify(state, null, 2), "utf8");
+    await fsAsync.rename(tmp, file);
+}
+/**
+ * Read tunnel state. Returns `undefined` when missing/unparseable. Does NOT
+ * verify liveness — callers that care use `isProcessAlive(state.pid)`.
+ */
+export function readTunnelState() {
+    try {
+        const raw = fs.readFileSync(tunnelStatePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.url === "string" &&
+            typeof parsed.provider === "string" &&
+            typeof parsed.pid === "number" &&
+            typeof parsed.proxyPort === "number") {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Remove the state file. Silent on missing file. */
+export async function clearTunnelState() {
+    try {
+        await fsAsync.unlink(tunnelStatePath());
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/core/tunnel/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/tunnel/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAqB1D,SAAS,eAAe;IACtB,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,qBAAqB,CAAC,CAAC;AAC/D,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAkB;IACvD,MAAM,IAAI,GAAG,eAAe,EAAE,CAAC;IAC/B,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,MAAM,GAAG,GAAG,GAAG,IAAI,MAAM,CAAC;IAC1B,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACrE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,EAAE,MAAM,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACvD,IACE,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;YAC9B,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;YACnC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;YAC9B,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,EACpC,CAAC;YACD,OAAO,MAAqB,CAAC;QAC/B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,qDAAqD;AACrD,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC;IAClE,CAAC;AACH,CAAC"}

package/dist/core/tunnel/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tunnel provider contract — the seam behind `brigade expose`.
+ *
+ * A provider's only job is to take a LOCAL port (where Brigade's
+ * token-checking auth-proxy is listening) and publish it on the internet,
+ * returning the public URL. Providers never touch the gateway directly: the
+ * auth-proxy already sits between the public URL and the (unauthenticated,
+ * loopback-only) gateway, so a provider just forwards bytes.
+ *
+ * Built-in providers live in `./providers/`:
+ *   - `cloudflare` — anonymous TryCloudflare quick tunnel (auto-managed binary)
+ *   - `bore`       — the OSS `bore` client (self-hostable relay)
+ *   - `custom`     — a user-supplied command template (`{port}` placeholder)
+ *
+ * Authoring a new provider = implement `TunnelProvider` and register it in
+ * `./registry.ts`. Everything else (auth-proxy, token gate, state file,
+ * lifecycle, CLI) is provider-agnostic.
+ */
+/** Options handed to a provider's `start()`. */
+export interface TunnelStartOptions {
+    /** Loopback host the auth-proxy is bound to (always `127.0.0.1`). */
+    localHost: string;
+    /** Port the auth-proxy is listening on — the tunnel points HERE, never at
+     *  the raw gateway port. */
+    localPort: number;
+    /** Self-hosted relay address (`bore` / `custom`). Provider-defined default
+     *  when omitted. */
+    relay?: string;
+    /** `custom` provider command template; `{port}` → `localPort`. */
+    command?: string;
+    /** Sink for provider log lines (binary stdout/stderr, status). */
+    onLog?: (line: string) => void;
+}
+/** A running tunnel. `stop()` must be idempotent. */
+export interface TunnelHandle {
+    /** Provider name that produced this handle. */
+    provider: string;
+    /** Public URL (scheme included), e.g. `https://lively-fox-42.trycloudflare.com`
+     *  or `http://bore.pub:41734`. Does NOT include the auth token. */
+    url: string;
+    /** Tear down the tunnel process/connection. Safe to call more than once. */
+    stop(): Promise<void>;
+}
+/** A tunnel backend. */
+export interface TunnelProvider {
+    /** Stable id used in config + the `--provider` flag. */
+    name: string;
+    /** Human label for status output. */
+    label: string;
+    /** Whether this provider can run right now on this machine (binary present,
+     *  command supplied, …). Cheap; called before `start()`. */
+    isAvailable(opts?: TunnelStartOptions): Promise<TunnelAvailability>;
+    /** Establish the tunnel. Rejects if the public URL can't be obtained. */
+    start(opts: TunnelStartOptions): Promise<TunnelHandle>;
+}
+export interface TunnelAvailability {
+    ok: boolean;
+    /** Operator-facing reason when `ok === false` (how to fix it). */
+    reason?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/tunnel/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/tunnel/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB;gCAC4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB;wBACoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB;uEACmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAwB;AACxB,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd;gEAC4D;IAC5D,WAAW,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpE,yEAAyE;IACzE,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/core/tunnel/types.js

@@ -0,0 +1,20 @@
+/**
+ * Tunnel provider contract — the seam behind `brigade expose`.
+ *
+ * A provider's only job is to take a LOCAL port (where Brigade's
+ * token-checking auth-proxy is listening) and publish it on the internet,
+ * returning the public URL. Providers never touch the gateway directly: the
+ * auth-proxy already sits between the public URL and the (unauthenticated,
+ * loopback-only) gateway, so a provider just forwards bytes.
+ *
+ * Built-in providers live in `./providers/`:
+ *   - `cloudflare` — anonymous TryCloudflare quick tunnel (auto-managed binary)
+ *   - `bore`       — the OSS `bore` client (self-hostable relay)
+ *   - `custom`     — a user-supplied command template (`{port}` placeholder)
+ *
+ * Authoring a new provider = implement `TunnelProvider` and register it in
+ * `./registry.ts`. Everything else (auth-proxy, token gate, state file,
+ * lifecycle, CLI) is provider-agnostic.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/tunnel/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/tunnel/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/infra/net/fetch-guard.d.ts

@@ -19,6 +19,20 @@
  */
 /** Default redirect cap — matches the upstream reference. */
 export declare const DEFAULT_MAX_REDIRECTS = 3;
+/** The injectable fetch primitive — production uses the global `fetch`. */
+export type FetchLike = typeof fetch;
+/**
+ * SSRF classification options. `allowPrivateNetwork` is a DANGEROUS opt-in for
+ * channels that legitimately talk to a LAN / private-IP host (e.g. a BlueBubbles
+ * macOS server on `192.168.x.x`). It relaxes the private/loopback/link-local IP
+ * checks — but NEVER the cloud-metadata block: `169.254.169.254`, the
+ * `metadata.*` hostnames, and the IPv6 metadata literal stay forbidden, so a
+ * redirect-to-metadata SSRF is still blocked even with private access on.
+ */
+export interface SsrfClassifyOptions {
+    /** Allow RFC1918 / loopback / link-local / ULA targets (cloud-metadata stays blocked). */
+    allowPrivateNetwork?: boolean;
+}
 /** Custom error thrown when an SSRF gate rejects a URL or resolved IP. */
 export declare class SsrfBlockedError extends Error {
     readonly url: string;
@@ -35,7 +49,7 @@ export declare class RedirectError extends Error {
  * obvious cases (literal `localhost`, IP-in-hostname, forbidden suffix)
  * so we don't even spend a DNS round-trip.
  */
-export declare function classifyHostnameSync(hostname: string): string | null;
+export declare function classifyHostnameSync(hostname: string, opts?: SsrfClassifyOptions): string | null;
 /**
  * Full SSRF check — sync hostname classify + DNS resolution + re-classify
  * every resolved A/AAAA record. A hostname like `attacker.com` passing
@@ -46,13 +60,21 @@ export declare function classifyHostnameSync(hostname: string): string | null;
  * URL is safe, returns an `SsrfBlockedError`-shaped reason string when
  * not. Caller throws.
  */
-export declare function classifyUrlForSsrf(rawUrl: string): Promise<string | null>;
+export declare function classifyUrlForSsrf(rawUrl: string, opts?: SsrfClassifyOptions): Promise<string | null>;
 export interface GuardedFetchOptions {
     method?: string;
     headers?: Record<string, string>;
     body?: RequestInit["body"];
     maxRedirects?: number;
     timeoutMs?: number;
+    /**
+     * DANGEROUS opt-in: allow private/LAN/loopback targets (cloud-metadata stays
+     * blocked on every hop). For channels that talk to an operator's own host
+     * (e.g. a BlueBubbles macOS server on `192.168.x.x`).
+     */
+    allowPrivateNetwork?: boolean;
+    /** Inject the network primitive (TEST SEAM). Defaults to the global `fetch`. */
+    fetchImpl?: FetchLike;
     /** Signal from the caller (e.g. agent turn cancel). Combined with the timeout signal. */
     signal?: AbortSignal;
     /** When set, retry transient failures (429 / 5xx / network) with exp-backoff. */