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 relay protocol and its allowlist.
//
// This is the file that has to be right. The allowlist is the only thing
// standing between "three.ws can read your room graph and turn your lights on"
// and "three.ws can do anything to the machine your house runs on", so it is
// tested exhaustively and without a network: `protocol.js` is pure on purpose.
//
// The tests are organised by the question a reviewer would actually ask:
// what may go in, what may come out, what is refused, and can the two
// enforcement points (the relay in JavaScript, the integration in Python)
// disagree.
import { readFileSync } from 'node:fs';
import { describe, expect, it } from 'vitest';
import {
ALLOWED_EVENT_TYPES,
CODE,
DENIED_SERVICES,
DENIED_SERVICE_DOMAINS,
FRAME,
INBOUND_TYPES,
LIMITS,
MIN_AGENT_PROTOCOL,
OUTBOUND_TYPES,
PROTOCOL_VERSION,
allowlistManifest,
checkInbound,
checkOutbound,
decodeFrame,
encodeFrame,
frames,
negotiate,
} from '../services/home-relay/src/protocol.js';
import { constantTimeEquals, mintInstallToken, newRelayId, verifyInstallToken } from '../services/home-relay/src/token.js';
const KEY = 'k'.repeat(48);
describe('what the platform may send into a house', () => {
it('allows exactly the message types the client library emits', () => {
// Derived from home-assistant-js-websocket and packages/home-bridge, not
// from a wish list. If this set grows, something upstream started sending
// something new and that is a decision, not a detail.
expect([...OUTBOUND_TYPES].sort()).toEqual(
[
'call_service',
'config/area_registry/list',
'config/device_registry/list',
'config/entity_registry/list',
'config/floor_registry/list',
'get_config',
'get_states',
'ping',
'subscribe_entities',
'subscribe_events',
'supported_features',
'unsubscribe_events',
].sort(),
);
for (const type of OUTBOUND_TYPES) {
if (type === 'subscribe_events' || type === 'call_service') continue;
expect(checkOutbound({ type })).toEqual({ allowed: true });
}
});
it('refuses a type that is not on the list', () => {
for (const type of ['get_services', 'auth/current_user', 'config/auth/create', 'render_template', 'execute_script']) {
const verdict = checkOutbound({ type });
expect(verdict.allowed).toBe(false);
expect(verdict.code).toBe(CODE.NOT_ALLOWED);
expect(verdict.reason).toContain(type);
}
});
it('never carries an authentication frame, because auth never crosses the relay', () => {
expect(checkOutbound({ type: 'auth', access_token: 'x' }).allowed).toBe(false);
expect(OUTBOUND_TYPES).not.toContain('auth');
expect(INBOUND_TYPES).not.toContain('auth_required');
expect(INBOUND_TYPES).not.toContain('auth_ok');
});
it('limits subscribe_events to the events the room graph is built from', () => {
expect(checkOutbound({ type: 'subscribe_events', event_type: 'state_changed' })).toEqual({ allowed: true });
// The registry events are how a relayed home learns it was rearranged.
// Without them the graph freezes at whatever the house looked like when
// the socket opened, while a direct home keeps up: the same product
// behaving differently by transport, which is the bug this list fixes.
for (const event of ['area_registry_updated', 'device_registry_updated', 'entity_registry_updated', 'floor_registry_updated']) {
expect(checkOutbound({ type: 'subscribe_events', event_type: event })).toEqual({ allowed: true });
}
// A bare subscribe_events is a firehose of everything happening in the
// house, including other integrations' service calls.
expect(checkOutbound({ type: 'subscribe_events' }).allowed).toBe(false);
expect(checkOutbound({ type: 'subscribe_events', event_type: 'call_service' }).allowed).toBe(false);
// The permitted set stays a closed list, and every member of it is an
// announcement whose full result the relay already carries through a
// `config/*_registry/list` read.
expect(ALLOWED_EVENT_TYPES).toEqual([
'state_changed',
'area_registry_updated',
'device_registry_updated',
'entity_registry_updated',
'floor_registry_updated',
]);
});
it('allows ordinary device control, including the guarded ones', () => {
// The relay is not the safety gate. An unlock is allowed HERE and refused
// by packages/home-bridge/src/safety.js until a human says yes; conflating
// the two would mean a confirmed unlock could never run.
expect(checkOutbound({ type: 'call_service', domain: 'light', service: 'turn_on' })).toEqual({ allowed: true });
expect(checkOutbound({ type: 'call_service', domain: 'lock', service: 'unlock' })).toEqual({ allowed: true });
expect(checkOutbound({ type: 'call_service', domain: 'alarm_control_panel', service: 'alarm_disarm' })).toEqual({ allowed: true });
expect(checkOutbound({ type: 'call_service', domain: 'scene', service: 'turn_on' })).toEqual({ allowed: true });
});
it('refuses a service call that would own the machine rather than a device', () => {
for (const domain of DENIED_SERVICE_DOMAINS) {
const verdict = checkOutbound({ type: 'call_service', domain, service: 'anything' });
expect(verdict.allowed, `${domain} must be refused`).toBe(false);
expect(verdict.code).toBe(CODE.NOT_ALLOWED);
}
for (const full of DENIED_SERVICES) {
const [domain, service] = full.split('.');
expect(checkOutbound({ type: 'call_service', domain, service }).allowed, `${full} must be refused`).toBe(false);
}
});
it('refuses a call_service that is missing its target verb', () => {
expect(checkOutbound({ type: 'call_service', domain: 'light' }).code).toBe(CODE.MALFORMED);
expect(checkOutbound({ type: 'call_service', service: 'turn_on' }).code).toBe(CODE.MALFORMED);
expect(checkOutbound({ type: 'call_service', domain: 'light', service: 'turn_on', return_response: 'yes' }).code).toBe(CODE.MALFORMED);
});
it('refuses anything that is not an object', () => {
for (const value of [null, undefined, 'get_states', 42, ['get_states']]) {
expect(checkOutbound(value).allowed).toBe(false);
}
});
it('bounds an attacker-controlled type in the refusal message', () => {
const verdict = checkOutbound({ type: 'x'.repeat(500) });
expect(verdict.allowed).toBe(false);
expect(verdict.reason.length).toBeLessThan(200);
});
});
describe('what a house may send out', () => {
it('allows the three reply shapes Home Assistant answers in', () => {
expect(INBOUND_TYPES).toEqual(['result', 'event', 'pong']);
for (const type of INBOUND_TYPES) expect(checkInbound({ type })).toEqual({ allowed: true });
});
it('refuses anything else, including the auth handshake', () => {
for (const type of ['auth_required', 'auth_ok', 'auth_invalid', 'call_service']) {
expect(checkInbound({ type }).allowed, `${type} must not leave the house`).toBe(false);
}
});
});
describe('framing', () => {
it('round-trips every frame builder', () => {
const built = [
frames.hello('hr_x', { name: 'n', version: '1' }),
frames.helloOk('hr_x', { version: '1' }),
frames.helloErr(CODE.REVOKED, 'gone'),
frames.ping(1),
frames.pong(1),
frames.sessionOpen('s_1'),
frames.sessionReady('s_1', '2026.9.0'),
frames.sessionClose('s_1', CODE.OK, 'done'),
frames.ha('s_1', { type: 'get_states' }),
];
for (const frame of built) {
const decoded = decodeFrame(encodeFrame(frame));
expect(decoded.ok, JSON.stringify(frame)).toBe(true);
expect(decoded.frame).toEqual(frame);
}
});
it('refuses a frame from a different protocol version', () => {
const decoded = decodeFrame(JSON.stringify({ v: 99, t: FRAME.PING }));
expect(decoded.ok).toBe(false);
expect(decoded.code).toBe(CODE.MALFORMED);
});
it('refuses an unknown frame type, malformed JSON and a non-object', () => {
expect(decodeFrame(JSON.stringify({ v: 1, t: 'exec' })).ok).toBe(false);
expect(decodeFrame('{oh no').ok).toBe(false);
expect(decodeFrame(JSON.stringify([1, 2])).ok).toBe(false);
expect(decodeFrame(JSON.stringify({ v: 1, t: FRAME.HA, sid: 's_1' })).ok).toBe(false);
});
it('requires a well-formed session id on every session frame', () => {
for (const sid of ['', '../etc', 'a'.repeat(65), 42, null]) {
expect(decodeFrame(JSON.stringify({ v: 1, t: FRAME.SESSION_OPEN, sid })).ok, String(sid)).toBe(false);
}
expect(decodeFrame(JSON.stringify({ v: 1, t: FRAME.SESSION_OPEN, sid: 's_abc-123_X' })).ok).toBe(true);
});
it('refuses a frame larger than the cap without parsing it', () => {
const decoded = decodeFrame('x'.repeat(LIMITS.maxFrameBytes + 1));
expect(decoded.ok).toBe(false);
expect(decoded.message).toContain('exceeds');
});
});
describe('version negotiation', () => {
it('accepts the current version', () => {
expect(negotiate(PROTOCOL_VERSION)).toEqual({ ok: true, protocol: PROTOCOL_VERSION });
});
it('names the upgrade path when the integration is too old', () => {
const verdict = negotiate(MIN_AGENT_PROTOCOL - 1);
expect(verdict.ok).toBe(false);
expect(verdict.code).toBe(CODE.PROTOCOL_TOO_OLD);
expect(verdict.message).toMatch(/HACS/);
});
it('says the relay is behind rather than blaming the house', () => {
const verdict = negotiate(PROTOCOL_VERSION + 1);
expect(verdict.code).toBe(CODE.PROTOCOL_TOO_NEW);
expect(verdict.message).toMatch(/retrying/);
});
it('refuses a non-integer version', () => {
expect(negotiate('1').ok).toBe(false);
expect(negotiate(1.5).ok).toBe(false);
});
});
describe('install tokens', () => {
it('round-trips the claims the relay routes on', () => {
const relayId = newRelayId();
const token = mintInstallToken({ relayId, userId: 'u1', homeId: 'h1' }, KEY);
const verdict = verifyInstallToken(token, KEY);
expect(verdict.ok).toBe(true);
expect(verdict.claims).toMatchObject({ relayId, userId: 'u1', homeId: 'h1' });
});
it('refuses a tampered payload, so a token cannot be re-aimed at another house', () => {
const mine = mintInstallToken({ relayId: 'hr_mine', userId: 'u1', homeId: 'h1' }, KEY);
const [prefix, , mac] = mine.split('.');
const forgedPayload = Buffer.from(JSON.stringify({ rid: 'hr_yours', uid: 'u1', hid: 'h1', iat: 1 }))
.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
expect(verifyInstallToken(`${prefix}.${forgedPayload}.${mac}`, KEY).ok).toBe(false);
});
it('refuses a token signed with a different key', () => {
const token = mintInstallToken({ relayId: 'hr_x', userId: 'u', homeId: 'h' }, KEY);
expect(verifyInstallToken(token, 'j'.repeat(48)).ok).toBe(false);
});
it('refuses garbage without throwing', () => {
for (const value of ['', 'hr1.a', 'nope', null, undefined, 'hr1..']) {
expect(verifyInstallToken(value, KEY).ok).toBe(false);
}
});
it('insists on a real signing key rather than silently accepting a weak one', () => {
expect(() => mintInstallToken({ relayId: 'a', userId: 'b', homeId: 'c' }, 'short')).toThrow(/32 characters/);
});
it('mints relay ids that are unique and URL safe', () => {
const ids = new Set(Array.from({ length: 500 }, () => newRelayId()));
expect(ids.size).toBe(500);
for (const id of ids) expect(id).toMatch(/^hr_[A-Za-z0-9_-]{24}$/);
});
it('compares secrets without a length side channel', () => {
expect(constantTimeEquals('abc', 'abc')).toBe(true);
expect(constantTimeEquals('abc', 'abd')).toBe(false);
expect(constantTimeEquals('abc', 'a')).toBe(false);
expect(constantTimeEquals('', '')).toBe(true);
});
});
describe('the two enforcement points cannot drift', () => {
it('the generated allowlist.json still matches protocol.js', () => {
// The Python side inside the house reads this file rather than
// transcribing the rules. Regenerate with:
// node services/home-relay/scripts/gen-allowlist.mjs
const onDisk = JSON.parse(readFileSync(new URL('../services/home-relay/allowlist.json', import.meta.url), 'utf8'));
expect(onDisk).toEqual(allowlistManifest());
});
it('the copy shipped inside the Home Assistant integration is byte identical', () => {
const service = readFileSync(new URL('../services/home-relay/allowlist.json', import.meta.url), 'utf8');
const integration = readFileSync(
new URL('../home-assistant-integration/custom_components/three_ws/allowlist.json', import.meta.url),
'utf8',
);
expect(integration).toBe(service);
});
it('the integration enforces the same rules the relay does', () => {
// A structural check rather than a running Python one: every denied domain
// and every allowed type has to appear in the manifest the Python reads,
// because that file IS its rule set.
const manifest = allowlistManifest();
expect(manifest.outboundTypes).toEqual([...OUTBOUND_TYPES]);
expect(manifest.deniedServiceDomains).toEqual([...DENIED_SERVICE_DOMAINS]);
expect(manifest.limits.maxFrameBytes).toBe(LIMITS.maxFrameBytes);
});
});