sdk/rust | XID

异步 Rust 服务端 SDK，提供 networkless JWT 验证、请求认证和 webhook 签名校验。

状态

已在本地实现并验证。针对真实 XID 实例的 IdP 往返验证（JWKS 获取、token 签名/验证）尚未执行，生产使用前必须完成。

安装

添加到 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 claim。
`.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)`	验证 token 字符串；返回 `XidResult<VerifiedToken>`。
`client.authenticate_request(headers, cookies)`	从原始请求头和 cookie 中提取并验证 token；返回 `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 专用变体。