sdk/linux

SDK Rust pour bureau Linux utilisant xdg-open pour lancer le navigateur,TCP loopback pour le callback d'autorisation, PKCE S256 et le stockage dejetons Secret Service de freedesktop.org.

Statut

Le statut du package est Implémenté · vérifié localement. cargotest passe 24 cas. Le stockage D-Bus Secret Service et le flux deredirection complet via navigateur nécessitent gnome-keyring ou kwalletsur un système Linux bureau. L’aller-retour réel avec un IdP est enattente de vérification manuelle. Cette page documente le comportementimplémenté ; ce n’est pas une affirmation de disponibilité en production.

Prérequis

Rust (stable, édition 2021)
runtime async tokio
Linux bureau avec xdg-open (xdg-utils) pour lancer le navigateur systèmeet une session D-Bus active avec gnome-keyring ou kwallet pour le stockageSecret Service
Environnements headless / CI : utilisez la fonctionnalitéin-memory-storage ou injectez InMemoryStorage directement

Installation

Ajoutez xid-linux dans Cargo.toml :

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

Démarrage rapide

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

Utilisation headless / CI

Quand aucun démon D-Bus Secret Service n’est disponible, passezInMemoryStorage pour éviter une erreur d’exécution :

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 principale

Méthode	Description
`XidConfigBuilder::new()`	Constructeur pour XidConfig. Champs requis : issuer, client_id,redirect_uri. Optionnels : scopes, redirect_port (par défaut 51234),http_timeout_secs (par défaut 30).
`XidClient::configure(config)`	Créer le client avec le SecretServiceStorage par défaut.
`XidClient::configure_with_storage(config, adapter)`	Créer le client avec un StorageAdapter personnalisé (p. ex.InMemoryStorage).
`sign_in(options) async`	Ouvrir le navigateur via xdg-open, démarrer l’écouteur TCP loopback surredirect_port, attendre le callback de code d’autorisation, l’échanger,stocker les jetons et retourner une Session.
`get_session() async`	Retourner la session stockée avec rotation automatique du jetond’actualisation si proche de l’expiration.
`get_access_token(options) async`	Retourner une chaîne de jeton d’accès valide, en rafraîchissantautomatiquement si nécessaire.
`sign_out() async`	Révoquer le jeton d’actualisation au point de terminaison /revocation etvider le stockage local.
`set_token_storage(adapter)`	Remplacer l’adaptateur de stockage après la construction.

Adaptateurs de stockage

Adaptateur	Description
`SecretServiceStorage`	Par défaut. Stocke les jetons dans le Secret Service freedesktop.org(gnome-keyring ou kwallet) via D-Bus. Nécessite une session bureau active.
`InMemoryStorage`	Mémoire en cours de processus uniquement. Les jetons sont perdus à la findu processus. À utiliser pour les tests ou les environnements CI sansSecret Service.

Sécurité

Client public — aucun secret client stocké ni transmis.
PKCE S256 uniquement. Le serveur rejette la méthode plain challenge.
État OAuth validé sur le callback loopback pour prévenir le CSRF(redirection loopback RFC 8252).
Secret Service chiffre les jetons au repos via le démon de trousseau dubureau — l’application ne gère pas directement les clés de chiffrement.
Les jetons d’actualisation sont tournés à chaque utilisation par leserveur XID ; le SDK sauvegarde le nouveau jeton après chaque appel derafraîchissement.

Limites connues

La verification du jeton ID par JWKS et le rafraichissement du cache sont implementes et testes localement. Secret Service de bureau et un test IdP reel restent requis avant L4.
Le port de redirection est fixe et doit correspondre au redirect_urienregistré dans la console XID. La randomisation dynamique du port (RFC8252) nécessite la prise en charge de l’enregistrement dynamique declient.
La redirection du navigateur systeme et le stockage Secret Service necessitent une preuve d environnement de bureau.