eimzo-sign-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+/**
+ * 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).
+ */
+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';
+interface EimzoErrorOptions {
+    cause?: unknown;
+}
+declare 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);
+    /** `EimzoError.is(e)` yoki `EimzoError.is(e, 'E_TIMEOUT')`. */
+    static is(error: unknown, code?: EimzoErrorCode): error is EimzoError;
+    /** Bekor qilingan (foydalanuvchi voz kechgan) — odatda jimgina o'tiladi. */
+    static isCancelled(error: unknown): boolean;
+}
+/** Noma'lum qiymatni EimzoError'ga keltiradi (allaqachon EimzoError bo'lsa — o'zini qaytaradi). */
+declare function toEimzoError(error: unknown, fallbackCode: EimzoErrorCode, fallbackMessage: string): EimzoError;
+
+/** Sertifikat turi. `idcard` — ID-karta (alohida oqim, `loadKey` chaqirilmaydi). */
+type CertType = 'pfx' | 'ftjc' | 'idcard';
+/**
+ * Normallashtirilgan sertifikat. `raw` — vendor xom obyekti, `loadKey` ga
+ * o'zgarishsiz uzatiladi (undan tashqarida foydalanmang).
+ */
+interface Cert {
+    serialNumber: string;
+    /** CN — egasi (F.I.Sh yoki tashkilot rahbari). */
+    CN: string;
+    /** STIR / JSHSHIR. */
+    TIN: string;
+    UID: string;
+    /** Tashkilot nomi (jismoniy shaxs kalitida bo'sh). */
+    O: string;
+    T: string;
+    validFrom: Date;
+    validTo: Date;
+    type: CertType;
+    /** @internal vendor xom obyekti */
+    raw: unknown;
+}
+interface EimzoVersion {
+    major: number;
+    minor: number;
+}
+interface EimzoClientOptions {
+    /**
+     * Domen API kalitlari: `[[domen, kalit], ...]`.
+     * E-IMZO tomonidan har domen uchun beriladi.
+     *
+     * MUHIM: kutubxonada default YO'Q. Ilova (consumer) o'z kalitlarini
+     * shu yerda beradi; prod kalitlari kutubxona kodiga yozilmaydi.
+     */
+    apiKeys: ReadonlyArray<readonly [domain: string, key: string]>;
+    /** Har bir CAPIWS chaqiruvi uchun timeout, ms. Default: 30000. */
+    timeoutMs?: number;
+    /**
+     * Kalit yuklash (parol kiritish) uchun alohida, uzunroq timeout, ms.
+     * Default: 120000.
+     */
+    keyLoadTimeoutMs?: number;
+    /** Minimal talab qilinadigan E-IMZO versiyasi. Default: 3.37. */
+    minVersion?: EimzoVersion;
+    /**
+     * Audit hook. Kutubxona HECH QACHON `console` ga yozmaydi — barcha
+     * kuzatuv shu yerdan o'tadi. Ilova buni o'z jurnaliga / SIEM'ga yozadi.
+     * Hook'dagi istisno kutubxonani buzmaydi (yutiladi).
+     *
+     * DIQQAT: `AuditEvent` ataylab minimal — faqat `serial` va `docId`.
+     * CN / TIN / JSHSHIR / imzo bloblari uzatilmaydi.
+     */
+    onAudit?: (event: AuditEvent) => void;
+}
+/** Imzolanadigan bitta hujjat. */
+interface SignDoc {
+    /** Ilova ichidagi barqaror identifikator (natijani hujjatga bog'lash uchun). */
+    id: string;
+    /** Imzolanadigan XOM kontent (matn / XML / base64). Base64 kodlashni kutubxona bajaradi. */
+    content: string;
+}
+/** Bitta hujjat bo'yicha imzo natijasi. */
+interface SignResult {
+    id: string;
+    pkcs7_64: string;
+    signature_hex: string;
+    signer_serial_number: string;
+}
+/** Partiyadagi bitta element — muvaffaqiyat yoki xato. */
+type BatchSignItem = ({
+    id: string;
+    ok: true;
+} & Omit<SignResult, 'id'>) | {
+    id: string;
+    ok: false;
+    error: EimzoError;
+};
+interface BatchProgress {
+    /** Tugagan hujjatlar soni. */
+    done: number;
+    /** Jami hujjatlar. */
+    total: number;
+    /** Hozir imzolanayotgan hujjat id'si (tugagach — undefined). */
+    currentId?: string;
+}
+interface SignBatchOptions {
+    /** Tashqi bekor qilish signali (idle-taymer, modal yopilishi). */
+    signal?: AbortSignal;
+    /** Har bir hujjatdan oldin/keyin chaqiriladi. */
+    onProgress?: (progress: BatchProgress) => void;
+}
+/**
+ * Audit hodisalari. Ataylab minimal maydonlar — shaxsiy ma'lumot yo'q.
+ */
+type AuditEvent = {
+    type: 'version_checked';
+    ts: string;
+    major: number;
+    minor: number;
+} | {
+    type: 'certs_listed';
+    ts: string;
+    count: number;
+} | {
+    type: 'key_loaded';
+    ts: string;
+    serial: string;
+} | {
+    type: 'sign_started';
+    ts: string;
+    serial: string;
+    docId: string;
+} | {
+    type: 'sign_ok';
+    ts: string;
+    serial: string;
+    docId: string;
+} | {
+    type: 'sign_failed';
+    ts: string;
+    docId: string;
+    code: EimzoErrorCode;
+} | {
+    type: 'session_ended';
+    ts: string;
+    serial: string;
+    signed: number;
+    failed: number;
+};
+
+/**
+ * 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.
+ */
+declare class EimzoClient {
+    private readonly apiKeys;
+    private readonly timeoutMs;
+    private readonly keyLoadTimeoutMs;
+    private readonly minVersion;
+    private readonly onAudit?;
+    /** Faqat joriy sessiya davomida to'ldiriladi; `signBatch` oxirida tozalanadi. */
+    private activeKeySerial;
+    constructor(options: EimzoClientOptions);
+    /**
+     * Versiyani tekshiradi va domen API kalitlarini o'rnatadi.
+     * Har imzolash seansidan oldin (yoki ilova yuklanganda bir marta) chaqiring.
+     */
+    install(): Promise<EimzoVersion>;
+    checkVersion(): Promise<EimzoVersion>;
+    private installApiKeys;
+    /** Foydalanuvchining barcha kalitlari (disk + token). ID-karta bunga kirmaydi. */
+    listCerts(): Promise<Cert[]>;
+    /** ID-karta o'quvchiga ulanganmi. Timeout'da `false` qaytaradi (xato tashlamaydi). */
+    isIdCardPlugged(): Promise<boolean>;
+    /** ID-karta uchun "sertifikat" o'rnini bosuvchi belgili obyekt. */
+    static idCardCert(): Cert;
+    /**
+     * 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.
+     */
+    signBatch(cert: Cert, docs: readonly SignDoc[], options?: SignBatchOptions): Promise<BatchSignItem[]>;
+    /** Yagona hujjatni imzolash — `signBatch` ustidagi qulaylik. */
+    sign(cert: Cert, content: string, options?: SignBatchOptions): Promise<BatchSignItem>;
+    private acquireKey;
+    private loadKey;
+    private createPkcs7;
+    private audit;
+}
+
+/** Sertifikat berilgan sanada muddati o'tganmi. */
+declare function certIsExpired(cert: Cert, at?: Date): boolean;
+/** Sertifikat hali kuchга kirmaganmi (validFrom kelajakda). */
+declare function certIsNotYetValid(cert: Cert, at?: Date): boolean;
+/** Sertifikat hozir amal qiladimi (from <= now <= to). */
+declare function certIsUsable(cert: Cert, at?: Date): boolean;
+/** Muddati yaqin kunlarda tugaydimi (default 14 kun). */
+declare function certExpiresSoon(cert: Cert, withinDays?: number, at?: Date): boolean;
+/**
+ * Ro'yxatni ko'rsatish tartibiga keltiradi: amaldagilar tepada,
+ * keyin muddat tugash sanasi bo'yicha kamayish tartibida.
+ * Yangi massiv qaytaradi (mutatsiya yo'q).
+ */
+declare function sortCerts(certs: readonly Cert[], at?: Date): Cert[];
+/** Bir xil seriya raqamli takroriy sertifikatlarni olib tashlaydi (disk + token). */
+declare function dedupeCerts(certs: readonly Cert[]): Cert[];
+
+export { type AuditEvent, type BatchProgress, type BatchSignItem, type Cert, type CertType, EimzoClient, type EimzoClientOptions, EimzoError, type EimzoErrorCode, type EimzoErrorOptions, type EimzoVersion, type SignBatchOptions, type SignDoc, type SignResult, certExpiresSoon, certIsExpired, certIsNotYetValid, certIsUsable, dedupeCerts, sortCerts, toEimzoError };