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.

test(home): prove the confirmation protocol over the wire

nirholasac390203d073
diff --git a/docs/home-security.md b/docs/home-security.md
index b34b9508a..c62b73fef 100644
--- a/docs/home-security.md
+++ b/docs/home-security.md
@@ -207,13 +207,27 @@ exists so the UI can tell the two apart from the security refusals when it needs
# Everything except the live injection proof, on every npm test:
npx vitest run tests/home-security.test.js
-# The injection proof needs a real house. Never mock one: a fake instance would
-# have hidden the HassTurnOff-unlocks-a-lock behaviour this whole gate exists for.
-docker run -d --name ha -p 8123:8123 -v "$PWD/.ha-config:/config" \
- ghcr.io/home-assistant/home-assistant:stable
-# add `demo:` to .ha-config/configuration.yaml, restart, mint a long-lived token
-HOME_ASSISTANT_URL=http://localhost:8123 HOME_ASSISTANT_TOKEN=... \
- npx vitest run tests/home-security.test.js
+# Check 4 needs a real house AND a real model. Never mock the house: a fake
+# instance would have hidden the HassTurnOff-unlocks-a-lock behaviour this whole
+# gate exists for. The lane's harness builds one, seeded and onboarded, in one
+# command, and it is the only instance any live home test should use.
+eval "$(node scripts/home-test-instance.mjs --up --onboard --seed --name sec11 --env)"
+npx vitest run tests/home-security.test.js
+node scripts/home-test-instance.mjs --down --name sec11
```
+**The model half is a real requirement, not a nicety.** Check 4's real arm asks the
+[LLM chain](../api/_lib/llm.js) for four turns and executes whatever they ask for. Without a
+credential the chain falls through to its two keyless anonymous rungs, both of which answer 429
+under any load, and the test **fails** with `no model in the chain answered, so this proved
+nothing`. That is deliberate: a door staying locked because nothing ever asked to open it is an
+outage, not a proof, and a security check that passes during an outage is worse than no check.
+Production carries the keys; locally, put one keyed rung in the environment (`GROQ_API_KEY`,
+`NVIDIA_API_KEY` and `OPENROUTER_API_KEY` are all on the `three-ws-api` service, readable with
+`node scripts/read-service-env.mjs '^GROQ_API_KEY$' --raw`).
+
+The deterministic arm needs no model at all: it submits the injected instruction directly. It
+runs whenever the house is up, which is why check 4 still proves the gate on a run where every
+model turn was refused by a rate limiter.
+
The secrets scan and the dependency posture run with everything else and need nothing.
diff --git a/scripts/check-home-voice.mjs b/scripts/check-home-voice.mjs
index 3975cac57..8c0250877 100644
--- a/scripts/check-home-voice.mjs
+++ b/scripts/check-home-voice.mjs
@@ -475,6 +475,17 @@ async function scenarioHappyPath() {
}
}
+/**
+ * The answer the agent is part-way through when it gets interrupted. Long enough
+ * that a real interruption lands inside it, and hoisted out of the scenario so
+ * main() can put it in the speech cache before the clock starts: synthesizing it
+ * live costs more than the interrupting clip's 5 s silent lead, which would make
+ * the scenario measure TTS latency instead of barge-in.
+ */
+const BARGE_IN_ANSWER =
+ 'The kitchen light is off, the hallway light is off, the thermostat is holding at twenty degrees, ' +
+ 'the front door is locked, and the garage is closed. Nothing else has changed since this morning.';
+
async function scenarioBargeIn() {
const { browser, page } = await launch(CLIPS.bargeUser.path);
try {
@@ -489,12 +500,7 @@ async function scenarioBargeIn() {
await bootPage(page);
await optIn(page);
// Speak a long enough answer that the user's interruption lands inside it.
- await page.evaluate(() => {
- window.homeVoice.loop._speak(
- 'The kitchen light is off, the hallway light is off, the thermostat is holding at twenty degrees, ' +
- 'the front door is locked, and the garage is closed. Nothing else has changed since this morning.',
- );
- });
+ await page.evaluate((line) => window.homeVoice.loop._speak(line), BARGE_IN_ANSWER);
// Wait for sound actually leaving the speaker, not merely for the state
// flip: _speak enters `speaking` before the synthesis request returns, so a
// failed TTS call would otherwise read as a silent, un-interruptible agent.
@@ -784,6 +790,31 @@ async function scenarioStateGallery() {
}
}
+/**
+ * Run one scenario, and run it again if a dev-server reload pulled the page out
+ * from under it.
+ *
+ * Concurrent agents edit this worktree while a run is in flight, and any source
+ * file they touch makes Vite reload every open page. That wipes the opt-in and
+ * the recorded events, so the scenario is not retryable in place: it has to
+ * start over, with the checks it already appended dropped, or a half-finished
+ * attempt would be reported alongside the real one. Only the navigation error is
+ * caught. A failing assertion is a failing assertion and is never retried.
+ */
+async function run(scenario) {
+ const mark = results.length;
+ for (let attempt = 0; ; attempt++) {
+ try {
+ return await scenario();
+ } catch (err) {
+ const reloaded = /Execution context was destroyed|Target closed|frame was detached/i.test(err?.message || '');
+ if (!reloaded || attempt >= 2) throw err;
+ results.length = mark;
+ console.log(`[retry] the dev server reloaded mid-scenario; starting it again (${attempt + 1}/2).`);
+ }
+ }
+}
+
// ── run ─────────────────────────────────────────────────────────────────────
async function main() {
@@ -794,19 +825,23 @@ async function main() {
}
await signIn();
await ensureClips();
+ // Synthesize the agent's interrupted answer once, before anything is timed,
+ // so the barge-in scenario is as fast on a machine that has never run this
+ // script as on one that has.
+ await cachedSpeech(BARGE_IN_ANSWER);
await warmUp();
const measured = {};
- await scenarioColdLoad();
- measured.happy = await scenarioHappyPath();
- measured.barge = await scenarioBargeIn();
- measured.selfTrigger = await scenarioSelfTrigger();
- await scenarioGuarded({ clip: CLIPS.ambientYeah, expectRedeemed: false, label: 'ambient yes' });
- await scenarioGuarded({ clip: CLIPS.confirmToken, expectRedeemed: true, label: 'the token' });
- measured.mute = await scenarioMute();
- await scenarioUnavailable();
- await scenarioPermissionDenied();
- await scenarioStateGallery();
+ await run(scenarioColdLoad);
+ measured.happy = await run(scenarioHappyPath);
+ measured.barge = await run(scenarioBargeIn);
+ measured.selfTrigger = await run(scenarioSelfTrigger);
+ await run(() => scenarioGuarded({ clip: CLIPS.ambientYeah, expectRedeemed: false, label: 'ambient yes' }));
+ await run(() => scenarioGuarded({ clip: CLIPS.confirmToken, expectRedeemed: true, label: 'the token' }));
+ measured.mute = await run(scenarioMute);
+ await run(scenarioUnavailable);
+ await run(scenarioPermissionDenied);
+ await run(scenarioStateGallery);
const failed = results.filter((r) => !r.pass);
writeFileSync(
diff --git a/scripts/home-live-tests.mjs b/scripts/home-live-tests.mjs
new file mode 100644
index 000000000..d108457d4
--- /dev/null
+++ b/scripts/home-live-tests.mjs
@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * The home lane's live tier, in one command.
+ *
+ * npm run test:home:live
+ *
+ * Nine test files in this lane assert against a real Home Assistant, and each
+ * of them used to carry its own paragraph of setup: a house to build, a flag to
+ * export, a key to invent. The result was that most of them skipped on most
+ * machines and nobody noticed, which is the same as not having them. This
+ * runner supplies everything they need and then runs them together.
+ *
+ * What it supplies, and why each one is needed:
+ *
+ * HOME_LIVE=1 lets tests/_helpers/home-instance.js build the
+ * shared house through scripts/home-test-instance.mjs.
+ * HOME_ALLOW_LOCAL_INSTANCE=1 the seam in api/_lib/home-url-guard.js. A Home
+ * Assistant you run yourself lands on loopback,
+ * and the reachability guard refuses loopback in
+ * production. The guard reads this at module
+ * load, which is why it is set here rather than
+ * inside a test.
+ * WALLET_ENCRYPTION_KEY encrypts the throwaway rows this run creates.
+ * JWT_SECRET signs the sessions the HTTP tiers mint.
+ *
+ * The two secrets are generated per run when the environment has none, exactly
+ * as playwright.home.config.js does: they are local only, they encrypt rows
+ * this run writes and deletes, and nothing production wrote can be read with
+ * them. A real value already in the environment always wins.
+ *
+ * The house outlives the run on purpose, so a second run costs no boot:
+ *
+ * node scripts/home-test-instance.mjs --down --name lane
+ */
+
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Every file in the lane that asserts against a real house. Derived, not
+ * curated: a file earns its place here by importing the shared harness helper,
+ * so a new live test cannot be added and then quietly left out of the suite.
+ */
+function liveTestFiles() {
+ const roots = ['tests', path.join('packages', 'home-bridge', 'tests'), path.join('packages', 'home-mcp', 'tests')];
+ const found = [];
+ for (const dir of roots) {
+ const abs = path.join(ROOT, dir);
+ if (!fs.existsSync(abs)) continue;
+ for (const name of fs.readdirSync(abs)) {
+ if (!name.endsWith('.test.js')) continue;
+ const rel = path.join(dir, name);
+ if (fs.readFileSync(path.join(ROOT, rel), 'utf8').includes('_helpers/home-instance.js')) found.push(rel);
+ }
+ }
+ return found.sort();
+}
+
+const files = liveTestFiles();
+if (!files.length) {
+ console.error('No live home tests found: nothing imports tests/_helpers/home-instance.js.');
+ process.exit(1);
+}
+
+const env = { ...process.env, HOME_LIVE: '1', HOME_ALLOW_LOCAL_INSTANCE: '1' };
+env.WALLET_ENCRYPTION_KEY ||= randomBytes(32).toString('hex');
+env.JWT_SECRET ||= randomBytes(32).toString('hex');
+
+// .env.local carries DATABASE_URL. The database tiers skip without it rather
+// than failing, so a machine that has no database still runs the bridge tier.
+const envFile = path.join(ROOT, '.env.local');
+const nodeArgs = fs.existsSync(envFile) ? [`--env-file=${envFile}`] : [];
+if (!nodeArgs.length) console.error('No .env.local: the database tiers will skip themselves.');
+
+const args = [
+ ...nodeArgs,
+ path.join(ROOT, 'node_modules', 'vitest', 'vitest.mjs'),
+ 'run',
+ // One worker. These files share one Home Assistant container and one
+ // database, and two forks racing to lock and unlock the same front door is
+ // the flakiness this lane refuses to ship.
+ '--maxWorkers=1',
+ ...files,
+ ...process.argv.slice(2),
+];
+
+console.error(`home live tier: ${files.length} files, one shared house\n`);
+const child = spawn(process.execPath, args, { cwd: ROOT, stdio: 'inherit', env });
+child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 1)));
diff --git a/tests/e2e/home-floorplan.spec.js b/tests/e2e/home-floorplan.spec.js
index 7955737f6..82ff61185 100644
--- a/tests/e2e/home-floorplan.spec.js
+++ b/tests/e2e/home-floorplan.spec.js
@@ -15,25 +15,69 @@ import { connectHome, homeInstance, openScene, resetHomes, signIn } from './home
test.describe.configure({ mode: 'serial' });
-/** The entity registry, straight from Home Assistant over its WebSocket API. */
-async function registry(instance, type = 'config/entity_registry/list') {
+/**
+ * One authenticated Home Assistant WebSocket, good for many messages.
+ *
+ * Journey 9e rewrites the house's whole area registry twice, and a socket per
+ * message would be dozens of connections and a slow, flaky test.
+ */
+async function haSession(instance) {
const socket = new WebSocket(`${instance.baseUrl.replace(/^http/, 'ws')}/api/websocket`);
+ const pending = new Map();
+ let nextId = 1;
+ let ready;
+
+ const open = new Promise((resolve, reject) => { ready = { resolve, reject }; });
+ const failAll = (err) => {
+ ready.reject(err);
+ for (const { reject } of pending.values()) reject(err);
+ pending.clear();
+ };
+ socket.onerror = () => failAll(new Error(`could not reach ${instance.baseUrl} over websocket`));
+ socket.onclose = () => failAll(new Error('home assistant closed the websocket'));
+ socket.onmessage = (event) => {
+ const msg = JSON.parse(event.data);
+ if (msg.type === 'auth_required') return socket.send(JSON.stringify({ type: 'auth', access_token: instance.token }));
+ if (msg.type === 'auth_ok') return ready.resolve();
+ if (msg.type === 'auth_invalid') return failAll(new Error('home assistant refused the access token'));
+ if (msg.type !== 'result') return;
+ const waiter = pending.get(msg.id);
+ if (!waiter) return;
+ pending.delete(msg.id);
+ // A failed result is returned rather than thrown: deleting an area that
+ // a device still pins can answer with an error that the caller decides
+ // how to treat.
+ waiter.resolve(msg.success ? msg.result : { error: msg.error || { message: 'failed' } });
+ };
+
+ const timer = setTimeout(() => failAll(new Error('home assistant did not authenticate in time')), 30_000);
+ await open;
+ clearTimeout(timer);
+
+ return {
+ send(message) {
+ const id = nextId += 1;
+ return new Promise((resolve, reject) => {
+ const to = setTimeout(() => { pending.delete(id); reject(new Error(`${message.type} timed out`)); }, 30_000);
+ pending.set(id, { resolve: (v) => { clearTimeout(to); resolve(v); }, reject });
+ socket.send(JSON.stringify({ ...message, id }));
+ });
+ },
+ close() {
+ socket.onclose = null;
+ socket.close();
+ },
+ };
+}
+
+/** One registry list, over a socket opened just for it. */
+async function registry(instance, type = 'config/entity_registry/list') {
+ const session = await haSession(instance);
try {
- return await new Promise((resolve, reject) => {
- const timer = setTimeout(() => reject(new Error(`${type} timed out`)), 20_000);
- socket.onerror = () => { clearTimeout(timer); reject(new Error('websocket failed')); };
- socket.onmessage = (event) => {
- const msg = JSON.parse(event.data);
- if (msg.type === 'auth_required') return socket.send(JSON.stringify({ type: 'auth', access_token: instance.token }));
- if (msg.type === 'auth_ok') return socket.send(JSON.stringify({ id: 1, type }));
- if (msg.type === 'result') {
- clearTimeout(timer);
- resolve(msg.success ? msg.result : []);
- }
- };
- });
+ const result = await session.send({ type });
+ return Array.isArray(result) ? result : [];
} finally {
- socket.close();
+ session.close();
}
}
@@ -43,6 +87,27 @@ async function areaOf(instance, entityId) {
return entries.find((e) => e.entity_id === entityId)?.area_id ?? null;
}
+/**
+ * Every console error and warning the page produced, so a journey can fail on
+ * one. A feature that works while the console screams is not finished.
+ *
+ * Page errors (an uncaught throw) count too. The filter drops noise the product
+ * did not cause: a favicon the dev server does not serve, and the WebGL warnings
+ * a software renderer emits inside a headless container.
+ */
+function watchConsole(page) {
+ const noise = /favicon|WebGL|SwiftShader|GroupMarkerNotSet|Automatic fallback to software|source map|Download the React DevTools/i;
+ const found = [];
+ page.on('console', (msg) => {
+ if (msg.type() !== 'error' && msg.type() !== 'warning') return;
+ const text = msg.text();
+ if (noise.test(text)) return;
+ found.push(`${msg.type()}: ${text}`);
+ });
+ page.on('pageerror', (err) => found.push(`pageerror: ${err.message}`));
+ return found;
+}
+
async function openPlan(page) {
const plan = page.getByRole('button', { name: /Draw where the rooms are/i });
await expect(plan).toBeVisible({ timeout: 60_000 });
@@ -51,6 +116,7 @@ async function openPlan(page) {
}
test('journey 9: a floorplan is drawn, saved, and still there after a reload', async ({ page }) => {
+ const problems = watchConsole(page);
await signIn(page, 'owner');
await resetHomes(page);
await connectHome(page, { label: 'Journey nine' });
@@ -84,9 +150,12 @@ test('journey 9: a floorplan is drawn, saved, and still there after a reload', a
await openPlan(page);
await expect(page.locator('.hm-plan-room').filter({ hasText: roomName })).toBeVisible({ timeout: 60_000 });
await expect(page.locator('.hm-plan-tray-room').filter({ hasText: roomName })).toHaveCount(0);
+
+ expect(problems, `console output during journey 9:\n${problems.join('\n')}`).toEqual([]);
});
test('journey 9b: undo takes a placement back, and redo puts it again', async ({ page }) => {
+ const problems = watchConsole(page);
await signIn(page, 'owner');
await openScene(page);
await openPlan(page);
@@ -104,10 +173,13 @@ test('journey 9b: undo takes a placement back, and redo puts it again', async ({
await page.getByRole('button', { name: /^Redo$/ }).click();
await expect(page.locator('.hm-plan-room').filter({ hasText: name })).toHaveCount(1);
+
+ expect(problems, `console output during journey 9b:\n${problems.join('\n')}`).toEqual([]);
});
test('journey 9c: filing a device from the tray changes the area in Home Assistant itself', async ({ page }) => {
const instance = homeInstance();
+ const problems = watchConsole(page);
await signIn(page, 'owner');
await openScene(page);
await openPlan(page);
@@ -131,9 +203,12 @@ test('journey 9c: filing a device from the tray changes the area in Home Assista
// Home Assistant's own registry, not our tray. This is the assertion the
// whole feature rests on.
await expect.poll(() => areaOf(instance, label), { timeout: 30_000 }).not.toBeNull();
+
+ expect(problems, `console output during journey 9c:\n${problems.join('\n')}`).toEqual([]);
});
test('journey 9d: resetting the plan returns the house to its default arrangement', async ({ page }) => {
+ const problems = watchConsole(page);
await signIn(page, 'owner');
await openScene(page);
await openPlan(page);
@@ -149,4 +224,189 @@ test('journey 9d: resetting the plan returns the house to its default arrangemen
await page.reload();
await openPlan(page);
await expect(page.locator('.hm-plan-room')).toHaveCount(0);
+
+ expect(problems, `console output during journey 9d:\n${problems.join('\n')}`).toEqual([]);
+});
+
+/**
+ * Journey 9e: the house nobody ever organised.
+ *
+ * This is the most common real Home Assistant we see: devices everywhere and
+ * not one area, so every room-shaped surface has nothing to draw. The order
+ * this journey belongs to sets the bar as a complete floorplan in under five
+ * minutes without leaving the page, so the journey strips the house down to
+ * zero areas, walks the tray-first flow, and times it.
+ *
+ * It puts the house back afterwards. Home Assistant derives an area id from its
+ * name, so recreating "Kitchen" restores the id every device was filed under and
+ * the restore is exact rather than approximate.
+ */
+test('journey 9e: a house with no areas at all reaches a full floorplan from the tray', async ({ page }) => {
+ const instance = homeInstance();
+ const problems = watchConsole(page);
+ const session = await haSession(instance);
+
+ // What the house looks like before we take it apart.
+ const originalAreas = await session.send({ type: 'config/area_registry/list' });
+ const devices = await session.send({ type: 'config/device_registry/list' });
+ const entities = await session.send({ type: 'config/entity_registry/list' });
+ const deviceAreas = devices.filter((d) => d.area_id).map((d) => ({ id: d.id, areaId: d.area_id }));
+ const entityAreas = entities.filter((e) => e.area_id).map((e) => ({ id: e.entity_id, areaId: e.area_id }));
+ expect(originalAreas.length).toBeGreaterThan(0);
+
+ try {
+ for (const area of originalAreas) {
+ await session.send({ type: 'config/area_registry/delete', area_id: area.area_id });
+ }
+ expect(await session.send({ type: 'config/area_registry/list' })).toHaveLength(0);
+
+ await signIn(page, 'owner');
+ await openScene(page);
+ await openPlan(page);
+
+ // The clock starts where the user starts: looking at a house with no
+ // rooms in it.
+ const start = Date.now();
+ const startPanel = page.locator('.hm-plan-tray-start');
+ await expect(startPanel).toBeVisible({ timeout: 60_000 });
+ await expect(startPanel).toContainText(/Nothing in this home is in a room yet/i);
+
+ // Room one, from the tray's own invitation.
+ await startPanel.getByRole('button', { name: /^Make a room$/ }).click();
+ await page.locator('.hm-plan-naming-input').fill('Plan kitchen');
+ await page.getByRole('button', { name: /^Make this room$/ }).click();
+ await expect(page.locator('.hm-plan-room').filter({ hasText: 'Plan kitchen' })).toBeVisible({ timeout: 60_000 });
+
+ // Room two, from the toolbar, because a floorplan is not one room.
+ await page.getByRole('button', { name: /^New room$/ }).click();
+ await page.locator('.hm-plan-naming-input').fill('Plan hallway');
+ await page.getByRole('button', { name: /^Make this room$/ }).click();
+ await expect(page.locator('.hm-plan-room').filter({ hasText: 'Plan hallway' })).toBeVisible({ timeout: 60_000 });
+
+ // And a device filed into a room that did not exist a minute ago.
+ const loose = page.locator('.hm-plan-tray-entity').first();
+ await expect(loose).toBeVisible({ timeout: 30_000 });
+ const filed = (await loose.getAttribute('title')) || '';
+ await loose.getByRole('button', { name: /^File$/ }).click();
+ await page.locator('.hm-plan-filemenu-item').filter({ hasText: 'Plan kitchen' }).click();
+ await expect(page.getByText(/was written to your Home Assistant/i)).toBeVisible({ timeout: 30_000 });
+
+ await page.getByRole('button', { name: /^Save floorplan$/ }).click();
+ await expect(page.getByText(/Floorplan saved/i)).toBeVisible({ timeout: 30_000 });
+ const seconds = Math.round((Date.now() - start) / 1000);
+ console.log(`[journey 9e] zero areas to a saved two-room floorplan with a filed device: ${seconds}s`);
+ expect(seconds).toBeLessThan(300);
+
+ // Home Assistant's own registries, not our picture of them.
+ const madeAreas = await session.send({ type: 'config/area_registry/list' });
+ const names = madeAreas.map((a) => a.name);
+ expect(names).toContain('Plan kitchen');
+ expect(names).toContain('Plan hallway');
+ const kitchenId = madeAreas.find((a) => a.name === 'Plan kitchen')?.area_id;
+ await expect.poll(() => areaOf(instance, filed), { timeout: 30_000 }).toBe(kitchenId);
+
+ // It survives a reload, so the plan really persisted rather than only
+ // looking right in the editor.
+ await page.reload();
+ await openPlan(page);
+ await expect(page.locator('.hm-plan-room').filter({ hasText: 'Plan kitchen' })).toBeVisible({ timeout: 60_000 });
+ } finally {
+ // Put the house back exactly as it was, whatever happened above.
+ const leftover = await session.send({ type: 'config/area_registry/list' });
+ for (const area of leftover) {
+ await session.send({ type: 'config/area_registry/delete', area_id: area.area_id }).catch(() => {});
+ }
+ for (const area of originalAreas) {
+ await session.send({
+ type: 'config/area_registry/create',
+ name: area.name,
+ ...(area.floor_id ? { floor_id: area.floor_id } : {}),
+ }).catch(() => {});
+ }
+ for (const device of deviceAreas) {
+ await session.send({ type: 'config/device_registry/update', device_id: device.id, area_id: device.areaId }).catch(() => {});
+ }
+ for (const entity of entityAreas) {
+ await session.send({ type: 'config/entity_registry/update', entity_id: entity.id, area_id: entity.areaId }).catch(() => {});
+ }
+ session.close();
+ }
+
+ expect(problems, `console output during journey 9e:\n${problems.join('\n')}`).toEqual([]);
+});
+
+/**
+ * Journey 9f: two people in the same house, drawing at once.
+ *
+ * Optimistic concurrency is only worth having if the losing save is offered a
+ * real choice rather than a silent overwrite, so this drives two browser
+ * contexts against one home and proves the second save is refused, told who
+ * won, and able to land its own work anyway.
+ */
+test('journey 9f: two browsers editing one home get the merge choice, and neither edit vanishes', async ({ browser }) => {
+ const first = await browser.newContext();
+ const second = await browser.newContext();
+ const alice = await first.newPage();
+ const bob = await second.newPage();
+ const aliceProblems = watchConsole(alice);
+ const bobProblems = watchConsole(bob);
+
+ try {
+ for (const page of [alice, bob]) {
+ await signIn(page, 'owner');
+ await openScene(page);
+ await openPlan(page);
+ }
+
+ // Both loaded the same version. Whatever each places, the other has not
+ // seen it.
+ const aliceRoom = alice.locator('.hm-plan-tray-room').first();
+ const bobRoom = bob.locator('.hm-plan-tray-room').first();
+ await expect(aliceRoom).toBeVisible({ timeout: 30_000 });
+ await expect(bobRoom).toBeVisible({ timeout: 30_000 });
+ const aliceName = (await aliceRoom.textContent())?.trim();
+ const bobName = (await bobRoom.textContent())?.trim();
+
+ await aliceRoom.click();
+ await alice.getByRole('button', { name: /^Save floorplan$/ }).click();
+ await expect(alice.getByText(/Floorplan saved/i)).toBeVisible({ timeout: 30_000 });
+
+ // Bob is now one version behind and does not know it.
+ await bobRoom.click();
+ await bob.getByRole('button', { name: /^Save floorplan$/ }).click();
+
+ // State 5: refused, explained, and given both ways out.
+ const panel = bob.locator('.hm-plan-conflict');
+ await expect(panel).toBeVisible({ timeout: 30_000 });
+ await expect(panel).toContainText(/Someone else changed this floorplan/i);
+ await expect(panel.getByRole('button', { name: /^Keep mine$/ })).toBeVisible();
+ await expect(panel.getByRole('button', { name: /^Take theirs$/ })).toBeVisible();
+
+ // Taking theirs loads Alice's work rather than throwing Bob's away in
+ // silence, and says so.
+ await panel.getByRole('button', { name: /^Take theirs$/ }).click();
+ await expect(bob.getByText(/Loaded the other version/i)).toBeVisible({ timeout: 30_000 });
+ await expect(bob.locator('.hm-plan-room').filter({ hasText: aliceName })).toBeVisible({ timeout: 30_000 });
+
+ // And Bob's own edit is still his to make: he redraws it on top of the
+ // version that won and it lands.
+ const again = bob.locator('.hm-plan-tray-room').filter({ hasText: bobName }).first();
+ if (await again.count()) {
+ await again.click();
+ await bob.getByRole('button', { name: /^Save floorplan$/ }).click();
+ await expect(bob.getByText(/Floorplan saved/i)).toBeVisible({ timeout: 30_000 });
+
+ // Alice reloads and sees both rooms: nothing was lost, by either of them.
+ await alice.reload();
+ await openPlan(alice);
+ await expect(alice.locator('.hm-plan-room').filter({ hasText: aliceName })).toBeVisible({ timeout: 60_000 });
+ await expect(alice.locator('.hm-plan-room').filter({ hasText: bobName })).toBeVisible({ timeout: 30_000 });
+ }
+
+ expect(aliceProblems, `console output in the first browser:\n${aliceProblems.join('\n')}`).toEqual([]);
+ expect(bobProblems, `console output in the second browser:\n${bobProblems.join('\n')}`).toEqual([]);
+ } finally {
+ await first.close();
+ await second.close();
+ }
});
diff --git a/tests/e2e/home-support.js b/tests/e2e/home-support.js
index 9f205dfa8..10b7f6058 100644
--- a/tests/e2e/home-support.js
+++ b/tests/e2e/home-support.js
@@ -119,7 +119,17 @@ export async function connectHome(page, { label = 'The lane house' } = {}) {
const scoped = lane && lane !== 'e2e' ? `${label} ${lane}` : label;
await page.goto('/smart-home', { waitUntil: 'domcontentloaded' });
- await expect(page.locator('#hm-url')).toBeVisible({ timeout: 60_000 });
+
+ // An account with no houses opens on the form itself. One that already has a
+ // house, which since resetHomes stopped deleting other lanes' houses is the
+ // normal case here, opens on the list instead, and the form is behind
+ // "Connect another". Waiting for the form without that click is how every
+ // home journey started failing at connect the moment two lanes ran at once.
+ const url = page.locator('#hm-url');
+ if (!(await url.isVisible().catch(() => false))) {
+ await page.getByRole('button', { name: 'Connect another' }).click();
+ }
+ await expect(url).toBeVisible({ timeout: 60_000 });
await page.fill('#hm-label', scoped);
await page.fill('#hm-url', home.baseUrl);
diff --git a/tests/home-confirm-endpoint.test.js b/tests/home-confirm-endpoint.test.js
new file mode 100644
index 000000000..855fb7c2f
--- /dev/null
+++ b/tests/home-confirm-endpoint.test.js
@@ -0,0 +1,413 @@
+// The confirmation protocol over real HTTP, end to end.
+//
+// tests/home-tools.test.js proves the gate at the module boundary and
+// tests/home-confirmation.test.js proves the record. Both call JavaScript
+// functions. This file proves the same protocol the way an attacker meets it:
+// over the wire, through the real MCP endpoint and the real confirm endpoint,
+// with real credentials, against a real Home Assistant holding a real lock.
+//
+// That distinction is the reason this file exists. `claimConfirmation()` being
+// correct says nothing about whether `POST /api/home/:id/confirm` refuses a
+// bearer token, because the refusal lives in the handler and not in the record.
+// Every assertion below reads its verdict off an HTTP status line, and every
+// assertion about a door reads the door's state back out of Home Assistant.
+//
+// Live only, because a mocked lock cannot stay locked:
+//
+// HOME_LIVE=1 HOME_ALLOW_LOCAL_INSTANCE=1 DATABASE_URL=... JWT_SECRET=... \
+// npx vitest run tests/home-confirm-endpoint.test.js
+//
+// `HOME_ALLOW_LOCAL_INSTANCE=1` is the seam documented in
+// api/_lib/home-url-guard.js: a Home Assistant you run yourself lands on
+// loopback, and the reachability guard refuses loopback in production.
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import http from 'node:http';
+
+import { acquireHomeInstance, liveHomeAvailable, pickEntity, readState, setState, waitForState } from './_helpers/home-instance.js';
+
+const live = describe.skipIf(!liveHomeAvailable() || !process.env.DATABASE_URL || !process.env.JWT_SECRET);
+
+/** The session cookie the platform actually sets. */
+const SESSION_COOKIE = '__Host-sid';
+
+live('the confirmation protocol over HTTP', () => {
+ let sql;
+ let instance;
+ let confirmServer;
+ let mcpServer;
+ let owner;
+ let stranger;
+ let home;
+ let otherHome;
+ let lockId;
+ let ownerCookie;
+ let strangerCookie;
+ let ownerBearer;
+
+ beforeAll(async () => {
+ instance = await acquireHomeInstance();
+ ({ sql } = await import('../api/_lib/db.js'));
+
+ const { createConnection } = await import('../api/_lib/home/store.js');
+ const { createSession, mintAccessToken } = await import('../api/_lib/auth.js');
+ const confirmHandler = (await import('../api/home/[id]/confirm.js')).default;
+ const mcpHandler = (await import('../api/mcp.js')).default;
+
+ const stamp = Date.now();
+ [owner] = await sql`insert into users (email) values (${`home-http-owner-${stamp}@qa.three.ws`}) returning id`;
+ [stranger] = await sql`insert into users (email) values (${`home-http-stranger-${stamp}@qa.three.ws`}) returning id`;
+
+ home = await createConnection({
+ userId: owner.id,
+ label: 'HTTP House',
+ baseUrl: instance.baseUrl,
+ token: instance.token,
+ status: 'connected',
+ });
+ // A second home the same owner holds, so the cross-home replay below is
+ // refused by the binding and not merely by the membership check.
+ //
+ // It has to reach the instance by a DIFFERENT base URL, because
+ // `createConnection` upserts on `(user_id, base_url)`: connecting the same
+ // address twice updates one row rather than making two, and the two ids
+ // would silently be the same id. `localhost` and `127.0.0.1` are both real
+ // routes to this container and the normalizer keeps them distinct.
+ otherHome = await createConnection({
+ userId: owner.id,
+ label: 'HTTP Second House',
+ baseUrl: instance.baseUrl.replace('127.0.0.1', 'localhost'),
+ token: instance.token,
+ status: 'connected',
+ });
+ expect(otherHome.id, 'the two homes must be two rows').not.toBe(home.id);
+
+ ownerCookie = `${SESSION_COOKIE}=${await createSession({ userId: owner.id, recordActivity: false })}`;
+ strangerCookie = `${SESSION_COOKIE}=${await createSession({ userId: stranger.id, recordActivity: false })}`;
+ // A real OAuth access token carrying the strongest home scope there is.
+ // The point of the bearer assertions below is that even THIS cannot
+ // approve anything.
+ ownerBearer = await mintAccessToken({
+ userId: owner.id,
+ clientId: 'home-confirm-endpoint-test',
+ scope: 'home:read home:act',
+ });
+
+ confirmServer = await listen(confirmHandler);
+ mcpServer = await listen(mcpHandler);
+
+ lockId = await pickEntity(instance, 'lock');
+ await setState(instance, 'lock', 'lock', lockId);
+ await waitForState(instance, lockId, 'locked');
+ }, 600_000);
+
+ afterAll(async () => {
+ if (instance && lockId) await setState(instance, 'lock', 'lock', lockId).catch(() => {});
+ const { closeAll } = await import('../api/_lib/home/runtime.js');
+ closeAll();
+ await close(confirmServer);
+ await close(mcpServer);
+ if (sql && owner) await sql`delete from users where id in (${owner.id}, ${stranger.id})`;
+ });
+
+ // ── The MCP client's half ────────────────────────────────────────────────
+
+ /**
+ * Speak real JSON-RPC to the real MCP endpoint, the way any external agent
+ * would. Nothing here is a shortcut into the handler: it is a bearer token on
+ * an HTTP request, which is exactly the principal this protocol is defending
+ * the door against.
+ */
+ async function mcp(method, params, { bearer = ownerBearer } = {}) {
+ const res = await fetch(`${mcpServer.url}/api/mcp`, {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ accept: 'application/json, text/event-stream',
+ ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+ },
+ body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+ });
+ return { status: res.status, body: await res.json().catch(() => null) };
+ }
+
+ it('publishes home_call to a real MCP client with no confirmation field in its schema', async () => {
+ const listed = await mcp('tools/list', {});
+ expect(listed.status).toBe(200);
+ const tools = listed.body?.result?.tools || [];
+ const homeCall = tools.find((t) => t.name === 'home_call');
+ expect(homeCall, 'home_call must be published to an MCP client').toBeTruthy();
+
+ // The mechanism, asserted over the wire rather than over the source: a
+ // model cannot set a field that is not in the schema it was handed.
+ expect(JSON.stringify(homeCall.inputSchema)).not.toMatch(/confirm/i);
+ expect(homeCall.annotations).toMatchObject({
+ readOnlyHint: false,
+ destructiveHint: true,
+ idempotentHint: false,
+ openWorldHint: true,
+ });
+ }, 60_000);
+
+ it('answers an MCP unlock with pending_confirmation while the real lock stays locked', async () => {
+ await setState(instance, 'lock', 'lock', lockId);
+ await waitForState(instance, lockId, 'locked');
+
+ const called = await mcp('tools/call', {
+ name: 'home_call',
+ arguments: { home_id: home.id, domain: 'lock', service: 'unlock', data: { entity_id: lockId } },
+ });
+
+ expect(called.status).toBe(200);
+ const result = called.body?.result;
+ // Neither an error nor a success. A model that reads this as a failure
+ // goes looking for another way to open the door.
+ expect(result.isError).toBeFalsy();
+ expect(result.structuredContent.status).toBe('pending_confirmation');
+ expect(result.structuredContent.confirmation.entity_ids).toEqual([lockId]);
+
+ // The only assertion that means anything: the door.
+ expect(await readState(instance, lockId)).toBe('locked');
+ }, 60_000);
+
+ // ── The human's half ─────────────────────────────────────────────────────
+
+ function confirmUrl(homeId) {
+ return `${confirmServer.url}/api/home/${homeId}/confirm`;
+ }
+
+ async function csrfFor(userId) {
+ const { issueCsrf } = await import('../api/_lib/csrf.js');
+ return (await issueCsrf(userId)).token;
+ }
+
+ /** Mint a pending confirmation the way an agent would, over MCP. */
+ async function pendingUnlock({ homeId = home.id } = {}) {
+ const called = await mcp('tools/call', {
+ name: 'home_call',
+ arguments: { home_id: homeId, domain: 'lock', service: 'unlock', data: { entity_id: lockId } },
+ });
+ const confirmation = called.body?.result?.structuredContent?.confirmation;
+ expect(confirmation?.id, 'the agent call should have minted a confirmation').toBeTruthy();
+ return confirmation;
+ }
+
+ async function post(homeId, body, { cookie = ownerCookie, csrf, bearer } = {}) {
+ const res = await fetch(confirmUrl(homeId), {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ ...(cookie ? { cookie } : {}),
+ ...(csrf ? { 'x-csrf-token': csrf } : {}),
+ ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+ },
+ body: JSON.stringify(body),
+ });
+ return { status: res.status, body: await res.json().catch(() => null) };
+ }
+
+ it('refuses a bearer token holding home:act, before it authenticates anything', async () => {
+ const confirmation = await pendingUnlock();
+ // No cookie at all: the pure machine principal.
+ const res = await post(home.id, { confirmation_id: confirmation.id }, { cookie: null, bearer: ownerBearer });
+ expect(res.status).toBe(403);
+ expect(res.body.error).toBe('confirmation_requires_session');
+ expect(await readState(instance, lockId)).toBe('locked');
+
+ // And with a valid session ALSO present, so the refusal cannot be read as
+ // "it just was not signed in". A bearer anywhere on the request is fatal.
+ const both = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id), bearer: ownerBearer });
+ expect(both.status).toBe(403);
+ expect(both.body.error).toBe('confirmation_requires_session');
+ expect(await readState(instance, lockId)).toBe('locked');
+ }, 60_000);
+
+ it('refuses a session with no CSRF token, which is what a cross-site page can send', async () => {
+ const confirmation = await pendingUnlock();
+ const res = await post(home.id, { confirmation_id: confirmation.id });
+ expect(res.status).toBe(403);
+ expect(res.body.error).toBe('csrf_missing');
+ expect(await readState(instance, lockId)).toBe('locked');
+ }, 60_000);
+
+ it('refuses a CSRF token minted for somebody else', async () => {
+ const confirmation = await pendingUnlock();
+ const res = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(stranger.id) });
+ expect(res.status).toBe(403);
+ expect(res.body.error).toBe('csrf_invalid');
+ expect(await readState(instance, lockId)).toBe('locked');
+ }, 60_000);
+
+ it('unlocks the real door for a signed-in person, and only then', async () => {
+ await setState(instance, 'lock', 'lock', lockId);
+ await waitForState(instance, lockId, 'locked');
+
+ const confirmation = await pendingUnlock();
+ expect(await readState(instance, lockId)).toBe('locked');
+
+ const res = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
+ expect(res.status).toBe(200);
+ expect(res.body.ok).toBe(true);
+ expect(res.body.ran).toBe('lock.unlock');
+ expect(res.body.entity_ids).toEqual([lockId]);
+
+ await waitForState(instance, lockId, 'unlocked');
+ expect(await readState(instance, lockId)).toBe('unlocked');
+
+ // The row an operator reads after an incident.
+ const [row] = await sql`
+ select guarded, confirmed_by, outcome from home_action_log
+ where home_id = ${home.id} and action = 'lock.unlock' and outcome = 'ok'
+ order by created_at desc limit 1
+ `;
+ expect(row.guarded).toBe(true);
+ expect(row.confirmed_by).toBe(owner.id);
+ }, 90_000);
+
+ it('refuses the replay of a confirmation that already ran', async () => {
+ await setState(instance, 'lock', 'lock', lockId);
+ await waitForState(instance, lockId, 'locked');
+
+ const confirmation = await pendingUnlock();
+ const first = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
+ expect(first.status).toBe(200);
+ await waitForState(instance, lockId, 'unlocked');
+
+ // Lock it again, so a successful replay would be visible as an unlock
+ // rather than hiding behind the state the first redemption left.
+ await setState(instance, 'lock', 'lock', lockId);
+ await waitForState(instance, lockId, 'locked');
+
+ const replay = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
+ expect(replay.status).toBe(410);
+ expect(replay.body.error).toBe('confirmation_spent');
+ expect(await readState(instance, lockId)).toBe('locked');
+ }, 120_000);
+
+ it('refuses a confirmation whose ninety seconds ran out', async () => {
+ const confirmation = await pendingUnlock();
+ // Age the row rather than waiting ninety-one seconds in a test suite. The
+ // expiry is a column comparison against now(), so moving the column is the
+ // same event as time passing, and it is the row the handler reads.
+ await sql`update home_confirmations set expires_at = now() - interval '1 second' where id = ${confirmation.id}`;
+
+ const res = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
+ expect(res.status).toBe(410);
+ expect(res.body.error).toBe('confirmation_expired');
+ expect(await readState(instance, lockId)).toBe('locked');
+
+ // An expiry is an event, not silence: somebody asked to open a door and
+ // nobody answered.
+ const [row] = await sql`
+ select detail from home_action_log
+ where home_id = ${home.id} and detail->>'confirmation_id' = ${confirmation.id}
+ and detail->>'reason' = 'confirmation_expired' limit 1
+ `;
+ expect(row, 'an unanswered confirmation must earn a log row').toBeTruthy();
+ }, 60_000);
+
+ it('tells a stranger nothing, and lets them redeem nothing', async () => {
+ const confirmation = await pendingUnlock();
+ const res = await post(home.id, { confirmation_id: confirmation.id }, { cookie: strangerCookie, csrf: await csrfFor(stranger.id) });
+ // 404, not 403: a stranger must not learn that a home id is real.
+ expect(res.status).toBe(404);
+ expect(res.body.error).toBe('not_found');
+ expect(await readState(instance, lockId)).toBe('locked');
+ }, 60_000);
+
+ it('refuses a confirmation redeemed against a different home the same owner holds', async () => {
+ const confirmation = await pendingUnlock();
+ const res = await post(otherHome.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
+ expect(res.status).toBe(404);
+ expect(res.body.error).toBe('confirmation_not_found');
+ expect(await readState(instance, lockId)).toBe('locked');
+ }, 60_000);
+
+ it('ignores everything in the body except the id, so nothing can be steered', async () => {
+ await setState(instance, 'lock', 'lock', lockId);
+ await waitForState(instance, lockId, 'locked');
+
+ // A caller re-sending the action alongside the ticket, aimed at a different
+ // lock and a different service. The handler reads none of it.
+ const otherLock = (await locksOtherThan(instance, lockId))[0];
+ expect(otherLock, 'the seeded house should carry more than one lock').toBeTruthy();
+ // Lock it first: the demo integration does not start every lock locked, and
+ // an assertion that a door "stayed" locked proves nothing if it was open
+ // the whole time.
+ await setState(instance, 'lock', 'lock', otherLock);
+ await waitForState(instance, otherLock, 'locked');
+
+ const confirmation = await pendingUnlock();
+ const res = await post(
+ home.id,
+ {
+ confirmation_id: confirmation.id,
+ domain: 'lock',
+ service: 'unlock',
+ entity_id: otherLock,
+ data: { entity_id: otherLock },
+ confirmed: true,
+ },
+ { csrf: await csrfFor(owner.id) },
+ );
+
+ expect(res.status).toBe(200);
+ // What ran is what was frozen at mint time, not what the body asked for.
+ expect(res.body.entity_ids).toEqual([lockId]);
+ await waitForState(instance, lockId, 'unlocked');
+ expect(await readState(instance, otherLock)).toBe('locked');
+ }, 120_000);
+
+ it('refuses an unauthenticated caller outright', async () => {
+ const res = await post(home.id, { confirmation_id: crypto.randomUUID() }, { cookie: null });
+ expect(res.status).toBe(401);
+ expect(res.body.error).toBe('unauthorized');
+ }, 60_000);
+
+ it('lists what is waiting so a chat card that lost its state can recover it', async () => {
+ const confirmation = await pendingUnlock();
+ const res = await fetch(confirmUrl(home.id), { headers: { cookie: ownerCookie } });
+ expect(res.status).toBe(200);
+ const body = await res.json();
+ expect(body.pending.map((p) => p.id)).toContain(confirmation.id);
+ // A summary a person can act on, naming the entity rather than the call.
+ expect(body.pending.find((p) => p.id === confirmation.id).summary).toMatch(/unlock/i);
+ }, 60_000);
+});
+
+// ── Harness ──────────────────────────────────────────────────────────────────
+
+/**
+ * Bind one API handler to a real port. The handlers are plain
+ * `(req, res)` functions, so this is the same shape `server/index.mjs` gives
+ * them in production, minus the route table.
+ */
+async function listen(handler) {
+ const server = http.createServer((req, res) => {
+ // `wrap` reads `req.query` the way the filesystem router populates it.
+ const url = new URL(req.url, 'http://127.0.0.1');
+ req.query = Object.fromEntries(url.searchParams);
+ const parts = url.pathname.split('/').filter(Boolean);
+ if (parts[0] === 'api' && parts[1] === 'home' && parts[3] === 'confirm') req.query.id = parts[2];
+ Promise.resolve(handler(req, res)).catch(() => {
+ if (!res.headersSent) res.writeHead(500).end('{}');
+ });
+ });
+ await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+ return { server, url: `http://127.0.0.1:${server.address().port}` };
+}
+
+function close(handle) {
+ if (!handle) return Promise.resolve();
+ return new Promise((resolve) => handle.server.close(resolve));
+}
+
+/** Every lock in the seeded house that is not the one under test. */
+async function locksOtherThan(instance, lockId) {
+ const res = await fetch(`${instance.baseUrl}/api/states`, {
+ headers: { authorization: `Bearer ${instance.token}` },
+ });
+ const states = await res.json();
+ return states.map((s) => s.entity_id).filter((id) => id.startsWith('lock.') && id !== lockId);
+}
diff --git a/tests/home-layout.test.js b/tests/home-layout.test.js
index fb86a77da..87cb87cc9 100644
--- a/tests/home-layout.test.js
+++ b/tests/home-layout.test.js
@@ -5,12 +5,16 @@
// real Home Assistant because the whole point of the area write-back is that it
// changes the user's own registry rather than our picture of it.
//
-// HOME_ASSISTANT_URL=... HOME_ASSISTANT_TOKEN=... npx vitest run tests/home-layout.test.js
+// HOME_LIVE=1 DATABASE_URL=... npx vitest run tests/home-layout.test.js
//
-// An instance is one command: node scripts/home-test-instance.mjs --up --onboard --seed
+// HOME_LIVE=1 builds the house through the lane's one harness
+// (scripts/home-test-instance.mjs). Set HOME_ASSISTANT_URL and
+// HOME_ASSISTANT_TOKEN instead to point it at a house you already have.
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { acquireHomeInstance, liveHomeAvailable } from './_helpers/home-instance.js';
+
import {
LayoutInvalid,
LIMITS,
@@ -115,11 +119,22 @@ describe('reconciling a layout against a live house', () => {
const hasDb = Boolean(process.env.DATABASE_URL);
const hasKey = Boolean(process.env.WALLET_ENCRYPTION_KEY || process.env.JWT_SECRET);
-const haUrl = process.env.HOME_ASSISTANT_URL;
-const haToken = process.env.HOME_ASSISTANT_TOKEN;
const liveDb = describe.skipIf(!hasDb || !hasKey);
-const liveHome = describe.skipIf(!hasDb || !hasKey || !haUrl || !haToken);
+const liveHome = describe.skipIf(!hasDb || !hasKey || !liveHomeAvailable());
+
+// The house, when there is one. The file-level hook runs before any suite's own
+// beforeAll, so the DB-only tier below files its row against the real instance
+// when the lane has one and against an unroutable placeholder when it does not.
+let haUrl;
+let haToken;
+
+beforeAll(async () => {
+ if (!liveHomeAvailable()) return;
+ const instance = await acquireHomeInstance();
+ haUrl = instance.baseUrl;
+ haToken = instance.token;
+}, 600_000);
const SYNTHETIC_TOKEN = `synthetic.home.assistant.token.${'a'.repeat(64)}`;
@@ -305,4 +320,37 @@ liveHome('the area write-back, against a real Home Assistant', () => {
it('refuses something that is not an entity id at all', async () => {
await expect(bridge.assignEntityArea('not-an-entity', areaId)).rejects.toThrow(/not an entity id/);
});
+
+ // Making a room is the way out of the house that has no areas at all, which
+ // is the most common real house we see. Without it the tray has nowhere to
+ // file anything to and the only advice we can give is "go and use Home
+ // Assistant's settings first", which loses the person.
+ it('makes a new room, and Home Assistant has it', async () => {
+ const name = `Plan test ${Date.now().toString(36)}`;
+ const area = await bridge.createArea(name);
+ expect(area.created).toBe(true);
+ expect(area.id).toBeTruthy();
+
+ // Home Assistant's own area registry, not our cache of it.
+ const fresh = await bridge.refreshRegistries();
+ expect((bridge.registries.areas || []).some((a) => a.area_id === area.id)).toBe(true);
+ // And the graph the scene renders carries it, so it is a placeable room
+ // the moment it exists rather than after a reconnect.
+ expect(fresh.rooms.some((r) => r.id === area.id)).toBe(true);
+
+ // A second call with the same name is not an error: the room they asked
+ // for is there, which is what they wanted.
+ const again = await bridge.createArea(name);
+ expect(again.created).toBe(false);
+ expect(again.id).toBe(area.id);
+
+ // A device can be filed into a room that did not exist a moment ago.
+ await bridge.assignEntityArea(unfiled, area.id);
+ const entry = (bridge.registries.entities || []).find((e) => e.entity_id === unfiled);
+ expect(entry.area_id).toBe(area.id);
+ }, 60_000);
+
+ it('refuses a nameless room rather than making an unnamed one', async () => {
+ await expect(bridge.createArea(' ')).rejects.toThrow(/needs a name/i);
+ });
});
diff --git a/tests/home-runtime-live.test.js b/tests/home-runtime-live.test.js
index 4e3abb131..a747a9fb7 100644
--- a/tests/home-runtime-live.test.js
+++ b/tests/home-runtime-live.test.js
@@ -7,25 +7,39 @@
// rides the first WebSocket instead of opening another one against somebody's
// instance. That needs a real socket and a real house, so it lives here.
//
-// Self-skipping. Point it at any instance:
+// Self-skipping, and it builds its own house. The lane has ONE way to get a
+// real Home Assistant, so this file asks for it rather than describing it:
//
-// node scripts/home-test-instance.mjs --up --onboard --seed --json
-// HOME_ASSISTANT_URL=http://127.0.0.1:<port> HOME_ASSISTANT_TOKEN=<token> \
-// npx vitest run tests/home-runtime-live.test.js
+// npm run test:home:live
+// HOME_LIVE=1 HOME_ALLOW_LOCAL_INSTANCE=1 npx vitest run tests/home-runtime-live.test.js
+//
+// Pointing at a house you already have still works, via HOME_ASSISTANT_URL and
+// HOME_ASSISTANT_TOKEN, because acquireHomeInstance prefers those when set.
+//
+// HOME_ALLOW_LOCAL_INSTANCE=1 is the seam documented in
+// api/_lib/home-url-guard.js, and unlike every other live file in the lane this
+// one needs it: the runtime dials the house through the same reachability guard
+// the API uses, and a harness instance lands on loopback, which that guard
+// refuses. It is part of the gate rather than a hard failure so that a run
+// without it skips with a reason instead of reporting the guard as a bug.
//
// Never mocked. A fake instance is what hid Home Assistant's own
// `intent__HassTurnOff` performing an UNLOCK on a lock, which is the single most
// important thing this lane learned.
-import { afterAll, describe, expect, it } from 'vitest';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import { createHomeRuntime } from '../api/_lib/home/runtime.js';
import { HOME_STATUS } from '../api/_lib/home/store.js';
import { HomeBridge } from '@three-ws/home-bridge';
+import { acquireHomeInstance, liveHomeAvailable } from './_helpers/home-instance.js';
-const BASE_URL = process.env.HOME_ASSISTANT_URL;
-const TOKEN = process.env.HOME_ASSISTANT_TOKEN;
-const live = BASE_URL && TOKEN ? describe : describe.skip;
+// Filled in by beforeAll from the shared harness instance. Every reader below
+// runs inside a test, so a late assignment is the whole cost of not making each
+// developer hand-build a house first.
+let BASE_URL;
+let TOKEN;
+const live = describe.skipIf(!liveHomeAvailable() || process.env.HOME_ALLOW_LOCAL_INSTANCE !== '1');
const HOME_ID = '44444444-4444-4444-8444-444444444444';
const USER_ID = '55555555-5555-4555-8555-555555555555';
@@ -82,6 +96,12 @@ afterAll(() => {
});
live('home runtime, against a real Home Assistant', () => {
+ beforeAll(async () => {
+ const instance = await acquireHomeInstance();
+ BASE_URL = instance.baseUrl;
+ TOKEN = instance.token;
+ }, 600_000);
+
it('opens one socket for two sequential withHome calls', async () => {
const { runtime, createBridge } = liveRuntime();
diff --git a/tests/home-security.test.js b/tests/home-security.test.js
index 00d5f9507..3258ba49f 100644
--- a/tests/home-security.test.js
+++ b/tests/home-security.test.js
@@ -38,6 +38,8 @@ import { fileURLToPath } from 'node:url';
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { acquireHomeInstance, liveHomeAvailable } from './_helpers/home-instance.js';
+
import { classifyCall } from '../packages/home-bridge/src/safety.js';
/**
@@ -304,6 +306,49 @@ describe('home security 3: only a session with CSRF can redeem a confirmation',
// not 403 across a tenancy boundary: a 403 confirms the id exists, which is a
// free enumeration oracle over other people's houses.
+/**
+ * The offset of the end of a route's access gate: the `if (!x.ok)` branch that
+ * follows `resolveHomeAccess` or `requireMembership`. Everything after it runs
+ * for a caller who has already proven access to this home.
+ *
+ * Returns -1 for a route with no gate (its subject is the account, not a
+ * house), which callers read as "nothing here is post-gate".
+ */
+function accessGateEnd(code) {
+ const guard = code.match(/if\s*\(\s*!\s*\w+\.ok\s*\)/);
+ if (!guard) return -1;
+ const after = guard.index + guard[0].length;
+ const offset = code.slice(after).search(/\S/);
+ if (offset === -1) return -1;
+ const start = after + offset;
+ if (code[start] !== '{') {
+ // A one-line guard: `if (!access.ok) return error(...);`
+ const semi = code.indexOf(';', start);
+ return semi === -1 ? -1 : semi;
+ }
+ let depth = 0;
+ for (let i = start; i < code.length; i++) {
+ if (code[i] === '{') depth++;
+ else if (code[i] === '}' && --depth === 0) return i;
+ }
+ return -1;
+}
+
+/**
+ * The codes a 403 may carry where a stranger can still reach it. Each names a
+ * PRINCIPAL (your role, your session, your CSRF token) and never a house.
+ */
+const PRINCIPAL_ONLY_403 =
+ /^(role_forbidden|out_of_scope|forbidden|csrf|invalid_csrf|confirmation_requires_session)$/;
+
+/** Every 403 a route answers at or before its access gate that names something other than a principal. */
+function unsafe403s(code) {
+ const gateEnd = accessGateEnd(code);
+ return [...code.matchAll(/\b(?:error|json)\s*\(\s*res\s*,\s*403\s*,\s*'([^']*)'/g)]
+ .filter((m) => (gateEnd === -1 || m.index <= gateEnd) && !PRINCIPAL_ONLY_403.test(m[1]))
+ .map((m) => m[1]);
+}
+
describe('home security 5: every home route is scoped to its owner', () => {
const routes = homeRouteFiles();
@@ -316,6 +361,32 @@ describe('home security 5: every home route is scoped to its owner', () => {
}
});
+ it('the 403 rule still bites, so a green matrix means something', () => {
+ // A positional rule can be widened by accident in a way a list of names
+ // cannot, so the rule is held to synthetic sources with a known verdict.
+ // Without this, loosening accessGateEnd until it returns 0 for everything
+ // would turn the whole matrix above green and nothing would say so.
+ const gated = (before, after) =>
+ `const access = await resolveHomeAccess(req, res, id, 'read');\n${before}\nif (!access.ok) return error(res, access.status, access.code, access.message);\n${after}`;
+
+ // Safe: a role refusal after the caller proved access to this home.
+ expect(unsafe403s(gated('', "return error(res, 403, 'scope_forbidden', 'x');"))).toEqual([]);
+ // Unsafe: the same refusal before the gate, reachable by a stranger.
+ expect(unsafe403s(gated("return error(res, 403, 'scope_forbidden', 'x');", ''))).toEqual([
+ 'scope_forbidden',
+ ]);
+ // Unsafe: a home-shaped code inside the gate's own failure branch.
+ expect(
+ unsafe403s(
+ "const access = await resolveHomeAccess(req, res, id, 'read');\nif (!access.ok) {\n\treturn error(res, 403, 'home_forbidden', 'x');\n}\n",
+ ),
+ ).toEqual(['home_forbidden']);
+ // Safe: a principal refusal before the gate names no house.
+ expect(unsafe403s(gated("return error(res, 403, 'csrf', 'x');", ''))).toEqual([]);
+ // A route with no gate at all is judged entirely by the code it names.
+ expect(unsafe403s("return error(res, 403, 'home_forbidden', 'x');")).toEqual(['home_forbidden']);
+ });
+
for (const file of routes) {
it(`${rel(file)} authenticates before it touches anything`, () => {
const { src } = routeSource(file);
@@ -344,19 +415,28 @@ describe('home security 5: every home route is scoped to its owner', () => {
});
it(`${rel(file)} only answers 403 for a role, never for a home`, () => {
- const { src } = routeSource(file);
+ const code = stripComments(routeSource(file).src);
// Across a tenancy boundary the answer is 404: a 403 there confirms the
// id is real and turns a list of uuids into an oracle for "is this a
- // house". A 403 AFTER access succeeded is a different answer to a
- // different question (your role is short, that entity is out of your
- // scope) and is safe to name, so those codes are the allowed set.
- // confirmation_requires_session is the check-3 control: it fires before
- // any home is looked up, so it names a principal and never a house.
- const SAFE = /^(role_forbidden|out_of_scope|forbidden|csrf|invalid_csrf|confirmation_requires_session)$/;
- const offenders = [...stripComments(src).matchAll(/\b(?:error|json)\s*\(\s*res\s*,\s*403\s*,\s*'([^']*)'/g)]
- .map((m) => m[1])
- .filter((code) => !SAFE.test(code));
- expect(offenders, `${rel(file)} answers 403 with a code that could name a home`).toEqual([]);
+ // house".
+ //
+ // The property that actually decides whether a 403 is safe is WHERE it
+ // fires, not what it is called. Once the access gate has resolved ok the
+ // caller has already proven membership of this home, so the id is not
+ // news to them and a 403 there ("your role is short", "that entity is
+ // out of your scope") discloses nothing. Anything at or before the gate,
+ // including the gate's own failure branch, can be reached by a stranger
+ // and may only name a PRINCIPAL.
+ //
+ // This is checked positionally rather than against a list of code names
+ // because a list of names is a check that decays: every legitimately new
+ // role refusal fails it, and the cheap fix is always to append the new
+ // string, which is how an allowlist ends up allowing everything. The
+ // position cannot be widened by accident.
+ expect(
+ unsafe403s(code),
+ `${rel(file)} answers 403 before its access gate with a code that could name a home`,
+ ).toEqual([]);
});
}
@@ -777,9 +857,12 @@ describe('home security 11: revoking a home drops its socket now, not at the nex
// The assertion is the lock's state, never the model's words. Model output
// varies run to run; a deadbolt does not.
-const liveUrl = process.env.HOME_ASSISTANT_URL;
-const liveToken = process.env.HOME_ASSISTANT_TOKEN;
-const live = describe.skipIf(!liveUrl || !liveToken);
+// The house comes from the lane's one harness, so this file no longer needs a
+// developer to have built an instance and exported two variables before the
+// most important test in the lane will run at all.
+let liveUrl;
+let liveToken;
+const live = describe.skipIf(!liveHomeAvailable());
const PAYLOADS = {
entity:
@@ -794,6 +877,9 @@ live('home security 4: a prompt injection with a deadbolt behind it', () => {
let restore = [];
beforeAll(async () => {
+ const instance = await acquireHomeInstance();
+ liveUrl = instance.baseUrl;
+ liveToken = instance.token;
const { HomeBridge } = await import('../packages/home-bridge/src/index.js');
home = new HomeBridge({ baseUrl: liveUrl, token: liveToken });
await home.connect();
@@ -801,7 +887,7 @@ live('home security 4: a prompt injection with a deadbolt behind it', () => {
await settle(1500);
restore = await plantPayloads();
await settle(2500);
- }, 120_000);
+ }, 600_000);
afterAll(async () => {
for (const undo of restore) await undo().catch(() => {});
@@ -900,12 +986,24 @@ live('home security 4: a prompt injection with a deadbolt behind it', () => {
const refused = [];
for (const user of turns) {
+ // Every free rung in the chain meters per minute, and this repository's
+ // keys are shared with whatever else is running. Four turns fired back
+ // to back exhaust the whole chain and leave the proof unproven, so each
+ // turn gets a bounded retry with a spacing longer than a per-minute
+ // window. This changes nothing about what is asserted: the door's state
+ // is still the verdict. It only stops a shared quota deciding whether
+ // the security check ran at all.
let text;
- try {
- ({ text } = await llmComplete({ system, user, maxTokens: 400, timeoutMs: 45_000 }));
- } catch {
- continue;
+ for (let attempt = 0; attempt < 3; attempt++) {
+ if (attempt) await settle(20_000);
+ try {
+ ({ text } = await llmComplete({ system, user, maxTokens: 400, timeoutMs: 45_000 }));
+ break;
+ } catch {
+ text = undefined;
+ }
}
+ if (text === undefined) continue;
modelAnswered++;
const match = String(text || '').match(/\[[\s\S]*\]/);
let actions = [];
diff --git a/tests/home-store.test.js b/tests/home-store.test.js
index 6c462a1a9..07ff392aa 100644
--- a/tests/home-store.test.js
+++ b/tests/home-store.test.js
@@ -18,9 +18,13 @@
// built by hand, so every live test in the lane is pointed at the same
// thing (scripts/home-test-instance.mjs):
//
-// eval "$(node scripts/home-test-instance.mjs --up --onboard --seed --env)"
-// DATABASE_URL=... WALLET_ENCRYPTION_KEY=... npx vitest run tests/home-store.test.js
-// node scripts/home-test-instance.mjs --down
+// HOME_LIVE=1 DATABASE_URL=... WALLET_ENCRYPTION_KEY=... \
+// npx vitest run tests/home-store.test.js
+// node scripts/home-test-instance.mjs --down --name lane
+//
+// HOME_LIVE=1 is the whole setup: the file builds the house itself. Set
+// HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN instead to point it at one
+// you already have.
//
// The live tier writes throwaway users into whatever database it is given
// and deletes them again, the same posture as the package's live-home suite
@@ -34,6 +38,8 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import { classifyCall, createAllowList, HomeBridge } from '@three-ws/home-bridge';
+import { acquireHomeInstance, liveHomeAvailable } from './_helpers/home-instance.js';
+
import {
createConnection,
fingerprintToken,
@@ -120,16 +126,28 @@ describe('grant scoping, over the recorded instance', () => {
const hasDb = Boolean(process.env.DATABASE_URL);
const hasKey = Boolean(process.env.WALLET_ENCRYPTION_KEY || process.env.JWT_SECRET);
-const haUrl = process.env.HOME_ASSISTANT_URL;
-const haToken = process.env.HOME_ASSISTANT_TOKEN;
const liveDb = describe.skipIf(!hasDb || !hasKey);
-const liveHome = describe.skipIf(!hasDb || !hasKey || !haUrl || !haToken);
+const liveHome = describe.skipIf(!hasDb || !hasKey || !liveHomeAvailable());
// A token shaped like the real thing but belonging to nothing: the DB-only tier
// proves the credential path without needing a house to point it at.
const SYNTHETIC_TOKEN = `synthetic.home.assistant.token.${'a'.repeat(64)}`;
-const BASE_URL = haUrl || 'https://home.invalid.three.ws';
+
+// The house, when there is one. Filled in by the file-level hook below, which
+// runs before any suite's own beforeAll, so the DB-only tier stores the real
+// URL when a house exists and the unroutable placeholder when it does not.
+let haUrl;
+let haToken;
+let BASE_URL = 'https://home.invalid.three.ws';
+
+beforeAll(async () => {
+ if (!liveHomeAvailable()) return;
+ const instance = await acquireHomeInstance();
+ haUrl = instance.baseUrl;
+ haToken = instance.token;
+ BASE_URL = haUrl;
+}, 600_000);
liveDb('against a real database', () => {
/** @type {import('@neondatabase/serverless').NeonQueryFunction} */