sdk/flutter

SDK Dart / Flutter para iOS, Android e desktop usandoflutter_web_auth_2, fluxo de código de autorização PKCE S256 epersistência de tokens com flutter_secure_storage.

Estado

O status do pacote é Implementado · verificado localmente.Testes unitários Dart puro (21 passaram) cobrem PKCE, modelos detoken e armazenamento em memória. Caminhos de platform-channel(flutter_secure_storage, flutter_web_auth_2) requerem um dispositivoou simulador real para verificação. A ida e volta real com o IdP estápendente de verificação manual. Esta página documenta o comportamentoimplementado; não é uma declaração de prontidão para produção.

Instalação

Adicione ao pubspec.yaml e execute flutter pub get:

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

Configuração da plataforma

Registre o esquema de URI de callback em 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>

Início 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	Descrição
`configure(XidOptions, {storageAdapter?})`	Inicializa o SDK e busca a discovery OIDC. Deve ser chamado antes detodos os outros métodos.
`signIn({}additionalParameters?, audience?})`	Abre o navegador do sistema com a URL de autorização PKCE S256; trocao código e retorna XidSession.
`handleRedirect(String url)`	Processa callback de App Link ou esquema personalizado. Chamadointernamente por signIn; invoque manualmente para recuperação deredirecionamento entre processos.
`getSession()`	Retorna XidSession? — dispara rotação do refresh token se o token deacesso estiver próximo da expiração (dentro de 60 s).
`getAccessToken({}bool forceRefresh})`	Retorna uma string de token de acesso válida. Passe forceRefresh:true para forçar a renovação.
`signOut({}bool openLogoutUrl})`	Revoga o refresh token (RFC 7009), limpa o armazenamento seguro e,opcionalmente, abre o end_session_endpoint no navegador.
`setTokenStorage(TokenStorageAdapter)`	Substitua o SecureStorageAdapter padrão (flutter_secure_storage) poruma implementação personalizada.

Dependências

Pacote	Versão	Finalidade
`flutter_web_auth_2`	^4.0.0	Sessão de autorização no navegador do sistema e recebimento docallback
`flutter_secure_storage`	^9.2.4	Armazenamento seguro da plataforma (Keychain / Keystore / DPAPI)
`crypto`	^3.0.3	SHA-256 para computação do desafio PKCE S256
`http`	^1.2.2	Cliente HTTP para endpoints de discovery e token

Segurança

Cliente público — nenhum segredo de cliente armazenado ou transmitido.
Apenas PKCE S256. Sem fluxo implícito nem password grant.
State OAuth gerado por requisição; validado em handleRedirect paraprevenir CSRF.
Os refresh tokens são armazenados no armazenamento seguro daplataforma (Keychain no iOS, Keystore no Android) e rotacionados acada uso pelo servidor XID.

Limitações conhecidas

A verificacao ES256 de ID token com JWKS, PKCE persistente por state e refresh single-flight estao implementados e testados localmente. A validacao com dispositivo real e IdP ainda e necessaria para L4.
offline_access deve ser incluído nos escopos para receber um refreshtoken.