Guía de integración

Es un prompt autocontenido: no necesita que tu IA conozca idoo.dev de antemano, incluye todo el contrato (headers, fórmula de la firma, ejemplos en PHP/Node y la lógica genérica para cualquier otro lenguaje). Pégalo dentro de tu propio proyecto para que el asistente detecte tu framework y adapte el código directo.

# Integra mi API con el gateway de idoo.dev

Voy a publicar esta API en idoo.dev (https://idoo.dev), un marketplace que
funciona como middleware: controla la autenticación de los consumidores,
sus planes, límites de uso (rate limit) y cuotas. Todo el tráfico de mis
consumidores llega a mi API a través del gateway de idoo.dev, nunca directo.

Tu tarea: adaptar este proyecto para que solo acepte peticiones que
realmente vengan del gateway de idoo.dev, verificando una firma HMAC-SHA256
en cada petición entrante, y exponer al resto del código el contexto del
consumidor (id, plan, ambiente) que el gateway envía en los headers.

## Cómo funciona el gateway

Un consumidor llama a `https://api.idoo.dev/v1/{slug-de-mi-api}/{mi-ruta}`
con su propia API key de idoo.dev. El gateway valida esa key, la
suscripción, la cuota del plan y el rate limit — mi API NO necesita
implementar nada de eso. Si todo es válido, reenvía la petición a la URL
base que configuré en el panel (método, query, body y Content-Type
intactos) agregando estos headers:

| Header               | Contenido                                                          |
|----------------------|---------------------------------------------------------------------|
| `X-Idoo-Signature`   | HMAC-SHA256 de `"{timestamp}.{body_crudo}"` con mi secret, en hex  |
| `X-Idoo-Timestamp`   | Unix timestamp usado para calcular la firma (caduca a los 5 min)  |
| `X-Idoo-Consumer-Id` | Id del consumidor en idoo.dev                                      |
| `X-Idoo-Ambiente`    | `sandbox` o `produccion`, según la key que usó el consumidor       |
| `X-Idoo-Plan`        | Nombre del plan contratado por el consumidor                       |

Mi API debe:

1. Verificar `X-Idoo-Signature` recalculando `HMAC-SHA256("{timestamp}.{body}", MI_SECRET)`
   y comparando en **tiempo constante**. Rechazar con 401 si no coincide o
   si el timestamp tiene más de 5 minutos de antigüedad.
2. Rechazar con 401 cualquier petición que NO traiga esos headers (tráfico
   directo, sin pasar por el gateway).
3. Usar `X-Idoo-Consumer-Id` como identificador de "tenant" en vez de
   manejar mis propios usuarios/API keys — ese trabajo ya lo hace idoo.dev.
4. (Opcional pero recomendado) Separar datos por `X-Idoo-Ambiente`: sandbox
   para pruebas, producción para datos reales — con el patrón que uses tú
   (prefijo de tabla, base de datos separada, lo que aplique a tu stack).

## Qué hacer, paso a paso

1. Detecta el lenguaje/framework de este proyecto y el punto de entrada de
   cada endpoint HTTP que se vaya a exponer a través de idoo.dev.
2. Si el proyecto es **PHP**: usa el SDK oficial `idoo/idoodev-sdk`
   (documentación completa en https://idoo.dev/sdk/) — un solo archivo sin
   dependencias, instalable por Composer o copiándolo directo:
   ```php
   $peticion = \IdooDev\Peticion::desdeGlobals('TU_HMAC_SECRET');
   $peticion->requerir(); // responde 401 y termina si la firma no es válida

   $consumidorId = $peticion->consumidorId(); // int
   $plan         = $peticion->plan();         // "Free", "Pro", ...
   $ambiente     = $peticion->ambiente();     // 'sandbox' | 'produccion'
   ```
3. Si es **Node.js / Express**: usa `idoodev-sdk` (https://idoo.dev/sdk/):
   ```js
   const { middlewareExpress } = require('idoodev-sdk');
   app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
   app.use(middlewareExpress(process.env.IDOO_HMAC_SECRET));
   // req.idoo = { consumidorId, plan, ambiente, esSandbox }
   ```
4. Para cualquier **otro lenguaje** (Python, Go, Ruby, Java, .NET...),
   implementa la verificación manual siguiendo exactamente esta lógica:
   ```
   firma_esperada = hmac_sha256(secret, f"{timestamp}.{body_crudo}")
   if not comparar_tiempo_constante(firma_esperada, header["X-Idoo-Signature"]):
       return 401
   if abs(ahora() - int(timestamp)) > 300:
       return 401
   ```
   Usa la función de comparación en tiempo constante de tu lenguaje
   (`hmac.compare_digest` en Python, `crypto.timingSafeEqual` en Node,
   `hash_equals` en PHP, etc.) — nunca compares con `==` directo, es
   vulnerable a timing attacks.
5. Agrega esta verificación como middleware/guard al inicio de CADA
   endpoint expuesto a idoo.dev (o de forma global si todos los endpoints
   del proyecto son para idoo.dev).
6. El secret HMAC se obtiene en el panel de creador de idoo.dev (se puede
   regenerar ahí si se compromete) — configúralo como variable de entorno,
   nunca lo hardcodees en el código ni lo subas al repositorio.
7. Mis respuestas NO tienen que seguir un formato impuesto por idoo.dev —
   el gateway reenvía mi respuesta tal cual al consumidor (status, headers,
   body). Aun así, usa un sobre JSON consistente en todos los endpoints,
   por ejemplo:
   ```json
   { "valid": true, "status": 200, "message": "...", "data": { }, "timestamp": "..." }
   ```
8. Escribe (o actualiza) un archivo `docs.md` en la raíz del proyecto
   documentando cada endpoint: método, ruta relativa, body de ejemplo,
   respuesta de ejemplo y una tabla de códigos de error. Ese archivo lo
   subiré tal cual al panel de creador para generar la documentación
   pública (soporta Markdown con tablas y bloques de código — GitHub
   Flavored Markdown).
9. Al terminar, dame un resumen de: (a) qué endpoints quedaron protegidos,
   (b) qué variable de entorno debo configurar con el secret, (c) si el
   proyecto ya corre en algún dominio público que pueda usar como URL base
   al registrar la API en idoo.dev.

## No hagas esto

- No implementes tu propio sistema de usuarios, API keys, límites de uso o
  cobro — todo eso ya existe en idoo.dev y sería trabajo duplicado.
- No expongas ningún endpoint sin la verificación de firma: cualquiera que
  conozca tu URL podría llamarte directo y saltarse los planes y límites
  de idoo.dev.
- No devuelvas errores 500 genéricos ante fallos de validación de negocio:
  usa 400/422 con mensajes claros, como cualquier API bien diseñada.