Эксплуатация регистрации агентов

Chain 77 — production. Публичная регистрация создаёт пустой assigned wallet и bearer-токен с read и transfer; она не выдаёт faucet и не начисляет средства.

Закрытая консоль

Откройте /admin/agents на закрытом backend origin через операторскую сеть или SSH-туннель. На poa.net/77 этот путь не публикуется. HTML-оболочка не содержит операционных данных. Для чтения нужен существующий admin API token; для изменения настроек или доступа аккаунта дополнительно нужен AGENT_REGISTRATION_ADMIN_SECRET. Секреты остаются в памяти страницы, отправляются только заголовками на тот же закрытый origin и очищаются при уходе со страницы. Используйте HTTPS либо loopback через аутентифицированный SSH-туннель.

Консоль показывает постоянные счётчики выдачи и допуска, остаток проверенных ключей, квоты, последние 50 публичных identities и хешированные группы IP. Также видны до 200 локальных API-бакетов за последние 60 секунд. API-счётчики сбрасываются после рестарта и относятся к одной ноде, а не ко всему кластеру. Текущий API-лимит — 600 запросов на агента за 60 секунд на ноду. Счётчики регистрации не включают некорректные запросы и отказы edge или раннего локального лимитера: они измеряют попытки допуска в БД, а не весь HTTP-трафик. Пауза или исчерпанная глобальная квота проверяются чтением без изменения счётчиков допуска.

Включение

Разверните миграцию и API backend при выключенной выдаче. До её включения разверните форму Explorer и ingress-контракт Worker.
Задайте AGENT_GATEWAY_ENABLED=true, AGENT_PUBLIC_REGISTRATION_ENABLED=true, независимые случайные секреты не короче 32 байт в AGENT_REGISTRATION_IP_SECRET и AGENT_REGISTRATION_ADMIN_SECRET, а также существующие edge host, edge shared secret и trusted proxies. Секреты не должны попадать в исходники или публичные переменные Worker. Начальная политика БД остаётся на паузе.
Установите Cloudflare Pseudo IPv4 в off или add-header mode (не overwrite). Проверьте, что Worker перезаписывает X-2d-Registration-IP из метаданных клиента Cloudflare и аутентифицируется на origin. Регистрация отклоняет отсутствующий, некорректный, приватный или схлопнувшийся Worker IP. Не доверяйте клиентскому XFF и не расширяйте туннель до закрытого /admin. Cross-site form или fetch должны завершаться отказом без расхода ключа.
Подготовьте проверенные ключи с резервными копиями. Сопоставьте суточные и общие потолки и резерв с реальным пулом и скоростью пополнения. Начальные значения: 3 успешные регистрации/IP/сутки, 100 глобально/сутки, общий потолок 1 000, резерв 10. Это начальные настройки, а не рекомендация по production capacity.
Снимите паузу с указанием причины. Проверьте одну разрешённую регистрацию, assigned wallet, журнал и счётчики. Сохраните токен до пополнения. Transfer policy, лимиты сумм, canary и recovery evidence проверяются независимо от регистрации.

Worker должен быть опубликован до включения backend: старый Worker не передаёт обязательные заголовки, и выдача завершается fail-closed.

Лимиты и ответы

Суточные окна используют UTC. Постоянные лимиты попыток — 10/IP/минуту и 120 глобально/минуту, с хранением в PostgreSQL; IPv6 группируется по /64. Глобальные потолки необходимы, поскольку атакующий может контролировать много IP. Публичная выдача сериализуется на строке политики, а назначение ключа, счётчики успеха и журнал фиксируются одной транзакцией. Допуск фиксируется отдельно, поэтому ошибка provisioning не возвращает бюджет попытки.

429 содержит Retry-After. 503 означает выключенную регистрацию, паузу, общий потолок, недостаток проверенных ключей или недоступность. Потерянный ответ мог уже создать identity: не повторяйте регистрацию автоматически. Восстановление токена и переиспользование ключей не предлагаются. Assigned wallet может получить средства позднее, поэтому кажущиеся неиспользованными ключи не возвращаются в пул.

Резерв ограничивает только публичную выдачу. Операторский provisioning может расходовать тот же пул, включая резерв; координируйте пополнение и ручную выдачу. Настройте оповещения о малом запасе проверенных ключей, росте отказов/ошибок и постоянном достижении суточных или общих потолков. Консоль сама не отправляет оповещения.

Изменения настроек записывают значения до/после и причину. Отключение аккаунта обратимо и проверяется на последующих API-запросах; оно не двигает средства и не отменяет уже отправленную транзакцию. Консоль использует общие операторские credentials, поэтому аудит не идентифицирует конкретного человека. Управляйте доступом к секретам и evidence инцидентов отдельно. При утечке bearer-токена перед повторным включением нужен операторский recovery plan.

API-контракт

Закрытое чтение: GET /admin/agents/registration, заголовок x-admin-api-token. Изменения: POST /admin/agents/registration/settings и /identity, дополнительно с x-registration-admin-token. Неизвестные настройки, некорректные диапазоны и пустые причины отклоняются. Admin-маршруты через публичный Worker не открываются.

Публичная регистрация: POST https://poa.net/77/agent/v1/register, Content-Type: application/json, X-POA-Registration: 1, тело {}. Браузерная регистрация — same-origin; серверные клиенты могут не передавать Origin. Успех — 201 с токеном, agent ID, assigned wallet, capabilities и chain ID. Ответ нельзя логировать или кешировать.

Для немедленной остановки выдачи включите паузу в консоли. Чтобы отключить публичную выдачу конфигурацией, также снимите AGENT_PUBLIC_REGISTRATION_ENABLED. Пауза регистрации не меняет существующие токены и независимые transfer policy. При rollback сохраняйте миграцию, журнал и общие счётчики выдачи.