---
title: "sdk/linux"
description: "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."
locale: "es"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/es/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/linux

## 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 vonvon-linux a Cargo.toml:

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

## Inicio rápido

```rust
use vonvon_linux::{VonvonClient, VonvonConfigBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
// 1. Build config. offline_access is rejected until DPoP is implemented.
let config = VonvonConfigBuilder::new()
    .issuer("https://vonvon.id")
    .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 = VonvonClient::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:

```rust
use vonvon_linux::{VonvonClient, VonvonConfigBuilder};
use vonvon_linux::storage::InMemoryStorage;
use std::sync::Arc;

let config = VonvonConfigBuilder::new()
.issuer("https://vonvon.id")
.client_id("your_client_id")
.redirect_uri("http://127.0.0.1:51234/callback")
.build()?;

let client = VonvonClient::configure_with_storage(config, Arc::new(InMemoryStorage::new()))?;
```

## API principal

| Método | Descripción |
| --- | --- |
| `VonvonConfigBuilder::new()` | Constructor para VonvonConfig. Campos obligatorios: issuer, client\_id, redirect\_uri. Opcionales: scopes, redirect\_port (por defecto 51234), http\_timeout\_secs (por defecto 30). |
| `VonvonClient::configure(config)` | Crea el cliente con el SecretServiceStorage predeterminado. |
| `VonvonClient::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 Vonvon. 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.

Source: https://vonvon.id/es/sdks/linux/index.mdx