Part 3 of the ERTH Architecture Series: Preventing port-scanning attacks and local socket hijacking in multi-process desktop apps.

In the second part of this series, we built a self-healing Watchdog daemon in Bun to monitor and resurrect our Python sidecar backend (Robyn).

Now, our desktop app is extremely stable. But it is also extremely insecure.

You might think: "This is a desktop app running entirely on 127.0.0.1 (localhost). People from the internet can't access it, so why do I need security?"

This is a classic cognitive blind spot in desktop app development. In reality, your local loopback interface is shared globally by the operating system. Any script running in the user’s web browser (e.g., a malicious website they happen to visit) can aggressively scan local ports (from 10000 to 65535). Once it hits your Robyn sidecar's dynamic port, it can send unauthenticated POST requests to delete databases, read private files, or trigger system actions.

To prevent this, we must build a Zero-Trust Shield using Opaque Tokens to lock down all communication between the frontend WebView and the Python sidecar.

The Zero-Trust Security Model

To block unauthorized local traffic, the frontend and backend must share a cryptographically secure, short-lived token. Any request lacking this token will be instantly rejected by Robyn with a 403 Forbidden response.

Here is how the defense line functions:

Let's implement this architecture step-by-step.

Step 1: Generating the Ephemeral Token in Bun

Rather than saving credentials to a local config file (which could be read by malware on the system), we generate a random UUIDv4 in Bun’s process memory at startup. This token exists only during the application's runtime.

// src-app/frontend/src/bun/index.ts
// Generate a cryptographically secure, one-time Opaque Token in memory
const agentSecretToken = crypto.randomUUID();

Next, we inject this token into the child process's environment variables when we spawn the Python sidecar:

// Spawn the Robyn child process, injecting the token silently
backendProcess = spawn({
  cmd: ["uv", "run", "python", "app.py"],
  cwd: backendPath,
  env: {
    ...process.env,
    AGENT_SECRET_TOKEN: agentSecretToken, // Cross-process memory delivery
    PYTHONUNBUFFERED: "1"
  },
  stdout: "pipe",
  stderr: "pipe",
});

Step 2: Implementing Python Interception Middleware

On the Python side, Robyn reads this secret token at startup. We implement a global @app.before_request() decorator that intercepts all incoming requests and verifies the Authorization header.

# backend/app.py
import os
import json
from robyn import Robyn, Request, Response, ALLOW_CORS

app = Robyn(__file__)

# Load the secret token injected by the Bun main process
AGENT_SECRET_TOKEN = os.environ.get("AGENT_SECRET_TOKEN")

@app.before_request()
def auth_middleware(request: Request):
    # CRITICAL: Always bypass CORS preflight OPTIONS requests!
    if request.method == "OPTIONS":
        return request

    auth_header = request.headers.get("Authorization") or request.headers.get("authorization")
    expected_token = f"Bearer {AGENT_SECRET_TOKEN}"

    # Check authorization header
    if auth_header == expected_token:
        return request

    # Block unauthorized request
    return Response(
        status_code=403,
        headers={"Content-Type": "application/json"},
        description=json.dumps({"error": "Forbidden: Invalid or Missing Opaque Token"})
    )

Step 3: Resolving the OPTIONS Preflight Trap

If you add custom headers like Authorization to cross-origin requests, the browser WebView will trigger an OPTIONS preflight request before sending the actual request (e.g. a POST or PUT).

If your authentication middleware immediately checks for the Authorization header and rejects the request, the OPTIONS preflight will fail with a 403 Forbidden. The browser will then block the subsequent real request, causing your frontend to hang.

This is why we do two things:

1. Pass OPTIONS through: The first line in our Python middleware returns the request immediately if method == "OPTIONS".
2. CORS configuration: We explicitly configure CORS in Robyn to whitelist our custom headers:

# Configure CORS to accept custom headers and HTMX signatures
ALLOW_CORS(app, origins=["*"], headers=[
    "Authorization", "Content-Type", 
    "hx-target", "hx-current-url", "hx-request", "hx-trigger"
])

Step 4: Injecting the Token into the WebView

When the WebView DOM is ready, the Bun process injects both the dynamic port and the secret token into the WebView’s window object:

win.webview.on("dom-ready", () => {
  if (portFound && backendPort > 0) {
    win.webview.executeJavascript(`
      window.__ENV__ = {
        BACKEND_PORT: ${backendPort},
        TOKEN: "${agentSecretToken}"
      };
      window.dispatchEvent(new CustomEvent('backend-ready', { 
        detail: { port: ${backendPort}, token: "${agentSecretToken}" } 
      }));
    `);
  }
});

Now, we hook into HTMX's configuration interceptor in our HTML frontend to automatically append the token to every outgoing AJAX request:

<script>
  document.addEventListener('htmx:configRequest', (evt) => {
    // Append the dynamic dynamic port to local URLs
    if (window.__ENV__ && window.__ENV__.BACKEND_PORT) {
      const port = window.__ENV__.BACKEND_PORT;
      if (evt.detail.path.startsWith('/')) {
        evt.detail.path = `http://127.0.0.1:${port}${evt.detail.path}`;
      }
    }

    // Inject the Opaque Token into the request headers
    if (window.__ENV__ && window.__ENV__.TOKEN) {
      evt.detail.headers['Authorization'] = `Bearer ${window.__ENV__.TOKEN}`;
    }
  });
</script>

Penetration Testing the Shield

To verify this, we run a local penetration test using curl.

If we send an unauthenticated request to the sidecar:

curl -i http://127.0.0.1:54321/api/v1/health

Robyn instantly intercepts and returns:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error": "Forbidden: Invalid or Missing Opaque Token"}

But when we pass the correct token:

curl -i -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:54321/api/v1/health

It returns:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "healthy"}

Our loopback interface is now fully locked down.

What’s Next?

Our dual-core engine is responsive, self-healing, and secure. But our application is still stateless. If the user restarts their computer, all data is lost. We need a persistence layer.

But we don't want a heavy local database daemon, and we also want our app to work offline on the subway and sync to the cloud when network becomes available.

In Part 4, we will introduce the Local-First Philosophy using Turso (libSQL) for seamless, zero-latency cloud-edge data sync.

📖 Read the Full Book on Leanpub (Includes a free 5-chapter preview edition!)

👉 Explore the open-source code on GitHub

Stay tuned for Part 4!