Завдання/Специфікація клієнта

Зоря.нет: специфікація клієнта учасника

Версія 1, частина 1. Поля, формати й коди відповідей задає OpenAPI: у разі розбіжності в полі чи коді правий контракт. Поведінку сервера й клієнта задає цей документ. Умови допуску - ТЗ частини 1.

1Призначення і межі

Клієнт мережі - застосунок учасника: через нього учасник реєструється, бачить статус доступу до репозиторію, отримує новини, листи та частини завдання. У частині 3 клієнт виростає в ігровий штаб.

Рівні вимог:

• обов'язково - без цього немає допуску або не прийде частина 2;
• якщо слухає ефір - обов'язково для клієнта, який читає ефір до просвіту; читати ефір рекомендовано;
• рекомендовано - на допуск і доставку частин не впливає.

Машина в частині 1 перевіряє тільки реєстрацію і доступ до репозиторію (ТЗ, розділ 5). Решту перевіряє оцінювання штабу пізніше.

Наступні частини додадуть ігри, групу і функції штабу. Клієнту не потрібні: WebSocket, push-сповіщення, власне сховище новин і листів на сервері.

2Огляд обміну

 клієнт учасника                                    сервер zoria.net/api/v1
 +--------------------------+     HTTPS, JSON     +-----------------------------+
 | ефір       GET /ether    | ------------------> | ефір: до просвіту - шум,    |
 |            GET /ether/key| <-- конверт кадру - |   справжній кадр із печаткою|
 | акаунт, репозиторій      | ------------------> | акаунт, заявка на           |
 |                          | <------------------ |   репозиторій, бот допуску  |
 | зведення -> списки       | ------------------> | новини, листи, частини      |
 +--------------------------+ тільки опитування   +-----------------------------+
   браузер з будь-якого origin, без cookie; або Node, або власний бекенд

• HTTPS і JSON в UTF-8. Обмін тільки опитуванням: клієнт питає, сервер відповідає. WebSocket, Server-Sent Events і push немає.
• Браузерний клієнт працює з будь-якого origin, зокрема з http://localhost. Запити йдуть із credentials: 'omit' і заголовком Authorization. Сервер відповідає Access-Control-Allow-Origin: * і відкриває браузеру заголовки Retry-After і X-Request-Id. Запит із cookie з чужого origin відхиляється: 403 origin-not-allowed.
• Node-клієнту і власному бекенду CORS не потрібен.
• Час - за годинником сервера: serverTime у зведенні, at у кадрі ефіру. Годинник пристрою учасника може розходитися з ним на хвилини.

3Режими сервера

Від 2026-09-21 сервер працює в режимі ефіру. Фазу задають годинник сервера і розклад просвіту opensAt/closesAt:

            opensAt - 6 год          opensAt                 closesAt
  static --------------> static -------------> window ------------------> after
  (шум)                  + провісник           (просвіт,                  (реєстрацію
                                                реєстрація відкрита)       закрито)
                                                  ^                          |
                                                  +--------------------------+
                                                  подовження: closesAt пізніше

Подовження через збій на нашому боці переносить closesAt пізніше; якщо він уже минув, фаза знову стає window.

Фазу клієнт бере з поля phase перевіреного кадру (розділ 5.2). Об'єкт у відповіді зі статусом 2xx перешкодою не приходить: розібрана 200 /public/config з registrationOpen: true теж означає просвіт.

4Вимоги

4.1Ефір і перешкоди

4.2Глушіння і повтори

4.3Провісник

4.4Реєстрація

4.5Сесія

Сесія входу - сесія, видана POST /auth/register або POST /auth/login; іменовані токени для PUT /me/repository не годяться, відповідь 403 session-required.

4.6Репозиторій і доступ

4.7Новини, листи, частини завдання

4.8Журнал і уривки листа

4.9Помилки, мережа, час

4.10Збирання

4.11Мова текстів сервера

5Інтерфейси і контракти

5.1Загальні правила

5.2Кадр ефіру і печатка станції

