@camstack/addon-cloudflare-tunnel 0.1.14 → 0.1.16

package/dist/cloudflare-tunnel.addon.js

@@ -1,79 +1,1130 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_crypto = require("node:crypto");
+let node_child_process = require("node:child_process");
+let _camstack_types = require("@camstack/types");
+let zod = require("zod");
+//#region src/cloudflare-tunnel.ts
+/**
+* Direct child_process.spawn() driver for the `cloudflared` binary.
+*
+* Why no IProcessManager: `IKernelServices` doesn't expose one to addons,
+* and ProcessConfig doesn't have an output-callback hook. We need stdout
+* to live-parse the Quick-tunnel public URL, so spawn directly.
+*
+* Lifecycle:
+*   - start() spawns the binary, attaches stdout/stderr line forwarders
+*     (every line → `this.logger.info` with `tags.topic='tunnel'`),
+*     watches for the `https://*.trycloudflare.com` line on Quick mode,
+*     and updates `this.endpoint.url` when found.
+*   - stop() sends SIGTERM, escalates to SIGKILL after 5s.
+*   - Auto-restart on unexpected exit, capped at 5 retries.
+*/
+var QUICK_URL_REGEX = /\bhttps:\/\/[a-z0-9-]+\.trycloudflare\.com\b/i;
+var CloudflareTunnelService = class CloudflareTunnelService {
+	id = "cloudflare-tunnel";
+	type = "cloudflare";
+	endpoint = null;
+	lastError;
+	child = null;
+	restartCount = 0;
+	intentionalStop = false;
+	static MAX_RESTARTS = 5;
+	static STOP_GRACE_MS = 5e3;
+	constructor(config, logger, eventBus) {
+		this.config = config;
+		this.logger = logger;
+		this.eventBus = eventBus;
+	}
+	async start() {
+		this.logger.info("Starting Cloudflare tunnel", {
+			meta: {
+				mode: this.config.mode,
+				localPort: this.config.localPort
+			},
+			tags: {
+				topic: "tunnel",
+				phase: "starting"
+			}
+		});
+		if (this.config.mode === "custom") {
+			if (!this.config.customTunnelToken) {
+				const err = /* @__PURE__ */ new Error("Custom tunnel not configured — run \"Enable\" from settings first");
+				this.logger.error(err.message, { tags: {
+					topic: "tunnel",
+					phase: "config-error"
+				} });
+				throw err;
+			}
+			if (!this.config.customHostname) {
+				const err = /* @__PURE__ */ new Error("Custom tunnel missing public hostname — re-run \"Enable\"");
+				this.logger.error(err.message, { tags: {
+					topic: "tunnel",
+					phase: "config-error"
+				} });
+				throw err;
+			}
+		}
+		if (this.child !== null) {
+			this.logger.warn("Cloudflare tunnel already running — refusing to spawn a duplicate", { tags: {
+				topic: "tunnel",
+				phase: "already-running"
+			} });
+			if (this.endpoint) return this.endpoint;
+		}
+		this.intentionalStop = false;
+		this.restartCount = 0;
+		this.lastError = void 0;
+		this.spawnChild();
+		const placeholderHost = this.config.mode === "custom" ? this.config.customHostname : "pending.trycloudflare.com";
+		this.endpoint = {
+			url: `https://${placeholderHost}`,
+			hostname: placeholderHost,
+			port: 443,
+			protocol: "https"
+		};
+		this.eventBus.emit({
+			id: (0, node_crypto.randomUUID)(),
+			timestamp: /* @__PURE__ */ new Date(),
+			source: {
+				type: "addon",
+				id: "cloudflare-tunnel"
+			},
+			category: _camstack_types.EventCategory.NetworkTunnelStarted,
+			data: { url: this.endpoint.url }
+		});
+		return this.endpoint;
+	}
+	async stop() {
+		this.logger.info("Stopping Cloudflare tunnel", {
+			meta: {
+				hadProcess: this.child !== null,
+				hadEndpoint: this.endpoint !== null
+			},
+			tags: {
+				topic: "tunnel",
+				phase: "stopping"
+			}
+		});
+		this.intentionalStop = true;
+		if (this.child !== null) {
+			const child = this.child;
+			this.child = null;
+			try {
+				child.kill("SIGTERM");
+				const killTimer = setTimeout(() => {
+					if (!child.killed) {
+						this.logger.warn("cloudflared did not exit within grace — SIGKILL", { tags: {
+							topic: "tunnel",
+							phase: "force-kill"
+						} });
+						try {
+							child.kill("SIGKILL");
+						} catch {}
+					}
+				}, CloudflareTunnelService.STOP_GRACE_MS);
+				await new Promise((resolve) => {
+					child.once("exit", () => {
+						clearTimeout(killTimer);
+						resolve();
+					});
+				});
+			} catch (err) {
+				this.logger.warn("cloudflared process stop reported an error", {
+					meta: { error: err instanceof Error ? err.message : String(err) },
+					tags: {
+						topic: "tunnel",
+						phase: "stop-error"
+					}
+				});
+			}
+		}
+		this.endpoint = null;
+		this.logger.info("Cloudflare tunnel stopped", { tags: {
+			topic: "tunnel",
+			phase: "stopped"
+		} });
+		this.eventBus.emit({
+			id: (0, node_crypto.randomUUID)(),
+			timestamp: /* @__PURE__ */ new Date(),
+			source: {
+				type: "addon",
+				id: "cloudflare-tunnel"
+			},
+			category: _camstack_types.EventCategory.NetworkTunnelStopped,
+			data: {}
+		});
+	}
+	getEndpoint() {
+		return this.endpoint;
+	}
+	getStatus() {
+		const status = {
+			connected: this.endpoint !== null,
+			endpoint: this.endpoint
+		};
+		if (this.lastError !== void 0) status.error = this.lastError;
+		return status;
+	}
+	spawnChild() {
+		const args = this.config.mode === "quick" ? [
+			"tunnel",
+			"--url",
+			`http://${this.config.localHost || "127.0.0.1"}:${this.config.localPort}`
+		] : [
+			"tunnel",
+			"run",
+			"--token",
+			this.config.customTunnelToken
+		];
+		let child;
+		try {
+			child = (0, node_child_process.spawn)("cloudflared", args, { stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+		} catch (err) {
+			this.logger.error("Failed to spawn cloudflared (binary missing?)", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "spawn-error"
+				}
+			});
+			throw err;
+		}
+		this.child = child;
+		this.logger.info("cloudflared spawned", {
+			meta: {
+				pid: child.pid,
+				args: args.join(" ")
+			},
+			tags: {
+				topic: "tunnel",
+				phase: "spawned"
+			}
+		});
+		const forwardLines = (stream, level) => {
+			let buf = "";
+			stream.setEncoding("utf8");
+			stream.on("data", (chunk) => {
+				buf += chunk;
+				const lines = buf.split("\n");
+				buf = lines.pop() ?? "";
+				for (const line of lines) {
+					if (!line.trim()) continue;
+					if (this.config.mode === "quick") {
+						const match = line.match(QUICK_URL_REGEX);
+						if (match && this.endpoint && this.endpoint.url !== match[0]) {
+							try {
+								const parsed = new URL(match[0]);
+								this.endpoint = {
+									url: match[0],
+									hostname: parsed.hostname,
+									port: parsed.port ? Number(parsed.port) : parsed.protocol === "https:" ? 443 : 80,
+									protocol: parsed.protocol === "https:" ? "https" : "http"
+								};
+							} catch {
+								this.endpoint = {
+									...this.endpoint,
+									url: match[0]
+								};
+							}
+							this.logger.info("Quick tunnel URL ready", {
+								meta: { url: match[0] },
+								tags: {
+									topic: "tunnel",
+									phase: "quick-url-ready"
+								}
+							});
+							this.eventBus.emit({
+								id: (0, node_crypto.randomUUID)(),
+								timestamp: /* @__PURE__ */ new Date(),
+								source: {
+									type: "addon",
+									id: "cloudflare-tunnel"
+								},
+								category: _camstack_types.EventCategory.NetworkTunnelStarted,
+								data: {
+									url: match[0],
+									updated: true
+								}
+							});
+						}
+					}
+					if (level === "warn") this.logger.warn(line, { tags: {
+						topic: "tunnel",
+						stream: "stderr"
+					} });
+					else this.logger.info(line, { tags: {
+						topic: "tunnel",
+						stream: "stdout"
+					} });
+				}
+			});
+		};
+		forwardLines(child.stdout, "info");
+		forwardLines(child.stderr, "info");
+		child.on("exit", (code, signal) => {
+			this.logger.info("cloudflared exited", {
+				meta: {
+					code,
+					signal,
+					intentional: this.intentionalStop
+				},
+				tags: {
+					topic: "tunnel",
+					phase: "exited"
+				}
+			});
+			if (this.child === child) this.child = null;
+			if (!this.intentionalStop && this.restartCount < CloudflareTunnelService.MAX_RESTARTS) {
+				this.restartCount++;
+				const backoffMs = Math.min(1e3 * Math.pow(2, this.restartCount), 3e4);
+				this.logger.warn("cloudflared crashed — restarting with backoff", {
+					meta: {
+						attempt: this.restartCount,
+						backoffMs
+					},
+					tags: {
+						topic: "tunnel",
+						phase: "restarting"
+					}
+				});
+				setTimeout(() => {
+					if (!this.intentionalStop) try {
+						this.spawnChild();
+					} catch (err) {
+						this.logger.error("cloudflared restart failed", {
+							meta: { error: err instanceof Error ? err.message : String(err) },
+							tags: {
+								topic: "tunnel",
+								phase: "restart-error"
+							}
+						});
+					}
+				}, backoffMs);
+			} else if (!this.intentionalStop) {
+				this.logger.error("cloudflared crashed too many times — giving up", {
+					meta: { restartCount: this.restartCount },
+					tags: {
+						topic: "tunnel",
+						phase: "gave-up"
+					}
+				});
+				this.endpoint = null;
+			}
+		});
+		child.on("error", (err) => {
+			this.logger.error("cloudflared process error", {
+				meta: { error: err.message },
+				tags: {
+					topic: "tunnel",
+					phase: "process-error"
+				}
+			});
+		});
+	}
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
+//#endregion
+//#region src/cloudflare-api.ts
+/**
+* Cloudflare API client — Tunnel + DNS Zones operations needed by the
+* Custom-tunnel flow.
+*
+* Auth: user-pasted API token (created once in the Cloudflare dashboard
+*       with `Account.Cloudflare Tunnel:Edit` + `Zone.DNS:Edit` scopes).
+*       The token is treated as opaque and never logged.
+*
+* Endpoints used:
+*   - GET  /accounts                                           — discover account id
+*   - GET  /zones                                              — list zones (interactive picker)
+*   - POST /accounts/{accountId}/cfd_tunnel                    — create tunnel
+*   - DELETE /accounts/{accountId}/cfd_tunnel/{id}             — delete tunnel
+*   - PUT  /accounts/{accountId}/cfd_tunnel/{id}/configurations — set ingress
+*   - POST /zones/{zoneId}/dns_records                         — create CNAME
+*   - DELETE /zones/{zoneId}/dns_records/{id}                  — cleanup
+*
+* The wrappers throw `CloudflareApiError` with the `code` + first `message`
+* from the response envelope so callers can surface actionable errors
+* (e.g. "Invalid API token" vs "Insufficient permissions").
+*/
+var API_BASE = "https://api.cloudflare.com/client/v4";
+var CloudflareApiError = class extends Error {
+	constructor(status, code, message, raw) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.raw = raw;
+		this.name = "CloudflareApiError";
+	}
 };
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/cloudflare-tunnel.addon.ts
-var cloudflare_tunnel_addon_exports = {};
-__export(cloudflare_tunnel_addon_exports, {
-  CloudflareTunnelAddon: () => CloudflareTunnelAddon
-});
-module.exports = __toCommonJS(cloudflare_tunnel_addon_exports);
-var import_types = require("@camstack/types");
-var CloudflareTunnelAddon = class extends import_types.BaseAddon {
-  constructor() {
-    super({ mode: "quick", namedTunnelToken: "", localPort: 3e3 });
-  }
-  async onInitialize() {
-    this.ctx.logger.info("Cloudflare Tunnel addon initialized");
-    return [{ capability: import_types.networkAccessCapability, provider: this }];
-  }
-  globalSettingsSchema() {
-    return this.schema({
-      sections: [{
-        id: "tunnel",
-        title: "Tunnel Settings",
-        fields: [
-          this.field({
-            type: "select",
-            key: "mode",
-            label: "Tunnel Mode",
-            description: "Quick mode creates a temporary public URL; Named mode uses a persistent named tunnel.",
-            default: "quick",
-            options: [
-              { value: "quick", label: "Quick Tunnel", description: "Temporary public URL, no Cloudflare account required" },
-              { value: "named", label: "Named Tunnel", description: "Persistent tunnel using a Cloudflare tunnel token" }
-            ]
-          }),
-          this.field({
-            type: "password",
-            key: "namedTunnelToken",
-            label: "Tunnel Token",
-            description: "Token from your Cloudflare Zero Trust dashboard (required for Named Tunnel mode)",
-            showToggle: true,
-            showWhen: { field: "mode", equals: "named" }
-          }),
-          this.field({
-            type: "number",
-            key: "localPort",
-            label: "Local Port",
-            description: "The local port that the tunnel will expose publicly",
-            min: 1,
-            max: 65535,
-            step: 1,
-            default: 3e3
-          })
-        ]
-      }]
-    });
-  }
+var CloudflareApi = class {
+	constructor(token) {
+		this.token = token;
+	}
+	/**
+	* Resolve the account behind the token.
+	*
+	* Cloudflare's `GET /accounts` requires `User:Read` (or a multi-account
+	* token); a token scoped narrowly to `Account → Cloudflare Tunnel:Edit
+	* + Zone → DNS:Edit` on a single account returns an empty list. We
+	* fall back to listing zones and reading `zone.account` — zones always
+	* carry account metadata so this works regardless of token scopes.
+	*/
+	async getAccount() {
+		try {
+			const accounts = await this.req("GET", "/accounts");
+			if (accounts.length > 0) return accounts[0];
+		} catch (err) {
+			if (!(err instanceof CloudflareApiError) || err.status !== 403) throw err;
+		}
+		const zones = await this.listZones();
+		for (const z of zones) if (z.account?.id) return {
+			id: z.account.id,
+			name: z.account.name ?? z.account.id
+		};
+		throw new CloudflareApiError(404, void 0, "Token cannot reach any account — make sure it has Account → Cloudflare Tunnel:Edit AND Zone → DNS:Edit");
+	}
+	/** List every zone the token can reach. */
+	async listZones() {
+		return this.req("GET", "/zones?per_page=50");
+	}
+	/**
+	* Look up an existing tunnel by name. Returns the first non-deleted
+	* match. Used by `enableCustom` to make tunnel creation idempotent —
+	* a previous attempt that crashed mid-flow may have left a
+	* 'camstack' tunnel behind; this lets us reuse / delete-and-recreate
+	* rather than failing with "tunnel with this name already exists".
+	*/
+	async findTunnelByName(accountId, name) {
+		const list = await this.req("GET", `/accounts/${accountId}/cfd_tunnel?name=${encodeURIComponent(name)}&is_deleted=false`);
+		return list.length > 0 ? list[0] : null;
+	}
+	/**
+	* Cloudflare's `GET /accounts/{id}/cfd_tunnel/{id}/token` returns the
+	* connector JWT for an existing tunnel. We use it when reusing a
+	* previously-created tunnel — the create-tunnel response embeds the
+	* token, but lookups by name only return metadata.
+	*/
+	async getTunnelToken(accountId, tunnelId) {
+		return this.req("GET", `/accounts/${accountId}/cfd_tunnel/${tunnelId}/token`);
+	}
+	async createTunnel(accountId, name) {
+		return this.req("POST", `/accounts/${accountId}/cfd_tunnel`, {
+			name,
+			tunnel_secret: Buffer.from((0, node_crypto.randomUUID)() + (0, node_crypto.randomUUID)()).toString("base64"),
+			config_src: "cloudflare"
+		});
+	}
+	async deleteTunnel(accountId, tunnelId) {
+		await this.req("DELETE", `/accounts/${accountId}/cfd_tunnel/${tunnelId}`);
+	}
+	async putTunnelConfiguration(accountId, tunnelId, ingress) {
+		await this.req("PUT", `/accounts/${accountId}/cfd_tunnel/${tunnelId}/configurations`, { config: { ingress } });
+	}
+	async createDnsRecord(zoneId, record) {
+		return this.req("POST", `/zones/${zoneId}/dns_records`, {
+			type: record.type,
+			name: record.name,
+			content: record.content,
+			proxied: record.proxied ?? true,
+			ttl: 1
+		});
+	}
+	async deleteDnsRecord(zoneId, recordId) {
+		await this.req("DELETE", `/zones/${zoneId}/dns_records/${recordId}`);
+	}
+	async req(method, path, body) {
+		const res = await fetch(`${API_BASE}${path}`, {
+			method,
+			headers: {
+				Authorization: `Bearer ${this.token}`,
+				"Content-Type": "application/json"
+			},
+			body: body === void 0 ? void 0 : JSON.stringify(body)
+		});
+		const text = await res.text();
+		let parsed;
+		try {
+			parsed = text ? JSON.parse(text) : void 0;
+		} catch {
+			parsed = void 0;
+		}
+		if (!res.ok || !parsed?.success) {
+			const firstError = parsed?.errors?.[0];
+			throw new CloudflareApiError(res.status, firstError?.code, firstError?.message ?? `Cloudflare API ${method} ${path} failed (${res.status})`, parsed);
+		}
+		return parsed.result;
+	}
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  CloudflareTunnelAddon
+//#endregion
+//#region src/cloudflare-actions.ts
+/**
+* Cloudflare Tunnel — customActions catalog.
+*
+* Exposes the server-managed flow as discrete steps that the admin-ui
+* settings form drives via `api.addons.custom.{query,mutate}({ addonId,
+* action, input })`:
+*
+*   validateToken  — probe the API token, return account name + id
+*                    (used by the settings form as an inline "Connect"
+*                    button; populates the zone picker on success).
+*
+*   listZones      — return the zones the token can reach
+*                    (drives the interactive "Domain" select in Custom
+*                    mode; this is the option-source for the new
+*                    `addon-action-select` form-builder field type).
+*
+*   enableCustom   — server-managed setup: create the tunnel via the
+*                    Cloudflare API, write the public CNAME, persist the
+*                    tunnel JWT, and switch the addon into 'custom' mode
+*                    so subsequent starts pick the persisted token.
+*
+*   disableCustom  — tear down: best-effort delete the DNS record + the
+*                    tunnel via the API and reset persisted state to the
+*                    Quick-tunnel default.
+*
+* Quick mode needs NO actions — `start`/`stop` on the network-access cap
+* is enough (cloudflared invents the public URL).
+*/
+var ZoneSchema = zod.z.object({
+	id: zod.z.string(),
+	name: zod.z.string(),
+	status: zod.z.string()
+});
+var cloudflareTunnelActions = (0, _camstack_types.defineCustomActions)({
+	validateToken: (0, _camstack_types.customAction)(zod.z.object({ token: zod.z.string().min(20) }), zod.z.object({
+		ok: zod.z.literal(true),
+		accountId: zod.z.string(),
+		accountName: zod.z.string()
+	}), { kind: "mutation" }),
+	listZones: (0, _camstack_types.customAction)(zod.z.object({ token: zod.z.string().min(20) }), zod.z.object({ zones: zod.z.array(ZoneSchema).readonly() }), { kind: "mutation" }),
+	enableCustom: (0, _camstack_types.customAction)(zod.z.object({
+		token: zod.z.string().min(20),
+		zoneId: zod.z.string().min(1),
+		hostname: zod.z.string().min(1),
+		localPort: zod.z.number().int().min(1).max(65535)
+	}), zod.z.object({
+		ok: zod.z.literal(true),
+		tunnelId: zod.z.string(),
+		hostname: zod.z.string()
+	}), { kind: "mutation" }),
+	disableCustom: (0, _camstack_types.customAction)(zod.z.object({}).optional(), zod.z.object({ ok: zod.z.literal(true) }), { kind: "mutation" }),
+	/**
+	* Bridge to the hub-only `local-network` cap so the settings UI can
+	* populate an `addon-action-select` field with operator-pinnable
+	* candidate addresses for the tunnel ingress. Returned shape matches
+	* what the form-builder's `addon-action-select` expects:
+	* `{ addresses: [{ value, label, description }] }`.
+	*/
+	listLocalAddresses: (0, _camstack_types.customAction)(zod.z.object({}).optional(), zod.z.object({ addresses: zod.z.array(zod.z.object({
+		value: zod.z.string(),
+		label: zod.z.string(),
+		description: zod.z.string()
+	})).readonly() }))
 });
+//#endregion
+//#region src/cloudflare-tunnel.addon.ts
+/**
+* Cloudflare Tunnel — exposes CamStack via Cloudflare's network.
+*
+* Two flows, both driven by a single `start()` button on the Remote
+* Access page:
+*
+*  • Quick (`mode='quick'`) — `start()` spawns `cloudflared tunnel --url
+*    http://localhost:<port>`; cloudflared invents a random
+*    `*.trycloudflare.com` URL and we surface it back to the operator.
+*
+*  • Custom (`mode='custom'`) — operator fills API token + zone +
+*    hostname in settings, then hits `start()`. The addon (server-side)
+*    auto-provisions: creates / reuses the tunnel, writes the CNAME,
+*    persists the JWT, then spawns `cloudflared tunnel run --token <jwt>`.
+*    Subsequent starts skip the provisioning step (token is cached).
+*
+* `listZones` is exposed as a customAction so the settings form's
+* `addon-action-select` zone picker can populate options live.
+*/
+var CloudflareTunnelAddon = class extends _camstack_types.BaseAddon {
+	service = null;
+	constructor() {
+		super({
+			mode: "quick",
+			localPort: 0,
+			localHost: "",
+			customApiToken: "",
+			customAccountId: "",
+			customTunnelId: "",
+			customTunnelToken: "",
+			customZoneId: "",
+			customZoneName: "",
+			customDnsRecordId: "",
+			customHostname: "camstack"
+		});
+	}
+	/**
+	* Resolve the local hub HTTP port the tunnel must front. Order:
+	*   1. Explicit `localPort` in addon config (> 0) — operator override.
+	*   2. `CAMSTACK_PORT` env (set by the bootstrap config manager).
+	*   3. `PORT` env (legacy / .env fallback).
+	*   4. 4000 — current CamStack default.
+	*/
+	resolveLocalPort() {
+		if (this.config.localPort && this.config.localPort > 0) return this.config.localPort;
+		const camstack = Number.parseInt(process.env["CAMSTACK_PORT"] ?? "", 10);
+		if (Number.isFinite(camstack) && camstack > 0) return camstack;
+		const port = Number.parseInt(process.env["PORT"] ?? "", 10);
+		if (Number.isFinite(port) && port > 0) return port;
+		return 4e3;
+	}
+	/**
+	* Ask the `local-network` cap for the preferred LAN address. Fallback
+	* is `127.0.0.1` when the cap is unreachable / not yet mounted.
+	* Cached for the duration of one provisioning call.
+	*/
+	async resolveLocalHost() {
+		try {
+			const preferred = await this.ctx.api.localNetwork?.getPreferred?.query();
+			if (preferred?.address) return preferred.address;
+		} catch (err) {
+			this.ctx.logger.warn("local-network getPreferred failed — falling back to localhost", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "localhost-fallback"
+				}
+			});
+		}
+		return "127.0.0.1";
+	}
+	async onInitialize() {
+		const localHost = await this.resolveLocalHost();
+		this.service = new CloudflareTunnelService({
+			...this.config,
+			localPort: this.resolveLocalPort(),
+			localHost
+		}, this.ctx.logger, this.ctx.eventBus);
+		this.ctx.logger.info("Cloudflare Tunnel addon initialized", { meta: {
+			mode: this.config.mode,
+			hasCustomToken: !!this.config.customTunnelToken
+		} });
+		return {
+			providers: [{
+				capability: _camstack_types.networkAccessCapability,
+				provider: {
+					start: () => this.handleStart(),
+					stop: () => this.requireService().stop(),
+					getStatus: () => this.requireService().getStatus()
+				}
+			}],
+			customActions: cloudflareTunnelActions,
+			actionHandlers: {
+				validateToken: async (input) => this.validateToken(input),
+				listZones: async (input) => this.listZones(input),
+				enableCustom: async (input) => this.enableCustom(input),
+				disableCustom: async () => this.disableCustom(),
+				listLocalAddresses: async () => this.listLocalAddresses()
+			}
+		};
+	}
+	async onShutdown() {
+		if (this.service) {
+			await this.service.stop().catch(() => void 0);
+			this.service = null;
+		}
+	}
+	async onConfigChanged() {
+		const wasRunning = this.service?.getStatus().connected === true;
+		if (this.service) await this.service.stop().catch(() => void 0);
+		const localHost = await this.resolveLocalHost();
+		this.service = new CloudflareTunnelService({
+			...this.config,
+			localPort: this.resolveLocalPort(),
+			localHost
+		}, this.ctx.logger, this.ctx.eventBus);
+		if (wasRunning) {
+			this.ctx.logger.info("config changed while running — re-spawning tunnel", { tags: {
+				topic: "tunnel",
+				phase: "config-reload"
+			} });
+			try {
+				await this.handleStart();
+			} catch (err) {
+				this.ctx.logger.error("config-reload restart failed", {
+					meta: { error: err instanceof Error ? err.message : String(err) },
+					tags: {
+						topic: "tunnel",
+						phase: "config-reload-error"
+					}
+				});
+			}
+		}
+	}
+	/**
+	* Start the tunnel, provisioning custom mode first if needed. This is
+	* the single button the orchestrator (Remote Access page) calls; the
+	* addon decides whether the underlying spawn is quick or token-based.
+	*/
+	async handleStart() {
+		if (this.config.mode === "custom" && (!this.config.customTunnelToken || !this.config.customHostname.includes("."))) {
+			this.ctx.logger.info("start: custom mode needs (re)provisioning", {
+				meta: {
+					hasToken: !!this.config.customTunnelToken,
+					hostname: this.config.customHostname
+				},
+				tags: {
+					topic: "tunnel",
+					phase: "auto-provision"
+				}
+			});
+			const token = this.config.customApiToken;
+			const zoneId = this.config.customZoneId;
+			const hostname = this.config.customHostname;
+			if (!token || !zoneId || !hostname) {
+				const missing = [
+					!token && "API token",
+					!zoneId && "zone",
+					!hostname && "hostname"
+				].filter(Boolean).join(", ");
+				const err = /* @__PURE__ */ new Error(`Custom tunnel needs: ${missing}. Fill the settings above first.`);
+				this.ctx.logger.error("start: custom mode config incomplete", {
+					meta: { missing },
+					tags: {
+						topic: "tunnel",
+						phase: "auto-provision-incomplete"
+					}
+				});
+				throw err;
+			}
+			await this.enableCustom({
+				token,
+				zoneId,
+				hostname,
+				localPort: this.resolveLocalPort()
+			});
+		}
+		return this.requireService().start();
+	}
+	requireService() {
+		if (!this.service) throw new Error("Cloudflare tunnel service not initialized");
+		return this.service;
+	}
+	async validateToken(input) {
+		this.ctx.logger.info("validateToken: probing API token", { tags: {
+			topic: "tunnel",
+			phase: "validate-token"
+		} });
+		const api = new CloudflareApi(input.token);
+		try {
+			const account = await api.getAccount();
+			this.ctx.logger.info("validateToken: token OK", {
+				meta: {
+					accountId: account.id,
+					accountName: account.name
+				},
+				tags: {
+					topic: "tunnel",
+					phase: "validate-token-ok"
+				}
+			});
+			return {
+				ok: true,
+				accountId: account.id,
+				accountName: account.name
+			};
+		} catch (err) {
+			this.ctx.logger.error("validateToken: probe failed", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "validate-token-error"
+				}
+			});
+			throw err;
+		}
+	}
+	/**
+	* Surface the local-network cap's interface list to the form-builder
+	* `addon-action-select` field so the operator can pin which address
+	* the tunnel ingress should target (Docker sidecar, multi-NIC host,
+	* etc). Empty `value` represents "auto — fall back to
+	* local-network.getPreferred()".
+	*/
+	async listLocalAddresses() {
+		try {
+			return { addresses: [{
+				value: "",
+				label: "Auto (use local-network preferred)",
+				description: "re-evaluated on every start"
+			}, ...((await this.ctx.api.localNetwork?.list?.query())?.interfaces ?? []).filter((i) => !i.internal && !i.address.startsWith("169.254.") && i.family === "IPv4").map((i) => ({
+				value: i.address,
+				label: `${i.name} — ${i.address}`,
+				description: `${i.kind}${i.preferred ? " · auto-preferred" : ""}`
+			}))] };
+		} catch (err) {
+			this.ctx.logger.warn("listLocalAddresses: local-network cap unreachable", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "list-local-addresses-error"
+				}
+			});
+			return { addresses: [{
+				value: "",
+				label: "Auto (use local-network preferred)",
+				description: "fallback"
+			}] };
+		}
+	}
+	async listZones(input) {
+		this.ctx.logger.info("listZones: fetching zones", { tags: {
+			topic: "tunnel",
+			phase: "list-zones"
+		} });
+		const api = new CloudflareApi(input.token);
+		try {
+			const zones = await api.listZones();
+			this.ctx.logger.info("listZones: returned zones", {
+				meta: { count: zones.length },
+				tags: {
+					topic: "tunnel",
+					phase: "list-zones-ok"
+				}
+			});
+			return { zones: zones.map((z) => ({
+				id: z.id,
+				name: z.name,
+				status: z.status
+			})) };
+		} catch (err) {
+			this.ctx.logger.error("listZones: fetch failed", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "list-zones-error"
+				}
+			});
+			throw err;
+		}
+	}
+	/**
+	* Server-managed custom-tunnel provisioning. Idempotent — reuses an
+	* existing 'camstack' tunnel by name and treats "DNS record already
+	* exists" as success. Persists tunnel id + JWT + DNS record id back
+	* into the addon config so subsequent `start()` calls skip provisioning.
+	*
+	* Kept exposed as a customAction (rather than purely internal) for
+	* scripting / manual re-provisioning from external clients; the UI
+	* now drives provisioning via the `start()` Start button instead.
+	*/
+	async enableCustom(input) {
+		this.ctx.logger.info("enableCustom: starting", {
+			meta: {
+				hostname: input.hostname,
+				zoneId: input.zoneId,
+				localPort: input.localPort
+			},
+			tags: {
+				topic: "tunnel",
+				phase: "enable-start"
+			}
+		});
+		const api = new CloudflareApi(input.token);
+		try {
+			const zone = (await api.listZones()).find((z) => z.id === input.zoneId);
+			if (!zone) throw new Error(`Selected zone ${input.zoneId} is not visible to this token`);
+			const subdomain = input.hostname.trim();
+			const subBare = subdomain.endsWith(`.${zone.name}`) ? subdomain.slice(0, -1 - zone.name.length) : subdomain;
+			const fqdn = subBare === "@" || subBare === "" ? zone.name : `${subBare}.${zone.name}`;
+			this.ctx.logger.info("enableCustom: resolved FQDN", {
+				meta: {
+					subBare,
+					zoneName: zone.name,
+					fqdn
+				},
+				tags: {
+					topic: "tunnel",
+					phase: "enable-fqdn"
+				}
+			});
+			const account = await api.getAccount();
+			this.ctx.logger.info("enableCustom: account resolved", {
+				meta: {
+					accountId: account.id,
+					accountName: account.name
+				},
+				tags: {
+					topic: "tunnel",
+					phase: "enable-account"
+				}
+			});
+			if (this.config.customDnsRecordId && this.config.customZoneId && this.config.customHostname && this.config.customHostname.toLowerCase() !== fqdn.toLowerCase()) {
+				this.ctx.logger.info("enableCustom: removing previous DNS record (hostname changed)", {
+					meta: {
+						from: this.config.customHostname,
+						to: input.hostname
+					},
+					tags: {
+						topic: "tunnel",
+						phase: "enable-dns-cleanup"
+					}
+				});
+				try {
+					await api.deleteDnsRecord(this.config.customZoneId, this.config.customDnsRecordId);
+				} catch (err) {
+					this.ctx.logger.warn("enableCustom: previous DNS cleanup failed (continuing)", {
+						meta: { error: err instanceof Error ? err.message : String(err) },
+						tags: {
+							topic: "tunnel",
+							phase: "enable-dns-cleanup-failed"
+						}
+					});
+				}
+			}
+			const TUNNEL_NAME = "camstack";
+			let tunnel = await api.findTunnelByName(account.id, TUNNEL_NAME);
+			if (tunnel) {
+				this.ctx.logger.info("enableCustom: reusing existing tunnel by name", {
+					meta: {
+						tunnelId: tunnel.id,
+						name: tunnel.name
+					},
+					tags: {
+						topic: "tunnel",
+						phase: "enable-tunnel-reused"
+					}
+				});
+				const token = await api.getTunnelToken(account.id, tunnel.id);
+				tunnel = {
+					...tunnel,
+					token
+				};
+			} else {
+				tunnel = await api.createTunnel(account.id, TUNNEL_NAME);
+				this.ctx.logger.info("enableCustom: tunnel created", {
+					meta: {
+						tunnelId: tunnel.id,
+						name: tunnel.name
+					},
+					tags: {
+						topic: "tunnel",
+						phase: "enable-tunnel-created"
+					}
+				});
+			}
+			const localHost = await this.resolveLocalHost();
+			await api.putTunnelConfiguration(account.id, tunnel.id, [{
+				hostname: fqdn,
+				service: `http://${localHost}:${input.localPort}`
+			}, { service: "http_status:404" }]);
+			this.ctx.logger.info("enableCustom: tunnel ingress configured", {
+				meta: {
+					hostname: fqdn,
+					localHost,
+					localPort: input.localPort
+				},
+				tags: {
+					topic: "tunnel",
+					phase: "enable-ingress"
+				}
+			});
+			let dns;
+			try {
+				dns = await api.createDnsRecord(input.zoneId, {
+					type: "CNAME",
+					name: fqdn,
+					content: `${tunnel.id}.cfargotunnel.com`,
+					proxied: true
+				});
+				this.ctx.logger.info("enableCustom: DNS record created", {
+					meta: {
+						recordId: dns.id,
+						hostname: fqdn
+					},
+					tags: {
+						topic: "tunnel",
+						phase: "enable-dns-created"
+					}
+				});
+			} catch (err) {
+				if (err instanceof Error && /already exists/i.test(err.message)) {
+					this.ctx.logger.warn("enableCustom: DNS record already exists — assuming it points at this tunnel", {
+						meta: { hostname: fqdn },
+						tags: {
+							topic: "tunnel",
+							phase: "enable-dns-existing"
+						}
+					});
+					dns = {
+						id: "",
+						name: fqdn,
+						content: "",
+						type: "CNAME"
+					};
+				} else throw err;
+			}
+			const patch = {
+				mode: "custom",
+				localPort: input.localPort,
+				customAccountId: account.id,
+				customTunnelId: tunnel.id,
+				customTunnelToken: tunnel.token,
+				customZoneId: input.zoneId,
+				customZoneName: zone.name,
+				customDnsRecordId: dns.id,
+				customHostname: fqdn
+			};
+			await this.updateGlobalSettings(patch);
+			this.ctx.logger.info("enableCustom: complete", {
+				meta: {
+					tunnelId: tunnel.id,
+					hostname: fqdn
+				},
+				tags: {
+					topic: "tunnel",
+					phase: "enable-complete"
+				}
+			});
+			return {
+				ok: true,
+				tunnelId: tunnel.id,
+				hostname: fqdn
+			};
+		} catch (err) {
+			this.ctx.logger.error("enableCustom: failed", {
+				meta: { error: err instanceof Error ? err.message : String(err) },
+				tags: {
+					topic: "tunnel",
+					phase: "enable-error"
+				}
+			});
+			throw err;
+		}
+	}
+	async disableCustom() {
+		const reset = {
+			mode: "quick",
+			localHost: "",
+			customAccountId: "",
+			customTunnelId: "",
+			customTunnelToken: "",
+			customZoneId: "",
+			customZoneName: "",
+			customDnsRecordId: "",
+			customHostname: "camstack",
+			customApiToken: ""
+		};
+		this.ctx.logger.info("disableCustom: reset to quick mode", { tags: {
+			topic: "tunnel",
+			phase: "disable"
+		} });
+		await this.updateGlobalSettings(reset);
+		return { ok: true };
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "mode",
+			title: "Tunnel Mode",
+			immediate: true,
+			fields: [this.field({
+				type: "select",
+				key: "mode",
+				label: "Mode",
+				description: "Quick: random *.trycloudflare.com URL, no account. Custom: server-managed named tunnel on your own domain (requires a Cloudflare account + API token). Hit Start on the Remote Access page to launch — Custom mode auto-provisions on first start. The local hub port is auto-detected from CAMSTACK_PORT / PORT env.",
+				default: "quick",
+				options: [{
+					value: "quick",
+					label: "Quick Tunnel",
+					description: "Temporary public URL, no account required"
+				}, {
+					value: "custom",
+					label: "Custom Domain",
+					description: "Persistent tunnel on your own zone"
+				}]
+			}), {
+				type: "addon-action-select",
+				key: "localHost",
+				label: "Local Address",
+				description: "Which local host address cloudflared should forward traffic to. \"Auto\" follows the local-network preferred interface — pin a specific address only when running multi-NIC or Docker sidecar setups.",
+				default: "",
+				addonId: "cloudflare-tunnel",
+				action: "listLocalAddresses",
+				mapOption: {
+					value: "value",
+					label: "label",
+					description: "description"
+				},
+				emptyResultsMessage: "No local addresses available — fix the local-network cap first."
+			}]
+		}, {
+			id: "custom",
+			title: "Custom Domain Setup",
+			immediate: true,
+			fields: [
+				{
+					type: "info",
+					key: "customHelp",
+					label: "How to get an API token",
+					format: "html",
+					content: "Create a token at <a href=\"https://dash.cloudflare.com/profile/api-tokens\">dash.cloudflare.com/profile/api-tokens</a>:<ul><li>Click <strong>Create Token</strong> → use the <em>Custom token</em> template.</li><li>Permissions: <code>Account → Cloudflare Tunnel → Edit</code> AND <code>Zone → DNS → Edit</code>.</li><li>Account Resources: <code>Include → your account</code>. Zone Resources: <code>Include → the zone</code> you want.</li><li>Continue → Create → copy the token, paste it below.</li></ul>",
+					variant: "info",
+					showWhen: {
+						field: "mode",
+						equals: "custom"
+					}
+				},
+				this.field({
+					type: "password",
+					key: "customApiToken",
+					label: "Cloudflare API Token",
+					description: "Used to provision + manage the tunnel.",
+					showToggle: true,
+					showWhen: {
+						field: "mode",
+						equals: "custom"
+					}
+				}),
+				{
+					type: "addon-action-select",
+					key: "customZoneId",
+					label: "Zone",
+					description: "Pick the Cloudflare zone (root domain) the tunnel will sit on.",
+					addonId: "cloudflare-tunnel",
+					action: "listZones",
+					paramsFromForm: { token: "customApiToken" },
+					refreshOn: ["customApiToken"],
+					mapOption: {
+						value: "id",
+						label: "name",
+						description: "status"
+					},
+					emptyParamsMessage: "Paste your API token above first.",
+					emptyResultsMessage: "Token has no zones with DNS:Edit permission.",
+					showWhen: {
+						field: "mode",
+						equals: "custom"
+					}
+				},
+				this.field({
+					type: "text",
+					key: "customHostname",
+					label: "Sub-domain",
+					description: "Sub-domain to prepend to the selected zone (e.g. \"camstack\" → camstack.yourdomain.com). Use \"@\" or empty for the apex.",
+					default: "camstack",
+					placeholder: "camstack",
+					showWhen: {
+						field: "mode",
+						equals: "custom"
+					}
+				})
+			]
+		}] });
+	}
+};
+//#endregion
+exports.CloudflareTunnelAddon = CloudflareTunnelAddon;
+exports.CloudflareTunnelService = CloudflareTunnelService;
+exports.cloudflareTunnelActions = cloudflareTunnelActions;
+exports.customActions = cloudflareTunnelActions;
+
 //# sourceMappingURL=cloudflare-tunnel.addon.js.map