sdk/go | XID

SDK serveur Go pour la vérification JWT sans réseau, l'authentificationdes requêtes et la validation des signatures webhook.

Statut

Implémenté et vérifié localement. La vérification aller-retour avec unvrai IdP (récupération JWKS, signature/vérification de jeton contre uneinstance XID active) n’a pas encore été effectuée et doit être complétéeavant toute utilisation en production.

Installer

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

Démarrage rapide

Créez un seul Client au démarrage de l’application et réutilisez-lepour toutes les requêtes. Le client met le JWKS en cache en interne avecun TTL configurable.

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)
}

Vérifier le jeton directement

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

Vérifier le webhook

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)
}

API principale

Symbole	Description
`NewClient(opts)`	Construire le client. `Issuer` est requis ; les autres champs sontoptionnels.
`(*Client).VerifyAccessToken(ctx, token)`	Vérifier une chaîne JWT, retourner `*Claims` ou une erreur.
`(*Client).AuthenticateRequest(ctx, r)`	Extraire et vérifier le jeton d’une requête HTTP. Retourne toujours`AuthState`, ne panique pas.
`(*Client).Middleware(next, onUnauthorized)`	Middleware `net/http` standard. Injecte `*Claims` dans lecontexte en cas de succès.
`ClaimsFromContext(ctx)`	Extraire les revendications injectées par le Middleware.
`(*Client).VerifyWebhook(r)`	Vérifier la signature de la requête webhook. Retourne `*WebhookEvent`avec le corps brut en cas de succès.

ClientOptions

Champ	Défaut	Description
`Issuer`	requis	URL d’émetteur XID
`Audience`	vide (ignorer)	Revendication aud JWT attendue
`WebhookSecret`	vide	Secret de signature HMAC pour webhook
`JWKSCacheTTL`	`1h`	TTL du cache JWKS local
`HTTPClient`	Délai d’attente par défaut de 10s	Client HTTP pour la récupération JWKS

Notes de plateforme

ES256 est l’algorithme principal ; RS256 est pris en charge pour lacompatibilité. ES384 et ES512 ne sont pas encore implémentés.
Le JWKS est récupéré depuis {issuer}/jwks. La détection automatiqueOIDC Discovery est une amélioration prévue.
Claims intègre jwt.RegisteredClaims et ajouteClientID, Scope, AMR, ACR, OrgID,OrgSlug.