---
title: "sdk/macos"
description: "Swift SDK for macOS using ASWebAuthenticationSession, PKCE S256 authorization code flow, and Keychain token storage. Shares the implementation pattern with sdk/ios."
locale: "en"
---

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

# sdk/macos

## Status

Package status is **Implemented and verified locally**. The Swift unit-test suite passes on macOS. Keychain access, the complete ASWebAuthenticationSession callback, and a real IdP round-trip still require desktop integration evidence. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

## 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:

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

## Quick start

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

## Core API

| Method | Description |
| --- | --- |
| `configure(_ options:)` | Set issuer, clientId, redirectUri, and scopes. Call before all other methods. |
| `signIn() async throws -> VonvonSession` | Launch ASWebAuthenticationSession, complete PKCE S256 authorization code flow, persist tokens to Keychain, and return a session. |
| `handleRedirect(_ url:) async throws -> VonvonSession` | Process a redirect URL from an external source and exchange the code for tokens. |
| `getSession() async throws -> VonvonSession?` | Return the current unexpired macOS session; expired token state is cleared and the method returns nil. |
| `getAccessToken() async throws -> String` | Return the current unexpired access token. The SDK rejects offline\_access until DPoP is implemented; expiry requires reauthorization. |
| `signOut() async throws` | Clear Keychain tokens and optionally call the end\_session endpoint; no refresh-token revocation is performed. |

## 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.

Source: https://vonvon.id/sdks/macos/index.mdx