iwlink 0.1.1

IntelliWallet Link - encrypted phone to computer protocol for IntelliWallet for Browser
Documentation
//! IntelliWallet Link: the encrypted protocol between the IntelliWallet phone
//! app and the IntelliWallet for Browser helper on a computer.
//!
//! The helper advertises a Bluetooth Low Energy service; the phone connects to
//! it and the two run a Noise handshake over GATT. Once the handshake is done,
//! every message between them is a JSON [`Message`] sealed by the Noise
//! transport. Bluetooth itself is treated as an open radio: nothing here relies
//! on Bluetooth pairing or link-layer encryption.
//!
//! The crate is deliberately free of platform code. It never touches
//! Bluetooth, files, the Keychain or the clock: callers pass bytes and the
//! current time in, and get bytes out. That is what lets the same code run in
//! the phone app (through iwapp's own Rust layer) and in the macOS helper, and
//! what lets the tests control time.
//!
//! # Layers, bottom up
//!
//! - [`frame`]: splits a sealed message into Bluetooth-sized fragments and
//!   puts them back together.
//! - [`noise`]: the two handshakes ([`noise::Handshake`]) and the transport
//!   ([`noise::Session`]).
//! - [`message`]: the typed messages and their limits.
//!
//! Beside them, [`pairing`] encodes the QR code that starts a pairing,
//! [`version`] negotiates the protocol version, and [`grant`] holds the timing
//! rules both sides must agree on.
//!
//! # Handshakes
//!
//! - **Pairing**, once per computer: `Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s`.
//!   The phone is the initiator. It learns the helper's static key and a
//!   one-time pre-shared key from the QR code, so a helper that did not show
//!   that QR code cannot complete the handshake.
//! - **Reconnect**, every later connection:
//!   `Noise_KK_25519_ChaChaPoly_BLAKE2s`. Both sides already hold each other's
//!   static key from pairing.
//!
//! Fresh ephemeral keys on both sides make every session unique, so a recorded
//! session cannot be replayed into a new one.
//!
//! # Example
//!
//! ```
//! use iwlink::{Handshake, HelperId, PairingOffer, StaticKeypair};
//!
//! let now = 1_800_000_000;
//!
//! // Helper: show a QR code.
//! let helper = StaticKeypair::generate()?;
//! let offer = PairingOffer::create(HelperId::generate()?, helper.public(), "Studio Mac", now)?;
//! let qr_text = offer.to_uri();
//!
//! // Phone: scan it and start pairing.
//! let phone = StaticKeypair::generate()?;
//! let scanned = PairingOffer::parse(&qr_text)?;
//! let mut initiator = Handshake::pairing_initiator(&phone, &scanned, 1, now)?;
//! let mut responder = Handshake::pairing_responder(&helper, &offer.psk, 1)?;
//!
//! let first = initiator.write(b"")?;
//! responder.read(&first)?;
//! let second = responder.write(b"")?;
//! initiator.read(&second)?;
//!
//! let mut phone_side = initiator.finish()?;
//! let mut helper_side = responder.finish()?;
//! let sealed = phone_side.session.seal(b"hello")?;
//! assert_eq!(helper_side.session.open(&sealed)?.as_slice(), b"hello");
//! # Ok::<(), iwlink::LinkError>(())
//! ```

pub mod error;
pub mod frame;
pub mod grant;
pub mod keys;
pub mod message;
pub mod noise;
pub mod pairing;
pub mod version;

mod random;

pub use error::{LinkError, Result};
pub use keys::{PublicKey, StaticKeypair};
pub use message::Message;
pub use noise::{Established, Handshake, Session};
pub use pairing::{HelperId, PairingOffer};
pub use version::VersionRange;