DEV Community: UNYIME ETIM

Discovery Is Not Authentication: Designing a Local-Network File Transfer System in Rust

UNYIME ETIM — Sat, 03 Oct 2026 09:46:51 +0000

Lanweave is an open-source Rust application that sends files and folders between devices on the same local network. Two people run the terminal UI, one selects the other's device, they pair with a one-time code, and either side can propose files; the recipient reviews the full list and chooses where the files land. There is no account, no cloud service, and no background daemon. The device that starts a connection is the initiator; the device that accepts it is the responder.

This article is an engineering case study of that architecture: how discovery, encryption, pairing, per-transfer approval, session lifecycle, and filesystem handling fit together — and where the guarantees stop.

Status, stated up front: Lanweave is a work in progress, has not been audited, and is not safe for sensitive files. The pairing implementation is a prototype on an unaudited PAKE library, and the project keeps a release gate open pending specialist review. Nothing below claims the system is secure; the goal is to explain the reasoning and name what is not established. The repository is the authority for every statement: github.com/etim66/lanweave.

The problem, stated precisely

The goal is narrow: move files between two devices on the same LAN, using only those devices, with clear consent at every step. That narrowness is what makes the security design interesting — the usual shortcut, a server both sides trust, is not available.

The constraints I set for the first version:

No central infrastructure. The app must work on an isolated network with no internet access and no coordination server.
No persistent trust. Authorization belongs to one live connection: no trusted-device database, no reusable certificate, no reconnect token.
The LAN is hostile input. Any device can publish discovery records, copy display names, open connections, and send arbitrary bytes.
Received data is untrusted until proven otherwise. A filename on the wire is not a path; a byte count on the wire is not the size of what arrives.
Bounded everything. Memory, queues, parse sizes, prompt lifetimes, and idle time all have fixed limits, because "the peer behaves" is not something the receiver controls.

Those constraints split the problem into separate questions:

Discovery and authentication: where might a peer be, and is this the device the user intends?
Authorization: may this peer send these files?
Confidentiality and integrity: who can read the bytes, and is what arrived what was sent?
Lifecycle: how long does any of this last?
Filesystem safety: what happens to the bytes after they arrive?

That decomposition produces the central claim of this article:

Discovering a device on a network is not the same thing as authenticating it.

mDNS answers where a listener might be, not who operates it. Any device can advertise _lanweave._tcp.local., copy a display name, or point a connection at an endpoint it controls. A design that treats "it appeared in the device list" as trust would fail immediately. In Lanweave, discovery produces candidates; only pairing turns a candidate into the intended connection.

flowchart LR
    subgraph LAN["LAN — untrusted"]
        MDNS[mDNS records<br/>spoofable, unauthenticated]
        PEER[Any TCP peer<br/>arbitrary bytes]
    end

    subgraph APP["Lanweave process"]
        DISC[Discovery<br/>candidate list, bounds, escaping]
        TLS[Transport<br/>TLS 1.3, fresh identity per connection]
        PAIR[Pairing<br/>one-time code + PAKE confirmation]
        SESS[Protocol state machine<br/>authorized idle session]
        REVIEW[Transfer review<br/>manifest + local accept/reject]
        STORE[Storage<br/>validate → temp file<br/>→ verify → publish]
    end

    USER[Local user decisions]

    MDNS --> DISC
    DISC -->|select a candidate| PEER
    PEER --> TLS --> PAIR
    USER -->|accept or reject request| PAIR
    PAIR --> SESS --> REVIEW
    USER -->|approve manifest, choose directory| REVIEW --> STORE

The rest of this article walks down that stack, focusing on what messages are allowed to mean. The wire format itself — frame boundaries, decoding, streaming without loading whole files into memory — belongs to the companion article, TCP Is a Byte Stream: Designing a Framed Application Protocol in Rust with Tokio.

System shape

Lanweave is one Cargo package: a private library and a thin binary. The modules that matter here are discovery, transport, pairing, protocol, session, transfer, and storage, composed by a bootstrap module that owns task startup and ordered shutdown.

Two architectural rules shape the security reasoning:

One task owns each connection and its mutable state. Reader, writer, file I/O, and timer code talk to that owner through bounded channels; the UI gets a read-only snapshot and never mutates live session state.
Layers cannot make decisions that belong to other layers. Protocol validation has no dependency on the TUI, sockets, mDNS, or the filesystem. Transport carries frames but does not decide consent. Storage validates names but never invents overwrite or rename behavior. The TUI renders state but contains no protocol rules.

That separation makes the state machine testable without a network, the frame decoder fuzzable without a filesystem, and "who is allowed to decide this?" answerable one layer at a time.

Discovery: a candidate list, not a trust list

Lanweave advertises and browses a DNS-SD service, _lanweave._tcp.local., using mDNS, so devices appear without configuration (RFC 6762, RFC 6763). The SRV record supplies the host and port. The TXT record carries exactly one value:

Key	Value	Meaning
`v`	`1`	The listener speaks experimental protocol version 1

The service instance is the local computer name, sanitized into a DNS label but keeping its casing, so the list stays human-readable. The host record is not the computer name: it is a per-run lowercase label with a random suffix, because reusing the computer name can collide with the platform's own responder. The app also tracks its own advertisement aliases and mDNS name-conflict events, so it does not list itself as a peer.

Why mDNS? With no server in the design, there are three options:

Manual host:port entry avoids multicast, but users must find and share addresses.
A coordination service assumes a reachable coordinator, contradicting the isolated-network requirement.
Zero-configuration discovery (mDNS/DNS-SD) is already deployed on most LANs and needs no server, configuration, or internet connection.

I chose the third; direct host:port entry remains a fallback, not a replacement.

What mDNS is not. mDNS records are unauthenticated by design — a naming mechanism, not a security mechanism. Any device can publish a record, copy a name, or flood the network with noise.

When multicast fails. Guest Wi-Fi and VLAN policies sometimes block multicast, so the app accepts a direct host:port that skips mDNS and nothing else: pairing, the one-time code, and transfer approval still apply.

IPv4 only, for now. This version disables IPv6 in the listener and the discovery adapter: the listener binds an IPv4 wildcard socket on an ephemeral port, and the mDNS adapter disables IPv6 interfaces rather than relying on dual-stack defaults. That is a v1 limitation, not a claimed capability.

The candidate store bounds the number of devices, the endpoints per device, and the byte length of service, host, and interface names, so hostile advertisements cannot become a resource problem. Names are untrusted display text: control characters and Unicode bidirectional controls are escaped into visible \u{XXXX} sequences before rendering, and the device list labels them untrusted rather than treating them as identity. When a device disappears, any selection of it is cleared, so a stale row cannot connect to a device that has been replaced.

Discovery is not a runtime dependency of an established session: once two peers have paired, losing the mDNS record neither closes nor alters the session. The connection, not the record, is the unit of trust.

The encrypted channel: TLS before any trust exists

The order of operations is deliberate: TCP connects, TLS 1.3 completes, and only then does any application message flow. ALPN carries the identifier lanweave/1, and the connection is TLS 1.3 only: both sides configure rustls with TLS 1.3 as the sole version, and the initiator's verifier fails closed if a TLS 1.2 handshake signature reaches it (RFC 8446).

Why TLS rather than a custom encrypted transport? Because there is no version of "we'll implement our own record layer" that ends well. TLS 1.3 has been analysed, implemented, and deployed by people whose full-time job is not a file-sharing app, and Rust has a mature implementation in rustls. Confidentiality is needed before the pairing code is used, and it must not depend on anything Lanweave-specific. Pairing then confirms which connection this is; it does not need to invent encryption.

