Skip to content

OpenSIN-AI/OpenSIN-Bridge

BranchesTags

Repository files navigation

🌉 OpenSIN Bridge

Die ultimative Brücke zwischen AI-Agenten und echtem Chrome
🔒 Session-bound Automation | 🎭 Unsichtbar für Bot-Detektoren | ⚡ 92 RPC Tools

Version License Stealth Tools

📋 Inhaltsverzeichnis

🚀 Was ist OpenSIN Bridge?

OpenSIN Bridge ist eine Chrome Manifest V3 Extension, die den echten Chrome-Browser eines Benutzers in einen scriptfähigen Browser für AI-Agenten verwandelt.

🔑 Kernmerkmale

Feature Beschreibung
Echte Sessions Nutzt echte Cookies, Passwörter, Autofill und Fingerprints
92 RPC Tools Vollständige Kontrolle über Tabs, DOM, Cookies, Network und mehr
Stealth v2 17-Evasion-Module neutralisieren Bot-Erkennung
Multi-Transport WebSocket, Native Messaging, extern_connectable
Session-Bound Perfekt für Plattformen, die Playwright/Puppeteer blockieren

💡 Anwendungsfälle

  • ✅ Bezahlte Umfrage-Plattformen (Session-Erhaltung)
  • ✅ CRM-Automatisierung mit echten Logins
  • ✅ E-Commerce Preis-Monitoring mit Account-Zugang
  • ✅ Social Media Management mit echten Profilen
  • ✅ Jede Plattform, die Headless-Browser erkennt und blockiert

⚔️ Warum Bridge statt Playwright?

Die meisten Agent-Browser starten ein frisches Chromium ohne Profil. Das ist perfekt für Tests, aber katastrophal für Seiten, die auf echte User-Sessions prüfen.

Vergleichstabelle

Dimension Playwright/Puppeteer OpenSIN Bridge
Chrome Instanz Gespawnetes Chromium Echtes installiertes Chrome
Profil/Cookies/2FA Leer, synthetisch Echt, vor-authentifiziert
navigator.webdriver true (leckt!) undefined (v2 Stealth)
Headful Optional Standard — User sieht alles
Fingerprint Generisch Individuell wie echter User
Use Case Testing, Scraping Session-bound Automation

💡 WICHTIG FÜR ENTWICKLER:
Diese Extension ist NICHT für hermetic testing gedacht. Dafür bleibt Playwright die bessere Wahl. Bridge ist spezialisiert auf Szenarien, wo Session-State (Cookies, Logins, History) überlebenswichtig ist.

🏗️ Architektur

┌─────────────────────────────────────────────────────────────────────────┐
│                    OPEN SIN BRIDGE ARCHITEKTUR                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────────────┐         JSON-RPC / JWT        ┌─────────────┐│
│  │  Chrome MV3          │ <---------------------------> │  Cloudflare ││
│  │  Extension           │                               │  Workers    ││
│  │                      │                               │  API        ││
│  │  • 92 RPC Tools      │                               │             ││
│  │  • Accessibility-Tree│                               │  • Auth     ││
│  │  • Multi-Strategy    │                               │  • Rate Lim ││
│  │    Clicker (CDP→DOM) │                               │  • Tracking ││
│  │  • Stealth Layer v2  │                               │  • Stripe   ││
│  │  • Offscreen Doc     │                               └──────┬──────┘│
│  │  • Native Messaging  │                                        │      │
│  └──────────┬───────────┘                                        │      │
│             │                                                    │      │
│             │ WebSocket / Native                                 │      │
│             ▼                                                    ▼      │
│  ┌──────────────────────┐                              ┌─────────────┐│
│  │  Real User Chrome    │                              │  Supabase   ││
│  │  (Echtes Profil)     │                              │  + Stripe   ││
│  │                      │                              │             ││
│  │  • Echte Cookies     │                              │  • DB       ││
│  │  • Echte Sessions    │                              │  • Subs     ││
│  │  • Echter Fingerprint│                              │  • Usage    ││
│  └──────────────────────┘                              └─────────────┘│
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Datenfluss (Schritt-für-Schritt)

  1. AI Agent sendet JSON-RPC Request (z.B. {"method": "dom.click", "params": {...}})
  2. Cloudflare Worker validiert JWT, prüft Rate-Limits, loggt Usage
  3. WebSocket/Native Messaging transportiert zum Chrome Extension
  4. Extension Background routet zur richtigen Tool-Implementierung
  5. Content Script führt Aktion im MAIN-World Kontext aus (mit Stealth v2)
  6. Ergebnis wird zurückgemeldet mit Proof (Screenshot-Delta, DOM-Hash)

