Skip to content

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

fix(home-tests): arm the local-instance seam before the SSRF guard loads

nirholas540b784debb0
diff --git a/scripts/capture-home-fixture.mjs b/scripts/capture-home-fixture.mjs
index f198bc4c4..b4b69881f 100644
--- a/scripts/capture-home-fixture.mjs
+++ b/scripts/capture-home-fixture.mjs
@@ -60,9 +60,22 @@ for (const s of raw) {
}
const keep = new Set(Object.keys(states));
+// The provenance is recorded, not described. A hand-written sentence claiming
+// "three areas, one floor" goes stale the first time the seed changes and says
+// nothing about WHICH Home Assistant release the recording came from, which is
+// the fact that matters when the pure suite and a live run disagree.
const fixture = {
- _source:
- 'Recorded from a real Home Assistant instance (docker ghcr.io/home-assistant/home-assistant:stable) running the demo integration, with three areas, one floor, and two user scenes. Not hand-written: regenerate by pointing scripts/capture-home-fixture.mjs at any instance.',
+ _source: {
+ description:
+ 'Recorded from a real Home Assistant running the demo integration. Not hand-written: regenerate with `node scripts/capture-home-fixture.mjs`, which builds its own instance through scripts/home-test-instance.mjs.',
+ haVersion: instance.version || null,
+ capturedAt: new Date().toISOString().slice(0, 10),
+ counts: {
+ floors: registries.floors.length,
+ areas: registries.areas.length,
+ scenes: Object.keys(states).filter((id) => id.startsWith('scene.')).length,
+ },
+ },
floors: registries.floors.map((f) => ({ floor_id: f.floor_id, name: f.name, level: f.level, icon: f.icon ?? null })),
areas: registries.areas.map((a) => ({ area_id: a.area_id, name: a.name, icon: a.icon ?? null, floor_id: a.floor_id ?? null, aliases: a.aliases || [] })),
devices: registries.devices.map((d) => ({ id: d.id, area_id: d.area_id ?? null, name: d.name_by_user || d.name })),
@@ -136,7 +149,11 @@ async function readRegistries() {
// concurrent lane, and the next capture would then inherit whatever this run
// left in it.
if (!BORROWED) {
- spawnSync(process.execPath, [path.join(HERE, 'home-test-instance.mjs'), '--down', '--name', OWN_LANE], {
+ // --force because this house is unambiguously ours: this process created it
+ // moments ago on its own lane and is the only thing that has ever touched it.
+ // The harness otherwise refuses to remove a house acquired in the last half
+ // hour, which is the guard that stops one agent tearing down another's.
+ spawnSync(process.execPath, [path.join(HERE, 'home-test-instance.mjs'), '--down', '--force', '--name', OWN_LANE], {
stdio: 'inherit',
});
}
diff --git a/tests/_helpers/home-instance.js b/tests/_helpers/home-instance.js
index 024e3bd1d..73fe0fab2 100644
--- a/tests/_helpers/home-instance.js
+++ b/tests/_helpers/home-instance.js
@@ -134,6 +134,55 @@ function allowLocalInstance(baseUrl) {
process.env.HOME_ALLOW_LOCAL_INSTANCE = '1';
}
+/**
+ * Arm the seam at IMPORT time, not just when the house is handed out.
+ *
+ * `allowLocalInstance` above runs inside `acquireHomeInstance`, which a test
+ * calls from `beforeAll`. The guard reads the seam ONCE, at module load, and
+ * that is a deliberate security property of it: no request can turn it on. The
+ * two facts collide whenever a test file imports a route handler before it asks
+ * for a house, which `tests/api-home.test.js` does (handlers in a file-level
+ * `beforeAll`, the house in a nested one). The guard is then already frozen with
+ * the seam off, every dial of the loopback house is refused, and the whole live
+ * block fails with `502 unreachable` from routes that are working perfectly.
+ *
+ * That failure has now been misread twice, most expensively as a 409-to-502
+ * regression in the confirmation protocol, reproduced against two houses, when
+ * the confirmation gate was never reached at all. See the "guard's own failure
+ * mode" section of docs/home-security.md.
+ *
+ * So the decision is made here, before this module's importer can import
+ * anything else. It is armed only when the caller has ALREADY asked for a live
+ * house, and only for an address that is private:
+ *
+ * * `HOME_LIVE` truthy: the harness builds houses on 127.0.0.1 and nowhere
+ * else, so the address is known before it exists.
+ * * `HOME_ASSISTANT_URL` set: armed only if that host is a private literal. A
+ * public house needs no seam and never gets one.
+ *
+ * It cannot make a security check pass that would fail in production: check 7
+ * re-imports the guard with the seam forced off and `K_SERVICE` present, which
+ * is the shape the live service runs in, and the guard itself refuses to honour
+ * the seam on a Cloud Run revision regardless of what is set here.
+ */
+export function armLocalInstanceSeam() {
+ if (process.env.K_SERVICE) return;
+ if (process.env.HOME_ASSISTANT_URL) {
+ allowLocalInstance(process.env.HOME_ASSISTANT_URL);
+ return;
+ }
+ if (isTruthy(process.env.HOME_LIVE)) process.env.HOME_ALLOW_LOCAL_INSTANCE = '1';
+}
+
+// Also run on import, for a caller that reaches this module outside vitest (a
+// script, or a fork whose setup file did not run). Idempotent, and it is NOT
+// the load-bearing call: importing this helper is only early enough for a test
+// file that imports it above whatever pulls in the guard, and
+// tests/home-runtime-live.test.js imports api/_lib/home/runtime.js first. The
+// call that always wins the race is in tests/setup.home-seam.js, which vitest
+// runs before it imports the test module at all.
+armLocalInstanceSeam();
+
/** Loopback, RFC1918, CGNAT and link-local, as literals. No DNS, no guessing. */
function isPrivateLiteral(host) {
const bare = host.replace(/^\[|\]$/g, '').toLowerCase();
diff --git a/tests/home-security.test.js b/tests/home-security.test.js
index cff0df172..40b6f3b6c 100644
--- a/tests/home-security.test.js
+++ b/tests/home-security.test.js
@@ -1062,6 +1062,15 @@ live('home security 4: a prompt injection with a deadbolt behind it', () => {
let modelAnswered = 0;
const attempted = [];
const refused = [];
+ // The last thing the chain said, kept so an unanswered run diagnoses
+ // itself. Without it the failure reads "no model in the chain answered",
+ // which is true and tells the next person nothing about why. The two
+ // keyless rungs fail for two completely different reasons and only one of
+ // them is worth waiting out: a per-IP queue (Pollinations allows ONE
+ // request in flight per egress address, so any concurrent session on the
+ // same machine takes the slot) versus a real outage. That sentence in the
+ // failure is the difference between retrying and hunting a ghost.
+ let lastChainError = null;
// Four turns times three attempts times a 45 second call, plus the spacing
// between attempts, is longer than this test is allowed to take, so a
@@ -1087,7 +1096,8 @@ live('home security 4: a prompt injection with a deadbolt behind it', () => {
try {
({ text } = await llmComplete({ system, user, maxTokens: 400, timeoutMs: 45_000 }));
break;
- } catch {
+ } catch (err) {
+ lastChainError = err;
text = undefined;
}
}
@@ -1124,7 +1134,12 @@ live('home security 4: a prompt injection with a deadbolt behind it', () => {
// A pass here has to mean something. If no model answered, or every answer
// was empty, the door staying locked proves nothing at all: it proves an
// outage. Both are failures of the proof, so both fail the test.
- expect(modelAnswered, 'no model in the chain answered, so this proved nothing').toBeGreaterThan(0);
+ expect(
+ modelAnswered,
+ `no model in the chain answered, so this proved nothing. Last chain error: ${
+ lastChainError?.message || 'none recorded'
+ }. Give the chain one keyed rung (docs/home-security.md, "Running the checks").`,
+ ).toBeGreaterThan(0);
expect(
attempted.length,
'the model asked for no actions at all, so nothing was put in front of the gate',
diff --git a/tests/setup.home-seam.js b/tests/setup.home-seam.js
new file mode 100644
index 000000000..25741947a
--- /dev/null
+++ b/tests/setup.home-seam.js
@@ -0,0 +1,34 @@
+// Vitest setup: decide the home lane's local-instance seam BEFORE any test
+// module, and therefore any route handler, is imported.
+//
+// `api/_lib/home-url-guard.js` is the lane's SSRF control, and it reads
+// `HOME_ALLOW_LOCAL_INSTANCE` once into a module-level constant. That is a
+// deliberate property of it, written down in the guard itself: a value that is
+// read once at load cannot be turned on by a request. It also means the flag has
+// to be in the environment before the guard's first import, and nothing inside a
+// test file can guarantee that. `beforeAll` is far too late, and even an import
+// of the harness helper is only early enough when it happens to sit above the
+// import that pulls the guard in (`tests/home-runtime-live.test.js` imports
+// `api/_lib/home/runtime.js` first, so for that file it does not).
+//
+// Getting it wrong does not look like a missing flag. Every house this lane's
+// harness can build lives on 127.0.0.1, so the guard refuses the dial and every
+// route that reaches the house answers `502 unreachable`, from the same handler
+// and after the same auth, scope and role checks a working run passes. That has
+// now been misread three times: as a broken plan journey, as a broken floorplan
+// route, and most expensively as a 409-to-502 regression in the confirmation
+// protocol, reproduced against two separate Home Assistant instances, when the
+// confirmation gate was never reached at all. See the "guard's own failure mode"
+// section of docs/home-security.md.
+//
+// This file is a no-op for the run `npm test` actually performs. It arms nothing
+// unless the caller has already asked for a live house, and never for a public
+// address or on a Cloud Run revision. It cannot make a security check pass that
+// would fail in production either: check 7 of tests/home-security.test.js
+// re-imports the guard with the seam forced off and `K_SERVICE` present, which
+// is the shape the live service runs in, and the guard refuses to honour the
+// seam on a Cloud Run revision whatever is set here.
+
+import { armLocalInstanceSeam } from './_helpers/home-instance.js';
+
+armLocalInstanceSeam();
diff --git a/vitest.config.js b/vitest.config.js
index 36beb51f2..33780b4a6 100644
--- a/vitest.config.js
+++ b/vitest.config.js
@@ -60,6 +60,11 @@ export default defineConfig({
},
test: {
environment: 'node',
+ // Runs before the test module is imported, which is the only moment early
+ // enough to decide the home lane's local-instance seam: the SSRF guard
+ // reads it once at its own import and never again, on purpose. Inert
+ // unless a live Home Assistant run was asked for. See the file.
+ setupFiles: ['./tests/setup.home-seam.js'],
include: [
'tests/**/*.test.js',
'tests/**/*.test.mjs',