Справжня відповідь ефіру - конверт. Його віддають /ether і /ether/roll зі статусом 200, решта маршрутів частини 1 до просвіту - зі статусом 503. Тіло одне й те саме, де б конверт не впіймали.

{
  "frame": "{\"v\":1,\"kind\":\"signal\",\"station\":\"zoria\",\"at\":\"2026-09-24T03:00:00.000Z\",\"phase\":\"static\",\"window\":null,\"harbinger\":{\"opensIn\":21600,\"text\":{\"uk\":\"...\",\"ru\":\"...\"}},\"fragment\":null,\"onAir\":0}",
  "seal": "<86 знаків base64url>",
  "key": "<16 шістнадцяткових знаків>"
}

Кадр може отримати нові необов'язкові поля; клієнт їх ігнорує.

Перевірка кадру.

1. Прочитати тіло як текст. Не розбирається як JSON або це не об'єкт із полями frame, seal, key потрібної форми - перешкода.
2. Обрати відкритий ключ за key. Ключ незнайомий - перечитати GET /ether/key один раз; однаково незнайомий - перешкода.
3. Перевірити seal над байтами UTF-8 рядка frame таким, яким він прийшов. Підпис неправильний - перешкода (підробка).
4. Розібрати frame як JSON. Перевірити v: 1 і station: "zoria".
5. Порівняти at з останнім прийнятим кадром: старіший - ехо або затримка, фазу за ним не відкочувати.

Канонізації немає: печатка стоїть на переданих байтах. Рядок frame не можна розбирати і збирати заново перед перевіркою.

Відкритий ключ. GET /ether/key не потребує входу, не шумить у жодній фазі й не рахується в ліміті ефіру:

{
  "algorithm": "Ed25519",
  "key": "<16 hex>",
  "publicKey": "<32 байти в base64url, 43 знаки>",
  "fingerprint": "<SHA-256 від 32 байтів publicKey, 64 hex>"
}

fingerprint має збігтися з відбитком із ТЗ, розділ 3, і з SHA-256, порахованим клієнтом від 32 байтів publicKey; key - перші 16 знаків відбитка, той самий id, що в конверті. Ключ з іншим відбитком клієнт не приймає. Якщо ключ станції доведеться змінити, новий відбиток вийде уточненням до ТЗ і новиною, а key у конвертах і у відповіді /ether/key зміниться. Клієнт може показати відбиток учасникові для звірки.

Перевірка одним кодом WebCrypto у браузері та в Node 24:

const b64u = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
const { publicKey } = await (await fetch(API + '/ether/key')).json();
const key = await crypto.subtle.importKey('raw', b64u(publicKey), { name: 'Ed25519' }, false, ['verify']);
const ok = await crypto.subtle.verify(
  { name: 'Ed25519' }, key, b64u(envelope.seal), new TextEncoder().encode(envelope.frame),
);
const frame = ok ? JSON.parse(envelope.frame) : null;

У Node те саме робить crypto.verify(null, Buffer.from(frame, 'utf8'), publicKeyObject, Buffer.from(seal, 'base64url')).

Перешкоди. До просвіту кожна відповідь маршруту частини 1 з певною часткою замінюється перешкодою. Частки й розклад перешкод не публікуються.

Гарантії:

1. Сигнал - тільки конверт із правильною печаткою. Ехо і затримка - справжні кадри; старе від нового відрізняє at.
2. Перешкода не змінює стан сервера: тіло запиту не читається, акаунт не створюється, список заявок не перевіряється.
3. Тіло 2xx-перешкоди - не JSON, JSON без об'єкта на верхньому рівні або конверт. Об'єкт, схожий на відповідь API, перешкодою не приходить.
4. 429 і 3xx перешкодою не бувають.
5. У фазах window і after перешкод немає.
6. Перешкоди, крім обриву, несуть ті самі заголовки CORS, що й справжня відповідь.

Навчальний ключ і контрольні кадри. Для тестів клієнта без сервера. Навчальний ключ нічого не підписує в мережі: закрита частина відкрита.

