@gerege-systems/eid-mongolia-sdk 0.14.1 → 0.15.0

package/README.md

@@ -7,7 +7,8 @@ RP-API v3, Smart-ID нийцтэй. Бүрэн баримт: <https://developer.
 > ⚠️ SDK **backend**-д ажиллана: бүх дуудлага API secret (`rp_sk_…`)-ээр баталгаажна, secret-ийг браузер/гар утсанд
 > хэзээ ч задлахгүй. Браузерт зөвхөн таны backend-ийн өгсөн холбоос/QR/товч харагдана — «eID-ээр нэвтрэх» товч
 > (`/button`) ч таны backend-ийг л дуудна (§1a). `@gerege-systems/eid-mongolia-sdk/browser`-ийн legacy device-link
-> туслахууд 2026-10-07-оос ажиллахгүй (§4).
+> туслахууд 2026-10-07-оос ажиллахгүй (§4). Үл хамаарах: `@gerege-systems/eid-mongolia-sdk/pades` (клиент талын PDF
+> гарын үсэг, secret-гүй) хөтөч болон Node-д ажиллана (§3d).
 
 ## Суулгах
 
@@ -15,7 +16,8 @@ RP-API v3, Smart-ID нийцтэй. Бүрэн баримт: <https://developer.
 npm install @gerege-systems/eid-mongolia-sdk
 ```
 
-Node.js ≥ 22 (global `fetch`, `node:crypto`).
+Node.js ≥ 18 (global `fetch`, `node:crypto`) — бүх entry (`.`, `/browser`, `/button`, `/pades`), CI-д Node 18 / 20 / 22-оор шалгагдана.
+`/pades` мөн орчин үеийн хөтөчид (Web Crypto) ажиллана.
 
 ## 1. RP бүртгүүлэх
 
@@ -235,7 +237,7 @@ UTF8String/PrintableString/BMPString. `parseSubject` нь зөвхөн задл
 > жагсаалтаар ирдэг; Smart-ID ба eID-д Notification төрлийн device link **байхгүй** (CA `docs/DEVICE_LINK_V3.md` §3).
 > Хуучин `/dl?sessionId&vc` холбоос (`deviceLink`) push session-д ч юу ч өгөхгүй (сервер `DEVICE_LINK_REQUIRED`).
 > Иргэн RP-ийг eID апптай ижил утсан дээр нээсэн бол push-ийн оронд **device-link Web2App** урсгал хэрэглэ
-> (`auth.deviceLink*` / `pdf.prepare({ flow: "device-link" })` + `buildDeviceLink(…, "Web2App")`, §4) — товч аппыг шууд
+> (`auth.deviceLink*` / `signPdfDigest({ flow: "device-link" })` + `buildDeviceLink(…, "Web2App")`, §4) — товч аппыг шууд
 > нээж, callback-аар буцна. Push-д «eID аппаа нээнэ үү» гэсэн текст л хангалттай.
 
 ## 3. Гарын үсэг (qualified signature)
@@ -272,10 +274,16 @@ RAW_DIGEST_SIGNATURE-д `flowType` гарын үсэгт ордоггүй (зө
 холбоосыг backend-д `buildDeviceLink(deviceLinkInput(s, "QR", "mon"))` (auth/cert session-д ч мөн). `s.sign`
 (`SignContext`: digest, hash, алгоритм, interactions, callback)-ийг session-тэй хамт серверт хадгал.
 
-**`expiresAt`** (ms epoch) — sign / certificate-choice session-ий *тооцоолсон* дуусах мөч: CA session start хариунд
-хугацаа буцаадаггүй (зөвхөн `sessionID`), CA-ийн анхдагч 600с (`DEFAULT_SIGN_SESSION_TTL_MS`; CA админ 60–1800с болгож
-болно → `signSessionTtlMs`). Хүсэлтээс өмнөх цагаас тооцдог тул CA-ийнхаас хойно хэзээ ч биш; эцсийн үнэн нь
-`GET /session` (`TIMEOUT`).
+**`expiresAt`** (ms epoch) — session дуусах мөч: CA-ийн session start хариуны `expiresAt` (RFC 3339; auth / sign /
+certificate-choice бүгдэд, 2026-10-14-өөс). Хуучин CA (талбаргүй) үед sign / certificate-choice-д SDK тооцоолно — CA-ийн
+анхдагч 600с (`DEFAULT_SIGN_SESSION_TTL_MS`; CA админ 60–1800с болгож болно → `signSessionTtlMs`), auth-д undefined.
+Эцсийн үнэн нь `GET /session` (`TIMEOUT`).
+
+**Session эхлэх алдаа** (`ApiError`-ийн дэд анги, `.code`-той): `NoSigningCertificateError` — 409
+`NO_SIGNING_CERTIFICATE` (sign / certificate-choice start, `/pdf/sign/prepare`: иргэнд идэвхтэй төхөөрөмж / хүчинтэй
+гарын үсгийн гэрчилгээ алга, session үүсээгүй); `CertChoiceInvalidError` — 409 `CERT_CHOICE_INVALID` (linked sign-ийн
+certificate-choice хүчингүй / хуучирсан / ашиглагдсан → cert-choice-ийг дахин эхлүүл); `RequestInvalidError` — 400
+`REQUEST_INVALID` (ж: linked-д `linkedSessionID` дутуу).
 
 ### 3.1. Гэрчилгээг урьдчилж мэдэх (client-side PAdES / CMS)
 
@@ -318,42 +326,22 @@ const { representations } = await eid.organization.getRepresentations("PNOMN-123
 // → [{ orgEtsi: "NTRMN-6235972", orgName: "Гэрэгэ Системс ХХК", role: "ceo", roleLabel: "Гүйцэтгэх захирал",
 //      rightType: "ADMIN", rightTypeLabel: "Админ", source: "REGISTRY", sourceLabel: "Улсын бүртгэл", … }]
 
-// 2. PDF (PAdES, CA угсарна) — санал болгох урсгал.
+// 2. PDF: §3d (клиент талын PAdES) — signPdfDigest({ …, onBehalfOf }) + prepare({ claimedRole: rep.claimedRole }).
+// 3. Raw digest гарын үсэг: eid.sign.digestByEtsi(id, digest, interactions, { onBehalfOf: "NTRMN-6235972" })
+//    — CMS-ийг та угсардаг тул мэдүүлсэн үүргийг (signer-attributes-v2) өөрөө нэмнэ.
 try {
-  const s = await eid.pdf.prepare({
-    pdf: pdfBytes, fileName: "Гэрээ №12.pdf",
-    signer: { etsi: "PNOMN-12345678" }, flow: "notification",
-    onBehalfOf: "NTRMN-6235972",
-  });
-  showToUser(s.vc);
-  const r = await eid.session.waitForResult(s.sessionId);
-  // MUST: endResult OK, pdf.documentStatus READY, pdf.signer.onBehalfOf = хүссэн байгууллага,
-  // татсан файлын SHA-256 = pdf.outSha256, validation.indication "valid", ltv true.
-  if (r.pdf?.documentStatus !== "READY" || r.pdf.signer?.onBehalfOf !== "NTRMN-6235972") throw new Error("…");
-  const signed = await eid.pdf.documentVerified(s.sessionId, r.pdf); // SHA-256 ≠ pdf.outSha256 → ValidationError
-  console.log(r.pdf.signer.claimedRole); // "Гүйцэтгэх захирал, Гэрэгэ Системс ХХК (NTRMN-6235972)"
+  /* … */
 } catch (e) {
   if ((e instanceof ForbiddenError || e instanceof ApiError) && e.code) {
     // REPRESENTATION_DENIED | REPRESENTATION_PENDING | REPRESENTATION_EXPIRED | ORG_NOT_ACTIVE |
-    // SIGNER_UNIDENTIFIED (403) · ORG_NOT_FOUND (404) · REPRESENTATION_REVOKED (403, document татах үед)
+    // SIGNER_UNIDENTIFIED (403) · ORG_NOT_FOUND (404) · REPRESENTATION_REVOKED (403, бүртгэлийн үед)
   }
   throw e;
 }
-
-// Raw digest гарын үсэгт ч мөн: eid.sign.digestByEtsi(id, digest, interactions, { onBehalfOf: "NTRMN-6235972" })
-// — CMS/PDF-ийг та угсардаг тул мэдүүлсэн үүргийг (signer-attributes-v2) өөрөө нэмнэ.
 ```
 
