---
title: "sdk/go"
description: "Go-Server-SDK für netzwerklose JWT-Prüfung, Anfrage-Authentifizierung undWebhook-Signaturvalidierung."
locale: "de"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/de/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/go

## Zustand

Implementiert und lokal verifiziert. Die echteIdP-Round-Trip-Verifizierung (JWKS-Abruf, Token-Signierung/Prüfung gegeneine Live-Vonvon-Instanz) wurde noch nicht durchgeführt und muss vor demProduktionseinsatz abgeschlossen werden.

Registry-Status: UNPUBLISHED. Installieren Sie dieses SDK nur aus einem Checkout des Repository-Quellcodes; verwenden Sie keine externe Paket-Registry.

Die Anfrageauthentifizierung akzeptiert standardmäßig nur Bearer. Ein anwendungseigenes JWT-Cookie wird nur gelesen, wenn sein exakter Name konfiguriert ist. Das opake Core-Cookie \_\_Host-vonvon.rt.\* wird niemals durchsucht oder lokal verifiziert; tauschen Sie es aus, indem Sie den vollständigen Cookie-Header ohne Weiterleitungen an den exakt gleichursprünglichen Endpunkt POST /v1/sessions/token weiterleiten, und akzeptieren Sie nur eine Antwort, die ausschließlich das Feld token enthält.

## Installieren

```shell
go get github.com/StringKe/vonvon/sdk/go@main
```

## Schnellstart

Erstellen Sie beim Anwendungsstart einen `Client` und verwenden Sieihn über Anfragen hinweg wieder. Der Client speichert JWKS intern mitkonfigurierbarer TTL zwischen.

```go
import "github.com/StringKe/vonvon/sdk/go/vonvon"

client, err := vonvon.NewClient(vonvon.ClientOptions{
Issuer:        "https://vonvon.id",
Audience:      "your-client-id",
WebhookSecret: "whs_...",
})
if err != nil {
log.Fatal(err)
}

// HTTP middleware (recommended)
http.Handle("/api/", client.Middleware(apiHandler, func(w http.ResponseWriter, r *http.Request) {
http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
}))

// Inside a protected handler
func apiHandler(w http.ResponseWriter, r *http.Request) {
claims := vonvon.ClaimsFromContext(r.Context())
fmt.Fprintf(w, "hello %s", claims.Subject)
}
```

## Token direkt prüfen

```go
claims, err := client.VerifyAccessToken(ctx, tokenString)
if err != nil {
// handle verification failure
}
fmt.Println(claims.Subject, claims.OrgID)

// Explicit same-origin Core session -> JWT exchange
token, err := client.ExchangeSessionToken(
ctx,
"https://app.example.com/account",
request.Header.Get("Cookie"),
"/v1/sessions/token",
)
```

## Webhook prüfen

```go
func webhookHandler(w http.ResponseWriter, r *http.Request) {
event, err := client.VerifyWebhook(r)
if err != nil {
    http.Error(w, "invalid signature", http.StatusBadRequest)
    return
}
// event.Body: raw JSON body
// event.ID:   svix-id for idempotency
w.WriteHeader(http.StatusNoContent)
}
```

## Kern-API

| Symbol | Beschreibung |
| --- | --- |
| `NewClient(opts)` | Den Client erstellen. `Issuer` ist Pflicht; alle anderen Felder sindoptional. |
| `(*Client).VerifyAccessToken(ctx, token)` | Einen JWT-String prüfen, `*Claims` oder Fehler zurückgeben. |
| `(*Client).AuthenticateRequest(ctx, r)` | Token aus einer HTTP-Anfrage extrahieren und prüfen. Gibt immer`AuthState` zurück, panic nicht. |
| `(*Client).Middleware(next, onUnauthorized)` | Standard-`net/http`-Middleware. Injiziert bei Erfolg `*Claims`in den Kontext. |
| `ClaimsFromContext(ctx)` | Von der Middleware injizierte Claims extrahieren. |
| `(*Client).VerifyWebhook(r)` | Webhook-Anfrage-Signatur prüfen. Gibt bei Erfolg `*WebhookEvent` mitrohem Body zurück. |

## ClientOptions

| Feld | Standard | Beschreibung |
| --- | --- | --- |
| `Issuer` | erforderlich | Vonvon-Issuer-URL |
| `Audience` | leer (überspringen) | Erwarteter JWT-aud-Claim |
| `WebhookSecret` | leer | Webhook-HMAC-Signing-Secret |
| `JWKSCacheTTL` | `1h` | Lokale JWKS-Cache-TTL |
| `HTTPClient` | Standard-Timeout: 10 s | HTTP-Client für den JWKS-Abruf |

## Plattformhinweise

- ES256 ist der primäre Algorithmus; RS256 wird zur Kompatibilitätunterstützt. ES384 und ES512 sind noch nicht implementiert.
- JWKS wird von `{issuer}/jwks` abgerufen. Die automatischeOIDC-Discovery-Erkennung ist eine geplante Verbesserung.
- `Claims` bettet `jwt.RegisteredClaims` ein und ergänzt`ClientID`, `Scope`, `AMR`, `ACR`, `OrgID`,`OrgSlug`.

Source: https://vonvon.id/de/sdks/go/index.mdx