eimzo-sign-core 0.1.0

package/src/client.ts

@@ -0,0 +1,456 @@
+import { EimzoError, toEimzoError } from './errors'
+import type {
+  AuditEvent,
+  BatchSignItem,
+  Cert,
+  CertType,
+  EimzoClientOptions,
+  EimzoVersion,
+  SignBatchOptions,
+  SignDoc,
+} from './types'
+import { nowIso, normalizeSerial, throwIfAborted, withTimeout } from './util'
+import { getBase64, getCapiws, rawClient } from './vendor'
+import type { RawCapiResponse, RawCert } from './raw-types'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_KEY_LOAD_TIMEOUT_MS = 120_000
+const DEFAULT_MIN_VERSION: EimzoVersion = { major: 3, minor: 37 }
+
+/**
+ * E-IMZO bilan ishlashning framework-agnostik yadrosi.
+ *
+ * Kafolatlar:
+ *  - har chaqiruvda timeout bor (osilib qolmaydi);
+ *  - `signBatch` kalitni BIR MARTA yuklaydi (parol bir marta so'raladi);
+ *  - har imzodan keyin seriya raqami tanlangan sertifikatga tekshiriladi;
+ *  - sessiya tugagach yuklangan kalit holati JS'da saqlanmaydi;
+ *  - `console` ga hech narsa yozilmaydi — hammasi `onAudit` orqali.
+ */
+export class EimzoClient {
+  private readonly apiKeys: ReadonlyArray<readonly [string, string]>
+  private readonly timeoutMs: number
+  private readonly keyLoadTimeoutMs: number
+  private readonly minVersion: EimzoVersion
+  private readonly onAudit?: (event: AuditEvent) => void
+
+  /** Faqat joriy sessiya davomida to'ldiriladi; `signBatch` oxirida tozalanadi. */
+  private activeKeySerial: string | null = null
+
+  constructor(options: EimzoClientOptions) {
+    if (!Array.isArray(options?.apiKeys) || options.apiKeys.length === 0) {
+      throw new EimzoError(
+        'E_MISCONFIGURED',
+        "EimzoClient: 'apiKeys' berilishi shart ([[domen, kalit], ...]).",
+      )
+    }
+    this.apiKeys = options.apiKeys
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    this.keyLoadTimeoutMs = options.keyLoadTimeoutMs ?? DEFAULT_KEY_LOAD_TIMEOUT_MS
+    this.minVersion = options.minVersion ?? DEFAULT_MIN_VERSION
+    this.onAudit = options.onAudit
+  }
+
+  // ─── Commanda: o'rnatish ────────────────────────────────────────────────
+
+  /**
+   * Versiyani tekshiradi va domen API kalitlarini o'rnatadi.
+   * Har imzolash seansidan oldin (yoki ilova yuklanganda bir marta) chaqiring.
+   */
+  async install(): Promise<EimzoVersion> {
+    const version = await this.checkVersion()
+
+    if (!isVersionAtLeast(version, this.minVersion)) {
+      throw new EimzoError(
+        'E_VERSION_LOW',
+        `E-IMZO ${version.major}.${version.minor} — kamida ` +
+          `${this.minVersion.major}.${this.minVersion.minor} talab qilinadi.`,
+      )
+    }
+
+    rawClient.API_KEYS = this.apiKeys.flatMap(([domain, key]) => [domain, key])
+    await this.installApiKeys()
+    return version
+  }
+
+  checkVersion(): Promise<EimzoVersion> {
+    return withTimeout<EimzoVersion>(
+      this.timeoutMs,
+      () =>
+        new EimzoError(
+          'E_NOT_INSTALLED',
+          "E-IMZO dasturi javob bermadi (versiya so'rovi). Dastur ishga tushganini tekshiring.",
+        ),
+      (resolve, reject) => {
+        rawClient.checkVersion(
+          (major, minor) => {
+            this.audit({ type: 'version_checked', ts: nowIso(), major, minor })
+            resolve({ major, minor })
+          },
+          (error) =>
+            reject(
+              new EimzoError('E_NOT_INSTALLED', 'E-IMZO dasturi topilmadi.', {
+                cause: error,
+              }),
+            ),
+        )
+      },
+    )
+  }
+
+  private installApiKeys(): Promise<void> {
+    return withTimeout<void>(
+      this.timeoutMs,
+      () => new EimzoError('E_TIMEOUT', "API kalitlari o'rnatilmadi (javob yo'q)."),
+      (resolve, reject) => {
+        rawClient.installApiKeys(
+          () => resolve(),
+          (error) =>
+            reject(
+              new EimzoError(
+                'E_API_KEY_REJECTED',
+                "Domen API kaliti rad etildi. Domen va kalit juftligini tekshiring.",
+                { cause: error },
+              ),
+            ),
+        )
+      },
+    )
+  }
+
+  // ─── So'rov: sertifikatlar ───────────────────────────────────────────────
+
+  /** Foydalanuvchining barcha kalitlari (disk + token). ID-karta bunga kirmaydi. */
+  listCerts(): Promise<Cert[]> {
+    return withTimeout<Cert[]>(
+      this.timeoutMs,
+      () => new EimzoError('E_TIMEOUT', "Sertifikatlar ro'yxati javob bermadi."),
+      (resolve, reject) => {
+        rawClient.listAllUserKeys(
+          (cert, index) => `${cert.serialNumber}-${index}`,
+          (_id, cert) => cert,
+          (items) => {
+            const certs = (items as RawCert[]).map((raw) => normalizeCert(raw))
+            this.audit({ type: 'certs_listed', ts: nowIso(), count: certs.length })
+            resolve(certs)
+          },
+          (error) =>
+            reject(
+              new EimzoError('E_NO_CERTS', "Sertifikatlarni o'qib bo'lmadi.", {
+                cause: error,
+              }),
+            ),
+        )
+      },
+    )
+  }
+
+  /** ID-karta o'quvchiga ulanganmi. Timeout'da `false` qaytaradi (xato tashlamaydi). */
+  isIdCardPlugged(): Promise<boolean> {
+    return new Promise<boolean>((resolve) => {
+      let settled = false
+      const finish = (value: boolean): void => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        resolve(value)
+      }
+      const timer = setTimeout(() => finish(false), this.timeoutMs)
+      try {
+        rawClient.idCardIsPLuggedIn(
+          (plugged) => finish(Boolean(plugged)),
+          () => finish(false),
+        )
+      } catch {
+        finish(false)
+      }
+    })
+  }
+
+  /** ID-karta uchun "sertifikat" o'rnini bosuvchi belgili obyekt. */
+  static idCardCert(): Cert {
+    const far = new Date(Date.now() + 10 * 365 * 24 * 60 * 60 * 1000)
+    return {
+      serialNumber: 'IDCARD',
+      CN: 'ID card',
+      TIN: '',
+      UID: '',
+      O: '',
+      T: '',
+      validFrom: new Date(0),
+      validTo: far,
+      type: 'idcard',
+      raw: null,
+    }
+  }
+
+  // ─── Commanda: partiyali imzolash ───────────────────────────────────────
+
+  /**
+   * Bitta sertifikat bilan bir nechta hujjatni imzolaydi.
+   *
+   * Oqim:
+   *  1. Kalitni bir marta yuklaydi (`idcard` bo'lsa — yuklamaydi).
+   *  2. Har hujjat uchun `create_pkcs7` ni KETMA-KET chaqiradi (parallel EMAS —
+   *     CAPIWS bitta soket).
+   *  3. Har natijada `signer_serial_number` ni tekshiradi.
+   *  4. Yakunda kalit holatini tozalaydi.
+   *
+   * Bitta hujjat xato bersa — massivda `ok:false` bilan qoladi, qolganlari davom etadi.
+   * Foydalanuvchi bekor qilsa (`signal`) — `E_CANCELLED` tashlanadi.
+   */
+  async signBatch(
+    cert: Cert,
+    docs: readonly SignDoc[],
+    options: SignBatchOptions = {},
+  ): Promise<BatchSignItem[]> {
+    if (docs.length === 0) {
+      throw new EimzoError('E_MISCONFIGURED', "Imzolash uchun hujjat berilmadi.")
+    }
+    assertUniqueIds(docs)
+    const { signal, onProgress } = options
+    throwIfAborted(signal)
+
+    const base64 = getBase64()
+    const keyId = await this.acquireKey(cert, signal)
+
+    const results: BatchSignItem[] = []
+    let signed = 0
+    let failed = 0
+
+    try {
+      for (let i = 0; i < docs.length; i += 1) {
+        throwIfAborted(signal)
+        const doc = docs[i]!
+        onProgress?.({ done: i, total: docs.length, currentId: doc.id })
+        this.audit({
+          type: 'sign_started',
+          ts: nowIso(),
+          serial: cert.serialNumber,
+          docId: doc.id,
+        })
+
+        try {
+          const raw = await this.createPkcs7(keyId, base64.encode(doc.content), signal)
+          const signerSerial = String(raw['signer_serial_number'] ?? '')
+
+          if (
+            cert.type !== 'idcard' &&
+            normalizeSerial(signerSerial) !== normalizeSerial(cert.serialNumber)
+          ) {
+            throw new EimzoError(
+              'E_SERIAL_MISMATCH',
+              'Imzolangan sertifikat seriyasi tanlangandan farq qiladi.',
+            )
+          }
+
+          results.push({
+            id: doc.id,
+            ok: true,
+            pkcs7_64: String(raw['pkcs7_64'] ?? ''),
+            signature_hex: String(raw['signature_hex'] ?? ''),
+            signer_serial_number: signerSerial,
+          })
+          signed += 1
+          this.audit({
+            type: 'sign_ok',
+            ts: nowIso(),
+            serial: cert.serialNumber,
+            docId: doc.id,
+          })
+        } catch (error) {
+          // Bekor qilish — butun partiyani to'xtatadi.
+          if (EimzoError.is(error, 'E_CANCELLED')) throw error
+
+          const err = toEimzoError(error, 'E_SIGN_FAILED', 'Hujjatni imzolab bo\'lmadi.')
+          results.push({ id: doc.id, ok: false, error: err })
+          failed += 1
+          this.audit({
+            type: 'sign_failed',
+            ts: nowIso(),
+            docId: doc.id,
+            code: err.code,
+          })
+        }
+      }
+
+      onProgress?.({ done: docs.length, total: docs.length })
+      return results
+    } finally {
+      // Kalitni JS holatida ushlab turmaymiz. E-IMZO dasturi kalitni o'z
+      // ichida qisqa TTL bilan eslaydi; biz unga tayanmaymiz.
+      this.activeKeySerial = null
+      this.audit({
+        type: 'session_ended',
+        ts: nowIso(),
+        serial: cert.serialNumber,
+        signed,
+        failed,
+      })
+    }
+  }
+
+  /** Yagona hujjatni imzolash — `signBatch` ustidagi qulaylik. */
+  async sign(
+    cert: Cert,
+    content: string,
+    options: SignBatchOptions = {},
+  ): Promise<BatchSignItem> {
+    const [item] = await this.signBatch(cert, [{ id: 'single', content }], options)
+    return item!
+  }
+
+  // ─── Ichki ─────────────────────────────────────────────────────────────
+
+  private async acquireKey(cert: Cert, signal?: AbortSignal): Promise<string> {
+    if (cert.type === 'idcard') return 'idcard'
+    try {
+      return await this.loadKey(cert, signal)
+    } catch (error) {
+      throw toEimzoError(
+        error,
+        'E_KEY_LOAD_CANCELLED',
+        'Kalit yuklanmadi yoki bekor qilindi.',
+      )
+    }
+  }
+
+  private loadKey(cert: Cert, signal?: AbortSignal): Promise<string> {
+    return withTimeout<string>(
+      this.keyLoadTimeoutMs,
+      () =>
+        new EimzoError(
+          'E_KEY_LOAD_CANCELLED',
+          "Kalit yuklash javob bermadi (parol oynasi ochilmadi yoki yopilmadi).",
+        ),
+      (resolve, reject) => {
+        rawClient.loadKey(
+          cert.raw as RawCert,
+          (id) => {
+            this.activeKeySerial = cert.serialNumber
+            this.audit({
+              type: 'key_loaded',
+              ts: nowIso(),
+              serial: cert.serialNumber,
+            })
+            resolve(id)
+          },
+          (error) =>
+            reject(
+              new EimzoError('E_KEY_LOAD_CANCELLED', 'Kalit yuklanmadi.', {
+                cause: error,
+              }),
+            ),
+        )
+      },
+      signal,
+    )
+  }
+
+  private createPkcs7(
+    keyId: string,
+    contentBase64: string,
+    signal?: AbortSignal,
+  ): Promise<RawCapiResponse> {
+    return withTimeout<RawCapiResponse>(
+      this.timeoutMs,
+      () => new EimzoError('E_TIMEOUT', "Imzolash javob bermadi (create_pkcs7)."),
+      (resolve, reject) => {
+        let capiws
+        try {
+          capiws = getCapiws()
+        } catch (error) {
+          reject(error)
+          return
+        }
+        capiws.callFunction(
+          {
+            plugin: 'pkcs7',
+            name: 'create_pkcs7',
+            arguments: [contentBase64, keyId, 'no'],
+          },
+          (_event, data) => {
+            if (data && data.success) {
+              resolve(data)
+            } else {
+              reject(
+                new EimzoError(
+                  'E_SIGN_FAILED',
+                  reasonOf(data) || 'E-IMZO imzolashni rad etdi.',
+                  { cause: data },
+                ),
+              )
+            }
+          },
+          (error) =>
+            reject(
+              new EimzoError('E_TRANSPORT', "E-IMZO bilan aloqa uzildi.", {
+                cause: error,
+              }),
+            ),
+        )
+      },
+      signal,
+    )
+  }
+
+  private audit(event: AuditEvent): void {
+    if (!this.onAudit) return
+    try {
+      this.onAudit(event)
+    } catch {
+      // Audit hook consumer kodida yashaydi — uning xatosi kutubxonani buzmasin.
+    }
+  }
+}
+
+// ─── Modul yordamchilari ──────────────────────────────────────────────────
+
+function isVersionAtLeast(actual: EimzoVersion, min: EimzoVersion): boolean {
+  if (actual.major !== min.major) return actual.major > min.major
+  return actual.minor >= min.minor
+}
+
+function reasonOf(data: RawCapiResponse | undefined | null): string {
+  return data && typeof data.reason === 'string' ? data.reason : ''
+}
+
+const KNOWN_TYPES: ReadonlySet<CertType> = new Set(['pfx', 'ftjc', 'idcard'])
+
+function normalizeCert(raw: RawCert): Cert {
+  return {
+    serialNumber: normalizeSerial(raw.serialNumber),
+    CN: str(raw.CN),
+    TIN: str(raw.TIN),
+    UID: str(raw.UID),
+    O: str(raw.O),
+    T: str(raw.T),
+    validFrom: toDate(raw.validFrom),
+    validTo: toDate(raw.validTo),
+    type: KNOWN_TYPES.has(raw.type as CertType) ? (raw.type as CertType) : 'pfx',
+    raw,
+  }
+}
+
+function str(value: unknown): string {
+  return value == null ? '' : String(value)
+}
+
+function toDate(value: string | Date | undefined): Date {
+  if (value instanceof Date) return value
+  const d = new Date(String(value ?? ''))
+  return Number.isNaN(d.getTime()) ? new Date(0) : d
+}
+
+function assertUniqueIds(docs: readonly SignDoc[]): void {
+  const seen = new Set<string>()
+  for (const doc of docs) {
+    if (!doc.id) {
+      throw new EimzoError('E_MISCONFIGURED', 'Har bir hujjatda id bo\'lishi shart.')
+    }
+    if (seen.has(doc.id)) {
+      throw new EimzoError('E_MISCONFIGURED', `Hujjat id'si takrorlangan: ${doc.id}`)
+    }
+    seen.add(doc.id)
+  }
+}

