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-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.mjsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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.jsindex 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',