Что такое реестр
Каждый повторяющийся класс ошибок в истории FlareWatch был сформулирован в виде пронумерованного механизма защиты: однопараграфного правила, обоснования и указания на место в коде, которое его применяет. Новые механизмы защиты добавляются, когда появляется класс ошибок или паттерн, который следует предотвращать от повторения.
Реестр — это рабочий документ, а не маркетинговый материал. Его цель — держать команду и цикл проверки, ориентированный на аудит, в честности относительно того, какие правила применяются где. На реестр ссылаются в комментариях кода (например, // Safeguard 24), чтобы читатель любого файла мог найти правило, которое управляет окружающими строками.
Эта страница — краткое резюме для общественности. Полный реестр находится в исходном репозитории наряду с кодом, который он регулирует. Цель здесь — дать исследователю в области безопасности, рецензенту гранта или потенциальному участнику представление о категориях, которые охватывает реестр, и о типе дисциплины, которую он обеспечивает.
Зачем нужен реестр
Реестр механизмов защиты имеет смысл только если он предотвращает одну и ту же ошибку дважды. Послужной список реестра — это ответ:
- Каждый механизм защиты называет баг, который он предотвращает. Правило без запомненного инцидента — это не механизм защиты, а предпочтение стиля. Предпочтения стиля принадлежат правилам линтера, а не реестру.
- Механизмы защиты ссылаются из кода, а не только из документации. Изменение кода, нарушающее механизм защиты, читается как флаг на этапе review, потому что номер механизма находится в окружающих комментариях.
- Некоторые механизмы защиты применяются автоматически. Часть из них применяется через правила ESLint или shell-скрипты, запускаемые в CI. Остальные полагаются на дисциплину автора и паттерн review-first audit, который хорошо зарекомендовал себя на практике.
- Реестр проверяется честными тестами. Несколько механизмов защиты зафиксированы регрессионными тестами, которые читают исходные файлы как строки и утверждают, что антипаттерны не появляются. Хрупкость — это особенность: будущий рефакторинг, который вернётся к антипаттерну, не пройдёт тест до того, как регрессия достигнет production.
Категории
Реестр организован по областям. Категории ниже стабильны; конкретные механизмы защиты в каждой добавляются по мере обнаружения новых режимов отказа.
| Категория | Что он охватывает |
|---|---|
| Аутентификация и авторизация | Единая контрольная точка валидации сессии, проверки собственности кошелька на каждом маршруте, отклонение кросс-токен между токенами доступа и обновления, gating маршрутов админа. |
| Целостность данных | Нормализация адресов, контракты преобразования единиц на границах producer/consumer, дисциплина построения ключей и правила против молчаливого объединения сбоев в нулевые значения. |
| Чтение on-chain данных | Правила единственной реализации для любого значения, прочитанного из смарт-контракта, разрешение адреса контракта из реестра on-chain и правила против дублирования логики вознаграждений. |
| Корректность отображения | Централизованное форматирование чисел, валют и дат; безопасность от null на каждом числовом дисплее; дисциплина маркировки APR vs. APY; дисциплина tax-rate-as-effective. |
| Оповещения и уведомления | Единый источник истины для оценки оповещений на клиенте и сервере; явные allowlist'ы для того, какие оповещения распространяются на отслеживаемые кошельки; правила замещения, так что оповещение "rewards landed" отменяет устаревшее "rewards available" оповещение; синхронизация отклонения между устройствами. |
| Персистентность и кэш | Правила выбора между каноническим хранилищем на основе key-value и localStorage; дисциплина миграции; кэш service worker в пределах развёртывания; явное динамическое отключение для маршрутов, читающих актуальное состояние. |
| UI и жизненный цикл | Шлюзы готовности страницы, монотонные полы, предотвращающие временные нули от замещения известных балансов, и правила для skeleton-рендеринга во время холодной загрузки. |
| Процесс и инструментарий | Правила явного согласия на запуск функций, полный запуск набора тестов при изменениях поверхности оповещений, структурированное логирование в серверном коде и дисциплина проверки против быстрых исправлений. |
Несколько репрезентативных правил
Это публично-безопасные краткие описания защит, которые иллюстрируют характер реестра. Они перефразированы и сокращены; канонический текст находится рядом с кодом.
Единственный источник истины для on-chain чтений
Любое значение, прочитанное из смарт-контракта — заявляемые вознаграждения, балансы, состояние стейка, данные эпохи, цены — вычисляется ровно одной функцией в слое сервисов. Каждая функция, которой нужно это значение, импортирует одну и ту же функцию. Если две функции вычисляют одно значение, одна из них неправильна; правило — удалить её, а не добавлять третью.
Единственный узел пропускной способности для валидации сессии
Каждый аутентифицированный маршрут в FlareWatch валидирует cookies сессии через один вспомогательный модуль. Ни один обработчик маршрута не проверяет tokens сессии независимо. Этот инвариант обеспечивает универсальный отзыв на стороне сервера — нет побочных дверей, обходящих проверку.
Гейтинг владения по кошелькам, обе стороны
Per-wallet маршруты проверяют владение на стороне сервера, а не на клиенте. Исходный аудит установил это правило, потому что предыдущие работы закрыли клиентские шлюзы, но оставили серверные точки доступа полностью открытыми. Обе части теперь отслеживаются как отдельные явные задачи — закрыто на клиенте, закрыто на сервере — для предотвращения повторения этого режима отказа.
Используйте централизованные форматтеры, никогда не встраивайте
Все форматирование чисел, валют и дат проходит через небольшой набор централизованных вспомогательных функций. Ни один компонент не форматирует данные встроенно. Правило не касается стиля: когда изменяется определение одной локали или валюты, каждая часть приложения обновляется вместе с ней. Расхождения между поверхностями молчаливы и трудно заметны, пока пользователь их не обнаружит.
Преобразования единиц документируются в обоих местах
Когда две части системы обмениваются значениями, единица измерения которых может быть неоднозначной (секунды или миллисекунды, десятичная или процентная доля, адреса в нижнем регистре или с контрольной суммой), соглашение документируется как у производителя, так и у потребителя. Комментарий только в одном месте устаревает; только контракт на границе, проверяемый в обоих местах, выживает при рефакторинге.
Одна реализация на действие пользователя
Каждое инициированное пользователем действие — добавление отслеживаемого кошелька, изменение налоговой ставки, закрытие оповещения, выход из системы — имеет ровно одну реализацию. Правило существует потому, что действия, запущенные из разных частей интерфейса, раньше расходились незаметно: один вход очищал кэш, другой — нет, и возникал класс ошибок «устаревшее значение после операции X».
Режимы отказа, которые должны быть заметными
Некоторые режимы отказа молчаливы по своей природе — неправильная классификация награды, несоответствие единиц, превращающее уведомление в пустую операцию, запись об удалении, которая так и не попала в хранилище ключ-значение. По возможности реестр требует, чтобы производители этих значений декларировали свой контракт достаточно громко, чтобы любое будущее изменение, нарушающее его, оканчивалось громким отказом в тестах, до попадания в production.
Как развивается реестр
- Новые гарантии. Добавляются, когда класс ошибок повторяется или одна ошибка стоит достаточно дорого, чтобы оправдать постоянное правило.
- Замененные гарантии. Сохраняются в реестре с маркером «superseded» и указателем на замену, чтобы исторические ссылки в коде оставались интерпретируемыми.
- Повышены из рабочих заметок. Некоторые гарантии начинаются как неформальные правила в документе передачи информации и повышаются в реестр после того, как доказывают свой вес.
- Ежеквартальная проверка. Временные исключения lint и маркеры «to-do до следующего квартала» проверяются ежеквартально. Все устаревшее либо разрешается, либо явно продлевается.
Почему это опубликовано
FlareWatch публикует этот обзор, а не полный внутренний реестр, по двум причинам.
- Внутренний реестр содержит детали на уровне кода (пути файлов, имена схем хранилища ключ-значение, временные метки инцидентов), которые полезны команде и рецензенту по безопасности с доступом к коду, но не подходят для публикации без этого доступа.
- Категории и дисциплина — это суть истории. Рецензент гранта или исследователь безопасности, оценивающий FlareWatch, хочет знать, какой это тип проекта, насколько серьезно он относится к корректности и как выглядит его рабочий цикл — а не в каком файле находится правило №91.
Исследователи, которые хотели бы обсудить конкретную защиту, предложить новую или сообщить об пробеле, могут связаться с нами по адресу [email protected].
Дополнительная информация
- Архитектура — как построена FlareWatch.
- Функции безопасности — аутентификация, авторизация, заголовки, история аудита.