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 connection store: where a user's homes live, and the only module that
// ever touches a home's credential.
//
// Everything here takes and returns plain objects. No HTTP, no `res`, no Home
// Assistant. The runtime (api/_lib/home/runtime.js) and the endpoints
// (api/home/*) sit above it, and neither of them is allowed to write SQL
// against these tables or to read a credential column.
//
// Two invariants this module enforces so its callers cannot get them wrong:
//
// 1. A connection row is NEVER returned with `access_token_enc` on it. The
// safe projection is built in SQL (SAFE_COLUMNS below), so a new caller
// cannot accidentally spread a credential into a response body.
// 2. Ownership is a `where user_id = $1` inside every query, never a check in
// JavaScript after the row is already in hand. A miss and a
// wrong-owner both return null, so the store never leaks the existence of
// another user's home.
//
// `getDecryptedToken` is the single exception to (1), which is exactly why it is
// its own export with its own name: every call site that can hold a plaintext
// key to someone's front door is one grep away.
import { createHash } from 'node:crypto';
import { normalizeBaseUrl } from '../../../packages/home-bridge/src/url.js';
import { logAudit } from '../audit.js';
import { sql } from '../db.js';
import { withDbRetry } from '../db-retry.js';
import { decryptSecret, encryptSecret } from '../secret-box.js';
import { scrubSecrets } from '../scrub-secrets.js';
import { safeError } from './log-safe.js';
/** Statuses the schema's check constraint accepts. */
export const HOME_STATUS = Object.freeze({
PENDING: 'pending',
CONNECTED: 'connected',
UNREACHABLE: 'unreachable',
AUTH_FAILED: 'auth_failed',
REVOKED: 'revoked',
});
const VALID_STATUSES = new Set(Object.values(HOME_STATUS));
const VALID_TRANSPORTS = new Set(['direct', 'relay']);
const LABEL_MAX = 120;
const DETAIL_MAX = 500;
// Every column a caller may see. `access_token_enc` is absent on purpose and
// must stay absent: this list is the mechanical guarantee behind invariant (1).
// Built on first use rather than at module load. `sql` is the database driver:
// calling it while this module is being imported does driver work before any
// caller has asked for a query, which made merely IMPORTING this file fail
// wherever the driver is absent or stubbed. That took the whole critical-path
// test gate down (tests/api/healthz.test.js reaches store.js through
// home/runtime.js and never gets to run a single test). Memoized, so the
// fragment is still built exactly once per process.
let safeColumnsFragment = null;
function SAFE_COLUMNS() {
if (!safeColumnsFragment) {
safeColumnsFragment = sql`
id, user_id, label, base_url, token_fingerprint, transport, relay_id,
capabilities, status, status_detail, last_ok_at, last_error_at,
created_at, updated_at, revoked_at
`;
}
return safeColumnsFragment;
}
// The same projection, qualified, for the reads that join home_members.
//
// Those reads answer "may this caller see this home" through membership rather
// than through `user_id` equality, and a join makes the bare list ambiguous:
// home_members carries a user_id of its own. `c.user_id` stays on the row and
// keeps meaning what it always meant, the account that connected the house,
// which is why order 12 could add membership beside this column instead of
// rewriting it.
let safeColumnsCFragment = null;
function SAFE_COLUMNS_C() {
if (!safeColumnsCFragment) {
safeColumnsCFragment = sql`
c.id, c.user_id, c.label, c.base_url, c.token_fingerprint, c.transport, c.relay_id,
c.capabilities, c.status, c.status_detail, c.last_ok_at, c.last_error_at,
c.created_at, c.updated_at, c.revoked_at
`;
}
return safeColumnsCFragment;
}
/** sha256 of the token, hex. Never reversible, only comparable. */
export function fingerprintToken(token) {
return createHash('sha256').update(String(token), 'utf8').digest('hex');
}
/**
* Record that a user connected a house, or refresh the record they already had.
*
* The URL is normalized before it is written, because the unique index is over
* the normalized form: "https://home.example.com/" and "home.example.com" are
* the same house and must collide, not stack up as two live rows.
*
* Re-connecting the same house is an update, not a duplicate: a token rotation
* lands as new ciphertext and a new fingerprint on the SAME row, so the grants
* and the action log that reference it survive the rotation.
*
* @param {object} input
* @param {string} input.userId
* @param {string} input.label what the user calls this home
* @param {string} input.baseUrl as typed; normalized before write
* @param {string} input.token a Home Assistant long-lived access token
* @param {'direct'|'relay'} [input.transport]
* @param {string|null} [input.relayId]
* @param {object} [input.capabilities] measured at connect, never assumed
* @param {string} [input.status]
* @param {string|null} [input.statusDetail]
* @returns {Promise<object>} the credential-free row
*/
export async function createConnection({
userId,
label,
baseUrl,
token,
transport = 'direct',
relayId = null,
capabilities = {},
status = HOME_STATUS.PENDING,
statusDetail = null,
}) {
if (!userId) throw new Error('createConnection: userId is required');
if (!token) throw new Error('createConnection: a Home Assistant access token is required');
if (!VALID_TRANSPORTS.has(transport)) throw new Error(`createConnection: unknown transport "${transport}"`);
if (!VALID_STATUSES.has(status)) throw new Error(`createConnection: unknown status "${status}"`);
const { http } = normalizeBaseUrl(baseUrl);
const cleanLabel = normalizeLabel(label) || hostOf(http);
const enc = await encryptSecret(String(token));
const fingerprint = fingerprintToken(token);
// A row created as `connected` was created because a handshake succeeded and
// its capabilities were measured, so the house has demonstrably answered and
// the timestamp that says so is true. Leaving it null was a real defect on
// the surface above: `last_ok_at` is what "Live, updated 2 minutes ago" and
// the whole staleness window read, and with it empty a house that had just
// connected could never go stale, never showed an age, and when it stopped
// answering fell back to the connect-time diagnosis and told its owner their
// address might be wrong. It was never wrong; the house was.
const okAt = status === HOME_STATUS.CONNECTED ? new Date() : null;
const rows = await sql`
insert into home_connections
(user_id, label, base_url, access_token_enc, token_fingerprint,
transport, relay_id, capabilities, status, status_detail, last_ok_at)
values
(${userId}, ${cleanLabel}, ${http}, ${enc}, ${fingerprint},
${transport}, ${relayId}, ${JSON.stringify(capabilities)}::jsonb, ${status}, ${truncate(statusDetail, DETAIL_MAX)}, ${okAt})
on conflict (user_id, base_url) where revoked_at is null
do update set
label = excluded.label,
access_token_enc = excluded.access_token_enc,
token_fingerprint = excluded.token_fingerprint,
transport = excluded.transport,
relay_id = excluded.relay_id,
capabilities = excluded.capabilities,
status = excluded.status,
status_detail = excluded.status_detail,
-- A reconnect that failed must not erase when the house last worked.
last_ok_at = coalesce(excluded.last_ok_at, home_connections.last_ok_at),
updated_at = now()
returning ${SAFE_COLUMNS()}
`;
return rows[0];
}
/**
* One user's live homes, newest first, with no credential on any of them.
* @param {string} userId
* @returns {Promise<object[]>}
*/
export async function listConnections(userId) {
if (!userId) return [];
return sql`
select ${SAFE_COLUMNS_C()}, m.role, m.entity_scope
from home_connections c
join home_members m on m.home_id = c.id and m.user_id = ${userId}
where c.revoked_at is null
order by c.created_at desc
`;
}
/**
* One home, ownership-checked in SQL.
*
* Returns null both when the id does not exist and when the caller is not in
* its household, so a caller cannot distinguish the two and turn this into an
* oracle for "does this home id exist". The endpoint layer maps null to 404,
* never 403.
*
* Entitlement is MEMBERSHIP, not ownership: the join against home_members is
* what lets a partner, a house sitter or a colleague reach a home somebody else
* connected. There is deliberately no `or c.user_id = ${userId}` beside it. Such
* a branch would look like belt and braces and would in fact be the bypass, and
* it is unnecessary: the migration's trigger gives every connection an owner row
* the moment it is inserted, so the account that connected a house is always in
* its household.
*
* The returned row carries `role` and `entity_scope`, because every caller that
* needs the home also needs to know what this member may do with it, and a
* second round trip to find out is a second place to forget.
*
* @param {string} id
* @param {string} userId
* @param {{ includeRevoked?: boolean }} [options]
* @returns {Promise<object|null>} the credential-free row plus `role` and `entity_scope`
*/
export async function getConnection(id, userId, { includeRevoked = false } = {}) {
if (!id || !userId || !isUuid(id)) return null;
const rows = includeRevoked
? await sql`
select ${SAFE_COLUMNS_C()}, m.role, m.entity_scope
from home_connections c
join home_members m on m.home_id = c.id and m.user_id = ${userId}
where c.id = ${id}
`
: await sql`
select ${SAFE_COLUMNS_C()}, m.role, m.entity_scope
from home_connections c
join home_members m on m.home_id = c.id and m.user_id = ${userId}
where c.id = ${id} and c.revoked_at is null
`;
return rows[0] || null;
}
/**
* The ONLY function that returns a plaintext home credential.
*
* Its own export, its own name, so `grep -rn getDecryptedToken api/` is a
* complete list of the places a key to someone's house can be held in memory.
* It writes nothing and logs nothing: not the token, not a prefix of it, not its
* length. A revoked home has an empty ciphertext and returns null rather than
* throwing, because "this home was disconnected" is an ordinary state the caller
* has to render, not an exception.
*
* @param {string} id
* @param {string} userId
* @returns {Promise<{ token: string, baseUrl: string, transport: string, relayId: string|null, fingerprint: string }|null>}
*/
export async function getDecryptedToken(id, userId) {
if (!id || !userId || !isUuid(id)) return null;
const rows = await sql`
select c.access_token_enc, c.base_url, c.transport, c.relay_id, c.token_fingerprint
from home_connections c
join home_members m on m.home_id = c.id and m.user_id = ${userId}
where c.id = ${id} and c.revoked_at is null
`;
const row = rows[0];
if (!row || !row.access_token_enc) return null;
return {
token: await decryptSecret(row.access_token_enc),
baseUrl: row.base_url,
transport: row.transport,
relayId: row.relay_id,
fingerprint: row.token_fingerprint,
};
}
/**
* Record the outcome of a handshake against the house.
*
* Called by the runtime on every connect attempt, so the connect UI can explain
* a broken home without opening a socket of its own. `capabilities` is merged
* rather than replaced: a failed MCP probe must not erase the WebSocket
* capabilities a successful one measured a minute earlier.
*
* Ownership is not checked here on purpose: the caller has already proved it by
* holding the id, and the runtime reaches this from a background reconnect where
* no user is present. It is not reachable from an endpoint without a prior
* ownership-checked read.
*
* @param {string} id
* @param {{ status: string, statusDetail?: string|null, capabilities?: object|null }} update
* @returns {Promise<object|null>} the credential-free row
*/
export async function recordHandshake(id, { status, statusDetail = null, capabilities = null } = {}) {
if (!id || !isUuid(id)) return null;
if (!VALID_STATUSES.has(status)) throw new Error(`recordHandshake: unknown status "${status}"`);
const ok = status === HOME_STATUS.CONNECTED;
const rows = await sql`
update home_connections set
status = ${status},
status_detail = ${truncate(statusDetail, DETAIL_MAX)},
capabilities = case when ${capabilities === null}::boolean then capabilities
else capabilities || ${JSON.stringify(capabilities || {})}::jsonb end,
last_ok_at = case when ${ok}::boolean then now() else last_ok_at end,
last_error_at = case when ${ok}::boolean then last_error_at else now() end,
updated_at = now()
where id = ${id} and revoked_at is null
returning ${SAFE_COLUMNS()}
`;
return rows[0] || null;
}
/**
* Disconnect a home: soft delete the row, destroy the credential.
*
* The row survives so the action log keeps its lineage (an operator must still
* be able to answer "what did my agent do in my house last Tuesday" about a
* house they have since removed). The ciphertext does not survive: it is
* overwritten with '' in the same statement, so a database dump taken after a
* revoke cannot be replayed against the user's front door.
*
* Idempotent: revoking twice succeeds twice, and the second call reports
* `alreadyRevoked` rather than pretending it did the work again.
*
* @param {string} id
* @param {string} userId
* @returns {Promise<{ revoked: boolean, alreadyRevoked: boolean, home: object|null }>}
*/
export async function revokeConnection(id, userId) {
if (!id || !userId || !isUuid(id)) return { revoked: false, alreadyRevoked: false, home: null };
const rows = await sql`
update home_connections set
revoked_at = now(),
access_token_enc = '',
status = ${HOME_STATUS.REVOKED},
status_detail = 'Disconnected by the owner.',
updated_at = now()
where id = ${id} and user_id = ${userId} and revoked_at is null
returning ${SAFE_COLUMNS()}
`;
if (rows[0]) {
// The platform audit trail lives in a different table, with a different
// (365 day) window and a different set of readers, and its rows outlive
// the account that made them (audit_log.user_id is set null on deletion,
// not removed). So it gets the correlation key and nothing else: never the
// base URL, which is the address of somebody's building, and never the
// label, which is a name a person chose ("Mum's flat"). The home id is
// enough to join back to the row while it exists, and meaningless after.
logAudit({
userId,
action: 'revoke_home_connection',
resourceId: id,
meta: { transport: rows[0].transport, status: rows[0].status },
});
return { revoked: true, alreadyRevoked: false, home: rows[0] };
}
// Either it was already revoked, or it is not this user's. Distinguish those
// for the caller (one is a 200, the other a 404) without a second read that
// could leak existence: the ownership filter is still in the query.
const existing = await getConnection(id, userId, { includeRevoked: true });
return { revoked: false, alreadyRevoked: Boolean(existing), home: existing };
}
/**
* Grant the agent a standing allowance for ONE entity in one home.
*
* Per entity and per home, never per domain: letting the agent open the office
* door is not letting it open the front door. Re-granting refreshes the expiry
* on the existing row so a user extending "just for tonight" does not
* accumulate rows.
*
* @param {{ homeId: string, entityId: string, grantedBy: string, expiresAt?: Date|string|null }} input
* @returns {Promise<object>}
*/
export async function grantEntity({ homeId, entityId, grantedBy, expiresAt = null }) {
if (!homeId || !isUuid(homeId)) throw new Error('grantEntity: homeId is required');
if (!grantedBy) throw new Error('grantEntity: grantedBy is required');
const entity = normalizeEntityId(entityId);
const rows = await sql`
insert into home_entity_grants (home_id, entity_id, granted_by, expires_at)
values (${homeId}, ${entity}, ${grantedBy}, ${expiresAt ? new Date(expiresAt) : null})
on conflict (home_id, entity_id) do update set
granted_by = excluded.granted_by,
expires_at = excluded.expires_at,
created_at = now()
returning id, home_id, entity_id, granted_by, expires_at, created_at
`;
return rows[0];
}
/**
* Withdraw a standing allowance. Idempotent.
* @param {{ homeId: string, entityId: string }} input
* @returns {Promise<boolean>} true when a grant was actually removed
*/
export async function revokeGrant({ homeId, entityId }) {
if (!homeId || !isUuid(homeId)) return false;
const rows = await sql`
delete from home_entity_grants
where home_id = ${homeId} and entity_id = ${normalizeEntityId(entityId)}
returning id
`;
return rows.length > 0;
}
/**
* The live allowances for a home.
*
* Expiry is filtered in SQL, not in JavaScript: an expired grant that reaches a
* caller is an entity the gate would wave through, and "the caller remembered to
* check the date" is not a security boundary.
*
* @param {string} homeId
* @returns {Promise<object[]>}
*/
export async function listGrants(homeId) {
if (!homeId || !isUuid(homeId)) return [];
return sql`
select id, home_id, entity_id, granted_by, expires_at, created_at
from home_entity_grants
where home_id = ${homeId}
and (expires_at is null or expires_at > now())
order by entity_id asc
`;
}
/**
* The set of entity ids the gate may wave through for this home, ready to hand
* to `createAllowList` in the bridge.
* @param {string} homeId
* @returns {Promise<string[]>}
*/
export async function listAllowedEntities(homeId) {
const grants = await listGrants(homeId);
return grants.map((g) => g.entity_id);
}
/**
* Record a write the platform performed against a house.
*
* Fire and forget, mirroring api/_lib/audit.js: it never throws and never blocks
* a response, because a logging failure must not be able to stop a light from
* turning on. Use `logHomeActionNow` where the row IS the deliverable.
*
* @param {object} entry see logHomeActionNow
*/
export function logHomeAction(entry) {
queueMicrotask(() => {
logHomeActionNow(entry);
});
}
/**
* The same write, awaitable, resolving true when the row landed.
*
* @param {object} entry
* @param {string} entry.homeId
* @param {string|null} [entry.userId] null when an agent principal acted with no account
* @param {'user'|'agent'|'voice'|'mcp'|'automation'} entry.actor
* @param {'websocket'|'mcp'} entry.channel
* @param {string} entry.action `light.turn_on`, or the MCP tool name
* @param {string[]} [entry.entityIds] resolved targets, not the raw argument
* @param {boolean} [entry.guarded] did the physical-action gate fire
* @param {string|null} [entry.confirmedBy] who said yes, when it did
* @param {'security'|'physical'|null} [entry.risk]
* @param {'ok'|'refused'|'failed'} entry.outcome
* @param {object|null} [entry.detail] small; no state dumps. Passed through
* scrubSecrets() before it lands, so a caller that spreads an options object
* carrying a token into it writes '[redacted]' rather than a key to a house.
* @returns {Promise<boolean>}
*/
export async function logHomeActionNow({
homeId,
userId = null,
actor,
channel,
action,
entityIds = [],
guarded = false,
confirmedBy = null,
risk = null,
outcome,
detail = null,
}) {
try {
await withDbRetry(
() => sql`
insert into home_action_log
(home_id, user_id, actor, channel, action, entity_ids, guarded, confirmed_by, risk, outcome, detail)
values
(${homeId}, ${userId}, ${actor}, ${channel}, ${action},
${entityIds.map(String)}, ${Boolean(guarded)}, ${confirmedBy}, ${risk}, ${outcome},
${detail === null ? null : JSON.stringify(scrubSecrets(detail))}::jsonb)
`,
{ timeoutMs: 5_000 },
);
return true;
} catch (err) {
// Ids and a service name only. `action` is a Home Assistant service or an
// MCP tool name ('light.turn_on'), never a friendly name, and the entity
// ids are deliberately absent: correlating a dropped write needs the home
// and the verb, not the list of things in somebody's bedroom. A driver
// error can echo a bound parameter, so it goes through safeError() like
// every other error in the lane: a code, and a message with every host
// stripped out of it.
console.warn('[home-store] action log insert dropped', { homeId, action, outcome, ...safeError(err) });
return false;
}
}
/**
* What the agent did in this house, most recent first.
* @param {string} homeId
* @param {{ limit?: number, before?: Date|string|null }} [options]
* @returns {Promise<object[]>}
*/
export async function listHomeActions(homeId, { limit = 50, before = null } = {}) {
if (!homeId || !isUuid(homeId)) return [];
const cap = Math.min(Math.max(Number(limit) || 50, 1), 200);
return before
? 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} and created_at < ${new Date(before)}
order by created_at desc
limit ${cap}
`
: 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 created_at desc
limit ${cap}
`;
}
function normalizeLabel(label) {
return typeof label === 'string' ? label.trim().slice(0, LABEL_MAX) : '';
}
function normalizeEntityId(entityId) {
const id = String(entityId || '').trim().toLowerCase();
if (!/^[a-z_]+\.[a-z0-9_]+$/.test(id)) {
throw new Error(`grantEntity: "${entityId}" is not an entity id. Grants are per entity, never per domain.`);
}
return id;
}
function truncate(value, max) {
if (value === null || value === undefined) return null;
return String(value).slice(0, max);
}
function hostOf(url) {
try {
return new URL(url).hostname;
} catch {
return 'Home';
}
}
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
function isUuid(value) {
return UUID_RE.test(String(value));
}