@gerege-systems/eid-mongolia-sdk 0.9.0 → 0.10.0

package/README.md

@@ -154,6 +154,17 @@ console.log(who.documentNumber, who.subject); // баталгаажсан ирг
 const { name, serialNumber } = who.parsedSubject; // "Болд Бат", "PNOMN-12345678" (givenName/surname/commonName/country…)
 ```
 
+Session-ий `person` блок (CA бүртгэлээс — гэрчилгээнд байдаггүй кирилл нэр, төрсөн огноо, хүйс) гарын үсэгт **ордоггүй** —
+гэрчилгээний `SERIALNUMBER`-тэй тулгаж байж итгэнэ:
+
+```ts
+import { personMatchesCertificate } from "@gerege-systems/eid-mongolia-sdk";
+if (personMatchesCertificate(result.person, who.parsedSubject)) {
+  const { firstName, lastName /* ЭЦГИЙН нэр */, familyName /* УРГИЙН овог */, civilId, regNo, birthDate, gender, geID } = result.person!;
+}
+// result.raw — серверийн түүхий JSON (SDK задлаагүй талбарт)
+```
+
 Subject-ийн талбарууд (`parsedSubject`, `validateSign`-д ч мөн) нь `parseSubject(cert)`-ээс — OID 2.5.4.42/4/3/5/6/10/97,
 UTF8String/PrintableString/BMPString. `parseSubject` нь зөвхөн задлалт: баталгаажаагүй гэрчилгээний нэрэнд бүү итгэ.
 
@@ -182,6 +193,18 @@ const sig = eid.validator.validateSign(result, digest); // digest-ийн эср
 console.log(sig.signatureValueB64, sig.subject);
 ```
 
+`SignOptions.fileName` — баримтын нэр CA-ийн /verify хуудас, иргэний түүхэнд харагдана (заавал биш).
+
+Device-link / push-оор эхлүүлсэн sign session-д эхлүүлсэн урсгалаа `expectedFlowType`-оор тулга (`validateAuth`-тай
+ижил: зөрвөл `ValidationError`). Гуравдах параметр нь `hashAlgorithm` мөр (хуучин хэлбэр) эсвэл объект:
+
+```ts
+eid.validator.validateSign(result, digest, { expectedFlowType: "QR" }); // эсвэл "Web2App" / "App2App" / "Notification"
+eid.validator.validateSign(result, digest384, { hashAlgorithm: "SHA-384", expectedFlowType: "Web2App" });
+```
+
+RAW_DIGEST_SIGNATURE-д `flowType` гарын үсэгт ордоггүй (зөвхөн digest зурагдана) — энэ нь RP-API хариуны тулгалт.
+
 ## 3a. Байгууллагын нэрийн өмнөөс гарын үсэг (onBehalfOf)
 
 Иргэн **өөрийн PIN2 гэрчилгээгээр** зурна; тухайн мөчид байгууллагыг төлөөлөх эрхтэйг eID **өөрийн бүртгэлээр**
