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.

9.0 KB
Raw Blame
// /api/home, the caller's homes, and the door that adds one.
//
//   GET   list every home this account has connected, credential-free
//   POST  verify a Home Assistant instance for real, then store it
//
// The POST is the only place a Home Assistant long-lived access token ever
// enters the platform, which is why it does three things in a fixed order and
// refuses to reorder them:
//
//   1. Validate the URL shape BEFORE anything opens a socket, so a LAN address
//      is refused with an explanation instead of a fifteen second timeout.
//   2. Open a real connection and MEASURE the instance: version, entity count,
//      areas, floors, and whether the optional Model Context Protocol Server
//      integration answers. Nothing here is inferred from the URL or assumed
//      from a version string. A capability we did not observe is reported as
//      absent, never as present.
//   3. Only then encrypt the token and write the row. A house we could not
//      reach never becomes a stored credential, so the connection list cannot
//      fill up with rows that have never worked.
//
// A home whose `mcp_server` integration is not enabled is NOT an error at any
// point in that sequence. It is an ordinary home, it connects, it stores, and it
// comes back with `capabilities.mcp === false` plus the setting path the user
// would follow to turn it on. Treating a missing optional integration as a
// failure is how a connect screen tells a person their working house is broken.

import { normalizeBaseUrl } from '@three-ws/home-bridge';

import { logAudit } from '../_lib/audit.js';
import { requireCsrf } from '../_lib/csrf.js';
import { homeScopeRefusal, publicHome, resolveCaller } from '../_lib/home/access.js';
import { assertWithinLimit, HomeQuotaError, resolveHomeEntitlementsForUser } from '../_lib/home/entitlements.js';
import { homeError, homeFailure, HOME_ERR } from '../_lib/home/errors.js';
import { assertDialableHomeUrl, HomeUrlError } from '../_lib/home-url-guard.js';
import { createConnection, HOME_STATUS, listConnections } from '../_lib/home/store.js';
import { verifyConnection } from '../_lib/home/verify.js';
import { cors, error, json, method, rateLimited, readJson, wrap } from '../_lib/http.js';
import { limits } from '../_lib/rate-limit.js';

/** A label is a display string, not an identifier. Long enough for "Mum's house". */
const LABEL_MAX = 120;
/** Home Assistant long-lived tokens are JWTs of roughly 180 to 260 characters. */
const TOKEN_MAX = 4_000;

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	const caller = await resolveCaller(req, res);
	if (!caller) return error(res, 401, 'unauthorized', 'Sign in to see your homes.');
	// No single home to resolve here, so the OAuth scope is checked directly:
	// listing is home:read, connecting, pairing and pausing are home:act.
	const refused = homeScopeRefusal(caller, req.method === 'GET' ? 'read' : 'act');
	if (refused) return error(res, refused.status, refused.code, refused.message);

	if (req.method === 'GET') return handleList(req, res, caller);
	return handleConnect(req, res, caller);
});

async function handleList(req, res, caller) {
	const rl = await limits.homeRead(caller.userId);
	if (!rl.success) return rateLimited(res, rl, 'too many home reads, slow down');

	// Every home this account is a MEMBER of, which is not the same list as every
	// home it connected: a partner's house and a colleague's office belong here
	// too, each carrying the role this account holds in it so the UI can render a
	// guest's house as a guest's house without a second call per home.
	const homes = await listConnections(caller.userId);
	return json(res, 200, { homes: homes.map((h) => ({ ...publicHome(h), role: h.role })) });
}

