@camstack/addon-export-google 0.1.2 → 0.1.3

package/dist/export-google.addon.js

@@ -11379,6 +11379,28 @@ method(object({}), object({ blocks: array(CoreBlockSchema) }), { auth: "admin" }
 	content: string()
 })) }), { auth: "admin" });
 /**
+* Identity — preserves literal types for downstream inference.
+*
+* The constraint is `Record<string, unknown>` (not `CustomActionsSpec`) so
+* TypeScript does not widen each entry's literal `kind`/`auth` fields to
+* the broader unions declared on `CustomActionSpec`'s default generics.
+* Shape validity is enforced separately by the `customAction(...)` helper
+* whose return type is already a `CustomActionSpec<...>`.
+*/
+function defineCustomActions(spec) {
+	return spec;
+}
+function customAction(input, output, options) {
+	return {
+		input,
+		output,
+		kind: options?.kind ?? "query",
+		auth: options?.auth ?? "protected",
+		scope: options?.scope ?? { kind: "system" },
+		...options?.caller ? { caller: "required" } : {}
+	};
+}
+/**
 * `custom-model-registry` — collection cap exposing operator-registered
 * custom detection models. Each provider (today: `addon-model-studio`)
 * contributes a list of `CustomModelDescriptor`s; the hub auto-concatenates
@@ -36194,6 +36216,32 @@ DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
 //#endregion
+//#region src/custom-actions.ts
+/**
+* Google Home export — customActions catalog.
+*
+* One entry. The settings form's `type: 'button'` field dispatches through the
+* generic `api.addons.custom.mutate({ addonId, action, input })` channel, so a
+* button here costs no capability, no codegen and no framework publish train —
+* the catalog travels inside this addon's own bundle.
+*/
+var exportGoogleActions = defineCustomActions({ 
+/**
+* Re-scan the connected `network-access` providers and refresh the address
+* shown under the field.
+*
+* Deliberately NOT the same contract as `export-alexa`'s action of the same
+* shape: that one replaces a manual override when it is no longer detected,
+* because Alexa ROUTES on the value. Nothing routes on this one — it is what
+* the operator already pasted into Google's console — so this only fills the
+* field when it is empty. `filled` says whether it did.
+*/
+detectPublicHubUrl: customAction(object({}).optional(), object({
+	publicHubUrl: string(),
+	detectedPublicHubUrl: string(),
+	filled: boolean()
+}), { kind: "mutation" }) });
+//#endregion
 //#region src/google-home/trait-catalog.ts
 /**
 * The trait catalog — one ROW per camstack capability, and that row is the
@@ -36222,7 +36270,7 @@ var MB = 1024 * 1024;
 * Cameras. Google's `CameraStream` trait answers `GetCameraStream` with a
 * playable URL or a WebRTC signaling endpoint, and neither exists here yet, so
 * a camera would be declared and then fail every command. It is omitted rather
-* than declared — see docs/decisions/adr-0268-one-capability-is-one-trait-row-that-declares-reads-and-writes.md.
+* than declared — see docs/decisions/adr-0273-one-capability-is-one-trait-row-that-declares-reads-and-writes.md.
 */
 /**
 * The Google state a SUCCEEDED call establishes.
@@ -36971,9 +37019,262 @@ function buildGoogleOauthIntegration() {
 	};
 }
 //#endregion
+//#region src/public-hub-url.ts
+/**
+* The hub's public HTTPS origin — detected, never invented.
+*
+* `publicHubUrl` is the single operator-facing value in this addon, and the
+* three URLs pasted into the Google Home Developer Console (fulfillment,
+* authorization, token) are all rendered from it. Nothing ROUTES on it: Google
+* calls the fulfillment URL it was configured with. A wrong value therefore
+* fails at paste time, in the console, hours before anything here notices —
+* which is exactly why the field has to say where its content came from.
+*
+* ## Where the URL comes from
+*
+* The `network-access` capability, same source `addon-export-alexa` uses. It is
+* a codegen'd collection cap with `scope: 'system'`, so it is reachable
+* cross-process through `ctx.api` — unlike the `addons` core router, which a
+* forked addon calling `ctx.api.addons.*` would wait on forever.
+*
+* **Not** `CAMSTACK_HUB_PUBLIC_URL`. That variable answers a different
+* question: which origin the hub should mint its OWN media / model-distribution
+* links on, and it defaults to `https://127.0.0.1:4443`. It is routinely a
+* loopback or LAN address, and the backend's `publicHubUrl()` fallback is
+* localhost in dev. Google calls from its own cloud, so a LAN answer here is
+* worse than no answer — it produces three console URLs that look complete and
+* can never be reached.
+*
+* ## Why this is a second copy of Alexa's mechanism
+*
+* Alexa's lives in `packages/addon-export-alexa/src/export-alexa.addon.ts` as
+* private methods, and addons never import each other. The only shared home
+* would be `@camstack/types` or `@camstack/system` — both stay host-resolved in
+* an addon bundle (`tools/build/vite-lib.preset.ts`), so putting it there would
+* put this addon on the framework publish train and destroy the one property
+* that makes it attractive: `camstack deploy packages/addon-export-google` and
+* nothing else. The SOURCE and the POLICY are Alexa's; two behaviours diverge
+* on purpose and both are named below.
+*
+* ## Two deliberate divergences from Alexa
+*
+* 1. **Refresh never clobbers.** Alexa's `redetectPublicHubUrl` replaces a
+*    manual override whenever it is not among the detected endpoints — sound
+*    there, because the URL is baked into every Alexa-bound JWT as a routing
+*    claim and a stale one breaks routing. Here the value is what the operator
+*    already pasted into Google's console; silently rewriting it would leave
+*    the console and the hub disagreeing with no visible cause. Detection fills
+*    an EMPTY field and does nothing else.
+* 2. **A non-routable origin is dropped.** Alexa forwards whatever the cap
+*    reports. See {@link isPubliclyRoutableOrigin}.
+*/
+/** Trailing slashes off, surrounding space off. Nothing else is rewritten. */
+var normalisePublicHubUrl = (raw) => raw.trim().replace(/\/+$/, "");
+var LOOPBACK_HOSTS = [
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]",
+	"0.0.0.0"
+];
+/**
+* Whether Google's cloud could plausibly reach this origin.
+*
+* The `network-access` providers this hub ships (Cloudflare Tunnel, Tailscale
+* Funnel) publish public FQDNs, but the cap does not promise it: a provider is
+* free to report an HTTPS ingress on a private address. Defaulting the field to
+* one of those would hand the operator three console URLs that look finished
+* and can never answer — strictly worse than an empty field, because an empty
+* field is visibly unfinished.
+*
+* Conservative on purpose: only loopback, RFC1918, link-local, `.local` and
+* dotless hostnames are refused. A public tunnel hostname always has a dot.
+*/
+var isPubliclyRoutableOrigin = (origin) => {
+	let host;
+	try {
+		host = new URL(origin).hostname.toLowerCase();
+	} catch {
+		return false;
+	}
+	if (host.length === 0) return false;
+	if (LOOPBACK_HOSTS.includes(host)) return false;
+	if (host.startsWith("127.") || host.startsWith("169.254.")) return false;
+	if (host.startsWith("10.") || host.startsWith("192.168.")) return false;
+	if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return false;
+	if (host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".lan")) return false;
+	if (!host.includes(".")) return false;
+	return true;
+};
+/**
+* Every publicly routable HTTPS origin the `network-access` cap reports, in the
+* cap's own order, deduped. Empty when there is none — the caller leaves the
+* field alone rather than inventing a value.
+*/
+var detectPublicHubOrigins = async (deps) => {
+	const fromList = await originsFromListEndpoints(deps);
+	if (fromList.length > 0) return fromList;
+	const fromStatus = await originFromGetStatus(deps);
+	if (fromStatus.length > 0) return [fromStatus];
+	deps.logger.warn("export-google: no connected HTTPS external address — the public hub URL cannot be derived, so the Google console URLs stay unrendered. Set up remote access (Cloudflare Tunnel, Tailscale Funnel, …) and press \"Detect external address\", or type the URL on the settings form.");
+	return [];
+};
+var usableOrigins = (candidates, logger) => {
+	const out = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		if (candidate.protocol !== "https" || candidate.url.length === 0) continue;
+		const origin = normalisePublicHubUrl(candidate.url);
+		if (!isPubliclyRoutableOrigin(origin)) {
+			logger.info("export-google: ignored an external address that is not reachable from the internet — Google calls the fulfillment URL from its own cloud", { meta: { origin } });
+			continue;
+		}
+		out.add(origin);
+	}
+	return [...out];
+};
+var originsFromListEndpoints = async (deps) => {
+	try {
+		return usableOrigins(await deps.network.listEndpoints(), deps.logger);
+	} catch (err) {
+		deps.logger.debug("export-google: networkAccess.listEndpoints failed", { meta: { error: errMsg(err) } });
+		return [];
+	}
+};
+var originFromGetStatus = async (deps) => {
+	try {
+		const status = await deps.network.getStatus();
+		if (status === null || !status.connected || status.endpoint === null) return "";
+		return usableOrigins([status.endpoint], deps.logger)[0] ?? "";
+	} catch (err) {
+		deps.logger.debug("export-google: networkAccess.getStatus failed", { meta: { error: errMsg(err) } });
+		return "";
+	}
+};
+/**
+* Apply the default-not-override policy.
+*
+* The operator's value is never in the returned patch. Detection's own answer
+* always is, because the settings panel needs it to say "you set this one, and
+* a different one is detected".
+*/
+var resolvePublicHubUrl = (current, detected) => {
+	const detectedPublicHubUrl = detected[0] ?? "";
+	if (current.length > 0) return {
+		patch: { detectedPublicHubUrl },
+		publicHubUrl: current,
+		detectedPublicHubUrl,
+		defaulted: false
+	};
+	if (detectedPublicHubUrl.length === 0) return {
+		patch: { detectedPublicHubUrl },
+		publicHubUrl: "",
+		detectedPublicHubUrl,
+		defaulted: false
+	};
+	return {
+		patch: {
+			publicHubUrl: detectedPublicHubUrl,
+			detectedPublicHubUrl
+		},
+		publicHubUrl: detectedPublicHubUrl,
+		detectedPublicHubUrl,
+		defaulted: true
+	};
+};
+/** Which of the two authored the value currently in the field. */
+var publicHubUrlSource = (state) => {
+	if (state.publicHubUrl.length === 0) return "unset";
+	if (state.detectedPublicHubUrl.length > 0 && state.publicHubUrl === state.detectedPublicHubUrl) return "derived";
+	return "operator-set";
+};
+/**
+* The line under the field. A URL that appeared by itself with no provenance is
+* worse than a blank field: the operator cannot tell whether it is right.
+*/
+var buildPublicHubUrlNotice = (state) => {
+	switch (publicHubUrlSource(state)) {
+		case "derived": return {
+			variant: "info",
+			content: `Derived from remote access — ${state.publicHubUrl} is the first HTTPS address the network-access capability reports. Edit the field to override it; nothing here ever overwrites a value you set.`
+		};
+		case "operator-set": return {
+			variant: "info",
+			content: state.detectedPublicHubUrl.length > 0 ? `Set by you — ${state.publicHubUrl}. The address currently detected from remote access is ${state.detectedPublicHubUrl}; paste it in yourself if you want to switch, detection will not do it for you.` : `Set by you — ${state.publicHubUrl}. No external HTTPS address is detected right now, so nothing is corroborating it.`
+		};
+		case "unset": return state.detectedPublicHubUrl.length > 0 ? {
+			variant: "info",
+			content: `Detected external address: ${state.detectedPublicHubUrl}. Press "Detect external address" to fill the field with it.`
+		} : {
+			variant: "warning",
+			content: "No public HTTPS address detected — no network-access provider on this hub reports a connected HTTPS endpoint, so there is nothing to derive from. Set up remote access (Cloudflare Tunnel, Tailscale Funnel, …) and press \"Detect external address\", or type the URL yourself. An address on your own network will not do: Google calls this URL from its own cloud."
+		};
+	}
+};
+/**
+* The `device-export` setup block: the three console URLs plus the
+* linked-account count. All three come off the SAME origin, so they can never
+* disagree with each other.
+*/
+var buildConsoleSetup = (input) => {
+	const origin = normalisePublicHubUrl(input.publicHubUrl);
+	const linked = String(input.linkedAccounts);
+	if (origin.length === 0) return {
+		note: ["Set the public hub URL on the settings form first — every URL Google needs is derived from it.", buildPublicHubUrlNotice(input).content].join("\n"),
+		fields: [{
+			label: "Linked Google accounts",
+			value: linked
+		}]
+	};
+	return {
+		note: [
+			"In the Google Home Developer Console create a cloud-to-cloud integration, then paste these three URLs.",
+			"The integration stays in test mode: publishing requires Google certification, which a private hub cannot obtain.",
+			"This hub pushes nothing to Google — state is read by polling, so a change made outside the Home app appears on the next query, not instantly.",
+			buildPublicHubUrlNotice(input).content
+		].join("\n"),
+		fields: [
+			{
+				label: "Fulfillment URL",
+				value: `${origin}/addon/${input.addonId}/fulfillment`
+			},
+			{
+				label: "Authorization URL",
+				value: `${origin}/api/oauth2/authorize?integration=${input.addonId}`
+			},
+			{
+				label: "Token URL",
+				value: `${origin}/api/oauth2/token`
+			},
+			{
+				label: "Linked Google accounts",
+				value: linked
+			}
+		]
+	};
+};
+/**
+* Detect, apply the policy, persist, and say out loud what happened.
+*
+* Every branch here logs: a fill names the URL it picked and the source it came
+* from, and a miss that leaves the field empty says so rather than passing for
+* "never ran".
+*/
+var refreshPublicHubUrl = async (deps) => {
+	const detected = await deps.detect();
+	const resolution = resolvePublicHubUrl(deps.current().publicHubUrl, detected);
+	await deps.persist(resolution.patch);
+	if (resolution.defaulted) deps.logger.info("export-google: defaulted public hub URL to the detected external address", { meta: {
+		publicHubUrl: resolution.publicHubUrl,
+		source: "network-access"
+	} });
+	else if (resolution.publicHubUrl.length === 0) deps.logger.warn("export-google: public hub URL still unset after detection — the Google console URLs cannot be rendered until one is available", { meta: { detectedCount: detected.length } });
+	return resolution;
+};
+//#endregion
 //#region src/types.ts
 var DEFAULT_SETTINGS = {
 	publicHubUrl: "",
+	detectedPublicHubUrl: "",
 	exposed: [],
 	linkedAccounts: []
 };
