sdk/go | XID

Go-Server-SDK für netzwerklose JWT-Prüfung, Anfrage-Authentifizierung undWebhook-Signaturvalidierung.

Zustand

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

Installieren

go get github.com/StringKe/xid/sdk/go

Schnellstart

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

import "github.com/StringKe/xid/sdk/go/xid"

client, err := xid.NewClient(xid.ClientOptions{
    Issuer:        "https://xid.dev",
    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 := xid.ClaimsFromContext(r.Context())
    fmt.Fprintf(w, "hello %s", claims.Subject)
}

Token direkt prüfen

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

Webhook prüfen

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	XID-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änztClientID, Scope, AMR, ACR, OrgID,OrgSlug.