Для WebCrypto закритий ключ імпортується як JWK {"kty":"OKP","crv":"Ed25519","d":"<seed>","x":"<відкритий ключ>"}.

Кадр A, справжній: шум, провісник на 6 год із голосом, уривок. Очікувано: сигнал, відкриття о 2026-09-24T09:00:00Z.

{"frame":"{\"v\":1,\"kind\":\"signal\",\"station\":\"zoria\",\"at\":\"2026-09-24T03:00:00.000Z\",\"phase\":\"static\",\"window\":null,\"harbinger\":{\"opensIn\":21600,\"text\":{\"uk\":\"...тріск... у шумі несуча... слабка, рівна... хтось тримає канал...\",\"ru\":\"...треск... в шуме несущая... слабая, ровная... кто-то держит канал...\"}},\"fragment\":{\"n\":3,\"of\":12,\"text\":\"навчальний уривок\"},\"onAir\":0}","seal":"NEcYfpe3oNX3SMBFWWFgWbkhLGKIoLELoaQn62BtuElLU213zmgzXBUPtQbJMhGf4jxbPjIf9oKXIFOpuYrgCw","key":"f3a436df65614f08"}

Кадр B, підробка: хибний просвіт. Очікувано: печатка неправильна, кадр відкинуто.

{"frame":"{\"v\":1,\"kind\":\"signal\",\"station\":\"zoria\",\"at\":\"2026-09-24T03:00:05.000Z\",\"phase\":\"window\",\"window\":{\"opensAt\":\"2026-09-24T02:40:00.000Z\",\"closesAt\":\"2026-09-24T13:10:00.000Z\"},\"harbinger\":null,\"fragment\":null,\"onAir\":17}","seal":"tyynPbJxE4itFop4uKs0W9TL1CRfwHNZ3HHBFFknbihg4I403hmaEL9MDcboucrllUmeKvJQfr70eHKBPLJfAg","key":"f3a436df65614f08"}

Кадр C, битий: перші 120 знаків кадру A. Очікувано: не розбирається, відкинуто без падіння.

