sdk/linux

Rust-SDK für Linux-Desktop mit xdg-open für den Browser-Start,Loopback-TCP für den Autorisierungs-Callback, PKCE S256 undfreedesktop.org-Secret-Service-Token-Speicher.

Zustand

Paketstatus: Implementiert · lokal verifiziert. cargo test besteht24 Fälle. Secret-Service-D-Bus-Speicher und der vollständigeBrowser-Redirect-Flow erfordern gnome-keyring oder kwallet auf einemDesktop-Linux-System. Der echte IdP-Round-Trip steht manuell aus. DieseSeite dokumentiert implementiertes Verhalten und stellt keinenProduktionsbereitschaftsnachweis dar.

Anforderungen

Rust (stable, Edition 2021)
Asynchrone tokio-Laufzeitumgebung
Desktop-Linux mit xdg-open (xdg-utils) für den Systembrowserstart und einelaufende D-Bus-Sitzung mit gnome-keyring oder kwallet fürSecret-Service-Speicherung
Headless-/CI-Umgebungen: das in-memory-storage-Feature verwenden oderInMemoryStorage direkt injizieren

Installation

xid-linux zu Cargo.toml hinzufügen:

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

Schnellstart

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(())
}

Headless-/CI-Verwendung

Wenn kein D-Bus-Secret-Service-Daemon verfügbar ist, InMemoryStorageübergeben, um einen Laufzeitfehler zu vermeiden:

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

Kern-API

Methode	Beschreibung
`XidConfigBuilder::new()`	Builder für XidConfig. Pflichtfelder: issuer, client_id, redirect_uri.Optional: scopes, redirect_port (Standard 51234), http_timeout_secs(Standard 30).
`XidClient::configure(config)`	Client mit dem Standard-SecretServiceStorage erstellen.
`XidClient::configure_with_storage(config, adapter)`	Client mit einem benutzerdefinierten StorageAdapter (z. B.InMemoryStorage) erstellen.
`sign_in(options) async`	xdg-open-Browser öffnen, Loopback-TCP-Listener auf redirect_port starten,auf den Autorisierungscode-Callback warten, ihn eintauschen, Tokensspeichern und eine Session zurückgeben.
`get_session() async`	Die gespeicherte Sitzung zurückgeben, mit automatischerRefresh-Token-Rotation bei nahendem Ablauf.
`get_access_token(options) async`	Einen gültigen Access-Token-String zurückgeben, bei Bedarf automatischerneuern.
`sign_out() async`	Das Refresh-Token am /revocation-Endpunkt widerrufen und lokalen Speicherleeren.
`set_token_storage(adapter)`	Den Speicher-Adapter nach der Konstruktion ersetzen.

Speicher-Adapter

Adapter	Beschreibung
`SecretServiceStorage`	Standard. Speichert Tokens im freedesktop.org Secret Service(gnome-keyring oder kwallet) über D-Bus. Erfordert eine laufendeDesktop-Sitzung.
`InMemoryStorage`	Nur In-Process-Speicher. Tokens gehen beim Beenden des Prozesses verloren.Für Tests oder CI-Umgebungen ohne Secret Service verwenden.

Sicherheit

Öffentlicher Client — kein Client-Secret gespeichert oder übertragen.
Nur PKCE S256. Der Server lehnt die Plain-Challenge-Methode ab.
OAuth-State wird im Loopback-Callback zur CSRF-Prävention validiert (RFC8252 Loopback-Redirect).
Der Secret Service verschlüsselt Tokens im Ruhezustand über denDesktop-Keyring-Daemon — die App verwaltet Verschlüsselungsschlüssel nichtdirekt.
Refresh-Tokens werden bei jeder Verwendung vom XID-Server rotiert; das SDKspeichert nach jedem Refresh-Aufruf den neuen Token.

Bekannte Einschränkungen

JWKS-gestützte ID-Token-Prüfung und Cache-Aktualisierung sind implementiert und lokal getestet. Für L4 sind noch ein Desktop-Secret-Service und ein echter IdP-Test erforderlich.
Der Redirect-Port ist fest und muss mit der in der XID-Konsoleregistrierten redirect_uri übereinstimmen. Dynamische Port-Zufälligkeit(RFC 8252) erfordert Unterstützung für dynamische Client-Registrierung.
Systembrowser-Weiterleitung und Secret-Service-Speicher benötigen Desktop-Umgebungsevidenz.