Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(security): lock /api/cron/* at the edge so a handler that forgets requireCron is still closed

nirholasd71b08425dd1
diff --git a/server/cron-edge-auth.mjs b/server/cron-edge-auth.mjs
new file mode 100644
index 000000000..d64fe93bd
--- /dev/null
+++ b/server/cron-edge-auth.mjs
@@ -0,0 +1,202 @@
+// The second lock on /api/cron/*, applied at the edge before the handler runs.
+//
+// Cron auth is a per-file inline call to requireCron (api/_lib/cron-auth.js),
+// which is correct and fail-closed today: tests/api/cron-auth-sweep.test.js
+// invokes all 85 handlers unauthenticated every run and requires a closed
+// status from each. But it is a convention, not a mechanism. The server's
+// filesystem phase routes every api/cron/*.js file by existing, so ONE future
+// handler that forgets the line is directly internet-invokable, and money-moving
+// sweeps live in that directory (custody attestation, buybacks, treasury
+// top-ups, wallet intents). This layer makes that single omission survivable:
+// the request never reaches the handler at all.
+//
+// Two credentials are accepted, and both stay accepted permanently. This is
+// defense in depth, not a migration with a cutover:
+//
+// 1. CRON_SECRET, exactly as the handlers validate it. The verdict comes from
+// isCronAuthorized() rather than a second comparison written here, so the
+// edge and the handler can never disagree about what a valid secret is.
+// 2. A Google-signed OIDC identity token from the Cloud Scheduler service
+// account, which is what `gcloud scheduler jobs update http
+// --oidc-service-account-email` attaches. Unlike a bearer secret this one
+// cannot be replayed off a leaked env dump: it is short-lived, signed by
+// Google, and bound to one audience.
+//
+// Both halves of the OIDC identity are required, and the email half is the
+// load-bearing one: ANY Google service account can mint an ID token for an
+// arbitrary audience, so an audience match alone authenticates nobody. The
+// token must carry a verified email in CRON_OIDC_SERVICE_ACCOUNT *and* an
+// audience in CRON_OIDC_AUDIENCE. With either var unset the OIDC path is off
+// and only the secret is accepted.
+//
+// What this layer must never do is invent a new fail-open. The one case where
+// it stands aside is "no credential is configured at all" (no CRON_SECRET, no
+// OIDC pair), which is a developer's machine: there the request falls through
+// to the handler, whose requireCron answers the single canonical 503
+// not_configured. Production, which has CRON_SECRET set, is closed here.
+
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { isCronAuthorized } from '../api/_lib/cron-auth.js';
+
+// Google's OIDC issuer and its published signing keys. Both spellings of the
+// issuer are minted by Google for identity tokens and both are legitimate.
+const GOOGLE_JWKS_URL = 'https://www.googleapis.com/oauth2/v3/certs';
+const GOOGLE_ISSUERS = ['https://accounts.google.com', 'accounts.google.com'];
+
+const CRON_PREFIX = '/api/cron/';
+
+let _jwks = null;
+
+/** The shared remote key set, created once and cached by jose thereafter. */
+function googleJwks() {
+ if (!_jwks) {
+ _jwks = createRemoteJWKSet(new URL(GOOGLE_JWKS_URL), {
+ // A key rotation must not cost every in-flight cron a 5xx, and a
+ // hostile caller must not be able to turn unknown `kid`s into an
+ // outbound request per attempt. jose's cooldown bounds the refetch
+ // rate; the timeout bounds how long a Google blip can hold a request.
+ cooldownDuration: 30_000,
+ cacheMaxAge: 600_000,
+ timeoutDuration: 4_000,
+ });
+ }
+ return _jwks;
+}
+
+/** Test hook: forget the cached key set. */
+export function _resetCronJwks() {
+ _jwks = null;
+}
+
+function list(value) {
+ return String(value || '')
+ .split(',')
+ .map((s) => s.trim())
+ .filter(Boolean);
+}
+
+/**
+ * The OIDC half of the gate, read per call so a Cloud Run env update takes
+ * effect without a redeploy. `enabled` requires BOTH lists: an audience with no
+ * service-account allowlist would accept a token any Google customer can mint.
+ */
+export function readCronOidcConfig(env = process.env) {
+ const audiences = list(env.CRON_OIDC_AUDIENCE);
+ const serviceAccounts = list(env.CRON_OIDC_SERVICE_ACCOUNT).map((s) => s.toLowerCase());
+ return { audiences, serviceAccounts, enabled: audiences.length > 0 && serviceAccounts.length > 0 };
+}
+
+/**
+ * The bearer credential, if the request carries one. Returned raw: the caller
+ * decides whether it is a secret or a JWT.
+ */
+function bearer(req) {
+ const auth = req.headers?.['authorization'];
+ if (typeof auth !== 'string' || !auth.toLowerCase().startsWith('bearer ')) return '';
+ return auth.slice(7).trim();
+}
+
+/**
+ * Three dot-separated non-empty segments. Used only to decide whether a bearer
+ * value is worth a signature verification: CRON_SECRET is also a bearer, and
+ * running JWKS resolution over every wrong secret would let an unauthenticated
+ * flood drive outbound requests.
+ */
+export function looksLikeJwt(token) {
+ const parts = String(token || '').split('.');
+ return parts.length === 3 && parts.every((p) => p.length > 0);
+}
+
+/**
+ * Verify a Google OIDC identity token against the configured audience and
+ * service account. Returns the authorized email, or null. Never throws: a
+ * malformed token, an expired one, and a Google outage are all "not authorized
+ * by this path", and the secret path has already had its turn.
+ *
+ * `keys` is injectable so tests verify a REAL RS256 signature against a real
+ * local key set rather than stubbing the verification away.
+ */
+export async function verifyCronOidc(token, config, keys = googleJwks()) {
+ if (!config.enabled || !looksLikeJwt(token)) return null;
+ try {
+ const { payload } = await jwtVerify(token, keys, {
+ issuer: GOOGLE_ISSUERS,
+ audience: config.audiences,
+ clockTolerance: 60,
+ });
+ // Google marks service-account identity tokens email_verified:true. A
+ // token without it is not the scheduler and is refused rather than
+ // trusted on the email claim alone.
+ if (payload.email_verified !== true) return null;
+ const email = String(payload.email || '').toLowerCase();
+ if (!email || !config.serviceAccounts.includes(email)) return null;
+ return email;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * The verdict for one request, with no response side effects so it is directly
+ * assertable. `allow` true means the request may proceed to its handler, which
+ * runs its own requireCron regardless: this layer only ever removes callers.
+ *
+ * @returns {Promise<{allow: boolean, via: string, status?: number}>}
+ */
+export async function cronEdgeVerdict(req, { env = process.env, keys } = {}) {
+ if (isCronAuthorized(req)) return { allow: true, via: 'cron-secret' };
+
+ const config = readCronOidcConfig(env);
+ const email = await verifyCronOidc(bearer(req), config, keys ?? googleJwks());
+ if (email) return { allow: true, via: `oidc:${email}` };
+
+ // Nothing configured anywhere: a developer's machine. Let the handler own
+ // the 503 so "not configured" has exactly one spelling in the codebase.
+ const secretConfigured = Boolean(env.CRON_SECRET);
+ if (!secretConfigured && !config.enabled) return { allow: true, via: 'unconfigured' };
+
+ return { allow: false, via: 'none', status: 401 };
+}
+
+/** Does this path route into api/cron/? */
+export function isCronPath(pathname) {
+ return typeof pathname === 'string' && pathname.startsWith(CRON_PREFIX) && pathname.length > CRON_PREFIX.length;
+}
+
+/**
+ * Express middleware. Mounted before the route table so a rewritten dest cannot
+ * carry an unauthenticated caller past it.
+ */
+export function cronEdgeAuth(options = {}) {
+ return async (req, res, next) => {
+ let pathname;
+ try {
+ pathname = new URL(req.url, 'http://internal').pathname;
+ } catch {
+ next();
+ return;
+ }
+ if (!isCronPath(pathname)) {
+ next();
+ return;
+ }
+ let verdict;
+ try {
+ verdict = await cronEdgeVerdict(req, options);
+ } catch (err) {
+ // An unexpected fault in the gate itself is not a pass. The handler's
+ // own requireCron would still refuse, but a gate that opens when it
+ // breaks is not a gate.
+ console.error('[cron-edge] verdict failed:', err?.message || err);
+ verdict = { allow: false, via: 'error', status: 401 };
+ }
+ if (verdict.allow) {
+ next();
+ return;
+ }
+ res
+ .status(verdict.status || 401)
+ .set('cache-control', 'no-store')
+ .json({ error: 'unauthorized', error_description: 'cron credential required' });
+ };
+}
diff --git a/server/index.mjs b/server/index.mjs
index 13ad635e9..18ee584ce 100644
--- a/server/index.mjs
+++ b/server/index.mjs
@@ -39,6 +39,7 @@ import { isSsrRoute, renderSsrPage } from './ssr-pages.mjs';
import { hasSeoRoute, renderSeoHead } from './seo-head.mjs';
import { isMissingShellPage } from './shell-pages.mjs';
import { hardenHeaderBag } from './csp-hashes.mjs';
+import { cronEdgeAuth } from './cron-edge-auth.mjs';
// Route resolution lives in its own module so the audit scripts
// (scripts/audit-cron-liveness.mjs) exercise the SAME resolver production runs,
// instead of a copy that can silently drift from it.
@@ -360,6 +361,15 @@ app.use(express.urlencoded({ extended: true, limit: BODY_LIMIT, verify: captureR
app.use(express.text({ type: 'text/*', limit: BODY_LIMIT }));
app.use(express.raw({ type: 'application/octet-stream', limit: BODY_LIMIT }));
+// Second lock on /api/cron/*, ahead of the route table so no rewritten dest can
+// carry an unauthenticated caller past it. Every handler there still runs its
+// own requireCron; this exists so that ONE handler forgetting the line is not
+// the same thing as publishing a money-moving sweep to the internet. It accepts
+// the CRON_SECRET the handlers already validate and, when
+// CRON_OIDC_AUDIENCE + CRON_OIDC_SERVICE_ACCOUNT are set, a Cloud Scheduler
+// OIDC token. See server/cron-edge-auth.mjs.
+app.use(cronEdgeAuth());
+
app.use(async (req, res) => {
const url = new URL(req.url, 'http://internal');
let currentPath = url.pathname;
diff --git a/tests/server-cron-edge-auth.test.js b/tests/server-cron-edge-auth.test.js
new file mode 100644
index 000000000..eba7ff160
--- /dev/null
+++ b/tests/server-cron-edge-auth.test.js
@@ -0,0 +1,249 @@
+/**
+ * The edge gate on /api/cron/* (server/cron-edge-auth.mjs).
+ *
+ * The handlers' own requireCron is swept separately by
+ * tests/api/cron-auth-sweep.test.js. What is asserted here is the second lock:
+ * that an unauthenticated caller is refused BEFORE a handler runs, that a
+ * Cloud Scheduler OIDC token is accepted only when it is genuinely signed, for
+ * the configured audience, by the configured service account, and that the gate
+ * never invents a fail-open of its own.
+ *
+ * The OIDC half runs on real RS256 crypto: a keypair is generated, tokens are
+ * signed with it, and the gate verifies them against a real local JWKS built
+ * from the public half. Nothing about the signature check is stubbed, so a
+ * regression that stopped verifying signatures would fail here rather than pass
+ * against a mock that always says yes.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterAll } from 'vitest';
+import { SignJWT, createLocalJWKSet, exportJWK, generateKeyPair } from 'jose';
+import {
+ cronEdgeAuth,
+ cronEdgeVerdict,
+ isCronPath,
+ looksLikeJwt,
+ readCronOidcConfig,
+} from '../server/cron-edge-auth.mjs';
+
+const SECRET = 'edge-gate-test-secret';
+const AUDIENCE = 'https://three.ws';
+const SCHEDULER_SA = '[email protected]';
+
+let keys;
+let signingKey;
+let otherKey;
+const savedEnv = { ...process.env };
+
+beforeAll(async () => {
+ const scheduler = await generateKeyPair('RS256');
+ const impostor = await generateKeyPair('RS256');
+ signingKey = scheduler.privateKey;
+ otherKey = impostor.privateKey;
+ const jwk = await exportJWK(scheduler.publicKey);
+ jwk.kid = 'scheduler-key';
+ jwk.alg = 'RS256';
+ // Only the scheduler's key is published: a token signed by `otherKey` has no
+ // resolvable key, which is exactly Google's position on a forged token.
+ keys = createLocalJWKSet({ keys: [jwk] });
+});
+
+beforeEach(() => {
+ process.env.CRON_SECRET = SECRET;
+ process.env.CRON_OIDC_AUDIENCE = AUDIENCE;
+ process.env.CRON_OIDC_SERVICE_ACCOUNT = SCHEDULER_SA;
+});
+
+afterAll(() => {
+ process.env = { ...savedEnv };
+});
+
+async function token({
+ key = signingKey,
+ iss = 'https://accounts.google.com',
+ aud = AUDIENCE,
+ email = SCHEDULER_SA,
+ emailVerified = true,
+ expiresIn = '5m',
+} = {}) {
+ const jwt = new SignJWT({ email, email_verified: emailVerified })
+ .setProtectedHeader({ alg: 'RS256', kid: 'scheduler-key' })
+ .setIssuer(iss)
+ .setAudience(aud)
+ .setIssuedAt();
+ if (expiresIn !== null) jwt.setExpirationTime(expiresIn);
+ return jwt.sign(key);
+}
+
+function req(headers = {}, url = '/api/cron/economy-tick') {
+ return { method: 'GET', url, headers };
+}
+
+const verdict = (r, env = process.env) => cronEdgeVerdict(r, { env, keys });
+
+describe('cron edge gate: path scoping', () => {
+ it('covers every api/cron route and nothing else', () => {
+ expect(isCronPath('/api/cron/economy-tick')).toBe(true);
+ expect(isCronPath('/api/cron/[name].js')).toBe(true);
+ // The bare directory is not a route, and no other surface is gated here:
+ // widening this prefix would 401 the whole API.
+ expect(isCronPath('/api/cron/')).toBe(false);
+ expect(isCronPath('/api/ops/health')).toBe(false);
+ expect(isCronPath('/api/crontab')).toBe(false);
+ expect(isCronPath('/')).toBe(false);
+ });
+});
+
+describe('cron edge gate: the secret path', () => {
+ it('accepts the same Bearer secret the handlers validate', async () => {
+ const out = await verdict(req({ authorization: `Bearer ${SECRET}` }));
+ expect(out).toMatchObject({ allow: true, via: 'cron-secret' });
+ });
+
+ it('accepts X-Cron-Secret, which is where the header moves when OIDC is attached', async () => {
+ // Cloud Scheduler puts its OIDC token in Authorization, so a job that gains
+ // OIDC loses the Bearer secret. cron-auth.js already accepts this spelling;
+ // if the edge did not, attaching OIDC would 401 the fleet at the edge even
+ // though the handlers were fine.
+ const out = await verdict(req({ 'x-cron-secret': SECRET }));
+ expect(out).toMatchObject({ allow: true, via: 'cron-secret' });
+ });
+
+ it('refuses a wrong secret and an absent one', async () => {
+ expect(await verdict(req({ authorization: 'Bearer nope' }))).toMatchObject({ allow: false, status: 401 });
+ expect(await verdict(req())).toMatchObject({ allow: false, status: 401 });
+ });
+});
+
+describe('cron edge gate: the OIDC path', () => {
+ it('accepts a genuine scheduler token', async () => {
+ const out = await verdict(req({ authorization: `Bearer ${await token()}` }));
+ expect(out.allow).toBe(true);
+ expect(out.via).toBe(`oidc:${SCHEDULER_SA}`);
+ });
+
+ it('accepts it even with CRON_SECRET absent, so the secret can eventually retire', async () => {
+ delete process.env.CRON_SECRET;
+ const out = await verdict(req({ authorization: `Bearer ${await token()}` }));
+ expect(out.allow).toBe(true);
+ });
+
+ it('refuses a token signed by anything but Google', async () => {
+ // The whole point of the layer: a caller who knows the audience and the
+ // service-account email still cannot mint an acceptable token.
+ const out = await verdict(req({ authorization: `Bearer ${await token({ key: otherKey })}` }));
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('refuses another service account', async () => {
+ const out = await verdict(req({ authorization: `Bearer ${await token({ email: '[email protected]' })}` }));
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('refuses a token minted for a different audience', async () => {
+ const out = await verdict(req({ authorization: `Bearer ${await token({ aud: 'https://example.com' })}` }));
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('refuses a token from a different issuer', async () => {
+ const out = await verdict(req({ authorization: `Bearer ${await token({ iss: 'https://evil.example' })}` }));
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('refuses an expired token', async () => {
+ const out = await verdict(req({ authorization: `Bearer ${await token({ expiresIn: '-10m' })}` }));
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('refuses a token whose email is not verified', async () => {
+ const out = await verdict(req({ authorization: `Bearer ${await token({ emailVerified: false })}` }));
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('is off unless BOTH the audience and the service account are configured', async () => {
+ // An audience with no allowlist would accept a token any Google customer
+ // can mint for an arbitrary audience, which authenticates nobody.
+ delete process.env.CRON_OIDC_SERVICE_ACCOUNT;
+ expect(readCronOidcConfig(process.env).enabled).toBe(false);
+ const out = await verdict(req({ authorization: `Bearer ${await token()}` }));
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('only spends a signature check on something shaped like a JWT', () => {
+ // CRON_SECRET arrives as a Bearer too; resolving keys for every wrong
+ // secret would turn an unauthenticated flood into outbound requests.
+ expect(looksLikeJwt('a.b.c')).toBe(true);
+ expect(looksLikeJwt(SECRET)).toBe(false);
+ expect(looksLikeJwt('a.b.')).toBe(false);
+ expect(looksLikeJwt('')).toBe(false);
+ });
+});
+
+describe('cron edge gate: it never invents a fail-open', () => {
+ it('stands aside only when no credential is configured at all', async () => {
+ // A developer's machine: the handler owns the 503 so "not configured" has
+ // one spelling. Production always has CRON_SECRET, so it is never here.
+ delete process.env.CRON_SECRET;
+ delete process.env.CRON_OIDC_AUDIENCE;
+ delete process.env.CRON_OIDC_SERVICE_ACCOUNT;
+ const out = await verdict(req());
+ expect(out).toMatchObject({ allow: true, via: 'unconfigured' });
+ });
+
+ it('closes as soon as a secret exists, even with OIDC unconfigured', async () => {
+ delete process.env.CRON_OIDC_AUDIENCE;
+ delete process.env.CRON_OIDC_SERVICE_ACCOUNT;
+ expect(await verdict(req())).toMatchObject({ allow: false, status: 401 });
+ });
+
+ it('closes when the key resolver itself fails', async () => {
+ const exploding = async () => { throw new Error('jwks unreachable'); };
+ const out = await cronEdgeVerdict(req({ authorization: `Bearer ${await token()}` }), {
+ env: process.env,
+ keys: exploding,
+ });
+ expect(out).toMatchObject({ allow: false, status: 401 });
+ });
+});
+
+describe('cron edge gate: the middleware', () => {
+ function res() {
+ const r = { statusCode: null, headers: {}, body: null, ended: false };
+ r.status = (c) => { r.statusCode = c; return r; };
+ r.set = (k, v) => { r.headers[String(k).toLowerCase()] = v; return r; };
+ r.json = (b) => { r.body = b; r.ended = true; return r; };
+ return r;
+ }
+
+ async function run(request) {
+ const r = res();
+ let passed = false;
+ await cronEdgeAuth({ env: process.env, keys })(request, r, () => { passed = true; });
+ return { passed, res: r };
+ }
+
+ it('lets a non-cron request through untouched', async () => {
+ const { passed, res: r } = await run(req({}, '/api/ops/health'));
+ expect(passed).toBe(true);
+ expect(r.statusCode).toBeNull();
+ });
+
+ it('lets an authenticated cron request reach its handler', async () => {
+ const { passed } = await run(req({ authorization: `Bearer ${SECRET}` }));
+ expect(passed).toBe(true);
+ });
+
+ it('answers an anonymous cron request 401 without calling next', async () => {
+ const { passed, res: r } = await run(req());
+ expect(passed).toBe(false);
+ expect(r.statusCode).toBe(401);
+ expect(r.body).toEqual({ error: 'unauthorized', error_description: 'cron credential required' });
+ // A 401 that a CDN could cache would be served back to the scheduler.
+ expect(r.headers['cache-control']).toBe('no-store');
+ });
+
+ it('gates a cron request that arrives with a query string', async () => {
+ const { passed, res: r } = await run(req({}, '/api/cron/treasury-topup?dry=1'));
+ expect(passed).toBe(false);
+ expect(r.statusCode).toBe(401);
+ });
+});