Документация для разработчиков

DVeProto

Версия протокола: 1. Формат кадров и криптография не привязаны к WebSocket.

JSON-спецификация (API) Канонический адрес протокола: https://api.f-chat.ru/DVeProto (JSON: добавьте ?format=json или заголовок Accept: application/json). Ранее: dveproto_spec.php. Очередь обмена: dve_exchange.openapi.yaml.

Эталонный код (скачивание с сайта) Python 3: reference.py · браузер (ESM, Web Crypto): reference-client.js. Доступ из интернета, без внутренних репозиториев.

Транспорт — любой

DVeProto задаёт только что передаётся: последовательность JSON-объектов (UTF-8). Канал может быть чем угодно, если вы можете доставить одну JSON-строку за шаг:

WSS — одна текстовая рамка WebSocket на сообщение;
HTTPS — тело POST / ответ application/json, long polling, отдельные запросы на шаги рукопожатия;
NDJSON, gRPC JSON, очередь сообщений, обмен файлами — пока сохраняется порядок и целостность кадра.

TLS для HTTP/WebSocket по-прежнему защищает канал от третьих лиц; DVeProto даёт свой слой шифрования полезной нагрузки поверх уже существующего транспорта.

Рукопожатие

Сторона «сервер» (инициатор сессии в вашей модели) отправляет открытый JSON dve_hello с server_pk (X25519, 32 байта, Base64). Пара ключей сервера обычно новая на каждую логическую сессию.
Клиент генерирует X25519, считает общий секрет, выводит два ключа HKDF с метками DVeProto-v1/c2s и DVeProto-v1/s2c (соль — пустой байтовый массив длины 0).
Клиент отправляет dve_client_ack с client_pk (Base64).
Далее полезная нагрузка только в кадрах type: dve.

На HTTPS это может выглядеть как: ответ первого запроса = dve_hello, второй POST = dve_client_ack, затем обмен телами dve — схему маршрутов выбираете вы.

Удобная интеграция (как готовый мини-SDK)

Криптография та же, что в спецификации; добавлены только обёртки, чтобы не собирать кадры вручную на каждом шаге:

Python — DVeClientSession.from_server_hello_text: по строке dve_hello получаете сессию и JSON для dve_client_ack. Дальше pack_outgoing / unpack_incoming. На сервере после ack — developer_server_session_from_ack.
Браузер — dveDeveloperHandshake возвращает { session, clientAckJson }; далее те же encryptOutgoing / decryptIncoming.
Сообщения приложения — опционально единый вид JSON внутри GCM: поля dve_op (имя операции) и dve_seq (порядок), хелперы dveAppMessage / DVeSeq в JS и dve_app_message / DVeSeq в Python. Формат операций согласуйте между клиентом и сервером.

Машиночитаемо это же перечислено в JSON спецификации: ключ developer_experience на https://api.f-chat.ru/DVeProto.

Зашифрованный кадр

После рукопожатия каждое сообщение — JSON вида (поля n, c в Base64):

{ "type": "dve", "proto": "DVeProto", "v": 1, "n": "…", "c": "…" }

После расшифровки AES-GCM внутри c — снова JSON объекта приложения. Исходящие от клиента шифруются ключом c2s, входящие к клиенту расшифровываются ключом s2c.

Свой сервер и другие проекты

Реализуйте на стороне сервера генерацию пары X25519, ответ dve_hello и приём dve_client_ack, затем шифрование/расшифровку кадров type: dve так же, как в эталонах на Python и в Web Crypto. Передавайте JSON-строки по WebSocket, HTTP, очереди или файлам — протокол не задаёт хост и порт.

Обмен между своими проектами

Реализуйте рукопожатие и кадры по этой спецификации и передавайте строки так, как удобно вашему API (REST, gRPC, боты, микросервисы). Опционально можно использовать очередь обмена на нашем API при авторизации пользователя в экосистеме f-chat.ru.

English summary

DVeProto v1 is transport-agnostic: the same JSON messages work over WSS, HTTPS bodies, NDJSON, queues, etc. Reference implementations: reference.py, reference-client.js. Canonical machine-readable spec: https://api.f-chat.ru/DVeProto (?format=json).