Segurança, Autenticação & Impersonação (RBAC)
Segurança, Autenticação & Impersonação (RBAC & Security)
Section titled “Segurança, Autenticação & Impersonação (RBAC & Security)”Estado actual — botões traduzidos pelo navegador. O botão compartilhado mantém o rótulo no mesmo elemento ao iniciar e terminar o carregamento; a substituição do texto pelo tradutor do Chrome não interrompe essa transição no primeiro acesso e na troca de senha. O bloqueio durante o envio e o anúncio acessível de progresso permanecem ativos.
Estado actual — abertura do link. Falha de rede, HTTP recusado ou espera acima de 15 segundos mantém a página com Try again, sem anunciar link expirado; só a resposta válida da API decide expiração. Um link válido do escritório que pede senha nova inicia o primeiro acesso mesmo se o navegador ainda tem uma sessão dessa pessoa; reabrir um link usado ou vencido numa sessão válida não apaga a senha.
Estado actual — resumo do primeiro acesso. Ao concluir a janela de primeiro acesso depois de criar a senha, cada administrador ativo recebe uma notificação SYSTEM com nome, contato, papel, senha criada, biometria/passkey ativa ou não, Google vinculado (com o e-mail) ou não e horário de conclusão em Londres. As opções continuam facultativas: pular Google ou biometria também encerra e informa o estado real. O servidor registra a configuração em first_access_setups junto da criação da senha, lê os métodos efetivamente cadastrados e aceita a conclusão uma única vez; login comum, troca de senha comum e impersonação não geram esse aviso. O resumo fica persistido e a notificação usa o histórico e os canais push existentes. Fechar/abandonar antes de concluir a janela não anuncia conclusão.
Estado actual — acesso seguinte pelo PWA. Depois da conclusão registrada do primeiro acesso, a primeira abertura autenticada do funcionário (EMPLOYEE) no PWA instalado gera outra notificação SYSTEM para cada administrador ativo: PWA access confirmed, com nome, contato e horário em Londres. usePwaAccessConfirmation observa o modo instalado real, separado do aceite de instalação, e chama /auth/confirm-pwa-access; navegador comum, app nativo, outros papéis e impersonação não contam. Concluir o primeiro acesso dentro de um PWA já aberto não conta como segunda abertura: a confirmação aguarda a próxima abertura do app. pwa_accessed_at e as notificações no histórico são gravados juntos; reaberturas, dispositivos concorrentes e retries não duplicam o aviso. Falha de conexão não bloqueia o funcionário e permite tentativas posteriores; falha de push mantém a confirmação no histórico. O modo PWA é informado pelo cliente autenticado, não uma atestação do sistema operacional. Registros anteriores recebem a data da primeira abertura observada após a implantação, sem inventar acessos antigos; um novo primeiro acesso por link reinicia a confirmação.
Quando /api/auth/me responde 401, a restauração inicia o chunk da tela desconectada e aquece /api/public/config em paralelo. A resposta informa apenas se existe um cookie HttpOnly de refresh (available/absent), nunca seu valor: ausência confirmada elimina um POST condenado a outro 401, enquanto header ausente de um Worker antigo mantém o fallback compatível. Se a credencial existe, /api/auth/refresh continua sendo validado e rotacionado normalmente; se for recusado, o loader compartilhado com React.lazy já está pronto. O formulário aguarda somente seu próprio chunk: falha ou lentidão da configuração pública não bloqueia a interface, e a leitura do controller reutiliza a política HTTP de cinco minutos do endpoint. Assim o login social perde uma etapa serial em inicializações anônimas frias sem confiar em marcador local nem enfraquecer a restauração autenticada.
No Android, o botão Google permanece acionável enquanto a inicialização antecipada do provider termina. O primeiro toque aguarda a mesma Promise serializada, em vez de ser descartado e exigir um segundo toque; o lock síncrono continua impedindo duas Activities concorrentes. Perfil, configurações do chat e navegação usam useLogoutAction: a trava é adquirida antes até mesmo de uma confirmação opcional, todas as superfícies exibem o mesmo loading acessível e nenhuma anuncia sucesso antes da revogação. A operação de contexto também é idempotente, e o menu principal mantém uma ação de saída acessível mesmo recolhido. Um toque em push durante a restauração da sessão não é perdido: PWA, Android e iOS conservam apenas o destino acompanhado do recipientUserId assinado pelo envelope de notificação; no cold-start PWA o Service Worker acrescenta esse identificador somente depois de validar o cookie ativo. Depois da restauração, o destino é aberto somente para a mesma conta e é descartado para qualquer outra.
O retorno tardio dos seletores nativos Google/Apple pertence à montagem que iniciou o pedido: se a tela de acesso desmontou durante a Activity, o token não é enviado ao backend nem produz aviso/estado nessa tela. Na web, a troca entre login e cadastro reinstala o callback do Google; um callback antigo é ignorado, mas o botão da tela atual continua funcional.
O cliente HTTP verifica a geração da sessão e o sinal de cancelamento também depois da leitura assíncrona do corpo JSON, em todos os métodos. Essa leitura tem limite de tempo próprio e encerra de imediato ao cancelar, mesmo se a WebView nunca concluir o corpo. Assim um logout, troca de conta ou desmontagem ocorridos entre a chegada da resposta e a decodificação não entregam dados antigos aos serviços que atualizam stores/cache.
A exclusão de conta trava antes de abrir a confirmação, impedindo dois diálogos ou dois POSTs no mesmo frame, vincula a conclusão à identidade/lifecycle atual e limita o POST a 15 segundos. Cancelamento libera uma nova tentativa, falha mantém a ação disponível e sucesso permanece ocupado até o logout.
Perfil do cliente (2026-10-21). A aba chama-se Sign-in & security e começa por Password (ChangePasswordSection): qualquer pessoa troca a senha quando quiser, pelo mesmo /auth/change-password, com o resultado ao lado do botão; quem entrou por link sem senha (hasPassword === false) não digita a atual. Antes só existiam a troca forçada e a do primeiro acesso. Os endereços do próprio perfil (cliente e equipe) são OwnAddressList: fechados, com Edit; abertos, código postal, complemento e instruções de acesso — sem o pino no mapa nem o what3words, que são do escritório (ClientAddressManager), e um código postal novo apaga o what3words antigo. Para o cliente saem “Calling application” (softphone do escritório), “Toast duration” e o cartão técnico do build em About; as categorias de notificação têm texto do lado dele (CLIENT_CATEGORY_KEYS); o idioma diz só “The language of the app.” (a tradução de conversas é da equipe); e no Menu, abaixo do nome, “Profile & settings” no lugar do papel. No perfil do escritório o crachá do avatar é Manager, não Staff, e a taxa horária só aparece para a funcionária; softphone, calendário e o cartão do build ficam. Explicações longas deixaram as maiúsculas (CFCheckbox, descrições do perfil).
Em Profile → Sign-in & security → Linked Accounts, Android e iOS vinculam Google pelo mesmo provider nativo usado no login; web/PWA/desktop preservam o botão Google Identity Services. A configuração pública necessária é lida do boot com teto de 12 segundos, credenciais da sessão e cancelamento ao desmontar ou trocar de conta; a configuração anterior é apagada antes da nova leitura, impedindo que uma resposta tardia habilite o provider para outra identidade. A primeira ativação nativa aguarda a inicialização serializada, callbacks possuem lock e owner ID, e uma resposta iniciada por outra conta é descartada antes de alcançar POST /api/auth/link-google. Desvincular adquire a trava antes da confirmação, mantém loading até a resposta real e só confirma sucesso para a identidade que iniciou a operação.
Ativar e remover passkeys no Perfil compartilha lock síncrono e epoch da conta. Uma conclusão de Face ID, Touch ID, impressão digital ou Windows Hello iniciada antes de logout/impersonação não altera a identidade seguinte. Remover biometria só apaga a dica local e anuncia sucesso depois que /api/auth/webauthn/remove responde com sucesso; rede ou servidor indisponível preservam a dica e informam que a credencial continua ativa.
A troca administrativa de identidade possui lock síncrono antes do primeiro await e epoch vinculado ao usuário atual. O seletor emite apenas feedback de seleção ao iniciar; sucesso ocorre somente depois que o backend autoriza, o novo cookie é confirmado e a limpeza privada termina. Falha restaura o seletor, produz háptico de erro e mensagem recuperável, enquanto uma conclusão pertencente a uma tela ou identidade antiga é descartada. Em sucesso, o carregador permanece ativo até a navegação efetiva, impedindo que a interface administrativa reapareça com a sessão já trocada.
A camada de segurança do Prime Crown garante controle estrito de acessos aos dados operacionais e financeiros através de tokens JWT em Cookies HttpOnly, validação de permissões RBAC no Hono e suporte a Impersonação de Usuários para Suporte.
O login Google possui duas entradas equivalentes. No navegador/PWA, Google Identity Services entrega o ID token ou usa o redirect server-side; no Android Capacitor, o provider nativo abre o seletor de contas do sistema usando os scopes OIDC padrão já incluídos pelo plugin (openid, e-mail e perfil), sem options.scopes ou alteração especial da MainActivity. Ambos enviam o ID token ao mesmo backend, que valida a audience contra o OAuth Web Client ID antes de criar a sessão HttpOnly. Um lock síncrono aceita somente uma credencial Google por vez também no callback web/PWA, cobrindo replay do provider ou One Tap concorrente antes do React pintar o loading; Android/iOS preservam o lock da Activity nativa entre provedores. Antes de recarregar, o cliente confirma que esse cookie já pode ser lido por /api/auth/me; a janela de confirmação cobre a latência adicional do WebView e uma falha não é tratada como sucesso, evitando que o primeiro toque volte silenciosamente ao login. Na variante web, container e wrapper do GSI reservam exatamente 48 px e contêm overflow; o iframe recebe 44 px desde a inserção e fica centralizado, em vez de crescer de 22 px depois do primeiro frame. A montagem anônima/personalizada não desloca mais o card, sem alterar o conteúdo cross-origin ou a marca do Google. O cliente OAuth Android serve para autorizar o binário instalado e deve combinar o package uk.co.primecrowncleaning.app com o SHA-1 do certificado da instalação; ele não substitui a validação server-side.
Os rótulos auxiliares e divisores da autenticação preservam contraste AA sobre o card branco. O documento raiz também publica uma descrição estável para navegadores e indexadores.
Em viewports horizontais com até 560 px de altura, o mesmo card compartilhado adota cabeçalho em linha, espaços menores e corpo compacto. Assim Google, Apple quando disponível, biometria e a entrada por e-mail/telefone permanecem reconhecíveis na primeira tela de celulares rotacionados, split-screen e janelas desktop baixas. Formulários expandidos continuam dentro da região rolável e preservam safe areas e recuperação quando o teclado reduz o viewport.
robots.txt e llms.txt são servidos como texto antes do fallback da SPA, mantêm API, chat e guia interno fora de crawling e apontam somente para informações realmente públicas. Web Vitals observados antes da restauração da sessão ficam temporariamente em memória; são enviados apenas depois que AuthContext confirma uma identidade, e são descartados no login anônimo para não produzir telemetria 401.
No iPhone, a presença de Google Sign-In e de cadastro público torna arriscado depender da exceção empresarial da regra 4.8 da App Store. functions/lib/appleIdentity.ts valida o ID token contra o JWKS público da Apple e exige assinatura RS256, issuer oficial, audience configurada, validade temporal e subject. POST /api/auth/apple localiza primeiro pelo sub, aceita vínculo/criação inicial somente com e-mail verificado (inclusive relay privado), reutiliza funcionários/clientes existentes e emite a mesma sessão HttpOnly. O provider solicita troca correta do authorization code; quando as credenciais Apple estão configuradas, functions/lib/appleOAuth.ts troca o código no servidor e o refresh token é cifrado em D1 para futura revogação. Capability, entitlement e provider nativo estão incluídos; login e cadastro exibem o botão Apple apenas quando getRuntimePlatform() retorna ios, mantendo Android e PWA no fluxo próprio.
Passkeys WebAuthn descobríveis mantêm a chave privada no autenticador seguro do dispositivo e persistem somente a chave pública no backend. O botão de login aparece desde o primeiro render em runtimes WebAuthn e nos shells nativos com provider empacotado, evitando que o cartão cresça depois da detecção e gere layout shift. A capacidade não fica limitada ao autenticador de plataforma: passkeys sincronizadas e chaves de segurança externas também permanecem válidas no desktop. Em aparelhos novos, uma autenticação sem e-mail permite que Google Password Manager ou o autenticador do sistema apresente as passkeys sincronizadas e que o backend resolva a conta pelo credential ID. As chamadas de opções, verificação e remoção usam o transporte limitado de 15 segundos; o prompt do autenticador fica deliberadamente fora desse prazo, para que o usuário possa concluir Face ID, Touch ID, impressão digital ou chave externa sem uma corrida artificial. A admissão é única: senha, refresh, Google, Apple, magic link e WebAuthn consultam bloqueio/revogação e, para funcionários, o is_active do cadastro. Desativar a pessoa encerra a conexão em tempo real e impede uma nova sessão por qualquer método; impersonação administrativa respeita a mesma regra. O cliente guarda somente marcadores opacos de UX; a migração primecrown_passkey_markers_v3 converte e apaga as antigas listas e dicas de e-mail em texto claro. A dica Google é limitada ao sessionStorage. password_hash é omitido nos endpoints de autenticação e bloqueado defensivamente pelo mapper compartilhado antes de qualquer resposta JSON.
Enquanto o prompt biométrico está ativo, a tela substitui as demais ações de autenticação por um único indicador de progresso. Isso impede cliques concorrentes e restaura todas as opções automaticamente após cancelamento ou falha.
Os controles textuais da autenticação também preservam alvo de toque mínimo de 44 px: expansão de email/senha, cadastro manual, recuperação, criação de conta e retorno ao login. touch-manipulation mantém resposta direta sem alterar a hierarquia visual leve desses links, compartilhando a mesma ergonomia entre navegador, PWA, Android e iOS.
Login e cadastro anunciam os estados assíncronos de Google e biometria como status ocupados e educados. O botão Apple preserva seu nome acessível, publica aria-busy e permanece desabilitado enquanto o provider responde; todos os spinners ficam decorativos para VoiceOver/TalkBack.
Falhas nos fluxos de login, cadastro, recuperação, redefinição e troca obrigatória são regiões alert; a confirmação de recuperação é um status educado. A troca obrigatória usa o loading compartilhado de Button, e os botões de revelar senha publicam nome contextual e aria-pressed.
Falhas inesperadas de login, cadastro, sessão, impersonação, recuperação/troca de senha, Google OAuth e WebAuthn passam por authError.ts. O diagnóstico é sanitizado e classificado em system_logs; nenhuma resposta ou escrita de console recebe a exceção bruta. Mensagens funcionais — credencial inválida, conta existente, token inválido/expirado, autorização e orientação biométrica — preservam status e texto próprios. Assim o mesmo contrato atende navegador, PWA, desktop, Android e iOS sem empobrecer a correção do formulário.
As respostas JSON de identidade passam por parseApiJson mesmo quando o fluxo usa fetch direto em vez de CloudClient. Isso inclui restauração/refresh, senha, Google, Apple, telefone, magic link, impersonação, vínculo, troca e redefinição de senha, passkeys e exclusão pelo Perfil. O tratamento funcional de 4xx e seus fallbacks permanece igual, mas campos de instante SQLite são fixados em UTC antes de alcançar estado React; Safari/iOS, Android/Chromium, PWA e desktop não podem interpretar a mesma sessão ou auditoria em horários diferentes.
Login por senha ou biometria, cadastro, recuperação, magic link, troca obrigatória e redefinição de senha possuem trava síncrona contra toque duplo, bloqueiam campos e navegação durante a requisição e ignoram respostas que chegam depois da troca de tela, troca de usuário ou desmontagem. Senha, Google, Apple, cadastro, telefone, solicitação/verificação de link, recuperação, redefinição, impersonação, vínculo Google e troca de senha usam o transporte limitado compartilhado: mutações encerram em 15 segundos, e os formulários públicos abortam também ao trocar de tela ou desmontar. Depois que um provider ou credencial emite cookie, a confirmação por /api/auth/me possui teto total de oito segundos e tentativas individuais de dois segundos; uma leitura presa não bloqueia o retry seguinte nem deixa a WebView em loading indefinido. O token recebido por link é mantido apenas na memória e removido imediatamente da barra de endereço e do histórico visível. Em dispositivos nativos, início, sucesso e falha também produzem feedback tátil sem antecipar uma confirmação do servidor; cancelar a biometria continua sendo uma saída silenciosa.
O sanitizador reconhece também nomes compostos de segredo em texto, incluindo client_secret, refresh_token, chaves privadas, de assinatura e de acesso. A proteção vale para erros OAuth, logs dos Workers e telemetria do cliente, além das chaves sensíveis já tratadas em objetos aninhados.
As builds de produção instalam uma fronteira única para os 17 métodos de console que aceitam dados antes dos handlers globais. Browser, PWA e os WebViews Android/iOS preservam somente o primeiro rótulo operacional redigido e números/booleanos; objetos, exceções, payloads de provedores e textos auxiliares são omitidos. E-mail, telefone, UUID e query/hash encontrados no rótulo também são removidos. O console completo permanece disponível apenas no desenvolvimento local, e erros relevantes continuam chegando ao painel administrativo pela telemetria sanitizada.
Logout é uma fronteira de dispositivo, não apenas de cookie. A interface encerra a sessão local imediatamente, cancela e apaga consultas autenticadas e desmonta os dados antes das tarefas de rede, para o comando responder sem atraso também no WebView nativo. No Android/iOS, a leitura do token já persistido recebe um limite curto e a revogação de cookie começa sem aguardar a limpeza do provider; Firebase, Preferences ou unregister nunca ficam entre o toque e /api/auth/logout. Enquanto essa operação ou sua barreira offline estiver ativa, senha, Google, Apple, biometria, telefone e link mágico recusam iniciar uma nova sessão na mesma árvore React; isso impede que uma resposta tardia de logout apague o cookie do login seguinte. Uma impersonação em voo é abortada e vinculada à geração da sessão: sua resposta tardia não pode limpar a barreira, confirmar cookie ou redirecionar depois de logout ou revogação. Cada instalação agora possui uma família opaca de refresh token, preservada a cada rotação: logout e impersonação removem a família inteira, inclusive um sucessor emitido por refresh que já estava em voo, sem afetar as sessões em outros aparelhos. Tokens antigos migram com a própria hash como família, portanto também permanecem revogáveis durante a primeira rotação. Depois o cliente limpa fila offline, histórico de alertas, snapshots de boot e dica Google; Android/iOS também encerram em segundo plano a sessão mantida pelo provider Google. Revogação remota executa a limpeza local mesmo quando a exclusão server-side já não pode ser autorizada, e impersonação apaga conteúdo privado antes de carregar a identidade de destino. As etapas externas são limitadas por tempo e um failsafe de navegação garante que uma ponte nativa travada nunca obrigue o usuário a forçar o fechamento do app. O evento de retomada só revalida sessões já autenticadas: o retorno do seletor nativo Google não pode ser confundido com revogação enquanto a troca do token ainda está terminando.
A limpeza local na saída, na barreira offline e ao encerrar uma impersonação antiga tem limite de três segundos: um Cache API que nunca responde não mantém a tela de acesso no loader nem a Promise de logout pendente. Cada /api/boot traz o ID de referência da sessão que o servidor validou; antes de hidratar stores, o cliente exige correspondência com a identidade restaurada e tenta eliminar um snapshot divergente. Um snapshot antigo sem esse ID também é recusado quando a rede falha, em vez de expor dados de outra conta.
Mutações otimistas de clientes, funcionários, serviços, entidades fiscais, leads, adicionais e tarefas também pertencem à geração da sessão que as iniciou. Uma falha antiga não reinsere dados após logout/troca de conta, nem emite aviso na nova conta; uma confirmação antiga de cliente, funcionário, entidade fiscal ou tarefa não é apresentada como sucesso. A conversão de lead em voo não bloqueia uma conversão da conta seguinte que coincida no ID. A lista de tarefas ainda não salvas é apagada junto com as tarefas no logout; uma conclusão tardia de gravação individual ou em lote não pode recriá-la na conta seguinte.
Antes de remover a identidade React, o cliente grava uma barreira opaca pc_logout_pending_v1, sem ID, e-mail ou token. Como JavaScript não consegue apagar diretamente um cookie HttpOnly quando está offline, uma nova inicialização consulta essa barreira antes de /api/auth/me: tenta novamente o logout idempotente e permanece na tela de acesso se a rede ainda estiver ausente. A barreira só é removida por revogação confirmada ou por um novo login confirmado, portanto reiniciar Android/iOS, recarregar a PWA ou fechar o desktop não ressuscita a sessão que o usuário já encerrou.
Erros de campo em CFInput combinam aria-invalid, aria-describedby e uma região alert, mantendo o texto associado ao controle e anunciando validação dinâmica. Os disclosures de senha e cadastro manual usam aria-expanded e aria-controls, além de esconder a seta decorativa.
Exclusão de conta é iniciada na área destrutiva separada de Profile → About por POST /api/auth/account-deletion. A confirmação explica que a rota autenticada grava/atualiza uma única linha PENDING em account_deletion_requests, define deletion_due_at para 30 dias, revoga todos os refresh tokens, eleva access_revoked_at, aplica bloqueio temporário e limpa os cookies do dispositivo atual. Se houver vínculo Apple, a rota também revoga o refresh token pelo endpoint oficial e registra o resultado; a conclusão administrativa é bloqueada enquanto essa revogação estiver pendente, falhar ou exigir nova autorização. Após a desativação, todos os administradores recebem e-mail com o prazo e o caminho Settings → Account Deletions; admin_notification_status audita o envio sem transformar uma indisponibilidade do Resend em falha da solicitação. A fila exclusiva de ADMIN consulta e resolve solicitações por /api/auth/admin/account-deletions; concluir ou rejeitar exige confirmação explícita da revisão de retenção, registra horário e administrador responsável e não executa uma remoção genérica potencialmente destrutiva. A fila adquire lock antes da confirmação, bloqueia toda ação concorrente, limita mutações a 15 segundos e trata leituras como latest wins, abortando a anterior e descartando resposta antiga. Revogação de acesso da equipe usa o mesmo teto. Após a resolução, o usuário recebe confirmação pelo Resend; notification_status audita esse segundo envio. Antes de marcar COMPLETED, o operador deve anonimizar/remover os dados sem base legal e preservar somente registros fiscais, trabalhistas, antifraude ou de disputa pelo prazo aplicável. A página pública mantém e-mail como fallback para quem perdeu acesso, nunca como etapa obrigatória dentro do app.
No shell iOS, Google e Apple compartilham um único lock de autenticação social. Enquanto um provider está aberto, o outro botão fica desabilitado e o hook recusa uma segunda Activity mesmo se um toque escapar da interface; callbacks dos dois sheets não podem cruzar sessão, loading ou troca de token. Em instalação nova, o primeiro toque Google aguarda a mesma leitura pública deduplicada do Web Client ID e inicializa o provider com o valor resolvido, sem depender de um segundo render ou segundo toque. Essa leitura usa o transporte limitado compartilhado, encerra em 12 segundos e é abortada ao desmontar o login; rede degradada não pode prender indefinidamente a primeira ativação, e a Promise é liberada para uma tentativa posterior.
A restauração inicial mantém um único AbortController e timeout ativos durante /me, refresh e a segunda leitura, cancelando tudo no teardown. Qualquer início de sessão — senha, Google, Apple, telefone, biometria, magic link ou impersonação — também invalida a restauração inicial antes de chamar o servidor: mesmo um WebView que resolva um fetch já abortado não pode publicar a identidade anterior sobre a tentativa nova. Revalidações de app-resume são latest wins, abortam a anterior e confirmam o ID do usuário no limite da revogação; um 401 atrasado de outra sessão não encerra a conta atual. Revogação confirmada remove imediatamente o usuário da UI antes da limpeza de push/storage e da navegação final.
Uma revalidação ao voltar para a aba/app também compara a identidade e o escopo (papel, tipo de cadastro e troca obrigatória de senha) devolvidos por um 200 com a conta em tela. Se o cookie passou a pertencer a outra conta ou as permissões mudaram, a interface antiga é desmontada e seu cache privado é limpo antes de recarregar; a sessão nova não é revogada. Uma resposta iniciada antes de novo login ou troca de sessão é descartada pela geração da sessão. A lógica dessa leitura só é carregada no primeiro retorno ao app, fora do bundle inicial.
Renovação cancelada no meio (2026-09-30): o refresh troca o token no servidor mesmo quando o navegador cancela a requisição (recarga da atualização, validação que aborta a anterior) — o cookie novo nunca chega. Por isso um token trocado há até 30 s (REUSE_GRACE_MS, functions/api/auth/refresh.ts) recebe um sucessor próprio em vez de 401 REFRESH_RACE, que deixava esse navegador na tela de login logo depois de um deploy. Depois dos 30 s, o reuso continua apagando a família.
A confirmação de um novo cookie exige que /api/auth/me devolva a identidade de destino: um 200 atrasado da conta anterior não basta para concluir login, passkey, link mágico ou impersonação. Se a identidade correta não aparecer dentro do limite, a navegação não acontece e a ação informa a falha. A verificação de link mágico consulta a barreira de logout antes de consumir o token; a passkey consulta antes de pedir opções e novamente após o prompt do sistema, antes de emitir o novo cookie.
🔒 1. Fluxo de Autenticação & Impersonação
Section titled “🔒 1. Fluxo de Autenticação & Impersonação”sequenceDiagram
autonumber
actor Admin as Administrador / Gerente
actor User as Cliente / Funcionária
participant Edge as Edge Auth (/api/auth/*)
participant D1 as Cloudflare D1 (auth_accounts)
participant App as Dashboard SPA
Note over User, App: Login Padrão (Email/Senha, Google ou Apple)
User->>Edge: POST /api/auth/login { email, password }
Edge->>D1: Verifica hash PBKDF2 / BCRYPT em auth_accounts
Edge-->>User: Define Cookie HttpOnly `token` (JWT assinado com JWT_SECRET)
Note over Admin, App: Impersonação para Suporte Técnico
Admin->>Edge: POST /api/auth/impersonate { targetId }
Edge->>Edge: Valida se o solicitante possui role ADMIN
Edge-->>Admin: Retorna novo JWT assinado com a identidade do cliente/funcionário
Admin->>App: Navega na aplicação exatamente na visão do usuário impersonado
🛡️ 2. Níveis de Permissão (Roles RBAC)
Section titled “🛡️ 2. Níveis de Permissão (Roles RBAC)”O sistema possui quatro papéis de autorização. LEAD não é um novo valor de role: é um tipo de referência de uma conta CLIENT.
| Role | Escopo de Acesso | Permissões |
|---|---|---|
ADMIN |
Acesso Total | Acesso irrestrito a todos os dados, finanças, configurações de sistema, auditorias, logs e impersonação. |
MANAGER |
Operacional Geral | Gestão de agendamentos, clientes, equipes, suporte por chat e alocação de limpezas. Sem acesso a impersonação crítica. |
CLIENT / EMPLOYEE |
Restrito (Self Service) | Visualizam apenas seus próprios agendamentos, mensagens de chat e extrato/faturas pessoais. |
Email do funcionário (0147)
Section titled “Email do funcionário (0147)”employees.email é opcional para EMPLOYEE: a equipe de campo entra pelo celular (link de acesso). MANAGER e ADMIN continuam obrigados a ter email — o login Google/Apple encontra a pessoa por ele. Sem email, é preciso um celular válido (POST /api/atomic/employees recusa com 400). A impersonação aponta pelo id (targetId) do funcionário ou cliente, nunca pelo email; a conta-stub impersonation_only leva o email e o telefone que nenhuma outra conta já usa (dois clientes com o mesmo email, um lead, alguém da equipe), como o link de acesso; cliente inativo e conta bloqueada são recusados na hora (409), em vez de uma sessão que nunca abre. A 0147 trocou os @import.local da importação por NULL. O link de acesso (/api/auth/access-link) promove a conta-stub a conta real quando ela é a única da pessoa — como o login Google e a redefinição de senha; antes recusava, e quem já fora simulado ficava sem entrada.
Identidade referenciada e cadastro por telefone
Section titled “Identidade referenciada e cadastro por telefone”auth_accounts.reference_type pode ser LEAD, CLIENT ou EMPLOYEE; reference_id só pode ser interpretado junto com esse discriminador. Uma conta com role = CLIENT e reference_type = LEAD vê a mesma tela de cliente (useOwnClientRecord monta o registro a partir do lead: nome e endereços que já deu) e pede visitas pelo mesmo formulário do cliente, que viram quotes; não acessa dados de um cliente contratado. Quando uma cotação é confirmada, o backend muda a referência para CLIENT no mesmo fluxo que cria o atendimento.
Sem auto-cadastro (2026-10-14). Ninguém cria conta por conta própria: antes de uma quote ou de um serviço não há o que fazer no app. A conta só nasce para quem já está no cadastro — cliente (pré-cadastro do gestor), equipe, ou lead que pediu quote — achado pelo e-mail que o Google ou a Apple provaram (functions/api/auth/onFile.ts, quoteLeadByEmail); quem não está recebe 403 NOT_ON_FILE (“Ask for a quote first”), e nenhuma porta cria cliente ou lead. Saíram o cadastro por senha (/api/auth/register e o formulário “Create account”: não provava o e-mail e deixaria qualquer um tomar a conta de um cliente pré-cadastrado), o cadastro pendente com verificação de telefone (/api/auth/phone/start, PhoneVerificationStep) e todo o pedido de acesso pelo WhatsApp (whatsappAccessFulfill). Na tela de login, o lugar do “Create account” é “New here? Get a quote” (/quote). Quem está no cadastro e não tem senha entra pelo link de acesso (e-mail na hora; telefone liberado pelo gestor). A tabela whatsapp_access_requests saiu na migração 0213 (sai junto da limpeza semanal).
A matriz canRoleAccessView em src/constants/navigation.ts é aplicada ao menu, parâmetros ?view=, mensagens de navegação do service worker, Universal Links, custom schemes e ao próprio AppRoutes. Tentativas de abrir uma área incompatível com o papel voltam ao Dashboard antes de processar channelId ou reqId. A restauração também é reexecutada quando muda o ID ou o papel da sessão: usa a tela mais recente por referência, sem transformar cada navegação em dependência do efeito, e remove imediatamente uma rota administrativa após redução de privilégio. Essa barreira de interface complementa — e não substitui — o escopo obrigatório aplicado por cada endpoint do backend.
O gate npm run check executa npm audit --audit-level=moderate sobre a árvore travada antes do build. Isso cobre tanto dependências de execução sensíveis — como Hono e DOMPurify — quanto a cadeia local de Workers usada para validar o mesmo backend publicado. Um advisory moderado ou alto precisa ser resolvido e toda a suíte repetida antes do push.
O estado local de logout mantém o carregador global desativado: assim que a identidade vira null, a tela de login aparece no próximo commit, enquanto remoção do push e revogação server-side continuam com o cookie ainda válido. Isso evita que rede degradada transforme a saída em vários segundos de Connecting Engine no Android, iOS, PWA ou desktop.
A inicialização do login social nativo é deduplicada por configuração e serializada quando o Web Client ID ou o conjunto Android/iOS muda. Alternar entre Login e Cadastro não inicia configurações concorrentes do plugin, e a própria ação Google/Apple aguarda a configuração atual dentro do gesto antes de abrir o provider. Falhas liberam o cache para nova tentativa, evitando o primeiro toque sem efeito durante retomada ou configuração tardia da WebView.
O hook compartilhado de push só fica habilitado com usuário autenticado e fora de impersonação. A tela de login não lê permissões nem registra o dispositivo na montagem ou retomada web/nativa; uma chamada de Subscribe sem sessão retorna indisponibilidade explícita. Cada operação captura a identidade e a geração do lifecycle: logout, troca de conta e desmontagem descartam permissões, resultados de registro e feedback tardios. O Web Push propaga cancelamento às leituras/escritas HTTP e revalida após esperas do navegador, impedindo que uma assinatura obtida pela sessão anterior seja salva pela próxima. Cancelar HTTP não desfaz uma gravação já aceita pelo servidor. A desativação explícita também pertence à sessão: callbacks retidos após logout são ignorados; conclusão nativa tardia não sobrescreve a permissão da conta seguinte, e uma busca web antiga não consulta nem remove a assinatura do novo usuário.
O link de redefinição (/reset-password?token=…, por email ou WhatsApp) abre sempre o formulário de nova senha, mesmo quando o navegador já tem uma sessão: a tela de reset é decidida na abertura (resetTokenOnPage, src/shared/auth/resetPasswordLink.ts) e a sessão restaurada não a substitui. O token sai da barra de endereço mas fica no history.state da aba, para que um reload (a atualização automática no boot) volte ao formulário. A redefinição grava password_changed_at, o que encerra todas as sessões anteriores; “Go to Login” leva então ao login.
Links de acesso ficam guardados só como hash. Redefinição de senha, magic link e o link de acesso gerado pela gerência gravam em password_reset_tokens.token o SHA-256 do token (hashToken, em functions/api/auth/utils.ts); o valor bruto só existe no próprio link. Uma cópia do banco, portanto, não contém links de login válidos — apresentar o valor armazenado é recusado como token inválido.
Os limites de tentativa compartilham login_attempts (chaves email:/phone:/ip: do login, com janela de 15 minutos; magic:, magic-ip:, pwreset: e pwreset-ip:, com janela de uma hora). A limpeza feita pelo login apaga apenas linhas com mais de 60 minutos; ela apagava tudo acima de 15 e, com isso, os limites horários de magic link e de redefinição viravam limites de 15 minutos.
O feed ICS compara seu token em tempo constante, e POST /api/scheduling/client-change devolve as visitas pela mesma redação de papel do boot (redactRequestForViewer): o cliente que remarca ou cancela não recebe custo, lucro nem pagamento da equipe.
Arquivos enviados são servidos pela mesma origem do app, e o tipo com que foram gravados decide o que o navegador faz com eles.
/api/uploadgrava o tipo permitido pela extensão (contentTypeForUpload, emfunctions/api/common/mediaTypes.ts), não o que o navegador declara. O tipo declarado só é mantido quando combina com a extensão: em.mp4e.webm, áudio continua áudio, porque o encaminhamento para o WhatsApp decide pelo tipo gravado se o arquivo é mensagem de voz./api/uploads/*envia sempreX-Content-Type-Options: nosniff. O que não é imagem, PDF, áudio ou vídeo sai comoapplication/octet-streamcomContent-Disposition: attachment, inclusive o que chegou pelos webhooks do WhatsApp e da Meta.
Antes, um quote.pdf declarado como text/html era gravado como HTML. Aberto pelo chat, ele rodava como página do app com a sessão do gerente.
Encerrar o acesso de alguém encerra também as notificações. Logout remoto, bloqueio, pedido de exclusão de conta e exclusão do cadastro removem todos os aparelhos da pessoa, navegadores e apps nativos, via forgetPushDevices (functions/api/common/pushDevices.ts). Antes, os aparelhos continuavam registrados (a exclusão removia só os navegadores), e prévias de mensagens e de trabalhos seguiam chegando ao celular de quem já não tinha acesso. O registro de um aparelho passa por getSessionUser, e não só pela assinatura do token, então uma sessão revogada não registra aparelho novo.
Os feeds de agenda (/api/calendar/ics) seguem o acesso de quem assinou. O token do feed nunca expira. Por isso, a cada atualização do calendário, o servidor confere a conta de quem assinou:
- conta bloqueada ou funcionária desativada recebe 401;
- a agenda de outra pessoa exige que quem assinou ainda seja ADMIN ou MANAGER (403 caso contrário).
Antes bastava a assinatura do link, e uma pessoa bloqueada ou um gerente rebaixado continuava vendo nomes, endereços e instruções de acesso das clientes no calendário do celular.
Destino lembrado no login (2026-10-14). Qualquer link do app (/?view=…&reqId=…, &channelId=…), da fatura, de uma mensagem ou de outro lugar, aberto sem sessão mostra o login normal na mesma URL; ao entrar com senha ou Google, o app abre aquela tela. Quem ainda não tem senha (ou a esqueceu) pede pelo “Forgot password?”: o pedido leva o destino (next, aceito só se for uma tela do app — appReturnPath, src/shared/appReturnPath.ts) e o link é um /go/<código> para essa tela (returnDestination → issueAccessLink): entra, abre a tela e trata o primeiro acesso como qualquer /go. Por e-mail, quem tem conta recebe o link de redefinição; quem está no cadastro sem conta recebe o /go na hora.
Primeiro acesso na fatura (2026-10-30). A página /pay só vai ao titular da conta, então quem nunca teve como entrar (awaitsFirstAccess: cliente ativo, com contato, sem senha, Google/Apple ou passkey, e sem bloqueio) vê no rodapé “Your visits, all in one place” com Get started. O toque chama POST /api/public/first-access (rate limit 20/10 min por endereço, só o id da fatura), que reconfere a regra e devolve um /go para o Home, gerado na hora e nunca escrito na página; a conta nasce sem senha e o primeiro acesso segue o caminho de sempre. Assim que a pessoa tem uma forma de entrar, a oferta some e o endpoint recusa com 409: fatura encaminhada depois não abre nada. Quem já tem acesso vê o convite “Open the app” no mesmo lugar, depois de pagar. I have already paid só aparece com ?from=app (o Pay do app): a página pública manda confirmar no app, com fatura em aberto o /go leva a Bills, e /api/payments/transfer-claim não aceita mais pedido sem sessão. O mesmo botão aparece nos dois lugares, abaixo dos dados de pagamento da /pay no app e no cartão de Bills: faz o pedido e avisa na conversa com o escritório; visita paga à equipe só manda a mensagem, porque não há transferência a conferir. No statement, cada fatura paga abre a sua /pay, com o PDF. Sem a confirmação, o pagamento continua sendo achado pelo extrato.
Pedido por telefone passa pelo gestor (2026-10-14). Quem pede o link de acesso ou “esqueci a senha” digitando o telefone: o Bot escreve o link (/go, 48 h, para a tela de destino ou a inicial) como nota interna HELD na conversa direta de quem entra com aquele número — a conta que tem o telefone, inclusive de alguém da equipe, senão o cliente ou lead com ele (accessLinkOwner) (holdAccessLinkForOffice, automação accessLink) e o escritório recebe um push, porque o cliente está esperando. O gestor libera pelo Release de sempre (HeldMessageRelease): com a janela de 24 h aberta vai direto pela API; fechada, sai pelo WhatsApp Business. Vale também para o lead (quem pediu cotação e ainda não é cliente): sem conta, ela nasce nessa hora (toOwnContact em issueAccessLink), sem senha e com must_change_password, e no primeiro acesso ele cria a senha; quem garante é o gestor ao liberar. Por e-mail não há gestor no meio: o link de login e o “esqueci a senha” de quem está no cadastro (cliente ou lead) e ainda não tem conta mandam o link /go na hora para o próprio endereço, e a conta nasce do mesmo jeito — o e-mail é a prova. Só o número cadastrado do cliente ou do lead recebe. A tela responde igual para qualquer número, em texto curto (PHONE_ACKNOWLEDGED: entraremos em contato em breve; para o link na hora, use o e-mail) e com o botão “WhatsApp our office” (whatsappUrl, wa.me do escritório, OfficeWhatsAppLink), que abre o WhatsApp pessoal como na quote pública (openPersonalWhatsApp), nunca o Business, e um número que não é de cliente não cria nada. O /api/go/consume reconfere que a tela é da pessoa. A conversa (/chat/<código>) segue como caso especial: abre para ler antes dos passos de senha e instalação.
Sem link de login (2026-10-15). A tela de login não oferece mais “link de login” e o /api/auth/magic-link (pedido e o antigo ?magicToken=) saiu: o caminho sem senha é “Forgot password?” — por e-mail, o link de redefinição; pelo telefone, o escritório. O botão de abrir os campos de e-mail/telefone, aberto, diz “Use Google or biometrics”; “New here? Get a quote” aparece já na primeira tela. No “esqueci a senha” o botão de pedir some depois do pedido, para não pedir de novo.
Primeiro acesso: uma janela para toda entrada sem senha (2026-10-15). Link de acesso do escritório, “esqueci a senha” (por telefone ou e-mail — o e-mail agora manda o mesmo /go, e a página de redefinição fica só para conta sem pessoa no cadastro) e primeiro acesso terminam na mesma janela (FirstAccessModal), nesta ordem: confirmar dados → criar senha (um campo só, com o olho para conferir) → “Entrada rápida”, uma tela opcional com Google e biometria lado a lado (a biometria só se o aparelho aceita, há e-mail na conta e ainda não está ativa; sem nenhum dos dois, a senha encerra). O indicador mostra “Step n of N · nome” com uma barra. Salvar a senha tira o must_change_password; firstAccessStore mantém a janela aberta até o último passo, também depois de recarregar a aba (auth:first-access-continuing em sessionStorage: a troca de senha revoga a sessão antiga e um refresh em voo recarregava a página e pulava o passo opcional); ali o X só termina, não desloga. “Confirmar dados” é pulado só quando /api/auth/me diz detailsConfirmed: a pessoa já confirmou (quote, primeiro acesso anterior ou senha escolhida antes) e o cadastro tem e-mail e celular com autorização de WhatsApp (equipe: basta o celular) — sem esses, sempre pergunta, porque são o nosso contato. Se a pessoa abandonar a tela ou fechar a aba antes de criar a senha, a sessão não fica aberta (auth:first-access-alive em sessionStorage; na reinicialização sem o marcador ativo, endStaleFirstAccess revoga os cookies com /api/auth/logout), e a janela oferece “Cancelar e sair” em todas as etapas; o link no D1 permanece válido dentro do prazo para ser reaberto pelo WhatsApp. Quem entra normalmente com senha, Google ou biometria nunca vê a janela.
Link do escritório pede senha nova (2026-10-15, 0216). Quem precisa receber um link de acesso não sabe a senha. Por isso o link que o escritório envia (“enviar link de acesso”, issuedByStaff, que não seja de conversa) ou libera para quem pediu entrada (telefone, toOwnContact) sai marcado (app_links.fresh_password): ao abri-lo, a senha antiga (definida pelo escritório, por exemplo) deixa de valer e a conta entra no primeiro acesso — confirmar dados, vincular a conta Google (pode pular) e criar a senha (FirstAccessModal). O link de uma conversa que o escritório encaminha e o link de um aviso automático não mexem na senha.