@@ -224,13 +247,42 @@ try {
 ```
 
 `prepare`-ийн хариу `digest` (DTBS, base64) — иргэний зурах 32 байт, push ба device-link хоёуланд (хуучин CA push-д
-`undefined`). Иргэний гарын үсгийг өөрөө шалгах бол: `eid.validator.validateSign(r, s.digest!)`. Гарын үсэгтэй PDF-ийг
+`undefined`). Иргэний гарын үсгийг өөрөө шалгах бол: `eid.validator.validateSign(r, s.digest!, { expectedFlowType: "QR" })`
+(харуулсан урсгалаа). Гарын үсэгтэй PDF-ийг
 `pdf.document()`-ийн оронд `pdf.documentVerified(sessionId, r.pdf)`-аар тат — `READY` + `outSha256` тулгалтыг хийнэ.
 
+Түр алдаа — `ApiError.retryable` үнэн, `retryAfterMs`-ийн (CA-ийн `Retry-After`, секунд эсвэл огноо) дараа давтана:
+prepare 429 `PDF_PREPARE_BUSY`, 503 `LTV_UNAVAILABLE` / `TSA_UNAVAILABLE`; document 503 `DOCUMENT_PENDING`,
+`TSA_UNAVAILABLE`, `LTV_UNAVAILABLE` (`RETRYABLE_ERROR_CODES`). `headers` — хариуны header. PDF дуудлагын хугацаа
+`pdfTimeoutMs` (анхдагч 80000).
+
 Олон талт гэрээ: А байгууллагын гаралтыг өөрчлөлтгүй Б-ийн `prepare`-д (`docID`, өөр `onBehalfOf`) илгээнэ.
 Session-ий `onBehalfOf` блок (`role`/`rightType`) нь хариу угсрах үеийн бүртгэл; `pdf.signer.onBehalfOf`/`claimedRole`
 нь баримтад бичигдсэн утга.
 
+## 3b. Иргэний PKI самбар (`PKI_READ` эрх)
+
+`eid.person.certificates(etsi)` · `devices` · `activity(etsi, { flow, limit, offset })` · `summary` · `children` — иргэн
+сүүлийн 24 цагт танай RP-ээр нэвтэрсэн байх ёстой (эс бөгөөс `ForbiddenError`). Хариу бүрт `raw`.
+
+## 3c. USB токен
+
+```ts
+import { verifyTokenCertificates, tokenAuthDigest, tokenLimitOf } from "@gerege-systems/eid-mongolia-sdk";
+
+// гэрчилгээ олголт (TOKEN_ISSUE эрх) — иргэн утсаараа PIN2-оор батална
+const st = await eid.token.issueCertificate({ signerEtsi, csrAuth, csrSign, tokenSerial: "EP2003-0042A1" }); // onBehalfOf алга = хувийн
+// … eid.session.poll(st.sessionId) → result.tokenCertificate?.status === "ISSUED"
+const res = await eid.token.certificateResult(st.sessionId);
+verifyTokenCertificates(res, csrAuth, csrSign); // гэрчилгээ бүр CSR-ийн түлхүүртэй
+// 409 TOKEN_LIMIT_REACHED → tokenLimitOf(err): { kind, limit, organization? }
+
+// токеноор нэвтрэх (AUTH эрх)
+const ch = await eid.token.authChallenge();
+const digest = tokenAuthDigest(ch.rpUUID, ch.challenge); // токен CKM_ECDSA → түүхий r||s
+const who = await eid.token.authVerify(ch.challengeId, authCertDer, rs);
+```
+
 ## 4. QR ба ижил төхөөрөмж — device link v3
 
 Иргэн өөр төхөөрөмжийн дэлгэц дээрх **QR**-ийг утсаараа уншина, эсвэл RP-ийн сайт/аппыг eID апптай **ижил
@@ -327,25 +379,32 @@ OK ирж болзошгүй. Иймд `ResponseValidator`:
      `initialCallbackUrl`-ийг хариуны `signature.initialCallbackUrl`-аас авна (CA урсгалаар шийднэ: QR/Notification →
      `""`, Web2App/App2App → таны callback) — зөвхөн `""` эсвэл
      таны илгээсэн callback байхад, Web2App/App2App-д заавал таны callback; өөр утга → татгалзана
-   - **sign** → RP-ийн өгсөн digest дээр
+   - **sign** → RP-ийн өгсөн digest дээр; `expectedFlowType` өгвөл хариуны `flowType` ЯГ таарах (гарын үсэгт ордоггүй — хариуны тулгалт)
    - алгоритм нь гэрчилгээний түлхүүртэй уях: `ecdsa-with-SHA256` зөвхөн EC P-256 түлхүүрт, RSA алгоритмууд зөвхөн
      RSA түлхүүрт (alg confusion хаалт). Hash нь үргэлж хүссэнтэй ЯГ тэнцүү. RP-API session-ий гарын үсэг CA дээр
      SplitKey RSA (одоогийн бүх мобайл гэрчилгээ) эсвэл legacy threshold ECDSA P-256-аас гарна; ECDSA credential
      зөвхөн SHA-256 digest зурдаг (өөр hash хүссэн session-д сервер гарын үсэг гаргахгүй), тиймээс SHA-384/512
      хүссэн session-д `ecdsa-with-SHA256` хариу ирвэл хуурамч гэж татгалзана.
 
-Аль нэг алхам бүтэлгүйтвэл `ValidationError` шиднэ — хариунд **итгэхгүй**.
+5. Цуцлалт — `trust.revocation` (OCSP/CRL hook) → `checkRevocation`, эсвэл `checkRevocationStatus` (`"good"` /
+   `"unchecked"` (soft-fail) / `"skipped"` (hook алга)).
+6. Нэмэлт (сонголттой): `allowedIssuerSkis: [CITIZEN_ISSUING_CA_SKI]` — зөвхөн иргэний Issuing CA (04)-ийн гэрчилгээ;
+   `checkKeyUsage: true` — auth → clientAuth, sign → nonRepudiation (CA-ийн профайл); `schemeName` — CA-ийн
+   `acsp_scheme_name` (анхдагч `smart-id`).
+
+Аль нэг алхам бүтэлгүйтвэл `ValidationError` шиднэ — хариунд **итгэхгүй**. Алдааны текстэд иргэний нэр, PNOMN, РД
+ордоггүй (`NetworkError.op`-д замыг `/etsi/…` болгоно) — шууд лог руу бичиж болно.
 
 ## Алдааны төрлүүд
 
 | Алдаа | Утга |
 |---|---|
-| `AuthenticationError` | 401 — API secret буруу/байхгүй |
+| `AuthenticationError` | 401 — API secret буруу/байхгүй; CA-ийн JSON бол `.serverMessage` (+ `.code`), proxy-ийнх бол алга (`.body`, `.headers`) |
 | `ForbiddenError` | 403 — IP allowlist / mTLS / RP-ийн эрх; onBehalfOf татгалзвал `.code` (`OnBehalfErrorCode`) |
 | `SessionFailedError` | endResult ≠ OK (TIMEOUT, USER_REFUSED…) — `.endResult`-оор салга |
 | `ValidationError` | cert chain/signature/level шалгалт бүтэлгүйтсэн |
-| `ApiError` | бусад HTTP алдаа (`.status`, `.body`, серверийн `.code` — ж: 404 `ORG_NOT_FOUND`) |
-| `NetworkError` | timeout/сүлжээ |
+| `ApiError` | бусад HTTP алдаа (`.status`, `.body`, серверийн `.code`, `.retryAfterMs`, `.headers`, `.retryable` — ж: 404 `ORG_NOT_FOUND`) |
+| `NetworkError` | timeout/сүлжээ (`.op` — таних тэмдэггүй зам, `.timeout`) |
 | `EidOidcError` | «eID-ээр нэвтрэх» (OIDC) — `.code`: `access_denied`, `login_required`, `state_mismatch`, `invalid_grant`, `invalid_id_token`, `server_error` … |
 | `DeviceLinkError` | device-link холбоос угсрах боломжгүй (`deviceLinkBase` https биш, token/secret/lang хэлбэр, төрөлд хэрэгтэй талбар дутуу) |
 
@@ -366,3 +425,16 @@ npm install
 npm run lint   # tsc --noEmit
 npm test       # build + node --test
 ```
+
+### Гэрээний шалгалт
+
+SDK-ийн дууддаг RP-API зам бүр (`src/contract.ts`) live [`/.well-known/eid`](https://rp.eidmongolia.mn/.well-known/eid)-ийн
+`endpoints`-д байх ёстой; OIDC-ийн хүлээдэг утгууд (issuer, `ES256`, PKCE `S256`, `client_secret_basic`, `EidIdTokenClaims`-ийн
+талбарууд) [discovery](https://login.eidmongolia.mn/.well-known/openid-configuration)-тэй таарах ёстой. Discovery-д
+байгаа ч SDK хамраагүй замууд WARN (fail биш). Сүлжээ шаарддаг тул `npm test`-д ордоггүй:
+
+```bash
+npm run test:contract
+```
+
+CI: `.github/workflows/contract.yml` — PR, `main` push, өдөр бүр 00:00 UTC, гараар.

package/dist/{browser-B_XtyuFG.d.cts → browser-BWCDj8xO.d.cts}

@@ -135,6 +135,46 @@ interface SessionResult {
      * угсарсан объект). {@link PdfSessionBlock}.
      */
     pdf?: PdfSessionBlock | null;
+    /**
+     * COMPLETE+OK auth session-ий `person` блок (CA бүртгэлээс: кирилл нэр, төрсөн огноо, хүйс — гэрчилгээнд байдаггүй).
+     * Зөвхөн session эзэмшигч RP-д; CA иргэнийг олоогүй бол null. ГАРЫН ҮСЭГТ ОРДОГГҮЙ — validateAuth-ийн дараа
+     * {@link personMatchesCertificate}-ээр гэрчилгээний SERIALNUMBER (`PNOMN-<civilId>`)-тэй тулгаж л хэрэглэнэ.
+     */
+    person?: PersonBlock | null;
+    /** USB токены гэрчилгээ олголтын session-ий `tokenCertificate` блок (`token.issueCertificate`); бусад урсгалд null. */
+    tokenCertificate?: TokenCertSessionBlock | null;
+    /** Серверийн хариуны түүхий JSON (`parseSessionResult`-ийн оролт) — SDK задлаагүй талбарт. */
+    raw?: unknown;
+}
+/**
+ * Session-ий `person` блок (CA `dto.PersonBlock`). Нэршил core.gerege.mn-тэй нэг мөр — гурван нэр ӨӨР ойлголт:
+ * `firstName` = нэр, `lastName` = ЭЦГИЙН нэр (гэрчилгээнд ордог), `familyName` = УРГИЙН овог (гэрчилгээнд ОРОХГҮЙ).
+ * Мэдэгдэхгүй талбар undefined — RP заавал байх талбар гэж үзэхгүй.
+ */
+interface PersonBlock {
+    firstName?: string;
+    lastName?: string;
+    familyName?: string;
+    firstNameEn?: string;
+    lastNameEn?: string;
+    civilId?: string;
+    regNo?: string;
+    /** YYYY-MM-DD (цаг/бүсгүй). */
+    birthDate?: string;
+    /** M | F | X. */
+    gender?: string;
+    /** core.gerege.mn-ий дотоод дугаар; байхгүй = тулгагдаагүй. */
+    geID?: number;
+}
+/** Токены гэрчилгээ олголтын төлөв. */
+type TokenCertStatus = "PENDING" | "ISSUED" | "FAILED" | "EXPIRED";
+/** GET /session/{id}-ийн `tokenCertificate` (TOKEN_CERT §Төлөв). */
+interface TokenCertSessionBlock {
+    status: TokenCertStatus | string;
+    /** FAILED үед: endResult (USER_REFUSED, TIMEOUT …) эсвэл CSR_DIGEST_MISMATCH, TOKEN_LIMIT_REACHED г.м. */
+    errorCode?: string;
+    authSerialHex?: string;
+    signSerialHex?: string;
 }
 /** PDF баримтын төлөв: PENDING → READY (эсвэл FAILED / EXPIRED). */
 type PdfDocumentStatus = "PENDING" | "READY" | "FAILED" | "EXPIRED";
@@ -259,8 +299,32 @@ declare function openOrShowQR(session: DeviceLinkInput, opts: OpenOrShowQROption
 declare class EidError extends Error {
     constructor(message: string);
 }
-/** HTTP 401 — API secret буруу/байхгүй. Тохиргооны (RP secret) алдаа. */
+/** HTTP хариуны нэмэлт мэдээлэл (алдааны төрлүүдэд). */
+interface HttpErrorInit {
+    /** Хариуны header-ууд. */
+    headers?: Headers;
+    /** Retry-After (секунд эсвэл HTTP-огноо задалсан), мс; байхгүй/буруу бол undefined. */
+    retryAfterMs?: number;
+}
+/**
+ * HTTP 401 — API secret буруу/байхгүй. Тохиргооны (RP secret) алдаа. CA-ийн өөрийн 401 нь JSON `{"error"[,"code"]}` —
+ * `serverMessage` (ба байвал `code`) бөглөгдөнө; JSON биш (proxy / nginx) бол хоёул undefined — үүгээр CA-ийн 401-ийг
+ * proxy-ийнхоос ялгана.
+ */
 declare class AuthenticationError extends EidError {
+    /** Серверийн `{"code"}`; байхгүй / JSON биш (proxy) бол undefined. */
+    readonly code?: string;
+    /** Серверийн `{"error"}` текст (логт); JSON биш (proxy) бол undefined. */
+    readonly serverMessage?: string;
+    /** Хариуны бие (таслагдаагүй текст). */
+    readonly body?: string;
+    readonly headers?: Headers;
+    constructor(message: string, init?: {
+        code?: string;
+        serverMessage?: string;
+        body?: string;
+        headers?: Headers;
+    });
 }
 /**
  * HTTP 403 — IP allowlist/mTLS зөвшөөрөөгүй, RP-д эрх алга, эсвэл onBehalfOf-ийн төлөөлөл татгалзсан.
@@ -269,9 +333,12 @@ declare class AuthenticationError extends EidError {
 declare class ForbiddenError extends EidError {
     /** Серверийн тогтвортой алдааны код (`{"code"}`), байхгүй бол undefined. */
     readonly code?: string | undefined;
+    readonly headers?: Headers;
+    /** Retry-After (мс), байхгүй бол undefined. */
+    readonly retryAfterMs?: number;
     constructor(message: string, 
     /** Серверийн тогтвортой алдааны код (`{"code"}`), байхгүй бол undefined. */
-    code?: string | undefined);
+    code?: string | undefined, init?: HttpErrorInit);
 }
 /** RP-API-аас ирсэн бусад HTTP алдаа (4xx/5xx). status ба хариуны биеийг агуулна. */
 declare class ApiError extends EidError {
@@ -279,10 +346,31 @@ declare class ApiError extends EidError {
     readonly body: string;
     /** Серверийн тогтвортой алдааны код (`{"error","code"}`-ийн `code`), байхгүй бол undefined. */
     readonly code?: string | undefined;
+    readonly headers?: Headers;
+    /**
+     * Retry-After (мс, секунд эсвэл HTTP-огноо задалсан); байхгүй/буруу бол undefined. CA түр алдаанд (429
+     * PDF_PREPARE_BUSY / RATE_LIMITED, 503 DOCUMENT_PENDING / TSA_UNAVAILABLE / LTV_UNAVAILABLE г.м.) тавина.
+     */
+    readonly retryAfterMs?: number;
     constructor(status: number, body: string, 
     /** Серверийн тогтвортой алдааны код (`{"error","code"}`-ийн `code`), байхгүй бол undefined. */
-    code?: string | undefined);
+    code?: string | undefined, init?: HttpErrorInit);
+    /**
+     * CA-ийн түр алдаа ({@link RETRYABLE_ERROR_CODES}-ийн нэг, эсвэл 429/503 + Retry-After): `retryAfterMs`-ийн дараа
+     * ижил хүсэлтийг давтаж болно.
+     */
+    get retryable(): boolean;
 }
+/**
+ * CA-ийн түр (давтаж болох) алдааны кодууд — `ApiError.code`. PDF_PREPARE_BUSY (429 prepare, Retry-After 5),
+ * DOCUMENT_PENDING (503 document, 5), TSA_UNAVAILABLE (503, 30), LTV_UNAVAILABLE (503, 60), RATE_LIMITED (429 токен),
+ * STATE_UNAVAILABLE (503 токен), ISSUANCE_PENDING (503 токены үр дүн, 5).
+ */
+type RetryableErrorCode = "PDF_PREPARE_BUSY" | "DOCUMENT_PENDING" | "TSA_UNAVAILABLE" | "LTV_UNAVAILABLE" | "RATE_LIMITED" | "STATE_UNAVAILABLE" | "ISSUANCE_PENDING";
+/** {@link RetryableErrorCode}-ийн бүх утга. */
+declare const RETRYABLE_ERROR_CODES: readonly RetryableErrorCode[];
+/** RFC 9110 §10.2.3: delay-seconds эсвэл HTTP-date → мс. Буруу / өнгөрсөн / 24 цагаас их → undefined. */
+declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
 /**
  * Байгууллагын нэрийн өмнөөс (`onBehalfOf`) урсгалын татгалзлын кодууд — `ForbiddenError.code` /
  * `ApiError.code`-д ирнэ. 403: REPRESENTATION_DENIED (идэвхтэй төлөөлөгч биш), REPRESENTATION_PENDING (PIN2-оор
@@ -293,8 +381,19 @@ declare class ApiError extends EidError {
 type OnBehalfErrorCode = "REPRESENTATION_DENIED" | "REPRESENTATION_PENDING" | "REPRESENTATION_EXPIRED" | "ORG_NOT_ACTIVE" | "SIGNER_UNIDENTIFIED" | "ORG_NOT_FOUND" | "REPRESENTATION_REVOKED";
 /** {@link OnBehalfErrorCode}-ийн бүх утга (runtime шалгалтад). */
 declare const ON_BEHALF_ERROR_CODES: readonly OnBehalfErrorCode[];
-/** Сүлжээ/timeout — upstream хариу өгсөнгүй. */
+/**
+ * Сүлжээ/timeout — upstream хариу өгсөнгүй. Мессеж ба `op`-д хувь хүний таних тэмдэг ОРОХГҮЙ (замын `/etsi/{…}`,
+ * `/document/{…}` → `…`) — шууд лог руу бичиж болно.
+ */
 declare class NetworkError extends EidError {
+    /** "GET /session/…" (таних тэмдэг хасагдсан зам). */
+    readonly op?: string;
+    /** Хүсэлт хугацаа хэтэрсэн. */
+    readonly timeout?: boolean;
+    constructor(message: string, init?: {
+        op?: string;
+        timeout?: boolean;
+    });
 }
 /**
  * Session амжилтгүй дууссан (endResult ≠ OK): TIMEOUT, USER_REFUSED*, DOCUMENT_UNUSABLE гм.
@@ -318,4 +417,4 @@ declare class ValidationError extends EidError {
 declare class DeviceLinkError extends EidError {
 }
 
-export { type AcspContext as A, type CertificateLevel as C, type DeviceLinkSession as D, EidError as E, type FlowType as F, type HashAlgorithm as H, type Interaction as I, type NotificationSession as N, ON_BEHALF_ERROR_CODES as O, type PdfSessionBlock as P, type RpCredentials as R, type SignatureAlgorithm as S, ValidationError as V, type SessionResult as a, type RepresentationsResponse as b, ApiError as c, AuthenticationError as d, DeviceLinkError as e, type DeviceLinkInput as f, type EndResult as g, ForbiddenError as h, type NavigatorLike as i, NetworkError as j, type OnBehalfErrorCode as k, type OpenOrShowQROptions as l, type OrgResult as m, type PdfDocumentStatus as n, type PdfSigner as o, type Representation as p, SessionFailedError as q, type SessionState as r, type SignatureAlgorithmParameters as s, type SignatureProtocol as t, deviceLink as u, isMobileUserAgent as v, openOrShowQR as w };
+export { type AcspContext as A, isMobileUserAgent as B, type CertificateLevel as C, type DeviceLinkSession as D, EidError as E, type FlowType as F, openOrShowQR as G, type HashAlgorithm as H, type Interaction as I, parseRetryAfter as J, type NotificationSession as N, ON_BEHALF_ERROR_CODES as O, type PersonBlock as P, type RpCredentials as R, type SignatureAlgorithm as S, type TokenCertSessionBlock as T, ValidationError as V, type SessionResult as a, type PdfSessionBlock as b, type RepresentationsResponse as c, ApiError as d, AuthenticationError as e, DeviceLinkError as f, type DeviceLinkInput as g, type EndResult as h, ForbiddenError as i, type HttpErrorInit as j, type NavigatorLike as k, NetworkError as l, type OnBehalfErrorCode as m, type OpenOrShowQROptions as n, type OrgResult as o, type PdfDocumentStatus as p, type PdfSigner as q, RETRYABLE_ERROR_CODES as r, type Representation as s, type RetryableErrorCode as t, SessionFailedError as u, type SessionState as v, type SignatureAlgorithmParameters as w, type SignatureProtocol as x, type TokenCertStatus as y, deviceLink as z };

package/dist/{browser-B_XtyuFG.d.ts → browser-BWCDj8xO.d.ts}

@@ -135,6 +135,46 @@ interface SessionResult {
      * угсарсан объект). {@link PdfSessionBlock}.
      */
     pdf?: PdfSessionBlock | null;
+    /**
+     * COMPLETE+OK auth session-ий `person` блок (CA бүртгэлээс: кирилл нэр, төрсөн огноо, хүйс — гэрчилгээнд байдаггүй).
+     * Зөвхөн session эзэмшигч RP-д; CA иргэнийг олоогүй бол null. ГАРЫН ҮСЭГТ ОРДОГГҮЙ — validateAuth-ийн дараа
+     * {@link personMatchesCertificate}-ээр гэрчилгээний SERIALNUMBER (`PNOMN-<civilId>`)-тэй тулгаж л хэрэглэнэ.
+     */
+    person?: PersonBlock | null;
+    /** USB токены гэрчилгээ олголтын session-ий `tokenCertificate` блок (`token.issueCertificate`); бусад урсгалд null. */
+    tokenCertificate?: TokenCertSessionBlock | null;
+    /** Серверийн хариуны түүхий JSON (`parseSessionResult`-ийн оролт) — SDK задлаагүй талбарт. */
+    raw?: unknown;
+}
+/**
+ * Session-ий `person` блок (CA `dto.PersonBlock`). Нэршил core.gerege.mn-тэй нэг мөр — гурван нэр ӨӨР ойлголт:
+ * `firstName` = нэр, `lastName` = ЭЦГИЙН нэр (гэрчилгээнд ордог), `familyName` = УРГИЙН овог (гэрчилгээнд ОРОХГҮЙ).
+ * Мэдэгдэхгүй талбар undefined — RP заавал байх талбар гэж үзэхгүй.
+ */
+interface PersonBlock {
+    firstName?: string;
+    lastName?: string;
+    familyName?: string;
+    firstNameEn?: string;
+    lastNameEn?: string;
+    civilId?: string;
+    regNo?: string;
+    /** YYYY-MM-DD (цаг/бүсгүй). */
+    birthDate?: string;
+    /** M | F | X. */
+    gender?: string;
+    /** core.gerege.mn-ий дотоод дугаар; байхгүй = тулгагдаагүй. */
+    geID?: number;
+}
+/** Токены гэрчилгээ олголтын төлөв. */
+type TokenCertStatus = "PENDING" | "ISSUED" | "FAILED" | "EXPIRED";
+/** GET /session/{id}-ийн `tokenCertificate` (TOKEN_CERT §Төлөв). */
+interface TokenCertSessionBlock {
+    status: TokenCertStatus | string;
+    /** FAILED үед: endResult (USER_REFUSED, TIMEOUT …) эсвэл CSR_DIGEST_MISMATCH, TOKEN_LIMIT_REACHED г.м. */
+    errorCode?: string;
+    authSerialHex?: string;
+    signSerialHex?: string;
 }
 /** PDF баримтын төлөв: PENDING → READY (эсвэл FAILED / EXPIRED). */
 type PdfDocumentStatus = "PENDING" | "READY" | "FAILED" | "EXPIRED";
