sdk/linux

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.

Estado

O status do pacote é Implementado · verificado localmente.cargo test passa 24 casos. O armazenamento D-Bus no Secret Service eo fluxo completo de redirecionamento do navegador requeremgnome-keyring ou kwallet em execução num sistema Linux desktop. A idae volta real com o IdP está pendente de verificação manual. Estapágina documenta o comportamento implementado; não é uma declaraçãode prontidão para produção.

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 xid-linux ao Cargo.toml:

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

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

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

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	Descrição
`XidConfigBuilder::new()`	Builder para XidConfig. Campos obrigatórios: issuer, client_id,redirect_uri. Opcionais: scopes, redirect_port (padrão 51234),http_timeout_secs (padrão 30).
`XidClient::configure(config)`	Cria o cliente com SecretServiceStorage padrão.
`XidClient::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`	Retorna a sessão armazenada com rotação automática do refresh tokense próxima da expiração.
`get_access_token(options) async`	Retorna uma string de token de acesso válida, atualizandoautomaticamente se necessário.
`sign_out() async`	Revoga o refresh token no endpoint /revocation e limpa oarmazenamento local.
`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.
Os refresh tokens são rotacionados a cada uso pelo servidor XID; oSDK salva o novo token após cada chamada de atualização.

Limitações conhecidas

A verificacao de ID token com JWKS e a atualizacao de cache estao implementadas e testadas localmente. Secret Service de desktop e teste IdP real ainda sao necessarios para L4.
A porta de redirecionamento é fixa e deve corresponder aoredirect_uri registrado no console XID. 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.