sdk/macos

ASWebAuthenticationSession, PKCE S256 인증 코드 흐름, Keychain 토큰 저장소를 사용하는 macOS용 Swift SDK. sdk/ios와 구현 패턴을 공유합니다.

상태

패키지 상태: 구현됨 · 로컬 검증 완료. 단위 테스트(22개 통과)가 macOS에서 실행됩니다. Keychain 접근과 전체 ASWebAuthenticationSession OAuth 콜백 흐름은 L4 검증을 위해 실행 중인 XID 인스턴스가 필요합니다. 실제 IdP 왕복 테스트는 수동 검증 대기 중입니다. 이 페이지는 구현된 동작을 문서화하며, 프로덕션 준비 완료를 의미하지 않습니다.

요구 사항

macOS 13 이상
Swift 5.9 이상 및 Xcode 15 이상
서드파티 의존성 없음 — Apple 시스템 프레임워크(AuthenticationServices, CryptoKit, Security)를 사용합니다

설치

Package.swift에서 Swift Package Manager를 통해 추가하세요:

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

빠른 시작

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()

핵심 API

방법	설명
`configure(_ options:)`	issuer, clientId, redirectUri, scopes를 설정합니다. 다른 모든 메서드보다 먼저 호출하세요.
`signIn() async throws -> XidSession`	ASWebAuthenticationSession을 시작하고, PKCE S256 인증 코드 흐름을 완료하고, 토큰을 Keychain에 저장한 후 세션을 반환합니다.
`handleRedirect(_ url:) async throws -> XidSession`	외부 소스의 리디렉션 URL을 처리하고 코드를 토큰으로 교환합니다.
`getSession() async throws -> XidSession?`	저장된 세션을 반환하며 만료가 임박한 경우 자동으로 refresh 토큰을 교체합니다.
`getAccessToken() async throws -> String`	유효한 액세스 토큰 문자열을 반환하며 필요 시 자동으로 갱신합니다.
`signOut() async throws`	Keychain 토큰을 삭제하고 로컬 세션을 폐기합니다.

sdk/ios와의 관계

macOS SDK는 sdk/ios와 동일한 Swift 구현 패턴을 공유합니다. 브라우저 기반 인증에는 ASWebAuthenticationSession, PKCE S256에는 CryptoKit, 토큰 저장에는 Keychain을 사용합니다. 두 패키지는 플랫폼별 entitlement 구성을 위해 서로 다른 Apple 플랫폼 최솟값을 타깃으로 하며 별도로 관리됩니다.

보안

공개 클라이언트 — client secret이 저장되거나 전송되지 않습니다.
PKCE S256만 사용합니다. 서버는 plain challenge 방식을 거부합니다.
요청마다 생성되는 OAuth state; CSRF를 방지하기 위해 리디렉션 시 검증됩니다.
디바이스 전용 접근으로 Keychain에 저장된 토큰; iCloud Keychain에 동기화되지 않습니다.

알려진 제한 사항

JWKS 기반 ES256/RS256 ID token 검증과 end_session logout은 구현되어 로컬 테스트를 통과했습니다. L4 지원 전에는 macOS Keychain과 IdP 검증이 필요합니다.
sdk/ios와의 공유 Swift 코어 추출이 계획되어 있지만 아직 완료되지 않았습니다. 각 패키지는 자체 구현 사본을 가지고 있습니다.