sdk/go | XID

ネットワークレス JWT 検証、リクエスト認証、webhook 署名検証用の Go サーバー SDK。

状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 XID インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な __Host-xid.rt.* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

インストール

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

クイックスタート

アプリケーション起動時に Client を 1 つ作成してリクエスト間で再利用します。クライアントは設定可能な 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)

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

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 リクエストの署名を検証します。成功時は生のボディを含む `*WebhookEvent` を返します。

ClientOptions

フィールド	デフォルト	説明
`Issuer`	必須	XID 発行者 URL
`Audience`	（スキップ）	expected 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 を追加します。