Skip to content

fix(websockets): bracket IPv6 hosts in the iOS handshake - #27

Merged
edusperoni merged 2 commits into
masterfrom
fix/websockets-ipv6-host
Nov 21, 2026
Merged

edusperoni merged 2 commits into
masterfrom
fix/websockets-ipv6-host

Conversation

@edusperoni

@edusperoni edusperoni commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Symptom

On iOS, opening a WebSocket to an IPv6-literal URL such as ws://[fd7d:b219:4d03::2]:5173/ sends a handshake whose Host and Origin headers have no brackets around the address:

Host: fd7d:b219:4d03::2:5173
Origin: http://fd7d:b219:4d03::2:5173

RFC 3986 §3.2.2 and RFC 7230 §5.4 require IPv6 literals to be bracketed there. Servers that validate Host reject the upgrade, so the connection never opens. Vite's dev server host check is one example. This was seen on physical iOS 26 devices that reach a dev server over the CoreDevice USB tunnel, which uses an IPv6 ULA.

Root cause

The vendored SocketRocket fork, RCTSRWebSocket, builds both default headers from NSURL.host. For an IPv6 literal, NSURL.host returns the address without its brackets.

  • Host: native-src/ios/NativeScriptWebSockets/RCTSRWebSocket.m, -didConnect (was line 452: [NSString stringWithFormat:@"%@:%@", _url.host, _url.port])
  • Origin: -[NSURL RCTSR_origin] in the same file (was lines 1573-1575: @"%@://%@:%d", scheme, self.host, port)

Fix

