@gerege-systems/eid-mongolia-sdk 0.4.1 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@
 (authentication) ба хууль ёсны цахим гарын үсэг (qualified signature) хийлгэх Node.js/TypeScript сан.
 RP-API v3, Smart-ID нийцтэй. Бүрэн баримт: <https://developer.eidmongolia.mn/>.
 
-> ⚠️ Зөвхөн **backend**-д ажиллана (`@gerege-systems/eid-mongolia-sdk/browser`-ийн device-link туслахаас бусад).
+> ⚠️ Зөвхөн **backend**-д ажиллана (`@gerege-systems/eid-mongolia-sdk/browser`-ийн legacy device-link туслахаас бусад).
 > API secret (`rp_sk_…`) браузер/гар утсанд хэзээ ч задлахгүй.
 
 ## Суулгах
@@ -67,41 +67,86 @@ const sig = eid.validator.validateSign(result, digest); // digest-ийн эср
 console.log(sig.signatureValueB64, sig.subject);
 ```
 
-## 4. Ижил төхөөрөмж (App2App / Web2App)
+## 4. QR ба ижил төхөөрөмж — device link v3
 
-Иргэн RP-ийн сайт/аппыг **eID апптай ижил утсан дээр** нээсэн бол QR уншуулах боломжгүй — device-link
-session эхлүүлээд холбоосоор аппыг шууд нээнэ. Desktop дээр ижил холбоосыг QR болгож харуулна.
+Иргэн өөр төхөөрөмжийн дэлгэц дээрх **QR**-ийг утсаараа уншина, эсвэл RP-ийн сайт/аппыг eID апптай **ижил
+утсан** дээр нээсэн бол товчоор аппыг нээнэ (**Web2App** — утасны браузер, **App2App** — RP-ийн апп). Холбоосыг
+ЗӨВХӨН RP backend `buildDeviceLink`-ээр угсарна (Smart-ID RP-API v3 «dynamic link»):
 
-```ts
-// backend — session эхлүүлээд браузерт ЗӨВХӨН sessionId, vc, deviceLinkBase-ийг өгнө (secret/token биш)
-const s = await eid.auth.deviceLinkAnonymous([{ type: "displayTextAndPIN", displayText60: "Хаан Банк-д нэвтрэх" }]);
-res.json({ sessionId: s.sessionId, vc: s.vc, deviceLinkBase: s.deviceLinkBase }); // s.acsp-ийг серверт хадгал
+```
+QR:      {deviceLinkBase}?deviceLinkType=QR&elapsedSeconds={E}&sessionToken={T}&sessionType=auth&version=1.0&lang=mon&authCode={A}
+Web2App: {deviceLinkBase}?deviceLinkType=Web2App&sessionToken={T}&sessionType=auth&version=1.0&lang=mon&authCode={A}
+```
 
