ZTXBAS Go SDK

Go SDK は標準ライブラリ以外への依存がなく、HMAC の既知テストベクターと JWT の境界条件についてテストされています。

インストール

Go 1.22 以降が必要です。

go get github.com/corezt/ztxbas/sdk-go

インポート

以下のパッケージをインポートします。

import ztxbas "github.com/corezt/ztxbas/sdk-go"

最小構成のエンドツーエンド例

アプリとユーザーを登録し、オリジン・チャレンジを作成して、承認後に claims を取得する一連の流れです。

c, err := ztxbas.New(
    "https://ztxbas.example.com",
    "app_YOUR_APPLICATION_ID",
    "YOUR_HMAC_SECRET_HEX",
)
if err != nil { log.Fatal(err) }

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

_, _ = c.RegisterUser(ctx, ztxbas.RegisterUserRequest{Email: "alice@example.com"})
_, _ = c.RegisterOrigin(ctx, ztxbas.RegisterOriginRequest{
    Origin: "https://app.example.com", DisplayName: "Example App",
})
ch, _ := c.CreateChallenge(ctx, ztxbas.CreateChallengeRequest{
    UserEmail: "alice@example.com", Origin: "https://app.example.com",
})
claims, err := c.PollChallenge(ctx, ch.ChallengeID)
if err != nil { log.Fatal(err) }
fmt.Println(claims.Email, claims.Origin)

定義済みエラーの扱い

errors.Is で定義済みエラーを照合します。errors.As で APIError を取得すると Code、StatusCode、Message を参照できます。

_, err := c.PollChallenge(ctx, id)
switch {
case errors.Is(err, ztxbas.ErrChallengeDenied):    // user tapped Deny
case errors.Is(err, ztxbas.ErrChallengeExpired):   // TTL elapsed
case errors.Is(err, ztxbas.ErrUnregisteredOrigin): // programmer error
}

var apiErr *ztxbas.APIError
if errors.As(err, &apiErr) {
    log.Printf("code=%s status=%d message=%s", apiErr.Code, apiErr.StatusCode, apiErr.Message)
}

JWT 検証のみのモード

バックエンドが ZTXBAS API を直接呼び出さず、フロントエンドから JWT を受け取る場合は、NewVerifier だけを使用できます。

v, _ := ztxbas.NewVerifier(
    "https://ztxbas.example.com/.well-known/jwks.json",
    ztxbas.WithExpectedIssuer("https://ztxbas.example.com"),
)
claims, err := v.Verify(ctx, jwtFromMobile)

リポジトリとリファレンス

• SDK ソース
• Go ドキュメント：github.com/corezt/ztxbas/sdk-go
• クイックスタート