# localproxy — Anleitung & Tipps

> localproxy ist ein schlanker lokaler HTTP-Proxy für Browser-basierte Online-Tools — Download, Start, Konfiguration und Endpunkte, um externe URLs ohne CORS-Probleme abzurufen.

Source: https://www.jpkc.com/db/guides/proxy-jpkcom-dev-tools/

localproxy ist ein schlanker, sicherer lokaler HTTP-Proxy für Browser-basierte Online-Tools. Er bindet ausschließlich an `127.0.0.1` und erlaubt deinen Web-Anwendungen, externe URLs abzurufen — ohne an den CORS-Beschränkungen des Browsers zu scheitern.

## Anleitung

### Voraussetzungen

- Eine vorgefertigte Binary für deine Plattform (Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD — jeweils gängige Architekturen)
- Alternativ für den Build aus dem Quellcode: [Go 1.26+](https://go.dev/dl/)

### Binary herunterladen

Vorgefertigte Binaries für alle Plattformen liegen im Repository unter **Releases** (z. B. `localproxy-linux-amd64`, `localproxy-macos-apple-silicon`, `localproxy-windows-amd64.exe`).

### Ausführbar machen (macOS / Linux)

```bash
chmod +x ./localproxy-macos-apple-silicon
# macOS: Gatekeeper-Warnung der unsignierten Binary aufheben:
xattr -dr com.apple.quarantine ./localproxy-macos-apple-silicon
```

### Starten

Im einfachsten Fall ohne weitere Konfiguration:

```bash
./localproxy
```

Beim Start zeigt ein Banner die wichtigen Werte an: die **Adresse** (`http://127.0.0.1:PORT` — ohne `--port` ein zufälliger freier Port), das bei jedem Start neu erzeugte **Token**, die verwendeten **DNS-Server** und die zugelassenen **Origins**.

### Konfiguration

```
--port      int     TCP-Port (0 = zufälliger freier Port)                  [Standard: 0]
--origin    string  Erlaubte Origins, kommagetrennt
--timeout   int     Timeout für Upstream-Anfragen in Sekunden              [Standard: 30]
--max-mb    int64   Maximale Antwortgröße in MB (0 = unbegrenzt)           [Standard: 50]
--dns       string  DNS-Server, kommagetrennt, oder "system" für OS-DNS    [Standard: "1.1.1.1,8.8.8.8"]
--version           Versionsinformation ausgeben und beenden
```

Beispiele:

```bash
# Produktion: nur ein bestimmtes Tool zulassen
./localproxy --origin https://deintool.example.com

# Eigene DNS-Server (Quad9 + Cloudflare)
./localproxy --dns "9.9.9.9,1.1.1.1"

# DNS-Resolver des Betriebssystems verwenden
./localproxy --dns system
```

Standardmäßig löst localproxy Namen über **Cloudflare (1.1.1.1)** und **Google (8.8.8.8)** auf — unabhängig von der DNS-Konfiguration des Hosts, was über Maschinen hinweg konsistente Ergebnisse liefert. Fehlt beim `--dns`-Wert der Port, wird `:53` automatisch ergänzt.

### Endpunkte

| Endpunkt | Auth | Beschreibung |
|---|---|---|
| `GET/POST/HEAD /proxy?url=...` | ja (`X-Proxy-Token`) | Anfrage an die Ziel-URL weiterleiten (Body-Streaming, Metadaten-Header) |
| `GET /inspect?url=...` | ja | Verbindungs-Metadaten als JSON (SSL, Timing, IP, Header); `&body=1` inkl. Body |
| `GET /page?url=...` | ja | Vollständige Seitenanalyse: Redirect-Kette + Body + SSL + Timing in einem JSON |
| `OPTIONS /proxy|/inspect|/page` | nein | CORS-Preflight (204 mit CORS- und PNA-Headern) |
| `GET /ping` | nein | Health-Check (gibt `localproxy ok` zurück) |
| `GET /version` | nein | Versionsinfo als JSON |

### Einbindung im Tool

1. Nutzer gibt **Adresse** (`http://127.0.0.1:PORT`) und **Token** im Online-Tool ein.
2. Das Tool prüft die Verbindung über `/ping`.
3. Alle weiteren Anfragen laufen über `/proxy?url=...` mit dem Header `X-Proxy-Token`. Beispiel:

```javascript
const response = await fetch(
  `${PROXY_BASE}/proxy?url=${encodeURIComponent(targetUrl)}`,
  { headers: { "X-Proxy-Token": PROXY_TOKEN } }
);
```

Jede `/proxy`-Antwort liefert zusätzlich Upstream-Metadaten als Header: `X-Upstream-Protocol`, `X-Upstream-IP`, `X-Upstream-Timing` (z. B. `dns=12;tcp=45;ssl=23;ttfb=156;total=234`), `X-Upstream-Content-Encoding` und `X-Upstream-Content-Length`. Alle Upstream-Header sind per JavaScript lesbar.

## Tipps & Tricks

- **In Produktion Origins einschränken:** Ohne `--origin` sind alle Origins erlaubt. Für den produktiven Einsatz immer das konkrete Tool per `--origin https://deintool.example.com` freigeben.
- **HTTPS-Seite ruft HTTP-localhost auf — kein Problem:** Browser behandeln `http://127.0.0.1` als „potentially trustworthy origin" (W3C Secure Contexts). Anfragen von einer HTTPS-Seite an den lokalen Proxy werden **nicht** als Mixed Content blockiert; Chromes Private-Network-Access-Preflight wird automatisch beantwortet.
- **`/page` spart Roundtrips:** Der Endpunkt verfolgt die Redirect-Kette (bis zu 20 Hops), lädt den Body, inspiziert SSL und misst Timings in einem einzigen JSON — er ersetzt mehrere `/proxy`- und `/inspect`-Aufrufe.
- **SSL-Details, die der Browser nicht hergibt:** `/inspect` liefert Zertifikatsinformationen (Version, Aussteller, Gültigkeit, SANs, Chain), die über die Fetch-API nicht zugänglich sind. Ohne `body=1` wird upstream nur ein HEAD-Request gesendet (schneller, kein Body-Download).
- **Sicherheits-Defaults:** 48-Zeichen-Session-Token bei jedem Start neu, SSRF-Schutz (Ziel-Hosts werden aufgelöst und gegen private/Loopback-CIDRs geprüft), TLS-Upstream-Verifikation immer aktiv, Redirects werden **nicht** automatisch gefolgt (der Client entscheidet), Antwortgröße per `--max-mb` gedeckelt.
- **Nebenläufigkeit & Kompression:** Der Proxy bearbeitet Anfragen parallel (eine Goroutine pro Verbindung); jede Upstream-Anfrage nutzt eine frische Verbindung für genaues Timing. Brotli, gzip und deflate werden bei `/proxy` transparent durchgereicht — die Dekompression übernimmt der Browser.
- **Aus dem Quellcode bauen:** Mit Go 1.26+ via `go build -o localproxy .`; Cross-Compiles über `GOOS`/`GOARCH` (z. B. `GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -trimpath -o localproxy.exe .`). Ein Git-Tag (`git tag v1.0.5 && git push origin v1.0.5`) stößt über GitHub Actions automatisch plattformübergreifende Release-Builds an.
- **Tests & Linting:** `go test -race ./...` für den Race-Detector; das Projekt wird mit [staticcheck](https://staticcheck.dev/) gelintet (CI blockt den Release bei jedem Befund). staticcheck ist reines Dev-Tooling und landet nie in der Binary.

## Weiterführende Informationen

- Quellcode auf GitHub: <https://github.com/JPKCom/proxy-jpkcom-dev-tools>
- [Go (Download & Installation)](https://go.dev/dl/)
- [staticcheck](https://staticcheck.dev/)
- [Changelog dieses Projekts](https://www.jpkc.com/db/changelog/proxy-jpkcom-dev-tools/)