@gerege-systems/eid-mongolia-sdk 0.13.0 → 0.14.1

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, P as PersonBlock, b as PdfSessionBlock, c as RepresentationsResponse, A as AcspContext, F as FlowType, E as EidError } from './browser-C6JHm0lR.js';
-export { d as ApiError, e as AuthenticationError, f as DeviceLinkError, g as DeviceLinkInput, h as EndResult, i as ForbiddenError, j as HttpErrorInit, k as NavigatorLike, l as NetworkError, O as ON_BEHALF_ERROR_CODES, m as OnBehalfErrorCode, n as OpenOrShowQROptions, o as OrgResult, p as PdfDocumentStatus, q as PdfSigner, r as RETRYABLE_ERROR_CODES, s as Representation, t as ResponseTooLargeError, u as RetryableErrorCode, v as SessionFailedError, w as SessionState, x as SignatureAlgorithmParameters, y as SignatureProtocol, T as TokenCertSessionBlock, z as TokenCertStatus, V as ValidationError, B as deviceLink, G as isMobileUserAgent, J as openOrShowQR, K as parseRetryAfter } from './browser-C6JHm0lR.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, P as PersonBlock, b as PdfSessionBlock, c as RepresentationsResponse, A as AcspContext, F as FlowType } from './browser-CuMH5IVG.js';
+export { d as ApiError, e as AuthenticationError, f as DEFAULT_SIGN_SESSION_TTL_MS, g as DeviceLinkError, h as DeviceLinkInput, E as EidError, i as EndResult, j as ForbiddenError, k as HttpErrorInit, l as NavigatorLike, m as NetworkError, O as ON_BEHALF_ERROR_CODES, n as OnBehalfErrorCode, o as OpenOrShowQROptions, p as OrgResult, q as PdfDocumentStatus, r as PdfSigner, s as RETRYABLE_ERROR_CODES, t as Representation, u as ResponseTooLargeError, v as RetryableErrorCode, w as SessionFailedError, x as SessionState, y as SignContext, z as SignatureAlgorithmParameters, B as SignatureProtocol, T as TokenCertSessionBlock, G as TokenCertStatus, V as ValidationError, J as deviceLink, K as isMobileUserAgent, L as openOrShowQR, M as parseRetryAfter, Q as sessionExpiry } from './browser-CuMH5IVG.js';
 import { X509Certificate, KeyObject } from 'node:crypto';
 
 interface HttpConfig {
@@ -83,17 +83,23 @@ declare class AuthApi {
 
 interface SignDefaults {
     certificateLevel: CertificateLevel;
+    /** Sign / certificate-choice session-ий `expiresAt`-ийг тооцоолох хугацаа (мс); undefined = 600000. */
+    sessionTtlMs?: number;
 }
 interface SignOptions {
     certificateLevel?: CertificateLevel;
     /**
-     * Same-device App2App буцах URL. Query-д буцах browser-ийн hint нэмэхийг ЗӨВЛӨНӨ
+     * Same-device App2App/Web2App буцах URL (initialCallbackUrl). Device link-д Web2App/App2App холбоос зөвхөн үүнтэй
+     * session-д хүчинтэй; host нь RP-ийн callbackHosts-д байх ёстой. Query-д буцах browser-ийн hint нэмэхийг ЗӨВЛӨНӨ
      * (`?retScheme=` iOS / `?retPkg=` Android) — docs/RP_GEREGE_INTEGRATION.md §1.1b.
      */
     callbackUrl?: string;
     /** digest-ийн hash (default SHA-256). digest-ийг өөрөө бэлдсэн бол тааруулна (урт = hLen). */
     hashAlgorithm?: HashAlgorithm;
-    /** Гарын үсгийн алгоритм (default rsassa-pss; PKCS#1 v1.5 нь deprecated). */
+    /**
+     * Гарын үсгийн алгоритм (default rsassa-pss; PKCS#1 v1.5 нь deprecated). `digestForSigner` / `deviceLinkForSigner`-д
+     * default `sha256WithRSAEncryption` (PAdES/CMS).
+     */
     signatureAlgorithm?: SignatureAlgorithm;
     /**
      * Байгууллагын нэрийн өмнөөс гарын үсэг (docs/ORG_LOGIN.md) — байгууллагын ETSI
@@ -108,22 +114,72 @@ interface SignOptions {
      */
     fileName?: string;
 }
+/** Certificate-choice session-ий тохиргоо. */
+interface CertChoiceOptions {
+    certificateLevel?: CertificateLevel;
+}
+/**
+ * Гарын үсэг зурах төхөөрөмж — `validator.validateCertificateChoice`-ийн үр дүн (эсвэл түүнээс хадгалсан утга).
+ * `documentNumber` — гэрчилгээг сонгосон ЯГ ТЭР төхөөрөмж; `certChoiceSessionId` байвал linked sign.
+ */
+interface SignerRef {
+    documentNumber: string;
+    certChoiceSessionId?: string | null;
+}
 declare class SignApi {
     private readonly http;
     private readonly creds;
     private readonly defaults;
     constructor(http: Http, creds: RpCredentials, defaults: SignDefaults);
     private body;
-    private parse;
+    private notification;
+    private deviceLink;
     /**
      * Бэлэн digest-ээр push sign (РД/civil_id/ETSI). Баримт (PDF/файл)-ын байтын SHA-256
      * digest-ийг гаднаас бэлдэж өгнө — текст бус бинар баримтад тохиромжтой.
+     *
+     * ⚠️ Олон утастай иргэнд CA etsi-г ЭХНИЙ идэвхтэй төхөөрөмж рүү шийднэ. Гэрчилгээг урьдчилж мэдэх шаардлагатай бол
+     * (PAdES/CMS) {@link certificateChoiceByEtsi} → {@link digestForSigner}.
      */
     digestByEtsi(id: string, digestB64: string, interactions: Interaction[], opts?: SignOptions): Promise<NotificationSession>;
-    /** Бэлэн digest-ээр push sign — баримтын дугаараар (auth-аас гарсан documentNumber дээр). */
+    /** Бэлэн digest-ээр push sign — баримтын дугаараар (auth / certificate-choice-оос гарсан documentNumber дээр). */
     digestByDocument(documentNumber: string, digestB64: string, interactions: Interaction[], opts?: SignOptions): Promise<NotificationSession>;
     /** Текстийн SHA-256 digest-ийг дотроо тооцоод push sign (богино текст баримтад тохиромжтой). */
     textByEtsi(id: string, text: string, interactions: Interaction[], opts?: SignOptions): Promise<NotificationSession>;
+    /**
+     * QR / Web2App / App2App sign — тодорхой иргэн (РД/civil_id/ETSI). Холбоосыг backend-д
+     * `buildDeviceLink(deviceLinkInput(s, type, lang))`-ээр; Web2App/App2App-д `callbackUrl` заавал.
+     * `validateSign`-д `expectedFlowType` = харуулсан холбоосын төрөл.
+     */
+    deviceLinkByEtsi(id: string, digestB64: string, interactions: Interaction[], opts?: SignOptions): Promise<DeviceLinkSession>;
+    /** QR / Web2App / App2App sign — баримтын дугаараар (тодорхой төхөөрөмж). */
+    deviceLinkByDocument(documentNumber: string, digestB64: string, interactions: Interaction[], opts?: SignOptions): Promise<DeviceLinkSession>;
+    private certChoiceBody;
+    /**
+     * Push: иргэний (РД/civil_id/ETSI) утас руу гарын үсгийн гэрчилгээ сонгуулах хүсэлт (PIN-гүй). Үр дүнг
+     * `session.waitForResult` → `validator.validateCertificateChoice`. CERT эрх шаардана.
+     */
+    certificateChoiceByEtsi(id: string, opts?: CertChoiceOptions): Promise<NotificationSession>;
+    /**
+     * QR: иргэн хэн болохыг урьдчилж мэдэхгүй үед гэрчилгээ сонгуулах. CA-ийн certificate-choice хүсэлт
+     * initialCallbackUrl авдаггүй тул ЗӨВХӨН QR холбоос (`deviceLinkInput(s, "QR", lang)`). CERT эрх.
+     */
+    certificateChoiceDeviceLink(opts?: CertChoiceOptions): Promise<DeviceLinkSession>;
+    private signerBody;
+    /**
+     * Certificate-choice-оор сонгосон ЯГ ТЭР төхөөрөмж (`signer.documentNumber`) рүү push sign. Олон утастай иргэнд
+     * etsi-ээр эхлүүлбэл өөр утас (өөр гэрчилгээ) зурж, гэрчилгээг урьдчилж оруулсан CMS (PAdES signingCertificateV2)
+     * хүчингүй болдог — тиймээс digest-ийг ҮРГЭЛЖ documentNumber-аар зуруулна.
+     *
+     * `signer.certChoiceSessionId` байвал `/signature/notification/linked/{documentNumber}` (`linkedSessionID`), эс
+     * бөгөөс `/signature/notification/document/{documentNumber}`. Default `sha256WithRSAEncryption` + SHA-256 (digest =
+     * 32 байт DTBS); digest-ийн урт буруу бол хүсэлт явахгүй. Хариуг:
+     * `validator.validateSign(r, s.sign.digest, { hashAlgorithm: s.sign.hashAlgorithm, expectedAlgorithm:
+     * s.sign.signatureAlgorithm, expectedCertificate: signer.certificate, expectedFlowType: "Notification" })`.
+     */
+    digestForSigner(signer: SignerRef, digestB64: string, interactions: Interaction[], opts?: SignOptions): Promise<NotificationSession>;
+    /** {@link digestForSigner}-ийн QR / Web2App / App2App хувилбар: `/signature/device-link/document/{documentNumber}`. */
+    deviceLinkForSigner(signer: SignerRef, digestB64: string, interactions: Interaction[], opts?: SignOptions): Promise<DeviceLinkSession>;
 }
 
 /** RP-API-ийн session JSON-ийг SessionResult болгон задална (rpclient.ts-тэй ижил mapping). */
@@ -625,6 +681,34 @@ interface ValidateSignOptions {
      * тулгалт, криптограф баталгаа биш.
      */
     expectedFlowType?: FlowType;
+    /**
+     * Хүсэлтэд илгээсэн signatureAlgorithm (`s.sign.signatureAlgorithm`). Өгвөл хариуны RSA алгоритм ЯГ ИЖИЛ байх ёстой:
+     * `sha256WithRSAEncryption` хүссэн session-д `rsassa-pss` (эсвэл эсрэгээр) хариу → `ValidationError`. CA-ийн хуучин
+     * threshold-ECDSA credential хүссэнээс үл хамааран `ecdsa-with-SHA256` буцаадаг (түлхүүрийн төрөл гэрчилгээнд
+     * бэхлэгдсэн) — зөвхөн EC P-256 гэрчилгээ + SHA-256 үед зөвшөөрнө. Өгөөгүй бол хуучин зан (RSA алгоритмыг тулгахгүй).
+     */
+    expectedAlgorithm?: SignatureAlgorithm;
+    /**
+     * Урьдчилж мэдсэн гэрчилгээ (certificate-choice: `signer.certificate`). Өгвөл хариуны гэрчилгээ байт-ижил байх ёстой —
+     * өөр төхөөрөмж/гэрчилгээгээр зурсан бол (олон утастай иргэн) `ValidationError`.
+     */
+    expectedCertificate?: X509Certificate;
+}
+/**
+ * Certificate-choice-оор баталгаажсан гарын үсэг зурагч ({@link ResponseValidator.validateCertificateChoice}) —
+ * `sign.digestForSigner` / `sign.deviceLinkForSigner`-д өгнө.
+ */
+interface Signer {
+    /** Гэрчилгээг сонгосон ЯГ ТЭР төхөөрөмж — sign session-ийг ҮҮГЭЭР эхлүүлнэ. */
+    documentNumber: string;
+    /** Иргэний SIGN гэрчилгээ (KeyUsage contentCommitment). */
+    certificate: X509Certificate;
+    /** DER, стандарт base64. */
+    certificateDerB64: string;
+    certificateLevel: string;
+    parsedSubject: CertSubject;
+    /** Certificate-choice session (linked sign-ийн `linkedSessionID`). */
+    certChoiceSessionId: string | null;
 }
 /**
  * RevocationChecker — иргэний cert revoke хийгдсэн эсэхийг шалгах hook (OCSP/CRL).
@@ -728,6 +812,13 @@ declare class ResponseValidator {
      * @param opts — `hashAlgorithm` мөр (хуучин хэлбэр; default SHA-256) эсвэл {@link ValidateSignOptions}.
      */
     validateSign(result: SessionResult, digestB64: string, opts?: string | ValidateSignOptions): VerifiedSignature;
+    /**
+     * Certificate-choice session-ий хариуг шалгана: COMPLETE/OK (эс бөгөөс `SessionFailedError`), гэрчилгээ ба
+     * documentNumber байгаа, хугацаа, certLevel, зориулалт (гарын үсгийн — contentCommitment, `checkKeyUsage` үед), гинж,
+     * issuer. Энэ хариунд гарын үсэг БАЙХГҮЙ — иргэнийг таниагүй (нэвтрэлт биш); зөвхөн дараагийн sign session-ий
+     * гэрчилгээг урьдчилж мэдэхэд. `sessionId` — certificate-choice session.
+     */
+    validateCertificateChoice(result: SessionResult, sessionId?: string | null): Signer;
     /**
      * Хариуны signatureAlgorithm + hashAlgorithm-ийг RP-ийн хүссэнтэй ба иргэний түлхүүрийн төрөлтэй тулгана
      * (downgrade / alg confusion хаалт).
@@ -744,6 +835,10 @@ declare class ResponseValidator {
     private algorithmOf;
     /** state/endResult, cert байгаа эсэх, chain, validity, certLevel — нийтлэг шалгалт. */
     private precheck;
+    /** COMPLETE + OK; амжилтгүй endResult → SessionFailedError. */
+    private sessionDone;
+    /** Хариуны гэрчилгээ: documentNumber, задлалт, хугацаа, certLevel, зориулалт (protocol), гинж, issuer. */
+    private leafOf;
     /**
      * checkKeyUsage үед гэрчилгээний зориулалт протоколд тохирох эсэх (CA crypto/ca_profile.go): ACSP_V2 (auth) → KU
      * digitalSignature + EKU clientAuth (эсвэл anyExtendedKeyUsage); RAW_DIGEST_SIGNATURE (sign) → KU contentCommitment.
@@ -813,6 +908,12 @@ interface ClientConfig {
      * Анхдагч: илгээхгүй (сервер mn).
      */
     language?: string;
+    /**
+     * Sign / certificate-choice session-ий `expiresAt`-ийг тооцоолох хугацаа (мс). Анхдагч 600000
+     * ({@link DEFAULT_SIGN_SESSION_TTL_MS}, CA-ийн анхдагч); CA-ийн админ тохиргоог өөрчилсөн бол тааруул. CA session start
+     * хариунд хугацаа буцаадаггүй.
+     */
+    signSessionTtlMs?: number;
     /** Trust anchor (Root CA) — validator-д. Production-д ЗААВАЛ. */
     trust?: TrustConfig;
 }
@@ -829,6 +930,8 @@ declare class EidClient {
     readonly token: TokenApi;
     readonly session: SessionApi;
     readonly validator: ResponseValidator;
+    /** `credentials.rpName` — иргэний утсанд харагдах RP нэр. */
+    readonly rpName: string;
     constructor(cfg: ClientConfig);
 }
 
@@ -914,6 +1017,12 @@ interface BuildDeviceLinkInput {
  * @throws {DeviceLinkError} оролт буруу (base https биш, token/lang/secret хэлбэр, төрөлд хэрэгтэй талбар дутуу).
  */
 declare function buildDeviceLink(p: BuildDeviceLinkInput): string;
+/**
+ * Session start-ын хариу + хүсэлтийн утгуудаас {@link buildDeviceLink}-ийн оролт (auth: `acsp`, sign: `sign`, cert:
+ * `relyingPartyName`). `lang` — ISO 639-2 (`mon`, `eng`). Web2App/App2App-д session нь `callbackUrl`-тай эхэлсэн байх
+ * ёстой (эс бөгөөс `buildDeviceLink` DeviceLinkError). sessionToken/sessionSecret алга бол buildDeviceLink татгалзана.
+ */
+declare function deviceLinkInput(s: DeviceLinkSession, deviceLinkType: DeviceLinkType, lang: string): BuildDeviceLinkInput;
 interface QrDeviceLinkTickerOptions {
     /** Шинэчлэх давтамж (мс). Анхдагч 1000 — Smart-ID-ийн шаардлага. */
     intervalMs?: number;
@@ -927,156 +1036,155 @@ interface QrDeviceLinkTickerOptions {
  */
 declare function qrDeviceLinkTicker(input: Omit<BuildDeviceLinkInput, "deviceLinkType" | "now">, onLink: (link: string) => void, opts?: QrDeviceLinkTickerOptions): () => void;
 
-/** eID-ийн OIDC issuer (төгсгөлд `/` байхгүй). */
-declare const EID_OIDC_ISSUER = "https://login.eidmongolia.mn";
-/** `acr` утгууд — иргэний гэрчилгээний бодит түвшин. */
-declare const EID_ACR_QUALIFIED = "urn:eidmongolia:loa:qualified";
-declare const EID_ACR_ADVANCED = "urn:eidmongolia:loa:advanced";
-/**
- * OIDC алдааны код. Authorize redirect (RFC 6749 §4.1.2.1) ба token endpoint (§5.2)-ийн стандарт кодууд, мөн
- * SDK-ийн өөрийн шалгалтын кодууд:
- * - `state_mismatch` — callback-ийн `state` хадгалсантай таарсангүй (CSRF / өөр tab / cookie дууссан) → дахин эхлүүл;
- * - `invalid_callback` — `code` алга / хэт урт, эсвэл `iss` параметр өөр;
- * - `invalid_id_token` — id_token-ий гарын үсэг / iss / aud / exp / iat / nonce шалгалт унасан (ИТГЭХГҮЙ);
- * - `discovery_failed` — discovery/JWKS буруу эсвэл issuer таарахгүй.
- *
- * `access_denied` = иргэн татгалзсан, нэвтрэлтийн хугацаа дууссан, эсвэл гэрчилгээний шалгалт унасан → «дахин оролд».
- */
-type EidOidcErrorCode = "access_denied" | "login_required" | "invalid_request" | "invalid_scope" | "unauthorized_client" | "unsupported_response_type" | "request_not_supported" | "temporarily_unavailable" | "server_error" | "invalid_client" | "invalid_grant" | "unsupported_grant_type" | "state_mismatch" | "invalid_callback" | "invalid_id_token" | "discovery_failed";
-/**
- * OIDC урсгалын алдаа. `code`-оор салгана. `description` нь серверийн `error_description` — логт л,
- * хэрэглэгчид шууд харуулахгүй.
- */
-declare class EidOidcError extends EidError {
-    readonly code: EidOidcErrorCode;
-    readonly description?: string | undefined;
-    constructor(code: EidOidcErrorCode, message: string, description?: string | undefined);
-}
-interface EidOidcClientConfig {
-    /** RP UUID (`relyingPartyUUID`). */
-    clientId: string;
-    /** RP API secret (`rp_sk_…`) — зөвхөн backend-д. */
-    clientSecret: string;
-    /** Бүртгэлтэй redirect URI — тэмдэгт бүрээрээ таарах ёстой. */
-    redirectUri: string;
-    /** Анхдагч {@link EID_OIDC_ISSUER}. */
-    issuer?: string;
-    /** Анхдагч `"openid"`. Иргэний ETSI дугаар хэрэгтэй бол `"openid pnomn"` (RP-д `PNOMN` эрх). */
-    scope?: string;
-    /** HTTP timeout (мс), анхдагч 10000. */
-    timeoutMs?: number;
-    /**
-     * undici Dispatcher (mTLS client cert) — RP-API client-ийн `dispatcher`-тэй ижил:
-     * `new Agent({ connect: { cert, key } })`. Дамжуулсан бол OIDC-ийн бүх fetch-д хэрэглэнэ. Зөвхөн Node орчинд.
-     */
-    dispatcher?: unknown;
-    /**
-     * RFC 8705 §5: `true` бол code солих хүсэлт discovery-ийн `mtls_endpoint_aliases.token_endpoint` руу явна
-     * (`require_mtls`-тэй RP — `dispatcher`-т RP-ийн client cert заавал). Discovery-д alias байхгүй бол
-     * `token_endpoint` руу буцна; alias https биш бол `discovery_failed`. Анхдагч `false`.
-     */
-    useMtlsEndpointAliases?: boolean;
-    /** fetch орлуулагч (тест). */
-    fetchImpl?: typeof fetch;
-}
-interface EidOidcDiscovery {
-    issuer: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    jwks_uri: string;
-    /** RFC 8705 §5 — mTLS-тэй client-ийн endpoint-ууд (ж: `token_endpoint` → `https://rp.eidmongolia.mn/oauth2/token`). */
-    mtls_endpoint_aliases?: Record<string, string>;
-    [k: string]: unknown;
-}
-interface CreateAuthorizationOptions {
-    /** Энэ хүсэлтэд scope-ыг дарна. */
-    scope?: string;
-    /**
-     * `touch` (анхдагч) — утасны хөтчөөс шууд eID апп; `page` — үргэлж нэвтрэх хуудас (QR / push), ж: таблет киоск.
-     */
-    display?: "page" | "touch";
+/** Нэвтрэлтийн горим: desktop QR, регистрээр push, утасны хөтчөөс Web2App. */
+type EidLoginMode = "qr" | "push" | "web2app";
+/** Баталгаажсан иргэн — onSuccess-д. */
+interface EidLoginIdentity {
+    /** RP-API session-ий id (`sessionId`) — аудит, эсвэл энэ нэвтрэлтийг дараагийн алхамтай (гарын үсэг г.м.) холбоход. */
+    sessionId: string;
+    /** Гэрчилгээний SERIALNUMBER (`PNOMN-<иргэний дугаар>`). Хэрэглэгчийг ҮҮГЭЭР таньна (нэрээр биш). */
+    etsi: string;
+    /** `PNOMN-`-гүй иргэний дугаар (цифр); ETSI өөр хэлбэртэй бол null. */
+    civilId: string | null;
+    /** Гэрчилгээний нэр (латин): GIVENNAME / SURNAME, харуулах нэр. */
+    givenName: string | null;
+    surname: string | null;
+    name: string | null;
+    country: string | null;
+    /** Иргэний баримтын дугаар (`PNOMN-…-MOBILE-Q` г.м.) — `client.sign.*ByDocument`-аар ижил төхөөрөмж рүү гарын үсэг. */
+    documentNumber: string;
+    certificateLevel: string;
+    /** Иргэний нэвтрэлтийн гэрчилгээ (DER, base64) — validateAuth-аар гинж шалгагдсан. */
+    certificateDerB64: string;
+    /** Гарын үсэг зурагдсан урсгал: QR | Notification | Web2App. */
+    flowType: FlowType;
+    /** Session-ийн `person` блок (кирилл нэр г.м.) — гэрчилгээтэй таарсан үед л, эс бөгөөс null. */
+    person: PersonBlock | null;
 }
-/** RP-ийн хадгалах ёстой гүйлгээ — httpOnly cookie / server session-д (браузерийн JS-д биш). */
-interface EidAuthorization {
-    /** Хөтчийг энэ рүү 302. */
-    url: string;
-    state: string;
-    nonce: string;
-    codeVerifier: string;
+/** Серверт хадгалах нэвтрэлтийн төлөв (JSON-д хувирна). */
+interface EidLoginTx {
+    sessionId: string;
+    /** Cookie-ийн binding-ийн SHA-256 (hex) — түүхий утга хөтчид л. */
+    bindingHash: string;
+    mode: EidLoginMode;
+    expiresAt: number;
+    vc: string | null;
+    acsp: AcspContext;
+    /** QR/Web2App: холбоос угсрах материал. sessionSecret — ЗӨВХӨН серверт. */
+    link?: {
+        base: string;
+        token: string;
+        secret: string;
+        receivedAt: number;
+        lang: string;
+    };
 }
-/** createAuthorization-аас хадгалсан утгууд. */
-interface EidCallbackChecks {
-    state: string;
-    nonce: string;
-    codeVerifier: string;
+/** Төлөвийн сан. Анхдагч — процессын санах ой ({@link memoryLoginStore}); олон instance бол Redis г.м. */
+interface EidLoginStore {
+    get(sessionId: string): Promise<EidLoginTx | undefined> | EidLoginTx | undefined;
+    set(sessionId: string, tx: EidLoginTx, ttlMs: number): Promise<void> | void;
+    /** Устгана; байсан бол true. Амжилтыг нэг л удаа гаргахад ашиглана (атомар байх ёстой — Redis `DEL`). */
+    delete(sessionId: string): Promise<boolean> | boolean;
 }
-/** id_token-ий claim-ууд (`docs/OIDC.md` §4). */
-interface EidIdTokenClaims {
-    iss: string;
-    aud: string | string[];
-    azp?: string;
-    /** Pairwise — RP тус бүрд өөр, иргэнд тогтмол. Хэрэглэгчийг ҮҮГЭЭР таньна. */
-    sub: string;
-    exp: number;
-    iat: number;
-    nonce: string;
-    /** Иргэн баталгаажуулсан мөч (Unix сек). */
-    auth_time: number;
-    /** {@link EID_ACR_QUALIFIED} эсвэл {@link EID_ACR_ADVANCED}. */
-    acr: string;
-    /** Гэрчилгээний GIVENNAME — латин (ICAO, том үсэг). */
-    given_name: string;
-    /** Гэрчилгээний SURNAME (эцэг/эхийн нэр) — латин. */
-    family_name: string;
-    /** Нэр — кирилл (бүртгэлд байхгүй бол алга). */
-    given_name_mn?: string;
-    /** Эцэг/эхийн нэр — кирилл (бүртгэлд байхгүй бол алга). */
-    family_name_mn?: string;
-    /** `PNOMN-<иргэний дугаар>` — зөвхөн `pnomn` scope + `PNOMN` эрхтэй үед. */
-    pnomn?: string;
-    [k: string]: unknown;
+/** Нэг процессын санах ойн сан (TTL-тэй). Олон instance / serverless-д тохирохгүй. */
+declare function memoryLoginStore(): EidLoginStore;
+/** Хүсэлтийн хүрээ — onSuccess / rateLimit / onError-д. */
+interface EidLoginContext {
+    request: EidLoginRequest;
+    mode: EidLoginMode;
 }
-interface EidCallbackResult {
-    claims: EidIdTokenClaims;
-    idToken: string;
+/** onSuccess-ийн хариу: хаашаа явуулах, хөтчид буцаах өгөгдөл, нэмэлт header (ж: таны session-ийн Set-Cookie). */
+interface EidLoginSuccess {
+    /** Нэвтэрсний дараах хуудас (same-origin зам эсвэл URL). Callback (Web2App)-д анхдагч `successRedirect`. */
+    redirect?: string;
+    /** QR/push-д status хариунд `data` болж хөтчид очно (JSON). Нууц бүү оруул. */
+    data?: unknown;
+    headers?: Record<string, string | string[]>;
 }
-declare class EidOidcClient {
-    private readonly cfg;
-    readonly issuer: string;
-    private readonly scope;
-    private discovery?;
-    private jwks?;
-    constructor(cfg: EidOidcClientConfig);
-    /** Discovery document (1 цаг cache). `issuer` нь тохиргоотой яг таарах ёстой (OIDC Discovery §4.3). */
-    discover(): Promise<EidOidcDiscovery>;
-    private fetchDiscovery;
+interface EidLoginOptions {
+    client: EidClient;
+    /**
+     * RP-ийн session-ийг ЭНД үүсгэнэ (иргэн баталгаажсан). Хэрэглэгчийг `identity.etsi`-ээр таньж, шинэ session
+     * (session fixation-аас сэргийлж шинэ id) үүсгээд Set-Cookie-г `headers`-ээр буцаа.
+     */
+    onSuccess: (identity: EidLoginIdentity, ctx: EidLoginContext) => Promise<EidLoginSuccess | void> | EidLoginSuccess | void;
+    /**
+     * Web2App буцах https URL — host нь RP-ийн `callbackHosts`-д, зам нь ЗААВАЛ `/auth/eid/callback`. Өгөөгүй бол
+     * утасны хөтчийн урсгал (`mode=web2app`) 400 — QR/push л ажиллана.
+     */
+    callbackUrl?: string;
+    /** Callback амжилттай болоход (onSuccess redirect өгөөгүй бол). Анхдагч "/". */
+    successRedirect?: string;
+    /** Callback амжилтгүй болоход — `?eid_error=<код>` нэмэгдэнэ. Анхдагч "/". */
+    failureRedirect?: string;
+    /** Утсанд харагдах текст (≤60). Анхдагч «<rpName>-д нэвтрэх». */
+    displayText?: string;
+    certificateLevel?: CertificateLevel;
+    /** Нэвтрэлтийн хугацаа (мс). Анхдагч 120 000. */
+    ttlMs?: number;
+    /** Status-ийн нэг дуудлагад eID-ийг хүлээх (мс). Анхдагч 1000. */
+    pollMs?: number;
+    store?: EidLoginStore;
+    cookie?: {
+        name?: string;
+        path?: string;
+        secure?: boolean;
+        domain?: string;
+    };
     /**
-     * Authorize URL + санамсаргүй state / nonce / PKCE codeVerifier. RP буцаасан `state`, `nonce`, `codeVerifier`-ийг
-     * хөтчийн session-тэй холбож (httpOnly cookie эсвэл server session) хадгалаад хөтчийг `url` руу 302 хийнэ.
+     * Хязгаарлалт: `start:<ip>` (ip мэдэгдэж байвал) ба `push:<idCode>` түлхүүрээр дуудагдана; false → 429.
+     * Анхдагч: push-д нэг дугаарт 60 секундэд 3 (санах ойд) — хохирогчийн утсыг мэдэгдлээр дарахаас (MFA fatigue).
      */
-    createAuthorization(opts?: CreateAuthorizationOptions): Promise<EidAuthorization>;
+    rateLimit?: (key: string) => boolean | Promise<boolean>;
     /**
-     * redirect_uri руу ирсэн callback-ийг шийднэ: state тулгах → `error` бол {@link EidOidcError} → code солих →
-     * id_token шалгах. `input` — бүтэн callback URL, харьцангуй зам (`/cb?code=…`) эсвэл query (`URLSearchParams` / `code=…&state=…`); зөвхөн query-г уншина.
-     * Амжилтгүй бүх тохиолдолд {@link EidOidcError} (эсвэл {@link NetworkError}) шиднэ.
+     * `handle(Request)`-ийн клиент IP (`start:<ip>` хязгаарт). Web-standard `Request`-д IP байдаггүй тул эсвэл энийг, эсвэл
+     * {@link EidLoginOptions.trustProxy}-г өг; аль нь ч үгүй бол IP-ээр хязгаарлахгүй (анхны дуудлагад onError-оор анхааруулна).
+     * Ж: Vercel/Next `req.headers.get("x-real-ip")`, Bun `server.requestIP(req)?.address`, Deno `info.remoteAddr.hostname`.
      */
-    handleCallback(input: string | URL | URLSearchParams, checks: EidCallbackChecks): Promise<EidCallbackResult>;
-    /** `POST token_endpoint` (client_secret_basic, RFC 6749 §2.3.1) → id_token. */
-    private exchangeCode;
-    /** Code солих endpoint: `useMtlsEndpointAliases` + alias байвал alias (RFC 8705 §5), эс бөгөөс `token_endpoint`. */
-    private tokenEndpoint;
+    getClientIp?: (req: Request) => string | undefined | null;
     /**
-     * id_token шалгана: JWKS (`kid`, cache; танихгүй kid → нэг удаа дахин татна) ES256 гарын үсэг, `iss`, `aud`
-     * (= clientId; олон aud бол `azp`), `exp`/`iat` (±60 сек), `nonce`. Амжилтгүй бол `invalid_id_token`.
+     * Итгэмжит reverse proxy-ийн ард: IP-г `X-Forwarded-For`-оос (байхгүй бол `X-Real-IP`) уншина.
+     * `true` — XFF-ийн хамгийн зүүн утга (бүх hop итгэмжит; зөвхөн proxy нь клиентийн XFF-ийг дарж бичдэг бол);
+     * тоо `n` — баруунаас n дахь утга (n = таны итгэмжит proxy-ийн тоо; nginx нэг бол 1). Proxy-гүй үед бүү асаа —
+     * header-ийг клиент хуурамчаар илгээж хязгаарыг тойрно. `handleRequest`-д `req.ip` өгөөгүй үед ч хэрэглэгдэнэ.
      */
-    verifyIdToken(idToken: string, opts: {
-        nonce: string;
-    }): Promise<EidIdTokenClaims>;
-    private keys;
-    private getJson;
-    private fetch;
+    trustProxy?: boolean | number;
+    /** Дотоод алдаа (eID API, store). Анхдагч console.error (мессеж л). */
+    onError?: (err: unknown, ctx: EidLoginContext) => void;
 }
-/** PKCE S256: `BASE64URL(SHA-256(ASCII(code_verifier)))` (RFC 7636 §4.2). */
-declare function pkceChallenge(codeVerifier: string): Promise<string>;
+/** Framework-аас хамааралгүй хүсэлт (Express: `req.headers`, `req.body`, `req.ip`). */
+interface EidLoginRequest {
+    method: string;
+    /** Зам + query (`/auth/eid/status?…`) эсвэл бүтэн URL. */
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** POST-ийн задалсан JSON (Express `express.json()`), эсвэл түүхий мөр. */
+    body?: unknown;
+    ip?: string;
+}
+interface EidLoginResponse {
+    status: number;
+    headers: Record<string, string | string[]>;
+    body: string;
+}
+interface EidLogin {
+    /** Сүүлийн замын хэсгээр (`start` | `status` | `callback`) чиглүүлнэ. */
+    handleRequest(req: EidLoginRequest): Promise<EidLoginResponse>;
+    /** Web-standard (Next.js App Router, Hono, Bun, Deno). */
+    handle(req: Request): Promise<Response>;
+}
+/**
+ * Итгэмжит proxy-ийн header-ээс клиент IP (`trustProxy`-ийн дүрэм). XFF-д хангалттай hop байхгүй бол хамгийн зүүн
+ * утгыг (proxy-д ирсэн анхны) биш undefined буцаана — хуурамч header-ээр тойрохоос.
+ */
+declare function forwardedClientIp(headers: EidLoginRequest["headers"], trustProxy: boolean | number): string | undefined;
+/** `callbackUrl`-д буцах хөтчийн hint (`retScheme` iOS / `retPkg` Android) нэмнэ; танихгүй бол хэвээр. */
+declare function withReturnHint(callbackUrl: string, userAgent: string): string;
+/**
+ * «eID-ээр нэвтрэх»-ийн backend handler-ууд. Нэг instance-ийг модулийн түвшинд үүсгээд бүх хүсэлтэд ашиглана.
+ *
+ * @throws Error `callbackUrl` https биш эсвэл зам нь `/auth/eid/callback` биш бол.
+ */
+declare function createEidLogin(opts: EidLoginOptions): EidLogin;
 
-export { AcspContext, type AcspV2Params, type ActivityCounts, type ActivityItem, type ActivityQuery, AuthApi, type AuthDefaults, type AuthOptions, type BuildDeviceLinkInput, CITIZEN_ISSUING_CA_SKI, type CertCounts, type CertSubject, CertificateLevel, type ClientConfig, type CreateAuthorizationOptions, DEFAULT_BASE_URL, DEFAULT_PDF_MAX_BYTES, DEFAULT_PDF_TIMEOUT_MS, DeviceLinkSession, type DeviceLinkSessionType, type DeviceLinkType, EID_ACR_ADVANCED, EID_ACR_QUALIFIED, EID_OIDC_ISSUER, type EidAuthorization, type EidCallbackChecks, type EidCallbackResult, EidClient, EidError, type EidIdTokenClaims, EidOidcClient, type EidOidcClientConfig, type EidOidcDiscovery, EidOidcError, type EidOidcErrorCode, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, OrganizationApi, PdfApi, type PdfDefaults, type PdfPrepareInput, type PdfPrepareSession, PdfSessionBlock, type PdfSignerRef, type PdfTokenPrepareInput, type PdfTokenPrepareSession, type PersonActivity, PersonApi, PersonBlock, type PersonCertificate, type PersonCertificates, type PersonChild, type PersonChildren, type PersonDevice, type PersonDevices, type PersonSummary, type QrDeviceLinkTickerOptions, RepresentationsResponse, ResponseValidator, type RevocationChecker, type RevocationOutcome, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, TokenApi, type TokenAuthChallenge, type TokenAuthResult, type TokenCertInput, type TokenCertItem, type TokenCertResult, type TokenCertStart, type TokenIdentity, type TokenLimit, type TokenOrganization, type TrustConfig, type ValidateAuthOptions, type ValidateSignOptions, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, buildDeviceLink, interactionsToBase64, parseSessionResult, parseSubject, personMatchesCertificate, pkceChallenge, qrDeviceLinkTicker, randomChallenge, resolveBaseUrl, sha256Base64, tokenAuthDigest, tokenLimitOf, userChallengeOf, verifyPayloadSignature, verifyPrehashedSignature, verifyTokenCertificates };
+export { AcspContext, type AcspV2Params, type ActivityCounts, type ActivityItem, type ActivityQuery, AuthApi, type AuthDefaults, type AuthOptions, type BuildDeviceLinkInput, CITIZEN_ISSUING_CA_SKI, type CertChoiceOptions, type CertCounts, type CertSubject, CertificateLevel, type ClientConfig, DEFAULT_BASE_URL, DEFAULT_PDF_MAX_BYTES, DEFAULT_PDF_TIMEOUT_MS, DeviceLinkSession, type DeviceLinkSessionType, type DeviceLinkType, EidClient, type EidLogin, type EidLoginContext, type EidLoginIdentity, type EidLoginMode, type EidLoginOptions, type EidLoginRequest, type EidLoginResponse, type EidLoginStore, type EidLoginSuccess, type EidLoginTx, FlowType, HashAlgorithm, Http, type HttpConfig, Interaction, NotificationSession, OrganizationApi, PdfApi, type PdfDefaults, type PdfPrepareInput, type PdfPrepareSession, PdfSessionBlock, type PdfSignerRef, type PdfTokenPrepareInput, type PdfTokenPrepareSession, type PersonActivity, PersonApi, PersonBlock, type PersonCertificate, type PersonCertificates, type PersonChild, type PersonChildren, type PersonDevice, type PersonDevices, type PersonSummary, type QrDeviceLinkTickerOptions, RepresentationsResponse, ResponseValidator, type RevocationChecker, type RevocationOutcome, type RevocationStatus, RpCredentials, SessionApi, SessionResult, SignApi, type SignDefaults, type SignOptions, SignatureAlgorithm, type Signer, type SignerRef, TokenApi, type TokenAuthChallenge, type TokenAuthResult, type TokenCertInput, type TokenCertItem, type TokenCertResult, type TokenCertStart, type TokenIdentity, type TokenLimit, type TokenOrganization, type TrustConfig, type ValidateAuthOptions, type ValidateSignOptions, type VerifiedIdentity, type VerifiedSignature, acspV2Digest, buildAcspV2Payload, buildDeviceLink, createEidLogin, deviceLinkInput, forwardedClientIp, interactionsToBase64, memoryLoginStore, parseSessionResult, parseSubject, personMatchesCertificate, qrDeviceLinkTicker, randomChallenge, resolveBaseUrl, sha256Base64, tokenAuthDigest, tokenLimitOf, userChallengeOf, verifyPayloadSignature, verifyPrehashedSignature, verifyTokenCertificates, withReturnHint };