sdk/go | XID

SDK de servidor Go para verificação JWT sem rede, autenticação derequisições e validação de assinatura de webhook.

Estado

Implementado e verificado localmente. A verificação de ida e voltacom um IdP real (busca de JWKS, assinatura/verificação de tokencontra uma instância XID ativa) ainda não foi realizada e deve serconcluída antes do uso em produção.

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

A autenticação de requisições aceita somente Bearer por padrão. Um cookie JWT pertencente ao aplicativo só é lido quando seu nome exato é configurado. O cookie opaco do Core __Host-xid.rt.* nunca é pesquisado nem verificado localmente; troque-o encaminhando o header Cookie completo para o POST /v1/sessions/token da mesma origem exata, com redirects desativados, e aceite somente uma resposta que contenha apenas o campo token.

Instalar

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

Início rápido

Crie um Client na inicialização do aplicativo e reutilize-oentre requisições. O cliente faz cache do JWKS internamente com TTLconfigurável.

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

Verifica o token diretamente

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

Verifica 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	Descrição
`NewClient(opts)`	Constrói o cliente. `Issuer` é obrigatório; os demais campos sãoopcionais.
`(*Client).VerifyAccessToken(ctx, token)`	Verifica uma string JWT, retorna `*Claims` ou erro.
`(*Client).AuthenticateRequest(ctx, r)`	Extrai e verifica o token de uma requisição HTTP. Sempre retorna`AuthState`, não entra em pânico.
`(*Client).Middleware(next, onUnauthorized)`	Middleware padrão `net/http`. Injeta `*Claims` no contextoem caso de sucesso.
`ClaimsFromContext(ctx)`	Extrai claims injetados pelo Middleware.
`(*Client).VerifyWebhook(r)`	Verifica a assinatura da requisição de webhook. Retorna`*WebhookEvent` com o body bruto em caso de sucesso.

ClientOptions

Campo	Padrão	Descrição
`Issuer`	obrigatório	URL do emissor XID
`Audience`	vazio (ignorar)	Claim JWT aud esperado
`WebhookSecret`	vazio	Segredo de assinatura HMAC do webhook
`JWKSCacheTTL`	`1h`	TTL do cache local do JWKS
`HTTPClient`	Timeout padrão de 10s	Cliente HTTP para busca de JWKS

Notas da plataforma

ES256 é o algoritmo principal; RS256 é suportado paracompatibilidade. ES384 e ES512 ainda não estão implementados.
O JWKS é buscado de {issuer}/jwks. A detecção automática deOIDC Discovery é uma melhoria planejada.
Claims incorpora jwt.RegisteredClaims e adicionaClientID, Scope, AMR, ACR, OrgID,OrgSlug.