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
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.jsindex 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_TIMareaCount: 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.jsindex 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.mddeleted file mode 100644index 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.jsnew file mode 100644index 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);+});