teqo-backup/docs/plans/login-biometrico-campanha.md
Francisco Ignácio Fontoura Solla fb64e36537 Record the B40 closing triage without opening an ID.
Nothing left from the reviewers scored high enough to earn a roadmap item, so
the four discards are written down with their reasons instead — a discard whose
reason is missing comes back next session dressed as an obvious win. The one
worth keeping is the enrollment toast's third spelling of the failure copy: it
is deliberate, because that toast has no retry affordance and ending the
sentence in "Tente novamente." would be a false instruction.

Three engineering deferrals gained the trigger they lacked (shared HMAC core,
an optional `bodySchema` on the route shell, promoting `postJson`) — all three
are second-call-site abstractions, so the trigger is the third.

Also corrects two statements this delivery falsified: the notebook still said
`postJson` translates `SyntaxError`, which the simplify pass deleted, and the
roadmap's B40 item carried the pre-optimization 130 kB that its own header line
had already restated as 126 kB.
2026-07-28 12:34:59 -03:00

14 KiB
Raw Blame History

Login com biometria (WebAuthn) em /campanha

Status: entregue (2026-07-28) Atualizado em: 2026-07-28 Item do roadmap: docs/roadmap.md (Trilha B, item B40) Impeccable: C — fluxo novo na tela de login + registro pós-primeiro-login; brief compacto Appetite: ~1,5–2 dias eng; WebAuthn platform authenticator + storage server-side + UI login/perfil; migration leve Responsável: —

Design (Impeccable)

Âncoras: PRODUCT.md (Field Desk; PWA de campo) / DESIGN.md · tema data-theme='campaign' · LoginForm + shell de auth.

Na implementação (implement-roadmap-item): shape → craft → critique → polish (fluxo multi-passo; shape compacto basta).

Brief compacto:

  • Persona / contexto: Assessor no PWA/iPhone com Face ID / Android com digital, depois do primeiro login com senha; quer reabrir o app sem digitar senha a cada sessão curta.
  • Job principal: no dispositivo já confiável, autenticar com biometria do SO e obter sessão campaign-token válida.
  • Estratégia de cor: Restrained — botão secundário "Entrar com digital / Face ID" abaixo do form; sem branding de "passwordless startup".
  • Edit where you see: não — auth.
  • Anti-goals: substituir senha por completo no v1; biometria como único fator sem enrollment consciente; SDK nativo fora do browser; misturar com auth de /admin.

Dados → decisão → apresentação

Dados: N/A — credenciais WebAuthn; nenhum KPI/série/mapa.

Contexto

Hoje o único caminho de login é senha (payload.login → cookie campaign-token). B39 alonga a sessão (checkbox "Lembrar de mim"), mas quando a sessão expira o usuário digita de novo. Em dispositivos com Secure Enclave / StrongBox, o browser expõe WebAuthn (navigator.credentials) com platform authenticator — a UI do SO pede digital/Face ID e devolve uma asserção verificável no servidor.

Pedido de produto (2026-07-26): após o primeiro login, oferecer login com digital nos aparelhos que tiverem leitor.

Não há WebAuthn / passkey / Credential Management de produto no código hoje. O PWA (D1 ✓) é o melhor host (standalone), com as mesmas limitações do Safari iOS (WebAuthn suportado em versões recentes; validar no craft).

Objetivos

  • Após login com senha bem-sucedido neste dispositivo, oferecer enrollment opt-in ("Usar digital / Face ID neste aparelho").
  • Na próxima visita à tela de login (sessão expirada), se houver credencial local discoverable / allowCredentials, mostrar botão de biometria que completa login sem senha.
  • Credenciais amarradas a um campaignUser; revogáveis (remover neste dispositivo / remover todas no /campanha/perfil).
  • Sessão resultante = mesmo cookie campaign-token (TTL alinhado a B39: preferir o TTL "lembrar" no login biométrico, pois o dispositivo já é o opt-in de confiança).
  • Guardrails: migration para armazenar credenciais; sem Consent novo (fator de auth da conta staff/leader já autenticada — não é coleta de PII de apoiador); access: só o dono gerencia as próprias credenciais; overrideAccess: false nas mutações com user.

Decisões travadas

  • WebAuthn platform authenticator (passkey/device-bound), não "ler a digital e comparar com hash nosso". O SO faz a biometria; o app só verifica a asserção. Rejeitado: (a) Credential Management API só para autofill de senha (não é feature de produto); (b) armazenar senha cifrada e "desbloquear" com WebAuthn sem asserção server-side (pior modelo); (c) SDK nativo / Capacitor (fora do app Next).
  • Enrollment só depois de sessão senha válida (ou reset de senha recente). Rejeitado: registrar passkey a partir de e-mail mágico sem senha no v1 (explode recovery).
  • Storage server-side das credenciais (collection ou campo array versionado em campaignUser) com credentialID, publicKey, counter, transports, label do dispositivo. Rejeitado: só localStorage (não autentica no servidor); depender só do password manager do browser sem registro nosso (não controlamos UX "Entrar com digital").
  • Login biométrico emite o TTL longo (B39 "lembrar") — o enrollment no dispositivo é o consentimento de confiança. Rejeitado: TTL curto no biométrico (derrota o job); exigir checkbox remember no fluxo biométrico.
  • i18n e naming: campaignWebAuthn, passkey/webauthnCredential nos identificadores; copy pt-BR ("Entrar com digital ou Face ID", "Ativar neste aparelho").

