Skip to content

feat(fibre): Add TLS support - #996

Merged
citizen-stig merged 8 commits into
mainfrom
nikolai/fibre-tls-support
Sep 1, 2026
Merged

feat(fibre): Add TLS support#996
citizen-stig merged 8 commits into
mainfrom
nikolai/fibre-tls-support

Conversation

@citizen-stig

@citizen-stig citizen-stig commented Aug 31, 2026

Copy link
Copy Markdown
Collaborator

Overview

According to celestia-app fibre/cmd README:

https://github.com/celestiaorg/celestia-app/blob/ea02b6f61c02f296703710cbf0a7ce631ebce174/fibre/cmd/README.md?plain=1#L142

The Fibre server↔client gRPC link is TLS-only (TLS 1.3, always on, no
plaintext fallback). The server presents a self-signed certificate whose
ephemeral TLS key is endorsed by the validator's consensus key (signed via
SignRawBytes and embedded in a custom X.509 extension). The client verifies
that the peer's certificate is endorsed by the exact validator it intended to
dial, using the consensus pubkey from the current validator set.

Existing fibre client tries to connect as plaintext.

This PR addresses it

Solution

FibreIoConnector

Fibre separates socket creation from the protocol stack through FibreIoConnector. A connector opens an unauthenticated host:port byte stream implementing Tokio AsyncRead and AsyncWrite; Fibre then applies its authenticated TLS transport and runs HTTP/2 gRPC over it.

A non-browser WASM runtime can support Fibre from a downstream crate by implementing FibreIoConnector with its platform socket API, adapting the socket’s readable and writable streams into a boxed FibreIo, and injecting it through FibreClient::from_endpoint_with_io_connector. JavaScript-backed handles may require a single-thread wrapper to satisfy the connector’s Send bounds.
This keeps runtime-specific SDK dependencies out of Lumina while reusing Fibre’s TLS verification and protocol implementation.

Final architecture:

  • FibreIoConnector opens a raw bidirectional connection to a validator. It does not handle TLS or gRPC.
  • Native builds use NativeTcpConnector, which opens a normal TCP socket automatically.
  • Browser WASM builds always include BrowserWebSocketConnector. It creates a raw TCP tunnel through a WebSocket relay.
  • Other WASM runtimes implement FibreIoConnector in their own crate using their platform socket API.
  • WASM callers must explicitly supply a connector because Lumina cannot know which transport or relay to use. Calling the default constructor on WASM returns IoConnectorRequired.
  • After receiving the raw stream, Fibre always performs validator-authenticated Rustls TLS 1.3 and then starts HTTP/2 gRPC.

In short:

Native:       TCP ──────────────┐
Browser WASM: WebSocket tunnel ─┼─> Fibre TLS 1.3 ─> HTTP/2 ─> gRPC
Other WASM:   custom connector ─┘

Misc

Another reference from celestia-app celestiaorg/celestia-app#7306

@citizen-stig citizen-stig changed the title feat(fibre): Add TLS support for non-wasm targets feat(fibre): Add TLS support Aug 31, 2026
@citizen-stig
citizen-stig marked this pull request as ready for review September 1, 2026 07:43
@citizen-stig
citizen-stig requested a review from a team as a code owner September 1, 2026 07:43
@citizen-stig
citizen-stig requested review from mcrakhman and renaynay and removed request for a team and renaynay September 1, 2026 07:43
@citizen-stig
citizen-stig merged commit 4417a62 into main Sep 1, 2026
94 of 96 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.

2 participants