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 y verificado localmente. La suite de pruebas unitarias de Dart y Flutter se ejecuta correctamente y cubre PKCE, la verificación del nonce y del token de ID, la capacidad de invitado, la caducidad de la sesión y los contratos de almacenamiento. Las rutas del canal de plataforma y un recorrido de ida y vuelta con un IdP real aún requieren un dispositivo o simulador. Esta página documenta el comportamiento implementado; no afirma que esté listo para producción.

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

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). offline_access is rejected until DPoP is implemented.
await client.configure(
  const XidOptions(
    issuer: 'https://xid.dev',
    clientId: 'YOUR_CLIENT_ID',
    redirectUri: 'com.example.myapp://auth/callback',
    scopes: ['openid', 'profile', 'email'],
  ),
);

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

// 3. Get the current unexpired access token. Expiry requires reauthorization.
final token = await client.getAccessToken();

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

// 5. Clear secure storage and optionally open end_session. No revoke request is sent.
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 la XidSession actual no caducada o null después de borrar el estado local caducado.
`getAccessToken({}bool forceRefresh})`	Devuelve el token de acceso actual no caducado. forceRefresh: true borra la sesión y exige volver a autorizar.
`signOut({}bool openLogoutUrl})`	Borra el almacenamiento seguro y, opcionalmente, abre end_session_endpoint en el navegador del sistema; no se envía ninguna solicitud de revocación.
`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.
Las sesiones nuevas almacenan los tokens de acceso y de ID en el almacenamiento seguro de la plataforma. El campo de compatibilidad refreshToken permanece en null y offline_access se rechaza hasta que se implemente DPoP.

Limitaciones conocidas

La verificación de tokens de ID ES256 respaldada por JWKS, la validación del nonce y PKCE persistido con clave de estado están implementados y probados localmente. Aún se requieren validaciones con un dispositivo real y un IdP antes de ofrecer compatibilidad L4.
offline_access se rechaza hasta que el SDK implemente la vinculación de remitente DPoP; cuando caduca el token de acceso, es necesario volver a autorizar.