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.
Cron authentication: the two locks on /api/cron/*
The Cloud Scheduler jobs declared in vercel.json (its crons array is the
source of truth for how many) drive handlers that move real money: custody attestation, buybacks, treasury top-ups, payouts, wallet
intents, the dead-man switch. Anything that can invoke those can spend from
them, so the gate is layered and both layers fail closed.
Lock 1: the handler gate (api/_lib/cron-auth.js)
Every file under api/cron/ opens with if (!requireCron(req, res)) return;.
That helper is the only place the credential is compared:
CRON_SECRETunset is a503 not_configured, never a pass. A misconfigured deploy must not expose a money-moving sweep.- The comparison is constant time, so the secret has no timing oracle.
Authorization: Bearer <secret>andX-Cron-Secret: <secret>are both accepted, and both carry the same secret. The second spelling is not historical clutter: it is what makes lock 2 attachable at all (see below).- An inbound header like
x-vercel-cronis never authorization on its own.
tests/api/cron-auth-sweep.test.js invokes every handler in the directory with
no credential on every test run and requires a closed status from each, plus
each of the [name].js dispatcher's routes individually. The sweep is
behavioral, not a grep, so a guard that exists but is never called still fails
it. It also runs against four deliberately broken fixtures (no guard, a verdict
computed and discarded, a 200 above the guard, a handler that hangs) and must
reject all four, so a sweep that quietly degraded into a no-op cannot pass.
Lock 2: the edge gate (server/cron-edge-auth.mjs)
Lock 1 is a convention, not a mechanism. The server's filesystem phase routes
every api/cron/*.js file by its existence, so one future handler that forgets
the line is directly internet-invokable. The edge gate makes that omission
survivable: mounted ahead of the route table in server/index.mjs, it refuses
the request before any handler is imported.
It decides what counts as a cron path on the same view of the URL the API
dispatcher routes on (apiSegments in server/route-resolve.mjs): empty
segments dropped and each segment percent-decoded. Matching the raw string let
/api//cron/x and /api/%63ron/x slip past this gate while still dispatching
to api/cron/x.js; both are gated now, and a path that will not decode is
treated as gated rather than waved through.
It accepts two credentials, permanently. This is defense in depth, not a migration with a cutover:
CRON_SECRET, viaisCronAuthorized()from the same module lock 1 uses, so the edge and the handler can never disagree about what a valid secret is.- A Cloud Scheduler OIDC identity token: Google-signed, short-lived, bound to one audience, and unusable from a leaked env dump.
Both halves of the OIDC identity are required, and the email 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
email_verified: true, an 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.
| Var | Value to set | Effect |
|---|---|---|
CRON_OIDC_AUDIENCE |
the Cloud Run service URL | audiences the edge will accept, comma-separated |
CRON_OIDC_SERVICE_ACCOUNT |
[email protected] |
service-account emails the edge will accept, comma-separated |
Neither var is set on three-ws-api today, so the OIDC path is currently off and
the edge accepts only CRON_SECRET; the live Cloud Scheduler jobs still
authenticate with Authorization: Bearer $CRON_SECRET. The runbook below is the
step that turns the second credential on, and it has not been run yet.
The one case where the edge stands aside is "no credential configured at all"
(no CRON_SECRET, no OIDC pair), which is a developer's machine: the request
falls through so requireCron owns the single canonical 503. Production always
has CRON_SECRET, so production is always closed here. A fault inside the gate
itself is a 401, not a pass.
Covered by tests/server-cron-edge-auth.test.js, which verifies real RS256
signatures against a locally generated key set: a forged token, a wrong
audience, a wrong issuer, a wrong service account, an unverified email, and an
expired token are each refused, and a genuine one is accepted. It also pins the
path spellings above (doubled slashes, a percent-encoded cron) as gated.
Attaching the OIDC token (the fleet-wide step)
The trap: Cloud Scheduler puts its OIDC token in the Authorization header.
The jobs today authenticate with Authorization: Bearer $CRON_SECRET, so naively
adding --oidc-service-account-email DESTROYS the credential every job runs
on, and they 401 together. The secret must move to X-Cron-Secret in the same
update. node scripts/create-gcp-scheduler.mjs --oidc does exactly that, and
tests/cron-scheduler-sync.test.js pins the pairing so the two can never be
emitted apart.
Order matters. Attach the token first and require it second, never the reverse:
# 1. Teach the service which identity to trust (merge, never --set-env-vars).
gcloud run services update three-ws-api \
--region us-central1 --project aerial-vehicle-466722-p5 \
--update-env-vars \
CRON_OIDC_AUDIENCE=https://three-ws-api-lp642k3kpa-uc.a.run.app,\
CRON_OIDC_SERVICE_ACCOUNT=three-ws@aerial-vehicle-466722-p5.iam.gserviceaccount.com
# 2. Migrate ONE job and prove it before touching the fleet.
node scripts/create-gcp-scheduler.mjs --oidc --only uptime-check
gcloud scheduler jobs run cron--api-cron-uptime-check \
--location us-central1 --project aerial-vehicle-466722-p5
gcloud scheduler jobs describe cron--api-cron-uptime-check \
--location us-central1 --project aerial-vehicle-466722-p5 \
--format='value(status.code,lastAttemptTime,state)' # empty code = success
# 3. Migrate the rest.
node scripts/create-gcp-scheduler.mjs --oidc
# 4. Confirm nothing is failing, over a window that covers the slowest cron.
gcloud logging read \
'resource.type="cloud_run_revision"
resource.labels.service_name="three-ws-api"
httpRequest.requestUrl:"/api/cron/"
httpRequest.status=401' \
--project aerial-vehicle-466722-p5 --freshness=2h --limit=20
The sync reads CRON_SECRET from --env-file, then process.env, then the
live Cloud Run service, so on an authenticated machine step 2 needs no argument.
Every deploy also runs npm run deploy:gcp:sync-crons
(create-gcp-scheduler.mjs --missing-only), which creates a job for each newly
declared cron and never touches an existing one. It does not pass --oidc, so
after the migration a cron added later starts on the Bearer secret, which the
edge still accepts. Re-run step 3 to move it onto the token.
Rollback is one command and needs nothing else: node scripts/create-gcp-scheduler.mjs (no --oidc) puts the Bearer secret back on
every job. The edge keeps accepting it, because it never stopped.
Related
api/_lib/cron-auth.js,server/cron-edge-auth.mjs,scripts/create-gcp-scheduler.mjs- gcp-production.md for the service, env, and deploy story
npm run check:cron-drift(declared vs live jobs) andnpm run audit:cron-liveness(jobs that exist but never fire)
Anonymous upload size enforcement
Anonymous presigned PUTs (capture/uploads/, scene/shares/,
motion-swap/uploads/, forge/uploads/, print/uploads/) cannot sign
ContentLength without breaking the browser CORS preflight, so the declared
size is only checked at presign time. /api/cron/anon-upload-sweep (hourly,
api/cron/anon-upload-sweep.js, logic in api/_lib/anon-upload-sweep.js)
lists each prefix, HEAD-confirms objects over their ceiling and deletes them.
Ceilings live in api/_lib/anon-upload-limits.js, shared with the presign
handlers. Only objects modified in the last 26 hours are judged.