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 platform half of the dial-out relay: pairing, transport, revocation.
*
* A house that only exists on a LAN cannot be dialled from Cloud Run, so it
* dials us. `services/home-relay` terminates those sockets; the three.ws
* integration inside Home Assistant opens them; this module is everything
* three.ws itself needs to take part.
*
* Three responsibilities, and deliberately no more:
*
* 1. Pairing. Mint a short code, redeem it exactly once, hand back the
* relay address and this install's own token.
* 2. Transport. Turn a relay connection row into the `createSocket` that
* `HomeBridge` needs, so the runtime treats a relayed house exactly like a
* dialled one.
* 3. Revocation. Push a revoke to the relay so a disconnected home's socket
* drops immediately rather than at the next heartbeat.
*
* What this module never does is hold a Home Assistant credential. A relay
* home's `home_connections.access_token_enc` is empty, on purpose, and that is
* a product claim as much as a security one: connecting your house to three.ws
* this way hands us nothing that would open it if we were breached.
*/
import { createHash, randomInt, timingSafeEqual } from 'node:crypto';
import { createRelayTransport } from '@three-ws/home-bridge';
import { sql } from '../db.js';
import { HOME_STATUS } from './store.js';
// The relay verifies these tokens with the same code that mints them. Two
// copies of an HMAC scheme is exactly the drift the vendoring rules exist to
// prevent, and the API image is built with `COPY . .` from the repo root, so
// services/ is present at runtime and one copy is enough.
import { mintInstallToken, newRelayId } from '../../../services/home-relay/src/token.js';
/** How long a pairing code is worth typing. Pairing is an activity, not a state. */
export const PAIRING_TTL_MS = 10 * 60 * 1000;
/** Wrong guesses before the code dies. Turns 40 bits into unguessable. */
export const MAX_PAIRING_ATTEMPTS = 5;
/**
* Crockford base32 minus the characters people mistype into each other: no I,
* L, O or U. A code is read off one screen and typed into another, so the
* alphabet matters more than the entropy does.
*/
const CODE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
const CODE_LENGTH = 8;
/** Coded outcomes, so the endpoint and the integration agree on what happened. */
export const PAIRING_ERR = Object.freeze({
UNKNOWN_CODE: 'unknown_code',
EXPIRED: 'expired',
ALREADY_REDEEMED: 'already_redeemed',
TOO_MANY_ATTEMPTS: 'too_many_attempts',
PROTOCOL_TOO_OLD: 'protocol_too_old',
NOT_CONFIGURED: 'not_configured',
});
export class PairingError extends Error {
constructor(code, message, status) {
super(message);
this.name = 'PairingError';
this.code = code;
this.status = status;
}
}
/** The relay protocol version this build of the platform speaks. */
export const RELAY_PROTOCOL_VERSION = 1;
export const MIN_AGENT_PROTOCOL = 1;
/**
* Relay configuration, read at call time rather than at import time so a
* deploy that adds the variables does not need a code change to pick them up.
*/
export function relayConfig() {
return {
url: process.env.HOME_RELAY_URL || '',
serviceToken: process.env.HOME_RELAY_SERVICE_TOKEN || '',
signingKey: process.env.HOME_RELAY_SIGNING_KEY || '',
};
}
/**
* True when this deployment can offer the dial-out path at all. The connect UI
* branches on it: a platform without a relay says so plainly instead of showing
* a pairing code that could never be redeemed.
*/
export function isRelayConfigured() {
const { url, serviceToken, signingKey } = relayConfig();
return Boolean(url && serviceToken.length >= 32 && signingKey.length >= 32);
}
function requireRelay() {
const config = relayConfig();
if (!isRelayConfigured()) {
throw new PairingError(
PAIRING_ERR.NOT_CONFIGURED,
'This three.ws deployment has no home relay configured, so a home that is only on your network cannot be connected here yet.',
503,
);
}
return config;
}
// --------------------------------------------------------------------- codes
/**
* A pairing code, formatted for reading aloud and typing: `ABCD-EFGH`.
* `randomInt` is the CSPRNG, not `Math.random`: this is a credential, however
* short-lived.
*/
export function generatePairingCode() {
let raw = '';
for (let i = 0; i < CODE_LENGTH; i += 1) raw += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
return `${raw.slice(0, 4)}-${raw.slice(4)}`;
}
/**
* Codes arrive typed by a human: lowercase, spaced, hyphenated at will. Reduce
* every rendering to the one form the digest is taken over.
*/
export function normalizePairingCode(input) {
return String(input || '')
.toUpperCase()
.replace(/[^0-9A-Z]/g, '');
}
export function hashPairingCode(code) {
return createHash('sha256').update(`three.ws/home-pairing/${normalizePairingCode(code)}`).digest('hex');
}
// -------------------------------------------------------------------- pairing
/**
* Begin pairing a LAN-only house.
*
* Creates the `home_connections` row up front, with `transport: 'relay'`, an
* empty credential and a relay id, then mints a code that redeems into that
* one row and no other. Creating the row first is what makes the code safe to
* be short: it is not a ticket to "some house", it is a ticket to this one.
*
* @param {{ userId: string, label?: string }} input
* @returns {Promise<{ home: object, code: string, expiresAt: string, relayUrl: string }>}
*/
export async function startPairing({ userId, label }) {
const config = requireRelay();
if (!userId) throw new Error('startPairing: userId is required');
const relayId = newRelayId();
const cleanLabel = normalizeLabel(label) || 'My home';
// The direct path's createConnection() insists on a token, correctly: a
// dialled home without one is a bug. A relayed home without one is the
// design, so the relay row is written here instead, with the credential
// columns explicitly empty rather than absent.
const rows = await sql`
insert into home_connections
(user_id, label, base_url, access_token_enc, token_fingerprint,
transport, relay_id, capabilities, status, status_detail)
values
(${userId}, ${cleanLabel}, ${relayBaseUrl(relayId)}, '', '',
'relay', ${relayId}, '{}'::jsonb, ${HOME_STATUS.PENDING},
'Waiting for the three.ws integration in this home to pair.')
returning id, user_id, label, base_url, transport, relay_id, capabilities, status, status_detail, created_at
`;
const home = rows[0];
const code = generatePairingCode();
const expiresAt = new Date(Date.now() + PAIRING_TTL_MS);
await sql`
insert into home_relay_pairings (home_id, user_id, code_hash, relay_id, expires_at)
values (${home.id}, ${userId}, ${hashPairingCode(code)}, ${relayId}, ${expiresAt.toISOString()})
`;
return { home, code, expiresAt: expiresAt.toISOString(), relayUrl: config.url };
}
/**
* Mint a fresh code for a home that is already pending, without creating a
* second home. This is what "the code expired" recovers into: state 6 in the
* connect flow, one button, no orphaned rows.
*/
export async function refreshPairing({ homeId, userId }) {
const config = requireRelay();
const rows = await sql`
select id, relay_id, status
from home_connections
where id = ${homeId} and user_id = ${userId} and transport = 'relay' and revoked_at is null
`;
const home = rows[0];
if (!home) throw new PairingError(PAIRING_ERR.UNKNOWN_CODE, 'That home is not connected to this account.', 404);
// One live code per home: a stale one left redeemable would be a second,
// invisible way in.
await sql`delete from home_relay_pairings where home_id = ${homeId} and redeemed_at is null`;
const code = generatePairingCode();
const expiresAt = new Date(Date.now() + PAIRING_TTL_MS);
await sql`
insert into home_relay_pairings (home_id, user_id, code_hash, relay_id, expires_at)
values (${homeId}, ${userId}, ${hashPairingCode(code)}, ${home.relay_id}, ${expiresAt.toISOString()})
`;
return { code, expiresAt: expiresAt.toISOString(), relayUrl: config.url, relayId: home.relay_id };
}
/**
* Redeem a pairing code, from inside the house.
*
* This is the ONE unauthenticated endpoint in the home surface, because the
* caller is a Home Assistant install that has no three.ws session and never
* will. Everything that makes it safe is here: the code is single use under a
* conditional update (so two racing redemptions cannot both win), it is
* expiring, it is attempt-limited, and it only ever yields the one home it was
* minted for.
*
* @param {{ code: string, protocol?: number, agent?: object }} input
* @returns {Promise<{ relayId: string, relayUrl: string, installToken: string, label: string }>}
*/
export async function redeemPairing({ code, protocol, agent } = {}) {
const config = requireRelay();
const normalized = normalizePairingCode(code);
if (normalized.length !== CODE_LENGTH) {
throw new PairingError(PAIRING_ERR.UNKNOWN_CODE, 'That pairing code is not one three.ws issued.', 404);
}
if (protocol !== undefined && Number(protocol) < MIN_AGENT_PROTOCOL) {
throw new PairingError(
PAIRING_ERR.PROTOCOL_TOO_OLD,
`This three.ws integration speaks relay protocol ${protocol}; the platform needs ${MIN_AGENT_PROTOCOL} or newer. Update it in HACS.`,
426,
);
}
const hash = hashPairingCode(normalized);
const found = await sql`
select id, home_id, user_id, relay_id, expires_at, redeemed_at, attempts
from home_relay_pairings
where code_hash = ${hash}
`;
const pairing = found[0];
if (!pairing) {
throw new PairingError(PAIRING_ERR.UNKNOWN_CODE, 'That pairing code is not one three.ws issued.', 404);
}
if (pairing.redeemed_at) {
throw new PairingError(
PAIRING_ERR.ALREADY_REDEEMED,
'That pairing code has already been used. Generate a new one in three.ws.',
409,
);
}
if (pairing.attempts >= MAX_PAIRING_ATTEMPTS) {
throw new PairingError(
PAIRING_ERR.TOO_MANY_ATTEMPTS,
'That pairing code was entered incorrectly too many times and is no longer valid. Generate a new one in three.ws.',
429,
);
}
if (new Date(pairing.expires_at).getTime() <= Date.now()) {
throw new PairingError(PAIRING_ERR.EXPIRED, 'That pairing code expired. Generate a new one in three.ws.', 410);
}
// Single use, decided by the database rather than by this process: two
// integrations racing on the same code both reach here, and exactly one
// update matches.
const claimed = await sql`
update home_relay_pairings
set redeemed_at = now(), redeemed_by = ${JSON.stringify(describeAgent(agent))}::jsonb
where id = ${pairing.id} and redeemed_at is null
returning id
`;
if (!claimed.length) {
throw new PairingError(
PAIRING_ERR.ALREADY_REDEEMED,
'That pairing code has already been used. Generate a new one in three.ws.',
409,
);
}
const homes = await sql`
update home_connections
set status = ${HOME_STATUS.PENDING},
status_detail = 'Paired. Waiting for the first connection from this home.',
updated_at = now()
where id = ${pairing.home_id} and revoked_at is null
returning id, label, relay_id
`;
const home = homes[0];
if (!home) {
throw new PairingError(PAIRING_ERR.UNKNOWN_CODE, 'The home this code was for has been removed.', 404);
}
return {
relayId: home.relay_id,
relayUrl: config.url,
installToken: mintInstallToken(
{ relayId: home.relay_id, userId: pairing.user_id, homeId: home.id },
config.signingKey,
),
label: home.label,
protocol: RELAY_PROTOCOL_VERSION,
};
}
/**
* Count a wrong code against the pairing it was aimed at. A code that does not
* exist has nothing to count against, which is the honest asymmetry: guessing
* is bounded per live pairing, and there is nothing to bound when there is no
* live pairing to guess at.
*/
export async function recordFailedAttempt(code) {
const hash = hashPairingCode(code);
await sql`update home_relay_pairings set attempts = attempts + 1 where code_hash = ${hash} and redeemed_at is null`;
}
/** The live code for a home, if there is one, for the connect UI's countdown. */
export async function pendingPairing(homeId, userId) {
const rows = await sql`
select expires_at, redeemed_at, attempts, created_at
from home_relay_pairings
where home_id = ${homeId} and user_id = ${userId}
order by created_at desc
limit 1
`;
const row = rows[0];
if (!row || row.redeemed_at) return null;
if (new Date(row.expires_at).getTime() <= Date.now()) return { expired: true, expiresAt: row.expires_at };
return { expired: false, expiresAt: row.expires_at, attempts: row.attempts };
}
// ------------------------------------------------------------------ transport
/**
* The `transport` a relayed home's `HomeBridge` needs.
*
* Everything above this call is identical to the direct path. That is the whole
* design: `home-assistant-js-websocket` already takes a `createSocket`, so
* reaching a house through the relay is a socket factory and not a second
* client.
*
* @param {{ relay_id?: string, relayId?: string }} row a home_connections row
*/
export function relayTransportFor(row) {
const config = requireRelay();
const relayId = row?.relay_id || row?.relayId;
if (!relayId) {
throw new PairingError(
PAIRING_ERR.UNKNOWN_CODE,
'This home is set up for the three.ws integration but has no relay id. Reconnect it.',
409,
);
}
return createRelayTransport({ relayUrl: config.url, relayId, serviceToken: config.serviceToken });
}
// ----------------------------------------------------------------- revocation
/**
* Drop a house's socket at the relay, now.
*
* Revocation is both-ended: three.ws stops opening sessions the moment the row
* is revoked, and this makes the house's own socket go away rather than
* lingering until its next heartbeat. Failure here is logged and swallowed on
* purpose: the connection row is already revoked in the database, which is what
* actually gates access, and a relay that is briefly unreachable must not make
* "disconnect my home" fail.
*
* @returns {Promise<{ ok: boolean, detail?: string }>}
*/
export async function revokeAtRelay(relayId, { fetchImpl = fetch } = {}) {
if (!relayId || !isRelayConfigured()) return { ok: false, detail: 'no relay configured' };
const config = relayConfig();
try {
const res = await fetchImpl(new URL('/v1/revoke', toHttpUrl(config.url)).href, {
method: 'POST',
headers: { 'content-type': 'application/json', authorization: `Bearer ${config.serviceToken}` },
body: JSON.stringify({ relayId }),
signal: AbortSignal.timeout(8000),
});
if (!res.ok) return { ok: false, detail: `relay answered ${res.status}` };
return { ok: true, ...(await res.json().catch(() => ({}))) };
} catch (err) {
return { ok: false, detail: err?.message || String(err) };
}
}
/**
* Is this house currently dialled in. The connect UI uses it to tell state 3
* (paired and connected) apart from state 4 (the integration is offline)
* without opening a session that would only fail.
*/
export async function relayStatus(relayId, { fetchImpl = fetch } = {}) {
if (!relayId || !isRelayConfigured()) return { online: false, configured: false };
const config = relayConfig();
try {
const url = new URL('/v1/status', toHttpUrl(config.url));
url.searchParams.set('relay_id', relayId);
const res = await fetchImpl(url.href, {
headers: { authorization: `Bearer ${config.serviceToken}` },
signal: AbortSignal.timeout(8000),
});
if (!res.ok) return { online: false, configured: true, detail: `relay answered ${res.status}` };
return { configured: true, ...(await res.json()) };
} catch (err) {
return { online: false, configured: true, detail: err?.message || String(err) };
}
}
/** Removes pairings that can never be redeemed again. Called by the sweep cron. */
export async function prunePairings({ olderThanHours = 24 } = {}) {
const rows = await sql`
delete from home_relay_pairings
where (redeemed_at is not null and redeemed_at < now() - ${`${olderThanHours} hours`}::interval)
or (redeemed_at is null and expires_at < now() - ${`${olderThanHours} hours`}::interval)
returning id
`;
return { pruned: rows.length };
}
// ---------------------------------------------------------------- small parts
/**
* A relay home has no URL of ours to dial, but `home_connections.base_url` is
* not null and is unique per user. `relay://<relay id>` satisfies both, is
* unique by construction, and reads honestly in a row dump: this home is not
* somewhere we can reach, it is somewhere that reaches us.
*/
export function relayBaseUrl(relayId) {
return `relay://${relayId}`;
}
export function isRelayBaseUrl(baseUrl) {
return typeof baseUrl === 'string' && baseUrl.startsWith('relay://');
}
function toHttpUrl(relayUrl) {
const url = new URL(relayUrl);
if (url.protocol === 'ws:') url.protocol = 'http:';
if (url.protocol === 'wss:') url.protocol = 'https:';
return url;
}
/**
* What redeemed a code, bounded and typed. The integration supplies this and it
* is therefore untrusted text: it is stored for the owner to read and is never
* interpreted.
*/
function describeAgent(agent) {
const trim = (value, max) => (typeof value === 'string' ? value.slice(0, max) : null);
return {
name: trim(agent?.name, 96) || 'unknown',
version: trim(agent?.version, 32) || 'unknown',
at: new Date().toISOString(),
};
}
function normalizeLabel(label) {
return String(label || '').trim().slice(0, 120);
}
/** Exported for the pairing endpoint's constant-time compare on a code echo. */
export function codesMatch(a, b) {
const ha = createHash('sha256').update(normalizePairingCode(a)).digest();
const hb = createHash('sha256').update(normalizePairingCode(b)).digest();
return timingSafeEqual(ha, hb);
}