-// холбоос: `${deviceLinkBase}?sessionId=<uuid>&vc=<5 орон>` (ж: https://ca.eidmongolia.mn/dl?...)
-import { deviceLink } from "@gerege-systems/eid-mongolia-sdk";
-const link = deviceLink(s);
+- `authCode = BASE64URL(HMAC-SHA256(sessionSecret, …))` — холбоосын төрөл, session, RP-ийн challenge, callback-ийг
+  хамгаална. Сервер төрлийг session-д бэхэлж, гарын үсгийн `flowType` = тэр төрөл (хуурамчлах боломжгүй).
+- **QR секунд тутам шинэчлэгдэнэ** (`elapsedSeconds = floor(now − receivedAt)`); ~20 секундээс хуучин QR-ийг
+  сервер татгалзана → SMS/мессенжерээр дамжуулсан холбоос ажиллахгүй.
+- `sessionToken`, **`sessionSecret`-ийг зөвхөн backend-д** хадгална — браузер/апп руу ХЭЗЭЭ Ч бүү гарга.
+  Браузер QR-ийн бэлэн холбоосыг backend endpoint-оос секунд тутам авна.
+- QR ба товч хоёуланг нэг хуудсанд харуулах бол НЭГ session (`callbackUrl`-тай) эхлүүлж хоёр холбоос угсарна.
+  Web2App/App2App нь `callbackUrl`-тай session-д л хүчинтэй.
+- Гэрээ: [developer.eidmongolia.mn](https://developer.eidmongolia.mn/) ба ca-eidmongolia-mn `docs/DEVICE_LINK_V3.md`.
+
+```ts
+import { buildDeviceLink, type DeviceLinkSession } from "@gerege-systems/eid-mongolia-sdk";
+
+// backend — session эхлүүлээд бүх хариуг СЕРВЕРТ хадгална (sessionToken/sessionSecret/receivedAt/acsp)
+const s = await eid.auth.deviceLinkAnonymous(
+  [{ type: "displayTextAndPIN", displayText60: "Хаан Банк-д нэвтрэх" }],
+  { callbackUrl: "https://bank.example.mn/eid/callback?state=…" }, // товч харуулах бол
+);
+store.put(s.sessionId, s);
+res.json({ sessionId: s.sessionId, vc: s.vc }); // браузерт ЗӨВХӨН эдгээр
+
+const link = (s: DeviceLinkSession, type: "QR" | "Web2App" | "App2App") =>
+  buildDeviceLink({
+    deviceLinkBase: s.deviceLinkBase!,
+    deviceLinkType: type,
+    sessionToken: s.sessionToken!,
+    sessionSecret: s.sessionSecret!,
+    sessionType: "auth",
+    lang: "mon",
+    receivedAt: s.receivedAt, // SDK хариу хүлээн авсан мөчийг тэмдэглэнэ
+    rpChallenge: s.acsp!.rpChallenge,
+    relyingPartyName: s.acsp!.relyingPartyName,
+    interactions: s.acsp!.interactions,
+    initialCallbackUrl: s.acsp!.initialCallbackUrl, // QR-д authCode-д орохгүй
+  });
+
+// GET /eid/qr?sessionId=…  → браузер 1 секунд тутам дуудаж QR-ийг дахин зурна (Cache-Control: no-store)
+app.get("/eid/qr", (req, res) => {
+  const s = store.get(String(req.query.sessionId)); // өөрийн browser session-д хамаарахыг шалга
+  if (!s) return res.sendStatus(404);
+  res.set("Cache-Control", "no-store").json({ link: link(s, "QR") });
+});
+// гар утсанд: товчны href = link(s, "Web2App") (нэг удаа, шинэчлэхгүй)
 ```
 
+SSE/WebSocket-оор түлхэх бол `qrDeviceLinkTicker(input, (link) => send(link))` — шууд нэг, дараа нь секунд тутам
+холбоос гаргаж, буцаасан функцээр зогсооно (session дуусах/клиент салахад заавал).
+
+**Харуулсан төрлөө заавал тулга (relay хаалт).** `expectedFlowType` = RP-ийн харуулсан холбоосын төрөл:
+
 ```ts
-// браузер — node:*-гүй тусдаа entry
-import { openOrShowQR } from "@gerege-systems/eid-mongolia-sdk/browser";
-
-button.onclick = () => {
-  // session-ийг урьдчилж авсан байна — энд await хийхгүй
-  const how = openOrShowQR(session, { showQR: (link) => renderQr(link) }); // "opened" | "qr"
-  showVc(session.vc); // иргэний утсан дээрх кодтой тулгуулна (ПИН биш)
-};
-// дараа нь backend: eid.session.waitForResult(sessionId) → eid.validator.validateAuth(result, s.acsp)
+// QR хуудас → poll-оор дууссан үр дүн
+eid.validator.validateAuth(result, s.acsp, { expectedFlowType: "QR" });
+
+// Web2App/App2App товч → апп callback URL-д `userChallengeVerifier` нэмж буцна
+eid.validator.validateAuth(result, s.acsp, {
+  expectedFlowType: "Web2App", // RP-ийн апп дахь товч бол "App2App"
+  userChallengeVerifier: callbackQuery.get("userChallengeVerifier") ?? undefined,
+});
+// push (notificationBy*) → "Notification"
 ```
 
-- Гар утас (iOS/Android, desktop UA илгээдэг iPadOS ч) бол `location.assign(link)` — Universal Link / App Link
-  аппыг нээнэ; бусад үед `showQR(link)`. Илрүүлэгчийг `isMobile: boolean | () => boolean`-оор солино
-  (анхдагч `isMobileUserAgent()`).
-- **Click handler дотроос шууд дууд.** iOS урт async гинжийн (fetch → await → …) дараах навигацийг
-  хэрэглэгчийн үйлдэл гэж үзэхгүй, Universal Link-ийг алгасаж `/dl` хуудсыг нээдэг — тэр хуудас
-  «Аппаар нээх» товч ба App Store / Play холбоосыг санал болгоно (апп суугаагүй үед ч мөн).
-- `deviceLinkBase` хариунд байхгүй, `sessionId` UUID биш, `vc` 5 орон биш бол `DeviceLinkError` — холбоосыг
-  таахгүй. Апп руу custom scheme-ээр шууд бүү холбо — зөвхөн `deviceLink()`-ийн https холбоос.
+QR ба товч хоёуланг харуулсан хуудсанд: callback-аар ирсэн үр дүнг `Web2App`/`App2App`-аар, poll-оор ирснийг
+`QR`-аар шалга (товчоор нээгдсэн session зөвхөн callback-аар дуусна).
+
+> ⚠️ **Шилжилт.** eID Mongolia 2.2.3 (build 59)-өөс өмнөх апп v3 холбоосыг танихгүй. RP-ийн v3 рүү шилжилтийг
+> тохиргооны унтраалгаар (анхдагч legacy) хийж, build 59 store-д гарч `min_version=59` тавигдах мөчид асаана.
+> Legacy `deviceLink(session)` (`{deviceLinkBase}?sessionId=…&vc=…`) болон `/browser` entry-ийн
+> `openOrShowQR` **deprecated** — тэр мөчөөс сервер статик холбоосыг хүлээн авахгүй.
 
 ## Аюулгүй байдал — яагаад `validator` заавал
 
@@ -113,7 +158,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` шиднэ — хариунд **итгэхгүй**.
@@ -128,7 +174,7 @@ OK ирж болзошгүй. Иймд `ResponseValidator`:
 | `ValidationError` | cert chain/signature/level шалгалт бүтэлгүйтсэн |
 | `ApiError` | бусад HTTP алдаа (`.status`, `.body`) |
 | `NetworkError` | timeout/сүлжээ |
-| `DeviceLinkError` | device-link холбоос угсрах боломжгүй (`deviceLinkBase` байхгүй, sessionId/vc буруу) |
+| `DeviceLinkError` | device-link холбоос угсрах боломжгүй (`deviceLinkBase` https биш, token/secret/lang хэлбэр, төрөлд хэрэгтэй талбар дутуу) |
 
 ## mTLS (eIDAS qualified орчин)
 

package/dist/{browser-BS8JwSQk.d.cts → browser-PhjcbuAN.d.cts}

@@ -73,14 +73,17 @@ interface NotificationSession {
     /** Auth session-д validator-т өгөх контекст (sign session-д undefined). */
     acsp?: AcspContext;
 }
-/** Device-link (QR/App2App) session. Иргэн QR уншиж эсвэл deeplink дарж нэгдэнэ. */
+/**
+ * Device-link (QR/Web2App/App2App) session. Иргэн QR уншиж эсвэл товч дарж нэгдэнэ.
+ * `sessionToken`, `sessionSecret`-ийг ЗӨВХӨН backend-д хадгална — браузер руу бүү гарга.
+ */
 interface DeviceLinkSession {
     sessionId: string;
     sessionToken: string | null;
     sessionSecret: string | null;
     /**
      * QR/App2App/Web2App холбоосын суурь URL (ж: `https://ca.eidmongolia.mn/dl`). Холбоосыг
-     * өөрөө угсрахгүй — {@link deviceLink}-ээр.
+     * өөрөө угсрахгүй — backend-д {@link buildDeviceLink}-ээр (v3).
      */
     deviceLinkBase: string | null;
     /**
@@ -90,6 +93,12 @@ interface DeviceLinkSession {
     vc: string | null;
     rpChallenge: string;
     acsp?: AcspContext;
+    /**
+     * RP backend энэ хариуг хүлээн авсан мөч (ms epoch, SDK `Date.now()`-оор тэмдэглэнэ) — v3 QR-ийн
+     * `elapsedSeconds`-ийн эх ({@link buildDeviceLink} `receivedAt`). sessionToken/sessionSecret-тэй хамт
+     * ЗӨВХӨН backend-д хадгална.
+     */
+    receivedAt: number;
 }
 /** Session poll-ийн нэгтгэсэн үр дүн (validator-т орох түүхий материал). */
 interface SessionResult {
@@ -145,6 +154,11 @@ type DeviceLinkInput = Pick<DeviceLinkSession, "sessionId" | "vc" | "deviceLinkB
  * Device-link session-ийн холбоос: `${deviceLinkBase}?sessionId=<uuid>&vc=<код>`.
  * QR-д эсвэл «eID аппаар нээх» товчинд тавина.
  *
+ * @deprecated Legacy статик холбоос — холбоосын төрөл (QR/Web2App) хамгаалагдаагүй, relay-д нээлттэй.
+ * eID Mongolia 2.2.3 (build 59) гармагц сервер унтраана (`EID_DEVICE_LINK_LEGACY=false`). Шинэ код
+ * backend-д {@link buildDeviceLink} (v3) ашиглана; build 59-өөс өмнөх апп v3 холбоосыг танихгүй тул
+ * RP v3 рүү шилжих нь тохиргооны унтраалгаар (анхдагч legacy) хийгдэнэ.
+ *
  * @throws {DeviceLinkError} deviceLinkBase байхгүй / http(s) биш, sessionId UUID биш, vc 5 орон биш.
  */
 declare function deviceLink(session: DeviceLinkInput): string;

package/dist/{browser-BS8JwSQk.d.ts → browser-PhjcbuAN.d.ts}

@@ -73,14 +73,17 @@ interface NotificationSession {
     /** Auth session-д validator-т өгөх контекст (sign session-д undefined). */
     acsp?: AcspContext;
 }
-/** Device-link (QR/App2App) session. Иргэн QR уншиж эсвэл deeplink дарж нэгдэнэ. */
+/**
+ * Device-link (QR/Web2App/App2App) session. Иргэн QR уншиж эсвэл товч дарж нэгдэнэ.
+ * `sessionToken`, `sessionSecret`-ийг ЗӨВХӨН backend-д хадгална — браузер руу бүү гарга.
+ */
 interface DeviceLinkSession {
     sessionId: string;
     sessionToken: string | null;
     sessionSecret: string | null;
     /**
      * QR/App2App/Web2App холбоосын суурь URL (ж: `https://ca.eidmongolia.mn/dl`). Холбоосыг
-     * өөрөө угсрахгүй — {@link deviceLink}-ээр.
+     * өөрөө угсрахгүй — backend-д {@link buildDeviceLink}-ээр (v3).
      */
     deviceLinkBase: string | null;
     /**
@@ -90,6 +93,12 @@ interface DeviceLinkSession {
     vc: string | null;
     rpChallenge: string;
     acsp?: AcspContext;
+    /**
+     * RP backend энэ хариуг хүлээн авсан мөч (ms epoch, SDK `Date.now()`-оор тэмдэглэнэ) — v3 QR-ийн
+     * `elapsedSeconds`-ийн эх ({@link buildDeviceLink} `receivedAt`). sessionToken/sessionSecret-тэй хамт
+     * ЗӨВХӨН backend-д хадгална.
+     */
+    receivedAt: number;
 }
 /** Session poll-ийн нэгтгэсэн үр дүн (validator-т орох түүхий материал). */
 interface SessionResult {
@@ -145,6 +154,11 @@ type DeviceLinkInput = Pick<DeviceLinkSession, "sessionId" | "vc" | "deviceLinkB
  * Device-link session-ийн холбоос: `${deviceLinkBase}?sessionId=<uuid>&vc=<код>`.
  * QR-д эсвэл «eID аппаар нээх» товчинд тавина.
  *
+ * @deprecated Legacy статик холбоос — холбоосын төрөл (QR/Web2App) хамгаалагдаагүй, relay-д нээлттэй.
+ * eID Mongolia 2.2.3 (build 59) гармагц сервер унтраана (`EID_DEVICE_LINK_LEGACY=false`). Шинэ код
+ * backend-д {@link buildDeviceLink} (v3) ашиглана; build 59-өөс өмнөх апп v3 холбоосыг танихгүй тул
+ * RP v3 рүү шилжих нь тохиргооны унтраалгаар (анхдагч legacy) хийгдэнэ.
+ *
  * @throws {DeviceLinkError} deviceLinkBase байхгүй / http(s) биш, sessionId UUID биш, vc 5 орон биш.
  */
 declare function deviceLink(session: DeviceLinkInput): string;

package/dist/browser.d.cts

@@ -1 +1 @@
-export { d as DeviceLinkError, e as DeviceLinkInput, D as DeviceLinkSession, E as EidError, h as NavigatorLike, O as OpenOrShowQROptions, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-BS8JwSQk.cjs';
+export { d as DeviceLinkError, e as DeviceLinkInput, D as DeviceLinkSession, E as EidError, h as NavigatorLike, O as OpenOrShowQROptions, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-PhjcbuAN.cjs';

package/dist/browser.d.ts

@@ -1 +1 @@
-export { d as DeviceLinkError, e as DeviceLinkInput, D as DeviceLinkSession, E as EidError, h as NavigatorLike, O as OpenOrShowQROptions, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-BS8JwSQk.js';
+export { d as DeviceLinkError, e as DeviceLinkInput, D as DeviceLinkSession, E as EidError, h as NavigatorLike, O as OpenOrShowQROptions, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-PhjcbuAN.js';

package/dist/index.cjs

@@ -37,14 +37,17 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   acspV2Digest: () => acspV2Digest,
   buildAcspV2Payload: () => buildAcspV2Payload,
+  buildDeviceLink: () => buildDeviceLink,
   deviceLink: () => deviceLink,
   interactionsToBase64: () => interactionsToBase64,
   isMobileUserAgent: () => isMobileUserAgent,
   openOrShowQR: () => openOrShowQR,
   parseSessionResult: () => parseSessionResult,
+  qrDeviceLinkTicker: () => qrDeviceLinkTicker,
   randomChallenge: () => randomChallenge,
   resolveBaseUrl: () => resolveBaseUrl,
   sha256Base64: () => sha256Base64,
+  userChallengeOf: () => userChallengeOf,
   verifyPayloadSignature: () => verifyPayloadSignature,
   verifyPrehashedSignature: () => verifyPrehashedSignature
 });
@@ -223,7 +226,8 @@ var AuthApi = class {
       deviceLinkBase: r.deviceLinkBase != null ? String(r.deviceLinkBase) : null,
       vc: vc != null ? String(vc) : null,
       rpChallenge: acsp.rpChallenge,
-      acsp
+      acsp,
+      receivedAt: Date.now()
     };
   }
   /** Push — РД/иргэний дугаар/ETSI-ээр (сервер төрлийг таьна). Иргэний утас руу мэдэгдэл очно. */
@@ -415,7 +419,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 +427,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 +584,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);
@@ -782,6 +799,76 @@ function openOrShowQR(session, opts) {
   opts.showQR(link);
   return "qr";
 }
+
+// src/devicelinkv3.ts
+var import_node_crypto3 = require("crypto");
+var TYPES = ["QR", "Web2App", "App2App"];
+var PROTOCOL = { auth: "ACSP_V2", sign: "RAW_DIGEST_SIGNATURE", cert: "" };
+var TOKEN_RE = /^[A-Za-z0-9_-]+$/;
+var LANG_RE = /^[a-z]{3}$/;
+var STD_B64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+var b642 = (s) => Buffer.from(s, "utf8").toString("base64");
+var ms = (t) => t instanceof Date ? t.getTime() : t;
+function fail(msg) {
+  throw new DeviceLinkError(`buildDeviceLink: ${msg}`);
+}
+function buildDeviceLink(p) {
+  const base = p.deviceLinkBase?.trim();
+  if (!base) fail("deviceLinkBase \u0445\u043E\u043E\u0441\u043E\u043D \u2014 device-link session-\u0438\u0439 \u0445\u0430\u0440\u0438\u0443\u0433 \u0448\u0430\u043B\u0433\u0430");
+  let u;
+  try {
+    u = new URL(base);
+  } catch {
+    fail(`deviceLinkBase \u0431\u0443\u0440\u0443\u0443 URL: ${base}`);
+  }
+  if (u.protocol !== "https:" || /[?#]/.test(base)) fail("deviceLinkBase \u043D\u044C query/fragment-\u0433\u04AF\u0439 https URL \u0431\u0430\u0439\u0445 \u0451\u0441\u0442\u043E\u0439");
+  if (!TYPES.includes(p.deviceLinkType)) fail(`deviceLinkType ${String(p.deviceLinkType)} (QR | Web2App | App2App)`);
+  if (!(p.sessionType in PROTOCOL)) fail(`sessionType ${String(p.sessionType)} (auth | sign | cert)`);
+  if (!p.sessionToken || !TOKEN_RE.test(p.sessionToken)) fail("sessionToken \u0445\u044D\u043B\u0431\u044D\u0440 \u0431\u0443\u0440\u0443\u0443");
+  if (!LANG_RE.test(p.lang ?? "")) fail("lang \u043D\u044C ISO 639-2 \u0433\u0443\u0440\u0432\u0430\u043D \u0436\u0438\u0436\u0438\u0433 \u04AF\u0441\u044D\u0433 (mon, eng)");
+  if (!p.sessionSecret || !STD_B64_RE.test(p.sessionSecret)) fail("sessionSecret \u0441\u0442\u0430\u043D\u0434\u0430\u0440\u0442 Base64 (padding-\u0442\u044D\u0439) \u0431\u0438\u0448");
+  let challenge = "";
+  if (p.sessionType === "auth") {
+    if (!p.rpChallenge) fail("auth session-\u0434 rpChallenge \u0437\u0430\u0430\u0432\u0430\u043B");
+    challenge = p.rpChallenge;
+  } else if (p.sessionType === "sign") {
+    if (!p.digest) fail("sign session-\u0434 digest \u0437\u0430\u0430\u0432\u0430\u043B");
+    challenge = p.digest;
+  } else if (p.rpChallenge || p.digest) {
+    fail("cert session-\u0434 rpChallenge/digest \u0431\u0430\u0439\u0445\u0433\u04AF\u0439");
+  }
+  const qr = p.deviceLinkType === "QR";
+  const callback = qr ? "" : p.initialCallbackUrl ?? "";
+  if (!qr && !callback) fail(`${p.deviceLinkType} \u0445\u043E\u043B\u0431\u043E\u043E\u0441 initialCallbackUrl-\u0442\u0430\u0439 session-\u0434 \u043B \u0445\u04AF\u0447\u0438\u043D\u0442\u044D\u0439`);
+  let elapsed = "";
+  if (qr) {
+    if (p.receivedAt == null) fail("QR \u0445\u043E\u043B\u0431\u043E\u043E\u0441\u043E\u043D\u0434 receivedAt \u0437\u0430\u0430\u0432\u0430\u043B");
+    const e = Math.max(0, Math.floor((ms(p.now ?? Date.now()) - ms(p.receivedAt)) / 1e3));
+    if (!Number.isSafeInteger(e)) fail("receivedAt/now \u0431\u0443\u0440\u0443\u0443");
+    elapsed = `&elapsedSeconds=${e}`;
+  }
+  const unprotected = `${base}?deviceLinkType=${p.deviceLinkType}${elapsed}&sessionToken=${p.sessionToken}&sessionType=${p.sessionType}&version=1.0&lang=${p.lang}`;
+  const payload = [
+    p.schemeName ?? "smart-id",
+    PROTOCOL[p.sessionType],
+    challenge,
+    b642(p.relyingPartyName),
+    b642(p.brokeredRpName ?? ""),
+    p.interactions ?? "",
+    callback,
+    unprotected
+  ].join("|");
+  const authCode = (0, import_node_crypto3.createHmac)("sha256", Buffer.from(p.sessionSecret, "base64")).update(payload, "utf8").digest("base64url");
+  return `${unprotected}&authCode=${authCode}`;
+}
+function qrDeviceLinkTicker(input, onLink, opts) {
+  const clock = opts?.clock ?? Date.now;
+  const tick = () => onLink(buildDeviceLink({ ...input, deviceLinkType: "QR", now: clock() }));
+  tick();
+  const t = setInterval(tick, opts?.intervalMs ?? 1e3);
+  t.unref?.();
+  return () => clearInterval(t);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiError,
@@ -801,14 +888,17 @@ function openOrShowQR(session, opts) {
   ValidationError,
   acspV2Digest,
   buildAcspV2Payload,
+  buildDeviceLink,
   deviceLink,
   interactionsToBase64,
   isMobileUserAgent,
   openOrShowQR,
   parseSessionResult,
+  qrDeviceLinkTicker,
   randomChallenge,
   resolveBaseUrl,
   sha256Base64,
+  userChallengeOf,
   verifyPayloadSignature,
   verifyPrehashedSignature
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { R as RpCredentials, C as CertificateLevel, I as Interaction, S as SignatureAlgorithm, H as HashAlgorithm, N as NotificationSession, D as DeviceLinkSession, a as SessionResult, A as AcspContext, F as FlowType } from './browser-BS8JwSQk.cjs';
-export { b as ApiError, c as AuthenticationError, d as DeviceLinkError, e as DeviceLinkInput, E as EidError, f as EndResult, g as ForbiddenError, h as NavigatorLike, i as NetworkError, O as OpenOrShowQROptions, j as SessionFailedError, k as SessionState, l as SignatureAlgorithmParameters, m as SignatureProtocol, V as ValidationError, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-BS8JwSQk.cjs';
+import { R as RpCredentials, C as CertificateLevel, I as Interaction, S as SignatureAlgorithm, H as HashAlgorithm, N as NotificationSession, D as DeviceLinkSession, a as SessionResult, A as AcspContext, F as FlowType } from './browser-PhjcbuAN.cjs';
+export { b as ApiError, c as AuthenticationError, d as DeviceLinkError, e as DeviceLinkInput, E as EidError, f as EndResult, g as ForbiddenError, h as NavigatorLike, i as NetworkError, O as OpenOrShowQROptions, j as SessionFailedError, k as SessionState, l as SignatureAlgorithmParameters, m as SignatureProtocol, V as ValidationError, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-PhjcbuAN.cjs';
 import { X509Certificate, KeyObject } from 'node:crypto';
 
 interface HttpConfig {
@@ -131,6 +131,32 @@ declare class SessionApi {
     }): Promise<SessionResult>;
 }
 
+/**
+ * validateAuth-ийн нэмэлт шалгалт — RP ЯМАР урсгал эхлүүлснээ мэддэг тул түүнийг тулгана
+ * (device-link relay хаалт).
+ */
+interface ValidateAuthOptions {
+    /**
+     * RP-ийн ХАРУУЛСАН device link-ийн төрөл (эсвэл push). Өгвөл гарын үсэг зурагдсан ACSP_V2 `flowType`
+     * ЯГ ИЖИЛ байх ёстой: QR хуудас → "QR"; гар утасны браузер дахь товч → "Web2App"; RP-ийн апп дахь
+     * товч → "App2App"; push → "Notification". "Web2App"/"App2App" үед `userChallengeVerifier` ЗААВАЛ.
+     *
+     * v3 холбоосонд (`buildDeviceLink`) төрөл нь authCode-оор хамгаалагдсан — сервер түүнийг session-д
+     * бэхэлж, `flowType` = тэр төрөл. Нэг хуудсанд QR ба товч хоёуланг харуулсан бол: callback-аар
+     * (verifier-тэй) ирсэн үр дүнг "Web2App"/"App2App"-аар, poll-оор ирснийг "QR"-аар шалга — товчоор
+     * нээгдсэн session poll замаар OK болохгүй, callback-аар л дуусна.
+     *
+     * ⚠️ Legacy `/dl?sessionId&vc` холбоосонд төрөл хамгаалагдаагүй — build 59 + `min_version=59` хүртэл
+     * энэ шалгалт relay-ээс бүрэн хамгаалахгүй.
+     */
+    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 +223,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 +251,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 +316,71 @@ 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 };
+/** Холбоосын төрөл — апп гарын үсгийн `flowType`-д яг энэ утгыг зурна (authCode-оор хамгаалагдсан). */
+type DeviceLinkType = "QR" | "Web2App" | "App2App";
+/** Session-ий урсгал: auth = нэвтрэлт, sign = гарын үсэг, cert = гэрчилгээ сонгох. */
+type DeviceLinkSessionType = "auth" | "sign" | "cert";
+interface BuildDeviceLinkInput {
+    /** Session start хариуны `deviceLinkBase` (ж: `https://ca.eidmongolia.mn/dl`). */
+    deviceLinkBase: string;
+    deviceLinkType: DeviceLinkType;
+    /** Session start хариуны `sessionToken` — ЯГ ХЭВЭЭР. */
+    sessionToken: string;
+    /** Session start хариуны `sessionSecret` (стандарт Base64, padding-тэй). ЗӨВХӨН backend-д. */
+    sessionSecret: string;
+    sessionType: DeviceLinkSessionType;
+    /** ISO 639-2 гурван жижиг үсэг (`mon`, `eng`) — зөвхөн `/dl` fallback хуудасны хэл. */
+    lang: string;
+    /**
+     * RP backend session start хариуг ХҮЛЭЭН АВСАН мөч (өөрийн цагаар; ms epoch эсвэл Date).
+     * QR-д заавал (`elapsedSeconds = floor(now − receivedAt)`); Web2App/App2App-д ашиглагдахгүй.
+     */
+    receivedAt?: number | Date;
+    /** Одоогийн цаг (тест/тогтмол цагт). Анхдагч `Date.now()`. */
+    now?: number | Date;
+    /** auth: RP-ийн илгээсэн `rpChallenge` (base64 ТЕКСТЭЭРЭЭ). */
+    rpChallenge?: string;
+    /** sign: RP-ийн илгээсэн `digest` (base64 текст). */
+    digest?: string;
+    /** Session start хүсэлтэд илгээсэн ЯГ тэр `relyingPartyName`. */
+    relyingPartyName: string;
+    /** auth/sign: хүсэлтэд илгээсэн interactions-ийн base64 МӨР (дахин serialize хийхгүй). cert: `""`. */
+    interactions: string;
+    /**
+     * Хүсэлтэд илгээсэн түүхий `initialCallbackUrl`. Web2App/App2App-д заавал; QR-д authCode-д ОРОХГҮЙ
+     * (`""`), тиймээс QR ба товчинд ижил session-ий утгыг өгч болно.
+     */
+    initialCallbackUrl?: string;
+    /** Анхдагч `"smart-id"` (серверийн EID_ACSP_SCHEME_NAME). */
+    schemeName?: string;
+    /** Broker RP-ийн нэр. eID broker дэмждэггүй — анхдагч `""`. */
+    brokeredRpName?: string;
+}
+/**
+ * Device link v3-ийг бүтнээр нь угсарна (`…&authCode=…`). Цэвэр функц — `now`-оос өөр гаднын төлөвгүй.
+ *
+ * ```
+ * QR:      {base}?deviceLinkType=QR&elapsedSeconds={E}&sessionToken={T}&sessionType={S}&version=1.0&lang={L}&authCode={A}
+ * Web2App: {base}?deviceLinkType=Web2App&sessionToken={T}&sessionType={S}&version=1.0&lang={L}&authCode={A}
+ * ```
+ *
+ * QR холбоос ~20 секундэд хүчингүй болдог тул секунд тутам дахин дуудаж харуул ({@link qrDeviceLinkTicker}).
+ * Web2App/App2App холбоосыг нэг удаа угсарна.
+ *
+ * @throws {DeviceLinkError} оролт буруу (base https биш, token/lang/secret хэлбэр, төрөлд хэрэгтэй талбар дутуу).
+ */
+declare function buildDeviceLink(p: BuildDeviceLinkInput): string;
+interface QrDeviceLinkTickerOptions {
+    /** Шинэчлэх давтамж (мс). Анхдагч 1000 — Smart-ID-ийн шаардлага. */
+    intervalMs?: number;
+    /** Цагийн эх үүсвэр (тест). Анхдагч `Date.now`. */
+    clock?: () => number;
+}
+/**
+ * Node сервер (SSE/WebSocket)-т: QR холбоосыг шууд нэг удаа, дараа нь секунд тутам `onLink`-ээр гаргана.
+ * Буцаах функцээр зогсооно (session дуусах/клиент салахад заавал дууд). Timer процессыг барихгүй (unref).
+ * HTTP poll ашиглавал энэ хэрэггүй — хүсэлт бүрд {@link buildDeviceLink}-ийг `deviceLinkType: "QR"`-оор дууд.
+ */
+declare function qrDeviceLinkTicker(input: Omit<BuildDeviceLinkInput, "deviceLinkType" | "now">, onLink: (link: string) => void, opts?: QrDeviceLinkTickerOptions): () => void;
+
+export { AcspContext, type AcspV2Params, AuthApi, type AuthDefaults, type AuthOptions, type BuildDeviceLinkInput, CertificateLevel, type ClientConfig, DEFAULT_BASE_URL, DeviceLinkSession, type DeviceLinkSessionType, type DeviceLinkType, EidClient, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, type QrDeviceLinkTickerOptions, ResponseValidator, type RevocationChecker, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, type TrustConfig, type ValidateAuthOptions, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, buildDeviceLink, interactionsToBase64, parseSessionResult, qrDeviceLinkTicker, randomChallenge, resolveBaseUrl, sha256Base64, userChallengeOf, verifyPayloadSignature, verifyPrehashedSignature };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RpCredentials, C as CertificateLevel, I as Interaction, S as SignatureAlgorithm, H as HashAlgorithm, N as NotificationSession, D as DeviceLinkSession, a as SessionResult, A as AcspContext, F as FlowType } from './browser-BS8JwSQk.js';
-export { b as ApiError, c as AuthenticationError, d as DeviceLinkError, e as DeviceLinkInput, E as EidError, f as EndResult, g as ForbiddenError, h as NavigatorLike, i as NetworkError, O as OpenOrShowQROptions, j as SessionFailedError, k as SessionState, l as SignatureAlgorithmParameters, m as SignatureProtocol, V as ValidationError, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-BS8JwSQk.js';
+import { R as RpCredentials, C as CertificateLevel, I as Interaction, S as SignatureAlgorithm, H as HashAlgorithm, N as NotificationSession, D as DeviceLinkSession, a as SessionResult, A as AcspContext, F as FlowType } from './browser-PhjcbuAN.js';
+export { b as ApiError, c as AuthenticationError, d as DeviceLinkError, e as DeviceLinkInput, E as EidError, f as EndResult, g as ForbiddenError, h as NavigatorLike, i as NetworkError, O as OpenOrShowQROptions, j as SessionFailedError, k as SessionState, l as SignatureAlgorithmParameters, m as SignatureProtocol, V as ValidationError, n as deviceLink, o as isMobileUserAgent, p as openOrShowQR } from './browser-PhjcbuAN.js';
 import { X509Certificate, KeyObject } from 'node:crypto';
 
 interface HttpConfig {
@@ -131,6 +131,32 @@ declare class SessionApi {
     }): Promise<SessionResult>;
 }
 
+/**
+ * validateAuth-ийн нэмэлт шалгалт — RP ЯМАР урсгал эхлүүлснээ мэддэг тул түүнийг тулгана
+ * (device-link relay хаалт).
+ */
+interface ValidateAuthOptions {
+    /**
+     * RP-ийн ХАРУУЛСАН device link-ийн төрөл (эсвэл push). Өгвөл гарын үсэг зурагдсан ACSP_V2 `flowType`
+     * ЯГ ИЖИЛ байх ёстой: QR хуудас → "QR"; гар утасны браузер дахь товч → "Web2App"; RP-ийн апп дахь
+     * товч → "App2App"; push → "Notification". "Web2App"/"App2App" үед `userChallengeVerifier` ЗААВАЛ.
+     *
+     * v3 холбоосонд (`buildDeviceLink`) төрөл нь authCode-оор хамгаалагдсан — сервер түүнийг session-д
+     * бэхэлж, `flowType` = тэр төрөл. Нэг хуудсанд QR ба товч хоёуланг харуулсан бол: callback-аар
+     * (verifier-тэй) ирсэн үр дүнг "Web2App"/"App2App"-аар, poll-оор ирснийг "QR"-аар шалга — товчоор
+     * нээгдсэн session poll замаар OK болохгүй, callback-аар л дуусна.
+     *
+     * ⚠️ Legacy `/dl?sessionId&vc` холбоосонд төрөл хамгаалагдаагүй — build 59 + `min_version=59` хүртэл
+     * энэ шалгалт relay-ээс бүрэн хамгаалахгүй.
+     */
+    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 +223,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 +251,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 +316,71 @@ 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 };
+/** Холбоосын төрөл — апп гарын үсгийн `flowType`-д яг энэ утгыг зурна (authCode-оор хамгаалагдсан). */
+type DeviceLinkType = "QR" | "Web2App" | "App2App";
+/** Session-ий урсгал: auth = нэвтрэлт, sign = гарын үсэг, cert = гэрчилгээ сонгох. */
+type DeviceLinkSessionType = "auth" | "sign" | "cert";
+interface BuildDeviceLinkInput {
+    /** Session start хариуны `deviceLinkBase` (ж: `https://ca.eidmongolia.mn/dl`). */
+    deviceLinkBase: string;
+    deviceLinkType: DeviceLinkType;
+    /** Session start хариуны `sessionToken` — ЯГ ХЭВЭЭР. */
+    sessionToken: string;
+    /** Session start хариуны `sessionSecret` (стандарт Base64, padding-тэй). ЗӨВХӨН backend-д. */
+    sessionSecret: string;
+    sessionType: DeviceLinkSessionType;
+    /** ISO 639-2 гурван жижиг үсэг (`mon`, `eng`) — зөвхөн `/dl` fallback хуудасны хэл. */
+    lang: string;
+    /**
+     * RP backend session start хариуг ХҮЛЭЭН АВСАН мөч (өөрийн цагаар; ms epoch эсвэл Date).
+     * QR-д заавал (`elapsedSeconds = floor(now − receivedAt)`); Web2App/App2App-д ашиглагдахгүй.
+     */
+    receivedAt?: number | Date;
+    /** Одоогийн цаг (тест/тогтмол цагт). Анхдагч `Date.now()`. */
+    now?: number | Date;
+    /** auth: RP-ийн илгээсэн `rpChallenge` (base64 ТЕКСТЭЭРЭЭ). */
+    rpChallenge?: string;
+    /** sign: RP-ийн илгээсэн `digest` (base64 текст). */
+    digest?: string;
+    /** Session start хүсэлтэд илгээсэн ЯГ тэр `relyingPartyName`. */
+    relyingPartyName: string;
+    /** auth/sign: хүсэлтэд илгээсэн interactions-ийн base64 МӨР (дахин serialize хийхгүй). cert: `""`. */
+    interactions: string;
+    /**
+     * Хүсэлтэд илгээсэн түүхий `initialCallbackUrl`. Web2App/App2App-д заавал; QR-д authCode-д ОРОХГҮЙ
+     * (`""`), тиймээс QR ба товчинд ижил session-ий утгыг өгч болно.
+     */
+    initialCallbackUrl?: string;
+    /** Анхдагч `"smart-id"` (серверийн EID_ACSP_SCHEME_NAME). */
+    schemeName?: string;
+    /** Broker RP-ийн нэр. eID broker дэмждэггүй — анхдагч `""`. */
+    brokeredRpName?: string;
+}
+/**
+ * Device link v3-ийг бүтнээр нь угсарна (`…&authCode=…`). Цэвэр функц — `now`-оос өөр гаднын төлөвгүй.
+ *
+ * ```
+ * QR:      {base}?deviceLinkType=QR&elapsedSeconds={E}&sessionToken={T}&sessionType={S}&version=1.0&lang={L}&authCode={A}
+ * Web2App: {base}?deviceLinkType=Web2App&sessionToken={T}&sessionType={S}&version=1.0&lang={L}&authCode={A}
+ * ```
+ *
+ * QR холбоос ~20 секундэд хүчингүй болдог тул секунд тутам дахин дуудаж харуул ({@link qrDeviceLinkTicker}).
+ * Web2App/App2App холбоосыг нэг удаа угсарна.
+ *
+ * @throws {DeviceLinkError} оролт буруу (base https биш, token/lang/secret хэлбэр, төрөлд хэрэгтэй талбар дутуу).
+ */
+declare function buildDeviceLink(p: BuildDeviceLinkInput): string;
+interface QrDeviceLinkTickerOptions {
+    /** Шинэчлэх давтамж (мс). Анхдагч 1000 — Smart-ID-ийн шаардлага. */
+    intervalMs?: number;
+    /** Цагийн эх үүсвэр (тест). Анхдагч `Date.now`. */
+    clock?: () => number;
+}
+/**
+ * Node сервер (SSE/WebSocket)-т: QR холбоосыг шууд нэг удаа, дараа нь секунд тутам `onLink`-ээр гаргана.
+ * Буцаах функцээр зогсооно (session дуусах/клиент салахад заавал дууд). Timer процессыг барихгүй (unref).
+ * HTTP poll ашиглавал энэ хэрэггүй — хүсэлт бүрд {@link buildDeviceLink}-ийг `deviceLinkType: "QR"`-оор дууд.
+ */
+declare function qrDeviceLinkTicker(input: Omit<BuildDeviceLinkInput, "deviceLinkType" | "now">, onLink: (link: string) => void, opts?: QrDeviceLinkTickerOptions): () => void;
+
+export { AcspContext, type AcspV2Params, AuthApi, type AuthDefaults, type AuthOptions, type BuildDeviceLinkInput, CertificateLevel, type ClientConfig, DEFAULT_BASE_URL, DeviceLinkSession, type DeviceLinkSessionType, type DeviceLinkType, EidClient, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, type QrDeviceLinkTickerOptions, ResponseValidator, type RevocationChecker, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, type TrustConfig, type ValidateAuthOptions, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, buildDeviceLink, interactionsToBase64, parseSessionResult, qrDeviceLinkTicker, randomChallenge, resolveBaseUrl, sha256Base64, userChallengeOf, verifyPayloadSignature, verifyPrehashedSignature };

package/dist/index.js

@@ -151,7 +151,8 @@ var AuthApi = class {
       deviceLinkBase: r.deviceLinkBase != null ? String(r.deviceLinkBase) : null,
       vc: vc != null ? String(vc) : null,
       rpChallenge: acsp.rpChallenge,
-      acsp
+      acsp,
+      receivedAt: Date.now()
     };
   }
   /** Push — РД/иргэний дугаар/ETSI-ээр (сервер төрлийг таьна). Иргэний утас руу мэдэгдэл очно. */
@@ -343,7 +344,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 +352,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 +509,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);
@@ -668,6 +682,76 @@ var EidClient = class {
     this.validator = new ResponseValidator(cfg.trust ?? {});
   }
 };
+
+// src/devicelinkv3.ts
+import { createHmac } from "crypto";
+var TYPES = ["QR", "Web2App", "App2App"];
+var PROTOCOL = { auth: "ACSP_V2", sign: "RAW_DIGEST_SIGNATURE", cert: "" };
+var TOKEN_RE = /^[A-Za-z0-9_-]+$/;
+var LANG_RE = /^[a-z]{3}$/;
+var STD_B64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+var b642 = (s) => Buffer.from(s, "utf8").toString("base64");
+var ms = (t) => t instanceof Date ? t.getTime() : t;
+function fail(msg) {
+  throw new DeviceLinkError(`buildDeviceLink: ${msg}`);
+}
+function buildDeviceLink(p) {
+  const base = p.deviceLinkBase?.trim();
+  if (!base) fail("deviceLinkBase \u0445\u043E\u043E\u0441\u043E\u043D \u2014 device-link session-\u0438\u0439 \u0445\u0430\u0440\u0438\u0443\u0433 \u0448\u0430\u043B\u0433\u0430");
+  let u;
+  try {
+    u = new URL(base);
+  } catch {
+    fail(`deviceLinkBase \u0431\u0443\u0440\u0443\u0443 URL: ${base}`);
+  }
+  if (u.protocol !== "https:" || /[?#]/.test(base)) fail("deviceLinkBase \u043D\u044C query/fragment-\u0433\u04AF\u0439 https URL \u0431\u0430\u0439\u0445 \u0451\u0441\u0442\u043E\u0439");
+  if (!TYPES.includes(p.deviceLinkType)) fail(`deviceLinkType ${String(p.deviceLinkType)} (QR | Web2App | App2App)`);
+  if (!(p.sessionType in PROTOCOL)) fail(`sessionType ${String(p.sessionType)} (auth | sign | cert)`);
+  if (!p.sessionToken || !TOKEN_RE.test(p.sessionToken)) fail("sessionToken \u0445\u044D\u043B\u0431\u044D\u0440 \u0431\u0443\u0440\u0443\u0443");
+  if (!LANG_RE.test(p.lang ?? "")) fail("lang \u043D\u044C ISO 639-2 \u0433\u0443\u0440\u0432\u0430\u043D \u0436\u0438\u0436\u0438\u0433 \u04AF\u0441\u044D\u0433 (mon, eng)");
+  if (!p.sessionSecret || !STD_B64_RE.test(p.sessionSecret)) fail("sessionSecret \u0441\u0442\u0430\u043D\u0434\u0430\u0440\u0442 Base64 (padding-\u0442\u044D\u0439) \u0431\u0438\u0448");
+  let challenge = "";
+  if (p.sessionType === "auth") {
+    if (!p.rpChallenge) fail("auth session-\u0434 rpChallenge \u0437\u0430\u0430\u0432\u0430\u043B");
+    challenge = p.rpChallenge;
+  } else if (p.sessionType === "sign") {
+    if (!p.digest) fail("sign session-\u0434 digest \u0437\u0430\u0430\u0432\u0430\u043B");
+    challenge = p.digest;
+  } else if (p.rpChallenge || p.digest) {
+    fail("cert session-\u0434 rpChallenge/digest \u0431\u0430\u0439\u0445\u0433\u04AF\u0439");
+  }
+  const qr = p.deviceLinkType === "QR";
+  const callback = qr ? "" : p.initialCallbackUrl ?? "";
+  if (!qr && !callback) fail(`${p.deviceLinkType} \u0445\u043E\u043B\u0431\u043E\u043E\u0441 initialCallbackUrl-\u0442\u0430\u0439 session-\u0434 \u043B \u0445\u04AF\u0447\u0438\u043D\u0442\u044D\u0439`);
+  let elapsed = "";
+  if (qr) {
+    if (p.receivedAt == null) fail("QR \u0445\u043E\u043B\u0431\u043E\u043E\u0441\u043E\u043D\u0434 receivedAt \u0437\u0430\u0430\u0432\u0430\u043B");
+    const e = Math.max(0, Math.floor((ms(p.now ?? Date.now()) - ms(p.receivedAt)) / 1e3));
+    if (!Number.isSafeInteger(e)) fail("receivedAt/now \u0431\u0443\u0440\u0443\u0443");
+    elapsed = `&elapsedSeconds=${e}`;
+  }
+  const unprotected = `${base}?deviceLinkType=${p.deviceLinkType}${elapsed}&sessionToken=${p.sessionToken}&sessionType=${p.sessionType}&version=1.0&lang=${p.lang}`;
+  const payload = [
+    p.schemeName ?? "smart-id",
+    PROTOCOL[p.sessionType],
+    challenge,
+    b642(p.relyingPartyName),
+    b642(p.brokeredRpName ?? ""),
+    p.interactions ?? "",
+    callback,
+    unprotected
+  ].join("|");
+  const authCode = createHmac("sha256", Buffer.from(p.sessionSecret, "base64")).update(payload, "utf8").digest("base64url");
+  return `${unprotected}&authCode=${authCode}`;
+}
+function qrDeviceLinkTicker(input, onLink, opts) {
+  const clock = opts?.clock ?? Date.now;
+  const tick = () => onLink(buildDeviceLink({ ...input, deviceLinkType: "QR", now: clock() }));
+  tick();
+  const t = setInterval(tick, opts?.intervalMs ?? 1e3);
+  t.unref?.();
+  return () => clearInterval(t);
+}
 export {
   ApiError,
   AuthApi,
@@ -686,14 +770,17 @@ export {
   ValidationError,
   acspV2Digest,
   buildAcspV2Payload,
+  buildDeviceLink,
   deviceLink,
   interactionsToBase64,
   isMobileUserAgent,
   openOrShowQR,
   parseSessionResult,
+  qrDeviceLinkTicker,
   randomChallenge,
   resolveBaseUrl,
   sha256Base64,
+  userChallengeOf,
   verifyPayloadSignature,
   verifyPrehashedSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gerege-systems/eid-mongolia-sdk",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "e-ID Mongolia Relying Party SDK — иргэнээр утсаар нь нэвтрэлт ба хууль ёсны цахим гарын үсэг (RP-API v3, Smart-ID нийцтэй).",
   "license": "MIT",
   "type": "module",