[Bug]: Hysteria2 subscription link includes non-standard "fm" (finalmask) param that breaks parsing in mihomo/sing-box/subconverter

[KillReal1234]

Describe the bug

The Hysteria2 line in the plain/universal subscription (base64 list of URIs) includes a non-standard fm query parameter that raw-dumps the internal finalmask.udp[] JSON config, in addition to the already-present standard obfs/obfs-password fields:

hysteria2://@host:443?alpn=h3&fm=%7B%22udp%22%3A%5B%7B%22settings%22%3A%7B%22password%22%3A%22...%22%7D%2C%22type%22%3A%22salamander%22%7D%5D%7D&fp=firefox&obfs=salamander&obfs-password=...&security=tls&sni=host

fm is not part of the Hysteria2 URI scheme (https://v2.hysteria.network/docs/developers/URI-Scheme/) and is not understood by mihomo, sing-box, the official hysteria2 client, or subconverter. Since obfs/obfs-password already fully describe the salamander obfuscation, fm is redundant.

How to reproduce the problem

This did not happen before upgrading from 3x-ui < 3.5.0 (Xray-core 26.6.27) to 3.5.0. It appears to be tied to the addition of FinalMask support (commit c59f54b, "outbound: finalmask"). After the upgrade, the generated subscription link stopped working with mihomo (fails the whole proxy-provider update).

Expected behavior

Do not serialize the raw finalmask object into the public subscription URI — obfs/obfs-password (and security=tls, sni, alpn) are already sufficient for standard clients.

Actual behavior

No response

Relevant logs

Screenshots

No response

3x-ui version

3.5.0

Xray-core version

26.7.11

How did you install 3x-ui?

install.sh script

Operating system

Ubuntu 24.04

Which parts of the panel are affected?

Subscription (share links / Clash / JSON)

Browser (only if it is a UI bug)

No response

Is the panel behind a reverse proxy or CDN?

Yes — Nginx

Before submitting

• I searched existing issues and this bug has not been reported.
• I am running the latest released version of 3x-ui (or have verified the bug still exists on it).
• This bug report is written in English.
• I have redacted any sensitive data (tokens, real domains, client UUIDs).

[github-actions]

Root cause confirmed in internal/sub/service.go, genHysteriaLink (starts line 978), lines 1026-1045:

// salamander obfs (Hysteria2). The panel-side link generator already
// emits these; keep the subscription output in sync so a client has
// the obfs password to match the server.
if finalmask, ok := stream["finalmask"].(map[string]any); ok {
    applyFinalMaskParams(finalmask, params)
    if udpMasks, ok := finalmask["udp"].([]any); ok {
        for _, m := range udpMasks {
            ...
            params["obfs"] = "salamander"
            params["obfs-password"] = pw

applyFinalMaskParams (service.go:2283, doc comment at 2281-2282) unconditionally serializes the whole normalized finalmask object into params["fm"]; its own comment says this exists as "the compact fm=<json> share-link field used by v2rayN-compatible clients" - i.e. it's a deliberate v2rayN-specific extension, not part of the Hysteria2 URI scheme. Immediately below it, the loop over finalmask["udp"] already extracts the salamander password into the standard obfs/obfs-password fields. Both run unconditionally, so any Hysteria2 client with salamander obfuscation gets both the standard fields and the redundant fm blob in the same link, exactly as in the report. url.Values.Encode() (used by buildLinkWithParams/appendQueryAndFragment, service.go:1785-1820) sorts query keys alphabetically, which matches the reported ordering (alpn, fm, fp, obfs, obfs-password, security, sni) and confirms this is the exact code path that produced the link.

This is inconsistent with the Clash/Mihomo YAML generator: internal/sub/clash_service.go (lines 339-351) performs the same "read finalmask.udp[salamander] password" extraction into obfs/obfs-password for the Clash proxy format, but does not emit any fm-equivalent field. The JSON/sing-box subscription format (internal/sub/json_service.go, applyGlobalFinalMask/mergeFinalMask) is unaffected by this report - it keeps finalmask as a native structured JSON field rather than a URL-encoded query param, which is appropriate for that consumer. So genHysteriaLink's raw/base64-URI output is the one generator that leaks the raw payload.

I could not resolve the commit hash mentioned in the report (c59f54b) in this checkout, but the behavior is present and reproducible in current main (129f50d, past the v3.5.0 tag), so this is not fixed in the latest release.

One nuance for the fix: validFinalMaskUDPTypes (service.go:2132-2140) lists 7 valid Hysteria2 UDP mask types (salamander, mkcp-legacy, xdns, xicmp, noise, header-custom, realm); only salamander has a standard Hysteria2 URI representation. Unconditionally dropping fm would stop conveying the other six mask types to v2rayN via this link (per applyFinalMaskParams's stated purpose), so there is a small tradeoff between strict spec-compliance and v2rayN-specific round-tripping.

---

Title: Hysteria2 raw/base64 subscription link always includes the non-standard fm (finalmask) query param alongside the standard obfs/obfs-password fields

Severity: Medium

Category: Correctness

Why this matters: The fm value is a URL-encoded raw JSON dump of the internal finalmask config, which is not part of the Hysteria2 URI Scheme. For salamander obfuscation - the only finalmask UDP type Hysteria2 natively supports via obfs/obfs-password - fm is pure redundancy: the standard fields already fully describe it. Per the report, this breaks mihomo's proxy-provider subscription update entirely (and reportedly sing-box / subconverter / the official client), with no admin-facing toggle to suppress it, so every Hysteria2 + salamander inbound's subscription link stopped being usable in mihomo after upgrading to 3.5.0.

Recommendation: In genHysteriaLink, stop calling applyFinalMaskParams unconditionally. Two options, in order of simplicity:

1. Drop the fm param from this generator entirely and rely solely on the existing obfs/obfs-password extraction (lines 1031-1044) - mirrors the precedent already set in clash_service.go.
2. If preserving v2rayN fidelity for non-salamander mask types matters, only set fm when the normalized finalmask contains content beyond what obfs/obfs-password already represent (i.e. treat it as an overflow field, not an always-on dump).

The same applyFinalMaskParams/applyFinalMaskObj pattern is also used for VMess (service.go:703-705), VLESS (795-796), and the other protocol generators in this file - worth checking whether the same redundancy applies there, though that is outside the scope of this specific report.

Confidence: high on the root cause and file/line citations (verified directly in current main); the fix approach is a product tradeoff for the maintainer to decide, not asserted as the only correct option.

@MHSanaei for a decision on the fix approach.

This reply was generated automatically. A maintainer may follow up.