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.

docs(home): record what the connection store landed and retire its order file

nirholasd6d7ccdf74ec
diff --git a/prompts/finish/home-01-connection-store.md b/prompts/finish/home-01-connection-store.md
deleted file mode 100644
index ac4cfebc2..000000000
--- a/prompts/finish/home-01-connection-store.md
+++ /dev/null
@@ -1,189 +0,0 @@
-# 01. Connection store: schema, encrypted credentials, lifecycle
-
-**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; this file assumes it and
-does not repeat the architecture or the security rule.
-
-## 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. Every architectural decision here is already made; if you
-disagree with one, implement it and say so in your report rather than stopping to relitigate it.
-
-**Nothing in this file is a status claim to trust.** Step 0 re-measures.
-
----
-
-## Step 0: re-derive the current state
-
-```bash
-npx vitest run packages/home-bridge # the client library: expect 30 passed, 6 skipped
-ls api/_lib/migrations | grep -i home # expect nothing yet
-grep -rn "home_connections" api/ --include=*.js -l # expect nothing yet
-npm run db:status # READ IN FULL before touching the schema
-node -e "import('./api/_lib/secret-box.js').then(m=>console.log(Object.keys(m)))"
-node scripts/read-service-env.mjs '^WALLET_ENCRYPTION_KEY$' --names 2>/dev/null || echo "run this where gcloud is available"
-```
-
-`npm run db:migrate` applies **every** pending migration in `api/_lib/migrations/`, not only
-yours, and there is no dry run. Read `db:status` output in full first.
-
-## What this order owns
-
-The record of "this user has connected this home", the credential that makes it work, and the
-lifecycle around it. Nothing above the store: no endpoints (order 03), no runtime (order 02).
-
-## The schema
-
-One migration, `api/_lib/migrations/<UTC timestamp>_home_connections.sql`. Follow the header
-style of the neighbouring migrations: a comment block stating what the table is, why each
-non-obvious column exists, and which decisions were considered and rejected.
-
-### `home_connections`
-
-| Column | Type | Notes |
-|---|---|---|
-| `id` | `uuid primary key default gen_random_uuid()` | |
-| `user_id` | `uuid not null references users(id) on delete cascade` | the owner. Household membership arrives in order 12 and must not require a rewrite of this column. |
-| `label` | `text not null` | what the user calls it ("Home", "The office"). User-supplied, so treat as untrusted on render. |
-| `base_url` | `text not null` | normalized by `normalizeBaseUrl` before write. Store the normalized form, never the raw input. |
-| `access_token_enc` | `text not null` | `encryptSecret()` output. **Never** a plaintext token, never a hash (we must replay it). |
-| `token_fingerprint` | `text not null` | `sha256(token)` hex, so a re-connect with the same token is idempotent and a rotation is detectable without decrypting. |
-| `transport` | `text not null default 'direct'` | `direct` or `relay` (order 10). Constrained by a check. |
-| `relay_id` | `text` | null for `direct`. |
-| `capabilities` | `jsonb not null default '{}'` | measured at connect: `{ websocket: true, mcp: true, mcpToolCount: 29, haVersion: '2026.9.0' }`. Measured, never assumed. |
-| `status` | `text not null default 'pending'` | `pending`, `connected`, `unreachable`, `auth_failed`, `revoked`. Constrained by a check. |
-| `status_detail` | `text` | the last human-readable reason, for the UI to show without a second call. |
-| `last_ok_at` | `timestamptz` | last successful handshake. |
-| `last_error_at` | `timestamptz` | |
-| `created_at` / `updated_at` | `timestamptz not null default now()` | |
-| `revoked_at` | `timestamptz` | soft delete. A revoked row keeps its audit lineage; the ciphertext is scrubbed to `''` on revoke. |
-
-Indexes: `(user_id) where revoked_at is null`, and a unique `(user_id, base_url) where revoked_at
-is null` so one user cannot silently hold two live records for the same house.
-
-### `home_entity_grants`
-
-The standing per-entity allowances from the safety gate. **Per entity and per direction, never
-per domain.**
-
-| Column | Type | Notes |
-|---|---|---|
-| `id` | `uuid primary key default gen_random_uuid()` | |
-| `home_id` | `uuid not null references home_connections(id) on delete cascade` | |
-| `entity_id` | `text not null` | e.g. `lock.office_door`. |
-| `granted_by` | `uuid not null references users(id)` | who said yes. |
-| `expires_at` | `timestamptz` | null means until revoked. The UI must offer a bounded option. |
-| `created_at` | `timestamptz not null default now()` | |
-
-Unique on `(home_id, entity_id)`.
-
-**Rejected, with the reason, in the migration header:** a `granted_domain` column. A user who
-lets the agent open the office door has not let it open the front door, and a domain grant is
-exactly the mistake that turns a convenience into a burglary tool.
-
-### `home_action_log`
-
-Every write the platform performs against a house. This is not the general `audit_log`: it is
-higher volume, it carries the physical-action verdict, and an operator has to be able to answer
-"what did my agent do in my house last Tuesday" without a join across a shared table.
-
-| Column | Type | Notes |
-|---|---|---|
-| `id` | `bigserial primary key` | |
-| `home_id` | `uuid not null references home_connections(id) on delete cascade` | |
-| `user_id` | `uuid` | null when the actor is an agent principal with no account. |
-| `actor` | `text not null` | `user`, `agent`, `voice`, `mcp`, `automation`. |
-| `channel` | `text not null` | `websocket` or `mcp`. |
-| `action` | `text not null` | `light.turn_on`, or the MCP tool name. |
-| `entity_ids` | `text[] not null default '{}'` | resolved targets, not the raw argument. |
-| `guarded` | `boolean not null default false` | did the gate fire. |
-| `confirmed_by` | `uuid` | who said yes, when it did. |
-| `risk` | `text` | `security`, `physical`, or null. |
-| `outcome` | `text not null` | `ok`, `refused`, `failed`. |
-| `detail` | `jsonb` | small. No secrets, no full state dumps. |
-| `created_at` | `timestamptz not null default now()` | |
-
-Index `(home_id, created_at desc)`. Retention is order 15's job; leave the column set it needs.
-
-## The store module
-
-New file `api/_lib/home/store.js`. Every function takes and returns plain objects; no HTTP, no
-Home Assistant, no `res`.
-
-| Export | Contract |
-|---|---|
-| `createConnection({ userId, label, baseUrl, token, transport, relayId })` | normalizes the URL, encrypts the token, computes the fingerprint, upserts on the unique key, returns the row **without** any credential field. |
-| `listConnections(userId)` | live rows only, credential-free, newest first. |
-| `getConnection(id, userId)` | ownership-checked. Returns null rather than throwing on a miss, and never leaks existence across users. |
-| `getDecryptedToken(id, userId)` | the ONLY function that returns plaintext. Its own export so every call site is greppable. |
-| `recordHandshake(id, { status, statusDetail, capabilities })` | updates status, `last_ok_at` / `last_error_at`, capabilities. |
-| `revokeConnection(id, userId)` | sets `revoked_at`, scrubs `access_token_enc` to `''`, writes an audit row. Idempotent. |
-| `grantEntity({ homeId, entityId, grantedBy, expiresAt })` / `revokeGrant` / `listGrants(homeId)` | the allowance table. `listGrants` filters expired rows in SQL, not in JS. |
-| `logHomeAction(entry)` | fire and forget, mirroring [`api/_lib/audit.js`](../../api/_lib/audit.js): never throws, never blocks a response. |
-
-Rules the module enforces, not its callers:
-
-- A row is never returned with `access_token_enc` on it. Build the safe projection in SQL.
-- Ownership is a `WHERE user_id = $1` in every query, never a check in JS after a fetch.
-- `getDecryptedToken` writes nothing and logs nothing containing the token. `scrub-secrets.js`
- exists in `api/_lib/`; read it before you log anything near a credential.
-
-## Tasks, in risk order
-
-| # | Task | Files |
-|---|---|---|
-| 1 | Write the migration. Read `npm run db:status` in full, then apply with `npm run db:migrate`. | `api/_lib/migrations/<ts>_home_connections.sql` |
-| 2 | The store module with every export above. | `api/_lib/home/store.js` |
-| 3 | Connection verification: a `verifyConnection({ baseUrl, token })` that opens a real `HomeBridge`, reads the capabilities (HA version, entity count, whether `mcp_server` answers and with how many tools), closes it, and returns the measured capability object. Never guesses a capability. | `api/_lib/home/verify.js` |
-| 4 | Tests against a real instance and against the recorded fixture. | `tests/home-store.test.js` |
-| 5 | Wire `home_connections` into the credential inventory if one exists (`grep -rn "WALLET_ENCRYPTION_KEY" docs/ scripts/`), so the next key rotation covers these rows. | as found |
-
-## Definition of done
-
-Every line mechanically checkable. Paste the command output into your report.
-
-- [ ] `npm run db:status` reports the home migration applied and nothing of yours pending.
-- [ ] `grep -rn "access_token_enc" api/ --include=*.js` shows reads only inside `api/_lib/home/store.js`.
-- [ ] `grep -rn "getDecryptedToken" api/ --include=*.js` shows exactly the call sites you intend.
-- [ ] A round trip proves the credential path: create a connection against a live local HA, read it back, confirm the returned row has no credential field, then `getDecryptedToken` and open a real `HomeBridge` with it that connects.
-- [ ] `revokeConnection` twice in a row succeeds both times and leaves `access_token_enc = ''`.
-- [ ] `listConnections` for user B never returns user A's row; `getConnection(A.id, B.id)` returns null.
-- [ ] A grant for `lock.office_door` does not clear the gate for `lock.front_door`. Assert it.
-- [ ] An expired grant is filtered by the SQL, proved with a row whose `expires_at` is in the past.
-- [ ] `npx vitest run tests/home-store.test.js packages/home-bridge` passes.
-- [ ] `npm run check:rules -- --paths <your files>` is clean.
-- [ ] `STRUCTURE.md` gains nothing yet (no user surface), but `docs/smart-home.md` phase 1 is updated to say the store landed.
-
-## Never blocked
-
-| Blocker | Do this |
-|---|---|
-| `WALLET_ENCRYPTION_KEY` is not set locally | `secret-box.js` falls back to `JWT_SECRET` with a one-time warning, so local development works. Production has it. Do not invent a second key or store plaintext. |
-| `db:status` says pending migrations you did not write | Read them. Apply if unrelated and safe; that is the command's normal behaviour. Stop only on something destructive. |
-| The unique `(user_id, base_url)` constraint fights a legitimate case | Two records for the same URL under one user is the case it exists to prevent. If a real need appears (two accounts on one HA), the second dimension is the token fingerprint, not dropping the constraint. |
-| You want to store the room graph in Postgres | Do not. It is a live projection of a live socket and it goes stale the moment a light changes. Order 02 owns the in-memory cache. |
-| Encrypting feels like it can wait | It cannot. A home access token is a key to a physical building. It gets the same primitive as a custodial wallet key, on the first commit. |
-
-## Report format
-
-1. The `db:status` output before and after.
-2. The credential round-trip transcript (create, read back credential-free, decrypt, connect).
-3. The isolation proof (user B cannot see user A's home).
-4. The grant scoping proof.
-5. Test output, verbatim.
-6. Anything in this file you found to be wrong, and what you changed it to.
-
-## Retire this prompt when it is done (required)
-
-1. Verify every Definition of done line against actual command output in front of you.
-2. Append the outcome to `prompts/finish/home-PROGRESS.md` (create it if this is the first order
- to finish, following the format of a sibling `-PROGRESS.md`).
-3. Commit with explicit paths and a subject that describes the diff, and delete this file in that
- same commit:
-
- git rm prompts/finish/home-01-connection-store.md
-
-If a line genuinely cannot pass inside this session, finish everything else, leave this file in
-place, and state exactly which line remains and who owns it. Never delete this file on a partial.
diff --git a/prompts/finish/home-PROGRESS.md b/prompts/finish/home-PROGRESS.md
index 68e13539e..e4407083b 100644
--- a/prompts/finish/home-PROGRESS.md
+++ b/prompts/finish/home-PROGRESS.md
@@ -30,7 +30,7 @@ One section per finished order, newest at the bottom:
| Order | State | Finished |
|---|---|---|
| 00 CONTEXT | shared facts | n/a |
-| 01 connection store | open | |
+| 01 connection store | done | 2026-09-03 |
| 02 bridge runtime | open | |
| 03 API surface | open | |
| 04 agent tools | open | |
@@ -165,3 +165,82 @@ after this run, so two lines above are already stale and one is not:
run (`tests/home-privacy.test.js`, `tests/home-runtime.test.js`, `tests/audit-guards.test.js`)
and one in another; the first two pass in isolation. They read `api/_lib/migrations/` and the
guard registry from disk, and peers mutate both mid-run. Re-run the suite when the lane is quiet.
+
+
+## 01. Connection store: schema, encrypted credentials, lifecycle (2026-09-03)
+
+**Shipped:** `home_connections`, `home_entity_grants` and `home_action_log` exist and are
+applied (`20260903030000_home_connections.sql`). A house is one row: the normalized base URL,
+the Home Assistant long-lived token sealed with the same AES-256-GCM primitive as a custodial
+wallet key, a sha256 fingerprint so a re-connect is idempotent and a rotation is detectable
+without decrypting, and capabilities MEASURED at connect. Grants are per entity with no
+`granted_domain` column, and the migration header records why: letting the agent open the
+office door is not letting it open the front door. `api/_lib/home/store.js` is the only module
+that reads the credential column and `getDecryptedToken` is the only function that returns
+plaintext. `api/_lib/home/verify.js` opens a real bridge and measures the instance.
+`tests/home-store.test.js` covers all of it in three tiers. Two schema constraints beyond the
+order's table caught real bugs in review: `home_connections_relay_chk` (a relay row must carry
+a relay id) and `home_action_log_risk_chk`. Connected homes are now named in the key-rotation
+runbook alongside custodial wallets, with `scripts/audit-home-credential-health.mjs` as their
+own reading, because a sealed home has no on-chain balance to notice it by.
+
+**Measured:**
+
+- `npm run db:status`: 1 pending before, `All migrations already applied` after. No other
+ agent's migration was pending at the time it ran.
+- `npx vitest run tests/home-store.test.js packages/home-bridge` against a real Neon database
+ and the lane's seeded Home Assistant (`node scripts/home-test-instance.mjs --up --onboard
+ --seed --name lane`, HA 2026.9.0, 120 entities, 3 areas, 1 floor): **65 passed, 0 skipped.**
+ Without live env: 37 passed, 28 skipped.
+- Credential round trip, live: created a connection from a typed URL with a trailing slash,
+ read the row back with no credential field on it and no token anywhere in its JSON, confirmed
+ the stored ciphertext starts `v2:`, decrypted it and opened a real `HomeBridge` that connected
+ and built a room graph.
+- Isolation: `listConnections(B)` returned `[]` against A's live home, `getConnection(A.home, B)`
+ and `getDecryptedToken(A.home, B)` both returned null, and B's revoke of A's home reported
+ `alreadyRevoked: false` rather than acting.
+- Grant scoping: with only `lock.kitchen_door` granted, a live bridge unlocked it with no prompt
+ and refused `lock.front_door` with `code: 'needs_confirmation'` in the same session;
+ `lock.front_door` read back `locked`.
+- Expiry: a grant with `expires_at` an hour in the past sits in the table and never appears in
+ `listGrants`, proved by counting both.
+- Revoke: twice in a row, `{revoked:true}` then `{revoked:false, alreadyRevoked:true}`,
+ `access_token_enc = ''`, `status = 'revoked'`, action log intact, and the same house
+ connectable again as a new row.
+- `grep -rn "access_token_enc" api/ --include=*.js`: the only READS are in
+ `api/_lib/home/store.js`. `grep -rn "getDecryptedToken" api/ --include=*.js`: the definition
+ plus `api/_lib/home/runtime.js`, which is order 02's pool.
+- `npm run check:rules` clean on every file touched. `npm run audit:docs`: one finding, and it
+ is `packages/home-mcp` missing a README (order 18's directory, not this one's).
+
+**Deviations:**
+
+- The order's `verifyConnection` sketch left the HA version to be read off entity attributes.
+ Measured against a real instance that returns an integration's `installed_version`, not the
+ core version. It reads `/api/config` instead, and the test asserts equality with what that
+ endpoint returns rather than merely that a version is present.
+- The order's index sketch was `(user_id) where revoked_at is null`. Shipped as
+ `(user_id, created_at desc) where revoked_at is null`, a superset, because the list view's only
+ read shape is one user's homes newest first.
+- The order's live round trip used `<base>/lovelace/` as a "messy" input. It is not messy:
+ `normalizeBaseUrl` deliberately KEEPS a path so an instance behind a reverse proxy prefix
+ works, so that input stores a different house. The package's own doc comment claimed the
+ opposite and has been corrected (`packages/home-bridge/src/url.js`).
+- Task 5's "credential inventory" does not exist as a list of ciphertext columns. What exists is
+ the rotation runbook plus a wallet-specific health module whose numbers are SOL totals, which
+ home tokens have none of. Wired as a new section in `docs/ops/wallet-key-migration.md` and a
+ real read-only audit rather than a row in a table that was not there.
+- The order's "Never blocked" row says `secret-box.js` falls back to `JWT_SECRET` locally. In
+ this workspace `.env.local` carries only `DATABASE_URL`, so neither key is set and
+ `encryptSecret` throws. Local runs need a `WALLET_ENCRYPTION_KEY` in the environment; nothing
+ in the code changed for it.
+
+**Left open:** nothing in this order. Two observations for whoever owns them: `api/_lib/home/relay.js`
+writes `access_token_enc` as an intentional empty string when it creates a pending relay row, which
+is correct but means the audit had to learn that a relay home awaiting pairing is not a sealed one;
+and there are leftover `home_connections` rows in the production database from other agents' local
+test runs, sealed under their local keys, which the audit reports honestly.
+
+**Commits:** the schema, store, verify, tests and audit script were swept into concurrent agents'
+`git add -A` commits as they landed (`c3132956a`, `858a2f86b` among them); this entry and the
+retirement of the order file are the final commit.