@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_…) браузер/гар утсанд хэзээ ч задлахгүй.

Суулгах

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) — оператор баталсны дараа relyingPartyUUID ба API secret (rp_sk_…) олгогдоно; secret зөвхөн нэг удаа харагдана. Дэлгэрэнгүй: https://eidmongolia.mn/developers#burtgel.

2. Нэвтрэлт (push)

import { EidClient } from "@gerege-systems/eid-mongolia-sdk";

const eid = new EidClient({
  // baseUrl анхдагч https://rp.eidmongolia.mn (RP-API, /v3-гүй) — mTLS-тэй RP ч мөн энэ хост
  credentials: {
    rpUUID: process.env.EID_RP_UUID!,
    rpName: "Интернэт банк", // дэд системийн нэр, ≤120 тэмдэгт
    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)

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 орчин)

import { Agent } from "undici";
const eid = new EidClient({
  /* … */
  dispatcher: new Agent({ connect: { cert: clientCertPem, key: clientKeyPem } }),
});

Хөгжүүлэлт

npm install
npm run lint   # tsc --noEmit
npm test       # build + node --test