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
#!/usr/bin/env node
/**
* Run order 04's physical-action gate against a relayed home, from a network
* with no route to that home, and show the audit trail it leaves.
*
* scripts/home-relay-e2e.mjs already drives the gate at the bridge layer, which
* proves the transport does not swallow a refusal. This script tests the layer
* the product actually runs: `runHomeTool`, `mintConfirmation`, the claim and
* perform that api/home/[id]/confirm.js does, and the `home_action_log` rows
* all of that writes. The distinction matters because the gate is enforced in
* two places and only one of them is the bridge.
*
* What it asserts, in order:
*
* 1. three.ws holds no address and no credential for this house, so "cannot
* route to it" understates the position: there is nothing to route to.
* 2. Locking up runs with no prompt. A product that nags on the safe
* direction is a product people turn off.
* 3. Unlocking does NOT run. It returns a pending confirmation, and the door
* is still locked afterwards.
* 4. Redeeming that confirmation really unlocks the real door, and the same
* confirmation cannot be redeemed twice.
* 5. The same refusal over real HTTP, through the real
* `POST /api/home/:id/call` handler on a real port with a real session
* cookie and a real CSRF token, because the status code a client actually
* sees is decided there and nowhere else: an unconfirmed unlock is **409**
* carrying the resolved target, and the same call repeated with a person's
* `confirmed: true` is 200 and a door that really opens.
* 6. Every one of those wrote a `home_action_log` row with the same columns
* populated as a direct connection writes, so the transport creates no
* audit gap.
*
* It is invoked by scripts/home-relay-live.mjs, which builds the unroutable rig
* and passes the home it paired. Against a rig kept up with --keep:
*
* node scripts/home-relay-gate-proof.mjs --home <uuid> --user <uuid>
*
* Needs DATABASE_URL, JWT_SECRET (the HTTP section mints a real session and a
* real CSRF token) and the three HOME_RELAY_* variables in the environment.
*/
import http from 'node:http';
import { runHomeTool } from '../api/_lib/home/tools.js';
import { claimConfirmation, finalizeConfirmation } from '../api/_lib/home/confirm.js';
import { withHome, closeHome } from '../api/_lib/home/runtime.js';
import { logHomeActionNow } from '../api/_lib/home/store.js';
import { createSession } from '../api/_lib/auth.js';
import { issueCsrf } from '../api/_lib/csrf.js';
import { sql } from '../api/_lib/db.js';
const args = parseArgs(process.argv.slice(2));
const homeId = need('home');
const userId = need('user');
const ctx = { userId, source: 'api' };
const results = [];
let failures = 0;
function step(name, ok, detail) {
results.push({ name, ok, detail });
if (!ok) failures += 1;
console.log(`${ok ? 'PASS' : 'FAIL'} ${name}${detail ? `\n ${detail}` : ''}`);
}
// 1. The house is on a network this process cannot reach, and for a relayed
// home there is no address stored to reach it by. Both are true; the second
// is the stronger claim, so it is the one asserted here.
const [row] = await sql`
select transport, relay_id, base_url, access_token_enc, token_fingerprint
from home_connections where id = ${homeId}`;
step(
'three.ws holds no way to dial this house directly',
row?.transport === 'relay' && row.access_token_enc === '' && row.token_fingerprint === '' && row.base_url === `relay://${row.relay_id}`,
`transport=${row?.transport} base_url=${row?.base_url} access_token_enc=${JSON.stringify(row?.access_token_enc)} token_fingerprint=${JSON.stringify(row?.token_fingerprint)}`,
);
// The read tool, over the relay, before anything is changed.
const status = await runHomeTool('home_status', { home_id: homeId }, ctx);
step(
'home_status reads the house over the relay',
status.ok === true && !status.structured?.stale,
`rooms=${status.structured?.summary?.rooms} entities=${status.structured?.summary?.entities} locks=${status.structured?.summary?.locks} stale=${status.structured?.stale}`,
);
const lockId = await withHome(homeId, userId, (bridge) =>
Object.keys(bridge.states).filter((id) => id.startsWith('lock.') && bridge.states[id].state !== 'unavailable').sort()[0],
);
if (!lockId) {
step('a lock exists to gate', false, 'no lock.* entity in this house');
await finish();
}
// 2. The safe direction, which must not prompt.
const locked = await runHomeTool('home_call', { home_id: homeId, domain: 'lock', service: 'lock', data: { entity_id: lockId } }, ctx);
step(
'locking up runs immediately over the relay, with no prompt',
locked.ok === true,
`${lockId}: ok=${locked.ok} kind=${locked.kind} status=${locked.structured?.status || 'ran'}`,
);
await settleLock(lockId, 'locked');
// 3. The guarded direction, which must not run.
const refused = await runHomeTool('home_call', { home_id: homeId, domain: 'lock', service: 'unlock', data: { entity_id: lockId } }, ctx);
const pending = refused.structured?.confirmation;
step(
'an unlock over the relay is refused and returns a pending confirmation',
refused.ok === false && refused.kind === 'pending_confirmation' && Boolean(pending?.id),
`ok=${refused.ok} kind=${refused.kind} status=${refused.structured?.status} risk=${pending?.risk} summary=${JSON.stringify(pending?.summary)} expires_in=${pending?.expires_in_seconds}s confirm_url=${pending?.confirm_url}`,
);
if (!pending?.id) await finish();
const heldShut = await readLock(lockId);
step(
'the door did not move while the confirmation was pending',
heldShut === 'locked',
`${lockId} is ${heldShut} after the refused unlock`,
);
// 4. The redemption, performed exactly as api/home/[id]/confirm.js performs it:
// claim the frozen action, then call with `confirmed: true` on a server that
// is holding a redeemed claim. That flag is set in no other place.
const claim = await claimConfirmation({ id: pending.id, homeId, userId });
step('the confirmation claims once, for its owner', claim.ok === true, claim.ok ? `claimed ${pending.id}` : `${claim.reason}: ${claim.message}`);
if (!claim.ok) await finish();
const action = claim.confirmation;
let performed = null;
try {
await withHome(homeId, userId, (bridge) => bridge.call(action.domain, action.service, action.service_data, { confirmed: true }));
await finalizeConfirmation(action.id, 'ok');
performed = 'ok';
} catch (err) {
await finalizeConfirmation(action.id, 'failed');
performed = String(err?.message || err);
}
await logHomeActionNow({
homeId,
userId,
actor: 'user',
channel: 'websocket',
action: `${action.domain}.${action.service}`,
entityIds: action.entity_ids,
guarded: true,
confirmedBy: userId,
risk: action.risk,
outcome: performed === 'ok' ? 'ok' : 'failed',
detail: { confirmation_id: action.id, source: action.source },
});
const unlocked = await settleLock(lockId, 'unlocked');
step(
'the redeemed confirmation really unlocks the real door',
performed === 'ok' && unlocked === 'unlocked',
`${lockId}: locked -> ${unlocked}, confirmation ${action.id} redeemed by a human's claim (${performed})`,
);
// The same confirmation must not redeem twice.
const replay = await claimConfirmation({ id: pending.id, homeId, userId });
step(
'the same confirmation cannot be redeemed again',
replay.ok === false,
replay.ok ? 'a second claim on the same confirmation succeeded' : `${replay.reason}: ${replay.message}`,
);
// 5. The same gate over real HTTP.
//
// Everything above ran the tool layer in this process. The status code a client
// actually receives is decided in `api/home/[id]/call.js`, which shapes a
// NEEDS_CONFIRMATION failure into 409 through the table in
// `api/_lib/home/errors.js`, and answers a repeat carrying a person's
// `confirmed: true` by performing it. That path is transport-independent by
// construction, and the only way to show it is by driving the real handler over
// a real socket rather than reading the mapping out of the source.
//
// The section above left the door open, and a refusal proves nothing against a
// door that is already unlocked. Lock it for real rather than waiting for a
// state that would never arrive.
await runHomeTool('home_call', { home_id: homeId, domain: 'lock', service: 'lock', data: { entity_id: lockId } }, ctx);
await settleLock(lockId, 'locked');
const api = await serveHomeApi();
try {
const cookie = `__Host-sid=${await createSession({ userId, recordActivity: false })}`;
// A CSRF token is consumed by the request that presents it (`requireCsrf`
// validates and deletes in one statement), so every POST below mints its own.
// Reusing one is how this section first read a 403 and looked like a gate
// failure when it was a spent token.
const csrf = () => issueCsrf(userId).then((issued) => issued.token);
const unlockBody = { domain: 'lock', service: 'unlock', data: { entity_id: lockId } };
const refusedHttp = await api.post(`/api/home/${homeId}/call`, unlockBody, { cookie, csrf: await csrf() });
step(
'POST /api/home/:id/call answers an unconfirmed unlock with 409 over the relay',
refusedHttp.status === 409 && refusedHttp.body?.error === 'needs_confirmation' && refusedHttp.body?.pending?.entityId === lockId,
`HTTP ${refusedHttp.status} ${JSON.stringify(refusedHttp.body?.error)} pending=${JSON.stringify(refusedHttp.body?.pending)}`,
);
const heldByHttp = await readLock(lockId);
step('the door did not move on the 409', heldByHttp === 'locked', `${lockId} is ${heldByHttp} after the refused HTTP unlock`);
// The person's yes, re-POSTing the SAME call the 409 described. Same session,
// same body, one added flag.
const confirmedHttp = await api.post(`/api/home/${homeId}/call`, { ...unlockBody, confirmed: true }, { cookie, csrf: await csrf() });
const openedByHttp = await settleLock(lockId, 'unlocked');
step(
'the same call with a human\'s confirmed:true is 200 and the real door opens',
confirmedHttp.status === 200 && openedByHttp === 'unlocked',
`HTTP ${confirmedHttp.status} confirmed=${confirmedHttp.body?.confirmed} risk=${confirmedHttp.body?.risk}, ${lockId}: locked -> ${openedByHttp}`,
);
} finally {
await api.close();
}
// Put the house back the way it was found.
await runHomeTool('home_call', { home_id: homeId, domain: 'lock', service: 'lock', data: { entity_id: lockId } }, ctx).catch(() => null);
await settleLock(lockId, 'locked');
// 6. The audit trail. Completeness is the claim, so every row is printed whole
// rather than summarised.
const rows = await sql`
select id, home_id, user_id, actor, channel, action, entity_ids, guarded,
confirmed_by, risk, outcome, detail, created_at
from home_action_log where home_id = ${homeId} order by id asc`;
console.log(`\n---- home_action_log for the relayed home ${homeId} ----`);
for (const entry of rows) console.log(JSON.stringify(entry));
console.log('---- end action log ----\n');
// The columns a direct connection fills are the columns these must fill. The
// nullable ones (user_id, confirmed_by, risk, detail) are checked where they
// are meant to be present rather than everywhere.
const complete = (entry) =>
Boolean(entry.home_id) && Boolean(entry.user_id) && Boolean(entry.actor) && Boolean(entry.channel) &&
Boolean(entry.action) && Array.isArray(entry.entity_ids) && entry.entity_ids.length > 0 &&
typeof entry.guarded === 'boolean' && Boolean(entry.outcome) && Boolean(entry.created_at);
const confirmedRow = rows.find((entry) => entry.guarded && entry.confirmed_by);
step(
'every relayed action wrote a complete audit row',
rows.length >= 3 && rows.every(complete) && Boolean(confirmedRow),
`${rows.length} rows, all core columns populated: ${rows.every(complete)}. ` +
`Refusal logged: ${rows.some((e) => e.outcome === 'refused')}. ` +
`Confirmed row carries confirmed_by=${confirmedRow?.confirmed_by || 'none'} risk=${confirmedRow?.risk || 'none'}.`,
);
await finish();
// -------------------------------------------------------------- small parts
async function finish() {
// closeHome is synchronous in the runtime's export surface, so it is wrapped
// rather than awaited with a `.catch` that would not exist on its return.
try {
await closeHome(homeId);
} catch {
// The pool is being torn down anyway; a failure here would only mask the
// result the script exists to report.
}
console.log(`\n${results.length - failures}/${results.length} checks passed.`);
process.exit(failures ? 1 : 0);
}
function need(name) {
const value = args[name];
if (!value) {
console.error(`Missing --${name}. See the header of this file.`);
process.exit(2);
}
return value;
}
/**
* The real `POST /api/home/:id/call` handler on a real port.
*
* It is a plain `(req, res)` function, which is the same shape
* `server/index.mjs` hands it in production; the only thing missing is the
* route table, so the path is split here the way the filesystem router splits
* it. Nothing is stubbed: the request crosses a socket, carries a real session
* cookie and a real CSRF header, and comes back with the status the product
* would return.
*/
async function serveHomeApi() {
const call = (await import('../api/home/[id]/call.js')).default;
const server = http.createServer((req, res) => {
const url = new URL(req.url, 'http://127.0.0.1');
req.query = Object.fromEntries(url.searchParams);
req.query.id = url.pathname.split('/').filter(Boolean)[2];
Promise.resolve(call(req, res)).catch(() => {
if (!res.headersSent) res.writeHead(500).end('{}');
});
});
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
const base = `http://127.0.0.1:${server.address().port}`;
return {
post: async (path, body, { cookie, csrf } = {}) => {
const res = await fetch(`${base}${path}`, {
method: 'POST',
headers: {
'content-type': 'application/json',
...(cookie ? { cookie } : {}),
...(csrf ? { 'x-csrf-token': csrf } : {}),
},
body: JSON.stringify(body),
});
return { status: res.status, body: await res.json().catch(() => null) };
},
close: () => new Promise((resolve) => server.close(resolve)),
};
}
async function readLock(entityId) {
return withHome(homeId, userId, (bridge) => bridge.states[entityId]?.state);
}
/** Waits for the live state channel to report the change, not a fixed delay. */
async function settleLock(entityId, want, timeoutMs = 10_000) {
const deadline = Date.now() + timeoutMs;
let state = await readLock(entityId);
while (Date.now() < deadline && state !== want) {
await new Promise((resolve) => setTimeout(resolve, 200));
state = await readLock(entityId);
}
return state;
}
function parseArgs(argv) {
const out = {};
for (let i = 0; i < argv.length; i += 1) {
if (!argv[i].startsWith('--')) continue;
const key = argv[i].slice(2);
const next = argv[i + 1];
if (next && !next.startsWith('--')) {
out[key] = next;
i += 1;
} else {
out[key] = true;
}
}
return out;
}