LeccionesCómo mantener las claves de API fuera del frontend

Minilección 15 de 30 · Cuentas y acceso

Identifica qué valor debe quedar privado

¿Para quién es esta lección?

Para quienes conectan un sitio con IA u otro servicio privilegiado. El asistente puede conectar el proyecto; necesitas entender dónde usar el secreto, no programar el servidor.

El navegador debe usar la función sin recibir el secreto del proveedor.

Propósito de esta lección

  • Pon el secreto solo en el entorno privado del servidor.
  • Ejecuta la acción sin exponer la clave a visitantes.
  • Comprueba accesos correctos y rechazados.
Explicación, ejemplo resuelto y práctica

Antes de empezar

Necesitas tu acceso API Google AI Studio y un proyecto separado de funciones Netlify. Usa el taller completo y un asistente para el entorno privado. Confirma modelo, límites de cuenta y posibles cargos antes de llamar. El laboratorio usa otro código bajo control del propietario; no es un servicio público listo.

Comprueba tus habilidades iniciales

Son habilidades útiles, no cursos obligatorios bloqueados. Si ya las tienes, empieza aquí; si no, abre la preparación. Los archivos incluidos evitan necesitar un sitio personal previo.

  1. Cómo publicar tu sitio web desde GitHub

    Conecta un repositorio de práctica al alojamiento.

Tiempo estimado: 20–32 min

Estimaciones con los archivos iniciales y las cuentas y herramientas necesarias ya listas. La configuración, las colas de publicación y las esperas de correo o DNS requieren tiempo adicional. Configurar el proveedor y la cuenta puede llevar más tiempo. El uso está sujeto a las condiciones y cuota actuales de tu cuenta.

Comprende la idea

Abre el proyecto con el asistente. Identifica la clave como dato privado y el código de práctica independiente como control del propietario para este laboratorio pequeño.

Llamar .env al archivo no basta si una compilación copia su valor a scripts públicos. Pide examinar los archivos reales del visitante.

Un ejemplo concreto

Un campo oculto sigue perteneciendo al navegador y no esconde una clave.

Abre el taller de claves API y guía run-locally.txt. Mantén clave y modelo en servidor y usa un código de acceso de práctica separado. No pongas secretos en archivos públicos ni pidas pegarlos en mensajes compartidos. Ayúdame a examinar lo que recibe el navegador y probar permisos y rechazos. Explica la evidencia observable en vez de exigirme implementar el endpoint.

Archivos de este paso

Empieza aquíArchivos del taller

Abre o descarga los archivos de abajo. Al guardar el proyecto, conserva las rutas que aparecen en sus nombres.

Pruébalo

¿Qué valor no debe llegar al visitante y qué evidencia pedirás revisar?

Mostrar una solución desarrollada

Ejemplo de privacidad: «GEMINI_API_KEY es la credencial privada del proveedor. LAB_TOKEN es otro código de práctica, no otro nombre para esa clave. El asistente inspeccionará scripts entregados y solicitudes para detectar exposición accidental».

Un nombre de archivo privado no basta: la compilación podría copiar su contenido a la salida pública. Mantendré valores reales fuera de capturas y notas compartidas.

Qué incluye una respuesta adecuada

  • Identifica la clave como secreta y el código de práctica como otra frontera de acceso.
  • Identifica archivos públicos y solicitudes del navegador como lugares donde buscar exposición accidental.
Cómo funciona (opcional)

Mantén las claves privilegiadas fuera del navegador

El navegador del visitante puede examinar cada archivo que le envías.

Un secreto de proveedor puede autorizar gastos u operaciones privilegiadas. Ponerlo en JavaScript público, un campo oculto o una variable sustituida durante la compilación del frontend sigue enviándolo al navegador.

El ejemplo plantea a Gemini una pregunta educativa fija a través de tu función de servidor. El navegador recibe la respuesta; la clave del proveedor permanece en el entorno del servidor. No todas las claves son secretas: las claves publicables de Supabase están diseñadas para usarse en el navegador junto con políticas de acceso, mientras que sus claves secretas no lo están.