Revisão na entrega (2026-07-28)

As seis lacunas que a auditoria pré-implementação abriu, e como cada uma fechou:

  1. Como o token é forjado sem senha. Não existe caminho password-less no Payload 3.82.0 — loginOperation exige password. issueCampaignWebAuthnSession (src/utilities/campaignWebAuthnSession.ts) monta a sessão só com exports públicos: payload.db.findOne → checkLoginPermission → addSessionToUser (de payload/shared) → getFieldsToSign + jwtSign → setCampaignAuthCookie.
  2. A mina, confirmada e neutralizada. addSessionToUser reescreve o documento inteiro do usuário. Carregar com payload.findByID passaria pelo afterRead removePrivateAuthFields de CampaignUser e gravaria de volta um usuário sem sessions nem email, derrubando todas as outras sessões e transformando avatar em objeto. O db.findOne cru está no código com o comentário nomeando o perigo, e campaignWebAuthn.int.spec.ts prova que uma sessão pré-existente sobrevive ao mint.
  3. Concorrência. O mint roda em withPayloadTransaction + acquireTextAdvisoryLocks(['campaign-webauthn-session:{id}']), precedente do E14.
  4. getFieldsToSign exige email: string. Conta de liderança não tem e-mail; passamos user.email ?? '', claim decorativa (payload.auth relê o usuário do banco).
  5. RP ID / origem — e o furo que a auditoria não previu. getCampaignWebAuthnRelyingParty deriva rpID/origin de getCampaignInviteBaseURL e devolve null quando ela falha. Mas isso não bastava: num preview da Vercel a função devolvia a origem canônica com sucesso, o botão aparecia, e o browser estourava SecurityError porque o host servindo a página é outro. A função agora compara o host do request (origin, ou x-forwarded-host/host) com o host derivado e devolve null quando divergem — a UI se esconde onde a cerimônia não pode funcionar, que era a intenção declarada.
  6. Challenge em cookie HMAC, path /campanha, 5 min, apagado na verificação (molde de supporterImportToken.ts). A armadilha custou uma rodada de e2e: a primeira versão gerava o challenge por conta própria e deixava o @simplewebauthn/server gerar o dele, então o valor no cookie e o valor assinado pelo autenticador eram bytes diferentes e todo register respondia 400. O helper agora recebe o challenge que generateRegistrationOptions/generateAuthenticationOptions já produziram e guarda aquela string base64url, verbatim.

Outros achados da entrega:

  • Deleção de campaignUser quebrava. A FK que o Payload gera é ON DELETE SET NULL sobre um user_id NOT NULL. Em vez de editar a migration, CampaignUser ganhou um beforeDelete que apaga as credenciais do usuário — cascade explícito, na mesma transação.
  • Mensagem de conta bloqueada. checkLoginPermission lança o erro genérico do Payload; o mint captura e relança a cópia pt-BR, para que o usuário trancado saiba que é bloqueio e não falha de biometria.
  • Anúncio duplicado no leitor de tela. O erro vivia no FieldError e na região aria-live do botão; o sr-only agora só anuncia o estado pendente.
  • Medição de bundle: @simplewebauthn/browser adiciona 3,0 kB gzip (orçamento do plano: 10 kB), com /campanha/login em 130 kB de First Load JS. Sem débito registrado.
  • e2e com autenticador virtual CDP cobre cadastrar → sair → entrar com biometria → revogar. Para isso o fixture ganhou expectedRequestFailurePaths: o teste da credencial revogada provoca um 4xx de propósito, e o guard global de falhas tratava o console.error do fetch como erro não tratado.

Questões em aberto (fechadas na entrega)

  • Collection nova campaignWebAuthnCredential vs array no campaignUser? Opções: A) collection join (1:N, admin-visível, delete fácil) | B) array no user. Recomendação: A — contadores WebAuthn e revogação por dispositivo ficam limpos; access create/read/delete = self. Entregue como A.
  • Mostrar o botão biométrico antes de digitar o identificador (discoverable credentials) ou depois? Opções: A) botão sempre visível se o browser reportar platform authenticator + há credencial no device | B) só após blur do identificador. Recomendação: A com conditional UI (PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable). Entregue como A, com um segundo gate no servidor (o RP tem de estar configurado para o host que serve a página).

Abordagem proposta

