@gerege-systems/eid-mongolia-sdk 0.4.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 **e-ID Mongolia** (Монгол Улсын иргэний цахим үнэмлэх) Relying Party SDK — иргэнээр утсаар нь нэвтрэлт
 (authentication) ба хууль ёсны цахим гарын үсэг (qualified signature) хийлгэх Node.js/TypeScript сан.
-RP-API v3, Smart-ID нийцтэй. Бүрэн баримт: <https://eidmongolia.mn/developers>.
+RP-API v3, Smart-ID нийцтэй. Бүрэн баримт: <https://developer.eidmongolia.mn/>.
 
 > ⚠️ Зөвхөн **backend**-д ажиллана (`@gerege-systems/eid-mongolia-sdk/browser`-ийн device-link туслахаас бусад).
 > API secret (`rp_sk_…`) браузер/гар утсанд хэзээ ч задлахгүй.
@@ -19,7 +19,7 @@ Node.js ≥ 22 (global `fetch`, `node:crypto`).
 
 `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>.
+харагдана. Дэлгэрэнгүй: <https://developer.eidmongolia.mn/#burtgel>.
 
 ## 2. Нэвтрэлт (push)
 
@@ -91,9 +91,28 @@ button.onclick = () => {
   const how = openOrShowQR(session, { showQR: (link) => renderQr(link) }); // "opened" | "qr"
   showVc(session.vc); // иргэний утсан дээрх кодтой тулгуулна (ПИН биш)
 };
-// дараа нь backend: eid.session.waitForResult(sessionId) → eid.validator.validateAuth(result, s.acsp)
+// дараа нь backend: eid.session.waitForResult(sessionId) → eid.validator.validateAuth(result, s.acsp, {...})
 ```
 
+**Эхлүүлсэн урсгалаа заавал тулга (relay хаалт).** RP аль урсгалыг эхлүүлснээ мэддэг — гарын үсэг зурагдсан
+`flowType` түүнтэй таарах ёстой, same-device үед callback-ийн `userChallengeVerifier` заавал:
+
+```ts
+// desktop дээр QR харуулсан
+eid.validator.validateAuth(result, s.acsp, { expectedFlowType: "QR" });
+
+// гар утасны браузераас апп нээсэн (callbackUrl-тай session) — апп буцахдаа
+// `?userChallengeVerifier=...`-ийг callback URL-д нэмдэг
+eid.validator.validateAuth(result, s.acsp, {
+  expectedFlowType: "Web2App", // өөр аппаас бол "App2App"
+  userChallengeVerifier: callbackQuery.get("userChallengeVerifier") ?? undefined,
+});
+```
+
+> eID Mongolia апп бодит сувгийг 2.2.3 (build 58)-аас мэдээлнэ. Өмнөх build-ууд серверийн хүлээлтийг хуулдаг
+> (callback-тай session → `App2App`, үгүй → `QR`) тул серверт min_version тавигдтал энэ шалгалт relay-ээс бүрэн
+> хамгаалахгүй — гэхдээ QR урсгалд хуучин апптай ч эвдрэхгүй.
+
 - Гар утас (iOS/Android, desktop UA илгээдэг iPadOS ч) бол `location.assign(link)` — Universal Link / App Link
   аппыг нээнэ; бусад үед `showQR(link)`. Илрүүлэгчийг `isMobile: boolean | () => boolean`-оор солино
   (анхдагч `isMobileUserAgent()`).
