sdk/dotnet | Vonvon

.NET 8 Server-SDK für netzwerklose JWT-Prüfung, ASP.NETCore-Anfrage-Authentifizierung und Webhook-Signaturvalidierung.

Zustand

Implementiert und lokal verifiziert. Die echteIdP-Round-Trip-Verifizierung (JWKS-Abruf, Token-Signierung/Prüfung gegeneine Live-Vonvon-Instanz) wurde noch nicht durchgeführt und muss vor demProduktionseinsatz abgeschlossen werden.

Registry-Status: UNPUBLISHED. Installieren Sie dieses SDK nur aus einem Checkout des Repository-Quellcodes; verwenden Sie keine externe Paket-Registry.

Die Anfrageauthentifizierung akzeptiert standardmäßig nur Bearer. Ein anwendungseigenes JWT-Cookie wird nur gelesen, wenn sein exakter Name konfiguriert ist. Das opake Core-Cookie __Host-vonvon.rt.* wird niemals durchsucht oder lokal verifiziert; tauschen Sie es aus, indem Sie den vollständigen Cookie-Header ohne Weiterleitungen an den exakt gleichursprünglichen Endpunkt POST /v1/sessions/token weiterleiten, und akzeptieren Sie nur eine Antwort, die ausschließlich das Feld token enthält.

Installieren

.NET 8 als Zielplattform erforderlich.

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

ASP.NET Core-Einrichtung (empfohlen)

// Program.cs
using Vonvon;

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

Anfrage authentifizieren

// 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());
}

Token direkt prüfen

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

Webhook prüfen

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

Eigenschaft	Standard	Beschreibung
`Issuer`	erforderlich	Vonvon-Issuer-URL
`Audience`	`null`	Erwarteter aud-Claim; null überspringt die Validierung
`JwksTtl`	1 Stunde	JWKS-In-Memory-Cache-TTL
`SessionCookieName`	`disabled`	Name des anwendungseigenen JWT-Cookies; nur bei expliziter Konfiguration aktiviert
`ClockSkew`	5 Minuten	JWT-exp/nbf-Taktversatztoleranz
`WebhookToleranceWindow`	5 Minuten	Webhook-Replay-Präventionsfenster

VonvonClient-API

Methode	Beschreibung
`VerifyTokenAsync(token, ct)`	JWT-String prüfen; wirft bei Fehler `TokenVerificationException`.
`AuthenticateRequestAsync(authHeader, cookies, ct)`	Token extrahieren und prüfen; gibt `AuthStatus` zurück; wirft keineException.
`VerifyWebhook(payload, headers, secret)`	Webhook-Signatur validieren; löst bei Fehler`WebhookVerificationException` aus. Synchron.

Plattformhinweise

Verwendet Microsoft.IdentityModel.Tokens undSystem.IdentityModel.Tokens.Jwt 8.x. ES256 ist primär; RS256 undPS256 werden unterstützt.
AddVonvon() registriert VonvonClient als Singleton und verdrahtetIHttpClientFactory für den JWKS-Abruf.
Ausnahmehierarchie: VonvonException -> JwksException,TokenVerificationException, WebhookVerificationException.