sdk/flutter

SDK Dart / Flutter para iOS, Android y escritorio que usa flutter_web_auth_2, flujo de código de autorización PKCE S256 y persistencia de tokens con flutter_secure_storage.

Estado

El estado del paquete es Implementado · verificado localmente. Las pruebas unitarias Dart puras (21 pasadas) cubren PKCE, modelos de tokens y almacenamiento en memoria. Las rutas de canal de plataforma (flutter_secure_storage, flutter_web_auth_2) requieren un dispositivo real o simulador 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.

Instalación

Añade a pubspec.yaml y ejecuta flutter pub get:

# pubspec.yaml
dependencies:
  xid:
    git:
      url: https://github.com/StringKe/xid
      path: sdk/flutter
      ref: main

Configuración de plataforma

Registra el esquema URI de callback en cada plataforma.

<!-- Android: AndroidManifest.xml (main Activity) -->
<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="com.example.myapp" android:host="auth" />
</intent-filter>

<!-- iOS: Info.plist -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array><string>com.example.myapp</string></array>
  </dict>
</array>

Inicio rápido

import 'package:xid/xid.dart';

final client = XidClient();

// 1. Initialize (fetches OIDC discovery)
await client.configure(
  const XidOptions(
    issuer: 'https://xid.dev',
    clientId: 'YOUR_CLIENT_ID',
    redirectUri: 'com.example.myapp://auth/callback',
    scopes: ['openid', 'profile', 'email', 'offline_access'],
  ),
);

// 2. Sign in (opens system browser, PKCE S256)
final session = await client.signIn();
print(session.user.email);

// 3. Get valid access token (auto-refreshes)
final token = await client.getAccessToken();

// 4. Get current session
final current = await client.getSession();

// 5. Sign out (revokes refresh token + clears secure storage)
await client.signOut();

API principal

Método	Descripción
`configure(XidOptions, {storageAdapter?})`	Inicializa el SDK y obtiene el discovery OIDC. Debe llamarse antes que todos los demás métodos.
`signIn({}additionalParameters?, audience?})`	Abre el navegador del sistema con la URL de autorización PKCE S256; intercambia el código y devuelve XidSession.
`handleRedirect(String url)`	Procesa el callback de App Link o esquema personalizado. Lo llama internamente signIn; invócalo manualmente para la recuperación de redirección entre procesos.
`getSession()`	Devuelve XidSession? — desencadena la rotación del refresh token si el access token está próximo a expirar (dentro de 60 s).
`getAccessToken({}bool forceRefresh})`	Devuelve una cadena de access token válida. Pasa forceRefresh: true para forzar la renovación.
`signOut({}bool openLogoutUrl})`	Revoca el refresh token (RFC 7009), limpia el almacenamiento seguro y opcionalmente abre el end_session_endpoint en el navegador.
`setTokenStorage(TokenStorageAdapter)`	Reemplaza el SecureStorageAdapter predeterminado (flutter_secure_storage) con una implementación personalizada.

Dependencias

Paquete	Versión	Propósito
`flutter_web_auth_2`	^4.0.0	Sesión de autorización en el navegador del sistema y recepción del callback
`flutter_secure_storage`	^9.2.4	Almacenamiento seguro de la plataforma (Keychain / Keystore / DPAPI)
`crypto`	^3.0.3	SHA-256 para el cálculo del challenge PKCE S256
`http`	^1.2.2	Cliente HTTP para los endpoints de discovery y tokens

Seguridad

Cliente público: no se almacena ni transmite ningún secreto de cliente.
Solo PKCE S256. Sin flujo implícito ni password grant.
Estado OAuth generado por solicitud; validado en handleRedirect para prevenir CSRF.
Los refresh tokens se almacenan en el almacenamiento seguro de la plataforma (Keychain en iOS, Keystore en Android) y el servidor XID los rota en cada uso.

Limitaciones conocidas

La verificación ES256 de ID token basada en JWKS, PKCE persistente por state y refresh single-flight están implementados y probados localmente. La validación con dispositivo real e IdP sigue siendo necesaria para L4.
offline_access debe incluirse en los scopes para recibir un refresh token.