sdk/linux

SDK Rust para escritorio Linux que usa xdg-open para lanzar el navegador, TCP loopback para el callback de autorización, PKCE S256 y almacenamiento de tokens en el Secret Service de freedesktop.org.

Estado

El estado del paquete es Implementado · verificado localmente. cargo test supera 24 casos. El almacenamiento D-Bus del Secret Service y el flujo completo de redirección del navegador requieren gnome-keyring o kwallet ejecutándose en un sistema Linux de escritorio. La prueba de ida y vuelta real contra un IdP está pendiente de verificación manual. Esta página documenta el comportamiento implementado; no es una declaración de disponibilidad para producción.

Requisitos

Rust (stable, edición 2021)
entorno de ejecución asíncrono tokio
Linux de escritorio con xdg-open (xdg-utils) para lanzar el navegador del sistema y una sesión D-Bus activa con gnome-keyring o kwallet para el Secret Service
Entornos headless / CI: usa la funcionalidad in-memory-storage o inyecta InMemoryStorage directamente

Instalación

Añade xid-linux a Cargo.toml:

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

Inicio rápido

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

Uso headless / CI

Cuando no haya disponible un daemon D-Bus Secret Service, pasa InMemoryStorage para evitar un error en tiempo de ejecución:

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 principal

Método	Descripción
`XidConfigBuilder::new()`	Constructor para XidConfig. Campos obligatorios: issuer, client_id, redirect_uri. Opcionales: scopes, redirect_port (por defecto 51234), http_timeout_secs (por defecto 30).
`XidClient::configure(config)`	Crea el cliente con el SecretServiceStorage predeterminado.
`XidClient::configure_with_storage(config, adapter)`	Crea el cliente con un StorageAdapter personalizado (p. ej., InMemoryStorage).
`sign_in(options) async`	Abre el navegador xdg-open, inicia el listener TCP loopback en redirect_port, espera el callback del código de autorización, lo intercambia, almacena los tokens y devuelve una Session.
`get_session() async`	Devuelve la sesión almacenada con rotación automática del refresh token si está próxima a expirar.
`get_access_token(options) async`	Devuelve una cadena de access token válida, renovándola automáticamente si es necesario.
`sign_out() async`	Revoca el refresh token en el endpoint /revocation y limpia el almacenamiento local.
`set_token_storage(adapter)`	Reemplaza el adaptador de almacenamiento tras la construcción.

Adaptadores de almacenamiento

Adaptador	Descripción
`SecretServiceStorage`	Por defecto. Almacena tokens en el Secret Service de freedesktop.org (gnome-keyring o kwallet) vía D-Bus. Requiere una sesión de escritorio activa.
`InMemoryStorage`	Solo memoria en proceso. Los tokens se pierden al salir del proceso. Úsalo para entornos de prueba o CI sin Secret Service.

Seguridad

Cliente público: no se almacena ni transmite ningún secreto de cliente.
Solo PKCE S256. El servidor rechaza el método plain de challenge.
Estado OAuth validado en el callback loopback para prevenir CSRF (redirección loopback RFC 8252).
El Secret Service cifra los tokens en reposo a través del daemon del llavero del escritorio: la app no gestiona las claves de cifrado directamente.
El servidor XID rota los refresh tokens en cada uso; el SDK guarda el nuevo token después de cada llamada de renovación.

Limitaciones conocidas

La verificación de ID token basada en JWKS y la actualización de caché están implementadas y probadas localmente. Secret Service de escritorio y una prueba real de IdP siguen siendo necesarios para L4.
El puerto de redirección es fijo y debe coincidir con el redirect_uri registrado en la consola XID. La aleatorización dinámica de puertos (RFC 8252) requiere soporte de registro dinámico de clientes.
La redirección del navegador del sistema y el almacenamiento Secret Service requieren evidencia de entorno de escritorio.