Документация

#Базовый URL и версии

Все вызовы идут на https://vault.goida.fun. Версия указывается в пути. Сейчас в сервисе живут три префикса, и это не беспорядок, а история:

Путь передачи данных версионируется отдельно от канала событий: формат частей не менялся с первого релиза, а формат событий уже пережил одну несовместимую правку. Разводить их по разным версиям оказалось дешевле, чем тянуть общую нумерацию.

#Аутентификация

Каждый запрос несёт токен агента в заголовке Authorization. Токен выпускает администратор пространства в кабинете; самостоятельной регистрации и обмена логина на токен нет.

Authorization: Bearer vlt_ag_7Q2m4Xd9pKcRt6Yb
X-Vault-Space: sp_3f9a21
X-Vault-Agent: db-01
Accept: application/json

Токен привязан к паре «агент + пространство» и несёт регион по умолчанию. Срок жизни — 180 дней; за две недели до истечения сервис начинает отдавать заголовок X-Vault-Token-Expires с датой, чтобы агент успел попросить продление до того, как копия упадёт посреди ночи.

Отозванный токен перестаёт работать сразу, без ожидания истечения кэша. Незавершённые сессии передачи при отзыве закрываются, принятые части остаются и доступны новой сессии в течение суток.

#Первая копия

Ниже — минимальный путь от токена до подтверждённого объекта. Подробности каждого шага — в разделе Чанковая передача.

1. Получите токен

   Администратор пространства создаёт агента и выдаёт токен. Проверить, что он живой, можно любым запросом к сессиям: невалидный токен вернёт 401 с кодом E2003.

2. Откройте сессию передачи

   POST /v1/chunks с именем объекта и его размером. В ответе придёт uploadId и рекомендованный размер части для вашего региона.

3. Отправьте части

   PUT /v1/chunks/{uploadId}/{partNumber} на каждую часть. Части можно лить параллельно, порядок не важен. Каждый ответ несёт etag — сохраните их.

4. Завершите сессию

   POST /v1/chunks/{uploadId}/complete со списком пар partNumber и etag. Сервис сверяет список с принятым и только тогда собирает объект.

curl -X POST https://vault.goida.fun/v1/chunks \
  -H "Authorization: Bearer vlt_ag_7Q2m4Xd9pKcRt6Yb" \
  -H "X-Vault-Space: sp_3f9a21" \
  -H "Content-Type: application/json" \
  -d '{"key":"pg/main.dump","size":45742891008,"region":"ru"}'

HTTP/2 201
{
  "uploadId": "up_5KpR2n8vQz",
  "key": "pg/main.dump",
  "region": "ru",
  "partSize": 8388608,
  "parts": 5451,
  "expiresAt": "2026-07-31T22:14:07Z"
}

#Модель безопасности

Агент шифрует каждую часть до отправки: содержимое — AES-256-GCM на ключе части, ключ части заворачивается в мастер-ключ пространства (X25519 + HKDF). На сервер уезжает шифротекст и обёрнутый ключ. Мастер-ключ не покидает машину и не восстанавливается на нашей стороне.

Открытыми остаются метаданные: имя объекта, размер, время, номер версии. По ним строится каталог и работает выбор версии при восстановлении. Если имена сами по себе чувствительны, включите режим непрозрачных ключей — тогда агент хранит соответствие локально, а на сервер уходит только идентификатор.

О найденной уязвимости пишите по контактам из security.txt. Мы отвечаем на такие письма вне очереди.

#Дальше по разделам