@@ -259,8 +299,32 @@ declare function openOrShowQR(session: DeviceLinkInput, opts: OpenOrShowQROption
 declare class EidError extends Error {
     constructor(message: string);
 }
-/** HTTP 401 — API secret буруу/байхгүй. Тохиргооны (RP secret) алдаа. */
+/** HTTP хариуны нэмэлт мэдээлэл (алдааны төрлүүдэд). */
+interface HttpErrorInit {
+    /** Хариуны header-ууд. */
+    headers?: Headers;
+    /** Retry-After (секунд эсвэл HTTP-огноо задалсан), мс; байхгүй/буруу бол undefined. */
+    retryAfterMs?: number;
+}
+/**
+ * HTTP 401 — API secret буруу/байхгүй. Тохиргооны (RP secret) алдаа. CA-ийн өөрийн 401 нь JSON `{"error"[,"code"]}` —
+ * `serverMessage` (ба байвал `code`) бөглөгдөнө; JSON биш (proxy / nginx) бол хоёул undefined — үүгээр CA-ийн 401-ийг
+ * proxy-ийнхоос ялгана.
+ */
 declare class AuthenticationError extends EidError {
+    /** Серверийн `{"code"}`; байхгүй / JSON биш (proxy) бол undefined. */
+    readonly code?: string;
+    /** Серверийн `{"error"}` текст (логт); JSON биш (proxy) бол undefined. */
+    readonly serverMessage?: string;
+    /** Хариуны бие (таслагдаагүй текст). */
+    readonly body?: string;
+    readonly headers?: Headers;
+    constructor(message: string, init?: {
+        code?: string;
+        serverMessage?: string;
+        body?: string;
+        headers?: Headers;
+    });
 }
 /**
  * HTTP 403 — IP allowlist/mTLS зөвшөөрөөгүй, RP-д эрх алга, эсвэл onBehalfOf-ийн төлөөлөл татгалзсан.
@@ -269,9 +333,12 @@ declare class AuthenticationError extends EidError {
 declare class ForbiddenError extends EidError {
     /** Серверийн тогтвортой алдааны код (`{"code"}`), байхгүй бол undefined. */
     readonly code?: string | undefined;
+    readonly headers?: Headers;
+    /** Retry-After (мс), байхгүй бол undefined. */
+    readonly retryAfterMs?: number;
     constructor(message: string, 
     /** Серверийн тогтвортой алдааны код (`{"code"}`), байхгүй бол undefined. */
-    code?: string | undefined);
+    code?: string | undefined, init?: HttpErrorInit);
 }
 /** RP-API-аас ирсэн бусад HTTP алдаа (4xx/5xx). status ба хариуны биеийг агуулна. */
 declare class ApiError extends EidError {
@@ -279,10 +346,31 @@ declare class ApiError extends EidError {
     readonly body: string;
     /** Серверийн тогтвортой алдааны код (`{"error","code"}`-ийн `code`), байхгүй бол undefined. */
     readonly code?: string | undefined;
+    readonly headers?: Headers;
+    /**
+     * Retry-After (мс, секунд эсвэл HTTP-огноо задалсан); байхгүй/буруу бол undefined. CA түр алдаанд (429
+     * PDF_PREPARE_BUSY / RATE_LIMITED, 503 DOCUMENT_PENDING / TSA_UNAVAILABLE / LTV_UNAVAILABLE г.м.) тавина.
+     */
+    readonly retryAfterMs?: number;
     constructor(status: number, body: string, 
     /** Серверийн тогтвортой алдааны код (`{"error","code"}`-ийн `code`), байхгүй бол undefined. */
-    code?: string | undefined);
+    code?: string | undefined, init?: HttpErrorInit);
+    /**
+     * CA-ийн түр алдаа ({@link RETRYABLE_ERROR_CODES}-ийн нэг, эсвэл 429/503 + Retry-After): `retryAfterMs`-ийн дараа
+     * ижил хүсэлтийг давтаж болно.
+     */
+    get retryable(): boolean;
 }
