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.

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

La autenticación de solicitudes acepta solo Bearer de forma predeterminada. Una cookie JWT propiedad de la aplicación solo se lee cuando se configura su nombre exacto. La cookie opaca de Core __Host-xid.rt.* nunca se busca ni se verifica localmente; intercámbiala reenviando el header Cookie completo al POST /v1/sessions/token del mismo origen exacto, con las redirecciones desactivadas, y acepta solo una respuesta que contenga únicamente el campo token.

Instalación

Añade a Cargo.toml:

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

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

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)`	Configura un nombre de cookie JWT propiedad de la aplicación; desactivado de forma predeterminada.
`.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.