O que é o registro

Toda classe recorrente de bug no histórico do FlareWatch foi destilada em uma salvaguarda numerada: uma regra de um parágrafo, uma justificativa e um ponteiro para o lugar no código que a impõe. Novas salvaguardas são adicionadas quando uma classe de bug ou padrão emerge e deve ser evitado de recorrer.

O registro é um documento de trabalho, não texto de marketing. Seu propósito é manter a equipe — e o ciclo de revisão auditado primeiro que a equipe usa — honesta sobre quais regras se aplicam onde. O registro é referenciado em comentários inline do código (por exemplo, // Safeguard 24) para que um leitor de qualquer arquivo individual possa encontrar a regra que governa as linhas circundantes.

Esta página é o resumo público. O registro completo reside no repositório de origem ao lado do código que ele governa. O propósito aqui é dar a um pesquisador de segurança, revisor de subvenção ou colaborador em perspectiva uma noção das categorias que o registro cobre e do tipo de disciplina que ele impõe.

Por que um registro

Um registro de salvaguardas só se justifica se impedir o mesmo bug duas vezes. O histórico do registro é a resposta:

Cada salvaguarda nomeia o bug que previne. Uma regra sem um incidente memorável por trás dela não é uma salvaguarda, é uma preferência de estilo. Preferências de estilo pertencem a regras de lint, não ao registro.
Salvaguardas são referenciadas a partir do código, não apenas de docs. Uma mudança de código que viola uma salvaguarda aparece como um sinalizador no momento da revisão porque o número da salvaguarda está nos comentários circundantes.
Algumas salvaguardas são aplicadas automaticamente. Um subconjunto é aplicado através de regras ESLint ou scripts de shell que rodamem CI. O resto depende da disciplina do autor mais o padrão de revisão audit-first, que se mostrou eficaz na prática.
O registro é mantido honesto por testes. Várias salvaguardas são fixadas por testes de regressão que leem arquivos de fonte como strings e afirmam que anti-padrões não aparecem. Fragilidade é o recurso: um futuro refator que reverte para um anti-padrão falha no teste antes que a regressão chegue à produção.

Categorias

O registro é organizado por domínio. As categorias abaixo são estáveis; salvaguardas específicas dentro de cada uma são adicionadas conforme novos modos de falha são descobertos.

Categoria	O que cobre
Autenticação e autorização	Ponto único de estrangulamento para validação de sessão, verificações de propriedade por carteira em todas as rotas, rejeição de tokens cruzados entre tokens de acesso e atualização, gating de rotas admin.
Integridade dos dados	Normalização de endereço, contratos de conversão de unidades nos limites produtor/consumidor, disciplina de construtor de chaves e regras contra coalescer silenciosamente falhas em valores zero.
Leituras on-chain	Regras de implementação única para qualquer valor lido de um contrato inteligente, resolução de endereço de contrato a partir do registro on-chain e regras contra duplicação de lógica de recompensas.
Exatidão da exibição	Formatação centralizada de números, moedas e datas; segurança nula em cada exibição numérica; disciplina de rótulo APR vs. APY; disciplina de taxa de imposto como efetiva.
Alertas e notificações	Fonte única de verdade para avaliação de alertas entre cliente e servidor; listas de permissão explícitas para quais alertas se propagam para carteiras observadas; regras de supersessão para que um alerta "recompensas chegaram" cancele um alerta obsoleto "recompensas disponíveis"; sincronização de descarte entre dispositivos.
Persistência e cache	Regras para quando o armazenamento canônico é o backend de chave-valor versus localStorage; disciplina de migração; cache de service worker com escopo de deploy; opt-out dinâmico explícito para rotas que leem estado em tempo real.
UI e ciclo de vida	Gates de prontidão de página, pisos monótonos que impedem zeros transitórios de deslocar saldos conhecidos, e regras para renderização de skeleton durante janelas de cold-fetch.
Processo e ferramental	Regras para consentimento explícito de lançamento de recursos, execução de suite completa de testes em mudanças de superfície de alerta, logging estruturado em código servidor, e disciplina de revisão contra correções estilo atalho.

Um punhado de regras representativas

Estes são resumos publicamente seguros de salvaguardas que ilustram o caráter do registro. Eles são parafraseados e abreviados; o texto canônico fica ao lado do código.

Fonte única de verdade para leituras on-chain

Qualquer valor lido de um smart contract — recompensas resgatáveis, saldos, estado de stake, dados de epoch, preços — é computado por exatamente uma função na camada de serviços. Todo recurso que precisa desse valor importa a mesma função. Se duas funções computam o mesmo valor, uma delas está errada; a regra é deletá-la, não adicionar uma terceira.

Ponto único de estrangulamento para validação de sessão

Toda rota autenticada no FlareWatch valida cookies de sessão através de um único helper. Nenhum handler de rota verifica tokens de sessão independentemente. Esse invariante é o que torna a revogação servidor-lado universal — não há portas laterais que contornem a verificação.

Gating de propriedade por carteira, ambos os lados

Rotas por carteira verificam propriedade servidor-lado, não cliente-lado. A auditoria original estabeleceu a regra porque trabalho anterior havia fechado os gates cliente-lado mas deixado endpoints servidor-lado completamente sem gate. As duas metades agora são rastreadas como entregas explícitas separadas — fechadas no cliente, fechadas no servidor — para impedir que esse modo de falha recorra.

Use formatadores centralizados, nunca inline

Toda formatação de números, moedas e datas passa por um pequeno conjunto de auxiliares centralizados. Nenhum componente formata inline. A regra não tem nada a ver com estilo: quando uma definição de locale ou moeda muda, toda a superfície da aplicação é atualizada. A divergência entre superfícies é silenciosa e difícil de notar até que um usuário a identifique.

Conversões de unidades são documentadas em ambas as extremidades

Quando duas partes do sistema trocam valores cuja unidade pode ser ambígua (segundos vs. milissegundos, decimal vs. percentual, endereços em minúsculas vs. com checksum), a convenção é documentada tanto no produtor quanto no consumidor. Um comentário em apenas uma extremidade se torna obsoleto; apenas um contrato de limite que é verificado em ambas as extremidades sobrevive a uma refatoração.

Uma implementação por ação do usuário

Toda ação iniciada pelo usuário — adicionar uma carteira observada, alterar uma taxa de imposto, descartar um alerta, fazer logout — tem exatamente uma implementação. A regra existe porque ações disparadas de diferentes partes da UI costumavam divergir de maneiras sutis: um ponto de entrada limparia um cache, outro não, e uma classe de bugs "valor obsoleto após operação X" resultaria.

Modos de falha que devem ser ruidosos

Alguns modos de falha são silenciosos por natureza — uma recompensa mal classificada, uma incompatibilidade de unidade que transforma uma notificação em uma operação nula, um registro de descarte que nunca chega ao armazenamento de chave-valor. Quando possível, o registro exige que produtores desses valores declarem seu contrato com clareza suficiente para que uma mudança futura que o viole falhe de forma ruidosa, em testes, antes de chegar à produção.

Como o registro evolui

Novas salvaguardas. Adicionadas quando uma classe de bug recorre ou um único bug custou o suficiente para justificar uma regra permanente.
Salvaguardas supersedidas. Mantidas no registro com um marcador "supersedido" e um ponteiro para a substituição, para que referências históricas no código permaneçam interpretáveis.
Promovidas de notas de trabalho. Algumas salvaguardas começam como regras informais em um documento de handoff de sessão e são promovidas ao registro uma vez que provam seu valor.
Revisão trimestral. Exceções temporárias de lint e marcadores "a fazer no próximo trimestre" são verificados em cadência trimestral. Qualquer coisa que envelheceu é resolvida ou explicitamente estendida.

Por que isso é publicado

FlareWatch publica esta visão geral, em vez do registro interno completo, por dois motivos.

O registro interno contém detalhes no nível de código (caminhos de arquivo, nomes de schema de armazenamento de chave-valor, timestamps de incidentes) que são úteis para o time e para um revisor de segurança com acesso ao código, mas não é apropriado publicar sem esse acesso.
As categorias e a disciplina são a história real. Um revisor de concessões ou pesquisador de segurança avaliando FlareWatch quer saber que tipo de projeto é, quão seriamente leva a precisão e como seu loop de trabalho funciona — não qual arquivo contém a regra #91.

Pesquisadores que gostaria de discutir uma salvaguarda específica, propor uma nova ou relatar uma lacuna são bem-vindos a entrar em contato em [email protected].

Leitura adicional

Arquitetura — como FlareWatch é construído.
Recursos de Segurança — autenticação, autorização, cabeçalhos, histórico de auditoria.