{"id":133,"date":"2026-06-14T20:46:28","date_gmt":"2026-06-14T20:46:28","guid":{"rendered":"https:\/\/shattered.io\/it\/2026\/06\/14\/totp-2fa-nodejs\/"},"modified":"2026-06-14T20:47:55","modified_gmt":"2026-06-14T20:47:55","slug":"totp-2fa-nodejs","status":"publish","type":"post","link":"https:\/\/shattered.io\/it\/totp-2fa-nodejs\/","title":{"rendered":"TOTP 2FA in Node.js: Autenticatore in 12 Step [2026]"},"content":{"rendered":"\n

L’autenticazione a due fattori basata su TOTP<\/strong> (Time-based One-Time Password) \u00e8 oggi lo standard minimo per proteggere un account contro il furto di credenziali. Quando un utente inserisce le sei cifre generate dalla sua app, dimostra di possedere un segreto condiviso che non transita mai in rete dopo l’attivazione. In questo tutorial costruisci, da zero e in 12 step, un sistema 2FA TOTP completo in Node.js: generazione del segreto, QR code di provisioning, verifica con tolleranza temporale, codici di backup, rate limiting e integrazione nel login. Tutto il codice \u00e8 funzionante e allineato a RFC 6238<\/strong>, alle linee guida OWASP e a NIST SP 800-63B.<\/p>\n\n\n\n

Alla fine avrai un progetto Express pronto per la produzione, compatibile con Google Authenticator, Microsoft Authenticator e Authy. Il focus \u00e8 pratico: ogni step include codice reale, output atteso e gli errori che vediamo pi\u00f9 spesso nelle code review. Data di aggiornamento: 14 giugno 2026.<\/p>\n\n\n\n

Che cos’\u00e8 il TOTP e come funziona davvero<\/h2>\n\n\n\n

Il TOTP<\/strong> \u00e8 definito in RFC 6238<\/a> come estensione dell’algoritmo HOTP descritto in RFC 4226<\/a>. La differenza \u00e8 netta: HOTP usa un contatore di eventi che si incrementa a ogni codice, mentre TOTP sostituisce quel contatore con un fattore derivato dal tempo. In pratica il client e il server calcolano lo stesso codice perch\u00e9 condividono due cose: un segreto e l’orologio.<\/p>\n\n\n\n

Il meccanismo, ridotto all’osso, funziona cos\u00ec. Si prende l’ora corrente in secondi dall’epoca Unix, la si divide per un intervallo fisso (lo step<\/em>, di norma 30 secondi) e si ottiene un contatore intero. Questo contatore viene passato, insieme al segreto, a una funzione HMAC. Il digest risultante viene troncato secondo l’algoritmo di dynamic truncation di RFC 4226 fino a ottenere sei cifre decimali. Ogni 30 secondi il contatore cambia, quindi cambia anche il codice. Nessun dato sensibile viaggia in rete dopo l’enrollment: il segreto resta sul telefono dell’utente e nel database del server.<\/p>\n\n\n\n

L’algoritmo predefinito dell’ecosistema TOTP \u00e8 HMAC-SHA1<\/strong>, ereditato da HOTP. Non \u00e8 una scelta debole come pu\u00f2 sembrare: SHA-1 qui \u00e8 usato all’interno di un HMAC con chiave segreta, contesto in cui le collisioni note di SHA-1 non hanno alcun impatto pratico. RFC 6238 prevede comunque anche HMAC-SHA-256 e HMAC-SHA-512, ma attenzione: la maggior parte delle app di autenticazione assume SHA-1, e cambiare algoritmo senza che il client lo supporti produce codici che non combaciano mai. \u00c8 la prima causa di “il codice \u00e8 sempre sbagliato” che incontriamo.<\/p>\n\n\n\n

Il segreto condiviso \u00e8 quasi sempre codificato in Base32<\/strong>, perch\u00e9 si presta a essere scansionato in un QR code e digitato a mano senza ambiguit\u00e0 (niente 0\/O o 1\/l). La lunghezza raccomandata \u00e8 di 160 bit, valore che si allinea naturalmente all’output da 160 bit di HMAC-SHA1 e che NIST considera adeguato per un autenticatore di questo tipo. Da questi pochi parametri (segreto, step, cifre, algoritmo) deriva tutto il comportamento del sistema: vale la pena fissarli in modo esplicito invece di affidarsi ai default impliciti.<\/p>\n\n\n\n

TOTP vs HOTP vs passkey: quale scegliere nel 2026<\/h2>\n\n\n\n

Prima di scrivere codice conviene capire dove si colloca il TOTP nel panorama del 2026. HOTP, basato su contatore, soffre di problemi di desincronizzazione: se l’utente genera codici senza usarli, contatore client e server divergono e serve una finestra di recupero. Per questo TOTP, ancorato al tempo, ha vinto come standard di fatto per le app di autenticazione.<\/p>\n\n\n\n

Il limite vero del TOTP \u00e8 un altro, e va detto con chiarezza fin da subito: non \u00e8 phishing-resistant<\/strong>. Un attaccante che gestisce un proxy Adversary-in-the-Middle (AiTM) pu\u00f2 intercettare in tempo reale sia la password sia il codice a sei cifre e replicarli verso il sito legittimo entro la finestra di validit\u00e0. Le analisi di sicurezza del 2024-2025 hanno mostrato un aumento netto di questi attacchi con kit di phishing come Evilginx. Per questo, dove possibile, le passkey FIDO2\/WebAuthn restano superiori perch\u00e9 legano l’autenticazione all’origine del sito.<\/p>\n\n\n\n

Detto questo, il TOTP rimane lo strumento giusto in moltissimi contesti: non richiede hardware dedicato, funziona offline, \u00e8 gratuito, \u00e8 compatibile con tutte le app diffuse e alza enormemente il costo di un attacco rispetto alla sola password. La strategia sensata nel 2026 \u00e8 offrire le passkey come opzione primaria e il TOTP come secondo fattore universale e fallback. Il sistema che costruiamo qui \u00e8 esattamente questo secondo livello.<\/p>\n\n\n\n

Caratteristica<\/th>TOTP (RFC 6238)<\/th>HOTP (RFC 4226)<\/th>Passkey (FIDO2)<\/th><\/tr><\/thead>
Fattore mobile<\/td>Tempo (30 s)<\/td>Contatore eventi<\/td>Chiave crittografica<\/td><\/tr>
Phishing-resistant<\/td>No<\/td>No<\/td>S\u00ec<\/td><\/tr>
Richiede hardware<\/td>No<\/td>No<\/td>No (usa il dispositivo)<\/td><\/tr>
Funziona offline<\/td>S\u00ec<\/td>S\u00ec<\/td>S\u00ec<\/td><\/tr>
Desincronizzazione<\/td>Solo per drift orario<\/td>Frequente<\/td>Assente<\/td><\/tr>
App compatibili<\/td>Tutte<\/td>Limitate<\/td>Browser e OS moderni<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Prerequisiti: versioni, librerie e ambiente<\/h2>\n\n\n\n

Per seguire il tutorial servono competenze base di JavaScript e Node.js e un terminale. Useremo otplib<\/strong> come libreria TOTP perch\u00e9 \u00e8 attivamente mantenuta e implementa correttamente RFC 6238 e RFC 4226. Una nota sulla scelta: speakeasy<\/code>, a lungo la libreria pi\u00f9 popolare, \u00e8 ferma alla versione 2.0.0 da anni e non riceve aggiornamenti significativi; per un progetto nuovo nel 2026 consigliamo otplib. La tabella riporta le versioni verificate al 14 giugno 2026.<\/p>\n\n\n\n

Componente<\/th>Versione<\/th>Ruolo nel progetto<\/th><\/tr><\/thead>
Node.js<\/td>22 LTS o superiore<\/td>Runtime, modulo crypto<\/code> nativo<\/td><\/tr>
otplib<\/td>13.4.1<\/td>Generazione e verifica TOTP<\/td><\/tr>
qrcode<\/td>1.5.4<\/td>QR code dall’URI otpauth:\/\/<\/td><\/tr>
express<\/td>5.2.1<\/td>Server e rotte di login\/2FA<\/td><\/tr>
express-rate-limit<\/td>ultima versione<\/td>Throttling sulla verifica OTP<\/td><\/tr>
better-sqlite3<\/td>ultima versione<\/td>Persistenza dei segreti (demo)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Verifica subito la versione di Node, perch\u00e9 otplib 13 richiede un runtime moderno e il modulo crypto<\/code> aggiornato per la cifratura del segreto a riposo che vedremo nello Step 5.<\/p>\n\n\n\n

node --version\n# atteso: v22.x.x o superiore\n\nnpm --version\n# atteso: 10.x o superiore<\/code><\/pre>\n\n\n\n
Step 1-2: Inizializzare il progetto e installare le dipendenze<\/h2>\n\n\n\n
Crea la cartella del progetto e inizializza npm. Usiamo i moduli ES (\"type\": \"module\"<\/code>) perch\u00e9 sono ormai lo standard. Negli esempi alterniamo la sintassi import<\/code> ES e, dove pi\u00f9 chiaro, l’equivalente CommonJS.<\/p>\n\n\n\n
# Step 1: progetto\nmkdir totp-2fa-node && cd totp-2fa-node\nnpm init -y\nnpm pkg set type=module\n\n# Step 2: dipendenze\nnpm install otplib@13.4.1 qrcode@1.5.4 express@5.2.1 \\\n  express-rate-limit better-sqlite3<\/code><\/pre>\n\n\n\n
Output atteso al termine dell’installazione: npm elenca i pacchetti aggiunti senza vulnerabilit\u00e0 critiche. Se compaiono warning su better-sqlite3<\/code> relativi alla compilazione nativa, verifica di avere i build tools del sistema operativo (su Debian\/Ubuntu: build-essential<\/code> e python3<\/code>). La struttura minima che andremo a popolare \u00e8 questa:<\/p>\n\n\n\n
totp-2fa-node\/\n\u251c\u2500\u2500 package.json\n\u251c\u2500\u2500 totp.js         # logica TOTP: segreto, URI, verifica\n\u251c\u2500\u2500 crypto-store.js # cifratura del segreto a riposo\n\u251c\u2500\u2500 backup.js       # codici di recupero\n\u251c\u2500\u2500 db.js           # persistenza demo\n\u2514\u2500\u2500 server.js       # app Express completa<\/code><\/pre>\n\n\n\n
Step 3: Generare il segreto condiviso TOTP<\/h2>\n\n\n\n
Il cuore del 2FA \u00e8 il segreto. Con otplib lo generi in una riga: authenticator.generateSecret()<\/code> restituisce una stringa Base32 pronta per il provisioning. Per impostazione predefinita otplib produce un segreto di lunghezza adeguata; passando 20 byte ottieni i 160 bit raccomandati da RFC 4226. Configuriamo anche le opzioni globali in modo esplicito, cos\u00ec il comportamento \u00e8 prevedibile e documentato.<\/p>\n\n\n\n
\/\/ totp.js\nimport { authenticator } from 'otplib';\n\n\/\/ Parametri espliciti, allineati a RFC 6238 e alle app diffuse\nauthenticator.options = {\n  step: 30,          \/\/ intervallo in secondi\n  digits: 6,         \/\/ lunghezza del codice\n  algorithm: 'sha1', \/\/ default compatibile con Google Authenticator\n  window: 1,         \/\/ tolleranza: +\/- 1 step (vedi Step 7)\n};\n\nexport function generaSegreto() {\n  \/\/ 20 byte = 160 bit di entropia, codificati in Base32\n  return authenticator.generateSecret(20);\n}\n\nconsole.log(generaSegreto());\n\/\/ output esempio: KZXW6YTBOI======<\/code><\/pre>\n\n\n\n
Una regola d’oro: genera un segreto nuovo per ogni utente e per ogni nuovo enrollment<\/strong>. Non riutilizzare mai lo stesso segreto tra account diversi e non derivarlo dalla password. Il segreto \u00e8 materiale crittografico ad alta entropia e va trattato come tale. Nel prossimo step lo trasformiamo in qualcosa che l’app dell’utente possa importare con una scansione.<\/p>\n\n\n\n
Step 4: Creare l’URI otpauth:\/\/ e il QR code di provisioning<\/h2>\n\n\n\n
Le app di autenticazione importano il segreto tramite un URI standard nel formato otpauth:\/\/totp\/Emittente:account?secret=...&issuer=...<\/code>. L’etichetta contiene l’emittente (il nome del tuo servizio) e l’identificativo dell’utente; i parametri trasportano il segreto Base32 e ripetono l’issuer. otplib costruisce questo URI con authenticator.keyuri()<\/code>. Poi qrcode<\/code> lo trasforma in un’immagine scansionabile.<\/p>\n\n\n\n
\/\/ totp.js (continua)\nimport QRCode from 'qrcode';\n\nexport function creaOtpauthUri(account, segreto, emittente = 'ShatteredApp') {\n  return authenticator.keyuri(account, emittente, segreto);\n}\n\nexport async function creaQrDataUrl(otpauthUri) {\n  \/\/ Data URL PNG da incorporare in un tag img nella pagina di setup\n  return QRCode.toDataURL(otpauthUri, { margin: 1, width: 240 });\n}\n\n\/\/ Esempio d'uso\nconst segreto = generaSegreto();\nconst uri = creaOtpauthUri('mario.rossi@example.com', segreto);\nconsole.log(uri);\n\/\/ otpauth:\/\/totp\/ShatteredApp:mario.rossi@example.com?secret=KZXW6YTB...&issuer=ShatteredApp<\/code><\/pre>\n\n\n\n
L’issuer<\/code> non \u00e8 cosmetico: \u00e8 ci\u00f2 che l’utente vede nell’app accanto al codice. Impostarlo correttamente evita la confusione tra account multipli e riduce il rischio che l’utente cancelli la voce sbagliata. Mostra all’utente, nella stessa schermata, anche il segreto in chiaro come fallback per chi non pu\u00f2 scansionare il QR (per esempio chi usa un gestore di password desktop). Per approfondire come le diverse app gestiscono questi URI, vedi il nostro confronto su Google Authenticator, Microsoft Authenticator e Authy<\/a>.<\/p>\n\n\n\n
Step 5: Cifrare il segreto a riposo nel database<\/h2>\n\n\n\n
Qui si gioca la sicurezza reale del sistema. Se un attaccante esfiltra il database e i segreti TOTP sono in chiaro, pu\u00f2 rigenerare i codici di chiunque e il secondo fattore evapora. Il segreto non va hashato (deve restare recuperabile per il calcolo), quindi va cifrato a riposo<\/strong> con una chiave che vive fuori dal database, in una variabile d’ambiente o in un secrets manager. Usiamo AES-256-GCM dal modulo crypto<\/code> nativo di Node, che fornisce confidenzialit\u00e0 e autenticazione del dato.<\/p>\n\n\n\n
\/\/ crypto-store.js\nimport crypto from 'node:crypto';\n\n\/\/ 32 byte (256 bit) in esadecimale, da variabile d'ambiente\nconst KEY = Buffer.from(process.env.TOTP_ENC_KEY, 'hex');\n\nexport function cifra(testo) {\n  const iv = crypto.randomBytes(12); \/\/ 96 bit, raccomandato per GCM\n  const cipher = crypto.createCipheriv('aes-256-gcm', KEY, iv);\n  const enc = Buffer.concat([cipher.update(testo, 'utf8'), cipher.final()]);\n  const tag = cipher.getAuthTag();\n  \/\/ formato: iv:tag:ciphertext (tutto in base64)\n  return [iv.toString('base64'), tag.toString('base64'), enc.toString('base64')].join(':');\n}\n\nexport function decifra(pacchetto) {\n  const [ivB64, tagB64, dataB64] = pacchetto.split(':');\n  const decipher = crypto.createDecipheriv('aes-256-gcm', KEY, Buffer.from(ivB64, 'base64'));\n  decipher.setAuthTag(Buffer.from(tagB64, 'base64'));\n  return Buffer.concat([decipher.update(Buffer.from(dataB64, 'base64')), decipher.final()]).toString('utf8');\n}<\/code><\/pre>\n\n\n\n
Genera la chiave una sola volta con openssl rand -hex 32<\/code> e conservala fuori dal repository. Per i fondamenti della cifratura simmetrica in Node trovi il dettaglio nella nostra guida alla crittografia end-to-end in Node.js<\/a>. Da qui in poi, ogni volta che salvi un segreto chiami cifra(segreto)<\/code> e quando devi verificare un codice chiami decifra()<\/code>.<\/p>\n\n\n\n
Step 6: Verificare il codice TOTP inserito dall’utente<\/h2>\n\n\n\n
La verifica \u00e8 il momento in cui il server ricalcola il codice atteso e lo confronta con quello digitato. Con otplib usi authenticator.verify({ token, secret })<\/code>, che restituisce un booleano. La libreria gestisce internamente il confronto e la finestra di tolleranza configurata nello Step 3. Non implementare mai il confronto a mano con ===<\/code> su stringhe: otplib applica gi\u00e0 la logica corretta.<\/p>\n\n\n\n
\/\/ totp.js (continua)\nexport function verificaToken(token, segreto) {\n  \/\/ token: le 6 cifre digitate; segreto: stringa Base32 decifrata\n  try {\n    return authenticator.verify({ token: String(token).trim(), secret: segreto });\n  } catch {\n    return false; \/\/ token malformato (non numerico, lunghezza errata)\n  }\n}\n\n\/\/ Test rapido\nconst s = generaSegreto();\nconst codiceCorrente = authenticator.generate(s);\nconsole.log(verificaToken(codiceCorrente, s)); \/\/ true\nconsole.log(verificaToken('000000', s));        \/\/ quasi certamente false<\/code><\/pre>\n\n\n\n
Nota l’uso di trim()<\/code> e String()<\/code>: gli utenti incollano spesso codici con spazi o li passano come numeri che perdono lo zero iniziale. Un codice come 012345<\/code> diventa 12345<\/code> se trattato come intero, e la verifica fallisce. Normalizza sempre l’input prima di verificarlo. Questo \u00e8 uno degli errori pi\u00f9 frequenti e pi\u00f9 frustranti da diagnosticare.<\/p>\n\n\n\n
Step 7: Gestire il clock skew e la deriva temporale<\/h2>\n\n\n\n
TOTP dipende dal fatto che orologio del client e del server siano allineati. In pratica non lo sono mai perfettamente: il telefono dell’utente pu\u00f2 essere avanti o indietro di qualche secondo. Per assorbire questa deriva si accetta anche il codice degli step adiacenti, configurando il parametro window<\/code>. Con window: 1<\/code> il server accetta il codice corrente pi\u00f9 quello precedente e quello successivo, coprendo circa 90 secondi totali.<\/p>\n\n\n\n
NIST SP 800-63B \u00e8 esplicito su questo punto: la durata accettata di un OTP deve essere basata sulla deriva attesa dell’orologio dell’autenticatore, in entrambe le direzioni. Tradotto in pratica: tieni la finestra stretta. Una finestra ampia (per esempio window: 5<\/code>, che coprirebbe oltre cinque minuti) sembra comoda ma moltiplica i codici validi contemporaneamente, riducendo l’entropia effettiva e facilitando il brute force.<\/p>\n\n\n\n
Valore window<\/code><\/th>Codici accettati<\/th>Copertura temporale<\/th>Raccomandazione<\/th><\/tr><\/thead>
0<\/td>Solo corrente<\/td>~30 s<\/td>Troppo rigido per il mondo reale<\/td><\/tr>
1<\/td>Precedente, corrente, successivo<\/td>~90 s<\/td>Consigliato (default sensato)<\/td><\/tr>
2<\/td>5 codici<\/td>~150 s<\/td>Solo con utenti dagli orologi notoriamente instabili<\/td><\/tr>
5 o pi\u00f9<\/td>11+ codici<\/td>5,5+ minuti<\/td>Sconsigliato: indebolisce la sicurezza<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Assicurati che il server sincronizzi l’ora via NTP (systemd-timesyncd<\/code> o chrony<\/code>). Un server con orologio sbagliato fa fallire ogni verifica, anche con il codice giusto, e produce ticket di supporto impossibili da capire. \u00c8 la causa numero uno dei problemi in produzione e la prima cosa da controllare quando “tutti i codici sono errati”.<\/p>\n\n\n\n
Step 8: Generare e gestire i codici di backup<\/h2>\n\n\n\n
Cosa succede se l’utente perde il telefono? Senza una via di recupero, perde l’accesso all’account. I codici di backup<\/strong> (recovery codes) risolvono il problema: una serie di codici monouso da conservare in luogo sicuro, ognuno valido una sola volta. Vanno trattati come password: non salvarli mai in chiaro nel database, ma hashati. Qui usiamo lo scrypt nativo di Node.<\/p>\n\n\n\n
\/\/ backup.js\nimport crypto from 'node:crypto';\n\nexport function generaCodiciBackup(quanti = 10) {\n  const codici = [];\n  for (let i = 0; i < quanti; i++) {\n    \/\/ 5 byte -> 10 cifre esadecimali, leggibili e robuste\n    codici.push(crypto.randomBytes(5).toString('hex'));\n  }\n  return codici;\n}\n\nexport function hashCodice(codice) {\n  const salt = crypto.randomBytes(16);\n  const dk = crypto.scryptSync(codice, salt, 32);\n  return salt.toString('hex') + ':' + dk.toString('hex');\n}\n\nexport function verificaCodiceBackup(codice, hashSalvato) {\n  const [saltHex, dkHex] = hashSalvato.split(':');\n  const dk = crypto.scryptSync(codice, Buffer.from(saltHex, 'hex'), 32);\n  \/\/ confronto a tempo costante per evitare timing attack\n  return crypto.timingSafeEqual(dk, Buffer.from(dkHex, 'hex'));\n}<\/code><\/pre>\n\n\n\n
Mostra i codici di backup all’utente una sola volta<\/strong>, subito dopo l’attivazione del 2FA, e invitalo a stamparli o salvarli nel gestore di password. Quando un codice viene usato, rimuovilo o marcalo come consumato. L’uso di crypto.timingSafeEqual<\/code> non \u00e8 un dettaglio: il confronto a tempo costante impedisce a un attaccante di dedurre il codice carattere per carattere misurando i tempi di risposta. Per le basi dell’hashing sicuro vedi la nostra guida su hashing delle password con bcrypt<\/a>.<\/p>\n\n\n\n
Step 9: Rate limiting sulla verifica OTP contro il brute force<\/h2>\n\n\n\n
Un codice a sei cifre ha un milione di combinazioni. Sembrano tante, ma senza limiti un attaccante con la password gi\u00e0 rubata pu\u00f2 tentarle tutte in poco tempo, soprattutto con una finestra window<\/code> generosa che tiene validi pi\u00f9 codici insieme. Il rate limiting<\/strong> sull’endpoint di verifica \u00e8 obbligatorio, non opzionale. OWASP lo elenca tra i controlli fondamentali per l’autenticazione multifattore.<\/p>\n\n\n\n
\/\/ nel server.js\nimport rateLimit from 'express-rate-limit';\n\nexport const limiteOtp = rateLimit({\n  windowMs: 15 * 60 * 1000, \/\/ 15 minuti\n  max: 5,                   \/\/ max 5 tentativi per IP+utente nella finestra\n  standardHeaders: true,\n  legacyHeaders: false,\n  message: { errore: 'Troppi tentativi. Riprova tra qualche minuto.' },\n  keyGenerator: (req) => `${req.ip}:${req.body?.userId ?? 'anon'}`,\n});<\/code><\/pre>\n\n\n\n
Cinque tentativi ogni 15 minuti sono un punto di partenza ragionevole. Affianca al rate limiting un contatore persistente di fallimenti per utente: dopo N fallimenti consecutivi, blocca temporaneamente il 2FA e notifica l’utente via email, perch\u00e9 tentativi ripetuti sono spesso il segnale di un attacco in corso con credenziali gi\u00e0 compromesse. Lo stesso principio difensivo lo applichiamo nella nostra guida alla protezione CSRF in Node.js<\/a>.<\/p>\n\n\n\n
Step 10: Integrare il 2FA nel flusso di login con Express<\/h2>\n\n\n\n
Ora colleghiamo i pezzi. Il flusso corretto \u00e8 in due fasi: prima l’utente supera la verifica della password (primo fattore), poi viene messo in uno stato “in attesa di 2FA” e solo dopo aver fornito un TOTP valido riceve la sessione autenticata completa. Non emettere mai una sessione piena prima del secondo fattore.<\/p>\n\n\n\n
\/\/ server.js (estratto delle rotte 2FA)\nimport express from 'express';\nimport { verificaToken } from '.\/totp.js';\nimport { decifra } from '.\/crypto-store.js';\nimport { verificaCodiceBackup } from '.\/backup.js';\nimport { getUtente, consumaBackup } from '.\/db.js';\n\nconst app = express();\napp.use(express.json());\n\n\/\/ Fase 2: l'utente ha gia superato la password ed ha stato \"pending2fa\"\napp.post('\/2fa\/verifica', limiteOtp, (req, res) => {\n  const { userId, token } = req.body;\n  const u = getUtente(userId);\n  if (!u || !u.totpAttivo) return res.status(400).json({ errore: 'Setup non valido' });\n\n  const segreto = decifra(u.segretoCifrato);\n  if (verificaToken(token, segreto)) {\n    req.session = { userId, mfa: true }; \/\/ sessione piena\n    return res.json({ ok: true });\n  }\n\n  \/\/ Fallback: prova come codice di backup\n  for (const h of u.codiciBackup) {\n    if (verificaCodiceBackup(token, h)) {\n      consumaBackup(userId, h);\n      req.session = { userId, mfa: true };\n      return res.json({ ok: true, backupUsato: true });\n    }\n  }\n  return res.status(401).json({ errore: 'Codice non valido' });\n});<\/code><\/pre>\n\n\n\n
Questo pattern di “sessione a due livelli” si integra bene con i token applicativi: se usi i JWT per le API, emetti il token finale solo dopo la verifica del secondo fattore. Approfondisci nella nostra guida all’autenticazione JWT in Node.js<\/a>.<\/p>\n\n\n\n
Step 11: Disattivare, rigenerare e gestire il ciclo di vita<\/h2>\n\n\n\n
Un sistema 2FA non finisce all’attivazione. Devi gestire la disattivazione (che richiede sempre una conferma con un codice TOTP valido o la password, mai a clic libero), la rigenerazione del segreto se l’utente cambia dispositivo, e la rigenerazione dei codici di backup quando si esauriscono. Ogni operazione sensibile va registrata in un log di audit con timestamp e IP.<\/p>\n\n\n\n
\/\/ server.js (gestione ciclo di vita)\napp.post('\/2fa\/disattiva', limiteOtp, (req, res) => {\n  const { userId, token } = req.body;\n  const u = getUtente(userId);\n  const segreto = decifra(u.segretoCifrato);\n  if (!verificaToken(token, segreto)) {\n    return res.status(401).json({ errore: 'Conferma con un codice valido' });\n  }\n  disattiva2fa(userId);          \/\/ azzera segreto e codici di backup\n  logAudit(userId, '2fa_off', req.ip);\n  res.json({ ok: true });\n});<\/code><\/pre>\n\n\n\n
Punto critico spesso trascurato: durante l’enrollment, attiva il 2FA solo dopo che l’utente ha confermato un primo codice valido. Se imposti totpAttivo = true<\/code> appena generi il segreto, senza verificare che l’utente lo abbia davvero importato, rischi di bloccarlo fuori dal proprio account perch\u00e9 ha scansionato male il QR. La sequenza corretta \u00e8: genera segreto, mostra QR, l’utente inserisce un codice, verifichi, e solo se \u00e8 valido attivi.<\/p>\n\n\n\n
Step 12: Il progetto completo funzionante<\/h2>\n\n\n\n
Mettiamo insieme i moduli in un server.js<\/code> avviabile. Questa versione usa un archivio in memoria per chiarezza; in produzione sostituisci con better-sqlite3<\/code> o il tuo database, mantenendo la cifratura del segreto a riposo dello Step 5.<\/p>\n\n\n\n
\/\/ server.js (versione demo eseguibile)\nimport express from 'express';\nimport { authenticator } from 'otplib';\nimport QRCode from 'qrcode';\nimport { cifra, decifra } from '.\/crypto-store.js';\nimport { verificaToken } from '.\/totp.js';\nimport { generaCodiciBackup, hashCodice } from '.\/backup.js';\n\nconst app = express();\napp.use(express.json());\nconst utenti = new Map(); \/\/ demo: { segretoCifrato, totpAttivo, codiciBackup }\n\n\/\/ 1) Avvio enrollment: genera segreto e QR\napp.post('\/2fa\/setup', async (req, res) => {\n  const { userId, email } = req.body;\n  const segreto = authenticator.generateSecret(20);\n  const uri = authenticator.keyuri(email, 'ShatteredApp', segreto);\n  const qr = await QRCode.toDataURL(uri);\n  utenti.set(userId, { segretoCifrato: cifra(segreto), totpAttivo: false, codiciBackup: [] });\n  res.json({ qr, segreto }); \/\/ segreto in chiaro solo qui, come fallback manuale\n});\n\n\/\/ 2) Conferma enrollment: l'utente prova un codice\napp.post('\/2fa\/conferma', (req, res) => {\n  const { userId, token } = req.body;\n  const u = utenti.get(userId);\n  const segreto = decifra(u.segretoCifrato);\n  if (!verificaToken(token, segreto)) return res.status(401).json({ errore: 'Codice errato' });\n  const codici = generaCodiciBackup(10);\n  u.codiciBackup = codici.map(hashCodice);\n  u.totpAttivo = true;\n  res.json({ ok: true, codiciBackup: codici }); \/\/ mostrati una sola volta\n});\n\napp.listen(3000, () => console.log('2FA TOTP su http:\/\/localhost:3000'));<\/code><\/pre>\n\n\n\n
Avvia con TOTP_ENC_KEY=$(openssl rand -hex 32) node server.js<\/code>. Chiama POST \/2fa\/setup<\/code>, scansiona il QR con la tua app, poi conferma con POST \/2fa\/conferma<\/code>. Output atteso alla conferma: { \"ok\": true, \"codiciBackup\": [ ... ] }<\/code>. Hai un sistema 2FA TOTP funzionante end-to-end.<\/p>\n\n\n\n
Errori comuni da evitare con il TOTP<\/h2>\n\n\n\n
Questi sono i passi falsi che vediamo pi\u00f9 spesso e che, presi insieme, spiegano la quasi totalit\u00e0 dei sistemi 2FA difettosi in produzione.<\/p>\n\n\n\n