@opsregistry/bridge-client

Общая TypeScript-библиотека для безопасного взаимодействия браузерных приложений с локальным opsregistry-bridge. Она позволяет любому приложению использовать локальные операции OpsRegistry и не содержит кода, специфичного для VARM.

Клиент:

• находит локальный Bridge и проверяет версию протокола;
• связывает origin приложения с локальной службой;
• принимает короткоживущий допуск к каждой операции;
• проверяет запросы и ответы схемами @opsregistry/contracts;
• предоставляет типизированные методы для настройки электронной подписи, поиска устройств и сертификатов, а также создания подписи;
• различает недоступность службы, нарушение протокола и ошибку самой операции.

Библиотека не содержит интерфейс, криптографию, закрытые ключи и бизнес-логику провайдеров. Приложение само показывает пользователю установку и подписание, а допуски к операциям выдаёт его backend после проверки прав пользователя.

operationGrant — не произвольный API-токен, а короткоживущий компактный JWS с EdDSA. Перед обращением к backend приложение получает requestId через createRequestId(). Grant связан с конкретными Bridge, origin, кодом операции, requestId и SHA-256 канонизированного input, поэтому его нельзя перенести на другой запрос или повторно использовать. Backend должен вычислять хеш input по JSON Canonicalization Scheme (RFC 8785); формат claims экспортируется из @opsregistry/contracts/bridge/grant.

Пример

import { BridgeClient } from '@opsregistry/bridge-client';

const bridge = new BridgeClient();
const manifest = await bridge.discover();
const requestId = bridge.createRequestId();

// Backend signs bridgeId, origin, operation, requestId and the RFC 8785 input hash.
const operationGrant = await getOperationGrant({ bridgeId: manifest.bridgeId, requestId });

const environment = await bridge.inspectSigningEnvironment(
	{
		requirements: {
			signatureFormats: ['cadesBes'],
			qualifiedSignature: 'required'
		}
	},
	{ requestId, operationGrant }
);

Для полного сценария приложение сначала вызывает discover(), при необходимости выполняет pair(), открывает возвращённый approvalUrl в новой вкладке и опрашивает getPairing(requestId). После локального подтверждения оно получает допуск от своего backend и вызывает нужную операцию. Специализированные методы доступны для следующих контрактов:

• trust.signingEnvironment.inspect;
• trust.signingEnvironment.configure;
• trust.device.list;
• trust.certificate.list;
• trust.certificate.resolve;
• trust.digitalSignature.create.

Для остальных операций можно использовать типизированное ядро execute() с соответствующей Zod-схемой результата.

Результат discover() содержит modules и operations. Поле состояния операции позволяет интерфейсу различить готовую возможность, модуль, который можно установить, текущую установку и ошибку настройки. Старого общего operationCodes нет: оно не позволяло отличить установленный функционал от доступного для загрузки.

Manifest также возвращает operatingSystem, architecture и полный targetTriple. Клиент не угадывает совместимость платформ: выбор конкретного бинарника выполняет сам Bridge по точному совпадению с подписанным каталогом. Поэтому один и тот же клиент работает с Bridge на Windows, Linux, macOS и будущих поддерживаемых системах.

Безопасность транспорта

По умолчанию клиент обращается к http://127.0.0.1:47831. Удалённые хосты отклоняются даже при явной настройке. В production HTTPS-приложение должно быть связано с Bridge и передавать новый короткоживущий допуск для каждой операции.

Разработка

bun install
bun run check
bun test
bun run build

English

@opsregistry/bridge-client is a framework-neutral TypeScript client for secure communication between browser applications and a local OpsRegistry Bridge. It validates loopback endpoints, protocol envelopes and operation payloads without implementing UI or cryptography.