Variables de entorno

Las env vars están validadas con Zod al boot de ambos repos. Si falta una requerida, el proceso falla con un mensaje claro listando qué falta.

Precaución

Los valores reales NO están copiados acá. Esta tabla documenta nombre, propósito y ubicación. Para leer un valor: ver columna “Ubicación” + comandos en runbooks.

tcgcards-api (backend)

Definidas en src/config.ts (Zod schema). Validadas al startup del Cloud Run.

Variable	Requerida	Default	Propósito	Ubicación en prod
NODE_ENV	no	development	Entorno (development/test/production)	Cloud Run env
PORT	no	3000	Puerto Express	Cloud Run env (manejado por Cloud Run)
LOG_LEVEL	no	info	Nivel Pino (fatal/error/warn/info/debug/trace/silent)	Cloud Run env
MONGODB_URI	sí	—	Connection string Atlas	GCP Secret Manager
MONGODB_DB_NAME	no	api-cards	Database name	Cloud Run env
ADMIN_TOKEN	sí	—	Token para /admin/stats y /admin/sync/:tcg (mín 16 chars)	GCP Secret Manager
INTERNAL_JWT_SECRET	sí	—	Firma JWTs HS256 (mín 32 chars)	GCP Secret Manager. Mismo valor en Vercel.
INTERNAL_AUTH_SECRET	sí	—	Valida X-Internal-Auth (mín 32 chars)	GCP Secret Manager. Mismo valor en Vercel.
INTERNAL_CRON_SECRET	sí	—	Valida X-Internal-Cron-Secret (mín 16 chars)	GCP Secret Manager + Cloud Scheduler headers
CLOUDINARY_CLOUD_NAME	sí	—	Nombre del cloud	Cloud Run env (público, no secret)
CLOUDINARY_API_KEY	sí	—	API key	GCP Secret Manager
CLOUDINARY_API_SECRET	sí	—	API secret	GCP Secret Manager
RESEND_API_KEY	sí	—	API key Resend	GCP Secret Manager
RESEND_FROM_EMAIL	no	onboarding@resend.dev	Email “From”	Cloud Run env (típicamente notificaciones@tcgcards.cl)
WEB_PUBLIC_URL	no	https://tcgcards-web.vercel.app	URL del frontend (para links en emails)	Cloud Run env (en prod: https://tcgcards.cl)
ADMIN_NOTIFICATION_EMAIL	no	disputas@tcgcards.cl	Email para alertas admin	Cloud Run env
MP_WEBHOOK_SECRET	sí	—	Valida firma de webhooks MP	GCP Secret Manager
MP_ACCESS_TOKEN	sí	—	Access token MP (prefix APP_USR-)	GCP Secret Manager
BANK_ACCOUNT_ENCRYPTION_KEY	sí	—	Clave AES-GCM (32 bytes base64) para encrypt de cuentas bancarias	GCP Secret Manager

Cómo leer un secret de GCP Secret Manager

gcloud secrets versions access latest \
  --secret=MONGODB_URI \
  --project=api-cards-prod

Cómo agregar/modificar un secret

echo -n "NUEVO_VALOR" | gcloud secrets versions add MONGODB_URI \
  --data-file=- \
  --project=api-cards-prod

Después es obligatorio redeploy del Cloud Run para que la nueva versión se aplique. Ver runbook deploy.

tcgcards-web (frontend)

Definidas en src/lib/env.ts (Zod schema). Validadas al startup de Next.js.

Variable	Requerida	Default	Propósito	Ubicación en prod
TCGCARDS_API_URL	sí	—	URL base del backend (server-only)	Vercel env
NEXT_PUBLIC_API_URL	sí	—	Igual valor pero expuesta al client bundle (para componentes client como SearchAutocomplete)	Vercel env
NEXT_PUBLIC_SITE_URL	sí	—	URL pública del sitio (metadata, OG, canonical)	Vercel env (https://tcgcards.cl)
AUTH_SECRET	sí	—	Secreto Auth.js para cifrar cookies de sesión (mín 32 chars). Generar con openssl rand -hex 32	Vercel env
AUTH_GOOGLE_ID	sí	—	Google OAuth Client ID	Vercel env (config en Google Cloud Console)
AUTH_GOOGLE_SECRET	sí	—	Google OAuth Client Secret	Vercel env
INTERNAL_JWT_SECRET	sí	—	Igual valor que en el backend; firma JWTs propios	Vercel env. Mismo valor que el backend.
INTERNAL_AUTH_SECRET	sí	—	Igual valor que en el backend; autentica server actions → API	Vercel env. Mismo valor que el backend.

Cómo leer/modificar env vars en Vercel

Desde dashboard:

1. https://vercel.com → proyecto tcgcards-web → Settings → Environment Variables
2. Cada variable tiene environments: Production, Preview, Development. Generalmente queremos los 3 si la app local también la necesita.

Desde CLI:

# Listar
vercel env ls

# Agregar (interactive)
vercel env add NEXT_PUBLIC_SITE_URL production

# Quitar
vercel env rm NEXT_PUBLIC_SITE_URL production

Después de cambiar una env var, Vercel requiere redeploy para que aplique. Hacer push de cualquier commit o vercel --prod.

¿Y las “públicas” vs “secretas”?

• Variables con prefix NEXT_PUBLIC_ se incluyen en el bundle del browser. Nunca poner secrets ahí — cualquiera puede leerlas inspeccionando el JS.
• TCGCARDS_API_URL (sin prefix NEXT_PUBLIC_) solo existe en server-side. Se importa via import { env } from '@/lib/env' que tiene import 'server-only' arriba — si alguien la importa en un client component, falla el build.

Resumen — qué secrets son críticos y por qué

Secret	Si se filtra…
MONGODB_URI	acceso total a la BD productiva → catastrófico
MP_ACCESS_TOKEN	pueden iniciar cobros y reembolsos como nosotros → muy grave
MP_WEBHOOK_SECRET	pueden forgear webhooks para acreditar pagos falsos → muy grave
BANK_ACCOUNT_ENCRYPTION_KEY	decryptan las cuentas bancarias guardadas → catastrófico
INTERNAL_AUTH_SECRET / INTERNAL_JWT_SECRET	pueden hacer requests autenticados a la API como cualquier user → grave
INTERNAL_CRON_SECRET	pueden dispararnos los crons a discreción → moderado
AUTH_SECRET (Auth.js)	pueden forgear sesiones de cualquier user → grave
AUTH_GOOGLE_SECRET	hijack del flujo OAuth → grave
CLOUDINARY_API_SECRET	pueden subir imágenes y borrar las existentes → moderado
RESEND_API_KEY	pueden mandar emails como tcgcards → moderado (reputación)
ADMIN_TOKEN	acceso a triggers de sync de catálogo → moderado

Ver runbook rotación de credenciales para los pasos exactos cuando algo se filtre o periódicamente.