Проверка домена (Verified host)

Notifly умеет сканировать порты произвольного хоста. Чтобы этим нельзя было воспользоваться для атаки на чужую инфраструктуру, для публичных хостов сначала нужно подтвердить владение доменом — доказать, что хост действительно ваш. Verified host — это запись «пользователь X владеет хостом Y» со сроком действия 365 дней.

После подтверждения сканирование такого хоста идёт в ускоренном режиме (большие батчи портов и выше параллелизм); неподтверждённые хосты тоже можно сканировать, но осторожнее и медленнее.

Два способа подтверждения

Подтвердить владение можно одним из двух методов (method):

`method`	Что нужно разместить	Где проверяет Notifly
`dns`	DNS TXT-запись `_notifly-verify.<host>` со значением = токен	резолв TXT через системный DNS-резолвер
`http`	файл `/.well-known/notifly-verify.txt`, единственная строка = токен	`GET https://<host>/.well-known/notifly-verify.txt`, при неудаче — `http://`

Токен — это случайный UUID, который Notifly выдаёт на шаге start. При проверке значение TXT-записи (или содержимое файла) сравнивается с токеном после обрезки пробелов (strings.TrimSpace), поэтому лишние пробелы и перевод строки в конце значения не мешают.

Приватные хосты — авто-верификация

Если хост резолвится только в приватные адреса, владение не нужно подтверждать — такая запись создаётся автоматически с методом auto-private.

К приватным относятся (проверяется функцией IsPrivateHost):

localhost;
loopback 127.0.0.0/8 и ::1/128;
RFC 1918 — 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16;
link-local 169.254.0.0/16 и fe80::/10;
RFC 4193 ULA fc00::/7.

Для loopback-адресов и localhost подтверждение через DNS/HTTP в принципе невозможно, поэтому они всегда считаются верифицированными.

Состояния верификации

POST /verified-host/start возвращает разный status в зависимости от хоста:

`status`	Когда	HTTP-код
`already_verified`	для этого `host` уже есть действующая (непросроченная) запись — возвращается в поле `host`	`200`
`verified`	хост приватный, запись создана автоматически (`method: "auto-private"`)	`201`
`pending`	публичный хост — выданы `token` и `instruction`, ждём вашего шага и `check`	`200`

Запись с pending нигде не сохраняется до успешного check: токен надо запомнить на клиенте и передать обратно в /verified-host/check.

Как подтвердить домен

Шаг 1 — начать верификацию

curl -X POST "$NOTIFLY_URL/verified-host/start" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{ "host": "example.com", "method": "dns" }'

Ответ для публичного хоста:

{
  "status": "pending",
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "method": "dns",
  "host": "example.com",
  "instruction": "Create a DNS TXT record: _notifly-verify.example.com with value: 550e8400-e29b-41d4-a716-446655440000"
}

Шаг 2 — разместить доказательство

Метод dns — создайте TXT-запись в зоне домена:

_notifly-verify.example.com.  IN  TXT  "550e8400-e29b-41d4-a716-446655440000"

Метод http — положите файл по пути /.well-known/notifly-verify.txt, чтобы он отдавался по адресу:

https://example.com/.well-known/notifly-verify.txt

Содержимое файла — ровно токен, одной строкой:

550e8400-e29b-41d4-a716-446655440000

Шаг 3 — запустить проверку

Передайте host, method и token в check. Дождитесь распространения DNS-записи (TTL может быть несколько минут) перед вызовом:

curl -X POST "$NOTIFLY_URL/verified-host/check" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
       "host": "example.com",
       "method": "dns",
       "token": "550e8400-e29b-41d4-a716-446655440000"
     }'

Успех — запись создаётся, возвращается код 201 и сам объект:

{
  "id": 42,
  "host": "example.com",
  "method": "dns",
  "verifiedAt": "2026-06-23T10:00:00Z",
  "expiresAt": "2027-06-23T10:00:00Z"
}

Если токен не найден (TXT не распространилась, файл недоступен, значение не совпало) — вернётся код 422 с пояснением в поле error, например token not found in TXT records for _notifly-verify.example.com или HTTP 404 from https://example.com/.well-known/notifly-verify.txt. Просто повторите check после исправления.

Просмотр и удаление

Список действующих (непросроченных) верификаций пользователя:

curl "$NOTIFLY_URL/verified-host" \
     -H "X-Notifly-Key: <client-token>"

[
  {
    "id": 42,
    "host": "example.com",
    "method": "dns",
    "verifiedAt": "2026-06-23T10:00:00Z",
    "expiresAt": "2027-06-23T10:00:00Z"
  }
]

Удалить верификацию (например, если хост больше не ваш):

curl -X DELETE "$NOTIFLY_URL/verified-host/42" \
     -H "X-Notifly-Key: <client-token>"
# → {"ok":true}

Удалить можно только свою запись: чужой или несуществующий id вернёт 404.

REST API

Все endpoints требуют клиентский (или MCP) токен. Базовый URL — $NOTIFLY_URL (https://notifly.ru), заголовок авторизации — X-Notifly-Key.

Метод	Путь	Описание
`GET`	`/verified-host`	Список действующих верификаций пользователя
`POST`	`/verified-host/start`	Начать верификацию: `{ "host", "method" }`, где `method` = `dns` или `http`. Возвращает `status` (`already_verified` / `verified` / `pending`) и для публичного хоста — `token` + `instruction`
`POST`	`/verified-host/check`	Проверить размещённое доказательство: `{ "host", "method", "token" }`. Успех → `201` и объект записи; неудача → `422` с `error`
`DELETE`	`/verified-host/:id`	Удалить свою верификацию по `id` (чужой/несуществующий → `404`)

Поля объекта VerifiedHost: id, host, method (dns / http / auto-private), verifiedAt, expiresAt. Токен в выдаче не возвращается.

См. также

Сканирование портов — основной потребитель verified-host: подтверждённые хосты сканируются в ускоренном режиме.
Активные мониторы и порт-мониторы — другие способы следить за доступностью хостов и портов.