Skip to content
Antimatter

Security & Zero Trust

Operating a remote-control interface for an AI development environment demands enterprise-grade security. Antimatter connects your mobile device to your local machine without opening any firewall ports or exposing your local IP address, using multiple overlapping layers of protection.

Defense-in-Depth Architecture

Section titled “Defense-in-Depth Architecture”

Compromising any single layer is not sufficient to gain access to your agent or machine.

LAYER 1  ──  Cloudflare Tunnel (TLS + origin validation)
LAYER 2  ──  256-bit Bearer Token (timing-safe comparison)
LAYER 3  ──  Ed25519 Cryptographic Handshake (MITM prevention)
LAYER 4  ──  End-to-End Encryption (zero-knowledge routing)
LAYER 5  ──  Biometric Authentication Gate (device owner verification)
LAYER 6  ──  Gateway/Adapter Sandboxing (execution isolation)
LAYER 7  ──  Payload Size Limits (DoS mitigation)

Layer 1: Cloudflare Tunnel

Section titled “Layer 1: Cloudflare Tunnel”

The Gateway uses cloudflared to expose the WebSocket server through a Cloudflare tunnel. This means:

  • No open firewall ports — your machine’s local WebSocket server is never directly reachable from the internet.
  • No static IP required — the tunnel URL changes with every restart (unless using a persistent Zero Trust domain).
  • TLS termination at Cloudflare — all traffic between mobile and Cloudflare edge is TLS-encrypted.

Origin Header Validation (CSWSH Protection)

Section titled “Origin Header Validation (CSWSH Protection)”

To prevent Cross-Site WebSocket Hijacking, the Gateway enforces strict Origin header validation on every WebSocket upgrade request. Only these origins are accepted:

  • vscode-webview://… (Antigravity IDE webview)
  • https://<team>.cloudflareaccess.com (Cloudflare Access)
  • Mobile app origins

Anything else → HTTP 403 Forbidden. This prevents malicious websites in your browser from silently connecting to the local server.

Layer 2: 256-bit Bearer & IPC Tokens

Section titled “Layer 2: 256-bit Bearer & IPC Tokens”

On first run, the Gateway generates two 256-bit (32-byte) cryptographic tokens using OS-level entropy:

  1. Pairing Token (Mobile ↔ Gateway):
    • Stored permanently in the OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret).
    • If the keychain is unavailable, it falls back to a headless AES-GCM vault secured by a key derived via 600,000 PBKDF2 iterations.
  2. IPC Token (Adapter ↔ Gateway):
    • Stored in ~/.antimatter_daemon/.ipc_token (mode 0600).
    • Ensures local adapters are authenticated before establishing an IPC bridge.

Both tokens are verified using crypto.timingSafeEqual (or its Python equivalent hmac.compare_digest) — immune to timing side-channel attacks. Invalid token → close code 4001 Unauthorized.

Layer 3: Ed25519 Cryptographic Handshake

Section titled “Layer 3: Ed25519 Cryptographic Handshake”

After token verification, the Ed25519 handshake proves the Gateway’s identity:

Client                             Gateway
  │                                  │
  │  AUTH_CHALLENGE { nonce }        │
  │ ────────────────────────────────►│
  │                                  │  sign(nonce) with Ed25519 private key
  │  AUTH_RESPONSE { signature }     │
  │ ◄────────────────────────────────│
  │                                  │
  │  verify(signature, public_key)   │
  │  ✓ proven genuine Gateway        │

The Ed25519 private key is stored in the OS keychain. The public key is transferred to the mobile client only during QR pairing. After pairing, the client uses the stored public key to verify every future connection — making Man-in-the-Middle attacks impossible even if the Cloudflare tunnel is compromised.

Layer 4: End-to-End Encryption (E2EE)

Section titled “Layer 4: End-to-End Encryption (E2EE)”

Beyond TLS (handled by Cloudflare) and token auth, Antimatter implements true E2EE using a Diffie-Hellman key exchange:

