Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

7.5 KB
Raw Blame
/**
 * The handshake we run before we agree to store a home.
 *
 * Connecting is the one moment where we can tell the user something true and
 * specific about their instance, so we measure rather than assume: the Home
 * Assistant version, how many entities and areas it actually has, and whether
 * the optional `mcp_server` integration answers (and with how many tools). None
 * of that is inferred from the URL, the token, or a version string we hope is
 * there. If a capability is unknown we say unknown; we never claim one.
 *
 * The MCP probe is deliberately allowed to fail. `mcp_server` is an upgrade, not
 * a requirement: an instance without it is a perfectly good home, and the connect
 * screen offers the setting path rather than an error.
 */

import { connectHomeMcp, ERR, HomeBridge, HomeBridgeError, normalizeBaseUrl } from '@three-ws/home-bridge';

import {
	assertDialableHomeUrl,
	homeFetch,
	HomeUrlError,
	pinnedHomeFetch,
	pinnedHomeSocketFactory,
} from '../home-url-guard.js';

/** A house behind a slow tunnel is common; a hang is not. */
const CONNECT_TIMEOUT_MS = 15_000;
/** The optional channel gets a shorter leash: it must never dominate connect latency. */
const MCP_TIMEOUT_MS = 8_000;
/** The version lookup is a nicety: never let it hold up a connect. */
const CONFIG_TIMEOUT_MS = 5_000;

/**
 * Open a real connection, measure it, close it.
 *
 * @param {object} input
 * @param {string} input.baseUrl
 * @param {string} input.token
 * @param {number} [input.timeoutMs]
 * @returns {Promise<{ capabilities: object, graph: object }>}
 * @throws {HomeBridgeError} with the `ERR` vocabulary, so the route layer can
 *   map one table of codes instead of two.
 */
export async function verifyConnection({ baseUrl, token, timeoutMs = CONNECT_TIMEOUT_MS, pin = null }) {
	// Throws BAD_URL before anything opens a socket, which is what lets the UI
	// refuse a LAN address without a network call.
	const { http } = normalizeBaseUrl(baseUrl);

	// The SSRF guard, resolved HERE rather than trusted from the caller, so no
	// route can dial a house by forgetting to pass one. The hostname check the
	// connect route runs first is a courtesy to the user; this is the control.
	// A caller that already resolved the same URL passes its pin through so the
	// name is looked up once per connect rather than once per channel.
	const dial = pin || (await resolveDialPin(http));

	const bridge = new HomeBridge({ baseUrl: http, token, createSocket: pinnedHomeSocketFactory(dial) });
	let graph;
	try {
		graph = await withTimeout(
			bridge.connect(),
			timeoutMs,
			() => new HomeBridgeError(ERR.UNREACHABLE, `${http} did not answer within ${Math.round(timeoutMs / 1000)} seconds. If it is only on your home network, three.ws cannot route to it.`),
		);
	} catch (err) {
		bridge.close();
		throw err;
	}

	try {
		const states = bridge.states || {};
		const entityCount = Object.keys(states).length;
		const [mcp, config] = await Promise.all([
			probeMcp({ baseUrl: http, token, pin: dial }),
			readConfig({ baseUrl: http, token, pin: dial }),
		]);

		return {
			graph,
			capabilities: {
				websocket: true,
				entityCount,
				areaCount: graph?.rooms?.length ?? 0,
				floorCount: graph?.floors?.length ?? 0,
				macroCount: bridge.macros().length,
				// The socket already carries this: Home Assistant announces its
				// version in the WebSocket handshake, so a house whose state channel
				// opened has always told us. The /api/config read stays as a
				// fallback for the location name, but it must not be the only source
				// of the version: it is a second HTTP round trip with its own
				// failure modes, and when it fails the capability record advertises
				// `haVersion: null` for an instance we are actively talking to,
				// which is how a connected 2026.9.0 house came to report no version
				// at all.
				haVersion: bridge.haVersion ?? config.version,
				locationName: config.locationName,
				mcp: mcp.available,
				mcpToolCount: mcp.toolCount,
				mcpDetail: mcp.detail,
				measuredAt: new Date().toISOString(),
			},
		};
	} finally {
		bridge.close();
	}
}

/**
 * Home Assistant publishes its own version on the `zone.home`/`sun.sun`-style
 * state attributes only sporadically, but `persistent_notification` and the
 * config entry do not travel over subscribeEntities at all. The reliable place
 * on the state channel is any entity carrying the supervisor/core version
 * attribute; when nothing does, we return null rather than inventing a number.
 */
/**
 * Home Assistant's version, from the instance itself.
 *
 * Read from /api/config rather than scraped off entity attributes: a house full
 * of `update.*` entities publishes half a dozen `installed_version` attributes
 * belonging to add-ons and firmware, and picking one of those reports a
 * confident, wrong number to the user. An unreadable version is null, never a
 * guess, because the connect screen prints this verbatim.
 */
async function readConfig({ baseUrl, token, pin }) {
	try {
		const res = await homeFetch(pin, `${baseUrl}/api/config`, {
			headers: { authorization: `Bearer ${token}` },
			timeoutMs: CONFIG_TIMEOUT_MS,
		});
		if (!res.ok) return { version: null, locationName: null };
		const body = await res.json();
		return {
			version: typeof body?.version === 'string' ? body.version : null,
			locationName: typeof body?.location_name === 'string' ? body.location_name : null,
		};
	} catch {
		// The state channel already proved the instance is reachable and the token
		// works, so a failure here costs a version string, not the connection.
		return { version: null, locationName: null };
	}
}

async function probeMcp({ baseUrl, token, pin }) {
	try {
		const session = await withTimeout(
			connectHomeMcp({ baseUrl, token, fetchImpl: pinnedHomeFetch(pin) }),
			MCP_TIMEOUT_MS,
			() => new HomeBridgeError(ERR.NO_MCP, 'The MCP endpoint did not answer in time.'),
		);
		const toolCount = Array.isArray(session.tools) ? session.tools.length : 0;
		await session.close().catch(() => {});
		return { available: true, toolCount, detail: null };
	} catch (err) {
		// Not an error: the integration is simply not enabled, or this instance
		// does not expose it to this token. The connect screen offers the setting.
		return {
			available: false,
			toolCount: 0,
			detail: err instanceof HomeBridgeError && err.code === ERR.NO_MCP ? err.message : 'The Model Context Protocol Server integration did not answer.',
		};
	}
}

function withTimeout(promise, ms, makeError) {
	let timer;
	const timeout = new Promise((_resolve, reject) => {
		timer = setTimeout(() => reject(makeError()), ms);
	});
	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}

/**
 * Resolve a base URL to the addresses we are willing to dial, in this lane's
 * error vocabulary.
 *
 * A refusal here is nearly always a person typing their LAN address, not an
 * attack, so it comes back as UNREACHABLE with the sentence that tells them what
 * to do instead. The security property is the same either way: the name is
 * resolved on our side and the connection is pinned to what it resolved to, so a
 * public hostname pointing into RFC1918 (or flipping there after the check) is
 * refused rather than dialled from inside our network.
 */
async function resolveDialPin(http) {
	try {
		const dial = await assertDialableHomeUrl(http);
		return { host: dial.host, addresses: dial.addresses, secure: dial.secure };
	} catch (err) {
		if (!(err instanceof HomeUrlError)) throw err;
		const code = err.code === 'bad_url' ? ERR.BAD_URL : ERR.UNREACHABLE;
		throw new HomeBridgeError(code, err.message, err);
	}
}