sdk/go | XID

SDK de servidor Go para verificación JWT sin llamadas de red, autenticación de solicitudes y validación de firma de webhook.

Estado

Implementado y verificado localmente. La verificación de ida y vuelta contra un IdP real (obtención de JWKS, firma/verificación de tokens contra una instancia XID en producción) aún no se ha realizado y debe completarse antes del uso en producción.

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

La autenticación de solicitudes acepta solo Bearer de forma predeterminada. Una cookie JWT propiedad de la aplicación solo se lee cuando se configura su nombre exacto. La cookie opaca de Core __Host-xid.rt.* nunca se busca ni se verifica localmente; intercámbiala reenviando el header Cookie completo al POST /v1/sessions/token del mismo origen exacto, con las redirecciones desactivadas, y acepta solo una respuesta que contenga únicamente el campo token.

Instalación

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

Inicio rápido

Crea un único Client al arrancar la aplicación y reutilízalo entre solicitudes. El cliente almacena el JWKS en caché internamente con un 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)
}

Verificar token directamente

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",
)

Verificar 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 principal

Símbolo	Descripción
`NewClient(opts)`	Construye el cliente. `Issuer` es obligatorio; los demás campos son opcionales.
`(*Client).VerifyAccessToken(ctx, token)`	Verifica una cadena JWT y devuelve `*Claims` o un error.
`(*Client).AuthenticateRequest(ctx, r)`	Extrae y verifica el token de una solicitud HTTP. Siempre devuelve `AuthState`, no entra en pánico.
`(*Client).Middleware(next, onUnauthorized)`	Middleware estándar de `net/http`. Inyecta `*Claims` en el contexto al tener éxito.
`ClaimsFromContext(ctx)`	Extrae los claims inyectados por el Middleware.
`(*Client).VerifyWebhook(r)`	Verifica la firma de la solicitud del webhook. Devuelve `*WebhookEvent` con el cuerpo sin procesar al tener éxito.

ClientOptions

Campo	Por defecto	Descripción
`Issuer`	obligatorio	URL del emisor XID
`Audience`	vacío (omitir)	Claim aud de JWT esperado
`WebhookSecret`	vacío	Secreto de firma HMAC del webhook
`JWKSCacheTTL`	`1h`	TTL del caché local de JWKS
`HTTPClient`	tiempo de espera predeterminado: 10 s	Cliente HTTP para obtener el JWKS

Notas de plataforma

ES256 es el algoritmo principal; RS256 está soportado por compatibilidad. ES384 y ES512 aún no están implementados.
El JWKS se obtiene de {issuer}/jwks. La detección automática de OIDC Discovery es una mejora planificada.
Claims integra jwt.RegisteredClaims y añade ClientID, Scope, AMR, ACR, OrgID, OrgSlug.