sdk/rust | XID

Asynchrones Rust-Server-SDK für netzwerklose JWT-Prüfung,Anfrage-Authentifizierung und Webhook-Signaturvalidierung.

Zustand

Implementiert und lokal verifiziert. Die echteIdP-Round-Trip-Verifizierung (JWKS-Abruf, Token-Signierung/Prüfung gegeneine Live-XID-Instanz) wurde noch nicht durchgeführt und muss vor demProduktionseinsatz abgeschlossen werden.

Registry-Status: UNPUBLISHED. Installieren Sie dieses SDK nur aus einem Checkout des Repository-Quellcodes; verwenden Sie keine externe Paket-Registry.

Die Anfrageauthentifizierung akzeptiert standardmäßig nur Bearer. Ein anwendungseigenes JWT-Cookie wird nur gelesen, wenn sein exakter Name konfiguriert ist. Das opake Core-Cookie __Host-xid.rt.* wird niemals durchsucht oder lokal verifiziert; tauschen Sie es aus, indem Sie den vollständigen Cookie-Header ohne Weiterleitungen an den exakt gleichursprünglichen Endpunkt POST /v1/sessions/token weiterleiten, und akzeptieren Sie nur eine Antwort, die ausschließlich das Feld token enthält.

Installieren

Zu Cargo.toml hinzufügen:

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

Schnellstart

use std::sync::Arc;
use xid::{XidClient, XidClientConfig, AuthState};

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

    let client = Arc::new(XidClient::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}"),
    }
}

Anfrage authentifizieren

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 prüfen

use xid::WebhookVerifier;

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

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

Kern-API

Symbol	Beschreibung
`XidClientConfig::new(issuer)`	Minimalkonstruktor. Builder-Methoden für optionale Einstellungenverketten.
`.with_audience(aud)`	Erwarteten Audience-Claim festlegen.
`.with_session_cookie(name)`	Konfigurieren Sie einen anwendungseigenen JWT-Cookie-Namen; standardmäßig deaktiviert.
`.with_leeway(seconds)`	Taktversatztoleranz für exp/nbf.
`XidClient::new(config)`	Client mit dem Standard-reqwest-HTTP-Client erstellen.
`XidClient::with_http_client(config, http)`	Client mit einem benutzerdefinierten reqwest-Client erstellen (nützlichfür Tests).
`client.verify_token(token)`	Token-String prüfen; gibt `XidResult<VerifiedToken>` zurück.
`client.authenticate_request(headers, cookies)`	Token aus rohen Headern und Cookies extrahieren und prüfen; gibt`AuthState` zurück.
`WebhookVerifier::new(secret)`	Akzeptiert `whsec_<base64>` oder ein rohes Base64-Secret.
`verifier.verify_from_headers(headers, body)`	Svix-Header automatisch extrahieren und HMAC-SHA256-Signatur validieren.

Plattformhinweise

Async-first-API auf tokio-Basis. Verwendet rustls (keineOpenSSL-Abhängigkeit) über reqwest.
ES256 ist der primäre Algorithmus; RS256 wird unterstützt.PS256-Unterstützung ist geplant. ES384/ES512 sind noch nichtimplementiert.
Framework-Integrationsfunktionen (axum, actix-web) sindgeplant, aber in dieser Version nicht enthalten.
XidError verwendet thiserror für strukturierteFehlervarianten, darunter JwtValidation, JwksFetch,KeyNotFound, IssuerMismatch und webhook-spezifischeVarianten.