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-e2e): let a lane find its own house and its own slot on the QA account

nirholas805db9ca7b6a
diff --git a/tests/_helpers/home-instance.js b/tests/_helpers/home-instance.js
index 14b6adeb8..024e3bd1d 100644
--- a/tests/_helpers/home-instance.js
+++ b/tests/_helpers/home-instance.js
@@ -27,8 +27,23 @@ import { fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
const HARNESS = path.join(ROOT, 'scripts', 'home-test-instance.mjs');
-/** The shared instance every live test in the lane reuses. */
-const INSTANCE_NAME = process.env.HOME_LIVE_NAME || 'lane';
+/**
+ * The instance this caller's lane reuses, read at call time and not at import.
+ *
+ * The distinction is load-bearing and cost a run to find. `home-global-setup.js`
+ * imports this module and only then sets `HOME_LIVE_NAME`, so a constant
+ * evaluated at import saw the default while the setup, the stack file and the
+ * accounts file all saw `e2e`. The lane then drove container
+ * `three-ws-home-test-lane` while calling itself the `e2e` lane, and
+ * `resetHomes` (which clears only the homes on THIS lane's house, by base URL)
+ * stopped recognising the homes the previous run had created. On a free plan
+ * that is a hard stop: the account still held a home from the last run, so the
+ * next connect was refused 402 by the plan ceiling, which reads as a product
+ * bug and is a name mismatch.
+ */
+function instanceName() {
+ return process.env.HOME_LIVE_NAME || 'lane';
+}
/**
* Whether the live tier should run at all. Synchronous on purpose: vitest needs
@@ -48,8 +63,10 @@ export function liveHomeAvailable() {
*/
export async function acquireHomeInstance({ timeout = 600_000 } = {}) {
if (process.env.HOME_ASSISTANT_URL && process.env.HOME_ASSISTANT_TOKEN) {
+ const baseUrl = process.env.HOME_ASSISTANT_URL.replace(/\/+$/, '');
+ allowLocalInstance(baseUrl);
return {
- baseUrl: process.env.HOME_ASSISTANT_URL.replace(/\/+$/, ''),
+ baseUrl,
token: process.env.HOME_ASSISTANT_TOKEN,
version: null,
seed: null,
@@ -61,8 +78,9 @@ export async function acquireHomeInstance({ timeout = 600_000 } = {}) {
throw new Error('No live Home Assistant: set HOME_ASSISTANT_URL + HOME_ASSISTANT_TOKEN, or HOME_LIVE=1.');
}
- const result = await runHarness(['--up', '--onboard', '--seed', '--json', '--name', INSTANCE_NAME], { timeout });
+ const result = await runHarness(['--up', '--onboard', '--seed', '--json', '--name', instanceName()], { timeout });
if (!result.ok) throw new Error(`home-test-instance failed: ${result.error}`);
+ allowLocalInstance(result.baseUrl);
return {
baseUrl: result.baseUrl,
token: result.token,
@@ -78,6 +96,59 @@ export async function acquireHomeInstance({ timeout = 600_000 } = {}) {
};
}
+/**
+ * Open the reachability seam for a house that lives on a private address.
+ *
+ * A test that drives a route which dials the house from OUR side goes through
+ * `api/_lib/home-url-guard.js`, and that guard refuses loopback and RFC1918 by
+ * design: it is the SSRF control. Every house this harness can produce is on
+ * 127.0.0.1, so without the seam those routes fail at the dial and answer 502.
+ *
+ * That 502 does not read as a missing flag. It reads as the route being broken,
+ * and it has cost this lane at least one investigation: an unconfirmed
+ * `home:act` call that answers `409 needs_confirmation` with the seam open was
+ * reported as a 409-to-502 regression, reproduced across two instances, when
+ * both runs were simply dialling a loopback house through the production guard.
+ * Remembering an environment variable is not a control, so the harness sets it
+ * for the address it just handed out instead of asking every caller to.
+ *
+ * Narrow on purpose:
+ *
+ * * Only for a PRIVATE literal. A public house needs no seam and never gets
+ * one from here.
+ * * Only in this process, and only for tests. The seam is inert on Cloud Run
+ * regardless: the guard also requires `K_SERVICE` to be absent.
+ * * The security suite proves the shipped guard by re-importing it with the
+ * seam forced off and `K_SERVICE` present, so nothing here can make an SSRF
+ * check pass that would fail in production.
+ */
+function allowLocalInstance(baseUrl) {
+ if (process.env.HOME_ALLOW_LOCAL_INSTANCE === '1') return;
+ let host;
+ try {
+ host = new URL(baseUrl).hostname;
+ } catch {
+ return;
+ }
+ if (!isPrivateLiteral(host)) return;
+ process.env.HOME_ALLOW_LOCAL_INSTANCE = '1';
+}
+
+/** Loopback, RFC1918, CGNAT and link-local, as literals. No DNS, no guessing. */
+function isPrivateLiteral(host) {
+ const bare = host.replace(/^\[|\]$/g, '').toLowerCase();
+ if (bare === 'localhost' || bare === '::1') return true;
+ const v4 = bare.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+ if (!v4) return false;
+ const [a, b] = v4.slice(1).map(Number);
+ if (a === 127 || a === 10 || a === 0) return true;
+ if (a === 192 && b === 168) return true;
+ if (a === 172 && b >= 16 && b <= 31) return true;
+ if (a === 169 && b === 254) return true;
+ if (a === 100 && b >= 64 && b <= 127) return true;
+ return false;
+}
+
/**
* A live entity id of the given domain, read from the house itself rather than
* assumed. A test that hardcodes `light.bed_light` is a test that breaks the
@@ -133,6 +204,28 @@ export async function waitForState(instance, entityId, expected, { timeout = 20_
throw new Error(`${entityId} was "${last}" after ${Math.round(timeout / 1000)}s, expected one of ${[...wanted].join(', ')}`);
}
+/**
+ * Take the house off the network, keeping everything in it.
+ *
+ * The state a connected home enters when its house loses power is one the
+ * product has to render, and the only honest way to reach it is to stop the
+ * real container. `--stop` keeps the config directory, the access token and
+ * every seeded entity, so `startHomeInstance` puts the same house back in
+ * about fifteen seconds rather than paying for another onboarding.
+ */
+export async function stopHomeInstance({ name = instanceName(), timeout = 120_000 } = {}) {
+ const result = await runHarness(['--stop', '--json', '--name', name], { timeout });
+ if (!result.ok) throw new Error(`stopping the home instance failed: ${result.error}`);
+ return result;
+}
+
+/** Put the stopped house back, and wait until it reports itself running. */
+export async function startHomeInstance({ name = instanceName(), timeout = 300_000 } = {}) {
+ const result = await runHarness(['--start', '--json', '--name', name], { timeout });
+ if (!result.ok) throw new Error(`starting the home instance failed: ${result.error}`);
+ return result;
+}
+
/** Put an entity back the way the test found it, for the next test in the file. */
export async function setState(instance, domain, service, entityId) {
const res = await fetch(`${instance.baseUrl}/api/services/${domain}/${service}`, {
diff --git a/tests/e2e/home-global-setup.js b/tests/e2e/home-global-setup.js
index b4ce16da0..abbbcbed6 100644
--- a/tests/e2e/home-global-setup.js
+++ b/tests/e2e/home-global-setup.js
@@ -74,6 +74,7 @@ export default async function globalSetup(config) {
console.log(`[home-e2e] Home Assistant ${home.version || 'unknown'} at ${home.baseUrl}`);
const accounts = await ensureAccounts(origin);
+ await raiseHomeCeiling(accounts);
fs.writeFileSync(
STACK_FILE,
`${JSON.stringify({ home, accounts, origin, lane: LANE, startedAt: new Date().toISOString() }, null, '\t')}\n`,
@@ -81,6 +82,40 @@ export default async function globalSetup(config) {
console.log(`[home-e2e] accounts ready: ${ROLES.map((role) => accounts[role]?.username).filter(Boolean).join(', ')}`);
}
+/**
+ * Give the QA accounts room for more than one house.
+ *
+ * The free plan covers one home, which is correct product behaviour and is the
+ * exact thing order 19's plan-ceiling state exists to render. It is also a hard
+ * stop for this harness: every lane on this machine shares these two accounts,
+ * so the first lane to connect its house takes the only slot and every other
+ * lane is refused 402 by the ceiling. That reads as a broken connect flow and
+ * is a fixture collision, and it cost three runs to see.
+ *
+ * The fix uses the platform's own mechanism rather than inventing a test-only
+ * bypass: `home_plan_overrides` is exactly "this account has these numbers, and
+ * here is the sentence saying why". Nothing about the gate is relaxed, no code
+ * path is skipped, and the ceiling itself is still asserted (against a stub, in
+ * home-connect.spec.js) where it can be reached deterministically. Removing the
+ * row returns the accounts to the free plan.
+ */
+async function raiseHomeCeiling(accounts) {
+ const [{ sql }, { setAccountOverride }] = await Promise.all([
+ import('../../api/_lib/db.js'),
+ import('../../api/_lib/home/entitlements.js'),
+ ]);
+ for (const role of ['owner', 'guest']) {
+ const rows = await sql`select id from users where email = ${accounts[role].email}`;
+ if (!rows.length) continue;
+ await setAccountOverride({
+ userId: rows[0].id,
+ limits: { homes: 25, streams: 25, members: 25 },
+ note: 'Automated QA account for the home e2e lane (tests/e2e/home-global-setup.js). Concurrent lanes on one machine share these accounts, and the free one-home ceiling would let only one lane connect at a time.',
+ });
+ }
+ console.log('[home-e2e] QA accounts have room for concurrent lanes');
+}
+
/**
* Real three.ws accounts, created through the real signup page and kept.
*
diff --git a/tests/e2e/home-support.js b/tests/e2e/home-support.js
index 712bc86d6..4ef83b50c 100644
--- a/tests/e2e/home-support.js
+++ b/tests/e2e/home-support.js
@@ -33,6 +33,19 @@ export function homeInstance() {
return stack().home;
}
+/**
+ * The name of the lane this run is driving, as global setup recorded it.
+ *
+ * Read from the stack file rather than from the environment on purpose. The
+ * lane name decides which container the harness acts on, and a spec that
+ * stopped or started the wrong one would be taking a concurrent run's house
+ * off the network. The stack file is the one place that name is written down
+ * by the process that actually chose it.
+ */
+export function laneName() {
+ return stack().lane || process.env.HOME_LIVE_NAME || 'lane';
+}
+
/**
* Sign in as one of the two accounts global setup provisioned.
*