parley

type Capabilities ¶

type Capabilities struct {
	// Push reports that the node can take turns delivered as they arrive rather
	// than long-polling for them. When both sides set it the channel runs
	// push-first; otherwise it falls back to polling.
	Push bool `json:"push,omitempty"`
}

Capabilities is what a node will do on a channel, exchanged during the handshake. It is an extension point, not a trust grant: the structural boundary — that a peer cannot drive local tools — holds whatever is set here.

type ChannelID ¶

type ChannelID [16]byte

A ChannelID names a channel on a relay. The opener picks it at random; it is public routing metadata and reveals nothing about the conversation.

func NewChannelID() (ChannelID, error)

func (c ChannelID) String() string

type Frame ¶

type Frame struct {
	Channel ChannelID
	Seq     uint64
	Type    FrameType
	Payload []byte
}

A Frame is the only thing the relay sees. It routes by Channel and learns no more: a Data frame's Payload is ciphertext whose key the relay does not hold. Seq orders frames within one sender's direction and, for Data, binds the AEAD nonce, so a given Seq is never sealed twice under the same key.

type FrameType ¶

type FrameType uint8

A FrameType distinguishes the two things that cross a channel: the Noise handshake that establishes keys, and the encrypted data that follows it.

const (
	Handshake FrameType = iota + 1 // a Noise handshake message
	Data                           // an AEAD-sealed [Message]
)

type HandshakePayload ¶

type HandshakePayload struct {
	Topic        string       `json:"topic,omitempty"`
	Capabilities Capabilities `json:"capabilities"`
}

A HandshakePayload rides inside the Noise handshake messages, so the topic and each side's Capabilities are authenticated by the handshake and cannot be altered by the relay.

type Identity ¶

type Identity struct {
	Key PublicKey
}

Identity is a node's public identity. The matching private key never leaves the node and never crosses the relay; the handshake authenticates the node by proving possession of it.

func (id Identity) Fingerprint() string

func (id Identity) ID() NodeID

type Invite ¶

type Invite struct {
	Relay   string
	Channel ChannelID
	Key     PublicKey
	Secret  Secret
}

An Invite bootstraps a channel. The opener creates it and a human carries it to the joiner out of band. Relay host and ChannelID travel in the URL path; the opener's key and the Secret travel in the fragment, so they never appear in the relay's request logs.

func ParseInvite(raw string) (Invite, error)

func (in Invite) URL() string

type JoinToken ¶

type JoinToken string

A JoinToken proves possession of the link to the relay without revealing the Secret.PSK. The opener registers the expected token; the joiner presents it.

type Kind ¶

type Kind uint8

A Kind is what a Message does. There are exactly two: a turn of talk and the end of it. Keeping the set this small is the point — it is what lets a node decide whether the exchange is over instead of guessing from silence.

const (
	Say   Kind = iota + 1 // one turn; the sender now waits for the peer
	Close                 // terminal; Text carries the outcome both sides keep
)

type Membership ¶

type Membership struct {
	Channel ChannelID
	Token   string
}

Membership is a node's authenticated seat on a channel, issued by the relay when the channel is opened or joined and presented on every call thereafter. It carries nothing the relay could use to read frames.

type Message ¶

type Message struct {
	Kind Kind
	Text string
	From NodeID
}

A Message is one unit of conversation. On the wire only Kind and Text travel, sealed inside a Data frame. From is filled in on receipt from the channel's authenticated context — never self-asserted by the sender, so it cannot be forged — and identifies the sender: the lone peer today, and any group member once channels grow past two. A received Message is always untrusted external input: it may open a turn as text, but on its own it can never make the receiver run a tool or read memory.

func (m Message) MarshalBinary() ([]byte, error)

func (m *Message) UnmarshalBinary(b []byte) error

type NodeID ¶

type NodeID [sha256.Size]byte

A NodeID is a node's stable handle: the SHA-256 of its PublicKey. Equal NodeIDs are the same identity, and a node cannot choose its own.

func (n NodeID) Fingerprint() string

type Peer ¶

