---
title: "sdk/rust"
description: "异步 Rust 服务端 SDK，提供 networkless JWT 验证、请求认证和 webhook 签名校验。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/zh-hans/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/rust

## 状态

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

## 安装

添加到 `Cargo.toml`：

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

## 快速开始

```rust
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}"),
}
}
```

## 认证请求

```rust
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

```rust
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 专用变体。

Source: https://xid.dev/zh-hans/sdks/rust/index.mdx