idoodev-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Idoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# SDK de idoo.dev para creadores — Node.js
+
+Verifica en tu backend que cada petición proviene realmente del gateway de
+[idoo.dev](https://idoo.dev) y accede al contexto del consumidor. Sin
+dependencias; Node 16+.
+
+## Instalación
+
+```bash
+npm install idoodev-sdk
+```
+
+O copia `idoodev.js` a tu proyecto y haz `require` directo.
+
+## Uso con Express
+
+```js
+const express = require('express');
+const { middlewareExpress } = require('idoodev-sdk');
+
+const app = express();
+
+// El SDK necesita el body CRUDO (el mismo que firmó el gateway):
+app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
+
+// Rechaza con 401 todo lo que no venga firmado por idoo.dev:
+app.use(middlewareExpress(process.env.IDOO_HMAC_SECRET));
+
+app.post('/pedidos', (req, res) => {
+  // req.idoo = { consumidorId, plan, ambiente, esSandbox }
+  const tabla = req.idoo.esSandbox ? 'sandbox_pedidos' : 'pedidos';
+  res.json({ ok: true, consumidor: req.idoo.consumidorId, tabla });
+});
+
+app.listen(3000);
+```
+
+## Uso sin framework
+
+```js
+const { firmaValida, consumidor } = require('idoodev-sdk');
+
+// dentro de tu handler http.createServer, con el body crudo acumulado:
+if (!firmaValida({ secret: process.env.IDOO_HMAC_SECRET, headers: req.headers, body })) {
+  res.writeHead(401, { 'Content-Type': 'application/json' });
+  return res.end(JSON.stringify({ error: 'Firma de idoo.dev inválida' }));
+}
+const ctx = consumidor(req.headers); // { consumidorId, plan, ambiente, esSandbox }
+```
+
+## Referencia de headers del gateway
+
+| Header | Contenido |
+|---|---|
+| `X-Idoo-Signature` | `HMAC-SHA256("{timestamp}.{body}", secret)` en hexadecimal |
+| `X-Idoo-Timestamp` | Unix timestamp con el que se calculó la firma |
+| `X-Idoo-Consumer-Id` | Id del consumidor en idoo.dev |
+| `X-Idoo-Ambiente` | `sandbox` o `produccion` |
+| `X-Idoo-Plan` | Nombre del plan del consumidor |
+
+La firma cubre `timestamp.body` y caduca a los 5 minutos (`toleranciaSegundos`
+configurable). El HMAC secret se obtiene y regenera en el panel de creador.

package/idoodev.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * SDK de idoo.dev para creadores de APIs — Node.js (>= 16).
+ *
+ * Verifica que una petición entrante proviene del gateway de idoo.dev
+ * (firma HMAC-SHA256) y expone el contexto del consumidor.
+ * Sin dependencias externas.
+ */
+
+const crypto = require('crypto');
+
+const TOLERANCIA_DEFAULT = 300; // segundos
+
+/**
+ * Normaliza un objeto de headers a minúsculas.
+ */
+function normalizarHeaders(headers = {}) {
+  const salida = {};
+  for (const [nombre, valor] of Object.entries(headers)) {
+    salida[nombre.toLowerCase()] = Array.isArray(valor) ? valor[0] : String(valor);
+  }
+  return salida;
+}
+
+/**
+ * ¿La firma de la petición es válida?
+ *
+ * @param {Object} opciones
+ * @param {string} opciones.secret            HMAC secret del panel de creador
+ * @param {Object} opciones.headers           Headers de la petición (req.headers)
+ * @param {string|Buffer} opciones.body       Body CRUDO (el mismo que firmó el gateway)
+ * @param {number} [opciones.toleranciaSegundos=300]
+ * @returns {boolean}
+ */
+function firmaValida({ secret, headers, body = '', toleranciaSegundos = TOLERANCIA_DEFAULT }) {
+  const h = normalizarHeaders(headers);
+  const firma = h['x-idoo-signature'];
+  const timestamp = h['x-idoo-timestamp'];
+
+  if (!firma || !timestamp || !/^\d+$/.test(timestamp)) return false;
+  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranciaSegundos) return false;
+
+  const cuerpo = Buffer.isBuffer(body) ? body.toString('utf8') : String(body);
+  const esperada = crypto.createHmac('sha256', secret).update(`${timestamp}.${cuerpo}`).digest('hex');
+
+  const a = Buffer.from(esperada, 'utf8');
+  const b = Buffer.from(firma, 'utf8');
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+/**
+ * Contexto del consumidor a partir de los headers del gateway.
+ *
+ * @param {Object} headers req.headers
+ * @returns {{consumidorId: number|null, plan: string|null, ambiente: 'sandbox'|'produccion', esSandbox: boolean}}
+ */
+function consumidor(headers = {}) {
+  const h = normalizarHeaders(headers);
+  const id = h['x-idoo-consumer-id'];
+  const ambiente = h['x-idoo-ambiente'] === 'produccion' ? 'produccion' : 'sandbox';
+  return {
+    consumidorId: id && /^\d+$/.test(id) ? Number(id) : null,
+    plan: h['x-idoo-plan'] || null,
+    ambiente,
+    esSandbox: ambiente === 'sandbox',
+  };
+}
+
+/**
+ * Middleware para Express: rechaza con 401 las peticiones sin firma válida
+ * y agrega `req.idoo` con el contexto del consumidor.
+ *
+ * IMPORTANTE: necesita el body crudo. Configura tu parser así:
+ *   app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
+ *
+ * @param {string} secret
+ * @param {Object} [opciones]
+ * @param {number} [opciones.toleranciaSegundos=300]
+ */
+function middlewareExpress(secret, opciones = {}) {
+  return function (req, res, next) {
+    const body = req.rawBody ?? '';
+    if (!firmaValida({ secret, headers: req.headers, body, ...opciones })) {
+      return res.status(401).json({ error: 'Petición no autorizada: firma de idoo.dev inválida o ausente.' });
+    }
+    req.idoo = consumidor(req.headers);
+    next();
+  };
+}
+
+module.exports = { firmaValida, consumidor, middlewareExpress, TOLERANCIA_DEFAULT };

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "idoodev-sdk",
+  "version": "1.0.0",
+  "description": "SDK oficial de idoo.dev para creadores de APIs: verificación de la firma HMAC del gateway y contexto del consumidor.",
+  "main": "idoodev.js",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "idoodev.js"
+  ],
+  "keywords": ["idoo", "idoodev", "api", "gateway", "hmac", "marketplace"],
+  "homepage": "https://idoo.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.idoo.mx/publico/idoo-sdk-node.git"
+  }
+}