sdk/ios | XID

SDK Swift para iOS e macOS usando ASWebAuthenticationSession, fluxode código de autorização PKCE S256 e armazenamento de tokens noKeychain.

Estado

O status do pacote é Implementado · verificado localmente.Testes unitários (19 passaram) executam no macOS direcionados a umsimulador iOS. A ida e volta real com o IdP em uma instância XID emexecução está pendente de verificação manual. Esta página documenta ocomportamento implementado; não é uma declaração de prontidão paraprodução.

Requisitos

iOS 16+ / macOS 13+
Swift 5.9+ e Xcode 15+
Sem dependências de terceiros — usa apenas frameworks do sistema Apple

Instalação

Adicione o pacote via Swift Package Manager no Xcode (Arquivo ->Adicionar Dependências de Pacote) ou diretamente emPackage.swift:

// Package.swift
dependencies: [
    .package(url: "https://github.com/StringKe/xid", from: "0.1.0"),
],
targets: [
    .target(name: "YourApp", dependencies: [.product(name: "Xid", package: "xid")]),
]

Início rápido

import Xid

// 1. Configure in @main App.init
Xid.shared.configure(options: XidConfiguration(
    issuer: URL(string: "https://xid.dev")!,
    clientId: "your_client_id",
    redirectUri: URL(string: "com.example.app://auth/callback")!,
    scopes: ["openid", "profile", "email", "offline_access"]
))

// 2. Sign in (opens ASWebAuthenticationSession)
try await Xid.shared.signIn()

// 3. Handle redirect in SceneDelegate
let session = try await Xid.shared.handleRedirect(url: callbackUrl)

// 4. Get current session (auto-refreshes near expiry)
if let session = try await Xid.shared.getSession() {
    let token = try await Xid.shared.getAccessToken()
}

// 5. Sign out
try await Xid.shared.signOut(callEndSession: true)

API principal

Método	Descrição
`configure(options:)`	Inicializa com issuer, clientId, redirectUri, scopes. Chame antes detodos os outros.
`signIn(options:) async throws`	Abre ASWebAuthenticationSession com URL de autorização PKCE S256.Retorna quando a sessão do navegador termina.
`handleRedirect(url:) async throws -> XidSession`	Valida o state OAuth, troca o código de autorização no endpoint detoken, persiste os tokens no Keychain e retorna uma sessão.
`getSession() async throws -> XidSession?`	Retorna a sessão armazenada, disparando uma rotação do refresh tokense próxima da expiração.
`getAccessToken(forceRefresh:) async throws -> String`	Retorna uma string de token de acesso válida, atualizandoautomaticamente se necessário.
`signOut(callEndSession:) async throws`	Limpa os tokens do Keychain. Passe true para chamar o endpointend_session via navegador.
`setTokenStorage(_:) throws`	Substitua o KeychainTokenStorage padrão por uma implementaçãopersonalizada de TokenStorageAdapter.

Adaptador de armazenamento

O armazenamento padrão usa o Keychain comkSecAttrAccessibleAfterFirstUnlockThisDeviceOnly — os tokensnão são sincronizados com o iCloud Keychain. Implemente o protocoloTokenStorageAdapter para usar uma política de Keychainempresarial:

struct EnterpriseKeychain: TokenStorageAdapter {
    func save(key: String, value: String) throws { /* ... */ }
    func load(key: String) throws -> String? { /* ... */ }
    func delete(key: String) throws { /* ... */ }
}
try Xid.shared.setTokenStorage(EnterpriseKeychain())

Segurança

Cliente público — nenhum segredo de cliente armazenado ou transmitido.
Apenas PKCE S256. O servidor rejeita o método de desafio plain.
State OAuth aleatório gerado por requisição; validado noredirecionamento para prevenir CSRF.
O code_verifier PKCE é gravado no Keychain apenas durante o fluxo deautorização e excluído imediatamente após a troca de código.
ASWebAuthenticationSession iniciada comprefersEphemeralWebBrowserSession = true para evitar ocompartilhamento de cookies do navegador entre aplicativos.

Limitações conhecidas

A verificacao ES256/RS256 de ID token com JWKS, logout end_session e refresh single-flight estao implementados e testados localmente. Um teste IdP real em dispositivo ou simulador iOS ainda e necessario para L4.
O comportamento do Keychain deve ser verificado em teste Xcode de dispositivo ou simulador.