sdk/dotnet

SDK de servidor .NET 8 para verificación JWT sin llamadas de red, autenticación de solicitudes ASP.NET Core 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

Se requiere .NET 8 como destino.

<ItemGroup>
  <ProjectReference Include="../xid/sdk/dotnet/Xid.csproj" />
</ItemGroup>

Configuración de ASP.NET Core (recomendado)

// Program.cs
using Xid;

builder.Services.AddXid(options =>
{
    options.Issuer   = "https://xid.dev";
    options.Audience = "your-client-id"; // optional
});

Autenticar una solicitud

// Controller / Minimal API
public class MyController(XidClient xid) : ControllerBase
{
    [HttpGet("/me")]
    public async Task<IActionResult> GetMe()
    {
        var auth = await xid.AuthenticateRequestAsync(
            authorizationHeader: Request.Headers.Authorization);

        if (!auth.Authenticated)
            return Unauthorized(auth.Reason);

        return Ok(new { sub = auth.Claims!.Sub, email = auth.Claims.Email });
    }

    private Task<string> ExchangeSessionAsync() => xid.ExchangeSessionTokenAsync(
        $"{Request.Scheme}://{Request.Host}{Request.Path}",
        Request.Headers.Cookie.ToString());
}

Verificar token directamente

using Xid;

var client = new XidClient(new XidOptions { Issuer = "https://xid.dev" });

try
{
    var claims = await client.VerifyTokenAsync("eyJ...");
    Console.WriteLine($"sub={claims.Sub} email={claims.Email}");
}
catch (TokenVerificationException ex)
{
    Console.WriteLine($"Invalid token: {ex.Message}");
}

Verificar webhook

app.MapPost("/webhooks/xid", async (HttpRequest req, XidClient xid) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    var body = ms.ToArray();

    var headers = new Dictionary<string, string>
    {
        ["svix-id"]        = req.Headers["svix-id"].ToString(),
        ["svix-timestamp"] = req.Headers["svix-timestamp"].ToString(),
        ["svix-signature"] = req.Headers["svix-signature"].ToString(),
    };

    var webhookSecret = Environment.GetEnvironmentVariable("XID_WEBHOOK_SECRET")
        ?? throw new InvalidOperationException("XID_WEBHOOK_SECRET is required");

    try
    {
        var webhook = xid.VerifyWebhook(body, headers, secret: webhookSecret);
        return Results.Ok();
    }
    catch (WebhookVerificationException ex)
    {
        return Results.BadRequest(ex.Message);
    }
});

XidOptions

Propiedad	Por defecto	Descripción
`Issuer`	obligatorio	URL del emisor XID
`Audience`	`null`	Claim aud esperado; null omite la validación
`JwksTtl`	1 hora	TTL del caché en memoria de JWKS
`SessionCookieName`	`disabled`	Nombre de cookie JWT propiedad de la aplicación; desactivado salvo configuración explícita
`ClockSkew`	5 minutos	Tolerancia de desfase de reloj JWT para exp/nbf
`WebhookToleranceWindow`	5 minutos	Ventana de prevención de repetición del webhook

API de XidClient

Método	Descripción
`VerifyTokenAsync(token, ct)`	Verifica una cadena JWT; lanza `TokenVerificationException` al fallar.
`AuthenticateRequestAsync(authHeader, cookies, ct)`	Extrae y verifica el token; devuelve `AuthStatus`; no lanza excepciones.
`VerifyWebhook(payload, headers, secret)`	Valida la firma del webhook; lanza `WebhookVerificationException` al fallar. Síncrono.

Notas de plataforma

Usa Microsoft.IdentityModel.Tokens y System.IdentityModel.Tokens.Jwt 8.x. ES256 es el principal; RS256 y PS256 están soportados.
AddXid() registra XidClient como singleton y conecta IHttpClientFactory para obtener el JWKS.
Jerarquía de excepciones: XidException -> JwksException, TokenVerificationException, WebhookVerificationException.