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.

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

L’authentification des requêtes accepte uniquement Bearer par défaut. Un cookie JWT détenu par l’application n’est lu que lorsque son nom exact est configuré. Le cookie Core opaque __Host-xid.rt.* n’est jamais recherché ni vérifié localement ; échangez-le en transférant le header Cookie complet vers le POST /v1/sessions/token de même origine exacte, avec les redirections désactivées, et n’acceptez qu’une réponse contenant uniquement le champ token.

Installer

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

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)

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

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.