@gerege-systems/eid-mongolia-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gerege Systems LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @gerege-systems/eid-mongolia-sdk
+
+**e-ID Mongolia** (Монгол Улсын иргэний цахим үнэмлэх) Relying Party SDK — иргэнээр утсаар нь нэвтрэлт
+(authentication) ба хууль ёсны цахим гарын үсэг (qualified signature) хийлгэх Node.js/TypeScript сан.
+RP-API v3, Smart-ID нийцтэй. Бүрэн баримт: <https://eidmongolia.mn/developers>.
+
+> ⚠️ Зөвхөн **backend**-д ажиллана. API secret (`rp_sk_…`) браузер/гар утсанд хэзээ ч задлахгүй.
+
+## Суулгах
+
+```bash
+npm install @gerege-systems/eid-mongolia-sdk
+```
+
+Node.js ≥ 22 (global `fetch`, `node:crypto`).
+
+## 1. RP бүртгүүлэх
+
+`POST https://ca.eidmongolia.mn/v3/rp-applications` (эсвэл [developer.eidmongolia.mn](https://developer.eidmongolia.mn)) —
+оператор баталсны дараа **relyingPartyUUID** ба **API secret** (`rp_sk_…`) олгогдоно; secret **зөвхөн нэг удаа**
+харагдана. Дэлгэрэнгүй: <https://eidmongolia.mn/developers#burtgel>.
+
+## 2. Нэвтрэлт (push)
+
+```ts
+import { EidClient } from "@gerege-systems/eid-mongolia-sdk";
+
+const eid = new EidClient({
+  baseUrl: "https://ca.eidmongolia.mn",
+  credentials: {
+    rpUUID: process.env.EID_RP_UUID!,
+    rpName: "Хаан Банк",
+    apiSecret: process.env.EID_SECRET!, // rp_sk_…
+  },
+  trust: { trustAnchorsPem: [process.env.EID_NATIONAL_ROOT_CA_PEM!] }, // ← Mongolian National Root CA, production-д ЗААВАЛ
+});
+
+// ETSI (PNOMN-<иргэний дугаар>) / регистр / иргэний дугаар — аль нь ч болно (сервер таьна)
+const s = await eid.auth.notificationByEtsi("PNOMN-12345678", [
+  { type: "displayTextAndPIN", displayText60: "Хаан Банк-д нэвтрэх" },
+]);
+
+showToUser(s.vc); // ← иргэний утсан дээр харагдах баталгаажуулах код (VC)
+
+const result = await eid.session.waitForResult(s.sessionId); // long-poll
+const who = eid.validator.validateAuth(result, s.acsp); // ← гинж + ACSP_V2 крипто-баталгаажуулна
+
+console.log(who.documentNumber, who.subject); // баталгаажсан иргэн
+```
+
+## 3. Гарын үсэг (qualified signature)
+
+```ts
+import { sha256Base64 } from "@gerege-systems/eid-mongolia-sdk";
+
+const digest = sha256Base64(pdfBytes); // баримтын SHA-256 (base64)
+
+const s = await eid.sign.digestByEtsi("PNOMN-12345678", digest, [
+  { type: "displayTextAndPIN", displayText60: "Зээлийн гэрээнд гарын үсэг зурах" },
+]);
+showToUser(s.vc);
+
+const result = await eid.session.waitForResult(s.sessionId);
+const sig = eid.validator.validateSign(result, digest); // digest-ийн эсрэг баталгаажна
+
+console.log(sig.signatureValueB64, sig.subject);
+```
+
+## Аюулгүй байдал — яагаад `validator` заавал
+
+`endResult === "OK"` гэдэгт **дангаар нь итгэхгүй**. RP-API эвдэрсэн/proxy хийгдсэн бол хуурамч
+OK ирж болзошгүй. Иймд `ResponseValidator`:
+
+1. `state === COMPLETE && endResult === OK`
+2. Иргэний гэрчилгээг **trust anchor (Mongolian National Root CA)** хүртэл chain-аар баталгаажуулна
+   (Root → National Issuing CA → Gerege Issuing CA → eID Mongolia Issuing CA → иргэн)
+3. Гэрчилгээ хүчинтэй хугацаанд + шаардсан `certificateLevel` (default `QUALIFIED`)
+4. Гарын үсгийг иргэний public key-ээр шалгана:
+   - **auth** → ACSP_V2 payload (`smart-id|ACSP_V2|serverRandom|rpChallenge|userChallenge|B64(rpName)|B64(brokeredRpName)|B64(SHA-256(interactions))|interactionTypeUsed|initialCallbackUrl|flowType`, hash = хүсэлтийн `hashAlgorithm`) дээр — `flowType`, `userChallenge`, `serverRandom` ба алгоритмын downgrade-ийг мөн шалгана
+   - **sign** → RP-ийн өгсөн digest дээр
+
+Аль нэг алхам бүтэлгүйтвэл `ValidationError` шиднэ — хариунд **итгэхгүй**.
+
+## Алдааны төрлүүд
+
+| Алдаа | Утга |
+|---|---|
+| `AuthenticationError` | 401 — API secret буруу/байхгүй |
+| `ForbiddenError` | 403 — IP allowlist / mTLS зөвшөөрөөгүй |
+| `SessionFailedError` | endResult ≠ OK (TIMEOUT, USER_REFUSED…) — `.endResult`-оор салга |
+| `ValidationError` | cert chain/signature/level шалгалт бүтэлгүйтсэн |
+| `ApiError` | бусад HTTP алдаа (`.status`, `.body`) |
+| `NetworkError` | timeout/сүлжээ |
+
+## mTLS (eIDAS qualified орчин)
+
+```ts
+import { Agent } from "undici";
+const eid = new EidClient({
+  /* … */
+  dispatcher: new Agent({ connect: { cert: clientCertPem, key: clientKeyPem } }),
+});
+```
+
+## Хөгжүүлэлт
+
+```bash
+npm install
+npm run lint   # tsc --noEmit
+npm test       # build + node --test
+```