flowchart LR
  pwd["Login senha<br/>(B39)"] --> offer["Prompt enrollment<br/>opt-in"]
  offer --> reg["navigator.credentials.create"]
  reg --> store["POST /campanha/webauthn/register<br/>salva credential"]
  loginUI["LoginForm"] --> get["GET challenge"]
  get --> assert["navigator.credentials.get"]
  assert --> verify["POST /campanha/webauthn/login"]
  verify --> cookie["setCampaignAuthCookie<br/>TTL longo"]

Componentes:

  • Lib pura de challenge/verify (preferir pacote maduro tipo @simplewebauthn/server + browser pair — depth: não reinventar CBOR/COSE).
  • Routes / server actions sob /campanha: challenge de registro, registro, challenge de login, verificação → cookie.
  • UI: LoginForm (botão biométrico); banner/dialog pós-login ou toggle em /campanha/perfil.
  • Migration: pnpm migrate:create add_campaign_webauthn_credentials (collection ou fields).
  • Testes: unit dos helpers de verify com fixtures; int do register/login happy path + reject counter replay; e2e condicional (mock de WebAuthn no Playwright).

Depth check: reusa setCampaignAuthCookie / getCampaignUser; não cria segundo cookie. Não acoplar ao D2 push.

Dependências

  • Soft: B39 (sessão longa / "lembrar") — ideal landar antes para TTL e copy coerentes no mesmo LoginForm. Sem B39, B40 ainda funciona com o default atual.
  • Soft: D1 ✓ PWA (melhor host; não bloqueia).

Não escopo

  • Remover senha / passwordless-only.
  • Passkeys cross-device (iCloud/Google sync) como requisito — aceitar se o SO oferecer, não construir conta de sync.
  • Biometria para users / /admin.
  • MFA obrigatória para coordenador.

Rabbit holes

  • Attestation enterprise / MDM. Mitigação: none attestation no v1.
  • Polyfill WebAuthn em browsers velhos. Mitigação: feature-detect; esconder botão; senha continua.
  • Recovery se o aparelho morre. Mitigação: senha + "esqueci senha" já existem; listar/revogar credenciais no perfil.

Adiado com gatilho

  • Passkeys sincronizadas multi-device como copy de produto. Revisitar quando: mesa pedir login no laptop novo sem senha após enrollment no celular.
  • Exigir re-senha a cada N dias mesmo com biometria. Revisitar se assessoria jurídica pedir após lote Onda 0.
  • Núcleo HMAC compartilhado com supporterImportToken.ts. ~35 linhas idênticas (assinar, comparar em tempo constante, base64url), 2 call sites. Revisitar quando: um terceiro consumidor de cookie/token assinado nascer — extrair agora mexeria no caminho do token de import por nada.
  • bodySchema opcional em campaignJsonMutationRoute. Duas das quatro rotas WebAuthn não têm corpo para validar e usam campaignWebAuthnNoBodySchema (z.unknown()), porque a casca sempre faz parse. Revisitar quando: nascer uma terceira rota JSON sem corpo fora da biometria — aí o {} que o cliente posta e o schema-fantasma valem um seam.
  • postJson promovido a campaignJsonRequest.ts. A casca de uma linha sobre postCampaignJson só descarta o ok (o discriminante do envelope é que decide), e é o único chamador que quer isso. Revisitar quando: um segundo módulo fora da biometria precisar do payload sem o ok.

Explicitamente fora (triage do fechamento)

Achados dos revisores do /simplify descartados com motivo, para não voltarem como “óbvios”:

  • Sobrepor o import() do módulo de cerimônia ao POST de *-options. Economiza um RTT só na primeira cerimônia do dispositivo (o chunk tem 3,7 kB gzip e fica em cache depois), nunca foi medido em ms, e threading do Promise.all por duas funções exportadas e três ilhas é mais código do que o ganho justifica.
  • Webpack duplicando o módulo de cerimônia em dois chunks lazy (~1,6 kB gzip). Dimensionamento de split-chunk, não coisa do código-fonte; o próprio revisor de performance o pôs abaixo de P2.
  • A terceira grafia da falha de enrollment em BiometricEnrollmentToast. “Não foi possível cadastrar este aparelho agora.” não é a constante compartilhada de propósito: o toast não tem afordância de repetir, então terminar em “Tente novamente.” seria uma instrução falsa. Unificar pioraria a copy.
  • Unit test para campaignWebAuthnClient. O único ramo que merecia pino — a tradução de SyntaxError — foi deletado neste fechamento; o que sobrou é transporte, coberto pelo e2e com autenticador virtual.

Referências

  • docs/roadmap.md (Trilha B · B40)
  • lembrar-de-mim-sessao-campanha.md (B39)
  • src/utilities/campaignAuth.ts, LoginForm.tsx, actions/auth.ts
  • docs/plans/pwa-campanha.md, docs/plans/reset-senha-foto-perfil.md
  • AGENTS.md — Campaign auth
  • PRODUCT.md / DESIGN.md