Struct Session

Source

pub struct Session<K: NostrKeypair> {
    pub state: SessionState,
    /* private fields */
}

Expand description

A 1:1 double-ratchet session. Generic over the in-process keypair type K so it works with the production K256Keypair and any test signer alike.

Fields§

§state: SessionState

The serializable ratchet state.

Implementations§

Source §

impl<K: NostrKeypair> Session<K>

Source

pub fn from_state(state: SessionState) -> Self

Wrap an existing SessionState (e.g. loaded from storage).

Source

pub fn new_initiator( their_ephemeral_pubkey: &[u8; 32], our_secret: &[u8; 32], shared_secret: &[u8; 32], ) -> Result<Self, Nip104Error>

Initiator-side session bootstrap.

their_ephemeral_pubkey is the peer’s ephemeral x-only key, our_secret our ephemeral secret, and shared_secret the X3DH output.

§Errors

Propagates key-construction and NIP-44 derivation failures.

Source

pub fn new_responder( their_ephemeral_pubkey: &[u8; 32], our_secret: &[u8; 32], shared_secret: &[u8; 32], ) -> Result<Self, Nip104Error>

Responder-side session bootstrap. See Session::new_initiator.

§Errors

Propagates key-construction and NIP-44 derivation failures.

Source

pub const fn can_send(&self) -> bool

Whether the session currently holds enough state to encrypt a message.

Source

pub fn accepted_senders(&self) -> Vec<String>

The peer DH public keys (x-only hex) this session will currently accept as a message sender — exactly the set matches_sender tests: the peer’s current and next ratchet keys plus every banked skipped-chain key.

This set changes only when a message is received (the DH ratchet turns or a skipped key is banked); sending never alters it. A router can therefore index sessions by these keys and refresh the index after each plan_receive/apply, giving O(1) inbound routing instead of trial-decrypting every session.

Source

pub fn plan_send( &self, payload: &[u8], ) -> Result<(SessionState, MessageEnvelope), Nip104Error>

Encrypt payload, returning the envelope and the post-send state.

The session is not mutated; call Session::apply with the returned state to commit. This separation lets callers persist atomically.

§Errors

Nip104Error::CannotSendYet if no sending chain exists, plus any crypto failure.

Source

pub fn plan_receive( &self, envelope: &MessageEnvelope, ) -> Result<(SessionState, Vec<u8>), Nip104Error>

Decrypt envelope, returning the plaintext and the post-receive state. The session is not mutated; commit with Session::apply.

§Errors

Nip104Error::UnexpectedSender if the sender is unknown, plus any crypto or ratchet failure.

Source

pub fn apply(&mut self, next: SessionState)

Commit a planned state transition produced by Session::plan_send or Session::plan_receive.

Source

pub fn plan_send_event( &self, payload: &[u8], created_at: i64, ) -> Result<(SessionState, NostrNote), Nip104Error>

Like plan_send, but also renders a ready-to-publish, signed kind-MESSAGE_EVENT_KIND Nostr event.

The event is signed by the sender’s current ephemeral key (the one driving the ratchet), exactly as the reference implementation does — so the published event interoperates with Iris. The session is not mutated; commit the returned state with apply.

created_at is the Unix timestamp to stamp on the event.