@gerege-systems/eid-mongolia-sdk 0.14.2 → 0.15.1

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 бүртгүүлэх
 
@@ -70,7 +72,7 @@ export const eidLogin = createEidLogin({
     };
   },
   // store: redisStore,            // олон instance / serverless бол (анхдагч — процессын санах ой)
-  // rateLimit: (key) => redisLimiter.allow(key), // "start:<ip>", "push:<idCode>"; анхдагч push 3/мин нэг дугаарт
+  // rateLimit: { start: (key) => redisLimiter.allow(key) }, // анхдагчтай нэгтгэгдэнэ (push 3/мин хэвээр) — доор «Хязгаарлалт»
   trustProxy: 1, // handle(Request)-д клиент IP: nginx/LB нэг hop бол 1 (доор «Клиент IP»)
 });
 ```
@@ -93,8 +95,27 @@ export const POST = (req: Request) => eidLogin.handle(req);
   Vercel `req.headers.get("x-real-ip")`). `trustProxy`-оос давуу.
 
 Аль нь ч үгүй бол IP-ээр хязгаарлахгүй (эхний хүсэлтэд `onError`-оор нэг удаа анхааруулна). `handleRequest`-д `req.ip`
-(Express `req.ip`, `app.set("trust proxy", …)`-тэй) шууд хэрэглэгдэнэ. Анхдагч `rateLimit` зөвхөн `push:`-ийг хязгаарладаг —
-`start:<ip>`-ийг өөрийн `rateLimit`-ээр (Redis г.м.) хязгаарлана. Go: `eidlogin.Config.ClientIP` (`eidlogin.ForwardedClientIP(n)`) — ижил дүрэм.
+(Express `req.ip`, `app.set("trust proxy", …)`-тэй) шууд хэрэглэгдэнэ. Go: `eidlogin.Config.ClientIP` (`eidlogin.ForwardedClientIP(n)`) — ижил дүрэм.
+
+**Хязгаарлалт** (`rateLimit`). Түлхүүр: `start:<ip>` (IP мэдэгдэж байвал), `push:<idCode>`; татгалзвал 429 + `Retry-After: 60`.
+Анхдагч `defaultRateLimit` = `{ push: { limit: 3, windowMs: 60_000 } }` — нэг дугаарт минутад 3 мэдэгдэл (MFA fatigue);
+`start`-ийг анхдагчаар хязгаарладаггүй.
+
+- **Объект** `{ start?, push? }` — анхдагчтай **нэгтгэгдэнэ**: өгсөн төрөл анхдагчийг дарна, өгөөгүй нь анхдагчаараа үлдэнэ.
+  Утга: `{ limit, windowMs }` (процессын санах ойн гулсах цонх), `(key) => boolean | Promise<boolean>` (Redis г.м.),
+  эсвэл `false` (тухайн төрлийг хязгаарлахгүй). Өөр түлхүүр → `createEidLogin` throw.
+- **Функц** `(key) => …` — бүх түлхүүрт дуудагдана, анхдагч хязгаар **дээр нэмэгдэнэ** (хоёулаа зөвшөөрөх ёстой).
+  Анхдагчийг сулруулах/солих бол объектоор тухайн төрлийг өг (`{ push: … }`).
+
+```ts
+import { defaultRateLimit } from "@gerege-systems/eid-mongolia-sdk";
+rateLimit: { start: { limit: 20, windowMs: 60_000 } },             // push 3/мин хэвээр
+rateLimit: { ...defaultRateLimit, start: (k) => redis.allow(k) },  // ижил — анхдагчийг илэрхий бичсэн
+rateLimit: { push: (k) => redis.allow(k, 3, 60) },                 // олон instance: push-ийг Redis-ээр солино
+```
+
+Go: `eidlogin.Config.RateLimits` (`map[string]eidlogin.RateRule{"start": {Max: 20, Window: time.Minute}}`,
+`eidlogin.DefaultRateLimit()`) — ижил нэгтгэл; `Config.RateLimit` функц мөн анхдагч дээр нэмэгдэнэ.
 
 Express:
 
@@ -126,21 +147,39 @@ app.use("/auth/eid", express.json(), async (req, res) => {
 **Дизайн, theme.** Дизайн нь eID нэвтрэх хуудсынх (лого, өнгө). Фонт нь хуудаснаас өвлөгдөнө (товч, цонх, input бүгд).
 `theme="auto"` үед дараалал: хуудасны `html[data-theme="dark|light"]` → `html.dark` / `html.light` → OS
 (`prefers-color-scheme`); хуудас theme солиход (MutationObserver) шууд дагана. `theme="light|dark"` нь хуудсыг давна.
-Өнгө, радиусыг CSS хувьсагчаар (элемент дээр — shadow-ийн `:host`-оос давуу) дарна:
+Өнгө, радиусыг CSS хувьсагчаар дарна. `--eid-*` нь зөвхөн **оролт** (shadow дотор тодорхойлогддоггүй) тул хуудасны
+аль ч түвшинд (`:root`, эцэг элемент, `eid-login-button`) өгсөн утга өвлөгдөж **light ба dark хоёуланд** үйлчилнэ;
+`--eid-<нэр>-dark` нь зөвхөн dark-д, `--eid-<нэр>`-ээс давуу. Аль нь ч үгүй бол eID-ийн анхдагч (доорх хүснэгт) — fallback л.
+Dark-ийн дараалал: `--eid-<нэр>-dark` → `--eid-<нэр>` → dark анхдагч.
 
 ```css
