#15907: fix(discovery): propagate TLS fingerprint through gateway discovery chain
app: android
app: macos
stale
size: S
trusted-contributor
Cluster:
Gateway and TLS Enhancements
## Fix Summary
Propagate `gatewayTlsSha256` TLS fingerprint through the full gateway discovery chain on macOS (Bonjour + Wide Area) and add `requiresVerification` flag to Android discovered endpoints. This is the infrastructure prerequisite for certificate pinning enforcement.
## Issue Linkage
Refs #15906
## Security Snapshot
- CVSS v3.1: 8.3 (High)
- CVSS v4.0: 9.0 (Critical)
- CWE-287 (Improper Authentication), CWE-300 (Channel Accessible by Non-Endpoint)
## Implementation Details
### Files Changed
- `apps/macos/Sources/OpenClawDiscovery/WideAreaGatewayDiscovery.swift` — Add `tlsFingerprintSha256` to `WideAreaGatewayBeacon`, extract `gatewayTlsSha256` from DNS-SD TXT records
- `apps/macos/Sources/OpenClawDiscovery/GatewayDiscoveryModel.swift` — Add `tlsFingerprintSha256` to `DiscoveredGateway` and `GatewayTXT`, propagate through Bonjour and Wide Area fallback paths, log warning for unverified gateways
- `apps/android/app/src/main/java/ai/openclaw/android/gateway/GatewayEndpoint.kt` — Add `requiresVerification` field (true for discovered, false for manual)
- `apps/android/app/src/main/java/ai/openclaw/android/gateway/GatewayDiscovery.kt` — Log warning when TLS fingerprint is missing from discovered endpoints (local + wide-area)
### Technical Analysis
The discovery mechanism uses mDNS/Bonjour (local) and DNS-SD (wide area) to find gateways. These are inherently unauthenticated broadcast protocols. Android already extracted the `gatewayTlsSha256` TXT field but never enforced it; macOS did not extract it at all. Without the fingerprint propagated through the discovery chain, there is no data available for certificate pinning at connection time.
This change ensures the TLS fingerprint is available at every point in the discovery pipeline where connection decisions are made — the prerequisite for pinning enforcement in a follow-up PR.
## Validation Evidence
- Command: `pnpm build && pnpm check`
- Status: passed (build clean, 0 lint warnings, 0 format errors)
- Note: Changes are to Kotlin/Swift native code only; TypeScript test suite is unaffected
## Risk and Compatibility
Non-breaking. All new fields use default values (`nil`/`null`/`true`) preserving backward compatibility. Existing gateway connections are unaffected — this change only adds data propagation infrastructure.
## AI-Assisted Disclosure
- AI-assisted: yes
- Model: Claude Opus 4.6
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
Propagates the `gatewayTlsSha256` TLS fingerprint through the full gateway discovery chain on macOS (Bonjour + Wide Area DNS-SD) and adds a `requiresVerification` flag to Android `GatewayEndpoint`. This is the infrastructure prerequisite for certificate pinning enforcement in a follow-up PR.
- **macOS**: `WideAreaGatewayBeacon` and `DiscoveredGateway` now carry `tlsFingerprintSha256`, extracted from DNS-SD TXT records and propagated through both Bonjour and Wide Area fallback paths. `GatewayTXT` struct and `parseGatewayTXT()` updated to parse the `gatewayTlsSha256` field.
- **Android**: Discovery paths (local + wide-area) now set `requiresVerification = true` on discovered endpoints; manual endpoints get `false`. Warning logs added when fingerprint is absent.
- All new fields use optional/default values (`nil`/`null`/`true`), preserving backward compatibility. No breaking changes to existing gateway connections.
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge — it adds data propagation infrastructure with no behavioral changes to existing connections.
- Score reflects clean, additive-only changes with backward-compatible defaults across all four files. The fingerprint propagation follows established patterns for other TXT record fields. No logic changes to connection behavior — this is purely plumbing for a follow-up pinning enforcement PR. Minor note: warning logs in both Android and macOS discovery paths will fire repeatedly for gateways lacking fingerprints (every 5s on Android wide-area polling, on every NWBrowser state change on macOS), which is acceptable for debugging but worth being aware of.
- No files require special attention. All changes are straightforward field additions and TXT record extraction following existing code patterns.
<sub>Last reviewed commit: cc6ce95</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#22682: fix(gateway): [P0] status probe ignores gateway.tls.enabled — hardc...
by mahsumaktas · 2026-02-21
77.7%
#22453: fix(tui): resolve and pass tlsFingerprint for secure connections [A...
by captmoss · 2026-02-21
75.2%
#11205: Android: fix gateway connection and canvas URL for Tailscale serve
by emonty · 2026-02-07
75.0%
#4653: fix(gateway): improve crash resilience for mDNS and network errors
by AyedAlmudarra · 2026-01-30
73.5%
#8260: fix(macOS): gateway readiness detection + reversible Configure later
by xksteven · 2026-02-03
73.4%
#23735: Gateway: add first-class wss validation and remote TLS guidance
by bmendonca3 · 2026-02-22
73.3%
#22716: fix: gateway status probe uses wss:// when TLS enabled; accept self...
by Fratua · 2026-02-21
73.2%
#2530: fix(gateway): improve auth error for native apps
by Episkey-G · 2026-01-27
72.9%
#23403: Discovery: gate non-loopback full mDNS mode
by bmendonca3 · 2026-02-22
72.8%
#21842: fix(gateway-cli): use wss:// scheme when gatewayTls is enabled
by hydro13 · 2026-02-20
72.6%