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
// The household role matrix, asserted cell by cell against a real database.
//
// Order 12's role table is a product decision with a physical actuator on the
// other end of it, so it is not documented in a comment and hoped for: every
// cell in it is executed here, at the enforcement boundary the product calls,
// with real rows in real tables.
//
// What "enforcement boundary" means concretely: nothing in these tests asks a
// role question of a UI, a fixture or a stub. `requireMembership` is the call
// every surface makes (the store's reads, the runtime's acquire, the graph
// projection, the physical-action gate, the confirm endpoint, the grant, layout,
// invite and disconnect writers, and the chat and MCP tools acting for a bearer
// principal), so the matrix is asserted through it once and the surfaces above
// inherit it.
//
// The row that matters most, and the reason this file exists:
//
// a guest is REFUSED a confirmation, with a reason naming their role,
// rather than being shown a confirmation prompt they could say yes to.
//
// Requires DATABASE_URL. Every row it writes is prefixed and deleted afterwards,
// and the same prefix is swept before the run so a crashed previous run cannot
// leave anything behind.
import { randomUUID } from 'node:crypto';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import '../tests/setup.env.js';
const HAS_DB = Boolean(process.env.DATABASE_URL);
const d = HAS_DB ? describe : describe.skip;
// Every row this suite writes is namespaced to THIS run, not to the file.
//
// A constant prefix looked tidy and was a landmine: this workspace runs many
// agents, several of them with a vitest of their own in flight, and two
// overlapping runs of this file deleted each other's users and homes mid-test.
// The symptom is a wall of foreign-key violations on `sessions` and
// `home_invites` that reads like broken RBAC and is nothing of the kind.
const FAMILY = 'home-roles-test';
const PREFIX = `${FAMILY}-${randomUUID().slice(0, 8)}`;
const email = (who) => `${PREFIX}+${who}@example.invalid`;
/** Rows from a run that crashed before its own cleanup. Old enough that no live run owns them. */
const STALE_AFTER = '1 hour';
/** 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, 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. */
const SCOPED = new Set(['guest', 'viewer']);
let sql;
let members;
let store;
let users = {};
let homeId;
let otherHomeId;
async function makeUser(who) {
const [row] = await sql`
INSERT INTO users (email, display_name)
VALUES (${email(who)}, ${`${PREFIX} ${who}`})
RETURNING id
`;
return row.id;
}
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}+%`}`;
}
/**
* Rows left by a run that died before its own cleanup, from any prefix in this
* family. Bounded by age so it can never touch a run happening right now, which
* is the whole reason the per-run prefix exists.
*/
async function sweepStale() {
await sql`
DELETE FROM home_connections
WHERE label LIKE ${`${FAMILY}-%`} AND created_at < now() - ${STALE_AFTER}::interval
`;
await sql`
DELETE FROM sessions
WHERE user_id IN (
SELECT id FROM users
WHERE email LIKE ${`${FAMILY}-%`} AND created_at < now() - ${STALE_AFTER}::interval
)
`;
await sql`
DELETE FROM audit_log
WHERE user_id IN (
SELECT id FROM users
WHERE email LIKE ${`${FAMILY}-%`} AND created_at < now() - ${STALE_AFTER}::interval
)
`;
await sql`
DELETE FROM users
WHERE email LIKE ${`${FAMILY}-%`} AND created_at < now() - ${STALE_AFTER}::interval
`;
}
beforeAll(async () => {
if (!HAS_DB) return;
({ sql } = await import('../api/_lib/db.js'));
members = await import('../api/_lib/home/members.js');
store = await import('../api/_lib/home/store.js');
await sweepStale();
await sweep();
for (const who of ['owner', 'admin', 'member', 'guest', 'viewer', 'stranger', 'second']) {
users[who] = await makeUser(who);
}
// Two homes: the one under test, and a second one owned by a stranger, so
// "this member cannot see that home" is asserted against a real other house
// rather than a made-up id.
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
`;
otherHomeId = other.id;
// The owner row is not inserted here on purpose: the migration's trigger owns
// it, and the first assertion below is that the trigger did its job.
for (const role of ['admin', 'member']) {
await sql`INSERT INTO home_members (home_id, user_id, role, invited_by) VALUES (${homeId}, ${users[role]}, ${role}, ${users.owner})`;
}
for (const role of ['guest', 'viewer']) {
await sql`
INSERT INTO home_members (home_id, user_id, role, entity_scope, invited_by)
VALUES (${homeId}, ${users[role]}, ${role}, ${'{"mode":"allow","areas":["kitchen"],"entities":["light.hall_lamp"]}'}::jsonb, ${users.owner})
`;
}
}, 120_000);
afterAll(async () => {
if (!HAS_DB) return;
await sweep();
});
d('home_members: the backfill and the ownership invariant', () => {
it('gives every connection exactly one owner row, created by the database', async () => {
const [row] = await sql`SELECT user_id, role FROM home_members WHERE home_id = ${homeId} AND role = 'owner'`;
expect(row).toBeTruthy();
expect(row.user_id).toBe(users.owner);
const [{ owners }] = await sql`SELECT count(*)::int AS owners FROM home_members WHERE home_id = ${homeId} AND role = 'owner'`;
expect(owners).toBe(1);
});
it('holds the one-owner-per-home invariant against a second owner insert', async () => {
await expect(
sql`INSERT INTO home_members (home_id, user_id, role) VALUES (${homeId}, ${users.second}, 'owner')`,
).rejects.toMatchObject({ code: '23505' });
});
it('leaves no connection in the database without an owner row', async () => {
const [{ orphans }] = await sql`
SELECT count(*)::int AS orphans
FROM home_connections c
WHERE NOT EXISTS (SELECT 1 FROM home_members m WHERE m.home_id = c.id AND m.role = 'owner')
`;
expect(orphans).toBe(0);
});
});
d('the role matrix, every cell, at the enforcement boundary', () => {
for (const [role, expected] of Object.entries(EXPECTED)) {
for (const [capability, allowed] of Object.entries(expected)) {
it(`${role} ${allowed ? 'may' : 'may NOT'} ${capability}`, async () => {
const gate = await members.requireMembership(homeId, users[role], capability);
expect(gate.ok).toBe(allowed);
if (!allowed) {
// A member who lacks a capability is told so, and told which role
// they hold. 403 and not 404: they are in the household, and
// pretending the house does not exist would be a worse answer.
expect(gate.status).toBe(403);
expect(gate.code).toBe('role_forbidden');
expect(gate.reason).toContain(role);
expect(gate.reason).toContain(capability);
} else {
expect(gate.role).toBe(role);
}
});
}
}
it('marks exactly the scoped roles as scoped', async () => {
for (const role of Object.keys(EXPECTED)) {
const gate = await members.requireMembership(homeId, users[role], 'read');
expect(gate.membership.scoped).toBe(SCOPED.has(role));
if (!SCOPED.has(role)) expect(gate.membership.scope).toEqual({ mode: 'all' });
}
});
it('refuses every capability to a non-member with 404, never 403', async () => {
for (const capability of members.HOME_CAPABILITIES) {
const gate = await members.requireMembership(homeId, users.stranger, capability);
expect(gate.ok).toBe(false);
expect(gate.status).toBe(404);
expect(gate.code).toBe('home_not_found');
expect(gate.reason).not.toContain('role');
}
});
it('refuses a member of one home every capability on another home, with 404', async () => {
for (const capability of members.HOME_CAPABILITIES) {
const gate = await members.requireMembership(otherHomeId, users.member, capability);
expect(gate.status).toBe(404);
}
});
it('drops every member to 404 the moment the home is revoked', async () => {
const [tmp] = await sql`
INSERT INTO home_connections (user_id, label, base_url, access_token_enc, token_fingerprint, status)
VALUES (${users.owner}, ${`${PREFIX} temp`}, ${`https://${PREFIX}-3.invalid`}, '', ${`${PREFIX}-3`}, 'connected')
RETURNING id
`;
expect((await members.requireMembership(tmp.id, users.owner, 'read')).ok).toBe(true);
await sql`UPDATE home_connections SET revoked_at = now() WHERE id = ${tmp.id}`;
const after = await members.requireMembership(tmp.id, users.owner, 'read');
expect(after.status).toBe(404);
await sql`DELETE FROM home_connections WHERE id = ${tmp.id}`;
});
});
d('the guest refusal: a house sitter can turn on a light and cannot open a door', () => {
it('refuses a guest a confirmation with a role reason, not a prompt', async () => {
const act = await members.requireMembership(homeId, users.guest, 'act');
expect(act.ok).toBe(true);
const confirm = await members.requireMembership(homeId, users.guest, 'confirm');
expect(confirm.ok).toBe(false);
expect(confirm.status).toBe(403);
expect(confirm.code).toBe('role_forbidden');
expect(confirm.role).toBe('guest');
expect(confirm.capability).toBe('confirm');
expect(confirm.reason).toBe('the guest role cannot confirm in this home');
// The refusal carries no confirmation affordance of any kind: there is no
// token, no prompt and no pending id a client could echo back.
expect(Object.keys(confirm)).not.toContain('confirmation');
expect(Object.keys(confirm)).not.toContain('confirm_token');
});
it('refuses a guest a standing allowance, so they cannot grant their way past the gate', async () => {
const grant = await members.requireMembership(homeId, users.guest, 'grant');
expect(grant.ok).toBe(false);
expect(grant.status).toBe(403);
});
it('lets a member confirm: a member lives here, a guest is visiting', async () => {
expect((await members.requireMembership(homeId, users.member, 'confirm')).ok).toBe(true);
});
});
d('entity scope: enforced in the projection, never in the UI', () => {
// A house with two rooms and an unassigned entity. The guest above was given
// the kitchen as an area and one hall lamp as an individual entity.
const graph = {
floors: [
{ id: 'ground', name: 'Ground', level: 0 },
{ id: 'upstairs', name: 'Upstairs', level: 1 },
],
rooms: [
{
id: 'kitchen',
name: 'Kitchen',
floorId: 'ground',
entities: [
{ entityId: 'light.kitchen_ceiling', domain: 'light', areaId: 'kitchen', name: 'Ceiling', state: 'on', attributes: { brightness: 200 } },
{ entityId: 'lock.back_door', domain: 'lock', areaId: 'kitchen', name: 'Back door', state: 'locked', attributes: {} },
],
lighting: { total: 1, on: 1 },
climate: null,
secured: true,
},
{
id: 'hall',
name: 'Hall',
floorId: 'ground',
entities: [
{ entityId: 'light.hall_lamp', domain: 'light', areaId: 'hall', name: 'Hall lamp', state: 'off', attributes: {} },
{ entityId: 'light.hall_spots', domain: 'light', areaId: 'hall', name: 'Hall spots', state: 'on', attributes: { brightness: 255 } },
{ entityId: 'lock.front_door', domain: 'lock', areaId: 'hall', name: 'Front door', state: 'locked', attributes: {} },
],
lighting: { total: 2, on: 1 },
climate: null,
secured: true,
},
{
id: 'bedroom',
name: 'Bedroom',
floorId: 'upstairs',
entities: [{ entityId: 'light.bedside', domain: 'light', areaId: 'bedroom', name: 'Bedside', state: 'on', attributes: {} }],
lighting: { total: 1, on: 1 },
climate: null,
secured: null,
},
],
unassigned: [{ entityId: 'sensor.outside_temp', domain: 'sensor', areaId: null, name: 'Outside', state: '11', attributes: {} }],
};
it('gives an unscoped role the whole house, untouched', async () => {
const gate = await members.requireMembership(homeId, users.member, 'read');
const filtered = members.filterGraphForScope(graph, gate.scope);
expect(filtered).toBe(graph);
});
it('removes an out-of-scope room from a guest entirely, name included', async () => {
const gate = await members.requireMembership(homeId, users.guest, 'read');
const filtered = members.filterGraphForScope(graph, gate.scope);
const roomIds = filtered.rooms.map((r) => r.id);
expect(roomIds).toContain('kitchen');
expect(roomIds).toContain('hall');
expect(roomIds).not.toContain('bedroom');
// The whole serialized payload must not carry the room's name or any of
// its entity ids. This is the assertion that would fail if the filtering
// were a `visible: false` flag rather than a removal.
const wire = JSON.stringify(filtered);
expect(wire).not.toContain('Bedroom');
expect(wire).not.toContain('light.bedside');
});
it('narrows a partially granted room to the granted entity and recomputes its rollups', async () => {
const gate = await members.requireMembership(homeId, users.guest, 'read');
const filtered = members.filterGraphForScope(graph, gate.scope);
const hall = filtered.rooms.find((r) => r.id === 'hall');
expect(hall.entities.map((e) => e.entityId)).toEqual(['light.hall_lamp']);
// The unfiltered hall has two lights, one of them on, and a front door.
// Reporting that rollup to somebody who can see one lamp would disclose
// the state of the entities the filtering just removed.
expect(hall.lighting.total).toBe(1);
expect(hall.lighting.on).toBe(0);
expect(JSON.stringify(hall)).not.toContain('lock.front_door');
});
it('keeps a wholly granted room intact, rollups and all', async () => {
const gate = await members.requireMembership(homeId, users.guest, 'read');
const kitchen = members.filterGraphForScope(graph, gate.scope).rooms.find((r) => r.id === 'kitchen');
expect(kitchen.entities.map((e) => e.entityId)).toEqual(['light.kitchen_ceiling', 'lock.back_door']);
});
it('removes a floor that has no visible room, because the floor list is the shape of the building', async () => {
const gate = await members.requireMembership(homeId, users.guest, 'read');
const filtered = members.filterGraphForScope(graph, gate.scope);
expect(filtered.floors.map((f) => f.id)).toEqual(['ground']);
});
it('drops unassigned entities that were never granted', async () => {
const gate = await members.requireMembership(homeId, users.viewer, 'read');
const filtered = members.filterGraphForScope(graph, gate.scope);
expect(filtered.unassigned).toEqual([]);
});
it('names every out-of-scope target of a resolved action', async () => {
const gate = await members.requireMembership(homeId, users.guest, 'act');
const refused = members.outOfScopeEntities(gate.scope, [
{ entityId: 'light.hall_lamp', areaId: 'hall' },
{ entityId: 'light.kitchen_ceiling', areaId: 'kitchen' },
{ entityId: 'light.bedside', areaId: 'bedroom' },
]);
expect(refused).toEqual(['light.bedside']);
});
it('normalizes a scoped role back to the whole house when it is promoted', () => {
const stale = { mode: 'allow', areas: ['kitchen'], entities: [] };
expect(members.normalizeScope(stale, 'guest')).toEqual({ mode: 'allow', areas: ['kitchen'], entities: [] });
expect(members.normalizeScope(stale, 'member')).toEqual({ mode: 'all' });
});
});
d('roster administration', () => {
it('lets the owner manage everyone below, and never the owner row', () => {
expect(members.canManageMember('owner', 'admin')).toBe(true);
expect(members.canManageMember('owner', 'viewer')).toBe(true);
expect(members.canManageMember('owner', 'owner')).toBe(false);
expect(members.canManageMember('admin', 'owner')).toBe(false);
});
it('lets an admin add a peer admin and never remove one', () => {
expect(members.canAssignRole('admin', 'admin')).toBe(true);
expect(members.canManageMember('admin', 'admin')).toBe(false);
expect(members.canManageMember('admin', 'member')).toBe(true);
});
it('never assigns ownership', () => {
for (const role of members.HOME_ROLES) expect(members.canAssignRole(role, 'owner')).toBe(false);
expect(members.ASSIGNABLE_ROLES).not.toContain('owner');
});
it('gives a member and a guest no roster authority at all', () => {
for (const actor of ['member', 'guest', 'viewer']) {
expect(members.canManageMember(actor, 'viewer')).toBe(false);
expect(members.canAssignRole(actor, 'viewer')).toBe(false);
}
});
it('widens a promoted guest to the whole house in the same statement', async () => {
const before = await members.resolveMembership(homeId, users.guest);
expect(before.scope.mode).toBe('allow');
const promoted = await members.setMemberRole({ homeId, userId: users.guest, role: 'member', scope: before.scope });
expect(promoted.role).toBe('member');
expect(promoted.scope).toEqual({ mode: 'all' });
const restored = await members.setMemberRole({ homeId, userId: users.guest, role: 'guest', scope: before.scope });
expect(restored.scope).toEqual(before.scope);
});
it('refuses to change the owner row', async () => {
expect(await members.setMemberRole({ homeId, userId: users.owner, role: 'member' })).toBeNull();
const still = await members.resolveMembership(homeId, users.owner);
expect(still.role).toBe('owner');
});
});
d('removing a member revokes their standing allowances in the same transaction', () => {
it('deletes the grants they authorised and leaves everyone else alone', async () => {
await sql`INSERT INTO home_members (home_id, user_id, role, invited_by) VALUES (${homeId}, ${users.second}, 'admin', ${users.owner})`;
await sql`
INSERT INTO home_entity_grants (home_id, entity_id, granted_by)
VALUES (${homeId}, 'lock.office_door', ${users.second}), (${homeId}, 'cover.garage', ${users.second}), (${homeId}, 'lock.front_door', ${users.owner})
`;
const before = await sql`SELECT entity_id, granted_by FROM home_entity_grants WHERE home_id = ${homeId} ORDER BY entity_id`;
expect(before.map((r) => r.entity_id)).toEqual(['cover.garage', 'lock.front_door', 'lock.office_door']);
const result = await members.removeMember({ homeId, userId: users.second });
expect(result.removed).toBe(true);
expect(result.grantsRevoked).toEqual(['cover.garage', 'lock.office_door']);
const after = await sql`SELECT entity_id, granted_by FROM home_entity_grants WHERE home_id = ${homeId} ORDER BY entity_id`;
expect(after.map((r) => r.entity_id)).toEqual(['lock.front_door']);
expect(after[0].granted_by).toBe(users.owner);
expect(await members.resolveMembership(homeId, users.second)).toBeNull();
await sql`DELETE FROM home_entity_grants WHERE home_id = ${homeId}`;
});
it('refuses to remove the owner, so a home is never left ownerless', async () => {
const result = await members.removeMember({ homeId, userId: users.owner });
expect(result.removed).toBe(false);
expect((await members.resolveMembership(homeId, users.owner)).role).toBe('owner');
});
it('reaches every household when an identity is deprovisioned', async () => {
await sql`INSERT INTO home_members (home_id, user_id, role, invited_by) VALUES (${homeId}, ${users.second}, 'member', ${users.owner})`;
await sql`INSERT INTO home_members (home_id, user_id, role, invited_by) VALUES (${otherHomeId}, ${users.second}, 'guest', ${users.stranger})`;
await sql`INSERT INTO home_entity_grants (home_id, entity_id, granted_by) VALUES (${homeId}, 'lock.side_gate', ${users.second})`;
const result = await members.revokeAllMemberships(users.second);
expect(result.removedFrom.sort()).toEqual([homeId, otherHomeId].sort());
expect(await members.resolveMembership(homeId, users.second)).toBeNull();
expect(await members.resolveMembership(otherHomeId, users.second)).toBeNull();
const [{ left }] = await sql`SELECT count(*)::int AS left FROM home_entity_grants WHERE granted_by = ${users.second}`;
expect(left).toBe(0);
});
});
d('invitations are single use and they expire', () => {
it('admits exactly one holder and refuses the second attempt', async () => {
const invite = await members.createInvite({
homeId,
email: email('invitee'),
role: 'guest',
scope: { mode: 'allow', areas: ['kitchen'], entities: [] },
invitedBy: users.owner,
});
expect(invite.token).toBeTruthy();
const first = await members.acceptInvite({ token: invite.token, userId: users.second });
expect(first.ok).toBe(true);
expect(first.membership.role).toBe('guest');
expect(first.membership.scope).toEqual({ mode: 'allow', areas: ['kitchen'], entities: [] });
const second = await members.acceptInvite({ token: invite.token, userId: users.stranger });
expect(second.ok).toBe(false);
expect(second.code).toBe('invite_spent');
expect(await members.resolveMembership(homeId, users.stranger)).toBeNull();
await members.removeMember({ homeId, userId: users.second });
});
it('refuses an expired invitation', async () => {
const invite = await members.createInvite({
homeId,
email: email('expired'),
role: 'viewer',
invitedBy: users.owner,
ttlMs: -1000,
});
const attempt = await members.acceptInvite({ token: invite.token, userId: users.second });
expect(attempt.ok).toBe(false);
expect(attempt.code).toBe('invite_expired');
expect(await members.resolveMembership(homeId, users.second)).toBeNull();
});
it('refuses a withdrawn invitation', async () => {
const invite = await members.createInvite({ homeId, email: email('withdrawn'), role: 'viewer', invitedBy: users.owner });
expect(await members.revokeInvite({ homeId, inviteId: invite.id })).toBe(true);
const attempt = await members.acceptInvite({ token: invite.token, userId: users.second });
expect(attempt.code).toBe('invite_revoked');
});
it('stores the token as a hash and never in plaintext', async () => {
const invite = await members.createInvite({ homeId, email: email('hashed'), role: 'viewer', invitedBy: users.owner });
const [row] = await sql`SELECT token_hash FROM home_invites WHERE id = ${invite.id}`;
expect(row.token_hash).not.toBe(invite.token);
expect(row.token_hash).toMatch(/^[0-9a-f]{64}$/);
const [{ hits }] = await sql`SELECT count(*)::int AS hits FROM home_invites WHERE token_hash = ${invite.token}`;
expect(hits).toBe(0);
await members.revokeInvite({ homeId, inviteId: invite.id });
});
it('replaces an outstanding invitation to the same address rather than stacking a second key', async () => {
const first = await members.createInvite({ homeId, email: email('replaced'), role: 'viewer', invitedBy: users.owner });
const second = await members.createInvite({ homeId, email: email('replaced'), role: 'member', invitedBy: users.owner });
expect((await members.acceptInvite({ token: first.token, userId: users.second })).code).toBe('invite_revoked');
const accepted = await members.acceptInvite({ token: second.token, userId: users.second });
expect(accepted.ok).toBe(true);
expect(accepted.membership.role).toBe('member');
await members.removeMember({ homeId, userId: users.second });
});
it('never lets an invitation hand out ownership', async () => {
await expect(members.createInvite({ homeId, email: email('usurper'), role: 'owner', invitedBy: users.owner })).rejects.toThrow(/invalid invite role/);
});
it('keeps the role an existing member already holds', async () => {
const invite = await members.createInvite({ homeId, email: email('admin'), role: 'viewer', invitedBy: users.owner });
const result = await members.acceptInvite({ token: invite.token, userId: users.admin });
expect(result.ok).toBe(true);
expect(result.alreadyMember).toBe(true);
expect((await members.resolveMembership(homeId, users.admin)).role).toBe('admin');
});
it('lists outstanding invitations without ever returning a token', async () => {
const invite = await members.createInvite({ homeId, email: email('listed'), role: 'guest', invitedBy: users.owner });
const list = await members.listInvites(homeId);
const found = list.find((i) => i.id === invite.id);
expect(found).toBeTruthy();
expect(found.token).toBeUndefined();
expect(JSON.stringify(list)).not.toContain(invite.token);
await members.revokeInvite({ homeId, inviteId: invite.id });
});
});
d('the invitation email says what the seat is, and never renders a name as markup', () => {
it('names the role and the thing that role can never do', async () => {
const { renderHouseholdInvite } = await import('../api/_lib/email.js');
const mail = renderHouseholdInvite({
homeLabel: 'The office',
role: 'guest',
inviterName: 'Sam',
inviteUrl: 'https://three.ws/smart-home/join?invite=token',
expiresAt: '2026-09-10T03:31:52.462Z',
});
expect(mail.subject).toContain('The office');
// The guest line is the one that matters: somebody forwarding this should
// be able to see they are handing over a guest seat and not the house.
expect(mail.text).toContain('never be able to approve unlocking a door');
expect(mail.html).toContain('never be able to approve unlocking a door');
expect(mail.text).toContain('works once');
});
it('escapes a home label and an inviter name, both of which a person typed', async () => {
const { renderHouseholdInvite } = await import('../api/_lib/email.js');
const mail = renderHouseholdInvite({
homeLabel: '<img src=x onerror=alert(1)>',
role: 'viewer',
inviterName: '<b>nobody</b>',
inviteUrl: 'https://three.ws/smart-home/join?invite=token',
});
expect(mail.html).not.toContain('<img src=x');
expect(mail.html).not.toContain('<b>nobody</b>');
expect(mail.html).toContain('<img');
});
it('carries a different sentence for every assignable role', async () => {
const { renderHouseholdInvite } = await import('../api/_lib/email.js');
const lines = new Set();
for (const role of members.ASSIGNABLE_ROLES) {
const mail = renderHouseholdInvite({ homeLabel: 'Home', role, inviteUrl: 'https://three.ws/x' });
lines.add(mail.text);
}
expect(lines.size).toBe(members.ASSIGNABLE_ROLES.length);
});
});
d('a scope survives a round trip through the store', () => {
it('keeps the rooms an editor sent, and drops nothing on the way back', async () => {
const sent = { mode: 'allow', areas: ['kitchen', 'hall'], entities: ['light.hall_lamp'] };
const saved = await members.setMemberRole({ homeId, userId: users.viewer, role: 'viewer', scope: sent });
expect(saved.scope).toEqual(sent);
const read = await members.resolveMembership(homeId, users.viewer);
expect(read.scope).toEqual(sent);
// Widening back to the whole house is an explicit {mode:'all'}, not an
// omission: the editor's Save means "this is the scope now".
const widened = await members.setMemberRole({ homeId, userId: users.viewer, role: 'viewer', scope: { mode: 'all' } });
expect(widened.scope).toEqual({ mode: 'all' });
await members.setMemberRole({ homeId, userId: users.viewer, role: 'viewer', scope: { mode: 'allow', areas: ['kitchen'], entities: ['light.hall_lamp'] } });
});
it('refuses a scope the schema cannot describe', async () => {
await expect(
sql`UPDATE home_members SET entity_scope = ${'{"mode":"everything"}'}::jsonb WHERE home_id = ${homeId} AND user_id = ${users.viewer}`,
).rejects.toMatchObject({ code: '23514' });
});
it('de-duplicates and trims what an editor sends, and caps how much it can send', () => {
const messy = { mode: 'allow', areas: [' kitchen ', 'kitchen', '', null, 'hall'], entities: Array.from({ length: 900 }, (_, i) => `light.l${i}`) };
const clean = members.normalizeScope(messy, 'guest');
expect(clean.areas).toEqual(['kitchen', 'hall']);
expect(clean.entities).toHaveLength(500);
});
});
d('the action log attributes every action to the member who acted', () => {
it('records two members acting on one home under their own ids', async () => {
for (const who of ['admin', 'member']) {
const gate = await members.requireMembership(homeId, users[who], 'act');
expect(gate.ok).toBe(true);
// The acting member id is the one the gate resolved, never the
// connection's owner. This is the value every call site above (the
// runtime, the gate, the chat and MCP tools) must pass through.
const landed = await store.logHomeActionNow({
homeId,
userId: gate.membership.userId,
actor: 'user',
channel: 'websocket',
action: 'light.turn_on',
entityIds: ['light.kitchen_ceiling'],
outcome: 'ok',
});
expect(landed).toBe(true);
}
const rows = await sql`
SELECT user_id, action FROM home_action_log
WHERE home_id = ${homeId} AND action = 'light.turn_on'
ORDER BY created_at ASC
`;
expect(rows.map((r) => r.user_id).sort()).toEqual([users.admin, users.member].sort());
expect(rows.map((r) => r.user_id)).not.toContain(users.owner);
});
it('records a guest refusal against the guest, with the gate verdict', async () => {
const gate = await members.requireMembership(homeId, users.guest, 'confirm');
expect(gate.ok).toBe(false);
await store.logHomeActionNow({
homeId,
userId: gate.membership.userId,
actor: 'user',
channel: 'websocket',
action: 'lock.unlock',
entityIds: ['lock.front_door'],
guarded: true,
risk: 'security',
outcome: 'refused',
detail: { reason: gate.code, role: gate.role },
});
const [row] = await sql`
SELECT user_id, guarded, risk, outcome, confirmed_by, detail
FROM home_action_log WHERE home_id = ${homeId} AND action = 'lock.unlock'
`;
expect(row.user_id).toBe(users.guest);
expect(row.guarded).toBe(true);
expect(row.outcome).toBe('refused');
// Nobody confirmed it, and the row says so. A refused guarded action with
// a confirmed_by would be the audit trail lying about who opened a door.
expect(row.confirmed_by).toBeNull();
expect(row.detail.role).toBe('guest');
});
});
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);
const found = listed.find((h) => h.home_id === homeId);
expect(found).toBeTruthy();
expect(found.role).toBe('viewer');
expect(found.label).toBe(`${PREFIX} house`);
});
it('shows a stranger nothing of a home they are not in', async () => {
const listed = await members.listMembershipHomes(users.stranger);
expect(listed.map((h) => h.home_id)).not.toContain(homeId);
expect(listed.map((h) => h.home_id)).toContain(otherHomeId);
});
it('never returns a credential column on a membership listing', async () => {
const listed = await members.listMembershipHomes(users.owner);
for (const row of listed) expect(Object.keys(row)).not.toContain('access_token_enc');
});
});