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
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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.jsindex 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.jsindex 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;