sdk/go | XID

네트워크 호출 없는 JWT 검증, 요청 인증, webhook 서명 검증을 위한 Go 서버 SDK.

상태

로컬에서 구현 및 검증되었습니다. 실제 IdP 왕복 검증(JWKS 가져오기, 실제 XID 인스턴스에 대한 토큰 서명/검증)은 아직 수행되지 않았으며 프로덕션 사용 전에 완료되어야 합니다.

설치

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

빠른 시작

애플리케이션 시작 시 Client를 하나 생성하여 요청 전반에 재사용하세요. 클라이언트는 구성 가능한 TTL로 JWKS를 내부적으로 캐시합니다.

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

토큰을 직접 검증합니다

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

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

심볼	설명
`NewClient(opts)`	클라이언트를 생성합니다. `Issuer`는 필수이며 다른 필드는 선택 사항입니다.
`(*Client).VerifyAccessToken(ctx, token)`	JWT 문자열을 검증하고 `*Claims` 또는 오류를 반환합니다.
`(*Client).AuthenticateRequest(ctx, r)`	HTTP 요청에서 토큰을 추출하고 검증합니다. 항상 `AuthState`를 반환하며 패닉하지 않습니다.
`(*Client).Middleware(next, onUnauthorized)`	표준 `net/http` 미들웨어. 성공 시 컨텍스트에 `*Claims`를 주입합니다.
`ClaimsFromContext(ctx)`	미들웨어가 주입한 클레임을 추출합니다.
`(*Client).VerifyWebhook(r)`	webhook 요청 서명을 검증합니다. 성공 시 원시 body가 포함된 `*WebhookEvent`를 반환합니다.

ClientOptions

필드	기본값	설명
`Issuer`	필수	XID 발급자 URL
`Audience`	비어 있음(건너뜀)	예상 JWT aud 클레임
`WebhookSecret`	비어 있음	Webhook HMAC 서명 시크릿
`JWKSCacheTTL`	`1h`	JWKS 로컬 캐시 TTL
`HTTPClient`	기본 10초 타임아웃	JWKS 가져오기용 HTTP 클라이언트

플랫폼 참고 사항

ES256이 기본 알고리즘입니다. RS256은 호환성을 위해 지원됩니다. ES384와 ES512는 아직 구현되지 않았습니다.
JWKS는 {issuer}/jwks에서 가져옵니다. OIDC Discovery 자동 감지는 향후 개선 계획에 있습니다.
Claims는 jwt.RegisteredClaims를 임베드하며 ClientID, Scope, AMR, ACR, OrgID, OrgSlug를 추가합니다.