WMHillock
  • Joined on 2026-05-26

@harpus/contracts (2.1.0)

Published 2026-11-11 17:43:59 +03:00 by WMHillock

Installation

@harpus:registry=https://git.devbay.ru/api/packages/WMHillock/npm/
npm install @harpus/contracts@2.1.0
"@harpus/contracts": "2.1.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 — эталон подписи

Подпись команд

  1. payloadDigest = hex(SHA-256(canonicalJson(params))).
  2. Подписываемые поля: schemaVersion, commandId, hostId, issuerDeviceId, grantRevision, operation, target, params, createdAt, expiresAt, expectedRevision (отсутствующие опускаются).
  3. canonicalJson: ключи объектов отсортированы по кодовым единицам UTF-16, без пробелов, undefined отбрасывается, числа — как JSON.stringify.
  4. Подпись: ECDSA P-256 / SHA-256, формат IEEE P1363 (r‖s, 64 байта), base64. Android: Signature.getInstance("SHA256withECDSA") даёт DER → конвертировать в P1363.
  5. Публичный ключ устройства: SPKI DER, base64. Время жизни envelope ≤ 60 с.

Версии

CONTRACT_VERSION = semver пакета. Ломающее изменение — новая major-версия и новый путь API (/v3). Gateway поддерживает текущую и предыдущую minor.

Команды

npm run generate   # регенерация
npm run check      # регенерация + проверка, что generated/ не изменился (CI)
npm test           # фикстуры, лимиты, эталон подписи
Details
npm
2026-11-11 17:43:59 +03:00
4
UNLICENSED
14 KiB
Assets (1)
Versions (6) View all
2.5.0 2026-11-14
2.4.0 2026-11-14
2.3.0 2026-11-12
2.2.0 2026-11-11
2.1.0 2026-11-11