# Lightpanda Session Bridge

> An open-source bridge to explicitly transfer authenticated browser sessions (Google OAuth, Passkeys, SSO, 2FA cookies) into an isolated local [Lightpanda](https://lightpanda.io) headless browser runtime via Chrome DevTools Protocol (CDP).

## Key Metadata
- **Repository:** https://github.com/Raknaos/lightpanda-session-bridge
- **Live Demo & Docs:** https://raknaos.github.io/lightpanda-session-bridge/
- **Deep-Dive Article:** https://dev.to/raknaos/handing-real-logins-to-headless-ai-agents-building-the-lightpanda-session-bridge-17je
- **License:** MIT License
- **Target Runtime:** Lightpanda CDP (WebSocket on 127.0.0.1:9222)
- **Local Relay Port:** 127.0.0.1:8765 (Loopback only)

## Core Capabilities
- **Zero Credential Sharing:** AI agents and LLMs never receive plain text passwords or long-lived API keys.
- **Human-in-the-Loop Authentication:** The human user authenticates normally inside a standard desktop browser (Chrome, Comet, Edge). The extension securely captures scoped cookies for the active origin upon explicit user interaction.
- **Strict SSRF Firewall:** The local relay blocks identity providers (Google accounts, Microsoft, Apple, GitHub, Auth0), rejects private IPv4/IPv6 ranges (`127.0.0.0/8`, `10.0.0.0/8`, `192.168.0.0/16`), and resolves DNS with 60-second pinning to prevent TOCTOU / DNS rebinding.
- **Automatic Token Pairing:** First-run handshake via `/v1/bootstrap` ensures only callers carrying a verified `chrome-extension://` Origin receive the shared authorization secret (`X-Bridge-Token`).
- **Python Client SDK:** Simple Python module (`lightpanda_client.py`) allowing agents to attach to authenticated pages and execute DOM/JS evaluations.

## Installation & Usage
```bash
git clone https://github.com/Raknaos/lightpanda-session-bridge.git
cd lightpanda-session-bridge
pip install -r requirements.txt

# Start Lightpanda (WSL2)
./scripts/start-lightpanda.ps1

# Start Local Relay
./scripts/start-relay.ps1
```
Load the `extension/` directory unpacked in `chrome://extensions` (Developer Mode). Open popup to auto-pair. Click "Sync Session" on any logged-in site.