Ejemplo resuelto

Abre insecure-example.txt. El valor falso es visible porque está en código entregado. Minificarlo dificultaría leerlo, pero no cambiaría quién lo recibe.

Ejercicio técnico adicional

Una clave se guarda en .env y después se inserta en el JavaScript público durante la compilación. ¿Es privada frente a los visitantes?

Mostrar una solución desarrollada

No. Su ubicación original no importa después de insertarla en un paquete público. Traslada la operación privilegiada a una función de servidor y mantén allí el valor.

  • Sigue la clave hasta el paquete entregado.
  • Distingue el entorno de servidor de la sustitución del frontend.

Paso 1 · Cómo mantener las claves de API fuera del frontend

Inicia la acción protegida

Deja configurar al asistente la ruta servidor existente.

Explicación, ejemplo resuelto y práctica

Comprende la idea

Sigue run-locally.txt y server-env.example.txt con el asistente. Confirma cuenta/modelo y condiciones, configura la clave privada en servidor y genera otro código de práctica. Ejecuta el proyecto completo y abre su URL. Estos controles son obligatorios; escribir la función es opcional.

El navegador debe llamar a tu servidor y este al proveedor en privado. Si fallan configuración, acceso o cuota, indica esa etapa sin inventar respuesta.

Un ejemplo concreto

El código del formulario no es la clave de Google.

Archivos de este paso

Empieza aquíArchivos del taller

Abre o descarga los archivos de abajo. Al guardar el proyecto, conserva las rutas que aparecen en sus nombres.

Pruébalo

¿Funcionó la acción y qué paso privado o del proveedor sigue bloqueado?

Mostrar una solución desarrollada

Ejemplo de preparación: «El proyecto completo abrió en el proxy local. Con el código de práctica, la acción servidor devolvió una breve explicación de un servidor web. Credenciales y elección de modelo quedaron en el entorno privado».

Ejemplo bloqueado: «La aplicación funciona, pero el proveedor indica cuota no disponible; no observé respuesta correcta». Comprueba modelos autorizados, límites y posibles costes antes de repetir; la lección no promete llamadas gratuitas ni ilimitadas.

Qué incluye una respuesta adecuada

  • Registra URL local real y acción autorizada o bloqueo exacto de configuración/proveedor.
  • Mantiene credencial y modelo en servidor y revisa condiciones antes de llamar.
Cómo funciona (opcional)

Pon la llamada del proveedor detrás de tu endpoint

Configura el servidor y envía solo la pequeña solicitud que necesita la función.

Lee netlify/functions/mini-explain.mjs, despliega el proyecto separado y establece GEMINI_API_KEY, GEMINI_MODEL y LAB_TOKEN en el servidor. Elige un modelo de texto con soporte en tu cuenta en vez de copiar un nombre antiguo de tutorial.

Introduce el código independiente de práctica en el formulario. El navegador llama a /.netlify/functions/mini-explain; la función llama al endpoint HTTPS fijo de Google con x-goog-api-key. El código restringe el laboratorio al propietario; no es la credencial Gemini ni un sistema completo de cuotas públicas.

GEMINI_MODEL es el ID exacto disponible en tu cuenta API, no una etiqueta de captura. generate es una función auxiliar del mismo archivo de servidor. Ni la clave ni esa función pertenecen a public/. Una solicitud válida aún puede fallar si el proveedor no tiene cuota o está caído.

Para la secuencia local completa, abre run-locally.txt: prepara el entorno privado de la raíz, vincula solo el proyecto de práctica e inicia el proxy de funciones de Netlify. server-env.example.txt enumera variables sin secretos reales. Abrir solo el HTML no ejecuta el servidor.

Utiliza la guía actual siguiente o ejecuta list-text-models.mjs desde la raíz privada del taller con tu entorno. Enumera candidatos generateContent visibles para la cuenta sin imprimir la clave. Elige un modelo de texto con soporte, comprueba condiciones y cuota y copia su ID exacto en GEMINI_MODEL del servidor.

