feat: Implement ML-DSA-65 validation and enhance REALITY settings

- Added validation functions for ML-DSA-65 seed and verify keys, ensuring correct lengths and encoding.
- Updated XRayConfig to enforce pairing rules for mldsa65Seed and mldsa65Verify, raising errors for mismatches.
- Enhanced inbound dialog schema to include ML-DSA-65 fields and validation logic.
- Updated frontend components to display hints and validation messages related to ML-DSA-65 settings.
- Added tests for ML-DSA-65 validation to ensure robustness and correctness.

Author: x0sina

app/core/xray.py

@@ -9,7 +9,7 @@
 
 from app.models.core import CoreType
 from app.models.protocol import ProxyProtocol
-from app.utils.crypto import get_cert_SANs, get_x25519_public_key
+from app.utils.crypto import get_cert_SANs, get_x25519_public_key, validate_mldsa65_seed, validate_mldsa65_verify
 
 
 def _protocols_from_inbounds_by_tag(inbounds_by_tag: dict[str, dict]) -> frozenset[ProxyProtocol]:
@@ -238,7 +238,27 @@ def _handle_reality_settings(self, tls_settings: dict, settings: dict, inbound_t
         except Exception:
             settings["spx"] = ""
 
-        settings["mldsa65Verify"] = tls_settings.get("mldsa65Verify")
+        mldsa65_seed = tls_settings.get("mldsa65Seed")
+        mldsa65_verify = tls_settings.get("mldsa65Verify")
+        seed_set = isinstance(mldsa65_seed, str) and bool(mldsa65_seed.strip())
+        verify_set = isinstance(mldsa65_verify, str) and bool(mldsa65_verify.strip())
+
+        if seed_set or verify_set:
+            # Client pqv without a matching server seed causes silent REALITY auth failure.
+            if verify_set and not seed_set:
+                raise ValueError(
+                    f"mldsa65Verify is set without mldsa65Seed in realitySettings of {inbound_tag}. "
+                    "Set both (matching pair) or clear both."
+                )
+            if seed_set:
+                validate_mldsa65_seed(mldsa65_seed)
+            if verify_set:
+                settings["mldsa65Verify"] = validate_mldsa65_verify(mldsa65_verify)
+            else:
+                # Seed-only is valid (server signs; clients without pqv still connect).
+                settings["mldsa65Verify"] = None
+        else:
+            settings["mldsa65Verify"] = None
 
     def _handle_network_settings(self, net: str, net_settings: dict, settings: dict, inbound_tag: str):
         """Handle network-specific settings."""

app/subscription/clash.py

@@ -248,7 +248,6 @@ def _mihomo_download_settings_from_xray(self, download_settings: dict) -> dict:
             "reality-opts": {
                 "public-key": tls_settings.get("publicKey"),
                 "short-id": tls_settings.get("shortId") or "",
-                "support-x25519mlkem768": bool(tls_settings.get("mldsa65Verify")),
             }
             if security == "reality" and tls_settings.get("publicKey")
             else None,
@@ -310,10 +309,10 @@ def _apply_mihomo_download_tls(self, node: dict, tls_config: TLSConfig):
             node["client-fingerprint"] = tls_config.fingerprint
 
         if tls_config.tls == "reality" and tls_config.reality_public_key:
+            # Do not map mldsa65Verify → support-x25519mlkem768; those are different PQ features.
             node["reality-opts"] = {
                 "public-key": tls_config.reality_public_key,
                 "short-id": tls_config.reality_short_id or "",
-                "support-x25519mlkem768": bool(tls_config.mldsa65_verify),
             }
 
     @staticmethod
@@ -614,10 +613,10 @@ def _apply_tls(self, node: dict, tls_config: TLSConfig, protocol: str):
 
         # Add Reality opts
         if tls_config.tls == "reality" and tls_config.reality_public_key:
+            # Do not map mldsa65Verify → support-x25519mlkem768; those are different PQ features.
             node["reality-opts"] = {
                 "public-key": tls_config.reality_public_key,
                 "short-id": tls_config.reality_short_id or "",
-                "support-x25519mlkem768": bool(tls_config.mldsa65_verify),
             }
 
     def _build_vless(self, remark: str, address: str, inbound: SubscriptionInboundData, settings: dict) -> dict:

app/utils/crypto.py

@@ -26,6 +26,39 @@ def add_base64_padding(b64_string: str) -> str:
     return b64_string + ("=" * (4 - missing_padding)) if missing_padding else b64_string
 
 
+MLDSA65_SEED_LENGTH = 32
+MLDSA65_VERIFY_LENGTH = 1952  # FIPS 204 ML-DSA-65 public key
+
+
+def _decode_urlsafe_b64(value: str) -> bytes:
+    try:
+        return base64.urlsafe_b64decode(add_base64_padding(value.strip()))
+    except (ValueError, binascii.Error) as exc:
+        raise ValueError("Invalid Base64 encoding.") from exc
+
+
+def validate_mldsa65_seed(seed_b64: str) -> str:
+    """Validate REALITY mldsa65Seed (32-byte URL-safe Base64, no padding)."""
+    seed = seed_b64.strip()
+    if not seed:
+        raise ValueError("Invalid mldsa65Seed.")
+    seed_bytes = _decode_urlsafe_b64(seed)
+    if len(seed_bytes) != MLDSA65_SEED_LENGTH:
+        raise ValueError(f"Invalid mldsa65Seed length. Must be {MLDSA65_SEED_LENGTH} bytes after decoding.")
+    return seed
+
+
+def validate_mldsa65_verify(verify_b64: str) -> str:
+    """Validate REALITY mldsa65Verify (1952-byte URL-safe Base64, no padding)."""
+    verify = verify_b64.strip()
+    if not verify:
+        raise ValueError("Invalid mldsa65Verify.")
+    verify_bytes = _decode_urlsafe_b64(verify)
+    if len(verify_bytes) != MLDSA65_VERIFY_LENGTH:
+        raise ValueError(f"Invalid mldsa65Verify length. Must be {MLDSA65_VERIFY_LENGTH} bytes after decoding.")
+    return verify
+
+
 def get_x25519_public_key(private_key_b64: str) -> str:
     """
     Converts an X25519 private key (URL-safe Base64) into a public key (URL-safe Base64 format).

dashboard/public/statics/locales/en.json

@@ -2247,6 +2247,7 @@
     "copyMldsa65Verify": "Copy Verify Key",
     "mldsa65SeedCopied": "Seed copied to clipboard",
     "mldsa65VerifyCopied": "Verify key copied to clipboard",
+    "mldsa65DestCertHint": "Optional. Requires a matching seed+verify pair. The REALITY target should use a large (typically RSA) certificate — ECDSA targets often fail silently with no useful client/server logs.",
     "vlessHandshakeLabel": "Handshake method",
     "vlessEncryptionLabel": "Encryption method",
     "vlessEncryptionHint": "Choose the wire format for encrypted payloads.",
@@ -2706,7 +2707,12 @@
         "destinationPortRange": "Destination port must be a whole number from 0 to 65535.",
         "realityServerNamesRequired": "REALITY requires at least one server name.",
         "realityServerNamesFormat": "REALITY server names must be a list of non-empty strings.",
-        "realityServerNamesNoEmpty": "Each REALITY server name must be non-empty; remove blank lines or extra commas."
+        "realityServerNamesNoEmpty": "Each REALITY server name must be non-empty; remove blank lines or extra commas.",
+        "mldsa65SeedInvalid": "ML-DSA-65 seed must be a 32-byte URL-safe Base64 value.",
+        "mldsa65VerifyInvalid": "ML-DSA-65 verify must be a 1952-byte URL-safe Base64 public key.",
+        "mldsa65VerifyRequiresSeed": "ML-DSA-65 verify requires a matching seed on the server. Generate a pair or clear verify.",
+        "mldsa65SeedReusesPrivateKey": "ML-DSA-65 seed must not be the same as the REALITY private key.",
+        "mldsa65PairMismatch": "ML-DSA-65 verify does not match the seed. Generate a new pair or paste matching values."
       },
       "discardDraftTitle": "Discard new inbound?",
       "discardDraftDescription": "This inbound is not in the list yet. Close without adding it will discard your changes.",

dashboard/public/statics/locales/fa.json

@@ -2162,6 +2162,7 @@
     "copyMldsa65Verify": "کپی Verify",
     "mldsa65SeedCopied": "Seed در کلیپ‌بورد کپی شد",
     "mldsa65VerifyCopied": "Verify در کلیپ‌بورد کپی شد",
+    "mldsa65DestCertHint": "اختیاری. به جفت seed+verify هم‌خوان نیاز دارد. هدف REALITY باید گواهی بزرگ (معمولاً RSA) داشته باشد — اهداف ECDSA اغلب بدون لاگ مفید در کلاینت/سرور به‌صورت خاموش شکست می‌خورند.",
     "vlessHandshakeLabel": "روش دست‌دهی",
     "vlessEncryptionLabel": "روش رمزنگاری",
     "vlessEncryptionHint": "قالب داده‌ی رمزگذاری‌شده را انتخاب کنید.",
@@ -2619,7 +2620,12 @@
         "destinationPortRange": "پورت مقصد باید عدد صحیح از ۰ تا ۶۵۵۳۵ باشد.",
         "realityServerNamesRequired": "REALITY حداقل به یک نام سرور نیاز دارد.",
         "realityServerNamesFormat": "نام‌های سرور REALITY باید فهرستی از رشته‌های غیرخالی باشد.",
-        "realityServerNamesNoEmpty": "هر نام سرور REALITY باید غیرخالی باشد؛ خطوط خالی یا ویرگول‌های اضافی را حذف کنید."
+        "realityServerNamesNoEmpty": "هر نام سرور REALITY باید غیرخالی باشد؛ خطوط خالی یا ویرگول‌های اضافی را حذف کنید.",
+        "mldsa65SeedInvalid": "Seed مربوط به ML-DSA-65 باید مقدار Base64 URL-safe به‌طول ۳۲ بایت باشد.",
+        "mldsa65VerifyInvalid": "Verify مربوط به ML-DSA-65 باید کلید عمومی Base64 URL-safe به‌طول ۱۹۵۲ بایت باشد.",
+        "mldsa65VerifyRequiresSeed": "Verify مربوط به ML-DSA-65 به seed هم‌خوان در سرور نیاز دارد. جفت را تولید کنید یا Verify را پاک کنید.",
+        "mldsa65SeedReusesPrivateKey": "Seed مربوط به ML-DSA-65 نباید با کلید خصوصی REALITY یکی باشد.",
+        "mldsa65PairMismatch": "Verify مربوط به ML-DSA-65 با seed هم‌خوان نیست. جفت جدید تولید کنید یا مقادیر هم‌خوان وارد کنید."
       },
       "discardDraftTitle": "ورودی جدید را دور بیندازید؟",
       "discardDraftDescription": "این ورودی هنوز در فهرست نیست. بستن بدون افزودن، تغییرات را دور می‌اندازد.",

dashboard/public/statics/locales/ru.json

@@ -2137,6 +2137,7 @@
     "copyMldsa65Verify": "Копировать Verify",
     "mldsa65SeedCopied": "Seed скопирован в буфер обмена",
     "mldsa65VerifyCopied": "Verify скопирован в буфер обмена",
+    "mldsa65DestCertHint": "Необязательно. Нужна согласованная пара seed+verify. Цель REALITY должна использовать крупный (обычно RSA) сертификат — цели с ECDSA часто молча ломаются без полезных логов на клиенте и сервере.",
     "vlessHandshakeLabel": "Метод рукопожатия",
     "vlessEncryptionLabel": "Метод шифрования",
     "vlessEncryptionHint": "Выберите формат для зашифрованных данных.",
@@ -2594,7 +2595,12 @@
         "destinationPortRange": "Порт назначения должен быть целым числом от 0 до 65535.",
         "realityServerNamesRequired": "Для REALITY нужно хотя бы одно имя сервера (server name).",
         "realityServerNamesFormat": "Имена серверов REALITY должны быть списком непустых строк.",
-        "realityServerNamesNoEmpty": "Каждое имя сервера REALITY должно быть непустым; удалите пустые строки или лишние запятые."
+        "realityServerNamesNoEmpty": "Каждое имя сервера REALITY должно быть непустым; удалите пустые строки или лишние запятые.",
+        "mldsa65SeedInvalid": "Seed ML-DSA-65 должен быть URL-safe Base64 длиной 32 байта.",
+        "mldsa65VerifyInvalid": "Verify ML-DSA-65 должен быть URL-safe Base64 публичным ключом длиной 1952 байта.",
+        "mldsa65VerifyRequiresSeed": "Verify ML-DSA-65 требует matching seed на сервере. Создайте пару или очистите verify.",
+        "mldsa65SeedReusesPrivateKey": "Seed ML-DSA-65 не должен совпадать с private key REALITY.",
+        "mldsa65PairMismatch": "Verify ML-DSA-65 не соответствует seed. Создайте новую пару или вставьте согласованные значения."
       },
       "discardDraftTitle": "Отменить новый входящий?",
       "discardDraftDescription": "Этот входящий ещё не в списке. Закрытие без добавления отменит изменения.",

dashboard/public/statics/locales/zh.json

@@ -2206,6 +2206,7 @@
     "copyMldsa65Verify": "复制 Verify",
     "mldsa65SeedCopied": "Seed 已复制到剪贴板",
     "mldsa65VerifyCopied": "Verify 已复制到剪贴板",
+    "mldsa65DestCertHint": "可选。需要匹配的 seed+verify 密钥对。REALITY 目标站点应使用较大（通常为 RSA）的证书——ECDSA 目标常会静默失败，且客户端/服务端几乎没有有用日志。",
     "vlessHandshakeLabel": "握手方式",
     "vlessEncryptionLabel": "加密方式",
     "vlessEncryptionHint": "选择加密负载使用的线路格式。",
@@ -2663,7 +2664,12 @@
         "destinationPortRange": "目标端口必须为 0 至 65535 之间的整数。",
         "realityServerNamesRequired": "REALITY 至少需要填写一个 server name。",
         "realityServerNamesFormat": "REALITY 的 server names 必须为非空字符串的列表。",
-        "realityServerNamesNoEmpty": "每个 REALITY server name 都必须非空；请删除空行或多余逗号。"
+        "realityServerNamesNoEmpty": "每个 REALITY server name 都必须非空；请删除空行或多余逗号。",
+        "mldsa65SeedInvalid": "ML-DSA-65 seed 必须是 32 字节的 URL-safe Base64 值。",
+        "mldsa65VerifyInvalid": "ML-DSA-65 verify 必须是 1952 字节的 URL-safe Base64 公钥。",
+        "mldsa65VerifyRequiresSeed": "ML-DSA-65 verify 需要服务端有匹配的 seed。请生成密钥对或清空 verify。",
+        "mldsa65SeedReusesPrivateKey": "ML-DSA-65 seed 不能与 REALITY 私钥相同。",
+        "mldsa65PairMismatch": "ML-DSA-65 verify 与 seed 不匹配。请重新生成密钥对或粘贴匹配的值。"
       },
       "discardDraftTitle": "放弃新入站？",
       "discardDraftDescription": "此入站尚未加入列表。关闭而不添加将丢弃更改。",

dashboard/src/features/core-editor/components/xray/xray-inbounds-section.tsx

@@ -22,7 +22,12 @@ import { XrayStreamFinalmaskInboundAccordion } from '@/features/core-editor/comp
 import { InboundFallbacksEditor } from '@/features/core-editor/components/xray/inbound-fallbacks-editor'
 import { useSectionHeaderAddPulseEffect, type SectionHeaderAddPulse } from '@/features/core-editor/hooks/use-section-header-add-pulse'
 import { useXrayPersistModifyGuard } from '@/features/core-editor/hooks/use-xray-persist-modify-guard'
-import { createInboundDialogSchema, realityInboundZodTriggerFieldNames } from '@/features/core-editor/kit/inbound-dialog-schema'
+import {
+  createInboundDialogSchema,
+  INBOUND_FORM_FIELD_SEC_MLDSA65_SEED,
+  INBOUND_FORM_FIELD_SEC_MLDSA65_VERIFY,
+  realityInboundZodTriggerFieldNames,
+} from '@/features/core-editor/kit/inbound-dialog-schema'
 import { getInboundSecuritySelectOptions, getInboundTransportSelectOptions, transportCompatibleWithReality } from '@/features/core-editor/kit/inbound-form-options'
 import { profileDuplicateTagMessage, profileTagHasDuplicateUsage } from '@/features/core-editor/kit/profile-tag-uniqueness'
 import { remapIndexAfterArrayMove } from '@/features/core-editor/kit/remap-index-after-move'
@@ -46,6 +51,7 @@ import {
   vlessInboundEncryptionRawForForm,
   type VlessBuilderOptions,
 } from '@/lib/xray-generation'
+import { mldsa65PairMatches, validateMldsa65Seed, validateMldsa65Verify } from '@/utils/mldsa65'
 import { generateWireGuardKeyPair, getWireGuardPublicKey } from '@/utils/wireguard'
 import { arrayMove } from '@dnd-kit/sortable'
 import { zodResolver } from '@hookform/resolvers/zod'
@@ -1589,6 +1595,28 @@ export function XrayInboundsSection({ headerAddPulse, headerAddEpoch }: XrayInbo
     finalizeDetailClose()
   }
 
+  const assertMldsa65PairForCommit = async (): Promise<boolean> => {
+    if (form.getValues('security') !== 'reality') return true
+    const seed = String(form.getValues(INBOUND_FORM_FIELD_SEC_MLDSA65_SEED) ?? '').trim()
+    const verify = String(form.getValues(INBOUND_FORM_FIELD_SEC_MLDSA65_VERIFY) ?? '').trim()
+    if (!seed && !verify) return true
+    if (!seed || !verify) return true // Zod covers verify-without-seed / empty half-pairs
+    if (!validateMldsa65Seed(seed).ok || !validateMldsa65Verify(verify).ok) return true
+
+    const matches = await mldsa65PairMatches(seed, verify)
+    if (matches) {
+      form.clearErrors(INBOUND_FORM_FIELD_SEC_MLDSA65_VERIFY)
+      return true
+    }
+    form.setError(INBOUND_FORM_FIELD_SEC_MLDSA65_VERIFY, {
+      type: 'manual',
+      message: t('coreEditor.inbound.validation.mldsa65PairMismatch', {
+        defaultValue: 'ML-DSA-65 verify does not match the seed. Generate a new pair or paste matching values.',
+      }),
+    })
+    return false
+  }
+
   const commitAddInbound = async () => {
     if (!profile) return
     if (!draftInbound || draftInbound.protocol === 'unmanaged') return
@@ -1611,6 +1639,7 @@ export function XrayInboundsSection({ headerAddPulse, headerAddEpoch }: XrayInbo
     ]
     const ok = await form.trigger(fields, { shouldFocus: true })
     if (!ok) return
+    if (!(await assertMldsa65PairForCommit())) return
     if (!validateWireguardInboundForCommit(draftInbound)) return
     const insertAt = profile.inbounds.length
     updateXrayProfile(p => ({ ...p, inbounds: [...p.inbounds, draftInbound] }))
@@ -1629,6 +1658,7 @@ export function XrayInboundsSection({ headerAddPulse, headerAddEpoch }: XrayInbo
       const fields = ['protocol', 'tag', 'port', ...(form.getValues('security') === 'reality' ? realityInboundZodTriggerFieldNames() : [])]
       const ok = await form.trigger(fields, { shouldFocus: true })
       if (!ok) return
+      if (!(await assertMldsa65PairForCommit())) return
     } else if (inbound.protocol !== 'unmanaged' && isTunnelInboundProtocol(inbound.protocol)) {
       const ok = await form.trigger(['protocol', 'tag', 'port', 'tunnelRewriteAddress', 'tunnelRewritePort'], { shouldFocus: true })
       if (!ok) return
@@ -4144,7 +4174,7 @@ export function XrayInboundsSection({ headerAddPulse, headerAddEpoch }: XrayInbo
                                 </div>
                               )}
                               {isReality && jsonKey === 'fingerprint' && (
-                                <div className="w-full min-w-0 sm:col-span-2">
+                                <div className="w-full min-w-0 space-y-2 sm:col-span-2">
                                   <LoaderButton
                                     type="button"
                                     onClick={() => void handleGenerateMldsa65()}
@@ -4154,6 +4184,12 @@ export function XrayInboundsSection({ headerAddPulse, headerAddEpoch }: XrayInbo
                                   >
                                     <span className="flex items-center gap-2 truncate">{t('coreConfigModal.generateMldsa65')}</span>
                                   </LoaderButton>
+                                  <p className="text-muted-foreground text-xs leading-relaxed">
+                                    {t('coreConfigModal.mldsa65DestCertHint', {
+                                      defaultValue:
+                                        'Optional. Requires a matching seed+verify pair. The REALITY target should use a large (typically RSA) certificate — ECDSA targets often fail silently with no useful client/server logs.',
+                                    })}
+                                  </p>
                                 </div>
                               )}
                               {isReality && jsonKey === 'target' && (