package/src/errors.ts

@@ -0,0 +1,73 @@
+/**
+ * E-IMZO xatolarining barqaror kontrakti.
+ *
+ * Chaqiruvchi kod HAR DOIM `error.code` bo'yicha shox tanlaydi — xabar matnini
+ * hech qachon parslamaydi (matn i18n bilan o'zgaradi).
+ */
+export type EimzoErrorCode =
+  /** E-IMZO dasturi ishga tushmagan yoki javob bermayapti. */
+  | 'E_NOT_INSTALLED'
+  /** E-IMZO versiyasi talab qilinganidan past. */
+  | 'E_VERSION_LOW'
+  /** Domen uchun API kaliti rad etildi (noto'g'ri kalit yoki domen). */
+  | 'E_API_KEY_REJECTED'
+  /** Foydalanuvchida sertifikat/kalit topilmadi yoki ro'yxatni o'qib bo'lmadi. */
+  | 'E_NO_CERTS'
+  /** Kalit yuklanmadi — ko'pincha foydalanuvchi parol oynasini yopgan. */
+  | 'E_KEY_LOAD_CANCELLED'
+  /** Imzolangan sertifikatning seriya raqami tanlangandan farq qiladi. XAVFSIZLIK. */
+  | 'E_SERIAL_MISMATCH'
+  /** `create_pkcs7` muvaffaqiyatsiz tugadi. */
+  | 'E_SIGN_FAILED'
+  /** E-IMZO belgilangan vaqt ichida javob bermadi. */
+  | 'E_TIMEOUT'
+  /** Foydalanuvchi yoki idle-taymer amalni bekor qildi. */
+  | 'E_CANCELLED'
+  /** Lokal soket / transport xatosi. */
+  | 'E_TRANSPORT'
+  /** Kutubxona noto'g'ri sozlangan (masalan, apiKeys berilmagan). */
+  | 'E_MISCONFIGURED'
+
+export interface EimzoErrorOptions {
+  cause?: unknown
+}
+
+export class EimzoError extends Error {
+  readonly code: EimzoErrorCode
+  /** Asl sabab (vendor xatosi, CAPIWS javobi va h.k.). ES2022 `Error.cause` bilan bir xil nom. */
+  readonly cause?: unknown
+
+  constructor(code: EimzoErrorCode, message: string, options?: EimzoErrorOptions) {
+    super(message)
+    this.name = 'EimzoError'
+    this.code = code
+    this.cause = options?.cause
+    // TS -> eski target'da instanceof ishlashi uchun
+    Object.setPrototypeOf(this, EimzoError.prototype)
+  }
+
+  /** `EimzoError.is(e)` yoki `EimzoError.is(e, 'E_TIMEOUT')`. */
+  static is(error: unknown, code?: EimzoErrorCode): error is EimzoError {
+    return (
+      error instanceof EimzoError && (code === undefined || error.code === code)
+    )
+  }
+
+  /** Bekor qilingan (foydalanuvchi voz kechgan) — odatda jimgina o'tiladi. */
+  static isCancelled(error: unknown): boolean {
+    return (
+      EimzoError.is(error, 'E_CANCELLED') ||
+      EimzoError.is(error, 'E_KEY_LOAD_CANCELLED')
+    )
+  }
+}
+
+/** Noma'lum qiymatni EimzoError'ga keltiradi (allaqachon EimzoError bo'lsa — o'zini qaytaradi). */
+export function toEimzoError(
+  error: unknown,
+  fallbackCode: EimzoErrorCode,
+  fallbackMessage: string,
+): EimzoError {
+  if (EimzoError.is(error)) return error
+  return new EimzoError(fallbackCode, fallbackMessage, { cause: error })
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * eimzo-sign-core — E-IMZO imzolashning framework-agnostik yadrosi.
+ *
+ * @example
+ * ```ts
+ * import { EimzoClient } from 'eimzo-sign-core'
+ *
+ * const eimzo = new EimzoClient({
+ *   apiKeys: [['example.uz', '<E-IMZO tomonidan berilgan kalit>']],
+ *   onAudit: (e) => auditLog.write(e),
+ * })
+ *
+ * await eimzo.install()
+ * const certs = await eimzo.listCerts()
+ * const results = await eimzo.signBatch(certs[0], [
+ *   { id: 'doc-1', content: xml1 },
+ *   { id: 'doc-2', content: xml2 },
+ * ])
+ * ```
+ */
+export { EimzoClient } from './client'
+export { EimzoError, toEimzoError } from './errors'
+export type { EimzoErrorCode, EimzoErrorOptions } from './errors'
+
+export type {
+  AuditEvent,
+  BatchProgress,
+  BatchSignItem,
+  Cert,
+  CertType,
+  EimzoClientOptions,
+  EimzoVersion,
+  SignBatchOptions,
+  SignDoc,
+  SignResult,
+} from './types'
+
+export {
+  certExpiresSoon,
+  certIsExpired,
+  certIsNotYetValid,
+  certIsUsable,
+  dedupeCerts,
+  sortCerts,
+} from './cert-utils'

package/src/raw-types.ts

@@ -0,0 +1,65 @@
+/**
+ * Vendored E-IMZO SDK'ning XOM (raw) API shakllari.
+ * Bu tiplar faqat `client.ts` ichida ishlatiladi; tashqariga chiqmaydi.
+ * Tashqi API uchun `types.ts` ga qarang.
+ */
+
+export interface RawCapiResponse {
+  success: boolean
+  reason?: string
+  [key: string]: unknown
+}
+
+export interface RawCapiws {
+  URL?: string
+  callFunction(
+    funcDef: { plugin?: string; name: string; arguments: unknown[] },
+    callback: (event: unknown, data: RawCapiResponse) => void,
+    error: (e: unknown) => void,
+  ): void
+}
+
+export interface RawCert {
+  disk?: string
+  path?: string
+  name?: string
+  alias?: string
+  serialNumber: string
+  validFrom: string | Date
+  validTo: string | Date
+  CN?: string
+  TIN?: string
+  UID?: string
+  O?: string
+  T?: string
+  type?: string
+}
+
+export interface RawEimzoClient {
+  API_KEYS: string[]
+
+  checkVersion(
+    success: (major: number, minor: number) => void,
+    fail: (error: unknown, message?: unknown) => void,
+  ): void
+
+  installApiKeys(success: () => void, fail: (error: unknown) => void): void
+
+  idCardIsPLuggedIn(
+    success: (plugged: boolean) => void,
+    fail: (error: unknown) => void,
+  ): void
+
+  listAllUserKeys(
+    itemIdGen: (cert: RawCert, index: number) => string,
+    itemUiGen: (id: string, cert: RawCert) => unknown,
+    success: (items: unknown[], firstId: string | null) => void,
+    fail: (error: unknown, reason?: unknown) => void,
+  ): void
+
+  loadKey(
+    cert: RawCert,
+    success: (id: string) => void,
+    fail: (error: unknown) => void,
+  ): void
+}