Skip to content

feat: fallback to ICANN endpoint for native clients when Pubky TLS is unreachable#324

Open
francismars wants to merge 2 commits intopubky:mainfrom
francismars:feat/native-icann-fallback
Open

feat: fallback to ICANN endpoint for native clients when Pubky TLS is unreachable#324
francismars wants to merge 2 commits intopubky:mainfrom
francismars:feat/native-icann-fallback

Conversation

@francismars
Copy link

@francismars francismars commented Feb 24, 2026

This PR adds native SDK fallback to ICANN HTTPS when Pubky TLS is unreachable.

Why

Native clients can fail to reach Pubky-host endpoints when a homeserver is behind Cloudflare Tunnel, NAT, or other proxy/network setups. In these cases, PKARR may advertise a Pubky TLS endpoint that is not reachable from the client network, while the ICANN HTTPS endpoint is reachable.

What changed

In pubky-sdk/src/client/http_targets/native.rs:

  • Added native fallback logic in cross_request:
    • Keep normal Pubky TLS path for Pubky hosts.
    • If Pubky TLS endpoint is unreachable, fallback to ICANN HTTPS endpoint and attach pubky-host header.
  • Added endpoint resolution + reachability probe helpers:
    • Resolve PKARR HTTPS endpoints for the target key.
    • Probe Pubky TLS endpoint via TCP with a 3s timeout.
    • Use ICANN endpoint when probe fails and ICANN endpoint exists.
  • Tightened host handling parity:
    • Malformed _pubky.* now routes to ICANN handling instead of falling through to Pubky TLS.
  • Added native regression tests for:
    • malformed _pubky.* classification
    • rejection of pubky<z32> transport host in prepare_request
    • rejection of _pubky.pubky<z32> via cross_request
    • fallback/no-fallback behavior for unreachable/reachable Pubky TLS endpoints

Behavior summary

  • Before: Native requests to Pubky hosts preferred Pubky TLS and could fail when that endpoint was unreachable from the client network.
  • After: Native requests still prefer Pubky TLS, but automatically fallback to ICANN HTTPS when Pubky TLS is not reachable.

Test plan

  • cargo test -p pubky --lib http_targets::native -- --nocapture
  • cargo clippy -p pubky -- -D warnings
  • Manual SDK E2E (no Ring build): ✅
    • Ran a temporary native SDK signup binary against Umbrel + Cloudflare homeserver using signup token.
    • Signup succeeded and returned valid session info.

Scope / non-goals

  • No Ring app changes in this PR.
  • No change to WASM path.
  • No change to PKARR publishing format; this is client-side routing/fallback behavior only.

francismars and others added 2 commits February 23, 2026 20:31
…able

When a homeserver is behind a Cloudflare Tunnel (or NAT/firewall), the native Pubky TLS endpoint (port 6287) is unreachable from external clients. This adds a TCP probe + fallback: if the Pubky TLS endpoint times out within 3s and an ICANN endpoint is published in the PKARR record, the request is transparently rerouted to the ICANN HTTPS endpoint with a pubky-host header.

Co-authored-by: Cursor <cursoragent@cursor.com>
Route malformed _pubky hosts through ICANN handling for native parity and
add focused regression tests for prefixed transport host rejection in
prepare_request and cross_request.

Co-authored-by: Cursor <cursoragent@cursor.com>
@francismars
Copy link
Author

@SeverinAlexB please review 🤲

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