{"id":54,"date":"2026-06-11T16:58:54","date_gmt":"2026-06-11T16:58:54","guid":{"rendered":"https:\/\/shattered.io\/pt\/2026\/06\/11\/autenticacao-dois-fatores-nodejs\/"},"modified":"2026-06-11T16:58:54","modified_gmt":"2026-06-11T16:58:54","slug":"autenticacao-dois-fatores-nodejs","status":"publish","type":"post","link":"https:\/\/shattered.io\/pt\/2026\/06\/11\/autenticacao-dois-fatores-nodejs\/","title":{"rendered":"Autentica\u00e7\u00e3o de Dois Fatores em Node.js: 12 Passos [2026]"},"content":{"rendered":"\n

A autentica\u00e7\u00e3o de dois fatores<\/strong> deixou de ser um extra opcional. Em 2026, qualquer aplica\u00e7\u00e3o web que guarde dados sens\u00edveis precisa de uma segunda barreira para l\u00e1 da palavra-passe. A Microsoft repete h\u00e1 anos que mais de 99,9% das contas comprometidas n\u00e3o tinham MFA ativada, um n\u00famero que resume bem porque \u00e9 que este passo importa. Neste tutorial implementamos, do zero, autentica\u00e7\u00e3o de dois fatores<\/strong> baseada em TOTP (Time-based One-Time Password) numa API Node.js, com c\u00f3digo de seis d\u00edgitos compat\u00edvel com o Google Authenticator, Microsoft Authenticator e Authy.<\/p>\n\n\n\n

No final ter\u00e1 um projeto funcional completo: gera\u00e7\u00e3o do segredo partilhado, c\u00f3digo QR para registo, verifica\u00e7\u00e3o do c\u00f3digo de seis d\u00edgitos, c\u00f3digos de recupera\u00e7\u00e3o, limita\u00e7\u00e3o de tentativas e integra\u00e7\u00e3o no fluxo de login com JWT. S\u00e3o 12 passos, cerca de 30 minutos de trabalho, e tudo assente nas normas RFC 6238 e RFC 4226. Nenhuma depend\u00eancia paga, nenhum servi\u00e7o externo obrigat\u00f3rio.<\/p>\n\n\n\n

Autentica\u00e7\u00e3o de dois fatores: o que muda em 2026<\/h2>\n\n\n\n

A autentica\u00e7\u00e3o de dois fatores<\/strong> combina algo que o utilizador sabe (a palavra-passe) com algo que possui (o telem\u00f3vel com a app de c\u00f3digos). Mesmo que um atacante roube a palavra-passe num ataque de phishing ou numa fuga de dados, n\u00e3o consegue entrar sem o c\u00f3digo que muda a cada 30 segundos no dispositivo da v\u00edtima.<\/p>\n\n\n\n

Em 2026, a paisagem mudou em tr\u00eas pontos concretos. Primeiro, o SMS perdeu credibilidade: o envio de c\u00f3digos por mensagem continua vulner\u00e1vel ao SIM swap, em que o atacante transfere o n\u00famero da v\u00edtima para um cart\u00e3o SIM controlado por si. O TOTP, por gerar os c\u00f3digos localmente no dispositivo, elimina esse risco. Segundo, as passkeys (FIDO2\/WebAuthn) consolidaram-se como o fator mais resistente a phishing, porque a credencial fica ligada \u00e0 origem do site e n\u00e3o pode ser reutilizada num dom\u00ednio falso. Terceiro, mesmo com as passkeys em ascens\u00e3o, o TOTP mant\u00e9m-se como o m\u00e9todo de compatibilidade universal, suportado por todas as apps de autentica\u00e7\u00e3o e por milh\u00f5es de contas existentes.<\/p>\n\n\n\n

A escolha pr\u00e1tica para a maioria das equipas em 2026 \u00e9 clara: oferecer TOTP como segundo fator universal hoje, e planear passkeys como caminho a seguir. Este tutorial foca o TOTP porque \u00e9 o que pode implementar numa tarde, sem depender do suporte de hardware do cliente. Conv\u00e9m saber, desde j\u00e1, a sua principal limita\u00e7\u00e3o: o TOTP n\u00e3o \u00e9 resistente a phishing em tempo real. Um atacante que monte um proxy reverso entre o utilizador e o site verdadeiro pode capturar e reencaminhar o c\u00f3digo dentro da janela de 30 segundos. Mitigamos isso mais \u00e0 frente com limita\u00e7\u00e3o de tentativas e boas pr\u00e1ticas de sess\u00e3o.<\/p>\n\n\n\n

Como funciona o TOTP (RFC 6238 e RFC 4226)<\/h2>\n\n\n\n

O TOTP \u00e9 definido na RFC 6238<\/a> e assenta sobre o HOTP, descrito na RFC 4226<\/a>. A ideia \u00e9 simples e elegante. O servidor e a app de autentica\u00e7\u00e3o partilham um segredo \u00fanico, gerado no momento do registo. A partir da\u00ed, ambos calculam o mesmo c\u00f3digo de seis d\u00edgitos usando dois ingredientes: esse segredo partilhado e a hora atual.<\/p>\n\n\n\n

O c\u00e1lculo divide o tempo em janelas (por norma de 30 segundos), conta quantas janelas passaram desde 1 de janeiro de 1970, e aplica um HMAC-SHA1 sobre esse contador usando o segredo como chave. Do resultado extrai-se um n\u00famero de seis d\u00edgitos. Como o servidor e a app t\u00eam o mesmo segredo e o mesmo rel\u00f3gio, chegam ao mesmo c\u00f3digo de forma independente, sem nunca trocarem mensagens depois do registo inicial. Por isso \u00e9 que o TOTP funciona mesmo com o telem\u00f3vel em modo de avi\u00e3o.<\/p>\n\n\n\n

Os par\u00e2metros s\u00e3o quase sempre os mesmos em todas as aplica\u00e7\u00f5es populares. A tabela abaixo mostra os valores padr\u00e3o que vamos respeitar para garantir compatibilidade total.<\/p>\n\n\n\n

Par\u00e2metro<\/th>Valor padr\u00e3o<\/th>Google Authenticator<\/th>Microsoft Authenticator<\/th>Authy<\/th><\/tr><\/thead>
Per\u00edodo (janela)<\/td>30 segundos<\/td>30 s<\/td>30 s<\/td>30 s<\/td><\/tr>
D\u00edgitos<\/td>6<\/td>6<\/td>6<\/td>6<\/td><\/tr>
Algoritmo<\/td>HMAC-SHA1<\/td>SHA1<\/td>SHA1<\/td>SHA1<\/td><\/tr>
Codifica\u00e7\u00e3o do segredo<\/td>Base32<\/td>Base32<\/td>Base32<\/td>Base32<\/td><\/tr>
Norma<\/td>RFC 6238<\/td>RFC 6238<\/td>RFC 6238<\/td>RFC 6238<\/td><\/tr><\/tbody><\/table>
Par\u00e2metros TOTP padr\u00e3o suportados pelas principais apps de autentica\u00e7\u00e3o.<\/figcaption><\/figure>\n\n\n\n

Repare numa decis\u00e3o deliberada: o HMAC-SHA1. Apesar de o SHA-1 estar obsoleto para assinaturas digitais (recorde a colis\u00e3o SHATTERED), no contexto do HMAC-TOTP mant\u00e9m-se seguro e, mais importante, \u00e9 o \u00fanico algoritmo que todas as apps leem de forma fi\u00e1vel. Alterar para SHA-256 partiria a compatibilidade com muitos leitores de QR. Mantemos o SHA1.<\/p>\n\n\n\n

Pr\u00e9-requisitos e vers\u00f5es<\/h2>\n\n\n\n

Antes de escrever c\u00f3digo, confirme o ambiente. Este tutorial foi testado com as vers\u00f5es da tabela seguinte. Pode usar vers\u00f5es mais recentes, mas evite vers\u00f5es anteriores do Node.js, que n\u00e3o suportam algumas funcionalidades do Express 5.<\/p>\n\n\n\n

Ferramenta<\/th>Vers\u00e3o usada<\/th>Fun\u00e7\u00e3o no projeto<\/th><\/tr><\/thead>
Node.js<\/td>22 LTS ou 24 LTS<\/td>Ambiente de execu\u00e7\u00e3o<\/td><\/tr>
npm<\/td>10 ou superior<\/td>Gestor de pacotes<\/td><\/tr>
otplib<\/td>13.4.1<\/td>Gera\u00e7\u00e3o e verifica\u00e7\u00e3o de TOTP<\/td><\/tr>
qrcode<\/td>1.5.4<\/td>Gerar o c\u00f3digo QR de registo<\/td><\/tr>
express<\/td>5.2.1<\/td>Servidor HTTP da API<\/td><\/tr>
jsonwebtoken<\/td>9.x<\/td>Emitir o token de sess\u00e3o<\/td><\/tr><\/tbody><\/table>
Pr\u00e9-requisitos e vers\u00f5es de refer\u00eancia para o projeto.<\/figcaption><\/figure>\n\n\n\n

Confirme as vers\u00f5es instaladas antes de avan\u00e7ar. Uma incompatibilidade de Node.js \u00e9 a causa n\u00famero um de erros logo no primeiro passo.<\/p>\n\n\n\n

node --version\n# v22.x.x ou v24.x.x\n\nnpm --version\n# 10.x.x ou superior<\/code><\/pre>\n\n\n\n
Precisa tamb\u00e9m de uma app de autentica\u00e7\u00e3o no telem\u00f3vel para testar. Qualquer uma serve: Google Authenticator, Microsoft Authenticator, Authy, ou alternativas de c\u00f3digo aberto como o Aegis (Android) ou o Raivo (iOS). Conhecimentos b\u00e1sicos de JavaScript ass\u00edncrono (async\/await) e de pedidos HTTP s\u00e3o suficientes para acompanhar.<\/p>\n\n\n\n
Passo 1: Inicializar o projeto Node.js<\/h2>\n\n\n\n
Crie uma pasta para o projeto e inicialize-o. Vamos usar m\u00f3dulos ES (import\/export), por isso definimos o tipo do pacote logo de in\u00edcio.<\/p>\n\n\n\n
mkdir 2fa-nodejs && cd 2fa-nodejs\nnpm init -y\nnpm pkg set type=\"module\"\nnpm pkg set engines.node=\">=22\"<\/code><\/pre>\n\n\n\n
O comando npm pkg set type=\"module\"<\/code> evita o aviso recorrente sobre sintaxe de importa\u00e7\u00e3o e permite usar import<\/code> sem extens\u00f5es de ficheiro estranhas. A defini\u00e7\u00e3o de engines.node<\/code> documenta a vers\u00e3o m\u00ednima e avisa quem instalar o projeto num ambiente antigo.<\/p>\n\n\n\n
Passo 2: Instalar as depend\u00eancias (otplib, qrcode, express)<\/h2>\n\n\n\n
Instale as quatro bibliotecas centrais. O otplib<\/strong> trata da gera\u00e7\u00e3o e verifica\u00e7\u00e3o dos c\u00f3digos TOTP, o qrcode<\/strong> desenha o c\u00f3digo QR, o express<\/strong> serve a API e o jsonwebtoken<\/strong> emite o token de sess\u00e3o ap\u00f3s a verifica\u00e7\u00e3o bem-sucedida.<\/p>\n\n\n\n
npm install otplib@13.4.1 qrcode@1.5.4 express@5.2.1 jsonwebtoken@9\nnpm install --save-dev nodemon<\/code><\/pre>\n\n\n\n
Escolhemos o otplib em vez do speakeasy (vers\u00e3o 2.0.0, sem atualiza\u00e7\u00f5es recentes) porque o otplib \u00e9 mantido ativamente, tem API moderna baseada em classes e separa de forma limpa o TOTP do HOTP. Adicione um script de arranque ao package.json<\/code> para reiniciar o servidor durante o desenvolvimento.<\/p>\n\n\n\n
npm pkg set scripts.dev=\"nodemon server.js\"\nnpm pkg set scripts.start=\"node server.js\"<\/code><\/pre>\n\n\n\n
Passo 3: Gerar o segredo partilhado do utilizador<\/h2>\n\n\n\n
O segredo partilhado \u00e9 o cora\u00e7\u00e3o da autentica\u00e7\u00e3o de dois fatores<\/strong>. \u00c9 gerado uma \u00fanica vez, no momento em que o utilizador ativa o 2FA, e nunca mais \u00e9 mostrado em texto simples. Crie um ficheiro totp.js<\/code> com as fun\u00e7\u00f5es utilit\u00e1rias.<\/p>\n\n\n\n
\/\/ totp.js\nimport { authenticator } from 'otplib';\n\n\/\/ Parametros explicitos para garantir compatibilidade total\nauthenticator.options = {\n  digits: 6,\n  step: 30,        \/\/ janela de 30 segundos\n  window: 1,       \/\/ tolera 1 janela de deriva de relogio\n  algorithm: 'sha1',\n};\n\n\/\/ Gera um segredo Base32 novo para um utilizador\nexport function gerarSegredo() {\n  return authenticator.generateSecret(); \/\/ 32 caracteres Base32\n}\n\n\/\/ Cria a URI otpauth:\/\/ que a app de autenticacao le\nexport function gerarOtpauthUri(email, segredo) {\n  const emissor = 'ShatteredApp';\n  return authenticator.keyuri(email, emissor, segredo);\n}<\/code><\/pre>\n\n\n\n
A fun\u00e7\u00e3o keyuri<\/code> produz uma string no formato otpauth:\/\/totp\/ShatteredApp:ana@exemplo.pt?secret=...&issuer=ShatteredApp<\/code>. \u00c9 esta URI que transformamos em c\u00f3digo QR no passo seguinte. O campo emissor<\/code> aparece como nome da conta dentro da app do utilizador, por isso use o nome real do seu servi\u00e7o.<\/p>\n\n\n\n
Passo 4: Criar o c\u00f3digo QR para o authenticator<\/h2>\n\n\n\n
O utilizador n\u00e3o vai escrever 32 caracteres \u00e0 m\u00e3o. Convertemos a URI otpauth num c\u00f3digo QR em formato Data URL, que o frontend mostra como imagem. Acrescente ao totp.js<\/code>:<\/p>\n\n\n\n
\/\/ totp.js (continuacao)\nimport QRCode from 'qrcode';\n\n\/\/ Devolve um Data URL PNG pronto a usar num elemento de imagem\nexport async function gerarQrCode(otpauthUri) {\n  try {\n    return await QRCode.toDataURL(otpauthUri, {\n      errorCorrectionLevel: 'M',\n      margin: 2,\n      width: 240,\n    });\n  } catch (erro) {\n    throw new Error('Falha ao gerar o codigo QR: ' + erro.message);\n  }\n}<\/code><\/pre>\n\n\n\n
O n\u00edvel de corre\u00e7\u00e3o de erros M<\/code> (15%) \u00e9 o equil\u00edbrio certo entre densidade e fiabilidade de leitura. N\u00e3o suba para H<\/code> sem motivo: aumenta a densidade do QR e dificulta a leitura em ecr\u00e3s pequenos. Forne\u00e7a sempre, como alternativa, o segredo em texto para introdu\u00e7\u00e3o manual, para o caso de a c\u00e2mara do utilizador falhar.<\/p>\n\n\n\n
Passo 5: Guardar o segredo cifrado na base de dados<\/h2>\n\n\n\n
Erro grave e frequente: guardar o segredo TOTP em texto simples. Se a base de dados vazar, todos os segundos fatores ficam comprometidos de uma vez. O segredo deve ser cifrado em repouso com uma chave que viva fora da base de dados (numa vari\u00e1vel de ambiente ou num cofre de segredos). Aqui usamos AES-256-GCM, o padr\u00e3o recomendado para cifra autenticada.<\/p>\n\n\n\n
\/\/ cripto.js\nimport crypto from 'node:crypto';\n\n\/\/ Chave de 32 bytes em hex, definida em variavel de ambiente\nconst CHAVE = Buffer.from(process.env.TOTP_ENC_KEY, 'hex');\n\nexport function cifrar(textoSimples) {\n  const iv = crypto.randomBytes(12); \/\/ GCM usa IV de 12 bytes\n  const cipher = crypto.createCipheriv('aes-256-gcm', CHAVE, iv);\n  const cifrado = Buffer.concat([\n    cipher.update(textoSimples, 'utf8'),\n    cipher.final(),\n  ]);\n  const tag = cipher.getAuthTag();\n  \/\/ Formato armazenado: iv:tag:cifrado (tudo em hex)\n  return [iv.toString('hex'), tag.toString('hex'), cifrado.toString('hex')].join(':');\n}\n\nexport function decifrar(armazenado) {\n  const [ivHex, tagHex, dadosHex] = armazenado.split(':');\n  const decipher = crypto.createDecipheriv('aes-256-gcm', CHAVE, Buffer.from(ivHex, 'hex'));\n  decipher.setAuthTag(Buffer.from(tagHex, 'hex'));\n  return Buffer.concat([\n    decipher.update(Buffer.from(dadosHex, 'hex')),\n    decipher.final(),\n  ]).toString('utf8');\n}<\/code><\/pre>\n\n\n\n
Gere a chave de cifra uma vez com openssl rand -hex 32<\/code> e guarde-a numa vari\u00e1vel de ambiente TOTP_ENC_KEY<\/code>. Nunca a coloque no reposit\u00f3rio de c\u00f3digo. Se quiser aprofundar a cifra sim\u00e9trica, veja o nosso guia dedicado ao AES-256, ligado na sec\u00e7\u00e3o de cobertura relacionada.<\/p>\n\n\n\n
Passo 6: Verificar o c\u00f3digo de seis d\u00edgitos<\/h2>\n\n\n\n
Chegamos \u00e0 valida\u00e7\u00e3o. Quando o utilizador introduz o c\u00f3digo de seis d\u00edgitos, o servidor recalcula o c\u00f3digo esperado a partir do segredo decifrado e compara. O otplib faz a compara\u00e7\u00e3o em tempo constante, evitando fugas por timing. Acrescente ao totp.js<\/code>:<\/p>\n\n\n\n
\/\/ totp.js (continuacao)\n\/\/ Devolve true se o codigo corresponder a janela atual (ou adjacente)\nexport function verificarCodigo(codigo, segredo) {\n  \/\/ Normaliza: remove espacos que apps por vezes inserem\n  const limpo = String(codigo).replace(\/\\s+\/g, '');\n  if (!\/^\\d{6}$\/.test(limpo)) return false;\n  try {\n    return authenticator.check(limpo, segredo);\n  } catch {\n    return false;\n  }\n}<\/code><\/pre>\n\n\n\n
Repare em duas defesas. Primeiro, validamos o formato (exatamente seis d\u00edgitos) antes de chamar o otplib, o que descarta de imediato entradas inv\u00e1lidas. Segundo, envolvemos a verifica\u00e7\u00e3o num try\/catch porque um segredo malformado faz o otplib lan\u00e7ar uma exce\u00e7\u00e3o, e queremos devolver false<\/code> em vez de derrubar o servidor. O m\u00e9todo check<\/code> respeita a op\u00e7\u00e3o window: 1<\/code>, aceitando o c\u00f3digo da janela anterior e da seguinte para tolerar pequena deriva de rel\u00f3gio.<\/p>\n\n\n\n
Passo 7: Gerar e validar c\u00f3digos de recupera\u00e7\u00e3o<\/h2>\n\n\n\n
O que acontece se o utilizador perder o telem\u00f3vel? Sem plano B, fica trancado para fora da conta. Os c\u00f3digos de recupera\u00e7\u00e3o resolvem isto: um conjunto de c\u00f3digos de uso \u00fanico, gerados no registo, que o utilizador guarda em local seguro. Guardamo-los com hash, nunca em texto simples, exatamente como far\u00edamos com palavras-passe.<\/p>\n\n\n\n
\/\/ recuperacao.js\nimport crypto from 'node:crypto';\n\n\/\/ Gera 10 codigos de recuperacao legiveis\nexport function gerarCodigosRecuperacao(quantidade = 10) {\n  const codigos = [];\n  for (let i = 0; i < quantidade; i++) {\n    \/\/ 5 bytes -> 10 caracteres hex, agrupados em xxxxx-xxxxx\n    const bruto = crypto.randomBytes(5).toString('hex');\n    codigos.push(bruto.slice(0, 5) + '-' + bruto.slice(5));\n  }\n  return codigos;\n}\n\n\/\/ Guarda apenas o hash SHA-256 de cada codigo\nexport function fazerHashCodigos(codigos) {\n  return codigos.map((c) =>\n    crypto.createHash('sha256').update(c).digest('hex')\n  );\n}\n\n\/\/ Verifica um codigo contra a lista de hashes guardada\nexport function validarCodigoRecuperacao(codigo, hashesGuardados) {\n  const hash = crypto.createHash('sha256').update(codigo.trim()).digest('hex');\n  return hashesGuardados.indexOf(hash); \/\/ -1 se invalido; senao, o indice\n}<\/code><\/pre>\n\n\n\n
Quando um c\u00f3digo de recupera\u00e7\u00e3o \u00e9 usado com sucesso, remova-o (ou marque-o como consumido) na base de dados a partir do \u00edndice devolvido. Cada c\u00f3digo serve uma \u00fanica vez. Mostre os dez c\u00f3digos ao utilizador apenas uma vez, no ecr\u00e3 de ativa\u00e7\u00e3o, e avise para os guardar antes de continuar.<\/p>\n\n\n\n
Passo 8: Integrar o 2FA no fluxo de login com JWT<\/h2>\n\n\n\n
A autentica\u00e7\u00e3o de dois fatores<\/strong> encaixa-se a meio do login, n\u00e3o no in\u00edcio. O fluxo correto tem dois andares: primeiro a palavra-passe, depois o segundo fator. S\u00f3 ap\u00f3s ambos \u00e9 que emitimos o token de sess\u00e3o completo. Para a fase interm\u00e9dia usamos um token tempor\u00e1rio, de curta dura\u00e7\u00e3o, que prova que a palavra-passe j\u00e1 passou mas que ainda falta o segundo fator.<\/p>\n\n\n\n
\/\/ auth.js\nimport jwt from 'jsonwebtoken';\n\nconst SEGREDO_JWT = process.env.JWT_SECRET;\n\n\/\/ Token intermedio: palavra-passe correta, falta o 2FA\nexport function emitirTokenParcial(userId) {\n  return jwt.sign({ sub: userId, mfa: 'pendente' }, SEGREDO_JWT, {\n    expiresIn: '5m',\n  });\n}\n\n\/\/ Token de sessao completo: ambos os fatores validados\nexport function emitirTokenCompleto(userId) {\n  return jwt.sign({ sub: userId, mfa: 'ok' }, SEGREDO_JWT, {\n    expiresIn: '1h',\n  });\n}\n\n\/\/ Middleware que exige sessao totalmente autenticada\nexport function exigirMfaCompleto(req, res, next) {\n  const cabecalho = req.headers.authorization || '';\n  const token = cabecalho.replace('Bearer ', '');\n  try {\n    const dados = jwt.verify(token, SEGREDO_JWT);\n    if (dados.mfa !== 'ok') {\n      return res.status(403).json({ erro: 'Segundo fator em falta' });\n    }\n    req.userId = dados.sub;\n    next();\n  } catch {\n    return res.status(401).json({ erro: 'Token invalido' });\n  }\n}<\/code><\/pre>\n\n\n\n
Esta separa\u00e7\u00e3o evita um erro cl\u00e1ssico: emitir a sess\u00e3o completa logo ap\u00f3s a palavra-passe e tratar o 2FA como mera formalidade ignor\u00e1vel. Com o token parcial, qualquer endpoint protegido recusa o acesso at\u00e9 o segundo fator estar validado. Para mais detalhe sobre tokens de sess\u00e3o, veja o nosso tutorial de autentica\u00e7\u00e3o JWT, ligado em baixo.<\/p>\n\n\n\n
Passo 9: Lidar com a deriva de rel\u00f3gio (window)<\/h2>\n\n\n\n
O TOTP depende de rel\u00f3gios sincronizados. Se o rel\u00f3gio do telem\u00f3vel do utilizador estiver atrasado ou adiantado alguns segundos, o c\u00f3digo que ele v\u00ea pode n\u00e3o coincidir com o que o servidor calcula nesse instante. A op\u00e7\u00e3o window<\/code> resolve a maior parte destes casos ao aceitar tamb\u00e9m os c\u00f3digos das janelas vizinhas.<\/p>\n\n\n\n
Valor de window<\/th>Janelas aceites<\/th>Toler\u00e2ncia total<\/th>Recomenda\u00e7\u00e3o<\/th><\/tr><\/thead>
0<\/td>S\u00f3 a atual<\/td>At\u00e9 30 s<\/td>Demasiado r\u00edgido<\/td><\/tr>
1<\/td>Anterior, atual, seguinte<\/td>Cerca de 90 s<\/td>Equil\u00edbrio recomendado<\/td><\/tr>
2<\/td>Duas para cada lado<\/td>Cerca de 150 s<\/td>S\u00f3 com rel\u00f3gios pouco fi\u00e1veis<\/td><\/tr>
4 ou mais<\/td>Quatro ou mais<\/td>Mais de 4 min<\/td>Risco de seguran\u00e7a, evitar<\/td><\/tr><\/tbody><\/table>
Efeito do par\u00e2metro window na toler\u00e2ncia e na seguran\u00e7a.<\/figcaption><\/figure>\n\n\n\n
N\u00e3o caia na tenta\u00e7\u00e3o de subir o window<\/code> para reduzir queixas de suporte. Cada janela extra alarga a janela de oportunidade para um atacante reutilizar um c\u00f3digo capturado. O valor 1<\/code> que definimos no passo 3 cobre a esmagadora maioria dos casos reais. Garanta antes que o rel\u00f3gio do seu servidor est\u00e1 sincronizado via NTP, porque a causa mais comum de falhas n\u00e3o \u00e9 o telem\u00f3vel do utilizador, \u00e9 o servidor com a hora errada.<\/p>\n\n\n\n
Passo 10: Proteger contra for\u00e7a bruta (rate limiting)<\/h2>\n\n\n\n
Um c\u00f3digo de seis d\u00edgitos tem apenas um milh\u00e3o de combina\u00e7\u00f5es. Sem prote\u00e7\u00e3o, um atacante com a palavra-passe correta poderia tentar todos os c\u00f3digos por for\u00e7a bruta at\u00e9 acertar dentro da janela de toler\u00e2ncia. A defesa \u00e9 limitar as tentativas por conta e bloquear temporariamente ap\u00f3s um n\u00famero pequeno de falhas.<\/p>\n\n\n\n
\/\/ limitador.js\n\/\/ Limitador simples em memoria (use Redis em producao)\nconst tentativas = new Map();\n\nconst MAX_FALHAS = 5;\nconst JANELA_MS = 15 * 60 * 1000; \/\/ 15 minutos\n\nexport function podeTentar(userId) {\n  const registo = tentativas.get(userId);\n  if (!registo) return true;\n  if (Date.now() > registo.ate) {\n    tentativas.delete(userId);\n    return true;\n  }\n  return registo.falhas < MAX_FALHAS;\n}\n\nexport function registarFalha(userId) {\n  const registo = tentativas.get(userId) || { falhas: 0, ate: Date.now() + JANELA_MS };\n  registo.falhas += 1;\n  registo.ate = Date.now() + JANELA_MS;\n  tentativas.set(userId, registo);\n}\n\nexport function limparTentativas(userId) {\n  tentativas.delete(userId);\n}<\/code><\/pre>\n\n\n\n
Em produ\u00e7\u00e3o, troque o Map<\/code> em mem\u00f3ria por Redis ou outra cache partilhada, caso contr\u00e1rio o limite n\u00e3o funciona com v\u00e1rios processos ou servidores. Limpe o contador ap\u00f3s uma verifica\u00e7\u00e3o bem-sucedida com limparTentativas<\/code>, para que um utilizador leg\u00edtimo que erre o c\u00f3digo uma vez n\u00e3o fique penalizado depois de acertar.<\/p>\n\n\n\n
Passo 11: Testar o fluxo completo<\/h2>\n\n\n\n
Antes de montar o servidor final, valide a l\u00f3gica de ponta a ponta com um pequeno script. Isto confirma que a gera\u00e7\u00e3o do segredo, a cria\u00e7\u00e3o do c\u00f3digo e a verifica\u00e7\u00e3o encaixam, sem precisar de telem\u00f3vel.<\/p>\n\n\n\n
\/\/ teste.js\nimport { authenticator } from 'otplib';\nimport { gerarSegredo, verificarCodigo } from '.\/totp.js';\n\nconst segredo = gerarSegredo();\nconsole.log('Segredo Base32:', segredo);\n\n\/\/ Simula a app: gera o codigo atual a partir do mesmo segredo\nconst codigoAtual = authenticator.generate(segredo);\nconsole.log('Codigo gerado:', codigoAtual);\n\nconsole.log('Verificacao valida:', verificarCodigo(codigoAtual, segredo));\nconsole.log('Verificacao invalida:', verificarCodigo('000000', segredo));<\/code><\/pre>\n\n\n\n
Execute com node teste.js<\/code>. A sa\u00edda esperada confirma que o c\u00f3digo gerado passa e que um c\u00f3digo aleat\u00f3rio falha:<\/p>\n\n\n\n
Segredo Base32: KZXW6YTBOI5XW4TBORSXG===\nCodigo gerado: 482915\nVerificacao valida: true\nVerificacao invalida: false<\/code><\/pre>\n\n\n\n
Se a verifica\u00e7\u00e3o v\u00e1lida devolver false<\/code>, o problema quase sempre \u00e9 o rel\u00f3gio do sistema. Sincronize-o e repita. Quando este teste passa, a base criptogr\u00e1fica est\u00e1 correta e pode confiar nela no servidor.<\/p>\n\n\n\n
Passo 12: Projeto completo funcional (server.js)<\/h2>\n\n\n\n
Juntamos tudo num servidor Express com os tr\u00eas endpoints essenciais: ativar o 2FA (devolve o QR), confirmar a ativa\u00e7\u00e3o, e fazer login com o segundo fator. Para manter o exemplo focado, usamos um objeto em mem\u00f3ria como base de dados; substitua-o pela sua camada de persist\u00eancia real.<\/p>\n\n\n\n
\/\/ server.js\nimport express from 'express';\nimport { gerarSegredo, gerarOtpauthUri, gerarQrCode, verificarCodigo } from '.\/totp.js';\nimport { cifrar, decifrar } from '.\/cripto.js';\nimport { gerarCodigosRecuperacao, fazerHashCodigos } from '.\/recuperacao.js';\nimport { emitirTokenCompleto, exigirMfaCompleto } from '.\/auth.js';\nimport { podeTentar, registarFalha, limparTentativas } from '.\/limitador.js';\n\nconst app = express();\napp.use(express.json());\n\n\/\/ \"Base de dados\" em memoria apenas para demonstracao\nconst utilizadores = new Map();\nutilizadores.set('ana@exemplo.pt', { id: 'u1', mfaAtivo: false, segredo: null });\n\n\/\/ 1) Iniciar ativacao do 2FA: devolve QR e segredo\napp.post('\/2fa\/ativar', async (req, res) => {\n  const { email } = req.body;\n  const u = utilizadores.get(email);\n  if (!u) return res.status(404).json({ erro: 'Utilizador nao encontrado' });\n\n  const segredo = gerarSegredo();\n  const uri = gerarOtpauthUri(email, segredo);\n  const qr = await gerarQrCode(uri);\n\n  \/\/ Guarda o segredo cifrado, ainda como pendente\n  u.segredoPendente = cifrar(segredo);\n  res.json({ qr, segredoManual: segredo });\n});\n\n\/\/ 2) Confirmar ativacao: o utilizador introduz o primeiro codigo\napp.post('\/2fa\/confirmar', (req, res) => {\n  const { email, codigo } = req.body;\n  const u = utilizadores.get(email);\n  if (!u || !u.segredoPendente) return res.status(400).json({ erro: 'Sem ativacao pendente' });\n\n  const segredo = decifrar(u.segredoPendente);\n  if (!verificarCodigo(codigo, segredo)) {\n    return res.status(401).json({ erro: 'Codigo invalido' });\n  }\n\n  u.segredo = u.segredoPendente;\n  u.mfaAtivo = true;\n  delete u.segredoPendente;\n\n  const recuperacao = gerarCodigosRecuperacao();\n  u.recuperacaoHashes = fazerHashCodigos(recuperacao);\n  res.json({ ativo: true, codigosRecuperacao: recuperacao });\n});\n\n\/\/ 3) Login com segundo fator (palavra-passe ja validada antes)\napp.post('\/login\/2fa', (req, res) => {\n  const { email, codigo } = req.body;\n  const u = utilizadores.get(email);\n  if (!u || !u.mfaAtivo) return res.status(400).json({ erro: '2FA nao ativo' });\n\n  if (!podeTentar(u.id)) {\n    return res.status(429).json({ erro: 'Demasiadas tentativas. Tente mais tarde.' });\n  }\n\n  const segredo = decifrar(u.segredo);\n  if (!verificarCodigo(codigo, segredo)) {\n    registarFalha(u.id);\n    return res.status(401).json({ erro: 'Codigo invalido' });\n  }\n\n  limparTentativas(u.id);\n  res.json({ token: emitirTokenCompleto(u.id) });\n});\n\n\/\/ Endpoint protegido de exemplo\napp.get('\/perfil', exigirMfaCompleto, (req, res) => {\n  res.json({ mensagem: 'Acesso concedido', userId: req.userId });\n});\n\napp.listen(3000, () => console.log('API 2FA a correr em http:\/\/localhost:3000'));<\/code><\/pre>\n\n\n\n
Arranque com npm run dev<\/code>. Teste a ativa\u00e7\u00e3o com um pedido ao endpoint \/2fa\/ativar<\/code>, leia o QR com a sua app, e confirme com \/2fa\/confirmar<\/code>. A partir da\u00ed, cada login passa por \/login\/2fa<\/code>. Tem agora um sistema de autentica\u00e7\u00e3o de dois fatores<\/strong> funcional, com segredo cifrado, c\u00f3digos de recupera\u00e7\u00e3o e limita\u00e7\u00e3o de tentativas.<\/p>\n\n\n\n
Erros comuns ao implementar 2FA<\/h2>\n\n\n\n
Cinco armadilhas aparecem repetidamente em implementa\u00e7\u00f5es reais. Evit\u00e1-las desde o in\u00edcio poupa horas de depura\u00e7\u00e3o e fecha buracos de seguran\u00e7a.<\/p>\n\n\n\n