Antes de la primera solicitud, ejecuta la herramienta de modelos y elige uno actual que admita los campos generateContent usados aquí, incluido systemInstruction. La lista identifica candidatos, no cuota ni todas sus capacidades. Todo netlify/functions/mini-explain.mjs se ejecuta en el servidor; public/app.js se entrega a cada visitante. Comprueba también el tiempo máximo de funciones del plan: el límite de 20 segundos del proveedor no puede ampliar un límite menor del alojamiento.

Ejemplo resuelto

La instrucción del proveedor es fija en el servidor, así que quien llama no puede convertir la ruta en instrucciones arbitrarias enormes. La función limita también la salida y espera como máximo 20 segundos al proveedor.

Gemini: API generateContent · Gemini: claves de API · Gemini: ID y capacidades actuales de modelos · Node.js: estado de soporte de versiones

Ejercicio técnico adicional

¿Qué dos solicitudes deben existir y cuál no debe aparecer en Network del navegador?

Mostrar una solución desarrollada

El navegador muestra su llamada a tu función y la respuesta. El servidor solicita al proveedor; la llamada Google con credenciales no debe aparecer como solicitud del navegador.

  • Ve la solicitud del navegador a la función del propio sitio.
  • Mantiene la solicitud autenticada de Google en el servidor.

Paso 2 · Cómo mantener las claves de API fuera del frontend

Comprueba privacidad y fallo juntos

Una respuesta útil no justifica una clave expuesta.

Explicación, ejemplo resuelto y práctica

Comprende la idea

Pide revisar archivos públicos entregados y peticiones buscando el secreto sin mostrarlo en registros compartidos. Prueba código incorrecto y configuración ausente en el proyecto desechable.

La clave real no debe aparecer en archivos/peticiones del navegador. Los rechazos o indisponibilidad deben seguir siendo fallos con una vía útil para reintentar.

Un ejemplo concreto

Una respuesta convincente con la clave en app.js sigue siendo una tarea incompleta.

Archivos de este paso

Empieza aquíArchivos del taller

Abre o descarga los archivos de abajo. Al guardar el proyecto, conserva las rutas que aparecen en sus nombres.

Pruébalo

¿Qué mostraron realmente la revisión pública y el intento rechazado?

Mostrar una solución desarrollada

Ejemplo de privacidad/error: «El asistente inspeccionó salida pública y petición al servidor propio; no aparecía la clave. Un código erróneo fue rechazado. Al retirar configuración privada en el proyecto desechable, la acción falló en vez de inventar una explicación».

Esto registra una frontera inspeccionada, no una auditoría completa. Si aparece una clave pública, deja de compartir esa compilación y reemplaza la credencial con el proveedor antes de volver a usarla.

Qué incluye una respuesta adecuada

  • Explica qué salida y solicitudes públicas inspeccionó sin reproducir la clave secreta.
  • Registra acceso rechazado y configuración ausente como errores.
Cómo funciona (opcional)

Verifica tanto el límite como la respuesta

Una respuesta correcta no demuestra por sí sola que la clave siguiera privada.

Busca la clave real en HTML y scripts públicos desplegados sin pegarla en capturas ni registros compartidos. Examina solicitudes del navegador: el código de práctica puede ser visible al propietario, pero la clave Gemini no.

Prueba un código incorrecto y configuración de proveedor ausente en el proyecto desechable. Un fallo debe seguir siendo fallo. Un 429 puede indicar límites de cuota o frecuencia; 401 o 403 pueden indicar acceso o configuración. No los conviertas todos en una respuesta de IA inventada.

Ejemplo resuelto

Un código correcto y ajustes válidos deben devolver una respuesta real. El mismo endpoint con código incorrecto debe rechazar antes de solicitar al proveedor.

Ejercicio técnico adicional

La respuesta funciona, pero la clave también aparece en public/app.js. ¿Está terminada la tarea?

Mostrar una solución desarrollada

