GitWave API — документация

Главный принцип. Сервер хранит только шифротекст. Шифрование и расшифровка идут на клиенте (CLI, WASM в браузере, десктоп, аттестованный CI-раннер). Любой endpoint с телом application/octet-stream отдаёт зашифрованные байты; JSON-endpoint'ы — это только метаданные (счётчики, статусы, идентификаторы).

1. Базовый адрес и формат

Базовый URL: https://gitwave.ru
Все рабочие методы — под префиксом /v1.
Метаданные — JSON. Содержимое (объекты, ключи, одобрения) — бинарный шифротекст.
Коды: 200/201 — ок, 401 — нет/неверный токен, 404 — нет репо/ресурса, 409 — репозиторий уже существует.

2. Аутентификация

Каждый запрос к /v1/* требует заголовок Authorization: Bearer <jwt>. Токен — подписанный OIDC JWT (ES256). Получить его можно двумя способами:

Способ A — Aris Drive (hands-free, рекомендуется)

Локальный агент Aris Drive выдаёт токен без ручного ввода:

# получить токен
TOKEN=$(curl -s https://gitwave.ru/aris-drive/agent/session | jq -r .token)

# использовать его
curl -s https://gitwave.ru/v1/repos -H "authorization: Bearer $TOKEN"

Способ B — Aris ID (OIDC, в браузере)

Откройте /aris-id/authorize?redirect_uri=https://gitwave.ru/app&state=gw. После согласия произойдёт редирект на redirect_uri#access_token=<jwt> — токен во фрагменте URL.

Claims токена. sub (пользователь), company_id, device_id, roles (например developer), scopes (repo.read, repo.write). Сервер проверяет подпись и issuer; срок жизни ограничен.

3. Быстрый старт

export URL=https://gitwave.ru
TOKEN=$(curl -s $URL/aris-drive/agent/session | jq -r .token)

# список репозиториев (метаданные)
curl -s $URL/v1/repos -H "authorization: Bearer $TOKEN" | jq

# создать репозиторий
curl -s -X POST $URL/v1/repos -H "authorization: Bearer $TOKEN" \
     -H "content-type: application/json" -d '{"repo_id":"payments"}'

4. Полный жизненный цикл репозитория

На практике всю криптографию делает CLI/приложение (gitwave init, gitwave commit). Ниже — что при этом происходит на уровне API, чтобы вы могли встроиться сами.

POST/v1/repos — создать репозиторий.
PUT/v1/repos/{repo}/epochs/0 — положить обёрнутый ключ репозитория (эпоха 0). Клиент генерирует RepoKey и оборачивает его под устройство (ECDH P-256).
PUT/v1/repos/{repo}/devices/{device_id} — подписанное одобрение устройства (цепочка доверия).
PUT/v1/repos/{repo}/objects/{oid} — для каждого git-объекта: зашифровать локально (AES-256-GCM) и загрузить шифротекст.
PUT/v1/repos/{repo}/refs/main — указать ветку на oid нового коммита.

Чтение и расшифровка

GET/v1/repos/{repo}/objects — выгрузить карту oid → hex(шифротекст).
GET/aris-drive/agent/keys/{repo} — получить device-ключ (hex).
Развернуть RepoKey из эпохи и расшифровать объекты на устройстве. Сервер в этом не участвует.

# пример: объект приходит шифротекстом
curl -s $URL/v1/repos/demo/objects/04163b25 -H "authorization: Bearer $TOKEN" | xxd | head
# 96c9b846 a756217b 0f0063f7 ...  ← сервер видит только это

5. Что шифротекст, а что метаданные

Endpoint	Тело	Сервер читает?
`/v1/repos/{r}/objects/{oid}`	шифротекст	нет
`/v1/repos/{r}/epochs/{n}`	обёрнутый ключ	нет
`/v1/repos/{r}/devices/{id}`	подписанное одобрение	нет
`/v1/repos/{r}/refs/{name}`	oid коммита	да (метаданные)
`/v1/repos`, `/issues`, `/docs`, `/runs`	JSON-метаданные	да (метаданные)

6. CI/CD и Aris Monitor

PUT/v1/repos/{r}/runs/{commit} — раннер шлёт только {"ok":true|false}. Логи остаются у вас.
POST/v1/repos/{r}/monitor/errors — прод-ошибка {commit, fingerprint, title}. Первая → авто-issue, повторы → инкремент count. Стек-трейс шифруется рантаймом и сюда не уходит.

7. Issues и ArisDoc

POST/v1/repos/{r}/issues {title, commit?} · GET список · POST /issues/{id}/close.
POST/v1/repos/{r}/docs {title, kind, link?} — привязать ТЗ/договор из ArisDoc (kind: spec/contract/proposal/note).

Полный машинно-читаемый контракт: /openapi.json (OpenAPI 3.0). Ниже — интерактивный справочник: раскройте метод, нажмите Try it out, вставьте токен через Authorize и вызовите endpoint вживую.