sdk/rust | XID

SDK de servidor Rust asíncrono para verificación JWT sin llamadas de red, autenticación de solicitudes y validación de firma de webhook.

Estado

Implementado y verificado localmente. La verificación de ida y vuelta contra un IdP real (obtención de JWKS, firma/verificación de tokens contra una instancia XID en producción) aún no se ha realizado y debe completarse antes del uso en producción.

Instalación

Añade a Cargo.toml:

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

Inicio rápido

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

Autenticar una solicitud

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

Verificar 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 principal

Símbolo	Descripción
`XidClientConfig::new(issuer)`	Constructor mínimo. Encadena métodos builder para configuración opcional.
`.with_audience(aud)`	Establece el claim de audiencia esperado.
`.with_session_cookie(name)`	Anula el nombre de la cookie de sesión (por defecto `__session`).
`.with_leeway(seconds)`	Tolerancia de desfase de reloj para exp/nbf.
`XidClient::new(config)`	Construye el cliente con el cliente HTTP reqwest predeterminado.
`XidClient::with_http_client(config, http)`	Construye el cliente con un cliente reqwest personalizado (útil para pruebas).
`client.verify_token(token)`	Verifica una cadena de token; devuelve `XidResult<VerifiedToken>`.
`client.authenticate_request(headers, cookies)`	Extrae y verifica el token de encabezados y cookies sin procesar; devuelve `AuthState`.
`WebhookVerifier::new(secret)`	Acepta `whsec_<base64>` o secreto base64 sin prefijo.
`verifier.verify_from_headers(headers, body)`	Extrae automáticamente los encabezados svix y valida la firma HMAC-SHA256.

Notas de plataforma

API async-first construida sobre tokio. Usa rustls (sin dependencia de OpenSSL) a través de reqwest.
ES256 es el algoritmo principal; RS256 está soportado. El soporte para PS256 está planificado. ES384/ES512 aún no están implementados.
Las funciones de integración con frameworks (axum, actix-web) están planificadas pero no se incluyen en esta versión.
XidError usa thiserror para variantes de error estructuradas que incluyen JwtValidation, JwksFetch, KeyNotFound, IssuerMismatch y variantes específicas de webhook.