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-e2e): fail fast when the run's encryption key is not the one bound to its database

nirholase179f36a7561
diff --git a/playwright.home.config.js b/playwright.home.config.js
index e1f109690..fbed79d92 100644
--- a/playwright.home.config.js
+++ b/playwright.home.config.js
@@ -14,10 +14,9 @@ import { fileURLToPath } from 'node:url';
*
* npm run test:home:e2e
*
- * Secrets below are generated per run and are LOCAL ONLY. They encrypt rows
- * this run creates in the database it is pointed at and are thrown away with
- * the process, so nothing here can decrypt a production credential and nothing
- * production wrote can be read by this run.
+ * The session secret below is generated per run and is LOCAL ONLY. The at-rest
+ * encryption key is not: it has to be the key bound to the database the run
+ * writes to, which the comment above ENC_KEY explains.
*/
// The database, in THIS process and not only in the API child process.
//
@@ -53,9 +52,22 @@ const API_PORT = Number(process.env.HOME_E2E_API_PORT) || 8099;
const WEB_PORT = Number(process.env.HOME_E2E_WEB_PORT) || 3020;
const APP_ORIGIN = `http://localhost:${WEB_PORT}`;
+// The at-rest key is the one secret below that cannot be thrown away freely.
+// Since 2026-09-16 api/_lib/secret-box.js binds a database to the key that
+// writes into it and refuses any other writer, because a writer with its own
+// key is exactly how custodial wallets got stranded (docs/ops/stranded-wallets.md).
+// The database in .env.local is bound, so a per-run random key now dies at the
+// first connect with `secret_box_key_mismatch`. The run must carry the key bound
+// to the database it writes to: HOME_E2E_ENC_KEY, else an exported
+// WALLET_ENCRYPTION_KEY. A random key remains only for a database of the run's
+// own. Published back to the environment so the global setup can check the
+// binding before the first browser opens, instead of fifteen tests failing on it.
+const ENC_KEY = process.env.HOME_E2E_ENC_KEY || process.env.WALLET_ENCRYPTION_KEY || randomBytes(32).toString('hex');
+process.env.HOME_E2E_ENC_KEY = ENC_KEY;
+
const localSecrets = {
JWT_SECRET: process.env.HOME_E2E_JWT_SECRET || randomBytes(32).toString('hex'),
- WALLET_ENCRYPTION_KEY: process.env.HOME_E2E_ENC_KEY || randomBytes(32).toString('hex'),
+ WALLET_ENCRYPTION_KEY: ENC_KEY,
APP_ORIGIN,
ISSUER: APP_ORIGIN,
MCP_RESOURCE: `${APP_ORIGIN}/api/mcp`,
diff --git a/tests/e2e/README.md b/tests/e2e/README.md
index 796a06890..ec682106e 100644
--- a/tests/e2e/README.md
+++ b/tests/e2e/README.md
@@ -90,6 +90,19 @@ Dedicated ports and `reuseExistingServer: false` are deliberate. Other agents ru
stack: its `/api` proxy points at **production**, so the run silently tests the wrong API and
reports `No API route matches /api/home` as though the handler were missing.
+**The encryption key has to be the database's.** The API seals each connected house's access
+token with `WALLET_ENCRYPTION_KEY`, and `api/_lib/secret-box.js` binds a database to the one key
+allowed to write into it (see [`docs/ops/stranded-wallets.md`](../../docs/ops/stranded-wallets.md)
+for why). The database in `.env.local` is bound, so a per-run random key is refused at the first
+connect with `secret_box_key_mismatch`. Pass the bound key for the run; the global setup checks
+the fingerprint before anything boots and names this command when it does not match:
+
+```bash
+HOME_E2E_ENC_KEY="$(node scripts/read-service-env.mjs '^WALLET_ENCRYPTION_KEY$' --raw)" \
+ HOME_LIVE_NAME=mylane HOME_E2E_API_PORT=8141 HOME_E2E_WEB_PORT=3071 \
+ npm run test:home:e2e -- tests/e2e/home-a11y.spec.js
+```
+
The house lives on `127.0.0.1`, which both the browser and the server accept because
`normalizeBaseUrl` exempts loopback from the private-host refusal, so a developer running Home
Assistant on this machine still works. Journey 10 proves the refusal still fires for every other
diff --git a/tests/e2e/home-global-setup.js b/tests/e2e/home-global-setup.js
index 32c48542f..4ecf117e3 100644
--- a/tests/e2e/home-global-setup.js
+++ b/tests/e2e/home-global-setup.js
@@ -70,6 +70,7 @@ export default async function globalSetup(config) {
const origin = config?.projects?.[0]?.use?.baseURL || 'http://localhost:3020';
+ await assertWriteKeyBound();
const home = await acquireHomeInstance({ timeout: 900_000 });
console.log(`[home-e2e] Home Assistant ${home.version || 'unknown'} at ${home.baseUrl}`);
@@ -82,6 +83,33 @@ export default async function globalSetup(config) {
console.log(`[home-e2e] accounts ready: ${ROLES.map((role) => accounts[role]?.username).filter(Boolean).join(', ')}`);
}
+/**
+ * Refuse to start when the run's encryption key is not the database's.
+ *
+ * api/_lib/secret-box.js binds a database to the key that writes into it and
+ * refuses every other writer (docs/ops/stranded-wallets.md has why). A lane on
+ * the wrong key does not fail here on its own: it signs in fine, then every
+ * connect answers 500 with `secret_box_key_mismatch` in the API log, and the
+ * whole suite reads as a broken connect flow. Comparing the one-way
+ * fingerprints up front turns that into a single sentence naming the fix.
+ * Read only: an unbound database is left for the first real write to bind.
+ */
+async function assertWriteKeyBound() {
+ const [{ sql }, { secretBoxKeyFingerprint, WRITE_KEY_SETTING }] = await Promise.all([
+ import('../../api/_lib/db.js'),
+ import('../../api/_lib/secret-box.js'),
+ ]);
+ const [row] = await sql`select value from app_settings where key = ${WRITE_KEY_SETTING}`;
+ const bound = row?.value?.fingerprint;
+ if (!bound) return;
+ if (bound === (await secretBoxKeyFingerprint(process.env.HOME_E2E_ENC_KEY || ''))) return;
+ throw new Error(
+ 'this run\'s encryption key is not the one bound to the database in DATABASE_URL, so every connect would be refused with secret_box_key_mismatch. ' +
+ 'Run with the bound key: HOME_E2E_ENC_KEY="$(node scripts/read-service-env.mjs \'^WALLET_ENCRYPTION_KEY$\' --raw)" npm run test:home:e2e, ' +
+ 'or point DATABASE_URL at a database of the run\'s own.',
+ );
+}
+
/**
* Give the QA accounts room for more than one house.
*