⚠️ ACHTUNG ENTWICKLER:
Ändere NIEMALS die Reihenfolge der Stealth-Module in stealth-main.js. Die Idempotenz und Try-Catch-Wrap ist kritisch für die Stabilität. Jeder Fehler hier macht die gesamte Extension erkennbar!

🛠️ Installation

Voraussetzungen

  • Node.js >= 18.x
  • pnpm >= 8.x (npm install -g pnpm)
  • Chrome >= 116 (Manifest V3 Support)
  • Cloudflare Account (für Server-Deployment)
  • Supabase Project (für Auth/DB)

Schritt-für-Schritt

# 1. Repository klonen
git clone https://github.com/OpenSIN-AI/OpenSIN-Bridge.git
cd OpenSIN-Bridge

# 2. Dependencies installieren
pnpm install

# 3. Environment Variables setzen
cp .env.example .env
# Bearbeite .env mit deinen Keys (SUPABASE_URL, SUPABASE_KEY, STRIPE_SECRET)

# 4. Extension im Dev-Modus laden
pnpm run ext:dev
# → Öffne chrome://extensions
# → Aktiviere "Developer Mode"
# → Klicke "Load unpacked" und wähle ./extension

# 5. Server deployen (optional für Cloud-Nutzung)
pnpm run deploy:server

# 6. Tests ausführen
pnpm test

Native Messaging Host installieren (für lokale Kommunikation)

cd native-host
chmod +x install_host.sh
./install_host.sh

📝 HINWEIS: Der Native Messaging Host ermöglicht die Kommunikation zwischen lokalen Python-Skripten und der Chrome Extension ohne WebSocket. Perfekt für lokale Agenten!

🚀 Schnellstart

Beispiel: Login auf einer Website automatisieren

// Beispiel: Python Agent mit WebSocket
import asyncio
import websockets
import json

async def login_agent():
    uri = "ws://localhost:8787"  # Lokaler Server oder Cloudflare URL
    async with websockets.connect(uri) as ws:
        # 1. Navigiere zur Login-Seite
        await ws.send(json.dumps({
            "type": "tool_request",
            "id": 1,
            "method": "nav.goto",
            "params": {"url": "https://example.com/login"}
        }))
        response = await ws.recv()
        print("Navigation:", response)
        
        # 2. Fülle Email-Feld aus
        await ws.send(json.dumps({
            "type": "tool_request",
            "id": 2,
            "method": "dom.type",
            "params": {
                "selector": "input[type='email']",
                "text": "user@example.com"
            }
        }))
        
        # 3. Fülle Passwort-Feld aus
        await ws.send(json.dumps({
            "type": "tool_request",
            "id": 3,
            "method": "dom.type",
            "params": {
                "selector": "input[type='password']",
                "text": "geheim123"
            }
        }))
        
        # 4. Klicke Login-Button (mit menschlicher Maus!)
        await ws.send(json.dumps({
            "type": "tool_request",
            "id": 4,
            "method": "dom.click",
            "params": {"selector": "button[type='submit']"}
        }))
        
        # 5. Warte auf Erfolg
        await asyncio.sleep(2)
        print("✅ Login abgeschlossen!")

asyncio.run(login_agent())

Beispiel: Snapshot der Seite holen (Accessibility Tree)

# Holt einen kompakten Snapshot der aktuellen Seite
response = await ws.send(json.dumps({
    "type": "tool_request",
    "id": 5,
    "method": "dom.snapshot",
    "params": {}
}))
# Antwort enthält kompakte AX-Tree mit Handles (@e1, @e2, ...)
# Viel kleiner als voller DOM (ca. 4KB vs 200KB+)

