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 ever in the data path. The desktop application is built on Electron with an embedded NestJS service; internet transfers run over WebRTC, introduced by a lightweight, open-source, stateless relay that relays only the connection handshake.

The transfer model is pull-only: the recipient's client always initiates the request for a specific file, and the host process exposes no operation that pushes a file to a peer. This is enforced at the protocol level — a sender can make a file available and describe it, but cannot deliver it without the recipient requesting it — and holds identically on the LAN and over internet P2P.

This document describes the transport security model, the relay and connection-key scheme, access control architecture, audit mechanism, license activation, and the three network modes Privatta supports.

Privatta operates in three modes. 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, there is no peer-discovery step: the host requests a single-use, 32-character connection key from a signaling server, shares it with exactly one recipient out of band, and the recipient presents that key to be paired. The signaling server relays only SDP/ICE handshake messages over a WebSocket, using public STUN servers to help the two machines find a direct path; it never receives a file, a credential, or anything beyond the handshake, and it evicts the room the instant the peers connect, either one disconnects, or the 5-minute key expires unused. In a fully air-gapped deployment, the application runs LAN-only with zero outbound calls — no signaling server contact, no internet dependency of any kind.

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

The signaling server is a small, single-purpose WebSocket relay: it mints connection keys, matches a `join` request to the room a `create` request opened, and forwards opaque SDP/ICE payloads between the two sockets until the WebRTC data channel is up — at which point each client closes its own signaling connection and the server has nothing further to do with that session. It holds no database, and the reference implementation is built so that it structurally cannot log an IP address, a connection key, or a payload: its logging function takes a fixed string and has no parameter for one.

The default deployment, signal.royalsoftworks.com, is operated by Royal Softworks. The server is open source, so an organisation that would rather not depend on it can audit the code, run its own instance, and point its fleet at it instead by setting the signaling server address in Privatta's Settings — no application update required.

Internet connections are secured by WebRTC's mandatory DTLS handshake, negotiated directly between the two machines once the signaling server has introduced them; the data channel itself runs SCTP over that DTLS-secured transport. This is the same transport-security layer used by browser-native video calling rather than a bespoke protocol, so the cryptographic surface under review is WebRTC's own well-specified and widely audited implementation. LAN connections are secured the same way the LAN server has always secured them, independent of the internet transport.

Privatta does not rely on a persistent per-machine cryptographic identity for internet transfers. Instead, the host's signaling server mints a 32-character key (CSPRNG-backed, ~190 bits of entropy) on request. The key is single-use — deleted the moment the two peers pair, or after 5 minutes if nobody claims it — and must be shared with the intended recipient out of band (chat, email, in person). Anyone without the current key cannot join the room; anyone who does still has to clear the credential check below before any file list is returned.

On a local network, machine identity is instead checked by MAC address, which is unaffected by this model and continues to provide a second, independent identity signal alongside the credential check.

A connection request must satisfy independent conditions before any file metadata is returned. Over the internet: possession of the current, unexpired connection key — checked by the signaling server before the WebRTC connection is even established — plus a valid username and password (stored as a scrypt hash, never in plaintext), checked by the host's own process once the data channel is open. On the LAN: a MAC address explicitly whitelisted for that user account, plus the same username-and-password check.

Failed login attempts are rate-limited rather than rejected outright on the first try: 5 failures within a 10-minute window locks that session — over the internet or on the LAN — until the host issues a fresh connection key or re-approves the device. This replaces the earlier internet-transfer behaviour of banning a peer permanently on its first failed handshake.

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.

Pro and Enterprise licenses can be activated two ways. The default path calls an online activation endpoint once, which returns a license key bound to the installation. The offline path is designed for air-gapped or high-security environments that cannot make an outbound call: the administrator generates a machine fingerprint locally (a hash of hostname, platform and hardware identifiers), carries it to any online device, and downloads a machine-bound license file in return. That file is signed (Ed25519) and encrypted (AES-256-GCM) with a key derived from the license key and the machine's fingerprint together, so it decrypts only on the exact machine it was issued for and only with the correct license key.

Verifying the file requires no network access at all: the signature is checked before anything is decrypted, decryption itself enforces the license-key-and-fingerprint binding, and the file carries its own expiry independent of the underlying license's status. A license that has lapsed, been suspended, or been banned is rejected even if the file's own expiry window hasn't elapsed yet. Refreshing before that window closes requires returning to an online device once — the running installation itself never needs a connection.

On the Enterprise tier, every LAN connection attempt is written to a local SQLite access log: timestamp, source IP, machine identity, username, requested file, and outcome (allowed, denied, or blocked), with the specific denial reason recorded. Passwords are never written to the log under any circumstance. The log is append-only by construction — no delete or update operation exists in the codebase for it, so no administrator, support engineer, or attacker with application-level access can remove or alter an entry. The log persists across application restarts and is not transmitted off the machine; export and review are local operations.

Persisted audit logging for internet (P2P) transfers is on the roadmap. Today, P2P login failures are rate-limited and locked in memory for the session, but individual P2P requests are not yet written to the same durable log as LAN requests.

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. Pairing is by QR code: the desktop app displays a code encoding its address and TLS certificate fingerprint, the mobile app scans it, and the two are connected without an account or any manually typed connection string. An iOS client is in active development and will support the client (browsing and downloading) role first, including QR pairing.

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 Enterprise-tier local audit log supports compliance review without requiring a vendor data-sharing agreement. Offline license activation extends the same posture to the licensing layer itself: a deployment in a network-restricted environment never needs to phone home to keep running.