Verifica firme HMAC e previeni replay attack su webhook

Per chi è

• Team che ricevono webhook da Stripe, Slack, GitHub, Shopify, Twilio o altri provider
• Applicazioni serverless su Cloudflare Workers, Vercel Functions, Netlify Functions
• Progetti che vogliono garantire autenticità e prevenire replay attack
• Team che necessitano di test realistici con payload firmati

Cosa previene

1. Webhook non verificati: Richieste accettate senza verifica HMAC, vulnerabili a spoofing.
2. Replay attack: Webhook validi riutilizzati più volte per azioni non idempotenti.
3. Timestamp manipulation: Webhook vecchi riutilizzati modificando timestamp.

Cosa include

• Middleware/verifier — Per Cloudflare Workers, Vercel Edge/Functions, Netlify Functions
• HMAC verify presets — Stripe, Slack, GitHub, Shopify, Twilio (facile aggiungere altri)
• Timestamp tolerance — Configurabile, previene replay con timestamp troppo vecchi
• Replay nonce — Sistema opzionale di nonce per prevenire replay attack
• Idempotency opzionale — Gestione idempotency key per webhook che possono arrivare duplicati
• Raw-body safe — Gestione sicura del body per verifica HMAC (no parsing prima della verifica)
• CLI signer & simulator — Genera payload firmati realistici per test
• IP allowlist opzionale — Restringe accesso a IP noti (utile per alcuni provider)
• Rate guard — Tiny leaky-bucket per limitare richieste sospette
• GitHub Action PR Gate — Verifica che i webhook endpoint usino il middleware
• Report HTML firmato — SHA-256 + PR template

Compatibilità

Piattaforme: Cloudflare Workers, Vercel Edge/Functions, Netlify Functions
Provider: Stripe, Slack, GitHub, Shopify, Twilio (altri facilmente aggiungibili)
CI/CD: GitHub Actions

Installazione in 10 minuti

# 1. Installa il pack
npm install --save-dev @merlonsec/webhook-fortress

# 2. Crea policy.yml
cat > policy.yml << EOF
webhook_fortress:
  endpoints:
    - path: /api/webhooks/stripe
      provider: stripe
      secret_env: STRIPE_WEBHOOK_SECRET
      timestamp_tolerance: 300
      require_nonce: true
    - path: /api/webhooks/github
      provider: github
      secret_env: GITHUB_WEBHOOK_SECRET
      timestamp_tolerance: 600
EOF

# 3. Usa il middleware (esempio Vercel)
# api/webhooks/stripe.ts
import { verifyWebhook } from '@merlonsec/webhook-fortress/vercel';

export default async function handler(req, res) {
  const verified = await verifyWebhook(req, {
    provider: 'stripe',
    secret: process.env.STRIPE_WEBHOOK_SECRET
  });
  
  if (!verified) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook...
}

Security model / Non-obiettivi

Non è:

• Un WAF completo (solo verifica HMAC + replay guard)
• Un sistema di autenticazione utente
• Un rate limiter avanzato (solo leaky-bucket base)
• Un servizio hosted (tutto locale)

È:

• Deterministico: stessa firma = stesso risultato
• Verificabile: report firmati SHA-256
• Modulare: facile aggiungere nuovi provider

Esempio

Vedi un esempio completo con middleware configurato e test.

Oppure scarica un report di esempio.