Consegne firmate, e un’email che non dice nulla.

L’URL di un webhook è un segreto destinato a trapelare. Finisce in un ticket, in un messaggio su Slack, in una schermata dentro un documento di passaggio di consegne, nella cronologia di un portatile condiviso. Senza una firma, chiunque abbia visto quell’URL può inviarci ciò che vuole, e i vostri sistemi lo archivieranno come una risposta autentica alla consultazione. Per un comune che conta le osservazioni a una pratica edilizia, non è un problema teorico.

Per questo ogni consegna è firmata. Ogni webhook riceve un proprio segreto generato in modo casuale, mostrato nell’editor dietro un comando «mostra il segreto di firma». Noi calcoliamo un HMAC-SHA256 sui byte esatti del corpo della richiesta usando quel segreto; voi lo ricalcolate con la vostra copia e lo confrontate. Una richiesta contraffatta non supera il confronto, perché chi la contraffà non ha il segreto.

L’URL deve essere https. È imposto da un vincolo di database, non da un suggerimento nel modulo, perché un segreto di firma che viaggia su una connessione non cifrata non è un segreto.

Verificare una consegna in Node.js

Nella pratica sono due i dettagli che fanno quasi tutti i danni. Usate il corpo grezzo della richiesta, non un oggetto analizzato e riserializzato: le differenze negli spazi cambiano l’hash. E confrontate a tempo costante, così chi attacca non può ricavare la firma corretta un byte alla volta dai tempi di risposta.

import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.NOISSIME_WEBHOOK_SECRET;

// rawBody must be the exact bytes received, before any JSON parsing.
// Re-serialising a parsed object changes the whitespace and the check fails.
function isFromNoissime(rawBody, header) {
  if (typeof header !== 'string') return false;

  const expected =
    'sha256=' + createHmac('sha256', SECRET).update(rawBody).digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(header);

  // timingSafeEqual throws on a length mismatch, so compare lengths first.
  return a.length === b.length && timingSafeEqual(a, b);
}

Chiamatela prima di analizzare qualsiasi cosa. Se restituisce false, rispondete 401 e scartate la richiesta. Se restituisce true, avete una risposta che può provenire soltanto dal vostro questionario.

Aggiungete gli indirizzi che devono essere informati delle nuove risposte e riceveranno un’email all’arrivo di ciascuna. Il messaggio è in HTML personalizzato con un’alternativa in solo testo, perché sia i client testuali sia i filtri antispam leggono la parte in chiaro. Indica il questionario, riporta il totale progressivo delle risposte e rimanda ai risultati.

Ciò che non contiene sono le risposte. È una decisione, non una dimenticanza. Un’email di notifica viene inoltrata a un collega, archiviata automaticamente in una casella condivisa, sincronizzata su un telefono e conservata in un backup per anni. Immettere in quella catena le risposte in testo libero di una consultazione sparpaglia dati personali in sistemi che nessuno ha valutato, e disfa in sordina i controlli di accesso descritti nella pagina sulla sicurezza. I dati di chi risponde restano nel database, e l’email vi dice di andare a guardare.

Come i webhook, anche le notifiche sono innescate da un trigger di database, quindi seguono la risposta e non una particolare via di invio. Se non è configurato alcun indirizzo, non viene inviato nulla e non viene tentato nulla.