sdk/dotnet | Vonvon

.NET 8 サーバー SDK。ネットワークレス JWT 検証、ASP.NET Core リクエスト認証、webhook 署名検証をサポートします。

状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 Vonvon インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な __Host-vonvon.rt.* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

インストール

.NET 8 ターゲットが必要です。

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

ASP.NET Core セットアップ（推奨）

// Program.cs
using Vonvon;

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

リクエストを認証します

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

トークンを直接検証します

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 を検証

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

プロパティ	デフォルト	説明
`Issuer`	必須	Vonvon 発行者 URL
`Audience`	`null`	expected aud クレーム。null は検証をスキップします
`JwksTtl`	1 時間	JWKS メモリ内キャッシュ TTL
`SessionCookieName`	`disabled`	アプリケーション所有の JWT cookie 名。明示的に設定した場合のみ有効
`ClockSkew`	5 分	JWT exp/nbf クロックスキュー許容値
`WebhookToleranceWindow`	5 分	webhook リプレイ防止ウィンドウ

VonvonClient API

方式	説明
`VerifyTokenAsync(token, ct)`	JWT 文字列を検証します。失敗時は `TokenVerificationException` をスローします。
`AuthenticateRequestAsync(authHeader, cookies, ct)`	トークンを取得して検証します。`AuthStatus` を返し、スローしません。
`VerifyWebhook(payload, headers, secret)`	webhook 署名を検証します。失敗時は `WebhookVerificationException` をスローします。同期実行。

プラットフォームの注意事項

ES256 を主として Microsoft.IdentityModel.Tokens と System.IdentityModel.Tokens.Jwt 8.x を使用します。RS256 と PS256 もサポートしています。
AddVonvon() は VonvonClient をシングルトンとして登録し、JWKS 取得用に IHttpClientFactory を組み込みます。
例外階層：VonvonException -> JwksException、TokenVerificationException、WebhookVerificationException。