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 y verificado localmente. La suite de pruebas unitarias de Rust se ejecuta correctamente. El almacenamiento de Secret Service mediante D-Bus, xdg-open, el callback de loopback completo y un recorrido de ida y vuelta con un IdP real aún requieren un entorno de integración de Linux de escritorio. Esta página documenta el comportamiento implementado; no afirma que esté listo para producción.

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

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 = "../xid/sdk/linux" }
tokio = { version = "1", features = ["full"] }

Inicio rápido

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

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 actual no caducada; la caducidad borra el estado local del token y devuelve SessionExpired.
`get_access_token(options) async`	Devuelve el token de acceso actual no caducado; la caducidad o force_refresh borra el estado local del token y devuelve SessionExpired.
`sign_out() async`	Borra el almacenamiento local de tokens y sesiones de invitado; no se envía ninguna solicitud de revocación.
`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 SDK rechaza offline_access hasta que se implemente DPoP; los campos de respuesta refresh_token inesperados no se conservan.

Limitaciones conocidas

La verificación de tokens de ID respaldada por JWKS, la validación del nonce y la renovación de la caché JWKS están implementadas y probadas localmente. Aún se requieren un Secret Service de escritorio y un recorrido de ida y vuelta con un IdP real antes de ofrecer compatibilidad 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.