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.

17.6 KB
Raw Blame
// The confirmation protocol over real HTTP, end to end.
//
// tests/home-tools.test.js proves the gate at the module boundary and
// tests/home-confirmation.test.js proves the record. Both call JavaScript
// functions. This file proves the same protocol the way an attacker meets it:
// over the wire, through the real MCP endpoint and the real confirm endpoint,
// with real credentials, against a real Home Assistant holding a real lock.
//
// That distinction is the reason this file exists. `claimConfirmation()` being
// correct says nothing about whether `POST /api/home/:id/confirm` refuses a
// bearer token, because the refusal lives in the handler and not in the record.
// Every assertion below reads its verdict off an HTTP status line, and every
// assertion about a door reads the door's state back out of Home Assistant.
//
// Live only, because a mocked lock cannot stay locked:
//
//   HOME_LIVE=1 HOME_ALLOW_LOCAL_INSTANCE=1 DATABASE_URL=... JWT_SECRET=... \
//     npx vitest run tests/home-confirm-endpoint.test.js
//
// `HOME_ALLOW_LOCAL_INSTANCE=1` is the seam documented in
// api/_lib/home-url-guard.js: a Home Assistant you run yourself lands on
// loopback, and the reachability guard refuses loopback in production.

import { afterAll, beforeAll, describe, expect, it } from 'vitest';

import http from 'node:http';

import { acquireHomeInstance, liveHomeAvailable, pickEntity, readState, setState, waitForState } from './_helpers/home-instance.js';

const live = describe.skipIf(!liveHomeAvailable() || !process.env.DATABASE_URL || !process.env.JWT_SECRET);

/** The session cookie the platform actually sets. */
const SESSION_COOKIE = '__Host-sid';

