Status
Package status is Implemented · verified locally. Unit tests (22 passed) run on macOS. Keychain access and the full ASWebAuthenticationSession OAuth callback flow require a running XID instance for L4 verification. Real IdP round-trip is pending manual verification. This page documents implemented behavior; it is not a production-readiness claim.
Requirements
- macOS 13+
- Swift 5.9+ and Xcode 15+
- No third-party dependencies — uses Apple system frameworks (AuthenticationServices, CryptoKit, Security)
Installation
Add via Swift Package Manager in Package.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")]),
]Quick start
import Xid
let client = XidClient()
// 1. Configure
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 a valid access token (auto-refresh)
let token = try await client.getAccessToken()
// 4. Get current session
let current = try await client.getSession()
// 5. Sign out
try await client.signOut()Core API
| Method | Description |
|---|---|
configure(_ options:) |
Set issuer, clientId, redirectUri, and scopes. Call before all other methods. |
signIn() async throws -> XidSession |
Launch ASWebAuthenticationSession, complete PKCE S256 authorization code flow, persist tokens to Keychain, and return a session. |
handleRedirect(_ url:) async throws -> XidSession |
Process a redirect URL from an external source and exchange the code for tokens. |
getSession() async throws -> XidSession? |
Return the stored session with automatic refresh token rotation if near expiry. |
getAccessToken() async throws -> String |
Return a valid access token string, refreshing automatically if needed. |
signOut() async throws |
Clear Keychain tokens and revoke the local session. |
Relationship to sdk/ios
The macOS SDK shares the same Swift implementation pattern as sdk/ios — ASWebAuthenticationSession for browser-based authorization, CryptoKit for PKCE S256, and Keychain for token storage. The two packages target different Apple platform minima and are maintained separately to allow platform-specific entitlement configuration.
Security
- Public client — no client secret stored or transmitted.
- PKCE S256 only. Server rejects plain challenge method.
- OAuth state generated per request; validated on redirect to prevent CSRF.
- Tokens stored in Keychain with device-only access; not synced to iCloud Keychain.
Known limitations
- JWKS-backed ES256/RS256 ID token verification and end_session logout are implemented and locally tested. Real macOS Keychain and IdP round-trip validation is still required before L4 support.
- Shared Swift core extraction with sdk/ios is planned but not yet done — each package carries its own copy of the implementation.