Identity is the interesting question, because two devices that have never met have no certificates to verify against each other. Lanweave's answer has three parts:

The responder generates a fresh self-signed P-256 certificate and key for every connection (via rcgen). Nothing is reused, so there is no long-lived local key to steal and nothing to pin.
The initiator's verifier is deliberately narrow. A trust-chain check would fail — the certificate is self-signed — and a server-name check would be meaningless, since the name is not an identity. The verifier relaxes only those two checks. It still requires a single well-formed X.509 end-entity certificate (no intermediates) and still verifies the TLS 1.3 CertificateVerify signature with a fixed ECDSA P-256 / SHA-256 scheme, proving the responder holds the certificate's private key.
The certificate is never treated as an identity. It is a per-connection encryption key; user-visible identity comes from pairing.

// The provisional initiator verifier: chain and server-name checks are
// relaxed, every other check is kept.
fn verify_server_cert(
    &self,
    end_entity: &CertificateDer<'_>,
    intermediates: &[CertificateDer<'_>],
    _server_name: &ServerName<'_>,
    _ocsp_response: &[u8],
    _now: UnixTime,
) -> Result<ServerCertVerified, TlsError> {
    // The profile expects exactly one fresh end-entity certificate: a peer
    // that sends intermediates presents an unexpected chain shape.
    if !intermediates.is_empty() {
        return Err(TlsError::InvalidCertificate(CertificateError::UnknownIssuer));
    }
    // Required shape: a parseable X.509 end-entity certificate.
    EndEntityCert::try_from(end_entity)
        .map_err(|_| TlsError::InvalidCertificate(CertificateError::BadEncoding))?;
    Ok(ServerCertVerified::assertion())
}

// The handshake signature must use the fixed P-256 scheme, and the signature
// must verify: proof of private-key possession.
fn verify_tls13_signature(
    &self,
    message: &[u8],
    cert: &CertificateDer<'_>,
    dss: &DigitallySignedStruct,
) -> Result<HandshakeSignatureValid, TlsError> {
    if dss.scheme != SignatureScheme::ECDSA_NISTP256_SHA256 {
        return Err(TlsError::PeerMisbehaved(
            PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme,
        ));
    }
    let cert = EndEntityCert::try_from(cert)
        .map_err(|_| TlsError::InvalidCertificate(CertificateError::BadEncoding))?;
    cert.verify_signature(webpki::ring::ECDSA_P256_SHA256, message, dss.signature())
        .map_err(|_| TlsError::InvalidCertificate(CertificateError::BadSignature))?;
    Ok(HandshakeSignatureValid::assertion())
}

Two further details matter. First, resumption, session tickets, pre-shared keys, 0-RTT and early application data are all disabled, on both sides. Every connection gets fresh TLS state and a fresh key schedule, so no abbreviated handshake can bypass a future user decision. The server stores no sessions and sends no tickets; the client disables resumption.

Second, ALPN is enforced explicitly after the handshake. rustls alone does not fail when the peer sends no ALPN, so the code checks the negotiated protocol and rejects anything but exactly lanweave/1. Tests cover mismatched and absent ALPN on both sides.

After the handshake, each side derives a fresh 32-byte TLS exporter using export_keying_material with the lanweave/v1 label (RFC 8446 §7.5). The exporter is not a file key; it is one input to the pairing confirmation below, which binds the act of pairing to this TLS connection and no other.

Honesty note: the custom verifier and the TLS/pairing composition are flagged for specialist review. A verifier that relaxes chain checks is a sharp tool; the narrowness of the remaining checks is what makes it reviewable at all — but no review has happened yet.

Pairing: turning a connection into the intended connection

Lanweave separates three decisions that must never imply one another:

Decision	Who makes it	What it grants
Pairing decision	The responder's user accepts or rejects the request	Nothing by itself
Code authorization	The responder's user shares a one-time code; the initiator enters it	An authorized session on this connection
Transfer decision	The recipient's user reviews the manifest	Permission to send exactly that file list

Accepting a pairing request does not authorize the session; the code does. An authorized session does not approve any files; the recipient does that separately for every transfer.

The one-time code

The pairing code is generated only after the responder's user accepts a live request. It is eight decimal digits, kept in memory, valid for 120 seconds, usable for exactly one cryptographic pairing attempt, and never sent as a protocol field. One screen displays it, the other types it, and the humans move it through some private channel. The specification forbids it in discovery, logs, or any normal wire message.

Generation uses the operating system's cryptographically secure generator with rejection sampling, so every value in 00000000..=99999999 is equally likely and leading zeroes stay significant. A PairingCode zeroizes its digits on drop, has no Display implementation, and prints as PairingCode([REDACTED]) in Debug output. A failed pairing does not reveal whether the code was wrong, expired, already used, or bound to a different connection.

// Uniform sampling over the ten-million-value code space.
const LIMIT: u64 = (1u64 << 32) - (1u64 << 32) % CODE_RANGE as u64;
let value = loop {
    let sample = u64::from(rng.next_u32());
    if sample < LIMIT {
        break (sample % u64::from(CODE_RANGE)) as u32;
    }
};

An eight-digit code is about 26.6 bits of entropy. That is small, and the design does not pretend otherwise: the defence is not that the code resists offline guessing, but that there is one online attempt per accepted request, a wrong guess destroys the code and closes the connection, and the lifetime is short. The human ceremony — the responder's user must accept before a code even exists — is what keeps an attacker from grinding guesses.

Mutual confirmation with SPAKE2

The cryptographic step is an RFC 9382 SPAKE2 exchange using the P-256 / SHA-256 / HKDF / HMAC ciphersuite (RFC 9382). The pairing initiator is Party A, the responder is Party B, and the identity strings (lanweave-v1-initiator, lanweave-v1-responder) are fixed, not negotiated.

Why a PAKE? Sending the code (or its hash) over the connection would turn it into a bearer token: anyone who learns it — including an intermediary relaying the connection — could complete the exchange, and anyone who observes or relays the transcript could verify guesses offline. A PAKE prevents both: an observer or an attacker without the code cannot verify a guess, and a wrong guess yields confirmation failure rather than a reusable signal. Lanweave does not implement the group arithmetic; the adapter wraps an existing crate, and the project forbids implementing elliptic-curve arithmetic itself.

The code is mapped to the SPAKE2 password scalar as w = OS2IP(digits) mod n. Because the code space is small and the group order is large, this mapping is injective over all ten million codes. The mapping is small, reviewable, and flagged for specialist review.

Binding pairing to the connection

A confirmation that only proves "both sides know a code" would be vulnerable to a split-connection relay: an intermediary that sits between the two peers and pairs separately with each side. Lanweave binds the confirmation to the live connection by constructing additional authenticated data from four length-prefixed fields:

u32 length + "lanweave-v1-pairing"
u32 length + 32-byte TLS exporter
u32 length + exact initiator hello body
u32 length + exact responder hello body

pub(crate) fn binding(exporter: &[u8], initiator_hello: &[u8], responder_hello: &[u8]) -> Result<Zeroizing<Vec<u8>>, PairingError> {
    if exporter.len() != EXPORTER_LEN
        || initiator_hello.len() > MAX_HELLO_BODY_BYTES
        || responder_hello.len() > MAX_HELLO_BODY_BYTES
    {
        return Err(PairingError::InvalidInput);
    }
    let mut binding = Zeroizing::new(Vec::new());
    push_field(&mut binding, BINDING_LABEL);        // b"lanweave-v1-pairing"
    push_field(&mut binding, exporter);
    push_field(&mut binding, initiator_hello);
    push_field(&mut binding, responder_hello);
    Ok(binding)
}

The length prefixes mean no combination of fields can collide with another. The hello bodies are used exactly as encoded on the wire — the received bytes for the peer's message, the same deterministic encoding for the local one — and are bounded to 4,000 bytes. The SPAKE2 adapter passes this value as associated data, which RFC 9382 mixes into the confirmation key derivation, so a pairing completed across two different TLS connections cannot produce matching confirmations. That composition is flagged for adversarial testing.

The exchange itself is four records: initiator share, responder share, initiator confirmation, responder confirmation. The ordering rules ensure that no side considers the session authorized until it has verified the peer and is sure its own final confirmation is on the wire:

The responder consumes the code only after the initiator's confirmation verifies.
The initiator treats the session as authorized only after the responder's confirmation verifies.
The responder writes and flushes its confirmation before reporting the session authorized, using a transport barrier that resolves only when the frame has actually been written and flushed. If the final confirmation is lost, pairing fails safely and the code is not reusable.

sequenceDiagram
    actor U1 as User A
    participant I as Initiator app
    participant R as Responder app
    actor U2 as User B
    U1->>I: select a discovered device
    I->>R: TLS 1.3 (ALPN lanweave/1), hello
    R-->>I: hello
    I->>R: pair_request
    R->>U2: show pairing request
    U2-->>R: accept
    R->>R: generate one-time code
    R-->>I: pair_response(accepted)
    R->>U2: display code locally
    U2->>U1: share code through a private channel
    U1->>I: enter code
    I->>R: pairing share (Party A)
    R-->>I: pairing share (Party B)
    I->>R: pairing confirmation (must flush)
    R-->>I: pairing confirmation (must flush)
    Note over I,R: session authorized<br/>code consumed, never sent

Prototype status. The SPAKE2 adapter wraps pakery-spake2 and pakery-crypto, newer and unaudited crates selected for the fixed ciphersuite and its point validation. The release gate stays open until independent review accepts the dependency, the password mapping, and the exporter/hello binding. Until then, this is a plausible cryptographic story, not an established one.

Transfer authorization: consent per payload

An authorized session is not a file permit. After pairing, the session is idle, and either participant may propose one transfer at a time. Pairing roles — initiator and responder — stay fixed, but transfer roles change per request: whoever proposes is the requester, and whoever reviews is the recipient. Lanweave avoids "sender" and "receiver" as session-wide identities, because those names quietly assume a direction that does not exist.

A transfer request carries the complete ordered manifest: one to 1,024 entries, each a filename component and an exact byte size, plus optional folder metadata. It carries no local paths, timestamps, permissions, media types, file IDs, or pre-transfer hashes. The recipient sees the whole list — names, sizes, count, checked total, and the requester's untrusted display name — and accepts or rejects it as a unit. There is no partial approval, no remote rename, no overwrite, and the destination directory is chosen locally and never communicated to the peer.

Two details keep the manifest honest. The requester re-checks every source before sending it: if a file no longer matches the approved name, type, or size, it sends transfer_cancel rather than silently changing the manifest, which is immutable once sent. And a request that cannot be stored is rejected before any bytes move: the recipient validates every name, checks for conflicts and existing destinations, and prepares the first temporary file before accepting. If preparation fails, the rejection carries a specific reason (invalid_filename, name_conflict, destination_exists, unavailable, …) and no data is sent.

Because both peers can propose while idle, the protocol needs a rule for simultaneous requests. Version 1 has no request IDs, so the pairing initiator's proposal wins. If the responder has a proposal pending when the initiator's request arrives, it withdraws and re-queues its own proposal, records that exactly one stale busy response is owed, and reviews the initiator's request. It consumes that stale response in whatever phase the winning transfer is in, then may send its queued proposal once the session returns to idle. The rule applies only to simultaneous proposals, not as permanent initiator priority.

The cost is real: request IDs and a transaction layer would keep both proposals in flight and generalize failure handling. But "one active proposal, fixed priority, one tracked stale response" is a smaller state space — and the price is that the responder may have to wait and retry.

Session lifecycle and failure scopes

The session state machine is where the security properties become operational. Its rules fit in a short list:

Pairing must finish before the session becomes active.
Only one transfer request or transfer is active at a time.
Either participant can become the requester for the next transfer.
Transfer completion or rejection returns to session idle.
Protocol, authentication, and transport failures close the session.
Closing drops all temporary authorization and requires fresh pairing.

Failures are scoped in three different ways:

Outcome	Scope
Pairing rejection, failure, expiry, or cancellation	Close the connection
Malformed framing, unsafe input, wrong-state controls	Close the connection
Transfer rejection (including `busy`)	End the proposal; session stays idle
`transfer_cancel` before `ready`	End the proposal; session stays idle
`transfer_cancel` after `ready`	Clean the partial file; close the session
Failed `file_result`	Clean the partial file; close the session
`session_close`, idle expiry, transport loss	Close the session

stateDiagram-v2
    [*] --> session_idle
    session_idle --> awaiting_transfer_response: local transfer_request
    session_idle --> reviewing_transfer: peer transfer_request
    awaiting_transfer_response --> session_idle: rejected / cancelled before ready
    awaiting_transfer_response --> awaiting_ready: accepted
    reviewing_transfer --> session_idle: rejected
    reviewing_transfer --> receiving_file: accepted and ready
    awaiting_ready --> sending_file: ready
    sending_file --> session_idle: all files verified
    receiving_file --> session_idle: all files verified
    sending_file --> closed: failure or cancel after ready
    receiving_file --> closed: failure or cancel after ready
    session_idle --> closed: session_close / 600 s idle / transport loss
    closed --> [*]
    note right of closed
        Authorization is destroyed; the next
        connection repeats the full pairing flow.
    end note

The post-ready rule deserves its explanation, because "close the session on one failed file" looks harsh. Once the recipient has sent ready, the requester starts writing DATA frames, and a later failure or cancellation may leave bytes in flight or in the sender's queues.

Version 1 puts no transfer or file identifiers on DATA, because the connection state already supplies that context. That keeps frames small and parsers simple — and it is also why in-flight data cannot be safely attributed once its transfer has ended. Closing the session prevents a later transfer from misinterpreting stale bytes. Rejection before ready has no such problem: no file data exists yet.

Time bounds are part of the lifecycle:

Session idle: 600 seconds, starting when pairing completes and restarting when a transfer finishes or a proposal is rejected or cancelled before ready. An active transfer is not idle, but it has its own limits.
Prompt and code lifetime: 120 seconds. Pairing requests, the code, and transfer approval prompts all expire, so an unattended prompt cannot hold resources forever.
Progress deadline: 60 seconds without progress during an active transfer. This is local policy, not a wire constant; a stalled sender or silent recipient closes the session after cleanup instead of hanging.
Handshake and control deadlines bound TCP/TLS setup and the initial message exchange.

Every deadline runs against a monotonic clock, so wall-clock changes cannot extend an authorization window.

Closing is explicit when the connection allows it: session_close carries one of three reasons (user_closed, idle_timeout, shutdown), is valid in any authorized state, and is not acknowledged. EOF and transport loss also end the session, but they never prove an active file succeeded. That asymmetry is intentional: absence of an error is not success.

Filesystem safety: received data is hostile input

The recipient's storage layer is where an adversarial manifest would do damage, so it is strict about names before anything is written:

A name must be a single non-empty filename component of at most 255 UTF-8 bytes. Empty names, ., .., absolute or path-like names, embedded separators (/, \), NUL, and control characters are rejected.
Platform rules apply on top. On Windows, reserved device names (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9), trailing dots or spaces, and forbidden characters (< > : " | ? *) are rejected, and equivalence compares case-insensitively without trailing dots or spaces.
Duplicate or equivalent names within one manifest, and names that already exist in the destination, reject the whole request. Existence is checked with symlink_metadata, which does not follow links.

Data is written only to a temporary file: tempfile creates an unpredictable .lanweave-*.part name in the destination directory, without following links, and with mode 0600 on Unix. Nothing appears under the final name until the exact declared byte count and the SHA-256 digest both match.

// Flush, sync, then publish without replacing anything.
file.flush().await?;
file.sync_all().await?;
drop(file);

match temp.persist_noclobber(&final_path) {
    Ok(_) => Ok(()),
    Err(error) if error.error.kind() == std::io::ErrorKind::AlreadyExists => {
        Err(StorageError::DestinationExists)
    }
    Err(_) if std::fs::symlink_metadata(&final_path).is_ok() => {
        Err(StorageError::DestinationExists)
    }
    Err(_) => Err(StorageError::Io),
}

persist_noclobber makes the final step a no-replace operation: if a destination appears after the manifest check, finalization fails instead of overwriting it. Lanweave never overwrites and never silently renames, and files are written one at a time in manifest order — the sender waits for each file's verified result before starting the next.

Failure cleanup is defined by what the user keeps:

The current partial file is deleted.
Files already verified in this transfer remain.
Later manifest entries are not attempted.
The sender is told the failure while the connection is still safe.

Received files are never automatically opened, previewed, or executed. The application's job ends at "verified bytes under a safe name".

Threat model: what this protects against, and what it does not

The project's threat model assumes uncompromised endpoints, a working OS random generator, a correct TLS implementation, and users who share the code privately. Within those assumptions, a condensed excerpt:

Threat	Control	Remaining risk
Spoofed visible device	Discovery is untrusted; pairing confirmation is required	Attackers can create noise or denial of service
Misleading display name	Escaped, labelled untrusted, never treated as identity	Similar names may still confuse users
Pairing-request spam	Bounded requests and prompts, with deadlines	Attackers can consume bounded attention and resources
Pairing code disclosure	Generated after acceptance, displayed locally, never sent, 120 s lifetime	Anyone who sees the live code may pair
Online code guessing	One cryptographic attempt per accepted request, prompt limits, short expiry	Attackers can cause prompts or denial of service
Split-connection intermediary	Pairing confirmation bound to the TLS exporter and exact hello bodies	The property is intended, not verified
Replay	Fresh TLS and pairing state, strict state, no resumption	Replays still consume bounded parsing work
Malformed frames or JSON	Bounded lengths and strict schemas before allocation	Parser defects may remain
Terminal escape injection	Control and bidi characters escaped for display	Unicode look-alikes can still confuse users
Path traversal and overwrite	Single safe names, platform checks, no-follow temp files, no-replace finalization	Filesystem edge cases need platform tests
Corrupt transfer	TLS integrity plus exact size and SHA-256 before finalization	A paired peer can intentionally choose harmful content
Authorization reuse	No trust database, resumption, reusable code, or reconnect token	Users must repeat pairing after every disconnect

The out-of-scope list matters just as much. Lanweave cannot:

protect a compromised computer;
prove a person's real-world identity;
make a received file safe to open;
hide all traffic metadata — a passive LAN observer can still see that Lanweave is running and observe connection timing and volume, even though file contents are encrypted;
protect a code that has been disclosed;
guarantee network availability, or fully prevent denial of service.

The cryptographic implementation is also unaudited, which makes the entire "confidentiality and authentication" column a design intention rather than a verified property.

Testing as evidence of correctness — not of security

The project tests what is testable and is careful not to over-interpret the result. At the time of writing, cargo test --all --locked reports 229 passing tests across 32 test modules. The parts most relevant here:

End-to-end session tests over real connections. Two session services complete a real TLS 1.3 handshake, SPAKE2 exchange, and one-time code, then run transfers in both directions over loopback — folder preparation, cancellation, timeouts, manual close — with no mocked transport or pairing adapter.
Wrong-code and expiry tests. A wrong code never authorizes either peer; an expired code closes pairing without authorization; a timed-out prompt rejects without ever creating a code.
Failure-scope tests. Rejection before ready keeps the session usable; a cancel after ready cleans the partial file and closes both peers; a stalled or silent peer closes at the progress deadline.
Filesystem tests. Unsafe, duplicate, equivalent, existing, and path-like names are rejected; symlink and destination races fail safely; partial files are removed on drop; no-replace finalization is asserted against a raced destination.
Frame and parser tests. Every split point of a wire image decodes identically, byte-by-byte feeding reassembles frames, malformed headers fail before allocation, and oversized lengths are rejected regardless of how many bytes arrived. A separate fuzz target exercises the decoder with arbitrary bytes, but it is not yet in CI, and broader protocol fuzzing is planned work.

None of this proves the cryptography is right. As the project's testing document puts it, tests show that the implementation follows the draft; they do not prove that unaudited cryptography is secure. Several gates remain open: dependency review of the PAKE crate, deterministic positive and negative test vectors, certificate-verifier review, and review of the pairing/TLS composition.

Limitations and future work

Labelled as limitations, because they are:

No audit, prototype PAKE. The pairing dependency, password mapping, binding composition, and custom certificate verifier all need specialist review, and the app must not be described as secure or production-ready. pakery-spake2/pakery-crypto were chosen for ciphersuite fit and point validation, not for an audit history.
IPv4 only for now. Discovery disables IPv6 interfaces and the listener binds an IPv4 wildcard socket. IPv6 policy is future work.
Small code space. Eight digits is ~26.6 bits; the model relies on one attempt per accepted request and a short lifetime, not offline resistance.
No resume, no parallel transfers, no trusted devices. Deliberate v1 exclusions; each would need a new threat review.
Update channel. The self-updater trusts GitHub Releases and checksums, and Windows builds are not code-signed yet. That is a separate trust decision, documented as such.

Lessons learned

Write the trust boundary before the code. The most valuable early artifact was the sentence "discovery answers where, not who." It settled dozens of decisions — what the device list may claim, what the certificate may mean, what pairing must bind to — before any of them were code.

Separate decisions are stronger than one big gate. Pairing, code authorization, and transfer approval are three questions; folding them into one "trusted peer" state would have been simpler to build and worse to reason about, because a mistake in one would silently grant the others.

Failure scope is a design decision. Deciding explicitly that post-ready failures close the session — and writing down why — was more valuable than defensive coding. Vague failure behavior is where protocols accumulate ambiguity.

Bound everything, and test at the layer where the risk is. Per-kind frame limits, bounded queues, parsing before allocation, monotonic deadlines: each is small; together they define what a hostile peer can make the process do. The session tests use real TLS, real files, and real races; the frame tests cover every split point; the state machine is pure.

State what the system does not do. The limitations section is the part of the design most likely to be right. A tool that explains its own threat model is more trustworthy than one that asserts good intentions.

Conclusion

The design has one organising idea: never let one layer's output be mistaken for another layer's decision. Discovery produces candidates; TLS produces a confidential channel; the code produces a confirmed live connection; the recipient produces consent; the state machine produces bounded lifetimes; storage produces a verified file. Each step can fail without silently granting the next. Lanweave is unfinished and unaudited — the pairing prototype and the custom certificate verifier are where that matters most — but the architecture makes the remaining work identifiable instead of hidden.

Source and further reading

The implementation, protocol specification, threat model, and testing strategy are in the repository: github.com/etim66/lanweave. The protocol is documented in docs/PROTOCOL.md, the security boundary in docs/SECURITY.md, the adversary analysis in docs/THREAT_MODEL.md, and the open review gates in docs/CRYPTOGRAPHY.md.

Written by the developer of Lanweave. I build this in the open and document its design decisions so they can be reviewed, challenged, and improved; bug reports and design criticism — especially a broken security or state rule with a reproducible example — are the most useful feedback.

References

RFC 6762 — Multicast DNS: https://www.rfc-editor.org/rfc/rfc6762
RFC 6763 — DNS-Based Service Discovery: https://www.rfc-editor.org/rfc/rfc6763
RFC 8446 — The Transport Layer Security (TLS) Protocol Version 1.3 (keying material exporters, §7.5): https://www.rfc-editor.org/rfc/rfc8446
RFC 9382 — SPAKE2, a PAKE: https://www.rfc-editor.org/rfc/rfc9382
rustls documentation: https://docs.rs/rustls
rustls::ConnectionCommon::export_keying_material: https://docs.rs/rustls/latest/rustls/struct.ConnectionCommon.html#method.export_keying_material
tempfile::NamedTempFile::persist_noclobber: https://docs.rs/tempfile/latest/tempfile/struct.NamedTempFile.html#method.persist_noclobber
Rust standard library, std::fs::symlink_metadata: https://doc.rust-lang.org/std/fs/fn.symlink_metadata.html

TCP Is a Byte Stream: Designing a Framed Application Protocol in Rust with Tokio

UNYIME ETIM — Sat, 03 Oct 2026 09:45:52 +0000

A companion article, Discovery Is Not Authentication, covers how Lanweave establishes an authorized session between two devices on a local network: mDNS discovery, a one-time pairing code, TLS 1.3, and separate approval for every transfer. This article starts where that trust boundary ends: once two peers have an authenticated, encrypted connection, what actually travels over it, and why is it built this way?

Lanweave is a Rust terminal application for sending files and folders between devices on the same LAN (github.com/etim66/lanweave). It is a work in progress and has not been audited; nothing here is a security claim. The focus is protocol engineering: framing, strict parsing, connection state, backpressure, and streaming — the part of the system that must stay correct when the peer is hostile and the file is larger than memory.

Reliability is not message orientation

TCP guarantees that bytes arrive in order, without duplication, and without loss, or the connection fails (RFC 9293). It does not guarantee that a read corresponds to a write, or that a message arrives whole. A single read may return:

one byte of a header,
a complete 12-byte header and half of its body,
exactly one message,
five messages concatenated,
or any other split the kernel, network, and retransmission timing happen to produce.

This is not a bug to be fixed; it is the interface. TCP is a byte stream. TLS does not change that at the application layer: the record layer has its own framing, but an application read returns decrypted stream bytes, and no API promises that a record boundary lines up with a read or write. Any protocol whose messages are larger than one byte needs its own boundaries and validation.

The failure mode is familiar: code that works on loopback with small messages, then corrupts data on a real network where a 4,000-byte write is split across several reads. The fix is not a bigger read buffer; it is an incremental parser that treats the socket as an arbitrary byte source and the protocol as a state machine over it.

Lanweave's frame codec is that parser. The design rule: validate everything before allocating, and handle partial and coalesced reads identically to perfectly sized ones. A unit test takes a wire image of several frames and decodes it with the input split at every byte position; all splits must produce the same frame sequence.

flowchart TB
    A[TcpStream<br/>ordered bytes, no messages] --> B[TLS 1.3<br/>confidentiality + integrity]
    B --> C[Frame codec<br/>boundaries, lengths, kinds]
    C --> D[Strict JSON controls<br/>or raw DATA bytes]
    D --> E[Protocol state machine<br/>direction, order, phase]
    E --> F[Transfer engine<br/>stream, hash, verify, publish]

Each layer has one job. The frame codec knows nothing about messages, the message parser nothing about sockets, the state machine nothing about files. That separation makes each layer independently testable — and lets the frame codec be fuzzed without a network.

What goes on the wire

One TCP connection carries one authorized session, and that session can carry several sequential transfers in either direction. Control traffic is strict JSON; file bytes are raw binary frames. The distinction is deliberate:

JSON for control because the messages are small, inspectable field names help debugging, and a strict schema is easy to test exhaustively. A transfer_request is a list of names and sizes.
Binary for file data because base64 or numeric arrays would add CPU and memory overhead for no benefit. File bytes never pass through the JSON parser — the frame layer routes them to the transfer sink.

Newline-delimited JSON is a third possibility. It suits control-only protocols, but not binary file data: file bytes can contain newlines, so the data would still need an escaping layer. Length-prefixing applies one rule to both control and data.

The frame format

Every control message and every binary chunk travels in one frame with a fixed 12-byte header:

Offset	Size	Field	Value
0	4	magic	ASCII `LNWV`
4	1	frame version	`1`
5	1	kind	`0` = JSON control, `1` = DATA
6	2	header length	unsigned big-endian `12`
8	4	body length	unsigned big-endian
12	N	body	JSON object or raw file bytes

The header is fixed-size and fully specified, so a parser can reject a malformed frame after 12 bytes. The body length is a 32-bit unsigned integer, but the codec never trusts it: each frame kind has a maximum, checked before any body allocation.

Item	Limit
Generic JSON control body	1 MiB
`DATA` body	1 MiB (minimum 1 byte)
`hello` body	4,000 bytes
`pairing` body	4,096 bytes
`transfer_request` body	256 KiB
Files per manifest	1 to 1,024
Integer and checked total	2^53 − 1

One design detail is easy to miss: a DATA frame carries no file index and no offset. The connection state already knows which file is in flight and how many bytes have been accepted, so repeating that would create two sources of truth that a malicious peer could make disagree. DATA validity is instead a property of the protocol phase: data is acceptable only while receiving, and only after ready. A zero-byte file sends no DATA frame at all; it goes straight to file_end.

Note the difference between the maximum frame size (1 MiB, enforced on untrusted input) and the streaming chunk size (64 KiB, the sender's policy). The maximum bounds what an attacker can make the process allocate; the chunk size controls how often the sender checks channels, deadlines, and cancellation.

Incremental decoding without unbounded allocation

The decoder works over a growing BytesMut buffer. It returns Ok(None) when more bytes are needed, Ok(Some(frame)) for a complete frame, and an error that closes the connection for anything malformed:

pub fn decode(src: &mut BytesMut) -> Result<Option<Frame>, FrameError> {
    if src.len() < HEADER_LEN {
        return Ok(None);                          // wait for more bytes
    }
    if src[..4] != MAGIC {
        return Err(FrameError::BadMagic);
    }
    if src[4] != FRAME_VERSION {
        return Err(FrameError::BadVersion);
    }
    let kind = match src[5] {
        KIND_CONTROL => FrameKind::Control,
        KIND_DATA => FrameKind::Data,
        _ => return Err(FrameError::BadKind),
    };
    let header_len = u16::from_be_bytes([src[6], src[7]]);
    if usize::from(header_len) != HEADER_LEN {
        return Err(FrameError::BadHeaderLength);
    }
    let body_len = u32::from_be_bytes([src[8], src[9], src[10], src[11]]) as usize;
    if body_len > kind.max_body() {
        return Err(FrameError::BodyTooLarge);     // validated before allocation
    }
    if kind == FrameKind::Data && body_len == 0 {
        return Err(FrameError::EmptyData);
    }

    let needed = HEADER_LEN + body_len;
    if src.len() < needed {
        // Bounded by the just-validated body limit.
        src.reserve(needed - src.len());
        return Ok(None);
    }
    let mut frame = src.split_to(needed);
    frame.advance(HEADER_LEN);
    let body = frame.freeze();
    Ok(Some(match kind {
        FrameKind::Control => Frame::Control(body),
        FrameKind::Data => Frame::Data(body),
    }))
}

Four properties carry most of the weight:

Validate before allocate. Magic, version, kind, header length, and body length are checked from the first 12 bytes. A claimed 4 GiB body gets BodyTooLarge after 12 bytes, not a 4 GiB allocation; reserve only runs for a length that already passed a per-kind limit.
The buffer is bounded by construction. It accumulates at most one maximum-size frame plus whatever arrived after it. split_to removes the consumed prefix, so memory does not grow with frame count.
The body is handed off, not copied. split_to gives the frame its own slice of the buffer; advance skips the header; freeze yields an immutable Bytes the next layer can forward without copying the payload. For DATA, that Bytes reaches the file writer essentially unchanged.
Malformed framing is terminal. There is no "skip and continue" path: a bad magic, unknown kind, or impossible header length means a bug or hostile intent, and the connection closes. Recovery would mean trusting more of the stream that just proved untrustworthy.

Reading frames from a socket

FramedConnection::read_frame combines the decoder with an async read loop (read_buf):

pub(crate) async fn read_frame(&mut self) -> Result<Option<Frame>, ReadError> {
    loop {
        if let Some(frame) = decode(&mut self.buffer).map_err(ReadError::Frame)? {
            return Ok(Some(frame));
        }
        let read = self
            .reader
            .read_buf(&mut self.buffer)
            .await
            .map_err(ReadError::Io)?;
        if read == 0 {
            return if self.buffer.is_empty() {
                Ok(None)          // clean close after complete frames
            } else {
                Err(ReadError::Truncated)   // close in the middle of a frame
            };
        }
    }
}

The difference between Ok(None) and Err(Truncated) is protocol honesty in miniature. A close after complete frames is a normal end of stream, and every frame that arrived has been delivered. A close mid-frame means the stream was cut short — possibly a crash, possibly an attack — and the partial data cannot be interpreted. The transport refuses to pretend those cases are the same; a unit test writes a frame minus its last three bytes and asserts truncation rather than a clean close.

ReadError keeps the taxonomy narrow: I/O failure, malformed frame, or truncation. Message-level problems belong to the parser that receives the body.

Strict JSON, because ambiguity is a vulnerability

The control layer decodes a Bytes body into a typed Control enum. The rules are intentionally unforgiving:

The body must be exactly one UTF-8 JSON object with no trailing value (RFC 8259).
Duplicate fields are rejected.
Unknown fields are rejected once a schema has consumed its fields.
Numbers are integers from 0 through 2^53 − 1. Floats, exponent notation, and negatives are rejected; the protocol does not use null.
String values come from closed sets (accepted, verified, user_rejected, and so on); anything else is invalid.
Field names, strings, arrays, nesting, and total body size have fixed bounds.
Binary values use canonical unpadded base64url with an exact decoded length (RFC 4648 §5); digests are exactly 64 lowercase hexadecimal characters.

Two of these choices look like pedantry until they prevent a class of bug.

Duplicate and unknown fields create parser disagreement: two implementations that both "accept" {"accepted": false, "accepted": true} or {"type": "ready", "files": [...]} may disagree about what the message means. Rejecting removes the disagreement, and it stops a future protocol version from smuggling fields past an old implementation.

Errors never carry peer-controlled text. The parser's error type holds only &'static str schema names, never the peer's bytes. Error messages are the classic place untrusted input gets logged or reflected, and a detailed parse error can become an oracle for probing the parser. The wire error codes are coarse (invalid_message, authentication_failed, and so on); the exact reason stays local.

The parser's shape is deliberate. A JSON visitor collects entries as borrowed key/value pairs, each value an unparsed RawValue slice of the original body. Schemas ask for fields by name, and duplicate detection happens at access time:

/// Returns the single value of `field`, rejecting repeats.
fn one(&self, field: &'static str) -> Result<Option<&'a RawValue>, MessageError> {
    let mut values = self.values(field).into_iter();
    match values.next() {
        None => Ok(None),
        Some(value) => {
            if values.next().is_some() {
                Err(MessageError::DuplicateField(field))
            } else {
                Ok(Some(value))
            }
        }
    }
}

Because entries are borrowed slices of the body — already capped at 1 MiB by the frame layer — parser memory is bounded by the body itself, with no intermediate tree of owned strings.

On the encoding side, messages serialize with a documented field order and canonical encodings so golden fixtures are byte-stable. That reproducibility lets tests assert exact wire bytes, not just round-trips.

A protocol state machine, not just a parser

Parsing tells you a message is well-formed. It cannot tell you that a message is allowed right now. Lanweave answers the second question in a separate, pure module: protocol::state.

A connection end has a Role (pairing initiator or responder) and a Phase tracking the exchange in progress: hello handshake, pairing request and response, pairing record count, authorized-idle, pending outbound proposal, inbound review, sending or receiving a file, terminal closing. The session owner feeds decoded messages into three functions:

send(state, &control) — validates a locally generated control against the phase and returns the implied actions.
accept(state, inbound) — validates an inbound control or DATA frame and returns actions such as "deliver these bytes", "proposal ended", "transfer finished", or "session closed".
send_data(state) — answers a narrower question: may this side put file bytes on the wire right now?

The state layer has no sockets, no files, no TLS, no UI. Its tests can therefore walk an initiator and a responder through an entire session — two plain state values, no network — and assert every transition.

The rules are the specification in executable form: the initiator sends the first hello; pairing records alternate and only the correct party may send each one; DATA is valid only while receiving inside an un-ended file; file_end and file_result indices must match the tracked file; any transition not explicitly allowed is a terminal WrongState error. Wrong state is not recoverable: a peer that violates the sequence has made the rest of the stream unreliable.

The state machine also encodes the version 1 simultaneous-proposal rule. Two peers can both propose while idle, and there is no request ID, so the pairing initiator's request wins. A responder with a pending proposal withdraws and re-queues it and sets one collision_pending marker. The protocol layer then consumes exactly one stale transfer_response(busy) for that withdrawn proposal — in any phase of the winning transfer — and clears the marker:

// The responder consumes exactly one stale busy response for its
// withdrawn proposal, in any phase of the winning transfer.
if state.collision_pending
    && let Inbound::Control(Control::TransferResponse(response)) = &inbound
    && matches!(response.reason, Some(TransferRejection::Busy))
{
    state.collision_pending = false;
    return Ok(Vec::new());
}

That rule is a direct consequence of the "no request IDs" decision. Request IDs and a transaction layer would handle races more uniformly, but they would add state and failure modes. The chosen design keeps the state space small and pays with a slightly awkward collision rule the tests exercise explicitly.

One writer, two bounded queues

Reading is a loop. Writing is a task.

Concurrent writers could interleave their bytes and corrupt the stream, so there is exactly one writer task per connection, fed by two bounded queues:

flowchart LR
    S[session owner] -->|controls, capacity 64| CQ[control queue]
    S -->|DATA frames, capacity 8| DQ[DATA queue]
    CQ --> W[single writer task]
    DQ --> W
    W -->|write_all + flush per frame| TLS[TLS stream]
    B[barrier] -->|queued behind the frames it observes| CQ

The writer resolves frames in a select! loop with a biased branch order that checks DATA first:

loop {
    tokio::select! {
        biased;
        frame = data.recv() => {
            let Some(frame) = frame else { break };
            if write_frame(&mut writer, &frame).await.is_err() { break; }
        }
        item = controls.recv() => {
            match item {
                None => break,
                Some(WriterItem::Frame(frame)) => {
                    if write_frame(&mut writer, &frame).await.is_err() { break; }
                }
                Some(WriterItem::Barrier(acknowledge)) => {
                    let _ = acknowledge.send(());
                }
            }
        }
        stopped = stop.changed() => {
            if stopped.is_err() || *stop.borrow() { break; }
        }
    }
}

The ordering guarantee is precise, and the module documents both halves:

A control queued after a DATA frame cannot overtake it. That makes file_end safe: the session queues the trailing DATA chunks, then file_end, and the writer prefers DATA while any is queued, so file_end always follows the last chunk of its file.
A control queued before a DATA frame may still be overtaken, because the writer prefers DATA. Callers must not rely on cross-queue send order.

The second half is easy to get wrong by assuming one global FIFO across both queues. Naming the limitation and testing the first half was worth more than inventing an ordering guarantee the implementation does not need.

Two mechanisms make writing robust:

Flush per frame. Every frame is written with write_all, flushed (flush), and the whole write-plus-flush is wrapped in a 30-second deadline. A peer that stops reading applies backpressure; one that stops forever surfaces as a write deadline instead of a task that hangs until shutdown.
A flush barrier. send_control_flushed queues the frame and a barrier in the same control queue and returns only when the writer reaches the barrier — meaning every earlier frame has been written and flushed. This exists for one requirement: the pairing responder must not treat the session as authorized until its final confirmation is actually on the wire. It is the kind of ordering requirement that is invisible until it breaks a security property.

Shutdown has two flavors. Outbound::close signals the writer, waits for the task, lets queued frames finish, and shuts the write half down so the peer sees one clean EOF. Dropping the Outbound aborts the writer, which can truncate an in-flight frame — the peer sees Truncated instead. Both paths are tested: how a connection ends is part of the protocol.

Backpressure, end to end

Streaming to a peer whose network is slower than the disk is a classic way to turn a small program into a memory-hungry one: read fast, buffer without limit, watch RSS climb. Lanweave's answer: every handoff in the pipeline is a bounded channel, so a slow consumer blocks a fast producer instead of accumulating a queue.

Channel	Capacity	What it protects
App events	32	The event loop's inbox
App effects	16	Work dispatched to network services
Discovery events	32	mDNS updates into the app
Session commands	8	UI actions into the session owner
Accepted sockets	4	Listener to session owner (connection floods)
Per-connection commands	4	Local decisions into one connection task
Outbound control frames	64	Control traffic to the writer
Outbound DATA frames	8	File data to the writer (one frame ≤ 1 MiB)
File reader to sender	4	64 KiB chunks from disk to the session

The DATA queue matters most for memory: the writer path holds at most eight queued 1 MiB frames plus the one being written, the file-reader channel holds at most four 64 KiB chunks, and the reader owns one 64 KiB buffer. A 40 GB file does not produce a 40 GB buffer; it produces a steady state where the disk read task sleeps whenever the network cannot keep up. Backpressure is not a feature added later — it is what makes the memory bound true.

Streaming files without loading them

Both ends of a transfer run the same bounded pattern: read a chunk, hash it, hand it to the network; receive a chunk, write it to a temporary file, hash it.

On the sending side, the source is re-checked immediately before reading — a file that is no longer a regular file of the reviewed size is refused rather than streamed:

pub(crate) async fn send_file(
    path: &Path,
    size: u64,
    sink: &mpsc::Sender<Bytes>,
) -> Result<[u8; 32], SourceError> {
    let metadata = std::fs::symlink_metadata(path).map_err(|_| SourceError::Changed)?;
    if !metadata.file_type().is_file() || metadata.len() != size {
        return Err(SourceError::Changed);
    }

    let mut file = tokio::fs::File::open(path).await.map_err(|_| SourceError::Changed)?;
    let mut hasher = Sha256::new();
    let mut buffer = vec![0u8; CHUNK_SIZE]; // 65_536

    loop {
        let read = file.read(&mut buffer).await.map_err(|_| SourceError::Io)?;
        if read == 0 {
            break;
        }
        hasher.update(&buffer[..read]);
        sink.send(Bytes::copy_from_slice(&buffer[..read]))
            .await
            .map_err(|_| SourceError::Io)?;
    }

    Ok(hasher.finalize().into())
}

read_to_end would have been three lines. It would also make peak memory proportional to file size, contradicting the bounded-memory constraint. Streaming costs something real: an error can appear mid-file, after bytes have been sent. The protocol handles that by scoping failure to the current transfer and making the consequences explicit.

On the receiving side, each chunk is checked against the declared size before it is written, and the file is published only after the accumulated digest matches:

pub(crate) async fn write(&mut self, chunk: &[u8]) -> Result<(), FileFailure> {
    if self.written.saturating_add(chunk.len() as u64) > self.expected {
        return Err(FileFailure::SizeMismatch);   // excess data is rejected
    }
    self.temp.write_all(chunk).await.map_err(|_| FileFailure::WriteFailed)?;
    self.hasher.update(chunk);
    self.written += chunk.len() as u64;
    Ok(())
}

pub(crate) async fn finish(self, digest: [u8; 32]) -> Result<(), FileFailure> {
    if self.written != self.expected {
        return Err(FileFailure::SizeMismatch);   // short or long
    }
    let actual: [u8; 32] = self.hasher.finalize().into();
    if actual != digest {
        return Err(FileFailure::HashMismatch);
    }
    self.temp.finalize().await.map_err(|error| match error {
        StorageError::DestinationExists => FileFailure::DestinationExists,
        _ => FileFailure::WriteFailed,
    })
}

The receiver writes to a restrictive temporary file and never under the final name until verification succeeds; dropping the unfinished file removes the partial. Publication is a no-replace operation (persist_noclobber), so a file that appears after preflight is never overwritten. The sender waits for each file_result before starting the next file, so "verified" is always a peer's statement about a complete, published file, not a local hope based on a socket write.

sequenceDiagram
    participant R as File reader task
    participant S as Session owner
    participant W as Writer task
    participant P as Peer
    R->>S: 64 KiB chunk (bounded channel, capacity 4)
    S->>W: DATA frame (bounded queue, capacity 8)
    W->>P: write_all + flush per frame
    R-->>S: reader finished, returns SHA-256
    S->>W: file_end(index, sha256)
    W->>P: file_end
    P-->>S: file_result(verified)
    Note over S: only now does the next file start

Cancellation, timeouts, and cleanup

The send and receive loops are select! expressions over three events: an inbound read, a local UI command, and (on the sending side) the next chunk from the file reader. Cancellation is not a special path bolted on top; it is one of the arms the loop already waits on.

Cancellation semantics follow the protocol's failure scopes:

Before ready, nothing has been sent, so cancellation ends the proposal and the session stays authorized. The reviewed file list is kept locally so the user can try again.
After ready, file bytes may be in flight. The canceller sends transfer_cancel, the partial file is removed, and the session closes — in-flight DATA cannot be attributed to a later transfer without transfer IDs.
On a progress deadline, a stalled or silent peer is reported with a terminal error(timeout) when the connection is still writable, and the session closes after cleanup.

Receiver cleanup is tied to ownership, not a manual "run this on failure" step: the partial file is an object, and dropping it without finalizing removes the file. Cleanup therefore holds on every early return, not just the ones a developer remembered.

Testing the protocol

Protocol input is a byte string, which makes the set of interesting inputs more enumerable than in UI code. The test suite uses that:

Every split point. A wire image of several frames is decoded with the input divided at every byte position; all splits must produce the identical frame sequence, covering header splits, body splits, and coalesced frames in one sweep.
Byte-by-byte feeding. The same images are fed one byte at a time, catching parsers that only handle boundaries one level deep.
Golden vectors. Every control message has an exact expected JSON encoding, including canonical base64url pairing values and 64-character lowercase digests, so a specification and an implementation can be compared directly.
Malformed input. Bad magic, bad version, unknown kind, wrong header length, oversized body, and empty DATA form a table of expected errors, all asserted to fail before any body allocation.
Boundedness under pressure. A gated writer that never accepts bytes proves a full DATA queue blocks the sender instead of growing, and that the blocked send completes when the writer drains.
Real connections. The frame and protocol layers also run through actual TLS connections and an end-to-end loopback session: real handshake, real pairing, real files on disk, both directions.

One fuzz target complements the deterministic tests: frame_codec feeds arbitrary bytes to the decoder and requires that it never panics and never allocates for invalid or oversized headers. It is built with cargo fuzz (cargo-fuzz book), lives in a separate crate excluded from CI, and requires nightly Rust. Its whole body is small:

fuzz_target!(|data: &[u8]| {
    let mut buffer = bytes::BytesMut::from(data);
    while let Ok(Some(_frame)) = lanweave::fuzzing::decode(&mut buffer) {}
});

The library exposes the private codec to the fuzzer through a fuzz feature that compiles a re-export shim, so normal builds keep a private API. Fuzzing covers only the frame decoder; property tests for strict JSON, the state machine, pasted paths, and destination-name mapping are planned work.

Parsing untrusted bytes: the security implications

A protocol parser is attack surface. The most dangerous designs are generous: they accept what they do not understand, allocate from lengths before validating, keep owned copies of arbitrary size, and return errors that quote the input. Lanweave moves the other way at every point:

Validate before allocating, and bound the schema, not just the transport. The frame length is checked against a per-kind maximum using only the 12-byte header — a hostile 4 GiB claim costs 12 bytes to reject — and body limits are per message type, with arrays, strings, and integers capped at 2^53 − 1 so checked totals cannot exceed what the domain can represent.
Reject ambiguity. Duplicate fields, unknown fields, out-of-set string values, and impossible state transitions are errors, not warnings. An implementation that accepts more than the specification allows is an implementation whose behaviour is defined by accident.
Never reflect peer data. Parse errors contain only static schema names, wire errors use closed codes, and untrusted names are escaped before they reach a terminal. A malformed message is data to be judged, not text to be repeated.
Close on malformed framing. Once the frame layer has seen a violation, the rest of the stream is untrustworthy. There is no half-open recovery state, which removes a whole category of desynchronization bugs.

None of this is a proof of safety. Fuzzing shows the absence of crashes it happened to observe; tests show conformance to a draft; parser bugs can still exist in carefully read code. What the design provides is a small, explicit surface with limits stated in one document and enforced in one place.

Lessons learned

Boundaries are the protocol's first job. The frame header, per-kind limits, and the Ok(None)-means-incomplete contract make everything above them possible. Deciding what a DATA frame does not know — no file index, no offset — pushed the streaming questions to the front, and the answer (the connection state knows) simplified both layers.

Keep the pure layers pure. The state machine has no I/O, the parser no sockets, the frame codec no message knowledge. Each is cheap to test exhaustively, and when something breaks, "which layer is wrong" is usually obvious.

Say exactly what the writer guarantees. Single-writer serialization is easy; cross-queue ordering is subtle. Documenting that file_end cannot overtake its DATA but that a control queued before DATA may be overtaken beats a vague "frames are ordered" claim — and tells the next person which invariants not to rely on.

Backpressure is architecture, not tuning. Bounded channels everywhere make the memory ceiling a property of the topology, not a benchmark. The cost is that producers must be written to await — exactly the discipline the design wants.

Test the seams. Split-point decoding, coalesced reads, truncated closes, full queues, and real TLS connections test where assumptions meet reality. Most protocol bugs live at the seams, not in the middle of functions.

Conclusion

TCP gives reliability, not messages; everything above it in Lanweave is built on that distinction. The frame codec turns bytes into bounded, validated frames; the message layer turns frames into unambiguous typed controls; the state machine decides whether those controls are allowed right now; the writer serialises output under an ordering contract it states precisely; the transfer engine streams file data through bounded channels with hashes and deadlines attached. The hard parts — ordering, memory bounds, failure scopes, hostile input — are visible in the code and covered by tests aimed at the seams rather than the happy path.

Source and further reading

The implementation is at github.com/etim66/lanweave. The frame header and message schemas are documented in docs/MESSAGE_FORMAT.md, the protocol rules in docs/PROTOCOL.md, the state machines in docs/STATE_MACHINES.md, and the transport profile in docs/TRANSPORT.md.

Written by the developer of Lanweave. The project is open source and the design documents are part of it; if you find a protocol flaw or a case the framing tests miss, a reproducible example is the most useful contribution.

References

RFC 9293 — Transmission Control Protocol (TCP): https://www.rfc-editor.org/rfc/rfc9293
RFC 8446 — The Transport Layer Security (TLS) Protocol Version 1.3 (record layer, §5): https://www.rfc-editor.org/rfc/rfc8446#section-5
RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format: https://www.rfc-editor.org/rfc/rfc8259
RFC 4648 §5 — Base64url encoding: https://www.rfc-editor.org/rfc/rfc4648#section-5
Tokio, select! macro: https://docs.rs/tokio/latest/tokio/macro.select.html
Tokio, bounded mpsc channel: https://docs.rs/tokio/latest/tokio/sync/mpsc/fn.channel.html
Tokio, AsyncReadExt::read_buf: https://docs.rs/tokio/latest/tokio/io/trait.AsyncReadExt.html#method.read_buf
Tokio, AsyncWriteExt::flush: https://docs.rs/tokio/latest/tokio/io/trait.AsyncWriteExt.html#method.flush
bytes, BytesMut::split_to and BytesMut::freeze: https://docs.rs/bytes/latest/bytes/struct.BytesMut.html
serde_json::value::RawValue: https://docs.rs/serde_json/latest/serde_json/value/struct.RawValue.html
The cargo-fuzz book: https://rust-fuzz.github.io/book/cargo-fuzz.html
tempfile::NamedTempFile::persist_noclobber: https://docs.rs/tempfile/latest/tempfile/struct.NamedTempFile.html#method.persist_noclobber