---
title: "sdk/linux"
description: "브라우저 실행에 xdg-open, 인증 콜백에 loopback TCP, PKCE S256, freedesktop.org Secret Service 토큰 저장소를 사용하는 Linux 데스크톱용 Rust SDK."
locale: "ko"
---

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

# sdk/linux

## 상태

Package 상태는 **구현 및 로컬 검증 완료**입니다. Rust 단위 테스트 suite가 통과했습니다. Secret Service D-Bus storage, xdg-open, 전체 loopback callback 및 실제 IdP round-trip을 검증하려면 여전히 desktop Linux integration environment가 필요합니다. 이 페이지는 구현된 동작을 설명하며 production-ready 상태임을 주장하지 않습니다.

Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.

## 요구 사항

- Rust(stable, 2021 에디션)
- tokio 비동기 런타임
- 시스템 브라우저 실행을 위한 xdg-open(xdg-utils)과 Secret Service 저장소용 gnome-keyring 또는 kwallet이 있는 D-Bus 세션이 실행 중인 데스크톱 Linux
- 헤드리스 / CI 환경: in-memory-storage 기능을 사용하거나 InMemoryStorage를 직접 주입하세요

## 설치

Cargo.toml에 vonvon-linux를 추가하세요:

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

## 빠른 시작

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

## 헤드리스 / CI 사용

D-Bus Secret Service 데몬을 사용할 수 없는 경우 런타임 오류를 방지하려면 InMemoryStorage를 전달하세요:

```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

| 방법 | 설명 |
| --- | --- |
| `VonvonConfigBuilder::new()` | VonvonConfig 빌더. 필수 필드: issuer, client\_id, redirect\_uri. 선택 필드: scopes, redirect\_port(기본값 51234), http\_timeout\_secs(기본값 30). |
| `VonvonClient::configure(config)` | 기본 SecretServiceStorage로 클라이언트를 생성합니다. |
| `VonvonClient::configure_with_storage(config, adapter)` | 사용자 정의 StorageAdapter(예: InMemoryStorage)로 클라이언트를 생성합니다. |
| `sign_in(options) async` | xdg-open 브라우저를 열고 redirect\_port에서 loopback TCP 리스너를 시작한 후 인증 코드 콜백을 기다려 교환하고, 토큰을 저장한 후 Session을 반환합니다. |
| `get_session() async` | 현재 저장되어 있고 만료되지 않은 session을 반환합니다. 만료되면 로컬 token state를 지우고 SessionExpired를 반환합니다. |
| `get_access_token(options) async` | 현재 만료되지 않은 access token을 반환합니다. 만료되었거나 force\_refresh가 지정되면 로컬 token state를 지우고 SessionExpired를 반환합니다. |
| `sign_out() async` | 로컬 token과 guest session storage를 지웁니다. revoke request는 전송하지 않습니다. |
| `set_token_storage(adapter)` | 생성 후 저장소 어댑터를 교체합니다. |

## 저장소 어댑터

| 어댑터 | 설명 |
| --- | --- |
| `SecretServiceStorage` | 기본값. D-Bus를 통해 freedesktop.org Secret Service(gnome-keyring 또는 kwallet)에 토큰을 저장합니다. 실행 중인 데스크톱 세션이 필요합니다. |
| `InMemoryStorage` | 프로세스 메모리만 사용합니다. 프로세스 종료 시 토큰이 사라집니다. Secret Service가 없는 테스트 또는 CI 환경에 사용하세요. |

## 보안

- 공개 클라이언트 — client secret이 저장되거나 전송되지 않습니다.
- PKCE S256만 사용합니다. 서버는 plain challenge 방식을 거부합니다.
- CSRF를 방지하기 위해 loopback 콜백에서 OAuth state가 검증됩니다(RFC 8252 loopback 리디렉션).
- Secret Service는 데스크톱 키링 데몬을 통해 저장된 토큰을 암호화합니다. 앱은 암호화 키를 직접 관리하지 않습니다.
- DPoP가 구현될 때까지 SDK는 offline\_access를 거부합니다. 예기치 않은 refresh\_token response fields는 영속화하지 않습니다.

## 알려진 제한 사항

- JWKS 기반 ID token 검증, nonce 검증, JWKS cache renewal이 구현되어 로컬에서 테스트되었습니다. L4 지원을 선언하려면 desktop Secret Service와 실제 IdP round-trip을 더 검증해야 합니다.
- 리디렉션 포트는 고정되어 있으며 Vonvon 콘솔에 등록된 redirect\_uri와 일치해야 합니다. 동적 포트 무작위화(RFC 8252)는 동적 클라이언트 등록 지원이 필요합니다.
- System browser redirect와 Secret Service storage에는 desktop environment 증거가 필요합니다.

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