sdk/linux

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

상태

패키지 상태: 구현됨 · 로컬 검증 완료. cargo test가 24개 케이스를 통과합니다. Secret Service D-Bus 저장소와 전체 브라우저 리디렉션 흐름은 데스크톱 Linux에서 gnome-keyring 또는 kwallet이 실행 중이어야 합니다. 실제 IdP 왕복 테스트는 수동 검증 대기 중입니다. 이 페이지는 구현된 동작을 문서화하며, 프로덕션 준비 완료를 의미하지 않습니다.

요구 사항

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

설치

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

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

빠른 시작

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

헤드리스 / CI 사용

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

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

방법	설명
`XidConfigBuilder::new()`	XidConfig 빌더. 필수 필드: issuer, client_id, redirect_uri. 선택 필드: scopes, redirect_port(기본값 51234), http_timeout_secs(기본값 30).
`XidClient::configure(config)`	기본 SecretServiceStorage로 클라이언트를 생성합니다.
`XidClient::configure_with_storage(config, adapter)`	사용자 정의 StorageAdapter(예: InMemoryStorage)로 클라이언트를 생성합니다.
`sign_in(options) async`	xdg-open 브라우저를 열고 redirect_port에서 loopback TCP 리스너를 시작한 후 인증 코드 콜백을 기다려 교환하고, 토큰을 저장한 후 Session을 반환합니다.
`get_session() async`	저장된 세션을 반환하며 만료가 임박한 경우 자동으로 refresh 토큰을 교체합니다.
`get_access_token(options) async`	유효한 액세스 토큰 문자열을 반환하며 필요 시 자동으로 갱신합니다.
`sign_out() async`	/revocation 엔드포인트에서 refresh 토큰을 폐기하고 로컬 저장소를 지웁니다.
`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는 데스크톱 키링 데몬을 통해 저장된 토큰을 암호화합니다. 앱은 암호화 키를 직접 관리하지 않습니다.
Refresh 토큰은 XID 서버에 의해 매번 사용 시 교체됩니다. SDK는 각 갱신 호출 후 새 토큰을 저장합니다.

알려진 제한 사항

JWKS 기반 ID token 검증과 cache refresh는 구현되어 로컬 테스트를 통과했습니다. L4 지원 전에는 desktop Secret Service와 IdP 검증이 필요합니다.
리디렉션 포트는 고정되어 있으며 XID 콘솔에 등록된 redirect_uri와 일치해야 합니다. 동적 포트 무작위화(RFC 8252)는 동적 클라이언트 등록 지원이 필요합니다.
System browser redirect와 Secret Service storage에는 desktop environment 증거가 필요합니다.