sdk/macos

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

상태

Package 상태는 구현 및 로컬 검증 완료입니다. Swift 단위 테스트 suite가 macOS에서 통과했습니다. Keychain access, 전체 ASWebAuthenticationSession callback 및 실제 IdP round-trip에는 여전히 desktop integration evidence가 필요합니다. 이 페이지는 구현된 동작을 설명하며 production-ready 상태임을 주장하지 않습니다.

Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.

요구 사항

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

설치

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

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

빠른 시작

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

방법	설명
`configure(_ options:)`	issuer, clientId, redirectUri, scopes를 설정합니다. 다른 모든 메서드보다 먼저 호출하세요.
`signIn() async throws -> XidSession`	ASWebAuthenticationSession을 시작하고, PKCE S256 인증 코드 흐름을 완료하고, 토큰을 Keychain에 저장한 후 세션을 반환합니다.
`handleRedirect(_ url:) async throws -> XidSession`	외부 소스의 리디렉션 URL을 처리하고 코드를 토큰으로 교환합니다.
`getSession() async throws -> XidSession?`	현재 만료되지 않은 macOS session을 반환합니다. 만료된 token state를 지우고 nil을 반환합니다.
`getAccessToken() async throws -> String`	현재 만료되지 않은 access token을 반환합니다. DPoP가 구현될 때까지 SDK는 offline_access를 거부하며 token이 만료되면 다시 인증해야 합니다.
`signOut() async throws`	Keychain token을 지우고 필요하면 end_session endpoint를 호출합니다. refresh-token revocation은 수행하지 않습니다.

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 코어 추출이 계획되어 있지만 아직 완료되지 않았습니다. 각 패키지는 자체 구현 사본을 가지고 있습니다.