async function handleConnect(req, res, caller) {
	// A cookie session needs CSRF; `requireCsrf` exempts bearer callers itself, so
	// the agent lane is not asked for a token it has no way to hold.
	if (!(await requireCsrf(req, res, caller.userId))) return;

	const rl = await limits.homeConnect(caller.userId);
	if (!rl.success) return rateLimited(res, rl, 'too many connection attempts, wait a moment');

	const body = await readJson(req, 16_000).catch(() => null);
	if (!body || typeof body !== 'object') {
		return homeError(res, homeFailure(HOME_ERR.VALIDATION, 'Send a JSON body with baseUrl and token.'));
	}

	const rawUrl = typeof body.baseUrl === 'string' ? body.baseUrl : body.base_url;
	const token = typeof body.token === 'string' ? body.token.trim() : '';
	const label = typeof body.label === 'string' ? body.label.trim().slice(0, LABEL_MAX) : '';

	if (!token) {
		return homeError(res, homeFailure(HOME_ERR.AUTH, 'A Home Assistant long-lived access token is required. Create one in your Home Assistant profile, under Security.'));
	}
	if (token.length > TOKEN_MAX) {
		return homeError(res, homeFailure(HOME_ERR.AUTH, 'That does not look like a Home Assistant access token.'));
	}

	let normalized;
	try {
		// requireSecure mirrors what a browser on an https page can actually reach.
		// Failing here, before any socket, is what turns "it just spins" into a
		// sentence the user can act on.
		normalized = normalizeBaseUrl(rawUrl, { requireSecure: true });
	} catch (err) {
		return homeError(res, err);
	}

	// The plan check happens BEFORE the socket, for the same reason the URL check
	// does: an account that cannot add another home should be told so in a
	// sentence, not after a fifteen second handshake with a house we are about to
	// refuse. Reconnecting a house this account already has is an UPDATE, not an
	// acquisition (createConnection upserts on the normalized URL), so it is
	// excluded from the count and a token rotation is never refused for being one
	// home too many.
	const existing = await listConnections(caller.userId);
	const isReconnect = existing.some((h) => h.base_url === normalized.http);
	if (!isReconnect) {
		const entitlements = await resolveHomeEntitlementsForUser(caller.userId);
		const active = existing.filter((h) => !h.deactivated_at).length;
		try {
			assertWithinLimit({ entitlements, dimension: 'homes', used: active });
		} catch (err) {
			if (!(err instanceof HomeQuotaError)) throw err;
			return json(res, err.status, {
				error: err.code,
				error_description: err.message,
				code: err.code,
				message: err.message,
				quota: {
					dimension: err.dimension,
					label: err.dimensionLabel,
					limit: err.limit,
					used: err.used,
					tier: err.tierId,
					upgrade: err.upgradePath,
				},
			});
		}
	}

	// Our servers cannot route to RFC1918 space at all, so a private address is a
	// certain failure we can name up front rather than a fifteen second wait
	// followed by a generic timeout.
	//
	// This is a DNS resolution, not a hostname test, and the difference is the
	// whole control. A hostname test passes `10-0-0-1.nip.io` and every other
	// public name that answers with an address inside our network, and our
	// servers would then dial it on three channels with our network identity. The
	// addresses this returns are the only ones the connect is allowed to reach,
	// and they are handed to verifyConnection so the name is resolved once rather
	// than once per channel (which is also where a rebinding host would slip in).
	let dial;
	try {
		dial = await assertDialableHomeUrl(normalized.http);
	} catch (err) {
		if (!(err instanceof HomeUrlError)) throw err;
		return homeError(res, homeFailure(
			err.code === 'bad_url' ? HOME_ERR.BAD_URL : HOME_ERR.UNREACHABLE,
			err.message,
		));
	}

	let measured;
	try {
		measured = await verifyConnection({
			baseUrl: normalized.http,
			token,
			pin: { host: dial.host, addresses: dial.addresses, secure: dial.secure },
		});
	} catch (err) {
		// Nothing is stored on a failed verify: a house we could not reach never
		// becomes a row, and the token never becomes ciphertext at rest.
		return homeError(res, err);
	}

	const home = await createConnection({
		userId: caller.userId,
		label: label || defaultLabel(normalized.http),
		baseUrl: normalized.http,
		token,
		capabilities: measured.capabilities,
		status: HOME_STATUS.CONNECTED,
		statusDetail: null,
	});

	logAudit({
		userId: caller.userId,
		action: 'connect_home',
		resourceId: home.id,
		// The home id is the identifying fact, and it is already in resourceId. The
		// base URL is deliberately absent: audit_log has its own 365 day window,
		// its own readers, and its user_id is SET NULL on account deletion rather
		// than removed, so an address written here outlives the account that owned
		// it. The token is not here, is not logged anywhere else, and must never be
		// added. See docs/home-privacy.md.
		meta: { transport: home.transport, entity_count: measured.capabilities.entityCount, mcp: measured.capabilities.mcp },
		req,
	});

	return json(res, 201, {
		home: publicHome(home),
		capabilities: measured.capabilities,
		graph: measured.graph,
	});
}

/** "home.example.com" beats "Untitled home" when the user did not name it. */
function defaultLabel(httpUrl) {
	try {
		return new URL(httpUrl).hostname;
	} catch {
		return 'Home';
	}
}