eship/Extension/README.md

EShip Browser Extension

Chrome Extension (Manifest V3) fuer die Authentifizierung und Tool-Verwaltung der EShip Web-App.

Funktionen

• Authentifizierung: Login via Appwrite (Email/Password)
• Website-Schutz: Blockiert die Web-App fuer nicht-authentifizierte Benutzer
• Tools-System: Aktivierbare Tools mit individuellen Einstellungen
• Live-Updates: Einstellungen werden sofort auf der Website angewendet

Projektstruktur

Extension/
├── manifest.json           # Chrome Extension Manifest (MV3)
├── config.js               # Appwrite Konfiguration
├── background/
│   └── service-worker.js   # Background Service Worker
├── popup/
│   ├── popup.html          # Popup UI
│   ├── popup.css           # Popup Styles
│   └── popup.js            # Popup Logic
├── content/
│   └── content-script.js   # Content Script fuer Website
└── lib/
    └── appwrite.min.js     # Appwrite SDK Bundle

Installation

1. Appwrite API Key erstellen

WICHTIG: Du musst einen API Key in Appwrite erstellen:

1. Gehe zu https://cloud.appwrite.io
2. Waehle dein Projekt
3. Settings > API Keys > "Create API Key"
4. Scopes: users.read, users.write, sessions.write
5. Kopiere den API Key (wird nur einmal angezeigt!)

Siehe auch: setup/API_KEY_SETUP.md fuer detaillierte Anleitung.

2. Extension konfigurieren

Bearbeite Extension/config.js:

var APPWRITE_CONFIG = {
  endpoint: 'https://cloud.appwrite.io/v1',
  projectId: '696b82bb0036d2e547ad',
  apiKey: 'DEIN_API_KEY_HIER'  // WICHTIG: API Key hier einfuegen
};

3. Extension in Chrome laden

1. Oeffne Chrome und navigiere zu chrome://extensions
2. Aktiviere den Entwicklermodus (Toggle oben rechts)
3. Klicke auf Entpackte Erweiterung laden
4. Waehle den Extension/ Ordner aus
5. Die Extension erscheint in der Toolbar

4. Server starten

cd Server
npm install
npm run dev

Der Server startet unter http://localhost:5173

Testen

Auth-Flow testen

1. Ohne Login:

   • Oeffne http://localhost:5173
   • Die Seite zeigt einen "Zugriff gesperrt" Bildschirm

2. Login durchfuehren:

   • Klicke auf das Extension-Icon in der Toolbar
   • Gib deine Appwrite-Zugangsdaten ein
   • Klicke auf "Anmelden"
   • Nach erfolgreichem Login wird die Website automatisch geoeffnet

3. Nach Login:

   • Die Website ist voll zugaenglich
   • Das Extension-Popup zeigt das Tools-Menu

Tools testen

1. Oeffne das Extension-Popup (nach Login)
2. Aktiviere das Tool "Preise hervorheben"
3. Auf der Website werden alle .price Elemente mit rotem Rahmen hervorgehoben
4. Aendere den Selector oder die Farbe in den Tool-Einstellungen
5. Die Aenderungen werden sofort angewendet

Demo-Preise

Die Web-App enthaelt Demo-Preiselemente in der unteren rechten Ecke zum Testen des Highlight-Tools.

Tools-Registry

Tools werden in background/service-worker.js definiert:

const DEFAULT_TOOLS = [
  {
    id: 'highlight_prices',
    name: 'Preise hervorheben',
    enabled: false,
    settings: {
      selector: '.price',
      borderColor: '#ff0000',
      borderWidth: '2px'
    }
  }
];

Neues Tool hinzufuegen

1. Fuege das Tool zur DEFAULT_TOOLS Liste hinzu
2. Implementiere die Logik in content/content-script.js:

   function applyTool(tool) {
     switch (tool.id) {
       case 'dein_tool_id':
         applyDeinTool(tool.settings);
         break;
     }
   }
   

Message-Kommunikation

Popup <-> Service Worker

Action	Beschreibung
CHECK_AUTH	Prueft Auth-Status
LOGIN	Login mit Email/Password
LOGOUT	Beendet Session
GET_SETTINGS	Laedt Tool-Einstellungen
SAVE_SETTINGS	Speichert Tool-Einstellungen

Service Worker <-> Content Script

Action	Beschreibung
SETTINGS_UPDATED	Neue Tool-Einstellungen
AUTH_CHANGED	Auth-Status geaendert

Sicherheit

• Passwoerter werden nie im Klartext gespeichert
• Authentifizierung laeuft vollstaendig ueber Appwrite Sessions
• Session-Cookies sind HTTP-only und werden von Appwrite verwaltet
• Tool-Einstellungen werden in chrome.storage.sync gespeichert

Fehlerbehebung

Extension funktioniert nicht

1. Pruefe die Browser-Konsole auf Fehler
2. Oeffne chrome://extensions und klicke auf "Service Worker" bei der Extension
3. Pruefe die Konsole des Service Workers

Login schlaegt fehl

1. Pruefe die Appwrite-Konfiguration in config.js
2. Stelle sicher, dass der API Key gesetzt ist
3. Pruefe, ob der API Key die richtigen Scopes hat (users.read, users.write, sessions.write)
4. Stelle sicher, dass der Appwrite-Benutzer existiert
5. Pruefe, ob die Appwrite-Plattform-Einstellungen den Extension-Zugriff erlauben

Website bleibt blockiert

1. Lade die Website neu nach dem Login
2. Pruefe, ob die URL in manifest.json unter content_scripts.matches steht
3. Pruefe die Content-Script-Konsole (F12 auf der Website)

Bekannte Einschraenkungen

• Die Extension funktioniert nur auf den konfigurierten URLs (localhost:5173, localhost:3000)
• Fuer Produktions-URLs muss manifest.json angepasst werden
• Icons sind nicht enthalten (Chrome verwendet Standard-Icon)