- No static or hardcoded credentials: Eliminate default
admin/adminaccounts and plaintext token files. - Transport authentication by default: Reject unencrypted
http:///ws://unless explicitly overridden for isolated lab testing (--insecure-http), and support strict TLS SHA-256 certificate pinning (--tls-pin). - Hardware-locked key custody: Bind local signing keys, file vault keys, and bearer tokens to OS hardware mechanisms (
DPAPI,MachineGuid, TPM presence check). - Zero-knowledge Master Server option: Enable client-side
--e2efile encryption (EZV1) and end-to-end encrypted CubeHash/wspeer sessions so the Master Relay cannot read file contents, chat messages, or hardware serial telemetry. - Anti-impersonation & anti-traversal hardening: Pin device
Ed25519public keys across REST enrollment and WebSocket relay registration, and validate every relative file path and identifier strictly.
- When initialized without
--admin-pass,eazyconnect-servergenerates a 16-byte CSPRNG password (hex-encoded) for the initialadminuser and writes it to<data-dir>/bootstrap-admin.txt(0600on Unix). - Passwords are stored using
Argon2id(argon2) salted hashes in<data-dir>/users.json. - Session bearer tokens (
ezc_<64hex>, 24-hour TTL) are issued from CSPRNG and stored on disk only as their SHA-256 hex digest in<data-dir>/tokens.json.
- Devices enroll via challenge-response:
GET /api/v1/auth/challenge-> client signseazyconnect-http-auth-v2 || nonce || len(client_id) || client_id || len(challenge_id) || challenge_idwith itsEd25519key ->POST /api/v1/auth/verify. - Server supports
EnrollmentPolicy::OpenLanorEnrollmentPolicy::InviteCode(code)checked in constant time (subtle::ConstantTimeEq). When active VPN adapters are detected underOpenLan(without--lan-only),eazyconnect-serverwarns the operator at startup to enable--invite-code. - On first valid enrollment (or first WS registration), the device's
[u8; 32]Ed25519public key is pinned toclient_idin<data-dir>/devices.json(check_or_pin_device_key). Subsequent attempts using the sameclient_idwith any different key fail with403 identity_mismatchon HTTP and rejection on/ws. - When a roaming or reconnecting device proves ownership of its pinned
Ed25519key over a fresh WebSocketchallenge_nonce, the relay atomically replaces any lingering half-open session (session_replaced); mismatched keys are still blocked before session replacement. - Default self-signed server certificates are persisted under
<data-dir>/tls/{cert.pem,key.pem}(0600key on Unix) so client--tls-pinvalues remain valid across server restarts until--regen-tlsis invoked.
DISCOVER_EAZYCONNECTprobes return aDiscoveryBeaconJSON signed with the Master'sEd25519key overeazyconnect-discover-v3 || version || host || port || https || tls_cert_sha256_hex || master_ed25519_pub || alternate_urls.discover_mastersverifies every beacon signature (signature_valid) before returning it to CLI callers or diagnostics.
With --e2e, eazyconnect-client encrypts each file locally before calling POST /api/v1/files/upload:
- Local 32-byte
vault_keyis stored sealed viaseal_local_secret(vault.key.sealed) or supplied across trusted devices via--vault-key-hex. encrypt_file_for_vaultgenerates a random 16-bytesaltand 24-bytenonce.HardwareProvider::seal_secret(b"eazyconnect-file-vault-v1", vault_key)binds the key to the hostOsBoundHardwareProvider.hkdf_expand_labelderives a unique per-fileXChaCha20-Poly1305key bound to(salt, relative_filename)and seals withAAD = "eazyconnect-vault-aad-v1" || salt || relative_filename.- Output envelope layout:
EZV1 (4B) || salt (16B) || nonce (24B) || ciphertext + tag.
Copying ciphertext off the Master Server or attempting decryption on an unauthorized machine / mismatched filename fails authentication.
- Key Exchange:
PairOfferandPairAcceptexchange ephemeralX25519keys and initial ratchet keys, signed with each peer'sEd25519identity (pair_offer_sign_bytes,pair_accept_sign_bytes) and TOFU-pinned viaverify_or_pin_peer. - Transcript & PSK Binding: Shared ECDH output, transcript (
pair_id, IDs, ephemeral &Ed25519keys), and optional pre-shared key (--psk) feedhmac_sha256_parts+hkdf_expand_labelto provision asymmetric TX/RXDuplexCubeSessiondirections plus a human-verifiablesafety_fingerprint(XXXX-XXXX-XXXX-XXXX). - Metadata Padding: All
EazyAppMessagevariants (ChatText,FileShared,SerialData,SerialCommand,HardwareProbeRequest,HardwareProbeResponse) are encoded into 256-byte bucket multiples with CSPRNG padding (encode_padded_bucket) before CubeHash encryption so the blind relay cannot distinguish chat messages from hardware serial commands or leak exact lengths. - Zero-Oracle & Commit/Rollback:
- Senders keep TX mesh mutation staged (
pending_outbound) until receivingDeliveryAck(commit_ack) or rolling back cleanly (rollback_outbound) on peer disconnect. - Receivers decrypt via
decrypt_zero_oraclewithHoneyProfile::ChatPlaintext, executing constant work without mutating session state or exposing error oracles on tampered/forged frames.
- Senders keep TX mesh mutation staged (
- Bit-Rot Repair & Epoch Hopping:
WirePacketcarries TMR shadow bytes healed automatically by bitwise majority voting (healed_bits).hop_epochexecutes TX/RXX25519ratchets signed withEd25519(epoch_hop_sign_bytes).
validate_id(eazyconnect-hw): enforces non-empty identifiers (<= 128 chars) containing only[A-Za-z0-9_.-]and rejects traversal sequences (.., slashes, colons).validate_rel_path(eazyconnect-server): rejects empty/oversized paths (> 512 chars), leading slashes, drive letters (:), NUL/control characters, empty segments,.and.., and non-normal OS path components; skips symlinks during recursive listing.- Secret/state files are excluded via
.gitignore(bootstrap-admin.txt,users.json,devices.json,tokens.json,config.json,sync-manifest.json,*.key,*.pem,*.sealed,*.keystore,*keystore*.json,*.eazyconnect-id.json,tls/,keystore/,data/,target/).