-eid-login-button {
-  --eid-accent: #0b5cff; --eid-accent-fg: #fff;   /* үндсэн товч, QR-ийн алхмын тоо (--eid-accent-subtle, --eid-accent-subtle-fg) */
-  --eid-bg: #fff; --eid-bg-subtle: …; --eid-bg-muted: …;  /* цонх, hover */
-  --eid-fg: …; --eid-fg-muted: …; --eid-fg-subtle: …;     /* текст */
-  --eid-border: …; --eid-border-strong: …; --eid-ring: …; /* хүрээ, focus */
-  --eid-warning-bg: …; --eid-warning-border: …; --eid-warning-fg: …; --eid-danger-fg: …;
+:root {                                   /* эсвэл eid-login-button { … } */
+  --eid-accent: var(--brand);             /* хоёр theme-д */
+  --eid-accent-dark: var(--brand-400);    /* зөвхөн dark-д (өгөхгүй бол --eid-accent) */
   --eid-radius: 6px; --eid-radius-lg: 8px;
 }
-html[data-theme="dark"] eid-login-button { --eid-accent: …; } /* dark-д өөр өнгө бол */
-eid-login-button::part(button) { width: 100%; }               /* part: button, backdrop, dialog */
+eid-login-button::part(button) { width: 100%; }  /* part: button, backdrop, dialog */
 ```
 
+| Хувьсагч (`-dark` хувилбартай) | Юунд | Light анхдагч | Dark анхдагч |
+|---|---|---|---|
+| `--eid-accent` | үндсэн товч | `oklch(0.534 0.2 259)` | `oklch(0.64 0.15 259)` |
+| `--eid-accent-fg` | үндсэн товчны текст | `#fff` | `hsl(229 50% 6%)` |
+| `--eid-accent-subtle` | алхмын дугаарын дэвсгэр | `oklch(0.97 0.03 259)` | `oklch(0.24 0.06 259)` |
+| `--eid-accent-subtle-fg` | алхмын дугаар | `oklch(0.474 0.19 259)` | `oklch(0.82 0.1 259)` |
+| `--eid-ring` | focus | `oklch(0.604 0.2 259)` | `oklch(0.68 0.15 259)` |
+| `--eid-bg` | цонх, outline товч, input | `hsl(0 0% 100%)` | `hsl(229 50% 6%)` |
+| `--eid-bg-subtle` | — (нөөц) | `hsl(210 40% 98%)` | `hsl(222 47% 9%)` |
+| `--eid-bg-muted` | hover | `hsl(210 40% 96%)` | `hsl(217 33% 13%)` |
+| `--eid-fg` | текст | `hsl(222 47% 11%)` | `hsl(210 40% 98%)` |
+| `--eid-fg-muted` | хоёрдогч текст | `hsl(215 19% 35%)` | `hsl(213 27% 84%)` |
+| `--eid-fg-subtle` | тайлбар, placeholder | `hsl(215 16% 45%)` | `hsl(215 20% 65%)` |
+| `--eid-border` | цонх, QR, тусгаарлагч | `hsl(214 32% 91%)` | `hsl(217 33% 17%)` |
+| `--eid-border-strong` | outline товч, input | `hsl(213 27% 84%)` | `hsl(215 25% 27%)` |
+| `--eid-warning-bg` / `-border` / `-fg` | сүлжээний анхааруулга | `hsl(48 100% 96%)` / `hsl(45 95% 78%)` / `hsl(23 75% 33%)` | `hsl(20 60% 10%)` / `hsl(22 70% 26%)` / `hsl(40 92% 65%)` |
+| `--eid-danger-fg` | алдаа | `hsl(0 74% 42%)` | `hsl(0 91% 71%)` |
+| `--eid-radius` / `--eid-radius-lg` (theme-гүй) | булан | `6px` / `8px` | — |
+
 **eID аппын доод хувилбар.** `flowType` бэхлэлт (device link v3) ба Web2App-ийн `userChallengeVerifier` нь
 **iOS 2.2.3 (build 59)**, **Android 2.2.3 (versionCode 60)**-аас эхэлсэн. eID сервер 2026-10-07-оос legacy холбоосыг
 бүрэн хассан (v3-гүй session-д утас `DEVICE_LINK_REQUIRED`) бөгөөд доод хувилбарыг `/mobile/app-config`-оор албадан
@@ -235,7 +274,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)
@@ -324,42 +363,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-ий
@@ -368,9 +387,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` эрх)
 
@@ -394,14 +411,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 });
+```
+
+### Зөвхөн 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);
 ```
 
-`/token/auth/*`, `/pdf/token/*` нь CA-д байгаа ч `/.well-known/eid`-д хараахан жагсаагдаагүй (гэрээний тест WARN).
+`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
 
@@ -532,8 +646,9 @@ OK ирж болзошгүй. Иймд `ResponseValidator`:
 | `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 орчин)
@@ -550,10 +665,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-CSZjH9Xs.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). */
@@ -177,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-ийн дараа
@@ -223,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`-д өгөх утга. */
@@ -275,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; байхгүй = хугацаагүй. */
@@ -360,152 +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;
-}
-/**
- * 409 `NO_SIGNING_CERTIFICATE` — иргэнд (баримтад) идэвхтэй төхөөрөмж / SIGN credential / хүчинтэй гарын үсгийн
- * гэрчилгээ алга: sign ба certificate-choice session start, `/pdf/sign/prepare`. Session үүсээгүй. Танихгүй
- * лавлагаанд ч ижил хариу (бүртгэл задлахгүй) — хэрэглэгчид «eID гарын үсгийн гэрчилгээгүй» гэж харуулна.
- */
-declare class NoSigningCertificateError extends ApiError {
-}
-/**
- * 409 `CERT_CHOICE_INVALID` — linked sign-ийн `linkedSessionID` (certificate-choice) хүчингүй: өөр RP, COMPLETE+OK биш,
- * өөр documentNumber, 5 минутаас хуучин, гэрчилгээ солигдсон, эсвэл аль хэдийн ашиглагдсан. Certificate-choice-ийг
- * дахин эхлүүлнэ.
- */
-declare class CertChoiceInvalidError extends ApiError {
-}
-/** 400 `REQUEST_INVALID` — хүсэлтийн бие/талбар буруу (ж: linked sign-д `linkedSessionID` дутуу). Програмын алдаа. */
-declare class RequestInvalidError extends ApiError {
-}
-/**
- * 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 SessionState as B, type CertificateLevel as C, type DeviceLinkSession as D, EidError as E, type FlowType as F, type SignContext as G, type HashAlgorithm as H, type Interaction as I, type SignatureAlgorithmParameters as J, type SignatureProtocol as K, type TokenCertStatus as L, deviceLink as M, type NotificationSession as N, ON_BEHALF_ERROR_CODES as O, type PersonBlock as P, isMobileUserAgent as Q, type RpCredentials as R, type SignatureAlgorithm as S, type TokenCertSessionBlock as T, openOrShowQR as U, ValidationError as V, parseExpiresAt as W, parseRetryAfter as X, sessionExpiry as Y, startExpiry as Z, type SessionResult as a, type PdfSessionBlock as b, type RepresentationsResponse as c, ApiError as d, AuthenticationError as e, CertChoiceInvalidError as f, DEFAULT_SIGN_SESSION_TTL_MS as g, DeviceLinkError as h, type DeviceLinkInput as i, type EndResult as j, ForbiddenError as k, type HttpErrorInit as l, type NavigatorLike as m, NetworkError as n, NoSigningCertificateError as o, type OnBehalfErrorCode as p, type OpenOrShowQROptions as q, type OrgResult as r, type PdfDocumentStatus as s, type PdfSigner as t, RETRYABLE_ERROR_CODES as u, type Representation as v, RequestInvalidError as w, ResponseTooLargeError as x, type RetryableErrorCode as y, SessionFailedError 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 };