Autenticação HMAC e Segurança

Proteja suas URLs de imagem OG assinadas com HMAC usando a autenticação HMAC-SHA256 da FastOG. Este guia cobre assinatura, validação e solução de problemas de cada requisição, para que você possa gerar imagens Open Graph dinâmicas em tempo real — com acesso por assinatura e renders sem limite (sem cota mensal de renders e sem cobrança por excedente). Cadastre-se, escolha um plano da API Dinâmica e crie sua chave de API e segredo HMAC no painel (os renders pagos da API são limpos). Assine no seu servidor uma única vez e integre em minutos.

🚀 Início Rápido

Novo na assinatura HMAC? Comece por aqui:

1. Guia de Início Rápido — Comece a usar em 5 minutos
2. Tutorial de JavaScript — Guia completo para desenvolvedores Node.js/Next.js
3. Todos os tutoriais de frameworks — escolha sua 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 da Documentação

Conceitos Principais

• Guia de Assinatura HMAC — Referência completa com detalhes do algoritmo, requisitos e exemplos em JavaScript, PHP e Python
• Validação HMAC — Detalhes de implementação no servidor, recursos de segurança e respostas de erro

Tutoriais

• Tutorial de JavaScript/Node.js — Guia abrangente cobrindo:

  • Início Rápido (5 minutos)
  • Next.js App Router (3 padrões)
  • Next.js Pages Router
  • Backend Express.js
  • Node.js Puro
  • Padrões de Integração Frontend (SSG, SSR, Client-Side)
  • Testes e Depuração
  • Armadilhas Comuns

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Node.js Puro

• PHP/Laravel

• Python

• Ruby/Rails

Referência 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 Erro

🎯 Casos de Uso

Posts de Blog

Gere imagens OG dinâmicas para posts de blog:

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

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

Produtos de E-commerce

Crie imagens OG para páginas de produtos:

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

Depoimentos

Gere imagens OG para citações de depoimentos:

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

🔐 Segurança

Boas Práticas

1. Armazene segredos com segurança — Use variáveis de ambiente ou gerenciadores de segredos
2. Nunca exponha o segredo HMAC no código do cliente — Assine apenas no servidor
3. Use HTTPS — Evita ataques MITM
4. Rotacione segredos periodicamente — Especialmente se comprometidos
5. Monitore assinaturas com falha — Falhas repetidas podem indicar ataques
6. Isolamento por usuário — Cada chave de API tem seu próprio segredo HMAC

Obtendo Seu Segredo HMAC

1. Vá para Dashboard → Chaves de API
2. Crie uma nova chave de API
3. Copie o Segredo HMAC (exibido apenas uma vez!)
4. Armazene em variáveis de ambiente

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

🧪 Testes

Gerar URL de Teste

# 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);
"

Testar com curl

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

Respostas Esperadas

• ✅ Assinatura válida → Retorna a imagem OG (ou 422 se os parâmetros do template forem inválidos)
• ❌ Assinatura inválida → {"code": "invalid_signature"}
• ❌ Parâmetros ausentes → {"code": "missing_signature"}

🛠 Solução de Problemas

A assinatura não corresponde

1. Verifique se você está usando o segredo HMAC correto (confira a chave de API no painel)
2. Verifique a consulta canônica: todos os parâmetros de consulta, exceto s (incluindo key), valores codificados em rfc3986, chaves ordenadas lexicograficamente
3. Verifique se a assinatura está em hexadecimal minúsculo (64 caracteres)

📖 Recursos Adicionais

• Referência da API — Documentação completa da API
• Boas Práticas de Segurança — Guia detalhado de segurança
• Base de Conhecimento — Detalhes técnicos de implementação

❓ FAQ

P: Por que parâmetros de consulta em vez de cabeçalhos?
R: As imagens OG são buscadas por rastreadores de redes sociais (LinkedIn, Twitter, Facebook) que não enviam cabeçalhos personalizados. A assinatura DEVE estar na URL.

P: Posso usar a mesma assinatura para várias requisições?
R: Sim. Uma assinatura é calculada a partir da consulta exata (menos s), então a mesma URL assinada permanece válida enquanto os parâmetros não mudarem. Altere qualquer parâmetro (incluindo key) e você precisará assinar novamente.

P: Preciso assinar requisições para todos os templates?
R: Sim. Todas as requisições para /api/v1/og exigem assinaturas HMAC.

P: O que acontece se meu segredo HMAC for comprometido?
R: Revogue a chave de API no painel e crie uma nova. Cada chave de API tem seu próprio segredo HMAC.

P: Posso desativar a validação HMAC para serviços internos?
R: Entre em contato com o suporte para soluções personalizadas. A validação HMAC é obrigatória para todos os endpoints públicos da API.

🆘 Suporte

Precisa de ajuda?

• Consulte o Tutorial de JavaScript para exemplos completos de código
• Revise o Guia de Assinatura HMAC para detalhes do algoritmo
• Entre em contato com o suporte em [email protected]

Relacionados

• Documentação — Todos os guias e referências do FastOG
• Testador de Imagem OG Gratuito — Visualize sem uma conta
• Guia de Início Rápido — Comece a usar em 5 minutos
• Guia de Assinatura HMAC — Detalhes do algoritmo
• Validação HMAC — Validação no lado do servidor