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 two-factor connection scheme for internet transfers, access control architecture, audit mechanism, license activation, software distribution and update policy, and the three network modes Privatta supports. It reflects release 1.1.0; the changelog records what each release changed.

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 and generates a 6-character security code locally, shares the two with exactly one recipient by two different routes, and the recipient presents the key to be paired and the code to be answered. 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.

Since 1.1 the key is only the first of two factors, and deliberately the weaker one: it is minted by the signaling server and travels through it, so it is exactly the value an attacker on that path, or in the recipient's chat history, would obtain. The second factor is a 6-character security code generated on the host machine itself, from a CSPRNG over a 32-symbol alphabet chosen to survive being read aloud (no I/O/0/1). It never passes through the signaling server and is intended to travel by a different channel than the key — spoken on a call, sent by SMS. The host validates it before credentials and before returning any file metadata, including the public files a guest would otherwise see, so possession of a leaked key alone yields nothing. The code is bound to a single session, stops expiring once accepted so that long transfers are not interrupted, and is destroyed when sharing stops.

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 — then the security code, checked by the host process on every `list` and `get` frame, and then either a valid username and password (stored as a scrypt hash, never in plaintext) or an explicit guest session. On the LAN: a MAC address explicitly whitelisted for that user account, plus the same username-and-password check.

A guest session is an authenticated absence of credentials rather than an unauthenticated connection: the peer has still cleared both the key and the security code, and the file list it receives contains only entries whose access is set to Everyone and which the operator has additionally marked as internet-shared. A peer that signs in receives that same public set plus the files granted to its user or group. Requests for anything outside the resulting scope return the same uniform denial as any other out-of-scope request.

Failed attempts are rate-limited rather than rejected outright on the first try: 5 wrong security codes or passwords locks that session — over the internet or on the LAN — until the host issues a fresh connection key and code, 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: available to everyone, 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.

Internet exposure is a second, independent axis: a file is reachable over P2P only if the operator has marked it internet-shared, and the Everyone setting then determines whether a guest without an account can retrieve it. The two axes compose rather than override — a file marked Everyone but not internet-shared is unreachable over P2P, and a file marked internet-shared but restricted to a named user requires that user to sign in. The Internet P2P panel reports the number of files that would be visible to a guest before a connection key is issued, so the operator sees the exposed set before anyone else does.

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 connection attempt is written to a local SQLite access log: timestamp, channel (LAN or P2P), source IP, the connecting machine's name, MAC address and device ID, 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. Entries are additionally SHA-256 hash-chained to their predecessor with a checkpoint held outside the log table, so an edit, deletion, reordering or truncation performed directly against the database file is detected when the log is next opened rather than silently accepted. The log persists across application restarts and is not transmitted off the machine; export and review are local operations.

As of 1.1, internet (P2P) sessions are logged as durably as LAN ones. A P2P session records the connection itself, every sign-in and every refusal — including a rejected security code — each file the peer was denied, each completed or interrupted transfer, and the disconnect. Sign-in attempts against the LAN server are recorded on the same footing, successes and rate-limited attempts included, where previously only listings and downloads appeared. The hash chain is versioned, so entries written before the upgrade continue to verify against the newer field set.

One caveat about identity in the log: the entries record what the connecting machine reports about itself — its computer name, and its MAC address where it has one to report. Mobile clients send a device identifier generated on first run instead, because no current mobile operating system exposes a hardware MAC to applications. Neither is an authentication factor over the internet; the key, the security code and the credential check are. They are there so an operator reviewing the log can tell one visitor from another.

Windows builds — both the NSIS installer and the portable executable — are Authenticode-signed with a certificate issued to Royal SoftWorks, so the publisher is named by Windows at install time and the signature can be verified independently from the file's properties before it is run. macOS builds are not signed at the time of writing; Linux packages are distributed unsigned in the conventional formats (AppImage, deb, rpm).

From 1.1 the application checks for its own updates. The check is a single HTTPS GET for a small version manifest in the same directory the download page serves from, performed once, twenty seconds after launch, and never repeated while the application runs; it carries no account, identifier or telemetry, and a user-initiated check is available at any time from Settings. Nothing is downloaded without an explicit action. Update manifests are per-channel, so a pre-release build is never offered a stable release or the reverse.

Installation is attempted only where it can succeed. The application determines whether its own packaging format can replace itself — a portable executable and an unsigned macOS bundle cannot, and distribution packages belong to the system package manager — and where it cannot, it offers the download page instead of a failing in-place install. On macOS the check is a signature verification of the running bundle, so signed macOS builds enable in-place updates without an application change. Release notes are rendered as plain text rather than markup, and the decisions about whether a release is required, installable in place, or already declined are made in the privileged process rather than the renderer.

A release that changes the LAN protocol or the P2P handshake can declare itself required, either for all earlier versions or only for versions below a stated line. A required update removes the ordinary dismissal paths but not the user's agency: it can still be declined behind a confirmation that states the consequences, and that decision is recorded against the specific version rather than against required updates in general.

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.