breakpilot-pwa/pca-platform/README.md

# PCA Platform - Person-Corporate-Agent

Plattform zur Monetarisierung von KI-Crawler-Zugriffen und Human-vs-Bot-Erkennung.

## Übersicht

Die PCA Platform ermöglicht Website-Betreibern:
1. **Bot-Erkennung**: Unterscheidung zwischen Menschen und Bots durch Verhaltensheuristiken
2. **Step-Up-Verification**: WebAuthn oder Proof-of-Work für verdächtige Besucher
3. **Monetarisierung**: KI-Crawler können gegen Micropayment Zugriff erhalten (HTTP 402)

## Architektur

```
┌────────────────────┐     ┌────────────────────┐     ┌──────────────────┐
│   Website          │────▶│   PCA Heuristic    │────▶│   Redis          │
│   + PCA SDK        │     │   Service          │     │   Session Store  │
└────────────────────┘     └────────────────────┘     └──────────────────┘
         │                          │
         │                          ▼
         │                 ┌────────────────────┐
         │                 │   Payment Gateway  │ (Future)
         │                 │   HTTP 402         │
         │                 └────────────────────┘
         │
         ▼
┌────────────────────┐
│   ai-access.json   │
│   Policy Config    │
└────────────────────┘
```

## Komponenten

### 1. Heuristic Service (Go)
- Port: 8085
- Berechnet Human-Score basierend auf Verhaltensmetriken
- Verwaltet Step-Up-Verifikation (WebAuthn, PoW)

### 2. JavaScript SDK
- Sammelt Verhaltensmetriken (Scroll, Mouse, Clicks)
- Sendet Ticks an Backend
- Führt Step-Up bei Bedarf durch

### 3. ai-access.json
- Policy-Datei für Zugriffsregeln
- Definiert Preise pro Rolle/Bot
- Konfiguriert Schwellenwerte

## Quick Start

```bash
cd pca-platform
docker compose up -d
```

Services:
- Heuristic Service: http://localhost:8085
- Demo Site: http://localhost:8087
- Redis: localhost:6380

## API Endpoints

### Heuristic Service

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/health` | Health Check |
| GET | `/pca/v1/config` | Client Config |
| POST | `/pca/v1/tick` | Metrics empfangen |
| GET | `/pca/v1/evaluate` | Score auswerten |
| GET | `/pca/v1/webauthn-challenge` | WebAuthn Challenge |
| POST | `/pca/v1/webauthn-verify` | WebAuthn verifizieren |
| GET | `/pca/v1/pow-challenge` | PoW Challenge |
| POST | `/pca/v1/pow-verify` | PoW verifizieren |

### Tick Request

```json
{
  "session_id": "pca_xxx",
  "dwell_ratio": 0.85,
  "scroll_depth": 45.0,
  "clicks": 5,
  "mouse_moves": 120,
  "ts": 1702828800000
}
```

### Tick Response

```json
{
  "session_id": "pca_xxx",
  "score": 0.72,
  "action": "allow",
  "message": "Human behavior detected"
}
```

## ai-access.json Konfiguration

```json
{
  "thresholds": {
    "score_pass": 0.7,
    "score_challenge": 0.4
  },
  "weights": {
    "dwell_ratio": 0.30,
    "scroll_score": 0.25,
    "pointer_variance": 0.20,
    "click_rate": 0.25
  },
  "step_up": {
    "methods": ["webauthn", "pow"],
    "primary": "webauthn"
  },
  "pca_roles": {
    "Person": { "access": "allow", "price": null },
    "Agent": { "access": "charge", "price": "0.001 EUR" }
  }
}
```

## SDK Integration

### Vanilla JavaScript

```html
<script src="/sdk/pca-sdk.js"></script>
<script>
  PCA.init({
    tick: { endpoint: '/pca/v1/tick', interval_ms: 5000 }
  });

  PCA.onScoreUpdate((score, action) => {
    if (action === 'challenge') {
      PCA.triggerStepUp();
    }
  });
</script>
```

### React

```jsx
import { useEffect, useState } from 'react';

function ProtectedContent() {
  const [verified, setVerified] = useState(false);

  useEffect(() => {
    PCA.init(config);
    PCA.onScoreUpdate(async (score, action) => {
      if (score >= 0.7) {
        setVerified(true);
      } else if (action === 'challenge') {
        const success = await PCA.triggerStepUp();
        if (success) setVerified(true);
      }
    });
  }, []);

  if (!verified) return <p>Verifying...</p>;
  return <div>Protected Content</div>;
}
```

## Heuristiken

| Metrik | Gewicht | Beschreibung |
|--------|---------|--------------|
| `dwell_ratio` | 30% | Sichtbare Verweildauer / Gesamtzeit |
| `scroll_score` | 25% | Maximale Scrolltiefe (0-100%) |
| `pointer_variance` | 20% | Mausbewegungsmuster (Varianz) |
| `click_rate` | 25% | Klicks pro Sekunde + Intervall-Varianz |

### Score-Interpretation

| Score | Bedeutung | Aktion |
|-------|-----------|--------|
| ≥0.7 | Wahrscheinlich Mensch | Allow |
| 0.4-0.7 | Unsicher | Optional Challenge |
| <0.4 | Wahrscheinlich Bot | Challenge erforderlich |

## Step-Up Methoden

### WebAuthn
- Biometrische Authentifizierung (FaceID, TouchID)
- Hardware Security Keys
- Höchste Sicherheit

### Proof-of-Work
- Client löst SHA-256 Puzzle
- Kein User-Input nötig
- Bots werden gebremst

## GDPR Compliance

Die Plattform ist GDPR-konform:
- ✅ Keine personenbezogenen Daten
- ✅ Keine Cookies
- ✅ IP-Anonymisierung möglich
- ✅ Nur aggregierte Metriken

## Entwicklung

### Tests ausführen

```bash
cd heuristic-service
go test -v ./...
```

### Service lokal starten

```bash
cd heuristic-service
go run ./cmd/server
```

## Roadmap

- [ ] Payment Gateway (HTTP 402)
- [ ] Stablecoin Integration (USDC, EURC)
- [ ] Lightning Network Support
- [ ] Publisher Dashboard
- [ ] Agent SDK für KI-Crawler
- [ ] WordPress Plugin
- [ ] Nginx Module

## Integration mit BreakPilot

Die PCA Platform kann in BreakPilot integriert werden:

1. **Admin-Bereich schützen**: Bot-Schutz für Consent-Management
2. **API monetarisieren**: EduSearch-Daten gegen Zahlung verfügbar machen
3. **Legal Crawler**: Als zahlender Agent auf andere Seiten zugreifen

## Lizenz

MIT License - Kommerziell nutzbar