@@ -37012,7 +37313,7 @@ var DEFAULT_SETTINGS = {
 *
 * Switches, dimmable lights, locks and covers — the non-camera fleet neither
 * `export-hap` nor `export-alexa` covers. Cameras are out of scope on purpose
-* (docs/decisions/adr-0268-one-capability-is-one-trait-row-that-declares-reads-and-writes.md); the trait catalog is the single place that
+* (docs/decisions/adr-0273-one-capability-is-one-trait-row-that-declares-reads-and-writes.md); the trait catalog is the single place that
 * decides, so widening scope is one row.
 */
 var ADDON_ID = "export-google";
@@ -37027,6 +37328,9 @@ var ExportGoogleAddon = class extends BaseAddon {
 			logger: this.ctx.logger
 		});
 		this.gateway = gateway;
+		this.detectPublicHubUrl().catch((err) => {
+			this.ctx.logger.warn("export-google: public hub URL auto-detect failed", { meta: { error: errMsg(err) } });
+		});
 		const deviceExportProvider = {
 			getStatus: async () => ({
 				linkState: this.config.linkedAccounts.length > 0 ? "linked" : "unlinked",
@@ -37066,26 +37370,93 @@ var ExportGoogleAddon = class extends BaseAddon {
 			}
 		}));
 		const oauthIntegrationProvider = { getDescriptor: async () => buildGoogleOauthIntegration() };
