Autenticação HMAC e Segurança

Proteja os seus URLs de imagens OG assinados com HMAC usando a autenticação HMAC-SHA256 da FastOG. Este guia cobre a assinatura, validação e resolução de problemas de cada pedido, para que possa disponibilizar imagens Open Graph dinâmicas em tempo real — limitadas por subscrição, com renders sem medição (sem quota mensal de renders e sem faturação por excesso). Crie uma conta, escolha um plano Dynamic API e, em seguida, crie a sua chave de API e o segredo HMAC no painel de controlo (os renders de API pagos são limpos). Assine no seu servidor uma vez e integre em minutos.

🚀 Início Rápido

Novo na assinatura HMAC? Comece aqui:

1. Guia de Início Rápido — Comece a trabalhar em 5 minutos
2. Tutorial de JavaScript — Guia completo para programadores Node.js/Next.js
3. Todos os tutoriais de frameworks — escolha a 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, funcionalidades de segurança e respostas de erro

Tutoriais

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

  • 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 Utilização

Publicações de Blog

Gere imagens OG dinâmicas para publicações 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,
});

Testemunhos

Gere imagens OG para citações de testemunhos:

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

🔐 Segurança

Melhores Práticas

1. Guarde os segredos de forma segura — Utilize variáveis de ambiente ou um gestor de segredos
2. Nunca exponha o segredo HMAC em código do lado do cliente — Assine apenas no servidor
3. Utilize HTTPS — Previne ataques MITM
4. Rode os segredos periodicamente — Especialmente se forem comprometidos
5. Monitore assinaturas falhadas — Falhas repetidas podem indicar ataques
6. Isolamento por utilizador — Cada chave de API tem o seu próprio segredo HMAC

Obter o Seu Segredo HMAC

1. Vá a Painel de Controlo → Chaves de API
2. Crie uma nova chave de API
3. Copie o Segredo HMAC (mostrado apenas uma vez!)
4. Guarde-o 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 → Devolve a imagem OG (ou 422 se os parâmetros do modelo forem inválidos)
• ❌ Assinatura inválida → {"code": "invalid_signature"}
• ❌ Parâmetros em falta → {"code": "missing_signature"}

🛠 Resolução de Problemas

A assinatura não corresponde

1. Verifique se está a utilizar o segredo HMAC correto (consulte a chave de API no painel de controlo)
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 de segurança detalhado
• 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 obtidas pelos crawlers das redes sociais (LinkedIn, Twitter, Facebook) que não enviam cabeçalhos personalizados. A assinatura TEM de estar no URL.

P: Posso usar a mesma assinatura para vários pedidos?
R: Sim. Uma assinatura é calculada a partir da consulta exata (menos s), pelo que o mesmo URL assinado permanece válido enquanto os parâmetros não mudarem. Se alterar qualquer parâmetro (incluindo key), terá de voltar a assinar.

P: Preciso de assinar pedidos para todos os modelos?
R: Sim. Todos os pedidos para /api/v1/og exigem assinaturas HMAC.

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

P: Posso desativar a validação HMAC para serviços internos?
R: Contacte 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 de código completos
• Reveja o Guia de Assinatura HMAC para detalhes do algoritmo
• Contacte o suporte em [email protected]

Relacionados

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