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.

feat(home): pair a house through a satellite so no port has to be opened

nirholas6cf8d9811899
diff --git a/api/_lib/home/relay.js b/api/_lib/home/relay.js
new file mode 100644
index 000000000..d835a7622
--- /dev/null
+++ b/api/_lib/home/relay.js
@@ -0,0 +1,467 @@
+/**
+ * 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);
+}
diff --git a/api/_lib/home/satellites.js b/api/_lib/home/satellites.js
new file mode 100644
index 000000000..13461f57b
--- /dev/null
+++ b/api/_lib/home/satellites.js
@@ -0,0 +1,237 @@
+// The satellite store: where a paired voice satellite lives, and the only
+// module that touches its signing key.
+//
+// The same two invariants as api/_lib/home/store.js hold here and for the same
+// reasons. A satellite row is never returned with `viewer_secret_enc` on it,
+// and ownership is a `where user_id = $1` inside the query rather than a check
+// in JavaScript after the row is in hand, so a wrong owner and a missing row
+// are indistinguishable from outside.
+//
+// A pairing code is a bearer credential with a physical consequence: redeeming
+// one attaches a microphone in somebody's house to an agent. Three properties
+// are enforced here rather than by the caller, because a caller can forget.
+//
+// * The code is stored as a SHA-256 hash and compared by hash.
+// * Redemption is a conditional UPDATE, so two racing claims cannot both win.
+// * Expiry is in the WHERE clause, not in a JavaScript date comparison after
+// the row has already been read.
+
+import { createHash, randomBytes, randomInt, timingSafeEqual } from 'node:crypto';
+
+import { sql } from '../db.js';
+import { decryptSecret, encryptSecret } from '../secret-box.js';
+
+/** How long a pairing code is good for. Long enough to paste, short enough to leak safely. */
+export const CODE_TTL_MINUTES = 15;
+
+/**
+ * The code alphabet. No 0/O, no 1/I/L: a pairing code is read off a screen and
+ * typed into a terminal, often from a phone, and the characters people confuse
+ * are the ones that turn a working setup into "pairing failed".
+ */
+const ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+
+/** Generate a code in the shape `ABCD-EFGH`. */
+export function generateCode() {
+ let out = '';
+ for (let i = 0; i < 8; i += 1) out += ALPHABET[randomInt(ALPHABET.length)];
+ return `${out.slice(0, 4)}-${out.slice(4)}`;
+}
+
+/**
+ * Normalize a code as typed. People paste it with the hyphen, without it, in
+ * lower case, and with a trailing space from a terminal copy. All four are the
+ * same code.
+ */
+export function normalizeCode(raw) {
+ const cleaned = String(raw || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+ if (cleaned.length !== 8) return null;
+ if (![...cleaned].every((c) => ALPHABET.includes(c))) return null;
+ return `${cleaned.slice(0, 4)}-${cleaned.slice(4)}`;
+}
+
+const hashCode = (code) => createHash('sha256').update(code).digest('hex');
+
+/** Columns that are safe to return. `viewer_secret_enc` is deliberately absent. */
+const SAFE = sql`
+ id, user_id, agent_id, name, area, version, wyoming_version,
+ created_at, last_seen_at, revoked_at
+`;
+
+/**
+ * Mint a pairing code for one agent.
+ * @param {{ userId: string, agentId: string, name?: string|null }} input
+ */
+export async function createPairingCode({ userId, agentId, name = null }) {
+ const code = generateCode();
+ const [row] = await sql`
+ insert into home_satellite_codes (code_hash, user_id, agent_id, name, expires_at)
+ values (${hashCode(code)}, ${userId}, ${agentId}, ${name}, now() + ${`${CODE_TTL_MINUTES} minutes`}::interval)
+ returning id, created_at, expires_at
+ `;
+ return { code, id: row.id, created_at: row.created_at, expires_at: row.expires_at };
+}
+
+/**
+ * Redeem a code, creating the satellite it buys.
+ *
+ * Returns `{ ok: false, reason }` for every failure a stranger could provoke,
+ * so the endpoint can answer "that code is not valid" without a stack trace and
+ * without telling the caller which of the three failure modes it hit.
+ *
+ * @param {{ code: string, name?: string|null, area?: string|null, version?: string|null, wyomingVersion?: string|null }} input
+ */
+export async function claimPairingCode({ code, name = null, area = null, version = null, wyomingVersion = null }) {
+ const normalized = normalizeCode(code);
+ if (!normalized) return { ok: false, reason: 'malformed' };
+
+ // Single use and expiry, decided by the database in one statement. A read
+ // followed by a write would let two claims of the same code both observe it
+ // unclaimed; here exactly one UPDATE returns a row.
+ const [claimed] = await sql`
+ update home_satellite_codes
+ set claimed_at = now()
+ where code_hash = ${hashCode(normalized)}
+ and claimed_at is null
+ and expires_at > now()
+ returning id, user_id, agent_id, name
+ `;
+ if (!claimed) return { ok: false, reason: 'invalid' };
+
+ const [agent] = await sql`
+ select id, name from agent_identities
+ where id = ${claimed.agent_id} and deleted_at is null
+ limit 1
+ `;
+ if (!agent) return { ok: false, reason: 'agent_gone' };
+
+ const secret = randomSecret();
+ const [satellite] = await sql`
+ insert into home_satellites (user_id, agent_id, name, area, viewer_secret_enc, version, wyoming_version)
+ values (
+ ${claimed.user_id}, ${claimed.agent_id},
+ ${String(name || claimed.name || agent.name || 'three.ws agent').slice(0, 120)},
+ ${area ? String(area).slice(0, 120) : null},
+ ${await encryptSecret(secret)},
+ ${version ? String(version).slice(0, 40) : null},
+ ${wyomingVersion ? String(wyomingVersion).slice(0, 40) : null}
+ )
+ returning ${SAFE}
+ `;
+
+ await sql`update home_satellite_codes set satellite_id = ${satellite.id} where id = ${claimed.id}`;
+ return { ok: true, satellite, secret, agent };
+}
+
+/**
+ * Authenticate a satellite by the secret it was handed at claim time.
+ * Returns the row plus its decrypted secret, or null.
+ */
+export async function authenticateSatellite(satelliteId, secret) {
+ if (!satelliteId || !secret) return null;
+ const [row] = await sql`
+ select ${SAFE}, viewer_secret_enc
+ from home_satellites
+ where id = ${satelliteId} and revoked_at is null
+ limit 1
+ `;
+ if (!row) return null;
+ let stored;
+ try {
+ stored = await decryptSecret(row.viewer_secret_enc);
+ } catch {
+ return null;
+ }
+ // Constant time. The secret is a bearer credential for a microphone in a
+ // house; leaking it one byte at a time through response timing is a real
+ // attack even though the value is high entropy.
+ const a = Buffer.from(stored, 'utf8');
+ const b = Buffer.from(String(secret), 'utf8');
+ if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+ const { viewer_secret_enc: _ignored, ...safe } = row;
+ return { satellite: safe, secret: stored };
+}
+
+/** Record that a satellite checked in, and what it is running. */
+export async function touchSatellite(id, { version = null, wyomingVersion = null } = {}) {
+ await sql`
+ update home_satellites
+ set last_seen_at = now(),
+ version = coalesce(${version ? String(version).slice(0, 40) : null}, version),
+ wyoming_version = coalesce(${wyomingVersion ? String(wyomingVersion).slice(0, 40) : null}, wyoming_version)
+ where id = ${id}
+ `;
+}
+
+/** One satellite the caller owns, with its decrypted signing key. */
+export async function getSatelliteForOwner(id, userId) {
+ const [row] = await sql`
+ select ${SAFE}, viewer_secret_enc
+ from home_satellites
+ where id = ${id} and user_id = ${userId} and revoked_at is null
+ limit 1
+ `;
+ if (!row) return null;
+ const { viewer_secret_enc, ...safe } = row;
+ let secret = null;
+ try {
+ secret = await decryptSecret(viewer_secret_enc);
+ } catch {
+ secret = null;
+ }
+ return { satellite: safe, secret };
+}
+
+/** Every satellite the caller owns, newest first. */
+export async function listSatellites(userId) {
+ return sql`
+ select s.id, s.agent_id, s.name, s.area, s.version, s.wyoming_version,
+ s.created_at, s.last_seen_at, a.name as agent_name
+ from home_satellites s
+ join agent_identities a on a.id = s.agent_id
+ where s.user_id = ${userId} and s.revoked_at is null
+ order by s.created_at desc
+ limit 100
+ `;
+}
+
+/** Codes minted by the caller that have not been redeemed and have not expired. */
+export async function listPendingCodes(userId) {
+ return sql`
+ select c.id, c.agent_id, c.name, c.created_at, c.expires_at, a.name as agent_name
+ from home_satellite_codes c
+ join agent_identities a on a.id = c.agent_id
+ where c.user_id = ${userId} and c.claimed_at is null and c.expires_at > now()
+ order by c.created_at desc
+ limit 20
+ `;
+}
+
+/**
+ * Revoke a satellite. The row stays so the audit trail stays; every path that
+ * reads a satellite filters `revoked_at is null`, so the effect is immediate
+ * and its identity can never be re-authenticated.
+ */
+export async function revokeSatellite(id, userId) {
+ const [row] = await sql`
+ update home_satellites
+ set revoked_at = now()
+ where id = ${id} and user_id = ${userId} and revoked_at is null
+ returning id
+ `;
+ return !!row;
+}
+
+/** Withdraw an unclaimed pairing code. */
+export async function revokePairingCode(id, userId) {
+ const [row] = await sql`
+ delete from home_satellite_codes
+ where id = ${id} and user_id = ${userId} and claimed_at is null
+ returning id
+ `;
+ return !!row;
+}
+
+function randomSecret() {
+ return randomBytes(32).toString('base64url');
+}
diff --git a/api/_lib/migrations/20260903200000_home_satellites.sql b/api/_lib/migrations/20260903200000_home_satellites.sql
new file mode 100644
index 000000000..8376b1208
--- /dev/null
+++ b/api/_lib/migrations/20260903200000_home_satellites.sql
@@ -0,0 +1,86 @@
+begin;
+
+-- three.ws Home: voice satellites.
+--
+-- A Home Assistant instance can be told to treat a Wyoming service as one of
+-- its voice satellites. This is the record of a person having pointed one at a
+-- three.ws agent, so that the agent's face, voice and body appear on the far
+-- end of a pipeline that Home Assistant already owns.
+--
+-- Two tables, and the split matters. A pairing code is a bearer credential that
+-- lives for minutes and buys exactly one satellite; a satellite is a durable
+-- identity that lives until it is revoked. Keeping them in one table would mean
+-- a short-lived secret and a long-lived one sharing a lifecycle, which is how a
+-- code ends up still redeemable a year later.
+--
+-- Neither table holds a Home Assistant credential. The satellite never sees one
+-- either: authentication for the pipeline happens inside the house, between
+-- Home Assistant and the service on its own network, and never crosses this
+-- platform.
+
+create table if not exists home_satellites (
+ id uuid primary key default gen_random_uuid(),
+ -- Who it belongs to. A satellite hears a room, so ownership is not a
+ -- convenience column: it is the whole authorisation model.
+ user_id uuid not null references users(id) on delete cascade,
+ -- Which agent shows up on it. This is what makes the satellite a face
+ -- rather than a speaker.
+ agent_id uuid not null references agent_identities(id) on delete cascade,
+ -- What Home Assistant calls the device.
+ name text not null,
+ -- Suggested area, passed straight through to the Home Assistant device
+ -- registry. User-supplied and therefore untrusted; it is never interpreted.
+ area text,
+ -- The signing key for this satellite's own viewer tokens. It is what lets a
+ -- browser on the same network as the house attach without three.ws being
+ -- reachable at all, so it is a real credential and is encrypted at rest
+ -- with the same primitive as a home's access token (AES-256-GCM through
+ -- api/_lib/secret-box.js), never hashed: the service has to be handed the
+ -- plaintext back at claim time and again if it is ever re-provisioned.
+ viewer_secret_enc text not null,
+ -- Reported by the service on every session refresh, so an operator can see
+ -- which houses are running a build that predates a protocol change.
+ version text,
+ wyoming_version text,
+ created_at timestamptz not null default now(),
+ last_seen_at timestamptz,
+ revoked_at timestamptz
+);
+
+create index if not exists home_satellites_user_idx
+ on home_satellites (user_id, created_at desc)
+ where revoked_at is null;
+
+create index if not exists home_satellites_agent_idx
+ on home_satellites (agent_id)
+ where revoked_at is null;
+
+create table if not exists home_satellite_codes (
+ id uuid primary key default gen_random_uuid(),
+ -- SHA-256 of the code, never the code. A pairing code is typed into a
+ -- terminal and pasted into chat logs; storing it in the clear would make a
+ -- database read equivalent to owning every unclaimed satellite.
+ code_hash text not null unique,
+ user_id uuid not null references users(id) on delete cascade,
+ agent_id uuid not null references agent_identities(id) on delete cascade,
+ -- The name the satellite gets if it does not choose one.
+ name text,
+ created_at timestamptz not null default now(),
+ expires_at timestamptz not null,
+ -- Set on redemption. Single use is enforced here, not in application code:
+ -- two racing claims both pass a `claimed_at is null` read, and only the
+ -- conditional UPDATE below decides which one wins.
+ claimed_at timestamptz,
+ satellite_id uuid references home_satellites(id) on delete set null
+);
+
+create index if not exists home_satellite_codes_user_idx
+ on home_satellite_codes (user_id, created_at desc);
+
+-- Expired, unclaimed codes are swept by the same retention pass that clears the
+-- rest of the home tables. The index is what makes that sweep cheap.
+create index if not exists home_satellite_codes_expiry_idx
+ on home_satellite_codes (expires_at)
+ where claimed_at is null;
+
+commit;
diff --git a/api/home/pair.js b/api/home/pair.js
new file mode 100644
index 000000000..ca9dedfc2
--- /dev/null
+++ b/api/home/pair.js
@@ -0,0 +1,133 @@
+// /api/home/pair, the door a house that only exists on a LAN comes in through.
+//
+// POST { label } mint a pairing code for a new relayed home
+// POST { homeId, action: 'refresh' } mint a fresh code for one already pending
+// GET ?homeId= the live code's countdown and this home's link state
+//
+// The redemption half lives at /api/home/pair/redeem and is deliberately a
+// separate file, because it is the one endpoint in this whole surface with no
+// three.ws session behind it: the caller is a Home Assistant install, which has
+// no account, no cookie and no bearer token, and only ever will have the short
+// code its owner typed in.
+//
+// Why this exists at all: three.ws is served over https from Cloud Run and
+// cannot route to RFC1918 space, so for most Home Assistant installs there is
+// no URL we could ever dial. Those houses dial us. See
+// docs/home-relay-threat-model.md for what that connection can and cannot do.
+
+import { publicHome, resolveCaller } from '../_lib/home/access.js';
+import { can } from '../_lib/home/members.js';
+import { homeError, homeFailure, HOME_ERR } from '../_lib/home/errors.js';
+import {
+ isRelayConfigured,
+ PairingError,
+ pendingPairing,
+ refreshPairing,
+ relayStatus,
+ startPairing,
+} from '../_lib/home/relay.js';
+import { getConnection } from '../_lib/home/store.js';
+import { requireCsrf } from '../_lib/csrf.js';
+import { cors, error, json, method, rateLimited, readJson, wrap } from '../_lib/http.js';
+import { limits } from '../_lib/rate-limit.js';
+import { logAudit } from '../_lib/audit.js';
+
+const LABEL_MAX = 120;
+
+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 connect a home.');
+
+ if (!isRelayConfigured()) {
+ return homeError(
+ res,
+ homeFailure(
+ HOME_ERR.NOT_CONNECTED,
+ 'This three.ws deployment has no home relay configured yet, so a home that is only on your network cannot be connected here. A home with a remote https address still connects normally.',
+ ),
+ );
+ }
+
+ if (req.method === 'GET') return handleStatus(req, res, caller);
+ return handleMint(req, res, caller);
+});
+
+/**
+ * The connect UI polls this while the code is on screen: it renders the
+ * countdown from `expiresAt` and flips to the connected state the moment the
+ * house dials in, with no page reload and no user action.
+ */
+async function handleStatus(req, res, caller) {
+ const rl = await limits.homeRead(caller.userId);
+ if (!rl.success) return rateLimited(res, rl, 'too many home reads, slow down');
+
+ const homeId = new URL(req.url, 'http://local').searchParams.get('homeId');
+ if (!homeId) return homeError(res, homeFailure(HOME_ERR.VALIDATION, 'homeId is required.'));
+
+ const home = await getConnection(homeId, caller.userId);
+ if (!home) return homeError(res, homeFailure(HOME_ERR.NOT_FOUND, 'No such home.'));
+ // Re-pairing a relay changes how the house connects, which is connection
+ // administration rather than living in the house. A member can turn the
+ // lights on and cannot re-point the tunnel their household runs on.
+ if (!can(home.role, 'manage')) {
+ return homeError(res, homeFailure(HOME_ERR.FORBIDDEN, `A ${home.role} cannot manage this home's connection.`));
+ }
+ if (home.transport !== 'relay') {
+ return homeError(res, homeFailure(HOME_ERR.VALIDATION, 'That home connects to its own address, not through the three.ws integration.'));
+ }
+
+ const [pairing, live] = await Promise.all([
+ pendingPairing(homeId, caller.userId),
+ relayStatus(home.relay_id),
+ ]);
+
+ return json(res, 200, {
+ home: publicHome(home),
+ pairing,
+ // `online` is the honest answer to "is the integration in my house
+ // running right now", read from the relay rather than inferred from the
+ // last successful session. It is what tells state 3 from state 4.
+ relay: { online: Boolean(live.online), agent: live.agent || null, sessions: live.sessions ?? 0 },
+ });
+}
+
+async function handleMint(req, res, caller) {
+ 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, 4_000).catch(() => null)) || {};
+ const homeId = typeof body.homeId === 'string' ? body.homeId : '';
+
+ try {
+ if (homeId) {
+ const refreshed = await refreshPairing({ homeId, userId: caller.userId });
+ logAudit({ action: 'home.pair.refresh', userId: caller.userId, targetId: homeId });
+ return json(res, 200, { homeId, ...refreshed });
+ }
+
+ const label = typeof body.label === 'string' ? body.label.trim().slice(0, LABEL_MAX) : '';
+ const started = await startPairing({ userId: caller.userId, label });
+ logAudit({ action: 'home.pair.start', userId: caller.userId, targetId: started.home.id });
+ return json(res, 201, {
+ home: publicHome(started.home),
+ code: started.code,
+ expiresAt: started.expiresAt,
+ relayUrl: started.relayUrl,
+ // Everything the user has to do next, in the order they do it, so the
+ // UI renders instructions rather than inventing them.
+ instructions: {
+ hacs: 'https://github.com/nirholas/three-ws-home-assistant',
+ integration: 'three.ws',
+ where: 'Settings, Devices and services, Add integration, three.ws',
+ },
+ });
+ } catch (err) {
+ if (err instanceof PairingError) return error(res, err.status || 400, err.code, err.message);
+ throw err;
+ }
+}
diff --git a/api/home/pair/redeem.js b/api/home/pair/redeem.js
new file mode 100644
index 000000000..8918b92f2
--- /dev/null
+++ b/api/home/pair/redeem.js
@@ -0,0 +1,70 @@
+// /api/home/pair/redeem, called from inside a house.
+//
+// This is the only endpoint in the home surface with no three.ws session behind
+// it, and that is not an oversight. The caller is a Home Assistant install: it
+// has no account, no cookie, no bearer token, and the only thing it will ever
+// hold is the short code its owner read off a three.ws screen and typed into a
+// config flow. Authentication here IS the code.
+//
+// Everything that makes that safe lives in api/_lib/home/relay.js and is worth
+// restating, because a weak-looking secret on an unauthenticated endpoint is
+// exactly the shape of a real vulnerability:
+//
+// * The code redeems into ONE home_connections row, the one it was minted
+// for. It is not a ticket to "a house"; a guess cannot be aimed.
+// * It is single use, decided by a conditional UPDATE, so two racing
+// redemptions cannot both succeed.
+// * It expires in ten minutes.
+// * Wrong guesses are counted against the pairing and kill it after five.
+// * It is stored as a digest, so reading the table yields no live pairing.
+// * It is rate limited per IP here, on top of all of that.
+//
+// What it hands back is an install token: an HMAC over the relay id, the owner
+// and the home, which lets the relay verify a dial-in with no database. It is
+// not a Home Assistant credential, because three.ws never receives one for a
+// relayed home. The integration authenticates to Home Assistant locally.
+
+import { homeError, homeFailure, HOME_ERR } from '../../_lib/home/errors.js';
+import { isRelayConfigured, normalizePairingCode, PairingError, recordFailedAttempt, redeemPairing } from '../../_lib/home/relay.js';
+import { clientIp, limits } from '../../_lib/rate-limit.js';
+import { cors, error, json, method, rateLimited, readJson, wrap } from '../../_lib/http.js';
+import { logAudit } from '../../_lib/audit.js';
+
+export default wrap(async (req, res) => {
+ // No credentials on this route: the caller is a server, not a browser, so an
+ // origin-scoped cookie has no meaning here and asking for one would only make
+ // the integration harder to write without making anything safer.
+ if (cors(req, res, { methods: 'POST,OPTIONS', credentials: false })) return;
+ if (!method(req, res, ['POST'])) return;
+
+ if (!isRelayConfigured()) {
+ return homeError(
+ res,
+ homeFailure(HOME_ERR.NOT_CONNECTED, 'This three.ws deployment has no home relay configured, so there is nothing to pair with yet.'),
+ );
+ }
+
+ const ip = clientIp(req);
+ const rl = await limits.homePairRedeem(ip);
+ if (!rl.success) return rateLimited(res, rl, 'too many pairing attempts, wait a few minutes');
+
+ const body = await readJson(req, 4_000).catch(() => null);
+ const code = normalizePairingCode(body?.code);
+ if (!code) return error(res, 400, 'validation_error', 'A pairing code is required.');
+
+ try {
+ const paired = await redeemPairing({ code, protocol: body?.protocol, agent: body?.agent });
+ logAudit({ action: 'home.pair.redeem', targetId: paired.relayId, detail: { ip } });
+ return json(res, 200, paired);
+ } catch (err) {
+ if (err instanceof PairingError) {
+ // A wrong code that matches nothing has nothing to count against; a
+ // wrong code aimed at a live pairing burns one of its five attempts.
+ // Both answer identically, so a caller learns nothing from the shape of
+ // the refusal it did not already know from having the code.
+ if (err.code === 'unknown_code') await recordFailedAttempt(code).catch(() => null);
+ return error(res, err.status || 400, err.code, err.message);
+ }
+ throw err;
+ }
+});
diff --git a/api/home/satellite.js b/api/home/satellite.js
new file mode 100644
index 000000000..7b5f307b7
--- /dev/null
+++ b/api/home/satellite.js
@@ -0,0 +1,238 @@
+// Voice satellites: /api/home/satellite
+//
+// GET the caller's satellites and their unredeemed codes
+// POST { action: 'pair' } mint a pairing code for one agent
+// POST { action: 'claim' } a satellite service redeems that code, once
+// POST { action: 'session'} a paired service refreshes its hub token
+// POST { action: 'attach' } a browser asks for a token to watch a satellite
+// POST { action: 'revoke' } withdraw a code, or retire a satellite
+//
+// Two of these are called by a program, not a person, and that shapes the file.
+// `claim` and `session` carry no cookie: the service that calls them has a
+// pairing code or a satellite secret and nothing else, so they are exempt from
+// the session and CSRF checks that guard everything else here and are rate
+// limited by IP instead. Every other action requires a signed-in owner.
+//
+// What a token here buys is worth stating plainly, because it is not "some
+// JSON". A viewer token joins a live audio session with a microphone in
+// somebody's house on the other end. It is therefore minted for one satellite,
+// expires in minutes, and is signed rather than looked up, so the hub can
+// enforce it without a database and without ever holding a credential.
+
+import { getSessionUser } from '../_lib/auth.js';
+import { requireCsrf } from '../_lib/csrf.js';
+import { sql } from '../_lib/db.js';
+import { getAvatar } from '../_lib/avatars.js';
+import {
+ CODE_TTL_MINUTES,
+ authenticateSatellite,
+ claimPairingCode,
+ createPairingCode,
+ getSatelliteForOwner,
+ listPendingCodes,
+ listSatellites,
+ revokePairingCode,
+ revokeSatellite,
+ touchSatellite,
+} from '../_lib/home/satellites.js';
+import { cors, error, json, method, rateLimited, readJson, wrap } from '../_lib/http.js';
+import { clientIp, limits } from '../_lib/rate-limit.js';
+import { isUuid } from '../_lib/validate.js';
+import { ROLE, signToken } from '../../services/home-satellite/src/token.js';
+
+/** How long a satellite's own hub token lasts before it has to ask again. */
+const HUB_TOKEN_TTL_SECONDS = 24 * 60 * 60;
+
+/** How long a browser's viewer token lasts. Short: it is handed to a web page. */
+const VIEWER_TOKEN_TTL_SECONDS = 15 * 60;
+
+const hubSecret = () => process.env.HOME_SATELLITE_HUB_SECRET || '';
+const hubUrl = () => process.env.HOME_SATELLITE_HUB_URL || '';
+
+/** Resolve an agent the caller owns, with the model its face is rendered from. */
+async function ownedAgent(agentId, userId) {
+ const [agent] = await sql`
+ select id, name, avatar_id from agent_identities
+ where id = ${agentId} and user_id = ${userId} and deleted_at is null
+ limit 1
+ `;
+ return agent || null;
+}
+
+/** The public shape of an agent, as both the service and the browser see it. */
+async function agentView(agent, requesterId) {
+ if (!agent) return null;
+ let avatarUrl = null;
+ if (agent.avatar_id) {
+ const avatar = await getAvatar({ id: agent.avatar_id, requesterId }).catch(() => null);
+ avatarUrl = avatar?.model_url || null;
+ }
+ return { id: agent.id, name: agent.name, avatarUrl };
+}
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
+ if (!method(req, res, ['GET', 'POST'])) return;
+
+ if (req.method === 'GET') {
+ const user = await getSessionUser(req, res).catch(() => null);
+ if (!user) return error(res, 401, 'unauthorized', 'sign in to manage your satellites');
+ const [satellites, codes] = await Promise.all([listSatellites(user.id), listPendingCodes(user.id)]);
+ return json(res, 200, {
+ satellites: satellites.map((s) => ({
+ id: s.id,
+ name: s.name,
+ area: s.area,
+ agent: { id: s.agent_id, name: s.agent_name },
+ version: s.version,
+ wyoming_version: s.wyoming_version,
+ created_at: s.created_at,
+ last_seen_at: s.last_seen_at,
+ })),
+ pending_codes: codes.map((c) => ({
+ id: c.id,
+ agent: { id: c.agent_id, name: c.agent_name },
+ name: c.name,
+ created_at: c.created_at,
+ expires_at: c.expires_at,
+ })),
+ hub_configured: !!(hubSecret() && hubUrl()),
+ });
+ }
+
+ const body = await readJson(req).catch(() => null);
+ if (!body || typeof body !== 'object') return error(res, 400, 'bad_request', 'a JSON body is required');
+ const action = String(body.action || '');
+
+ /* ---------------------------------------------------------------- claim */
+ // Called by the service itself, holding only a pairing code.
+ if (action === 'claim') {
+ const rl = await limits.homeSatelliteClaimIp(clientIp(req)).catch(() => ({ success: true }));
+ if (rl && rl.success === false) return rateLimited(res, rl, 'too many pairing attempts, try again shortly');
+
+ const result = await claimPairingCode({
+ code: body.code,
+ name: typeof body.name === 'string' ? body.name : null,
+ area: typeof body.area === 'string' ? body.area : null,
+ version: typeof body.version === 'string' ? body.version : null,
+ wyomingVersion: typeof body.wyoming_version === 'string' ? body.wyoming_version : null,
+ });
+ if (!result.ok) {
+ // One answer for malformed, expired, already-claimed and never-existed.
+ // Distinguishing them would turn this endpoint into an oracle for
+ // guessing codes, and none of the four is actionable differently: the
+ // fix is always "get a fresh code".
+ return error(res, 400, 'invalid_code', 'that pairing code is not valid. Codes are single use and expire after 15 minutes; generate a new one at /home/satellite.');
+ }
+
+ const [agentRow] = await sql`select id, name, avatar_id from agent_identities where id = ${result.satellite.agent_id} limit 1`;
+ const agent = await agentView(agentRow, result.satellite.user_id);
+ const secret = hubSecret();
+ return json(res, 201, {
+ satellite_id: result.satellite.id,
+ secret: result.secret,
+ name: result.satellite.name,
+ agent,
+ hub_url: secret && hubUrl() ? `${hubUrl().replace(/\/+$/, '')}/room` : null,
+ hub_token: secret ? signToken({ sid: result.satellite.id, role: ROLE.SATELLITE }, secret, HUB_TOKEN_TTL_SECONDS) : null,
+ hub_token_exp: secret ? Math.floor(Date.now() / 1000) + HUB_TOKEN_TTL_SECONDS : 0,
+ });
+ }
+
+ /* -------------------------------------------------------------- session */
+ // Called by a paired service to refresh the token that gets it into its room.
+ if (action === 'session') {
+ const rl = await limits.homeSatelliteClaimIp(clientIp(req)).catch(() => ({ success: true }));
+ if (rl && rl.success === false) return rateLimited(res, rl, 'too many session requests, try again shortly');
+
+ if (!isUuid(body.satellite_id)) return error(res, 400, 'bad_request', 'satellite_id required');
+ const auth = await authenticateSatellite(body.satellite_id, body.secret);
+ if (!auth) return error(res, 401, 'unauthorized', 'this satellite is not paired, or its secret has been revoked');
+
+ await touchSatellite(auth.satellite.id, {
+ version: typeof body.version === 'string' ? body.version : null,
+ wyomingVersion: typeof body.wyoming_version === 'string' ? body.wyoming_version : null,
+ });
+
+ const [agentRow] = await sql`select id, name, avatar_id from agent_identities where id = ${auth.satellite.agent_id} limit 1`;
+ const agent = await agentView(agentRow, auth.satellite.user_id);
+ const secret = hubSecret();
+ return json(res, 200, {
+ agent,
+ hub_url: secret && hubUrl() ? `${hubUrl().replace(/\/+$/, '')}/room` : null,
+ hub_token: secret ? signToken({ sid: auth.satellite.id, role: ROLE.SATELLITE }, secret, HUB_TOKEN_TTL_SECONDS) : null,
+ hub_token_exp: secret ? Math.floor(Date.now() / 1000) + HUB_TOKEN_TTL_SECONDS : 0,
+ });
+ }
+
+ /* ------------------------------------------------- everything else: user */
+ const user = await getSessionUser(req, res).catch(() => null);
+ if (!user) return error(res, 401, 'unauthorized', 'sign in to manage your satellites');
+ if (!(await requireCsrf(req, res, user.id))) return;
+
+ if (action === 'pair') {
+ const rl = await limits.homeSatellitePair(user.id).catch(() => ({ success: true }));
+ if (rl && rl.success === false) return rateLimited(res, rl, 'too many pairing codes, try again shortly');
+
+ if (!isUuid(body.agent_id)) return error(res, 400, 'bad_request', 'agent_id required');
+ const agent = await ownedAgent(body.agent_id, user.id);
+ if (!agent) return error(res, 404, 'not_found', 'no agent of yours has that id');
+
+ const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim().slice(0, 120) : null;
+ const created = await createPairingCode({ userId: user.id, agentId: agent.id, name });
+ return json(res, 201, {
+ code: created.code,
+ expires_at: created.expires_at,
+ ttl_minutes: CODE_TTL_MINUTES,
+ agent: { id: agent.id, name: agent.name },
+ // The exact command, with the code already in it. A pairing flow that
+ // makes somebody assemble a docker run line from prose is a pairing
+ // flow half of them abandon.
+ command: `docker run -d --name three-ws-satellite --network host -v three-ws-satellite:/data -e THREE_WS_PAIRING_CODE=${created.code} ghcr.io/nirholas/three-ws-home-satellite:latest`,
+ });
+ }
+
+ if (action === 'attach') {
+ if (!isUuid(body.satellite_id)) return error(res, 400, 'bad_request', 'satellite_id required');
+ const owned = await getSatelliteForOwner(body.satellite_id, user.id);
+ if (!owned) return error(res, 404, 'not_found', 'no satellite of yours has that id');
+
+ const [agentRow] = await sql`select id, name, avatar_id from agent_identities where id = ${owned.satellite.agent_id} limit 1`;
+ const agent = await agentView(agentRow, user.id);
+ const secret = hubSecret();
+ return json(res, 200, {
+ satellite: {
+ id: owned.satellite.id,
+ name: owned.satellite.name,
+ area: owned.satellite.area,
+ version: owned.satellite.version,
+ wyoming_version: owned.satellite.wyoming_version,
+ last_seen_at: owned.satellite.last_seen_at,
+ },
+ agent,
+ // The hosted path: works from https://three.ws, needs the hub.
+ hub_url: secret && hubUrl() ? `${hubUrl().replace(/\/+$/, '')}/room` : null,
+ hub_token: secret ? signToken({ sid: owned.satellite.id, role: ROLE.VIEWER }, secret, VIEWER_TOKEN_TTL_SECONDS) : null,
+ // The local path: works from a browser on the same network as the
+ // house, with three.ws entirely out of the loop after this response.
+ lan_token: owned.secret ? signToken({ sid: owned.satellite.id, role: ROLE.VIEWER }, owned.secret, VIEWER_TOKEN_TTL_SECONDS) : null,
+ expires_in: VIEWER_TOKEN_TTL_SECONDS,
+ });
+ }
+
+ if (action === 'revoke') {
+ if (isUuid(body.satellite_id)) {
+ const done = await revokeSatellite(body.satellite_id, user.id);
+ if (!done) return error(res, 404, 'not_found', 'no satellite of yours has that id');
+ return json(res, 200, { revoked: 'satellite', id: body.satellite_id });
+ }
+ if (isUuid(body.code_id)) {
+ const done = await revokePairingCode(body.code_id, user.id);
+ if (!done) return error(res, 404, 'not_found', 'no unclaimed code of yours has that id');
+ return json(res, 200, { revoked: 'code', id: body.code_id });
+ }
+ return error(res, 400, 'bad_request', 'satellite_id or code_id required');
+ }
+
+ return error(res, 400, 'bad_request', 'action must be pair, claim, session, attach or revoke');
+});
diff --git a/pages/smart-home-satellite.html b/pages/smart-home-satellite.html
new file mode 100644
index 000000000..2013d213e
--- /dev/null
+++ b/pages/smart-home-satellite.html
@@ -0,0 +1,70 @@
+<!doctype html>
+<html lang="en">
+<head>
+ <script>/* three.ws theme boot */(function(){document.documentElement.classList.add('js');try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Voice satellite · Give your Home Assistant assistant a face · three.ws</title>
+ <meta name="description" content="Point an existing Home Assistant voice pipeline at a three.ws agent and it gains a face, an expression, lip sync and a body. Home Assistant keeps the wake word, the transcription and the answer; three.ws is the face." />
+ <link rel="canonical" href="https://three.ws/smart-home/satellite" />
+ <meta property="og:title" content="Voice satellite · three.ws" />
+ <meta property="og:description" content="Your Home Assistant voice assistant is a speaker with an LED ring. Give it a face, lip sync and a body that turns toward you." />
+ <meta property="og:url" content="https://three.ws/smart-home/satellite" />
+ <meta property="og:image" content="https://three.ws/api/page-og?s=build&amp;t=Voice+satellite&amp;d=Give+your+Home+Assistant+voice+assistant+a+face%2C+lip+sync+and+a+body.&amp;p=%2Fsmart-home%2Fsatellite" />
+ <meta name="twitter:card" content="summary_large_image" />
+ <meta name="twitter:site" content="@trythreews" />
+ <meta name="twitter:title" content="Voice satellite · three.ws" />
+ <meta name="twitter:description" content="Your Home Assistant voice assistant is a speaker with an LED ring. Give it a face, lip sync and a body that turns toward you." />
+ <link rel="icon" href="/favicon.ico" sizes="any" />
+ <link rel="stylesheet" href="/style.css" />
+ <link rel="stylesheet" href="/nav.css" />
+ <link rel="stylesheet" href="/fonts/fonts.css" />
+ <link rel="stylesheet" href="/src/home/satellite.css" />
+</head>
+<body>
+ <main class="hs-wrap" id="main">
+ <header>
+ <p class="hs-eyebrow">Voice satellite</p>
+ <h1 class="hs-title">Your voice assistant already works. Give it a face.</h1>
+ <p class="hs-lede">
+ Home Assistant owns the hard part: the wake word, the speech recognition, the intent, the
+ answer, and every device in your house. What it does not have is a body. Pair a three.ws
+ satellite and the same pipeline you already use gets one, lip-synced to its own speech, on
+ any screen in the house. Close this page and your assistant keeps working exactly as it did.
+ </p>
+ </header>
+
+ <!--
+ One live region for both views. The controller (src/home/satellite.js)
+ renders either the manage view (pair a satellite, see what is paired) or
+ the live view (the agent's body and the running pipeline), chosen by the
+ `?id=` in the URL. `aria-live="polite"` so a state change is announced
+ without stealing focus.
+ -->
+ <div id="hs-root" aria-live="polite" aria-busy="true">
+ <section class="hs-panel">
+ <div class="hs-skeleton" style="height:1.1rem;width:12rem"></div>
+ <div class="hs-skeleton" style="height:0.85rem;width:22rem;margin-top:0.6rem"></div>
+ <div class="hs-skeleton" style="height:2.6rem;margin-top:1.1rem"></div>
+ </section>
+ </div>
+
+ <noscript>
+ <section class="hs-panel">
+ <h2 class="hs-panel-title">JavaScript is required here</h2>
+ <p class="hs-panel-sub">
+ This page opens a live audio session and renders a 3D avatar, so it needs JavaScript.
+ The satellite itself does not: it runs beside Home Assistant on your own network and
+ keeps your voice pipeline working whether or not any browser is open.
+ </p>
+ <p class="hs-panel-sub">
+ <a href="/docs/home-satellite">Read the setup guide</a> for the install steps in plain text.
+ </p>
+ </section>
+ </noscript>
+ </main>
+
+ <script src="/nav.js"></script>
+ <script type="module" src="/src/home/satellite.js"></script>
+</body>
+</html>
diff --git a/services/home-relay/README.md b/services/home-relay/README.md
new file mode 100644
index 000000000..da2ac2431
--- /dev/null
+++ b/services/home-relay/README.md
@@ -0,0 +1,108 @@
+# home-relay
+
+**The socket a LAN-only house dials out through.**
+
+three.ws is served over https from Cloud Run. Home Assistant usually lives on a home network, on
+an address no server on the internet can route to. For those houses there is no URL we could ever
+dial, so the house dials us: the [three.ws Home Assistant
+integration](../../home-assistant-integration) opens one outbound WebSocket to this service and
+keeps it open, and the platform reaches the instance back down that socket.
+
+Nothing listens on the user's network. No port is forwarded. No inbound firewall rule exists.
+
+```
+ three.ws api ──POST /v1/agent(ws)──► home-relay ◄──dial-out ws── Home Assistant
+ (platform) (this service) (the house)
+```
+
+## What it deliberately is not
+
+It is small and dumb on purpose, because it sits between the platform and a building.
+
+- **It holds no database.** Ownership is proved by the signature on the install token the house
+ presents ([`src/token.js`](src/token.js)), so the connect path queries nothing.
+- **It holds no Home Assistant credential, ever.** Authentication happens locally, inside the
+ house. No long-lived token crosses this process, which is why a relayed home's
+ `home_connections.access_token_enc` is empty.
+- **It forwards only what the protocol permits**, in the direction it permits
+ ([`src/protocol.js`](src/protocol.js)), and the integration enforces the same list again at the
+ far end, so compromising this service does not compromise a house.
+
+That last point is the whole security argument, and it is why the allowlist is generated rather
+than transcribed: see [The allowlist](#the-allowlist).
+
+## Run it
+
+```bash
+cd services/home-relay
+npm ci
+HOME_RELAY_SIGNING_KEY=$(openssl rand -hex 32) \
+HOME_RELAY_SERVICE_TOKEN=$(openssl rand -hex 32) \
+PORT=8080 npm start
+# {"event":"relay.listening","port":8080}
+
+curl -s localhost:8080/healthz
+```
+
+| Variable | Required | What it is |
+|---|---|---|
+| `HOME_RELAY_SIGNING_KEY` | yes | Signs and verifies the install tokens a house presents. The platform mints tokens with the same key. |
+| `HOME_RELAY_SERVICE_TOKEN` | yes | The platform's own credential for opening a session over a house's socket. Not a user credential. |
+| `PORT` | no | Listen port. Defaults to 8080, which is what Cloud Run sets. |
+
+## Endpoints
+
+| Path | Who calls it | What it does |
+|---|---|---|
+| `GET /healthz`, `GET /` | Cloud Run, monitoring | Liveness plus counts |
+| `GET /v1/status` | the platform | Which installs are connected right now |
+| `WS /v1/agent` | a house | The dial-out socket. Presents an install token, then stays |
+| `WS /v1/bridge?relay_id=` | the platform | Opens one session over that house's socket |
+| `POST /v1/revoke`, `POST /v1/unrevoke` | the platform | Cut an install off, or restore it |
+
+`@three-ws/home-bridge` speaks the `/v1/bridge` side for you:
+`createRelayTransport({ relayUrl, relayId, serviceToken })` returns the transport a `HomeBridge`
+takes in place of a URL and a token. See [that package's
+README](../../packages/home-bridge/README.md#a-house-you-cannot-dial-into).
+
+## The allowlist
+
+[`allowlist.json`](allowlist.json) is the contract: which frame types cross, which Home Assistant
+WebSocket commands may be sent into a house, which event types may come back, and which service
+domains are refused outright (`shell_command`, `python_script`, `hassio`, `supervisor`, `backup`,
+`update`, `cloud`, `config`, `auth`, `command_line`, plus named services like
+`homeassistant.restart`).
+
+It is enforced twice: here in JavaScript, and again in Python inside the house. Two enforcement
+points that drift apart would be worse than one, so the Python side **reads this generated file**
+rather than transcribing the rules, and it is generated from `src/protocol.js` rather than
+hand-written:
+
+```bash
+node services/home-relay/scripts/gen-allowlist.mjs
+```
+
+`tests/home-relay-protocol.test.js` fails if the checked-in file is stale, so a rule change that
+forgets to regenerate is a red test rather than a silent divergence between the two enforcers.
+
+Rate limits live in the same manifest, per install, on both frame rate and actuation rate: a bug
+in an integration must not be able to flood a house, and a compromised platform caller must not be
+able to hammer a lock.
+
+## Deploy
+
+It deploys to Cloud Run with `--no-cpu-throttling` and a minimum instance count, and that is not a
+performance preference. A house's dial-out socket has to survive between platform requests; a
+throttled container lets every one of them die and reconnect in a loop.
+
+```bash
+docker build -t home-relay services/home-relay
+```
+
+## Read next
+
+- [`home-assistant-integration/`](../../home-assistant-integration): the other end of the socket,
+ the part that installs in the house through HACS.
+- [`@three-ws/home-bridge`](../../packages/home-bridge): the client that speaks to this.
+- [docs/smart-home.md](../../docs/smart-home.md): why the reachability problem exists and the
+ three honest answers to it.
diff --git a/services/home-satellite/README.md b/services/home-satellite/README.md
new file mode 100644
index 000000000..ba8219c9c
--- /dev/null
+++ b/services/home-satellite/README.md
@@ -0,0 +1,125 @@
+# home-satellite
+
+**Gives a three.ws agent's face and voice to the Home Assistant voice pipeline the household
+already has.**
+
+Home Assistant's Assist pipeline (wake word, speech to text, intent, text to speech) runs on the
+user's own hardware and is already good. What it does not have is a body. This service registers
+as a [Wyoming](https://github.com/rhasspy/wyoming) satellite, so Home Assistant treats it as any
+other voice satellite, and supplies exactly two things: a **microphone** (streamed from a browser
+showing the agent) and a **speaker** (that browser's audio output, with the agent's face moving in
+front of it).
+
+Everything else stays inside the house. The pipeline, the models, the audio: none of it crosses
+the internet.
+
+```
+ Home Assistant ──Wyoming/TCP──► home-satellite ──ws──► a browser with the agent's face
+ (the pipeline) (this service) (microphone in, speaker out)
+```
+
+## The one rule that shapes the whole service
+
+**The pipeline must never depend on the face.** A satellite that hangs Home Assistant because
+somebody closed a browser tab is a satellite that breaks a house, and that is not a trade worth a
+nicer demo. So every acknowledgement Home Assistant waits on is produced by the service itself,
+whether or not anyone is watching: `pong` answers `ping` from the socket, and `played` is sent
+when the audio has been consumed (waiting for a viewer to finish, bounded by the audio's own
+duration plus a grace period, and sent immediately when there is no viewer at all).
+
+Unplug three.ws entirely and the household's voice assistant works exactly as it did before.
+
+## Two roles, one binary
+
+```bash
+node src/index.js satellite # runs in the house, beside Home Assistant (the default)
+node src/index.js hub # runs on Cloud Run, joins satellites to browsers
+node src/index.js token # prints a viewer token for the LAN path, then exits
+node src/index.js --help
+```
+
+The **satellite** listens for Wyoming on TCP, serves viewers on the LAN over HTTP and WebSocket,
+and optionally dials out to a hub so a browser on `https://three.ws` can watch. The **hub** joins
+satellites to viewers and does nothing else: it carries the face, and only the face.
+
+## Run the satellite
+
+```bash
+cd services/home-satellite
+npm ci
+node src/index.js satellite --pairing-code ABC123 --name "Kitchen display" --area Kitchen
+curl -s localhost:10701/healthz
+```
+
+| Flag | Environment variable | Default | What it is |
+|---|---|---|---|
+| `--pairing-code` | `THREE_WS_PAIRING_CODE` | none | A code from three.ws. First run only; after that the identity is on disk |
+| `--name` | `SATELLITE_NAME` | `three.ws agent` | What Home Assistant calls this satellite |
+| `--area` | `SATELLITE_AREA` | none | Suggested area for the device |
+| `--api-base` | `THREE_WS_API_BASE` | `https://three.ws` | Where the pairing code is redeemed |
+| `--state-dir` | `SATELLITE_STATE_DIR` | `./.satellite` | Where the claimed identity is written |
+| `--wyoming-port` | `WYOMING_PORT` | `10700` | TCP port Home Assistant connects to |
+| `--viewer-port` | `VIEWER_PORT` | `10701` | HTTP and WebSocket port browsers on this network use |
+| `--no-hub` | `SATELLITE_HUB=off` | hub on | Do not dial out. LAN viewers only |
+
+The hub role needs `HOME_SATELLITE_HUB_SECRET` and listens on `PORT` (default 8080).
+
+An unpaired satellite **stays up**. It answers `/healthz`, and it tells a connecting Home
+Assistant exactly why it is refusing, which is more useful than a container that exits on boot.
+
+## Point Home Assistant at it
+
+Home Assistant is the client here, not the server: its `wyoming` integration dials out to this
+service.
+
+1. Settings, Devices and services, Add integration, **Wyoming Protocol**.
+2. Host: the machine running this service. Port: `10700`.
+3. It appears as a satellite device. Assign it to an Assist pipeline as you would any other.
+
+Then open the viewer (`http://<host>:10701/viewer`, with a token from `node src/index.js token`)
+on the display that should show the agent, or watch from three.ws when the hub is enabled.
+
+## Pairing, and why there is friction
+
+A satellite is a screen with a microphone that can hear a house. Letting one attach to an agent
+without proving it was invited would be an open relay into strangers' homes. So there is exactly
+one way in: the owner asks three.ws for a pairing code, the code is short, single use and expires
+in minutes, and the service redeems it once at first start. What comes back is a long-lived
+identity written to `--state-dir`, so the code is never handled again.
+
+That friction is the minimum that prevents an open relay, and no smaller version of it exists.
+
+## The states a face has to render
+
+The browser is driven by a small JSON control protocol plus raw PCM in binary frames, deliberately
+separate from Wyoming: Wyoming carries things a web page has no business receiving, and a browser
+needs things Wyoming has no concept of, like which state to draw.
+
+`unpaired`, `pairing`, `idle`, `wake`, `listening`, `thinking`, `speaking`, `error`,
+`disconnected`, `offline`. Every one of them has a design. Both ends validate what the other
+sends: the service because a viewer is a web page, and the browser because a message that does not
+typecheck should paint an honest error rather than a broken face.
+
+## Echo, and why audio in is gated
+
+Home Assistant restarts an always-on pipeline the instant the previous run ends. A display with
+speakers a metre from its microphone would otherwise hear its own answer and wake itself up, so
+audio in is gated while the satellite is speaking. The reference Wyoming satellite solves it the
+same way.
+
+## Endpoints
+
+| Path | Port | What it does |
+|---|---|---|
+| `GET /healthz`, `GET /` | viewer port | Paired state, agent, viewer count, Wyoming version, live pipeline stage |
+| `WS /viewer` | viewer port | A browser attaching a face, microphone and speaker |
+| `WS /room` | hub | The hub side of the same join |
+| Wyoming | `10700` (TCP) | What Home Assistant's `wyoming` integration connects to |
+
+## Read next
+
+- [docs/smart-home.md](../../docs/smart-home.md): where the voice work sits in the campaign.
+- [`@three-ws/home-bridge`](../../packages/home-bridge): the state and action channel, which is a
+ separate path from this one and does not depend on it.
+- [rhasspy/wyoming](https://github.com/rhasspy/wyoming): the protocol, and the reference
+ implementation this follows.
diff --git a/services/home-satellite/package.json b/services/home-satellite/package.json
new file mode 100644
index 000000000..b3bfe3002
--- /dev/null
+++ b/services/home-satellite/package.json
@@ -0,0 +1,22 @@
+{
+ "name": "@three-ws/home-satellite",
+ "version": "1.0.0",
+ "private": true,
+ "type": "module",
+ "description": "Home Assistant Wyoming voice satellite that gives a three.ws agent's 3D body to an existing voice pipeline.",
+ "license": "MIT",
+ "engines": {
+ "node": ">=20"
+ },
+ "bin": {
+ "three-ws-home-satellite": "src/index.js"
+ },
+ "scripts": {
+ "start": "node src/index.js satellite",
+ "hub": "node src/index.js hub",
+ "token": "node src/index.js token"
+ },
+ "dependencies": {
+ "ws": "^8.21.0"
+ }
+}
diff --git a/services/home-satellite/src/bridge.js b/services/home-satellite/src/bridge.js
new file mode 100644
index 000000000..f3ad44eaa
--- /dev/null
+++ b/services/home-satellite/src/bridge.js
@@ -0,0 +1,489 @@
+/**
+ * The bridge between one Wyoming session and the browsers watching it.
+ *
+ * Three pieces live here and they are deliberately the same code path:
+ *
+ * `attachViewer(satellite, socket)` binds a viewer socket to the satellite.
+ * `createViewerServer(...)` serves that directly on the LAN.
+ * `createHubLink(...)` / `createHub(...)` do it through a hosted room when
+ * the browser is on https://three.ws and
+ * the satellite is on a home network that
+ * an https page cannot reach.
+ *
+ * The satellite never knows which of the two it is talking to. It has one
+ * viewer socket, it writes state and audio to it, and it reads microphone audio
+ * and acknowledgements back. The hub fans that single stream out to however
+ * many screens are showing the agent and funnels the microphone back from
+ * whichever one is holding the lease. One house, one microphone, many faces.
+ *
+ * Why a hub exists at all: Home Assistant lives on a LAN, three.ws is served
+ * over https, and a browser refuses `ws://192.168.x.x` from an https page. The
+ * satellite therefore dials out. Nothing listens on the user's network, no port
+ * is forwarded, and the voice path itself never needs the hub: if three.ws is
+ * unreachable the pipeline still runs, the house still responds, and the only
+ * thing missing is the face.
+ */
+
+import { createServer } from 'node:http';
+import { WebSocketServer, WebSocket } from 'ws';
+
+import { DOWN, UP, STATE, readViewerMessage } from './session.js';
+import { ROLE, verifyToken } from './token.js';
+import { WYOMING_VERSION } from './protocol.js';
+
+/** Close codes. 4000+ is the application range. */
+export const CLOSE = Object.freeze({
+ UNAUTHORIZED: 4401,
+ FORBIDDEN: 4403,
+ REPLACED: 4409,
+ PROTOCOL: 4400,
+ GOING_AWAY: 1001,
+});
+
+/** Mic audio arriving faster than this is not a microphone. 16 kHz mono s16 is
+ * 32 kB/s; the ceiling is generous enough for a burst and small enough that a
+ * hostile page cannot use a house as an upload target. */
+const MAX_MIC_BYTES_PER_SECOND = 200_000;
+
+/**
+ * Bind a viewer socket to a satellite session.
+ *
+ * @param {import('./satellite.js').WyomingSatellite} satellite
+ * @param {import('ws').WebSocket} socket
+ * @param {object} options
+ * @param {object} options.identity `{ name, agent, version }` for the hello.
+ * @param {(entry: object) => void} [options.onLog]
+ * @returns {{ detach: () => void }}
+ */
+export function attachViewer(satellite, socket, { identity, onLog = () => {} } = {}) {
+ let detached = false;
+ let micBudget = MAX_MIC_BYTES_PER_SECOND;
+ const budgetTimer = setInterval(() => {
+ micBudget = MAX_MIC_BYTES_PER_SECOND;
+ }, 1000);
+ budgetTimer.unref?.();
+
+ const send = (message) => {
+ if (detached || socket.readyState !== WebSocket.OPEN) return;
+ socket.send(JSON.stringify(message));
+ };
+
+ send({
+ t: DOWN.HELLO,
+ satellite: {
+ name: identity?.name || satellite.name,
+ agent: identity?.agent || null,
+ version: identity?.version || satellite.version,
+ wyoming: WYOMING_VERSION,
+ },
+ state: satellite.state,
+ viewers: 1,
+ });
+
+ const onState = ({ state, detail }) => send({ t: DOWN.STATE, state, detail });
+ const onWake = ({ name }) => send({ t: DOWN.WAKE, name });
+ const onVoice = ({ speaking }) => send({ t: DOWN.VOICE, speaking });
+ const onTranscript = ({ text, final }) => send({ t: DOWN.TRANSCRIPT, text, final });
+ const onSpeech = ({ text }) => send({ t: DOWN.SPEECH, text });
+ const onAudioStart = (format) => send({ t: DOWN.AUDIO_START, ...format });
+ const onAudioStop = () => send({ t: DOWN.AUDIO_STOP });
+ const onError = ({ text, code }) => send({ t: DOWN.ERROR, text, code });
+ const onAudio = ({ audio }) => {
+ if (detached || socket.readyState !== WebSocket.OPEN) return;
+ socket.send(audio, { binary: true });
+ };
+ const onHaDisconnected = () => send({ t: DOWN.STATE, state: STATE.DISCONNECTED, detail: 'Home Assistant is not connected' });
+
+ satellite.on('state', onState);
+ satellite.on('wake', onWake);
+ satellite.on('voice', onVoice);
+ satellite.on('transcript', onTranscript);
+ satellite.on('speech', onSpeech);
+ satellite.on('audio-start', onAudioStart);
+ satellite.on('audio', onAudio);
+ satellite.on('audio-stop', onAudioStop);
+ satellite.on('pipeline-error', onError);
+ satellite.on('ha-disconnected', onHaDisconnected);
+
+ socket.on('message', (raw, isBinary) => {
+ if (detached) return;
+ if (isBinary) {
+ const bytes = raw.length ?? raw.byteLength ?? 0;
+ micBudget -= bytes;
+ if (micBudget < 0) {
+ onLog({ level: 'warn', event: 'viewer.mic_flood' });
+ socket.close(CLOSE.PROTOCOL, 'microphone rate');
+ return;
+ }
+ satellite.pushMic(raw);
+ return;
+ }
+ let parsed;
+ try {
+ parsed = JSON.parse(raw.toString('utf8'));
+ } catch {
+ socket.close(CLOSE.PROTOCOL, 'bad json');
+ return;
+ }
+ const message = readViewerMessage(parsed);
+ if (!message) {
+ socket.close(CLOSE.PROTOCOL, 'unknown message');
+ return;
+ }
+ switch (message.t) {
+ case UP.MIC_START:
+ if (!satellite.startMic(message.mode)) {
+ send({ t: DOWN.ERROR, code: 'not_connected', text: 'Home Assistant is not connected, so there is nothing to listen with.' });
+ }
+ return;
+ case UP.MIC_STOP:
+ satellite.stopMic();
+ return;
+ case UP.PLAYED:
+ satellite.reportPlayed();
+ return;
+ case UP.PING:
+ send({ t: DOWN.PONG, at: message.at });
+ return;
+ default:
+ return;
+ }
+ });
+
+ const detach = () => {
+ if (detached) return;
+ detached = true;
+ clearInterval(budgetTimer);
+ satellite.off('state', onState);
+ satellite.off('wake', onWake);
+ satellite.off('voice', onVoice);
+ satellite.off('transcript', onTranscript);
+ satellite.off('speech', onSpeech);
+ satellite.off('audio-start', onAudioStart);
+ satellite.off('audio', onAudio);
+ satellite.off('audio-stop', onAudioStop);
+ satellite.off('pipeline-error', onError);
+ satellite.off('ha-disconnected', onHaDisconnected);
+ satellite.stopMic();
+ };
+
+ socket.on('close', detach);
+ socket.on('error', detach);
+ return { detach };
+}
+
+/**
+ * Serve viewers directly from the satellite, on the same network as the house.
+ * This is the local-first path: no cloud, no relay, no account, and it keeps
+ * working when three.ws does not.
+ *
+ * @param {object} options
+ * @param {import('./satellite.js').WyomingSatellite} options.satellite
+ * @param {string} options.satelliteId
+ * @param {string} options.secret Viewer-token signing key for this satellite.
+ * @param {object} options.identity
+ * @param {(entry: object) => void} [options.onLog]
+ */
+export function createViewerServer({ satellite, satelliteId, secret, identity, onLog = () => {} }) {
+ const http = createServer((req, res) => {
+ if (req.url === '/healthz' || req.url === '/') {
+ const body = JSON.stringify({ ok: true, satellite_id: satelliteId, ...satellite.snapshot(), viewers: viewers.size });
+ res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+ res.end(body);
+ return;
+ }
+ res.writeHead(404, { 'content-type': 'application/json' });
+ res.end('{"error":"not_found"}');
+ });
+
+ const wss = new WebSocketServer({ noServer: true });
+ const viewers = new Set();
+
+ http.on('upgrade', (req, socket, head) => {
+ let url;
+ try {
+ url = new URL(req.url, 'http://satellite.local');
+ } catch {
+ socket.destroy();
+ return;
+ }
+ if (url.pathname !== '/viewer') {
+ socket.destroy();
+ return;
+ }
+ const check = verifyToken(url.searchParams.get('token') || '', secret);
+ if (!check.ok || check.claims.role !== ROLE.VIEWER || check.claims.sid !== satelliteId) {
+ onLog({ level: 'warn', event: 'viewer.rejected', reason: check.ok ? 'wrong_room' : check.reason });
+ // A rejection has to be a WebSocket close, not a destroyed socket: a
+ // browser reports a destroyed socket as a generic network failure and
+ // the person on the other end has no idea their session expired.
+ wss.handleUpgrade(req, socket, head, (ws) => ws.close(CLOSE.UNAUTHORIZED, check.ok ? 'wrong satellite' : check.reason));
+ return;
+ }
+ wss.handleUpgrade(req, socket, head, (ws) => {
+ const bound = attachViewer(satellite, ws, { identity, onLog });
+ viewers.add(ws);
+ ws.on('close', () => {
+ viewers.delete(ws);
+ bound.detach();
+ });
+ onLog({ level: 'info', event: 'viewer.attached', viewers: viewers.size });
+ });
+ });
+
+ return {
+ listen: (port, host = '0.0.0.0') => new Promise((resolve, reject) => {
+ http.on('error', reject);
+ http.listen(port, host, () => {
+ http.off('error', reject);
+ resolve(http.address());
+ });
+ }),
+ close: () => new Promise((resolve) => {
+ for (const ws of viewers) ws.close(CLOSE.GOING_AWAY, 'shutting down');
+ viewers.clear();
+ wss.close(() => http.close(resolve));
+ }),
+ get viewers() {
+ return viewers.size;
+ },
+ };
+}
+
+/**
+ * The hosted room. Joins one satellite to the browsers allowed to watch it.
+ *
+ * It holds no database and no Home Assistant credential. Membership is proved
+ * by the signature on the token each socket presents, and the only thing it can
+ * do is move bytes between two sockets that presented tokens for the same room.
+ */
+export function createHub({ secret, onLog = () => {} } = {}) {
+ if (!secret) throw new Error('createHub: secret required');
+ const rooms = new Map();
+
+ const room = (sid) => {
+ let r = rooms.get(sid);
+ if (!r) {
+ r = { sid, satellite: null, viewers: new Set(), hello: null, state: null, micHolder: null };
+ rooms.set(sid, r);
+ }
+ return r;
+ };
+
+ const http = createServer((req, res) => {
+ if (req.url === '/healthz') {
+ res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+ res.end(JSON.stringify({
+ ok: true,
+ rooms: rooms.size,
+ satellites: [...rooms.values()].filter((r) => r.satellite).length,
+ viewers: [...rooms.values()].reduce((n, r) => n + r.viewers.size, 0),
+ }));
+ return;
+ }
+ res.writeHead(404, { 'content-type': 'application/json' });
+ res.end('{"error":"not_found"}');
+ });
+
+ const wss = new WebSocketServer({ noServer: true });
+
+ http.on('upgrade', (req, socket, head) => {
+ let url;
+ try {
+ url = new URL(req.url, 'http://hub.local');
+ } catch {
+ socket.destroy();
+ return;
+ }
+ if (url.pathname !== '/room') {
+ socket.destroy();
+ return;
+ }
+ const check = verifyToken(url.searchParams.get('token') || '', secret);
+ if (!check.ok) {
+ onLog({ level: 'warn', event: 'hub.rejected', reason: check.reason });
+ wss.handleUpgrade(req, socket, head, (ws) => ws.close(CLOSE.UNAUTHORIZED, check.reason));
+ return;
+ }
+ wss.handleUpgrade(req, socket, head, (ws) => join(ws, check.claims));
+ });
+
+ function join(ws, claims) {
+ const r = room(claims.sid);
+ if (claims.role === ROLE.SATELLITE) {
+ if (r.satellite && r.satellite.readyState === WebSocket.OPEN) {
+ // The house reconnected before the hub noticed the old socket died.
+ // The newest socket is the live one.
+ r.satellite.close(CLOSE.REPLACED, 'replaced by a newer connection');
+ }
+ r.satellite = ws;
+ onLog({ level: 'info', event: 'hub.satellite_joined', sid: claims.sid, viewers: r.viewers.size });
+ ws.on('message', (raw, isBinary) => {
+ if (!isBinary) cacheDownstream(r, raw);
+ for (const viewer of r.viewers) {
+ if (viewer.readyState === WebSocket.OPEN) viewer.send(raw, { binary: isBinary });
+ }
+ });
+ ws.on('close', () => {
+ if (r.satellite !== ws) return;
+ r.satellite = null;
+ r.hello = null;
+ const gone = JSON.stringify({ t: DOWN.STATE, state: STATE.DISCONNECTED, detail: 'The satellite went offline' });
+ for (const viewer of r.viewers) {
+ if (viewer.readyState === WebSocket.OPEN) viewer.send(gone);
+ }
+ onLog({ level: 'info', event: 'hub.satellite_left', sid: claims.sid });
+ if (!r.viewers.size) rooms.delete(claims.sid);
+ });
+ return;
+ }
+
+ r.viewers.add(ws);
+ onLog({ level: 'info', event: 'hub.viewer_joined', sid: claims.sid, viewers: r.viewers.size });
+ // Replay what a joining viewer missed. Without this a browser that opens
+ // after the satellite has already announced itself sits on a blank screen
+ // until the next state change, which on a quiet house can be hours.
+ if (r.hello) ws.send(r.hello);
+ if (r.state) ws.send(r.state);
+ if (!r.satellite) ws.send(JSON.stringify({ t: DOWN.STATE, state: STATE.DISCONNECTED, detail: 'The satellite is offline' }));
+
+ ws.on('message', (raw, isBinary) => {
+ if (!r.satellite || r.satellite.readyState !== WebSocket.OPEN) return;
+ // One house has one microphone. The first viewer to open it holds the
+ // lease until it closes it or leaves; everyone else watches. Without
+ // this, two open tabs stream two microphones into one pipeline and the
+ // transcript is a duet.
+ if (isBinary) {
+ if (r.micHolder !== ws) return;
+ r.satellite.send(raw, { binary: true });
+ return;
+ }
+ let parsed;
+ try {
+ parsed = JSON.parse(raw.toString('utf8'));
+ } catch {
+ ws.close(CLOSE.PROTOCOL, 'bad json');
+ return;
+ }
+ const message = readViewerMessage(parsed);
+ if (!message) {
+ ws.close(CLOSE.PROTOCOL, 'unknown message');
+ return;
+ }
+ if (message.t === UP.MIC_START) {
+ if (r.micHolder && r.micHolder !== ws && r.micHolder.readyState === WebSocket.OPEN) return;
+ r.micHolder = ws;
+ }
+ if (message.t === UP.MIC_STOP) {
+ if (r.micHolder !== ws) return;
+ r.micHolder = null;
+ }
+ r.satellite.send(JSON.stringify(message));
+ });
+
+ ws.on('close', () => {
+ r.viewers.delete(ws);
+ if (r.micHolder === ws) {
+ r.micHolder = null;
+ if (r.satellite?.readyState === WebSocket.OPEN) r.satellite.send(JSON.stringify({ t: UP.MIC_STOP }));
+ }
+ onLog({ level: 'info', event: 'hub.viewer_left', sid: claims.sid, viewers: r.viewers.size });
+ if (!r.viewers.size && !r.satellite) rooms.delete(claims.sid);
+ });
+ }
+
+ function cacheDownstream(r, raw) {
+ const text = raw.toString('utf8');
+ let parsed;
+ try {
+ parsed = JSON.parse(text);
+ } catch {
+ return;
+ }
+ if (parsed?.t === DOWN.HELLO) r.hello = text;
+ else if (parsed?.t === DOWN.STATE) r.state = text;
+ }
+
+ return {
+ listen: (port, host = '0.0.0.0') => new Promise((resolve, reject) => {
+ http.on('error', reject);
+ http.listen(port, host, () => {
+ http.off('error', reject);
+ resolve(http.address());
+ });
+ }),
+ close: () => new Promise((resolve) => {
+ for (const r of rooms.values()) {
+ r.satellite?.close(CLOSE.GOING_AWAY, 'shutting down');
+ for (const v of r.viewers) v.close(CLOSE.GOING_AWAY, 'shutting down');
+ }
+ rooms.clear();
+ wss.close(() => http.close(resolve));
+ }),
+ stats: () => ({
+ rooms: rooms.size,
+ satellites: [...rooms.values()].filter((r) => r.satellite).length,
+ viewers: [...rooms.values()].reduce((n, r) => n + r.viewers.size, 0),
+ }),
+ };
+}
+
+/**
+ * Dial out to a hub and present that socket to the satellite as one viewer.
+ *
+ * Reconnects with a bounded exponential backoff. The backoff matters more than
+ * it looks: a thousand kitchen displays reconnecting in lockstep after a hub
+ * restart is a self-inflicted outage, so the delay is jittered.
+ */
+export function createHubLink({ satellite, url, token, identity, onLog = () => {} }) {
+ let socket = null;
+ let bound = null;
+ let stopped = false;
+ let attempt = 0;
+ let timer = null;
+
+ const connect = () => {
+ if (stopped) return;
+ const target = `${url}${url.includes('?') ? '&' : '?'}token=${encodeURIComponent(token())}`;
+ socket = new WebSocket(target);
+
+ socket.on('open', () => {
+ attempt = 0;
+ bound = attachViewer(satellite, socket, { identity, onLog });
+ onLog({ level: 'info', event: 'hub.link_open' });
+ });
+ socket.on('close', (code, reason) => {
+ bound?.detach();
+ bound = null;
+ socket = null;
+ onLog({ level: 'warn', event: 'hub.link_closed', code, reason: reason?.toString() });
+ schedule();
+ });
+ socket.on('error', (err) => {
+ onLog({ level: 'warn', event: 'hub.link_error', message: err.message });
+ });
+ };
+
+ const schedule = () => {
+ if (stopped) return;
+ attempt += 1;
+ const base = Math.min(30_000, 500 * 2 ** Math.min(attempt, 6));
+ const delay = Math.round(base * (0.5 + Math.random() / 2));
+ timer = setTimeout(connect, delay);
+ timer.unref?.();
+ };
+
+ connect();
+
+ return {
+ close: () => {
+ stopped = true;
+ if (timer) clearTimeout(timer);
+ bound?.detach();
+ socket?.close(CLOSE.GOING_AWAY, 'shutting down');
+ },
+ get connected() {
+ return socket?.readyState === WebSocket.OPEN;
+ },
+ };
+}
diff --git a/services/home-satellite/src/index.js b/services/home-satellite/src/index.js
new file mode 100755
index 000000000..e3ca4aa26
--- /dev/null
+++ b/services/home-satellite/src/index.js
@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Entry point. One binary, two roles.
+ *
+ * node src/index.js satellite run beside Home Assistant (the default)
+ * node src/index.js hub run the hosted room server
+ *
+ * Everything is configurable by environment variable so the container needs no
+ * arguments; the flags exist because reading a `docker run` line with eight
+ * `-e` switches is worse than reading one with eight flags.
+ */
+
+import { createSatelliteService, createHubService, SERVICE_VERSION } from './server.js';
+
+const argv = process.argv.slice(2);
+const role = argv.find((a) => !a.startsWith('-')) || process.env.SATELLITE_ROLE || 'satellite';
+const flag = (name, fallback) => {
+ const i = argv.indexOf(`--${name}`);
+ return i === -1 ? fallback : argv[i + 1];
+};
+
+if (argv.includes('--help') || argv.includes('-h')) {
+ process.stdout.write(`three.ws home satellite ${SERVICE_VERSION}
+
+ node src/index.js satellite [flags]
+ --pairing-code <code> redeem a code from three.ws/home/satellite (first run only)
+ --name <name> what Home Assistant calls this satellite
+ --area <area> suggested area for the device
+ --api-base <url> three.ws base URL (default https://three.ws)
+ --state-dir <dir> where the claimed identity is written (default ./.satellite)
+ --wyoming-port <port> TCP port Home Assistant connects to (default 10700)
+ --viewer-port <port> HTTP/WebSocket port browsers on this network use (default 10701)
+ --no-hub do not dial out; LAN viewers only
+
+ node src/index.js hub [flags]
+ --port <port> listen port (default 8080, or $PORT)
+
+ node src/index.js token print a viewer token for the LAN path and exit
+`);
+ process.exit(0);
+}
+
+const log = (entry) => console.log(JSON.stringify({ ts: new Date().toISOString(), ...entry }));
+
+if (role === 'hub') {
+ const service = await createHubService({ port: Number(flag('port', process.env.PORT || 8080)), log });
+ for (const signal of ['SIGTERM', 'SIGINT']) {
+ process.on(signal, () => {
+ log({ level: 'info', event: 'hub.shutdown', signal, ...service.stats() });
+ service.close().then(() => process.exit(0), () => process.exit(1));
+ });
+ }
+} else {
+ const service = await createSatelliteService({
+ stateDir: flag('state-dir', process.env.SATELLITE_STATE_DIR || './.satellite'),
+ apiBase: flag('api-base', process.env.THREE_WS_API_BASE || 'https://three.ws'),
+ pairingCode: flag('pairing-code', process.env.THREE_WS_PAIRING_CODE || null),
+ name: flag('name', process.env.SATELLITE_NAME || 'three.ws agent'),
+ area: flag('area', process.env.SATELLITE_AREA || null),
+ wyomingPort: Number(flag('wyoming-port', process.env.WYOMING_PORT || 10700)),
+ viewerPort: Number(flag('viewer-port', process.env.VIEWER_PORT || 10701)),
+ hub: !argv.includes('--no-hub') && process.env.SATELLITE_HUB !== 'off',
+ log,
+ });
+
+ if (role === 'token') {
+ const token = service.viewerToken(3600);
+ await service.close();
+ if (!token) {
+ console.error('this satellite has not been paired, so it has no room to hand out tokens for');
+ process.exit(1);
+ }
+ process.stdout.write(`${token}\n`);
+ process.exit(0);
+ }
+
+ const health = service.health();
+ log({ level: 'info', event: 'satellite.ready', ...health });
+ if (!health.paired) {
+ // Stay up. An unpaired satellite still answers its health endpoint and
+ // still tells a connecting Home Assistant exactly why it is refusing, and
+ // both of those are more useful than a container that exits on boot.
+ log({ level: 'warn', event: 'satellite.unpaired', message: health.pairing_error });
+ }
+
+ for (const signal of ['SIGTERM', 'SIGINT']) {
+ process.on(signal, () => {
+ log({ level: 'info', event: 'satellite.shutdown', signal });
+ service.close().then(() => process.exit(0), () => process.exit(1));
+ });
+ }
+}
diff --git a/services/home-satellite/src/pairing.js b/services/home-satellite/src/pairing.js
new file mode 100644
index 000000000..debc4d881
--- /dev/null
+++ b/services/home-satellite/src/pairing.js
@@ -0,0 +1,130 @@
+/**
+ * Pairing: how a satellite comes to belong to somebody.
+ *
+ * A satellite is a screen with a microphone that can hear a house. Letting one
+ * attach to an agent without proving it was invited would be an open relay into
+ * strangers' homes, so there is exactly one way in: the owner asks three.ws for
+ * a pairing code, the code is short, single-use and expires in minutes, and the
+ * service redeems it once at first start. What it gets back is a long-lived
+ * identity it writes to disk, so the code never has to be handled again.
+ *
+ * The friction here is the point. It is the minimum that prevents an open
+ * relay, and no smaller version of it exists.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const IDENTITY_FILE = 'identity.json';
+
+/**
+ * Read the identity written by a previous claim.
+ * @param {string} stateDir
+ * @returns {Promise<object|null>}
+ */
+export async function loadIdentity(stateDir) {
+ try {
+ const raw = await readFile(join(stateDir, IDENTITY_FILE), 'utf8');
+ const identity = JSON.parse(raw);
+ if (!identity?.satellite_id || !identity?.secret) return null;
+ return identity;
+ } catch (err) {
+ if (err.code === 'ENOENT') return null;
+ throw err;
+ }
+}
+
+/**
+ * Persist an identity. Written with mode 0600: it holds the key that lets this
+ * process act as somebody's satellite.
+ * @param {string} stateDir
+ * @param {object} identity
+ */
+export async function saveIdentity(stateDir, identity) {
+ await mkdir(stateDir, { recursive: true });
+ await writeFile(join(stateDir, IDENTITY_FILE), `${JSON.stringify(identity, null, '\t')}\n`, { mode: 0o600 });
+}
+
+/**
+ * Redeem a pairing code.
+ *
+ * @param {object} options
+ * @param {string} options.apiBase e.g. https://three.ws
+ * @param {string} options.code The code from three.ws/home/satellite.
+ * @param {string} options.name What the satellite should be called.
+ * @param {string} options.version This service's version.
+ * @param {string|null} [options.area]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @returns {Promise<object>} the identity to persist
+ */
+export async function claimPairingCode({ apiBase, code, name, version, area = null, fetchImpl = fetch }) {
+ const res = await fetchImpl(`${apiBase.replace(/\/+$/, '')}/api/home/satellite`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ action: 'claim', code, name, version, area }),
+ });
+ const text = await res.text();
+ let body = null;
+ try {
+ body = JSON.parse(text);
+ } catch {
+ /* handled below: a non-JSON body is reported verbatim */
+ }
+ if (!res.ok) {
+ const reason = body?.message || body?.error || text.slice(0, 200) || `HTTP ${res.status}`;
+ const err = new Error(`pairing failed: ${reason}`);
+ err.status = res.status;
+ err.code = body?.error || 'pairing_failed';
+ throw err;
+ }
+ if (!body?.satellite_id || !body?.secret) {
+ throw new Error('pairing failed: three.ws did not return a satellite identity');
+ }
+ return {
+ satellite_id: body.satellite_id,
+ secret: body.secret,
+ api_base: apiBase.replace(/\/+$/, ''),
+ hub_url: body.hub_url || null,
+ hub_token: body.hub_token || null,
+ hub_token_exp: body.hub_token_exp || 0,
+ agent: body.agent || null,
+ name: body.name || name,
+ claimed_at: new Date().toISOString(),
+ };
+}
+
+/**
+ * Exchange the stored secret for a fresh hub token. Called at start and again
+ * before the current one expires, so a satellite that has been up for a month
+ * is still allowed into its own room.
+ *
+ * @param {object} options
+ * @param {object} options.identity
+ * @param {typeof fetch} [options.fetchImpl]
+ */
+export async function refreshHubToken({ identity, fetchImpl = fetch }) {
+ const res = await fetchImpl(`${identity.api_base}/api/home/satellite`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ action: 'session', satellite_id: identity.satellite_id, secret: identity.secret }),
+ });
+ const text = await res.text();
+ let body = null;
+ try {
+ body = JSON.parse(text);
+ } catch {
+ /* handled below */
+ }
+ if (!res.ok) {
+ const err = new Error(`hub session refused: ${body?.message || body?.error || `HTTP ${res.status}`}`);
+ err.status = res.status;
+ err.code = body?.error || 'session_failed';
+ throw err;
+ }
+ return {
+ hub_url: body.hub_url || identity.hub_url,
+ hub_token: body.hub_token,
+ hub_token_exp: body.hub_token_exp || 0,
+ agent: body.agent || identity.agent,
+ };
+}
diff --git a/services/home-satellite/src/server.js b/services/home-satellite/src/server.js
new file mode 100644
index 000000000..902bbdaad
--- /dev/null
+++ b/services/home-satellite/src/server.js
@@ -0,0 +1,209 @@
+/**
+ * The service. Composes everything into the two shapes it deploys in.
+ *
+ * createSatelliteService() runs beside Home Assistant, on the user's own
+ * network. It listens for Wyoming on TCP, serves
+ * viewers on the LAN, and optionally dials out to a
+ * hub so a browser on https://three.ws can watch.
+ *
+ * createHubService() runs on Cloud Run. It joins satellites to viewers
+ * and does nothing else.
+ *
+ * Everything about the satellite is local-first by construction. The Wyoming
+ * socket, the pipeline, the microphone and the speaker never leave the house.
+ * The hub carries the face and only the face; unplug it and the voice assistant
+ * keeps working exactly as it did before three.ws was installed.
+ */
+
+import { WyomingSatellite } from './satellite.js';
+import { createViewerServer, createHub, createHubLink } from './bridge.js';
+import { loadIdentity, saveIdentity, claimPairingCode, refreshHubToken } from './pairing.js';
+import { signToken, ROLE } from './token.js';
+import { WYOMING_VERSION } from './protocol.js';
+
+export const SERVICE_VERSION = '1.0.0';
+
+/** Refresh the hub token this long before it expires. */
+const HUB_TOKEN_LEAD_SECONDS = 600;
+
+const stamp = (entry) => JSON.stringify({ ts: new Date().toISOString(), ...entry });
+
+/**
+ * @param {object} options
+ * @param {string} [options.stateDir] Where the identity is persisted.
+ * @param {string} [options.apiBase] three.ws base URL.
+ * @param {string|null} [options.pairingCode] Redeemed once, on first start.
+ * @param {string} [options.name]
+ * @param {string|null} [options.area]
+ * @param {number} [options.wyomingPort=10700]
+ * @param {number} [options.viewerPort=10701]
+ * @param {string} [options.host='0.0.0.0']
+ * @param {boolean} [options.hub=true] Dial out so https browsers can attach.
+ * @param {(entry: object) => void} [options.log]
+ * @param {typeof fetch} [options.fetchImpl]
+ */
+export async function createSatelliteService({
+ stateDir = process.env.SATELLITE_STATE_DIR || './.satellite',
+ apiBase = process.env.THREE_WS_API_BASE || 'https://three.ws',
+ pairingCode = process.env.THREE_WS_PAIRING_CODE || null,
+ name = process.env.SATELLITE_NAME || 'three.ws agent',
+ area = process.env.SATELLITE_AREA || null,
+ wyomingPort = Number(process.env.WYOMING_PORT || 10700),
+ viewerPort = Number(process.env.VIEWER_PORT || 10701),
+ host = process.env.BIND_HOST || '0.0.0.0',
+ hub = process.env.SATELLITE_HUB !== 'off',
+ log = (entry) => console.log(stamp(entry)),
+ fetchImpl = fetch,
+} = {}) {
+ let identity = await loadIdentity(stateDir);
+ let pairingError = null;
+
+ if (!identity && pairingCode) {
+ log({ level: 'info', event: 'pairing.claiming' });
+ try {
+ identity = await claimPairingCode({ apiBase, code: pairingCode, name, version: SERVICE_VERSION, area, fetchImpl });
+ await saveIdentity(stateDir, identity);
+ log({ level: 'info', event: 'pairing.claimed', satellite_id: identity.satellite_id, agent: identity.agent?.name || null });
+ } catch (err) {
+ pairingError = err.message;
+ log({ level: 'error', event: 'pairing.failed', message: err.message, code: err.code || null });
+ }
+ } else if (!identity) {
+ pairingError = 'no pairing code was supplied and no identity has been claimed';
+ log({ level: 'error', event: 'pairing.missing' });
+ }
+
+ const paired = !!identity;
+ const displayName = identity?.name || name;
+
+ // Declared before the satellite is constructed, not after: the satellite is
+ // handed `hasViewer` and starts listening in the same tick, and a reference
+ // that is still in its temporal dead zone when the first socket lands throws
+ // instead of answering.
+ let viewerServer = null;
+ let viewerAddress = null;
+ let hubLink = null;
+ let hubRefresh = null;
+ const viewerCount = () => (viewerServer?.viewers || 0) + (hubLink?.connected ? 1 : 0);
+ const satellite = new WyomingSatellite({
+ name: displayName,
+ description: identity?.agent?.name
+ ? `${identity.agent.name}, a three.ws agent with a face, a voice and a body`
+ : 'A three.ws agent with a face, a voice and a body',
+ version: SERVICE_VERSION,
+ area,
+ paired,
+ hasViewer: () => viewerCount() > 0,
+ });
+ satellite.on('log', log);
+ satellite.on('state', ({ state, detail }) => log({ level: 'debug', event: 'satellite.state', state, detail }));
+
+ const wyomingAddress = await satellite.listen(wyomingPort, host);
+ log({ level: 'info', event: 'wyoming.listening', port: wyomingAddress.port, paired });
+
+ const identityForViewer = {
+ name: displayName,
+ agent: identity?.agent || null,
+ version: SERVICE_VERSION,
+ };
+
+ if (paired) {
+ viewerServer = createViewerServer({
+ satellite,
+ satelliteId: identity.satellite_id,
+ secret: identity.secret,
+ identity: identityForViewer,
+ onLog: log,
+ });
+ viewerAddress = await viewerServer.listen(viewerPort, host);
+ log({ level: 'info', event: 'viewer.listening', port: viewerAddress.port });
+
+ if (hub && identity.hub_url) {
+ // The token is read fresh on every dial, so a reconnect after a long
+ // outage picks up whatever the refresh loop last stored rather than
+ // replaying an expired one.
+ hubLink = createHubLink({
+ satellite,
+ url: identity.hub_url,
+ token: () => identity.hub_token,
+ identity: identityForViewer,
+ onLog: log,
+ });
+
+ const refresh = async () => {
+ try {
+ const next = await refreshHubToken({ identity, fetchImpl });
+ identity = { ...identity, ...next };
+ await saveIdentity(stateDir, identity);
+ log({ level: 'info', event: 'hub.token_refreshed', expires: identity.hub_token_exp });
+ } catch (err) {
+ log({ level: 'warn', event: 'hub.token_refresh_failed', message: err.message });
+ }
+ };
+ const schedule = () => {
+ const seconds = Math.max(60, (identity.hub_token_exp || 0) - Math.floor(Date.now() / 1000) - HUB_TOKEN_LEAD_SECONDS);
+ hubRefresh = setTimeout(async () => {
+ await refresh();
+ schedule();
+ }, seconds * 1000);
+ hubRefresh.unref?.();
+ };
+ schedule();
+ }
+ }
+
+ return {
+ satellite,
+ identity,
+ wyomingPort: wyomingAddress.port,
+ viewerPort: viewerAddress?.port ?? null,
+ /**
+ * Mint a viewer token for the LAN path. A browser on the same network as
+ * the house can attach with this and never touch three.ws at all.
+ * @param {number} [ttlSeconds=900]
+ */
+ viewerToken(ttlSeconds = 900) {
+ if (!identity) return null;
+ return signToken({ sid: identity.satellite_id, role: ROLE.VIEWER }, identity.secret, ttlSeconds);
+ },
+ health() {
+ return {
+ ok: paired,
+ service: 'home-satellite',
+ version: SERVICE_VERSION,
+ wyoming: WYOMING_VERSION,
+ paired,
+ pairing_error: pairingError,
+ satellite_id: identity?.satellite_id || null,
+ agent: identity?.agent || null,
+ hub_connected: !!hubLink?.connected,
+ viewers: viewerCount(),
+ ...satellite.snapshot(),
+ };
+ },
+ async close() {
+ if (hubRefresh) clearTimeout(hubRefresh);
+ hubLink?.close();
+ await viewerServer?.close();
+ await satellite.close();
+ },
+ };
+}
+
+/**
+ * @param {object} options
+ * @param {string} [options.secret] Hub token signing key.
+ * @param {number} [options.port]
+ * @param {(entry: object) => void} [options.log]
+ */
+export async function createHubService({
+ secret = process.env.HOME_SATELLITE_HUB_SECRET,
+ port = Number(process.env.PORT || 8080),
+ log = (entry) => console.log(stamp(entry)),
+} = {}) {
+ if (!secret) throw new Error('createHubService: HOME_SATELLITE_HUB_SECRET is required');
+ const hub = createHub({ secret, onLog: log });
+ const address = await hub.listen(port);
+ log({ level: 'info', event: 'hub.listening', port: address.port });
+ return { hub, port: address.port, stats: hub.stats, close: () => hub.close() };
+}
diff --git a/src/home/satellite-link.js b/src/home/satellite-link.js
new file mode 100644
index 000000000..b9338871c
--- /dev/null
+++ b/src/home/satellite-link.js
@@ -0,0 +1,285 @@
+/**
+ * The browser's end of a satellite session.
+ *
+ * Owns one WebSocket to the satellite service (directly on the LAN, or through
+ * the hub), the microphone that feeds it, and the audio that comes back. It
+ * knows nothing about the DOM: it emits state and the page renders it, which is
+ * what makes the ten states testable and what stops "the socket dropped" and
+ * "the avatar looks wrong" from being the same bug.
+ *
+ * The one behaviour worth stating loudly: **this connection is optional.** Home
+ * Assistant's pipeline runs whether or not this page exists. Losing the socket
+ * loses the face, never the voice, and the UI is written to say so rather than
+ * to look broken.
+ */
+
+import { MicCapture, PcmDownsampler } from '../voice/mic-capture.js';
+import { PcmPlayer } from './pcm-player.js';
+
+/** Mirrors services/home-satellite/src/session.js. Both ends validate. */
+export const STATE = Object.freeze({
+ UNPAIRED: 'unpaired',
+ PAIRING: 'pairing',
+ IDLE: 'idle',
+ WAKE: 'wake',
+ LISTENING: 'listening',
+ THINKING: 'thinking',
+ SPEAKING: 'speaking',
+ ERROR: 'error',
+ DISCONNECTED: 'disconnected',
+ OFFLINE: 'offline',
+});
+
+const RECONNECT_BASE_MS = 700;
+const RECONNECT_MAX_MS = 20_000;
+
+export class SatelliteLink extends EventTarget {
+ /**
+ * @param {object} options
+ * @param {() => Promise<{url: string, token: string}>} options.resolve
+ * Fetches a fresh socket URL and token. Called on every connect, not
+ * once: viewer tokens are deliberately short lived, so a reconnect an
+ * hour later has to mint a new one rather than replay a dead one.
+ */
+ constructor({ resolve }) {
+ super();
+ this._resolve = resolve;
+ this._socket = null;
+ this._stopped = false;
+ this._attempt = 0;
+ this._timer = 0;
+
+ this.state = STATE.OFFLINE;
+ this.detail = null;
+ this.satellite = null;
+ this.transcript = '';
+ this.answer = '';
+ this.wakeWord = null;
+ this.lastError = null;
+
+ this._player = new PcmPlayer();
+ this._mic = null;
+ this._micMode = null;
+ }
+
+ /** The analyser the lipsync driver reads. Null until the agent first speaks. */
+ get analyser() {
+ return this._player.analyser;
+ }
+
+ get micOpen() {
+ return !!this._mic;
+ }
+
+ get connected() {
+ return this._socket?.readyState === WebSocket.OPEN;
+ }
+
+ _emit(type, detail = {}) {
+ this.dispatchEvent(new CustomEvent(type, { detail }));
+ }
+
+ _setState(state, detail = null) {
+ this.state = state;
+ this.detail = detail;
+ this._emit('state', { state, detail });
+ }
+
+ async connect() {
+ this._stopped = false;
+ clearTimeout(this._timer);
+
+ let target;
+ try {
+ target = await this._resolve();
+ } catch (err) {
+ this.lastError = err;
+ this._setState(STATE.ERROR, err.message);
+ this._scheduleReconnect();
+ return;
+ }
+ if (this._stopped) return;
+
+ const url = new URL(target.url);
+ url.searchParams.set('token', target.token);
+ const socket = new WebSocket(url.toString());
+ socket.binaryType = 'arraybuffer';
+ this._socket = socket;
+
+ socket.onopen = () => {
+ this._attempt = 0;
+ this._emit('open', {});
+ };
+
+ socket.onmessage = (event) => {
+ if (event.data instanceof ArrayBuffer) {
+ this._player.push(event.data);
+ return;
+ }
+ let message;
+ try {
+ message = JSON.parse(event.data);
+ } catch {
+ return;
+ }
+ this._handle(message);
+ };
+
+ socket.onerror = () => {
+ // `error` on a WebSocket carries nothing useful; `close` follows with
+ // the code that does.
+ };
+
+ socket.onclose = (event) => {
+ if (this._socket !== socket) return;
+ this._socket = null;
+ this._stopMic();
+ this._player.stop();
+ if (this._stopped) return;
+ // 4401 is the service refusing the token. Reconnecting on a loop with
+ // a token it has already rejected is a busy wait; the page has to send
+ // the user somewhere instead, so this surfaces rather than retries.
+ if (event.code === 4401 || event.code === 4403) {
+ this._setState(STATE.ERROR, 'This session is no longer allowed to watch that satellite.');
+ this._emit('unauthorized', { code: event.code, reason: event.reason });
+ return;
+ }
+ this._setState(STATE.OFFLINE, 'Reconnecting');
+ this._scheduleReconnect();
+ };
+ }
+
+ _scheduleReconnect() {
+ if (this._stopped) return;
+ this._attempt += 1;
+ const base = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** Math.min(this._attempt, 5));
+ this._timer = setTimeout(() => this.connect(), Math.round(base * (0.6 + Math.random() * 0.4)));
+ }
+
+ _handle(message) {
+ switch (message?.t) {
+ case 'hello':
+ this.satellite = message.satellite || null;
+ this._setState(message.state || STATE.IDLE, null);
+ this._emit('hello', { satellite: this.satellite });
+ return;
+ case 'state':
+ this._setState(message.state, message.detail || null);
+ return;
+ case 'wake':
+ this.wakeWord = message.name || null;
+ this.transcript = '';
+ this.answer = '';
+ this._emit('wake', { name: this.wakeWord });
+ return;
+ case 'voice':
+ this._emit('voice', { speaking: !!message.speaking });
+ return;
+ case 'transcript':
+ this.transcript = typeof message.text === 'string' ? message.text : '';
+ this._emit('transcript', { text: this.transcript, final: !!message.final });
+ return;
+ case 'speech':
+ this.answer = typeof message.text === 'string' ? message.text : '';
+ this._emit('speech', { text: this.answer });
+ return;
+ case 'audio-start':
+ this._startPlayback(message);
+ return;
+ case 'audio-stop':
+ this._finishPlayback();
+ return;
+ case 'error':
+ this.lastError = new Error(message.text || 'The pipeline reported an error.');
+ this.lastError.code = message.code || null;
+ this._emit('pipeline-error', { text: message.text, code: message.code });
+ return;
+ default:
+ }
+ }
+
+ async _startPlayback(format) {
+ try {
+ await this._player.start({ rate: format.rate, width: format.width, channels: format.channels });
+ this._emit('speaking', { analyser: this._player.analyser });
+ } catch (err) {
+ this._emit('pipeline-error', { text: err.message, code: 'audio_unavailable' });
+ }
+ }
+
+ async _finishPlayback() {
+ await this._player.finish();
+ // Tell the service the answer finished so it can tell Home Assistant. The
+ // service has its own timeout for exactly the case where this never
+ // arrives, so a closed tab cannot leave a pipeline hanging.
+ this._send({ t: 'played' });
+ this._emit('spoken', {});
+ }
+
+ _send(message) {
+ if (this._socket?.readyState !== WebSocket.OPEN) return false;
+ this._socket.send(JSON.stringify(message));
+ return true;
+ }
+
+ /**
+ * Open the microphone and stream it into the pipeline.
+ * @param {'wake'|'command'} mode
+ */
+ async startMic(mode = 'wake') {
+ if (this._mic) return true;
+ if (!this.connected) throw new Error('Not connected to the satellite yet.');
+
+ // The resampler is built on the first frame, not before `start()`: the
+ // device's real capture rate is only known once the audio context exists,
+ // and a resampler sized from a guess produces a transcript at the wrong
+ // pitch rather than an error anyone can trace.
+ let down = null;
+ const mic = new MicCapture({
+ retain: false,
+ onFrame: (frame) => {
+ if (!down) down = new PcmDownsampler(mic.sampleRate);
+ const pcm = down.push(frame);
+ if (pcm.length && this._socket?.readyState === WebSocket.OPEN) {
+ this._socket.send(pcm.buffer);
+ }
+ },
+ });
+ await mic.start();
+
+ this._mic = mic;
+ this._micMode = mode;
+ this._send({ t: 'mic-start', mode });
+ this._emit('mic', { open: true, mode });
+ return true;
+ }
+
+ stopMic() {
+ if (!this._mic) return false;
+ this._send({ t: 'mic-stop' });
+ this._stopMic();
+ this._emit('mic', { open: false, mode: this._micMode });
+ return true;
+ }
+
+ _stopMic() {
+ if (!this._mic) return;
+ this._mic.dispose();
+ this._mic = null;
+ }
+
+ /** Live microphone level, 0..1, for the listening indicator. */
+ micLevel() {
+ return this._mic?.getLevel?.() ?? 0;
+ }
+
+ close() {
+ this._stopped = true;
+ clearTimeout(this._timer);
+ this._stopMic();
+ this._player.dispose();
+ this._socket?.close(1000, 'leaving');
+ this._socket = null;
+ this._setState(STATE.OFFLINE, null);
+ }
+}
diff --git a/src/home/satellite.css b/src/home/satellite.css
new file mode 100644
index 000000000..03dcfd34b
--- /dev/null
+++ b/src/home/satellite.css
@@ -0,0 +1,417 @@
+/*
+ * Voice satellite view.
+ *
+ * Two layouts from one stylesheet. The manage view is a normal page: panels,
+ * forms, a list. The live view is a display: an avatar filling the frame with
+ * one line of text under it, readable from across a kitchen. The live view is
+ * the one that runs on a wall-mounted tablet at 3am, so it is dark, it has no
+ * chrome it does not need, and every piece of text on it is large.
+ *
+ * Prefixed `hs-` so it cannot collide with the rest of the home surface.
+ */
+
+.hs-wrap {
+ max-width: 68rem;
+ margin: 0 auto;
+ padding: clamp(1.25rem, 4vw, 3rem) clamp(1rem, 4vw, 2rem) 5rem;
+}
+
+.hs-eyebrow {
+ margin: 0 0 0.5rem;
+ font-size: 0.78rem;
+ font-weight: 600;
+ letter-spacing: 0.14em;
+ text-transform: uppercase;
+ color: var(--accent, #7c9cff);
+}
+
+.hs-title {
+ margin: 0 0 0.75rem;
+ font-size: clamp(1.9rem, 5vw, 2.9rem);
+ line-height: 1.1;
+ letter-spacing: -0.02em;
+}
+
+.hs-lede {
+ margin: 0 0 2rem;
+ max-width: 46rem;
+ font-size: 1.02rem;
+ line-height: 1.65;
+ color: var(--text-dim, #9aa4b2);
+}
+
+.hs-panel {
+ border: 1px solid var(--border, #23262d);
+ border-radius: 14px;
+ background: var(--surface, #14161a);
+ padding: clamp(1rem, 3vw, 1.6rem);
+ margin-bottom: 1.1rem;
+}
+
+.hs-panel-title {
+ margin: 0 0 0.35rem;
+ font-size: 1.05rem;
+ font-weight: 650;
+}
+
+.hs-panel-sub {
+ margin: 0 0 1rem;
+ font-size: 0.9rem;
+ line-height: 1.6;
+ color: var(--text-dim, #9aa4b2);
+}
+
+.hs-row {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.7rem;
+ align-items: center;
+}
+
+.hs-grow {
+ flex: 1 1 14rem;
+ min-width: 0;
+}
+
+.hs-btn {
+ appearance: none;
+ border: 1px solid var(--border, #2a2e37);
+ border-radius: 10px;
+ background: var(--surface-2, #1c1f26);
+ color: inherit;
+ font: inherit;
+ font-weight: 600;
+ padding: 0.62rem 1.05rem;
+ cursor: pointer;
+ transition: background 140ms ease, border-color 140ms ease, transform 140ms ease;
+}
+
+.hs-btn:hover:not(:disabled) {
+ background: var(--surface-3, #242832);
+ border-color: var(--border-strong, #39404d);
+}
+
+.hs-btn:active:not(:disabled) {
+ transform: translateY(1px);
+}
+
+.hs-btn:focus-visible {
+ outline: 2px solid var(--accent, #7c9cff);
+ outline-offset: 2px;
+}
+
+.hs-btn:disabled {
+ opacity: 0.5;
+ cursor: not-allowed;
+}
+
+.hs-btn-primary {
+ background: var(--accent, #7c9cff);
+ border-color: var(--accent, #7c9cff);
+ color: #0b0d10;
+}
+
+.hs-btn-primary:hover:not(:disabled) {
+ background: var(--accent-bright, #96b0ff);
+ border-color: var(--accent-bright, #96b0ff);
+}
+
+.hs-btn-quiet {
+ background: transparent;
+}
+
+.hs-select,
+.hs-input {
+ width: 100%;
+ border: 1px solid var(--border, #2a2e37);
+ border-radius: 10px;
+ background: var(--surface-2, #1c1f26);
+ color: inherit;
+ font: inherit;
+ padding: 0.62rem 0.8rem;
+}
+
+.hs-select:focus-visible,
+.hs-input:focus-visible {
+ outline: 2px solid var(--accent, #7c9cff);
+ outline-offset: 1px;
+}
+
+.hs-label {
+ display: block;
+ margin-bottom: 0.35rem;
+ font-size: 0.82rem;
+ font-weight: 600;
+ color: var(--text-dim, #9aa4b2);
+}
+
+/* The pairing code. Read off a screen and typed into a terminal, so it is big,
+ monospaced, and spaced out enough that nobody has to squint at a 5 next to
+ an S. */
+.hs-code {
+ display: inline-block;
+ font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+ font-size: clamp(1.6rem, 6vw, 2.4rem);
+ font-weight: 700;
+ letter-spacing: 0.16em;
+ padding: 0.5rem 0.9rem;
+ border-radius: 12px;
+ background: var(--surface-2, #1c1f26);
+ border: 1px dashed var(--border-strong, #39404d);
+ user-select: all;
+}
+
+.hs-cmd {
+ display: block;
+ overflow-x: auto;
+ white-space: pre;
+ font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+ font-size: 0.82rem;
+ line-height: 1.7;
+ padding: 0.85rem 1rem;
+ border-radius: 10px;
+ background: #0b0d10;
+ border: 1px solid var(--border, #23262d);
+ color: #c7d0dd;
+}
+
+.hs-list {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: grid;
+ gap: 0.6rem;
+}
+
+.hs-item {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.6rem 1rem;
+ align-items: center;
+ border: 1px solid var(--border, #23262d);
+ border-radius: 12px;
+ background: var(--surface-2, #1a1d23);
+ padding: 0.8rem 1rem;
+ transition: border-color 140ms ease;
+}
+
+.hs-item:hover {
+ border-color: var(--border-strong, #39404d);
+}
+
+.hs-item-name {
+ font-weight: 650;
+}
+
+.hs-item-meta {
+ font-size: 0.82rem;
+ color: var(--text-dim, #9aa4b2);
+}
+
+.hs-dot {
+ width: 0.55rem;
+ height: 0.55rem;
+ border-radius: 50%;
+ background: var(--text-dim, #6b7280);
+ flex: none;
+}
+
+.hs-dot[data-live="1"] {
+ background: #3ddc84;
+ box-shadow: 0 0 0 3px rgb(61 220 132 / 18%);
+}
+
+.hs-empty {
+ text-align: center;
+ padding: 2.4rem 1rem;
+ color: var(--text-dim, #9aa4b2);
+}
+
+.hs-empty-mark {
+ font-size: 2.2rem;
+ line-height: 1;
+ margin-bottom: 0.7rem;
+ opacity: 0.85;
+}
+
+.hs-note {
+ margin: 0.9rem 0 0;
+ font-size: 0.84rem;
+ line-height: 1.6;
+ color: var(--text-dim, #9aa4b2);
+}
+
+.hs-error {
+ border-color: #7f3030;
+ background: rgb(127 48 48 / 12%);
+}
+
+.hs-skeleton {
+ border-radius: 8px;
+ background: linear-gradient(90deg, #1a1d23 25%, #23272f 37%, #1a1d23 63%);
+ background-size: 400% 100%;
+ animation: hs-shimmer 1.4s ease infinite;
+}
+
+@keyframes hs-shimmer {
+ 0% { background-position: 100% 50%; }
+ 100% { background-position: 0 50%; }
+}
+
+/* ------------------------------------------------------------------ live */
+
+.hs-live {
+ display: grid;
+ grid-template-rows: auto 1fr auto;
+ min-height: 100dvh;
+ background: radial-gradient(120% 80% at 50% 0%, #171a21 0%, #0b0d10 70%);
+}
+
+.hs-live-top {
+ display: flex;
+ gap: 0.75rem;
+ align-items: center;
+ padding: 0.9rem clamp(0.9rem, 3vw, 1.6rem);
+ border-bottom: 1px solid var(--border, #1c1f26);
+}
+
+.hs-live-name {
+ font-weight: 650;
+ letter-spacing: -0.01em;
+}
+
+.hs-live-status {
+ font-size: 0.82rem;
+ color: var(--text-dim, #9aa4b2);
+}
+
+.hs-stage {
+ position: relative;
+ min-height: 42vh;
+}
+
+.hs-stage-canvas {
+ position: absolute;
+ inset: 0;
+}
+
+/* The whole point of the product: the badge that names the current state, over
+ the avatar, legible from across a room. */
+.hs-badge {
+ position: absolute;
+ top: clamp(0.7rem, 2vw, 1.2rem);
+ left: 50%;
+ transform: translateX(-50%);
+ display: inline-flex;
+ align-items: center;
+ gap: 0.5rem;
+ padding: 0.4rem 0.9rem;
+ border-radius: 999px;
+ font-size: 0.85rem;
+ font-weight: 600;
+ letter-spacing: 0.01em;
+ background: rgb(11 13 16 / 72%);
+ border: 1px solid var(--border, #23262d);
+ backdrop-filter: blur(8px);
+ transition: opacity 200ms ease, transform 200ms ease;
+}
+
+.hs-badge[data-state="listening"] { border-color: #2f6f4f; color: #86e2b0; }
+.hs-badge[data-state="wake"] { border-color: #6f5a2f; color: #f0cf86; }
+.hs-badge[data-state="thinking"] { border-color: #3a4b7a; color: #a9bcf3; }
+.hs-badge[data-state="speaking"] { border-color: #4a3a7a; color: #c8b4f5; }
+.hs-badge[data-state="error"] { border-color: #7f3030; color: #f3a9a9; }
+.hs-badge[data-state="disconnected"],
+.hs-badge[data-state="offline"] { border-color: #3a3f48; color: #9aa4b2; }
+
+/* Breathing ring behind the badge while the microphone is live. Transform and
+ opacity only, so it never triggers layout on a low-power display. */
+.hs-pulse::before {
+ content: "";
+ position: absolute;
+ inset: -6px;
+ border-radius: inherit;
+ border: 1px solid currentColor;
+ opacity: 0.4;
+ animation: hs-pulse 1.8s ease-out infinite;
+}
+
+@keyframes hs-pulse {
+ 0% { transform: scale(0.96); opacity: 0.45; }
+ 100% { transform: scale(1.12); opacity: 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .hs-pulse::before { animation: none; opacity: 0.3; }
+ .hs-skeleton { animation: none; }
+}
+
+.hs-caption {
+ padding: clamp(0.9rem, 3vw, 1.6rem);
+ border-top: 1px solid var(--border, #1c1f26);
+ display: grid;
+ gap: 0.55rem;
+}
+
+.hs-said,
+.hs-answered {
+ margin: 0;
+ font-size: clamp(1.02rem, 2.6vw, 1.35rem);
+ line-height: 1.5;
+ min-height: 1.5em;
+}
+
+.hs-said {
+ color: var(--text, #e6eaf0);
+ font-weight: 600;
+}
+
+.hs-answered {
+ color: var(--text-dim, #9aa4b2);
+}
+
+.hs-said:empty::after,
+.hs-answered:empty::after {
+ content: "";
+}
+
+.hs-live-actions {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.6rem;
+ align-items: center;
+ margin-top: 0.5rem;
+}
+
+.hs-meter {
+ width: 6.5rem;
+ height: 0.4rem;
+ border-radius: 999px;
+ background: var(--surface-2, #1c1f26);
+ overflow: hidden;
+}
+
+.hs-meter-fill {
+ height: 100%;
+ width: 0;
+ background: #3ddc84;
+ transform-origin: left center;
+ transition: width 80ms linear;
+}
+
+.hs-asleep {
+ position: absolute;
+ inset: 0;
+ display: grid;
+ place-content: center;
+ text-align: center;
+ gap: 0.6rem;
+ padding: 2rem;
+ background: rgb(6 7 9 / 92%);
+ color: var(--text-dim, #9aa4b2);
+}
+
+@media (max-width: 560px) {
+ .hs-item { align-items: flex-start; }
+ .hs-code { letter-spacing: 0.1em; }
+}
diff --git a/src/home/satellite.js b/src/home/satellite.js
new file mode 100644
index 000000000..26a0f17ed
--- /dev/null
+++ b/src/home/satellite.js
@@ -0,0 +1,500 @@
+/**
+ * /smart-home/satellite — the browser half of a Home Assistant voice satellite.
+ *
+ * Two views out of one module, chosen by the `?id=` in the URL:
+ *
+ * no id the manage view. Mint a pairing code, see what is paired, retire
+ * one. States 1 and 2 of the flow live here.
+ * ?id=… the live view. The agent's body, its face moving to the pipeline's
+ * own speech, the transcript under it. States 3 to 10 live here.
+ *
+ * The live view is a display. It is meant to run on a tablet on a kitchen wall
+ * for months, so it reconnects on its own, it survives the screen sleeping, and
+ * it never renders a state it is only guessing at. When it cannot reach the
+ * satellite it says exactly that, and it says the thing that is actually true
+ * and actually reassuring: the voice assistant is still working, you have just
+ * lost the face.
+ *
+ * The 3D work is not reimplemented here. TalkScene renders, AvatarMouthTarget
+ * binds the mouth, LipsyncDriver drives it off an analyser, and TalkEmotes
+ * plays the body language. All four already exist and are used by talk mode;
+ * this page feeds them from a different audio source, and that is the whole
+ * difference.
+ */
+
+import { LipsyncDriver } from '../voice/lipsync-driver.js';
+import { AvatarMouthTarget } from '../voice/avatar-morph-target.js';
+import { TalkScene } from '../voice/talk-scene.js';
+import { SatelliteLink, STATE } from './satellite-link.js';
+
+const root = document.getElementById('hs-root');
+const params = new URLSearchParams(location.search);
+const satelliteId = params.get('id');
+
+/** One place that decides what each state is called and what the body does. */
+const STATE_COPY = Object.freeze({
+ [STATE.UNPAIRED]: { label: 'Not paired', emote: 'idle' },
+ [STATE.PAIRING]: { label: 'Pairing', emote: 'idle' },
+ [STATE.IDLE]: { label: 'Ready', emote: 'idle' },
+ [STATE.WAKE]: { label: 'Yes?', emote: 'reaction' },
+ [STATE.LISTENING]: { label: 'Listening', emote: 'idle' },
+ [STATE.THINKING]: { label: 'Thinking', emote: 'idle' },
+ [STATE.SPEAKING]: { label: 'Speaking', emote: 'idle' },
+ [STATE.ERROR]: { label: 'Something went wrong', emote: 'reaction' },
+ [STATE.DISCONNECTED]: { label: 'Home Assistant is not connected', emote: 'idle' },
+ [STATE.OFFLINE]: { label: 'Reconnecting', emote: 'idle' },
+});
+
+let csrf = null;
+async function csrfToken() {
+ if (csrf && csrf.expiresAt > Date.now() + 5000) return csrf.token;
+ const res = await fetch('/api/csrf-token', { credentials: 'include' });
+ if (!res.ok) throw new Error('Could not get a security token. Sign in again and retry.');
+ const body = await res.json();
+ csrf = { token: body.data.token, expiresAt: Date.now() + (body.data.expires_in - 30) * 1000 };
+ return csrf.token;
+}
+
+async function api(payload) {
+ const token = await csrfToken();
+ csrf = null; // single use
+ const res = await fetch('/api/home/satellite', {
+ method: 'POST',
+ credentials: 'include',
+ headers: { 'content-type': 'application/json', 'x-csrf-token': token, accept: 'application/json' },
+ body: JSON.stringify(payload),
+ });
+ const body = await res.json().catch(() => ({}));
+ if (!res.ok) {
+ throw Object.assign(new Error(body?.error_description || body?.message || 'That did not work.'), {
+ status: res.status,
+ code: body?.error,
+ });
+ }
+ return body;
+}
+
+const el = (tag, props = {}, children = []) => {
+ const node = document.createElement(tag);
+ for (const [key, value] of Object.entries(props)) {
+ if (key === 'class') node.className = value;
+ else if (key === 'text') node.textContent = value;
+ else if (key === 'html') node.innerHTML = value;
+ else if (key.startsWith('on')) node.addEventListener(key.slice(2), value);
+ else if (value !== null && value !== undefined) node.setAttribute(key, value);
+ }
+ for (const child of [].concat(children)) if (child) node.append(child);
+ return node;
+};
+
+const clear = (node) => {
+ while (node.firstChild) node.firstChild.remove();
+};
+
+function fail(message, { retry = null } = {}) {
+ clear(root);
+ root.setAttribute('aria-busy', 'false');
+ root.append(
+ el('section', { class: 'hs-panel hs-error' }, [
+ el('h2', { class: 'hs-panel-title', text: 'That did not work' }),
+ el('p', { class: 'hs-panel-sub', text: message }),
+ retry ? el('button', { class: 'hs-btn', type: 'button', onclick: retry, text: 'Try again' }) : null,
+ ]),
+ );
+}
+
+/* ========================================================== manage view === */
+
+async function renderManage() {
+ root.setAttribute('aria-busy', 'true');
+ let data;
+ let agents = [];
+ try {
+ const [satRes, agentRes] = await Promise.all([
+ fetch('/api/home/satellite', { credentials: 'include', headers: { accept: 'application/json' } }),
+ fetch('/api/agents', { credentials: 'include', headers: { accept: 'application/json' } }),
+ ]);
+ if (satRes.status === 401) return renderSignedOut();
+ if (!satRes.ok) throw new Error('Could not load your satellites.');
+ data = await satRes.json();
+ if (agentRes.ok) {
+ const payload = await agentRes.json();
+ agents = payload.data?.agents || payload.agents || payload.data || [];
+ }
+ } catch (err) {
+ return fail(err.message, { retry: renderManage });
+ }
+
+ root.setAttribute('aria-busy', 'false');
+ clear(root);
+ root.append(renderPairPanel(agents, data));
+ root.append(renderPendingPanel(data.pending_codes || []));
+ root.append(renderSatellitePanel(data.satellites || []));
+}
+
+function renderSignedOut() {
+ root.setAttribute('aria-busy', 'false');
+ clear(root);
+ root.append(
+ el('section', { class: 'hs-panel' }, [
+ el('h2', { class: 'hs-panel-title', text: 'Sign in to pair a satellite' }),
+ el('p', {
+ class: 'hs-panel-sub',
+ text: 'A satellite is bound to one of your agents, so pairing needs an account. Trying it out does not: the service runs on your own network and shows the agent locally without three.ws in the loop.',
+ }),
+ el('a', { class: 'hs-btn hs-btn-primary', href: '/login?next=/smart-home/satellite', text: 'Sign in' }),
+ ]),
+ );
+}
+
+function renderPairPanel(agents, data) {
+ const panel = el('section', { class: 'hs-panel' }, [
+ el('h2', { class: 'hs-panel-title', text: 'Pair a new satellite' }),
+ el('p', {
+ class: 'hs-panel-sub',
+ text: 'Pick the agent that should appear on it. You will get a code that is good once, for fifteen minutes.',
+ }),
+ ]);
+
+ if (!agents.length) {
+ panel.append(
+ el('div', { class: 'hs-empty' }, [
+ el('div', { class: 'hs-empty-mark', text: '🎭' }),
+ el('p', { text: 'You do not have an agent yet, and a satellite needs a face to show.' }),
+ el('a', { class: 'hs-btn hs-btn-primary', href: '/create', text: 'Create an agent' }),
+ ]),
+ );
+ return panel;
+ }
+
+ const select = el('select', { class: 'hs-select', id: 'hs-agent', 'aria-label': 'Agent' });
+ for (const agent of agents) {
+ select.append(el('option', { value: agent.id, text: agent.name || 'Untitled agent' }));
+ }
+ const nameInput = el('input', {
+ class: 'hs-input',
+ id: 'hs-name',
+ type: 'text',
+ maxlength: '120',
+ placeholder: 'Kitchen display',
+ 'aria-label': 'What Home Assistant should call it',
+ });
+ const button = el('button', { class: 'hs-btn hs-btn-primary', type: 'submit', text: 'Get a pairing code' });
+ const out = el('div', { id: 'hs-code-out' });
+
+ const form = el('form', {
+ class: 'hs-row',
+ onsubmit: async (event) => {
+ event.preventDefault();
+ button.disabled = true;
+ button.textContent = 'Minting…';
+ try {
+ const result = await api({
+ action: 'pair',
+ agent_id: select.value,
+ name: nameInput.value.trim() || null,
+ });
+ renderCode(out, result);
+ } catch (err) {
+ clear(out);
+ out.append(el('p', { class: 'hs-note', text: err.message }));
+ } finally {
+ button.disabled = false;
+ button.textContent = 'Get a pairing code';
+ }
+ },
+ }, [
+ el('div', { class: 'hs-grow' }, [el('label', { class: 'hs-label', for: 'hs-agent', text: 'Agent' }), select]),
+ el('div', { class: 'hs-grow' }, [el('label', { class: 'hs-label', for: 'hs-name', text: 'Name' }), nameInput]),
+ el('div', {}, [el('span', { class: 'hs-label', text: ' ' }), button]),
+ ]);
+
+ panel.append(form, out);
+ if (data && data.hub_configured === false) {
+ panel.append(
+ el('p', {
+ class: 'hs-note',
+ text: 'This three.ws instance has no satellite hub configured, so a satellite pairs and runs, but this page can only watch it from a browser on the same network as the house. The pipeline itself is unaffected either way.',
+ }),
+ );
+ }
+ return panel;
+}
+
+function renderCode(out, result) {
+ clear(out);
+ const expires = new Date(result.expires_at);
+ out.append(
+ el('div', { style: 'margin-top:1.1rem' }, [
+ el('p', { class: 'hs-label', text: `Pairing code for ${result.agent?.name || 'your agent'}` }),
+ el('p', { style: 'margin:0 0 0.9rem' }, [el('code', { class: 'hs-code', text: result.code })]),
+ el('p', { class: 'hs-panel-sub', text: `Single use. Expires ${expires.toLocaleTimeString()}. Run this next to Home Assistant:` }),
+ el('code', { class: 'hs-cmd', text: result.command }),
+ el('p', {
+ class: 'hs-note',
+ text: 'Then in Home Assistant: Settings, Devices and services, Add integration, Wyoming Protocol, and give it the host running that container with port 10700.',
+ }),
+ ]),
+ );
+}
+
+function renderPendingPanel(codes) {
+ if (!codes.length) return el('span');
+ return el('section', { class: 'hs-panel' }, [
+ el('h2', { class: 'hs-panel-title', text: 'Codes waiting to be used' }),
+ el('ul', { class: 'hs-list' }, codes.map((code) =>
+ el('li', { class: 'hs-item' }, [
+ el('div', { class: 'hs-grow' }, [
+ el('div', { class: 'hs-item-name', text: code.name || code.agent?.name || 'Unnamed' }),
+ el('div', { class: 'hs-item-meta', text: `for ${code.agent?.name || 'an agent'} · expires ${new Date(code.expires_at).toLocaleTimeString()}` }),
+ ]),
+ el('button', {
+ class: 'hs-btn hs-btn-quiet',
+ type: 'button',
+ text: 'Withdraw',
+ onclick: async (event) => {
+ event.target.disabled = true;
+ try {
+ await api({ action: 'revoke', code_id: code.id });
+ await renderManage();
+ } catch (err) {
+ event.target.disabled = false;
+ event.target.textContent = err.message;
+ }
+ },
+ }),
+ ]),
+ )),
+ ]);
+}
+
+function renderSatellitePanel(satellites) {
+ const panel = el('section', { class: 'hs-panel' }, [
+ el('h2', { class: 'hs-panel-title', text: 'Your satellites' }),
+ ]);
+
+ if (!satellites.length) {
+ panel.append(
+ el('div', { class: 'hs-empty' }, [
+ el('div', { class: 'hs-empty-mark', text: '🛰️' }),
+ el('p', { text: 'Nothing paired yet. Get a code above, run the container next to Home Assistant, and add it as a Wyoming Protocol integration.' }),
+ el('a', { class: 'hs-btn hs-btn-quiet', href: '/docs/home-satellite', text: 'Read the setup guide' }),
+ ]),
+ );
+ return panel;
+ }
+
+ panel.append(el('ul', { class: 'hs-list' }, satellites.map((sat) => {
+ const seen = sat.last_seen_at ? new Date(sat.last_seen_at) : null;
+ const live = seen && Date.now() - seen.getTime() < 5 * 60 * 1000;
+ return el('li', { class: 'hs-item' }, [
+ el('span', { class: 'hs-dot', 'data-live': live ? '1' : '0', title: live ? 'Checked in recently' : 'Not seen recently' }),
+ el('div', { class: 'hs-grow' }, [
+ el('div', { class: 'hs-item-name', text: sat.name }),
+ el('div', {
+ class: 'hs-item-meta',
+ text: `${sat.agent?.name || 'agent'}${sat.area ? ` · ${sat.area}` : ''}${seen ? ` · last seen ${seen.toLocaleString()}` : ' · never checked in'}`,
+ }),
+ ]),
+ el('a', { class: 'hs-btn', href: `/smart-home/satellite?id=${encodeURIComponent(sat.id)}`, text: 'Open' }),
+ el('button', {
+ class: 'hs-btn hs-btn-quiet',
+ type: 'button',
+ text: 'Retire',
+ onclick: async (event) => {
+ event.target.disabled = true;
+ try {
+ await api({ action: 'revoke', satellite_id: sat.id });
+ await renderManage();
+ } catch (err) {
+ event.target.disabled = false;
+ event.target.textContent = err.message;
+ }
+ },
+ }),
+ ]);
+ })));
+ return panel;
+}
+
+/* ============================================================ live view === */
+
+async function renderLive(id) {
+ root.setAttribute('aria-busy', 'true');
+ let attach;
+ try {
+ attach = await api({ action: 'attach', satellite_id: id });
+ } catch (err) {
+ if (err.status === 401) return renderSignedOut();
+ return fail(err.message, { retry: () => renderLive(id) });
+ }
+
+ root.setAttribute('aria-busy', 'false');
+ clear(root);
+ document.body.classList.add('hs-body-live');
+
+ const badge = el('span', { class: 'hs-badge', 'data-state': STATE.OFFLINE, text: 'Connecting' });
+ const stage = el('div', { class: 'hs-stage-canvas' });
+ const asleep = el('div', { class: 'hs-asleep', hidden: 'hidden' }, [
+ el('p', { style: 'font-size:1.1rem;font-weight:600', text: 'Screen resting' }),
+ el('p', { text: 'The voice assistant is still running. Touch the screen to bring the agent back.' }),
+ ]);
+ const said = el('p', { class: 'hs-said', 'aria-live': 'polite' });
+ const answered = el('p', { class: 'hs-answered', 'aria-live': 'polite' });
+ const meterFill = el('div', { class: 'hs-meter-fill' });
+ const micButton = el('button', { class: 'hs-btn hs-btn-primary', type: 'button', text: 'Start listening' });
+ const status = el('span', { class: 'hs-live-status', text: 'Connecting to the satellite' });
+
+ root.append(el('div', { class: 'hs-live' }, [
+ el('header', { class: 'hs-live-top' }, [
+ el('a', { class: 'hs-btn hs-btn-quiet', href: '/smart-home/satellite', text: '← Satellites' }),
+ el('div', { class: 'hs-grow' }, [
+ el('div', { class: 'hs-live-name', text: attach.satellite?.name || 'Satellite' }),
+ status,
+ ]),
+ ]),
+ el('div', { class: 'hs-stage' }, [stage, badge, asleep]),
+ el('div', { class: 'hs-caption' }, [
+ said,
+ answered,
+ el('div', { class: 'hs-live-actions' }, [
+ micButton,
+ el('div', { class: 'hs-meter', role: 'presentation' }, [meterFill]),
+ el('span', { class: 'hs-item-meta', text: 'Home Assistant owns the wake word, the transcription and the answer. This screen is the face.' }),
+ ]),
+ ]),
+ ]));
+
+ /* --- the body ------------------------------------------------------- */
+ const mouth = new AvatarMouthTarget();
+ const scene = new TalkScene();
+ let emotes = null;
+ const glbUrl = attach.agent?.avatarUrl;
+ if (glbUrl) {
+ try {
+ await scene.mount({ container: stage, glbUrl, cameraPreset: 'half' });
+ scene.attachMouthTarget(mouth);
+ emotes = scene.getEmoteController();
+ scene.playEmote('idle');
+ } catch {
+ stage.append(el('div', { class: 'hs-empty' }, [
+ el('div', { class: 'hs-empty-mark', text: '🎭' }),
+ el('p', { text: 'The agent’s model could not be loaded, so there is no face on this screen. Everything else still works.' }),
+ ]));
+ }
+ } else {
+ stage.append(el('div', { class: 'hs-empty' }, [
+ el('div', { class: 'hs-empty-mark', text: '🎭' }),
+ el('p', { text: 'This agent has no avatar yet, so there is nothing to show. Give it one and this screen fills in.' }),
+ el('a', { class: 'hs-btn hs-btn-quiet', href: '/create', text: 'Give it a body' }),
+ ]));
+ }
+
+ /* --- the link ------------------------------------------------------- */
+ const link = new SatelliteLink({
+ resolve: async () => {
+ // Every connect mints a fresh short-lived token rather than replaying
+ // the one this page loaded with; a display left open overnight would
+ // otherwise be locked out by morning.
+ const fresh = await api({ action: 'attach', satellite_id: id });
+ const url = fresh.hub_url || attach.hub_url;
+ const token = fresh.hub_token || fresh.lan_token;
+ if (!url || !token) {
+ throw new Error('This three.ws instance has no satellite hub configured, so this page cannot reach the satellite. It is still running: open it from a browser on the same network as the house.');
+ }
+ return { url, token };
+ },
+ });
+
+ let driver = null;
+ link.addEventListener('speaking', (event) => {
+ driver?.dispose?.();
+ driver?.stop?.();
+ const analyser = event.detail?.analyser;
+ if (!analyser) return;
+ driver = new LipsyncDriver({ analyser, target: mouth });
+ driver.start();
+ });
+ link.addEventListener('spoken', () => {
+ driver?.stop();
+ mouth.setMouthShape?.({ open: 0, wide: 0, round: 0 });
+ });
+
+ link.addEventListener('hello', () => {
+ status.textContent = `Connected · ${link.satellite?.wyoming ? `Wyoming ${link.satellite.wyoming}` : 'Wyoming'}`;
+ });
+ link.addEventListener('transcript', (event) => {
+ said.textContent = event.detail.text;
+ });
+ link.addEventListener('speech', (event) => {
+ answered.textContent = event.detail.text;
+ });
+ link.addEventListener('wake', () => {
+ said.textContent = '';
+ answered.textContent = '';
+ });
+ link.addEventListener('pipeline-error', (event) => {
+ answered.textContent = event.detail.text || 'The pipeline reported an error.';
+ });
+ link.addEventListener('unauthorized', () => {
+ status.textContent = 'This session expired. Reload the page to watch again.';
+ });
+ link.addEventListener('mic', (event) => {
+ micButton.textContent = event.detail.open ? 'Stop listening' : 'Start listening';
+ });
+ link.addEventListener('state', (event) => {
+ const { state, detail } = event.detail;
+ const copy = STATE_COPY[state] || STATE_COPY[STATE.IDLE];
+ badge.dataset.state = state;
+ badge.textContent = detail || copy.label;
+ badge.classList.toggle('hs-pulse', state === STATE.LISTENING || state === STATE.WAKE);
+ if (state === STATE.DISCONNECTED) {
+ status.textContent = 'Home Assistant is not connected to this satellite right now.';
+ } else if (state === STATE.OFFLINE) {
+ status.textContent = 'Lost the satellite. Your voice assistant is unaffected; this screen is reconnecting.';
+ }
+ if (emotes && copy.emote && copy.emote !== 'idle') scene.playEmoteOnce?.(copy.emote);
+ });
+
+ micButton.addEventListener('click', async () => {
+ micButton.disabled = true;
+ try {
+ if (link.micOpen) link.stopMic();
+ else await link.startMic('wake');
+ } catch (err) {
+ answered.textContent = err.message;
+ } finally {
+ micButton.disabled = false;
+ }
+ });
+
+ // The microphone meter. rAF rather than an interval so it stops dead when
+ // the tab is hidden instead of spinning on a sleeping display.
+ const tick = () => {
+ meterFill.style.width = `${Math.round(link.micLevel() * 100)}%`;
+ rafId = requestAnimationFrame(tick);
+ };
+ let rafId = requestAnimationFrame(tick);
+
+ // The screen going to sleep is a normal state on a wall display, not a
+ // failure. The socket stays open, the pipeline keeps running, and the only
+ // thing that stops is the renderer.
+ document.addEventListener('visibilitychange', () => {
+ const hidden = document.visibilityState === 'hidden';
+ asleep.hidden = !hidden;
+ scene.setFpsCap?.(hidden ? 1 : 0);
+ });
+
+ window.addEventListener('pagehide', () => {
+ cancelAnimationFrame(rafId);
+ link.close();
+ scene.unmount?.();
+ });
+
+ await link.connect();
+}
+
+/* ===================================================================== */
+
+if (satelliteId) renderLive(satelliteId);
+else renderManage();
diff --git a/tests/home-relay-protocol.test.js b/tests/home-relay-protocol.test.js
new file mode 100644
index 000000000..0016c9b8d
--- /dev/null
+++ b/tests/home-relay-protocol.test.js
@@ -0,0 +1,121 @@
+// The relay's allowlist is enforced twice: here in JavaScript, and again in
+// Python inside the house. Two enforcement points that drift apart are worse
+// than one, so the Python side reads `services/home-relay/allowlist.json`
+// rather than transcribing the rules, and that file is generated from
+// `src/protocol.js` by `scripts/gen-allowlist.mjs`.
+//
+// This suite is the guard on that arrangement. A rule changed in protocol.js
+// without regenerating the manifest fails here, loudly, instead of leaving the
+// relay refusing one thing and the integration refusing another.
+//
+// npx vitest run tests/home-relay-protocol.test.js
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+import {
+ allowlistManifest,
+ checkInbound,
+ checkOutbound,
+} from '../services/home-relay/src/protocol.js';
+
+const checkedIn = JSON.parse(
+ readFileSync(new URL('../services/home-relay/allowlist.json', import.meta.url), 'utf8'),
+);
+
+describe('the generated allowlist manifest', () => {
+ it('matches the checked-in file the Home Assistant integration reads', () => {
+ // If this fails: node services/home-relay/scripts/gen-allowlist.mjs
+ expect(checkedIn).toEqual(allowlistManifest());
+ });
+
+ it('carries the shape the Python side destructures', () => {
+ for (const key of [
+ 'protocolVersion',
+ 'minAgentProtocol',
+ 'frameTypes',
+ 'outboundTypes',
+ 'inboundTypes',
+ 'allowedEventTypes',
+ 'deniedServiceDomains',
+ 'deniedServices',
+ 'limits',
+ ]) {
+ expect(checkedIn, `allowlist.json is missing ${key}`).toHaveProperty(key);
+ }
+ });
+});
+
+describe('what the relay carries into a house', () => {
+ it('allows the reads the room graph is built from', () => {
+ for (const type of [
+ 'get_states',
+ 'get_config',
+ 'config/floor_registry/list',
+ 'config/area_registry/list',
+ 'config/device_registry/list',
+ 'config/entity_registry/list',
+ 'subscribe_entities',
+ ]) {
+ expect(checkOutbound({ type }).allowed, `${type} should be carried`).toBe(true);
+ }
+ });
+
+ it('refuses a message type that is not on the list', () => {
+ const verdict = checkOutbound({ type: 'config/auth_provider/homeassistant/create' });
+ expect(verdict.allowed).toBe(false);
+ expect(verdict.reason).toMatch(/not a message type this relay carries into a home/);
+ });
+
+ it('limits subscribe_events to the one event type the room graph needs', () => {
+ expect(checkOutbound({ type: 'subscribe_events', event_type: 'state_changed' }).allowed).toBe(true);
+ const verdict = checkOutbound({ type: 'subscribe_events', event_type: 'call_service' });
+ expect(verdict.allowed).toBe(false);
+ expect(verdict.reason).toMatch(/more of the house than the room graph needs/);
+ });
+
+ it('refuses every service domain that can execute code or take the instance down', () => {
+ for (const domain of checkedIn.deniedServiceDomains) {
+ const verdict = checkOutbound({ type: 'call_service', domain, service: 'anything' });
+ expect(verdict.allowed, `${domain}.anything must be refused`).toBe(false);
+ }
+ });
+
+ it('refuses the named services that survive a permitted domain', () => {
+ for (const named of checkedIn.deniedServices) {
+ const [domain, service] = named.split('.');
+ const verdict = checkOutbound({ type: 'call_service', domain, service });
+ expect(verdict.allowed, `${named} must be refused`).toBe(false);
+ }
+ });
+
+ it('still carries an ordinary service call, including the one that locks up', () => {
+ expect(
+ checkOutbound({ type: 'call_service', domain: 'light', service: 'turn_on' }).allowed,
+ ).toBe(true);
+ expect(checkOutbound({ type: 'call_service', domain: 'lock', service: 'lock' }).allowed).toBe(true);
+ });
+
+ it('refuses anything that is not an object', () => {
+ for (const junk of [null, undefined, 'get_states', 42, ['get_states']]) {
+ expect(checkOutbound(junk).allowed, `${JSON.stringify(junk)} must be refused`).toBe(false);
+ }
+ });
+});
+
+describe('what the relay carries out of a house', () => {
+ it('allows only results, events and pongs', () => {
+ for (const type of checkedIn.inboundTypes) {
+ expect(checkInbound({ type }).allowed, `${type} should be carried`).toBe(true);
+ }
+ const verdict = checkInbound({ type: 'auth_required' });
+ expect(verdict.allowed).toBe(false);
+ expect(verdict.reason).toMatch(/not a message type this relay carries out of a home/);
+ });
+
+ it('refuses anything that is not an object', () => {
+ for (const junk of [null, undefined, 'result', 7, []]) {
+ expect(checkInbound(junk).allowed, `${JSON.stringify(junk)} must be refused`).toBe(false);
+ }
+ });
+});