---
title: "sdk/macos"
description: "适用于 macOS 的 Swift SDK，使用 ASWebAuthenticationSession、PKCE S256 授权码流程和 Keychain token 存储。与 sdk/ios 共享实现模式。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/zh-hans/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/macos

## 状态

包状态为**已在本地实现并验证**。Swift 单元测试套件已在 macOS 上通过。Keychain 访问、完整的 ASWebAuthenticationSession callback 和真实 IdP 往返仍需桌面集成证据。本页记录的是已实现行为，不代表已具备生产就绪状态。

Registry 状态:UNPUBLISHED。此 SDK 只能从仓库源码 checkout 安装；不要使用外部 package registry。

## 要求

- macOS 13+
- Swift 5.9+ 和 Xcode 15+
- 无第三方依赖——使用 Apple 系统框架（AuthenticationServices、CryptoKit、Security）

## 安装

通过 Package.swift 中的 Swift Package Manager 添加：

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

## 快速开始

```swift
import Vonvon

let client = VonvonClient()

// 1. Configure. offline_access is rejected until DPoP is implemented.
client.configure(VonvonOptions(
issuer: URL(string: "https://vonvon.id")!,
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 -> VonvonSession` | 启动 ASWebAuthenticationSession，完成 PKCE S256 授权码流程，将 token 持久化到 Keychain，并返回会话。 |
| `handleRedirect(_ url:) async throws -> VonvonSession` | 处理来自外部来源的重定向 URL 并用 code 换取 token。 |
| `getSession() async throws -> VonvonSession?` | 返回当前未过期的 macOS 会话；过期的 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 用于浏览器授权，CryptoKit 用于 PKCE S256，Keychain 用于 token 存储。两个包面向不同的 Apple 平台最低版本要求，分别维护以支持各平台专有的权限配置。

## 安全

- 公共客户端——不存储或传输客户端密钥。
- 仅 PKCE S256。服务器拒绝 plain challenge 方式。
- 每次请求生成 OAuth state；在重定向时验证以防 CSRF。
- Token 存储在仅限设备访问的 Keychain 中，不同步到 iCloud Keychain。

## 已知限制

- 基于 JWKS 的 ES256/RS256 ID token 验签和 end\_session 登出已实现并完成本地测试。真实 macOS Keychain 和 IdP 往返验证前仍不具备 L4 支持。
- 与 sdk/ios 共享 Swift 核心提取已在计划中，但尚未完成——每个包携带自己的实现副本。

Source: https://vonvon.id/zh-hans/sdks/macos/index.mdx