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
/**
* IRL World Lines — agent-placed proof-of-presence AR quests.
*
* A World Line is a persistent, location-anchored AR quest left by an agent. To
* complete it, a person must physically travel to the spot, prove co-location, and
* finish the agent-driven interaction in AR. On success the agent's OWN wallet
* cryptographically signs a proof-of-presence — independently verifiable, ownable as
* a collectible — without any precise coordinate ever entering the proof, a log, or
* an alert.
*
* POST /api/irl/world-lines create a World Line (auth + owned agent + owned pin)
* GET /api/irl/world-lines/nearby fix-gated, co-located discovery (lat/lng + x-irl-fix)
* GET /api/irl/world-lines/browse public region listing (coarse, no coordinates)
* GET /api/irl/world-lines/mine creator dashboard (completions + coarse heatmap)
* GET /api/irl/world-lines/collectibles the caller's earned proofs (profile/wallet)
* GET /api/irl/world-lines/:id single World Line (fix-gated for the AR detail)
* POST /api/irl/world-lines/challenge issue a single-use completion nonce (co-located)
* POST /api/irl/world-lines/complete the proof ceremony → agent-signed collectible
* GET /api/irl/world-lines/verify/:proofId re-check the agent signature (public)
*
* PRIVACY CONTRACT (mirrors api/irl/pins.js): the only surface that ever reveals a
* precise spot is the existing fix-gated pin proximity read. A World Line stores only
* its anchor pin_id + a coarse (~1.1 km, precision-6) cell. Co-location is ALWAYS
* server-derived — the caller's claimed point is anti-spoofed by the fix token and
* checked against the pin's server-side coordinates; the body is never trusted. No
* proof, nonce, notification, or log line carries a coordinate or a raw device token.
*/
import { cors, json, wrap, rateLimited, readJson } from '../_lib/http.js';
import { sql } from '../_lib/db.js';
import { getSessionUser } from '../_lib/auth.js';
import { requireCsrf } from '../_lib/csrf.js';
import { limits, clientIp, limitFailClosedRead } from '../_lib/rate-limit.js';
import { readDeviceToken } from '../_lib/irl-auth.js';
import { verifyFixToken, fixEnforced } from '../_lib/irl-presence.js';
import { insertNotification } from '../_lib/notify.js';
import { isUuid } from '../_lib/validate.js';
import { encodeGeohash } from '../_lib/geohash.js';
// The content floor and the pin-id shape are the pin feed's, not a second copy of
// it: a quest's public title/prompt has to clear exactly the gate a pin caption
// clears, and its anchor id has to satisfy the same UUID column. See the note above
// ensureTables() for why the pins module is a dependency here either way.
import { hardBlocked, namesOffBrandCoin, isValidPinId, ensurePinsSchema } from './pins.js';
import {
coarseCell, isCoarseCell, normalizeChallengeSpec, normalizeRewardKind, normalizeDifficulty,
canonicalProofMessage, completerHash, signPresenceProof, verifyPresenceProof,
mintPresenceNonce, verifyPresenceNonce, TITLE_MAX, PROMPT_MAX,
} from '../_lib/world-lines.js';
// Region cell (~5 km, precision-5) — the public-browse aggregation unit, deliberately
// coarser than the proof's ~1.1 km cell so the discovery map only ever says "N quests
// around this area," never anything that could localise one quest precisely.
const REGION_CELL_PRECISION = 5;
// Co-location radius: a completion's claimed point (anti-spoofed by the fix token)
// must be within this of the anchor pin's server-side coordinates. A touch wider than
// the 60 m pin proximity read to tolerate the GPS jitter at the exact moment someone
// taps "complete," far too tight to satisfy from across town.
const COLOCATION_RADIUS_M = 80;
// Discovery radius: how far away a walking explorer can SEE a quest to head toward it.
// Wider than the 60 m pin proximity (which alone resolves the precise AR anchor), so
// the game says "a quest is ~200 m north" while the exact spot still only materialises
// once you're on top of it via the pin feed. Coarse distance only.
const NEARBY_DEFAULT_RADIUS_M = 250;
const NEARBY_MAX_RADIUS_M = 600;
const MAX_WORLD_LINES_PER_OWNER = 30; // active quests one creator can run at once
const MAX_PER_REGION = 200; // safety ceiling per ~5 km region
const DEFAULT_LIFETIME_DAYS = 30;
const MAX_LIFETIME_DAYS = 90;
const MAX_COMPLETIONS_CAP = 100_000; // an explicit sane bound on the cap field
function haversineM(lat1, lng1, lat2, lng2) {
const R = 6371000;
const toRad = (d) => (d * Math.PI) / 180;
const dLat = toRad(lat2 - lat1);
const dLng = toRad(lng2 - lng1);
const a = Math.sin(dLat / 2) ** 2
+ Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) ** 2;
return 2 * R * Math.asin(Math.min(1, Math.sqrt(a)));
}
let _tableReady = false;
async function ensureTables() {
if (_tableReady) return;
// Every coordinate feed here JOINs irl_pins for the anchor's precise position, so
// this table is a hard dependency, not an optional one. Provision it through the
// definition that owns it (api/irl/pins.js) rather than a second copy of the DDL:
// on a database where no pin has ever been placed, `nearby` and the single-quest
// read otherwise 500 with a raw `relation "irl_pins" does not exist`.
await ensurePinsSchema();
await sql`
CREATE TABLE IF NOT EXISTS irl_world_lines (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
creator_user_id UUID,
creator_device TEXT,
agent_id UUID NOT NULL,
signer_pubkey TEXT NOT NULL,
pin_id UUID NOT NULL,
coarse_cell TEXT NOT NULL,
region_cell TEXT NOT NULL,
title TEXT NOT NULL,
prompt TEXT,
challenge_spec JSONB NOT NULL,
reward_kind TEXT NOT NULL DEFAULT 'collectible',
reward_ref TEXT,
reward_meta JSONB,
difficulty TEXT NOT NULL DEFAULT 'easy',
max_completions INTEGER,
completion_count INTEGER NOT NULL DEFAULT 0,
hidden_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT NOW(),
expires_at TIMESTAMPTZ
)
`;
await sql`CREATE INDEX IF NOT EXISTS irl_world_lines_cell ON irl_world_lines (coarse_cell) WHERE hidden_at IS NULL`;
await sql`CREATE INDEX IF NOT EXISTS irl_world_lines_region ON irl_world_lines (region_cell) WHERE hidden_at IS NULL`;
await sql`CREATE INDEX IF NOT EXISTS irl_world_lines_pin ON irl_world_lines (pin_id)`;
await sql`CREATE INDEX IF NOT EXISTS irl_world_lines_expires ON irl_world_lines (expires_at)`;
await sql`CREATE INDEX IF NOT EXISTS irl_world_lines_creator ON irl_world_lines (creator_user_id)`;
await sql`
CREATE TABLE IF NOT EXISTS irl_presence_proofs (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
world_line_id UUID NOT NULL,
agent_id UUID,
signer_pubkey TEXT NOT NULL,
coarse_cell TEXT NOT NULL,
nonce_id TEXT NOT NULL,
completer_hash TEXT NOT NULL,
completer_user_id UUID,
completer_device TEXT,
signature TEXT NOT NULL,
signed_message TEXT NOT NULL,
challenge_kind TEXT,
collectible_mint TEXT,
collectible_name TEXT,
reward_kind TEXT,
created_at TIMESTAMPTZ DEFAULT NOW()
)
`;
// nonce_id UNIQUE → one settled proof per server-issued nonce (idempotency + replay
// guard). (world_line_id, completer_hash) UNIQUE → one proof per visitor per quest.
await sql`CREATE UNIQUE INDEX IF NOT EXISTS irl_presence_proofs_nonce ON irl_presence_proofs (nonce_id)`;
await sql`CREATE UNIQUE INDEX IF NOT EXISTS irl_presence_proofs_once ON irl_presence_proofs (world_line_id, completer_hash)`;
await sql`CREATE INDEX IF NOT EXISTS irl_presence_proofs_wl ON irl_presence_proofs (world_line_id, created_at DESC)`;
await sql`CREATE INDEX IF NOT EXISTS irl_presence_proofs_user ON irl_presence_proofs (completer_user_id, created_at DESC)`;
await sql`CREATE INDEX IF NOT EXISTS irl_presence_proofs_device ON irl_presence_proofs (completer_device, created_at DESC)`;
_tableReady = true;
}
// ── Routing ──────────────────────────────────────────────────────────────────
// Parse the action segment after /api/irl/world-lines. vercel.json rewrites the
// sub-paths to this one function (mirrors how /api/irl/pins/mine routes to pins.js).
function routeOf(req) {
const path = String(req.url || '').split('?')[0].replace(/\/+$/, '');
const m = path.match(/\/api\/irl\/world-lines\/?(.*)$/);
const rest = m ? m[1] : '';
if (!rest) return { action: 'root' };
const [first, second] = rest.split('/');
if (first === 'verify') return { action: 'verify', id: second || null };
const KNOWN = new Set(['nearby', 'browse', 'mine', 'collectibles', 'challenge', 'complete']);
if (KNOWN.has(first)) return { action: first };
return { action: 'detail', id: first };
}
const isLive = `hidden_at IS NULL AND (expires_at IS NULL OR expires_at > NOW())`;
export default wrap(async (req, res) => {
// `methods` is written straight into the header, so an ARRAY emits three
// separate access-control-allow-methods lines instead of one list. Pass the
// comma string every neighbouring handler passes, and let cors() answer the
// preflight itself rather than calling res.end() a second time behind it.
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
await ensureTables();
const { action, id } = routeOf(req);
if (req.method === 'GET') {
// Public reads share the generic per-IP read ceiling; the fix-gated reads add
// the proof-of-presence binding on top so a quest's spot can't be browsed remotely.
// Fail-closed: `nearby` and `detail` hand back quest coordinates, so a limiter
// that cannot decide must deny with a retryable 429 rather than 500 the read
// (or, worse, wave it through unmetered).
const rl = await limitFailClosedRead('publicIp', limits.publicIp, clientIp(req));
if (!rl.success) return rateLimited(res, rl);
if (action === 'nearby') return handleNearby(req, res);
if (action === 'browse') return handleBrowse(req, res);
if (action === 'mine') return handleMine(req, res);
if (action === 'collectibles') return handleCollectibles(req, res);
if (action === 'verify') return handleVerify(req, res, id);
if (action === 'detail') return handleDetail(req, res, id);
return json(res, 404, { error: 'unknown world-lines route' });
}
if (req.method === 'POST') {
if (action === 'challenge') return handleChallenge(req, res);
if (action === 'complete') return handleComplete(req, res);
if (action === 'root') return handleCreate(req, res);
return json(res, 404, { error: 'unknown world-lines route' });
}
return json(res, 405, { error: 'method not allowed' });
});
// ── Co-location ──────────────────────────────────────────────────────────────
// Resolve, server-side, whether the caller is genuinely at a World Line's anchor.
// Returns { ok:true, cell } or { ok:false, status, body }. The claimed lat/lng is
// validated by the fix token (proves a real recent GPS fix near the claim) AND then
// checked against the anchor pin's server-side coordinates — the body is never
// trusted for the distance check. The coarse cell returned is derived from the pin,
// not the caller, so it matches the World Line exactly.
async function resolveColocation(req, body, wl) {
const lat = parseFloat(body.lat);
const lng = parseFloat(body.lng);
if (!Number.isFinite(lat) || !Number.isFinite(lng)) {
return { ok: false, status: 400, body: { error: 'lat and lng are required' } };
}
// Proof-of-presence: bind to a genuine fix when enforced (prod). Dev/preview without
// IRL_FIX_SECRET skips the token (same posture as the pins read) but STILL runs the
// server-side distance check below, so co-location is never simply trusted.
if (fixEnforced()) {
const fixHeader = req.headers['x-irl-fix'];
const fixToken = Array.isArray(fixHeader) ? fixHeader[0] : fixHeader;
const v = await verifyFixToken(fixToken, lat, lng);
if (!v.ok) {
return {
ok: false, status: 401,
body: { error: 'fix_required', reason: v.reason, error_description: 'a fresh location fix is required' },
};
}
}
// The anchor pin holds the precise coordinate (gated, never returned here). Read it
// server-side only to compute the co-location boolean.
const [pin] = await sql`
SELECT lat, lng FROM irl_pins
WHERE id = ${wl.pin_id} AND hidden_at IS NULL
AND (expires_at IS NULL OR expires_at > NOW())
LIMIT 1
`;
if (!pin) {
return { ok: false, status: 410, body: { error: 'anchor_gone', error_description: 'this quest’s anchor is no longer placed' } };
}
const dist = haversineM(lat, lng, pin.lat, pin.lng);
if (dist > COLOCATION_RADIUS_M) {
return {
ok: false, status: 403,
body: { error: 'not_colocated', error_description: 'travel to the quest to complete it', within_m: COLOCATION_RADIUS_M },
};
}
return { ok: true, cell: wl.coarse_cell };
}
// ── Create ───────────────────────────────────────────────────────────────────
async function handleCreate(req, res) {
const rl = await limits.worldLineCreateIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const session = await getSessionUser(req).catch(() => null);
// Creation is accountable: the agent's custodial wallet signs every proof this quest
// mints, so the creator must be a signed-in owner of that agent. Anonymous device
// placements (which have no agent wallet) can't author a signing quest.
if (!session) return json(res, 401, { error: 'sign in to place a World Line' });
if (!(await requireCsrf(req, res, session.id))) return; // CSRF on the authed write
let body;
try {
body = await readJson(req);
} catch (err) {
return json(res, err.status || 400, { error: err.message || 'invalid body' });
}
const pinId = body.pinId;
if (!isValidPinId(pinId)) return json(res, 400, { error: 'a valid pinId is required' });
// The caller must own the anchor pin (it carries the precise spot). Read its coords
// server-side to derive the coarse + region cells — never trusted from the body.
const [pin] = await sql`
SELECT id, user_id, agent_id, lat, lng, published FROM irl_pins
WHERE id = ${pinId} AND hidden_at IS NULL
AND (expires_at IS NULL OR expires_at > NOW())
LIMIT 1
`;
if (!pin) return json(res, 404, { error: 'pin not found' });
if (!pin.user_id || pin.user_id !== session.id) {
return json(res, 403, { error: 'you can only anchor a World Line to your own pin' });
}
// A World Line is a public invitation to walk to a spot. Anchoring one to a
// PRIVATE pin would publish the very coordinate the owner marked private, so
// refuse at creation rather than silently filtering it out of discovery later.
// The owner makes the pin public first — an explicit, deliberate act.
if (pin.published === false) {
return json(res, 409, {
error: 'this pin is private',
error_description: 'A World Line invites strangers to its location. Make the pin public before anchoring a quest to it.',
});
}
// The signing agent: the pin's agent, or a caller-supplied agent they own.
const agentId = isUuid(body.agentId) ? body.agentId : (pin.agent_id || null);
if (!agentId) return json(res, 400, { error: 'this pin has no agent; pass an agentId you own' });
const [agent] = await sql`
SELECT id, user_id FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL LIMIT 1
`;
if (!agent) return json(res, 404, { error: 'agent not found' });
if (agent.user_id !== session.id) {
return json(res, 403, { error: 'you can only sign quests with an agent you own' });
}
// Title + prompt: the public, agent-spoken content. Same content floor as a pin
// caption — slur gate + $THREE-only coin guard — so a quest can't shill or abuse.
const title = String(body.title ?? '').replace(/\s+/g, ' ').trim().slice(0, TITLE_MAX);
if (!title) return json(res, 400, { error: 'a title is required' });
if (hardBlocked(title) || namesOffBrandCoin(title)) {
return json(res, 422, { error: 'content', field: 'title', message: 'That title isn’t allowed. A quest can only reference $THREE.' });
}
const prompt = body.prompt != null ? String(body.prompt).replace(/\s+/g, ' ').trim().slice(0, PROMPT_MAX) : '';
if (prompt && (hardBlocked(prompt) || namesOffBrandCoin(prompt))) {
return json(res, 422, { error: 'content', field: 'prompt', message: 'That prompt isn’t allowed. A quest can only reference $THREE.' });
}
const challenge = normalizeChallengeSpec(body.challenge ?? body.challenge_spec);
if (!challenge.ok) return json(res, 400, { error: 'challenge', message: challenge.error });
// Quest prompt/phrase/question text gets the same content gate.
for (const field of ['prompt', 'question']) {
const v = challenge.spec[field];
if (v && (hardBlocked(v) || namesOffBrandCoin(v))) {
return json(res, 422, { error: 'content', field, message: 'That text isn’t allowed. A quest can only reference $THREE.' });
}
}
const rewardKind = normalizeRewardKind(body.reward_kind ?? body.rewardKind);
const rewardRef = body.reward_ref != null ? String(body.reward_ref).slice(0, 80) : null;
const difficulty = normalizeDifficulty(body.difficulty);
let maxCompletions = null;
const rawMax = Number(body.max_completions ?? body.maxCompletions);
if (Number.isInteger(rawMax) && rawMax > 0) maxCompletions = Math.min(MAX_COMPLETIONS_CAP, rawMax);
const lifetimeDays = Math.min(MAX_LIFETIME_DAYS, Math.max(1,
Number.isFinite(Number(body.lifetime_days)) ? Number(body.lifetime_days) : DEFAULT_LIFETIME_DAYS));
const expiresAt = new Date(Date.now() + lifetimeDays * 86400_000).toISOString();
const cell = coarseCell(pin.lat, pin.lng);
const region = encodeGeohash(pin.lat, pin.lng, REGION_CELL_PRECISION);
if (!isCoarseCell(cell)) return json(res, 400, { error: 'pin location is not placeable' });
// Per-owner active-quest cap + a per-region safety ceiling.
const [{ owned }] = await sql`
SELECT count(*)::int AS owned FROM irl_world_lines
WHERE creator_user_id = ${session.id} AND hidden_at IS NULL
AND (expires_at IS NULL OR expires_at > NOW())
`;
if (owned >= MAX_WORLD_LINES_PER_OWNER) {
return json(res, 429, { error: 'quest_limit', limit: MAX_WORLD_LINES_PER_OWNER, message: 'You’ve reached your active World Line limit. Retire one to place another.' });
}
const [{ inRegion }] = await sql`
SELECT count(*)::int AS "inRegion" FROM irl_world_lines
WHERE region_cell = ${region} AND hidden_at IS NULL
AND (expires_at IS NULL OR expires_at > NOW())
`;
if (inRegion >= MAX_PER_REGION) {
return json(res, 429, { error: 'region_full', message: 'This region already has the maximum number of quests.' });
}
// Capture the agent's signing public key now, so verification is anchored to the key
// in force at creation. ensureAgentWallet is idempotent (provisions on first need).
let signerPubkey;
try {
const { ensureAgentWallet } = await import('../_lib/agent-wallet.js');
const w = await ensureAgentWallet(agentId, session.id, { reason: 'world-line:create' });
signerPubkey = w.address;
} catch (err) {
console.error('[irl/world-lines] could not provision agent signer', { agentId, message: err?.message });
return json(res, 502, { error: 'could not provision the agent’s signing wallet' });
}
const [row] = await sql`
INSERT INTO irl_world_lines
(creator_user_id, agent_id, signer_pubkey, pin_id, coarse_cell, region_cell,
title, prompt, challenge_spec, reward_kind, reward_ref, difficulty,
max_completions, expires_at)
VALUES (
${session.id}, ${agentId}, ${signerPubkey}, ${pinId}, ${cell}, ${region},
${title}, ${prompt || null}, ${JSON.stringify(challenge.spec)}::jsonb,
${rewardKind}, ${rewardRef}, ${difficulty}, ${maxCompletions}, ${expiresAt}
)
RETURNING id, agent_id, signer_pubkey, pin_id, coarse_cell, region_cell, title,
prompt, challenge_spec, reward_kind, reward_ref, difficulty,
max_completions, completion_count, created_at, expires_at
`;
return json(res, 201, { world_line: publicWorldLine(row, { owner: true }) });
}
// ── Nearby (fix-gated, co-located discovery) ─────────────────────────────────
async function handleNearby(req, res) {
const lat = parseFloat(req.query.lat);
const lng = parseFloat(req.query.lng);
if (!Number.isFinite(lat) || !Number.isFinite(lng)) {
return json(res, 400, { error: 'lat and lng are required' });
}
const rawRadius = req.query.radius;
const parsed = rawRadius == null || rawRadius === '' ? NEARBY_DEFAULT_RADIUS_M : parseFloat(rawRadius);
if (!Number.isFinite(parsed)) return json(res, 400, { error: 'invalid radius' });
const radius = Math.min(NEARBY_MAX_RADIUS_M, Math.max(30, parsed));
// Dedicated coordinate-read budget (H7), fail-closed. This is by far the widest
// location read on the platform (600 m vs 60 m for pins), so one call covers
// ~100x the area of a pin read and it is the cheapest surface to sweep. It draws
// on the same 60/min/IP /irl location bucket as the tighter reads rather than
// the generic public ceiling. See docs/irl/THREAT-MODEL.md.
const nearbyRl = await limitFailClosedRead('irlNearbyIp', limits.irlNearbyIp, clientIp(req));
if (!nearbyRl.success) return rateLimited(res, nearbyRl);
// Same fix-gate as the pin proximity read: a quest's location is only revealed to a
// caller proven to be standing near it.
if (fixEnforced()) {
const fixHeader = req.headers['x-irl-fix'];
const fixToken = Array.isArray(fixHeader) ? fixHeader[0] : fixHeader;
const v = await verifyFixToken(fixToken, lat, lng);
if (!v.ok) return json(res, 401, { error: 'fix_required', reason: v.reason });
}
const latDelta = radius / 110540;
const lngDelta = radius / (111320 * Math.cos(lat * Math.PI / 180) || 1);
const session = await getSessionUser(req).catch(() => null);
const myId = session?.id ?? null;
const myDev = readDeviceToken(req);
// Join to the anchor pin for the proximity filter (precise coords used only to
// compute a coarse distance, never returned). The completer's own completion state
// is surfaced so the client can render "already done" without leaking who else did.
const myHash = await completerHash(myId ?? myDev ?? '');
const rows = await sql`
SELECT w.id, w.agent_id, w.signer_pubkey, w.pin_id, w.coarse_cell, w.title, w.prompt,
w.challenge_spec, w.reward_kind, w.reward_ref, w.difficulty,
w.max_completions, w.completion_count, w.created_at, w.expires_at,
p.lat AS pin_lat, p.lng AS pin_lng,
EXISTS (SELECT 1 FROM irl_presence_proofs pr
WHERE pr.world_line_id = w.id AND pr.completer_hash = ${myHash}) AS mine_done
FROM irl_world_lines w
JOIN irl_pins p ON p.id = w.pin_id
WHERE w.hidden_at IS NULL
AND (w.expires_at IS NULL OR w.expires_at > NOW())
AND p.hidden_at IS NULL AND (p.expires_at IS NULL OR p.expires_at > NOW())
-- A quest anchored to a PRIVATE pin never reaches a stranger. This feed has
-- the widest coordinate radius on the platform (600 m vs 60 m for pins), so
-- it must honour the anchor pin's visibility or it silently becomes the
-- cheapest private-pin bypass we ship.
AND p.published IS NOT FALSE
AND p.lat BETWEEN ${lat - latDelta} AND ${lat + latDelta}
AND p.lng BETWEEN ${lng - lngDelta} AND ${lng + lngDelta}
ORDER BY w.created_at DESC
LIMIT 50
`;
const quests = rows
.map((r) => {
const distance = Math.round(haversineM(lat, lng, r.pin_lat, r.pin_lng));
return { r, distance };
})
.filter(({ distance }) => distance <= radius)
.sort((a, b) => a.distance - b.distance)
.map(({ r, distance }) => ({
...publicWorldLine(r, { owner: false }),
// Distance coarsened to 10 m — enough to render an arrow + "≈200 m" without
// triangulating the exact spot from successive reads.
distance_m: Math.max(0, Math.round(distance / 10) * 10),
completed_by_me: r.mine_done === true,
capacity_reached: r.max_completions != null && r.completion_count >= r.max_completions,
}));
return json(res, 200, { world_lines: quests });
}
// ── Browse (public, coarse region listing — no coordinates) ──────────────────
async function handleBrowse(req, res) {
const difficulty = req.query.difficulty;
const diffFilter = difficulty && ['easy', 'medium', 'hard'].includes(String(difficulty)) ? String(difficulty) : null;
const region = typeof req.query.region === 'string' && /^[0-9bcdefghjkmnpqrstuvwxyz]{5}$/.test(req.query.region)
? req.query.region : null;
if (region) {
// One region's active quests — title/reward/difficulty + live completion stats.
// Still NO coordinate: the AR spot only ever resolves through the fix-gated feeds.
const rows = diffFilter
? await sql`
SELECT id, title, reward_kind, difficulty, completion_count, max_completions, created_at
FROM irl_world_lines
WHERE region_cell = ${region} AND difficulty = ${diffFilter} AND hidden_at IS NULL
AND (expires_at IS NULL OR expires_at > NOW())
ORDER BY created_at DESC LIMIT 60`
: await sql`
SELECT id, title, reward_kind, difficulty, completion_count, max_completions, created_at
FROM irl_world_lines
WHERE region_cell = ${region} AND hidden_at IS NULL
AND (expires_at IS NULL OR expires_at > NOW())
ORDER BY created_at DESC LIMIT 60`;
return json(res, 200, {
region,
quests: rows.map((r) => ({
id: r.id, title: r.title, reward_kind: r.reward_kind, difficulty: r.difficulty,
completion_count: r.completion_count,
capacity_reached: r.max_completions != null && r.completion_count >= r.max_completions,
})),
});
}
// Region roll-up: how many active quests per ~5 km region. Pure aggregate, the
// privacy-safe "where in the world are quests" map.
const rows = await sql`
SELECT region_cell, count(*)::int AS quests,
count(*) FILTER (WHERE difficulty = 'hard')::int AS hard,
sum(completion_count)::int AS completions
FROM irl_world_lines
WHERE hidden_at IS NULL AND (expires_at IS NULL OR expires_at > NOW())
GROUP BY region_cell
ORDER BY quests DESC
LIMIT 200
`;
res.setHeader('cache-control', 'public, s-maxage=60, stale-while-revalidate=300');
return json(res, 200, { regions: rows });
}
// ── Single World Line (fix-gated, for the AR detail view) ────────────────────
async function handleDetail(req, res, id) {
if (!isUuid(id)) return json(res, 400, { error: 'invalid world line id' });
const [w] = await sql`
SELECT w.id, w.agent_id, w.signer_pubkey, w.pin_id, w.coarse_cell, w.title, w.prompt,
w.challenge_spec, w.reward_kind, w.reward_ref, w.difficulty,
w.max_completions, w.completion_count, w.created_at, w.expires_at,
p.lat AS pin_lat, p.lng AS pin_lng, p.hidden_at AS pin_hidden, p.expires_at AS pin_expires
FROM irl_world_lines w
JOIN irl_pins p ON p.id = w.pin_id
WHERE w.id = ${id} AND w.hidden_at IS NULL AND (w.expires_at IS NULL OR w.expires_at > NOW())
LIMIT 1
`;
if (!w) return json(res, 404, { error: 'world line not found' });
// The challenge_spec includes the quiz/phrase ANSWER, which must not be handed to a
// caller who hasn't proven they're at the spot (it would let them pre-solve remotely).
// Resolve co-location; on success return the full spec, otherwise a redacted spec +
// the coarse cell so the "travel here" state can still render.
const lat = parseFloat(req.query.lat);
const lng = parseFloat(req.query.lng);
let colocated = false;
if (Number.isFinite(lat) && Number.isFinite(lng)) {
const co = await resolveColocation(req, { lat, lng }, w);
colocated = co.ok;
}
return json(res, 200, { world_line: publicWorldLine(w, { revealAnswer: colocated }), colocated });
}
// ── Challenge (issue a single-use completion nonce) ──────────────────────────
async function handleChallenge(req, res) {
const rl = await limits.worldLineChallengeIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
let body;
try {
body = await readJson(req);
} catch (err) {
return json(res, err.status || 400, { error: err.message || 'invalid body' });
}
const wlId = body.world_line_id ?? body.worldLineId ?? body.id;
if (!isUuid(wlId)) return json(res, 400, { error: 'a valid world_line_id is required' });
const wl = await loadWorldLine(wlId);
if (!wl) return json(res, 404, { error: 'world line not found' });
if (wl.max_completions != null && wl.completion_count >= wl.max_completions) {
return json(res, 409, { error: 'capacity_reached', message: 'This quest has reached its completion limit.' });
}
const co = await resolveColocation(req, body, wl);
if (!co.ok) return json(res, co.status, co.body);
// Already completed by this visitor? Surface the existing proof so the client renders
// the "already done" state instead of a fresh nonce.
const session = await getSessionUser(req).catch(() => null);
const who = await completerHash(session?.id ?? readDeviceToken(req) ?? '');
const [existing] = await sql`
SELECT id, collectible_mint FROM irl_presence_proofs
WHERE world_line_id = ${wlId} AND completer_hash = ${who} LIMIT 1
`;
if (existing) {
return json(res, 200, { already_completed: true, proof_id: existing.id, collectible_mint: existing.collectible_mint });
}
const minted = await mintPresenceNonce(wlId, wl.coarse_cell);
if (!minted) return json(res, 500, { error: 'could not issue a challenge' });
return json(res, 200, {
nonce: minted.nonce,
expires_in: minted.expires_in,
challenge: revealedSpec(wl.challenge_spec, true),
agent_id: wl.agent_id,
world_line: { id: wl.id, title: wl.title, prompt: wl.prompt, reward_kind: wl.reward_kind, reward_ref: wl.reward_ref },
});
}
// ── Complete (the proof ceremony) ────────────────────────────────────────────
async function handleComplete(req, res) {
const rl = await limits.worldLineCompleteIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
let body;
try {
body = await readJson(req);
} catch (err) {
return json(res, err.status || 400, { error: err.message || 'invalid body' });
}
const wlId = body.world_line_id ?? body.worldLineId ?? body.id;
if (!isUuid(wlId)) return json(res, 400, { error: 'a valid world_line_id is required' });
const nonce = body.nonce;
if (typeof nonce !== 'string' || !nonce) return json(res, 400, { error: 'a completion nonce is required' });
const wl = await loadWorldLine(wlId);
if (!wl) return json(res, 404, { error: 'world line not found' });
// 1) Server-derived co-location (re-checked at completion, never trusted from body).
const co = await resolveColocation(req, body, wl);
if (!co.ok) return json(res, co.status, co.body);
// 2) The nonce must be unforged, unexpired, and bound to THIS quest + coarse cell.
const nv = await verifyPresenceNonce(nonce, wlId, wl.coarse_cell);
if (!nv.ok) {
const status = nv.reason === 'expired' ? 410 : 403;
return json(res, status, { error: 'invalid_nonce', reason: nv.reason, message: 'Your challenge expired or was invalid — tap to try again.' });
}
// 3) The interaction itself, where the server CAN check it (quiz/phrase). For 'tap'
// the challenge is presence, already proven above.
const spec = wl.challenge_spec || {};
const interactionError = checkInteraction(spec, body);
if (interactionError) return json(res, 422, { error: 'challenge_failed', message: interactionError });
const session = await getSessionUser(req).catch(() => null);
const completerUserId = session?.id ?? null;
const completerDevice = readDeviceToken(req);
const who = await completerHash(completerUserId ?? completerDevice ?? '');
// 4) Idempotency / one-per-visitor: if this visitor already has a proof for this
// quest, return it unchanged rather than minting a second collectible.
const [already] = await sql`
SELECT * FROM irl_presence_proofs WHERE world_line_id = ${wlId} AND completer_hash = ${who} LIMIT 1
`;
if (already) return json(res, 200, { already_completed: true, proof: publicProof(already), collectible: collectibleOf(already) });
// 5) Capacity (re-checked just before the signing mint).
if (wl.max_completions != null && wl.completion_count >= wl.max_completions) {
return json(res, 409, { error: 'capacity_reached', message: 'This quest has reached its completion limit.' });
}
// 6) The agent wallet signs the canonical proof-of-presence message.
const message = canonicalProofMessage({
worldLineId: wlId, coarseCell: wl.coarse_cell, nonceId: nv.nonceId, completerHash: who,
});
let signed;
try {
signed = await signWithAgent(wl.agent_id, completerUserId, message);
} catch (err) {
console.error('[irl/world-lines] agent signing failed', { agentId: wl.agent_id, message: err?.message });
return json(res, 502, { error: 'the agent could not sign your proof — try again' });
}
// The signing key must match the key captured at creation, and the signature must
// verify against it — we verify server-side BEFORE persisting, so a stored proof is
// always genuine. (This is exactly what GET /verify re-runs for anyone.)
if (signed.signerPubkey !== wl.signer_pubkey ||
!verifyPresenceProof({ signerPubkey: signed.signerPubkey, message, signature: signed.signature })) {
console.error('[irl/world-lines] self-verify failed', { wlId, agentId: wl.agent_id });
return json(res, 502, { error: 'proof verification failed — try again' });
}
const collectibleName = wl.reward_ref || `${wl.title} — proof of presence`;
// 7) Persist + count, guarded so capacity and one-per-visitor hold under concurrency.
// The unique indexes (nonce_id; world_line_id+completer_hash) make a racing double
// completion a clean conflict rather than a double mint. collectible_mint is the
// deterministic, ownable id of the collectible; the verifiable signature is its body.
let proof;
try {
[proof] = await sql`
INSERT INTO irl_presence_proofs
(world_line_id, agent_id, signer_pubkey, coarse_cell, nonce_id, completer_hash,
completer_user_id, completer_device, signature, signed_message, challenge_kind,
collectible_name, reward_kind)
VALUES (
${wlId}, ${wl.agent_id}, ${signed.signerPubkey}, ${wl.coarse_cell}, ${nv.nonceId}, ${who},
${completerUserId}, ${completerDevice}, ${signed.signature}, ${message}, ${spec.kind || 'tap'},
${collectibleName}, ${wl.reward_kind}
)
ON CONFLICT (nonce_id) DO NOTHING
RETURNING *
`;
} catch (err) {
// A (world_line_id, completer_hash) unique violation = this visitor already
// completed via a different nonce in a race. Return their existing proof.
const [dupe] = await sql`
SELECT * FROM irl_presence_proofs WHERE world_line_id = ${wlId} AND completer_hash = ${who} LIMIT 1
`;
if (dupe) return json(res, 200, { already_completed: true, proof: publicProof(dupe), collectible: collectibleOf(dupe) });
throw err;
}
if (!proof) {
// nonce_id conflict (the same nonce was already spent) — idempotent replay.
const [dupe] = await sql`SELECT * FROM irl_presence_proofs WHERE nonce_id = ${nv.nonceId} LIMIT 1`;
if (dupe) return json(res, 200, { already_completed: true, proof: publicProof(dupe), collectible: collectibleOf(dupe) });
return json(res, 409, { error: 'already_completed', message: 'This challenge was already used.' });
}
// The collectible id is derived from the proof row id (stable, ownable, verifiable).
const collectibleMint = `presence:${proof.id}`;
await sql`UPDATE irl_presence_proofs SET collectible_mint = ${collectibleMint} WHERE id = ${proof.id}`;
proof.collectible_mint = collectibleMint;
// Bump the completion count under the capacity guard (no over-fill past max).
await sql`
UPDATE irl_world_lines SET completion_count = completion_count + 1
WHERE id = ${wlId} AND (max_completions IS NULL OR completion_count < max_completions)
`;
// 8) Tell the creator someone completed their World Line — coarse cell + count only,
// never a coordinate or the completer's identity.
if (wl.creator_user_id) {
insertNotification(wl.creator_user_id, 'world_line_completed', {
world_line_id: wlId,
title: wl.title,
coarse_cell: wl.coarse_cell,
completion_count: (wl.completion_count || 0) + 1,
link: '/world-lines/mine',
});
}
return json(res, 201, { ok: true, proof: publicProof(proof), collectible: collectibleOf(proof) });
}
// Server-checkable part of a challenge. Presence ('tap') is already proven; quiz +
// phrase are graded against the stored spec so a completion can't be faked by skipping
// the interaction. Returns an error string or null.
function checkInteraction(spec, body) {
if (!spec || spec.kind === 'tap') return null;
if (spec.kind === 'quiz') {
const ans = Number(body.answer);
if (!Number.isInteger(ans) || ans !== spec.answer) return 'That’s not the right answer — try the quiz again.';
return null;
}
if (spec.kind === 'phrase') {
const said = String(body.phrase ?? body.answer ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
if (!said || said !== spec.phrase) return 'That passphrase didn’t match — ask the agent again.';
return null;
}
return null;
}
// ── Verify (public, independent signature re-check) ──────────────────────────
async function handleVerify(req, res, proofId) {
if (!isUuid(proofId)) return json(res, 400, { error: 'invalid proof id' });
const [p] = await sql`
SELECT pr.*, w.title FROM irl_presence_proofs pr
LEFT JOIN irl_world_lines w ON w.id = pr.world_line_id
WHERE pr.id = ${proofId} LIMIT 1
`;
if (!p) return json(res, 404, { error: 'proof not found' });
// Re-run the exact check anyone could: does the agent signature validate over the
// stored canonical message? Self-contained — needs only fields on the proof row.
const verified = verifyPresenceProof({
signerPubkey: p.signer_pubkey, message: p.signed_message, signature: p.signature,
});
return json(res, 200, {
verified,
proof: {
id: p.id,
world_line_id: p.world_line_id,
world_line_title: p.title ?? null,
agent_id: p.agent_id,
signer_pubkey: p.signer_pubkey,
coarse_cell: p.coarse_cell, // ~1.1 km — the only location the proof carries
signed_message: p.signed_message,
signature: p.signature,
signature_scheme: 'ed25519',
collectible_mint: p.collectible_mint,
collectible_name: p.collectible_name,
completed_at: p.created_at,
},
});
}
// ── Creator dashboard ────────────────────────────────────────────────────────
async function handleMine(req, res) {
const session = await getSessionUser(req).catch(() => null);
if (!session) return json(res, 401, { error: 'sign in to view your World Lines' });
const rows = await sql`
SELECT id, agent_id, signer_pubkey, pin_id, coarse_cell, region_cell, title, prompt,
challenge_spec, reward_kind, reward_ref, difficulty, max_completions,
completion_count, created_at, expires_at, hidden_at
FROM irl_world_lines
WHERE creator_user_id = ${session.id}
ORDER BY created_at DESC LIMIT 100
`;
// Coarse heatmap: completions grouped by the proof's coarse cell — counts only, never
// a precise point. (A quest has one anchor cell, so this is "completions per quest's
// cell," the privacy-safe shape the dashboard renders.)
const ids = rows.map((r) => r.id);
let heat = [];
if (ids.length) {
heat = await sql`
SELECT world_line_id, coarse_cell, count(*)::int AS completions
FROM irl_presence_proofs
WHERE world_line_id = ANY(${ids}::uuid[])
GROUP BY world_line_id, coarse_cell
`;
}
return json(res, 200, {
world_lines: rows.map((r) => ({
...publicWorldLine(r, { owner: true }),
expired: r.expires_at != null && new Date(r.expires_at).getTime() <= Date.now(),
hidden: r.hidden_at != null,
})),
heatmap: heat,
});
}
// ── Collectibles (the caller's earned proofs, for profile/wallet) ────────────
async function handleCollectibles(req, res) {
const session = await getSessionUser(req).catch(() => null);
const myDev = readDeviceToken(req);
const myId = session?.id ?? null;
if (!myId && !myDev) return json(res, 400, { error: 'sign in or present a device token' });
// Strictly scoped to the caller's own id or device token — each arm null-guarded so a
// missing identifier can never surface another visitor's collectibles.
const rows = await sql`
SELECT pr.id, pr.world_line_id, pr.agent_id, pr.signer_pubkey, pr.coarse_cell,
pr.signature, pr.signed_message, pr.collectible_mint, pr.collectible_name,
pr.reward_kind, pr.created_at, w.title, w.difficulty
FROM irl_presence_proofs pr
LEFT JOIN irl_world_lines w ON w.id = pr.world_line_id
WHERE ((${myId}::uuid IS NOT NULL AND pr.completer_user_id = ${myId}::uuid)
OR (${myDev}::text IS NOT NULL AND pr.completer_device = ${myDev}))
ORDER BY pr.created_at DESC LIMIT 200
`;
return json(res, 200, {
collectibles: rows.map((r) => ({
...collectibleOf(r),
world_line_id: r.world_line_id,
world_line_title: r.title ?? null,
difficulty: r.difficulty ?? null,
coarse_cell: r.coarse_cell,
earned_at: r.created_at,
verify_url: `/api/irl/world-lines/verify/${r.id}`,
})),
});
}
// ── Shared helpers ───────────────────────────────────────────────────────────
async function loadWorldLine(id) {
const [w] = await sql`
SELECT id, creator_user_id, agent_id, signer_pubkey, pin_id, coarse_cell, title, prompt,
challenge_spec, reward_kind, reward_ref, difficulty, max_completions, completion_count
FROM irl_world_lines
WHERE id = ${id} AND hidden_at IS NULL AND (expires_at IS NULL OR expires_at > NOW())
LIMIT 1
`;
return w || null;
}
// Recover the agent's custodial Solana key and sign the message. Isolated so it's the
// single seam tests mock — the rest of completion is pure DB + crypto already covered.
async function signWithAgent(agentId, userId, message) {
const { ensureAgentWallet, recoverSolanaAgentKeypair } = await import('../_lib/agent-wallet.js');
await ensureAgentWallet(agentId, userId, { reason: 'world-line:sign' });
const [agent] = await sql`SELECT meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL LIMIT 1`;
const encrypted = agent?.meta?.encrypted_solana_secret;
if (!encrypted) throw new Error('agent has no recoverable signing key');
const kp = await recoverSolanaAgentKeypair(encrypted, { agentId, userId, reason: 'world-line:sign' });
return signPresenceProof({ secretKey: kp.secretKey, message });
}
// Strip the secret answer from a challenge spec unless the caller is co-located.
function revealedSpec(spec, reveal) {
if (!spec || typeof spec !== 'object') return { kind: 'tap', prompt: null };
if (reveal) return spec;
const { kind, prompt, question, choices } = spec;
// For a quiz, the question + choices are needed to render; only the answer index is
// hidden. For a phrase, the agent asks for it verbally — never echo the passphrase.
const out = { kind, prompt: prompt ?? null };
if (kind === 'quiz') { out.question = question; out.choices = choices; }
return out;
}
function publicWorldLine(r, { owner = false, revealAnswer = false } = {}) {
return {
id: r.id,
agent_id: r.agent_id,
signer_pubkey: r.signer_pubkey,
pin_id: r.pin_id,
coarse_cell: r.coarse_cell,
region_cell: r.region_cell,
title: r.title,
prompt: r.prompt,
challenge: owner ? r.challenge_spec : revealedSpec(r.challenge_spec, revealAnswer),
reward_kind: r.reward_kind,
reward_ref: r.reward_ref,
difficulty: r.difficulty,
max_completions: r.max_completions,
completion_count: r.completion_count,
created_at: r.created_at,
expires_at: r.expires_at,
};
}
function publicProof(p) {
return {
id: p.id,
world_line_id: p.world_line_id,
agent_id: p.agent_id,
signer_pubkey: p.signer_pubkey,
coarse_cell: p.coarse_cell,
signature: p.signature,
signed_message: p.signed_message,
signature_scheme: 'ed25519',
completed_at: p.created_at,
verify_url: `/api/irl/world-lines/verify/${p.id}`,
};
}
function collectibleOf(p) {
return {
mint: p.collectible_mint || `presence:${p.id}`,
name: p.collectible_name || 'Proof of presence',
kind: 'proof-of-presence',
reward_kind: p.reward_kind || 'collectible',
signer_pubkey: p.signer_pubkey,
signature: p.signature,
proof_id: p.id,
};
}