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
// Who is allowed to touch a home, resolved once, for every /api/home/* route.
//
// Three things go wrong when each route answers this for itself, and all three
// have shipped in real products:
//
// 1. One route authenticates with a session and another forgets the bearer
// path, so the agent lane silently 401s (or worse, the reverse).
// 2. One route checks ownership with a `WHERE user_id` and another fetches the
// row and compares in JavaScript. The second one is a tenancy bug waiting
// for a refactor to drop the comparison.
// 3. One route answers 403 for somebody else's home. A 403 confirms the id is
// real, which turns a list of uuids into an oracle for "is this a house".
// Across a tenancy boundary the answer is always 404.
//
// So: `resolveHomeAccess` is the only door. It authenticates, it reads the home
// through the store's ownership-filtered query, and it returns a discriminated
// result rather than throwing, because the caller is the only code that knows
// whether it is answering an SSE stream or a JSON POST.
import { authenticateBearer, extractBearer, getSessionUser, hasScope } from '../auth.js';
import { can, filterGraphForScope, normalizeScope, outOfScopeEntities } from './members.js';
import { getConnection } from './store.js';
/**
* Who is calling. Session first, then bearer, because a browser sends both a
* cookie and (on the agent lane) nothing else, and checking the cookie first
* keeps the common path off the token verification.
*
* @param {import('node:http').IncomingMessage} req
* @param {import('node:http').ServerResponse} [res]
* @returns {Promise<{ userId: string, via: 'session'|'bearer', scope: string|null }|null>}
*/
export async function resolveCaller(req, res) {
const session = await getSessionUser(req, res).catch(() => null);
if (session) return { userId: session.id, via: 'session', scope: null };
const bearer = await authenticateBearer(extractBearer(req)).catch(() => null);
if (bearer) return { userId: bearer.userId, via: 'bearer', scope: bearer.scope ?? null };
return null;
}
/**
* The OAuth scope a capability needs from a bearer principal.
*
* `home:read` and `home:act` are named on the consent screen the user approves,
* so a token that was never granted one must not reach the surface behind it.
* Reading is `home:read`; everything that changes a house, its roster, its
* layout or its standing allowances is `home:act`, because each of them is a
* write to somebody's building.
*
* A session principal is not scoped: the person is present, and the scopes exist
* to narrow what a DELEGATE may do on their behalf.
*/
const CAPABILITY_SCOPE = Object.freeze({
read: 'home:read',
act: 'home:act',
confirm: 'home:act',
grant: 'home:act',
layout: 'home:act',
invite: 'home:act',
manage: 'home:act',
disconnect: 'home:act',
});
/**
* The scope refusal for an account-level home route (list, connect, pair, plan)
* that has no single home to resolve through `resolveHomeAccess`, or null when
* the caller may proceed. Same table, same rule: a session is unscoped, a
* bearer needs the scope its capability maps to.
*
* @param {{ via?: string, scope?: string|null }|null} caller
* @param {string} capability
*/
export function homeScopeRefusal(caller, capability) {
const required = CAPABILITY_SCOPE[capability] || CAPABILITY_SCOPE.act;
if (caller?.via !== 'bearer' || hasScope(caller.scope, required)) return null;
return { status: 403, code: 'insufficient_scope', message: `${required} required. This token was not granted it.` };
}
/**
* Whether this caller may assert `confirmed: true`, the flag that stands for a
* human saying yes to opening a building.
*
* Only a browser session can. This is the same rule `api/home/:id/confirm.js`
* enforces for redeeming a minted confirmation, applied to the other half of the
* protocol: the routes that accept a confirmation inline. Without it the whole
* gate is optional, because `requireCsrf` exempts bearer callers by design (a
* token is not auto-attached by a browser, so there is nothing to forge), and a
* bearer caller could therefore write `confirmed: true` into a body and open a
* front door with no person anywhere in the request. Measured, before this
* existed: an API key holding only the `profile` scope unlocked a real deadbolt.
*
* `home:act` authorises ASKING to act. It has never authorised answering the
* question, and the consent screen says so in those words.
*
* @param {{ via?: string }|null} caller
*/
export function canAssertConfirmation(caller) {
return caller?.via === 'session';
}
/** The refusal a non-session principal gets when it claims a confirmation. */
export const CONFIRMATION_REQUIRES_SESSION = Object.freeze({
status: 403,
code: 'confirmation_requires_session',
message:
'A guarded action can only be confirmed by a signed-in person in a browser session. A bearer token, including one holding home:act, can ask to act and can never say yes on the account holder\'s behalf.',
});
/**
* Authenticate, then resolve one home this caller is entitled to, for a named
* capability.
*
* Two different refusals, and the difference is deliberate:
*
* 404 the caller is not in this household (or there is no such home, or it
* was disconnected). Indistinguishable on purpose: a 403 here would
* confirm the id is real and turn a list of uuids into an oracle for
* "is this a house".
* 403 the caller IS in the household and their role does not hold this
* capability. Naming the role is safe, and it is the only answer that
* lets a guest refused an unlock understand it is their role rather than
* a broken door.
*
* `capability` defaults to `read` because every route on this surface needs at
* least that, and a route that forgets to name one therefore fails closed at the
* weakest useful level rather than open.
*
* @param {import('node:http').IncomingMessage} req
* @param {import('node:http').ServerResponse} res
* @param {string} homeId from `req.query.id`
* @param {string} [capability] one of HOME_CAPABILITIES in ./members.js
* @returns {Promise<
* | { ok: true, caller: object, home: object, role: string, scope: object, scoped: boolean }
* | { ok: false, status: 401, code: 'unauthorized', message: string }
* | { ok: false, status: 404, code: 'not_found', message: string }
* | { ok: false, status: 403, code: 'insufficient_scope', message: string }
* | { ok: false, status: 403, code: 'role_forbidden', message: string, role: string }
* >}
*/
export async function resolveHomeAccess(req, res, homeId, capability = 'read') {
const caller = await resolveCaller(req, res);
if (!caller) {
return { ok: false, status: 401, code: 'unauthorized', message: 'Sign in to reach your home.' };
}
// The scope gate, and it runs BEFORE the home is read on purpose. It depends
// on nothing but the token, so it names a principal and never a house, and
// answering it first keeps a token that was never granted home access off the
// tenancy lookup entirely.
const required = CAPABILITY_SCOPE[capability];
if (caller.via === 'bearer' && required && !hasScope(caller.scope, required)) {
return {
ok: false,
status: 403,
code: 'insufficient_scope',
message: `${required} required. This token was not granted it.`,
caller,
};
}
// A malformed id is answered exactly like a real id you are not in. A 400
// here would tell an unauthenticated prober which of their guesses were even
// shaped like a home id.
const home = homeId ? await getConnection(homeId, caller.userId) : null;
if (!home) {
return { ok: false, status: 404, code: 'not_found', message: 'No such home.', caller };
}
const role = home.role;
const scope = normalizeScope(home.entity_scope, role);
if (capability && !can(role, capability)) {
return {
ok: false,
status: 403,
code: 'role_forbidden',
message: `${article(role)} cannot ${capability} in this home.`,
role,
capability,
caller,
home,
};
}
return { ok: true, caller, home, role, scope, scoped: scope.mode !== 'all' };
}
/** "an admin" / "a member": role names reach users as copy, not as identifiers. */
function article(role) {
return /^[aeiou]/i.test(String(role)) ? `an ${role}` : `a ${role}`;
}
/**
* The room graph as this member is allowed to see it.
*
* Re-exported from ./members.js through this module so every route reaches
* scope filtering from the same import it already uses for access, and a route
* that renders a graph without filtering it reads as an obvious omission rather
* than as one missing import among many.
*/
export { filterGraphForScope, outOfScopeEntities };
/**
* The credential-free projection every route returns for a home.
*
* Built here rather than in each route so a new column added to the table does
* not leak by default: a field reaches a client because it is listed below, not
* because it happened to be on the row. `access_token_enc` never reaches this
* function at all (the store's SAFE_COLUMNS drops it in SQL), so this is the
* second of two independent guards, not the only one.
*
* @param {object} row a row from api/_lib/home/store.js
*/
export function publicHome(row) {
if (!row) return null;
return {
id: row.id,
label: row.label,
base_url: row.base_url,
transport: row.transport,
relay_id: row.relay_id ?? null,
status: row.status,
status_detail: row.status_detail ?? null,
capabilities: row.capabilities ?? {},
last_ok_at: row.last_ok_at ?? null,
last_error_at: row.last_error_at ?? null,
created_at: row.created_at,
updated_at: row.updated_at,
revoked_at: row.revoked_at ?? null,
};
}