Antes de los ocho temas, mira la idea que los une a todos: el código es público (va a GitHub), pero los secretos quedan fuera de él, en una bóveda separada, y solo se inyectan al momento de ejecutarlo. Una capa más: la base con RLS — garantiza que, incluso con la app en línea, un usuario nunca vea los datos de otro.

Diagrama ilustrativo — seguridad en capas: ningún secreto en el código, claves solo en la bóveda e inyectadas en runtime, y la base de datos aislando los datos con RLS independientemente de los bugs de la app.

Qué es

Una variable de entorno es un valor que queda almacenado fuera del código y se inyecta en el programa solo al ejecutarlo (en runtime). El efecto es simple y poderoso: el código nunca contiene la clave. Donde antes escribirías const key = "sk-ant-abc123...", ahora escribe const key = process.env.ANTHROPIC_API_KEY — el valor real proviene del entorno, no del archivo.

Diagrama ilustrativo — el código se convierte en una referencia («dame la clave llamada ANTHROPIC_API_KEY»); el valor real vive en el entorno y nunca aparece en el repositorio.

Por qué aprender

Es el mecanismo que separa «lo que es público» (el código) de «lo que es secreto» (las claves). Sin él, todos los secretos viajan junto con el código, y basta con que un git push para que quede expuesto en GitHub para siempre, aunque lo borres después. Una variable de entorno es la base de todo lo que viene en los siguientes temas: es el fundamento de la gestión de secretos.

Conceptos clave

Qué es

El mismo secreto vive en dos lugares diferentes, según dónde se ejecute el código. En el modelo local, queda en un archivo .env en tu máquina. En el modelo nube, queda en el panel de Environment Variables de la plataforma (Trigger.dev, Vercel), que inyecta los valores en tiempo de ejecución. El detalle que sorprende a todos: el Trigger.dev no puede leer tu .env local — en la nube, solo conoce lo que registraste en el dashboard.

# .env — NUNCA vai para o GitHub (precisa estar no .gitignore)
ANTHROPIC_API_KEY=<sua-chave>
FIRECRAWL_API_KEY=<sua-chave>

# Google (acesso via OAuth — ver tópico 4)
GOOGLE_CLIENT_ID=<seu-client-id>
GOOGLE_CLIENT_SECRET=<seu-client-secret>
GOOGLE_REFRESH_TOKEN=<seu-refresh-token>
SHEET_ID=<id-da-sua-planilha>

Por qué aprender

Porque «funcionó en mi máquina» no basta: el entorno de la nube es otro, con otro almacén de secretos. Entender que son dos lugares —y que deben estar sincronizados— evita el error más frustrante del deploy. Y refuerza la regla del tema 5: puedes (y a veces debes) usar claves distintas para local y producción.

Conceptos clave

Qué es

O .env.example es un plantilla segura para hacer commit: enumera los nombres de las claves que el proyecto necesita, pero sin ningún valor. Documenta «lo que este proyecto exige» sin exponer ni un solo secreto. En cambio, el process.env es cómo el código lee estos valores en runtime: nunca los escribe directamente. En la práctica, le pides a Claude Code que cree el .env, confirmar que está en el .gitignore, generar el .env.example y ajustar el código para leer desde process.env.

# .env.example — só os NOMES, nenhum valor. Seguro de commitar.
# Copie para .env e preencha os valores reais.
ANTHROPIC_API_KEY=
FIRECRAWL_API_KEY=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REFRESH_TOKEN=
SHEET_ID=

// lê o valor do ambiente — o código fica sem segredo
const key = process.env.ANTHROPIC_API_KEY;

// falha rápido e claro se a chave não foi configurada
if (!key) {
  throw new Error("Faltou ANTHROPIC_API_KEY no ambiente (.env ou dashboard).");
}

Configure as variáveis de ambiente do projeto para estas chaves:
ANTHROPIC_API_KEY, FIRECRAWL_API_KEY, GOOGLE_CLIENT_ID,
GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN, SHEET_ID.

Faça, nesta ordem:
1. crie o arquivo .env (com placeholders <sua-chave>);
2. garanta que .env está no .gitignore;
3. crie um .env.example com as mesmas chaves SEM valores;
4. ajuste o código para ler tudo de process.env (nada hard-coded).
Não cole nenhuma chave real no chat.

Por qué aprender

Porque un proyecto sin .env.example es un rompecabezas: quien clona no sabe qué claves necesita y acaba descubriéndolo mediante prueba y error. El par .env.example + process.env resuelve esto con elegancia: documenta lo necesario y mantiene el código limpio de secretos. Es la práctica estándar de cualquier proyecto profesional.

Conceptos clave

Qué es

