sdk/linux

Linux 桌面 Rust SDK，使用 xdg-open 启动浏览器、loopback TCP 处理授权 callback、PKCE S256 和 freedesktop.org Secret Service token 存储。

状态

包状态为 已实现 · 本地已验证。cargo test 通过 24 个测试用例。Secret Service D-Bus 存储和完整浏览器重定向流程需要在桌面 Linux 系统上运行 gnome-keyring 或 kwallet。IdP 往返验证待人工核实。本页面记录已实现的行为，不代表生产就绪声明。

要求

Rust（stable，2021 版本）
tokio 异步运行时
桌面 Linux 使用 xdg-open（xdg-utils）启动系统浏览器，并需要运行中的 D-Bus 会话及 gnome-keyring 或 kwallet 用于 Secret Service 存储
无界面 / CI 环境：使用 in-memory-storage 特性或直接注入 InMemoryStorage

安装

将 xid-linux 添加到 Cargo.toml：

[dependencies]
xid-linux = { path = "../sdk/linux" }   # local development
# published release:
# xid-linux = "0.1"
tokio = { version = "1", features = ["full"] }

快速开始

use xid_linux::{XidClient, XidConfigBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Build config
    let config = XidConfigBuilder::new()
        .issuer("https://xid.dev")
        .client_id("your_client_id")
        .redirect_uri("http://127.0.0.1:51234/callback")
        .redirect_port(51234)
        .build()?;

    // 2. Create client (default: Secret Service storage)
    let client = XidClient::configure(config)?;

    // 3. Sign in -- opens xdg-open browser, loopback TCP receives callback
    let session = client.sign_in(None).await?;
    println!("user: {}", session.user.sub);

    // 4. Get access token (auto-refresh)
    let token = client.get_access_token(None).await?;

    // 5. Sign out (revokes refresh token + clears storage)
    client.sign_out().await?;
    Ok(())
}

无界面 / CI 用法

当 D-Bus Secret Service 守护进程不可用时，传入 InMemoryStorage 以避免运行时错误：

use xid_linux::{XidClient, XidConfigBuilder};
use xid_linux::storage::InMemoryStorage;
use std::sync::Arc;

let config = XidConfigBuilder::new()
    .issuer("https://xid.dev")
    .client_id("your_client_id")
    .redirect_uri("http://127.0.0.1:51234/callback")
    .build()?;

let client = XidClient::configure_with_storage(config, Arc::new(InMemoryStorage::new()))?;

核心 API

方式	描述
`XidConfigBuilder::new()`	XidConfig 的构建器。必填字段：issuer、client_id、redirect_uri。可选：scopes、redirect_port（默认 51234）、http_timeout_secs（默认 30）。
`XidClient::configure(config)`	使用默认 SecretServiceStorage 创建客户端。
`XidClient::configure_with_storage(config, adapter)`	使用自定义 StorageAdapter（例如 InMemoryStorage）创建客户端。
`sign_in(options) async`	打开 xdg-open 浏览器，在 redirect_port 启动 loopback TCP 监听器，等待授权码 callback，交换它，存储 token，并返回 Session。
`get_session() async`	返回存储的会话，接近过期时自动轮换 refresh token。
`get_access_token(options) async`	返回有效的访问令牌字符串，如需刷新则自动刷新。
`sign_out() async`	在 /revocation 端点吊销 refresh token 并清除本地存储。
`set_token_storage(adapter)`	在构造后替换存储适配器。

存储适配器

适配器	描述
`SecretServiceStorage`	默认。通过 D-Bus 将 token 存储在 freedesktop.org Secret Service（gnome-keyring 或 kwallet）中。需要正在运行的桌面会话。
`InMemoryStorage`	仅限进程内内存。进程退出时 token 丢失。适用于没有 Secret Service 的测试或 CI 环境。

安全

公共客户端——不存储或传输客户端密钥。
仅 PKCE S256。服务器拒绝 plain challenge 方式。
在 loopback callback 上验证 OAuth state 以防 CSRF（RFC 8252 loopback 重定向）。
Secret Service 通过桌面 keyring 守护进程对静态 token 进行加密——应用不直接管理加密密钥。
XID 服务器每次使用都会轮换 refresh token；SDK 在每次刷新调用后保存新 token。

已知限制

基于 JWKS 的 ID token 验签和缓存刷新已实现并完成本地测试。桌面 Secret Service 和真实 IdP 往返验证前仍不具备 L4 支持。
重定向端口固定，必须与在 XID 控制台注册的 redirect_uri 匹配。动态端口随机化（RFC 8252）需要动态客户端注册支持。
系统浏览器重定向和 Secret Service 存储需要桌面环境证据。