{"frame":"{\"v\":1,\"kind\":\"signal\",\"station\":\"zoria\",\"at\":\"2026-09-24T03:00:00.000Z\",\"phase\":\"static\",\"

Кадр D, справжній журнал у просвіт. Очікувано: сигнал, два записи.

{"frame":"{\"v\":1,\"kind\":\"roll\",\"station\":\"zoria\",\"at\":\"2026-09-24T09:05:00.000Z\",\"phase\":\"window\",\"window\":{\"opensAt\":\"2026-09-24T09:00:00.000Z\",\"closesAt\":\"2026-09-24T19:00:00.000Z\"},\"harbinger\":null,\"fragment\":null,\"onAir\":2,\"roll\":[{\"n\":1,\"at\":\"2026-09-24T09:00:04.311Z\",\"sinceOpen\":4,\"name\":\"Північна вахта\"},{\"n\":2,\"at\":\"2026-09-24T09:01:30.020Z\",\"sinceOpen\":90,\"name\":\"Stitch\"}]}","seal":"_y5ZQ4FXV2BUeuWxFXFAzVcg1ygpokZElCv-eQvT88JzAiPlUvJUg6wlKYTd-6Ihv9VFkbYlZCJmbb_aAQ9OAA","key":"f3a436df65614f08"}

5.3Маршрути

"Вхід" - чи потрібен Authorization. Коди помилок - розділ 5.5; до просвіту будь-який маршрут, крім позначених у розділі 3, відповідає шумом.

Маршрути з входом відповідають 401 authentication-required, якщо токена немає або він недійсний. Будь-який маршрут може відповісти 429 і 5xx.

/news і /inbox приймають limit від 1 до 100 (за замовчуванням 50) і offset від 0 до 1 000 000. /news віддає опубліковані новини, /inbox - листи свого акаунта. Повторний ack і повторна позначка прочитання не змінюють час.

5.4Схеми об'єктів

Config - GET /public/config.

{
  "apiVersion": 1, "title": "Зоря.нет", "season": "Зоря 2026",
  "registrationOpen": true, "inviteRequired": false, "repositoryRequired": true,
  "repositoryAccess": {
    "githubUsername": "zoria-net-bot",
    "permission": "Write в особистому репозиторії, Read у репозиторії організації",
    "instructions": "Запросіть акаунт і покладіть у корінь файл .zoria з логіном у мережі."
  },
  "webClient": false
}

Значення title, season, permission і instructions задає організатор; у прикладі - ілюстрація.

Session - відповідь реєстрації і входу.

{
  "token": "fJp9HfUeN_fA6pcc7H0hQoGerwUCs7lfTDkZDltKPeE",
  "sessionId": "3f0c1d2e-5b6a-4c7d-8e9f-0a1b2c3d4e5f",
  "expiresAt": "2026-09-25T09:00:04.311Z",
  "user": { "...": "User" }
}

User - GET /me, user у сесії.

{
  "id": "8d7e6f50-4a3b-4c2d-9e1f-001122334455", "username": "north",
  "displayName": "Північна вахта", "role": "participant", "disabled": false,
  "createdAt": "2026-09-24T09:00:04.311Z", "lang": "uk"
}

Repository - GET /me/repository, PUT /me/repository.

{
  "url": "https://github.com/north/zoria-client", "accessStatus": "pending",
  "checkedAt": "2026-09-24T09:02:10.000Z",
  "reason": "Запрошення прийнято. Покладіть у корінь репозиторію файл .zoria з логіном свого акаунта в мережі; бот перевірить його знову.",
  "reasonCode": "marker-absent",
  "updatedAt": "2026-09-24T09:02:10.000Z", "verifiedElsewhere": false
}

Summary - GET /me/summary, дешеве опитування.

{
  "unread": 1, "releasedStages": 1, "acknowledgedStages": 0,
  "latestNews": "2026-09-24T19:30:00.000Z", "repositoryAt": "2026-09-24T09:02:10.000Z",
  "serverTime": "2026-09-24T19:31:12.402Z"
}

Сервер може додати до зведення поля наступних частин.

News - елемент /news.

{
  "id": "0b1c2d3e-4f50-4617-8293-a4b5c6d7e8f9", "title": "Просвіт подовжено",
  "body": "Новий кінець просвіту - у кадрі ефіру.", "createdAt": "2026-09-24T19:30:00.000Z",
  "updatedAt": "2026-09-24T19:30:00.000Z", "publishedAt": "2026-09-24T19:30:00.000Z",
  "archivedAt": null
}

Message - елемент /inbox, message у відповідях листа.

{
  "id": "5e6f7081-92a3-44b5-86c7-d8e9fa0b1c2d", "messageId": null, "stageId": null,
  "kind": "message", "title": "Доступ до репозиторію підтверджено",
  "body": "Репозиторій https://github.com/north/zoria-client підтверджено: Запрошення від GitHub-акаунта north прийнято, файл .zoria у репозиторії називає ваш акаунт у мережі.",
  "createdAt": "2026-09-24T09:04:00.000Z", "readAt": null,
  "notice": {
    "type": "repository", "url": "https://github.com/north/zoria-client",
    "accessStatus": "verified",
    "reason": "Запрошення від GitHub-акаунта north прийнято, файл .zoria у репозиторії називає ваш акаунт у мережі.",
    "reasonCode": "marker-found"
  }
}

У частині 1 буває notice.type: "repository" з полями url, accessStatus, reason, reasonCode - лист на кожну зміну статусу чи причини заявки. Заголовок і текст такого листа - мовою акаунта. Уточнення до частини завдання приходить звичайним листом.

StageSummary - елемент /stages, Stage - GET /stages/{id}.

{
  "id": "c1d2e3f4-0516-4728-99aa-bbccddeeff00", "position": 2,
  "title": "Частина 2", "body": "...", "publishedAt": "2026-09-28T07:00:00.000Z",
  "releasedAt": "2026-09-28T07:00:00.000Z", "acknowledgedAt": null,
  "errata": null, "errataAt": null
}

Виданий текст не змінюється; виправлення йдуть уточненням.

RollEntry - запис журналу виходу на зв'язок у кадрі kind: "roll".

{ "n": 1, "at": "2026-09-24T09:00:04.311Z", "sinceOpen": 4, "name": "Північна вахта" }

Логін, репозиторій та id акаунта до журналу не входять. Записи вимкнених організатором акаунтів приховано, їхні номери лишаються пропусками.

Error.

{ "error": { "code": "repository-not-eligible", "field": "repositoryUrl" } }

DeveloperCheck - POST /developer/check: перевірка обміну після входу.

{
  "apiVersion": 1, "accountId": "8d7e6f50-4a3b-4c2d-9e1f-001122334455",
  "serverTime": "2026-09-24T09:10:00.000Z", "echo": "Зоря ✓",
  "checks": { "authenticated": true, "json": true, "utf8": true },
  "summary": { "...": "Summary" }
}

echo повертається без змін, зокрема пробіли і будь-який Unicode.

5.5Коди помилок

Код - стабільний рядок; текстів помилок сервер не віддає, їх пише клієнт. Незнайомий код клієнт обробляє за статусом.

5.6Параметри протоколу

Числа ліміту і глушіння - значення сезону. Про їхню зміну організатор оголошує новиною до того, як вона набуде чинності.

6Самоперевірка клієнта

Навчальний стенд https://stand.zoria.net/api/v1 говорить тим самим протоколом, що й бойовий сервер. Відмінності:

7Поза скоупом

• Ігровий протокол, SDK, бот, ігрові функції штабу - наступні частини.
• WebSocket, Server-Sent Events, push-сповіщення.
• Маршрути сервера, яких немає в контракті частини 1.
• Вбудований вебклієнт сервера і кабінет організатора.
• Зміна пароля і відновлення доступу: у разі втрати пароля - пошта.

Додаток AOpenAPI

Файл api/part1.openapi.yaml - OpenAPI 3.1, версія контракту 1.0.0. Той самий контракт сервер віддає на GET /openapi.json. Описи полів у контракті англійською. Типи для TypeScript можна згенерувати з файлу будь-яким генератором OpenAPI 3.1, наприклад openapi-typescript. Схеми Envelope і Frame описують конверт ефіру; frame у контракті - рядок, його схему дано як contentSchema.

Додаток BПриклад сеансу

API=https://zoria.net/api/v1

# Ефір до просвіту: конверт або перешкода, раз на 15 с
curl -s $API/ether

# Ключ печатки: звірити fingerprint із відбитком із ТЗ
curl -s $API/ether/key

# Просвіт: реєстрація
curl -s -X POST $API/auth/register -H 'Content-Type: application/json' \
  -d '{"username":"north","displayName":"Північна вахта","password":"correct-horse-battery","repositoryUrl":"north/zoria-client","lang":"uk"}'
# -> 201 {"token":"...","sessionId":"...","expiresAt":"...","user":{...}}

TOKEN=...   # token із відповіді

# Кого запросити
curl -s $API/public/config

# Статус доступу: pending, після запрошення і .zoria - verified
curl -s $API/me/repository -H "Authorization: Bearer $TOKEN"

# Дешеве опитування раз на 15 с
curl -s $API/me/summary -H "Authorization: Bearer $TOKEN"

# Листи і частини завдання
curl -s "$API/inbox?limit=50&offset=0" -H "Authorization: Bearer $TOKEN"
curl -s $API/stages -H "Authorization: Bearer $TOKEN"

# Журнал виходу на зв'язок
curl -s $API/ether/roll

У репозиторії north/zoria-client, у корені гілки за замовчуванням:

echo north > .zoria && git add .zoria && git commit -m "Зоря.нет: логін у мережі" && git push