+/**
+ * CA-ийн түр (давтаж болох) алдааны кодууд — `ApiError.code`. PDF_PREPARE_BUSY (429 prepare, Retry-After 5),
+ * DOCUMENT_PENDING (503 document, 5), TSA_UNAVAILABLE (503, 30), LTV_UNAVAILABLE (503, 60), RATE_LIMITED (429 токен),
+ * STATE_UNAVAILABLE (503 токен), ISSUANCE_PENDING (503 токены үр дүн, 5).
+ */
+type RetryableErrorCode = "PDF_PREPARE_BUSY" | "DOCUMENT_PENDING" | "TSA_UNAVAILABLE" | "LTV_UNAVAILABLE" | "RATE_LIMITED" | "STATE_UNAVAILABLE" | "ISSUANCE_PENDING";
+/** {@link RetryableErrorCode}-ийн бүх утга. */
+declare const RETRYABLE_ERROR_CODES: readonly RetryableErrorCode[];
+/** RFC 9110 §10.2.3: delay-seconds эсвэл HTTP-date → мс. Буруу / өнгөрсөн / 24 цагаас их → undefined. */
+declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
 /**
  * Байгууллагын нэрийн өмнөөс (`onBehalfOf`) урсгалын татгалзлын кодууд — `ForbiddenError.code` /
  * `ApiError.code`-д ирнэ. 403: REPRESENTATION_DENIED (идэвхтэй төлөөлөгч биш), REPRESENTATION_PENDING (PIN2-оор
@@ -293,8 +381,19 @@ declare class ApiError extends EidError {
 type OnBehalfErrorCode = "REPRESENTATION_DENIED" | "REPRESENTATION_PENDING" | "REPRESENTATION_EXPIRED" | "ORG_NOT_ACTIVE" | "SIGNER_UNIDENTIFIED" | "ORG_NOT_FOUND" | "REPRESENTATION_REVOKED";
 /** {@link OnBehalfErrorCode}-ийн бүх утга (runtime шалгалтад). */
 declare const ON_BEHALF_ERROR_CODES: readonly OnBehalfErrorCode[];
