sdk/windows

SDK C# / .NET para aplicaciones WinUI 3 que usa WebView2 para autorización, PKCE S256 y IsolatedStorage protegido con DPAPI para persistencia de tokens.

Estado

El estado del paquete es Implementado · verificado localmente. dotnet test supera 19 casos (compilación multiplataforma net8.0 y net10.0). Las APIs específicas de Windows (WebView2, DPAPI, WinUI 3) requieren un entorno de compilación Windows para su verificación. La prueba de ida y vuelta real contra un IdP está pendiente de verificación manual. Esta página documenta el comportamiento implementado; no es una declaración de disponibilidad para producción.

Requisitos

.NET 8 y Windows App SDK 1.6+
WebView2 Runtime (Evergreen: preinstalado con Microsoft Edge)
La aplicación debe establecer <UseWinUI>true</UseWinUI> en el archivo de proyecto

Instalación

Añade un PackageReference al archivo de proyecto de tu aplicación:

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

Inicio 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 URI personalizado (opcional)

Si usas una redirección de esquema URI personalizado en lugar de la ventana embebida de WebView2, reenvía la URI de activación del protocolo a 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	Descripción
`Configure(XidConfiguration)`	Inicializa el SDK. Llámalo una sola vez al arrancar la aplicación.
`SignInAsync(options?, ct)`	Abre una ventana de autorización WebView2 embebida con PKCE S256. Devuelve XidSession al completarse.
`HandleRedirectAsync(Uri, ct)`	Procesa un callback de esquema URI personalizado e intercambia el código de autorización.
`GetSession(ct)`	Devuelve la sesión actual, renovándola automáticamente si está próxima a expirar.
`GetAccessToken(options?, ct)`	Devuelve una cadena de access token válida, desencadenando la renovación si es necesario.
`SignOut(ct)`	Limpia los tokens de sesión locales del IsolatedStorage protegido con DPAPI.
`SetTokenStorage(ITokenStorage)`	Reemplaza el DpapiTokenStorage predeterminado con una implementación personalizada de ITokenStorage.

Adaptador de almacenamiento

El almacenamiento predeterminado cifra los tokens con DPAPI (ámbito CurrentUser) y los persiste en IsolatedStorage. Implementa ITokenStorage para usar Windows Hello o el Administrador de credenciales:

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

Dependencias

Paquete	Versión	Propósito
`Microsoft.WindowsAppSDK`	1.6.250228002	Host WinUI 3 y embedding de WebView2
`Microsoft.Web.WebView2`	1.0.3065.39	Ventana de autorización embebida basada en Chromium
`System.Security.Cryptography.ProtectedData`	8.0.0	Cifrado de tokens en reposo con DPAPI

Seguridad

Cliente público: no se almacena ni transmite ningún secreto de cliente.
Solo PKCE S256. El servidor rechaza el método plain de challenge.
Tokens cifrados con DPAPI (ámbito CurrentUser) y almacenados en IsolatedStorage. No accesibles para otras cuentas de usuario de Windows.
Estado OAuth generado por solicitud; validado en la redirección para prevenir CSRF.

Limitaciones conocidas

El WebView2 Runtime debe estar presente. El soporte de WebAuthenticationBroker como reserva está planificado pero aún no implementado.
La verificación de ID token basada en JWKS y el cierre de sesión end_session están implementados y probados localmente. Las pruebas reales de Windows WebView2, DPAPI e IdP siguen siendo necesarias para L4.
DpapiTokenStorage no funciona en plataformas distintas a Windows. Usa otra implementación de ITokenStorage al compilar de forma cruzada.