Architecture: what each component knows
Three components. Each knows only what it must.
Infra-server
Knows which stations are enrolled and their public Ed25519 keys. Knows who is requesting to connect to whom. Facilitates the WebRTC SDP exchange (session description — IP/port candidates, not payload). Never receives file bytes — even during TURN relay, the payload is DTLS-encrypted end-to-end before it enters the relay path.
Client daemon
Knows its own Ed25519 private key and the shared session key derived from X25519 ECDH. Knows the outbox and inbox paths on the local filesystem. Does not know the private keys of peer stations. Cannot modify its own crypto policy — policy is injected by the infra-server at session time.
File payload
Travels peer-to-peer via a DTLS-encrypted WebRTC DataChannel. In encrypt and sign+encrypt modes, a second application-layer envelope using a per-file ephemeral X25519 key wraps the payload inside the DTLS channel. Two independent encrypted channels.
Station authentication
Challenge-response over Ed25519. The private key never leaves the machine.
Key generation
Each daemon generates an Ed25519 keypair on first run. The private key is written to local storage and never transmitted. The public key is sent to the infra-server during enrolment — authenticated by a single-use enrolment token.
Challenge-response
On each connection, the infra-server issues a random 32-byte challenge. The daemon signs it with its Ed25519 private key and returns the signature. The infra-server verifies against the registered public key. No passwords. No shared secrets.
Enrolment tokens
One-time tokens issued from the admin panel. Each token is valid for a single enrolment and expires after 24 hours. Tokens cannot be reused and do not grant any persistent credential.
Crypto modes
Four modes. Configured per directional station pair. Enforced at session time by the infra-server — neither endpoint can negotiate them down.
No application-layer crypto. The WebRTC DataChannel still uses DTLS for transport encryption. Use only for internal transfers between fully trusted stations where performance is the priority.
Best for: internal LAN transfers, high-throughput pipelines
File is signed with the sender's Ed25519 key. The receiver verifies authenticity on arrival. File content is not encrypted at the application layer, but sender identity and integrity are cryptographically guaranteed.
Best for: internal transfers requiring non-repudiation
Per-file ephemeral X25519 key exchange. Payload encrypted with AES-256-GCM or ChaCha20-Poly1305. File content is opaque to anyone without the receiver's private key — including the relay.
Best for: external partner transfers, sensitive payloads
Combines Ed25519 signing with ephemeral X25519 encryption in one pass. The receiver gets both confidentiality and cryptographic proof of sender identity. The strongest option — negligible overhead on modern hardware.
Best for: regulated industry transfers, external partners, compliance
Ciphers & key derivation
Modern authenticated encryption. Both ciphers are AEAD — authentication and encryption in one pass.
AES-256-GCM
256-bit key, 96-bit nonce, 128-bit authentication tag. Hardware-accelerated on any x86-64 CPU with AES-NI. The default cipher for most deployments. NIST-approved and widely accepted in regulated environments (FIPS 140-2 context).
ChaCha20-Poly1305
256-bit key. Constant-time implementation avoids timing side-channels. Preferred on ARM and embedded targets where AES-NI is absent. RFC 8439 standard. Equivalent security level to AES-256-GCM.
Key exchange
Per-file ephemeral X25519 ECDH. A fresh keypair is generated for every file transfer. Session keys are never reused. Compromise of a long-term station key does not expose prior file payloads (forward secrecy at the file level).
Chunking
Files are streamed in 32 KB chunks. Each chunk is encrypted and authenticated independently. A corrupted or tampered chunk fails authentication before the receiver writes it to disk. Partial delivery is detected and rejected.
TURN relay model
PeerAegis always tries a direct peer connection first. The relay is a fallback, not the default path.
ICE negotiation
WebRTC ICE tries all candidate paths: direct (STUN reflexive), then relay (TURN). The fastest working path wins. On most corporate networks with permissive egress, a direct connection is established within seconds.
TURN encryption
When relay is required, bytes passing through the TURN server are still DTLS-encrypted end-to-end. The relay server sees UDP datagrams — it cannot decrypt them. In encrypt / sign+encrypt modes, there is additionally an application-layer encryption envelope inside the DTLS channel. The relay sees two layers of ciphertext.
Relay ownership
The TURN relay is embedded in your own infra-server binary. You own and operate the relay infrastructure — no third-party relay service is used. Enterprise customers can run the infra-server on-premises with no external dependencies.
Audit annotation
Every transfer log entry records the connection type: DIRECT or RELAY. Your audit team can see at a glance which transfers used direct P2P and which fell back to the TURN server.
Audit trail
Every transfer produces a structured log entry. No gaps, no summarisation — one row per file.
| Field | Type | Description |
|---|
| timestamp | ISO 8601 | Transfer completion time, UTC |
| transfer_id | UUID | Unique ID for this transfer event |
| sender_station | string | Enrolled station name (sender) |
| receiver_station | string | Enrolled station name (receiver) |
| filename | string | Original filename as sent |
| file_size_bytes | int64 | Payload size before encryption |
| sha256_hash | hex string | SHA-256 of original file content |
| crypto_mode | enum | none / sign / encrypt / sign+encrypt |
| cipher | enum | aes-256-gcm / chacha20-poly1305 |
| connection_type | enum | DIRECT or RELAY |
| duration_ms | int | Transfer wall-clock duration |
| status | enum | success / failed / rejected |
Logs are searchable and filterable in the admin panel. Professional and Enterprise tiers can export to CSV or Excel for audit submissions. Enterprise logs include a tamper-evident chain linking sequential entries.
IP allowlist enforcement
Available on Professional and Enterprise. Restrict which CIDR ranges can enrol stations or initiate connections.
Enrolment restriction
Enrolment token use can be restricted to specific IP ranges. A token issued to a partner can be configured to reject enrolment attempts from outside the partner's known address block.
Connection restriction
Per-station IP allowlists block signaling and TURN relay requests from non-whitelisted sources. An attacker with a valid enrolment token but the wrong source IP cannot establish a session.
Licence enforcement
We disclose this mechanism in full — no surprises.
The infra-server polls a Firebase Firestore document approximately every 6 hours to verify the licence status. On a valid licence, no action is taken. On expiry or explicit revocation, the infra-server stops brokering new peer connections. Existing transfers in progress are allowed to complete.
What the kill-switch can and cannot do
The kill-switch can prevent new sessions from being brokered by the infra-server. It cannot delete files already transferred, cannot access files on your daemon machines, and cannot affect daemons that are mid-transfer. Data you have already received is always yours. Enterprise customers can discuss air-gapped licence options that do not require internet access for validation.