sdk/dotnet | Vonvon

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 Vonvon 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-vonvon.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

.NET 8 requis comme cible.

<ItemGroup>
  <ProjectReference Include="../vonvon/sdk/dotnet/Vonvon.csproj" />
</ItemGroup>

Configuration ASP.NET Core (recommandée)

// Program.cs
using Vonvon;

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

Authentifier une requête

// Controller / Minimal API
public class MyController(VonvonClient vonvon) : ControllerBase
{
    [HttpGet("/me")]
    public async Task<IActionResult> GetMe()
    {
        var auth = await vonvon.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() => vonvon.ExchangeSessionTokenAsync(
        $"{Request.Scheme}://{Request.Host}{Request.Path}",
        Request.Headers.Cookie.ToString());
}

Vérifier le jeton directement

using Vonvon;

var client = new VonvonClient(new VonvonOptions { Issuer = "https://vonvon.id" });

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/vonvon", async (HttpRequest req, VonvonClient vonvon) =>
{
    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("VONVON_WEBHOOK_SECRET")
        ?? throw new InvalidOperationException("VONVON_WEBHOOK_SECRET is required");

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

VonvonOptions

Propriété	Défaut	Description
`Issuer`	requis	URL d’émetteur Vonvon
`Audience`	`null`	Revendication aud attendue ; null ignore la validation
`JwksTtl`	1 heure	TTL du cache JWKS en mémoire
`SessionCookieName`	`disabled`	Nom du cookie JWT détenu par l’application ; désactivé sauf configuration explicite
`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 VonvonClient

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.
AddVonvon() enregistre VonvonClient en tant que singleton et câbleIHttpClientFactory pour la récupération JWKS.
Hiérarchie d’exceptions : VonvonException -> JwksException,TokenVerificationException, WebhookVerificationException.