@islom929/react-eimzo

React hook for E-IMZO digital signatures. Simple API, zero UI dependencies — works with any component library.

Install

npm install @islom929/react-eimzo

No additional setup required. SDK is bundled and auto-injected.

Quick Start

1. Wrap your app with EimzoProvider

import { EimzoProvider } from '@islom929/react-eimzo'

function App() {
  return (
    <EimzoProvider
      apiKeys={['yourdomain.uz', 'YOUR_API_KEY_HERE']}
    >
      <YourApp />
    </EimzoProvider>
  )
}

Default keys for localhost and 127.0.0.1 are always included.

2. Use the hook

import { useEimzo } from '@islom929/react-eimzo'
import type { ICertificate } from '@islom929/react-eimzo'

function SignDocument() {
  const { sign, loadKeys, keyList, isInstalled, isLoading } = useEimzo()

  const handleSign = (cert: ICertificate) => {
    sign({
      keyId: cert,
      data: JSON.stringify({ document: 'content' }),
      onSuccess: (pkcs7) => {
        console.log('Signed:', pkcs7)
      },
      onError: (err) => {
        console.error('Error:', err)
      },
    })
  }

  return (
    <div>
      <button
        onClick={() => void loadKeys()}
        disabled={!isInstalled || isLoading}
      >
        Load keys
      </button>

      {keyList.map((cert) => (
        <button key={cert.serialNumber} onClick={() => handleSign(cert)}>
          {cert.CN}
        </button>
      ))}
    </div>
  )
}

Usage Examples

Sign with PFX certificate

User selects a certificate from the list. E-IMZO app prompts for password.

import { useEimzo } from '@islom929/react-eimzo'
import type { ICertificate } from '@islom929/react-eimzo'

function PfxSign() {
  const { sign, loadKeys, keyList, isInstalled, isLoading } = useEimzo()
  const [result, setResult] = useState('')

  useEffect(() => {
    if (isInstalled) loadKeys()
  }, [isInstalled])

  const handleSign = (cert: ICertificate) => {
    sign({
      keyId: cert,
      data: JSON.stringify({ orderId: 123, amount: 50000 }),
      verifyPassword: true,
      onSuccess: (pkcs7) => {
        setResult(pkcs7)
        // Send to backend
        fetch('/api/verify', {
          method: 'POST',
          body: JSON.stringify({ pkcs7 }),
        })
      },
      onError: (err) => {
        alert(err) // "Ввод пароля отменен" if user cancels
      },
    })
  }

  return (
    <div>
      <h3>Select certificate:</h3>
      {keyList.map((cert, i) => (
        <div key={`${cert.serialNumber}-${i}`}>
          <p>{cert.CN} — {cert.O}</p>
          <p>PINFL: {cert.PINFL} | STIR: {cert.TIN}</p>
          <p>Valid until: {new Date(cert.validTo).toLocaleDateString()}</p>
          <button
            onClick={() => handleSign(cert)}
            disabled={cert.expired || isLoading}
          >
            {cert.expired ? 'Expired' : 'Sign'}
          </button>
        </div>
      ))}
    </div>
  )
}

Sign with tokens

No certificate selection needed. Pass device type directly. Device status is checked automatically on mount.

function TokenSign() {
  const { sign, deviceStatus, isLoading } = useEimzo()

  const handleTokenSign = (device: 'idcard' | 'baikey' | 'ckc') => {
    sign({
      keyId: device,
      data: JSON.stringify({ document: 'content' }),
      onSuccess: (pkcs7) => console.log('Signed:', pkcs7),
      onError: (err) => console.error(err),
    })
  }

  return (
    <div>
      <button
        onClick={() => handleTokenSign('idcard')}
        disabled={!deviceStatus.idcard || isLoading}
      >
        ID Card {deviceStatus.idcard ? '(connected)' : '(not connected)'}
      </button>

      <button
        onClick={() => handleTokenSign('baikey')}
        disabled={!deviceStatus.baikey || isLoading}
      >
        BAIK Token {deviceStatus.baikey ? '(connected)' : '(not connected)'}
      </button>

      <button
        onClick={() => handleTokenSign('ckc')}
        disabled={!deviceStatus.ckc || isLoading}
      >
        CKC {deviceStatus.ckc ? '(connected)' : '(not connected)'}
      </button>
    </div>
  )
}