🧰 Tool-Referenz

Alle 92 Tools sind über JSON-RPC verfügbar. Hier die wichtigsten Kategorien:

Tabs-Management

Tool Beschreibung Beispiel
tabs.list Liste alle offenen Tabs {"method": "tabs.list"}
tabs.create Erstelle neuen Tab {"method": "tabs.create", "params": {"url": "..."}}
tabs.close Schließe Tab {"method": "tabs.close", "params": {"tabId": 123}}
tabs.activate Aktiviere Tab {"method": "tabs.activate", "params": {"tabId": 123}}

Navigation

Tool Beschreibung Beispiel
nav.goto Navigiere zu URL {"method": "nav.goto", "params": {"url": "..."}}
nav.back Zurück {"method": "nav.back"}
nav.reload Neu laden {"method": "nav.reload"}
nav.waitForLoad Warte auf Load-Event {"method": "nav.waitForLoad"}

DOM-Interaktion (HERZSTÜCK!)

Tool Beschreibung Besonderheit
dom.click Klicke Element 3-Stage Fallback: CDP → DOM.click() → MouseEvent
dom.type Tippe Text Mit menschlichen Verzögerungen
dom.fill Fülle Formular Smart Field Detection
dom.hover Hover über Element Für Dropdown-Menüs
dom.scroll Scrolle Seite Pixel-genau
dom.snapshot Hole AX-Tree Kompakt, mit Handles
dom.evaluate JS ausführen Im Page-Kontext

💡 WICHTIG: Der dom.click verwendet eine intelligente 3-Stufen-Strategie:

  1. CDP Mouse Input (echte Mausbewegung via Chrome Debugger Protocol)
  2. DOM click() (Fallback wenn CDP blockiert ist)
  3. MouseEvent Dispatch (letzter Ausweg)

Jeder Klick wird verifiziert durch DOM-Diff-Hash und optional Screenshot-Delta. Kein false positive! Wenn die Seite nicht reagiert, bekommst du ehrliches Feedback.

Cookies & Storage

Tool Beschreibung
cookies.get Hole Cookies für Domain
cookies.set Setze Cookie
cookies.getAll Alle Cookies
storage.local.get LocalStorage lesen
storage.session.set SessionStorage schreiben

Network

Tool Beschreibung
net.fetch HTTP Request ausführen
net.setUserAgent User-Agent ändern
net.block Ressourcen blocken (Ads, Tracker)
net.captureStart Network-Traffic mitschneiden

Vision (OCR & Element-Lokalisierung)

Tool Beschreibung
vision.locate Finde Element per Bilderkennung
vision.read OCR Texterkennung

Behavior Recording

Tool Beschreibung
behavior.start Starte Aufnahme
behavior.stop Stoppe Aufnahme
behavior.export Exportiere Timeline

🎭 Stealth Layer v2

Das Herzstück der Unsichtbarkeit. 17 Evasion-Module laufen als MAIN-World Content Script bei document_start.

Abgedeckte Fingerprints

Kategorie Module Status
Navigator webdriver, plugins, mimeTypes, languages ✅
Hardware hardwareConcurrency, deviceMemory ✅
Permissions permissions.query ✅
Media mediaDevices, getBattery, connection ✅
Chrome Runtime window.chrome.runtime ✅
Window Size outerWidth, outerHeight ✅
iFrames HTMLIFrameElement.contentWindow ✅
WebGL getParameter (Vendor/Renderer Spoof) ✅
Canvas toDataURL, getImageData (Micro-Noise) ✅
AudioContext getChannelData (Micro-Noise) ✅
Function.toString Proxy-preserved native signature ✅

So funktioniert's

Jedes Modul ist:

  • Idempotent: Kann mehrfach ausgeführt werden ohne Seiteneffekte
  • Try-Catch-gewrappt: Ein Fehler stoppt nicht den gesamten Stealth
  • Introspektierbar: window.__opensin_stealth_status__() gibt Status zurück

Testing gegen Bot-Detektoren

# 1. Extension bauen und laden
pnpm run ext:dev

# 2. Test-Seite öffnen
# Gehe zu: https://bot.sannysoft.com

