Proteger una API con autorización es uno de los pasos fundamentales para construir aplicaciones seguras y escalables. En esta sesión se muestra cómo implementar middlewares de autorización JWT en un backend construido con Hono sobre Cloudflare Workers, separando rutas públicas de rutas protegidas mediante scopes específicos.
¿Cómo funciona la autorización con JWT y scopes?
El punto de partida es un backend que expone varios endpoints y requiere distintos niveles de acceso. Al intentar hacer una petición sin token, la API responde con un error de autorización [0:09]. Para obtener acceso, primero se genera un token JWT utilizando un secret de administrador configurado como variable de entorno.
Cada token se genera con un scope determinado, lo que define a qué recursos puede acceder el usuario. Por ejemplo, un token con scope read self solo permite consultar el correo propio [0:22], mientras que un token con scope read all habilita el acceso a la lista completa de correos registrados [1:06]. Un token administrativo puede acceder a ambos recursos.
¿Qué es un middleware y cómo se implementa en Hono?
Un middleware es una función que intercepta la petición antes de que llegue al controlador final. En Hono, esta función recibe el objeto c (context), que da acceso a todas las propiedades de Cloudflare, y una función llamada next [2:07].
- Si la validación detecta un error, se responde inmediatamente con ese error.
- Si todo es correcto, se ejecuta
next() y la petición continúa hacia la función de la ruta correspondiente.
Este patrón permite separar la lógica de autorización del código de negocio de cada endpoint, manteniendo el código limpio y reutilizable.
¿Cómo se organizan las rutas públicas y protegidas?
En el archivo index, las rutas se dividen en grupos [1:29]:
- Ruta de auth: genera el JWT. Recibe el secret, lo valida contra una variable de entorno, recibe el scope y devuelve un token firmado en formato JSON.
- Rutas públicas: no requieren JWT. Por ejemplo, registrar un correo electrónico entra sin autenticación.
- Rutas protegidas: agrupadas en un router que valida scopes diferentes antes de permitir el acceso.
Cada ruta protegida declara explícitamente qué scope necesita. Esto se logra configurando el middleware con el scope requerido, como read all o read self [1:49].
¿Cómo se autodocumentan y validan los parámetros con Zod y OpenAPI?
Utilizando los objetos de Soho en Hono, se logra autodocumentar y autovalidar los parámetros de cada ruta [2:33]. Por ejemplo, el email se recibe como parámetro de la URL, no en el body de la petición. Esto permite que la documentación generada automáticamente refleje la estructura real de la API.
Los servicios asociados a cada ruta son sencillos. El servicio que lista todos los correos devuelve un mock con un diccionario de datos quemados [2:55]. El de búsqueda por email filtra dentro de esa misma lista. Aunque aún no hay persistencia, la estructura está preparada para escalar.
¿Qué patrones de arquitectura facilitan la escalabilidad?
La separación en carpetas para middlewares, rutas y servicios es un buen punto de partida [3:08]. Sin embargo, cuando el proyecto crece con múltiples dominios, se pueden aplicar otros patrones de código limpio y reorganizar las carpetas según las necesidades de la solución.
Algunos detalles importantes sobre las respuestas HTTP:
- Se puede responder en formato JSON, texto plano u otros tipos según se requiera [3:30].
- El status code se personaliza; por ejemplo, un
404 cuando no se encuentra un registro [3:42].
- La documentación de Hono ofrece opciones adicionales de routing, middlewares como CORS, autenticación bearer y autenticación básica [3:52].
¿Qué incluye el despliegue actual del proyecto?
Tras hacer merge del pull request, los servicios se desplegaron junto con un nuevo front-end [4:08]. Este incluye una página con server-side rendering que muestra datos ejecutados directamente en el servidor. Un detalle relevante es que ciertos headers de Cloudflare, como los de geolocalización, solo se populan correctamente en producción, no en el entorno local con workerd [4:21].
Las funcionalidades disponibles hasta ahora incluyen: generador de tokens JWT, registro de correo, listado de todos los correos y búsqueda individual por correo [4:42].
