sdk/windows

SDK C# / .NET para aplicações WinUI 3 usando WebView2 paraautorização, PKCE S256 e IsolatedStorage protegido por DPAPI parapersistência de tokens.

Estado

O status do pacote é Implementado · verificado localmente.dotnet test passa 19 casos (build net8.0 multiplataforma e net10.0).APIs específicas do Windows (WebView2, DPAPI, WinUI 3) requerem umambiente de build Windows para verificação. A ida e volta real com oIdP está pendente de verificação manual. Esta página documenta ocomportamento implementado; não é uma declaração de prontidão paraprodução.

Requisitos

.NET 8 e Windows App SDK 1.6+
WebView2 Runtime (Evergreen — pré-instalado com o Microsoft Edge)
O aplicativo deve definir <UseWinUI>true</UseWinUI> no arquivo deprojeto

Instalação

Adicione uma PackageReference ao arquivo de projeto do seu aplicativo:

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

Início rápido

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

Callback de esquema de URI personalizado (opcional)

Se usar um redirecionamento de esquema de URI personalizado em vez dajanela incorporada WebView2, encaminhe o URI de ativação do protocolopara 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 principal

Método	Descrição
`Configure(XidConfiguration)`	Inicializa o SDK. Chame uma vez na inicialização do aplicativo.
`SignInAsync(options?, ct)`	Abre uma janela de autorização WebView2 incorporada com PKCE S256.Retorna XidSession ao concluir.
`HandleRedirectAsync(Uri, ct)`	Processa um callback de esquema de URI personalizado e troca o códigode autorização.
`GetSession(ct)`	Retorna a sessão atual, atualizando automaticamente se próxima daexpiração.
`GetAccessToken(options?, ct)`	Retorna uma string de token de acesso válida, disparando atualizaçãose necessário.
`SignOut(ct)`	Limpa os tokens de sessão locais do IsolatedStorage protegido porDPAPI.
`SetTokenStorage(ITokenStorage)`	Substitua o DpapiTokenStorage padrão por uma implementaçãopersonalizada de ITokenStorage.

Adaptador de armazenamento

O armazenamento padrão criptografa os tokens com DPAPI (escopoCurrentUser) e os persiste no IsolatedStorage. ImplementeITokenStorage para usar o Windows Hello ou o CredentialManager:

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

Dependências

Pacote	Versão	Finalidade
`Microsoft.WindowsAppSDK`	1.6.250228002	Host WinUI 3 e incorporação do WebView2
`Microsoft.Web.WebView2`	1.0.3065.39	Janela de autorização incorporada baseada em Chromium
`System.Security.Cryptography.ProtectedData`	8.0.0	Criptografia de tokens em repouso com DPAPI

Segurança

Cliente público — nenhum segredo de cliente armazenado ou transmitido.
Apenas PKCE S256. O servidor rejeita o método de desafio plain.
Tokens criptografados com DPAPI (escopo CurrentUser) e armazenados noIsolatedStorage. Não acessíveis a outras contas de usuário do Windows.
State OAuth gerado por requisição; validado no redirecionamento paraprevenir CSRF.

Limitações conhecidas

O WebView2 Runtime deve estar presente. O suporte aWebAuthenticationBroker como fallback está planejado, mas ainda nãoimplementado.
A verificacao de ID token com JWKS e o sign-out end_session estao implementados e testados localmente. As validacoes de Windows WebView2, DPAPI e IdP ainda sao necessarias para L4.
DpapiTokenStorage não funciona em plataformas não-Windows. Use umaimplementação diferente de ITokenStorage ao compilar de forma cruzada.