[Bug]: Shadowsocks TLS share links are incompatible with SIP002 and v2rayNG

[vladon]

Describe the bug

For a Shadowsocks inbound using Xray-native transport TLS, the raw share/subscription link looks like:

ss://<base64url(method:password)>@example.com:443?alpn=h2%2Chttp%2F1.1&fp=firefox&security=tls&sni=example.com&type=tcp#user

This link looks complete, but it is not interoperable with SIP002 clients such as v2rayNG.

SIP002 defines the optional query component for a SIP003 plugin; parameters such as security, sni, alpn, fp, and type are not a standard representation of Xray streamSettings.

Current v2rayNG parses the server, port, method, and password, and only handles the plugin query when it contains obfs=http. It ignores the Xray-native TLS parameters, so it creates a plain Shadowsocks outbound while the server expects TLS. The connection then fails during the handshake.

3x-ui's own Shadowsocks importer demonstrates the same mismatch: it truncates the link at ? before parsing and therefore discards all generated TLS parameters.

Relevant source:

• 3x-ui generator adds TLS query parameters:

  3x-ui/internal/sub/service.go

  Lines 927 to 975 in 4e928a1

  	security, _ := stream["security"].(string)
  	if security == "tls" {
  	applyShareTLSParams(stream, params)
  	}
  	// SIP002 clients (v2rayN) ignore the xray-native type/headerType/host/path
  	// params and only read `plugin`. Re-encode a TCP http header as obfs-local so
  	// they build a matching tcp/http outbound (v2rayN forces request path "/").
  	if streamNetwork == "tcp" && params["headerType"] == "http" {
  	host := params["host"]
  	delete(params, "type")
  	delete(params, "headerType")
  	delete(params, "host")
  	delete(params, "path")
  	params["plugin"] = "obfs-local;obfs=http;obfs-host=" + host
  	}
  	// SIP002 userinfo is base64(method:password). For SIP022 (2022-blake3-*) the
  	// userinfo MUST NOT be base64-encoded; method and password are percent-encoded.
  	var userInfo string
  	if strings.HasPrefix(method, "2022") {
  	userInfo = fmt.Sprintf("%s:%s:%s",
  	url.QueryEscape(method),
  	url.QueryEscape(inboundPassword),
  	url.QueryEscape(client.Password))
  	} else {
  	userInfo = base64.RawURLEncoding.EncodeToString(fmt.Appendf(nil, "%s:%s", method, client.Password))
  	}
  	externalProxies, _ := stream["externalProxy"].([]any)
  	if len(externalProxies) > 0 {
  	proxyParams := cloneStringMap(params)
  	proxyParams["security"] = security
  	return s.buildExternalProxyURLLinks(
  	externalProxies,
  	proxyParams,
  	security,
  	func(_ map[string]any, dest string, port int) string {
  	return fmt.Sprintf("ss://%s@%s", userInfo, joinHostPort(dest, port))
  	},
  	func(ep map[string]any) string {
  	return s.endpointRemark(inbound, email, ep, streamNetwork)
  	},
  	)
  	}
  	link := fmt.Sprintf("ss://%s@%s", userInfo, joinHostPort(address, inbound.Port))
  	return buildLinkWithParams(link, params, s.genRemark(inbound, email, "", streamNetwork))

