---
title: "sdk/rust"
description: "네트워크 호출 없는 JWT 검증, 요청 인증, webhook 서명 검증을 지원하는 비동기 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/rust

## 상태

로컬에서 구현 및 검증되었습니다. 실제 IdP 왕복 검증(JWKS 가져오기, 실제 Vonvon 인스턴스에 대한 토큰 서명/검증)은 아직 수행되지 않았으며 프로덕션 사용 전에 완료되어야 합니다.

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

요청 인증은 기본적으로 Bearer만 허용합니다. 애플리케이션 소유 JWT cookie는 정확한 이름을 설정한 경우에만 읽습니다. 불투명한 \_\_Host-vonvon.rt.\* Core cookie는 스캔하거나 로컬에서 검증하지 않습니다. 전체 Cookie header를 redirect가 비활성화된 exact same-origin POST /v1/sessions/token으로 전달해 교환하고 token 필드만 포함한 응답만 허용하세요.

## 설치

`Cargo.toml`에 추가하세요:

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

## 빠른 시작

```rust
use std::sync::Arc;
use vonvon::{VonvonClient, VonvonClientConfig, AuthState};

#[tokio::main]
async fn main() {
let config = VonvonClientConfig::new("https://vonvon.id")
    .with_audience("your-client-id");

let client = Arc::new(VonvonClient::new(config).expect("build client"));

match client.verify_token("eyJ...").await {
    Ok(verified) => {
        println!("user: {}", verified.claims.sub);
        println!("email: {:?}", verified.claims.email);
    }
    Err(e) => eprintln!("invalid token: {e}"),
}
}
```

## 요청 인증

```rust
let state = client.authenticate_request(raw_headers, cookies).await;

match state {
AuthState::Authenticated(token) => {
    println!("user: {}", token.claims.sub);
    // token.claims.has_scope("openid") -> bool
    // token.claims.org_id -> Option<String>
}
AuthState::Unauthenticated => { /* return 401 */ }
AuthState::Invalid(e) => { /* return 401 */ }
}

let token = client.exchange_session_token(
"https://app.example.com/account",
raw_cookie_header,
Some("/v1/sessions/token"),
).await?;
```

## webhook 검증

```rust
use vonvon::WebhookVerifier;

let webhook_secret =
std::env::var("VONVON_WEBHOOK_SECRET").expect("VONVON_WEBHOOK_SECRET is required");
let verifier = WebhookVerifier::new(&webhook_secret).expect("valid secret");

match verifier.verify_from_headers(headers, body) {
Ok(()) => {
    let payload = vonvon::WebhookPayload::from_bytes(body).unwrap();
    println!("event: {}", payload.event_type);
}
Err(e) => { /* return 400 */ }
}
```

## 핵심 API

| 심볼 | 설명 |
| --- | --- |
| `VonvonClientConfig::new(issuer)` | 최소 생성자. 선택적 설정을 위해 빌더 메서드를 체이닝하세요. |
| `.with_audience(aud)` | 예상 audience 클레임을 설정합니다. |
| `.with_session_cookie(name)` | 애플리케이션 소유 JWT cookie 이름을 설정합니다. 기본값은 비활성화입니다. |
| `.with_leeway(seconds)` | exp/nbf에 대한 클럭 편차 허용 범위. |
| `VonvonClient::new(config)` | 기본 reqwest HTTP 클라이언트로 클라이언트를 빌드합니다. |
| `VonvonClient::with_http_client(config, http)` | 사용자 정의 reqwest 클라이언트로 클라이언트를 빌드합니다(테스트에 유용). |
| `client.verify_token(token)` | 토큰 문자열을 검증합니다; `VonvonResult<VerifiedToken>`를 반환합니다. |
| `client.authenticate_request(headers, cookies)` | 원시 헤더와 cookie에서 토큰을 추출하고 검증합니다; `AuthState`를 반환합니다. |
| `WebhookVerifier::new(secret)` | `whsec_<base64>` 또는 일반 base64 시크릿을 허용합니다. |
| `verifier.verify_from_headers(headers, body)` | svix 헤더를 자동으로 추출하고 HMAC-SHA256 서명을 검증합니다. |

## 플랫폼 참고 사항

- tokio 기반 비동기 우선 API. reqwest를 통해 rustls를 사용하며 OpenSSL에 의존하지 않습니다.
- ES256이 기본 알고리즘입니다. RS256이 지원됩니다. PS256 지원이 계획되어 있습니다. ES384/ES512는 아직 구현되지 않았습니다.
- 프레임워크 통합 기능(`axum`, `actix-web`)은 계획되어 있지만 이번 릴리스에는 포함되지 않습니다.
- `VonvonError`는 `thiserror`를 사용하며 `JwtValidation`, `JwksFetch`, `KeyNotFound`, `IssuerMismatch` 및 webhook 전용 변형을 포함한 구조적 오류 변형을 제공합니다.

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