+		const offTunnelStarted = this.ctx.eventBus.subscribe({ category: EventCategory.NetworkTunnelStarted }, () => {
+			this.detectPublicHubUrl().catch((err) => {
+				this.ctx.logger.warn("export-google: public hub URL detect after tunnel connect failed", { meta: { error: errMsg(err) } });
+			});
+		});
+		this.ctx.addDisposer(async () => offTunnelStarted());
 		this.ctx.logger.info("export-google: initialized", { meta: {
 			exposedCount: this.config.exposed.length,
 			linkedAccounts: this.config.linkedAccounts.length,
 			publicHubUrlSet: this.config.publicHubUrl.length > 0,
 			willReportState: false
 		} });
-		return { providers: [
-			{
-				capability: deviceExportCapability,
-				provider: deviceExportProvider
-			},
-			{
-				capability: addonRoutesCapability,
-				provider: routeProvider
+		return {
+			providers: [
+				{
+					capability: deviceExportCapability,
+					provider: deviceExportProvider
+				},
+				{
+					capability: addonRoutesCapability,
+					provider: routeProvider
+				},
+				{
+					capability: oauthIntegrationCapability,
+					provider: oauthIntegrationProvider
+				}
+			],
+			customActions: exportGoogleActions,
+			actionHandlers: { detectPublicHubUrl: async () => this.detectPublicHubUrl() }
+		};
+	}
+	/** This addon's slice of `PublicHubUrlState`. */
+	publicHubUrlState() {
+		return {
+			publicHubUrl: this.config.publicHubUrl,
+			detectedPublicHubUrl: this.config.detectedPublicHubUrl
+		};
+	}
+	/**
+	* Adapter from the codegen'd `network-access` router onto the narrow reader
+	* `public-hub-url.ts` consumes. Fields are copied one by one rather than
+	* passed through, so the module never depends on the cap's wider shape and a
+	* test double for it needs no cast.
+	*/
+	networkAccessReader() {
+		return {
+			listEndpoints: async () => {
+				return (await this.ctx.api.networkAccess.listEndpoints.query({})).map((entry) => ({
+					url: entry.url,
+					protocol: entry.protocol
+				}));
 			},
-			{
-				capability: oauthIntegrationCapability,
-				provider: oauthIntegrationProvider
+			getStatus: async () => {
+				const status = await this.ctx.api.networkAccess.getStatus.query({});
+				return {
+					connected: status.connected,
+					endpoint: status.endpoint === null ? null : {
+						url: status.endpoint.url,
+						protocol: status.endpoint.protocol
+					}
+				};
 			}
-		] };
+		};
+	}
+	/**
+	* Refresh the detected address and DEFAULT the field to it when it is empty.
+	* Backs both the boot-time detect and the "Detect external address" button.
+	*
+	* Never replaces a value the operator set — that value is what they already
+	* pasted into the Google console, and rewriting it here would leave the two
+	* sides disagreeing with nothing on screen to say so.
+	*/
+	async detectPublicHubUrl() {
+		const resolution = await refreshPublicHubUrl({
+			current: () => this.publicHubUrlState(),
+			detect: () => detectPublicHubOrigins({
+				network: this.networkAccessReader(),
+				logger: this.ctx.logger
+			}),
+			persist: (patch) => this.updateGlobalSettings(patch),
+			logger: this.ctx.logger
+		});
+		return {
+			publicHubUrl: resolution.publicHubUrl,
+			detectedPublicHubUrl: resolution.detectedPublicHubUrl,
+			filled: resolution.defaulted
+		};
 	}
 	async onShutdown() {
 		this.gateway = null;
@@ -37155,65 +37526,54 @@ var ExportGoogleAddon = class extends BaseAddon {
 	* tool for a real credential anyway (docs/decisions/adr-0269-a-google-export-that-holds-no-google-credential.md).
 	*/
 	buildSetupBlock() {
-		const origin = this.config.publicHubUrl.replace(/\/+$/, "");
-		const linked = this.config.linkedAccounts.length;
-		if (origin.length === 0) return {
-			note: "Set the public hub URL on the settings form first — every URL Google needs is derived from it.",
-			fields: [{
-				label: "Linked Google accounts",
-				value: String(linked)
-			}]
-		};
-		return {
-			note: [
-				"In the Google Home Developer Console create a cloud-to-cloud integration, then paste these three URLs.",
-				"The integration stays in test mode: publishing requires Google certification, which a private hub cannot obtain.",
-				"This hub pushes nothing to Google — state is read by polling, so a change made outside the Home app appears on the next query, not instantly."
-			].join("\n"),
+		return buildConsoleSetup({
+			addonId: ADDON_ID,
+			...this.publicHubUrlState(),
+			linkedAccounts: this.config.linkedAccounts.length
+		});
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: ADDON_ID,
+			title: "Google Home export",
+			description: "Publishes switches, dimmable lights, locks and covers to Google Home. The hub answers Google directly — no cloud function, and no Google credential is stored here.",
+			columns: 1,
 			fields: [
 				{
-					label: "Fulfillment URL",
-					value: `${origin}/addon/${ADDON_ID}/fulfillment`
-				},
-				{
-					label: "Authorization URL",
-					value: `${origin}/api/oauth2/authorize?integration=${ADDON_ID}`
+					type: "info",
+					key: "__google-setup-banner",
+					label: "Setup overview",
+					variant: "info",
+					content: [
+						"This hub must be reachable from the public internet over HTTPS (Cloudflare Tunnel, Tailscale Funnel, …) — Google calls the fulfillment URL from its own cloud.",
+						"Create a cloud-to-cloud integration in the Google Home Developer Console, paste the three URLs from the Export panel, and link your account from the Home app.",
+						"Cameras are not exported, and state is not pushed: Google polls. Ask \"Hey Google, sync my devices\" after exposing something new."
+					].join("\n")
 				},
+				this.field({
+					type: "text",
+					key: "publicHubUrl",
+					label: "Public hub URL",
+					description: "HTTPS origin Google reaches this hub on, e.g. https://hub.example.com. Used to render the URLs you paste into the Google console. Left empty, it defaults to the first external address remote access reports; once it holds a value, nothing overwrites it.",
+					placeholder: "https://hub.example.com",
+					default: DEFAULT_SETTINGS.publicHubUrl
+				}),
 				{
-					label: "Token URL",
-					value: `${origin}/api/oauth2/token`
+					type: "info",
+					key: "__public-hub-url-source",
+					label: "Where this came from",
+					...buildPublicHubUrlNotice(this.publicHubUrlState())
 				},
 				{
-					label: "Linked Google accounts",
-					value: String(linked)
+					type: "button",
+					key: "__detect-public-hub-url",
+					label: "External address",
+					description: "Re-scan the connected remote-access providers. Fills the field above when it is empty; a value you set is left exactly as it is.",
+					buttonLabel: "Detect external address",
+					action: "detectPublicHubUrl",
+					variant: "default"
 				}
 			]
-		};
-	}
-	globalSettingsSchema() {
-		return this.schema({ sections: [{
-			id: ADDON_ID,
-			title: "Google Home export",
-			description: "Publishes switches, dimmable lights, locks and covers to Google Home. The hub answers Google directly — no cloud function, and no Google credential is stored here.",
-			columns: 1,
-			fields: [{
-				type: "info",
-				key: "__google-setup-banner",
-				label: "Setup overview",
-				variant: "info",
-				content: [
-					"This hub must be reachable from the public internet over HTTPS (Cloudflare Tunnel, Tailscale Funnel, …) — Google calls the fulfillment URL from its own cloud.",
-					"Create a cloud-to-cloud integration in the Google Home Developer Console, paste the three URLs from the Export panel, and link your account from the Home app.",
-					"Cameras are not exported, and state is not pushed: Google polls. Ask \"Hey Google, sync my devices\" after exposing something new."
-				].join("\n")
-			}, this.field({
-				type: "text",
-				key: "publicHubUrl",
-				label: "Public hub URL",
-				description: "HTTPS origin Google reaches this hub on, e.g. https://hub.example.com. Used to render the URLs you paste into the Google console.",
-				placeholder: "https://hub.example.com",
-				default: DEFAULT_SETTINGS.publicHubUrl
-			})]
 		}] });
 	}
 	/**

package/dist/export-google.addon.mjs

@@ -11375,6 +11375,28 @@ method(object({}), object({ blocks: array(CoreBlockSchema) }), { auth: "admin" }
 	content: string()
 })) }), { auth: "admin" });
 /**
+* Identity — preserves literal types for downstream inference.
+*
+* The constraint is `Record<string, unknown>` (not `CustomActionsSpec`) so
+* TypeScript does not widen each entry's literal `kind`/`auth` fields to
+* the broader unions declared on `CustomActionSpec`'s default generics.
+* Shape validity is enforced separately by the `customAction(...)` helper
+* whose return type is already a `CustomActionSpec<...>`.
+*/
+function defineCustomActions(spec) {
+	return spec;
+}
+function customAction(input, output, options) {
+	return {
+		input,
+		output,
+		kind: options?.kind ?? "query",
+		auth: options?.auth ?? "protected",
+		scope: options?.scope ?? { kind: "system" },
+		...options?.caller ? { caller: "required" } : {}
+	};
+}
+/**
 * `custom-model-registry` — collection cap exposing operator-registered
 * custom detection models. Each provider (today: `addon-model-studio`)
 * contributes a list of `CustomModelDescriptor`s; the hub auto-concatenates
@@ -36190,6 +36212,32 @@ DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
 //#endregion
+//#region src/custom-actions.ts
+/**
+* Google Home export — customActions catalog.
+*
+* One entry. The settings form's `type: 'button'` field dispatches through the
+* generic `api.addons.custom.mutate({ addonId, action, input })` channel, so a
+* button here costs no capability, no codegen and no framework publish train —
+* the catalog travels inside this addon's own bundle.
+*/
+var exportGoogleActions = defineCustomActions({ 
+/**
+* Re-scan the connected `network-access` providers and refresh the address
+* shown under the field.
+*
+* Deliberately NOT the same contract as `export-alexa`'s action of the same
+* shape: that one replaces a manual override when it is no longer detected,
+* because Alexa ROUTES on the value. Nothing routes on this one — it is what
+* the operator already pasted into Google's console — so this only fills the
+* field when it is empty. `filled` says whether it did.
+*/
+detectPublicHubUrl: customAction(object({}).optional(), object({
+	publicHubUrl: string(),
+	detectedPublicHubUrl: string(),
+	filled: boolean()
+}), { kind: "mutation" }) });
+//#endregion
 //#region src/google-home/trait-catalog.ts
 /**
 * The trait catalog — one ROW per camstack capability, and that row is the
@@ -36218,7 +36266,7 @@ var MB = 1024 * 1024;
 * Cameras. Google's `CameraStream` trait answers `GetCameraStream` with a
 * playable URL or a WebRTC signaling endpoint, and neither exists here yet, so
 * a camera would be declared and then fail every command. It is omitted rather
-* than declared — see docs/decisions/adr-0268-one-capability-is-one-trait-row-that-declares-reads-and-writes.md.
+* than declared — see docs/decisions/adr-0273-one-capability-is-one-trait-row-that-declares-reads-and-writes.md.
 */
 /**
 * The Google state a SUCCEEDED call establishes.
@@ -36967,9 +37015,262 @@ function buildGoogleOauthIntegration() {
 	};
 }
 //#endregion
+//#region src/public-hub-url.ts
+/**
+* The hub's public HTTPS origin — detected, never invented.
+*
+* `publicHubUrl` is the single operator-facing value in this addon, and the
+* three URLs pasted into the Google Home Developer Console (fulfillment,
+* authorization, token) are all rendered from it. Nothing ROUTES on it: Google
+* calls the fulfillment URL it was configured with. A wrong value therefore
+* fails at paste time, in the console, hours before anything here notices —
+* which is exactly why the field has to say where its content came from.
+*
+* ## Where the URL comes from
+*
+* The `network-access` capability, same source `addon-export-alexa` uses. It is
+* a codegen'd collection cap with `scope: 'system'`, so it is reachable
+* cross-process through `ctx.api` — unlike the `addons` core router, which a
+* forked addon calling `ctx.api.addons.*` would wait on forever.
+*
+* **Not** `CAMSTACK_HUB_PUBLIC_URL`. That variable answers a different
+* question: which origin the hub should mint its OWN media / model-distribution
+* links on, and it defaults to `https://127.0.0.1:4443`. It is routinely a
+* loopback or LAN address, and the backend's `publicHubUrl()` fallback is
+* localhost in dev. Google calls from its own cloud, so a LAN answer here is
+* worse than no answer — it produces three console URLs that look complete and
+* can never be reached.
+*
+* ## Why this is a second copy of Alexa's mechanism
+*
+* Alexa's lives in `packages/addon-export-alexa/src/export-alexa.addon.ts` as
+* private methods, and addons never import each other. The only shared home
+* would be `@camstack/types` or `@camstack/system` — both stay host-resolved in
+* an addon bundle (`tools/build/vite-lib.preset.ts`), so putting it there would
+* put this addon on the framework publish train and destroy the one property
+* that makes it attractive: `camstack deploy packages/addon-export-google` and
+* nothing else. The SOURCE and the POLICY are Alexa's; two behaviours diverge
+* on purpose and both are named below.
+*
+* ## Two deliberate divergences from Alexa
+*
+* 1. **Refresh never clobbers.** Alexa's `redetectPublicHubUrl` replaces a
+*    manual override whenever it is not among the detected endpoints — sound
+*    there, because the URL is baked into every Alexa-bound JWT as a routing
+*    claim and a stale one breaks routing. Here the value is what the operator
+*    already pasted into Google's console; silently rewriting it would leave
+*    the console and the hub disagreeing with no visible cause. Detection fills
+*    an EMPTY field and does nothing else.
+* 2. **A non-routable origin is dropped.** Alexa forwards whatever the cap
+*    reports. See {@link isPubliclyRoutableOrigin}.
+*/
+/** Trailing slashes off, surrounding space off. Nothing else is rewritten. */
+var normalisePublicHubUrl = (raw) => raw.trim().replace(/\/+$/, "");
+var LOOPBACK_HOSTS = [
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]",
+	"0.0.0.0"
+];
+/**
+* Whether Google's cloud could plausibly reach this origin.
+*
+* The `network-access` providers this hub ships (Cloudflare Tunnel, Tailscale
+* Funnel) publish public FQDNs, but the cap does not promise it: a provider is
+* free to report an HTTPS ingress on a private address. Defaulting the field to
+* one of those would hand the operator three console URLs that look finished
+* and can never answer — strictly worse than an empty field, because an empty
+* field is visibly unfinished.
+*
+* Conservative on purpose: only loopback, RFC1918, link-local, `.local` and
+* dotless hostnames are refused. A public tunnel hostname always has a dot.
+*/
+var isPubliclyRoutableOrigin = (origin) => {
+	let host;
+	try {
+		host = new URL(origin).hostname.toLowerCase();
+	} catch {
+		return false;
+	}
+	if (host.length === 0) return false;
+	if (LOOPBACK_HOSTS.includes(host)) return false;
+	if (host.startsWith("127.") || host.startsWith("169.254.")) return false;
+	if (host.startsWith("10.") || host.startsWith("192.168.")) return false;
+	if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return false;
+	if (host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".lan")) return false;
+	if (!host.includes(".")) return false;
+	return true;
+};
+/**
+* Every publicly routable HTTPS origin the `network-access` cap reports, in the
+* cap's own order, deduped. Empty when there is none — the caller leaves the
+* field alone rather than inventing a value.
+*/
+var detectPublicHubOrigins = async (deps) => {
+	const fromList = await originsFromListEndpoints(deps);
+	if (fromList.length > 0) return fromList;
+	const fromStatus = await originFromGetStatus(deps);
+	if (fromStatus.length > 0) return [fromStatus];
+	deps.logger.warn("export-google: no connected HTTPS external address — the public hub URL cannot be derived, so the Google console URLs stay unrendered. Set up remote access (Cloudflare Tunnel, Tailscale Funnel, …) and press \"Detect external address\", or type the URL on the settings form.");
+	return [];
+};
+var usableOrigins = (candidates, logger) => {
+	const out = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		if (candidate.protocol !== "https" || candidate.url.length === 0) continue;
+		const origin = normalisePublicHubUrl(candidate.url);
+		if (!isPubliclyRoutableOrigin(origin)) {
+			logger.info("export-google: ignored an external address that is not reachable from the internet — Google calls the fulfillment URL from its own cloud", { meta: { origin } });
+			continue;
+		}
+		out.add(origin);
+	}
+	return [...out];
+};
+var originsFromListEndpoints = async (deps) => {
+	try {
+		return usableOrigins(await deps.network.listEndpoints(), deps.logger);
+	} catch (err) {
+		deps.logger.debug("export-google: networkAccess.listEndpoints failed", { meta: { error: errMsg(err) } });
+		return [];
+	}
+};
+var originFromGetStatus = async (deps) => {
+	try {
+		const status = await deps.network.getStatus();
+		if (status === null || !status.connected || status.endpoint === null) return "";
+		return usableOrigins([status.endpoint], deps.logger)[0] ?? "";
+	} catch (err) {
+		deps.logger.debug("export-google: networkAccess.getStatus failed", { meta: { error: errMsg(err) } });
+		return "";
+	}
+};
+/**
+* Apply the default-not-override policy.
+*
+* The operator's value is never in the returned patch. Detection's own answer
+* always is, because the settings panel needs it to say "you set this one, and
+* a different one is detected".
+*/
+var resolvePublicHubUrl = (current, detected) => {
+	const detectedPublicHubUrl = detected[0] ?? "";
+	if (current.length > 0) return {
+		patch: { detectedPublicHubUrl },
+		publicHubUrl: current,
+		detectedPublicHubUrl,
+		defaulted: false
+	};
+	if (detectedPublicHubUrl.length === 0) return {
+		patch: { detectedPublicHubUrl },
+		publicHubUrl: "",
+		detectedPublicHubUrl,
+		defaulted: false
+	};
+	return {
+		patch: {
+			publicHubUrl: detectedPublicHubUrl,
+			detectedPublicHubUrl
+		},
+		publicHubUrl: detectedPublicHubUrl,
+		detectedPublicHubUrl,
+		defaulted: true
+	};
+};
+/** Which of the two authored the value currently in the field. */
+var publicHubUrlSource = (state) => {
+	if (state.publicHubUrl.length === 0) return "unset";
+	if (state.detectedPublicHubUrl.length > 0 && state.publicHubUrl === state.detectedPublicHubUrl) return "derived";
+	return "operator-set";
+};
+/**
+* The line under the field. A URL that appeared by itself with no provenance is
+* worse than a blank field: the operator cannot tell whether it is right.
+*/
+var buildPublicHubUrlNotice = (state) => {
+	switch (publicHubUrlSource(state)) {
+		case "derived": return {
+			variant: "info",
+			content: `Derived from remote access — ${state.publicHubUrl} is the first HTTPS address the network-access capability reports. Edit the field to override it; nothing here ever overwrites a value you set.`
+		};
+		case "operator-set": return {
+			variant: "info",
+			content: state.detectedPublicHubUrl.length > 0 ? `Set by you — ${state.publicHubUrl}. The address currently detected from remote access is ${state.detectedPublicHubUrl}; paste it in yourself if you want to switch, detection will not do it for you.` : `Set by you — ${state.publicHubUrl}. No external HTTPS address is detected right now, so nothing is corroborating it.`
+		};
+		case "unset": return state.detectedPublicHubUrl.length > 0 ? {
+			variant: "info",
+			content: `Detected external address: ${state.detectedPublicHubUrl}. Press "Detect external address" to fill the field with it.`
+		} : {
+			variant: "warning",
+			content: "No public HTTPS address detected — no network-access provider on this hub reports a connected HTTPS endpoint, so there is nothing to derive from. Set up remote access (Cloudflare Tunnel, Tailscale Funnel, …) and press \"Detect external address\", or type the URL yourself. An address on your own network will not do: Google calls this URL from its own cloud."
+		};
+	}
+};
+/**
+* The `device-export` setup block: the three console URLs plus the
+* linked-account count. All three come off the SAME origin, so they can never
+* disagree with each other.
+*/
+var buildConsoleSetup = (input) => {
+	const origin = normalisePublicHubUrl(input.publicHubUrl);
+	const linked = String(input.linkedAccounts);
+	if (origin.length === 0) return {
+		note: ["Set the public hub URL on the settings form first — every URL Google needs is derived from it.", buildPublicHubUrlNotice(input).content].join("\n"),
+		fields: [{
+			label: "Linked Google accounts",
+			value: linked
+		}]
+	};
+	return {
+		note: [
+			"In the Google Home Developer Console create a cloud-to-cloud integration, then paste these three URLs.",
+			"The integration stays in test mode: publishing requires Google certification, which a private hub cannot obtain.",
+			"This hub pushes nothing to Google — state is read by polling, so a change made outside the Home app appears on the next query, not instantly.",
+			buildPublicHubUrlNotice(input).content
+		].join("\n"),
+		fields: [
+			{
+				label: "Fulfillment URL",
+				value: `${origin}/addon/${input.addonId}/fulfillment`
+			},
+			{
+				label: "Authorization URL",
+				value: `${origin}/api/oauth2/authorize?integration=${input.addonId}`
+			},
+			{
+				label: "Token URL",
+				value: `${origin}/api/oauth2/token`
+			},
+			{
+				label: "Linked Google accounts",
+				value: linked
+			}
+		]
+	};
+};
+/**
+* Detect, apply the policy, persist, and say out loud what happened.
+*
+* Every branch here logs: a fill names the URL it picked and the source it came
+* from, and a miss that leaves the field empty says so rather than passing for
+* "never ran".
+*/
+var refreshPublicHubUrl = async (deps) => {
+	const detected = await deps.detect();
+	const resolution = resolvePublicHubUrl(deps.current().publicHubUrl, detected);
+	await deps.persist(resolution.patch);
+	if (resolution.defaulted) deps.logger.info("export-google: defaulted public hub URL to the detected external address", { meta: {
+		publicHubUrl: resolution.publicHubUrl,
+		source: "network-access"
+	} });
+	else if (resolution.publicHubUrl.length === 0) deps.logger.warn("export-google: public hub URL still unset after detection — the Google console URLs cannot be rendered until one is available", { meta: { detectedCount: detected.length } });
+	return resolution;
+};
+//#endregion
 //#region src/types.ts
 var DEFAULT_SETTINGS = {
 	publicHubUrl: "",
+	detectedPublicHubUrl: "",
 	exposed: [],
 	linkedAccounts: []
 };
