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 package é Implementado e verificado localmente. A suíte de testes unitários Dart e Flutter passa e cobre PKCE, verificação de nonce e token de ID, capacidade de convidado, expiração de sessão e contratos de armazenamento. Os caminhos de platform channel e um ciclo completo com um IdP real ainda exigem um dispositivo ou simulador. Esta página documenta o comportamento implementado; não é uma declaração de prontidão para produção.

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

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). 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	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()`	Retornar a XidSession atual não expirada, ou null após limpar o estado local expirado.
`getAccessToken({}bool forceRefresh})`	Retornar o token de acesso atual não expirado. forceRefresh: true limpa a sessão e exige nova autorização.
`signOut({}bool openLogoutUrl})`	Limpar o armazenamento seguro e, opcionalmente, abrir end_session_endpoint no navegador do sistema; nenhuma solicitação de revogação é enviada.
`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.
Novas sessões armazenam tokens de acesso e de ID no armazenamento seguro da plataforma. O campo de compatibilidade refreshToken permanece null, e offline_access é rejeitado até que DPoP seja implementado.

Limitações conhecidas

A verificação de token de ID ES256 com suporte de JWKS, a validação de nonce e o PKCE persistido indexado por estado estão implementados e testados localmente. A validação em dispositivo real e com IdP ainda é necessária antes do suporte L4.
offline_access é rejeitado até que o SDK implemente a vinculação de remetente DPoP; a expiração do token de acesso exige nova autorização.