-`prepare`-ийн хариу `digest` (DTBS, base64) — иргэний зурах 32 байт, push ба device-link хоёуланд (хуучин CA push-д
-`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). `pdf.document` санах ойд `pdfMaxBytes` (анхдагч `DEFAULT_PDF_MAX_BYTES` = 64 MiB)
-хүртэл уншина; хэтэрвэл `ResponseTooLargeError`. JSON хариу 4 MiB-ээс хэтэрвэл мөн `ResponseTooLargeError` (таслахгүй).
+Түр алдаа — `ApiError.retryable` үнэн, `retryAfterMs`-ийн (CA-ийн `Retry-After`, секунд эсвэл огноо) дараа давтана
+(`RETRYABLE_ERROR_CODES`). `headers` — хариуны header. JSON хариу 4 MiB-ээс хэтэрвэл `ResponseTooLargeError` (таслахгүй).
 `getRepresentations`-ийн `raw` — серверийн түүхий JSON.
 
 **Хүнд харуулахдаа `roleLabel` / `rightTypeLabel` / `sourceLabel` ашигла** (representations болон session-ий
@@ -362,9 +350,7 @@ prepare 429 `PDF_PREPARE_BUSY`, 503 `LTV_UNAVAILABLE` / `TSA_UNAVAILABLE`; docum
 машин утга, өөрөө орчуулахгүй. Хэл: `new EidClient({ …, language: "en" })` → дуудлага бүрд `Accept-Language`; анхдагч
 илгээхгүй (сервер mn). Хуучин CA-д эдгээр талбар байхгүй.
 
-Олон талт гэрээ: А байгууллагын гаралтыг өөрчлөлтгүй Б-ийн `prepare`-д (`docID`, өөр `onBehalfOf`) илгээнэ.
-Session-ий `onBehalfOf` блок (`role`/`roleLabel`/`rightType`/`rightTypeLabel`) нь хариу угсрах үеийн бүртгэл; `pdf.signer.onBehalfOf`/`claimedRole`
-нь баримтад бичигдсэн утга.
+Session-ий `onBehalfOf` блок (`role`/`roleLabel`/`rightType`/`rightTypeLabel`) нь хариу угсрах үеийн бүртгэл.
 
 ## 3b. Иргэний PKI самбар (`PKI_READ` эрх)
 
@@ -388,14 +374,111 @@ 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);
 
-// токеноор PDF (PAdES, SIGN эрх) — session/утасгүй; байгууллагын токенд onBehalfOf = тухайн байгууллага
-const p = await eid.pdf.tokenPrepare({ pdf, fileName: "Гэрээ.pdf", signerEtsi, certificate: signCertDer });
-const rs = /* токен (PKCS#11): CKM_ECDSA(p.hashToSign) → түүхий r||s, 64 байт — p.expiresAt хүртэл */ new Uint8Array(64);
-const blk = await eid.pdf.tokenFinalize(p.signingId, rs); // READY; 503 DOCUMENT_PENDING → ижил rs-ийг дахин
-const signed = await eid.pdf.tokenDocument(p.signingId); // SHA-256 = blk.outSha256 тулга
+// токеноор PDF: §3d — prepare() → токен CKM_ECDSA(dtbs) → r||s → complete() → registerSignature() (sessionID-гүй, medium "token")
+```
+
+`/token/auth/*` нь CA-д байгаа ч `/.well-known/eid`-д хараахан жагсаагдаагүй (гэрээний тест WARN).
+
+## 3d. PDF гарын үсэг (PAdES, клиент тал) — `@gerege-systems/eid-mongolia-sdk/pades`
+
+**PDF eID-ийн сервер рүү ОЧИХГҮЙ** (Smart-ID / DigiDoc загвар). Баримтыг таны тал (браузер эсвэл Node) НАТИВ
+TypeScript-ээр (WASM-гүй, Web Crypto) угсарна; CA зөвхөн 32 байт DTBS-д гарын үсгийн session (ердийн
+`RAW_DIGEST_SIGNATURE`) ба CMS-ийн бүртгэлийг хийнэ. Гаралт: PAdES-BASELINE-LT (цагийн тэмдэг tsa.timeserver.mn, OCSP/CRL
+DSS-д), Adobe / EU DSS-д «LTV enabled», баталгаажуулах (QR) хуудастай (mn анхдагч / en). Go reference
+(`eid-mongolia-sdk-go/pades`, профайл `pades-client/1`)-тэй **байт-ижил** — conformance golden-оор CI-д шалгагдана.
+
+| Функц | Хаана | Тайлбар |
+|---|---|---|
+| `prepare(pdf, { signerCert, claimedRole?, verifyPage?, fileName?, lang?, docId?, … })` | браузер / Node | `{ dtbs, digest, docId, state }` — сүлжээгүй |
+| `eid.signPdfDigest({ dtbs, fileName, signer, flow?, onBehalfOf? })` | RP backend | DTBS-д гарын үсгийн session (push эсвэл device-link) |
+| `complete(state, signature)` | браузер / Node | TSA + OCSP/CRL → `{ pdf, cms, docId, outSha256, inSha256, hasPage, pageSha256, … }` |
+| `eid.registerSignature(registrationFromCompleted(done, { fileName, sessionID }))` | RP backend | `POST /pdf/signatures` — `/verify/{docID}` бүртгэл |
+
+`/pades` хөтчийн bundle ~125 KB gzip (Noto Sans фонт asset-тэй, CI-д ≤ 300 KB); үндсэн entry үүнийг агуулахгүй. `/pades` (ба бүх багц) **Node ≥ 18** (CI: 18 / 20 / 22),
+орчин үеийн хөтөч. Браузерийн CSP: `connect-src https://tsa.timeserver.mn https://ocsp.eidmongolia.mn
+https://crl.eidmongolia.mn`. Хөтөчид гэрчилгээний `http://` AIA/CDP-г зөвхөн эдгээр хостод `https://` болгоно; үндэсний
+CA-ийн CRL (`esign.gov.mn`) нь `crl.eidmongolia.mn` толин хуулбараас (бүх платформд). Шалгагч (`verify`) энд
+**байхгүй** — бүрэн криптограф шалгалт Go backend SDK-д; `prepare` нь өмнөх гарын үсгийг «хөнгөн» шалгуураар (бүтэц,
+CMS гарын үсэг, eID олгогч, timestamp, DSS) л шалгана.
+
+**Зурагчийн гэрчилгээ.** `prepare` иргэний SIGN гэрчилгээг (`signingCertificateV2`) шаарддаг тул session-оос ӨМНӨ
+хэрэгтэй — одоогоор `eid.person.certificates(etsi)` (`PKI_READ`; `type: "SIGN"`, `status: "VALID"`, `keyMedium: "MOBILE"`
+мөрийн `certValue` + `documentNumber`). Session-ийг тэр `documentNumber`-ээр эхлүүлнэ — өөр төхөөрөмж зурвал `complete`
+`SIGNATURE_INVALID`.
+
+### Вэб RP (браузер prepare/complete, backend session)
+
+```ts
+// ── браузер ─────────────────────────────────────────────────────────────────────────────
+import { prepare, complete } from "@gerege-systems/eid-mongolia-sdk/pades";
+
+const { signerCert, documentNumber } = await api("/sign/pdf/signer");          // backend: person.certificates
+const p = await prepare(pdfBytes, {
+  signerCert, verifyPage: true, fileName: "Гэрээ №12.pdf",
+  claimedRole, // байгууллагаар бол getRepresentations()-ийн claimedRole ЯГ ХЭВЭЭР
+});
+await idb.put("pades-state", p.state);                                           // хуудас дахин ачаалагдаж болно
+const s = await api("/sign/pdf/start", { dtbs: b64(p.dtbs), documentNumber, fileName: "Гэрээ №12.pdf" });
+showToUser(s.vc);                                                                // эсвэл backend-ийн QR (§4)
+const { signature } = await api(`/sign/pdf/${s.sessionId}/result`);              // backend poll + validateSign
+const done = await complete(p.state, signature);                                 // TSA + OCSP/CRL + DSS
+const { pdf, signerCert: _c, ...meta } = done;                                     // PDF backend рүү очихгүй
+await api(`/sign/pdf/${s.sessionId}/register`, { ...meta, cms: b64(done.cms) });
+download(done.pdf, "Гэрээ №12.pdf");
+
+// ── RP backend (Node) ─────────────────────────────────────────────────────────────────────
+// /sign/pdf/start — sessionSecret (device-link) backend-ээс гарахгүй; s.digest-ийг session-д хадгал.
+const s = await eid.signPdfDigest({
+  dtbs: req.body.dtbs, fileName: req.body.fileName,
+  signer: { documentNumber: req.body.documentNumber }, // эсвэл { etsi }
+  onBehalfOf: "NTRMN-6235972",                         // заавал биш
+});
+store(s.sessionId, { digest: s.digest, fileName: req.body.fileName });
+// /sign/pdf/:id/result
+const r = await eid.session.waitForResult(sessionId);
+const sig = eid.validator.validateSign(r, store.get(sessionId).digest, { expectedFlowType: "Notification" });
+reply({ signature: sig.signatureValueB64 });
+// /sign/pdf/:id/register — CA CMS-ийг өөрөө шалгана (session digest = SHA-256(signedAttrs), cert, claimedRole)
+// registrationFromCompleted: CA dto-той яг ижил бие (hasPage илгээхгүй, pageSha256 зөвхөн хуудастай үед); cms base64 ч болно.
+const reg = await eid.registerSignature(registrationFromCompleted(req.body, {
+  fileName: store.get(sessionId).fileName, sessionID: sessionId, onBehalfOf: "NTRMN-6235972" }));
+reply({ verifyUrl: reg.verifyUrl });
 ```
 
-`/token/auth/*`, `/pdf/token/*` нь CA-д байгаа ч `/.well-known/eid`-д хараахан жагсаагдаагүй (гэрээний тест WARN).
+### Зөвхөн Node (backend бүгдийг хийнэ)
+
+```ts
+import { registrationFromCompleted } from "@gerege-systems/eid-mongolia-sdk";
+import { prepare, complete, PadesError } from "@gerege-systems/eid-mongolia-sdk/pades";
+
+const p = await prepare(pdfBytes, { signerCert, verifyPage: true, fileName: "Гэрээ №12.pdf" });
+const s = await eid.signPdfDigest({ dtbs: p.dtbs, fileName: "Гэрээ №12.pdf", signer: { documentNumber } });
+showToUser(s.vc);
+const r = await eid.session.waitForResult(s.sessionId);
+const sig = eid.validator.validateSign(r, s.digest);
+let done;
+for (let i = 0; ; i++) {
+  try {
+    done = await complete(p.state, sig.signatureValueB64);
+    break;
+  } catch (e) {
+    if (e instanceof PadesError && e.retryable && i < 3) continue; // TSA_UNAVAILABLE / LTV_UNAVAILABLE — ижил state+гарын үсэг
+    throw e;
+  }
+}
+await eid.registerSignature(registrationFromCompleted(done, { fileName: "Гэрээ №12.pdf", sessionID: s.sessionId }));
+writeFileSync("signed.pdf", done.pdf);
+```
+
+`PadesError.code` (тогтвортой, бүх платформд ижил): `PDF_INVALID`, `PDF_ENCRYPTED`, `PDF_LOCKED` (DocMDP P=1),
+`PDF_TOO_LARGE`, `PDF_TOO_MANY_SIGNATURES`, `PDF_PRIOR_SIGNATURE_INVALID`, `PDF_FOREIGN_SIGNATURE`, `SIGNER_INVALID`,
+`REQUEST_INVALID`, `SIGNATURE_INVALID` (state хэвээр — дахин зуруулж болно), `TSA_UNAVAILABLE`, `LTV_UNAVAILABLE`
+(`retryable`), `SELF_VALIDATION_FAILED`, `PLACEHOLDER_OVERFLOW`, `STATE_INVALID`, `INTERNAL`.
+`state` нь бэлтгэсэн PDF-ийг агуулна — PDF-тэй ижил нууцлалтай хадгал. Формат нь Go SDK-тай ижил (хөтөчид `prepare`,
+Go backend-д `complete` хийж болно).
+
+0.14.0-д `eid.pdf` (`prepare`, `document`, `documentVerified`, `tokenPrepare`, `tokenFinalize`, `tokenDocument`) ба
+`pdfTimeoutMs` / `pdfMaxBytes` устсан — PDF upload endpoint-ууд CA-д байхгүй болно.
 
 ## 4. QR ба ижил төхөөрөмж — device link v3
 
@@ -522,9 +605,13 @@ OK ирж болзошгүй. Иймд `ResponseValidator`:
 | `ForbiddenError` | 403 — IP allowlist / mTLS / RP-ийн эрх; onBehalfOf татгалзвал `.code` (`OnBehalfErrorCode`) |
 | `SessionFailedError` | endResult ≠ OK (TIMEOUT, USER_REFUSED…) — `.endResult`-оор салга |
 | `ValidationError` | cert chain/signature/level шалгалт бүтэлгүйтсэн |
+| `NoSigningCertificateError` | 409 `NO_SIGNING_CERTIFICATE` — гарын үсгийн гэрчилгээ / төхөөрөмж алга (sign, cert-choice start, PDF prepare); `ApiError`-ийн дэд анги |
+| `CertChoiceInvalidError` | 409 `CERT_CHOICE_INVALID` — linked sign-ийн certificate-choice хүчингүй; `ApiError`-ийн дэд анги |
+| `RequestInvalidError` | 400 `REQUEST_INVALID` — хүсэлт буруу (ж: `linkedSessionID` дутуу); `ApiError`-ийн дэд анги |
 | `ApiError` | бусад HTTP алдаа (`.status`, `.body`, серверийн `.code`, `.retryAfterMs`, `.headers`, `.retryable` — ж: 404 `ORG_NOT_FOUND`) |
-| `ResponseTooLargeError` | хариу SDK-ийн хязгаараас их (JSON 4 MiB, PDF `pdfMaxBytes`) — `.op`, `.limit` |
+| `ResponseTooLargeError` | хариу SDK-ийн хязгаараас их (JSON 4 MiB) — `.op`, `.limit` |
 | `NetworkError` | timeout/сүлжээ (`.op` — таних тэмдэггүй зам, `.timeout`) |
+| `PadesError` (`/pades`) | клиент талын PAdES — `.code` (§3d), `.retryable` |
 | `DeviceLinkError` | device-link холбоос угсрах боломжгүй (`deviceLinkBase` https биш, token/secret/lang хэлбэр, төрөлд хэрэгтэй талбар дутуу) |
 
 ## mTLS (eIDAS qualified орчин)
@@ -541,10 +628,17 @@ const eid = new EidClient({
 
 ```bash
 npm install
-npm run lint   # tsc --noEmit
-npm test       # build + node --test
+npm run lint          # tsc --noEmit
+npm test              # build + node --test (pades golden — Go reference-тэй байт-ижил)
+npm run golden:check  # test/fixtures/pades/golden + src/pades/assets ↔ бэхэлсэн Go commit
+npm run size:pades    # /pades хөтчийн bundle gzip ≤ 300 KB
 ```
 
+`/pades`-ийн conformance fixture (golden: оролт, тестийн PKI-ийн гэрчилгээ, TSA/OCSP/CRL-ийн тогтмол хариу, хүлээгдэх
+sha256) ба фонт/гинжийн asset-ийг Go reference-ээс `node scripts/sync-pades-golden.mjs` хуулна (`GO_SDK_COMMIT` —
+tag `pades-golden-vN`); CI `--check`-ээр бэхэлсэн commit-тэй тулгана. Профайл: Go репогийн `pades/PROFILE.md`,
+`PAGE_SPEC.md`, `PRECHECKS.md`, `WIRE.md`.
+
 ### Гэрээний шалгалт
 
 SDK-ийн дууддаг RP-API зам бүр (`src/contract.ts`) live [`/.well-known/eid`](https://rp.eidmongolia.mn/.well-known/eid)-ийн

package/dist/{browser-CuMH5IVG.d.cts → browser-8k_VDSP8.d.cts}

@@ -1,3 +1,5 @@
+import './errors-Z7SgLVTr.cjs';
+
 /** Сертификатын баталгаажуулалтын түвшин (eIDAS LoA). QUALIFIED — хууль ёсны гарын үсэгт. */
 type CertificateLevel = "ADVANCED" | "QUALIFIED" | "QSCD";
 /** Гарын үсгийн протокол: auth → ACSP_V2, sign → RAW_DIGEST_SIGNATURE (Smart-ID v3). */
@@ -94,8 +96,9 @@ interface SignContext {
 }
 /**
  * CA-ийн SIGNATURE ба CERTIFICATE_CHOICE session-ий анхдагч хүчинтэй хугацаа (мс; `EID_SIGN_SESSION_TTL_SECONDS` = 600).
- * CA-ийн админ «Системийн тохиргоо»-нд 60–1800 секундэд өөрчилж болно; session start хариунд CA хугацааг буцаадаггүй
- * (зөвхөн `sessionID`) тул SDK үүнийг `ClientConfig.signSessionTtlMs`-ээр тооцоолно.
+ * CA-ийн админ «Системийн тохиргоо»-нд 60–1800 секундэд өөрчилж болно. CA 2026-10-14-өөс session start хариунд
+ * `expiresAt` (RFC 3339) буцаадаг — SDK түүнийг ашиглана; хуучин CA (талбаргүй) үед л `ClientConfig.signSessionTtlMs`-ээр
+ * тооцоолно ({@link startExpiry}).
  */
 declare const DEFAULT_SIGN_SESSION_TTL_MS = 600000;
 /**
@@ -104,6 +107,10 @@ declare const DEFAULT_SIGN_SESSION_TTL_MS = 600000;
  * эхлүүлэх» шийдвэрт л — эцсийн үнэн нь `GET /session` (`TIMEOUT`).
  */
 declare function sessionExpiry(sentAtMs: number, ttlMs?: number): number;
+/** CA-ийн `expiresAt` (RFC 3339) → ms epoch; байхгүй / задрахгүй бол undefined. */
+declare function parseExpiresAt(v: unknown): number | undefined;
+/** Session start-ын дуусах мөч: CA-ийн `expiresAt` байвал түүнийг, үгүй бол {@link sessionExpiry} (тооцоолол). */
+declare function startExpiry(raw: unknown, sentAtMs: number, ttlMs?: number): number;
 /**
  * Device-link (QR/Web2App/App2App) session. Иргэн QR уншиж эсвэл товч дарж нэгдэнэ.
  * `sessionToken`, `sessionSecret`-ийг ЗӨВХӨН backend-д хадгална — браузер руу бүү гарга.
@@ -136,7 +143,10 @@ interface DeviceLinkSession {
     sign?: SignContext;
     /** Certificate-choice session-ий хүсэлтэд илгээсэн нэр (cert холбоосын authCode-д). */
     relyingPartyName?: string;
-    /** Sign / certificate-choice session-ий ТООЦООЛСОН дуусах мөч (ms epoch, {@link sessionExpiry}); auth-д undefined. */
+    /**
+     * Session дуусах мөч (ms epoch): CA-ийн start хариуны `expiresAt`; хуучин CA-д sign / certificate-choice-д тооцоолсон
+     * ({@link startExpiry}), auth-д undefined.
+     */
     expiresAt?: number;
 }
 /** Session poll-ийн нэгтгэсэн үр дүн (validator-т орох түүхий материал). */
@@ -169,11 +179,6 @@ interface SessionResult {
      * RP энэ талбарыг л итгэж уншина (клиентийн сонголтод биш). docs/ORG_LOGIN.md.
      */
     onBehalfOf: OrgResult | null;
-    /**
-     * PAdES (`POST /pdf/sign/prepare`) session-ий `pdf` блок — PDF урсгал биш бол null (талбар алга = хуучин SDK-аар
-     * угсарсан объект). {@link PdfSessionBlock}.
-     */
-    pdf?: PdfSessionBlock | null;
     /**
      * COMPLETE+OK auth session-ий `person` блок (CA бүртгэлээс: кирилл нэр, төрсөн огноо, хүйс — гэрчилгээнд байдаггүй).
      * Зөвхөн session эзэмшигч RP-д; CA иргэнийг олоогүй бол null. ГАРЫН ҮСЭГТ ОРДОГГҮЙ — validateAuth-ийн дараа
@@ -215,35 +220,6 @@ interface TokenCertSessionBlock {
     authSerialHex?: string;
     signSerialHex?: string;
 }
-/** PDF баримтын төлөв: PENDING → READY (эсвэл FAILED / EXPIRED). */
-type PdfDocumentStatus = "PENDING" | "READY" | "FAILED" | "EXPIRED";
-/** PAdES гаралтын гарын үсэг зурагч. */
-interface PdfSigner {
-    etsi: string;
-    certSerial: string;
-    /** Байгууллагын нэрийн өмнөөс бол байгууллагын ETSI (`NTRMN-…`) — баримтад бичигдсэн утга. */
-    onBehalfOf?: string;
-    /** CMS signer-attributes-v2-д бичигдсэн мэдүүлсэн үүрэг: «<албан тушаал>, <нэр> (NTRMN-…)». */
-    claimedRole?: string;
-}
-/** GET /session/{id}-ийн `pdf` объект (PAdES, CA угсарна). */
-interface PdfSessionBlock {
-    docID: string;
-    documentStatus: PdfDocumentStatus | string;
-    /** FAILED үед — ж: `REPRESENTATION_REVOKED` (prepare-ээс хойш эрх хасагдсан, баримт үүсээгүй). */
-    errorCode?: string;
-    /** Гарын үсэгтэй PDF-ийн SHA-256 (hex) — татсан файлтай тулгана. */
-    outSha256?: string;
-    size?: number;
-    expiresAt?: string;
-    signatureLevel?: string;
-    signer?: PdfSigner;
-    validation?: {
-        indication: string;
-        ltv: boolean;
-        signatures: number;
-    };
-}
 /** Иргэний төлөөлж чадах нэг байгууллага (GET /organization/representations/etsi/{personEtsi}). */
 interface Representation {
     /** `NTRMN-<бүртгэл>` — `onBehalfOf`-д өгөх утга. */
@@ -267,6 +243,11 @@ interface Representation {
     source: "REGISTRY" | "MANUAL" | string;
     /** Эх үүсвэрийн хүнд харуулах нэр (REGISTRY → «Улсын бүртгэл», MANUAL → «Захирал нэмсэн»; хэл нь `roleLabel`-тэй ижил). Хуучин CA-д байхгүй. */
     sourceLabel?: string;
+    /**
+     * CMS signer-attributes-v2-д бичих мэдүүлсэн үүрэг («<албан тушаал>, <нэр> (NTRMN-…)») — клиент талын PAdES-д
+     * `pades.prepare({claimedRole})`-д ЯГ ХЭВЭЭР өгнө (CA бүртгэлд дахин тооцож тулгана). Хуучин CA-д байхгүй.
+     */
+    claimedRole?: string;
     /** ISO 8601. */
     validFrom: string;
     /** ISO 8601; байхгүй = хугацаагүй. */
@@ -352,135 +333,4 @@ interface OpenOrShowQROptions {
  */
 declare function openOrShowQR(session: DeviceLinkInput, opts: OpenOrShowQROptions): "opened" | "qr";
 
-/** Бүх SDK алдааны суурь. */
-declare class EidError extends Error {
-    constructor(message: string);
-}
-/** 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-ийн төлөөлөл татгалзсан.
- * Сервер `{"error","code"}` буцаасан бол `code` (ж: `REPRESENTATION_DENIED`) — салааллыг үүгээр хийнэ.
- */
-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, init?: HttpErrorInit);
-}
-/** RP-API-аас ирсэн бусад HTTP алдаа (4xx/5xx). status ба хариуны биеийг агуулна. */
-declare class ApiError extends EidError {
-    readonly status: number;
-    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, 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-оор
- * баталгаажуулаагүй), REPRESENTATION_EXPIRED (хугацааны гадна), ORG_NOT_ACTIVE, SIGNER_UNIDENTIFIED (anonymous
- * session); 404: ORG_NOT_FOUND; PDF баримт татахад 403 REPRESENTATION_REVOKED (prepare-ээс хойш эрх хасагдсан —
- * баримт үүсээгүй).
- */
-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 хариу өгсөнгүй. Мессеж ба `op`-д хувь хүний таних тэмдэг ОРОХГҮЙ (замын `/etsi/{…}`,
- * `/document/{…}` → `…`) — шууд лог руу бичиж болно.
- */
-declare class NetworkError extends EidError {
-    /** "GET /session/…" (таних тэмдэг хасагдсан зам). */
-    readonly op?: string;
-    /** Хүсэлт хугацаа хэтэрсэн. */
-    readonly timeout?: boolean;
-    constructor(message: string, init?: {
-        op?: string;
-        timeout?: boolean;
-    });
-}
-/**
- * Хариуны бие SDK-ийн хязгаараас их (JSON 4 MiB, PDF `pdfMaxBytes`) — бие таслагдаж задлагдахгүй. `op` — method +
- * таних тэмдэггүй зам.
- */
-declare class ResponseTooLargeError extends EidError {
-    readonly op: string;
-    readonly limit: number;
-    constructor(op: string, limit: number);
-}
-/**
- * Session амжилтгүй дууссан (endResult ≠ OK): TIMEOUT, USER_REFUSED*, DOCUMENT_UNUSABLE гм.
- * endResult-оор салгаж RP UI-д тохирох мессеж харуулна.
- */
-declare class SessionFailedError extends EidError {
-    readonly endResult: string;
-    constructor(endResult: string);
-}
-/**
- * Хариуны баталгаажуулалт бүтэлгүйтсэн — cert chain итгэлцэлгүй, signature challenge-тэй
- * таарсангүй, эсвэл certLevel хүрэлцээгүй. ЭНЭ алдаа гарвал хариунд ИТГЭХГҮЙ
- * (хуурамч/proxy хийгдсэн байж болзошгүй).
- */
-declare class ValidationError extends EidError {
-}
-/**
- * Device-link (App2App/Web2App) холбоос угсрах боломжгүй — хариунд `deviceLinkBase` байхгүй,
- * эсвэл sessionId/vc/суурь URL хэлбэр буруу. Session-ийг дахин эхлүүлнэ; холбоосыг таахгүй.
- */
-declare class DeviceLinkError extends EidError {
-}
-
-export { type AcspContext as A, type SignatureProtocol as B, type CertificateLevel as C, type DeviceLinkSession as D, EidError as E, type FlowType as F, type TokenCertStatus as G, type HashAlgorithm as H, type Interaction as I, deviceLink as J, isMobileUserAgent as K, openOrShowQR as L, parseRetryAfter as M, type NotificationSession as N, ON_BEHALF_ERROR_CODES as O, type PersonBlock as P, sessionExpiry as Q, 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, DEFAULT_SIGN_SESSION_TTL_MS as f, DeviceLinkError as g, type DeviceLinkInput as h, type EndResult as i, ForbiddenError as j, type HttpErrorInit as k, type NavigatorLike as l, NetworkError as m, type OnBehalfErrorCode as n, type OpenOrShowQROptions as o, type OrgResult as p, type PdfDocumentStatus as q, type PdfSigner as r, RETRYABLE_ERROR_CODES as s, type Representation as t, ResponseTooLargeError as u, type RetryableErrorCode as v, SessionFailedError as w, type SessionState as x, type SignContext as y, type SignatureAlgorithmParameters as z };
+export { type AcspContext as A, type CertificateLevel as C, type DeviceLinkSession as D, type EndResult as E, type FlowType as F, type HashAlgorithm as H, type Interaction as I, type NotificationSession as N, type OpenOrShowQROptions as O, type PersonBlock as P, type RpCredentials as R, type SignatureAlgorithm as S, type TokenCertSessionBlock as T, type SessionResult as a, type RepresentationsResponse as b, DEFAULT_SIGN_SESSION_TTL_MS as c, type DeviceLinkInput as d, type NavigatorLike as e, type OrgResult as f, type Representation as g, type SessionState as h, type SignContext as i, type SignatureAlgorithmParameters as j, type SignatureProtocol as k, type TokenCertStatus as l, deviceLink as m, isMobileUserAgent as n, openOrShowQR as o, parseExpiresAt as p, startExpiry as q, sessionExpiry as s };