The fix is in the native code. A new RCTSR_hostForHeader property on the file-private NSURL (RCTSRWebSocket) category returns NSURL.host wrapped in brackets when the host contains : and does not already start with [. Otherwise it returns the host unchanged. Host and Origin both use it.

  • The port and default-port handling is unchanged. Host keeps an explicit port. Origin drops the scheme's default port.
  • CFStreamCreatePairWithSocketToHost in _initializeStreams still gets the raw, unbracketed host. The fork sets no explicit TLS peer name, so TLS uses that same raw host.
  • Caller-supplied headers are applied after the defaults, as before, so a custom Origin still wins.
  • No other place in native-src formats the host into a URL or header. There is no proxy or CONNECT path in the fork.
  • No TypeScript changes. The workaround in the first version of this PR (bridge.ios.ts overrides, a handshake-headers.ts helper, and a Jest target) has been removed.

Zone-scoped literals such as fe80::1%en0 are bracketed as NSURL.host returns them. The zone is not re-encoded as %25.

Regenerated xcframework

platforms/ios/NativeScriptWebSockets.xcframework was rebuilt with the package's own script, native-src/ios/build.sh (the build.native target), using DEVELOPER_DIR=/Applications/Xcode-16.4.0.app on macOS 15.8.3.

  • Toolchain: Xcode 16.4 (16F6), iOS SDK 18.5, visionOS SDK 2.5. This matches the SDKs recorded in the previous artifact.
  • The slices are the same: ios-arm64, ios-arm64_x86_64-simulator, ios-arm64-maccatalyst, xros-arm64, xros-arm64-simulator.
  • In the fix commit, lipo -info and vtool -show-build output (architectures, platform, minos, sdk) is identical before and after. The visionOS minos then changes in the follow-up commit; see the next section.
  • Headers and module maps are unchanged.
  • Besides the binaries and dSYMs, the diff contains only BuildMachineOSBuild in the per-slice Info.plists and a reordering of the library entries in the top-level Info.plist.
  • No Android artifacts changed. The package has no Android native code; it uses OkHttp.

visionOS deployment target

The Xcode project set IPHONEOS_DEPLOYMENT_TARGET = 9.0 but no XROS_DEPLOYMENT_TARGET. The visionOS slices therefore took the building Xcode's visionOS SDK version as their minimum: 2.5 with Xcode 16.4, or 26.2 with Xcode 26.3. A second commit sets XROS_DEPLOYMENT_TARGET = 1.0 in the project-level Debug and Release configurations, next to the iOS setting.

Why 1.0:

  • It is the lowest value that both the Xcode 16.4 and the Xcode 26.3 visionOS SDKs accept (MinimumDeploymentTarget in SDKSettings.json).
  • It matches the floor that the NativeScript runtime's SwiftPM manifest declares for visionOS (.visionOS(.v1)), so the plugin never raises the bar above the runtime. The runtime's libffi build targets 2.0, and the shipped @nativescript/visionos 9.0.1 binaries currently carry minos 26.0, because the runtime also leaves its own target unset.
  • The native code uses only Foundation, Security and CommonCrypto. The xros builds produce no unguarded-availability warnings with CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE.

minos per slice (from otool -l):

Slice Before After
ios-arm64 9.0 (LC_VERSION_MIN_IPHONEOS) 9.0, byte-identical
ios-arm64_x86_64-simulator x86_64 9.0, arm64 14.0 unchanged, byte-identical
ios-arm64-maccatalyst 14.0 unchanged, byte-identical
xros-arm64 2.5 1.0
xros-arm64-simulator 2.5 1.0

Toolchain: I built with native-src/ios/build.sh under the machine's default Xcode 26.3. That build gave visionOS minos 1.0, which shows the setting makes the result independent of the Xcode version. It also moved every iOS and Catalyst slice to SDK 26.2 and changed their binaries, although their minos stayed the same. The committed framework is therefore the Xcode 16.4 build (DEVELOPER_DIR=/Applications/Xcode-16.4.0.app/Contents/Developer, iOS SDK 18.5, visionOS SDK 2.5). Only the two xros slices and their dSYMs differ from the previous commit.

I re-ran the iOS 26.3 simulator smoke test with the committed framework (same dwarfdump --uuid). ws://[::1]:9897 sent Host: [::1]:9897 and Origin: http://[::1]:9897, got 101, and fired onopen. I did not run a visionOS launch, because the demo app has no visionOS runtime dependency or config. The xros dSYM UUIDs match their binaries. The xros relocation maps are now populated like the iOS ones (previously empty).

Verification

I ran a raw TCP server bound to [::]:9897. It logs the request head and answers 101 only when Host is a bracketed IPv6 literal. The demo app ran four probes in sequence. On iOS, the built .app embedded the rebuilt simulator slice (same dwarfdump --uuid).

Platform URL Host sent Origin sent Result
iOS 26.2 sim, before ws://[::1]:9897 ::1:9897 http://::1:9897 403, onerror
iOS 26.2 sim, after ws://[::1]:9897 [::1]:9897 http://[::1]:9897 101, onopen
iOS 26.2 sim, after ws://127.0.0.1:9897 127.0.0.1:9897 http://127.0.0.1:9897 unchanged (403 by design of the test server)
iOS 26.2 sim, after ws://localhost:9897 localhost:9897 http://localhost:9897 unchanged (403 by design of the test server)
iOS 26.2 sim, after ws://[::1]:9897 + headers.origin [::1]:9897 http://custom.example 101, onopen
Android 15 (API 35) emulator, no change ws://[::1]:9897 [::1]:9897 http://[::1]:9897 101, onopen
Android 15 (API 35) emulator, no change ws://127.0.0.1:9897 127.0.0.1:9897 http://127.0.0.1:9897 as expected (403 by design)
Android 15 (API 35) emulator, no change ws://localhost:9897 localhost:9897 http://localhost:9897 as expected (403 by design)
Android 15 (API 35) emulator, no change ws://[::1]:9897 + headers.origin [::1]:9897 http://custom.example 101, onopen

The iOS "before" row comes from the earlier run of this PR on the same simulator against the same server, using the previously committed framework.

Every request carried exactly one Host line and one Origin line.

Android already handles IPv6 literals correctly, so it needs no change. OkHttp 4.9.3 brackets the Host header, and the plugin's default Origin comes from java.net.URI.getHost(), which keeps the brackets. On the emulator, adb reverse tcp:9897 tcp:9897 listens on the device's [::]:9897. So ws://[::1]:9897 went over the device's IPv6 loopback, and the headers above are what the app sent.

Also ran:

  • nx run nativescript-websockets:lint: no errors. The 4 warnings were already there.
  • nx run nativescript-websockets:build --exclude-task-dependencies: passes. dist carries the rebuilt framework.
  • The package has no unit tests.

@nx-cloud

nx-cloud Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

View your CI Pipeline Execution ↗ for commit ad54234

Command Status Duration Result
nx affected --target=build.all ✅ Succeeded 1m 45s View ↗
nx affected:lint ✅ Succeeded 1s View ↗

💡 With Ultracache enabled, Nx Cloud learns each task's file inputs in CI and uses them on later runs. Turn on Ultracache in workspace settings ↗ · Read docs ↗


☁️ Nx Cloud last updated this comment at 2026-11-20 20:33:30 UTC

RCTSRWebSocket built the default Host and Origin headers from NSURL.host,
which returns IPv6 literals without brackets. ws://[::1]:9897 sent
"Host: ::1:9897" and "Origin: http://::1:9897", so servers that validate
Host (e.g. Vite's dev server) rejected the upgrade.

Add an RCTSR_hostForHeader helper on the private NSURL category that
brackets a host containing ':' unless it already starts with '[', and use
it for Host and Origin. The socket connection keeps using the raw host.

Regenerate NativeScriptWebSockets.xcframework with native-src/ios/build.sh
under Xcode 16.4 (iOS SDK 18.5, visionOS SDK 2.5), the toolchain of the
previous artifact, so slices, architectures and deployment targets are
unchanged.
@edusperoni
edusperoni force-pushed the fix/websockets-ipv6-host branch from 66d0186 to 3cc96fa Compare November 20, 2026 19:37
The Xcode project set no XROS_DEPLOYMENT_TARGET, so the visionOS slices
took the building Xcode's SDK version as their minimum (2.5 with
Xcode 16.4, 26.2 with Xcode 26.3). Set it to 1.0 in the project-level
Debug and Release configurations, next to IPHONEOS_DEPLOYMENT_TARGET.

Rebuilt the xcframework with native-src/ios/build.sh under Xcode 16.4.
Only the xros-arm64 and xros-arm64-simulator slices change (minos
2.5 -> 1.0); the iOS and Mac Catalyst binaries are byte-identical.
@edusperoni
edusperoni merged commit 87d3246 into master Nov 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant