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.

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

L’authentification des requêtes accepte uniquement Bearer par défaut. Un cookie JWT détenu par l’application n’est lu que lorsque son nom exact est configuré. Le cookie Core opaque __Host-xid.rt.* n’est jamais recherché ni vérifié localement ; échangez-le en transférant le header Cookie complet vers le POST /v1/sessions/token de même origine exacte, avec les redirections désactivées, et n’acceptez qu’une réponse contenant uniquement le champ token.

Installer

Ajoutez dans Cargo.toml :

[dependencies]
xid = { path = "../sdk/rust" }
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 */ }
}

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

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)`	Configurez un nom de cookie JWT détenu par l’application ; désactivé par défaut.
`.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.