OAuth es el protocolo que permite delegar el acceso a un servicio (por ejemplo, Google) sin exponer tu contraseña. En vez de darle tu contraseña a la app, autorizas a la app a actuar en tu nombre y esta recibe tokens. El refresh token es el token de larga duración que renueva el acceso por sí solo cuando expira el acceso temporal — es lo que mantiene funcionando a un agente alojado sin que tengas que volver a iniciar sesión cada vez.

Por qué aprender

Porque así es como los agentes en la nube acceden a Google Sheets, Drive y Gmail sin que abras el navegador en cada ejecución. El camino concreto: crear credenciales OAuth (client ID + secret) en Google Cloud Console y obtener un refresh token. El flujo estándar por OAuth Playground a veces falla con «access blocked» o «request is invalid»; la alternativa que funciona es un script de terminal que imprime una URL de autorización y, al final, te devuelve el refresh token para que lo pegues en el .env y en las variables de entorno de Trigger.dev.

Conceptos clave

Qué es

Tres reglas innegociables para manejar secretos. Un: nunca pegues claves de API en el chat de la IA: el chat no es el lugar para un secreto. Dos: nunca hagas commit del .env en GitHub: una vez en el historial, considera que la clave quedó expuesta. Tres: rota/regenera las claves periódicamente y, de ser posible, usa claves diferentes para local y producción. La imagen mental: trata una clave de API como el acceso a una tarjeta de crédito.

El ciclo de vida de un secreto seguro

Por qué aprender

Porque la mayoría de los incidentes de seguridad con apps de IA no se deben a un hacker sofisticado: se deben a una clave pegada en el lugar equivocado. Interiorizar estas tres reglas es lo que diferencia un prototipo descuidado de un producto que puedes dejar funcionando con tranquilidad.

Conceptos clave

Qué es

RLS (Row-Level Security) son reglas que viven dentro de la propia base de datos (en Supabase, por ejemplo) e impiden que un usuario vea las filas de otro, incluso si hay un bug en el frontend. Es una capa extra de defensa: la base de datos protege los datos independientemente de la app. Si tu código pide por error "todos los leads", la base de datos, con RLS, devuelve solo los leads de ese usuario.

Diagrama ilustrativo — con RLS, la regla de aislamiento reside en la base de datos; un error en el frontend ya no puede filtrar los datos de otro usuario.

-- liga o Row-Level Security na tabela
alter table leads enable row level security;

-- política: cada usuário só enxerga as próprias linhas
-- (compara o dono da linha com o usuário autenticado)
create policy "cada um vê só os seus leads"
on leads
for select
using ( user_id = auth.uid() );

Por qué aprender

Porque vas a construir rápido, y el código hecho rápido tiene errores. RLS es el cinturón de seguridad: aunque el frontend falle, la base de datos no permite que un usuario vea los datos de otro. Es la diferencia entre «un error molesto» y «una filtración de datos que se vuelve noticia».

Conceptos clave

Qué es

Antes de dejar la app en producción, le pides a la IA que actúa como especialista en seguridad y revisa el proyecto con una lista de cuatro puntos: rutas protegidas, ninguna clave expuesta en el frontend, secretos solo en variables de entorno e RLS habilitado. Una buena práctica es limpiar la conversación antes (el contexto fresco audita mejor) y, después, corregir todo lo que falle.

Aja como especialista de segurança e audite este app.
Verifique, item por item:
1. rotas protegidas (nada sensível acessível sem login);
2. nenhuma chave de API exposta no frontend / no bundle;
3. segredos APENAS em variáveis de ambiente (nada hard-coded);
4. RLS habilitado em todas as tabelas com dados de usuário.

Liste o que FALHAR e, para cada falha, diga exatamente
como corrigir. Não invente: se não der pra confirmar, diga.

Por qué aprender

Porque con vibe coding construyes rápido y es fácil dejar una puerta abierta sin darte cuenta. Una auditoría explícita, con checklist, cuesta poco (un prompt) y detecta justamente lo que se pasó por alto. Es el «trust but verify» aplicado a la seguridad: no confíes en que quedó seguro; verifícalo.

Conceptos clave

Qué es

Un app abierta — sin autenticación, es un riesgo financiero concreto: cualquiera que tenga la URL puede activar tu workflow y consumir tus tokens de IA. Como pagas por el uso, el uso de otras personas se carga a tu cuenta. Por eso, no dejes una app sin inicio de sesión funcionando en producción por mucho tiempo: antes de compartirla, agrega autenticación (Supabase) y límites de uso.

Por qué aprender

Porque es el disparador natural para el siguiente módulo. Agregar inicio de sesión con Supabase y límites de uso no es solo seguridad: es el primer paso de un modelo de negocio: si vas a controlar quién lo usa y cuánto, estás a un paso de cobrar por ello. Este razonamiento motiva el modelo freemium con Stripe que ves en 6.3.

Conceptos clave