sdk/dotnet

SDK serveur .NET 8 pour la vérification JWT sans réseau,l'authentification des requêtes ASP.NET Core et la validation dessignatures 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

.NET 8 requis comme cible.

<PackageReference Include="Xid" Version="0.1.0" />

Configuration ASP.NET Core (recommandée)

// Program.cs
using Xid;

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

Authentifier une requête

// 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,
            cookies: Request.Cookies.ToDictionary(c => c.Key, c => c.Value));

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

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

Vérifier le jeton directement

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

Vérifier le 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

Propriété	Défaut	Description
`Issuer`	requis	URL d’émetteur XID
`Audience`	`null`	Revendication aud attendue ; null ignore la validation
`JwksTtl`	1 heure	TTL du cache JWKS en mémoire
`SessionCookieName`	`__session`	Nom de cookie de repli pour l’extraction du jeton
`ClockSkew`	5 minutes	Tolérance au décalage d’horloge JWT pour exp/nbf
`WebhookToleranceWindow`	5 minutes	Fenêtre de prévention des relectures de webhook

API XidClient

Méthode	Description
`VerifyTokenAsync(token, ct)`	Vérifier la chaîne JWT ; lève `TokenVerificationException` en casd’échec.
`AuthenticateRequestAsync(authHeader, cookies, ct)`	Extraire et vérifier le jeton ; retourne `AuthStatus` ; ne lève pasd’exception.
`VerifyWebhook(payload, headers, secret)`	Valider la signature webhook ; lève `WebhookVerificationException` encas d’échec. Synchrone.

Notes de plateforme

Utilise Microsoft.IdentityModel.Tokens etSystem.IdentityModel.Tokens.Jwt 8.x. ES256 est principal ; RS256 etPS256 sont pris en charge.
AddXid() enregistre XidClient en tant que singleton et câbleIHttpClientFactory pour la récupération JWKS.
Hiérarchie d’exceptions : XidException -> JwksException,TokenVerificationException, WebhookVerificationException.