Environment variables and secrets

Summary#

_worker.js reads its entire configuration from env. There is no config file in the repository that holds a live value, and there is no build step that injects one. Everything is either a binding declared in wrangler.toml, an environment variable or secret set on the Cloudflare Pages project, or a row in the platform_config D1 table that can be changed without a deploy.

This page enumerates all three, states what breaks when each is absent, and marks whether the code fails closed (refuses the request) or fails open (degrades, falls back, or silently skips). Read the fail mode before you remove anything: several gates deliberately refuse rather than guess, and one of them returns a 503 that looks like an outage.

Overview#

Four places configuration lives.

Fail closed means the request is refused with an explicit error rather than proceeding with a weaker assumption. The four gates that fail closed are MV_INTERNAL_SECRET, STRIPE_WEBHOOK_SECRET, ANTHROPIC_API_KEY on the Claude-backed routes, and PERPLEXITY_API_KEY on fact-check and citations. Each one guards something where guessing would be worse than stopping. Everything else degrades.

Bindings (declared in wrangler.toml)#

wrangler.toml is in Pages format: name = "metricvaultai", pages_build_output_dir = "dist", compatibility_date = "2024-01-01". account_id is not supported in Pages config and comes from the CLOUDFLARE_ACCOUNT_ID GitHub secret instead.

MV_INTERNAL_SECRET — the one that must be set in three places#

MV_INTERNAL_SECRET is the shared secret that separates operator and machine-to-machine calls from customer traffic. It protects:

• POST /api/cron/run — the background-job trigger
• POST /api/billing/sync — the Stripe reconciliation job
• Every /api/diag/* probe and /api/dbgdfs
• GET /api/blog/higgsfield/signin — the operator image-provider re-auth

It must be set to the same value in three places:

It fails closed, by design. mvVerifyInternalSecret returns

• 503 { "error": "Internal jobs are not configured (MV_INTERNAL_SECRET is not set)." } when the variable is absent, and
• 401 { "error": "Unauthorized internal call" } when the supplied value does not match.

Diagnostic routes have their own gate and return 403 { "ok": false, "error": "forbidden" } when the secret is unset or wrong.

The 503 symptom. Background jobs are the loudest place this shows up. The cron Worker posts to /api/cron/run with the header x-mv-internal-secret; if the secret is unset the receiver 503s and no scheduled job runs at all — Competitor Monitor stops detecting changes, rank alerts stop firing, scheduled reports never advance. The code deliberately refuses to fall back to a derivable value, because a guessable fallback would make the endpoint effectively public.

Secondary symptoms of a mismatch, in order of how often they are noticed:

Other operator variables#

Data providers and AI#

Per-task Claude model overrides#

All optional. Each falls back through a chain, so setting only AI_TEXT_MODEL moves most of them at once.

Billing#

Price ids are env-first with hardcoded fallbacks, so checkout keeps working if a variable is missing or empty.

mvStripePriceToPlan also maps retired price ids, so a SKU rename never downgrades an existing subscriber.

Authentication#

See Authentication and authorization flow for how these combine into the five authentication mechanisms.

Social publishing OAuth#

Six platforms. Each accepts several variable names, tried in order, so a secret works whether it was added with the SOCIAL_ prefix or bare, and the Meta apps can share one pair.

SOCIAL_REDIRECT_BASE overrides the OAuth callback base without a redeploy. The default is https://metricvaultai.com for any *.metricvaultai.com or *.metricvaultai.pages.dev host; otherwise the request's own origin is used. The callback shape is <base>/api/social/callback/<platform>. GET /api/diag/social prints the exact redirect_uri each platform will send, which is the value that must be whitelisted with the provider.

WEBFLOW_CLIENT_ID and SHOPIFY_CLIENT_ID are checked for presence only. The publish path is hard-disabled and always returns { "ok": false, "enabled": false, "status": "draft", "error": "Publishing is not enabled yet. Once your admin finishes connecting a platform, drafts are pushed as unpublished (never live)." }.

Higgsfield (AI image provider)#

A provider counts as configured when HIGGSFIELD_API_KEY, or both HIGGSFIELD_REFRESH_TOKEN and HIGGSFIELD_CLIENT_ID, or HIGGSFIELD_ACCESS_TOKEN is present.

GitHub Actions#

.dev.vars — local values#

.dev.vars sits at the repository root, is read by wrangler pages dev, and is git-ignored. The names present locally today are:

DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD, OPENAI_API_KEY, ANTHROPIC_API_KEY,
GEMINI_API_KEY, PERPLEXITY_API_KEY, PSI_API_KEY, SUPABASE_URL,
SUPABASE_ANON_KEY, MV_INTERNAL_SECRET, BLOG_CONSOLE_TOKEN, BLOG_PLATFORM_URL,
AI_IMAGE_PROVIDER, HIGGSFIELD_ACCESS_TOKEN, HIGGSFIELD_REFRESH_TOKEN,
HIGGSFIELD_CLIENT_ID, LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET,
X_CLIENT_ID, X_CLIENT_SECRET, FACEBOOK_CLIENT_ID, FACEBOOK_CLIENT_SECRET,
INSTAGRAM_CLIENT_ID, INSTAGRAM_CLIENT_SECRET, THREADS_CLIENT_ID,
THREADS_CLIENT_SECRET, TIKTOK_CLIENT_KEY, TIKTOK_CLIENT_SECRET

Deliberately not present locally, so those features cannot be exercised without adding them yourself: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, SUPABASE_SERVICE_KEY, RESEND_API_KEY, PEXELS_API_KEY, DEEPL_API_KEY, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, ADMIN_EMAILS.

Runtime configuration that is not an environment variable#

Some behavior is tunable without a deploy, through the D1 table platform_config. Rows are read through mvConfigAll, cached in memory, and the cache is invalidated on write.

Only an owner can write these. A non-owner receives 403 { "error": "Only an owner can change config." }, and every write is recorded in the admin audit log as config.set or config.delete. The customer-facing view of this screen is Runtime configuration.

Known discrepancies#

Recorded so nobody re-derives them from a stale comment.