sdk/windows

Status

Package status is Implemented and verified locally. The cross-platform .NET unit-test suite passes. WebView2, DPAPI, WinUI 3, and a real IdP round-trip still require a Windows integration environment. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Requirements

• .NET 8 and Windows App SDK 1.6+
• WebView2 Runtime (Evergreen — pre-installed with Microsoft Edge)
• Application must set <UseWinUI>true</UseWinUI> in the project file

Installation

Add a ProjectReference to the source checkout from your application project file:

<ItemGroup>
  <ProjectReference Include="../xid/sdk/windows/Xid.Windows.csproj" />
</ItemGroup>

Quick start

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

Custom URI scheme callback (optional)

If using a custom URI scheme redirect rather than the WebView2 embedded window, forward the protocol activation URI to 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);
    }
}

Core API

Storage adapter

The default storage encrypts tokens with DPAPI (CurrentUser scope) and persists them in IsolatedStorage. Implement ITokenStorage to use Windows Hello or 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());

Dependencies

Security

• Public client — no client secret stored or transmitted.
• PKCE S256 only. Server rejects plain challenge method.
• Tokens encrypted with DPAPI (CurrentUser scope) and stored in IsolatedStorage. Not accessible to other Windows user accounts.
• OAuth state generated per request; validated on redirect to prevent CSRF.

Known limitations

• WebView2 Runtime must be present. WebAuthenticationBroker support as a fallback is planned but not yet implemented.
• JWKS-backed ID token verification and end_session sign-out are implemented and locally tested. Real Windows WebView2, DPAPI, and IdP round-trip validation is still required before L4 support.
• DpapiTokenStorage does not run on non-Windows platforms. Use a different ITokenStorage implementation when cross-compiling.