Handing Real Logins to Headless AI Agents: Building the Lightpanda Session Bridge

TL;DR: When autonomous AI agents need to interact with modern web dashboards, handing them passwords or session tokens in prompts is a security disaster. I built Lightpanda Session Bridge — an open-source MV3 Chrome extension and a hardened loopback relay that safely replicates your live browser session into a local Lightpanda headless runtime via CDP. Zero credentials typed, zero secrets exposed to LLMs.

If you build AI agents that do real work on the modern web, you know the exact wall every developer hits: authentication.

The moment your agent needs to check an AWS billing console, inspect private logs on a SaaS dashboard, or pull data from an internal portal, the demo breaks down. Modern apps don’t live on basic auth; they sit behind Google OAuth, SSO federations, hardware passkeys, and biometric 2FA prompts.

A headless browser cannot tap your security key, answer your phone's authenticator app, or blink at a FaceID prompt.

Faced with this, most builders resort to terrible compromises:

1. Hardcoding passwords into agent prompts or .env files (which leak into LLM context logs, chat histories, and traces).
2. Copy-pasting session cookies manually into configs (which expire quickly and offer zero scoping or SSRF protection).
3. Driving the user’s primary browser via raw CDP (which disrupts real work, risks hijacking other tabs, and introduces scary blast radiuses).

The Lightpanda Session Bridge is built on a different philosophy: keep the authentication ritual with the human, and hand the agent an isolated, authenticated runtime.

+-----------------------------------------------------------------------+
|  HUMAN BROWSER (Chrome / Edge / Comet)                                |
|  User logs in via Passkey / Google OAuth / 2FA                        |
|                                                                       |
|  [ 🐼 Sync Tab ] ---> Extension MV3 extracts strictly scoped cookies   |
+---------------------------------------+-------------------------------+
                                        | POST 127.0.0.1:8765
                                        | (with X-Bridge-Token + CORS check)
                                        v
+-----------------------------------------------------------------------+
|  LOCAL BRIDGE RELAY (relay/server.py)                                 |
|  - Loopback-only (127.0.0.1)                                          |
|  - IdP & Private IP blocking (anti-SSRF + DNS cache)                  |
|  - Cookie normalization (__Host-, __Secure-, RFC 6265bis)             |
+---------------------------------------+-------------------------------+
                                        | WebSocket CDP Protocol
                                        v
+-----------------------------------------------------------------------+
|  HEADLESS RUNTIME (Lightpanda in WSL2 @ :9222)                        |
|  - Isolated V8 / Zig engine                                           |
|  - Instant DOM / JS evaluation                                        |
|                                                                       |
|  AI Agent reads data via SDK (lightpanda_client.py)                   |
+-----------------------------------------------------------------------+

Why Session Transfer Beats Credential Sharing

Passwords and API tokens are the wrong unit of trust for agents. They grant permanent, unrestricted access. Once an LLM agent has your password, you have zero guarantee where that string will travel — subagent handoffs, external telemetry, debug dumps, or third-party inference providers.

A session cookie is fundamentally safer:

• It is ephemeral and expires automatically.
• It can be instantly revoked from your main browser simply by logging out.
• It is strictly scoped to a single target origin.

With the bridge, you authenticate once in your familiar browser. When you click Sync, the extension packages only the cookies relevant to that specific origin and pushes them into an isolated headless browser instance.

The LLM never sees your credentials. The relay never logs a cookie value. The machine gets straight to work.

Architecture: The Three Layers

The architecture is purposely minimal, robust, and audit-friendly:

1. The Chrome Extension (Manifest V3)

Designed with a clean, dark Quota Glass interface. It requires only standard scoped permissions (activeTab, cookies, storage). When clicked, it captures cookies for the active domain, normalizes them, and prepares a transfer envelope.

On first launch, it executes an auto-pairing handshake (/v1/bootstrap) with the local relay, storing a shared cryptographic token in local isolated storage without requiring manual copy-pasting.

2. The Hardened Loopback Relay (relay/server.py)

Listening exclusively on 127.0.0.1:8765, the relay is the security gateway. It:

