sdk/macos

SDK Swift para macOS usando ASWebAuthenticationSession, fluxo decódigo de autorização PKCE S256 e armazenamento de tokens noKeychain. Compartilha o padrão de implementação com sdk/ios.

Estado

O status do package é Implementado e verificado localmente. A suíte de testes unitários Swift passa no macOS. O acesso ao Keychain, o callback ASWebAuthenticationSession completo e um ciclo completo com um IdP real ainda exigem evidências de integração em desktop. 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.

Requisitos

macOS 13+
Swift 5.9+ e Xcode 15+
Sem dependências de terceiros — usa frameworks do sistema Apple(AuthenticationServices, CryptoKit, Security)

Instalação

Adicione via Swift Package Manager em Package.swift:

// Package.swift
dependencies: [
    .package(path: "../xid/sdk/macos"),
],
targets: [
    .target(name: "YourApp", dependencies: [.product(name: "Xid", package: "macos")]),
]

Início rápido

import Xid

let client = XidClient()

// 1. Configure. offline_access is rejected until DPoP is implemented.
client.configure(XidOptions(
    issuer: URL(string: "https://xid.dev")!,
    clientId: "your_client_id",
    redirectUri: "yourapp://callback"
))

// 2. Sign in (opens ASWebAuthenticationSession)
let session = try await client.signIn()

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

// 4. Get the current unexpired session.
let current = try await client.getSession()

// 5. Clear local state and optionally call end_session.
try await client.signOut()

API principal

Método	Descrição
`configure(_ options:)`	Define issuer, clientId, redirectUri e escopos. Chame antes de todosos outros métodos.
`signIn() async throws -> XidSession`	Abre ASWebAuthenticationSession, conclui o fluxo de código deautorização PKCE S256, persiste os tokens no Keychain e retorna umasessão.
`handleRedirect(_ url:) async throws -> XidSession`	Processa uma URL de redirecionamento de uma fonte externa e troca ocódigo por tokens.
`getSession() async throws -> XidSession?`	Retornar a sessão macOS atual não expirada; o estado do token expirado é limpo e o método retorna nil.
`getAccessToken() async throws -> String`	Retornar o token de acesso atual não expirado. O SDK rejeita offline_access até que DPoP seja implementado; a expiração exige nova autorização.
`signOut() async throws`	Limpar os tokens do Keychain e, opcionalmente, chamar o endpoint end_session; nenhuma revogação de refresh token é realizada.

Relação com sdk/ios

O SDK macOS compartilha o mesmo padrão de implementação Swift quesdk/ios — ASWebAuthenticationSession para autorização baseada emnavegador, CryptoKit para PKCE S256 e Keychain para armazenamento detokens. Os dois pacotes têm versões mínimas da plataforma Applediferentes e são mantidos separadamente para permitir a configuraçãode entitlements específicos da plataforma.

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 gerado por requisição; validado no redirecionamento paraprevenir CSRF.
Tokens armazenados no Keychain com acesso exclusivo ao dispositivo;não sincronizados com o iCloud Keychain.

Limitações conhecidas

A verificacao ES256/RS256 de ID token com JWKS e o logout end_session estao implementados e testados localmente. A validacao de macOS Keychain e IdP ainda e necessaria para L4.
A extração do núcleo Swift compartilhado com sdk/ios está planejada,mas ainda não foi realizada — cada pacote carrega sua própria cópiada implementação.