live('the confirmation protocol over HTTP', () => {
	let sql;
	let instance;
	let confirmServer;
	let mcpServer;
	let owner;
	let stranger;
	let home;
	let otherHome;
	let lockId;
	let ownerCookie;
	let strangerCookie;
	let ownerBearer;

	beforeAll(async () => {
		instance = await acquireHomeInstance();
		({ sql } = await import('../api/_lib/db.js'));

		const { createConnection } = await import('../api/_lib/home/store.js');
		const { createSession, mintAccessToken } = await import('../api/_lib/auth.js');
		const confirmHandler = (await import('../api/home/[id]/confirm.js')).default;
		const mcpHandler = (await import('../api/mcp.js')).default;

		const stamp = Date.now();
		[owner] = await sql`insert into users (email) values (${`home-http-owner-${stamp}@qa.three.ws`}) returning id`;
		[stranger] = await sql`insert into users (email) values (${`home-http-stranger-${stamp}@qa.three.ws`}) returning id`;

		home = await createConnection({
			userId: owner.id,
			label: 'HTTP House',
			baseUrl: instance.baseUrl,
			token: instance.token,
			status: 'connected',
		});
		// A second home the same owner holds, so the cross-home replay below is
		// refused by the binding and not merely by the membership check.
		//
		// It has to reach the instance by a DIFFERENT base URL, because
		// `createConnection` upserts on `(user_id, base_url)`: connecting the same
		// address twice updates one row rather than making two, and the two ids
		// would silently be the same id. `localhost` and `127.0.0.1` are both real
		// routes to this container and the normalizer keeps them distinct.
		otherHome = await createConnection({
			userId: owner.id,
			label: 'HTTP Second House',
			baseUrl: instance.baseUrl.replace('127.0.0.1', 'localhost'),
			token: instance.token,
			status: 'connected',
		});
		expect(otherHome.id, 'the two homes must be two rows').not.toBe(home.id);

		ownerCookie = `${SESSION_COOKIE}=${await createSession({ userId: owner.id, recordActivity: false })}`;
		strangerCookie = `${SESSION_COOKIE}=${await createSession({ userId: stranger.id, recordActivity: false })}`;
		// A real OAuth access token carrying the strongest home scope there is.
		// The point of the bearer assertions below is that even THIS cannot
		// approve anything.
		ownerBearer = await mintAccessToken({
			userId: owner.id,
			clientId: 'home-confirm-endpoint-test',
			scope: 'home:read home:act',
		});

		confirmServer = await listen(confirmHandler);
		mcpServer = await listen(mcpHandler);

		lockId = await pickEntity(instance, 'lock');
		await setState(instance, 'lock', 'lock', lockId);
		await waitForState(instance, lockId, 'locked');
	}, 600_000);

	afterAll(async () => {
		if (instance && lockId) await setState(instance, 'lock', 'lock', lockId).catch(() => {});
		const { closeAll } = await import('../api/_lib/home/runtime.js');
		closeAll();
		await close(confirmServer);
		await close(mcpServer);
		if (sql && owner) await sql`delete from users where id in (${owner.id}, ${stranger.id})`;
	});

	// ── The MCP client's half ────────────────────────────────────────────────

	/**
	 * Speak real JSON-RPC to the real MCP endpoint, the way any external agent
	 * would. Nothing here is a shortcut into the handler: it is a bearer token on
	 * an HTTP request, which is exactly the principal this protocol is defending
	 * the door against.
	 */
	async function mcp(method, params, { bearer = ownerBearer } = {}) {
		const res = await fetch(`${mcpServer.url}/api/mcp`, {
			method: 'POST',
			headers: {
				'content-type': 'application/json',
				accept: 'application/json, text/event-stream',
				...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
			},
			body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
		});
		return { status: res.status, body: await res.json().catch(() => null) };
	}

	it('publishes home_call to a real MCP client with no confirmation field in its schema', async () => {
		const listed = await mcp('tools/list', {});
		expect(listed.status).toBe(200);
		const tools = listed.body?.result?.tools || [];
		const homeCall = tools.find((t) => t.name === 'home_call');
		expect(homeCall, 'home_call must be published to an MCP client').toBeTruthy();

		// The mechanism, asserted over the wire rather than over the source: a
		// model cannot set a field that is not in the schema it was handed.
		expect(JSON.stringify(homeCall.inputSchema)).not.toMatch(/confirm/i);
		expect(homeCall.annotations).toMatchObject({
			readOnlyHint: false,
			destructiveHint: true,
			idempotentHint: false,
			openWorldHint: true,
		});
	}, 60_000);

	it('answers an MCP unlock with pending_confirmation while the real lock stays locked', async () => {
		await setState(instance, 'lock', 'lock', lockId);
		await waitForState(instance, lockId, 'locked');

		const called = await mcp('tools/call', {
			name: 'home_call',
			arguments: { home_id: home.id, domain: 'lock', service: 'unlock', data: { entity_id: lockId } },
		});

		expect(called.status).toBe(200);
		const result = called.body?.result;
		// Neither an error nor a success. A model that reads this as a failure
		// goes looking for another way to open the door.
		expect(result.isError).toBeFalsy();
		expect(result.structuredContent.status).toBe('pending_confirmation');
		expect(result.structuredContent.confirmation.entity_ids).toEqual([lockId]);

		// The only assertion that means anything: the door.
		expect(await readState(instance, lockId)).toBe('locked');
	}, 60_000);

	// ── The human's half ─────────────────────────────────────────────────────

	function confirmUrl(homeId) {
		return `${confirmServer.url}/api/home/${homeId}/confirm`;
	}

	async function csrfFor(userId) {
		const { issueCsrf } = await import('../api/_lib/csrf.js');
		return (await issueCsrf(userId)).token;
	}

	/** Mint a pending confirmation the way an agent would, over MCP. */
	async function pendingUnlock({ homeId = home.id } = {}) {
		const called = await mcp('tools/call', {
			name: 'home_call',
			arguments: { home_id: homeId, domain: 'lock', service: 'unlock', data: { entity_id: lockId } },
		});
		const confirmation = called.body?.result?.structuredContent?.confirmation;
		expect(confirmation?.id, 'the agent call should have minted a confirmation').toBeTruthy();
		return confirmation;
	}

	async function post(homeId, body, { cookie = ownerCookie, csrf, bearer } = {}) {
		const res = await fetch(confirmUrl(homeId), {
			method: 'POST',
			headers: {
				'content-type': 'application/json',
				...(cookie ? { cookie } : {}),
				...(csrf ? { 'x-csrf-token': csrf } : {}),
				...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
			},
			body: JSON.stringify(body),
		});
		return { status: res.status, body: await res.json().catch(() => null) };
	}

	it('refuses a bearer token holding home:act, before it authenticates anything', async () => {
		const confirmation = await pendingUnlock();
		// No cookie at all: the pure machine principal.
		const res = await post(home.id, { confirmation_id: confirmation.id }, { cookie: null, bearer: ownerBearer });
		expect(res.status).toBe(403);
		expect(res.body.error).toBe('confirmation_requires_session');
		expect(await readState(instance, lockId)).toBe('locked');

		// And with a valid session ALSO present, so the refusal cannot be read as
		// "it just was not signed in". A bearer anywhere on the request is fatal.
		const both = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id), bearer: ownerBearer });
		expect(both.status).toBe(403);
		expect(both.body.error).toBe('confirmation_requires_session');
		expect(await readState(instance, lockId)).toBe('locked');
	}, 60_000);

	it('refuses a session with no CSRF token, which is what a cross-site page can send', async () => {
		const confirmation = await pendingUnlock();
		const res = await post(home.id, { confirmation_id: confirmation.id });
		expect(res.status).toBe(403);
		expect(res.body.error).toBe('csrf_missing');
		expect(await readState(instance, lockId)).toBe('locked');
	}, 60_000);

	it('refuses a CSRF token minted for somebody else', async () => {
		const confirmation = await pendingUnlock();
		const res = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(stranger.id) });
		expect(res.status).toBe(403);
		expect(res.body.error).toBe('csrf_invalid');
		expect(await readState(instance, lockId)).toBe('locked');
	}, 60_000);

	it('unlocks the real door for a signed-in person, and only then', async () => {
		await setState(instance, 'lock', 'lock', lockId);
		await waitForState(instance, lockId, 'locked');

		const confirmation = await pendingUnlock();
		expect(await readState(instance, lockId)).toBe('locked');

		const res = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
		expect(res.status).toBe(200);
		expect(res.body.ok).toBe(true);
		expect(res.body.ran).toBe('lock.unlock');
		expect(res.body.entity_ids).toEqual([lockId]);

		await waitForState(instance, lockId, 'unlocked');
		expect(await readState(instance, lockId)).toBe('unlocked');

		// The row an operator reads after an incident.
		const [row] = await sql`
			select guarded, confirmed_by, outcome from home_action_log
			where home_id = ${home.id} and action = 'lock.unlock' and outcome = 'ok'
			order by created_at desc limit 1
		`;
		expect(row.guarded).toBe(true);
		expect(row.confirmed_by).toBe(owner.id);
	}, 90_000);

	it('refuses the replay of a confirmation that already ran', async () => {
		await setState(instance, 'lock', 'lock', lockId);
		await waitForState(instance, lockId, 'locked');

		const confirmation = await pendingUnlock();
		const first = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
		expect(first.status).toBe(200);
		await waitForState(instance, lockId, 'unlocked');

		// Lock it again, so a successful replay would be visible as an unlock
		// rather than hiding behind the state the first redemption left.
		await setState(instance, 'lock', 'lock', lockId);
		await waitForState(instance, lockId, 'locked');

		const replay = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
		expect(replay.status).toBe(410);
		expect(replay.body.error).toBe('confirmation_spent');
		expect(await readState(instance, lockId)).toBe('locked');
	}, 120_000);

	it('refuses a confirmation whose ninety seconds ran out', async () => {
		const confirmation = await pendingUnlock();
		// Age the row rather than waiting ninety-one seconds in a test suite. The
		// expiry is a column comparison against now(), so moving the column is the
		// same event as time passing, and it is the row the handler reads.
		await sql`update home_confirmations set expires_at = now() - interval '1 second' where id = ${confirmation.id}`;

		const res = await post(home.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
		expect(res.status).toBe(410);
		expect(res.body.error).toBe('confirmation_expired');
		expect(await readState(instance, lockId)).toBe('locked');

		// An expiry is an event, not silence: somebody asked to open a door and
		// nobody answered.
		const [row] = await sql`
			select detail from home_action_log
			where home_id = ${home.id} and detail->>'confirmation_id' = ${confirmation.id}
			  and detail->>'reason' = 'confirmation_expired' limit 1
		`;
		expect(row, 'an unanswered confirmation must earn a log row').toBeTruthy();
	}, 60_000);

	it('tells a stranger nothing, and lets them redeem nothing', async () => {
		const confirmation = await pendingUnlock();
		const res = await post(home.id, { confirmation_id: confirmation.id }, { cookie: strangerCookie, csrf: await csrfFor(stranger.id) });
		// 404, not 403: a stranger must not learn that a home id is real.
		expect(res.status).toBe(404);
		expect(res.body.error).toBe('not_found');
		expect(await readState(instance, lockId)).toBe('locked');
	}, 60_000);

	it('refuses a confirmation redeemed against a different home the same owner holds', async () => {
		const confirmation = await pendingUnlock();
		const res = await post(otherHome.id, { confirmation_id: confirmation.id }, { csrf: await csrfFor(owner.id) });
		expect(res.status).toBe(404);
		expect(res.body.error).toBe('confirmation_not_found');
		expect(await readState(instance, lockId)).toBe('locked');
	}, 60_000);

	it('ignores everything in the body except the id, so nothing can be steered', async () => {
		await setState(instance, 'lock', 'lock', lockId);
		await waitForState(instance, lockId, 'locked');

		// A caller re-sending the action alongside the ticket, aimed at a different
		// lock and a different service. The handler reads none of it.
		const otherLock = (await locksOtherThan(instance, lockId))[0];
		expect(otherLock, 'the seeded house should carry more than one lock').toBeTruthy();
		// Lock it first: the demo integration does not start every lock locked, and
		// an assertion that a door "stayed" locked proves nothing if it was open
		// the whole time.
		await setState(instance, 'lock', 'lock', otherLock);
		await waitForState(instance, otherLock, 'locked');

		const confirmation = await pendingUnlock();
		const res = await post(
			home.id,
			{
				confirmation_id: confirmation.id,
				domain: 'lock',
				service: 'unlock',
				entity_id: otherLock,
				data: { entity_id: otherLock },
				confirmed: true,
			},
			{ csrf: await csrfFor(owner.id) },
		);

		expect(res.status).toBe(200);
		// What ran is what was frozen at mint time, not what the body asked for.
		expect(res.body.entity_ids).toEqual([lockId]);
		await waitForState(instance, lockId, 'unlocked');
		expect(await readState(instance, otherLock)).toBe('locked');
	}, 120_000);

	it('refuses an unauthenticated caller outright', async () => {
		const res = await post(home.id, { confirmation_id: crypto.randomUUID() }, { cookie: null });
		expect(res.status).toBe(401);
		expect(res.body.error).toBe('unauthorized');
	}, 60_000);

	it('lists what is waiting so a chat card that lost its state can recover it', async () => {
		const confirmation = await pendingUnlock();
		const res = await fetch(confirmUrl(home.id), { headers: { cookie: ownerCookie } });
		expect(res.status).toBe(200);
		const body = await res.json();
		expect(body.pending.map((p) => p.id)).toContain(confirmation.id);
		// A summary a person can act on, naming the entity rather than the call.
		expect(body.pending.find((p) => p.id === confirmation.id).summary).toMatch(/unlock/i);
	}, 60_000);
});

