sdk/rust | XID

SDK serveur Rust asynchrone pour la vérification JWT sans réseau,l'authentification des requêtes et la validation des signatures webhook.

Statut

Implémenté et vérifié localement. La vérification aller-retour avec unvrai IdP (récupération JWKS, signature/vérification de jeton contre uneinstance XID active) n’a pas encore été effectuée et doit être complétéeavant toute utilisation en production.

Installer

Ajoutez dans Cargo.toml :

[dependencies]
xid = "0.1"
tokio = { version = "1", features = ["full"] }

Démarrage rapide

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}"),
    }
}

Authentifier une requête

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 */ }
}

Vérifier le webhook

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 */ }
}

API principale

Symbole	Description
`XidClientConfig::new(issuer)`	Constructeur minimal. Enchaînez les méthodes du constructeur pour lesparamètres optionnels.
`.with_audience(aud)`	Définir la revendication d’audience attendue.
`.with_session_cookie(name)`	Remplacer le nom du cookie de session (par défaut `__session`).
`.with_leeway(seconds)`	Tolérance au décalage d’horloge pour exp/nbf.
`XidClient::new(config)`	Construire le client avec le client HTTP reqwest par défaut.
`XidClient::with_http_client(config, http)`	Construire le client avec un client reqwest personnalisé (utile pour lestests).
`client.verify_token(token)`	Vérifier la chaîne de jeton ; retourne `XidResult<VerifiedToken>`.
`client.authenticate_request(headers, cookies)`	Extraire et vérifier le jeton depuis les en-têtes et cookies bruts ;retourne `AuthState`.
`WebhookVerifier::new(secret)`	Accepte un secret `whsec_<base64>` ou base64 brut.
`verifier.verify_from_headers(headers, body)`	Extraire automatiquement les en-têtes svix et valider la signatureHMAC-SHA256.

Notes de plateforme

API asynchrone construite sur tokio. Utilise rustls (sans dépendanceOpenSSL) via reqwest.
ES256 est l’algorithme principal ; RS256 est pris en charge. La prise encharge de PS256 est prévue. ES384/ES512 ne sont pas encore implémentés.
Les fonctionnalités d’intégration de framework (axum,actix-web) sont prévues mais ne sont pas incluses dans cetteversion.
XidError utilise thiserror pour les variantes d’erreursstructurées incluant JwtValidation, JwksFetch,KeyNotFound, IssuerMismatch et des variantes spécifiques auxwebhooks.