@@ -37008,7 +37309,7 @@ var DEFAULT_SETTINGS = {
 *
 * Switches, dimmable lights, locks and covers — the non-camera fleet neither
 * `export-hap` nor `export-alexa` covers. Cameras are out of scope on purpose
-* (docs/decisions/adr-0268-one-capability-is-one-trait-row-that-declares-reads-and-writes.md); the trait catalog is the single place that
+* (docs/decisions/adr-0273-one-capability-is-one-trait-row-that-declares-reads-and-writes.md); the trait catalog is the single place that
 * decides, so widening scope is one row.
 */
 var ADDON_ID = "export-google";
@@ -37023,6 +37324,9 @@ var ExportGoogleAddon = class extends BaseAddon {
 			logger: this.ctx.logger
 		});
 		this.gateway = gateway;
+		this.detectPublicHubUrl().catch((err) => {
+			this.ctx.logger.warn("export-google: public hub URL auto-detect failed", { meta: { error: errMsg(err) } });
+		});
 		const deviceExportProvider = {
 			getStatus: async () => ({
 				linkState: this.config.linkedAccounts.length > 0 ? "linked" : "unlinked",
@@ -37062,26 +37366,93 @@ var ExportGoogleAddon = class extends BaseAddon {
 			}
 		}));
 		const oauthIntegrationProvider = { getDescriptor: async () => buildGoogleOauthIntegration() };