# 3. Probe-Script in DevTools Console einfügen
# Datei: test/stealth/sannysoft-probe.js

# 4. Alle Checks müssen PASS melden!

⚠️ KRITISCH FÜR ENTWICKLER:
Teste JEDE Änderung an Stealth-Modulen gegen mindestens 3 Detektoren:

Dokumentiere Ergebnisse in docs/BENCHMARKS.md. Ohne Benchmark-Update kein Merge!

👨‍💻 Entwicklung

Projektstruktur

OpenSIN-Bridge/
├── extension/                 # Chrome MV3 Extension
│   ├── manifest.json          # ⚠️ ACHTUNG: CSP muss proxy + DNR erlauben!
│   ├── icons/
│   └── src/
│       ├── background/        # Service Worker (Hirn der Extension)
│       ├── content/           # Content Scripts
│       │   ├── bridge-isolated.js  # RPC Handler (isolated world)
│       │   ├── stealth-main.js     # 🎭 Stealth v2 (MAIN world!)
│       │   └── stealth-legacy.js   # v1 Shim (Rollback)
│       ├── core/              # Config, Logger, Errors, RPC
│       ├── drivers/           # Tabs, CDP, Offscreen
│       ├── automation/        # Human, Clicker, Typer, Snapshot
│       ├── tools/             # 92 Tool-Implementierungen
│       ├── transports/        # WebSocket, Native, External
│       └── shared/            # Deterministische Primitives
├── native-host/               # Python Native Messaging Host
├── server.js                  # WebSocket Relay (Cloudflare)
├── docs/                      # Dokumentation
├── test/                      # Testsuite
└── scripts/                   # Build & Deploy

Wichtige Entwicklungsregeln

  1. NIEMALS im default Branch arbeiten! Immer Issue-Worktrees nutzen:

    pnpm run issue:worktree -- --issue 42 --branch feature/mein-feature

  2. IMMER Tests schreiben bevor Code geändert wird (Test-Driven Development)

  3. IMMER Benchmarks aktualisieren bei Stealth-Änderungen

  4. NIEMALS Secrets committen! .env steht in .gitignore

  5. IMMER Comments hinzufügen! Andere Entwickler sind oft dumm und kaputtmachen ist leicht.

Nützliche Commands

# Extension im Dev-Modus laden
pnpm run ext:dev

# Stealth Unit Tests
pnpm run test:stealth

# Alle Tests
pnpm test

# Extension packen (für Chrome Web Store)
pnpm run ext:package

# Server deployen
pnpm run deploy:server

# Issue-Worktree erstellen
pnpm run issue:worktree -- --issue <NUMMER>

# Scope-Verification
pnpm run verify:issue-scope -- <DATEIEN>

Local bridge mode (dev):

  • Start the local MCP server: PORT=7777 node server.js
  • Load the unpacked extension from ./extension
  • The unpacked build defaults to ws://localhost:7777/extension

Runtime environment

Required server env vars:

  • PORT
  • TOOL_TIMEOUT_MS
  • EXTENSION_STALE_MS
  • KEEPALIVE_URL

Required Cloudflare/worker secrets:

  • SUPABASE_URL
  • SUPABASE_SERVICE_KEY
  • STRIPE_SECRET_KEY
  • STRIPE_WEBHOOK_SECRET
  • OPENAI_API_KEY

Local bridge notes:

  • ws://localhost:7777/extension is the unpacked-extension default
  • public tunneling should use a durable named Cloudflare Tunnel when the URL must stay stable

🧪 Testing & Benchmarks

Test-Suites

Suite Beschreibung Command
Stealth v2 Unit-Tests für Stealth-Module pnpm run test:stealth
Bridge Contract Tool-API-Verifikation pnpm run test:contract
Behavior Timeline Recording/Playback-Tests pnpm run test:behavior
Native Host Python-Host-Integration pnpm run test:native
Issue Worktree Isolationstests pnpm run test:issue-worktree

Benchmark-Prozedur

Siehe docs/BENCHMARKS.md für detaillierte Anleitung.