No. Elimina la clave de archivos públicos, rótala porque fue expuesta, actualiza el servidor y comprueba el nuevo despliegue y el historial en busca de exposición restante.

  • No acepta una salida correcta como prueba suficiente.
  • Elimina la filtración y rota la clave expuesta.

Paso 3 · Cómo mantener las claves de API fuera del frontend

Haz un cambio limitado de forma segura

Conserva el límite del secreto al cambiar la función.

Explicación, ejemplo resuelto y práctica

Comprende la idea

Pide adaptar la operación fija para explicar DNS brevemente. Conserva modelo/clave en servidor y acceso de práctica solo del propietario.

Repite respuesta prevista y código inválido. Antes de abrir al público, decide autenticación real, controles duraderos de uso y supervisión del presupuesto.

Un ejemplo concreto

Cambiar el tema no debe trasladar datos privados a la página.

Archivos de este paso

Empieza aquíArchivos del taller

Abre o descarga los archivos de abajo. Al guardar el proyecto, conserva las rutas que aparecen en sus nombres.

Pruébalo

Entrega la acción cambiada y pruebas de privacidad/válida/inválida realmente realizadas.

Qué debes entregar: Un registro sin datos sensibles del límite de la clave y peticiones válidas/inválidas de la acción.

Mostrar una solución desarrollada

Ejemplo de cambio: «La operación fija explica DNS en dos frases. Una llamada autorizada devolvió ese tema; un código erróneo fue rechazado; la inspección pública seguía sin mostrar la clave».

«Antes de abrirlo a desconocidos, necesito autenticación real, límites duraderos y seguimiento de presupuesto». El código compartido es una frontera pequeña de laboratorio, no evidencia de servicio público completo.

Qué incluye una respuesta adecuada

  • Cambia el tema fijo a DNS conservando clave/modelo solo en servidor.
  • Repite llamadas permitidas y rechazadas y enumera controles públicos pendientes de coste/acceso.
Cómo funciona (opcional)

Tu tarea: trasladar una segunda operación fija

Al cambiar la operación, conserva deliberadamente las mismas restricciones de acceso y ejecución, sin ampliarlas por accidente.

Cambia la instrucción fija del servidor para explicar DNS en dos frases. Mantén credenciales, elección de modelo y límite de salida en el servidor; el navegador debe seguir sin conocer la clave.

Registra el resultado con códigos válidos e inválidos. Explica qué añadirías antes del acceso público: usuarios autenticados u otro límite significativo, límites persistentes de uso y monitorización del presupuesto del proveedor.

Ejemplo resuelto

Cambiar una instrucción fija demuestra que entiendes dónde se controla el proveedor. Aceptar modelos, endpoints o límites de salida arbitrarios del navegador anularía ese control.

Encontrarás el desarrollo completo de referencia en reference/assignment-walkthrough.txt. Compara sus pasos con tu resultado; rellena el registro de pruebas con observaciones de tu propio proyecto.

Ejercicio técnico adicional

Entrega la versión DNS y un registro breve de pruebas del límite.

Mostrar una solución desarrollada

En mini-explain, exclusiva del servidor, sustituye la pregunta fija sobre un servidor web por 'Explain DNS in two sentences for a beginner.' (explica DNS en dos frases para principiantes). Conserva clave y modelo en variables del servidor; la función completa de referencia muestra el cambio exacto.

Examina scripts entregados y solicitudes Network. El navegador envía su solicitud a tu función; no debe enviar GEMINI_API_KEY a Google. El código de laboratorio introducido por el propietario es distinto de la clave del proveedor.

Prueba un código incorrecto: debe rechazarse antes de llamar al proveedor. Un fallo de cuota o red debe seguir siendo un fallo honesto, no una respuesta correcta predefinida. Si expusiste un secreto real, elimínalo y rótalo; ignorar después el archivo no revoca la exposición.

  • No se entrega ningún secreto del proveedor al navegador.
  • Se rechaza el acceso incorrecto y se muestra honestamente el fallo del proveedor.

¿Te resultó útil esta lección?

Deja un me gusta o compártela con alguien a quien pueda servirle.