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
// Distributed rate limiting via Upstash Redis. Falls back to Postgres for the
// buckets that must stay distributed (money, auth), and to in-memory otherwise.
import { Ratelimit } from '@upstash/ratelimit';
import { env } from './env.js';
import { sql } from './db.js';
import { getRedis, isRedisAuthError } from './redis.js';
const redis = getRedis();
// Prod signal: real deployments set NODE_ENV=production (Vercel does). Tests and
// local dev never do, so the in-memory fallback stays fully permissive there.
const IS_PRODUCTION = env.NODE_ENV === 'production' || env.VERCEL_ENV === 'production';
const REDIS_CONFIGURED = Boolean(redis);
// Platform-wide hourly ceiling on PLATFORM-keyed paid 3D generations (the shared
// Replicate / self-host GPU budget). This is a circuit breaker, NOT a per-user
// limit: it stops the failure mode where an influx — or distributed abuse — sends
// many callers who each stay under their own 30/h cap but collectively drain real
// spend. Tunable via env without a code change; the default is generous enough
// that only a genuine surge or attack trips it, and when it does the free NVIDIA /
// HuggingFace lanes stay open, so paid capacity degrades instead of dead-ending.
const FORGE_PAID_GLOBAL_HOURLY = Math.max(1, Number(process.env.FORGE_PAID_GLOBAL_HOURLY) || 600);
// FORGE_SELFHOST_PRIMARY: the per-principal free-lane ceiling (mcp3dGenerateFree,
// below) is sized at 60/h to protect the RATE-LIMITED hosted NVIDIA NIM allocation
// the free lane leans on today. Once our own Cloud Run GPU fleet is primary that
// hosted allocation is out of the path, so the ceiling can rise to what the deployed
// fleet sustains. Default 240/h (4× — see the math in docs/gcp-credits.md: credit-
// window fleet of trellis_selfhost[max 2] + hunyuan3d[max 3] = 5 concurrent L4 slots
// at ~60s/asset blended ≈ 300 assets/h global, so a single heavy iterator at 240/h
// stays well under the fleet ceiling). Tunable via FORGE_FREE_HOURLY_SELFHOST once
// real per-asset latency is measured post-deploy. Reverts to 60/h the moment the
// flag is unset — abuse and per-IP paid gates are unaffected by this lever.
const FORGE_SELFHOST_PRIMARY = /^(1|true|on|yes)$/i.test(
String(process.env.FORGE_SELFHOST_PRIMARY || '').trim(),
);
const FREE_HOURLY_BASE = FORGE_SELFHOST_PRIMARY
? Math.max(60, Number(process.env.FORGE_FREE_HOURLY_SELFHOST) || 240)
: 60;
// One-time startup notice when Redis is unconfigured in production. Cheap buckets
// fall back to a PER-INSTANCE in-memory map — fine for a flood guard, meaningless
// as a bound across serverless fan-out — while money/cost and auth buckets degrade
// onto the durable Postgres counter (see fallbackLimiter), so this is a "running
// degraded" notice rather than an outage. Suppressed under vitest: the Vercel build
// inherits VERCEL_ENV=production while running the test gate, which made this fire
// as scary-but-meaningless build-log noise. The fallback behavior itself is NOT
// gated on VITEST — tests exercise it deliberately.
if (IS_PRODUCTION && !REDIS_CONFIGURED && !process.env.VITEST) {
console.error(
'[rate-limit] CONFIG: UPSTASH_REDIS_REST_URL/TOKEN are unset in production. ' +
'Money/auth limiters are counting in Postgres (durable, distributed, fixed-window); ' +
'cheap per-IP limiters fall back to a non-distributed in-memory map. Restore Redis ' +
'for sliding-window precision and to take the upsert off the database.',
);
}
const limiters = new Map();
const memoryBuckets = new Map();
// Circuit-breaker ceiling for the generic paid-endpoint family's facilitator
// /verify fan-out (api/_lib/x402-paid-endpoint.js). A backstop against a runaway
// retry loop or a distributed junk-X-PAYMENT flood — set well above realistic
// peak and raisable via env as volume grows, so scaling up is a config change,
// not a redeploy. Floored so a fat-fingered env value can't throttle the
// platform to a crawl.
const X402_VERIFY_GLOBAL_PER_HOUR = Math.max(
1200,
Number(process.env.X402_VERIFY_GLOBAL_PER_HOUR) || 12000,
);
// Per-IP ceilings for the same family, tunable by env for the same reason. The
// verify bucket is failure-weighted (see limits.x402VerifyIp / x402VerifyPenalty):
// a settled payment costs 1 token, a failed verify costs X402_VERIFY_FAIL_PENALTY.
// The defaults let one paying client pull 300 datapoints/min while still cutting a
// junk-payment flood off after ~20 failures/min. Floored so a bad env value cannot
// throttle paying traffic to a crawl, or (for the penalty) disable the guard.
const X402_PROBE_IP_PER_MIN = Math.max(120, Number(process.env.X402_PROBE_IP_PER_MIN) || 600);
const X402_VERIFY_IP_PER_MIN = Math.max(20, Number(process.env.X402_VERIFY_IP_PER_MIN) || 300);
const X402_VERIFY_FAIL_PENALTY = Math.max(
1,
Number(process.env.X402_VERIFY_FAIL_PENALTY) || 15,
);
// Global settle/verify ceiling for OUR self-hosted facilitator
// (api/x402-facilitator). Every co-signed settle burns sponsor SOL (~5000
// lamports base fee), so an unbounded flood of tiny allowlisted transfers could
// grind the sponsor down to SPONSOR_SOL_FLOOR_LAMPORTS and halt the whole paid
// loop. Bound it. Same floor rationale as the verify ceiling above.
const X402_FACILITATOR_GLOBAL_PER_HOUR = Math.max(
600,
Number(process.env.X402_FACILITATOR_GLOBAL_PER_HOUR) || 12000,
);
// Per-IP facilitator ceiling. The ring tick settles every paid call through
// the self-hosted facilitator from ONE egress IP (verify + settle = 2 hits per
// call), so at 94 calls/min the old hardcoded 60/min starved the ring itself
// (observed 2026-07-25: http_429 cascade, whole ticks failing). Env-tunable
// with the old value as the floor; external abusers still hit this wall.
const X402_FACILITATOR_IP_PER_MIN = Math.max(
60,
Number(process.env.X402_FACILITATOR_IP_PER_MIN) || 60,
);
// A limiter that always denies. Used in production for cost/money-moving buckets
// when Redis is absent: better to 503 a paid action than to silently allow
// unbounded spend across serverless instances.
function failClosedLimiter({ limit, window }) {
const ms = parseWindowMs(window);
return {
async limit() {
return {
success: false,
limit,
remaining: 0,
reset: Date.now() + ms,
reason: 'rate_limiter_unavailable',
};
},
};
}
/**
* @param {string} name
* @param {{ limit: number, window: string, critical?: boolean, local?: boolean }} opts
* `critical: true` marks a cost/money-moving bucket. When Redis is absent in
* production these fail closed (deny) instead of using the unbounded in-memory
* fallback. Non-critical buckets keep the permissive in-memory fallback so a
* missing-Redis misconfig degrades read endpoints gracefully rather than
* taking the whole site down.
* `degradeToMemory: true` overrides the critical fail-closed disposition on a
* Redis outage: instead of denying, the bucket falls back to the per-instance
* memory limiter. For sensitive-but-availability-critical buckets (auth/login)
* where a total lockout is worse than a weaker per-instance cap. Never use it
* for money-moving buckets — there, denying is the correct safety posture.
* `local: true` deliberately enforces per-instance, in-memory only — never a
* Redis command. For high-frequency, cheap-read buckets (status polling) whose
* only job is to bound poll floods, per-instance caps bound throughput just as
* well (limit × warm instances, and Vercel bounds instances), and the saved
* commands are what keep the Upstash quota alive (June 2026 outage). Never
* combine with `critical`.
*/
function getLimiter(name, opts) {
const key = `${name}:${opts.limit}:${opts.window}`;
if (limiters.has(key)) return limiters.get(key);
if (opts.local) {
const lim = memoryLimiter(name, opts);
limiters.set(key, lim);
return lim;
}
if (!redis) {
// No Redis configured at all. Money/auth buckets still get a distributed
// counter (Postgres); cheap buckets stay in per-instance memory.
const lim = fallbackLimiter(name, opts);
limiters.set(key, lim);
return lim;
}
const rl = new Ratelimit({
redis,
limiter: Ratelimit.slidingWindow(opts.limit, opts.window),
prefix: `rl:${name}`,
analytics: false,
});
const resilient = resilientLimiter(rl, name, opts);
limiters.set(key, resilient);
return resilient;
}
/**
* Hand a consumed hit back to its bucket, for the one case that justifies it:
* the request was charged, then produced nothing at all because a dependency we
* own was unavailable. The caller keeps its window instead of paying for our
* outage. Two conditions, both load-bearing: the bucket must be a single-use
* window (see the Redis note in resilientLimiter, which is why this refuses any
* other ceiling), and the refund must be unconditional at that point in the
* handler. A refund on a path that DID something turns the limiter off.
*/
export async function refundLimit(name, opts, id) {
if (opts.limit !== 1) {
throw new Error(`refundLimit: ${name} is not a single-use window (limit ${opts.limit})`);
}
return getLimiter(name, opts).refund(id);
}
// One warn per limiter name per cooldown — a Redis outage hits every request,
// so unthrottled logging would itself become a denial-of-service on the logs.
const _degradeWarnedAt = new Map();
const DEGRADE_WARN_COOLDOWN_MS = 60_000;
function warnDegradedOnce(name, err) {
// The shared Redis auth breaker (api/_lib/redis.js) already logged the one
// "auth failure" line and is fast-failing every command; its short-circuit
// rejections carry `circuitOpen`. Re-warning per limiter per cooldown on top of
// that is pure noise — skip it and let the breaker own the signal.
if (err?.circuitOpen) return;
// @upstash/ratelimit catches the underlying Redis rejection and re-throws its
// own UpstashError, dropping the `circuitOpen` tag — so an auth failure reaching
// here on the breaker's once-per-cooldown trial command would still log, once per
// limiter name. Across dozens of limiter names that recreates the WRONGPASS flood
// the breaker exists to silence. The breaker already owns the single auth-failure
// line and the rotate-the-token remediation, so suppress auth errors here too.
if (isRedisAuthError(err)) return;
const last = _degradeWarnedAt.get(name) || 0;
const t = Date.now();
if (t - last < DEGRADE_WARN_COOLDOWN_MS) return;
_degradeWarnedAt.set(name, t);
console.warn(
`[rate-limit] redis degraded for "${name}", limiter served from fallback decision:`,
err?.message || err,
);
}
// Upstash rejects every command with this once the account's plan-wide command
// allowance is spent. It is NOT a transient blip: the counter resets on the plan's
// billing boundary, so the store stays dead for the remainder of the period. It
// therefore deserves its own, unmistakable log line — the generic "redis degraded"
// warning sends an operator hunting for a network fault that isn't there.
export function isRedisQuotaError(err) {
return /max requests limit exceeded/i.test(String(err?.message || err || ''));
}
// Open-source Redis and Valkey (for example behind a self-hosted SRH proxy) reject
// the `#!lua flags=allow-key-locking` shebang that @upstash/ratelimit >= 2.1.0
// prefixes to its scripts, an Upstash-hosted-only extension. The rejection is
// deterministic, so no backoff can ever clear it: classify it apart from a
// transient fault so logs and /healthz stop calling it self-healing.
export function isRedisShebangIncompatibilityError(err) {
return /unexpected flag in script shebang/i.test(String(err?.message || err || ''));
}
let _shebangWarnedAt = 0;
let _lastFailureShebang = false;
function warnShebangIncompatibilityOnce(name, err) {
const t = Date.now();
if (t - _shebangWarnedAt < 60_000) return;
_shebangWarnedAt = t;
console.error(
`[rate-limit] FATAL INCOMPATIBILITY: the Redis backend rejects @upstash/ratelimit's Lua ` +
`script shebang for "${name}" (likely open-source Redis/Valkey behind the SRH proxy, not ` +
`Upstash-hosted). Not transient: pin @upstash/ratelimit below 2.1.0 or patch the scripts.`,
err?.message || err,
);
}
let _quotaWarnedAt = 0;
function warnQuotaOnce() {
const t = Date.now();
if (t - _quotaWarnedAt < 600_000) return;
_quotaWarnedAt = t;
console.error(
'[rate-limit] FATAL CAPACITY: the Upstash store has spent its plan-wide command ' +
'allowance. Every rate-limit command is rejected until the plan period rolls over. ' +
'Money/auth buckets are now counting in Postgres (durable); cheap buckets count ' +
'per-instance. Remediation: raise the Upstash plan, or cut command volume.',
);
}
// Circuit breaker in front of Redis, mirroring api/_lib/cache.js. Without it a
// degraded store makes EVERY rate-limited request pay a full failing round-trip
// before reaching its fallback — during the 2026-07-09 over-quota incident that
// was a ~300ms tax on every single API call, plus a rejected command per request.
// After CIRCUIT_FAIL_THRESHOLD consecutive failures we skip Redis entirely for a
// cooldown and serve from the fallback directly. One trial command is admitted
// once the cooldown elapses; its success closes the breaker.
//
// The cooldown escalates ×2 per consecutive re-arm up to CIRCUIT_COOLDOWN_MAX_MS,
// so a transient blip recovers inside 5s while an over-quota store — which cannot
// recover until its plan period rolls over — settles at one probe per 10 minutes
// instead of one per request.
const CIRCUIT_FAIL_THRESHOLD = 5;
const CIRCUIT_COOLDOWN_BASE_MS = 5_000;
const CIRCUIT_COOLDOWN_MAX_MS = 600_000;
let circuitFailures = 0;
let circuitOpenUntil = 0;
let circuitTrialInFlight = false;
let circuitRearms = 0;
function circuitAllows() {
if (circuitOpenUntil === 0) return true;
if (Date.now() < circuitOpenUntil) return false;
if (circuitTrialInFlight) return false;
circuitTrialInFlight = true; // half-open: exactly one trial
return true;
}
function circuitRecordSuccess() {
if (circuitOpenUntil !== 0) console.warn('[rate-limit] redis recovered — circuit closed');
circuitFailures = 0;
circuitOpenUntil = 0;
circuitTrialInFlight = false;
circuitRearms = 0;
_lastFailureShebang = false;
}
function circuitRecordFailure() {
circuitTrialInFlight = false;
circuitFailures += 1;
if (circuitFailures < CIRCUIT_FAIL_THRESHOLD && circuitOpenUntil === 0) return;
const cooldown = Math.min(CIRCUIT_COOLDOWN_MAX_MS, CIRCUIT_COOLDOWN_BASE_MS * 2 ** circuitRearms);
circuitRearms += 1;
circuitOpenUntil = Date.now() + cooldown;
}
// Thrown to route a caller straight to its fallback while the breaker is open,
// without emitting a per-request warning (the open/close transitions log once).
class RlCircuitOpenError extends Error {
constructor() {
super('rate-limit redis circuit open');
this.circuitOpen = true;
}
}
// Observability for /healthz — is the limiter's Redis path live right now, and
// how badly has it degraded over this instance's lifetime?
export function rateLimiterHealth() {
return {
configured: REDIS_CONFIGURED,
circuitOpen: circuitOpenUntil !== 0 && Date.now() < circuitOpenUntil,
circuitReopensInMs: Math.max(0, circuitOpenUntil - Date.now()),
quotaExhausted: _quotaWarnedAt > 0,
scriptIncompatible: _lastFailureShebang,
durableFallback: pgAvailable(),
// Outside production a bucket with no backend degrades to the permissive
// memory limiter rather than denying, so "no Redis, no Postgres" is the
// normal, healthy dev/test posture — not an outage.
enforcing: IS_PRODUCTION,
};
}
// Wrap a real (Redis-backed) Ratelimit so a Redis error — most importantly the
// account-wide "max requests limit exceeded" over-quota UpstashError — degrades
// instead of throwing an unhandled 500 out of every route. Non-critical buckets
// (the read/public/auth-IP limiters every page hits) FAIL OPEN: a limiter
// outage must never take down the API. Critical buckets (cost/money-moving)
// FAIL CLOSED: better to 503 a paid action than allow unbounded spend when the
// distributed limiter is blind.
function resilientLimiter(rl, name, opts) {
const ms = parseWindowMs(opts.window);
// Money and auth buckets must stay bounded across instances even when Redis
// cannot answer, so they degrade onto the durable Postgres counter rather
// than failing closed (which takes the paid product down for the length of
// the outage) or trusting per-instance memory (which bounds nothing). See
// fallbackLimiter. Everything else FAILS OPEN: a limiter outage must never
// take down a read endpoint.
const durable = opts.critical || opts.degradeToMemory ? fallbackLimiter(name, opts) : null;
return {
async limit(id) {
try {
if (!circuitAllows()) throw new RlCircuitOpenError();
const r = await rl.limit(id);
circuitRecordSuccess();
return r;
} catch (err) {
if (!err?.circuitOpen) {
circuitRecordFailure();
_lastFailureShebang = isRedisShebangIncompatibilityError(err);
if (isRedisQuotaError(err)) warnQuotaOnce();
else if (_lastFailureShebang) warnShebangIncompatibilityOnce(name, err);
else warnDegradedOnce(name, err);
}
if (durable) return durable.limit(id);
return {
success: true,
limit: opts.limit,
remaining: opts.limit,
reset: Date.now() + ms,
reason: 'rate_limiter_degraded',
};
}
},
// Upstash has no "give one token back": resetUsedTokens clears the whole
// identifier. That equals a refund only on a single-use window, which is
// why refundLimit refuses any other ceiling. A refund
// that cannot reach Redis is dropped rather than retried: the cost of
// losing it is one caller waiting out a window they should not have
// spent, and failing the request they are already being apologised to
// for would be worse.
async refund(id) {
try {
if (!circuitAllows()) throw new RlCircuitOpenError();
await rl.resetUsedTokens(id);
circuitRecordSuccess();
return true;
} catch (err) {
if (!err?.circuitOpen) {
circuitRecordFailure();
_lastFailureShebang = isRedisShebangIncompatibilityError(err);
if (isRedisQuotaError(err)) warnQuotaOnce();
else if (_lastFailureShebang) warnShebangIncompatibilityOnce(name, err);
else warnDegradedOnce(name, err);
}
if (durable) return durable.refund(id);
return false;
}
},
};
}
// Eviction for the in-memory fallback. The map otherwise grows one entry per
// distinct key forever (a scanner rotating IPs would balloon a long-lived dev
// process). Only sweeps when the map is over the cap, so the amortized cost on
// the hot path is O(1); the sweep itself drops every bucket whose newest
// timestamp predates the largest window any memory limiter uses (conservative
// — never evicts an entry a live limiter could still count).
const MEMORY_BUCKETS_MAX = 10_000;
let maxMemoryWindowMs = 60_000;
function sweepMemoryBuckets(now) {
if (memoryBuckets.size <= MEMORY_BUCKETS_MAX) return;
const cutoff = now - maxMemoryWindowMs;
for (const [id, timestamps] of memoryBuckets) {
if (!timestamps.length || timestamps[timestamps.length - 1] <= cutoff) {
memoryBuckets.delete(id);
}
}
}
// `name` namespaces the shared memoryBuckets map. Without it every fallback
// limiter counts against ONE array per IP, so distinct buckets contaminate
// each other the moment more than one degrades to memory (e.g. a Redis outage
// putting auth:ip and authed:read:ip in the same counter — page reads would
// then exhaust the login budget).
function memoryLimiter(name, { limit, window }) {
const ms = parseWindowMs(window);
if (ms > maxMemoryWindowMs) maxMemoryWindowMs = ms;
return {
async limit(id) {
const key = `${name}\u0000${id}`;
const now = Date.now();
sweepMemoryBuckets(now);
const bucket = memoryBuckets.get(key) || [];
const cutoff = now - ms;
const kept = bucket.filter((t) => t > cutoff);
if (kept.length >= limit) {
memoryBuckets.set(key, kept);
return { success: false, limit, remaining: 0, reset: kept[0] + ms };
}
kept.push(now);
memoryBuckets.set(key, kept);
return { success: true, limit, remaining: limit - kept.length, reset: now + ms };
},
// Hand back the newest hit in this bucket. See `refund` on the exported
// limiters for when a caller is allowed to do that.
async refund(id) {
const key = `${name}\u0000${id}`;
const kept = memoryBuckets.get(key);
if (!kept?.length) return false;
kept.pop();
if (kept.length) memoryBuckets.set(key, kept);
else memoryBuckets.delete(key);
return true;
},
};
}
function parseWindowMs(w) {
const m = /^(\d+)\s*(ms|s|m|h|d)$/.exec(w);
if (!m) return 60_000;
const n = parseInt(m[1], 10);
const unit = m[2];
return n * { ms: 1, s: 1e3, m: 60e3, h: 3600e3, d: 86400e3 }[unit];
}
// ── Postgres fallback limiter ─────────────────────────────────────────────
//
// The disposition of a `critical` bucket when Redis is blind used to be "deny"
// (failClosedLimiter). That is the right instinct for spend — an unmetered paid
// endpoint is worse than an unavailable one — but it is the wrong OUTCOME when
// the outage lasts: on 2026-07-09 the shared Upstash store hit its plan-wide
// command ceiling, which does not reset until the next calendar month, so every
// checkout, withdrawal, mint and trade would have 503'd for three weeks.
//
// Postgres is already a hard dependency of exactly those endpoints (their
// ledgers live in it), so a counter here is distributed, survives instance
// fan-out, and cannot succeed-when-the-action-couldn't-anyway. Fixed window,
// one atomic upsert — see the migration for the boundary-burst tradeoff.
//
// Cheap, non-critical buckets never come here: they degrade to the per-instance
// memory limiter, whose cost is zero. Only money and auth pay for an upsert.
const PG_PRUNE_INTERVAL_MS = 600_000;
let pgPrunedAt = 0;
// The widest window any bucket in `limits` declares (the daily caps: '1 d' /
// '24 h'). The prune floor below must be derived from this and NOT from
// `maxMemoryWindowMs`: that counter only rises when a limiter is CONSTRUCTED in
// the current process, so an instance whose first pg-backed bucket was, say,
// '5 m' prunes with a 10-minute floor and deletes every OTHER instance's live
// daily row. The table is shared, so one such instance silently resets the
// 5/day and 3/day spend caps for everybody (observed live: six calls against a
// 5/day bucket all succeeded, because a sibling process had wiped the row
// mid-window). Raise this if a wider window is ever added.
const PG_WIDEST_WINDOW_MS = 86_400_000;
// Drop windows that no live limiter can still be counting: 2x the widest window
// any bucket uses, so a row is only deleted once its window is long dead on
// every instance. Fire-and-forget: a failed prune is a no-op that retries on the
// next interval, never an error on the caller's request path.
function prunePgCounters(now) {
if (now - pgPrunedAt < PG_PRUNE_INTERVAL_MS) return;
pgPrunedAt = now;
const cutoff = now - 2 * Math.max(PG_WIDEST_WINDOW_MS, maxMemoryWindowMs);
sql`DELETE FROM rate_limit_counters WHERE window_start < ${cutoff}`.catch(() => {});
}
function pgLimiter(name, { limit, window }) {
const ms = parseWindowMs(window);
if (ms > maxMemoryWindowMs) maxMemoryWindowMs = ms;
return {
async limit(id) {
const now = Date.now();
const windowStart = Math.floor(now / ms) * ms;
const reset = windowStart + ms;
prunePgCounters(now);
// One statement: increment and read the post-increment count. No
// read-modify-write window for concurrent instances to race through.
const [row] = await sql`
INSERT INTO rate_limit_counters (bucket, window_start, hits)
VALUES (${`${name}\0${id}`}, ${windowStart}, 1)
ON CONFLICT (bucket, window_start)
DO UPDATE SET hits = rate_limit_counters.hits + 1
RETURNING hits
`;
const hits = row?.hits ?? 1;
return {
success: hits <= limit,
limit,
remaining: Math.max(0, limit - hits),
reset,
reason: 'rate_limiter_degraded_postgres',
};
},
async refund(id) {
const windowStart = Math.floor(Date.now() / ms) * ms;
const [row] = await sql`
UPDATE rate_limit_counters SET hits = greatest(0, hits - 1)
WHERE bucket = ${`${name}\0${id}`} AND window_start = ${windowStart}
RETURNING hits
`;
return Boolean(row);
},
};
}
// Is a durable fallback available? A limiter can only reach for Postgres if the
// connection string exists; `env.DATABASE_URL` throws when unset (it is a
// required var), so probe it without letting that escape.
function pgAvailable() {
try {
return Boolean(env.DATABASE_URL);
} catch {
return false;
}
}
// The fallback a bucket uses when Redis cannot answer, in priority order:
// critical / degradeToMemory → Postgres (distributed, durable)
// …with Postgres unreachable → the bucket's original disposition
// everything else → per-instance memory (cost-free, good enough)
// Wrapping pgLimiter in a try/catch keeps a DB blip from turning a Redis outage
// into a hard 500: it collapses to the pre-existing behaviour instead.
function fallbackLimiter(name, opts) {
const durable = (opts.critical || opts.degradeToMemory) && pgAvailable();
if (!durable) {
return opts.degradeToMemory || !(opts.critical && IS_PRODUCTION)
? memoryLimiter(name, opts)
: failClosedLimiter(opts);
}
const pg = pgLimiter(name, opts);
const lastResort = opts.degradeToMemory
? memoryLimiter(name, opts)
: IS_PRODUCTION
? failClosedLimiter(opts)
: memoryLimiter(name, opts);
return {
async limit(id) {
try {
return await pg.limit(id);
} catch (err) {
warnDegradedOnce(`${name}:pg`, err);
return lastResort.limit(id);
}
},
async refund(id) {
try {
return await pg.refund(id);
} catch (err) {
warnDegradedOnce(`${name}:pg`, err);
return lastResort.refund(id);
}
},
};
}
// The free 3D Studio's buckets, exported so its denials can name the limit a
// caller hit (api/_mcp-studio/handler.js) from the same numbers that enforce
// it below (limits.studioIp / studioGenBurst / studioGenHourly /
// studioGenPoolHourly / studioInstallCreate / studioGenerateGlobal).
export const STUDIO_LIMITS = Object.freeze({
genBurst: { limit: 4, window: '1 m' },
genHourly: { limit: 30, window: '1 h' },
genPoolHourly: { limit: 300, window: '1 h' },
genGlobal: { limit: FORGE_PAID_GLOBAL_HOURLY, window: '1 h' },
transport: { limit: 300, window: '1 m' },
installMint: { limit: 10, window: '1 h' },
});
// Preset limiters. Tune once viral traffic shape is known.
export const limits = {
// One-click "Surprise me" avatar composition. Each call composes a rigged GLB
// (~1s CPU + a few base-body fetches), so the ceiling stops a script from
// hammering the composer while leaving a delighted human free to reroll fast:
// 40 per 5 min per IP comfortably covers rapid rerolling, well under abuse.
surpriseIp: (ip) =>
getLimiter('avatar:surprise:ip', { limit: 40, window: '5 m', local: true }).limit(ip),
// Gallery view tracking (/api/avatars/view). Deliberately a dedupe rather than
// a throttle: one counted view per (IP, avatar) per 30 minutes, so a reader
// who reopens a card ten times moves view_count by one. Keyed on
// `${ip}:${avatarId}` so a browsing session can still count a view on every
// distinct avatar it opens. NOT local: with several Cloud Run instances a
// per-instance counter would let the same viewer count once per instance,
// which is exactly the inflation this bucket exists to stop.
avatarViewIp: (ipAndAvatar) =>
getLimiter('avatar:view:ip', { limit: 1, window: '30 m' }).limit(ipAndAvatar),
// Webcam sign-language transcription (/api/asl-recognition). Each call runs
// a sub-second CPU inference on the worker; 30 per 5 min per IP covers an
// active signed conversation while stopping scripted hammering.
aslTranscribeIp: (ip) =>
getLimiter('asl:transcribe:ip', { limit: 30, window: '5 m', local: true }).limit(ip),
// Text → signed animation clip (/api/sign). The compile is pure CPU (tens of
// milliseconds) and the response is deterministic, so the edge cache absorbs
// repeats; 120 per 5 min per IP leaves a live console and a batching agent
// plenty of headroom while capping how much CPU one caller can burn.
signCompileIp: (ip) =>
getLimiter('sign:compile:ip', { limit: 120, window: '5 m', local: true }).limit(ip),
// GuardChain preflight (/api/agent/guard). Pure in-process policy evaluation,
// sub-millisecond, no I/O; the cap only stops a script from using the box as
// a free CPU treadmill. An agent preflighting every tool call in an active
// chat session stays far under 300 evaluations per 5 minutes.
agentGuardIp: (ip) =>
getLimiter('agent:guard:ip', { limit: 300, window: '5 m', local: true }).limit(ip),
// The server-side agent loop (/api/agent/run). One request can fan into
// several LLM rounds plus tool executions against shared free-lane quotas,
// so it gets a tighter ceiling than the plain chat proxy: 30 runs per 5
// minutes per IP is an active conversation, not a drain.
agentRunIp: (ip) =>
getLimiter('agent:run:ip', { limit: 30, window: '5 m', local: true }).limit(ip),
// Public headless-chromium renderers (/api/render/glb, /api/render/avatar-clip).
// One call boots or borrows a chromium page, pulls up to 10 MB of GLB, and
// holds a CPU for seconds, so this is a real cost ceiling and NOT local: a
// per-instance counter multiplies by however many Cloud Run instances are up,
// which is exactly the bypass that made a 60/10m cap meaningless under
// autoscale. Both renderers share one bucket because they share the browser.
renderIp: (ip) =>
getLimiter('render:ip', { limit: 60, window: '10 m' }).limit(ip),
// The terminal renderer (/api/tty). Deliberately its OWN bucket rather than
// sharing render:ip: it uses no chromium at all (a CPU software rasterizer),
// but it holds one connection open for up to 45 seconds while it streams
// frames. Sharing meant a burst of browser renders could starve `curl
// three.ws/tty`, and a burst of terminal streams could starve the OG cards.
// Different cost shape, different ceiling. Not local, for the same
// autoscale-bypass reason as render:ip.
ttyIp: (ip) =>
getLimiter('tty:ip', { limit: 40, window: '10 m' }).limit(ip),
// Auth buckets gate credential guessing / account-creation spam. They are
// sensitive (critical) but use degradeToMemory: on a Redis outage they fall
// back to the per-instance memory limiter rather than failing closed. Failing
// closed here locks every user out of login — a self-inflicted outage strictly
// worse than the brute-force window a degraded per-instance cap leaves open,
// especially with bcrypt already throttling the credential path per request.
// 50/10m per IP: generous enough for shared NAT / office egress and an active
// user retrying a forgotten password without tripping, yet far below what a
// credential-stuffing run needs — bcrypt's per-request cost already throttles
// the guess rate, and `registerIp` (5/h) caps account creation independently.
authIp: (ip) =>
getLimiter('auth:ip', { limit: 50, window: '10 m', critical: true, degradeToMemory: true }).limit(ip),
// Per-account login bucket (key = hash of the lowercased login id). authIp
// alone is evaded by rotating addresses; this caps guesses at one account
// whatever the source. Sized above a human's retries so lockout abuse is
// bounded to a 15 minute pause on login for that account.
authAccount: (key) =>
getLimiter('auth:account', { limit: 30, window: '15 m', critical: true, degradeToMemory: true }).limit(key),
registerIp: (ip) =>
getLimiter('register:ip', { limit: 5, window: '1 h', critical: true, degradeToMemory: true }).limit(ip),
// `three-ws login` device links (api/cli/[action].js). Starting a link is
// unauthenticated, so it is capped per IP: 20 per 10 min covers a developer
// retrying across several machines behind one NAT and stops a script from
// flooding the table with codes. Polling is keyed on the device code itself
// and clears one poll every three seconds for the full ten-minute life of a
// code; anything faster is answered `slow_down` by the handler first.
cliLinkIp: (ip) =>
getLimiter('cli:link:ip', { limit: 20, window: '10 m', critical: true, degradeToMemory: true }).limit(ip),
// iOS app to Safari session handoff (api/auth/handoff.js). Minting is one
// tap on a payment, launch or trade surface, so 30 per 10 min per user is
// far above a real person and keeps a hijacked WebView from filling the
// table with live codes.
sessionHandoffUser: (userId) =>
getLimiter('auth:handoff:user', { limit: 30, window: '10 m', critical: true, degradeToMemory: true }).limit(userId),
cliPoll: (deviceHash) =>
getLimiter('cli:poll', { limit: 240, window: '10 m', local: true }).limit(deviceHash),
// Account linking (api/auth/telegram, api/auth/link-codes, api/auth/external-wallet).
// A magic link or a link code is one tap per device; 20 per 10 min per IP
// covers a flaky phone retrying and stops a script from filling the table.
// Polls are keyed on the request id and clear one every two seconds for
// the ten-minute life of a token. Claims from the device side are per IP.
// Wallet proofs are per user: a nonce burns on use, so retries are rare.
telegramMagicIp: (ip) =>
getLimiter('tg:magic:ip', { limit: 20, window: '10 m', critical: true, degradeToMemory: true }).limit(ip),
telegramMagicPoll: (id) =>
getLimiter('tg:magic:poll', { limit: 300, window: '10 m', local: true }).limit(id),
linkCodeUser: (userId) =>
getLimiter('link:code:user', { limit: 20, window: '10 m', critical: true, degradeToMemory: true }).limit(userId),
linkCodeClaimIp: (ip) =>
getLimiter('link:code:claim:ip', { limit: 20, window: '10 m', critical: true, degradeToMemory: true }).limit(ip),
linkCodePoll: (id) =>
getLimiter('link:code:poll', { limit: 300, window: '10 m', local: true }).limit(id),
externalWalletUser: (userId) =>
getLimiter('wallet:external', { limit: 20, window: '10 m', critical: true, degradeToMemory: true }).limit(userId),
// Open inference network (api/nodes/*). Node registration is an idempotent
// upsert an operator runs once per boot, so it gets a tight per-IP ceiling.
// The poll loop and result submission are the node's steady-state traffic:
// one long-poll plus one result per job, so the ceiling has to clear a busy
// operator running several capabilities without letting an unregistered IP
// hammer the claim queue. Both are `local` on purpose: every request already
// carries an ed25519 signature the handler verifies, so this bucket is spam
// shaping, not the security boundary, and it should not spend the shared
// Redis allowance.
nodeRegisterIp: (ip) =>
getLimiter('node:register:ip', { limit: 30, window: '10 m', local: true }).limit(ip),
nodeJobIp: (ip) => getLimiter('node:job:ip', { limit: 600, window: '5 m', local: true }).limit(ip),
// Session-scoped READS that fire on ordinary page loads (/api/me, home feed,
// credits balance, profile pages, wallet balance lookups). These borrowed the
// strict credential `authIp` bucket for years, which meant a few minutes of
// normal browsing drained the same 50/10m budget that gates real writes —
// users then got 429'd on the one request that mattered (e.g. creating an
// agent). Reads are cheap DB lookups behind auth, so the ceiling is generous:
// it only needs to stop scripted scraping, not human navigation.
// `local` on purpose. This bucket fires on essentially every authenticated page
// load, so it is the single hottest limiter on the platform — and its only job is
// to bound scripted scraping of endpoints the caller is already entitled to read.
// A per-instance cap does that (limit × warm instances, and Cloud Run bounds
// instances) while costing zero Redis commands. Keeping it distributed is what
// spent the shared Upstash allowance that the money buckets actually need.
authedReadIp: (ip) => getLimiter('authed:read:ip', { limit: 300, window: '5 m', local: true }).limit(ip),
// Agent creation (POST /api/agents) mints real EVM + Solana wallets, so it
// keeps a strict ceiling — but a DEDICATED one. Sharing `authIp` meant page
// browsing could exhaust the budget before the user ever pressed "create",
// failing the flow after the avatar upload had already succeeded. 20/10m is
// far more than any human setting up agents needs while still capping
// scripted wallet-mint spam per IP.
agentCreateIp: (ip) =>
getLimiter('agent:create:ip', { limit: 20, window: '10 m', critical: true, degradeToMemory: true }).limit(ip),
// CZ agent claim (/api/cz/claim). The GET mints a nonce row, the POST
// redeems it against one ECDSA signature; a real claim is two calls, so 10
// per hour leaves room for a wallet rejection and a retry while capping how
// many rows one IP can write into cz_claims. `local` because the handler
// writes nothing of value on the GET (a random nonce that is useless without
// the matching signature) and the money buckets need the shared Redis
// allowance more; per-instance is also exactly what this endpoint's previous
// hand-rolled in-memory bucket gave, so it is not a regression.
czClaimIp: (ip) => getLimiter('cz:claim:ip', { limit: 10, window: '1 h', local: true }).limit(ip),
// CAPTCHA-verified login bucket. When a user solves the Altcha proof-of-work
// puzzle (api/auth/captcha.js) they receive a signed bypass token that routes
// their login through this separate bucket instead of authIp. It is intentionally
// generous — a real human who solved a puzzle can retry freely — while still
// bounding bot runs that automate puzzle solving. degradeToMemory so a Redis
// outage never locks out a user who already solved the CAPTCHA.
authIpCaptcha: (ip) =>
getLimiter('auth:ip:captcha', { limit: 20, window: '10 m', critical: true, degradeToMemory: true }).limit(ip),
// NL→strategy compile (api/sniper/compile.js) runs a real LLM call per request,
// so it gets a dedicated, tighter-than-trading bucket: enough to iterate on a
// strategy a few times, bounded so it can't be turned into a free LLM relay.
sniperCompileIp: (ip) => getLimiter('sniper:compile:ip', { limit: 20, window: '10 m' }).limit(ip),
// Tweet drafting (api/x/draft.js) fans one request out to up to three LLM
// completions on platform-paid keys, so it gets its own bucket rather than
// draining `authIp`, which gates the actual publish. 20 per 10 min is many
// more rerolls than composing a tweet needs and still caps the fan-out.
xDraftIp: (ip) => getLimiter('x:draft:ip', { limit: 20, window: '10 m' }).limit(ip),
// README 3D (api/readme-3d.js POST): each call fetches a model and runs a
// mesh decimation pass, so it is CPU-heavy. 12 per 10 min covers a person
// tuning a budget and still bounds a script.
readme3dIp: (ip) => getLimiter('readme3d:ip', { limit: 12, window: '10 m' }).limit(ip),
// Flappin UFO run submissions (api/play/ufo-runs.js POST): each one replays the
// whole run through the simulation, a few ms of CPU. A person finishes a run
// every 30s at best; 30 per 10 min covers real play and bounds a script.
ufoRunIp: (ip) => getLimiter('play:ufo-run:ip', { limit: 30, window: '10 m' }).limit(ip),
// Copy Coach questions (api/copy/coach.js POST): anonymous, one LLM
// completion each. A first-timer asks a handful; 30 per 10 min is generous
// for a person and still bounds a script.
copyCoachIp: (ip) => getLimiter('copy:coach:ip', { limit: 30, window: '10 m' }).limit(ip),
// Per-agent X posting (api/x/agents.js, the post_to_x tool and run tool):
// every request runs the policy and may reach X, so bound it per account.
xAgentPost: (userId) => getLimiter('x:agent-post', { limit: 30, window: '10 m' }).limit(userId),
// Linking or unlinking a sign-in identity (api/auth/google, api/auth/identities).
identityLink: (userId) => getLimiter('identity:link', { limit: 10, window: '10 m' }).limit(userId),
// Strategy backtest (api/sniper/backtest.js) is a read-only replay over captured
// history; cached by strategy hash, so this only gates cache-miss origin work.
sniperBacktestIp: (ip) => getLimiter('sniper:backtest:ip', { limit: 40, window: '5 m' }).limit(ip),
// Strategy Lab live match preview (api/strategies.js preview). Fires on slider
// changes (debounced client side) and replays a cached history window in memory.
strategyPreviewIp: (ip) => getLimiter('strategy:preview:ip', { limit: 120, window: '5 m', local: true }).limit(ip),
// pump.fun coin metadata upload (name/symbol/image → R2 JSON). Cheap and
// idempotent, so it gets its own bucket instead of draining the strict
// `authIp` budget shared by on-chain buy/sell/launch actions. Iterating in
// the launch wizard would otherwise lock the user out of trading for 10 min.
pumpMetaIp: (ip) => getLimiter('pump:meta:ip', { limit: 60, window: '10 m' }).limit(ip),
// IRL write buckets — /irl places real 3D agents at GPS spots and logs visitor
// interactions, all from public (often anonymous) callers, so the write paths
// need their own ceilings or a script could carpet a map with pins, inflate
// view counts, or flood an owner's interaction inbox.
// · irlPinIp — create/edit/delete a placement (heavier; placing dozens is abuse)
// · irlInteractIp — log a tap/view/message (lighter; legit viewing fans out)
irlPinIp: (ip) => getLimiter('irl:pin:ip', { limit: 20, window: '10 m' }).limit(ip),
irlInteractIp: (ip) => getLimiter('irl:interact:ip', { limit: 60, window: '1 m' }).limit(ip),
// IRL shareable pin cards (api/irl/share.js) — uploads a real image to R2 per
// call, so this sits between irlPinIp and irlInteractIp: generous enough for a
// few reshares of the same moment, tight enough that scripting the upload path
// can't be used as free image-hosting.
irlShareIp: (ip) => getLimiter('irl:share:ip', { limit: 10, window: '10 m' }).limit(ip),
// /club viewer-presence heartbeat (api/club/presence.js). Every open tab posts
// once per 15s, so a handful of tabs behind one address sits near 20/min; 120
// leaves a shared NAT egress plenty of room while capping how fast a script can
// churn distinct session ids at the counter. `local` on purpose: the counter it
// guards is per-instance in-memory state, so a per-instance bucket is exactly
// the right scope and costs zero Redis commands on a page that polls forever.
clubPresenceIp: (ip) => getLimiter('club:presence:ip', { limit: 120, window: '1 m', local: true }).limit(ip),
// Living Stages tip recording (api/stage/tip.js). Each call carries a real
// on-chain settlement signature and is deduped per signature, so the limiter
// only blunts a forger spamming distinct fake signatures at the recorder — a
// generous ceiling for a lively crowd that still caps that abuse surface.
stageTipIp: (ip) => getLimiter('stage:tip:ip', { limit: 60, window: '1 m' }).limit(ip),
// IRL proof-of-presence mint (H3) — a walking viewer re-mints a fix token only
// when their coarse cell changes (every ~150 m of travel), so a generous 30/min
// covers a brisk walk + a few re-tries while a token-banking sweep (mint many
// distinct cells to scrape) trips fast. Keyed per IP.
irlFixIp: (ip) => getLimiter('irl:fix:ip', { limit: 30, window: '1 m' }).limit(ip),
// IRL World Lines (proof-of-presence AR quests). Three write buckets, per IP:
// · create — placing a quest is heavier + accountable (auth-gated), the tightest.
// · challenge — issuing a single-use completion nonce; a co-located visitor may
// re-issue a few times (expiry, retries) while walking the spot.
// · complete — settling the agent-signed proof. A real visitor completes once, so
// this only absorbs retries; a low ceiling blunts grinding the mint path.
worldLineCreateIp: (ip) => getLimiter('wl:create:ip', { limit: 15, window: '10 m' }).limit(ip),
worldLineChallengeIp: (ip) => getLimiter('wl:challenge:ip', { limit: 30, window: '5 m' }).limit(ip),
worldLineCompleteIp: (ip) => getLimiter('wl:complete:ip', { limit: 20, window: '5 m' }).limit(ip),
// IRL placement token bucket (D4) — keyed per (device_token + IP), tighter than
// the coarse per-IP `irlPinIp` so one device can't script a rapid placement flood
// even from a rotating IP. Two windows: a 5/min burst guard and a 30/hour ceiling.
// Non-critical → a Redis outage fails open (degraded + logged once/min) so an
// infra hiccup never blocks a legitimate placement.
irlPinBurst: (key) => getLimiter('irl:pin:burst', { limit: 5, window: '1 m' }).limit(key),
irlPinHourly: (key) => getLimiter('irl:pin:hourly', { limit: 30, window: '1 h' }).limit(key),
// IRL report submissions (D4) — one report write per (device + IP) burst. The
// distinct-reporter dedup in api/irl/report.js is the real anti-abuse gate; this
// just bounds raw POST volume from one source.
irlReportIp: (ip) => getLimiter('irl:report:ip', { limit: 10, window: '5 m' }).limit(ip),
// Same-origin image proxy (api/img). A token-cloud view loads dozens of
// thumbnails at once, so the ceiling is generous — but bounded so the proxy
// can't be turned into an open bandwidth relay. Responses are CDN-cached.
// local: those dozens-per-pageview each spent a distributed Redis command purely
// to bound a bandwidth flood on a side-effect-free, CDN-cached read. A
// per-instance cap bounds one IP's throughput just as well (limit × warm
// instances) — the reasoning already applied to publicIp / widgetRead /
// authedReadIp. After those moved this was the largest remaining source of
// avoidable quota burn, and the Upstash plan allowance ran out on 2026-07-10.
imgProxyIp: (ip) => getLimiter('img:ip', { limit: 300, window: '5 m', local: true }).limit(ip),
// Live holder-cohort reads (api/coin/:mint/cohorts for un-snapshotted agent
// tokens) fan out to a paid Helius getTokenAccounts walk. Responses are CDN-
// cached, so this only gates cache-miss origin hits — generous for an
// interactive panel, tight enough that one IP can't run up the Helius bill.
cohortsIp: (ip) => getLimiter('cohorts:ip', { limit: 45, window: '5 m' }).limit(ip),
oauthRegisterIp: (ip) =>
getLimiter('oauth:register:ip', { limit: 10, window: '1 h' }).limit(ip),
// zauth RepoScan pass-through (api/zauth-reposcan). Each POST forwards to
// zauth's paid x402 endpoint and each GET polls a scan session; cap per IP
// so one caller can't use the proxy as a relay to hammer their upstream.
zauthScanIp: (ip) => getLimiter('zauthscan:ip', { limit: 30, window: '1 m' }).limit(ip),
// aixbt intelligence bridge (api/aixbt/*). Each call may fall through to the
// upstream aixbt REST API, which is rate-limited per key — cap per IP so one
// caller can't drain the shared key's budget. Reads are cached, so this is
// generous enough for an interactive feed. The global ceiling prevents many
// distributed IPs from collectively exhausting the shared upstream key.
aixbtIp: (ip) => getLimiter('aixbt:ip', { limit: 90, window: '1 m' }).limit(ip),
// Hourly per-IP share of the global ceiling for the optional-auth /api/v1
// market door: the per-minute bucket above would let one source spend the whole
// 1800/h budget in about 20 minutes and 429 every other caller.
aixbtHourlyIp: (ip) => getLimiter('aixbt:ip-hourly', { limit: 60, window: '1 h' }).limit(ip),
aixbtGlobal: () => getLimiter('aixbt:global', { limit: 1800, window: '1 h' }).limit('global'),
// Solana Developer Platform proxy (api/sdp/*). Each call fronts the SDP API
// under our server-side key, and writes (wallet create / issuance / payment)
// move real value, so cap per IP to keep that egress bounded and prevent the
// shared key's quota from being drained by one caller. Generous enough for an
// interactive dashboard; reads are not cached so this gates every origin hit.
sdpIp: (ip) => getLimiter('sdp:ip', { limit: 60, window: '1 m' }).limit(ip),
// Avatar custodial-wallet payouts (api/agent/send-sol). The per-send USD cap
// and per-IP limit bound a single call, but neither bounds total daily outflow
// if the demo token leaks or many IPs are used. This wallet-wide daily ceiling
// (keyed on the wallet pubkey, not the caller) caps aggregate payouts to
// N × per-send-cap per day. Critical → fails closed in prod without Redis so a
// missing limiter can never silently uncap a money-moving endpoint.
avatarPayoutDaily: (walletAddr) =>
getLimiter('avatar:payout:daily', { limit: 50, window: '24 h', critical: true }).limit(
walletAddr,
),
// Proof-of-grind gallery. Publishing verifies a signed receipt server-side then
// writes a public rarity entry — bound per IP so one caller can't carpet the
// gallery, but generous enough for a real owner publishing a few grinds.
// Reads (gallery list / leaderboard / appraisal) are cheap and CDN-cacheable.
// Referral-code availability check (GET /api/users/referral-code?code=…).
// Debounced at 280 ms client-side; a 20-char code produces ~20 checks. Use a
// dedicated bucket (not authIp) so typing a vanity code doesn't consume the
// login/auth budget and lock out shared-IP users (offices, shared NAT).
referralCodeCheckIp: (ip) =>
getLimiter('referral:code:check:ip', { limit: 120, window: '5 m' }).limit(ip),
// Referral-link visit beacons (public, unauthenticated). Generous — a real
// visitor fires once per link per page-load — but bounded so the funnel
// table can't be flooded from one IP.
referralVisitIp: (ip) =>
getLimiter('referral:visit:ip', { limit: 60, window: '5 m' }).limit(ip),
// Referral attribution claims (POST /api/users/referral-claim). A real person
// claims once per account, so a handful per IP per day covers shared NAT while
// stopping one machine from attributing a stream of throwaway accounts.
referralClaimIp: (ip) =>
getLimiter('referral:claim:ip', { limit: 10, window: '1 d', critical: true, degradeToMemory: true }).limit(ip),
vanityGalleryPublishIp: (ip) =>
getLimiter('vanity:gallery:publish:ip', { limit: 12, window: '10 m' }).limit(ip),
vanityGalleryReadIp: (ip) =>
getLimiter('vanity:gallery:read:ip', { limit: 240, window: '5 m' }).limit(ip),
// Both `local`: generous per-caller flood guards on the MCP transport, not spend
// controls (the paid MCP tools carry their own `critical` buckets — mcpAgentPay,
// mcp3dGenerate, mcpPumpGated — which stay distributed). At 1200/min and 600/min
// these were among the biggest Redis-command consumers on the platform while
// bounding nothing that costs money.
mcpUser: (userId) => getLimiter('mcp:user', { limit: 1200, window: '1 m', local: true }).limit(userId),
mcpIp: (ip) => getLimiter('mcp:ip', { limit: 600, window: '1 m', local: true }).limit(ip),
// Generic per-IP bucket for authenticated app endpoints (agent screen feed,
// task queue, etc.). Callers pass an override to size the bucket to their
// traffic shape — a screenshot push stream needs hundreds/min, a roster poll
// only a handful. getLimiter keys its cache by name+limit+window, so each
// distinct override gets its own isolated bucket under the rl:api:ip prefix.
apiIp: (ip, opts = {}) =>
getLimiter('api:ip', { limit: 120, window: '1 m', ...opts }).limit(ip),
// The Crawl (api/crawl/[action].js). Frames are fetched once per step per tile
// by every viewer of /crawl, so that bucket stays in per-instance memory rather
// than spending a Redis command per JPEG; it guards against floods, not spend.
// Reads are the stats/crawlers/pages/live lane; missions are the owner write.
crawlFrameIp: (ip) => getLimiter('crawl:frame:ip', { limit: 900, window: '1 m', local: true }).limit(ip),
crawlReadIp: (ip) => getLimiter('crawl:read:ip', { limit: 240, window: '1 m', local: true }).limit(ip),
crawlMissionIp: (ip) => getLimiter('crawl:mission:ip', { limit: 30, window: '10 m' }).limit(ip),
// Free, unauthenticated 3D Studio (api/mcp-studio.js) abuse protection. Every
// studio tool routes through a FREE lane (NVIDIA NIM text→3D, HF Spaces
// image→3D) — zero marginal vendor cost — because the studio never names the
// paid Replicate backend and this deployment has free engines configured, so
// forge's free-first router never falls back to paid (see BACKENDS.trellis:
// "Free deployments never route here automatically"). These per-IP caps (a
// short burst cap that stops hammering + an hourly cap per source) still
// enforce whenever Redis is healthy — they are real quota, not a comment.
//
// NON-critical on purpose (fail OPEN on a Redis outage), mirroring the paid
// server's own free lane (mcp3dGenerateFree): "a Redis outage must never deny
// a zero-cost generation." Failing these closed took the whole free studio
// down during the June-2026 Upstash over-quota outage — a self-inflicted
// denial of a free feature for no spend saved. Spend is still protected in
// depth: /api/forge underneath fail-CLOSES its own paid-lane global breaker
// (mcp3dGenerateGlobal), so even a misrouted paid call can't drain budget.
studioGenBurst: (ip) =>
getLimiter('studio:gen:burst', { limit: 4, window: '1 m' }).limit(ip),
studioGenHourly: (ip) =>
getLimiter('studio:gen:hourly', { limit: 30, window: '1 h' }).limit(ip),
// Ceiling on one source IP when the burst/hourly caps above are keyed per
// ChatGPT user (openai/subject) instead of per IP. Every ChatGPT user reaches
// us from OpenAI's shared egress pool, so a per-IP 30/h would ration the whole
// directory as one caller; the subject is client-supplied, so this pool cap is
// what stops a forged subject per call from escaping the limits entirely.
studioGenPoolHourly: (ip) =>
getLimiter('studio:gen:pool:hourly', { limit: 300, window: '1 h' }).limit(ip),
// Minting a free install token (POST /api/mcp-studio/install): one tiny insert,
// but unbounded minting would let one caller escape every per-caller cap, so it
// is capped per IP. Tokens still share studioGenPoolHourly per IP.
studioInstallCreate: (ip) =>
getLimiter('studio:install:create', { limit: 10, window: '1 h' }).limit(ip),
// Cheap per-IP cap on studio transport/discovery (initialize, tools/list,
// ping, resources). Bounds discovery floods without touching the generation
// budget. Non-critical: a missing-Redis misconfig degrades gracefully.
studioIp: (ip) => getLimiter('studio:ip', { limit: 300, window: '1 m' }).limit(ip),
// Free-studio persona writes (create_agent_persona / persona_say): each fetches
// or restores a bounded GLB and writes a small identity record — cheap, but not
// free, so a per-IP burst cap stops a scripted flood from filling storage. The
// read path (get_agent_persona) rides the studioIp transport cap above.
// Non-critical: like the generation lanes, a Redis outage must never deny a
// zero-cost embodiment feature (spend is protected in depth downstream).
studioPersonaWrite: (ip) =>
getLimiter('studio:persona:write', { limit: 20, window: '1 m' }).limit(ip),
// Per-principal ceiling on the expensive/gated pump-fun MCP tools (vanity grind,
// whale/claim watches, metadata upload that burns shared IPFS pinning credits).
// A bearer authorizes these for free, so without a per-principal cap one account
// could drive unlimited expensive calls. Critical — fail closed in prod.
mcpPumpGated: (principal) =>
getLimiter('mcp:pump:gated', { limit: 30, window: '1 m', critical: true }).limit(principal),
// Paid MCP tools — each call runs real compute (glTF validation / inspection
// / optimization on a fetched model). Marked critical so they fail closed in
// prod without Redis rather than allowing unbounded paid work per instance.
mcpValidate: (key) =>
getLimiter('mcp:validate', { limit: 10, window: '1 m', critical: true }).limit(key),
mcpInspect: (key) =>
getLimiter('mcp:inspect', { limit: 30, window: '1 m', critical: true }).limit(key),
mcpOptimize: (key) =>
getLimiter('mcp:optimize', { limit: 10, window: '1 m', critical: true }).limit(key),
// Materialize. Analysis fetches, parses, welds and probes a mesh, then builds
// a BVH over it, so it costs about as much as an optimize; quoting adds only
// arithmetic on top of the same analysis (which is memoized per source URL),
// so it gets a wider budget for an agent dragging a size or material choice.
mcpPrintAnalyze: (key) =>
getLimiter('mcp:print-analyze', { limit: 10, window: '1 m', critical: true }).limit(key),
mcpPrintQuote: (key) =>
getLimiter('mcp:print-quote', { limit: 30, window: '1 m', critical: true }).limit(key),
// Diffing fetches and fully parses TWO models per call, so it costs roughly
// double an inspect and gets half the budget.
mcpDiff: (key) =>
getLimiter('mcp:diff', { limit: 15, window: '1 m', critical: true }).limit(key),
// mint_3d_asset calls that did not pay per call (an OAuth / API key caller,
// or an x402 subscription window). The platform authority pays the rent and
// fee of every mint, and a fresh recipient wallet defeats the idempotency
// key, so without this an account could loop mainnet mints off the treasury.
// Per-call x402 payments skip it: each of those already covered its own cost.
mcpMint3dUnpaidMainnet: (key) =>
getLimiter('mcp:mint3d:unpaid:mainnet', { limit: 5, window: '1 d', critical: true }).limit(key),
// Web domains. Every uncached search or check is a metered Cloud Domains
// request (300 a day per project), so a caller gets a small hourly budget and
// a registration attempt, which spends credits, a smaller one.
domainsLookup: (key) => getLimiter('domains:lookup', { limit: 40, window: '1 h' }).limit(key),
domainsRegister: (key) => getLimiter('domains:register', { limit: 10, window: '1 h', critical: true }).limit(key),
mcpMint3dUnpaidDevnet: (key) =>
getLimiter('mcp:mint3d:unpaid:devnet', { limit: 30, window: '1 h', critical: true }).limit(key),
// 3D Studio MCP. Generation submits a real GPU job on Replicate (text→image
// and/or image→3D reconstruction) that costs real money, so it gets a hard
// hourly ceiling per principal. Status polling is cheap and frequent.
mcp3dGenerate: (key) =>
getLimiter('mcp3d:generate', { limit: 30, window: '1 h', critical: true }).limit(key),
// Global circuit breaker on platform-keyed paid generation — the shared
// Replicate/self-host budget. Keyed by 'global' (mirrors chatHostKeyGlobal /
// x402PayGlobal): stops many accounts, each under their own mcp3dGenerate cap,
// from collectively draining spend during an influx. Critical → fails closed in
// prod without Redis, like the per-user paid bucket it backstops.
mcp3dGenerateGlobal: () =>
getLimiter('mcp3d:generate:global', {
limit: FORGE_PAID_GLOBAL_HOURLY,
window: '1 h',
critical: true,
}).limit('global'),
// Free generation lane (NVIDIA NIM TRELLIS draft). No Replicate/vendor spend,
// so it gets a much higher per-principal ceiling than the paid bucket and is
// NON-critical: a Redis outage must never deny a zero-cost generation (fail
// open), unlike the paid lane which fails closed to protect spend. A real
// human iterating on a prompt routinely exceeds 12/h; this lane lets them.
mcp3dGenerateFree: (key) =>
getLimiter('mcp3d:generate:free', { limit: FREE_HOURLY_BASE, window: '1 h' }).limit(key),
// Holder perk (Lever 2): $THREE tiers raise the free-generation ceiling by their
// rate multiplier. Same per-key counter + prefix as the base free lane — the tier
// only lifts the threshold, so a holder iterating heavily isn't throttled at 60/h.
// `multiplier` comes from a verified tier pass (pure HMAC, no RPC on the hot path).
mcp3dGenerateFreeTiered: (key, multiplier = 1) =>
getLimiter('mcp3d:generate:free', {
limit: Math.max(FREE_HOURLY_BASE, Math.round(FREE_HOURLY_BASE * (Number(multiplier) || 1))),
window: '1 h',
}).limit(key),
// Batch submit (api/forge-batch.js): one call fans out to N /forge
// submissions internally, so it needs its own, much tighter ceiling than
// mcp3dGenerateFreeTiered guards per-item spend already (each fanned-out
// item still passes through the free lane's own per-IP limiter). This
// bucket just caps how many BATCH calls a principal can open per hour; the
// same $THREE tier multiplier that raises the free lane also raises this.
forgeBatchSubmit: (key, multiplier = 1) =>
getLimiter('forge:batch:submit', {
limit: Math.max(10, Math.round(10 * (Number(multiplier) || 1))),
window: '1 h',
}).limit(key),
// Batch group polling (GET /api/forge-batch?batch=) fans out to N
// /forge?job= status checks per call, same high-frequency shape as
// mcp3dStatus, so it gets the same per-instance (`local`) treatment: a
// distributed Redis command per poll buys no real protection here.
forgeBatchStatus: (key) =>
getLimiter('forge:batch:status', { limit: 120, window: '1 m', local: true }).limit(key),
// Material Studio (api/material-studio.js): non-destructive material edits,
// AI restyle (one watsonx call + one gltf-transform mutation pass — cheap,
// no GPU job), and seeded variant fan-out. Free, hosted, and non-critical
// like mcp3dGenerateFree — a Redis outage must never deny a zero-cost edit.
// Uploads (exporting/checkpointing a lineage version) get a higher ceiling
// than restyle/variants since they carry no LLM/CPU-heavy cost.
materialStudioRestyle: (key) =>
getLimiter('material-studio:restyle', { limit: 40, window: '1 h' }).limit(key),
materialStudioUpload: (key) =>
getLimiter('material-studio:upload', { limit: 120, window: '1 h' }).limit(key),
// BNB vault upload (api/bnb/vault-upload.js) — encrypts + writes a real
// Greenfield tx + SP PUT per call, the heaviest write in the BNB vault
// track. Tight per-IP ceiling; a seller listing dozens of items per hour is
// already an outlier, and each call carries real Greenfield gas cost.
bnbVaultUploadIp: (ip) => getLimiter('bnb:vault:upload:ip', { limit: 20, window: '1 h' }).limit(ip),
// BNB vault reads (api/vault/list.js, api/vault/status.js) — free, no
// write cost, but each call does a real `eth_getLogs`/`eth_call` against a
// public RPC (list.js) or a Storage-Provider fetch (manifest joins), so a
// generous but real ceiling, not unlimited.
bnbVaultReadIp: (ip) => getLimiter('bnb:vault:read:ip', { limit: 120, window: '10 m' }).limit(ip),
// BNB vault unlock (api/vault/unlock.js) — the one call in this track that
// releases a real (wrapped) secret. Tighter than the read ceiling; a
// legitimate buyer unlocks the same object at most a handful of times.
bnbVaultUnlockIp: (ip) => getLimiter('bnb:vault:unlock:ip', { limit: 30, window: '10 m', critical: true }).limit(ip),
// Status polling is the highest-frequency call in the generation flow (every
// active job polls every few seconds, plus the /forge health pill). It only
// guards against pathological poll floods, so it is enforced per instance
// (`local`) — spending a distributed Redis command per poll is what drained
// the Upstash quota without buying any real protection here.
mcp3dStatus: (key) =>
getLimiter('mcp3d:status', { limit: 240, window: '1 m', local: true }).limit(key),
// Free X post reader / video tool. Extract fans out to up to three third-party
// endpoints per call; download streams bytes through us, so both are per IP.
xVideoExtract: (ip) => getLimiter('x-video:extract', { limit: 20, window: '1 m' }).limit(ip),
xVideoDownload: (ip) => getLimiter('x-video:download', { limit: 20, window: '1 m' }).limit(ip),
// Persona wallet identity reads (balances, reputation, holdings, nameplate) —
// several live RPC/HTTP calls per invocation, so a tighter ceiling than plain
// status polling but generous enough for a chat turn to check before tipping.
mcp3dPersonaIdentity: (key) =>
getLimiter('mcp3d:persona:identity', { limit: 60, window: '1 m', local: true }).limit(key),
// Persona value-movement (persona_tip / persona_send) — moves real USDC, so it
// gets a hard, critical, low-throughput ceiling independent of the per-call and
// per-session USDC spend caps enforced inside the handler.
mcp3dPersonaSpend: (key) =>
getLimiter('mcp3d:persona:spend', { limit: 20, window: '1 h', critical: true }).limit(key),
// Platform-wide hourly circuit breaker across ALL free-studio IPs, so
// distributed callers each under their own studioGenHourly cap can't
// collectively flood the free NVIDIA / HF allocation. Enforced whenever Redis
// is healthy. NON-critical (fail OPEN on a Redis outage) for the same reason as
// studioGenBurst/Hourly above: the studio's lanes are zero marginal cost, so a
// Redis outage must never dead-end a free generation. Real paid spend is still
// fail-CLOSED one layer down at forge's own mcp3dGenerateGlobal, which this
// breaker only backstops. (studioIp / studioGenBurst / studioGenHourly are
// defined above next to the other mcp buckets.)
studioGenerateGlobal: () =>
getLimiter('studio:generate:global', {
limit: FORGE_PAID_GLOBAL_HOURLY,
window: '1 h',
}).limit('global'),
// Forge prompt enhancer — one free-tier LLM rewrite per call. Cheap text
// completion, but each one hits an upstream provider, so cap per principal to
// keep that egress bounded. Non-critical: a Redis outage must never block a
// rewrite (the enhancer degrades gracefully to the original prompt anyway).
forgeEnhance: (key) => getLimiter('forge:enhance', { limit: 40, window: '1 h' }).limit(key),
// Instant Agent (/start): the anonymous "one sentence to a live agent" call.
// One real LLM completion per request with no account behind it, so it gets
// its own bucket rather than the shared publicIp pool: a script hammering it
// must not be able to spend provider budget, and must not be able to starve
// the read endpoints the same visitor's page needs. 12/10m is roughly a dozen
// honest retries while a person is deciding on their idea.
instantAgentIp: (ip) => getLimiter('instant-agent:ip', { limit: 12, window: '10 m' }).limit(ip),
// Self-hosted TRELLIS NIM demo (api/forge-nim) — each call is one real
// image/text→3D inference against the NIM, so cap per principal to keep that
// GPU egress bounded. Non-critical: a Redis blip must never block the demo.
forgeNim: (key) => getLimiter('forge:nim', { limit: 30, window: '1 h' }).limit(key),
// Conversational iteration (api/forge-iterate) — an ownership-preserving
// twin of the free studio's refine_model tool, called from the signed-in
// Forge Studio UI. Each call is one real regeneration, so cap per principal
// like every other forge-adjacent REST endpoint. /api/forge underneath has
// its own generation gates; this bounds the composition/lineage wrapper
// itself. Non-critical: a Redis blip must never block an iteration.
forgeIterate: (key) => getLimiter('forge:iterate', { limit: 60, window: '1 h' }).limit(key),
// Forge-Off upvotes (api/forge-vote) — one cheap DB write per tap from an
// anonymous browser. Generous so a visitor can toggle and browse a full
// board without hitting a wall, tight enough to blunt a single IP carpeting
// votes across the catalogue (the per-(creation,voter) PRIMARY KEY already
// caps real influence at one vote each). Non-critical: a Redis blip must
// never block a vote — the vote itself is idempotent.
forgeVote: (key) => getLimiter('forge:vote', { limit: 120, window: '10 m' }).limit(key),
// Discord Activity shared Forge room (api/gateway/discord-activity-room):
// one group of up to a voice channel's worth of people posting prompts,
// creations and votes into one room. Keyed per Discord user id so a bored
// participant can't flood the room's event log for the whole call; a real
// voice channel session comfortably fits inside this.
discordActivityWrite: (discordUserId) => getLimiter('discord:activity:write', { limit: 60, window: '10 m' }).limit(discordUserId),
// Free text→3D lane (api/v1/ai/text-to-3d) — each generation drives one real
// NVIDIA NIM TRELLIS GPU inference, so the free tier is a per-IP daily quota
// (10/day). Above it the endpoint returns 429 + a pointer to the paid
// /api/x402/forge tiers rather than paywalling silently. Non-critical: a Redis
// blip degrades to the per-instance memory limiter, never blocks generation.
aiTextTo3d: (ip) => getLimiter('ai:text-to-3d', { limit: 10, window: '24 h' }).limit(ip),
// Free token security check (api/v1/token/security) — reads getAccountInfo +
// getTokenLargestAccounts off the shared RPC and DexScreener, all cached 60s at
// the edge, so this only gates cache-miss origin hits. 20/min per IP is generous
// for an agent screening a watchlist while capping a scripted enumeration flood.
// Non-critical: a Redis blip degrades to the per-instance memory limiter.
tokenSecurityIp: (ip) => getLimiter('token:security:ip', { limit: 20, window: '1 m' }).limit(ip),
// Robinhood Chain market data (api/v1/robinhood/*) — free reads that fan out to
// on-chain multicall (Chainlink NAV snapshot), Blockscout, DefiLlama, CoinGecko
// and DexScreener, every one behind a short-TTL cache, so this only gates
// cache-miss origin hits. A DEDICATED per-IP bucket (never the shared publicIp
// pool — see the play-lobby-429 self-DoS lesson): 60/min is generous for an
// interactive board polling the stocks/coins tabs while capping a scripted
// enumeration flood. Non-critical: a Redis blip degrades to the per-instance
// memory limiter, never blocks a read.
robinhoodRead: (ip) => getLimiter('robinhood:read:ip', { limit: 60, window: '1 m' }).limit(ip),
// Free name resolution (api/v1/resolve) — wraps the same ENS RPC failover
// chain and SNS/Bonfida calls api/agents/ens/[name].js and api/sns.js already
// make, all with their own in-process caches, so this only gates cache-miss
// origin hits. 30/min per IP matches the spec's high-frequency-agent-primitive
// budget without inviting a scripted enumeration flood. Non-critical: a Redis
// blip degrades to the per-instance memory limiter, never blocks a resolution.
resolveIp: (ip) => getLimiter('v1:resolve:ip', { limit: 30, window: '1 m' }).limit(ip),
// Diorama composer (api/diorama action:compose) — one free-first LLM
// completion per call that decomposes a sentence into a placed object set.
// Paid upstream egress, so cap per IP and add a global hourly circuit breaker.
// Critical: a Redis outage in prod fails closed rather than handing out
// unbounded paid inference (the same posture as the chat/brain buckets).
dioramaComposeIp: (ip) =>
getLimiter('diorama:compose:ip', { limit: 20, window: '10 m', critical: true }).limit(ip),
dioramaComposeGlobal: () =>
getLimiter('diorama:compose:global', {
limit: Math.max(120, Number(process.env.DIORAMA_COMPOSE_GLOBAL_HOURLY) || 600),
window: '1 h',
critical: true,
}).limit('global'),
// CAD Forge (api/cad): a design is up to four LLM completions (write plus
// repair rounds) and as many sandboxed kernel builds on workers/cad-forge, so
// it is the heaviest anonymous action here and capped like the diorama
// composer: per IP plus a global hourly breaker, critical so a Redis outage
// fails closed. Rebuilds (slider moves on an existing design) skip the LLM and
// cost one build, so they get a looser bucket of their own.
cadForgeIp: (ip) =>
getLimiter('cad:forge:ip', { limit: 12, window: '10 m', critical: true }).limit(ip),
cadForgeGlobal: () =>
getLimiter('cad:forge:global', {
limit: Math.max(60, Number(process.env.CAD_FORGE_GLOBAL_HOURLY) || 400),
window: '1 h',
critical: true,
}).limit('global'),
cadRebuildIp: (ip) =>
getLimiter('cad:rebuild:ip', { limit: 90, window: '10 m', critical: true }).limit(ip),
// Anatomy (api/anatomy): one generation streams up to two long Claude
// completions (write plus one repair), so it is capped per IP with a global
// hourly breaker, critical so a Redis outage fails closed. Publishing a spec
// an agent wrote itself costs no model call, only a row, so it gets a looser
// bucket of its own.
anatomyIp: (ip) =>
getLimiter('anatomy:ip', { limit: 12, window: '10 m', critical: true }).limit(ip),
anatomyGlobal: () =>
getLimiter('anatomy:global', {
limit: Math.max(60, Number(process.env.ANATOMY_GLOBAL_HOURLY) || 400),
window: '1 h',
critical: true,
}).limit('global'),
anatomyPublishIp: (ip) =>
getLimiter('anatomy:publish:ip', { limit: 60, window: '10 m', critical: true }).limit(ip),
// Portal (api/portal): fetches a caller-supplied website once and builds a
// walkable world from it. The spend is other people's bandwidth rather than
// ours, which is exactly why it is capped: a build is one origin request plus
// a robots.txt read, and an uncapped endpoint would turn three.ws into a
// crawler someone else pays for. Cached worlds do not reach this limiter, so
// the cap governs distinct pages, not shares of the same link. Non-critical:
// a Redis blip degrades to the per-instance limiter rather than refusing a
// visitor a world we can build for free from cache.
portalBuildIp: (ip) =>
getLimiter('portal:build:ip', { limit: 30, window: '10 m' }).limit(ip),
// Fleet-wide brake, so no distribution of IPs can point Portal at one origin
// hard enough to look like an attack from three.ws.
portalBuildGlobal: () =>
getLimiter('portal:build:global', {
limit: Math.max(200, Number(process.env.PORTAL_BUILD_GLOBAL_HOURLY) || 1200),
window: '1 h',
}).limit('global'),
// GLB export of an already-built world: pure CPU on our side plus a download,
// so it gets its own, smaller cap.
portalExportIp: (ip) =>
getLimiter('portal:export:ip', { limit: 12, window: '10 m' }).limit(ip),
// Diorama save (api/diorama action:save) — persists a forged world to the
// public gallery table. Anonymous write, so cap per IP to stop one caller
// carpeting the gallery; non-critical so an infra hiccup never blocks a save.
dioramaSaveIp: (ip) =>
getLimiter('diorama:save:ip', { limit: 30, window: '10 m' }).limit(ip),
// Diorama scene export (api/diorama action:export) — merges already-forged
// object GLBs + a procedural ground/lights into one GLB via @gltf-transform
// and uploads it to object storage. No LLM/GPU spend, but it does real
// network egress (re-fetching every object GLB) and a storage write, so it
// gets its own moderate per-IP cap; non-critical since a Redis blip should
// degrade, not block, a local export.
dioramaExportIp: (ip) =>
getLimiter('diorama:export:ip', { limit: 20, window: '10 m' }).limit(ip),
// Diorama one-shot build (api/diorama action:build) — the full server-side
// compose → forge every object → export pipeline in a single call, for
// agents/MCP clients with no browser to drive the progressive client flow.
// It runs the same paid LLM completion as compose PLUS N free-lane forges,
// so it shares compose's critical/fail-closed posture and gets a tighter
// per-IP ceiling than compose alone.
dioramaBuildIp: (ip) =>
getLimiter('diorama:build:ip', { limit: 6, window: '10 m', critical: true }).limit(ip),
dioramaBuildGlobal: () =>
getLimiter('diorama:build:global', {
limit: Math.max(40, Number(process.env.DIORAMA_BUILD_GLOBAL_HOURLY) || 200),
window: '1 h',
critical: true,
}).limit('global'),
// x402 Bazaar MCP. Discovery calls fan out to external facilitators, so cap
// per principal to keep that egress bounded without throttling normal use.
mcpBazaar: (key) =>
getLimiter('mcp:bazaar', { limit: 60, window: '1 m', critical: true }).limit(key),
// threews-agent MCP. Read/discovery calls are cheap; pay_and_call moves real
// money, so it gets a much tighter ceiling on top of the per-spend caps.
mcpAgent: (key) =>
getLimiter('mcp:agent', { limit: 60, window: '1 m', critical: true }).limit(key),
mcpAgentPay: (key) =>
getLimiter('mcp:agent:pay', { limit: 20, window: '1 m', critical: true }).limit(key),
// Labor-market write buckets, keyed per user. These had borrowed the MCP agent
// buckets above, which coupled two unrelated surfaces: a user actively using the
// MCP `pay_and_call`/agent tools could exhaust the shared budget and 429 their
// bounty posts (and vice versa). Split out so each surface has its own ceiling.
// · laborPost — posting a bounty escrows real $THREE on-chain, so it's the
// money path: critical (fail closed in prod without Redis). 20/min lets an
// owner post a burst while bounding a runaway client.
// · laborBid — bids move no money (escrow happens at post), so non-critical;
// 60/min mirrors a worker agent placing offers across many open bounties.
laborPost: (userId) =>
getLimiter('labor:post', { limit: 20, window: '1 m', critical: true }).limit(userId),
laborBid: (userId) =>
getLimiter('labor:bid', { limit: 60, window: '1 m' }).limit(userId),
oauthToken: (clientId) =>
getLimiter('oauth:token', { limit: 120, window: '1 m' }).limit(clientId),
// Stud-listing writes (POST /api/genome/stud): an owner toggling one of their
// agents into the public stud market and pricing it in $THREE. Each call is a
// single owner-scoped meta write, so the ceiling only needs to stop a scripted
// flood from churning the market ordering. Non-critical: a Redis outage must
// never lock an owner out of unlisting their own agent.
genomeStudWrite: (userId) =>
getLimiter('genome:stud:write', { limit: 30, window: '1 m' }).limit(userId),
upload: (userId) => getLimiter('upload', { limit: 60, window: '1 h' }).limit(userId),
// Auto-rig submission (api/_lib/auto-rig.js → maybeAutoRigAvatar). Every gate
// lands BEFORE a paid UniRig GPU rerig job is submitted to Replicate / the
// self-host backend, so these are the money path of the auto-rig program — all
// critical (fail closed in prod without Redis, the same posture as
// mcp3dGenerate / videoGenerateUser). The create request itself stays gated
// only by size (enforceQuotas); the spend lives here.
// · rig — per-user hourly burst ceiling on auto-rig submissions (10/h).
// · rigDaily — per-user 24h hard cost cap, independent of the hourly bucket,
// so a user can't drip-feed 10/h around the clock. Env-tunable
// via AUTO_RIG_DAILY_PER_USER (default 20, floored at 5).
// · rigGlobal — platform-wide hourly circuit breaker on the shared GPU budget,
// keyed 'global' (mirrors mcp3dGenerateGlobal). Env-tunable via
// AUTO_RIG_GLOBAL_HOURLY (default 300, floored at 60).
rig: (userId) => getLimiter('rig', { limit: 10, window: '1 h', critical: true }).limit(userId),
rigDaily: (userId) =>
getLimiter('rig:daily', {
limit: Math.max(5, Number(process.env.AUTO_RIG_DAILY_PER_USER) || 20),
window: '1 d',
critical: true,
}).limit(userId),
rigGlobal: () =>
getLimiter('rig:global', {
limit: Math.max(60, Number(process.env.AUTO_RIG_GLOBAL_HOURLY) || 300),
window: '1 h',
critical: true,
}).limit('global'),
avatarPatch: (userId) => getLimiter('avatar:patch', { limit: 20, window: '1 h' }).limit(userId),
// Attaching an avatar to an agent (api/onboarding/link-avatar). Onboarding
// links once and reassignment is rare, so this is generous for real use while
// bounding a script that churns an agent's body. Its own bucket rather than
// avatarPatch's: editing avatar metadata must not exhaust the link budget.
avatarLink: (userId) => getLimiter('avatar:link', { limit: 30, window: '1 h' }).limit(userId),
prefsWrite: (userId) => getLimiter('prefs:write', { limit: 30, window: '1 h' }).limit(userId),
// Walk snapshot upserts (api/walk/session.js). Sized from the client's real
// cadence rather than the generic prefs budget: src/walk-session.js saves on a
// 30s heartbeat (120/h) plus debounced writes on interactive changes, so a
// 30/h ceiling silenced cross-device sync ~15 minutes into a walk. Keyed by
// userId so one office NAT can't collapse every walker into one bucket.
walkSessionWrite: (userId) =>
getLimiter('walk:session:write', { limit: 240, window: '1 h' }).limit(userId),
// Claiming a reputation-unlocked cosmetic onto an agent (api/agents/:id/unlocks).
// A low-frequency owner action; this just bounds abusive retries.
unlockClaim: (userId) => getLimiter('unlock:claim', { limit: 40, window: '1 h' }).limit(userId),
// Per-user budget for the embeddings endpoint (api/agents/:id/embed — free
// NVIDIA NIM lane first, paid Voyage fallback). Keyed by userId (not IP) so
// the shared platform keys/quotas can't be drained by one account rotating
// IPs. recall() embeds one query at a time, so a generous per-minute
// ceiling still leaves headroom for interactive memory search.
embedUser: (userId) => getLimiter('embed:user', { limit: 120, window: '1 m' }).limit(userId),
// Token-gated 3D embeds (api/embed/gate-create.js, api/embed/gate-verify.js).
// Create is an authenticated, low-frequency creator action — bound to stop a
// compromised session from spraying gates. Verify is called by anonymous
// visitors and drives a real Solana RPC read + signature check per attempt,
// so it gets both a per-IP flood guard AND a per-wallet ceiling (the wallet
// bucket is the one that actually matters — a distributed-IP attacker still
// can't brute-force past a single wallet's budget without also owning it).
embedGateCreateIp: (ip) => getLimiter('embed:gate:create:ip', { limit: 20, window: '10 m' }).limit(ip),
embedGateVerifyIp: (ip) => getLimiter('embed:gate:verify:ip', { limit: 30, window: '5 m' }).limit(ip),
embedGateVerifyWallet: (addr) =>
getLimiter('embed:gate:verify:wallet', { limit: 10, window: '5 m' }).limit(addr),
// Token-gated scene shares (api/scene/gate-check.js). Same anonymous-visitor
// shape as the embed gate above, so it gets the same pairing: a per-IP flood
// guard plus the per-wallet ceiling that a distributed-IP attacker cannot
// rotate around. Its own buckets rather than the embed ones so a busy embed
// does not lock a scene visitor out (and vice versa). The IP bucket is looser
// than the wallet bucket because one visitor spends two calls (nonce, then
// signature) per attempt and may legitimately switch wallets.
sceneGateCheckIp: (ip) => getLimiter('scene:gate:check:ip', { limit: 30, window: '5 m' }).limit(ip),
sceneGateCheckWallet: (addr) =>
getLimiter('scene:gate:check:wallet', { limit: 10, window: '5 m' }).limit(addr),
avatarRollback: (userId) =>
getLimiter('avatar:rollback', { limit: 10, window: '1 h' }).limit(userId),
// Chat inference spends real money on the host's LLM keys, so these are
// critical: a Redis outage in prod fails closed (deny) rather than handing out
// unbounded paid inference. chatUser/chatIp bound a single account/IP.
chatUser: (userId) =>
getLimiter('chat:user', { limit: 40, window: '1 m', critical: true }).limit(userId),
chatIp: (ip) => getLimiter('chat:ip', { limit: 60, window: '1 m', critical: true }).limit(ip),
// Embeddable concierge widget (/api/concierge) — anonymous, any-origin
// traffic from third-party sites, so it gets its own bucket instead of
// sharing chat:ip: a widget-hosting page must not starve the signed-in
// viewer chat (and vice versa). Same critical fail-closed policy: this lane
// spends free-tier LLM quota and can fall through to funded rungs.
conciergeIp: (ip) =>
getLimiter('concierge:ip', { limit: 20, window: '1 m', critical: true }).limit(ip),
// Global ceiling across every embedded widget combined — bounds the total
// free-tier draw of the whole third-party fleet, mirroring chatHostKeyGlobal.
conciergeGlobal: () =>
getLimiter('concierge:global', { limit: 600, window: '1 m', critical: true }).limit('global'),
// Global ceiling on inference billed to the HOST's provider keys (i.e. callers
// who supplied no key of their own). Stops distributed abuse — many accounts
// each under their per-user limit collectively draining the platform's quota.
chatHostKeyGlobal: () =>
getLimiter('chat:hostkey:global', { limit: 1200, window: '1 m', critical: true }).limit(
'global',
),
// AI bounty judge (api/bounties/:id/judge). Each run spends real LLM tokens
// scoring a whole field of submissions, so cap per poster and fail closed
// without Redis in prod rather than allowing unbounded paid inference.
bountyJudge: (userId) =>
getLimiter('bounty:judge:user', { limit: 30, window: '1 h', critical: true }).limit(userId),
// Agent action-log append (api/agent-actions POST). Append-only, never-deleted
// table, so cap per user to prevent unbounded storage growth from a script.
agentActionAppend: (userId) =>
getLimiter('agent:action:append', { limit: 120, window: '1 m' }).limit(userId),
// Bounty creation + submission. Both are authenticated writes to public,
// everyone-reads tables, so cap per user to stop one account scripting spam
// that pollutes the feed and bloats storage.
bountyCreate: (userId) =>
getLimiter('bounty:create', { limit: 15, window: '1 h' }).limit(userId),
bountySubmit: (userId) =>
getLimiter('bounty:submit', { limit: 40, window: '1 h' }).limit(userId),
// Agent Spotlight (api/spotlight/[action].js). Writing a showcase entry is a
// considered act (a builder does it once per agent and edits it a few times),
// so the create bucket is deliberately tight. Voting is a browse-time
// gesture down a long page, so it gets a much wider one; both are keyed on
// the user id, because the abuse this guards against is one account
// astroturfing the ranking, not one office sharing an IP.
showcaseWrite: (userId) =>
getLimiter('showcase:write', { limit: 20, window: '1 h' }).limit(userId),
showcaseVote: (userId) =>
getLimiter('showcase:vote', { limit: 120, window: '10 m' }).limit(userId),
// Direct messages between friends — its own bucket so DM spam can't starve
// world-chat posting and vice versa. Mirrors world chat's order of magnitude.
dmSend: (userId) => getLimiter('dm:send', { limit: 30, window: '1 m' }).limit(userId),
// Demo /api/x402-pay — agent wallet pays real USDC per call, so we keep the
// per-IP burst small (6/min ≈ $0.006/min) and rely on the agent wallet
// balance as the global ceiling.
x402PayIp: (ip) => getLimiter('x402:pay:ip', { limit: 6, window: '1 m' }).limit(ip),
x402PayGlobal: () =>
getLimiter('x402:pay:global', { limit: 600, window: '1 h', critical: true }).limit(
'global',
),
// x402 checkout analytics record (api/x402-checkout-record). Public + write,
// so bound per-IP to stop an attacker scripting fabricated revenue rows.
x402RecordIp: (ip) => getLimiter('x402:record:ip', { limit: 30, window: '1 m' }).limit(ip),
// Generic paid x402 endpoints (paidEndpoint(), incl. the ~4.4k-URL datapoint
// fabric). Two tiers:
// • probe — every anonymous request (price-discovery 402 + paid retry).
// Generous + NON-critical so a Redis outage never blocks discovery or a
// legitimate paid call; authenticated/subscription callers skip it entirely
// (they have their own access-control gating). Pure anonymous-flood guard.
// • verify — only requests carrying an X-PAYMENT header reach the facilitator
// /verify round-trip. Without this, one cheap inbound request amplifies into
// one outbound facilitator call at our expense (cost/DDoS vector). Bounded
// per-IP AND a global circuit breaker, both CRITICAL (fail closed in prod):
// during a Redis outage, rejecting a payment retry (buyer keeps funds and
// retries) beats letting the amplification run unbounded.
//
// The per-IP verify bucket is FAILURE-WEIGHTED, not attempt-weighted. Metering
// every attempt equally capped a *paying* client at 20 calls/min, which is
// incoherent for a per-datapoint API whose whole value is bulk reads: a buyer
// pulling 50 metrics got 429s despite paying for every one. The amplification
// vector is a junk X-PAYMENT flood, and junk payments FAIL verify. So a
// successful (settled) verify costs 1 token, while a failed verify costs
// X402_VERIFY_FAIL_PENALTY (default 15) via x402VerifyPenalty(). At 300/min a
// legitimate payer gets 300 paid calls/min, while a pure junk flood drains the
// bucket after ~20 failures/min, the same bound as the old flat cap, still
// enforced by the pre-verify gate BEFORE any facilitator call is made.
x402ProbeIp: (ip) =>
getLimiter('x402:probe:ip', { limit: X402_PROBE_IP_PER_MIN, window: '1 m' }).limit(ip),
x402VerifyIp: (ip) =>
getLimiter('x402:verify:ip', {
limit: X402_VERIFY_IP_PER_MIN,
window: '1 m',
critical: true,
}).limit(ip),
// Burn the extra tokens that make a failed verify expensive. Called ONLY on the
// verify-failure path; the one token for the attempt itself was already spent by
// x402VerifyIp() at the pre-verify gate. Best-effort: a limiter fault here must
// never convert a payment error into a 500, so it swallows its own errors.
x402VerifyPenalty: async (ip) => {
const extra = Math.max(0, X402_VERIFY_FAIL_PENALTY - 1);
if (!extra) return;
const bucket = getLimiter('x402:verify:ip', {
limit: X402_VERIFY_IP_PER_MIN,
window: '1 m',
critical: true,
});
try {
await Promise.all(Array.from({ length: extra }, () => bucket.limit(ip)));
} catch {
/* penalty is best-effort; the pre-verify gate is the hard bound */
}
},
x402VerifyGlobal: () =>
getLimiter('x402:verify:global', {
limit: X402_VERIFY_GLOBAL_PER_HOUR,
window: '1 h',
critical: true,
}).limit('global'),
// OUR self-hosted facilitator (api/x402-facilitator/verify+settle). Its public
// URL means anyone with a few cents of USDC can spam /settle with valid tiny
// allowlisted transfers, each forcing a sponsor co-sign that burns ~5000
// lamports — a fee-burn grief that can pause the paid economy at the SOL floor.
// Per-IP is generous (60/min, NOT the tighter 20/min verify cap): legit settle
// traffic loops back through the platform's own egress IP via callFacilitator,
// so a small cap here would self-DoS; 60/min still bounds a single direct
// attacker IP. CRITICAL like verify — fail closed, since rejecting a settle just
// leaves the buyer holding funds to retry, which beats unbounded fee burn.
x402FacilitatorIp: (ip) =>
getLimiter('x402:facilitator:ip', {
limit: X402_FACILITATOR_IP_PER_MIN,
window: '1 m',
critical: true,
}).limit(ip),
x402FacilitatorGlobal: () =>
getLimiter('x402:facilitator:global', {
limit: X402_FACILITATOR_GLOBAL_PER_HOUR,
window: '1 h',
critical: true,
}).limit('global'),
checkName: (ip) => getLimiter('check-name:ip', { limit: 60, window: '1 m' }).limit(ip),
ensResolve: (ip) => getLimiter('ens:resolve:ip', { limit: 60, window: '1 m' }).limit(ip),
snsResolve: (ip) => getLimiter('sns:resolve:ip', { limit: 60, window: '1 m' }).limit(ip),
// Generic public read endpoints (explore, showcase, public agent fetch).
// local: high-frequency public reads with no side effects — the only job is
// flood protection, and a per-instance cap bounds one IP's throughput just as
// well without spending a Redis command per page view.
//
// 240/min, NOT 60. At 60 this bucket was a self-DoS: ~166 endpoints share it,
// and real pages fan out to many of them in one load — the agent profile fires
// 7-8 (duplicated /reputation + /solana/networth), /crypto fires 5, oracle's
// /activity fires 5 and re-polls all 5 every 90s, galaxy polls 2 every 6s. A
// user opening two tabs burned the minute budget and 429'd their own page. Since
// this is a `local` in-memory guard (no Redis cost) and every endpoint behind it
// is an edge-cached side-effect-free read, a higher ceiling costs nothing and
// still stops a scripted flood. Page-load-critical clusters additionally get
// their own dedicated buckets below so one surface can never starve another.
publicIp: (ip) => getLimiter('public:ip', { limit: 240, window: '1 m', local: true }).limit(ip),
// /api/avatar-stream with a remote ?src: one download (up to 64 MB) and one
// CPU-bound pack per distinct URL, so it is held well under publicIp.
avatarStreamRemoteIp: (ip) => getLimiter('avatar-stream:remote:ip', { limit: 20, window: '1 m' }).limit(ip),
// Fiat onramp checkout links (/api/onramp/link). Unlike the generic public read,
// each configured call mints a single-use session token against Coinbase's CDP
// API, so an unauthenticated flood here is upstream quota burn, not just our CPU.
// 20 per 5 min per IP covers a user reopening the Add funds overlay and switching
// between USDC and SOL several times, and nothing legitimate needs more.
onrampLinkIp: (ip) =>
getLimiter('onramp:link:ip', { limit: 20, window: '5 m', local: true }).limit(ip),
// /irl coordinate reads (pins nearby, drops nearby, world-lines nearby). These
// are the only public reads that reveal WHERE another user placed something, so
// their ceiling is a privacy budget, not a flood guard, and it must not drift
// with the generic read bucket: when publicIp was raised 60 -> 240 for unrelated
// page-load fan-out, the /irl grid-sweep cost quietly dropped 4x (the H7 threat
// model still documented 60). A dedicated bucket pins the number to the surface
// it protects. 60/min against a legit viewer's ~6/min (a 10s nearby poll) leaves
// 10x headroom, and no page fans out to more than one of these at a time.
// local: an in-memory bucket never throws on a Redis outage, which is what lets
// the callers fail CLOSED on it without inventing an availability risk.
// See docs/irl/THREAT-MODEL.md.
irlNearbyIp: (ip) => getLimiter('irl:nearby:ip', { limit: 60, window: '1 m', local: true }).limit(ip),
// Agent profile reads (networth, patronage, achievements, reputation, tiers).
// One profile view fans out to 7-8 of these; isolate them so opening a few
// profiles can't drain the budget shared with markets/home/oracle surfaces.
agentProfileIp: (ip) =>
getLimiter('agent-profile:ip', { limit: 240, window: '1 m', local: true }).limit(ip),
// Market/DeFi/crypto dashboards (api/coin/*, api/defi/*, api/crypto/*). Every
// one is an edge-cached upstream mirror, and the dashboards fan out 3-5 per load
// (/crypto probes 5; /coins polls liquidations every 30s; /gas every 15s).
marketDataIp: (ip) =>
getLimiter('market-data:ip', { limit: 240, window: '1 m', local: true }).limit(ip),
// Galaxy visualiser (/api/galaxy, /api/galaxy/flows). The only continuous
// high-frequency drain on the platform: a 6s delta poll on the galaxy page plus
// a 12s economy-ticker poll on home. Needs its own headroom or an idle galaxy
// tab slowly starves every other public read in the same browser.
galaxyIp: (ip) => getLimiter('galaxy:ip', { limit: 300, window: '1 m', local: true }).limit(ip),
// Lobby-critical market feeds (/api/pump/trending, /api/pump/search). These
// render the /play lobby on every page load, sit behind a 30s server cache +
// stale fallback (so the upstream cost of a burst is near zero), and MUST NOT
// share the generic `publicIp` bucket: ~166 endpoints drain that one 60/min
// pool, so a browser with a few three.ws tabs open starves its own lobby and
// /play dead-ends on a 429 it did nothing to earn (same failure mode that
// moved /api/play/nonce to its own bucket — see playNonceIp below). local:
// per-instance flood guard is all a cached read needs.
marketFeedIp: (ip) =>
getLimiter('market-feed:ip', { limit: 120, window: '1 m', local: true }).limit(ip),
// Free x402 developer toolkit (echo / debug / verify-receipt). Free ≠
// abusable: these decode caller-supplied payment envelopes and recompute
// hashes, so 30/min per IP is generous for a developer iterating on their
// integration while bounding a script that hammers the decode path.
x402DevToolIp: (ip) => getLimiter('x402-dev-tool:ip', { limit: 30, window: '1 m' }).limit(ip),
// Client-side error report ingestion (api/client-errors). The browser
// reporter batches and caps itself at 25 events/page, so legitimate traffic
// is a handful of requests per pageview even on a broken page; 30/min per
// IP absorbs that while keeping log-flooding abuse bounded.
// local: bounding a log flood is exactly what a per-instance cap is for —
// spending a distributed Redis command to record that an error was reported is
// pure quota burn, and it lands hardest precisely when the site is already broken.
clientErrorsIp: (ip) =>
getLimiter('client-errors:ip', { limit: 30, window: '1 m', local: true }).limit(ip),
// Publishing a /play build to a coin's featured surface (R20). Each write stores
// a screenshot in Redis, so cap the burst per IP to keep that bounded; reads use
// the generic publicIp bucket.
buildPublishIp: (ip) => getLimiter('build:publish:ip', { limit: 10, window: '10 m' }).limit(ip),
// /play sign-in nonce (GET /api/play/nonce). Hit on every /play page load — and
// again on each sign-in attempt — to read the gate config + mint a self-verifying
// HMAC nonce. It has NO side effects and NO cost (no RPC, no DB), so it must NOT
// borrow the strict credential `authIp` bucket (30/10m, shared with login/register/
// trading): a shared office/NAT, a burst of players, or a couple of reloads would
// exhaust that and 429 the gate on what is almost always an open game. The real
// abuse surface is /verify (ed25519 signature + RPC balance read), which keeps
// `authIp`. local: a per-instance flood guard is all this needs — like publicIp /
// tokenPriceIp — and it spends zero Redis commands on a high-traffic page-load path.
playNonceIp: (ip) =>
getLimiter('play:nonce:ip', { limit: 120, window: '1 m', local: true }).limit(ip),
// Browser Solana JSON-RPC proxy (api/solana-rpc). Forwards to the keyed
// upstream (Helius), so cap per-IP burst to keep the studio launch panel
// responsive while preventing anonymous quota drain, plus a global hourly
// ceiling as a hard cost cap independent of any one client.
solanaRpcIp: (ip) => getLimiter('solana-rpc:ip', { limit: 120, window: '1 m' }).limit(ip),
solanaRpcGlobal: () =>
getLimiter('solana-rpc:global', { limit: 12000, window: '1 h' }).limit('global'),
// Browser EVM JSON-RPC proxy (api/evm-rpc). Same shape as the Solana proxy:
// the chain may front a keyed Alchemy upstream, so cap per-IP burst and add a
// global hourly ceiling as the hard cost cap.
evmRpcIp: (ip) => getLimiter('evm-rpc:ip', { limit: 120, window: '1 m' }).limit(ip),
evmRpcGlobal: () =>
getLimiter('evm-rpc:global', { limit: 12000, window: '1 h' }).limit('global'),
// Helius DAS / enhanced-API endpoints (nft/resolve getAsset, tx/explain
// enhanced-tx, live holder cohorts getTokenAccounts). DAS is billed at a far
// higher credit multiplier than plain RPC, and these are public. Per-endpoint
// caches collapse repeat hits on the same key; this shared global hourly
// ceiling is the hard cost cap against a bot enumerating many DISTINCT keys
// (which caching can't stop). One bucket across all DAS endpoints.
heliusDasGlobal: () =>
getLimiter('helius-das:global', { limit: 3000, window: '1 h' }).limit('global'),
// Per-IP share of that ceiling for /api/crypto/holders, whose keyed walk is
// up to five DAS pages. Without it one scraper (3,500 reads/h from a single
// IP, 2026-10-10) spent the whole Helius plan; past it the caller still gets
// a real answer from the keyless lane.
cryptoHoldersHeliusIp: (ip) =>
getLimiter('crypto-holders:helius:ip', { limit: 30, window: '1 h' }).limit(ip),
// The holders read costs three RPC calls even on the keyless lane, against
// free nodes the whole platform shares, so it gets a tighter per-IP burst
// than the family's 60/min.
cryptoHoldersIp: (ip) => getLimiter('crypto-holders:ip', { limit: 20, window: '1 m' }).limit(ip),
// /api/crypto/linkage walks each address's recent history (a signatures page
// plus up to DEFAULT_SIGNATURE_LIMIT parsed-transaction fetches) against the
// shared Solana RPC lanes, so it gets its own tighter-than-the-family burst
// plus a global hourly ceiling, the same shape as the holders family above.
cryptoLinkageIp: (ip) => getLimiter('crypto-linkage:ip', { limit: 10, window: '1 m' }).limit(ip),
cryptoLinkageGlobal: () => getLimiter('crypto-linkage:global', { limit: 600, window: '1 h' }).limit('global'),
// Free Crypto Data API family (api/crypto/*). Keyless, no-account reads an agent
// makes mid-task (wallet portfolio, token snapshots). Some paths fan out to the
// keyed Helius/public-RPC upstreams, so a generous-but-bounded per-IP burst keeps
// interactive use snappy while a shared global hourly ceiling is the hard cost cap
// against one caller (or many) draining the upstream quota. One bucket for the family.
cryptoDataIp: (ip) => getLimiter('crypto-data:ip', { limit: 60, window: '1 m' }).limit(ip),
cryptoDataGlobal: () =>
getLimiter('crypto-data:global', { limit: 6000, window: '1 h' }).limit('global'),
// Agent-to-agent economy demo (api/agent-economy/transact). Each call can send
// a tiny real SOL payment from the server wallet, so cap per-IP and add a
// global daily ceiling as a hard spend cap independent of wallet balance.
// The global bucket is only consumed when a payment actually fires.
agentEconomyIp: (ip) => getLimiter('agent-economy:ip', { limit: 10, window: '1 h' }).limit(ip),
agentEconomyGlobal: () =>
getLimiter('agent-economy:global', { limit: 500, window: '1 d' }).limit('global'),
// IBM watsonx.ai Granite embeddings (api/watsonx/embed). Each call bills real
// watsonx inference against the server key, so keep the per-IP burst small and
// add a global hourly ceiling as a hard cost cap independent of any one client.
watsonxEmbedIp: (ip) => getLimiter('watsonx:embed:ip', { limit: 20, window: '1 m' }).limit(ip),
watsonxEmbedGlobal: () =>
getLimiter('watsonx:embed:global', { limit: 600, window: '1 h' }).limit('global'),
// IBM Granite Guardian governance (api/guardian/assess). Each request fans out
// to one Granite Guardian classifier pass per risk against the server watsonx
// key, so cap the per-IP burst and keep a global hourly ceiling as a cost cap.
guardianIp: (ip) => getLimiter('guardian:ip', { limit: 30, window: '1 m' }).limit(ip),
guardianGlobal: () =>
getLimiter('guardian:global', { limit: 1200, window: '1 h' }).limit('global'),
// Granite identity-integrity check (api/agents/identity-check). Each call does
// one Granite embedding + a fan-out of Guardian passes against the server key,
// so keep the per-IP burst tight and add a global hourly ceiling as a cost cap.
identityCheckIp: (ip) =>
getLimiter('identity-check:ip', { limit: 20, window: '1 m' }).limit(ip),
identityCheckGlobal: () =>
getLimiter('identity-check:global', { limit: 600, window: '1 h' }).limit('global'),
// Skills marketplace browse — isolated bucket so traffic on other public endpoints
// can't starve the skills list. 60/min per IP.
skillsBrowse: (ip) => getLimiter('skills:browse', { limit: 60, window: '1 m' }).limit(ip),
// Plugin manifest import (POST /api/plugins/import). Every call makes the
// server fetch a caller-supplied URL, so this is the one plugin lane that can
// be turned into an egress amplifier: 600/min (the generic browse ceiling) is
// 600 outbound requests a minute per IP pointed wherever the caller likes.
// 20 per 5 min is more imports than any human performs and still lets a
// developer iterate on a manifest they are debugging.
pluginImportIp: (ip) =>
getLimiter('plugin:import:ip', { limit: 20, window: '5 m' }).limit(ip),
// Plugin publish (POST /api/plugins/publish). Keyed on the authenticated user
// rather than the IP because the row it writes is owned by that account.
// Re-publishing the same identifier is an upsert, so the ceiling only bounds
// how many DISTINCT plugin rows one account can create per hour.
pluginPublishUser: (userId) =>
getLimiter('plugin:publish:user', { limit: 30, window: '1 h' }).limit(userId),
// Install-counter dedupe (POST /api/plugins/:id/install), same shape as
// avatarViewIp: one counted install per (IP, plugin) per 30 minutes so a user
// who reinstalls a plugin four times moves install_count by one. NOT local:
// a per-instance counter would let the same caller count once per warm Cloud
// Run instance, which is exactly the inflation this bucket exists to stop.
pluginInstallDedupe: (ipAndPlugin) =>
getLimiter('plugin:install:dedupe', { limit: 1, window: '30 m' }).limit(ipAndPlugin),
// Marketplace agent preview chat — anonymous "try before fork" flow on the
// agent detail page. Strict per-IP and per-agent caps so one client can't
// drain LLM credits and one agent can't starve the global pool.
previewIp: (ip) => getLimiter('preview:ip', { limit: 30, window: '1 h' }).limit(ip),
previewAgent: (agentId) =>
getLimiter('preview:agent', { limit: 200, window: '1 h' }).limit(agentId),
widgetWrite: (userId) => getLimiter('widget:write', { limit: 60, window: '1 m' }).limit(userId),
// Specialist teams: creating/editing a team provisions agents (write), and a
// role run fans out to RPC, the intel store and the trade engine (run).
teamWrite: (userId) => getLimiter('team:write', { limit: 20, window: '1 h' }).limit(userId),
teamRun: (userId) => getLimiter('team:run', { limit: 60, window: '10 m' }).limit(userId),
// local: embedded-widget read fetch — flood protection only, no side effects.
// Widgets on third-party pages poll continuously, so a Redis command per read
// at 600/min is pure burn; a per-instance cap bounds throughput just as well.
widgetRead: (ip) =>
getLimiter('widget:read', { limit: 600, window: '1 m', local: true }).limit(ip),
// Per-widget visitor chat. Limit is dynamic — one bucket per (widgetId, perMinute).
widgetChat: ({ ip, widgetId, perMinute }) =>
getLimiter('widget:chat', {
limit: Math.max(1, Math.min(60, perMinute || 8)),
window: '1 m',
}).limit(`${widgetId}:${ip}`),
// We-pay LLM proxy: 60 req/min per IP (global floor), and per-agent dynamic bucket.
// Critical: this lane spends the host's own provider keys, so a Redis outage
// must degrade to the Postgres-backed counter rather than to no counter at all.
embedLlmIp: (ip) =>
getLimiter('embed:llm:ip', { limit: 60, window: '1 m', critical: true }).limit(ip),
embedLlmAgent: (agentId, perMin) =>
getLimiter('embed:llm:agent', {
limit: Math.max(1, Math.min(1000, perMin || 10)),
window: '1 m',
}).limit(agentId),
// Autonomous agent skill purchases: 10 per hour per buyer agent to prevent runaway spending.
// Critical (moves real money) — fail closed in prod without Redis.
agentBuy: (agentId) =>
getLimiter('agent:buy', { limit: 10, window: '1 h', critical: true }).limit(agentId),
// Gas-spending endpoints: 10 redeems per 5 minutes per IP
strict: (key) =>
getLimiter('permissions:redeem:strict', { limit: 10, window: '5 m' }).limit(key),
pinUser: (userId) => getLimiter('pin:user', { limit: 30, window: '1 h' }).limit(userId),
// local: pin-status poll — read-only progress check, flood guard only. The
// pin UI polls this on an interval, so a per-instance cap saves a Redis
// command per poll without weakening the throughput bound.
pinStatusIp: (ip) =>
getLimiter('pin:status:ip', { limit: 60, window: '1 m', local: true }).limit(ip),
agentByAddress: (ip) =>
getLimiter('agents:by-address', { limit: 120, window: '1 m' }).limit(ip),
pricingPerIp: (ip) => getLimiter('pricing:ip', { limit: 120, window: '1 m' }).limit(ip),
walletLink: (userId) => getLimiter('wallet:link', { limit: 10, window: '10 m' }).limit(userId),
// Agent wallet read endpoints (GET balance, activity). Per authenticated user.
// `local`: a read guard on wallet balance/holdings views (33 call sites, polled by
// open dashboards). Reads move no funds — the send/withdraw/trade paths keep their
// own distributed `critical` buckets.
walletRead: (userId) => getLimiter('wallet:read', { limit: 60, window: '1 m', local: true }).limit(userId),
// Assisted candidate scan (api/trading/scan.js). One call can cost six live
// on-chain quotes plus six firewall simulations, so the generic authed-read
// IP bucket (300 per 5 min) is far too loose to sit alone in front of it.
// Owner-scoped ceiling: the UI button is single-flight and the brain caches
// its context scan for 60s, so a real owner never approaches this.
tradingScan: (userId) => getLimiter('trading:scan', { limit: 30, window: '5 m', local: true }).limit(userId),
// Public cross-origin wallet embed card (GET /api/agents/wallet-embed). Served
// CORS:* so a stranger's blog can mount the wallet chip — keyed per IP and
// generous (a page with several embeds hydrates them all on load) but bounded
// so the open endpoint can't be turned into a free balance-scraping relay. Reads
// are short-TTL cached, so this only gates cache-miss origin hits.
walletEmbedIp: (ip) => getLimiter('wallet:embed:ip', { limit: 120, window: '1 m' }).limit(ip),
agentSuggest: (ip) => getLimiter('agents:suggest', { limit: 120, window: '1 m' }).limit(ip),
// Signed-out "describe it, we build it" generation in the create-agent wizard.
// The try-first flow lets anyone generate a spec before making an account, so
// this hits the paid LLM chain with no user identity behind it — keyed per IP
// and deliberately tight (enough to explore a few ideas and tweak, not enough
// to turn the open endpoint into a free generation relay). The global daily
// spend cap in api/_lib/llm.js is the second line of defence.
agentSuggestAnon: (ip) => getLimiter('agents:suggest:anon', { limit: 10, window: '1 h' }).limit(ip),
// On-chain agent registration (register_agent MCP tool). Each call may mint a
// Core asset + Agent Identity PDA — real SOL spend — so this is deliberately
// tight, keyed per authenticated user.
agentRegister: (userId) =>
getLimiter('agent:register', { limit: 12, window: '1 h' }).limit(userId),
read: (ip) => getLimiter('permissions:read', { limit: 300, window: '1 m' }).limit(ip),
permissionsGrant: (userId) =>
getLimiter('permissions:grant', { limit: 10, window: '1 h' }).limit(userId),
permissionsRevoke: (userId) =>
getLimiter('permissions:revoke', { limit: 20, window: '1 h' }).limit(userId),
// Developer API keys (api/keys). Minting is the expensive, abusable action, so
// it keeps the tight hourly bucket. Listing and revoking get their own buckets
// on purpose: when all three shared one, the dashboard's list-on-load plus
// list-after-every-mutation could burn the 30/h budget and then refuse the
// revoke, locking an owner out of killing a leaked key. A safety valve must
// never be throttled by the thing it protects against.
apiKeyManage: (userId) =>
getLimiter('api-key:manage', { limit: 30, window: '1 h' }).limit(userId),
apiKeyList: (userId) =>
getLimiter('api-key:list', { limit: 120, window: '1 m', local: true }).limit(userId),
apiKeyRevoke: (userId) =>
getLimiter('api-key:revoke', { limit: 60, window: '1 h' }).limit(userId),
// Unified API gateway (/api/v1/*). One bucket fronts every versioned endpoint,
// keyed per principal — API key id when present, else user id, else IP — so a
// single key's burst is bounded without one caller starving another. 120/min
// is generous for an interactive integration while capping scripted floods;
// individual capability handlers add their own tighter ceilings on top when
// they fan out to a metered upstream (e.g. the shared aixbt key).
apiV1: (key) => getLimiter('api:v1', { limit: 120, window: '1 m' }).limit(key),
// Event Markets writes (picks, withdrawals, admin edits). A forecaster changes
// a pick a handful of times before lock; 30 per 5 minutes per account and 60
// per IP stop a script without touching a person reconsidering.
eventMarketWriteUser: (userId) =>
getLimiter('event-markets:write:user', { limit: 30, window: '5 m', critical: true }).limit(userId),
eventMarketWriteIp: (ip) =>
getLimiter('event-markets:write:ip', { limit: 60, window: '5 m', critical: true }).limit(ip),
// Auth-critical (see authIp/registerIp above): brute-forcing verification
// codes / spamming reset+verify emails must fail closed when Redis is down.
verifyEmailIp: (ip) =>
getLimiter('verify-email:ip', { limit: 10, window: '15 m', critical: true }).limit(ip),
// Per account as well as per IP: a code lives 30 minutes, so this bounds
// the guesses any one pending code can take to ~20 however many IPs try.
verifyEmailUser: (userId) =>
getLimiter('verify-email:user', { limit: 10, window: '15 m', critical: true }).limit(userId),
// Reset mail goes only to registered addresses, but the per-email bucket
// alone lets one client walk a list of them; this caps the sender.
forgotPasswordIp: (ip) =>
getLimiter('forgot-password:ip', { limit: 10, window: '15 m', critical: true }).limit(ip),
forgotPasswordEmail: (email) =>
getLimiter('forgot-password:email', { limit: 3, window: '15 m', critical: true }).limit(
email,
),
resendVerifyUser: (userId) =>
getLimiter('resend-verify:user', { limit: 2, window: '10 m', critical: true }).limit(
userId,
),
newsletterIp: (ip) => getLimiter('newsletter:ip', { limit: 5, window: '1 h' }).limit(ip),
// Voice cloning: expensive ElevenLabs API call — 3 per user per day.
// Critical (real per-call cost) — fail closed in prod without Redis.
voiceClone: (userId) =>
getLimiter('voice:clone', { limit: 3, window: '1 d', critical: true }).limit(userId),
// Persona extraction (POST /api/persona/extract): a metered completion on the
// shared LLM chain, 5 per user per day. Critical for the same reason its
// sibling personaPreviewUser is: a non-critical bucket degrades to a
// PER-INSTANCE memory counter, so on a Redis outage the daily budget is
// silently multiplied by the live Cloud Run instance count and a free-signup
// loop can spend past it. This is the tighter of the two persona budgets, so
// it fails closed rather than open.
personaExtract: (userId) =>
getLimiter('persona:extract', { limit: 5, window: '1 d', critical: true }).limit(userId),
// Onboarding interview (POST /api/persona/interview) in the create-agent
// wizard. Same try-first shape as agentSuggest: signed-in callers get room to
// re-run the interview while they tune their answers, signed-out callers get a
// tight per-IP budget because the call hits the shared LLM chain with no user
// attribution behind it. Keyed per IP in both cases (the wizard is one browser
// per build) with the global daily spend cap in api/_lib/llm.js behind it.
personaInterview: (ip) => getLimiter('persona:interview', { limit: 30, window: '1 h' }).limit(ip),
personaInterviewAnon: (ip) =>
getLimiter('persona:interview:anon', { limit: 8, window: '1 h' }).limit(ip),
// Persona preview: a metered completion on the shared LLM chain (api/_lib/llm.js),
// same as extract, not a fixed Claude-only lane. Looser than extract (it's
// interactive) but still per-user critical so a free-signup loop can't run up an
// unbounded LLM bill. Anonymous shouldn't reach it (auth required), so per-user.
personaPreviewUser: (userId) =>
getLimiter('persona:preview:user', { limit: 30, window: '1 h', critical: true }).limit(userId),
// Oracle social ingestion: unauthenticated, state-mutating write into the
// narrative virality/conviction scorer (up to 500 tweets/call). Tight per-IP cap
// so it can't be driven for narrative manipulation. (Replaces a mis-wired limiter
// that referenced an undefined bucket and dead-429'd the endpoint.)
oracleSocialIp: (ip) =>
getLimiter('oracle:social:ip', { limit: 20, window: '5 m' }).limit(ip),
// Forever/inscribe: creates a real OrdinalsBot order against the platform's API
// key. Per-IP so the platform's key/quota can't be scripted. Critical — a Redis
// outage should fail closed rather than uncap third-party order creation.
inscribeIp: (ip) =>
getLimiter('inscribe:ip', { limit: 10, window: '10 m', critical: true }).limit(ip),
// Forever/status: proxies OrdinalsBot's order lookup, also metered against the
// platform's key. The pay screen polls every 6s while the user waits on a
// Bitcoin confirmation, so the ceiling clears a long wait in a couple of tabs
// (50 polls per tab per 5 min) and still caps an anonymous scripted drain.
// Not critical: a Redis outage must never freeze a paying user's pay screen.
inscribeStatusIp: (ip) =>
getLimiter('inscribe:status:ip', { limit: 200, window: '5 m' }).limit(ip),
// IBM attest submit: broadcasts a fee-paying on-chain tx from the shared attester
// wallet. Per-attester-pubkey daily ceiling so concurrent calls can't drain the
// wallet's SOL via fees. Critical — fail closed in prod without Redis.
attestSubmitDaily: (pubkey) =>
getLimiter('attest:submit:daily', { limit: 50, window: '1 d', critical: true }).limit(pubkey),
agentDelegate: (key) => getLimiter('agent:delegate', { limit: 10, window: '1 m' }).limit(key),
// GitHub memory seeding: expensive (GitHub API + Claude). 1 seed per agent per 24 hours.
memorySeed: (agentId) => getLimiter('memory:seed', { limit: 1, window: '1 d' }).limit(agentId),
// Edge TTS: free upstream but cached in R2 — limit unique synthesis requests per user/min.
ttsEdge: (userId) => getLimiter('tts:edge', { limit: 20, window: '1 m' }).limit(userId),
// OpenAI TTS (api/tts/speak) — paid per-character against the server key. Per
// user, and critical so it fails closed in prod without Redis rather than
// allowing unbounded paid synthesis. Anonymous callers (keyed by IP) get a
// much tighter bucket since they share no accountable identity.
ttsSpeakUser: (userId) =>
getLimiter('tts:speak:user', { limit: 40, window: '1 h', critical: true }).limit(userId),
ttsSpeakIp: (ip) =>
getLimiter('tts:speak:ip', { limit: 10, window: '1 h', critical: true }).limit(ip),
// An agent's bound voice speaking to a visitor (api/tts/eleven agent_byok lane).
// The agent owner's own ElevenLabs account pays, so this bucket protects THEIR
// quota from a scripted visitor: generous enough for a real back-and-forth
// conversation, tight enough that one IP cannot drain an owner's character
// budget. Keyed per agent AND per IP so one noisy visitor can't mute an agent
// for everyone else. Critical — fail closed rather than uncap someone's bill.
ttsAgentVoiceIp: (agentIdAndIp) =>
getLimiter('tts:agent-voice:ip', { limit: 60, window: '1 h', critical: true }).limit(
agentIdAndIp,
),
// NVIDIA Riva ASR (api/asr) — free upstream but credit-metered, and each call
// streams an audio clip the server holds in memory, so meter per principal.
// Authenticated users get a generous bucket; anonymous callers (keyed by IP) a
// tighter one. Critical so a missing Redis in prod fails closed rather than
// leaving an open transcription drain.
asrUser: (userId) =>
getLimiter('asr:user', { limit: 60, window: '1 h', critical: true }).limit(userId),
asrIp: (ip) =>
getLimiter('asr:ip', { limit: 15, window: '1 h', critical: true }).limit(ip),
// Productized speech package free tier (api/v1/ai/tts, api/v1/ai/asr). A tight
// per-IP DAILY quota that gates the free NIM lane before the x402 402
// fall-through — the free tier is the funnel, x402 is the metered overage.
// Kept low to protect the credit-metered NIM GPU allocation. Critical so a
// Redis outage in prod fails closed: an over-quota caller is routed to PAY
// (the route sends a denied free check to the 402 challenge) rather than the
// free GPU lane being silently uncapped across serverless instances.
aiTtsFreeIp: (ip) =>
getLimiter('ai:tts:free:ip', { limit: 10, window: '1 d', critical: true }).limit(ip),
aiAsrFreeIp: (ip) =>
getLimiter('ai:asr:free:ip', { limit: 5, window: '1 d', critical: true }).limit(ip),
// News-archive SEARCH quota (api/news/archive query mode) — same freemium
// shape as the AI lanes above: a free daily allowance per IP is the funnel,
// x402 ($0.001/search) is the metered overage. Each search fans out to GCS
// month files (2–11 MB each, up to 12 per request), so an uncapped scraper
// pulling the 660k corpus through the API is a real egress + CPU drain; 60
// searches/day covers a heavy interactive session on /markets/archive while
// pricing bulk extraction onto the paid rail. stats/months/trending modes
// are cheap + cached and stay outside this quota. Critical so a Redis outage
// fails closed to the 402 challenge rather than uncapping the scan path.
newsArchiveFreeIp: (ip) =>
getLimiter('news:archive:free:ip', { limit: 60, window: '1 d', critical: true }).limit(ip),
// Grounded web search (api/web-search.js). Every call is a Vertex Gemini
// generateContent with the google_search tool: real GCP-credit spend plus a
// Google Search round-trip, so it must NOT sit in the generic publicIp
// bucket where a scraper could turn our credits into a free SERP API. 20/10m
// covers interactive use (a person refining a query) and prices bulk
// extraction out. Critical so a Redis outage fails closed rather than
// uncapping paid inference.
webSearchIp: (ip) =>
getLimiter('web-search:ip', { limit: 20, window: '10 m', critical: true }).limit(ip),
// Premium-pass purchase lane (api/premium/*). Quote builds a Solana tx (an
// RPC blockhash round-trip + a DB row) and subscribe replays an RPC
// getParsedTransaction per attempt — both cheap, but neither should be
// free-form scriptable. Status is a read for the dashboards.
premiumQuoteIp: (ip) => getLimiter('premium:quote:ip', { limit: 10, window: '10 m' }).limit(ip),
premiumSubscribeIp: (ip) =>
getLimiter('premium:subscribe:ip', { limit: 30, window: '10 m' }).limit(ip),
premiumStatusIp: (ip) =>
getLimiter('premium:status:ip', { limit: 120, window: '1 m', local: true }).limit(ip),
// Key management (api/premium/keys). Metered per account, not per IP: it is
// session-gated, so the principal is the user. A rotate mints a real
// x402_subscriptions row every call, which is the one premium action an
// already-authenticated caller can repeat to grow a table without paying
// anything; nobody legitimately rotates a key more than a handful of times
// a day.
premiumKeysUser: (userId) =>
getLimiter('premium:keys:user', { limit: 20, window: '1 h' }).limit(userId),
// Fact Checker (api/x402/fact-check) free daily lane. Same "free tier is the
// funnel, x402 is the metered overage" shape as the AI speech routes above —
// each free check runs the REAL search+LLM chain (never a degraded fake), so
// the quota is tight to bound upstream (search + LLM token) cost. Critical so
// a Redis outage fails closed to the paid rail rather than opening the chain.
factCheckFreeIp: (ip) =>
getLimiter('fact-check:free:ip', { limit: 3, window: '1 d', critical: true }).limit(ip),
// Keyless x402 services (api/x402/{weather-guard,carbon,domains,research,
// books,news-wire,transit,places}): each ports a live public-data API with
// no API key at all, so the free lane costs us nothing but the upstream's
// goodwill. Quotas are sized to each upstream's own tolerance, tightest
// for the ones that actively rate-limit or ask for restraint (GDELT's
// 5.1s min-gap, Overpass's shared community infra), loosest for the ones
// built for exactly this kind of polling (Open-Meteo, UK Carbon Intensity,
// MBTA's public GTFS feed). Critical: a Redis outage fails closed to the
// paid rail rather than opening an unmetered proxy to the upstream.
weatherGuardFreeIp: (ip) =>
getLimiter('weather-guard:free:ip', { limit: 20, window: '1 d', critical: true }).limit(ip),
carbonFreeIp: (ip) =>
getLimiter('carbon:free:ip', { limit: 20, window: '1 d', critical: true }).limit(ip),
domainsFreeIp: (ip) =>
getLimiter('domains:free:ip', { limit: 15, window: '1 d', critical: true }).limit(ip),
researchFreeIp: (ip) =>
getLimiter('research:free:ip', { limit: 10, window: '1 d', critical: true }).limit(ip),
booksFreeIp: (ip) =>
getLimiter('books:free:ip', { limit: 10, window: '1 d', critical: true }).limit(ip),
newsWireFreeIp: (ip) =>
getLimiter('news-wire:free:ip', { limit: 5, window: '1 d', critical: true }).limit(ip),
transitFreeIp: (ip) =>
getLimiter('transit:free:ip', { limit: 20, window: '1 d', critical: true }).limit(ip),
placesFreeIp: (ip) =>
getLimiter('places:free:ip', { limit: 15, window: '1 d', critical: true }).limit(ip),
// NVIDIA Audio2Face-3D (api/a2f) — free upstream but credit-metered, and each
// call streams a full speech clip through a bidirectional gRPC stream the
// server holds in memory while collecting the blendshape track. Meter per
// principal like the other free NVIDIA lanes; the per-IP bucket is tighter
// since the optional text→speech→animation path also burns a Magpie synthesis.
// Critical so a missing Redis in prod fails closed rather than leaving an open
// animation drain.
a2fUser: (userId) =>
getLimiter('a2f:user', { limit: 40, window: '1 h', critical: true }).limit(userId),
a2fIp: (ip) =>
getLimiter('a2f:ip', { limit: 10, window: '1 h', critical: true }).limit(ip),
// NVIDIA NIM vision (api/vision) — free upstream but credit-metered, and each
// call carries an image the server may relay to the NVCF asset store. Meter
// per principal like the other free NVIDIA lanes; critical so it fails closed
// without Redis in prod.
visionUser: (userId) =>
getLimiter('vision:user', { limit: 60, window: '1 h', critical: true }).limit(userId),
visionIp: (ip) =>
getLimiter('vision:ip', { limit: 15, window: '1 h', critical: true }).limit(ip),
// /brain multi-LLM proxy. Paid flagship models (Claude/GPT-4o) run on the
// server keys, so meter per principal: authenticated users get a generous
// per-user bucket, anonymous callers a tighter per-IP one. Both critical so a
// missing Redis in prod fails closed instead of opening the paid floodgate.
brainChatUser: (userId) =>
getLimiter('brain:chat:user', { limit: 60, window: '1 m', critical: true }).limit(userId),
brainChatIp: (ip) =>
getLimiter('brain:chat:ip', { limit: 20, window: '1 m', critical: true }).limit(ip),
// X (Twitter) memory seeding: 1 seed per agent per 6 hours.
xSeed: (agentId) => getLimiter('memory:seed:x', { limit: 1, window: '6 h' }).limit(agentId),
// Give the window back when a seed run stored nothing: X refused the read,
// the token could not be refreshed, or the run produced no usable fact. The
// agent's memories are untouched on all of those paths, so charging six hours
// for them bills the owner for someone else's outage.
xSeedRefund: (agentId) => refundLimit('memory:seed:x', { limit: 1, window: '6 h' }, agentId),
// Consent-first GitHub memory seeding: reads the GitHub API and one LLM pass
// per run. 1 seed per agent per 6 hours, matching the X lane.
githubSeed: (agentId) =>
getLimiter('memory:seed:github', { limit: 1, window: '6 h' }).limit(agentId),
// Give the window back when a seed run wrote nothing because every model
// provider was busy at once. Without this a platform-side outage costs the
// owner six hours on a run that never touched their agent's memories.
githubSeedRefund: (agentId) =>
refundLimit('memory:seed:github', { limit: 1, window: '6 h' }, agentId),
// Consent-first Farcaster memory seeding: reads a hub (or Neynar) and runs one
// LLM pass per seed. 1 seed per agent per 6 hours, matching the X and GitHub
// lanes. Issuing a signing challenge is deliberately outside this budget so a
// user can retry the wallet step without burning the window.
farcasterSeed: (agentId) =>
getLimiter('memory:seed:farcaster', { limit: 1, window: '6 h' }).limit(agentId),
// Withdrawal requests: 5 per user per day. This is the daily cap on the only
// owner-initiated path that sweeps real funds out of custody, so it is critical
// — a missing Redis in prod must fail closed rather than fall back to the
// per-instance map (uncapped across serverless fan-out) and silently uncap
// custodial withdrawals.
withdrawalPerUser: (userId) =>
getLimiter('withdrawal:user', { limit: 5, window: '1 d', critical: true }).limit(userId),
// Pricing a transfer without signing it (`simulate: true` on send / fund-agent).
// This deliberately does NOT draw on withdrawalPerUser: that budget is 5 per
// DAY, so charging previews against it meant four price checks locked a user
// out of their own funds until the next day. A preview moves nothing, but it
// does spend Solana RPC reads, so it gets its own per-minute ceiling instead
// of being free.
walletSimulate: (userId) =>
getLimiter('wallet:simulate', { limit: 30, window: '1 m' }).limit(userId),
// Discretionary agent-wallet trades: server-signed buys/sells from the agent's
// custodial wallet (POST /api/agents/:id/trade). Each one moves real funds and
// decrypts a custodial key, so it gets its own per-user write budget separate
// from the strict per-IP `authIp` ceiling — 30/min lets an owner actively trade
// while still capping a runaway client or a hijacked session. Critical so a
// Redis outage fails closed rather than uncapping custodial spends.
tradePerUser: (userId) =>
getLimiter('agent-trade:user', { limit: 30, window: '1 m', critical: true }).limit(userId),
// Trading-swarm mutations (POST /api/swarms): contribute/exit move real SOL out
// of a custodial wallet and kill/pause change a live treasury's mandate. Same
// class as an agent trade, so it gets the same 30/min per-user write budget in
// its own bucket (an owner actively trading must not 429 their swarm actions,
// and vice versa). Critical: a Redis outage fails closed rather than uncapping
// custodial spends.
swarmMutate: (userId) =>
getLimiter('swarm:mutate:user', { limit: 30, window: '1 m', critical: true }).limit(userId),
// Per-user audit-log reads — the page polls on mount + "load older". 120/min
// per user is generous for browse but discourages scraping the full year.
// local: per-user browse/poll of one's own audit log — no side effects, no
// shared resource. A per-instance 120/min still discourages bulk scraping
// while spending zero Redis commands on a mount-poll + "load older" surface.
auditLogRead: (userId) =>
getLimiter('audit-log:read', { limit: 120, window: '1 m', local: true }).limit(userId),
// Notifications inbox poll — the nav badge polls every 30s and re-polls on
// each navigation + tab focus. Keyed by userId with its own generous bucket so
// it never competes with the strict per-IP `authIp` budget (which a shared
// office/NAT IP would otherwise exhaust, 429-ing the badge for everyone).
// local: pure poll-flood guard on a read with no side effects and no shared
// resource — a per-instance cap suffices, and at one Redis command per poll
// (every 30s × focus/navigation re-polls × every signed-in user) this is one
// of the heaviest avoidable burners. Never critical.
notificationsRead: (userId) =>
getLimiter('notifications:read', { limit: 120, window: '1 m', local: true }).limit(userId),
// Web Push subscription register/unregister — one per device install plus the
// occasional re-subscribe when the browser rotates the endpoint.
pushSubscribe: (userId) =>
getLimiter('push:subscribe', { limit: 30, window: '1 h' }).limit(userId),
// Preference-center writes — debounced client, generous ceiling.
notifPrefsWrite: (userId) =>
getLimiter('notif:prefs:write', { limit: 60, window: '1 h' }).limit(userId),
// Chat gateways (api/_lib/gateway/). A paired chat drives LLM turns and
// wallet reads, so each link gets its own per-minute budget; an unpaired chat
// can only ask for pairing codes, capped hourly so a group cannot mint them in
// a loop; the settings page's issue/redeem/revoke writes share one ceiling.
gatewayMessage: (linkId) =>
getLimiter('gateway:msg', { limit: 20, window: '1 m' }).limit(linkId),
gatewayPair: (chatKey) =>
getLimiter('gateway:pair', { limit: 8, window: '1 h' }).limit(chatKey),
gatewaySiteWrite: (userId) =>
getLimiter('gateway:site', { limit: 30, window: '1 h' }).limit(userId),
// Herald delivery rail (/api/herald/*). Announces are machine-written (CI,
// crons, agents holding an API key) and land as a physical interruption on
// the owner's screen, so the ceiling is a spam guard on their own attention
// as much as on our Redis: 60/min is far above any sane integration and far
// below a runaway loop. NOT local: the whole point is a global cap on how
// often anything can interrupt one person, and a per-instance counter would
// multiply that by the instance count.
heraldAnnounce: (userId) =>
getLimiter('herald:announce', { limit: 60, window: '1 m' }).limit(userId),
// The SSE listener. One connection per open tab, re-established every ~5
// minutes when the stream hits its duration cap, so this only has to stop a
// reconnect storm. local: a connection budget per instance is the thing that
// actually protects that instance.
heraldStream: (userId) =>
getLimiter('herald:stream', { limit: 60, window: '5 m', local: true }).limit(userId),
// Companion (/api/companion/*). Reads are a page load plus a poll while the
// setup page is open, so they get the same generous local bucket the bell
// inbox uses. Writes touch encrypted credentials and are human-paced.
companionRead: (userId) =>
getLimiter('companion:read', { limit: 120, window: '1 m', local: true }).limit(userId),
companionWrite: (userId) =>
getLimiter('companion:write', { limit: 60, window: '10 m' }).limit(userId),
// "Check now" and connection tests each open a real connection to the user's
// provider (Telegram, an ICS host, an IMAP server), so this is a cost
// ceiling on somebody else's infrastructure as much as on ours, and it must
// NOT be local: a per-instance counter multiplies by the instance count.
companionPoll: (userId) =>
getLimiter('companion:poll', { limit: 30, window: '10 m' }).limit(userId),
// Reading a checkout page (POST /api/companion/checkout). One call per
// payment screen a person actually reaches, which is a handful a day for a
// heavy shopper, so the ceiling is set to catch a loop in a content script
// rather than to ration honest use. It is the only companion bucket that
// gates an LLM call on untrusted third-party page text, which is why it is
// tighter than companionWrite.
companionCheckout: (userId) =>
getLimiter('companion:checkout', { limit: 40, window: '10 m' }).limit(userId),
// Visitor feedback (POST /api/feedback/report). Deliberately generous: the
// cost of dropping a real bug report is far higher than the cost of storing a
// few extra rows, and the reporter may be anonymous and mid-outage. Keyed to
// the account, else a hashed browser key, else the IP.
feedbackWrite: (id) =>
getLimiter('feedback:write', { limit: 20, window: '1 h' }).limit(id),
// The admin review queue (/api/feedback). One admin refreshing a dashboard.
feedbackRead: (userId) =>
getLimiter('feedback:read', { limit: 240, window: '1 m', local: true }).limit(userId),
// The phone/desktop bridge (POST /api/companion/ingest). Keyed by the bridge
// token, since the poster is a Shortcut or a shell script with no session.
// A phone forwarding every notification it receives stays well under this;
// a loop does not.
companionIngest: (token) =>
getLimiter('companion:ingest', { limit: 120, window: '5 m' }).limit(token),
// Knock (/api/knock/*). The owner's own reads are a page load plus polling
// while the inbox is open.
knockRead: (userId) =>
getLimiter('knock:read', { limit: 120, window: '1 m', local: true }).limit(userId),
knockWrite: (userId) =>
getLimiter('knock:write', { limit: 90, window: '10 m' }).limit(userId),
// Public door + directory reads, keyed by IP. A door page is one read; a
// crawler walking the directory stays inside this.
knockPublic: (ip) =>
getLimiter('knock:public', { limit: 120, window: '5 m' }).limit(ip),
// Free-door knocks (POST /api/knock/send), keyed by IP. Free means there is
// no price to make a flood expensive, so the ceiling has to do that job:
// a person writing to a few people is fine, a script is not. Priced doors
// go through the x402 lane and are limited by their own cost.
knockSendIp: (ip) =>
getLimiter('knock:send:ip', { limit: 8, window: '1 h' }).limit(ip),
// Motion synthesis (/api/motion). Compiling a score is pure arithmetic and
// deterministic, so it gets a generous local bucket an editor can type into.
// Authoring one from a sentence can reach a language model, so it is metered
// the way every other model-backed surface here is.
motionCompile: (key) =>
getLimiter('motion:compile', { limit: 240, window: '1 m', local: true }).limit(key),
motionAuthor: (key) =>
getLimiter('motion:author', { limit: 60, window: '10 m' }).limit(key),
// Funnel tracking (opened/returned) — high local ceiling; one ping per
// notification interaction, deduped server-side anyway.
notifTrack: (userId) =>
getLimiter('notif:track', { limit: 240, window: '1 m', local: true }).limit(userId),
// Newsletter confirm/unsubscribe link clicks (token in URL, no auth).
newsletterConfirmIp: (ip) =>
getLimiter('newsletter:confirm:ip', { limit: 20, window: '1 h' }).limit(ip),
// $THREE token payment layer (api/token/*).
// quote: 30 per user per minute — prevents price-polling abuse; each quote
// hits a live price feed and signs a HMAC. Generous enough for interactive
// flows (spin UI, listing flow) and burst-resistant for agent consumers.
tokenQuote: (userId) => getLimiter('token:quote', { limit: 30, window: '1 m' }).limit(userId),
// settle: 10 per user per minute — each settle does an RPC round-trip + DB
// write. A real user sends 1 tx; the ceiling absorbs retries + latency.
tokenSettle: (userId) => getLimiter('token:settle', { limit: 10, window: '1 m' }).limit(userId),
// price: public endpoint, 120/min per IP — fast cache-served; upstream
// Jupiter is rate-limit-free, but the cache makes this essentially free.
// local: cache-served price reads; upstream Jupiter is rate-limit-free, so
// this bucket only bounds poll floods. A per-instance cap does that without
// a Redis command per quote refresh on a high-traffic public endpoint.
tokenPriceIp: (ip) =>
getLimiter('token:price:ip', { limit: 120, window: '1 m', local: true }).limit(ip),
// Livepeer LLM comparison endpoint — calls both Claude and Livepeer per POST.
// Per-IP only (unauthenticated public demo). Critical so Redis outage in prod
// fails closed rather than opening the LLM floodgate.
livepeerIp: (ip) =>
getLimiter('livepeer:ip', { limit: 20, window: '1 m', critical: true }).limit(ip),
// Talking-avatar video generation — submits GPU jobs to Cloud Run. Each job
// costs real compute. Per-user ceiling (authenticated endpoint). Critical.
videoGenerateUser: (userId) =>
getLimiter('video:generate:user', { limit: 5, window: '1 h', critical: true }).limit(userId),
videoGenerateGlobal: () =>
getLimiter('video:generate:global', { limit: 100, window: '1 h', critical: true }).limit(
'global',
),
// Oracle personal Telegram test-alert (api/oracle/test-alert). Fires a real
// Telegram message via the bot, so keep per-IP burst tight to prevent spamming
// third-party chats. 5 per 10 minutes is generous enough for manual setup
// retries while blocking scripted abuse.
oracleTelegramTestIp: (ip) =>
getLimiter('oracle:tg-test:ip', { limit: 5, window: '10 m' }).limit(ip),
// Coin Clash community battles (api/clash/*). enlist verifies a wallet sig +
// runs a balance read, so cap per IP. rally is the hot tap loop — per wallet,
// generous enough for furious tapping but bounded so one tab can't flood; the
// real influence ceiling is the per-wallet power cap in clash-store.js.
clashEnlistIp: (ip) => getLimiter('clash:enlist:ip', { limit: 20, window: '5 m' }).limit(ip),
clashRallyWallet: (wallet) =>
getLimiter('clash:rally:wallet', { limit: 40, window: '1 m' }).limit(wallet),
clashStateIp: (ip) =>
getLimiter('clash:state:ip', { limit: 120, window: '1 m', local: true }).limit(ip),
// Oracle follower subscribe/update — write path creates a DB row and will
// eventually fan out Telegram messages, so keep post-rate tight.
// 10 per hour per IP is enough for manual setup; bots would need more.
oracleFollowIp: (ip) =>
getLimiter('oracle:follow:ip', { limit: 10, window: '1 h' }).limit(ip),
// Aggregator free tier (api/v1/x/[...slug].js). Endpoints in api/v1/_providers.js
// may carry a `free: { perMin, perDay }` quota — an unauthenticated caller (no
// BYOK key, no three.ws credentials) gets real, no-signup data before the x402
// 402 challenge kicks in. Two dynamic buckets, keyed per (provider/endpoint, IP)
// so each endpoint's own quota sizes its own counter (mirrors the widgetChat /
// embedLlmAgent per-resource-dynamic-limit pattern above). Non-critical: a Redis
// outage must never turn a free call into a false 402 — it degrades to the
// per-instance memory limiter, same posture as the other zero-marginal-cost free
// lanes (mcp3dGenerateFree, studioGenBurst) in this file.
apiV1FreeMin: (key, perMin) =>
getLimiter('v1:free:min', { limit: Math.max(1, Number(perMin) || 30), window: '1 m' }).limit(key),
apiV1FreeDay: (key, perDay) =>
getLimiter('v1:free:day', { limit: Math.max(1, Number(perDay) || 1000), window: '1 d' }).limit(key),
// Gasless ERC-8004 registration relay (api/bnb/register-agent.js). Each call
// either consumes a real MegaFuel-sponsored gas slot or broadcasts a real
// self-pay tx — tighter than a generic read bucket, keyed per IP since the
// whole point is a caller with no wallet history to key on.
bnbRegisterIp: (ip) => getLimiter('bnb:register:ip', { limit: 10, window: '10 m', critical: true }).limit(ip),
// Materialize printability + quote (api/print/quote.js). Each miss downloads a
// GLB and runs the mesh analysis, so the bucket is sized for a human moving the
// size slider (results are cached per model, so only the first call costs) while
// stopping a script from using the analyzer as a free mesh-processing service.
printQuoteIp: (ip) =>
getLimiter('print:quote:ip', { limit: 90, window: '5 m', local: true }).limit(ip),
// Slicer handoff file (api/slicer/model.js). A miss downloads the creation's
// GLB and writes an STL or 3MF, so it is CPU-bound like the quote analyzer;
// hits are served from the converted-file cache and the CDN and never reach
// this bucket. Sized for someone opening a few models in OrcaSlicer, re-sizing
// them, and downloading the fallback file, not for bulk conversion.
slicerFileIp: (ip) =>
getLimiter('slicer:file:ip', { limit: 30, window: '5 m', local: true }).limit(ip),
// "Get it printed" through Craftcloud (api/print/craftcloud-quote.js). A miss
// uploads the STL to Craftcloud and polls its pricing engine across the whole
// 186-shop network, which is slower and costs more upstream calls than the
// in-house quote path, so the bucket is tighter. NOT local: Craftcloud's model
// upload is the shared resource being rationed, and a per-instance counter
// would multiply by however many Cloud Run instances are up.
craftcloudQuoteIp: (ip) =>
getLimiter('print:craftcloud:ip', { limit: 20, window: '5 m' }).limit(ip),
// Materialize checkout (api/print/orders.js and its confirm step). Both are
// session-gated and CSRF-gated already, so this is not the security boundary;
// it caps how often one IP can open orders or poll the chain for a payment.
// NOT local: the confirm path spends the shared Solana RPC allowance, and a
// per-instance counter would multiply by however many Cloud Run instances are
// up, which is exactly the bypass that makes an RPC cap meaningless.
printOrderIp: (ip) =>
getLimiter('print:order:ip', { limit: 60, window: '5 m' }).limit(ip),
// Household invitations (api/home/[id]/members.js). An invite link is a bearer
// credential for a role in a physical building, so the ceiling is deliberately
// low: 20 per hour per account is more households than anyone administers and
// far too few for a compromised session to spray keys with. Keyed on the
// account, not the IP, because the account is what the capability hangs off.
// NOT local: a per-instance counter would multiply the ceiling by however many
// Cloud Run instances are up, which is exactly the bypass that matters here.
homeInvite: (userId) =>
getLimiter('home:invite:user', { limit: 20, window: '1 h' }).limit(userId),
// Redeeming a household invitation (api/home/invites/[token].js). The token is
// 256 bits of randomness, so this is not what stops a guess; it is what makes
// "guessing is not feasible" a bounded statement rather than a hopeful one, and
// what stops an enumeration sweep from costing us a database round trip each.
homeInviteRedeem: (ip) =>
getLimiter('home:invite:redeem:ip', { limit: 30, window: '10 m' }).limit(ip),
// Redeeming a relay pairing code (api/home/pair/redeem.js). Unlike the invite
// token above, this secret is deliberately weak: 8 characters a person reads
// off one screen and types into another, so roughly 40 bits. The per-pairing
// attempt counter is what actually makes guessing hopeless (five wrong tries
// kills the code); this bounds a distributed sweep across every live pairing
// at once, which the per-pairing counter alone cannot see. Ten in ten minutes
// is far above what a person retyping a code they mistyped ever needs.
homePairRedeem: (ip) =>
getLimiter('home:pair:redeem:ip', { limit: 10, window: '10 m' }).limit(ip),
// Minting a voice-satellite pairing code (api/home/satellite.js). A code buys
// a microphone in a house an attachment to an agent, so the ceiling is the
// same shape as homeInvite: keyed on the account, low enough that a
// compromised session cannot mint a pile of them, high enough that somebody
// setting up four displays in one afternoon never notices it.
homeSatellitePair: (userId) =>
getLimiter('home:satellite:pair:user', { limit: 20, window: '1 h' }).limit(userId),
// Redeeming one (action 'claim') and refreshing a satellite's hub token
// (action 'session'). Both are called by a program with no session cookie, so
// the IP is the only key available. The code itself is 8 characters from a
// 31-character alphabet, roughly 40 bits, single use, and dead in 15 minutes;
// this is what makes a distributed sweep across every live code at once cost
// more than it can possibly return. A satellite refreshing its own token does
// so once a day, so 30 in ten minutes never binds on the honest path.
homeSatelliteClaimIp: (ip) =>
getLimiter('home:satellite:claim:ip', { limit: 30, window: '10 m' }).limit(ip),
// Redeeming a pending physical-action confirmation (api/home/[id]/confirm.js).
// Every redemption is a human pressing a button in front of a door, so the
// honest ceiling is "faster than a person could ever mean to": 30 in five
// minutes. It exists to bound a stolen-session replay sweep and an id guess,
// not to shape normal use, which never approaches it.
// NOT local: a per-instance counter would multiply by however many Cloud Run
// instances are up, and the thing on the other side of this limit is a lock.
homeConfirm: (userId) =>
getLimiter('home:confirm:user', { limit: 30, window: '5 m' }).limit(userId),
// The Home surface proper (api/home/*). Three buckets, because the three
// shapes of request have three completely different costs and one of them is
// not measured in money at all.
//
// read: list, snapshot, macros, action log. Cache-backed, or a single read off
// an already-pooled socket, so the ceiling only has to stop a poll storm. 240
// a minute is a page open in four tabs with a chatty client, comfortably.
// Local, because a per-instance counter is plenty for something this cheap and
// it keeps a Redis command off every page load.
homeRead: (userId) =>
getLimiter('home:read', { limit: 240, window: '1 m', local: true }).limit(userId),
// act: every service call and every scene activation. This bucket touches
// PHYSICAL HARDWARE. A runaway client here does not run up a bill, it cycles a
// real garage door in a real building, so the ceiling is set by what a person
// could plausibly mean to do rather than by what the server can afford: 40
// actions in 5 minutes is a very busy household (a scene fires many entities
// in ONE call, so a "good night" that touches twelve lights costs one), and a
// broken loop hits the wall in seconds. NOT local, deliberately: a
// per-instance counter multiplied by the instance count is exactly the bypass
// that would make this ceiling a decoration, and this is the one bucket in
// this file whose failure mode is mechanical wear on somebody's house.
homeAct: (userId) =>
getLimiter('home:act', { limit: 40, window: '5 m' }).limit(userId),
// connect: connecting a home, and re-verifying one. Each call opens a real
// WebSocket to a third party and may hold it for up to 15 seconds, and it is
// the credential-stuffing surface on this whole surface: the request body
// carries a Home Assistant token, so a caller who can retry freely can test
// tokens against a house through us. 10 in 10 minutes is several honest
// attempts at a fiddly URL and nothing like enough to sweep. NOT local, for
// the same reason as homeAct.
homeConnect: (userId) =>
getLimiter('home:connect', { limit: 10, window: '10 m' }).limit(userId),
// revoke: disconnecting a home (DELETE /api/home/:id). Its own bucket, and
// NOT a share of homeConnect, because sharing one inverts this lane's whole
// rule that a move toward safety always goes through. Revoking carries no
// token, is not a credential-stuffing surface, and is how a person cuts our
// access to their building. Sharing the connect budget meant the moment that
// budget was spent, which is exactly the moment someone had been fumbling a
// token or connecting several houses, they were told "too many connection
// changes, wait a moment" when they tried to disconnect one. Being unable to
// revoke for ten minutes is the wrong failure to have chosen. Still bounded,
// because a revoke writes to the database and drops sockets: 30 in 10 minutes
// is far more disconnecting than anyone does on purpose.
homeRevoke: (userId) =>
getLimiter('home:revoke', { limit: 30, window: '10 m' }).limit(userId),
// The live stream (api/home/[id]/stream.js). Its own bucket rather than a
// share of homeRead: an EventSource that reconnects in a tight loop (a dead
// network, a client bug) would otherwise eat a page-load budget it should not
// share, and a stream costs a held reference on a pooled socket rather than
// one cheap read.
homeStream: (userId) =>
getLimiter('home:stream', { limit: 60, window: '5 m', local: true }).limit(userId),
// The privacy surface (api/home/privacy.js): the full data export, the
// retention change, and the deletion. Its own bucket, and a tight one, for
// two different reasons that happen to want the same ceiling. The export
// assembles every home, every grant and the whole action log for an account
// in one response, so it is the most expensive read on the surface and an
// obvious amplification lever. The DELETE destroys data that cannot be
// regenerated, so a loop that hits it is not abuse we merely want to slow
// down. 20 an hour is far more than anyone exercising their own privacy
// rights will ever need. NOT local: this must hold across instances.
homePrivacy: (userId) =>
getLimiter('home:privacy', { limit: 20, window: '1 h' }).limit(userId),
// The per-plan API envelope (data/plans.json `rate_limit`), applied to every
// /api request by server/index.mjs through api/_lib/plan-rate-limit.js and
// advertised as RateLimit-* headers. Keyed per account (or per IP when
// signed out), sized by the caller's plan. A fixed window counted per serving
// instance: it runs on every API request, so it never spends a Redis command
// (the June 2026 Upstash quota outage), and a per-instance count can only
// ever be more generous than the published number, never stricter.
planApi: (planId, key, { limit, windowSeconds }) => planWindowLimit(`${planId}\u0000${key}`, limit, windowSeconds * 1000),
// Approval inbox (api/approvals/*): list, read, decide. Generous because an
// owner clearing a backlog taps fast; it exists so a stuck client loop cannot
// hammer the decide path. Local: a decision is already idempotent in the DB.
approvalsUser: (userId) => getLimiter('approvals:user', { limit: 240, window: '5 m', local: true }).limit(userId),
// Destination allowlist (api/wallet-whitelist). Reads and edits per user, a tight
// lane for step-up attempts (password / code guessing), and a per-IP lane for the
// unauthenticated signed cancel link.
whitelistUser: (userId) => getLimiter('whitelist:user', { limit: 120, window: '5 m' }).limit(userId),
whitelistStepUp: (userId) => getLimiter('whitelist:stepup', { limit: 10, window: '10 m' }).limit(userId),
whitelistCancelIp: (ip) => getLimiter('whitelist:cancel-ip', { limit: 30, window: '10 m' }).limit(ip),
creatorPayoutUser: (userId) => getLimiter('creator-payout:user', { limit: 120, window: '5 m' }).limit(userId),
creatorPayoutInfoIp: (ip) => getLimiter('creator-payout:info-ip', { limit: 60, window: '1 m' }).limit(ip),
// Agent self-signup (api/v1/agents/signup.js). Creating an account mints
// wallets, so both lanes are tight and fail closed when Redis is down: a
// per-IP lane against one host spraying keys, and a per-public-key lane
// against one key hammering a signature it cannot get right.
agentSignupIp: (ip) => getLimiter('agent-signup:ip', { limit: 5, window: '1 h', critical: true }).limit(ip),
agentSignupKey: (publicKey) => getLimiter('agent-signup:key', { limit: 10, window: '1 h', critical: true }).limit(publicKey),
// Challenge issuance for /api/auth/agent-signup. Cheap to serve, so the lanes are
// looser than the signup lanes above, but still fail closed: an unthrottled
// challenge endpoint is a free write path into the nonce table.
agentChallengeIp: (ip) => getLimiter('agent-signup:challenge-ip', { limit: 30, window: '1 h', critical: true }).limit(ip),
agentChallengeKey: (publicKey) => getLimiter('agent-signup:challenge-key', { limit: 10, window: '1 h', critical: true }).limit(publicKey),
// Agent plan upgrade (api/billing/agent-upgrade.js): the 402 challenge itself.
agentUpgradeKey: (apiKeyId) => getLimiter('agent-upgrade:key', { limit: 60, window: '1 h' }).limit(apiKeyId),
// Agent commerce (api/agent-commerce/[...route].js). The public invoice page
// and its verify button reach the chain, so they are capped per IP; owner
// writes per user; an approval decision checks a password or a signature, so
// it fails closed and stays tight against guessing.
commercePublic: (ip) => getLimiter('commerce:public', { limit: 120, window: '1 m' }).limit(ip),
commerceVerify: (ip) => getLimiter('commerce:verify', { limit: 20, window: '1 m' }).limit(ip),
commerceOwner: (userId) => getLimiter('commerce:owner', { limit: 120, window: '1 m' }).limit(userId),
commerceDecide: (userId) => getLimiter('commerce:decide', { limit: 10, window: '10 m', critical: true }).limit(userId),
// External skill import (api/skill-imports.js). Browse is served from a
// five-minute index cache; a scan or update check fetches upstream bytes and
// runs the Guardian pass, so those are capped per owner.
skillImportBrowseIp: (ip) => getLimiter('skill-import:browse:ip', { limit: 120, window: '5 m', local: true }).limit(ip),
skillImportScanUser: (userId) => getLimiter('skill-import:scan:user', { limit: 40, window: '10 m' }).limit(userId),
// OpenAPI/GitHub skill import (api/skills/import.js, packages/skill-import).
// Each request fetches an owner-supplied upstream spec/README through the
// SSRF guard and runs codegen, so it is capped per owner like a scan.
openapiSkillImportUser: (userId) => getLimiter('openapi-skill-import:user', { limit: 20, window: '10 m' }).limit(userId),
// Developer plan burst ceiling (api/_lib/dev-plans/quota.js). One sliding
// minute per account; the limit comes from the plan config, so each plan
// gets its own bucket name and the memo in getLimiter keys on the limit too.
devPlanBurst: (planId, key, { limit }) => getLimiter(`devplan:burst:${planId}`, { limit, window: '1 m' }).limit(key),
// Scene Studio Agent tab (api/scene/agent.js): free, anonymous, tool-calling
// round the browser drives one turn at a time. Same shape as concierge: a
// per-IP lane plus a global ceiling on the free-tier draw, both critical so a
// Redis outage fails closed rather than handing out unbounded free inference.
sceneAgentIp: (ip) =>
getLimiter('scene:agent:ip', { limit: 20, window: '1 m', critical: true }).limit(ip),
sceneAgentGlobal: () =>
getLimiter('scene:agent:global', { limit: 600, window: '1 m', critical: true }).limit('global'),
};
// Fixed-window counters for limits.planApi. One small record per principal, so
// the envelope costs O(1) per request however high a plan's ceiling is.
const planWindows = new Map();
const PLAN_WINDOWS_MAX = 50_000;
function planWindowLimit(id, limit, windowMs) {
const now = Date.now();
let w = planWindows.get(id);
if (!w || now >= w.start + windowMs) {
if (!w && planWindows.size >= PLAN_WINDOWS_MAX) {
for (const [k, v] of planWindows) if (now >= v.start + windowMs) planWindows.delete(k);
if (planWindows.size >= PLAN_WINDOWS_MAX) planWindows.clear();
}
w = { start: now, count: 0 };
planWindows.set(id, w);
}
const reset = w.start + windowMs;
if (w.count >= limit) return { success: false, limit, remaining: 0, reset };
w.count += 1;
return { success: true, limit, remaining: limit - w.count, reset };
}
// ── Fail-closed limiter call for privacy-boundary reads (H7) ─────────────────
// Most call sites fail OPEN when a limiter throws: the request is bounded by
// something else downstream (a DB cap, an ownership check), so a limiter outage
// should not deny legitimate traffic. A read that returns someone else's LOCATION
// has no such downstream bound, so its degradation path is the opposite: if the
// limiter cannot decide, deny with a retryable `rate_limiter_unavailable` verdict
// rather than open an unmetered scrape window. Shared by the three /irl coordinate
// reads (pins, drops, world-lines nearby) so the guarantee is one implementation
// instead of three drifting copies. See docs/irl/THREAT-MODEL.md.
//
// `name` ties the warning to a bucket; the cooldown keeps an outage that hits every
// request from flooding the logs with the same line.
const _failClosedWarnedAt = new Map();
const FAIL_CLOSED_WARN_COOLDOWN_MS = 60_000;
export async function limitFailClosedRead(name, fn, ...args) {
try {
return await fn(...args);
} catch (err) {
const last = _failClosedWarnedAt.get(name) || 0;
const now = Date.now();
if (now - last >= FAIL_CLOSED_WARN_COOLDOWN_MS) {
_failClosedWarnedAt.set(name, now);
console.warn(`[rate-limit] read limiter "${name}" failed, failing CLOSED (deny):`, err?.message || err);
}
return { success: false, reason: 'rate_limiter_unavailable', reset: Date.now() + 60_000 };
}
}
// Trust only proxy headers that Vercel itself sets and signs. Naively reading
// X-Forwarded-For (or X-Real-IP, which clients can also supply directly) lets
// callers bypass per-IP rate limits by rotating the claimed address.
//
// Order of trust:
// 1. x-vercel-forwarded-for — set by the Vercel edge on every proxied
// request; clients cannot inject it past the platform.
// 2. socket remote address — authoritative on direct connections (local
// dev / tests, where no Vercel headers exist).
// 3. x-real-ip — last resort only, for non-Vercel reverse-proxy setups where
// the socket address is the proxy's. Client-settable on direct hits, but
// by this point there is no better signal.
// How many trailing X-Forwarded-For entries THIS deployment's own infrastructure
// appends. Google's external Application Load Balancer (three.ws prod) hands the
// backend:
//
// X-Forwarded-For: <caller-supplied…>, <real-client-ip>, <load-balancer-ip>
//
// It appends the connecting client's IP and the forwarding rule's IP. So exactly one
// trailing hop (the LB) must be skipped, and the entry before it is the real client.
// Cloud Run reached directly (no LB in front) appends nothing → set this to 0.
const TRUSTED_PROXY_HOPS = (() => {
const n = Number.parseInt(process.env.TRUSTED_PROXY_HOPS ?? '', 10);
return Number.isInteger(n) && n >= 0 ? n : 1;
})();
// The caller's IP, as the key for every per-IP rate limiter on the platform.
//
// Two ways to get this wrong, both of which this function used to:
//
// 1. Trust `req.socket.remoteAddress`. Behind a load balancer the socket peer is
// ALWAYS the balancer, so every visitor on earth collapses into ONE bucket key.
// After the Vercel→Cloud Run migration this was the live behaviour (the Vercel
// header below is never set on GCP), which silently turned every per-IP limit
// into a platform-wide global limit — a self-DoS, not a control. It is why
// /api/irl/privacy answered 429 to its very first caller.
//
// 2. Trust the LEFTMOST X-Forwarded-For entry, or any header a caller can set
// (`x-vercel-forwarded-for`, `x-real-ip`). Everything left of the hops our own
// infrastructure appends is attacker-controlled: a sweeper sending a random
// X-Forwarded-For on each request mints a fresh limiter bucket every time.
//
// So: read X-Forwarded-For, walk it from the RIGHT, skip the hops we append, and
// take the next address. Fall back to the socket only when there is no XFF at all
// (local dev, tests, direct container access) — there, the socket IS the client.
/**
* Rate-limit bucket key for an IP. IPv6 subscribers are routinely handed a whole
* /64, so a per-address bucket is trivially evaded; collapse IPv6 to its /64.
* IPv4 (and anything unparseable) is returned unchanged.
*/
export function ipRateKey(ip) {
const s = String(ip ?? '');
if (!s.includes(':') || /^::ffff:\d+\.\d+\.\d+\.\d+$/i.test(s)) return s;
const [head, tail] = s.split('::');
const headGroups = head ? head.split(':') : [];
const tailGroups = tail === undefined ? [] : tail ? tail.split(':') : [];
const missing = tail === undefined ? 0 : 8 - headGroups.length - tailGroups.length;
const groups = [...headGroups, ...Array(Math.max(0, missing)).fill('0'), ...tailGroups];
if (groups.length !== 8) return s;
return groups.slice(0, 4).map((g) => g.toLowerCase().replace(/^0+(?=.)/, '')).join(':') + '::/64';
}
export function clientIp(req) {
const xff = req.headers?.['x-forwarded-for'];
if (xff) {
const hops = String(xff).split(',').map((s) => s.trim()).filter(Boolean);
if (hops.length) {
// Clamp: a shorter-than-expected chain (direct hit, or a stripped header)
// must degrade to the leftmost real entry, never to a negative index.
// The *.run.app URL bypasses the load balancer: Cloud Run appends only the
// real client, so no trailing hop may be skipped there. The Host header on
// that URL is fixed by Google's routing; a caller who sends it through the
// LB only collapses their own key onto the LB address.
const host = String(req.headers?.host ?? '').split(':')[0].toLowerCase();
const skip = host.endsWith('.run.app') ? 0 : TRUSTED_PROXY_HOPS;
const ip = hops[Math.max(0, hops.length - 1 - skip)];
if (ip) return ip;
}
}
const sock = req.socket?.remoteAddress;
if (sock) return sock;
return '0.0.0.0';
}