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
// api/_lib/x402/pipelines/api-key-bypass-audit.js
//
// API Key Bypass Security Test — autonomous pipeline (self/security).
//
// A run()-style registry entry (autonomous-registry.js → `api-key-bypass-audit`)
// the per-tick spend loop invokes once a day. It is the platform's free-access
// canary: it proves the X-API-Key bypass lane (api/_lib/x402/access-control.js →
// installAccessControl) only ever grants free access to a VALID key — and that a
// missing or invalid key still hits the paywall. A refactor that accidentally
// short-circuits the 402 for ANY key (or no key) lets the whole paid surface be
// drained for free; this audit catches that within a day.
//
// The bypass matrix it exercises against every audited route:
// • VALID key → expect a free grant: HTTP 200 carrying `x-payment-bypass`,
// NOT a 402 and NOT a 403. (the bypass lane working)
// • INVALID key → expect denial: a 403 (Invalid API key) or a 402 paywall —
// anything that does NOT grant free access. A 200 here is a LEAK.
// • NO key → expect the 402 paywall challenge. A 200 here means the
// paywall was removed — a LEAK.
// • REVOKED key → (subscription lane only) after we revoke the canary key, the
// SAME key must now be denied. A grant here is a LEAK.
//
// Both audited routes share the same installAccessControl() hook but invoke it
// from different consumers, so the pair covers both code paths a refactor could
// break:
// • /api/x402/model-check — hand-rolled access-control invocation (GET, $0.001,
// read-only/idempotent). Full matrix (valid grant + denials) runs here, and
// this is the one route we actually PAY: paying its no-key 402 challenge once
// proves the paywall→verify→settle path is intact end-to-end ("without a valid
// key you must pay, and paying works").
// • /api/x402/dance-tip — paidEndpoint(spec) factory access-control (POST,
// $0.001). Deny matrix only (invalid → 403, no-key → 402); those paths reject
// BEFORE the handler runs, so probing them has no side effects and we never
// fire a free dance-tip.
//
// Acquiring a VALID key: we mint an EPHEMERAL subscription key (createSubscription)
// with a 10-minute self-expiry, exercise the partner/DB bypass lane every
// paidEndpoint relies on, then revoke it in a finally — so a crash mid-run can
// never leave a live free-access key behind (it self-expires regardless). When the
// DB is unavailable we fall back to the INTERNAL_API_KEY env (the internal-service
// lane). With neither, the grant check is skipped (verdict: inconclusive) but the
// deny matrix + paywall payment still run.
//
// Recording: the loop records ONE x402_autonomous_log row per run (signalData →
// signal_data, valueExtracted → value_extracted, amountAtomic = the single $0.001
// paywall-proof payment). The dedicated value sink is `x402_api_key_bypass_audit`
// — one row per audit with the full per-route matrix, the pass/fail verdict, and
// the paywall-payment evidence.
//
// Downstream consumer: api/ops/health.js reads the latest x402_api_key_bypass_audit
// row (loadApiKeyBypassAudit) and folds a confirmed bypass leak / broken bypass
// into the platform health verdict (alongside the idempotency audit and the
// cross-network circuit breaker), so the status page / on-call surface a leaking
// paywall immediately.
import { randomUUID, randomBytes } from 'node:crypto';
import { sql as defaultSql } from '../../db.js';
import { env } from '../../env.js';
import { logger } from '../../usage.js';
import { sendOpsAlert } from '../../alerts.js';
import { createSubscription, revokeSubscription } from '../api-keys.js';
import {
loadSeedKeypair,
bootstrapSolanaContext,
payX402,
fetchWithTimeout,
} from '../pay.js';
const log = logger('x402-api-key-bypass-audit');
const UA = 'threews-x402-autonomous/1.0';
// fox.glb — a tiny public canary the model-check server fetches behind its SSRF
// guard. Pinned to the canonical public origin so model-check always has a real
// public asset to inspect on the paid (no-key) probe.
const CANARY_GLB = 'https://three.ws/avatars/fox.glb';
// Routes under audit. `probeGrant` runs the valid-key grant probe (read-only
// routes only, so a free grant has no side effect). `pay` marks the single route
// whose no-key 402 we actually settle to prove the paywall path end-to-end.
const AUDIT_ROUTES = [
{
route: '/api/x402/model-check',
label: 'hand-rolled',
method: 'GET',
query: `?url=${encodeURIComponent(CANARY_GLB)}`,
body: null,
probeGrant: true,
pay: true,
},
{
route: '/api/x402/dance-tip',
label: 'paidEndpoint',
method: 'GET',
query: '',
// Deny matrix only: the invalid-key (403) and no-key (402) paths both reject
// inside / before the access-control hook, well before the dance-tip handler
// runs — so probing them is read-only and never fires a free tip. No grant
// probe here (that would run the handler), so no params are needed.
body: null,
probeGrant: false,
pay: false,
},
];
let _schemaReady = false;
async function ensureSchema(sql) {
if (_schemaReady) return;
await sql`
CREATE TABLE IF NOT EXISTS x402_api_key_bypass_audit (
id bigserial PRIMARY KEY,
ts timestamptz DEFAULT now(),
run_id uuid,
route text NOT NULL,
valid_key_source text,
valid_status int,
valid_bypassed boolean,
invalid_status int,
invalid_denied boolean,
nokey_status int,
nokey_challenged boolean,
revoked_status int,
revoked_denied boolean,
routes_tested int NOT NULL DEFAULT 0,
leaks int NOT NULL DEFAULT 0,
paid_status int,
paid_settled boolean NOT NULL DEFAULT false,
paid_tx text,
amount_atomic bigint NOT NULL DEFAULT 0,
verdict text NOT NULL,
pass boolean NOT NULL,
leak boolean NOT NULL DEFAULT false,
details jsonb,
duration_ms int,
error_msg text
)
`;
await sql`CREATE INDEX IF NOT EXISTS x402_api_key_bypass_audit_ts ON x402_api_key_bypass_audit (ts DESC)`;
_schemaReady = true;
}
async function storeAudit(sql, runId, row) {
try {
await ensureSchema(sql);
await sql`
INSERT INTO x402_api_key_bypass_audit
(run_id, route, valid_key_source, valid_status, valid_bypassed,
invalid_status, invalid_denied, nokey_status, nokey_challenged,
revoked_status, revoked_denied, routes_tested, leaks,
paid_status, paid_settled, paid_tx, amount_atomic,
verdict, pass, leak, details, duration_ms, error_msg)
VALUES
(${runId || null}, ${row.route}, ${row.valid_key_source || null},
${row.valid_status}, ${row.valid_bypassed},
${row.invalid_status}, ${row.invalid_denied},
${row.nokey_status}, ${row.nokey_challenged},
${row.revoked_status}, ${row.revoked_denied},
${row.routes_tested}, ${row.leaks},
${row.paid_status}, ${row.paid_settled}, ${row.paid_tx || null},
${row.amount_atomic || 0},
${row.verdict}, ${row.pass}, ${row.leak},
${JSON.stringify(row.details || [])}, ${row.duration_ms}, ${row.error_msg || null})
`;
} catch (err) {
// A DB fault must never crash the loop — log and move on.
log.warn('api_key_bypass_audit_insert_failed', { message: err?.message });
}
}
// One free probe of a route with a given header set. Never throws — a network
// fault lands as status 0 (classified 'error', never a leak).
async function probe(url, route, extraHeaders) {
const headers = { 'user-agent': UA, ...extraHeaders };
const init = { method: route.method, headers };
if (route.method !== 'GET' && route.body != null) {
headers['content-type'] = 'application/json';
init.body = JSON.stringify(route.body);
}
try {
const res = await fetchWithTimeout(url, init);
return {
status: res.status,
bypass: !!res.headers?.get?.('x-payment-bypass'),
};
} catch (err) {
return { status: 0, bypass: false, error: err?.message || 'network' };
}
}
// Classify one probe against what the scenario expects.
// expectation 'grant' → a valid key must yield a free bypass (200 + header).
// expectation 'deny' → invalid/revoked key must NOT grant free access.
// expectation 'challenge' → no key must hit the 402 paywall.
// A 200 carrying x-payment-bypass on a deny/challenge scenario, or any 200 that
// ran the handler without paying, is a LEAK.
function classify(scenario, route, p, expectation) {
const granted = p.status === 200 && p.bypass;
const free200 = p.status === 200 && !p.bypass;
const challenged = p.status === 402;
const denied = p.status === 401 || p.status === 403;
let verdict;
if (p.status === 0) {
verdict = 'error';
} else if (expectation === 'grant') {
verdict = granted ? 'secure' : 'bypass_broken';
} else if (granted || free200) {
verdict = 'leak';
} else if (expectation === 'challenge') {
verdict = challenged ? 'secure' : denied ? 'anomaly_denied' : 'anomaly';
} else {
// deny: a 403 reject OR a 402 paywall both withhold free access → secure.
verdict = denied || challenged ? 'secure' : 'anomaly';
}
return {
route: route.route,
label: route.label,
scenario,
status: p.status,
bypass: p.bypass,
verdict,
};
}
// Acquire a VALID api key to prove the bypass lane grants free access. Prefer an
// ephemeral subscription key (the partner/DB lane every paidEndpoint depends on);
// fall back to the internal-service key; else null (grant probe is skipped).
async function acquireValidKey() {
try {
const expiresAt = new Date(Date.now() + 10 * 60 * 1000).toISOString();
const sub = await createSubscription({
name: `bypass-audit-canary ${new Date().toISOString()}`,
rateLimitPerMinute: 120,
expiresAt, // self-expires in 10 min even if revoke never runs
meta: { canary: true, purpose: 'api-key-bypass-audit' },
});
return { token: sub.token, source: 'subscription', subId: sub.id };
} catch (err) {
const internal = process.env.INTERNAL_API_KEY;
if (internal) return { token: internal, source: 'internal', subId: null };
return { token: null, source: null, subId: null, error: err?.message };
}
}
/**
* Run the API key bypass security test. Self-contained: builds its own Solana
* payment context for the paywall-proof payment when one isn't supplied, so it can
* be invoked directly (manual test) or handed the loop's shared blockhash + keypair.
*
* @param {object} [ctx] — supplied by the loop:
* { origin, buyer, conn, blockhash, mintInfo, redis, sql, log, runId, remainingCap }
* @returns {Promise<{success, amountAtomic, txSig, responseData, signalData,
* valueExtracted, errorMsg, note}>} the outcome the loop records to x402_autonomous_log.
*/
export async function runApiKeyBypassAudit(ctx = {}) {
const runId = ctx.runId || randomUUID();
const origin = ctx.origin || env.APP_ORIGIN || 'https://three.ws';
const sql = ctx.sql || defaultSql;
const remainingCap = ctx.remainingCap ?? Number.POSITIVE_INFINITY;
const t0 = Date.now();
// A well-formed-but-unregistered key: passes the `x402_live_` namespace gate so
// the access-control hook actually runs the DB lookup (returns no row → 403),
// exercising the real invalid-key path rather than short-circuiting on prefix.
const invalidKey = `x402_live_${randomBytes(32).toString('base64url')}`;
const valid = await acquireValidKey();
const matrix = [];
try {
for (const r of AUDIT_ROUTES) {
const url = `${origin}${r.route}${r.query || ''}`;
// NO key → expect the 402 paywall.
matrix.push(classify('no-key', r, await probe(url, r, {}), 'challenge'));
// INVALID key → expect denial (403 or 402), never a free grant.
matrix.push(
classify('invalid-key', r, await probe(url, r, { 'x-api-key': invalidKey }), 'deny'),
);
// VALID key → expect a free bypass. Read-only routes only.
if (r.probeGrant && valid.token) {
matrix.push(
classify('valid-key', r, await probe(url, r, { 'x-api-key': valid.token }), 'grant'),
);
}
}
// Revocation lifecycle (subscription lane): revoke the canary, then confirm
// the SAME key is now denied on the read-only route.
if (valid.source === 'subscription' && valid.subId) {
try {
await revokeSubscription(valid.subId);
const primary = AUDIT_ROUTES.find((r) => r.probeGrant) || AUDIT_ROUTES[0];
const url = `${origin}${primary.route}${primary.query || ''}`;
matrix.push(
classify('revoked-key', primary, await probe(url, primary, { 'x-api-key': valid.token }), 'deny'),
);
} catch (err) {
log.warn('api_key_bypass_revoke_probe_failed', { message: err?.message });
}
}
} finally {
// Belt-and-suspenders cleanup: never leave a live canary key.
if (valid.source === 'subscription' && valid.subId) {
try {
await revokeSubscription(valid.subId);
} catch { /* already revoked / DB blip — the 10-min expiry still bounds it */ }
}
}
const leak = matrix.some((m) => m.verdict === 'leak');
const bypassBroken = matrix.some((m) => m.verdict === 'bypass_broken');
const leaks = matrix.filter((m) => m.verdict === 'leak').length;
const grantTested = matrix.some((m) => m.scenario === 'valid-key');
// ── Paywall-proof payment: settle the no-key 402 once to prove the full
// paywall → verify → settle path still works (the "you must pay" side of the
// test). Best-effort: a missing wallet skips this step gracefully, the free
// bypass-matrix verdict above stands on its own. ────────────────────────────
let amountAtomic = 0;
let paidTx = null;
let paidStatus = null;
let paidSettled = false;
let payNote = null;
const payRoute = AUDIT_ROUTES.find((r) => r.pay);
let buyer = ctx.buyer;
if (!buyer) {
try {
buyer = loadSeedKeypair();
} catch (err) {
payNote = `wallet_unconfigured: ${err.message}`;
log.info('api_key_bypass_pay_skipped', { reason: payNote });
}
}
if (buyer && payRoute) {
let conn = ctx.conn;
let blockhash = ctx.blockhash;
let mintInfo = ctx.mintInfo;
if (!conn || !blockhash || !mintInfo) {
try {
({ conn, blockhash, mintInfo } = await bootstrapSolanaContext({ buyer }));
} catch (err) {
payNote = `solana_preflight_failed: ${err?.message}`;
log.warn('api_key_bypass_solana_preflight_failed', { message: err?.message });
}
}
if (conn && blockhash && mintInfo) {
const url = `${origin}${payRoute.route}${payRoute.query || ''}`;
const out = await payX402({
url,
method: payRoute.method,
body: payRoute.body || null,
buyer,
conn,
blockhash,
mintInfo,
remainingCap,
});
paidStatus = out.status;
paidSettled = !!(out.paid && out.txSig);
amountAtomic = out.paid ? out.amountAtomic : 0;
paidTx = out.txSig;
if (!out.paid) payNote = out.errorMsg || 'pay_unsettled';
}
}
// ── Verdict ────────────────────────────────────────────────────────────────
let verdict;
let pass;
if (leak) {
verdict = 'bypass_leak';
pass = false;
} else if (bypassBroken) {
verdict = 'bypass_broken';
pass = false;
} else if (!grantTested) {
// Deny matrix held, but we never confirmed a valid key grants access (no key
// source / network error) — not proof of a sound bypass lane.
verdict = 'inconclusive';
pass = false;
} else {
verdict = 'secure';
pass = true;
}
const errorMsg = leak
? `api_key_bypass_leak: ${matrix.filter((m) => m.verdict === 'leak').map((m) => `${m.scenario}@${m.route}=${m.status}`).join(', ')}`
: bypassBroken
? `api_key_bypass_broken: ${matrix.filter((m) => m.verdict === 'bypass_broken').map((m) => `${m.scenario}@${m.route}=${m.status}`).join(', ')}`
: payNote && !paidSettled && verdict === 'secure'
? `paywall_payment_unverified: ${payNote}`
: null;
const primaryRoute = (AUDIT_ROUTES.find((r) => r.probeGrant) || AUDIT_ROUTES[0]).route;
const pick = (scenario, route) =>
matrix.find((m) => m.scenario === scenario && m.route === route) || null;
const validRow = pick('valid-key', primaryRoute);
const invalidRow = pick('invalid-key', primaryRoute);
const nokeyRow = pick('no-key', primaryRoute);
const revokedRow = pick('revoked-key', primaryRoute);
const durationMs = Date.now() - t0;
await storeAudit(sql, runId, {
route: primaryRoute,
valid_key_source: valid.source,
valid_status: validRow?.status ?? null,
valid_bypassed: validRow ? validRow.verdict === 'secure' : null,
invalid_status: invalidRow?.status ?? null,
invalid_denied: invalidRow ? invalidRow.verdict === 'secure' : null,
nokey_status: nokeyRow?.status ?? null,
nokey_challenged: nokeyRow ? nokeyRow.verdict === 'secure' : null,
revoked_status: revokedRow?.status ?? null,
revoked_denied: revokedRow ? revokedRow.verdict === 'secure' : null,
routes_tested: AUDIT_ROUTES.length,
leaks,
paid_status: paidStatus,
paid_settled: paidSettled,
paid_tx: paidTx,
amount_atomic: amountAtomic,
verdict,
pass,
leak,
details: matrix,
duration_ms: durationMs,
error_msg: errorMsg,
});
// A confirmed free-access leak is a security-critical event — page ops.
if (leak) {
sendOpsAlert(
'x402 API-key bypass LEAK — paywall granting free access',
`The X-API-Key bypass lane granted free access where it must not: ` +
`${matrix.filter((m) => m.verdict === 'leak').map((m) => `${m.scenario} on ${m.route} → HTTP ${m.status}`).join('; ')}. ` +
`A missing or invalid key is bypassing payment — paid endpoints can be drained for free.`,
{ signature: 'x402-api-key-bypass:leak' },
).catch(() => {});
} else if (bypassBroken) {
// Lower severity: partners with valid keys are being charged/blocked.
sendOpsAlert(
'x402 API-key bypass BROKEN — valid keys not honored',
`A valid API key failed to bypass the paywall: ` +
`${matrix.filter((m) => m.verdict === 'bypass_broken').map((m) => `${m.scenario} on ${m.route} → HTTP ${m.status}`).join('; ')}. ` +
`Subscribers are being charged for access they already pay for.`,
{ signature: 'x402-api-key-bypass:broken' },
).catch(() => {});
}
log.info('api_key_bypass_audit_complete', {
run_id: runId,
verdict,
pass,
leak,
bypass_broken: bypassBroken,
valid_key_source: valid.source,
paid_settled: paidSettled,
routes_tested: AUDIT_ROUTES.length,
duration_ms: durationMs,
});
const signalData = {
audited: true,
verdict,
pass,
leak,
bypass_broken: bypassBroken,
routes_tested: AUDIT_ROUTES.length,
leaks,
valid_key_source: valid.source,
grant_tested: grantTested,
paid_settled: paidSettled,
matrix: matrix.map((m) => ({ s: m.scenario, r: m.route, code: m.status, v: m.verdict })),
};
return {
// amountAtomic reflects ONLY the single legitimate paywall-proof payment.
success: pass,
amountAtomic,
txSig: paidTx,
responseData: {
matrix,
paid: { status: paidStatus, settled: paidSettled, tx: paidTx, note: payNote },
},
signalData,
valueExtracted: { verdict, leaks, routes_tested: AUDIT_ROUTES.length, paid_settled: paidSettled },
errorMsg,
note: verdict,
};
}
// Alias matching the pipelines convention (bazaar-warmup exports `run`).
export { runApiKeyBypassAudit as run };