@@ -113,7 +132,8 @@ OK ирж болзошгүй. Иймд `ResponseValidator`:
    (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-ийг мөн шалгана
+   - **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-ийг мөн шалгана;
+     `expectedFlowType` өгвөл `flowType` эхлүүлсэн урсгалтай ЯГ таарах, Web2App/App2App-д `userChallengeVerifier` заавал
    - **sign** → RP-ийн өгсөн digest дээр
 
 Аль нэг алхам бүтэлгүйтвэл `ValidationError` шиднэ — хариунд **итгэхгүй**.

package/dist/index.cjs

@@ -45,6 +45,7 @@ __export(index_exports, {
   randomChallenge: () => randomChallenge,
   resolveBaseUrl: () => resolveBaseUrl,
   sha256Base64: () => sha256Base64,
+  userChallengeOf: () => userChallengeOf,
   verifyPayloadSignature: () => verifyPayloadSignature,
   verifyPrehashedSignature: () => verifyPrehashedSignature
 });
@@ -415,7 +416,7 @@ var ResponseValidator = class {
    * Auth session-ийн хариуг бүрэн шалгаж, баталгаажсан иргэнийг буцаана.
    * @param acsp — session эхлүүлэхэд SDK-ийн буцаасан `acsp` контекст (RP хадгалсан).
    */
-  validateAuth(result, acsp) {
+  validateAuth(result, acsp, opts = {}) {
     const leaf = this.precheck(result, "ACSP_V2");
     const { serverRandom, userChallenge, flowType, interactionTypeUsed } = result;
     if (!serverRandom || Buffer.from(serverRandom, "base64").length < 18) throw new ValidationError("serverRandom \u0430\u043B\u0433\u0430/\u0431\u043E\u0433\u0438\u043D\u043E");
@@ -423,6 +424,16 @@ var ResponseValidator = class {
     if (!flowType || !acsp.flowTypes.includes(flowType)) {
       throw new ValidationError(`flowType ${flowType} \u043D\u044C \u0441\u0430\u043D\u0430\u043B \u0431\u043E\u043B\u0433\u043E\u0441\u043E\u043D \u0443\u0440\u0441\u0433\u0430\u043B\u0434 \u0431\u0430\u0439\u0445\u0433\u04AF\u0439`);
     }
+    if (opts.expectedFlowType && flowType !== opts.expectedFlowType) {
+      throw new ValidationError(`flowType ${flowType} \u2260 \u044D\u0445\u043B\u04AF\u04AF\u043B\u0441\u044D\u043D \u0443\u0440\u0441\u0433\u0430\u043B ${opts.expectedFlowType} (relay \u0431\u0430\u0439\u0436 \u0431\u043E\u043B\u0437\u043E\u0448\u0433\u04AF\u0439)`);
+    }
+    const sameDevice = opts.expectedFlowType === "Web2App" || opts.expectedFlowType === "App2App";
+    if (sameDevice && !opts.userChallengeVerifier) {
+      throw new ValidationError(`${opts.expectedFlowType} \u0443\u0440\u0441\u0433\u0430\u043B\u0434 callback-\u0438\u0439\u043D userChallengeVerifier \u0437\u0430\u0430\u0432\u0430\u043B`);
+    }
+    if (opts.userChallengeVerifier !== void 0 && userChallengeOf(opts.userChallengeVerifier) !== userChallenge) {
+      throw new ValidationError("userChallengeVerifier \u043D\u044C \u0433\u0430\u0440\u044B\u043D \u04AF\u0441\u044D\u0433 \u0437\u0443\u0440\u0430\u0433\u0434\u0441\u0430\u043D userChallenge-\u0442\u044D\u0439 \u0442\u0430\u0430\u0440\u0441\u0430\u043D\u0433\u04AF\u0439");
+    }
     if (!interactionTypeUsed) throw new ValidationError("interactionTypeUsed \u0430\u043B\u0433\u0430");
     const { alg, hash } = this.algorithmOf(result, acsp.signatureAlgorithm, acsp.hashAlgorithm);
     const payload = buildAcspV2Payload({
@@ -570,6 +581,9 @@ var ResponseValidator = class {
     }
   }
 };
+function userChallengeOf(verifier) {
+  return (0, import_node_crypto2.createHash)("sha256").update(verifier, "utf8").digest("base64url");
+}
 function verifyPayloadSignature(payload, sigB64, key, alg, hash) {
   const sig = Buffer.from(sigB64, "base64");
   const h = nodeHash(hash);
@@ -809,6 +823,7 @@ function openOrShowQR(session, opts) {
   randomChallenge,
   resolveBaseUrl,
   sha256Base64,
+  userChallengeOf,
   verifyPayloadSignature,
   verifyPrehashedSignature
 });

package/dist/index.d.cts

@@ -131,6 +131,28 @@ declare class SessionApi {
     }): Promise<SessionResult>;
 }
 
+/**
+ * validateAuth-ийн нэмэлт шалгалт — RP ЯМАР урсгал эхлүүлснээ мэддэг тул түүнийг тулгана
+ * (device-link relay хаалт).
+ */
+interface ValidateAuthOptions {
+    /**
+     * RP-ийн эхлүүлсэн урсгал. Өгвөл гарын үсэг зурагдсан ACSP_V2 `flowType` ЯГ ИЖИЛ байх ёстой:
+     * desktop QR → "QR"; браузераас холбоосоор апп нээсэн → "Web2App"; өөр аппаас → "App2App";
+     * push → "Notification". "Web2App"/"App2App" үед `userChallengeVerifier` ЗААВАЛ.
+     *
+     * ⚠️ Апп нь бодит сувгийг eID Mongolia 2.2.3 (build 58)-аас мэдээлнэ. Түүнээс өмнөх build-ууд
+     * серверийн хүлээлтийг хуулдаг тул серверт min_version тавигдтал энэ шалгалт relay-ээс
+     * бүрэн хамгаалахгүй (гэхдээ хуучин апптай ч эвдрэхгүй — QR урсгалд "QR" ирнэ).
+     */
+    expectedFlowType?: FlowType;
+    /**
+     * Callback URL-ийн `userChallengeVerifier` параметр (same-device урсгалд апп RP руу буцаахдаа
+     * нэмдэг). Өгвөл `BASE64URL(SHA-256(UTF-8(verifier)))` нь гарын үсэг зурагдсан `userChallenge`-тэй
+     * таарах ёстой.
+     */
+    userChallengeVerifier?: string;
+}
 /**
  * RevocationChecker — иргэний cert revoke хийгдсэн эсэхийг шалгах hook (OCSP/CRL).
  * Сүлжээний I/O шаардсан тул async. RP нь cert доторх AIA (OCSP) / CDP (CRL) URL-аар
@@ -197,7 +219,7 @@ declare class ResponseValidator {
      * Auth session-ийн хариуг бүрэн шалгаж, баталгаажсан иргэнийг буцаана.
      * @param acsp — session эхлүүлэхэд SDK-ийн буцаасан `acsp` контекст (RP хадгалсан).
      */
-    validateAuth(result: SessionResult, acsp: AcspContext): VerifiedIdentity;
+    validateAuth(result: SessionResult, acsp: AcspContext, opts?: ValidateAuthOptions): VerifiedIdentity;
     /**
      * Sign session-ийн хариуг бүрэн шалгаж, баталгаажсан гарын үсгийг буцаана.
      * @param hashAlgorithm — digest-ийг үүсгэсэн hash (хүсэлтэд илгээсэнтэй ижил; default SHA-256).
@@ -225,6 +247,8 @@ declare class ResponseValidator {
     checkRevocation(cert: X509Certificate): Promise<void>;
 }
 /** Payload (auth) дээрх гарын үсэг — алгоритмаар салаалж node:crypto verify. */
+/** Smart-ID: userChallenge = BASE64URL(SHA-256(UTF-8(userChallengeVerifier))), padding-гүй. */
+declare function userChallengeOf(verifier: string): string;
 declare function verifyPayloadSignature(payload: Buffer, sigB64: string, key: KeyObject, alg: string, hash: string): boolean;
 /** Prehashed digest (sign) дээрх гарын үсэг. RSA: raw public op + EMSA-PSS-VERIFY / PKCS#1 DigestInfo. */
 declare function verifyPrehashedSignature(digest: Buffer, sigB64: string, key: KeyObject, alg: string, hash: string): boolean;
@@ -288,4 +312,4 @@ declare function buildAcspV2Payload(p: AcspV2Params): Buffer;
 /** HASH_{hashAlgorithm}(payload). */
 declare function acspV2Digest(p: AcspV2Params, hashAlgorithm: HashAlgorithm | string): Buffer;
 
-export { AcspContext, type AcspV2Params, AuthApi, type AuthDefaults, type AuthOptions, CertificateLevel, type ClientConfig, DEFAULT_BASE_URL, DeviceLinkSession, EidClient, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, ResponseValidator, type RevocationChecker, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, type TrustConfig, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, interactionsToBase64, parseSessionResult, randomChallenge, resolveBaseUrl, sha256Base64, verifyPayloadSignature, verifyPrehashedSignature };
+export { AcspContext, type AcspV2Params, AuthApi, type AuthDefaults, type AuthOptions, CertificateLevel, type ClientConfig, DEFAULT_BASE_URL, DeviceLinkSession, EidClient, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, ResponseValidator, type RevocationChecker, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, type TrustConfig, type ValidateAuthOptions, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, interactionsToBase64, parseSessionResult, randomChallenge, resolveBaseUrl, sha256Base64, userChallengeOf, verifyPayloadSignature, verifyPrehashedSignature };

package/dist/index.d.ts

@@ -131,6 +131,28 @@ declare class SessionApi {
     }): Promise<SessionResult>;
 }
 
+/**
+ * validateAuth-ийн нэмэлт шалгалт — RP ЯМАР урсгал эхлүүлснээ мэддэг тул түүнийг тулгана
+ * (device-link relay хаалт).
+ */
+interface ValidateAuthOptions {
+    /**
+     * RP-ийн эхлүүлсэн урсгал. Өгвөл гарын үсэг зурагдсан ACSP_V2 `flowType` ЯГ ИЖИЛ байх ёстой:
+     * desktop QR → "QR"; браузераас холбоосоор апп нээсэн → "Web2App"; өөр аппаас → "App2App";
+     * push → "Notification". "Web2App"/"App2App" үед `userChallengeVerifier` ЗААВАЛ.
+     *
+     * ⚠️ Апп нь бодит сувгийг eID Mongolia 2.2.3 (build 58)-аас мэдээлнэ. Түүнээс өмнөх build-ууд
+     * серверийн хүлээлтийг хуулдаг тул серверт min_version тавигдтал энэ шалгалт relay-ээс
+     * бүрэн хамгаалахгүй (гэхдээ хуучин апптай ч эвдрэхгүй — QR урсгалд "QR" ирнэ).
+     */
+    expectedFlowType?: FlowType;
+    /**
+     * Callback URL-ийн `userChallengeVerifier` параметр (same-device урсгалд апп RP руу буцаахдаа
+     * нэмдэг). Өгвөл `BASE64URL(SHA-256(UTF-8(verifier)))` нь гарын үсэг зурагдсан `userChallenge`-тэй
+     * таарах ёстой.
+     */
+    userChallengeVerifier?: string;
+}
 /**
  * RevocationChecker — иргэний cert revoke хийгдсэн эсэхийг шалгах hook (OCSP/CRL).
  * Сүлжээний I/O шаардсан тул async. RP нь cert доторх AIA (OCSP) / CDP (CRL) URL-аар
@@ -197,7 +219,7 @@ declare class ResponseValidator {
      * Auth session-ийн хариуг бүрэн шалгаж, баталгаажсан иргэнийг буцаана.
      * @param acsp — session эхлүүлэхэд SDK-ийн буцаасан `acsp` контекст (RP хадгалсан).
      */
-    validateAuth(result: SessionResult, acsp: AcspContext): VerifiedIdentity;
+    validateAuth(result: SessionResult, acsp: AcspContext, opts?: ValidateAuthOptions): VerifiedIdentity;
     /**
      * Sign session-ийн хариуг бүрэн шалгаж, баталгаажсан гарын үсгийг буцаана.
      * @param hashAlgorithm — digest-ийг үүсгэсэн hash (хүсэлтэд илгээсэнтэй ижил; default SHA-256).
@@ -225,6 +247,8 @@ declare class ResponseValidator {
     checkRevocation(cert: X509Certificate): Promise<void>;
 }
 /** Payload (auth) дээрх гарын үсэг — алгоритмаар салаалж node:crypto verify. */
+/** Smart-ID: userChallenge = BASE64URL(SHA-256(UTF-8(userChallengeVerifier))), padding-гүй. */
+declare function userChallengeOf(verifier: string): string;
 declare function verifyPayloadSignature(payload: Buffer, sigB64: string, key: KeyObject, alg: string, hash: string): boolean;
 /** Prehashed digest (sign) дээрх гарын үсэг. RSA: raw public op + EMSA-PSS-VERIFY / PKCS#1 DigestInfo. */
 declare function verifyPrehashedSignature(digest: Buffer, sigB64: string, key: KeyObject, alg: string, hash: string): boolean;
@@ -288,4 +312,4 @@ declare function buildAcspV2Payload(p: AcspV2Params): Buffer;
 /** HASH_{hashAlgorithm}(payload). */
 declare function acspV2Digest(p: AcspV2Params, hashAlgorithm: HashAlgorithm | string): Buffer;
 
-export { AcspContext, type AcspV2Params, AuthApi, type AuthDefaults, type AuthOptions, CertificateLevel, type ClientConfig, DEFAULT_BASE_URL, DeviceLinkSession, EidClient, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, ResponseValidator, type RevocationChecker, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, type TrustConfig, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, interactionsToBase64, parseSessionResult, randomChallenge, resolveBaseUrl, sha256Base64, verifyPayloadSignature, verifyPrehashedSignature };
+export { AcspContext, type AcspV2Params, AuthApi, type AuthDefaults, type AuthOptions, CertificateLevel, type ClientConfig, DEFAULT_BASE_URL, DeviceLinkSession, EidClient, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, ResponseValidator, type RevocationChecker, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, type TrustConfig, type ValidateAuthOptions, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, interactionsToBase64, parseSessionResult, randomChallenge, resolveBaseUrl, sha256Base64, userChallengeOf, verifyPayloadSignature, verifyPrehashedSignature };

package/dist/index.js

@@ -343,7 +343,7 @@ var ResponseValidator = class {
    * Auth session-ийн хариуг бүрэн шалгаж, баталгаажсан иргэнийг буцаана.
    * @param acsp — session эхлүүлэхэд SDK-ийн буцаасан `acsp` контекст (RP хадгалсан).
    */
-  validateAuth(result, acsp) {
+  validateAuth(result, acsp, opts = {}) {
     const leaf = this.precheck(result, "ACSP_V2");
     const { serverRandom, userChallenge, flowType, interactionTypeUsed } = result;
     if (!serverRandom || Buffer.from(serverRandom, "base64").length < 18) throw new ValidationError("serverRandom \u0430\u043B\u0433\u0430/\u0431\u043E\u0433\u0438\u043D\u043E");
@@ -351,6 +351,16 @@ var ResponseValidator = class {
     if (!flowType || !acsp.flowTypes.includes(flowType)) {
       throw new ValidationError(`flowType ${flowType} \u043D\u044C \u0441\u0430\u043D\u0430\u043B \u0431\u043E\u043B\u0433\u043E\u0441\u043E\u043D \u0443\u0440\u0441\u0433\u0430\u043B\u0434 \u0431\u0430\u0439\u0445\u0433\u04AF\u0439`);
     }
+    if (opts.expectedFlowType && flowType !== opts.expectedFlowType) {
+      throw new ValidationError(`flowType ${flowType} \u2260 \u044D\u0445\u043B\u04AF\u04AF\u043B\u0441\u044D\u043D \u0443\u0440\u0441\u0433\u0430\u043B ${opts.expectedFlowType} (relay \u0431\u0430\u0439\u0436 \u0431\u043E\u043B\u0437\u043E\u0448\u0433\u04AF\u0439)`);
+    }
+    const sameDevice = opts.expectedFlowType === "Web2App" || opts.expectedFlowType === "App2App";
+    if (sameDevice && !opts.userChallengeVerifier) {
+      throw new ValidationError(`${opts.expectedFlowType} \u0443\u0440\u0441\u0433\u0430\u043B\u0434 callback-\u0438\u0439\u043D userChallengeVerifier \u0437\u0430\u0430\u0432\u0430\u043B`);
+    }
+    if (opts.userChallengeVerifier !== void 0 && userChallengeOf(opts.userChallengeVerifier) !== userChallenge) {
+      throw new ValidationError("userChallengeVerifier \u043D\u044C \u0433\u0430\u0440\u044B\u043D \u04AF\u0441\u044D\u0433 \u0437\u0443\u0440\u0430\u0433\u0434\u0441\u0430\u043D userChallenge-\u0442\u044D\u0439 \u0442\u0430\u0430\u0440\u0441\u0430\u043D\u0433\u04AF\u0439");
+    }
     if (!interactionTypeUsed) throw new ValidationError("interactionTypeUsed \u0430\u043B\u0433\u0430");
     const { alg, hash } = this.algorithmOf(result, acsp.signatureAlgorithm, acsp.hashAlgorithm);
     const payload = buildAcspV2Payload({
@@ -498,6 +508,9 @@ var ResponseValidator = class {
     }
   }
 };
+function userChallengeOf(verifier) {
+  return createHash2("sha256").update(verifier, "utf8").digest("base64url");
+}
 function verifyPayloadSignature(payload, sigB64, key, alg, hash) {
   const sig = Buffer.from(sigB64, "base64");
   const h = nodeHash(hash);
@@ -694,6 +707,7 @@ export {
   randomChallenge,
   resolveBaseUrl,
   sha256Base64,
+  userChallengeOf,
   verifyPayloadSignature,
   verifyPrehashedSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gerege-systems/eid-mongolia-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "e-ID Mongolia Relying Party SDK — иргэнээр утсаар нь нэвтрэлт ба хууль ёсны цахим гарын үсэг (RP-API v3, Smart-ID нийцтэй).",
   "license": "MIT",
   "type": "module",
@@ -52,7 +52,7 @@
     "type": "git",
     "url": "git+https://github.com/gerege-systems/eid-mongolia-sdk.git"
   },
-  "homepage": "https://eidmongolia.mn/developers",
+  "homepage": "https://developer.eidmongolia.mn/",
   "bugs": {
     "url": "https://github.com/gerege-systems/eid-mongolia-sdk/issues"
   },