Kurzversion:

  1. Extension bauen und installieren
  2. Test-Seiten besuchen (sannysoft, creepjs, pixelscan)
  3. Probe-Scripts in DevTools ausführen
  4. Ergebnisse in docs/BENCHMARKS.md dokumentieren
  5. Nur mergen wenn ALLE Tests grün!

🔗 Integration mit OpenSIN Stealth Browser

OpenSIN Bridge und OpenSIN Stealth Browser teilen sich dieselben Algorithmen für menschliche Interaktionen.

Gemeinsame Features

Feature Bridge (JS) Stealth Browser (Python)
Bezier-Kurven ✅ automation/human.js ✅ input/human_mouse.py
Physiologischer Tremor ✅ ±0.4px Jitter ✅ ±0.4px Jitter
Variable Geschwindigkeit ✅ Gauss-Verteilung ✅ Gauss-Verteilung
3-Stage Clicker ✅ CDP → DOM → Dispatch ✅ Vision → DOM → JS-Force
Smart Frame Scan ✅ Iframe-Rekursion ✅ Iframe-Rekursion

Code-Beispiel: Gleiche Algorithmen in beiden Sprachen

JavaScript (Bridge):

// extension/src/automation/human.js
function applyPhysiologicTremor(points) {
    return points.map((p, i) => {
        if (i === 0 || i === points.length - 1) return p;
        return {
            x: p.x + (Math.random() - 0.5) * 0.8,
            y: p.y + (Math.random() - 0.5) * 0.8
        };
    });
}

Python (Stealth Browser):

# input/human_mouse.py
def _apply_physiologic_tremor(pts):
    vibrated = []
    for i, (x, y) in enumerate(pts):
        if i == 0 or i == len(pts) - 1:
            vibrated.append((x, y))
            continue
        tx = x + random.uniform(-0.4, 0.4)
        ty = y + random.uniform(-0.4, 0.4)
        vibrated.append((tx, ty))
    return vibrated

💡 SYNERGIE: Beide Projekte profitieren voneinander! Verbesserungen an einem Algorithmus sollten immer in BOTH Repositories eingespielt werden. Siehe docs/INTEGRATION-STEALTH-BROWSER.md.

⚠️ Wichtige Hinweise für Entwickler

🔴 DOs (Unbedingt beachten!)

✅ IMMER ausführliche Kommentare schreiben
Andere Entwickler verstehen sonst den Code nicht und machen alles kaputt.

✅ IMMER Issue-Worktrees nutzen
Nie direkt auf main committen!

pnpm run issue:worktree -- --issue 42 --branch feature/xyz

✅ IMMER Tests vor Änderungen schreiben
Test-Driven Development verhindert Regressionen.

✅ IMMER Benchmarks bei Stealth-Änderungen updaten
Dokumentiere in docs/BENCHMARKS.md.

✅ IMMER Secrets in .env lagern
Nie .env committen! Steht in .gitignore.

🔴 DON'Ts (Auf keinen Fall!)

❌ NIEMALS Stealth-Modul-Reihenfolge ändern
Die Idempotenz ist kritisch!

❌ NIEMALS headless: true verwenden
Sofortige Erkennung! Bridge braucht zwingend headful.

❌ NIEMALS CDP-Attach ohne Stealth v2
Der Debugger hinterlässt Fingerabdrücke.

❌ NIEMALS ohne Tests mergen
Auch kleine Änderungen brechen unerwartet Dinge.

❌ NIEMALS .env committen
GitGuardian scannt automatisch und blockt Commits.

📄 License

Proprietary. All rights reserved.

Der Server-seitige Code ist Trade-Secret-Material und nicht öffentlich zugänglich.
Die Extension-Quellen sind für Kunden unter NDA einsehbar.

🌟 Contributors

Dieses Projekt ist Teil des OpenSIN AI Ökosystems:

📞 Support & Kontakt

Made with ❤️ by the OpenSIN Team

Stars Forks

About

OpenSIN Bridge — Thin-Client Chrome Extension + Server-Side SaaS Brain (5€/mo). Extension is a dumb shell, all intelligence lives on Cloudflare Workers. PRIVATE — trade secret.

a2a.delqhi.com

Topics

chrome-extension saas monetization cloudflare-workers opnsin-agent

Resources

Readme

License

View license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages