Skip to content
theia-hqPublic

About

Reach a peer by its ed25519 key over a swappable transport: iroh today, a from-scratch UDP transport beside it

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

bifrost

Open a byte-stream to a machine identified by its public key, wherever it is on the internet, across NATs, without knowing its address. Identity is an ed25519 public key (a NodeId): you address who a peer is, not where. bifrost gives you the connection and nothing more; what you send over it is up to you.

It carries the connection over its own backends: iroh (QUIC with NAT hole-punching) and an in-process backend for tests.

The name. Bifröst is the burning rainbow bridge of Norse myth, the span that reaches from one world to any other. This crate is the bridge to a peer: name a public key and it carries a connection there.

Experimental. APIs will change and it is not ready for production use.

Add it as a dependency

Git-only for now, not published to crates.io. Point at the repo:

[dependencies]
bifrost = { git = "https://github.com/theia-hq/bifrost" }
bifrost-iroh = { git = "https://github.com/theia-hq/bifrost" }

Compose a node, dial by key

Compose a transport with a discovery mechanism into a Node, then dial peers by identity:

use bifrost::{Node, NoDiscovery, Session};
use bifrost_iroh::Endpoint;

let node = Node::new(Endpoint::bind().await?, NoDiscovery);
let session = node.connect(peer_id).await?;
let (mut writer, mut reader) = session.open_bi().await?;

Transport, Session, and Discovery are the pluggable interfaces. Implement Transport to add a backend; it passes the conformance suite, so a dial written against these interfaces runs unchanged over any of them. A shipping backend proves the peer's key in its handshake and protects its streams under that handshake's keys; the in-process backend is for tests and proves nothing.

The crates

crate role
bifrost facade: the connection API (Node, Transport, Session, Discovery)
bifrost-core identity: NodeId, an ed25519 public key with a crypto-suite tag
bifrost-transport the Transport and Session traits
bifrost-iroh transport backend over iroh (QUIC with NAT hole-punching)
bifrost-mem in-process transport backend for hermetic tests
bifrost-mdns discovery over mDNS on the local network
bifrost-conformance transport-agnostic test suite every backend must pass
bifrost-wire one-shot blob transfer over a stream, BLAKE3-verified end to end

This page describes the default branch.

Things to know

  • bifrost establishes the connection and hands you a byte-stream. It says nothing about what those bytes mean; that is the caller's protocol.
  • Verified blob transfer lives in bifrost-wire, a sibling crate the facade re-exports as bifrost::wire.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

About

Reach a peer by its ed25519 key over a swappable transport: iroh today, a from-scratch UDP transport beside it

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages