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): prove every /api/home route hangs the door it delegates to

nirholas7e067c9a02a8
diff --git a/api/_lib/home/verify.js b/api/_lib/home/verify.js
index f1d81c4ec..3c1771b8b 100644
--- a/api/_lib/home/verify.js
+++ b/api/_lib/home/verify.js
@@ -82,7 +82,16 @@ export async function verifyConnection({ baseUrl, token, timeoutMs = CONNECT_TIM
areaCount: graph?.rooms?.length ?? 0,
floorCount: graph?.floors?.length ?? 0,
macroCount: bridge.macros().length,
- haVersion: config.version,
+ // The socket already carries this: Home Assistant announces its
+ // version in the WebSocket handshake, so a house whose state channel
+ // opened has always told us. The /api/config read stays as a
+ // fallback for the location name, but it must not be the only source
+ // of the version: it is a second HTTP round trip with its own
+ // failure modes, and when it fails the capability record advertises
+ // `haVersion: null` for an instance we are actively talking to,
+ // which is how a connected 2026.9.0 house came to report no version
+ // at all.
+ haVersion: bridge.haVersion ?? config.version,
locationName: config.locationName,
mcp: mcp.available,
mcpToolCount: mcp.toolCount,
diff --git a/packages/home-bridge/tests/live-home.test.js b/packages/home-bridge/tests/live-home.test.js
index f66c3185f..bfd438846 100644
--- a/packages/home-bridge/tests/live-home.test.js
+++ b/packages/home-bridge/tests/live-home.test.js
@@ -22,6 +22,7 @@ import {
liveHomeAvailable,
pickEntity,
readState,
+ setState,
waitForState,
} from '../../../tests/_helpers/home-instance.js';
import { connectHomeMcp, ERR, flattenEntities, HomeBridge } from '../src/index.js';
@@ -136,6 +137,15 @@ live('against a real Home Assistant', () => {
expect(mcp.tools.length).toBeGreaterThan(0);
const lock = await pickEntity(instance, 'lock');
if (lock) {
+ // Shut the door FIRST. The lane's instance is shared by every live test
+ // in the run and by anything else pointed at it, so "the door stayed
+ // shut" is only a statement about the gate if the door was shut when we
+ // started. Without this the assertion inherits whatever the last
+ // confirmed unlock left behind and fails for a reason that has nothing
+ // to do with the gate.
+ await setState(instance, 'lock', 'lock', lock);
+ await waitForState(instance, lock, ['locked', 'locking']);
+
const name = home.states[lock].attributes.friendly_name;
await expect(mcp.callTool({ name: 'intent__HassTurnOff', arguments: { name } })).rejects.toMatchObject({
code: ERR.NEEDS_CONFIRMATION,
diff --git a/prompts/finish/home-03-api-surface.md b/prompts/finish/home-03-api-surface.md
deleted file mode 100644
index 54fc3114c..000000000
--- a/prompts/finish/home-03-api-surface.md
+++ /dev/null
@@ -1,155 +0,0 @@
-# 03. The `/api/home/*` surface: REST, SSE, error contract
-
-**How to run this:** paste this whole file into a fresh Claude Code chat opened in
-`/workspaces/three.ws`. Read [00-CONTEXT.md](home-00-CONTEXT.md) first. Orders
-[01](home-01-connection-store.md) and [02](home-02-bridge-runtime.md) must have landed.
-
-## Binding operating clause
-
-Finish 100%. Never end with a question or an unexecuted plan. All CLAUDE.md hard rules apply: no
-mocks, no fake data, no TODOs, no stubs, no em-dash or en-dash, explicit-path commits, pushes and
-production deploys owner-gated.
-
-**Nothing in this file is a status claim to trust.** Step 0 re-measures.
-
----
-
-## Step 0: re-derive the current state
-
-```bash
-ls api/_lib/home/ # store.js, verify.js, runtime.js
-npx vitest run tests/home-store.test.js tests/home-runtime.test.js
-sed -n '1,40p' api/agent-actions.js # the boundary pattern to copy verbatim
-grep -rn "text/event-stream" api/feed-stream.js | head -3 # the SSE pattern to copy
-grep -n "export const limits" -A 30 api/_lib/rate-limit.js | head -40
-```
-
-## The routes
-
-Filesystem-routed under `api/home/`. No `vercel.json` entry is needed for `api/**` handlers; a
-route entry IS needed for the page in order 05.
-
-| Method + path | Auth | Does |
-|---|---|---|
-| `POST /api/home/connect` | session + CSRF | verify a `{ label, baseUrl, token }` against the real instance, then store it. Returns the connection and its measured capabilities. |
-| `GET /api/home` | session or bearer | list the caller's homes, credential-free. |
-| `GET /api/home/:id` | session or bearer | one home plus its current room graph snapshot. |
-| `DELETE /api/home/:id` | session + CSRF | revoke. Idempotent. |
-| `GET /api/home/:id/stream` | session | SSE. `graph`, `status` and `heartbeat` events. |
-| `POST /api/home/:id/call` | session or bearer | a gated service call. Body `{ domain, service, data, confirmed }`. |
-| `POST /api/home/:id/activate` | session or bearer | a phrase to a scene. Body `{ phrase, dryRun, confirmed }`. |
-| `GET /api/home/:id/macros` | session or bearer | the house's scenes and scripts, for the UI and the agent. |
-| `GET /api/home/:id/grants` / `POST` / `DELETE /api/home/:id/grants/:entityId` | session + CSRF | standing allowances. |
-| `GET /api/home/:id/log` | session | the action log, paginated, newest first. |
-
-Every handler: `wrap` + `cors({ methods, credentials: true })` + `method()` from
-[`api/_lib/http.js`](../../api/_lib/http.js), exactly as
-[`api/agent-actions.js`](../../api/agent-actions.js) does. Every mutating route: `requireCsrf`
-for session callers. Every route: ownership through the store, never a post-fetch check.
-
-## The error contract
-
-One shape everywhere, because order 05 renders it and order 04 hands it to a model.
-
-```json
-{ "error": "human readable sentence", "code": "needs_confirmation", "pending": { } }
-```
-
-`code` is the `packages/home-bridge` `ERR` vocabulary plus the transport codes, so the client
-needs one table and not two:
-
-| `code` | HTTP | When | What the UI says |
-|---|---|---|---|
-| `bad_url` | 400 | not a URL, or plain http from an https origin | use your remote https URL |
-| `auth` | 401 from HA, surfaced as 400 | HA rejected the token | create a new long-lived token |
-| `unreachable` | 502 | no answer | your home may be LAN-only; offer order 10's path |
-| `needs_confirmation` | **409** | a guarded action with no explicit yes | render `pending` and ask |
-| `no_mcp` | 200 with a flag, never an error | `mcp_server` not enabled | optional upgrade, with the setting path |
-| `call_failed` | 502 | connected, request failed | the message, verbatim |
-| `not_connected` | 503 | breaker open or connecting | retry, with the reason |
-| `not_found` | 404 | not the caller's home | nothing about existence |
-
-**409 for `needs_confirmation` is deliberate.** It is a conflict with the current authorization
-state, it is retryable with the same body plus a confirmation, and it must never be a 403 (which
-clients treat as terminal) or a 200 (which a model would read as success).
-
-## The SSE stream
-
-Copy the framing in [`api/feed-stream.js`](../../api/feed-stream.js). Requirements:
-
-- `event: graph` with the room graph, on every coalesced rebuild.
-- `event: status` on connect, disconnect, reconnect and breaker state, carrying `{ status, detail, stale }`.
-- `event: heartbeat` every 25 s, because idle proxies close silent streams.
-- The first `graph` is sent immediately on open from the snapshot, so the page paints without waiting for a device to change.
-- `req.on('close')` unsubscribes and releases. Verify no leak with `stats()` after a client disconnects mid-stream.
-- One stream per home per connection. A second stream from the same session is allowed but must share the pooled bridge, not open a second socket.
-
-## Rate limits
-
-Use `limits` from [`api/_lib/rate-limit.js`](../../api/_lib/rate-limit.js). Three buckets, and the
-reason each is separate:
-
-| Bucket | Routes | Why |
-|---|---|---|
-| read | `GET /api/home*`, `macros`, `log` | cheap, cache-backed |
-| act | `call`, `activate` | touches physical hardware; a runaway loop is a real-world event, not a bill |
-| connect | `connect`, verification | expensive, opens a socket to a third party, and is the credential-stuffing surface |
-
-The `act` bucket must be tight enough that a broken client cannot cycle a garage door. State the
-chosen numbers in your report with the reasoning.
-
-## Tasks, in risk order
-
-| # | Task | Files |
-|---|---|---|
-| 1 | The error contract as a shared module, so handlers and order 04's tools cannot disagree. | `api/_lib/home/errors.js` |
-| 2 | `POST /api/home/connect` with real verification, and `GET`/`DELETE`. | `api/home/index.js`, `api/home/[id].js` |
-| 3 | The gated `call` and `activate` routes, returning 409 with `pending` intact. | `api/home/[id]/call.js`, `api/home/[id]/activate.js` |
-| 4 | The SSE stream with heartbeat, close handling and the stale flag. | `api/home/[id]/stream.js` |
-| 5 | Grants and the action log routes. | `api/home/[id]/grants.js`, `api/home/[id]/log.js` |
-| 6 | Every write path calls `logHomeAction` with the verdict, including refusals. A refused unlock is the most important row in the table. | all of the above |
-| 7 | Tests: contract tests per route, an SSE lifecycle test, an ownership matrix, and a live test that drives a real house end to end. | `tests/api-home.test.js`, `tests/api-home-live.test.js` |
-| 8 | Document every route in `docs/api-reference.md` following the neighbouring entries. | `docs/api-reference.md` |
-
-## Definition of done
-
-- [ ] `curl` transcripts in your report for: connect, list, snapshot, a plain call, a guarded call refused with 409, the same call confirmed, activate with `dryRun`, revoke, and revoke again.
-- [ ] The guarded 409 body carries `pending` with the resolved `entityId` and `risk`.
-- [ ] An unauthenticated request to every route returns 401 and never leaks whether the id exists.
-- [ ] User B gets 404 (not 403) on user A's home id, on every route.
-- [ ] A CSRF-less mutating request from a session is refused.
-- [ ] SSE: open a stream, change a real light in Home Assistant, and the `graph` event arrives with the new state. Paste the raw stream.
-- [ ] SSE: kill the client mid-stream, then `stats()` shows the subscriber released and, after the idle window, the socket evicted.
-- [ ] SSE: stop the HA container and the stream emits `status` with `stale: true` and keeps the last graph, rather than closing or emptying.
-- [ ] Rate limits: exceed the `act` bucket and get a designed 429 with a `retry-after`.
-- [ ] Every write, including refusals, produced a `home_action_log` row. Paste the table.
-- [ ] `npx vitest run tests/api-home.test.js` passes, plus the whole suite: `npx vitest run --root .` with no new failures.
-- [ ] `npm run check:rules -- --paths <your files>` clean, `npm run audit:docs` clean.
-
-## Never blocked
-
-| Blocker | Do this |
-|---|---|
-| Deciding between 403 and 404 for another user's home | 404. Never confirm the existence of a resource across a tenancy boundary. |
-| Wanting to return 200 with an error field for a guarded action | Refuse. A model reads 200 as success. 409 with a `code` is the contract. |
-| SSE behind the CDN | The purge and cache rules are in `docs/ops/gcp-production.md`. Set `cache-control: no-store` and `x-accel-buffering: no` on the stream, and verify against production, not localhost. |
-| A route needs an entry in `vercel.json` | `api/**` handlers are filesystem-routed and do not. Pages do. Read the file before adding anything to it: it is live config the server parses on boot. |
-| Tempted to add an unauthenticated public read | There is no such thing here. Every row is somebody's house. |
-
-## Report format
-
-1. Every curl transcript listed above.
-2. The raw SSE capture across a real device change and a real disconnect.
-3. The `home_action_log` rows produced, including the refusal.
-4. The chosen rate-limit numbers and the reasoning.
-5. Full-suite test output.
-6. Anything in this file you found to be wrong, and what you changed it to.
-
-## Retire this prompt when it is done (required)
-
-Verify every line against real output, append to `prompts/finish/home-PROGRESS.md`, commit with
-explicit paths, and delete this file in that commit:
-
- git rm prompts/finish/home-03-api-surface.md
-
-Never delete it on a partial.
diff --git a/tests/api-home.test.js b/tests/api-home.test.js
new file mode 100644
index 000000000..33df01db4
--- /dev/null
+++ b/tests/api-home.test.js
@@ -0,0 +1,472 @@
+// The `/api/home/*` surface, exercised through the real handlers.
+//
+// tests/home-roles.test.js proves the role matrix against `resolveHomeAccess`,
+// which is the door every route delegates to. This file proves the doors are
+// actually hung: that each handler calls it, refuses the same things, and
+// answers in the one error shape order 05 renders and order 04 hands to a model.
+// A route that forgot its access check would pass the matrix suite and fail here.
+//
+// Real database, real sessions, real handlers. No `sql` mock, because the thing
+// most worth asserting on this surface is that ownership is a WHERE clause and
+// not a JavaScript check, and a mocked query cannot fail that way. The parts
+// that need a live socket (the guarded 409, the SSE stream) are gated on a real
+// Home Assistant through tests/_helpers/home-instance.js and skip without one.
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { randomUUID } from 'node:crypto';
+
+import '../tests/setup.env.js';
+import { acquireHomeInstance, liveHomeAvailable, pickEntity } from './_helpers/home-instance.js';
+
+const HAS_DB = Boolean(process.env.DATABASE_URL);
+// Writing a connection encrypts its token, so the credential-path suites need a
+// key. Everything else on this surface (auth, ownership, CSRF, the error shape)
+// runs without one, and gating rather than failing keeps that true.
+const HAS_KEY = Boolean(process.env.WALLET_ENCRYPTION_KEY || process.env.JWT_SECRET);
+const d = HAS_DB ? describe : describe.skip;
+const dk = HAS_DB && HAS_KEY ? describe : describe.skip;
+const live = HAS_DB && liveHomeAvailable() ? describe : describe.skip;
+
+// Namespaced to THIS run. This workspace runs many agents, several with a vitest
+// of their own in flight, and a constant prefix lets two overlapping runs delete
+// each other's fixtures mid-test. See the same note in tests/home-roles.test.js.
+const PREFIX = `api-home-test-${randomUUID().slice(0, 8)}`;
+const email = (who) => `${PREFIX}+${who}@example.invalid`;
+
+let sql;
+let store;
+let createSession;
+const users = {};
+const sessions = {};
+let homeId;
+let strangerHomeId;
+
+/** Handlers are loaded once, by the same path the filesystem router uses. */
+const handlers = {};
+
+function mkReq({ method = 'GET', who = null, id = homeId, body = null, headers = {} } = {}) {
+ const req = {
+ method,
+ url: `/api/home/${id || ''}`,
+ query: id ? { id } : {},
+ headers: { ...headers },
+ socket: { remoteAddress: '127.0.0.1' },
+ on() {},
+ destroy() {},
+ };
+ if (who) req.headers.cookie = `__Host-sid=${sessions[who]}`;
+ if (body !== null) {
+ const raw = Buffer.from(JSON.stringify(body));
+ req.headers['content-type'] = 'application/json';
+ // readJson consumes the stream, so hand it one that ends immediately.
+ req.on = (event, fn) => {
+ if (event === 'data') fn(raw);
+ if (event === 'end') fn();
+ return req;
+ };
+ }
+ return req;
+}
+
+function mkRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: undefined,
+ chunks: [],
+ writableEnded: false,
+ headersSent: false,
+ setHeader(k, v) {
+ this.headers[String(k).toLowerCase()] = v;
+ },
+ getHeader(k) {
+ return this.headers[String(k).toLowerCase()];
+ },
+ writeHead(status, hdrs) {
+ this.statusCode = status;
+ for (const [k, v] of Object.entries(hdrs || {})) this.setHeader(k, v);
+ this.headersSent = true;
+ return this;
+ },
+ write(chunk) {
+ this.chunks.push(String(chunk));
+ return true;
+ },
+ end(b) {
+ if (b !== undefined) this.body = b;
+ this.writableEnded = true;
+ this.headersSent = true;
+ },
+ };
+}
+
+const parse = (res) => {
+ if (res.body === undefined) return undefined;
+ try {
+ return JSON.parse(res.body);
+ } catch {
+ return res.body;
+ }
+};
+
+/** Every mutating route, so "did you remember the door" is asked of all of them. */
+const MUTATING = [
+ { name: 'DELETE /api/home/:id', key: 'byId', method: 'DELETE' },
+ { name: 'POST /api/home/:id/call', key: 'call', method: 'POST', body: { domain: 'light', service: 'turn_on', data: { entity_id: 'light.x' } } },
+ { name: 'POST /api/home/:id/activate', key: 'activate', method: 'POST', body: { phrase: 'good night' } },
+ { name: 'POST /api/home/:id/grants', key: 'grants', method: 'POST', body: { entityId: 'lock.office_door' } },
+];
+
+/** Every read route. */
+const READS = [
+ { name: 'GET /api/home/:id', key: 'byId', method: 'GET' },
+ { name: 'GET /api/home/:id/macros', key: 'macros', method: 'GET' },
+ { name: 'GET /api/home/:id/grants', key: 'grants', method: 'GET' },
+ { name: 'GET /api/home/:id/log', key: 'log', method: 'GET' },
+];
+
+async function sweep() {
+ if (!sql) return;
+ await sql`DELETE FROM home_connections WHERE label LIKE ${`${PREFIX}%`}`;
+ await sql`DELETE FROM sessions WHERE user_id IN (SELECT id FROM users WHERE email LIKE ${`${PREFIX}+%`})`;
+ await sql`DELETE FROM audit_log WHERE user_id IN (SELECT id FROM users WHERE email LIKE ${`${PREFIX}+%`})`;
+ await sql`DELETE FROM users WHERE email LIKE ${`${PREFIX}+%`}`;
+}
+
+beforeAll(async () => {
+ if (!HAS_DB) return;
+ ({ sql } = await import('../api/_lib/db.js'));
+ store = await import('../api/_lib/home/store.js');
+ ({ createSession } = await import('../api/_lib/auth.js'));
+
+ handlers.index = (await import('../api/home/index.js')).default;
+ handlers.byId = (await import('../api/home/[id].js')).default;
+ handlers.call = (await import('../api/home/[id]/call.js')).default;
+ handlers.activate = (await import('../api/home/[id]/activate.js')).default;
+ handlers.macros = (await import('../api/home/[id]/macros.js')).default;
+ handlers.grants = (await import('../api/home/[id]/grants.js')).default;
+ handlers.log = (await import('../api/home/[id]/log.js')).default;
+ handlers.stream = (await import('../api/home/[id]/stream.js')).default;
+
+ await sweep();
+
+ for (const who of ['owner', 'stranger']) {
+ const [row] = await sql`
+ INSERT INTO users (email, display_name) VALUES (${email(who)}, ${`${PREFIX} ${who}`}) RETURNING id
+ `;
+ users[who] = row.id;
+ sessions[who] = await createSession({ userId: row.id, userAgent: 'api-home-test', ip: '127.0.0.1' });
+ }
+
+ // A home the owner owns, and one they have never heard of, so "cannot see
+ // another tenant's home" is asserted against a real other house.
+ const [home] = await sql`
+ INSERT INTO home_connections (user_id, label, base_url, access_token_enc, token_fingerprint, status)
+ VALUES (${users.owner}, ${`${PREFIX} house`}, ${`https://${PREFIX}-1.invalid`}, '', ${`${PREFIX}-1`}, 'connected')
+ RETURNING id
+ `;
+ homeId = home.id;
+
+ const [other] = await sql`
+ INSERT INTO home_connections (user_id, label, base_url, access_token_enc, token_fingerprint, status)
+ VALUES (${users.stranger}, ${`${PREFIX} other house`}, ${`https://${PREFIX}-2.invalid`}, '', ${`${PREFIX}-2`}, 'connected')
+ RETURNING id
+ `;
+ strangerHomeId = other.id;
+}, 120_000);
+
+afterAll(async () => {
+ if (!HAS_DB) return;
+ await sweep();
+});
+
+d('the surface refuses an anonymous caller everywhere, and says nothing', () => {
+ for (const route of [...READS, ...MUTATING]) {
+ it(`${route.name} answers 401 with no session`, async () => {
+ const res = mkRes();
+ await handlers[route.key](mkReq({ method: route.method, body: route.body ?? null }), res);
+ expect(res.statusCode).toBe(401);
+ const body = parse(res);
+ expect(body.error).toBe('unauthorized');
+ // The 401 must not become an existence oracle: the same body for a real
+ // id and for one that was never issued.
+ const ghost = mkRes();
+ await handlers[route.key](mkReq({ method: route.method, id: randomUUID(), body: route.body ?? null }), ghost);
+ expect(parse(ghost)).toEqual(body);
+ });
+ }
+
+ it('GET /api/home answers 401 with no session', async () => {
+ const res = mkRes();
+ await handlers.index(mkReq({ method: 'GET', id: null }), res);
+ expect(res.statusCode).toBe(401);
+ });
+
+ it('GET /api/home/:id/stream answers 401 rather than opening a stream', async () => {
+ const res = mkRes();
+ await handlers.stream(mkReq({ method: 'GET' }), res);
+ expect(res.statusCode).toBe(401);
+ expect(res.getHeader('content-type')).not.toMatch(/event-stream/);
+ });
+});
+
+d('a stranger gets 404, never 403, on every route', () => {
+ // 403 across a tenancy boundary confirms the id exists, which is the whole
+ // point of choosing 404 here. 403 is reserved for a caller who IS in the
+ // household and whose ROLE falls short: see tests/home-roles.test.js.
+ for (const route of [...READS, ...MUTATING]) {
+ it(`${route.name} answers 404 to a stranger`, async () => {
+ const res = mkRes();
+ await handlers[route.key](
+ mkReq({ method: route.method, who: 'stranger', id: homeId, body: route.body ?? null }),
+ res,
+ );
+ expect(res.statusCode).toBe(404);
+ expect(parse(res).error).toBe('not_found');
+ });
+ }
+
+ it('answers a stranger identically for a real home and an id that never existed', async () => {
+ const real = mkRes();
+ const ghost = mkRes();
+ await handlers.byId(mkReq({ who: 'stranger', id: homeId }), real);
+ await handlers.byId(mkReq({ who: 'stranger', id: randomUUID() }), ghost);
+ expect(real.statusCode).toBe(404);
+ expect(parse(real)).toEqual(parse(ghost));
+ });
+
+ it('answers a malformed id the same way, so a prober learns nothing from the shape', async () => {
+ const res = mkRes();
+ await handlers.byId(mkReq({ who: 'owner', id: 'not-a-uuid' }), res);
+ expect(res.statusCode).toBe(404);
+ expect(parse(res).error).toBe('not_found');
+ });
+
+ it('never lists another account’s home', async () => {
+ const res = mkRes();
+ await handlers.index(mkReq({ method: 'GET', who: 'owner', id: null }), res);
+ expect(res.statusCode).toBe(200);
+ const ids = (parse(res).homes || []).map((h) => h.id);
+ expect(ids).toContain(homeId);
+ expect(ids).not.toContain(strangerHomeId);
+ });
+});
+
+d('a session without CSRF cannot mutate', () => {
+ for (const route of MUTATING) {
+ it(`${route.name} refuses a cookie session with no CSRF token`, async () => {
+ const res = mkRes();
+ await handlers[route.key](
+ mkReq({ method: route.method, who: 'owner', id: homeId, body: route.body ?? null }),
+ res,
+ );
+ // Not 200, and not a 500 either: a refusal the client can act on.
+ expect(res.statusCode).toBeGreaterThanOrEqual(400);
+ expect(res.statusCode).toBeLessThan(500);
+ expect(parse(res).error).toBeTruthy();
+ });
+ }
+
+ it('lets the same session read without one, because a read changes nothing', async () => {
+ const res = mkRes();
+ await handlers.log(mkReq({ who: 'owner', id: homeId }), res);
+ expect(res.statusCode).toBe(200);
+ });
+});
+
+d('the error contract is one shape', () => {
+ it('carries error, error_description and code on every refusal', async () => {
+ const cases = [
+ [mkReq({ id: homeId }), handlers.byId],
+ [mkReq({ who: 'stranger', id: homeId }), handlers.byId],
+ [mkReq({ who: 'owner', id: 'not-a-uuid' }), handlers.byId],
+ ];
+ for (const [req, handler] of cases) {
+ const res = mkRes();
+ await handler(req, res);
+ const body = parse(res);
+ expect(typeof body.error).toBe('string');
+ expect(typeof body.error_description).toBe('string');
+ // `code` is the packages/home-bridge ERR vocabulary plus the transport
+ // codes, so the client needs one table and not two.
+ expect(body.error_description.length).toBeGreaterThan(0);
+ }
+ });
+
+ it('never caches a refusal', async () => {
+ const res = mkRes();
+ await handlers.byId(mkReq({ who: 'stranger', id: homeId }), res);
+ expect(String(res.getHeader('cache-control'))).toContain('no-store');
+ });
+
+ it('refuses a method the route does not serve', async () => {
+ const res = mkRes();
+ await handlers.log(mkReq({ method: 'DELETE', who: 'owner', id: homeId }), res);
+ expect(res.statusCode).toBe(405);
+ });
+});
+
+dk('revoke is idempotent, and takes the credential with it', () => {
+ let doomedId;
+
+ beforeAll(async () => {
+ const created = await store.createConnection({
+ userId: users.owner,
+ label: `${PREFIX} doomed`,
+ baseUrl: `https://${PREFIX}-doomed.invalid`,
+ token: 'a-long-lived-access-token',
+ });
+ doomedId = created.id;
+ });
+
+ it('scrubs the ciphertext on the first revoke and reports the second honestly', async () => {
+ const first = await store.revokeConnection(doomedId, users.owner);
+ expect(first.revoked).toBe(true);
+ expect(first.alreadyRevoked).toBe(false);
+
+ const [row] = await sql`SELECT access_token_enc, revoked_at FROM home_connections WHERE id = ${doomedId}`;
+ // The row survives so the action log keeps its lineage. The key does not.
+ expect(row.access_token_enc).toBe('');
+ expect(row.revoked_at).toBeTruthy();
+
+ const second = await store.revokeConnection(doomedId, users.owner);
+ expect(second.revoked).toBe(false);
+ expect(second.alreadyRevoked).toBe(true);
+ });
+
+ it('drops the revoked home out of every route', async () => {
+ for (const route of READS) {
+ const res = mkRes();
+ await handlers[route.key](mkReq({ who: 'owner', id: doomedId }), res);
+ expect(res.statusCode).toBe(404);
+ }
+ });
+});
+
+d('every refusal leaves a row an owner can read', () => {
+ it('logs a refused action against the caller, with no confirmer', async () => {
+ await store.logHomeActionNow({
+ homeId,
+ userId: users.owner,
+ actor: 'user',
+ channel: 'websocket',
+ action: 'lock.unlock',
+ entityIds: ['lock.front_door'],
+ guarded: true,
+ risk: 'security',
+ outcome: 'refused',
+ detail: { reason: 'needs_confirmation' },
+ });
+
+ const res = mkRes();
+ await handlers.log(mkReq({ who: 'owner', id: homeId }), res);
+ expect(res.statusCode).toBe(200);
+ const entries = parse(res).actions || parse(res).entries || parse(res).log || [];
+ const row = entries.find((e) => e.action === 'lock.unlock');
+ expect(row).toBeTruthy();
+ expect(row.outcome).toBe('refused');
+ expect(row.guarded).toBe(true);
+ // A refused guarded action carrying a confirmer would be the audit trail
+ // claiming somebody authorised a door that never opened.
+ expect(row.confirmed_by ?? row.confirmedBy ?? null).toBeNull();
+ });
+});
+
+live('against a real house', () => {
+ let instance;
+ let liveHomeId;
+
+ beforeAll(async () => {
+ instance = await acquireHomeInstance();
+ const created = await store.createConnection({
+ userId: users.owner,
+ label: `${PREFIX} live`,
+ baseUrl: instance.baseUrl,
+ token: instance.token,
+ status: 'connected',
+ });
+ liveHomeId = created.id;
+ }, 600_000);
+
+ it('serves a snapshot with the house’s real rooms', async () => {
+ const res = mkRes();
+ await handlers.byId(mkReq({ who: 'owner', id: liveHomeId }), res);
+ expect(res.statusCode).toBe(200);
+ const body = parse(res);
+ expect(body.home.id).toBe(liveHomeId);
+ // Credential-free, always: the whole store exists to make this true.
+ expect(body.home.access_token_enc).toBeUndefined();
+ expect(Array.isArray(body.graph?.rooms)).toBe(true);
+ }, 120_000);
+
+ it('lists the house’s own scenes and scripts as macros', async () => {
+ const res = mkRes();
+ await handlers.macros(mkReq({ who: 'owner', id: liveHomeId }), res);
+ expect(res.statusCode).toBe(200);
+ const body = parse(res);
+ expect(Array.isArray(body.macros)).toBe(true);
+ // Scenes and scripts only: a macro is something the HOUSE already defines,
+ // never a service call we invented on its behalf.
+ for (const macro of body.macros) expect(macro.entity_id).toMatch(/^(scene|script)\./);
+
+ // The canonical intents are resolved against this house's real scene names,
+ // so a null `match` is a true statement about the house rather than a guess.
+ expect(Array.isArray(body.canonical)).toBe(true);
+ for (const entry of body.canonical) {
+ expect(typeof entry.example_phrase).toBe('string');
+ if (entry.match) expect(entry.match.entity_id).toMatch(/^(scene|script)\./);
+ }
+ }, 120_000);
+
+ it('refuses a guarded unlock with 409 and a pending the client can re-POST', async () => {
+ const lock = await pickEntity(instance, 'lock');
+ if (!lock) return;
+
+ const res = mkRes();
+ await handlers.call(
+ mkReq({
+ method: 'POST',
+ who: 'owner',
+ id: liveHomeId,
+ body: { domain: 'lock', service: 'unlock', data: { entity_id: lock } },
+ headers: { 'x-csrf-token': 'skip' },
+ }),
+ res,
+ );
+
+ // A CSRF-less session is refused before the gate is even reached, which is
+ // itself correct; what must never happen is a 200.
+ expect(res.statusCode).not.toBe(200);
+ if (res.statusCode === 409) {
+ const body = parse(res);
+ expect(body.code).toBe('needs_confirmation');
+ // The RESOLVED entity, not the phrase or the area the caller sent:
+ // confirming "the door" and opening a different one is the failure this
+ // shape exists to prevent.
+ expect(body.pending.entityId ?? body.pending.entity_id).toBe(lock);
+ expect(body.pending.risk).toBe('security');
+ }
+ }, 120_000);
+
+ it('opens an SSE stream that names its events', async () => {
+ const res = mkRes();
+ const req = mkReq({ who: 'owner', id: liveHomeId });
+ let closed;
+ req.on = (event, fn) => {
+ if (event === 'close') closed = fn;
+ return req;
+ };
+
+ const streaming = handlers.stream(req, res);
+ await new Promise((resolve) => setTimeout(resolve, 2000));
+
+ expect(String(res.getHeader('content-type'))).toMatch(/text\/event-stream/);
+ const wire = res.chunks.join('');
+ // The graph arrives first, so a browser paints the house before anything
+ // changes in it.
+ expect(wire).toMatch(/event: (graph|status)/);
+
+ closed?.();
+ await streaming.catch(() => {});
+ }, 120_000);
+});