// ── Harness ──────────────────────────────────────────────────────────────────

/**
 * Bind one API handler to a real port. The handlers are plain
 * `(req, res)` functions, so this is the same shape `server/index.mjs` gives
 * them in production, minus the route table.
 */
async function listen(handler) {
	const server = http.createServer((req, res) => {
		// `wrap` reads `req.query` the way the filesystem router populates it.
		const url = new URL(req.url, 'http://127.0.0.1');
		req.query = Object.fromEntries(url.searchParams);
		const parts = url.pathname.split('/').filter(Boolean);
		if (parts[0] === 'api' && parts[1] === 'home' && parts[3] === 'confirm') req.query.id = parts[2];
		Promise.resolve(handler(req, res)).catch(() => {
			if (!res.headersSent) res.writeHead(500).end('{}');
		});
	});
	await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
	return { server, url: `http://127.0.0.1:${server.address().port}` };
}

function close(handle) {
	if (!handle) return Promise.resolve();
	return new Promise((resolve) => handle.server.close(resolve));
}

/** Every lock in the seeded house that is not the one under test. */
async function locksOtherThan(instance, lockId) {
	const res = await fetch(`${instance.baseUrl}/api/states`, {
		headers: { authorization: `Bearer ${instance.token}` },
	});
	const states = await res.json();
	return states.map((s) => s.entity_id).filter((id) => id.startsWith('lock.') && id !== lockId);
}