sdk/windows

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

状态

包状态为已在本地实现并验证。跨平台 .NET 单元测试套件已通过。WebView2、DPAPI、WinUI 3 和真实 IdP 往返仍需 Windows 集成环境。本页记录的是已实现行为，不代表已具备生产就绪状态。

Registry 状态:UNPUBLISHED。此 SDK 只能从仓库源码 checkout 安装；不要使用外部 package registry。

要求

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

安装

从应用项目文件添加指向源码 checkout 的 ProjectReference:

<ItemGroup>
  <ProjectReference Include="../xid/sdk/windows/Xid.Windows.csproj" />
</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 is rejected until DPoP is implemented.
});

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

// 3. Get the current unexpired access token. Expiry requires reauthorization.
string? token = await XidClient.Shared.GetAccessToken();

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

// 5. Clear local state.
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)`	返回当前未过期的会话；如果已过期，则清除本地状态并返回 null。
`GetAccessToken(options?, ct)`	返回当前未过期的 access token；ForceRefresh 会清除会话并要求重新授权。
`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 实现。