@prozorro/prozorro-eds

Бібліотека електронного підпису для вебзастосунків Prozorro. Забезпечує:

• ініціалізацію оточення підпису;
• підпис та перевірку об’єктів із ЦБД;
• підпис довільних даних;
• роботу з віджетом (iframe) для накладання підпису користувачем.

Встановлення

NPM

npm i @prozorro/prozorro-eds

YARN

yarn add @prozorro/prozorro-eds

Швидкий старт

import { ProzorroEds } from "@prozorro/prozorro-eds";

await ProzorroEds.init({ debug: true });

Приклад підпису довільних даних

import { ProzorroEds } from "@prozorro/prozorro-eds";

await ProzorroEds.init({ debug: true });

const signed = await ProzorroEds.sign("Any data", {
  asBase64String: true,          // опційно: отримати base64
});

console.log(signed);

Приклад перевірки підпису

import { ProzorroEds } from "@prozorro/prozorro-eds";

await ProzorroEds.init({ debug: true });

const info = await ProzorroEds.verify("BASE64_SIGNED_DATA");

console.log(info.signers); // масив підписантів

Робота з віджетом (iframe)

import { ProzorroEds } from "@prozorro/prozorro-eds";

await ProzorroEds.init({ debug: true });

const widget = await ProzorroEds.loadWidget();

// Напр., скинути зчитаний ключ
await widget.resetKey();

Для завантаження віджета домен вебзастосунку має бути доданий у список дозволених (інакше користувач побачить “Доступ заборонено”). В тестовому середовищі історично дозволені localhost та sign-widget-test.eu.iit.com.ua. На сторінці має бути контейнер для iframe, напр.:
<div id="sign-widget-parent" style="width: 580px; height: 420px"></div>.

API

Нижче — зведена специфікація методів https://www.npmjs.com/package/@prozorro/prozorro-eds?activeTab=code файл prozorro-eds.d.ts; реальні типи доступні з пакета.

Ініціалізація

await ProzorroEds.init(options?: EdsInitializationConfigType): Promise<void>

• Має бути викликаний перед будь-якими іншими операціями (підпис/перевірка/віджет).
  Опції:
  • debug?: boolean — службові логи в консолі;
  • callbackAfterAuth?: (certs: CertificateType[]) => void — викликається після зчитування ключа користувачем;
  • ignoreFields?: string[] — ключі полів, які ігноруються при порівнянні об’єктів (під час валідації підпису з ЦБД).

Віджет підпису

const widget = await ProzorroEds.loadWidget(): Promise<WidgetUserServiceInterface>

• Завантажує iframe-віджет підпису (потрібний для накладання підпису).
• WidgetUserServiceInterface:
  • resetKey(): Promise<void> — скинути зчитаний ключ.

Підписання

// 1) Підпис довільних даних
await ProzorroEds.sign(data: Uint8Array | string, options?: UserSignOptionsType): Promise<Uint8Array | string>

// 2) Підпис хешу
await ProzorroEds.signHash(data: string, options?: UserSignOptionsType): Promise<Uint8Array | string>

UserSignOptionsType:

• asBase64String?: boolean — повернути підпис як base64-рядок (інакше Uint8Array);
• previousSign?: Uint8Array | string | null — додати підпис до наданого (можливо лише якщо попередній підпис не містить цього підписувача).

Повернення:

• sign(...) / signHash(...) — масив байт або base64 (залежно від asBase64String);

Перевірка

// 1) Перевірка довільного підпису (base64)
await ProzorroEds.verify(sign: string): Promise<SignType>

// 2) Перевірка об’єктів із ЦБД
await ProzorroEds.verifyObjects(links: string[]): Promise<VerifyObjectResponseType[]>

Повернення:

• verify(...) — структура підпису SignType з масивом підписантів;
• verifyObjects(...) — дані про відмінності між підписом і фактичним JSON з ЦБД (через jsondiffpatch), список підписантів, та нормалізовані дані з підпису.

Типи

EdsInitializationConfigType

• ignoreFields?: string[]
• callbackAfterAuth?: (CertificateType[]) => void
• debug?: boolean
• environment?: "production" | "development"

EdsWidgetConfigType

• parentId: string; - Ідентифікатор братківського елементу для відображення iframe, який завантажує сторінку SignWidget
• frameId: string; - Ідентифікатор iframe, який завантажує сторінку SignWidget

UserSignOptionsType

• asBase64String?: boolean
• previousSign?: Uint8Array | string | null

SignType

• data: string
• signers: SignerType[]

SignerType (витяг)

• issuer, issuerCN, serial, subject, subjectCN, subjectOrg, subjectOrgUnit, subjectTitle, subjectState, subjectLocality, subjectFullName, subjectAddress, subjectPhone, subjectEMail, subjectDNS, subjectEDRPOUCode, subjectDRFOCode
• isFilled, isTimeAvail, isTimeStamp
• time: TimeType

TimeType

• year, month, dayOfWeek, day, hour, minute, second, milliseconds

SignedObjectType

• id: string — ідентифікатор об’єкта з ЦБД
• sign: Uint8Array | string — підпис (тип залежить від опцій підпису)

VerifyObjectResponseType

• difference?: DeltaType — результат порівняння підпису з JSON-даними ЦБД
• signers: SignerType[]
• data.fromSign: JSON — дані з підпису
• data.fromDb: JSON — дані з ЦБД

CertificateType

• data: Uint8Array
• infoEx: InfoExType — розширена інформація сертифіката (OCSP/TSP/модуль RSA, строки дії, серійний номер, ключові призначення тощо).

Обробка помилок

Обгортайте виклики бібліотеки у try..catch. Користувач отримує читабельний текст помилки; службова інформація виводиться у консоль (за debug: true).

Release notes

• 21.10.2025
  • Refactored eusign.js dependency;
• 23.10.2025
  • Removed environment dependency from -beta library tag;
  • Renamed the UserOptionsType type to EdsInitializationConfigType;
  • Extended the EdsInitializationConfigType type, added environment field;
  • Added the EdsWidgetConfigType type for loadWidget;
  • Renamed window.eds to window.ProzorroEds;
  • Updated the validation messages;
  • Deleted the Sentry service;
• 25.11.2025
  • Returned signHash method;

Ліцензія

© Prozorro. Усі права захищені.