Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.sqlnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.htmlnew file mode 100644index 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&t=Voice+satellite&d=Give+your+Home+Assistant+voice+assistant+a+face%2C+lip+sync+and+a+body.&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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100755index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.cssnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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);+ }+ });+});