mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-19 17:13:07 +00:00
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.
141 lines
14 KiB
Markdown
141 lines
14 KiB
Markdown
# 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`
|