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

141 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Login com biometria (WebAuthn) em `/campanha`
Status: entregue (2026-07-28)
Atualizado em: 2026-07-28
Item do roadmap: [docs/roadmap.md](../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](../../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](../../src/collections/CampaignUser.ts) 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
```mermaid
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`](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`