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
feat(gate): fail the build on any third-party fetch with no deadline
nirholasdc6bf47fc48c
diff --git a/docs/shared-utilities.md b/docs/shared-utilities.mdindex 31ef59208..b353ef94e 100644--- a/docs/shared-utilities.md+++ b/docs/shared-utilities.md@@ -314,6 +314,35 @@ visitor-supplied chat transcripts.## Operations+### `scripts/check-fetch-timeouts.mjs`: no unbounded third-party call++```bash+npm run check:fetch-timeouts # wired into `npm run gate`+node scripts/check-fetch-timeouts.mjs --json+```++Fails the gate on any `fetch()` to a literal external host that carries no+deadline. A fetch with no signal has no deadline at all: undici's defaults run+to minutes, so one upstream that accepts a connection and then stalls holds the+request until the platform kills the invocation, and takes the request budget of+every fallback behind it with it. In production that does not read as "an+upstream was slow", it reads as a dead endpoint, a dead cron, or a page that+spins forever.++A call counts as bounded when it passes a `signal` or goes through a wrapper+that supplies one (`fetchUpstream`, `fetchFirst`, `pumpFetchJson`, ...). Only+the deadline is enforced, deliberately: retries, provider ladders and last-good+tiers are the right thing to add on top, but which one fits is a judgement call+per call site, while a deadline never is. Same-origin and relative calls are out+of scope.++The checker reads each call's real extent by balancing parentheses rather than+scanning a fixed window, because `signal` is conventionally the last key of an+options object and a windowed check reports a bounded call as unbounded exactly+when its options are longest. `tests/check-fetch-timeouts.test.js` covers that+case: a checker that silently stops catching things is worse than no checker,+since the gate keeps passing while the protection erodes.+### `scripts/check-cron-drift.mjs` — cron config vs. realityValidates every cron expression in `vercel.json` withdiff --git a/package.json b/package.jsonindex 696e13b8a..5d640b94b 100644--- a/package.json+++ b/package.json@@ -195,7 +195,7 @@"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs","audit:handlers": "node scripts/audit-empty-handlers.mjs","audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",- "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run audit:docs && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:guards && npm run audit:tour-atlas",+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run audit:docs && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:guards && npm run audit:tour-atlas","test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js","audit:mcp-golden": "node scripts/audit-mcp-golden.mjs","audit:mcp-safety": "node scripts/audit-mcp-safety.mjs",@@ -329,6 +329,7 @@"check:claude": "node scripts/check-claude-md.mjs","verify:erc8004-validation": "node scripts/erc8004/verify-validation-registry.mjs","check:rules": "node scripts/check-rules.mjs",+ "check:fetch-timeouts": "node scripts/check-fetch-timeouts.mjs","check:vendored": "node scripts/check-vendored-workers.mjs","check:secrets": "node scripts/check-secrets.mjs","check:gcloudignore": "node scripts/check-gcloudignore.mjs",diff --git a/public/studio/fees-panel.js b/public/studio/fees-panel.jsindex 508765e74..2575296aa 100644--- a/public/studio/fees-panel.js+++ b/public/studio/fees-panel.js@@ -565,9 +565,11 @@ export function mountFeesPanel(container, opts = {}) {async function importGithubRepo(parsed) {s.githubBusy = true; s.githubError = ''; render();try {+ // The panel shows a spinner while this runs, so an unbounded call leaves+ // it spinning with no error the user can act on.const r = await fetch(`https://api.github.com/repos/${parsed.owner}/${parsed.repo}/contributors?per_page=10`,- { headers: { accept: 'application/vnd.github+json' } });+ { headers: { accept: 'application/vnd.github+json' }, signal: AbortSignal.timeout(12_000) });if (r.status === 404) throw new Error('Repository not found.');if (r.status === 403) throw new Error('GitHub rate limit hit — try again in a minute.');if (!r.ok) throw new Error(`GitHub error ${r.status}`);diff --git a/scripts/check-fetch-timeouts.mjs b/scripts/check-fetch-timeouts.mjsnew file mode 100644index 000000000..a7b064581--- /dev/null+++ b/scripts/check-fetch-timeouts.mjs@@ -0,0 +1,155 @@+#!/usr/bin/env node+/**+ * Guard every outbound call to a third-party host against hanging forever.+ *+ * A `fetch()` with no signal has no deadline. Node's undici defaults run to+ * minutes, so one upstream that accepts a connection and then stalls holds a+ * request open until the platform kills the whole invocation. In production+ * that does not read as "an upstream was slow": it reads as a dead endpoint, a+ * dead cron, or a page that spins forever, and it takes the request budget of+ * every fallback behind it with it. That is the failure this repo has paid for+ * repeatedly, and it is trivially preventable at review time, which is exactly+ * what a mechanical check is for.+ *+ * The rule: any fetch to a literal external URL must be bounded. It counts as+ * bounded when it passes a `signal`, or goes through one of the shared wrappers+ * that supplies one (fetchUpstream, fetchFirst, pumpFetchJson, ...). Retries,+ * provider ladders and last-good tiers are the RIGHT thing to add on top, but+ * they are judgement calls per call site; a deadline is not, so only the+ * deadline is enforced here.+ *+ * Same-origin calls (three.ws, localhost, relative paths) are out of scope: a+ * browser call to our own API is bounded by the page's own lifecycle and by+ * src/api.js, and a server call to itself is a different kind of bug.+ *+ * node scripts/check-fetch-timeouts.mjs # report and exit non-zero on a violation+ * node scripts/check-fetch-timeouts.mjs --json # machine-readable+ */++import { readFileSync } from 'node:fs';+import { execSync } from 'node:child_process';++const ROOTS = ['api', 'src', 'public', 'workers'];++// Wrappers that always supply a deadline of their own.+const BOUNDED_BY = [+ 'fetchUpstream', 'fetchUpstreamJson', 'fetchAnyJson', 'fetchFirst', 'fetchFirstOrNull',+ 'pumpFetchJson', 'fetchPumpBoard', 'fetchPumpTrades', 'fetchPumpCoin', 'fetchTokenMarketData',+ 'fetchTokenPriceUsd', 'solPriceUsd', 'fetchFromGateways', 'fetchSafePublicUrl', 'apiFetch',+ 'importFromCdn', 'loadModule', 'makeRotatingFetch',+];+const BOUNDED_RE = new RegExp(`\\b(${BOUNDED_BY.join('|')})\\s*\\(`);+const SIGNAL_RE = /signal\s*[:,)]|AbortSignal\.timeout|controller\.signal|\.signal\b/;++// Built bundles, vendored third-party code, and minified files are not ours to+// edit; a violation there belongs to whatever produced them.+const SKIP_PATH = /\/vendor\/|node_modules|public\/chat\/assets\/|\.min\.js$|\/dist\//;++const OWN_HOST = /three\.ws|localhost|127\.0\.0\.1/;++function listFiles() {+ const cmd = `grep -rl 'fetch(' ${ROOTS.join(' ')} --include=*.js --include=*.mjs 2>/dev/null || true`;+ return execSync(cmd, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })+ .split('\n')+ .filter(Boolean)+ .filter((f) => !SKIP_PATH.test(f));+}++/** Names of consts in `src` bound to a literal external URL. */+function externalConsts(lines) {+ const names = new Set();+ for (const l of lines) {+ const m = /^\s*(?:export\s+)?const\s+([A-Za-z_0-9]+)\s*=\s*[`'"](https?:\/\/[^`'"]+)/.exec(l);+ if (m && !OWN_HOST.test(m[2])) names.add(m[1]);+ }+ return names;+}++/**+ * The source text of the fetch call starting on line `start`, from `fetch(` to+ * its matching close paren (capped, so an unbalanced file cannot run away).+ * Includes the six lines above it, which is where a wrapper or an+ * already-declared signal usually lives.+ */+function callExtent(lines, start) {+ const from = Math.max(0, start - 6);+ const head = lines.slice(from, start).join('\n');+ const idx = lines[start].indexOf('fetch(');+ let depth = 0;+ let started = false;+ const out = [];+ for (let i = start; i < Math.min(lines.length, start + 60); i++) {+ const line = lines[i];+ out.push(line);+ for (let c = i === start ? idx : 0; c < line.length; c++) {+ const ch = line[c];+ if (ch === '(') { depth++; started = true; } else if (ch === ')') depth--;+ if (started && depth === 0) return `${head}\n${out.join('\n')}`;+ }+ }+ return `${head}\n${out.join('\n')}`;+}++export function scanFile(file, src) {+ const lines = src.split('\n');+ const consts = externalConsts(lines);+ const out = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i];+ if (!/\bfetch\(/.test(line)) continue;+ if (/^\s*(\/\/|\*|\/\*)/.test(line)) continue;+ // Definitions, stubs and re-assignments are not call sites.+ if (/function fetch|globalThis\.fetch\s*=|global\.fetch\s*=|vi\.fn|fetchImpl\b|=\s*fetch\s*[;,)]/.test(line)) continue;++ const call = lines.slice(i, i + 4).join(' ');+ const urlLiteral = call.match(/[`'"]https?:\/\/[^`'"]*/)?.[0] || '';+ const inlineExternal = !!urlLiteral && !OWN_HOST.test(urlLiteral);+ const constExternal = [...consts].some((c) => new RegExp(`\\b${c}\\b`).test(call));+ if (!inlineExternal && !constExternal) continue;++ // Read the ACTUAL extent of the call by balancing parentheses from `fetch(`+ // rather than guessing a window: an options object can run for thirty+ // lines, and `signal` is conventionally its last key, so a fixed window+ // reports a bounded call as unbounded exactly when the options are long.+ const win = callExtent(lines, i);+ if (BOUNDED_RE.test(win) || SIGNAL_RE.test(win)) continue;+ out.push({ file, line: i + 1, code: line.trim().slice(0, 100) });+ }+ return out;+}++function main() {+ const json = process.argv.includes('--json');+ const violations = [];+ for (const file of listFiles()) {+ let src;+ try { src = readFileSync(file, 'utf8'); } catch { continue; }+ violations.push(...scanFile(file, src));+ }++ if (json) {+ console.log(JSON.stringify({ ok: violations.length === 0, violations }, null, 2));+ process.exit(violations.length ? 1 : 0);+ }++ if (!violations.length) {+ console.log('check:fetch-timeouts: every external fetch is bounded by a deadline');+ process.exit(0);+ }++ console.error(`check:fetch-timeouts: ${violations.length} external fetch(es) with no deadline\n`);+ for (const v of violations) {+ console.error(` ${v.file}:${v.line}`);+ console.error(` ${v.code}`);+ }+ console.error(`+Every one of these can hang until the platform kills the request. Fix by either:+ - routing it through a shared wrapper that already bounds it and adds a retry,+ e.g. fetchUpstream / fetchUpstreamJson (api/_lib/upstream-fetch.js) on the+ server, or fetchFirst (src/shared/failover-fetch.js) in the browser; or+ - passing a signal directly: { signal: AbortSignal.timeout(8000) }.+See docs/shared-utilities.md for which wrapper suits which call.`);+ process.exit(1);+}++if (import.meta.url === `file://${process.argv[1]}`) main();diff --git a/src/agent-skills-pumpfun-compose.js b/src/agent-skills-pumpfun-compose.jsindex e3c2f2c71..a6d732445 100644--- a/src/agent-skills-pumpfun-compose.js+++ b/src/agent-skills-pumpfun-compose.js@@ -39,6 +39,7 @@ function cfg(ctx, key) {async function mcp(toolName, args) {const res = await fetch(MCP_ENDPOINT, {method: 'POST',+ signal: AbortSignal.timeout(30_000),headers: { 'Content-Type': 'application/json' },body: JSON.stringify({jsonrpc: '2.0',diff --git a/src/avatar-page.js b/src/avatar-page.jsindex bf0ab0342..43e971ac0 100644--- a/src/avatar-page.js+++ b/src/avatar-page.js@@ -358,8 +358,10 @@ async function fetchRelated() {url.searchParams.set('source', 'avatar');url.searchParams.set('limit', '12');if (avatar.tags?.[0]) url.searchParams.set('q', avatar.tags[0]);- const r = await fetch(url);- if (!r.ok) return [];+ // Related avatars are a side panel: an empty list is a designed state, but a+ // stalled request that never resolves is not, so it is bounded.+ const r = await fetch(url, { signal: AbortSignal.timeout(10_000) }).catch(() => null);+ if (!r?.ok) return [];const j = await r.json();return (j.items || []).filter((it) => it.kind === 'avatar' && it.avatarId !== avatarId).slice(0, 8);}diff --git a/src/erc8004/agent-registry.js b/src/erc8004/agent-registry.jsindex ae16407d0..a98cd5c99 100644--- a/src/erc8004/agent-registry.js+++ b/src/erc8004/agent-registry.js@@ -261,14 +261,24 @@ export async function pinFile(blob, apiToken) {if (apiToken) {const form = new FormData();form.append('file', blob, blob.name || 'upload');- const res = await fetch('https://api.pinata.cloud/pinning/pinFileToIPFS', {- method: 'POST',- headers: { Authorization: `Bearer ${apiToken}` },- body: form,- });- if (!res.ok) throw new Error(`Pinata upload failed (${res.status})`);- const data = await res.json();- return `ipfs://${data.IpfsHash}`;+ // A caller-supplied Pinata token is a preference, not a requirement: this+ // runs mid-registration, so an unbounded upload used to leave the flow+ // hanging with a half-built agent, and a Pinata outage failed it outright+ // even though the platform's own pinning route was right there. Bound it,+ // and fall through to that route rather than losing the registration.+ try {+ const res = await fetch('https://api.pinata.cloud/pinning/pinFileToIPFS', {+ method: 'POST',+ headers: { Authorization: `Bearer ${apiToken}` },+ body: form,+ signal: AbortSignal.timeout(60_000),+ });+ if (!res.ok) throw new Error(`Pinata upload failed (${res.status})`);+ const data = await res.json();+ return `ipfs://${data.IpfsHash}`;+ } catch (err) {+ console.warn('[agent-registry] direct Pinata pin failed, using the platform pinning route:', err?.message || err);+ }}const res = await fetch('/api/erc8004/pin', {diff --git a/src/pinning/pinata.js b/src/pinning/pinata.jsindex d64836707..547e26d84 100644--- a/src/pinning/pinata.js+++ b/src/pinning/pinata.js@@ -117,6 +117,7 @@ export class PinataPinner {fetch(`${BASE}/pinning/unpin/${cid}`, {method: 'DELETE',headers: this._headers(),+ signal: AbortSignal.timeout(15_000),}).then(async (r) => {if (!r.ok) {const body = await r.text().catch(() => '');diff --git a/src/social/x-post-impact.js b/src/social/x-post-impact.jsindex 8a4c306ad..80b2f2b1d 100644--- a/src/social/x-post-impact.js+++ b/src/social/x-post-impact.js@@ -47,6 +47,7 @@ export async function correlateXPost({ postUrl, mint, windowMin = 30 }) {try {const oRes = await fetch(`https://publish.twitter.com/oembed?url=${encodeURIComponent(postUrl)}&omit_script=true`,+ { signal: AbortSignal.timeout(8000) },);if (oRes.ok) {const od = await oRes.json();diff --git a/src/swap-jupiter.js b/src/swap-jupiter.jsindex a188b48a5..17e6ea128 100644--- a/src/swap-jupiter.js+++ b/src/swap-jupiter.js@@ -619,7 +619,12 @@ function closePicker() {async function loadRemoteTokens() {if (_remoteTokens.length) return;try {- const resp = await fetch('https://lite-api.jup.ag/tokens/v1/tagged/verified', { mode: 'cors' });+ // The picker already ships QUICK_TOKENS, so this list only widens it: an+ // unbounded call meant the widening could hang the picker instead.+ const resp = await fetch('https://lite-api.jup.ag/tokens/v1/tagged/verified', {+ mode: 'cors',+ signal: AbortSignal.timeout(8000),+ });if (!resp.ok) return;const data = await resp.json();if (Array.isArray(data)) {diff --git a/tests/check-fetch-timeouts.test.js b/tests/check-fetch-timeouts.test.jsnew file mode 100644index 000000000..6b547ef1c--- /dev/null+++ b/tests/check-fetch-timeouts.test.js@@ -0,0 +1,64 @@+// The guard that keeps every outbound third-party call bounded. Its own logic+// is worth testing: a checker that silently stops catching things is worse than+// no checker, because the gate keeps passing while the protection erodes.+import { describe, it, expect } from 'vitest';+import { scanFile } from '../scripts/check-fetch-timeouts.mjs';++const scan = (src) => scanFile('x.js', src);++describe('check-fetch-timeouts', () => {+ it('flags an external fetch with no deadline', () => {+ const out = scan(`const r = await fetch('https://api.example.com/v1/thing', { method: 'POST' });`);+ expect(out).toHaveLength(1);+ expect(out[0].line).toBe(1);+ });++ it('accepts a signal passed as the LAST key of a long options object', () => {+ // The window this replaced was fixed-size, so a call whose options ran+ // past it was reported as unbounded precisely when it was hardest to read.+ const body = Array.from({ length: 24 }, (_, i) => `\t\t\tfield${i}: ${i},`).join('\n');+ const out = scan([+ `const res = await fetch(URL_CONST, {`,+ `\tmethod: 'POST',`,+ `\tbody: JSON.stringify({`,+ body,+ `\t}),`,+ `\tsignal: controller.signal,`,+ `});`,+ `const URL_CONST = 'https://api.example.com/x';`,+ ].join('\n'));+ expect(out).toEqual([]);+ });++ it('accepts AbortSignal.timeout and the shared wrappers', () => {+ expect(scan(`await fetch('https://a.example/x', { signal: AbortSignal.timeout(5000) });`)).toEqual([]);+ expect(scan(`await fetchUpstream('https://a.example/x', {}, { timeoutMs: 5000 });`)).toEqual([]);+ expect(scan(`await pumpFetchJson('https://frontend-api-v3.pump.fun/coins/x');`)).toEqual([]);+ });++ it('resolves an external URL held in a const', () => {+ const src = [+ `const BASE = 'https://api.example.com';`,+ `const r = await fetch(\`\${BASE}/thing\`, { method: 'GET' });`,+ ].join('\n');+ expect(scan(src)).toHaveLength(1);+ });++ it('ignores same-origin and relative calls, which are a different concern', () => {+ expect(scan(`await fetch('/api/thing');`)).toEqual([]);+ expect(scan(`await fetch('https://three.ws/api/thing');`)).toEqual([]);+ expect(scan(`const B = 'http://localhost:3000';\nawait fetch(\`\${B}/x\`);`)).toEqual([]);+ });++ it('ignores stubs, definitions and commented-out code', () => {+ expect(scan(`globalThis.fetch = vi.fn(async () => new Response());`)).toEqual([]);+ expect(scan(`// await fetch('https://api.example.com/x');`)).toEqual([]);+ expect(scan(`\t * await fetch('https://api.example.com/x');`)).toEqual([]);+ });++ it('reports the file and line so the message is actionable', () => {+ const out = scan(`const a = 1;\nconst b = 2;\nawait fetch('https://api.example.com/x');`);+ expect(out[0]).toMatchObject({ file: 'x.js', line: 3 });+ expect(out[0].code).toContain('api.example.com');+ });+});