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): close the local-instance seam on production for real

nirholas58270098f853
diff --git a/api/_lib/home-url-guard.js b/api/_lib/home-url-guard.js
index 3812b2af4..331c18246 100644
--- a/api/_lib/home-url-guard.js
+++ b/api/_lib/home-url-guard.js
@@ -52,7 +52,8 @@ export const REACHABILITY_CODES = new Set(['private_address', 'unroutable_host']
* The one way a private address is ever dialable, and it is off unless BOTH of
* these are true at once:
*
- * * this process is not production (`NODE_ENV !== 'production'`), and
+ * * this process is not a Cloud Run revision (no `K_SERVICE`) and is not
+ * otherwise marked production (`NODE_ENV !== 'production'`), and
* * `HOME_ALLOW_LOCAL_INSTANCE=1` is set in the environment.
*
* It exists because the Home campaign's own instruction is "never mock Home
@@ -64,12 +65,23 @@ export const REACHABILITY_CODES = new Set(['private_address', 'unroutable_host']
* internet so it passes the guard) is far worse than the thing the guard
* prevents.
*
- * Two properties keep it from being a hole: it is read once at module load, so
- * a request cannot turn it on; and the production check is on NODE_ENV rather
- * than on the flag alone, so setting the flag on the live service does nothing.
+ * Three properties keep it from being a hole. It is read once at module load, so
+ * no request can turn it on. It needs the flag, which is set nowhere. And the
+ * production check is POSITIVE: `K_SERVICE` is stamped on every Cloud Run
+ * revision by the runtime and cannot be unset from the service config, so the
+ * seam is off on the live service whatever else is configured.
+ *
+ * That last one is not a stylistic preference. The check was originally
+ * `NODE_ENV !== 'production'`, and `NODE_ENV` is not set on the three-ws-api
+ * service at all, so it read TRUE in production and the whole guard rested on
+ * one unset flag. A negative test for production is only as good as somebody
+ * remembering to set the variable it tests; `K_SERVICE` is set by the platform.
+ * api/cron/economy-tick.js uses the same signal for the same reason.
*/
const ALLOW_LOCAL_INSTANCE =
- process.env.NODE_ENV !== 'production' && process.env.HOME_ALLOW_LOCAL_INSTANCE === '1';
+ !process.env.K_SERVICE &&
+ process.env.NODE_ENV !== 'production' &&
+ process.env.HOME_ALLOW_LOCAL_INSTANCE === '1';
// The connect probe talks to a home that may be a residential uplink on the far
// side of a reverse proxy. Ten seconds is long enough for that and short enough
diff --git a/docs/home-security.md b/docs/home-security.md
index 1289dc5c3..b34b9508a 100644
--- a/docs/home-security.md
+++ b/docs/home-security.md
@@ -131,6 +131,21 @@ All three channels take the pin. Node's global `WebSocket` is undici's and honou
`dispatcher`, which is what makes pinning the state channel possible at all; the pinned socket
factory is verified against a real Home Assistant rather than assumed to work.
+**There is exactly one way a private address is ever dialable**, and it is the local-instance
+seam: `HOME_ALLOW_LOCAL_INSTANCE=1` on a process that is not a Cloud Run revision. It exists
+because this campaign's own rule is "never mock Home Assistant, run one", and the way you run one
+lands on loopback; without it, no part of this surface could be exercised against a real instance
+on a developer machine, and the workaround people reach for (publishing their test Home
+Assistant, token and all, so it passes the guard) is far worse than what the guard prevents.
+
+Its production check is **positive**, and that matters more than it sounds. It was originally
+`NODE_ENV !== 'production'`, and `NODE_ENV` is not set on the `three-ws-api` service at all, so
+that test read true in production and the entire guard rested on one unset flag. It now keys off
+`K_SERVICE`, which the Cloud Run runtime stamps on every revision and which cannot be removed
+from the service config. Proven both ways: with the flag set and no `K_SERVICE`, loopback
+resolves; with the flag set and `K_SERVICE` present, loopback and `169.254.169.254` are both
+refused.
+
**The pin is re-derived on every dial, not stored.** `api/_lib/home/runtime.js` re-resolves a
direct home each time the pool opens a connection to it, so a house whose name was public when
the user added it and points into our network today is refused at reconnect rather than trusted
diff --git a/tests/home-security.test.js b/tests/home-security.test.js
index 07a5e038b..326997ed4 100644
--- a/tests/home-security.test.js
+++ b/tests/home-security.test.js
@@ -538,6 +538,25 @@ describe('home security 7: a user-supplied home URL cannot reach our network', (
expect(offenders, 'these dial a home without the SSRF guard').toEqual([]);
});
+ it('the local-instance seam cannot be on in production', async () => {
+ // The seam exists so the lane can be exercised against a real Home
+ // Assistant on a developer machine, which lands on loopback. It is also
+ // the one switch that turns this whole guard off, so its production check
+ // has to be one the platform sets rather than one a person remembers to.
+ const src = read(join(REPO, 'api', '_lib', 'home-url-guard.js'));
+ expect(src, 'the seam must key off K_SERVICE, which Cloud Run stamps on every revision').toMatch(
+ /!process\.env\.K_SERVICE/,
+ );
+ expect(src, 'the seam must still require its own flag').toMatch(/HOME_ALLOW_LOCAL_INSTANCE === '1'/);
+
+ // And it is off by default, which is the state every test in this file
+ // above has been running under.
+ const guard = await import('../api/_lib/home-url-guard.js');
+ await expect(guard.assertDialableHomeUrl('https://127.0.0.1:8123')).rejects.toMatchObject({
+ code: 'private_address',
+ });
+ });
+
it('the guard is actually reached by the connect path, so the check above means something', () => {
for (const file of ['api/home/index.js', 'api/_lib/home/verify.js', 'api/_lib/home/runtime.js']) {
expect(read(join(REPO, file)), `${file} must dial through the guard`).toMatch(/home-url-guard/);