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.

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.md
index 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. reality
Validates every cron expression in `vercel.json` with
diff --git a/package.json b/package.json
index 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.js
index 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.mjs
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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');
+ });
+});