Error handling

function EimzoStatus() {
  const { isInstalled, error, version } = useEimzo()

  if (error) {
    return (
      <div>
        <p style={{ color: 'red' }}>{error}</p>
        <a href="https://e-imzo.uz/main/downloads/">Download E-IMZO</a>
      </div>
    )
  }

  if (!isInstalled) {
    return <p>Loading...</p>
  }

  return <p>E-IMZO v{version?.major}.{version?.minor} ready</p>
}

Error handling in sign

Errors from E-IMZO SDK are passed directly to onError. Common errors:

sign({
  keyId: cert,
  data: '...',
  onSuccess: (pkcs7) => { /* success */ },
  onError: (err) => {
    // err contains the SDK error message:
    // "Ввод пароля отменен" — user cancelled password dialog
    // "BadPaddingException" — wrong password
    // Other SDK-native errors
    console.error(err)
  },
})

Possible errors

| When | Error | Description | |------|-------|-------------| | Install | "E-IMZO не запущен. Убедитесь, что приложение E-IMZO установлено и запущено." | E-IMZO app is not running or not installed | | Install | "Версия E-IMZO устарела (X.XX). Минимальная версия: 3.36" | E-IMZO version is too old | | loadKeys | "Please install new version of E-IMZO" | SDK version check failed | | sign | "Ввод пароля отменен" | User cancelled password dialog | | sign | "BadPaddingException" | Wrong password entered | | sign | WebSocket error code (number) | Connection to E-IMZO lost |

Version check

The package automatically checks E-IMZO version on mount. Minimum required version is 3.36.

function VersionInfo() {
  const { version, isInstalled } = useEimzo()

  if (!isInstalled || !version) return null

  const v = parseInt(version.major) * 100 + parseInt(version.minor)

  return (
    <div>
      <p>E-IMZO v{version.major}.{version.minor}</p>
      <p>PFX: supported</p>
      <p>ID-card: {v >= 412 ? 'supported' : 'not supported (need v4.12+)'}</p>
      <p>BAIK/CKC: {v >= 486 ? 'supported' : 'not supported (need v4.86+)'}</p>
    </div>
  )
}

E-IMZO version determines which key types are available:

| Version | PFX | ID-card | BAIK | CKC | |---------|-----|---------|------|-----| | v3.36+ | yes | no | no | no | | v4.12+ | yes | yes | no | no | | v4.86+ | yes | yes | yes | yes |

API

EimzoProvider

Wraps your app. Initializes E-IMZO SDK automatically.

| Prop | Type | Description | |------|------|-------------| | apiKeys | string[] | Optional. Additional domain + API key pairs | | children | ReactNode | Required |

useEimzo()

| Property | Type | Description | |----------|------|-------------| | isInstalled | boolean | E-IMZO app detected and running | | isLoading | boolean | Key loading, preparation, or signing is in progress | | error | string \| null | Latest E-IMZO operation error, null if OK | | version | IEimzoVersion \| null | E-IMZO version { major, minor } | | keyList | ICertificate[] | Available certificates | | deviceStatus | IDeviceStatus | Connected hardware devices | | loadKeys | (options?) => Promise<void> | Load certificates into keyList; cached unless force is true | | reloadKeys | (options?) => Promise<void> | Force-refresh certificates; rejects if the refresh fails | | prepareKey | (certificate, verifyPassword?) => Promise<string> | Load a certificate and optionally verify its password/PIN | | signAsync | (params) => Promise<string> | Promise-first signing API; resolves with PKCS#7 | | sign | (params: ISignParams) => void | Sign data |

Device status (idcard, baikey, ckc) is probed in the background once installation succeeds. A slow or unavailable hardware probe does not block PFX key loading or signing.

sign(params)

| Param | Type | Description | |-------|------|-------------| | keyId | ICertificate \| string | Certificate object or 'idcard' / 'baikey' / 'ckc' | | data | string | Data to sign (usually JSON.stringify) | | verifyPassword | boolean | Optional. Verify PFX password or FTJC PIN before signing | | onSuccess | (pkcs7: string) => void | Called with base64 PKCS#7 signature | | onError | (error: string) => void | Optional. Called on failure |

