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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// The one place a user-supplied Home Assistant URL is allowed to become a socket.
//
// A home connection record carries a base URL the user typed. Our servers then
// dial it from inside the production network, on three different channels:
//
// 1. the state WebSocket wss://<host>/api/websocket
// 2. the MCP channel https://<host>/api/mcp (streamable HTTP)
// 3. plain REST probes https://<host>/api/config, /api/states, ...
//
// That is a textbook SSRF surface with a physical actuator behind it: the URL is
// attacker-controlled, the dial happens with our network identity, and the
// response is relayed back to the caller. Cloud metadata (169.254.169.254),
// loopback, and RFC1918 are all one string away.
//
// packages/home-bridge/src/url.js already normalizes the URL and knows which
// hostnames are unroutable, but a hostname check alone is not a security
// control: DNS decides what a name means, and it can mean 93.184.216.34 during
// validation and 169.254.169.254 a millisecond later at connect time. So this
// module resolves the name ONCE, rejects the connection if any resolved address
// is private, and hands back a dispatcher pinned to exactly those addresses.
// Every one of the three channels above takes that dispatcher, which is what
// closes the check-then-connect window rather than narrowing it.
//
// The primitives come from api/_lib/ssrf.js (the same guard the x402 proxy and
// the model fetcher use). This module is the home lane's spelling of them, so
// there is one function to call and no room to compose them wrongly.
import { ERR_CANNOT_CONNECT, ERR_INVALID_AUTH, normalizeBaseUrl } from '@three-ws/home-bridge';
import { Agent } from 'undici';
import { isPrivateAddress, pinnedAgent, resolvePublicHost, SsrfError } from './ssrf.js';
/**
* Refusal to dial a home. `code` is stable and safe to branch on; `message` is
* written for the person who typed the URL, because most refusals here are not
* attacks at all: they are somebody entering `homeassistant.local`, which is the
* single most common thing a real user types and is genuinely unroutable from a
* public server.
*/
export class HomeUrlError extends Error {
constructor(code, message) {
super(message);
this.name = 'HomeUrlError';
this.code = code;
}
}
/** Refusals that mean "your house is on a LAN", not "you are attacking us". */
export const REACHABILITY_CODES = new Set(['private_address', 'unroutable_host']);
/**
* The one way a private address is ever dialable, and it is off unless BOTH of
* these are true at once:
*
* * this process is not a Cloud Run revision (no `K_SERVICE`) and is not
* otherwise marked production (`NODE_ENV !== 'production'`), and
* * `HOME_ALLOW_LOCAL_INSTANCE=1` is set in the environment.
*
* It exists because the Home campaign's own instruction is "never mock Home
* Assistant, run one", and the way you run one is
* `docker run -p 8123:8123 ghcr.io/home-assistant/home-assistant:stable`, which
* lands on loopback. Without this seam no part of this surface could ever be
* exercised against a real instance on a developer machine, and the alternative
* people reach for (publishing their test Home Assistant, token and all, to the
* internet so it passes the guard) is far worse than the thing the guard
* prevents.
*
* Three properties keep it from being a hole. It is read once at module load, so
* no request can turn it on. It needs the flag, which is set nowhere. And the
* production check is POSITIVE: `K_SERVICE` is stamped on every Cloud Run
* revision by the runtime and cannot be unset from the service config, so the
* seam is off on the live service whatever else is configured.
*
* That last one is not a stylistic preference. The check was originally
* `NODE_ENV !== 'production'`, and `NODE_ENV` is not set on the three-ws-api
* service at all, so it read TRUE in production and the whole guard rested on
* one unset flag. A negative test for production is only as good as somebody
* remembering to set the variable it tests; `K_SERVICE` is set by the platform.
* api/cron/economy-tick.js uses the same signal for the same reason.
*/
const ALLOW_LOCAL_INSTANCE =
!process.env.K_SERVICE &&
process.env.NODE_ENV !== 'production' &&
process.env.HOME_ALLOW_LOCAL_INSTANCE === '1';
// The connect probe talks to a home that may be a residential uplink on the far
// side of a reverse proxy. Ten seconds is long enough for that and short enough
// that a black-holed address cannot pin a request for its whole lifetime.
const DIAL_TIMEOUT_MS = 10_000;
/**
* Validate a user-supplied Home Assistant base URL and resolve it to a pinned
* set of public addresses. Throws HomeUrlError on anything we refuse to dial.
*
* @param {string} rawBaseUrl the URL as the user typed it
* @param {object} [options]
* @param {boolean} [options.allowHttp] permit plain http. Off by default: a
* token that opens a building does not travel in clear text. Callers that dial
* a local instance from a developer machine pass it explicitly.
* @returns {Promise<{http: string, ws: string, origin: string, host: string, secure: boolean, addresses: Array<{address: string, family: number}>}>}
*/
export async function assertDialableHomeUrl(rawBaseUrl, { allowHttp = false } = {}) {
// A literal private address is checked before anything else, so that a
// redirect to http://169.254.169.254/ is reported as what it is rather than
// as a scheme complaint. The order matters for the operator reading the log,
// and for the caller branching on REACHABILITY_CODES.
const literalHost = literalHostOf(rawBaseUrl);
if (literalHost && !ALLOW_LOCAL_INSTANCE) {
const family = literalHost.includes(':') ? 6 : 4;
if (isPrivateAddress(literalHost, family)) {
throw new HomeUrlError(
'private_address',
`${literalHost} is a private address. A three.ws server on the public internet cannot route to it. Use your remote https URL, or connect the add-on so your house dials out to us instead.`,
);
}
}
let normalized;
try {
normalized = normalizeBaseUrl(rawBaseUrl, { requireSecure: !allowHttp && !ALLOW_LOCAL_INSTANCE });
} catch (err) {
throw new HomeUrlError('bad_url', err?.message || 'That is not a Home Assistant URL.');
}
const url = new URL(normalized.http);
let addresses;
try {
addresses = ALLOW_LOCAL_INSTANCE
? await resolveAnyHost(url.hostname)
: await resolvePublicHost(url.hostname);
} catch (err) {
throw toHomeUrlError(err, url.hostname);
}
return {
http: normalized.http,
ws: normalized.ws,
origin: normalized.origin,
host: url.hostname,
secure: normalized.secure,
addresses,
};
}
/**
* Resolve a host without the public-address requirement. Reached ONLY from the
* development seam above, and it still resolves and still pins: a local instance
* gets the same check-then-connect protection as a remote one, it is simply
* allowed to land on 127.0.0.1.
*/
async function resolveAnyHost(host) {
const { lookup } = await import('node:dns/promises');
const resolved = await lookup(host, { all: true });
return resolved.map((r) => ({ address: r.address, family: r.family }));
}
/**
* An undici dispatcher that will only ever open a socket to the addresses the
* validation above approved, for the host it approved them for.
*
* @param {{host: string, addresses: Array<{address: string, family: number}>}} pin
*/
export function homeDispatcher(pin) {
// `pinnedAgent` re-checks every address against isPrivateAddress, which is
// right for every real deployment and wrong for the local-instance seam: the
// guard has already resolved and approved 127.0.0.1, and a second filter here
// would drop it and report "no public address to connect to". Under the seam
// the pin still applies (the lookup only ever yields the approved addresses
// for the approved host); it simply skips the public-address requirement it
// was already exempted from upstream.
if (ALLOW_LOCAL_INSTANCE) return localPinnedAgent(pin.host, pin.addresses);
return pinnedAgent(pin.host, pin.addresses);
}
/**
* The seam's dispatcher: identical to `pinnedAgent` minus the public-address
* filter. Development only, and unreachable unless ALLOW_LOCAL_INSTANCE is on,
* which requires a non-production NODE_ENV.
*/
function localPinnedAgent(expectedHost, addresses) {
return new Agent({
connect: {
lookup(hostname, _opts, cb) {
if (hostname !== expectedHost) {
cb(new HomeUrlError('host_pin_mismatch', `unexpected connect host: ${hostname}`));
return;
}
cb(null, addresses.map((a) => ({ address: a.address, family: a.family })));
},
},
});
}
/**
* A pinned WebSocket to the home's state channel.
*
* Node's global WebSocket is undici's, and it honours a `dispatcher`, so the
* same pin that protects our HTTP calls protects the socket. Verified against a
* live Home Assistant: the pinned lookup is consulted for the socket handshake.
* This matters more than the HTTP path does, because the socket is the channel
* that stays open for the life of the connection.
*
* `home-assistant-js-websocket` takes this as its `createSocket` option, so the
* bridge runtime never constructs a raw socket of its own.
*
* @param {{host: string, addresses: Array<{address: string, family: number}>}} pin
* @param {string} wsUrl the ws:// or wss:// URL from assertDialableHomeUrl
* @param {string[]} [protocols]
*/
export function pinnedHomeSocket(pin, wsUrl, protocols = []) {
const target = new URL(wsUrl);
if (target.hostname !== pin.host) {
throw new HomeUrlError('host_pin_mismatch', 'Refusing to open a socket to a host we did not validate.');
}
return new WebSocket(wsUrl, { protocols, dispatcher: homeDispatcher(pin) });
}
/**
* SSRF-guarded fetch against a validated home.
*
* Redirects are followed by hand, and every hop is re-validated and re-pinned:
* a home that answers `302 Location: http://169.254.169.254/` is refused at the
* hop, not at the first request, which is the case a `redirect: 'follow'` fetch
* gets wrong silently.
*
* @param {{host: string, addresses: Array<{address: string, family: number}>}} pin
* @param {string} url an absolute URL on the pinned home
* @param {object} [init] fetch init, plus `timeoutMs` and `maxRedirects`
*/
export async function homeFetch(pin, url, init = {}) {
const { timeoutMs = DIAL_TIMEOUT_MS, maxRedirects = 2, fetchImpl = fetch, ...rest } = init;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
let current = new URL(url);
// A home reached over plain http (a developer instance, or the add-on relay's
// loopback leg) may follow its own same-origin redirects; everything else is
// held to https from the first hop on.
let currentPin = { ...pin, allowHttp: pin.allowHttp ?? pin.secure === false };
let dispatcher = homeDispatcher(currentPin);
let hops = 0;
try {
while (true) {
if (current.hostname !== currentPin.host) {
throw new HomeUrlError('host_pin_mismatch', 'Refusing to dial a host we did not validate.');
}
const res = await fetchImpl(current, {
...rest,
redirect: 'manual',
signal: controller.signal,
dispatcher,
});
const location = res.status >= 300 && res.status < 400 ? res.headers.get('location') : null;
if (!location) return res;
if (++hops > maxRedirects) {
throw new HomeUrlError('too_many_redirects', 'That home redirected too many times.');
}
const next = new URL(location, current);
// The redirect target is a fresh untrusted URL. It gets the whole
// validation again, including its own DNS resolution and its own pin.
// A same-origin hop inherits the origin's scheme allowance; a hop to
// anywhere else is held to https, because a home that bounces us to a
// new host in clear text is not a home we dial.
const revalidated = await assertDialableHomeUrl(next.origin, {
allowHttp: next.hostname === currentPin.host && next.protocol === 'http:' && currentPin.allowHttp === true,
});
currentPin = {
host: revalidated.host,
addresses: revalidated.addresses,
secure: revalidated.secure,
allowHttp: currentPin.allowHttp === true && next.hostname === currentPin.host,
};
await dispatcher.close().catch(() => {});
dispatcher = homeDispatcher(currentPin);
current = next;
}
} finally {
clearTimeout(timer);
await dispatcher.close().catch(() => {});
}
}
// The bare IP literal a URL points at, or null when it names a host. Parsed
// leniently (the user may have typed no scheme at all) because this runs before
// normalizeBaseUrl has had a chance to reject anything.
function literalHostOf(rawBaseUrl) {
const raw = String(rawBaseUrl ?? '').trim();
if (!raw) return null;
const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`;
let hostname;
try {
hostname = new URL(withScheme).hostname;
} catch {
return null;
}
const bare = hostname.replace(/^\[|\]$/g, '');
if (/^\d{1,3}(\.\d{1,3}){3}$/.test(bare)) return bare;
return bare.includes(':') ? bare : null;
}
function toHomeUrlError(err, hostname) {
if (!(err instanceof SsrfError)) {
return new HomeUrlError('dial_failed', `Could not reach ${hostname}.`);
}
if (err.code === 'private_address') {
return new HomeUrlError(
'private_address',
`${hostname} resolves to a private address, which a three.ws server on the public internet cannot route to. Use your remote https URL, or connect the add-on so your house dials out to us instead.`,
);
}
if (err.code === 'dns_timeout' || err.code === 'dns_failed') {
return new HomeUrlError(
'unroutable_host',
`${hostname} does not resolve from the public internet. A ".local" or LAN-only name only works from inside your own network.`,
);
}
return new HomeUrlError('bad_url', err.message);
}
/**
* A `createSocket` for `home-assistant-js-websocket` whose socket is pinned to
* the validated addresses.
*
* The library's own createSocket is one line away from being usable here: it
* builds `new WebSocket(url)` against the global, with no way to pass undici a
* dispatcher, so the state channel (the connection that stays open for hours)
* would be the one dial in the lane that a rebinding host could still redirect.
* The auth handshake below therefore mirrors the library's, and only the socket
* construction differs. It is verified against a real Home Assistant rather than
* assumed: see tests/home-security.test.js.
*
* Upstream would rather have the option than our copy, and asking for it is the
* right end state; until it exists this is the pin.
*
* @param {{host: string, addresses: Array<{address: string, family: number}>}} pin
* @returns {(options: {auth: object, setupRetry?: number}) => Promise<WebSocket>}
*/
export function pinnedHomeSocketFactory(pin) {
return homeSocketFactory(pin.host, () => homeDispatcher(pin));
}
/**
* The Home Assistant auth handshake over a socket built by `dispatcherFor`.
*
* Split out from `pinnedHomeSocketFactory` for one reason: the address decision
* and the handshake are different jobs, and only the handshake can be verified
* against a Home Assistant running on a developer machine (a pin will never
* carry a loopback address, correctly). Production never calls this directly;
* everything that dials a user's house goes through `pinnedHomeSocketFactory`,
* so `homeDispatcher` is always the thing choosing the addresses.
*
* @param {string} expectedHost the only host this factory will open a socket to
* @param {() => import('undici').Agent} dispatcherFor
*/
export function homeSocketFactory(expectedHost, dispatcherFor) {
return function createHomeSocket(options) {
const auth = options?.auth;
if (!auth) throw new HomeUrlError('bad_url', 'A Home Assistant auth object is required.');
const url = auth.wsUrl;
if (new URL(url).hostname !== expectedHost) {
throw new HomeUrlError('host_pin_mismatch', 'Refusing to open a socket to a host we did not validate.');
}
const connect = (triesLeft, resolve, reject) => {
const socket = new WebSocket(url, { dispatcher: dispatcherFor() });
let invalidAuth = false;
const onClose = () => {
socket.removeEventListener('close', onClose);
if (invalidAuth) return reject(ERR_INVALID_AUTH);
if (triesLeft === 0) return reject(ERR_CANNOT_CONNECT);
const next = triesLeft === -1 ? -1 : triesLeft - 1;
setTimeout(() => connect(next, resolve, reject), 1_000);
};
const onOpen = () => {
socket.send(JSON.stringify({ type: 'auth', access_token: auth.accessToken }));
};
const onMessage = (event) => {
const message = JSON.parse(event.data);
if (message.type === 'auth_invalid') {
invalidAuth = true;
socket.close();
return;
}
if (message.type !== 'auth_ok') return;
socket.removeEventListener('open', onOpen);
socket.removeEventListener('message', onMessage);
socket.removeEventListener('close', onClose);
socket.removeEventListener('error', onClose);
socket.haVersion = message.ha_version;
// 2022.9 and newer negotiate compressed state subscriptions; the
// library sends this immediately after auth and the graph builder
// depends on the reply shape it selects.
if (atLeastVersion(socket.haVersion, 2022, 9)) {
socket.send(JSON.stringify({ type: 'supported_features', id: 1, features: { coalesce_messages: 1 } }));
}
resolve(socket);
};
socket.addEventListener('open', onOpen);
socket.addEventListener('message', onMessage);
socket.addEventListener('close', onClose);
socket.addEventListener('error', onClose);
};
return new Promise((resolve, reject) => connect(options.setupRetry ?? 0, resolve, reject));
};
}
/** Home Assistant versions read "2024.6.1", sometimes with a suffix. */
function atLeastVersion(version, major, minor) {
const parts = String(version || '').split('.');
const [gotMajor, gotMinor] = [Number(parts[0]), Number(parts[1])];
if (!Number.isFinite(gotMajor) || !Number.isFinite(gotMinor)) return false;
return gotMajor > major || (gotMajor === major && gotMinor >= minor);
}
/**
* A pinned `fetch` for anything that takes one: the MCP SDK's streamable HTTP
* transport, and any other client that dials the home over plain HTTP.
*
* @param {{host: string, addresses: Array<{address: string, family: number}>, secure?: boolean}} pin
*/
export function pinnedHomeFetch(pin) {
return (url, init = {}) => homeFetch(pin, typeof url === 'string' ? url : url.toString(), init);
}