• Enforces strict origin matching.
• Translates browser cookie structures into Lightpanda-compliant DevTools protocol messages (including converting lowercase sameSite tags like lax to Lightpanda's PascalCase Lax to avoid -31998 InvalidEnumTag CDP crashes).
• Normalizes __Host- and __Secure- cookie prefixes per RFC 6265bis.
• Forwards cookies over CDP WebSockets to the headless engine.

3. Lightpanda Headless Engine

Lightpanda is an ultra-fast, open-source headless browser built in Zig with V8, purpose-built for AI automation. Running Lightpanda in WSL2 isolates it from your Windows host environment while keeping execution blindingly fast with tiny memory footprints compared to full Chromium.

The Security Checklist: Defending Against SSRF & Local Leaks

Treating a local HTTP relay as a trusted boundary is how local privilege escalation happens. Because the relay accepts cookies, I designed it as an adversarial SSRF surface from day one:

• 🛡️ Zero Logging: Cookie names and values are never printed to stdout, logged to disk, or saved in history.
• 🔒 Loopback Only: Hardcoded binding to 127.0.0.1. No routable network interfaces exposed.
• 🚫 Strict Identity-Provider (IdP) Blacklisting: The relay automatically rejects transfers intended for identity roots — accounts.google.com, login.microsoftonline.com, appleid.apple.com, github.com, and auth0.com cannot be targeted.
• 🛑 SSRF IP & DNS Verification: Target domains must resolve to valid public IPv4/IPv6 addresses. Localhost aliases, 127.0.0.0/8, private subnets (10.0.0.0/8, 192.168.0.0/16), and wildcard DNS tools like nip.io are categorically dropped. DNS lookups are pinned with a 60-second cache to prevent time-of-check to time-of-use (TOCTOU) rebinding.
• 🔑 Origin-Restricted Handshake: Web pages or rogue local CLI scripts attempting to query /v1/bootstrap receive an immediate 403 Forbidden. Only callers presenting a legitimate chrome-extension:// Origin header can receive the pairing secret.
• 🧪 Live Verified: Backed by 9 automated security test suites, validating private IP rejections, CDP payload structures, and token enforcement.

How AI Agents Interact With The Session

Once the session is synced into Lightpanda, your agent script uses the bundled lightweight Python SDK (lightpanda_client.py):

from lightpanda_client import LightpandaClient

# 1. Connect to Lightpanda CDP runtime
client = LightpandaClient(cdp_ws="ws://127.0.0.1:9222/")
client.connect()

# 2. Attach to or spawn the target page (already carrying the synced session)
client.attach_or_create("https://app.example.com/dashboard")

# 3. Evaluate JavaScript inside the authenticated session context
dashboard_data = client.evaluate("""(() => {
    return {
        user: document.querySelector('.user-profile')?.textContent?.trim(),
        quotaRemaining: document.querySelector('.quota-display')?.textContent?.trim(),
        csrfToken: document.querySelector('meta[name="csrf-token"]')?.content
    };
})()""")

print(f"Agent operating as: {dashboard_data['user']}")
print(f"Remaining quota: {dashboard_data['quotaRemaining']}")

client.close()

The agent never asked for a password. The user never risked account takeover.

Quickstart (Under 3 Minutes)

1. Clone & Install Dependencies

git clone https://github.com/Raknaos/lightpanda-session-bridge.git
cd lightpanda-session-bridge
pip install -r requirements.txt

2. Launch Lightpanda & The Bridge Relay

In two PowerShell terminals:

./scripts/start-lightpanda.ps1   # Runs Lightpanda CDP on 127.0.0.1:9222 (WSL2)
./scripts/start-relay.ps1        # Starts relay on 127.0.0.1:8765

3. Load the Extension

1. Open chrome://extensions in Chrome, Comet, or Edge.
2. Toggle Developer Mode on.
3. Click Load unpacked and select the repository's extension/ folder.
4. Open the popup once while the relay runs — it auto-pairs instantly.
5. Navigate to any authenticated site, click the 🐼 icon, and hit Sync Session.

Honest Limitations

• Human-in-the-loop: You must click Sync once per session. This is an intentional security design choice, but it means this is built for supervised agent workflows, not headless server farms starting from scratch.
• Local machine only: The relay strictly refuses remote connections. Your agent script and your browser must reside on the same workstation or dev environment.
• Zig / WSL2 dependency: Lightpanda currently runs most smoothly on Linux/WSL2; the PowerShell scripts manage this automatically for Windows setups.

Try It Out & Contribute

The project is fully open-source under the MIT license:

• 📦 GitHub Repository: Raknaos/lightpanda-session-bridge
• 🌐 Project Landing Page: raknaos.github.io/lightpanda-session-bridge
• 🏷️ Release v0.3.4 (Zip Packaged): GitHub Releases

If you're building autonomous agents that need to navigate authenticated environments safely, take it for a spin and star the repo! Feedback, issues, and PRs are warmly welcome.