+		const offTunnelStarted = this.ctx.eventBus.subscribe({ category: EventCategory.NetworkTunnelStarted }, () => {
+			this.detectPublicHubUrl().catch((err) => {
+				this.ctx.logger.warn("export-google: public hub URL detect after tunnel connect failed", { meta: { error: errMsg(err) } });
+			});
+		});
+		this.ctx.addDisposer(async () => offTunnelStarted());
 		this.ctx.logger.info("export-google: initialized", { meta: {
 			exposedCount: this.config.exposed.length,
 			linkedAccounts: this.config.linkedAccounts.length,
 			publicHubUrlSet: this.config.publicHubUrl.length > 0,
 			willReportState: false
 		} });
-		return { providers: [
-			{
-				capability: deviceExportCapability,
-				provider: deviceExportProvider
-			},
-			{
-				capability: addonRoutesCapability,
-				provider: routeProvider
+		return {
+			providers: [
+				{
+					capability: deviceExportCapability,
+					provider: deviceExportProvider
+				},
+				{
+					capability: addonRoutesCapability,
+					provider: routeProvider
+				},
+				{
+					capability: oauthIntegrationCapability,
+					provider: oauthIntegrationProvider
+				}
+			],
+			customActions: exportGoogleActions,
+			actionHandlers: { detectPublicHubUrl: async () => this.detectPublicHubUrl() }
+		};
+	}
+	/** This addon's slice of `PublicHubUrlState`. */
+	publicHubUrlState() {
+		return {
+			publicHubUrl: this.config.publicHubUrl,
+			detectedPublicHubUrl: this.config.detectedPublicHubUrl
+		};
+	}
+	/**
+	* Adapter from the codegen'd `network-access` router onto the narrow reader
+	* `public-hub-url.ts` consumes. Fields are copied one by one rather than
+	* passed through, so the module never depends on the cap's wider shape and a
+	* test double for it needs no cast.
+	*/
+	networkAccessReader() {
+		return {
+			listEndpoints: async () => {
+				return (await this.ctx.api.networkAccess.listEndpoints.query({})).map((entry) => ({
+					url: entry.url,
+					protocol: entry.protocol
+				}));
 			},
-			{
-				capability: oauthIntegrationCapability,
-				provider: oauthIntegrationProvider
+			getStatus: async () => {
+				const status = await this.ctx.api.networkAccess.getStatus.query({});
+				return {
+					connected: status.connected,
+					endpoint: status.endpoint === null ? null : {
+						url: status.endpoint.url,
+						protocol: status.endpoint.protocol
+					}
+				};
 			}
-		] };
+		};
+	}
+	/**
+	* Refresh the detected address and DEFAULT the field to it when it is empty.
+	* Backs both the boot-time detect and the "Detect external address" button.
+	*
+	* Never replaces a value the operator set — that value is what they already
+	* pasted into the Google console, and rewriting it here would leave the two
+	* sides disagreeing with nothing on screen to say so.
+	*/
+	async detectPublicHubUrl() {
+		const resolution = await refreshPublicHubUrl({
+			current: () => this.publicHubUrlState(),
+			detect: () => detectPublicHubOrigins({
+				network: this.networkAccessReader(),
+				logger: this.ctx.logger
+			}),
+			persist: (patch) => this.updateGlobalSettings(patch),
+			logger: this.ctx.logger
+		});
+		return {
+			publicHubUrl: resolution.publicHubUrl,
+			detectedPublicHubUrl: resolution.detectedPublicHubUrl,
+			filled: resolution.defaulted
+		};
 	}
 	async onShutdown() {
 		this.gateway = null;
@@ -37151,65 +37522,54 @@ var ExportGoogleAddon = class extends BaseAddon {
 	* tool for a real credential anyway (docs/decisions/adr-0269-a-google-export-that-holds-no-google-credential.md).
 	*/
 	buildSetupBlock() {
-		const origin = this.config.publicHubUrl.replace(/\/+$/, "");
-		const linked = this.config.linkedAccounts.length;
-		if (origin.length === 0) return {
-			note: "Set the public hub URL on the settings form first — every URL Google needs is derived from it.",
-			fields: [{
-				label: "Linked Google accounts",
-				value: String(linked)
-			}]
-		};
-		return {
-			note: [
-				"In the Google Home Developer Console create a cloud-to-cloud integration, then paste these three URLs.",
-				"The integration stays in test mode: publishing requires Google certification, which a private hub cannot obtain.",
-				"This hub pushes nothing to Google — state is read by polling, so a change made outside the Home app appears on the next query, not instantly."
-			].join("\n"),
+		return buildConsoleSetup({
+			addonId: ADDON_ID,
+			...this.publicHubUrlState(),
+			linkedAccounts: this.config.linkedAccounts.length
+		});
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: ADDON_ID,
+			title: "Google Home export",
+			description: "Publishes switches, dimmable lights, locks and covers to Google Home. The hub answers Google directly — no cloud function, and no Google credential is stored here.",
+			columns: 1,
 			fields: [
 				{
-					label: "Fulfillment URL",
-					value: `${origin}/addon/${ADDON_ID}/fulfillment`
-				},
-				{
-					label: "Authorization URL",
-					value: `${origin}/api/oauth2/authorize?integration=${ADDON_ID}`
+					type: "info",
+					key: "__google-setup-banner",
+					label: "Setup overview",
+					variant: "info",
+					content: [
+						"This hub must be reachable from the public internet over HTTPS (Cloudflare Tunnel, Tailscale Funnel, …) — Google calls the fulfillment URL from its own cloud.",
+						"Create a cloud-to-cloud integration in the Google Home Developer Console, paste the three URLs from the Export panel, and link your account from the Home app.",
+						"Cameras are not exported, and state is not pushed: Google polls. Ask \"Hey Google, sync my devices\" after exposing something new."
+					].join("\n")
 				},
+				this.field({
+					type: "text",
+					key: "publicHubUrl",
+					label: "Public hub URL",
+					description: "HTTPS origin Google reaches this hub on, e.g. https://hub.example.com. Used to render the URLs you paste into the Google console. Left empty, it defaults to the first external address remote access reports; once it holds a value, nothing overwrites it.",
+					placeholder: "https://hub.example.com",
+					default: DEFAULT_SETTINGS.publicHubUrl
+				}),
 				{
-					label: "Token URL",
-					value: `${origin}/api/oauth2/token`
+					type: "info",
+					key: "__public-hub-url-source",
+					label: "Where this came from",
+					...buildPublicHubUrlNotice(this.publicHubUrlState())
 				},
 				{
-					label: "Linked Google accounts",
-					value: String(linked)
+					type: "button",
+					key: "__detect-public-hub-url",
+					label: "External address",
+					description: "Re-scan the connected remote-access providers. Fills the field above when it is empty; a value you set is left exactly as it is.",
+					buttonLabel: "Detect external address",
+					action: "detectPublicHubUrl",
+					variant: "default"
 				}
 			]
-		};
-	}
-	globalSettingsSchema() {
-		return this.schema({ sections: [{
-			id: ADDON_ID,
-			title: "Google Home export",
-			description: "Publishes switches, dimmable lights, locks and covers to Google Home. The hub answers Google directly — no cloud function, and no Google credential is stored here.",
-			columns: 1,
-			fields: [{
-				type: "info",
-				key: "__google-setup-banner",
-				label: "Setup overview",
-				variant: "info",
-				content: [
-					"This hub must be reachable from the public internet over HTTPS (Cloudflare Tunnel, Tailscale Funnel, …) — Google calls the fulfillment URL from its own cloud.",
-					"Create a cloud-to-cloud integration in the Google Home Developer Console, paste the three URLs from the Export panel, and link your account from the Home app.",
-					"Cameras are not exported, and state is not pushed: Google polls. Ask \"Hey Google, sync my devices\" after exposing something new."
-				].join("\n")
-			}, this.field({
-				type: "text",
-				key: "publicHubUrl",
-				label: "Public hub URL",
-				description: "HTTPS origin Google reaches this hub on, e.g. https://hub.example.com. Used to render the URLs you paste into the Google console.",
-				placeholder: "https://hub.example.com",
-				default: DEFAULT_SETTINGS.publicHubUrl
-			})]
 		}] });
 	}
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-export-google",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Google Home export — hub-side smart-home fulfillment (SYNC / QUERY / EXECUTE / DISCONNECT) for the non-camera fleet, served over the hub's own OAuth account link. No Google credential is stored, sent or required.",
   "keywords": [
     "camstack",