sdk/dotnet

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

状態

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

インストール

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

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

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

// Program.cs
using Xid;

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

リクエストを認証します

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

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

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

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

プロパティ	デフォルト	説明
`Issuer`	必須	XID 発行者 URL
`Audience`	`null`	expected aud クレーム。null は検証をスキップします
`JwksTtl`	1 時間	JWKS メモリ内キャッシュ TTL
`SessionCookieName`	`__session`	トークン取得のフォールバック Cookie 名
`ClockSkew`	5 分	JWT exp/nbf クロックスキュー許容値
`WebhookToleranceWindow`	5 分	webhook リプレイ防止ウィンドウ

XidClient 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 もサポートしています。
AddXid() は XidClient をシングルトンとして登録し、JWKS 取得用に IHttpClientFactory を組み込みます。
例外階層：XidException -> JwksException、TokenVerificationException、WebhookVerificationException。