eimzo-ts: TypeScript client for E-IMZO

Let a web page use E-IMZO, the desktop application for electronic digital signatures in Uzbekistan (ЭЦП / ERI): list the user's keys, create PKCS#7 signatures, and log users in with their digital signature.

Unofficial library. Not affiliated with the developers of E-IMZO.

What it is

eimzo-ts is a browser library with a typed, Promise-based API and zero runtime dependencies. It replaces e-imzo.js and e-imzo-client.js from the official E-IMZO example: no global variables and no changes to built-in prototypes. ESM, CommonJS and a <script> build (global EimzoClient) are included, with TypeScript declarations.

How it works

1. The page connects to E-IMZO on the user's computer over WebSocket: ws://127.0.0.1:64646 for http pages, wss://127.0.0.1:64443 for https.
2. E-IMZO shows its own password window. The page never sees the password.
3. E-IMZO returns a PKCS#7 (CMS) signature as base64.
4. Your backend verifies the signature with e-imzo-server. This library does not verify signatures.

Install

npm install eimzo-ts

Quick start

import { createEimzo, createFetchBackend, DEV_API_KEYS } from 'eimzo-ts';

const eimzo = createEimzo({
  apiKeys: { ...DEV_API_KEYS, 'my-site.uz': 'API key for my-site.uz' },
  backend: createFetchBackend({
    challengeUrl: '/api/eimzo/challenge',
    loginUrl: '/api/eimzo/login',
    timestampUrl: '/api/eimzo/timestamp',
  }),
});

const keys = await eimzo.listKeys();                // the user's keys
const user = await eimzo.login(keys[0]);            // E-IMZO asks for the password
const pkcs7 = await eimzo.signDocument('document'); // signature + timestamp

Use cases

• Log in with a digital signature: challenge, signature, server-side verification.
• Sign documents and files: attached or detached PKCS#7, with a timestamp.
• Show the user's keys: owner name, TIN (INN), PINFL, organization, validity, expiry.
• Migrate from e-imzo.js callbacks to async/await (migration guide, in Russian).

Features

• PFX keys, ID card, BAIK token and CKC devices.
• Typed errors with stable codes (NOT_INSTALLED, WRONG_PASSWORD, CANCELLED, …) and messages in Russian, Uzbek (Latin and Cyrillic), Karakalpak and English.
• Signing calls are queued: a double click does not open two password windows.
• When E-IMZO forgets the loaded key, it is loaded again and the signature is retried.
• createFetchBackend() matches e-imzo-server's response format.
• Checked against E-IMZO 6.3.5: cancel, wrong password, signing, unloading the key.

Compatibility

Runs in modern browsers (ES2020). It is framework-agnostic, so it can be used from Angular, React, Vue, Svelte or plain JavaScript. With server-side rendering (Next.js, Nuxt, Angular SSR) call it only on the client, because E-IMZO runs on the user's computer. Requires E-IMZO 4.86 or newer by default.

When not to use it

• To verify signatures: use e-imzo-server on your backend.
• For mobile signing (ID-CARD E-IMZO MOBILE): not supported yet.
• If you need ready-made UI components: there are none.

More in the FAQ. Try the live demo; it works without E-IMZO, using mock keys.