sdk/rust | XID

非同期 Rust サーバー SDK。ネットワークレス JWT 検証、リクエスト認証、webhook 署名検証をサポートします。

状態

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

インストール

Cargo.toml に追加します：

[dependencies]
xid = "0.1"
tokio = { version = "1", features = ["full"] }

クイックスタート

use std::sync::Arc;
use xid::{XidClient, XidClientConfig, AuthState};

#[tokio::main]
async fn main() {
    let config = XidClientConfig::new("https://xid.dev")
        .with_audience("your-client-id");

    let client = Arc::new(XidClient::new(config).expect("build client"));

    match client.verify_token("eyJ...").await {
        Ok(verified) => {
            println!("user: {}", verified.claims.sub);
            println!("email: {:?}", verified.claims.email);
        }
        Err(e) => eprintln!("invalid token: {e}"),
    }
}

リクエストを認証します

let state = client.authenticate_request(raw_headers, cookies).await;

match state {
    AuthState::Authenticated(token) => {
        println!("user: {}", token.claims.sub);
        // token.claims.has_scope("openid") -> bool
        // token.claims.org_id -> Option<String>
    }
    AuthState::Unauthenticated => { /* return 401 */ }
    AuthState::Invalid(e) => { /* return 401 */ }
}

webhook を検証

use xid::WebhookVerifier;

let webhook_secret =
    std::env::var("XID_WEBHOOK_SECRET").expect("XID_WEBHOOK_SECRET is required");
let verifier = WebhookVerifier::new(&webhook_secret).expect("valid secret");

match verifier.verify_from_headers(headers, body) {
    Ok(()) => {
        let payload = xid::WebhookPayload::from_bytes(body).unwrap();
        println!("event: {}", payload.event_type);
    }
    Err(e) => { /* return 400 */ }
}

コア API

シンボル	説明
`XidClientConfig::new(issuer)`	最小コンストラクター。オプション設定はビルダーメソッドをチェーンします。
`.with_audience(aud)`	期待される audience クレームを設定します。
`.with_session_cookie(name)`	セッション Cookie 名を上書きします（デフォルト `__session`）。
`.with_leeway(seconds)`	exp/nbf のクロックスキュー許容値。
`XidClient::new(config)`	デフォルト reqwest HTTP クライアントでビルドします。
`XidClient::with_http_client(config, http)`	カスタム reqwest クライアントでビルドします（テストに便利）。
`client.verify_token(token)`	トークン文字列を検証し、`XidResult<VerifiedToken>` を返します。
`client.authenticate_request(headers, cookies)`	生のヘッダーと Cookie からトークンを取得して検証します。`AuthState` を返します。
`WebhookVerifier::new(secret)`	`whsec_<base64>` または生 base64 シークレットを受け入れます。
`verifier.verify_from_headers(headers, body)`	svix ヘッダーを自動的に取得して HMAC-SHA256 署名を検証します。

プラットフォームの注意事項

tokio 上に構築された非同期ファースト API。reqwest 経由で rustls を使用します（OpenSSL 依存なし）。
ES256 が主要アルゴリズムです。RS256 はサポートされています。PS256 のサポートは計画中です。ES384/ES512 はまだ実装されていません。
フレームワーク統合機能（axum、actix-web）は計画中ですが、このリリースには含まれていません。
XidError は thiserror を使って JwtValidation、JwksFetch、KeyNotFound、IssuerMismatch、webhook 固有のバリアントを含む構造化エラーバリアントを定義します。