Pairing time:
  Phone generates ephemeral DH keypair → shares public key via QR
  Gateway generates ephemeral DH keypair → shares public key in response
  Both sides derive identical 256-bit shared secret (ECDH)
  *(This guarantees **Forward Secrecy** — because keys are ephemeral per-session, a compromised key today cannot decrypt past traffic.)*


Runtime:
  Sender: AES-GCM encrypt(payload, sharedSecret, randomNonce)
  Transport: only ciphertext traverses Cloudflare
  Receiver: AES-GCM decrypt(ciphertext, sharedSecret, nonce)

Zero-knowledge routing: Cloudflare, proxies, and any other intermediary can only see encrypted bytes. Only the device and Gateway can decrypt.

Platform Implementations

Section titled “Platform Implementations”
Platform Crypto Library
Android javax.crypto.Cipher (AES/GCM/NoPadding) + JCA Ed25519
iOS CryptoKit — AES.GCM.seal/open + Curve25519.Signing
Gateway Node.js crypto — createCipheriv / verify

Layer 5: Biometric Authentication

Section titled “Layer 5: Biometric Authentication”

Before the mobile app establishes any WebSocket connection, it requires the device owner’s biometric verification:

  • Android: BiometricPrompt — Fingerprint, Face Unlock, or PIN fallback.
  • iOS: LocalAuthentication — Face ID, Touch ID, or passcode fallback.

This ensures that even if someone physically picks up your phone, they cannot issue commands to your agent without authenticating as you.

Layer 6: Gateway/Adapter Sandboxing

Section titled “Layer 6: Gateway/Adapter Sandboxing”

The system creates a strict security airgap between network ingress and local execution:

Layer Internet Access Local Execution Holds Secrets
Gateway ✅ (via Cloudflare) ❌ ✅ (keys, tokens)
Adapters ❌ ✅ ❌

If an attacker breaches the Cloudflare tunnel, they still need to defeat the 256-bit token + Ed25519 handshake.

If they defeat the handshake, the Gateway only forwards structured JSON payloads to adapters via 127.0.0.1:8765. Adapters have zero internet exposure.

If they compromise an adapter, they can only send structured IPC messages — not execute arbitrary code on the Gateway.

Layer 7: Payload Size Limits

Section titled “Layer 7: Payload Size Limits”

To mitigate memory exhaustion (DoS) attacks:

  • Maximum WebSocket payload size: 10 MiB
  • Oversized frames → immediate connection close
  • Per-IP connection limits enforced at the Gateway level

Optional: Cloudflare Zero Trust (Enterprise)

Section titled “Optional: Cloudflare Zero Trust (Enterprise)”

For the strongest security posture, configure a persistent Cloudflare Zero Trust tunnel with an Application Policy:

  1. Create a Cloudflare Zero Trust account.
  2. Create a Tunnel and point it to localhost:8765.
  3. Add an Application Policy that requires your email/SSO to access the tunnel URL.
  4. Update your antimatter-gateway config with the CLOUDFLARE_TUNNEL_TOKEN.

This adds a secondary authentication layer before any WebSocket connection is even attempted — your mobile must be logged in to Cloudflare Access first.

Threat Model Summary

Section titled “Threat Model Summary”
Threat Mitigation
Network MITM (Cloudflare compromised) E2EE + Ed25519 handshake
Stolen QR code / pairing token Ed25519 identity proof on every connection
CSWSH (malicious website) Origin header validation → 403
Brute force token Timing-safe comparison + rate limiting
Physical phone theft Biometric auth gate before any connection
Adapter RCE escalation Gateway/adapter sandboxing + payload size limits
DoS via large payloads 10 MiB payload cap
Saif Mukhtar

Saif Mukhtar

Creator & Lead Developer of Antimatter · Android, iOS & Python engineer

🌐 saifmukhtar.dev⭐ GitHub👤 Gravatar❤️ Sponsor