Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(home-satellite): keep the token role's stdout clean and re-read identity

nirholas4702cf223be8
diff --git a/scripts/home-relay-gate-proof.mjs b/scripts/home-relay-gate-proof.mjs
new file mode 100644
index 000000000..625f0c5b1
--- /dev/null
+++ b/scripts/home-relay-gate-proof.mjs
@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * Run order 04's physical-action gate against a relayed home, from a network
+ * with no route to that home, and show the audit trail it leaves.
+ *
+ * scripts/home-relay-e2e.mjs already drives the gate at the bridge layer, which
+ * proves the transport does not swallow a refusal. This script tests the layer
+ * the product actually runs: `runHomeTool`, `mintConfirmation`, the claim and
+ * perform that api/home/[id]/confirm.js does, and the `home_action_log` rows
+ * all of that writes. The distinction matters because the gate is enforced in
+ * two places and only one of them is the bridge.
+ *
+ * What it asserts, in order:
+ *
+ * 1. three.ws holds no address and no credential for this house, so "cannot
+ * route to it" understates the position: there is nothing to route to.
+ * 2. Locking up runs with no prompt. A product that nags on the safe
+ * direction is a product people turn off.
+ * 3. Unlocking does NOT run. It returns a pending confirmation, and the door
+ * is still locked afterwards.
+ * 4. Redeeming that confirmation really unlocks the real door, and the same
+ * confirmation cannot be redeemed twice.
+ * 5. Every one of those wrote a `home_action_log` row with the same columns
+ * populated as a direct connection writes, so the transport creates no
+ * audit gap.
+ *
+ * It is invoked by scripts/home-relay-live.mjs, which builds the unroutable rig
+ * and passes the home it paired. Against a rig kept up with --keep:
+ *
+ * node scripts/home-relay-gate-proof.mjs --home <uuid> --user <uuid>
+ *
+ * Needs DATABASE_URL and the three HOME_RELAY_* variables in the environment.
+ */
+
+import { runHomeTool } from '../api/_lib/home/tools.js';
+import { claimConfirmation, finalizeConfirmation } from '../api/_lib/home/confirm.js';
+import { withHome, closeHome } from '../api/_lib/home/runtime.js';
+import { logHomeActionNow } from '../api/_lib/home/store.js';
+import { sql } from '../api/_lib/db.js';
+
+const args = parseArgs(process.argv.slice(2));
+const homeId = need('home');
+const userId = need('user');
+const ctx = { userId, source: 'api' };
+
+const results = [];
+let failures = 0;
+
+function step(name, ok, detail) {
+ results.push({ name, ok, detail });
+ if (!ok) failures += 1;
+ console.log(`${ok ? 'PASS' : 'FAIL'} ${name}${detail ? `\n ${detail}` : ''}`);
+}
+
+// 1. The house is on a network this process cannot reach, and for a relayed
+// home there is no address stored to reach it by. Both are true; the second
+// is the stronger claim, so it is the one asserted here.
+const [row] = await sql`
+ select transport, relay_id, base_url, access_token_enc, token_fingerprint
+ from home_connections where id = ${homeId}`;
+step(
+ 'three.ws holds no way to dial this house directly',
+ row?.transport === 'relay' && row.access_token_enc === '' && row.token_fingerprint === '' && row.base_url === `relay://${row.relay_id}`,
+ `transport=${row?.transport} base_url=${row?.base_url} access_token_enc=${JSON.stringify(row?.access_token_enc)} token_fingerprint=${JSON.stringify(row?.token_fingerprint)}`,
+);
+
+// The read tool, over the relay, before anything is changed.
+const status = await runHomeTool('home_status', { home_id: homeId }, ctx);
+step(
+ 'home_status reads the house over the relay',
+ status.ok === true && !status.structured?.stale,
+ `rooms=${status.structured?.summary?.rooms} entities=${status.structured?.summary?.entities} locks=${status.structured?.summary?.locks} stale=${status.structured?.stale}`,
+);
+
+const lockId = await withHome(homeId, userId, (bridge) =>
+ Object.keys(bridge.states).filter((id) => id.startsWith('lock.') && bridge.states[id].state !== 'unavailable').sort()[0],
+);
+if (!lockId) {
+ step('a lock exists to gate', false, 'no lock.* entity in this house');
+ await finish();
+}
+
+// 2. The safe direction, which must not prompt.
+const locked = await runHomeTool('home_call', { home_id: homeId, domain: 'lock', service: 'lock', data: { entity_id: lockId } }, ctx);
+step(
+ 'locking up runs immediately over the relay, with no prompt',
+ locked.ok === true,
+ `${lockId}: ok=${locked.ok} kind=${locked.kind} status=${locked.structured?.status || 'ran'}`,
+);
+await settleLock(lockId, 'locked');
+
+// 3. The guarded direction, which must not run.
+const refused = await runHomeTool('home_call', { home_id: homeId, domain: 'lock', service: 'unlock', data: { entity_id: lockId } }, ctx);
+const pending = refused.structured?.confirmation;
+step(
+ 'an unlock over the relay is refused and returns a pending confirmation',
+ refused.ok === false && refused.kind === 'pending_confirmation' && Boolean(pending?.id),
+ `ok=${refused.ok} kind=${refused.kind} status=${refused.structured?.status} risk=${pending?.risk} summary=${JSON.stringify(pending?.summary)} expires_in=${pending?.expires_in_seconds}s confirm_url=${pending?.confirm_url}`,
+);
+if (!pending?.id) await finish();
+
+const heldShut = await readLock(lockId);
+step(
+ 'the door did not move while the confirmation was pending',
+ heldShut === 'locked',
+ `${lockId} is ${heldShut} after the refused unlock`,
+);
+
+// 4. The redemption, performed exactly as api/home/[id]/confirm.js performs it:
+// claim the frozen action, then call with `confirmed: true` on a server that
+// is holding a redeemed claim. That flag is set in no other place.
+const claim = await claimConfirmation({ id: pending.id, homeId, userId });
+step('the confirmation claims once, for its owner', claim.ok === true, claim.ok ? `claimed ${pending.id}` : `${claim.reason}: ${claim.message}`);
+if (!claim.ok) await finish();
+
+const action = claim.confirmation;
+let performed = null;
+try {
+ await withHome(homeId, userId, (bridge) => bridge.call(action.domain, action.service, action.service_data, { confirmed: true }));
+ await finalizeConfirmation(action.id, 'ok');
+ performed = 'ok';
+} catch (err) {
+ await finalizeConfirmation(action.id, 'failed');
+ performed = String(err?.message || err);
+}
+await logHomeActionNow({
+ homeId,
+ userId,
+ actor: 'user',
+ channel: 'websocket',
+ action: `${action.domain}.${action.service}`,
+ entityIds: action.entity_ids,
+ guarded: true,
+ confirmedBy: userId,
+ risk: action.risk,
+ outcome: performed === 'ok' ? 'ok' : 'failed',
+ detail: { confirmation_id: action.id, source: action.source },
+});
+
+const unlocked = await settleLock(lockId, 'unlocked');
+step(
+ 'the redeemed confirmation really unlocks the real door',
+ performed === 'ok' && unlocked === 'unlocked',
+ `${lockId}: locked -> ${unlocked}, confirmation ${action.id} redeemed by a human's claim (${performed})`,
+);
+
+// The same confirmation must not redeem twice.
+const replay = await claimConfirmation({ id: pending.id, homeId, userId });
+step(
+ 'the same confirmation cannot be redeemed again',
+ replay.ok === false,
+ replay.ok ? 'a second claim on the same confirmation succeeded' : `${replay.reason}: ${replay.message}`,
+);
+
+// Put the house back the way it was found.
+await runHomeTool('home_call', { home_id: homeId, domain: 'lock', service: 'lock', data: { entity_id: lockId } }, ctx).catch(() => null);
+
+// 5. The audit trail. Completeness is the claim, so every row is printed whole
+// rather than summarised.
+const rows = await sql`
+ select id, home_id, user_id, actor, channel, action, entity_ids, guarded,
+ confirmed_by, risk, outcome, detail, created_at
+ from home_action_log where home_id = ${homeId} order by id asc`;
+console.log(`\n---- home_action_log for the relayed home ${homeId} ----`);
+for (const entry of rows) console.log(JSON.stringify(entry));
+console.log('---- end action log ----\n');
+
+// The columns a direct connection fills are the columns these must fill. The
+// nullable ones (user_id, confirmed_by, risk, detail) are checked where they
+// are meant to be present rather than everywhere.
+const complete = (entry) =>
+ Boolean(entry.home_id) && Boolean(entry.user_id) && Boolean(entry.actor) && Boolean(entry.channel) &&
+ Boolean(entry.action) && Array.isArray(entry.entity_ids) && entry.entity_ids.length > 0 &&
+ typeof entry.guarded === 'boolean' && Boolean(entry.outcome) && Boolean(entry.created_at);
+const confirmedRow = rows.find((entry) => entry.guarded && entry.confirmed_by);
+step(
+ 'every relayed action wrote a complete audit row',
+ rows.length >= 3 && rows.every(complete) && Boolean(confirmedRow),
+ `${rows.length} rows, all core columns populated: ${rows.every(complete)}. ` +
+ `Refusal logged: ${rows.some((e) => e.outcome === 'refused')}. ` +
+ `Confirmed row carries confirmed_by=${confirmedRow?.confirmed_by || 'none'} risk=${confirmedRow?.risk || 'none'}.`,
+);
+
+await finish();
+
+// -------------------------------------------------------------- small parts
+
+async function finish() {
+ await closeHome(homeId).catch(() => null);
+ console.log(`\n${results.length - failures}/${results.length} checks passed.`);
+ process.exit(failures ? 1 : 0);
+}
+
+function need(name) {
+ const value = args[name];
+ if (!value) {
+ console.error(`Missing --${name}. See the header of this file.`);
+ process.exit(2);
+ }
+ return value;
+}
+
+async function readLock(entityId) {
+ return withHome(homeId, userId, (bridge) => bridge.states[entityId]?.state);
+}
+
+/** Waits for the live state channel to report the change, not a fixed delay. */
+async function settleLock(entityId, want, timeoutMs = 10_000) {
+ const deadline = Date.now() + timeoutMs;
+ let state = await readLock(entityId);
+ while (Date.now() < deadline && state !== want) {
+ await new Promise((resolve) => setTimeout(resolve, 200));
+ state = await readLock(entityId);
+ }
+ return state;
+}
+
+function parseArgs(argv) {
+ const out = {};
+ for (let i = 0; i < argv.length; i += 1) {
+ if (!argv[i].startsWith('--')) continue;
+ const key = argv[i].slice(2);
+ const next = argv[i + 1];
+ if (next && !next.startsWith('--')) {
+ out[key] = next;
+ i += 1;
+ } else {
+ out[key] = true;
+ }
+ }
+ return out;
+}
diff --git a/scripts/home-relay-live.mjs b/scripts/home-relay-live.mjs
new file mode 100644
index 000000000..119002cd0
--- /dev/null
+++ b/scripts/home-relay-live.mjs
@@ -0,0 +1,601 @@
+#!/usr/bin/env node
+/**
+ * Stand up the whole dial-out rig and prove it, in one command.
+ *
+ * docs/home-relay.md described this rig as a sequence of docker commands with
+ * `<id>` and `<token>` left for a human to fill in from output nobody had yet
+ * produced. That is a recipe, not a proof: it cannot be re-run after a change,
+ * so in practice it was never re-run at all. This script is the same rig, built
+ * and torn down by machine, so the relay's central claim can be re-checked as
+ * cheaply as a unit test.
+ *
+ * The claim under test is narrow and worth stating exactly: three.ws can drive
+ * a Home Assistant it has no route to, because the house dials out and nothing
+ * dials in.
+ *
+ * The topology, and why each piece sits where it does:
+ *
+ * house-net the house. A real Home Assistant with NO published port, so it
+ * is unreachable from anywhere except this network. It reaches
+ * the outside through host-gateway, which is what a real house's
+ * NAT gives it.
+ * cloud-net three.ws. Both the relay AND every caller live here. Docker
+ * refuses to route between two user-defined bridges, so nothing
+ * in cloud-net can open a connection to the house. The relay is
+ * deliberately on this side: if it sat on the host, which can
+ * reach both bridges, the rig would prove less than it appears to.
+ *
+ * The only path between the two is the socket the house opens outbound to the
+ * relay's host-published port. Every proof below runs from cloud-net, and each
+ * begins by failing to reach the house directly.
+ *
+ * node scripts/home-relay-live.mjs # up, prove, tear down
+ * node scripts/home-relay-live.mjs --keep # leave the rig running
+ * node scripts/home-relay-live.mjs --down # tear a kept rig down
+ *
+ * Needs DATABASE_URL, because pairing is a real row in a real table. It creates
+ * a throwaway owner and deletes it, along with its home, on the way out.
+ */
+
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const opts = parseArgs(process.argv.slice(2));
+const NAME = opts.name || 'relay10';
+
+/** Marks every container this script creates. Nothing without it is touched. */
+const LABEL = 'ws.three.home-relay-live';
+const HOUSE = `threews-house-${NAME}`;
+const RELAY = `threews-relay-${NAME}`;
+const CONFIG_DIR = path.join(ROOT, `.ha-relay-${NAME}`);
+const HOUSE_NET = 'house-net';
+const CLOUD_NET = 'cloud-net';
+const IMAGE = 'ghcr.io/home-assistant/home-assistant:stable';
+const NODE_IMAGE = 'node:24-slim';
+const OWNER = { name: 'Relay Lane', username: 'threews', password: 'threews-relay-lane' };
+
+const results = [];
+let failures = 0;
+
+function step(name, ok, detail) {
+ results.push({ name, ok, detail });
+ if (!ok) failures += 1;
+ console.log(`${ok ? 'PASS' : 'FAIL'} ${name}${detail ? `\n ${detail}` : ''}`);
+}
+
+function log(...args) {
+ console.error('[rig]', ...args);
+}
+
+async function main() {
+ if (opts.down) {
+ await teardown();
+ console.log('rig down.');
+ return;
+ }
+ if (!process.env.DATABASE_URL) {
+ console.error('DATABASE_URL is not set. It lives in .env.local; pairing writes a real row.');
+ process.exit(2);
+ }
+
+ // One relay, two names. In production HOME_RELAY_URL is a single public
+ // address; here the house and the platform each reach the same container by
+ // a different route, so the two sides are configured separately and that
+ // split is a property of the rig, not of the product.
+ const relayHostPort = await freePort();
+ const redeemPort = await freePort();
+ const houseFacingRelay = `ws://relay.host:${relayHostPort}`;
+ const cloudFacingRelay = `ws://${RELAY}:8899`;
+ const signingKey = crypto.randomBytes(32).toString('hex');
+ const serviceToken = crypto.randomBytes(32).toString('hex');
+
+ let owner = null;
+ let redeemServer = null;
+ const { sql } = await import('../api/_lib/db.js');
+
+ try {
+ await ensureNetworks();
+ const houseIp = await startHouse();
+ await startRelay({ relayHostPort, signingKey, serviceToken });
+
+ step(
+ 'cloud-net cannot open a connection to the house',
+ !(await cloudNetCanReach(houseIp)),
+ `a container on ${CLOUD_NET} fetching http://${houseIp}:8123 from the house on ${HOUSE_NET}`,
+ );
+
+ const token = await onboardHouse();
+ await installIntegration();
+
+ owner = await createOwner(sql);
+ const { home, code } = await mintPairing({ owner, houseFacingRelay, signingKey, serviceToken });
+ step(
+ 'a relayed home is stored with no Home Assistant credential',
+ home.access_token_enc === '' && home.token_fingerprint === '' && home.base_url === `relay://${home.relay_id}`,
+ `home ${home.id}: transport=${home.transport} relay_id=${home.relay_id} base_url=${home.base_url} access_token_enc=${JSON.stringify(home.access_token_enc)} token_fingerprint=${JSON.stringify(home.token_fingerprint)}`,
+ );
+
+ redeemServer = await serveRedeem({ port: redeemPort, houseFacingRelay, signingKey, serviceToken });
+ await pairThroughConfigFlow({ token, code, redeemPort });
+ await waitForDialIn({ relayHostPort, relayId: home.relay_id, serviceToken });
+ step('the house dialled the relay and is online', true, `relay reports ${home.relay_id} connected`);
+
+ await runProof('the unroutable end-to-end proof', [
+ 'node', 'scripts/home-relay-e2e.mjs',
+ '--relay', cloudFacingRelay,
+ '--relay-id', home.relay_id,
+ '--service-token', serviceToken,
+ '--unroutable', `http://${houseIp}:8123`,
+ ], { HOME_RELAY_SIGNING_KEY: signingKey });
+
+ await runProof('the order 04 gate and the action log, over the relay', [
+ 'node', 'scripts/home-relay-gate-proof.mjs',
+ '--home', home.id,
+ '--user', owner.id,
+ ], {
+ DATABASE_URL: process.env.DATABASE_URL,
+ HOME_RELAY_URL: cloudFacingRelay,
+ HOME_RELAY_SERVICE_TOKEN: serviceToken,
+ HOME_RELAY_SIGNING_KEY: signingKey,
+ HOME_ENCRYPTION_KEY: process.env.HOME_ENCRYPTION_KEY || '',
+ });
+
+ await proveKillAndRecover({ relayHostPort, relayId: home.relay_id, serviceToken });
+ } finally {
+ if (redeemServer) await new Promise((resolve) => redeemServer.close(resolve));
+ if (owner) {
+ await sql`delete from users where id = ${owner.id}`;
+ log(`deleted the throwaway owner ${owner.id} and its home`);
+ }
+ if (!opts.keep) await teardown();
+ else log(`rig kept up. Tear it down with: node scripts/home-relay-live.mjs --down --name ${NAME}`);
+ }
+
+ console.log(`\n${results.length - failures}/${results.length} checks passed.`);
+ process.exit(failures ? 1 : 0);
+}
+
+// ------------------------------------------------------------------ the rig
+
+async function ensureNetworks() {
+ for (const network of [HOUSE_NET, CLOUD_NET]) {
+ const existing = await docker(['network', 'ls', '--filter', `name=^${network}$`, '--format', '{{.Name}}']);
+ if (existing.trim() !== network) {
+ await docker(['network', 'create', network]);
+ log(`created network ${network}`);
+ }
+ }
+}
+
+/** The house: a real Home Assistant with nothing published. */
+async function startHouse() {
+ if (await containerRunning(HOUSE)) {
+ log(`house ${HOUSE} already up`);
+ } else {
+ await removeIfOurs(HOUSE);
+ fs.mkdirSync(CONFIG_DIR, { recursive: true });
+ // demo gives the house lights and a lock to actually drive. Without it
+ // the proof has nothing to turn on and reports a pass over an empty room.
+ fs.writeFileSync(
+ path.join(CONFIG_DIR, 'configuration.yaml'),
+ 'default_config:\n\ndemo:\n\nlogger:\n default: info\n logs:\n custom_components.three_ws: debug\n',
+ );
+ await docker([
+ 'run', '-d', '--name', HOUSE, '--label', LABEL,
+ '--network', HOUSE_NET,
+ // How the house reaches the outside world, standing in for its NAT.
+ '--add-host', 'relay.host:host-gateway',
+ '-v', `${CONFIG_DIR}:/config`,
+ IMAGE,
+ ]);
+ log(`started the house ${HOUSE} with no published port`);
+ }
+ const ip = await houseIp();
+ await waitForHouse(ip);
+ return ip;
+}
+
+async function startRelay({ relayHostPort, signingKey, serviceToken }) {
+ await removeIfOurs(RELAY);
+ await docker([
+ 'run', '-d', '--name', RELAY, '--label', LABEL,
+ '--network', CLOUD_NET,
+ // Published so the house can dial in through host-gateway, which is the
+ // only direction any connection is ever opened.
+ '-p', `${relayHostPort}:8899`,
+ '-v', `${ROOT}:/app`, '-w', '/app',
+ '-e', 'PORT=8899',
+ '-e', `HOME_RELAY_SIGNING_KEY=${signingKey}`,
+ '-e', `HOME_RELAY_SERVICE_TOKEN=${serviceToken}`,
+ NODE_IMAGE,
+ 'node', 'services/home-relay/src/index.js',
+ ]);
+ await waitFor(async () => {
+ const res = await fetch(`http://127.0.0.1:${relayHostPort}/healthz`, { signal: AbortSignal.timeout(3000) }).catch(() => null);
+ return res?.ok === true;
+ }, { label: 'the relay to answer /healthz' });
+ log(`relay ${RELAY} up on cloud-net, published at 127.0.0.1:${relayHostPort}`);
+}
+
+/** The isolation the whole design rests on, measured rather than assumed. */
+async function cloudNetCanReach(ip) {
+ const out = await docker([
+ 'run', '--rm', '--network', CLOUD_NET, '--label', LABEL, NODE_IMAGE,
+ 'node', '-e',
+ `fetch('http://${ip}:8123/',{signal:AbortSignal.timeout(8000)}).then(r=>console.log('REACHED '+r.status),e=>console.log('BLOCKED '+e.name))`,
+ ]);
+ log(`cloud-net -> house: ${out.trim()}`);
+ return out.includes('REACHED');
+}
+
+async function teardown() {
+ for (const container of [HOUSE, RELAY]) await removeIfOurs(container);
+ fs.rmSync(CONFIG_DIR, { recursive: true, force: true });
+ log('removed the containers and the config directory');
+}
+
+// ------------------------------------------------------------- the house API
+
+/**
+ * Home Assistant's real onboarding flow, the one the browser performs, then a
+ * long-lived token. Driven from the host, which can route to house-net; only
+ * the proofs need to run from a network that cannot.
+ */
+async function onboardHouse() {
+ const ip = await houseIp();
+ const baseUrl = `http://${ip}:8123`;
+ const clientId = `${baseUrl}/`;
+ const steps = await json(`${baseUrl}/api/onboarding`);
+ const done = new Set(steps.filter((s) => s.done).map((s) => s.step));
+
+ let session;
+ if (done.has('user')) {
+ const flow = await json(`${baseUrl}/auth/login_flow`, {
+ method: 'POST',
+ body: { client_id: clientId, handler: ['homeassistant', null], redirect_uri: clientId, type: 'authorize' },
+ });
+ const result = await json(`${baseUrl}/auth/login_flow/${flow.flow_id}`, {
+ method: 'POST',
+ body: { client_id: clientId, username: OWNER.username, password: OWNER.password },
+ });
+ session = await exchangeCode(baseUrl, clientId, result.result);
+ } else {
+ const created = await json(`${baseUrl}/api/onboarding/users`, {
+ method: 'POST',
+ body: { client_id: clientId, ...OWNER, language: 'en' },
+ });
+ session = await exchangeCode(baseUrl, clientId, created.auth_code);
+ for (const stage of ['core_config', 'analytics']) {
+ await json(`${baseUrl}/api/onboarding/${stage}`, {
+ method: 'POST',
+ token: session.access_token,
+ body: stage === 'analytics' ? { preferences: { base: false } } : {},
+ optional: true,
+ });
+ }
+ await json(`${baseUrl}/api/onboarding/integration`, {
+ method: 'POST',
+ token: session.access_token,
+ body: { client_id: clientId, redirect_uri: clientId },
+ optional: true,
+ });
+ }
+ const token = await mintLongLivedToken(baseUrl, session.access_token);
+ log('onboarded the house and minted a long-lived token');
+ return token;
+}
+
+async function exchangeCode(baseUrl, clientId, code) {
+ const res = await fetch(`${baseUrl}/auth/token`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/x-www-form-urlencoded' },
+ body: new URLSearchParams({ grant_type: 'authorization_code', code, client_id: clientId }),
+ });
+ if (!res.ok) throw new Error(`token exchange returned ${res.status}: ${await res.text()}`);
+ return res.json();
+}
+
+/** The long-lived token is a WebSocket command, not a REST call. */
+async function mintLongLivedToken(baseUrl, accessToken) {
+ const { WebSocket } = await import('ws');
+ const socket = new WebSocket(`${baseUrl.replace(/^http/, 'ws')}/api/websocket`);
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => finish(new Error('timed out minting a long-lived token')), 30_000);
+ const finish = (err, value) => {
+ clearTimeout(timer);
+ try {
+ socket.close();
+ } catch {
+ // Already gone.
+ }
+ if (err) reject(err);
+ else resolve(value);
+ };
+ socket.on('message', (raw) => {
+ const frame = JSON.parse(String(raw));
+ if (frame.type === 'auth_required') {
+ socket.send(JSON.stringify({ type: 'auth', access_token: accessToken }));
+ } else if (frame.type === 'auth_ok') {
+ socket.send(JSON.stringify({
+ id: 1,
+ type: 'auth/long_lived_access_token',
+ client_name: `three.ws relay lane ${Date.now()}`,
+ lifespan: 30,
+ }));
+ } else if (frame.id === 1) {
+ if (frame.success) finish(null, frame.result);
+ else finish(new Error(`long-lived token refused: ${JSON.stringify(frame.error)}`));
+ }
+ });
+ socket.on('error', (err) => finish(err));
+ });
+}
+
+/** Install the integration the way HACS does: copy it in and restart. */
+async function installIntegration() {
+ const source = path.join(ROOT, 'home-assistant-integration', 'custom_components', 'three_ws');
+ const target = path.join(CONFIG_DIR, 'custom_components', 'three_ws');
+ fs.rmSync(target, { recursive: true, force: true });
+ fs.mkdirSync(path.dirname(target), { recursive: true });
+ fs.cpSync(source, target, { recursive: true });
+ await docker(['restart', HOUSE]);
+ await waitForHouse(await houseIp());
+ log('installed the integration into the house and restarted it');
+}
+
+/**
+ * Redeem the code through the integration's real config flow, which is the
+ * screen a user fills in. Nothing is written into .storage by hand.
+ */
+async function pairThroughConfigFlow({ token, code, redeemPort }) {
+ const baseUrl = `http://${await houseIp()}:8123`;
+ const flow = await json(`${baseUrl}/api/config/config_entries/flow`, {
+ method: 'POST',
+ token,
+ body: { handler: 'three_ws', show_advanced_options: false },
+ });
+ const result = await json(`${baseUrl}/api/config/config_entries/flow/${flow.flow_id}`, {
+ method: 'POST',
+ token,
+ // relay.host is the house's name for the machine outside it, so this is
+ // the same outbound-only route the relay socket uses.
+ body: { pairing_code: code, platform_url: `http://relay.host:${redeemPort}` },
+ });
+ step(
+ 'the house redeemed the pairing code through its own config flow',
+ result?.type === 'create_entry',
+ result?.type === 'create_entry'
+ ? `config entry "${result.title}" created inside Home Assistant`
+ : `flow returned ${JSON.stringify(result).slice(0, 300)}`,
+ );
+ if (result?.type !== 'create_entry') throw new Error('pairing failed, so nothing below would mean anything');
+}
+
+// ------------------------------------------------------------ the redeem API
+
+/**
+ * Serve the real /api/home/pair/redeem handler, and only that one, on a port
+ * the house can reach. This is the production module, imported and called: the
+ * point of the rig is that the house talks to our actual pairing code path.
+ */
+async function serveRedeem({ port, houseFacingRelay, signingKey, serviceToken }) {
+ // The install token this endpoint mints must name the relay URL as the HOUSE
+ // sees it, which is why the redeem side is configured separately from the
+ // platform side above.
+ process.env.HOME_RELAY_URL = houseFacingRelay;
+ process.env.HOME_RELAY_SIGNING_KEY = signingKey;
+ process.env.HOME_RELAY_SERVICE_TOKEN = serviceToken;
+ const { default: handler } = await import('../api/home/pair/redeem.js');
+
+ const server = http.createServer((req, res) => {
+ handler(req, res).catch((err) => {
+ console.error('[redeem]', err);
+ if (!res.headersSent) res.writeHead(500).end('{"error":"handler_failed"}');
+ });
+ });
+ await new Promise((resolve) => server.listen(port, '0.0.0.0', resolve));
+ log(`serving the real /api/home/pair/redeem handler on port ${port}`);
+ return server;
+}
+
+// ------------------------------------------------------------------- pairing
+
+async function createOwner(sql) {
+ const [owner] = await sql`
+ insert into users (email) values (${`home-relay-live-${Date.now()}@qa.three.ws`}) returning id`;
+ log(`created the throwaway owner ${owner.id}`);
+ return owner;
+}
+
+async function mintPairing({ owner, houseFacingRelay, signingKey, serviceToken }) {
+ process.env.HOME_RELAY_URL = houseFacingRelay;
+ process.env.HOME_RELAY_SIGNING_KEY = signingKey;
+ process.env.HOME_RELAY_SERVICE_TOKEN = serviceToken;
+ const relay = await import('../api/_lib/home/relay.js');
+ const { sql } = await import('../api/_lib/db.js');
+ const { home, code } = await relay.startPairing({ userId: owner.id, label: 'Unroutable house' });
+ const [row] = await sql`
+ select id, transport, relay_id, base_url, access_token_enc, token_fingerprint
+ from home_connections where id = ${home.id}`;
+ log(`minted a pairing code for home ${home.id}`);
+ return { home: row, code };
+}
+
+async function waitForDialIn({ relayHostPort, relayId, serviceToken }) {
+ await waitFor(async () => {
+ const res = await fetch(`http://127.0.0.1:${relayHostPort}/v1/status?relay_id=${relayId}`, {
+ headers: { authorization: `Bearer ${serviceToken}` },
+ signal: AbortSignal.timeout(3000),
+ }).catch(() => null);
+ if (!res?.ok) return false;
+ const body = await res.json().catch(() => null);
+ return body?.connected === true;
+ }, { label: 'the house to dial the relay', timeout: 120_000 });
+}
+
+// -------------------------------------------------------------- the proofs
+
+/** Every proof runs from cloud-net, which has no route to the house. */
+async function runProof(label, argv, env) {
+ console.log(`\n---- ${label} (from ${CLOUD_NET}) ----`);
+ const args = ['run', '--rm', '--network', CLOUD_NET, '--label', LABEL, '-v', `${ROOT}:/app`, '-w', '/app'];
+ for (const [key, value] of Object.entries(env)) {
+ if (value) args.push('-e', `${key}=${value}`);
+ }
+ args.push(NODE_IMAGE, ...argv);
+ const { code, out } = await dockerRaw(args);
+ process.stdout.write(out);
+ step(label, code === 0, `exit ${code}`);
+ console.log(`---- end ${label} ----\n`);
+}
+
+/**
+ * State 4: the add-on goes away and the home reports it honestly, then comes
+ * back on its own. "On its own" is the part that matters, so nothing here
+ * touches three.ws between the two halves.
+ */
+async function proveKillAndRecover({ relayHostPort, relayId, serviceToken }) {
+ const status = async () => {
+ const res = await fetch(`http://127.0.0.1:${relayHostPort}/v1/status?relay_id=${relayId}`, {
+ headers: { authorization: `Bearer ${serviceToken}` },
+ signal: AbortSignal.timeout(3000),
+ }).catch(() => null);
+ return res?.ok ? res.json() : null;
+ };
+
+ await docker(['stop', HOUSE]);
+ const gone = await waitFor(async () => (await status())?.connected === false, {
+ label: 'the relay to notice the house is gone',
+ timeout: 90_000,
+ }).then(() => true, () => false);
+ step(
+ 'killing the integration puts the home in the offline state',
+ gone,
+ gone ? `relay reports ${relayId} disconnected within the heartbeat window` : 'the relay still reported the house as connected',
+ );
+
+ await docker(['start', HOUSE]);
+ const back = await waitFor(async () => (await status())?.connected === true, {
+ label: 'the house to come back on its own',
+ timeout: 180_000,
+ }).then(() => true, () => false);
+ step(
+ 'restarting it recovers with no action on the three.ws side',
+ back,
+ back ? `${relayId} reconnected by itself, nothing was re-paired` : 'the house did not reconnect',
+ );
+}
+
+// -------------------------------------------------------------- small parts
+
+function parseArgs(argv) {
+ const out = {};
+ for (let i = 0; i < argv.length; i += 1) {
+ if (!argv[i].startsWith('--')) continue;
+ const key = argv[i].slice(2);
+ const next = argv[i + 1];
+ if (next && !next.startsWith('--')) {
+ out[key] = next;
+ i += 1;
+ } else {
+ out[key] = true;
+ }
+ }
+ return out;
+}
+
+function docker(args) {
+ return dockerRaw(args).then(({ code, out }) => {
+ if (code !== 0) throw new Error(`docker ${args.slice(0, 3).join(' ')} failed (${code}): ${out.slice(0, 400)}`);
+ return out;
+ });
+}
+
+function dockerRaw(args) {
+ return new Promise((resolve) => {
+ const child = spawn('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+ let out = '';
+ child.stdout.on('data', (chunk) => {
+ out += chunk;
+ });
+ child.stderr.on('data', (chunk) => {
+ out += chunk;
+ });
+ child.on('close', (code) => resolve({ code, out }));
+ });
+}
+
+/** Never stop or remove a container this script did not create. */
+async function removeIfOurs(container) {
+ const label = await dockerRaw(['inspect', '-f', '{{index .Config.Labels "' + LABEL + '"}}', container]);
+ if (label.code !== 0) return;
+ if (label.out.trim() !== LABEL) {
+ log(`refusing to touch ${container}: it is not ours`);
+ return;
+ }
+ await dockerRaw(['rm', '-f', container]);
+}
+
+async function containerRunning(container) {
+ const res = await dockerRaw(['inspect', '-f', '{{.State.Running}}{{index .Config.Labels "' + LABEL + '"}}', container]);
+ return res.code === 0 && res.out.trim() === `true${LABEL}`;
+}
+
+async function houseIp() {
+ const out = await docker(['inspect', '-f', `{{(index .NetworkSettings.Networks "${HOUSE_NET}").IPAddress}}`, HOUSE]);
+ return out.trim();
+}
+
+async function waitForHouse(ip) {
+ await waitFor(async () => {
+ // A fresh instance answers /api/onboarding with 200 and an onboarded one
+ // with 401. Either means it is up; a refused connection means it is not.
+ const res = await fetch(`http://${ip}:8123/api/onboarding`, { signal: AbortSignal.timeout(4000) }).catch(() => null);
+ return res ? res.status === 200 || res.status === 401 : false;
+ }, { label: 'Home Assistant to boot', timeout: 240_000 });
+}
+
+async function waitFor(condition, { timeout = 60_000, interval = 2000, label = 'condition' } = {}) {
+ const deadline = Date.now() + timeout;
+ while (Date.now() < deadline) {
+ if (await condition()) return true;
+ await new Promise((resolve) => setTimeout(resolve, interval));
+ }
+ throw new Error(`timed out waiting for ${label}`);
+}
+
+async function json(url, { method: verb = 'GET', body, token, optional = false } = {}) {
+ const res = await fetch(url, {
+ method: verb,
+ headers: {
+ 'content-type': 'application/json',
+ ...(token ? { authorization: `Bearer ${token}` } : {}),
+ },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ signal: AbortSignal.timeout(60_000),
+ });
+ if (!res.ok) {
+ if (optional) return null;
+ throw new Error(`${verb} ${url} returned ${res.status}: ${(await res.text()).slice(0, 300)}`);
+ }
+ return res.status === 204 ? null : res.json();
+}
+
+function freePort() {
+ return new Promise((resolve, reject) => {
+ const server = net.createServer();
+ server.on('error', reject);
+ server.listen(0, '127.0.0.1', () => {
+ const { port } = server.address();
+ server.close(() => resolve(port));
+ });
+ });
+}
+
+await main();
diff --git a/services/home-satellite/src/index.js b/services/home-satellite/src/index.js
index 2acf084a4..90fd9ab2e 100755
--- a/services/home-satellite/src/index.js
+++ b/services/home-satellite/src/index.js
@@ -40,7 +40,13 @@ if (argv.includes('--help') || argv.includes('-h')) {
process.exit(0);
}
-const log = (entry) => console.log(JSON.stringify({ ts: new Date().toISOString(), ...entry }));
+// `token` prints one credential to stdout and nothing else, because the
+// documented way to use it is `--token "$(node src/index.js token)"`. Logging a
+// startup line to stdout in that role puts JSON in front of the token and hands
+// the caller something that cannot authenticate. Every other role logs to
+// stdout, where a container runtime collects it.
+const logStream = role === 'token' ? process.stderr : process.stdout;
+const log = (entry) => logStream.write(`${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`);
if (role === 'hub') {
const service = await createHubService({ port: Number(flag('port', process.env.PORT || 8080)), log });
diff --git a/services/home-satellite/src/server.js b/services/home-satellite/src/server.js
index 902bbdaad..5d8229abe 100644
--- a/services/home-satellite/src/server.js
+++ b/services/home-satellite/src/server.js
@@ -57,12 +57,14 @@ export async function createSatelliteService({
} = {}) {
let identity = await loadIdentity(stateDir);
let pairingError = null;
+ let claimedNow = false;
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);
+ claimedNow = true;
log({ level: 'info', event: 'pairing.claimed', satellite_id: identity.satellite_id, agent: identity.agent?.name || null });
} catch (err) {
pairingError = err.message;
@@ -73,6 +75,28 @@ export async function createSatelliteService({
log({ level: 'error', event: 'pairing.missing' });
}
+ // A satellite claimed months ago is otherwise running on whatever the
+ // identity file recorded that day: the agent's name as it was then, its
+ // avatar as it was then, and whichever hub existed then. Ask three.ws once
+ // at every start, so renaming an agent or giving it a new body reaches the
+ // screen on the wall, and so a satellite paired before a hub was configured
+ // starts using one without being re-paired.
+ //
+ // Best effort, and deliberately so. The house's voice assistant does not
+ // depend on three.ws being reachable, and neither does starting the service
+ // that gives it a face: a failure here is logged and the satellite comes up
+ // on what it already knows.
+ if (identity && !claimedNow) {
+ try {
+ const next = await refreshHubToken({ identity, fetchImpl });
+ identity = { ...identity, ...next };
+ await saveIdentity(stateDir, identity);
+ log({ level: 'info', event: 'session.refreshed', agent: identity.agent?.name || null, hub: !!identity.hub_url });
+ } catch (err) {
+ log({ level: 'warn', event: 'session.refresh_failed', message: err.message });
+ }
+ }
+
const paired = !!identity;
const displayName = identity?.name || name;