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.

feat(home): let a household reach a home, not just the account that connected it

nirholas51b103b1ac35
diff --git a/docs/home-households.md b/docs/home-households.md
new file mode 100644
index 000000000..431801a0e
--- /dev/null
+++ b/docs/home-households.md
@@ -0,0 +1,315 @@
+# Households: members, roles and per-member scopes
+
+A house has more than one person in it. Before this landed, the account that connected a home was
+the only way into it, which left exactly two options: share one login (the worst possible outcome
+for a system that opens doors) or let one person use the product. For a hotel, an office or a
+serviced building, the roles and the attribution are the entire purchase decision.
+
+This document is the contract. It covers the five roles, what each one may do, how a scoped member
+sees a narrowed house, how invitations work, and what happens to somebody's access when they leave.
+
+Related: [smart-home.md](smart-home.md) for why three.ws writes zero device code and what the Home
+Assistant bridge does.
+
+---
+
+## The rule everything else hangs off
+
+**A guest can never confirm a guarded action.**
+
+Home Assistant's published description of its own `intent__HassTurnOff` tool reads: *"Turns
+off/closes a device or entity. For locks, this performs an 'unlock' action."* Verified against a
+live instance with a lock exposed to Assist: an agent told to turn something off really does open
+the front door, and nothing in the tool name says so.
+
+So "turn the lights off" and "open the building" are the same call with different targets, and the
+only thing separating them is who is allowed to say yes. A house sitter should be able to turn the
+lights on. A house sitter should not be able to authorise unlocking the front door. That single
+distinction is why this table exists, and it is enforced on the server, once, in
+`api/_lib/home/members.js`.
+
+## The five roles
+
+| Role | Read state | Ungated actions | Confirm a guarded action | Grant standing allowances | Edit layout | Invite | Manage connection | Disconnect |
+|---|---|---|---|---|---|---|---|---|
+| `owner` | whole house | yes | yes | yes | yes | yes | yes | yes |
+| `admin` | whole house | yes | yes | yes | yes | yes | yes | no |
+| `member` | whole house | yes | yes | no | yes | no | no | no |
+| `guest` | scoped | scoped | **no** | no | no | no | no | no |
+| `viewer` | scoped | no | no | no | no | no | no | no |
+
+Read it as the product decision it is:
+
+- **`owner`** connected the house. Exactly one per home, enforced by a partial unique index, which
+ is what makes "you cannot remove the last owner" a schema fact instead of a check somebody
+ forgets. Ownership is never assignable and never invitable; transferring it is an update of that
+ one row.
+- **`admin`** runs the household and cannot take the house off the platform. An admin may add a
+ peer admin and may not remove one; only the owner can. You can hire, you cannot fire your equals.
+- **`member`** lives here. Acts, confirms, arranges the layout. Cannot hand out access and cannot
+ leave a standing allowance behind, because a permanent yes to unlocking something should come
+ from the person who owns the risk.
+- **`guest`** is visiting. Scoped, and never a confirmation.
+- **`viewer`** is a wall display or a monitoring seat. Scoped, and reads only.
+
+**Custom roles are deliberately out of scope.** Five cover households, house sitters, offices and
+hotels. Anything past that needs a policy engine with its own evaluation order, conflict rules and
+audit surface, which is a different product than "let my partner turn the lights on".
+
+## Capabilities, not role strings
+
+Every enforcement point names a capability rather than testing a role, so adding a role is a change
+to one table and not a grep across the codebase. The vocabulary is `read`, `act`, `confirm`,
+`grant`, `layout`, `invite`, `manage`, `disconnect`.
+
+`grant`, `invite` and `manage` are held by the same two roles today and are still three names.
+They are powers over different things (a lock, the roster, the connection), and collapsing them
+would mean a future role could not hold one without the others.
+
+```js
+import { requireMembership } from '../_lib/home/members.js';
+
+const gate = await requireMembership(homeId, user.id, 'confirm');
+if (!gate.ok) return error(res, gate.status, gate.code, gate.reason);
+// gate.role the role this caller holds
+// gate.scope {mode:'all'} or {mode:'allow', areas:[], entities:[]}
+```
+
+`requireMembership` returns a result rather than throwing, because the two failure modes need
+different answers:
+
+| Outcome | Status | Meaning |
+|---|---|---|
+| `{ok: true, role, scope, membership}` | | the caller holds the capability |
+| `{ok: false, code: 'home_not_found'}` | 404 | not a member, or no such home, or the home was revoked |
+| `{ok: false, code: 'role_forbidden', role, capability, reason}` | 403 | a member, but this role may not do this |
+
+**404 and never 403 for a non-member.** A stranger must not be able to learn that a home id is
+real, so "you are not in this household" and "that home does not exist" are the same answer. A
+member who lacks a capability gets 403 naming their role, because a guest refused an unlock
+deserves to be told it is their role and not a broken door.
+
+## Entity scope
+
+`guest` and `viewer` carry an allowlist of areas and entities:
+
+```json
+{ "mode": "allow", "areas": ["kitchen"], "entities": ["light.hall_lamp"] }
+```
+
+`{"mode":"all"}` is the whole house, and it is what every non-scoped role gets. Promoting a guest to
+a member normalizes their scope to `{"mode":"all"}` in the same statement, so a stale allowlist
+cannot silently keep narrowing somebody who was widened.
+
+There is no domain form (`"all locks"`), for the same reason `home_entity_grants` refused a
+`granted_domain` column: a scope that names a domain is a scope nobody can reason about at the
+moment they grant it, and a user who let the agent open the office door has not let it open the
+front door.
+
+### Scope is enforced in the projection, never in the UI
+
+`filterGraphForScope(graph, scope)` runs server side, before serialization. Three things happen and
+all three matter:
+
+1. **Rooms the member was not given are removed, not marked.** A room whose name reached the client
+ has been disclosed. A `visible: false` flag would be a leak with a checkbox on it.
+2. **In a room reached through a single entity grant, the room's rollups are recomputed.** The
+ unfiltered hall reports two lights with one on; a guest who was given one lamp sees one light
+ with none on. Leaving the original rollup would report the state of exactly the entities the
+ filtering just removed.
+3. **Floors with no visible room are removed**, because the floor list is the shape of the building.
+
+For actions rather than reads, `outOfScopeEntities(scope, targets)` names every resolved target
+that falls outside the scope. Pass it the RESOLVED entities, not the raw argument: an area name or
+a device id in a request expands to the entities it actually touches, and that expansion is the
+only form that answers "did it open the front door".
+
+## Where it is enforced
+
+Membership resolution replaced `user_id` equality in the store, so every surface above it became
+membership-aware at once rather than each one growing its own check.
+
+| Point | Where | How |
+|---|---|---|
+| Store reads | `api/_lib/home/store.js` | `getConnection`, `listConnections` and `getDecryptedToken` join `home_members`. Each row comes back carrying `role` and `entity_scope`. There is deliberately no `or user_id = ...` beside the join. |
+| Bridge runtime | `api/_lib/home/runtime.js` | `acquire` reads the home and its token through those two store functions, so it inherits membership without a check of its own |
+| REST routes | `api/_lib/home/access.js` | `resolveHomeAccess(req, res, homeId, capability)` is the single door. It returns `role` and `scope`, refuses a non-member 404 and a member without the capability 403 |
+| Room graph | `api/home/[id].js`, `api/home/[id]/stream.js` | `filterGraphForScope` runs before serialization, on the single read and on every streamed frame |
+| The gate | `api/home/[id]/call.js` | `confirmed: true` from a role without `confirm` is refused before the socket is acquired, and an out-of-scope target is refused against the live graph |
+| Scenes | `api/home/[id]/activate.js` | needs `act`; a scoped role is refused outright, because a scene reaches the whole house and a half-run scene is worse than none |
+| Confirmation redemption | `api/home/[id]/confirm.js` | needs `confirm`; bearer principals are refused before authentication |
+| Chat and MCP tools | `api/_lib/home/tools.js` | a bearer principal inherits the role of the account whose token it is, through `requireMembership` |
+| Action log | everywhere it is written | `user_id` is the acting member, never the connection's owner |
+
+Route by route:
+
+| Route | Capability |
+|---|---|
+| `GET /api/home` | membership list (every home this account is in, each with its role) |
+| `GET /api/home/:id` | `read` |
+| `DELETE /api/home/:id` | `disconnect` |
+| `GET /api/home/:id/stream` | `read` |
+| `GET /api/home/:id/log`, `/macros` | `read` |
+| `POST /api/home/:id/call`, `/activate` | `act`, plus `confirm` when the body carries `confirmed: true` |
+| `POST /api/home/:id/confirm` | `confirm` |
+| `GET /api/home/:id/grants` | `read` |
+| `POST`, `DELETE /api/home/:id/grants` | `grant` |
+| `/api/home/pair` on an existing home | `manage` |
+| `GET /api/home/:id/members` | `read` |
+| `POST`, `PATCH`, `DELETE /api/home/:id/members` | `invite` |
+
+`resolveHomeAccess` defaults to `read`, which is the safe default and also a silent one: a new
+route that writes to a house and forgets to name a capability would be admitted to a viewer.
+`tests/home-roles.test.js` reads every call site under `api/home/` and fails if any of them omits
+it, because that omission is invisible at runtime until somebody exploits it.
+
+## Invitations
+
+An invite is an email address plus a link: single use, expiring (7 days by default), and bound to
+one home and one role.
+
+- **The plaintext token leaves the server exactly once**, in the `invite_url` of the creating
+ response. What is stored is `sha256` of it. An invite is a bearer credential for a role in a
+ building, so a leaked database must not be a set of working keys.
+- **Single use is enforced in the redeeming UPDATE's own WHERE clause**, not by a read followed by
+ a write, so two people opening the same link at the same moment cannot both become members.
+- **Accepting requires an account, and this endpoint does not create one.** Registration and
+ sign-in already exist, they carry the captcha, the password rules and the session handling, and a
+ second door into account creation is a second door to keep secure. An unauthenticated POST
+ answers 401 with the invite intact, so a client can send the visitor through `/register` and
+ bring them back to the same link.
+- **A re-invite to the same address replaces the outstanding one** rather than stacking a second
+ working key.
+- **An account that is already in the household keeps the role it has.** An invite is a way in, not
+ a way to be quietly demoted (or promoted) by a stale link. Use the roster `PATCH` to change
+ somebody's role.
+- **Ownership is never invitable.** `createInvite` throws on `role: 'owner'` and the schema's check
+ constraint refuses the row.
+
+## Removing somebody
+
+`removeMember` deletes the membership row **and every standing allowance that member authorised, in
+one transaction.** The two halves are inseparable: a standing allowance is a permanent yes to
+unlocking one specific thing, recorded against the account that said it. Leaving a removed member's
+allowances in place means the front door still opens on the authority of somebody who no longer
+lives there, and nothing in any UI would ever show it.
+
+```
+before after
+lock.office_door granted by Sam lock.front_door granted by the owner
+cover.garage granted by Sam
+lock.front_door granted by the owner
+```
+
+## The API
+
+| Method | Path | Capability | What it does |
+|---|---|---|---|
+| `GET` | `/api/home/:id/members` | `read` | the roster, the outstanding invitations, and the matrix |
+| `POST` | `/api/home/:id/members` | `invite` | invite an email address to a role and scope |
+| `PATCH` | `/api/home/:id/members` | `invite` | change a member's role or scope |
+| `DELETE` | `/api/home/:id/members` | `invite` | remove a member (`user_id`) or withdraw an invitation (`invite_id`) |
+| `GET` | `/api/home/invites/:token` | none | what this link is for, without spending it |
+| `POST` | `/api/home/invites/:token` | account | redeem it and join the household |
+
+Reading the roster is a plain `read` capability on purpose: you should be able to see who else holds
+keys to the house you are in.
+
+Creating an invite:
+
+```bash
+curl -X POST https://three.ws/api/home/$HOME_ID/members \
+ -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
+ --cookie "__Host-sid=$SESSION" \
+ -d '{"email":"[email protected]","role":"guest",
+ "scope":{"mode":"allow","areas":["kitchen"],"entities":["light.hall_lamp"]}}'
+```
+
+```json
+{
+ "invite": { "id": "...", "email": "[email protected]", "role": "guest",
+ "scope": { "mode": "allow", "areas": ["kitchen"], "entities": ["light.hall_lamp"] },
+ "expires_at": "2026-09-10T03:31:52.462Z" },
+ "invite_url": "https://three.ws/home/join?invite=BBQFpFGdBbULN9KQUhbIfw0SiFA0DDbPx1iFFpx2Lng"
+}
+```
+
+The refusals, in full:
+
+| Situation | Status | Code |
+|---|---|---|
+| not a member of this home | 404 | `home_not_found` |
+| a member, but the role lacks the capability | 403 | `role_forbidden` |
+| an admin acting on the owner row | 403 | `role_forbidden` |
+| an invite link that was never issued | 404 | `invite_not_found` |
+| an invite already redeemed | 410 | `invite_spent` |
+| an invite past its expiry | 410 | `invite_expired` |
+| an invite withdrawn before use | 410 | `invite_revoked` |
+| the home was disconnected | 410 | `home_revoked` |
+
+## Attribution
+
+`home_action_log.user_id` is the **acting member**, always, and never the connection's owner. Two
+people acting in one house produce two rows under two ids, and a refused guarded action records the
+refusal with `confirmed_by` null: an audit trail that named a confirmer for an action nobody
+confirmed would be lying about who opened a door.
+
+Roster changes (invite, role change, invitation withdrawn, member removed, invitation accepted) go
+to the general `audit_log` as `household.*` actions, because they are writes against the household
+and not against the house.
+
+## SSO and the enterprise case
+
+three.ws has SAML SSO at `/api/auth/saml/*` (login, ACS, logout). Households work with it, with one
+honest limitation.
+
+**SAML group claims are not available.** Measured, not assumed: `extractSamlIdentity` in
+`api/_lib/saml.js` returns `{issuer, nameID, nameIDFormat, email, name, sessionIndex}` and nothing
+else. It checks the common spellings for email, display name, given name and surname, and every
+other attribute in the assertion is dropped before the handler sees it. There is no `GROUP_KEYS`
+list and no group plumbing anywhere below it.
+
+So there is no role mapping to implement, and half-wiring one that cannot be tested against a real
+IdP would be worse than not having it. **A SAML-authenticated user joins a household through the
+same invite path as everybody else**, and their role is set by a person who already administers the
+home. For an office rolling out to a floor of people, that is one invite per person, or one shared
+link per role sent to a distribution list.
+
+If group-based provisioning becomes a requirement, the work is: collect group attributes in
+`extractSamlIdentity` (add a `GROUP_KEYS` list beside the existing ones and return the matches),
+store a per-issuer group-to-role mapping, and apply it at ACS time. That is a real feature with a
+real test surface, and it needs an IdP to test against. It is not a line of glue.
+
+### Deprovisioning
+
+**Membership outlives a session, so revoking sessions is not enough.** An account with a `guest` row
+in somebody's house still has standing access to a building after every one of its sessions is
+gone, and any standing allowance it left behind still opens a lock on its authority.
+
+`revokeAllMemberships(userId)` is the half that reaches the houses. It removes the account from
+every household it is a member of, deletes every standing allowance it authorised anywhere, and
+revokes any invitation it accepted. It is wired into account deletion in `api/auth/[action].js`,
+beside the session and refresh-token revocation.
+
+**Owner rows are left alone.** An owner's home is their own record, and cascading a deprovision into
+deleting somebody's house is not a decision a webhook gets to make. Their allowances are still
+revoked.
+
+SAML has no SLO endpoint and no SCIM provisioning here, so upstream-initiated deprovisioning is not
+automatic today: an IdP deactivating a user stops them signing in and does not by itself reach
+`home_members`. Call `revokeAllMemberships` from whatever path removes the account.
+
+## Where the code is
+
+| Piece | File |
+|---|---|
+| Schema, backfill, the owner trigger | `api/_lib/migrations/20260903130000_home_members.sql` |
+| The role matrix, scope, invitations, deprovisioning | `api/_lib/home/members.js` |
+| The roster endpoint | `api/home/[id]/members.js` |
+| Invite redemption | `api/home/invites/[token].js` |
+| The matrix as an executable test | `tests/home-roles.test.js` |
+
+The owner row is created by a database trigger on `home_connections`, not by the application. "A
+connection has an owner" is an integrity fact about the data rather than a step in one code path, so
+it holds for every writer: the connection store, a future admin tool, a support script, a manual
+insert. A home can never exist in a state where nobody can administer it.
diff --git a/tests/home-roles.test.js b/tests/home-roles.test.js
index 7308f6047..349fd7dd5 100644
--- a/tests/home-roles.test.js
+++ b/tests/home-roles.test.js
@@ -34,11 +34,11 @@ const email = (who) => `${PREFIX}+${who}@example.invalid`;
/** The order 12 table, transcribed. Rows are roles, columns are capabilities. */
const EXPECTED = {
- owner: { read: true, act: true, confirm: true, grant: true, layout: true, invite: true, disconnect: true },
- admin: { read: true, act: true, confirm: true, grant: true, layout: true, invite: true, disconnect: false },
- member: { read: true, act: true, confirm: true, grant: false, layout: true, invite: false, disconnect: false },
- guest: { read: true, act: true, confirm: false, grant: false, layout: false, invite: false, disconnect: false },
- viewer: { read: true, act: false, confirm: false, grant: false, layout: false, invite: false, disconnect: false },
+ owner: { read: true, act: true, confirm: true, grant: true, layout: true, invite: true, manage: true, disconnect: true },
+ admin: { read: true, act: true, confirm: true, grant: true, layout: true, invite: true, manage: true, disconnect: false },
+ member: { read: true, act: true, confirm: true, grant: false, layout: true, invite: false, manage: false, disconnect: false },
+ guest: { read: true, act: true, confirm: false, grant: false, layout: false, invite: false, manage: false, disconnect: false },
+ viewer: { read: true, act: false, confirm: false, grant: false, layout: false, invite: false, manage: false, disconnect: false },
};
/** Roles whose reads and actions are narrowed by entity_scope. */
@@ -62,6 +62,11 @@ async function makeUser(who) {
async function sweep() {
await sql`DELETE FROM home_connections WHERE label LIKE ${`${PREFIX}%`}`;
+ // Sessions and audit rows are keyed on the user rather than the home, so they
+ // do not follow the connection's cascade and have to be named here. Without
+ // this the suite leaves a session behind on every run.
+ 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}+%`}`;
}
@@ -584,6 +589,101 @@ d('the action log attributes every action to the member who acted', () => {
});
});
+d('the access door enforces the matrix for every /api/home route', () => {
+ // resolveHomeAccess is the single door every REST route on this surface goes
+ // through, so the matrix is asserted against it directly, with a real session
+ // cookie, rather than against nine handlers that all delegate to it.
+ let access;
+ let sessions = {};
+
+ beforeAll(async () => {
+ access = await import('../api/_lib/home/access.js');
+ const { createSession } = await import('../api/_lib/auth.js');
+ for (const who of ['owner', 'admin', 'member', 'guest', 'viewer', 'stranger']) {
+ sessions[who] = await createSession({ userId: users[who], userAgent: 'home-roles-test', ip: '127.0.0.1' });
+ }
+ }, 120_000);
+
+ const reqFor = (who) => ({ headers: { cookie: `__Host-sid=${sessions[who]}` }, socket: {} });
+ const res = { setHeader() {}, getHeader() {}, headersSent: false };
+
+ for (const [role, expected] of Object.entries(EXPECTED)) {
+ for (const [capability, allowed] of Object.entries(expected)) {
+ it(`the door ${allowed ? 'admits' : 'refuses'} a ${role} asking to ${capability}`, async () => {
+ const result = await access.resolveHomeAccess(reqFor(role), res, homeId, capability);
+ expect(result.ok).toBe(allowed);
+ if (allowed) {
+ expect(result.role).toBe(role);
+ expect(result.home.id).toBe(homeId);
+ // The credential never reaches a route, whichever role asked.
+ expect(Object.keys(result.home)).not.toContain('access_token_enc');
+ } else {
+ expect(result.status).toBe(403);
+ expect(result.code).toBe('role_forbidden');
+ expect(result.message).toContain(role);
+ }
+ });
+ }
+ }
+
+ it('answers a non-member 404 without confirming the home is real', async () => {
+ const result = await access.resolveHomeAccess(reqFor('stranger'), res, homeId, 'read');
+ expect(result.ok).toBe(false);
+ expect(result.status).toBe(404);
+ expect(result.code).toBe('not_found');
+ expect(result.home).toBeUndefined();
+ });
+
+ it('answers a signed-out caller 401', async () => {
+ const result = await access.resolveHomeAccess({ headers: {}, socket: {} }, res, homeId, 'read');
+ expect(result.status).toBe(401);
+ });
+
+ it('carries the scope a scoped role is held to', async () => {
+ const result = await access.resolveHomeAccess(reqFor('guest'), res, homeId, 'read');
+ expect(result.scoped).toBe(true);
+ expect(result.scope.areas).toContain('kitchen');
+
+ const whole = await access.resolveHomeAccess(reqFor('member'), res, homeId, 'read');
+ expect(whole.scoped).toBe(false);
+ expect(whole.scope).toEqual({ mode: 'all' });
+ });
+
+ it('defaults to `read` so a route that names no capability fails closed, not open', async () => {
+ const viewer = await access.resolveHomeAccess(reqFor('viewer'), res, homeId);
+ expect(viewer.ok).toBe(true);
+ expect(viewer.role).toBe('viewer');
+ });
+});
+
+d('every route on the surface names the capability it needs', () => {
+ // A drift guard, not a behaviour test. `resolveHomeAccess` defaults to `read`,
+ // which is the safe default and also a silent one: a new route that writes to
+ // a house and forgets to say so would be admitted to a viewer. Reading the
+ // call sites is the only way to catch that, because the omission is invisible
+ // at runtime until somebody exploits it.
+ it('passes a capability at every resolveHomeAccess call site under api/home', async () => {
+ const { readdirSync, readFileSync, statSync } = await import('node:fs');
+ const { join } = await import('node:path');
+
+ const walk = (dir) =>
+ readdirSync(dir).flatMap((name) => {
+ const full = join(dir, name);
+ return statSync(full).isDirectory() ? walk(full) : full.endsWith('.js') ? [full] : [];
+ });
+
+ const bare = [];
+ for (const file of walk('api/home')) {
+ const src = readFileSync(file, 'utf8');
+ for (const call of src.match(/resolveHomeAccess\([^)]*\)/g) || []) {
+ // Three arguments is (req, res, homeId) with the capability left off.
+ if (call.split(',').length < 4) bare.push(`${file}: ${call}`);
+ }
+ }
+ expect(bare).toEqual([]);
+ });
+});
+
d('listing homes resolves through membership, not through ownership', () => {
it('shows a member the home they were invited to, with the role they hold', async () => {
const listed = await members.listMembershipHomes(users.viewer);