Autenticación y seguridad HMAC

Protege tus URLs de imágenes OG firmadas con HMAC con la autenticación HMAC-SHA256 de FastOG. Esta guía cubre la firma, validación y resolución de problemas de cada solicitud, para que puedas generar imágenes Open Graph dinámicas sobre la marcha — con acceso restringido por suscripción y renders sin límite (sin cuota mensual de renders ni facturación por exceso). Regístrate, elige un plan de Dynamic API y crea tu clave de API y secreto HMAC en el panel de control (los renders de API de pago son limpios). Firma en tu servidor una vez e intégralo en minutos.

🚀 Inicio rápido

¿Nuevo en la firma HMAC? Empieza aquí:

1. Guía de inicio rápido — Ponte en marcha en 5 minutos
2. Tutorial de JavaScript — Guía completa para desarrolladores de Node.js/Next.js
3. Todos los tutoriales de frameworks — elige tu stack:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Node.js puro
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Índice de Documentación

Conceptos Básicos

• Guía de Firmas HMAC — Referencia completa con detalles del algoritmo, requisitos y ejemplos en JavaScript, PHP y Python
• Validación HMAC — Detalles de implementación en el servidor, características de seguridad y respuestas de error

Tutoriales

• Tutorial de JavaScript/Node.js — Guía completa que cubre:

  • Inicio Rápido (5 minutos)
  • Next.js App Router (3 patrones)
  • Next.js Pages Router
  • Backend con Express.js
  • Node.js Puro
  • Patrones de Integración Frontend (SSG, SSR, Lado del Cliente)
  • Pruebas y Depuración
  • Errores Comunes

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Node.js Puro

• PHP/Laravel

• Python

• Ruby/Rails

Referencia Rápida

Algoritmo

method = "GET"
path = "/api/v1/og"
canonicalQuery = every query param EXCEPT `s` (including `key`): array values sorted too; each pair rfc3986Encode(key)=rfc3986Encode(value); pairs sorted lexicographically and joined with "&"

message = method + path + "\n" + canonicalQuery
signature = hex(HMAC-SHA256(message, hmac_secret))

URL: /api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>

Parámetros de Consulta

Códigos de Error

🎯 Casos de uso

Entradas de blog

Genera imágenes OG dinámicas para entradas de blog:

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});

// <meta property="og:image" content="{ogUrl}" />

Productos de comercio electrónico

Crea imágenes OG para páginas de producto:

const ogUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});

Testimonios

Genera imágenes OG para citas de testimonios:

const ogUrl = generateSignedOgUrl({
    template: "testimonial",
    author_name: user.name,
    author_avatar: user.avatarUrl,
    quote: user.bio,
});

🔐 Seguridad

Buenas prácticas

1. Almacena los secretos de forma segura — Usa variables de entorno o un gestor de secretos
2. Nunca expongas el secreto HMAC en código de cliente — Firma solo en el servidor
3. Usa HTTPS — Evita ataques MITM
4. Rota los secretos periódicamente — Especialmente si se han visto comprometidos
5. Supervisa las firmas fallidas — Los fallos repetidos pueden indicar ataques
6. Aislamiento por usuario — Cada clave de API tiene su propio secreto HMAC

Cómo obtener tu secreto HMAC

1. Ve a Panel de control → Claves de API
2. Crea una nueva clave de API
3. Copia el Secreto HMAC (¡solo se muestra una vez!)
4. Guárdalo en variables de entorno

# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Pruebas

Generar URL de prueba

# Node.js
node -e "
const crypto = require('crypto');
const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
const all = { title: 'Test', key: 'sk_quick_123abc' };
const pairs = [];
for (const [k, v] of Object.entries(all)) for (const vv of Array.isArray(v) ? v : [v]) pairs.push(enc(k) + '=' + enc(vv));
pairs.sort();
const canonical = pairs.join('&');
const sig = crypto.createHmac('sha256', 'YOUR_HMAC_SECRET').update('GET/api/v1/og\n' + canonical).digest('hex');
console.log('https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=' + sig);
"

Probar con curl

curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>"

Respuestas esperadas

• ✅ Firma válida → Devuelve la imagen OG (o 422 si los parámetros de la plantilla no son válidos)
• ❌ Firma no válida → {"code": "invalid_signature"}
• ❌ Parámetros faltantes → {"code": "missing_signature"}

🛠 Solución de problemas

La firma no coincide

1. Verifica que estás usando el secreto HMAC correcto (consulta la clave de API en el panel de control)
2. Comprueba la consulta canónica: todos los parámetros de consulta excepto s (incluido key), valores codificados con rfc3986, claves ordenadas lexicográficamente
3. Verifica que la firma sea hexadecimal en minúsculas (64 caracteres)

📖 Recursos adicionales

• Referencia de la API — Documentación completa de la API
• Prácticas recomendadas de seguridad — Guía de seguridad detallada
• Base de conocimientos — Detalles técnicos de implementación

❓ FAQ

P: ¿Por qué parámetros de consulta en lugar de cabeceras?
R: Las imágenes OG se obtienen mediante rastreadores de redes sociales (LinkedIn, Twitter, Facebook) que no envían cabeceras personalizadas. La firma DEBE estar en la URL.

P: ¿Puedo usar la misma firma para varias solicitudes?
R: Sí. Una firma se calcula a partir de la consulta exacta (menos s), por lo que la misma URL firmada sigue siendo válida mientras los parámetros no cambien. Si cambias cualquier parámetro (incluido key), debes volver a firmar.

P: ¿Necesito firmar las solicitudes para todas las plantillas?
R: Sí. Todas las solicitudes a /api/v1/og requieren firmas HMAC.

P: ¿Qué ocurre si mi secreto HMAC se ve comprometido?
R: Revoca la clave de API en el panel de control y crea una nueva. Cada clave de API tiene su propio secreto HMAC.

P: ¿Puedo desactivar la validación HMAC para servicios internos?
R: Contacta con soporte para soluciones personalizadas. La validación HMAC es obligatoria para todos los endpoints públicos de la API.

🆘 Soporte

¿Necesitas ayuda?

• Consulta el Tutorial de JavaScript para ver ejemplos de código completos
• Revisa la Guía de Firmas HMAC para conocer los detalles del algoritmo
• Contacta con el soporte en [email protected]

Relacionado

• Documentación — Todas las guías y referencias de FastOG
• Probador de imágenes OG gratuito — Vista previa sin cuenta
• Guía de inicio rápido — Ponte en marcha en 5 minutos
• Guía de firma HMAC — Detalles del algoritmo
• Validación HMAC — Validación en el servidor