• 3x-ui importer drops the entire query:

  3x-ui/internal/util/link/outbound.go

  Lines 336 to 383 in 4e928a1

  	func parseShadowsocks(link string) (*ParseResult, error) {
  	// Two shapes:
  	// ss://base64(method:pass)@host:port#remark
  	// ss://base64(method:pass@host:port)#remark
  	remark := ""
  	if i := strings.Index(link, "#"); i >= 0 {
  	remark, _ = url.QueryUnescape(link[i+1:])
  	link = link[:i]
  	}
  	if i := strings.Index(link, "?"); i >= 0 {
  	link = link[:i]
  	}
  	core := strings.TrimPrefix(link, "ss://")
  	at := strings.Index(core, "@")
  	if at >= 0 {
  	// modern
  	userB64 := core[:at]
  	hp := strings.TrimRight(core[at+1:], "/")
  	userInfo, err := base64DecodeFlexible(userB64)
  	if err != nil {
  	// SIP022 (2022-blake3-*) userinfo is percent-encoded, not base64.
  	if dec, uerr := url.QueryUnescape(userB64); uerr == nil {
  	userInfo = dec
  	} else {
  	userInfo = userB64 // not b64, rare
  	}
  	}
  	colon := strings.LastIndex(hp, ":")
  	if colon < 0 {
  	return nil, fmt.Errorf("bad ss host:port")
  	}
  	host := hp[:colon]
  	port, err := strconv.Atoi(hp[colon+1:])
  	if err != nil {
  	return nil, fmt.Errorf("bad ss port %q: %w", hp[colon+1:], err)
  	}
  	method, pass := splitMethodPass(userInfo)
  	identity := "ss:" + method + ":" + pass + "@" + host + ":" + strconv.Itoa(port)
  	ob := Outbound{
  	"protocol": "shadowsocks",
  	"tag": remark,
  	"settings": map[string]any{
  	"servers": []any{
  	map[string]any{"address": host, "port": port, "password": pass, "method": method},
  	},
  	},
  	}
  	return &ParseResult{Outbound: ob, Identity: identity}, nil

• v2rayNG only handles the SIP002 plugin query: https://github.com/2dust/v2rayNG/blob/master/V2rayNG/app/src/main/java/com/v2ray/ang/fmt/ShadowsocksFmt.kt#L29-L68
• SIP002 grammar: https://github.com/shadowsocks/shadowsocks-org/wiki/SIP002-URI-Scheme

The same generator logic is still present on the current 3x-ui main branch.

How to reproduce the problem

1. Create a Shadowsocks inbound:
   • method: chacha20-ietf-poly1305
   • network: TCP
   • transport security: TLS
   • valid certificate and SNI
2. Add a client and fetch its normal raw subscription.
3. Import the generated ss:// entry into v2rayNG.
4. Try to connect. The profile fails because v2rayNG creates a plain Shadowsocks outbound.
5. As a control, build an Xray outbound with the same address, port, method, and password plus:

   {
     "streamSettings": {
       "network": "tcp",
       "security": "tls",
       "tlsSettings": {
         "serverName": "example.com"
       }
     }
   }

   The control connection works.
6. Remove native TLS from the server inbound and refresh the same subscription. The unmodified v2rayNG profile then works.

I reproduced this with an end-to-end HTTPS request through an independent Xray client:

• generated SIP002 core fields without manually restoring TLS: failed
• same credentials with TLS stream settings: HTTP 200
• after changing the server inbound to standard Shadowsocks without TLS: HTTP 200

Expected behavior

3x-ui should not emit a misleading standard ss:// link that common SIP002 clients import without the server-required TLS layer.

Possible safe outcomes:

1. Reject or warn about Shadowsocks + Xray-native TLS when raw share links/subscriptions are used.
2. Omit the raw ss:// entry and provide a full JSON configuration for this non-SIP002 combination.
3. Use a SIP003 plugin representation only when both the generated link and server configuration actually use the same supported plugin.

A regression test should cover either:

• genShadowsocksLink -> ParseLink preserving all server-required transport settings, or
• refusing/marking the combination as non-exportable when it cannot round-trip.

Actual behavior

genShadowsocksLink emits Xray-native transport fields as non-standard ss:// query parameters. v2rayNG and 3x-ui's own importer discard them, producing a plain Shadowsocks client configuration that cannot connect to the TLS-enabled inbound.

The existing characterization test currently locks this incompatible output in as expected:

3x-ui/internal/sub/characterization_test.go

Lines 152 to 174 in 4e928a1

	// C3b — Shadowsocks 2022 (method[0]=='2'), TLS base, 1 externalProxy entry.
	// Locks the ss-2022 triple-segment userinfo path through the shared builder.
	func TestChar_C3_ShadowsocksExternalProxy(t *testing.T) {
	stream := `{
	"network":"tcp","security":"tls",
	"tcpSettings":{"header":{"type":"none"}},
	"tlsSettings":{"serverName":"base.sni","settings":{"fingerprint":"chrome"}},
	"externalProxy":[{"forceTls":"tls","dest":"ss.example.com","port":8443,"remark":"SS","sni":"ss.sni"}]
	}`
	in := &model.Inbound{
	Listen: "203.0.113.1",
	Port: 443,
	Protocol: model.Shadowsocks,
	Remark: "char",
	Settings: `{"method":"2022-blake3-aes-256-gcm","password":"inboundpw","clients":[{"password":"clientpw","email":"user"}]}`,
	StreamSettings: stream,
	}
	s := &SubService{}
	got := s.genShadowsocksLink(in, "user")
	want := "ss://2022-blake3-aes-256-gcm:inboundpw:clientpw@ss.example.com:8443?fp=chrome&security=tls&sni=ss.sni&type=tcp#char-SS-user"
	if got != want {
	t.Fatalf("C3-SS mismatch.\n got: %q\nwant: %q", got, want)
	}

Relevant logs

Generated link (credentials redacted):
ss://<redacted>@example.com:443?alpn=h2%2Chttp%2F1.1&fp=firefox&security=tls&sni=example.com&type=tcp#user

v2rayNG import result:
- Shadowsocks server/method/password imported
- no TLS stream settings created
- connection fails

Control Xray outbound with streamSettings.security=tls:
- HTTP 200

Screenshots

Not applicable.

3x-ui version

3.5.0 (tag commit 4e928a1ce0945a6e956aa63365034ec24d2b1387); verified that current main still contains the same logic.

Xray-core version

26.7.11

How did you install 3x-ui?

install.sh script

Operating system

Ubuntu 26.04 LTS

Which parts of the panel are affected?

• Subscription (share links / Clash / JSON)
• Backend share-link generation

Browser (only if it is a UI bug)

Not applicable.

Is the panel behind a reverse proxy or CDN?

No — direct access

Before submitting

• I searched existing issues for Shadowsocks TLS, SIP002, native TLS, and v2rayNG; no duplicate was found.
• I am running the latest released version of 3x-ui and verified the same code on current main.
• This bug report is written in English.
• All tokens, real domains, addresses, client identifiers, and credentials are redacted.

[MHSanaei]

@claude

[github-actions]

Claude finished @MHSanaei's task in 6m 53s —— View job

---

Summary

The report is accurate on the facts, and it points at a real round-trip bug — but I disagree with the two remedies it leads with. There is no SIP002 encoding for Xray-native TLS, so deleting the parameters does not make the link work in v2rayNG; it only destroys the one record of what the server requires and breaks the clients that do read them. The achievable fix is the reporter's own test option (a): make genShadowsocksLink → ParseLink round-trip, which today it does not.

What I confirmed in the source

1. The generator emits Xray-native params (as described). internal/sub/service.go:919-930 — params["type"] = streamNetwork, then applyShareNetworkParams, then applyShareTLSParams when security == "tls". The frontend twin does the same in frontend/src/lib/xray/inbound-link.ts:609-650.

2. The combination is reachable by design, not by accident. shadowsocks is in TLS_ELIGIBLE_PROTOCOLS in frontend/src/lib/xray/protocol-capabilities.ts:8, so canEnableTls deliberately offers TLS on a Shadowsocks inbound.

3. The panel's own importer discards the query — and this is asymmetric with Trojan. This is the part I would call the bug. parseShadowsocks (internal/util/link/outbound.go:336) truncates at ? on lines 345-347 and returns an outbound with no streamSettings key at all (lines 374-383). parseTrojan (outbound.go:294), which parses an identical URL shape, builds the full stream on lines 314-318 via buildStream / applyTransport / applySecurity / applyFinalMask. The same asymmetry exists on the frontend: parseTrojanLink (outbound-link-parser.ts:419) returns streamSettings; parseShadowsocksLink (:442) does not.

That truncation is not an oversight — it came from #5895, which stripped the query to stop strconv.Atoi failing on host:port?query and silently yielding port 0. The port fix was correct; it just threw the query away instead of parsing it.

This has a user-visible consequence beyond the round-trip test: ParseLink backs external outbound links (internal/sub/external_config.go:196) and outbound subscriptions (internal/web/service/outbound_subscription.go:376). Pasting an ss://…?security=tls&sni=… link from any panel into 3x-ui produces a plain Shadowsocks outbound that cannot connect — the same failure the reporter saw in v2rayNG, reproduced inside 3x-ui itself.

Why I would not drop the parameters

Option 1 (reject/warn) and option 2 (omit the raw entry) both assume the params are the problem. They are not: SIP002 clients ignore unknown query keys, so their presence costs nothing there, and their absence buys nothing — the profile fails either way, because the server wants a TLS layer the client will not build. Removing them converts a link that works in Xray-aware clients into one that works nowhere.

The precedent in #6048 (dropping fm from Hysteria2 URIs) does not transfer: fm made mihomo reject the whole link during provider updates. Nothing rejects these.

Option 3 is already implemented for the one case that maps: TCP + http header is re-encoded as an obfs-local SIP003 plugin at internal/sub/service.go:932-942. TLS has no SIP003 plugin equivalent, so that path cannot be extended to cover it.

Which export path is correct today

The JSON subscription is the one that already carries this combination correctly. genServer (internal/sub/json_service.go:440-490) assigns outbound.StreamSettings = streamSettings, and at the call site (json_service.go:229) that value is the fully-resolved stream including security: "tls" and tlsSettings. A user on Shadowsocks + native TLS should be given the JSON subscription, not the raw one.

Worth noting separately: the Clash path has the same class of defect. clash_service.go:263-276 emits type: ss, then applySecurity (clash_service.go:658-697) adds tls: true / servername / client-fingerprint — mihomo's ss proxy schema has no TLS layer, so those keys do not produce a TLS connection either. That is a separate fix from this issue.

Proposed fix — round-trip the query in parseShadowsocks

Capture the query before truncating (keeping #5895's port fix intact), and build the stream the way parseTrojan does. In internal/util/link/outbound.go:

	params := url.Values{}
	if i := strings.Index(link, "?"); i >= 0 {
		if q, err := url.ParseQuery(link[i+1:]); err == nil {
			params = q
		}
		link = link[:i]
	}
	core := strings.TrimPrefix(link, "ss://")

Then in the modern (userinfo@host:port) branch, attach the stream:

		method, pass := splitMethodPass(userInfo)
		stream := shadowsocksStream(params)
		identity := "ss:" + method + ":" + pass + "@" + host + ":" + strconv.Itoa(port)
		ob := Outbound{
			"protocol": "shadowsocks",
			"tag":      remark,
			"settings": map[string]any{
				"servers": []any{
					map[string]any{"address": host, "port": port, "password": pass, "method": method},
				},
			},
			"streamSettings": stream,
		}
		return &ParseResult{Outbound: ob, Identity: identity}, nil

The legacy branch needs no change — a fully-base64 link has no query by construction.

The new helper, placed next to splitMethodPass. It also decodes the panel's own obfs-local output back into a TCP http header, which closes the other half of the round-trip:

func shadowsocksStream(p url.Values) map[string]any {
	if plugin := p.Get("plugin"); strings.Contains(plugin, "obfs=http") {
		p = cloneValues(p)
		p.Set("type", "tcp")
		p.Set("headerType", "http")
		for _, opt := range strings.Split(plugin, ";") {
			if host, ok := strings.CutPrefix(opt, "obfs-host="); ok {
				p.Set("host", host)
			}
		}
	}
	network := p.Get("type")
	if network == "" {
		network = "tcp"
	}
	security := p.Get("security")
	if security == "" {
		security = "none"
	}
	stream := buildStream(network, security)
	applyTransport(stream, p)
	applySecurity(stream, p)
	applyFinalMask(stream, p)
	return stream
}

func cloneValues(p url.Values) url.Values {
	out := make(url.Values, len(p))
	maps.Copy(out, p)
	return out
}

maps is already imported (outbound.go:11), and buildStream seeds security: "none" without a tlsSettings block, so plain Shadowsocks links keep working and merely gain an inert streamSettings.

Two judgment calls I would leave to you:

• identity. parseTrojan appends "?" + canonicalQuery(params) (outbound.go:317). Matching that here is more consistent, but identity drives stable tag assignment across subscription refreshes (outbound_subscription.go:376-405), so changing its format causes a one-time tag reshuffle for existing Shadowsocks subscriptions. The positional fallback absorbs it, but the snippet above leaves identity alone to keep the diff behavioural-neutral.
• The frontend twin. parseShadowsocksLink (outbound-link-parser.ts:442-498) needs the mirrored change, or link import in the UI stays lossy while the Go path is fixed. Per the repo rules that only reaches users once the Vite build regenerates internal/web/dist/.

Suggested test

This is the reporter's option (a), expressed against both packages. In internal/util/link/outbound_test.go:

func TestParseShadowsocksPreservesTLSStream(t *testing.T) {
	user := base64.RawURLEncoding.EncodeToString([]byte("chacha20-ietf-poly1305:secretpass"))
	res, err := ParseLink("ss://" + user + "@example.com:443?alpn=h2%2Chttp%2F1.1&fp=firefox&security=tls&sni=example.com&type=tcp#user")
	if err != nil {
		t.Fatalf("ParseLink: %v", err)
	}
	stream, ok := res.Outbound["streamSettings"].(map[string]any)
	if !ok {
		t.Fatal("outbound has no streamSettings")
	}
	if stream["security"] != "tls" {
		t.Fatalf("security = %v, want tls", stream["security"])
	}
	tls, ok := stream["tlsSettings"].(map[string]any)
	if !ok {
		t.Fatal("tls stream has no tlsSettings")
	}
	if tls["serverName"] != "example.com" {
		t.Fatalf("serverName = %v, want example.com", tls["serverName"])
	}
	if tls["fingerprint"] != "firefox" {
		t.Fatalf("fingerprint = %v, want firefox", tls["fingerprint"])
	}
}

A true end-to-end guard would generate with genShadowsocksLink and parse back, but internal/sub importing internal/util/link for a test crosses a package boundary the suite does not currently cross — the pairing above plus the existing characterization test covers the same contract from both ends.

Regarding the existing characterization test at internal/sub/characterization_test.go:152-174: I would leave it as-is. It locks the ss-2022 triple-segment userinfo through the external-proxy builder, which is what #5432/#5670 fixed; the security=tls in its expectation is incidental to what it guards.

I could not compile or run these snippets — this workflow is read-only and the Go toolchain is not available to it — so treat the code above as reviewed-by-reading against the current main, not as verified-green.

[vladon]

Thanks — this confirms the main diagnosis, and I agree that simply deleting the query parameters while continuing to export the same ss:// entry would not be a fix.

One clarification: options 1 and 2 in the report were not proposing “remove the parameters and keep exporting the raw profile”. They were proposing either warning/refusing that raw export, or directing the user to the full JSON representation, precisely because SIP002 has no encoding for Xray-native TLS.

The proposed parseShadowsocks change is valuable and should fix the backend/frontend 3x-ui round-trip. However, it does not resolve the originally reported v2rayNG failure: current v2rayNG ShadowsocksFmt.parseSip002 still ignores security, sni, alpn, fp, and type, so the same raw subscription entry will still become a plain Shadowsocks outbound and silently fail against a TLS-enabled inbound.

I think the complete scope should therefore be:

1. Preserve the query and build streamSettings in both 3x-ui Shadowsocks parsers, as proposed.
2. Treat Shadowsocks + Xray-native TLS raw/SIP002 export as client-specific and non-portable: show a warning or avoid presenting it as a generally compatible raw subscription entry, with the JSON subscription as the supported alternative.
3. Track the Clash/mihomo export problem separately.

Tests should cover both contracts:

• genShadowsocksLink -> ParseLink preserves the required stream settings.
• A native-TLS Shadowsocks inbound is not silently advertised through a compatibility path whose target client cannot reconstruct TLS.

If this issue is intentionally fixed as parser-only, the remaining v2rayNG incompatibility should be documented explicitly, because the raw ss:// profile will still fail there after that patch.

[vladon]

I opened the client-side v2rayNG fix as 2dust/v2rayNG#5950.

That PR makes ShadowsocksFmt.parseSip002 reuse v2rayNG's existing Xray query mapper, so explicit type, security, sni, alpn, and fp values reach ProfileItem and the already-existing Shadowsocks outbound builder can produce the required streamSettings. It also adds regression coverage for native TLS, standard SIP002 links, and the existing obfs-local plugin mapping.

This addresses the v2rayNG side of the interoperability failure. It does not make these keys part of SIP002, and it does not replace the separate 3x-ui fixes discussed here for its own lossy Shadowsocks importer and raw-export compatibility behavior.

[morsuning]

I have discovered a bug, but I am currently unable to create a new issue. I would like to use this existing issue to report it; if it is not appropriate, it can be deleted at any time. I hope this issue will receive the attention it deserves.

Describe the bug

After upgrading 3x-ui to v3.6.0, existing VLESS inbound clients using flow: xtls-rprx-vision stop working. The client (mihomo/Clash Meta) successfully completes REALITY authentication, but data transfer hangs and connections time out.

Root cause: v3.6.0 migrates clients into the new standalone clients table, but the flow value is not migrated. Both clients.flow and client_inbounds.flow_override are empty after the upgrade. Every time x-ui restarts and regenerates /usr/local/x-ui/bin/config.json, the client entry is missing "flow": "xtls-rprx-vision". The server-side client then has no flow while the client-side uses XTLS Vision, so the Vision data stream cannot be processed properly → the connection hangs after a successful REALITY handshake.

How to reproduce the problem

1. On a pre-3.6.0 install, create a VLESS + REALITY inbound whose client has flow: xtls-rprx-vision. Verify it works.
2. Upgrade to v3.6.0.
3. Restart x-ui.
4. Inspect /usr/local/x-ui/bin/config.json — the client entry contains only email and id, with no flow.
5. Connect with a client using xtls-rprx-vision → REALITY authentication succeeds but data transfer stalls (timeout).

Expected behavior

Upgrading should preserve each client's flow setting.

Actual behavior

flow is silently lost. After the upgrade, clients.flow and client_inbounds.flow_override are both empty in the database.

Evidence — generated config.json client entry before fix:

{"email": "...", "id": "..."}

After manually setting clients.flow = 'xtls-rprx-vision' and client_inbounds.flow_override = 'xtls-rprx-vision' and restarting x-ui, the entry is:

{"email": "...", "flow": "xtls-rprx-vision", "id": "..."}

Relevant logs

Client-side (mihomo, debug level): REALITY Authentication: true followed by a silent hang (no response). Server-side: no errors logged.

Note: this is easy to miss because the panel UI still shows the client with its flow setting; only the DB migration is at fault.

3x-ui version

3.6.0

Xray-core version

26.6.27 (also reproduced on 26.7.28)

Is the panel behind a reverse proxy or CDN?

No — direct access

---

Additionally, I have discovered that version 3.6.0 also comes with another issue.

Describe the bug

Upgrading 3x-ui to its latest release also bumps the bundled Xray-core to v26.7.28. Xray-core v26.7.28 introduces a breaking default: REALITY now enforces a minimum client version of Xray-core v26.3.27 unless minClientVer is explicitly set. Non-Xray clients (mihomo/Clash Meta, sing-box, etc.) are refused, so after a routine panel upgrade every such client stops working at once.

The startup log shows:

REALITY: The default minimal client version is Xray-core v26.3.27, other clients may be refused to connect

Client-side symptom: REALITY authentication failed (mihomo) — the connection is refused at the protocol layer even though the port, keys, and SNI are all correct.

I also verified that setting minClientVer to an old value (e.g. "1.8.4") on the inbound does not help on 26.7.28 — mihomo is still rejected. The only working workaround is downgrading Xray-core to 26.6.27.

How to reproduce the problem

1. Upgrade 3x-ui to the latest version (bundled Xray-core v26.7.28).
2. Create (or keep) a VLESS + REALITY inbound.
3. Connect with mihomo/Clash Meta → REALITY authentication failed.
4. Connect with an Xray-core client ≥ v26.3.27 → works.

Expected behavior

A routine 3x-ui upgrade should not silently break all non-Xray clients. At minimum, the upgrade flow should warn the user when the bundled Xray-core introduces breaking defaults, or offer to keep the previous Xray-core version.

Actual behavior

The panel upgrade silently breaks every non-Xray client. Users are left with no server-side workaround on 26.7.28 (setting minClientVer to an older value does not help) and must downgrade Xray-core manually.

Relevant logs

Server startup (xray 26.7.28):

WARNING - XRAY: infra/conf: REALITY: The default minimal client version is Xray-core v26.3.27, other clients may be refused to connect

Client-side (mihomo):

connect error: REALITY authentication failed

3x-ui version

3.6.0

Xray-core version

26.7.28 (broken) / 26.6.27 (working)

Is the panel behind a reverse proxy or CDN?

No — direct access