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.

5.8 KB
Raw Blame
// api/world/[action]: the generic per-world persistence service (T3).
//
//   GET  /api/world/load?worldId=<id>
//     Public. Returns the world's current document + concurrency metadata, or
//     { doc: null } if it has never been saved. Builds are shared, visible
//     places, so reads are open (rate-limited by IP).
//
//   POST /api/world/save   { worldId, doc, ifMatch?, owner? }
//     Authenticated. The authoritative multiplayer server writes with a service
//     token (Authorization: Bearer <world-service-token>); a browser session may
//     write subject to the per-world permission model (world-store.canWriteWorld,
//     the hook T16 tightens). `ifMatch` carries the etag the caller last read for
//     optimistic concurrency, so a stale etag returns 409.
//
// Storage lives in api/_lib/world-store.js (Postgres index + R2 blob offload).

import { cors, json, method, wrap, error, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { extractBearer } from '../_lib/auth.js';
import { resolveAccount } from '../_lib/account-auth.js';
import { verifyWorldServiceToken } from '../_lib/world-service-auth.js';
import {
	loadWorld,
	loadWorldMeta,
	saveWorld,
	canWriteWorld,
	isValidWorldId,
	ConflictError,
	TooLargeError,
	PermissionError,
	MAX_DOC_BYTES,
} from '../_lib/world-store.js';

const BODY_ERROR_CODES = { 413: 'payload_too_large', 415: 'unsupported_media_type' };

function actionOf(req) {
	return (req.query?.action || new URL(req.url, 'http://x').pathname.split('/').pop() || '').toLowerCase();
}

export default wrap(async (req, res) => {
	// Public reads + server-to-server writes use a wildcard origin. Browser saves
	// are same-origin (three.ws → three.ws), so the session cookie rides along
	// without needing credentialed CORS.
	if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;

	const action = actionOf(req);
	if (action === 'load') return handleLoad(req, res);
	if (action === 'save') return handleSave(req, res);
	return error(res, 404, 'not_found', 'unknown world action');
});

async function handleLoad(req, res) {
	if (!method(req, res, ['GET'])) return;

	const rl = await limits.publicIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const worldId = new URL(req.url, 'http://x').searchParams.get('worldId') || '';
	if (!isValidWorldId(worldId)) return error(res, 400, 'validation_error', 'invalid or missing worldId');

	const world = await loadWorld(worldId);
	if (!world) return json(res, 200, { worldId, doc: null, version: 0, etag: null });

	return json(res, 200, {
		worldId: world.worldId,
		doc: world.doc,
		version: world.version,
		etag: world.etag,
		schemaVersion: world.schemaVersion,
		ownerId: world.ownerId,
		updatedAt: world.updatedAt,
	});
}

async function handleSave(req, res) {
	if (!method(req, res, ['POST'])) return;

	// Principal resolution: a valid service token outranks a session and marks the
	// write as authoritative (the game server). Otherwise fall back to the caller's
	// browser session / bearer identity.
	const service = await verifyWorldServiceToken(extractBearer(req));
	let writer = null;
	let account = null;
	if (service) {
		writer = 'service';
	} else {
		account = await resolveAccount(req, res);
		if (!account) return error(res, 401, 'unauthorized', 'authentication required to write a world');
		writer = account.userId;
		const rl = await limits.prefsWrite(account.userId);
		if (!rl.success) return rateLimited(res, rl, 'too many world saves');
	}

	let body;
	try {
		body = await readJson(req, MAX_DOC_BYTES + 1024);
	} catch (err) {
		// readJson signals an over-cap body as 413 and a non-JSON content-type as
		// 415. Labelling either one `validation_error` left a client unable to tell
		// "your build is too big" from "your JSON is malformed", so each status
		// keeps the house error code its own status already implies.
		const status = err.status || 400;
		const code = BODY_ERROR_CODES[status] || 'validation_error';
		return error(res, status, code, err.message || 'invalid body');
	}

	const { worldId, doc, ifMatch, owner } = body || {};
	if (!isValidWorldId(worldId)) return error(res, 400, 'validation_error', 'invalid or missing worldId');
	if (doc === undefined || doc === null || typeof doc !== 'object') {
		return error(res, 400, 'validation_error', 'doc must be a JSON object or array');
	}
	if (ifMatch != null && ifMatch !== '*' && typeof ifMatch !== 'string') {
		return error(res, 400, 'validation_error', 'ifMatch must be an etag string, "*", or null');
	}

	// Permission gate. Service writes are always allowed; user writes depend on the
	// world's current owner, so peek at the index row first. loadWorldMeta reads
	// only the index columns (never the body), which keeps a builder's autosave to
	// one cheap lookup instead of re-downloading and re-parsing the whole prior
	// document. It returns null for a brand-new world (unowned, first writer allowed).
	if (!service) {
		const existing = await loadWorldMeta(worldId);
		const allowed = canWriteWorld({
			isService: false,
			account: account.userId,
			currentOwner: existing?.ownerId ?? null,
			exists: Boolean(existing),
		});
		if (!allowed) return error(res, 403, 'forbidden', 'not permitted to build in this world');
	}

	// On first save by a user, stamp them as the owner so they keep edit rights.
	const ownerToSet = service ? (typeof owner === 'string' ? owner : null) : account.userId;

	try {
		const result = await saveWorld({ worldId, doc, ifMatch: ifMatch ?? null, writer, owner: ownerToSet });
		return json(res, 200, result);
	} catch (err) {
		if (err instanceof ConflictError) {
			return error(res, 409, err.code, err.message, { etagMismatch: true });
		}
		if (err instanceof TooLargeError) {
			return error(res, 413, err.code, err.message);
		}
		if (err instanceof PermissionError) {
			return error(res, 403, err.code, err.message);
		}
		throw err;
	}
}