---
title: "sdk/linux"
description: "SDK Rust para Linux desktop usando xdg-open para abertura donavegador, TCP loopback para o callback de autorização, PKCE S256 earmazenamento de tokens no Secret Service do freedesktop.org."
locale: "pt-BR"
---

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

# sdk/linux

## Estado

O status do package é **Implementado e verificado localmente**. A suíte de testes unitários Rust passa. O armazenamento do Secret Service via D-Bus, xdg-open, o callback de loopback completo e um ciclo completo com um IdP real ainda exigem um ambiente de integração Linux para desktop. Esta página documenta o comportamento implementado; não é uma declaração de prontidão para produção.

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

## Requisitos

- Rust (stable, edição 2021)
- runtime assíncrono tokio
- Linux desktop com xdg-open (xdg-utils) para abrir o navegador dosistema e uma sessão D-Bus em execução com gnome-keyring ou kwalletpara armazenamento no Secret Service
- Ambientes headless / CI: use o recurso in-memory-storage ou injeteInMemoryStorage diretamente

## Instalação

Adicione vonvon-linux ao Cargo.toml:

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

## Início 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

Quando nenhum daemon D-Bus Secret Service estiver disponível, passeInMemoryStorage para evitar um erro em tempo de execução:

```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 | Descrição |
| --- | --- |
| `VonvonConfigBuilder::new()` | Builder para VonvonConfig. Campos obrigatórios: issuer, client\_id,redirect\_uri. Opcionais: scopes, redirect\_port (padrão 51234),http\_timeout\_secs (padrão 30). |
| `VonvonClient::configure(config)` | Cria o cliente com SecretServiceStorage padrão. |
| `VonvonClient::configure_with_storage(config, adapter)` | Cria o cliente com um StorageAdapter personalizado (ex.:InMemoryStorage). |
| `sign_in(options) async` | Abre o navegador via xdg-open, inicia um listener TCP loopback emredirect\_port, aguarda o callback com o código de autorização,realiza a troca, armazena os tokens e retorna uma Session. |
| `get_session() async` | Retornar a sessão armazenada atual não expirada; a expiração limpa o estado local do token e retorna SessionExpired. |
| `get_access_token(options) async` | Retornar o token de acesso atual não expirado; a expiração ou force\_refresh limpa o estado local do token e retorna SessionExpired. |
| `sign_out() async` | Limpar o armazenamento local de tokens e da sessão de convidado; nenhuma solicitação de revogação é enviada. |
| `set_token_storage(adapter)` | Substitui o adaptador de armazenamento após a construção. |

## Adaptadores de armazenamento

| Adaptador | Descrição |
| --- | --- |
| `SecretServiceStorage` | Padrão. Armazena tokens no Secret Service freedesktop.org(gnome-keyring ou kwallet) via D-Bus. Requer uma sessão de desktop emexecução. |
| `InMemoryStorage` | Apenas memória em processo. Os tokens são perdidos ao sair doprocesso. Use para ambientes de teste ou CI sem um Secret Service. |

## Segurança

- Cliente público — nenhum segredo de cliente armazenado ou transmitido.
- Apenas PKCE S256. O servidor rejeita o método de desafio plain.
- State OAuth validado no callback de loopback para prevenir CSRF(redirecionamento loopback RFC 8252).
- O Secret Service criptografa os tokens em repouso via daemon dekeyring do desktop — o aplicativo não gerencia chaves de criptografiadiretamente.
- O SDK rejeita offline\_access até que DPoP seja implementado; campos refresh\_token inesperados na resposta não são persistidos.

## Limitações conhecidas

- A verificação de token de ID com suporte de JWKS, a validação de nonce e a renovação do cache JWKS estão implementadas e testadas localmente. Um Secret Service de desktop e um ciclo completo com um IdP real ainda são necessários antes do suporte L4.
- A porta de redirecionamento é fixa e deve corresponder aoredirect\_uri registrado no console Vonvon. A randomização dinâmica deporta (RFC 8252) requer suporte a registro dinâmico de cliente.
- O redirecionamento do navegador do sistema e o armazenamento Secret Service exigem evidencia de ambiente desktop.

Source: https://vonvon.id/pt-br/sdks/linux/index.mdx