sdk/windows

适用于 WinUI 3 应用的 C# / .NET SDK，使用 WebView2 进行授权、PKCE S256 和 DPAPI 保护的 IsolatedStorage 进行 token 持久化。

状态

包状态为 已实现 · 本地已验证。dotnet test 通过 19 个测试用例（net8.0 跨平台构建和 net10.0）。Windows 专有 API（WebView2、DPAPI、WinUI 3）需要 Windows 构建环境验证。IdP 往返验证待人工核实。本页面记录已实现的行为，不代表生产就绪声明。

要求

.NET 8 和 Windows App SDK 1.6+
WebView2 运行时（常青版——随 Microsoft Edge 预装）
应用必须在项目文件中设置 <UseWinUI>true</UseWinUI>

安装

在应用项目文件中添加 PackageReference：

<ItemGroup>
  <PackageReference Include="Xid.Windows" Version="0.1.0" />
</ItemGroup>

快速开始

using Xid.Windows;

// 1. Configure in App.xaml.cs OnLaunched
XidClient.Shared.Configure(new XidConfiguration
{
    Issuer      = new Uri("https://xid.dev"),
    ClientId    = "your_client_id",
    RedirectUri = "com.example.myapp://auth/callback",
    // Scopes default: openid profile email offline_access
});

// 2. Sign in (opens embedded WebView2 window)
XidSession session = await XidClient.Shared.SignInAsync();
Console.WriteLine($"Signed in: {session.User.Email}");

// 3. Get a valid access token (auto-refresh)
string? token = await XidClient.Shared.GetAccessToken();

// 4. Get current session
XidSession? current = await XidClient.Shared.GetSession();

// 5. Sign out
await XidClient.Shared.SignOut();

自定义 URI scheme callback（可选）

如果使用自定义 URI scheme 重定向而非 WebView2 嵌入窗口，请将协议激活 URI 转发给 HandleRedirectAsync：

// App.xaml.cs
protected override void OnActivated(IActivatedEventArgs args)
{
    if (args.Kind == ActivationKind.Protocol)
    {
        var protocolArgs = (ProtocolActivatedEventArgs)args;
        await XidClient.Shared.HandleRedirectAsync(protocolArgs.Uri);
    }
}

核心 API

方式	描述
`Configure(XidConfiguration)`	初始化 SDK。在应用启动时调用一次。
`SignInAsync(options?, ct)`	以 PKCE S256 打开嵌入式 WebView2 授权窗口。完成后返回 XidSession。
`HandleRedirectAsync(Uri, ct)`	处理自定义 URI scheme callback 并交换授权码。
`GetSession(ct)`	返回当前会话，接近过期时自动刷新。
`GetAccessToken(options?, ct)`	返回有效的访问令牌字符串，如需刷新则触发刷新。
`SignOut(ct)`	从 DPAPI 保护的 IsolatedStorage 中清除本地会话 token。
`SetTokenStorage(ITokenStorage)`	用自定义 ITokenStorage 实现替换默认的 DpapiTokenStorage。

存储适配器

默认存储使用 DPAPI（CurrentUser 范围）加密 token，并将其持久化到 IsolatedStorage。实现 ITokenStorage 以使用 Windows Hello 或 Credential Manager：

public sealed class MyCustomStorage : ITokenStorage
{
    public Task SaveAsync(StoredTokenSet tokens, CancellationToken ct = default) { ... }
    public Task<StoredTokenSet?> LoadAsync(CancellationToken ct = default) { ... }
    public Task ClearAsync(CancellationToken ct = default) { ... }
}
XidClient.Shared.SetTokenStorage(new MyCustomStorage());

依赖项

包	版本	用途
`Microsoft.WindowsAppSDK`	1.6.250228002	WinUI 3 宿主和 WebView2 嵌入
`Microsoft.Web.WebView2`	1.0.3065.39	基于 Chromium 的嵌入式授权窗口
`System.Security.Cryptography.ProtectedData`	8.0.0	DPAPI token 静态加密

安全

公共客户端——不存储或传输客户端密钥。
仅 PKCE S256。服务器拒绝 plain challenge 方式。
使用 DPAPI（CurrentUser 范围）加密 token，并存储在 IsolatedStorage 中。其他 Windows 用户账户无法访问。
每次请求生成 OAuth state；在重定向时验证以防 CSRF。

已知限制

必须安装 WebView2 运行时。WebAuthenticationBroker 作为回退方案已在计划中，但尚未实现。
基于 JWKS 的 ID token 验签和 end_session 登出已实现并完成本地测试。真实 Windows WebView2、DPAPI 和 IdP 往返验证前仍不具备 L4 支持。
DpapiTokenStorage 不能在非 Windows 平台上运行。交叉编译时请使用其他 ITokenStorage 实现。