Block a user
@harpus/contracts (2.5.0)
Published 2026-11-14 21:53:52 +03:00 by WMHillock
Installation
@harpus:registry=https://git.devbay.ru/api/packages/WMHillock/npm/npm install @harpus/contracts@2.5.0"@harpus/contracts": "2.5.0"About this package
Harpus public wire contract v2 (gateway HTTP API, Host tunnel, widget snapshot, releases) — ADR-043
@harpus/contracts — публичный контракт v2
Единственный источник правды для всего, что пересекает сеть между Host (desktop), Harpus Gateway и клиентами (Android, PWA). Решения — ADR-043.
| Файл | Назначение |
|---|---|
schemas/contract.json |
JSON Schema (draft 2020-12, подмножество). Источник правды |
openapi.yaml |
HTTP API gateway, ссылается на схемы |
generated/ |
Сгенерировано npm run generate: index.d.ts (TS), schema.js, kotlin/HarpusContract.kt (kotlinx.serialization). Руками не править |
src/runtime.js |
Канонический JSON и валидатор подмножества JSON Schema (без зависимостей) |
fixtures/ |
Общие фикстуры для TS и JVM-тестов; signature-vector.json — эталон подписи |
Подпись команд
payloadDigest = hex(SHA-256(canonicalJson(params))).- Подписываемые поля:
schemaVersion, commandId, hostId, issuerDeviceId, grantRevision, operation, target, params, createdAt, expiresAt, expectedRevision(отсутствующие опускаются). canonicalJson: ключи объектов отсортированы по кодовым единицам UTF-16, без пробелов,undefinedотбрасывается, числа — какJSON.stringify.- Подпись: ECDSA P-256 / SHA-256, формат IEEE P1363 (
r‖s, 64 байта), base64. Android:Signature.getInstance("SHA256withECDSA")даёт DER → конвертировать в P1363. - Публичный ключ устройства: SPKI DER, base64. Время жизни envelope ≤ 60 с.
Версии
CONTRACT_VERSION = semver пакета. Ломающее изменение — новая major-версия и новый путь API (/v3). Gateway поддерживает текущую и предыдущую minor.
Команды
npm run generate # регенерация
npm run check # регенерация + проверка, что generated/ не изменился (CI)
npm test # фикстуры, лимиты, эталон подписи