-/** Сүлжээ/timeout — upstream хариу өгсөнгүй. */
+/**
+ * Сүлжээ/timeout — upstream хариу өгсөнгүй. Мессеж ба `op`-д хувь хүний таних тэмдэг ОРОХГҮЙ (замын `/etsi/{…}`,
+ * `/document/{…}` → `…`) — шууд лог руу бичиж болно.
+ */
 declare class NetworkError extends EidError {
+    /** "GET /session/…" (таних тэмдэг хасагдсан зам). */
+    readonly op?: string;
+    /** Хүсэлт хугацаа хэтэрсэн. */
+    readonly timeout?: boolean;
+    constructor(message: string, init?: {
+        op?: string;
+        timeout?: boolean;
+    });
 }
 /**
  * Session амжилтгүй дууссан (endResult ≠ OK): TIMEOUT, USER_REFUSED*, DOCUMENT_UNUSABLE гм.
@@ -318,4 +417,4 @@ declare class ValidationError extends EidError {
 declare class DeviceLinkError extends EidError {
 }
 
-export { type AcspContext as A, type CertificateLevel as C, type DeviceLinkSession as D, EidError as E, type FlowType as F, type HashAlgorithm as H, type Interaction as I, type NotificationSession as N, ON_BEHALF_ERROR_CODES as O, type PdfSessionBlock as P, type RpCredentials as R, type SignatureAlgorithm as S, ValidationError as V, type SessionResult as a, type RepresentationsResponse as b, ApiError as c, AuthenticationError as d, DeviceLinkError as e, type DeviceLinkInput as f, type EndResult as g, ForbiddenError as h, type NavigatorLike as i, NetworkError as j, type OnBehalfErrorCode as k, type OpenOrShowQROptions as l, type OrgResult as m, type PdfDocumentStatus as n, type PdfSigner as o, type Representation as p, SessionFailedError as q, type SessionState as r, type SignatureAlgorithmParameters as s, type SignatureProtocol as t, deviceLink as u, isMobileUserAgent as v, openOrShowQR as w };
+export { type AcspContext as A, isMobileUserAgent as B, type CertificateLevel as C, type DeviceLinkSession as D, EidError as E, type FlowType as F, openOrShowQR as G, type HashAlgorithm as H, type Interaction as I, parseRetryAfter as J, type NotificationSession as N, ON_BEHALF_ERROR_CODES as O, type PersonBlock as P, type RpCredentials as R, type SignatureAlgorithm as S, type TokenCertSessionBlock as T, ValidationError as V, type SessionResult as a, type PdfSessionBlock as b, type RepresentationsResponse as c, ApiError as d, AuthenticationError as e, DeviceLinkError as f, type DeviceLinkInput as g, type EndResult as h, ForbiddenError as i, type HttpErrorInit as j, type NavigatorLike as k, NetworkError as l, type OnBehalfErrorCode as m, type OpenOrShowQROptions as n, type OrgResult as o, type PdfDocumentStatus as p, type PdfSigner as q, RETRYABLE_ERROR_CODES as r, type Representation as s, type RetryableErrorCode as t, SessionFailedError as u, type SessionState as v, type SignatureAlgorithmParameters as w, type SignatureProtocol as x, type TokenCertStatus as y, deviceLink as z };

package/dist/browser.d.cts

@@ -1 +1 @@
-export { e as DeviceLinkError, f as DeviceLinkInput, D as DeviceLinkSession, E as EidError, i as NavigatorLike, l as OpenOrShowQROptions, u as deviceLink, v as isMobileUserAgent, w as openOrShowQR } from './browser-B_XtyuFG.cjs';
+export { f as DeviceLinkError, g as DeviceLinkInput, D as DeviceLinkSession, E as EidError, k as NavigatorLike, n as OpenOrShowQROptions, z as deviceLink, B as isMobileUserAgent, G as openOrShowQR } from './browser-BWCDj8xO.cjs';

package/dist/browser.d.ts

@@ -1 +1 @@
-export { e as DeviceLinkError, f as DeviceLinkInput, D as DeviceLinkSession, E as EidError, i as NavigatorLike, l as OpenOrShowQROptions, u as deviceLink, v as isMobileUserAgent, w as openOrShowQR } from './browser-B_XtyuFG.js';
+export { f as DeviceLinkError, g as DeviceLinkInput, D as DeviceLinkSession, E as EidError, k as NavigatorLike, n as OpenOrShowQROptions, z as deviceLink, B as isMobileUserAgent, G as openOrShowQR } from './browser-BWCDj8xO.js';

package/dist/browser.js

@@ -4,7 +4,7 @@ import {
   deviceLink,
   isMobileUserAgent,
   openOrShowQR
-} from "./chunk-NXDKQZIW.js";
+} from "./chunk-YDVPZMAL.js";
 export {
   DeviceLinkError,
   EidError,

package/dist/{chunk-NXDKQZIW.js → chunk-YDVPZMAL.js}

@@ -6,25 +6,79 @@ var EidError = class extends Error {
   }
 };
 var AuthenticationError = class extends EidError {
+  /** Серверийн `{"code"}`; байхгүй / JSON биш (proxy) бол undefined. */
+  code;
+  /** Серверийн `{"error"}` текст (логт); JSON биш (proxy) бол undefined. */
+  serverMessage;
+  /** Хариуны бие (таслагдаагүй текст). */
+  body;
+  headers;
+  constructor(message, init) {
+    super(message);
+    this.code = init?.code;
+    this.serverMessage = init?.serverMessage;
+    this.body = init?.body;
+    this.headers = init?.headers;
+  }
 };
 var ForbiddenError = class extends EidError {
-  constructor(message, code) {
+  constructor(message, code, init) {
     super(message);
     this.code = code;
+    this.headers = init?.headers;
+    this.retryAfterMs = init?.retryAfterMs;
   }
   code;
+  headers;
+  /** Retry-After (мс), байхгүй бол undefined. */
+  retryAfterMs;
 };
 var ApiError = class extends EidError {
-  constructor(status, body, code) {
+  constructor(status, body, code, init) {
     super(`RP-API ${status}: ${body}`);
     this.status = status;
     this.body = body;
     this.code = code;
+    this.headers = init?.headers;
+    this.retryAfterMs = init?.retryAfterMs;
   }
   status;
   body;
   code;
+  headers;
+  /**
+   * Retry-After (мс, секунд эсвэл HTTP-огноо задалсан); байхгүй/буруу бол undefined. CA түр алдаанд (429
+   * PDF_PREPARE_BUSY / RATE_LIMITED, 503 DOCUMENT_PENDING / TSA_UNAVAILABLE / LTV_UNAVAILABLE г.м.) тавина.
+   */
+  retryAfterMs;
+  /**
+   * CA-ийн түр алдаа ({@link RETRYABLE_ERROR_CODES}-ийн нэг, эсвэл 429/503 + Retry-After): `retryAfterMs`-ийн дараа
+   * ижил хүсэлтийг давтаж болно.
+   */
+  get retryable() {
+    if (this.code && RETRYABLE_ERROR_CODES.includes(this.code)) return true;
+    return (this.status === 429 || this.status === 503) && (this.retryAfterMs ?? 0) > 0;
+  }
 };
+var RETRYABLE_ERROR_CODES = [
+  "PDF_PREPARE_BUSY",
+  "DOCUMENT_PENDING",
+  "TSA_UNAVAILABLE",
+  "LTV_UNAVAILABLE",
+  "RATE_LIMITED",
+  "STATE_UNAVAILABLE",
+  "ISSUANCE_PENDING"
+];
+function parseRetryAfter(value, now = Date.now()) {
+  const v = (value ?? "").trim();
+  if (!v) return void 0;
+  if (/^-?\d+$/.test(v)) {
+    const n = Number(v);
+    return n > 0 && n <= 86400 ? n * 1e3 : void 0;
+  }
+  const t = Date.parse(v);
+  return Number.isNaN(t) || t <= now ? void 0 : t - now;
+}
 var ON_BEHALF_ERROR_CODES = [
   "REPRESENTATION_DENIED",
   "REPRESENTATION_PENDING",
@@ -35,7 +89,19 @@ var ON_BEHALF_ERROR_CODES = [
   "REPRESENTATION_REVOKED"
 ];
 var NetworkError = class extends EidError {
+  /** "GET /session/…" (таних тэмдэг хасагдсан зам). */
+  op;
+  /** Хүсэлт хугацаа хэтэрсэн. */
+  timeout;
+  constructor(message, init) {
+    super(message);
+    this.op = init?.op;
+    this.timeout = init?.timeout;
+  }
 };
+function maskPath(path) {
+  return path.split(/[?#]/)[0].replace(/\/(etsi|document)\/[^/?#\s]+/g, "/$1/\u2026");
+}
 var SessionFailedError = class extends EidError {
   constructor(endResult) {
     super(`Session \u0430\u043C\u0436\u0438\u043B\u0442\u0433\u04AF\u0439: ${endResult}`);
@@ -95,8 +161,11 @@ export {
   AuthenticationError,
   ForbiddenError,
   ApiError,
+  RETRYABLE_ERROR_CODES,
+  parseRetryAfter,
   ON_BEHALF_ERROR_CODES,
   NetworkError,
+  maskPath,
   SessionFailedError,
   ValidationError,
   DeviceLinkError,