Protocol & Architecture: Privatta

Privatta is a peer-to-peer file transfer application that moves files directly between two machines, with no server, relay or third-party storage in the data path at any point. The desktop application is built on Electron with an embedded NestJS service; transport security and peer discovery are provided by libp2p.

This document describes the transport security model, peer identity scheme, access control architecture, audit mechanism, and the three network modes Privatta supports.

Privatta operates in three modes, selected automatically based on context. On a local network, peers are discovered via mDNS broadcast and an active network scan, with no router configuration or port forwarding required. Over the internet, peer discovery uses a Kademlia distributed hash table (DHT), with Circuit Relay v2 and AutoNAT handling NAT traversal for peers behind restrictive routers. In a fully air-gapped deployment, the application runs LAN-only with zero outbound calls — no DHT bootstrap, no internet dependency of any kind.

In all three modes, once two peers locate each other, the file transfer itself follows the same direct, encrypted path — there is no architectural difference in the data plane between LAN and internet transfers.

Every connection is secured by the Noise Protocol Framework as implemented in libp2p (@chainsafe/libp2p-noise). The handshake performs an X25519 elliptic-curve Diffie-Hellman key exchange to derive a shared session key with forward secrecy, authenticated with ChaCha20-Poly1305 AEAD encryption for the data channel itself. An Ed25519 signature over the handshake transcript proves possession of the peer's private key, binding the cryptographic session to a specific machine identity rather than merely to a network address.

Each Privatta installation generates a persistent Ed25519 keypair on first run, stored locally and never transmitted. The public key (the Peer ID) is the machine's identity over the internet; it survives reinstallation of the application but is unique per machine, so a stolen password alone cannot be used to connect from an unregistered device.

On a local network, machine identity is additionally checked by MAC address, providing a second, independent identity signal that does not depend on the cryptographic handshake having completed.

A connection request must satisfy three independent conditions before any file metadata is returned: a valid username and password (stored as a scrypt hash, never in plaintext), a machine identity that is explicitly whitelisted for that user account (Peer ID over the internet, MAC address on the LAN), and — implicitly — a completed Noise handshake proving the requesting machine actually controls the private key behind that Peer ID.

Any single failure is treated as a full rejection. Over the internet, a failed handshake triggers a permanent connection-gater ban for that peer for the remainder of the session, removing the option for repeated automated attempts. On the LAN, failed login attempts are rate-limited.

File visibility is configured per file: public to anyone on the local network, restricted to specific named users, or restricted to a user group (Enterprise tier). Related files can be grouped into virtual folders that share a single permission policy, so access for a large set of files is managed once rather than per file. Requests for files outside a requester's permission scope return a uniform denial — they do not reveal whether the underlying path exists, preventing enumeration.

Administrators can pre-authorise specific CIDR ranges as trusted — RFC 1918 private address space by default, with common overlay VPN ranges (Tailscale, ZeroTier, Hamachi) configurable — allowing remote teammates on a corporate VPN to connect with LAN-equivalent ergonomics without weakening the underlying authentication model.

Every connection attempt is written to a local SQLite access log: timestamp, source IP, machine identity, username, requested file, and outcome (allowed, denied, or banned), with the specific denial reason recorded. Passwords are never written to the log under any circumstance. The log persists across application restarts and is not transmitted off the machine; export and review are local operations.

The desktop application ships for Windows, macOS and Linux via Electron. An Android companion application (built on Expo / React Native) connects to a desktop Privatta server over the local network using the same authentication flow, and — on Android specifically — can itself act as a file server. An iOS client is in active development and will support the client (browsing and downloading) role first.

Because no server, relay or cloud component is ever in the data path, Privatta introduces no third-party data processor for the files it transfers. There is no Privatta-operated infrastructure that ever receives a copy of a transferred file. This architecture is compatible with data residency requirements that prohibit any cloud intermediary, and the local audit log supports compliance review without requiring a vendor data-sharing agreement.