sdk/linux

Rust SDK for Linux desktop using xdg-open for browser launch, loopback TCP for the authorization callback, PKCE S256, and freedesktop.org Secret Service token storage.

Status

Package status is Implemented and verified locally. The Rust unit-test suite passes. Secret Service D-Bus storage, xdg-open, the complete loopback callback, and a real IdP round-trip still require a desktop Linux integration environment. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Requirements

Rust (stable, 2021 edition)
tokio async runtime
Desktop Linux with xdg-open (xdg-utils) for system browser launch and a running D-Bus session with gnome-keyring or kwallet for Secret Service storage
Headless / CI environments: use the in-memory-storage feature or inject InMemoryStorage directly

Installation

Add xid-linux to Cargo.toml:

[dependencies]
xid-linux = { path = "../xid/sdk/linux" }
tokio = { version = "1", features = ["full"] }

Quick start

use xid_linux::{XidClient, XidConfigBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Build config. offline_access is rejected until DPoP is implemented.
    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. xdg-open launches the browser and loopback TCP receives the callback.
    let session = client.sign_in(None).await?;
    println!("user: {}", session.user.sub);

    // 4. Get the current unexpired access token. Expiry returns SessionExpired.
    let token = client.get_access_token(None).await?;

    // 5. Clear local token and guest state. No revoke request is sent.
    client.sign_out().await?;
    Ok(())
}

Headless / CI usage

When no D-Bus Secret Service daemon is available, pass InMemoryStorage to avoid a runtime error:

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()))?;

Core API

Method	Description
`XidConfigBuilder::new()`	Builder for XidConfig. Required fields: issuer, client_id, redirect_uri. Optional: scopes, redirect_port (default 51234), http_timeout_secs (default 30).
`XidClient::configure(config)`	Create client with default SecretServiceStorage.
`XidClient::configure_with_storage(config, adapter)`	Create client with a custom StorageAdapter (e.g. InMemoryStorage).
`sign_in(options) async`	Open xdg-open browser, start loopback TCP listener on redirect_port, wait for the authorization code callback, exchange it, store tokens, and return a Session.
`get_session() async`	Return the current unexpired stored session; expiry clears local token state and returns SessionExpired.
`get_access_token(options) async`	Return the current unexpired access token; expiry or force_refresh clears local token state and returns SessionExpired.
`sign_out() async`	Clear local token and guest session storage; no revoke request is sent.
`set_token_storage(adapter)`	Replace the storage adapter after construction.

Storage adapters

Adapter	Description
`SecretServiceStorage`	Default. Stores tokens in the freedesktop.org Secret Service (gnome-keyring or kwallet) via D-Bus. Requires a running desktop session.
`InMemoryStorage`	In-process memory only. Tokens are lost on process exit. Use for testing or CI environments without a Secret Service.

Security

Public client — no client secret stored or transmitted.
PKCE S256 only. Server rejects plain challenge method.
OAuth state validated on the loopback callback to prevent CSRF (RFC 8252 loopback redirect).
Secret Service encrypts tokens at rest via the desktop keyring daemon — the app does not manage encryption keys directly.
The SDK rejects offline_access until DPoP is implemented; unexpected refresh_token response fields are not persisted.

Known limitations

JWKS-backed ID token verification, nonce validation, and JWKS cache renewal are implemented and locally tested. A desktop Secret Service and real IdP round-trip are still required before L4 support.
The redirect port is fixed and must match the redirect_uri registered in the XID console. Dynamic port randomization (RFC 8252) requires dynamic client registration support.
System browser redirect and Secret Service storage require desktop environment evidence.