signAsync(params)

Use signAsync when the surrounding code already uses async/await:

const { signAsync } = useEimzo()

const pkcs7 = await signAsync({
  keyId: certificate,
  data: JSON.stringify(payload),
  verifyPassword: true,
})

Use prepareKey(certificate, true) when password/PIN verification must happen before another operation, such as requesting a short-lived server challenge. Pass the returned key ID string to signAsync.

loadKeys({ includeLegacyTokens: true }) includes legacy FTJC certificates. Use reloadKeys(...) when a certificate or token may have been attached after the first list operation.

v0.6 security compatibility

Starting with v0.6, the bundled SDK no longer modifies native Date.prototype or String.prototype objects. The documented React API (EimzoProvider, useEimzo, loadKeys, and sign) is unchanged.

Applications that used undocumented SDK globals directly must migrate:

• Use an application-local date formatter instead of legacy date extensions.
• Use Base64.encode(value) / Base64.decode(value) instead of legacy string extensions.
• The legacy certificate-field splitting extension was internal and has no public replacement.

Behavior

Install is deduplicated per page load. Parallel mounts (including React StrictMode double-invocation) share one installation promise. A failed attempt is cleared, so a later key load can retry after the user starts E-IMZO.

loadKeys() is cached. Once the first successful call populates keyList, later calls resolve immediately. Use reloadKeys() or loadKeys({ force: true }) for a fresh device/certificate list. Requesting includeLegacyTokens: true also refreshes a cache that only contains PFX certificates. For compatibility with v0.5, loadKeys() records an error but resolves after a failed load; the new reloadKeys() API rejects so callers can handle refresh failures explicitly.

apiKeys are managed as domain/key pairs. Reusing a domain during a later provider initialization updates its key instead of corrupting the flat SDK key list. Treat apiKeys as initialization configuration rather than a frequently changing prop.

Types

import type {
  ICertificate,
  ILoadKeysOptions,
  ISignAsyncParams,
  ISignParams,
  IDeviceStatus,
  IEimzoContext,
  IEimzoProviderProps,
  IEimzoVersion,
  TKeyType,
} from '@islom929/react-eimzo'

IEimzoVersion

| Field | Type | Description | |-------|------|-------------| | major | string | Major version (e.g. "4") | | minor | string | Minor version (e.g. "86") |

ICertificate

| Field | Type | Description | |-------|------|-------------| | CN | string | Full name | | PINFL | string | Personal ID number | | TIN | string | Tax ID (STIR) | | O | string | Organization | | T | string | Title/Position | | UID | string | User ID | | serialNumber | string | Certificate serial number | | validFrom | Date | Start of validity | | validTo | Date | End of validity | | type | 'pfx' \| 'ftjc' | Certificate type | | expired | boolean | Whether certificate has expired |

IDeviceStatus

| Field | Type | Description | |-------|------|-------------| | idcard | boolean | ID card / EIMZO-Token connected | | baikey | boolean | BAIK-Token connected | | ckc | boolean | CKC device connected |

Supported Key Types

| Type | Description | E-IMZO Version | |------|-------------|----------------| | PFX | Local certificate file (ERI) | v3.36+ | | ID-card / EIMZO-Token | Physical smart card | v4.12+ | | BAIK-Token | BAIK hardware token | v4.86+ | | CKC | CryptKeyContainer (universal) | v4.86+ |

How It Works

Your React App
    ↓ useEimzo()
@islom929/react-eimzo
    ↓ WebSocket (wss://127.0.0.1:64443)
E-IMZO Desktop App
    ↓
PFX files / USB tokens / ID cards

1. Package injects E-IMZO SDK into the page automatically
2. SDK connects to E-IMZO desktop app via WebSocket
3. loadKeys() fetches available certificates
4. sign() sends data to E-IMZO app for signing
5. E-IMZO app prompts user for password/PIN
6. Signed PKCS#7 (base64) returned via onSuccess

Requirements

• React 18+
• E-IMZO desktop application installed on user's computer

License

MIT