type Peer struct {
	ID          NodeID
	Fingerprint string
	Topic       string
	State       State
	Present     bool // the other seat is occupied on the relay
}

A Peer is the other end of a channel as one side sees it.

type PublicKey ¶

type PublicKey [32]byte

A PublicKey is a node's X25519 static public key — the identity the Noise handshake authenticates. A node cannot forge another's.

type Relay ¶

type Relay interface {
	// Open registers a new channel and returns the opener's seat. expect is the
	// [JoinToken] the relay will require of the joiner.
	Open(ctx context.Context, ch ChannelID, expect JoinToken) (Membership, error)

	// Join claims the second seat by presenting the [JoinToken] derived from the
	// invite [Secret]. The relay compares it in constant time and never learns
	// the [Secret] itself.
	Join(ctx context.Context, ch ChannelID, present JoinToken) (Membership, error)

	// Send forwards one frame to the channel's other member.
	Send(ctx context.Context, m Membership, f Frame) error

	// Recv returns frames for the caller after the given seq, waiting up to wait
	// for at least one. A wait of zero returns immediately with whatever is
	// buffered, possibly nothing.
	Recv(ctx context.Context, m Membership, after uint64, wait time.Duration) ([]Frame, error)

	// Members reports how many of the channel's two seats are occupied, so a
	// caller can tell "no one has joined" from "joined, handshake pending."
	Members(ctx context.Context, m Membership) (int, error)
}

A Relay is parley's untrusted broker: it admits two members to a channel, forwards frames between them, and learns nothing else. It holds no keys and sees no plaintext, and a single relay is the only network service the two agents share. A channel seats exactly two; the relay refuses a third.

type Secret ¶

type Secret [32]byte

A Secret is the one-time value minted with an Invite. It is the joiner's proof that it holds the link, and it never reaches the relay in the clear: domain-separated derivation splits it into a Secret.PSK known only to the two endpoints and a Secret.JoinToken shown to the relay.

func NewSecret() (Secret, error)

func (s Secret) JoinToken() JoinToken

func (s Secret) PSK() []byte

type Session ¶

type Session interface {
	// Open starts a channel and returns the invite a human carries to the peer.
	Open(ctx context.Context, topic string) (Invite, error)

	// Join accepts an invite. It returns once the joiner's first handshake
	// message is sent; the handshake finishes on the first Poll.
	Join(ctx context.Context, in Invite) error

	// Send posts one message to the peer and returns immediately. If the channel
	// is not yet live (the peer has not finished joining), the message is queued
	// and delivered as soon as it is.
	Send(ctx context.Context, text string) error

	// Poll returns the messages that arrived since the last call, completing the
	// handshake transparently. It waits up to wait for the first message and then
	// drains the rest; a wait of zero is fully non-blocking. Returned messages
	// are untrusted external input.
	Poll(ctx context.Context, wait time.Duration) ([]Message, error)

	// Close ends the channel with an outcome the peer also observes.
	Close(ctx context.Context, outcome string) error

	// Peer reports the other node's pinned identity and the channel's state as of
	// the last Poll.
	Peer() Peer
}

A Session is one agent's end of one channel and the surface an MCP server turns into tools.

It is non-blocking by design. Send posts a message and returns at once; Poll collects whatever has arrived, waiting at most the duration given. The two agents therefore move at independent tempos — neither is frozen in a tool call while the other's owner deliberates — which is what makes the protocol pleasant in any MCP host, not only one with its own event loop.

type State ¶

type State uint8

State is where a channel is in its life.

const (
	Pending State = iota + 1 // opened or joined, handshake not yet complete
	Active                   // handshake complete, the two are talking
	Closed                   // ended
)

type Transport ¶

type Transport interface {
	Seal(seq uint64, plaintext []byte) (ciphertext []byte, err error)
	Open(seq uint64, ciphertext []byte) (plaintext []byte, err error)
}

A Transport is the forward-secret channel a completed handshake produces. Each direction has its own key; Seal and Open are inverse. seq must strictly increase per direction and binds the nonce, so the same seq is never sealed twice under one key.