enigma-memory 0.1.18 → 0.1.22

package/apps/ios/EnigmaIOS/Enigma/CreateView.swift

@@ -0,0 +1,152 @@
+import AVKit
+import EnigmaCore
+import SwiftUI
+
+private enum CreationMode: String, CaseIterable, Identifiable {
+    case image = "Images"
+    case video = "Video"
+    case code = "Code"
+    var id: String { rawValue }
+}
+
+struct CreateView: View {
+    @EnvironmentObject private var model: AppModel
+    @State private var mode: CreationMode = .image
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 20) {
+                Picker("Mode", selection: $mode) {
+                    ForEach(CreationMode.allCases) { option in Text(option.rawValue).tag(option) }
+                }
+                .pickerStyle(.segmented)
+                switch mode {
+                case .image: ImageToolView()
+                case .video: VideoToolView()
+                case .code: CodeToolView()
+                }
+            }
+            .padding(20)
+            .padding(.bottom, 32)
+        }
+        .navigationTitle("Create")
+        .navigationBarTitleDisplayMode(.inline)
+        .enigmaCanvas()
+    }
+}
+
+private struct ImageToolView: View {
+    @EnvironmentObject private var model: AppModel
+    @State private var prompt = ""
+    @State private var selectedModel = ""
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 18) {
+            intro("ENIGMA IMAGE", "Generate without building a prompt archive.", "Prompts are minimized on-device. Returned assets remain caller-controlled.")
+            Picker("Image model", selection: $selectedModel) {
+                Text("Choose image model").tag("")
+                ForEach(model.imageModels) { route in Text(route.id).tag(route.id) }
+            }
+            .pickerStyle(.menu)
+            TextField("Describe the image…", text: $prompt, axis: .vertical)
+                .lineLimit(5...10)
+                .padding(12)
+                .background(.white)
+                .overlay(RoundedRectangle(cornerRadius: 10).stroke(EnigmaTheme.line))
+            Button("Generate image") { Task { await model.generateImage(prompt: prompt, model: selectedModel) } }
+                .buttonStyle(PrimaryButtonStyle())
+                .disabled(prompt.isEmpty || selectedModel.isEmpty || model.isBusy)
+            ForEach(Array(model.generatedImages.enumerated()), id: \.offset) { _, asset in
+                image(asset)
+                    .frame(maxWidth: .infinity)
+                    .aspectRatio(1, contentMode: .fit)
+                    .background(Color.black.opacity(0.04))
+                    .clipShape(RoundedRectangle(cornerRadius: 12))
+            }
+        }
+        .onAppear { if selectedModel.isEmpty { selectedModel = model.imageModels.first?.id ?? "" } }
+    }
+
+    @ViewBuilder private func image(_ asset: GeneratedImageAsset) -> some View {
+        if let raw = asset.base64, let data = Data(base64Encoded: raw), let uiImage = UIImage(data: data) {
+            Image(uiImage: uiImage).resizable().scaledToFit()
+        } else if let value = asset.url, let url = URL(string: value) {
+            AsyncImage(url: url) { phase in
+                if let image = phase.image { image.resizable().scaledToFit() }
+                else if phase.error != nil { ContentUnavailableView("Image unavailable", systemImage: "photo") }
+                else { ProgressView() }
+            }
+        } else { ContentUnavailableView("Image unavailable", systemImage: "photo") }
+    }
+}
+
+private struct VideoToolView: View {
+    @EnvironmentObject private var model: AppModel
+    @State private var prompt = ""
+    @State private var selectedModel = ""
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 18) {
+            intro("ENIGMA VIDEO", "Queue private motion generation.", "Progress is bounded job metadata. The final artifact belongs to you.")
+            Picker("Video model", selection: $selectedModel) {
+                Text("Choose video model").tag("")
+                ForEach(model.videoModels) { route in Text(route.id).tag(route.id) }
+            }
+            TextField("Describe motion, scene, and camera…", text: $prompt, axis: .vertical)
+                .lineLimit(5...10)
+                .padding(12)
+                .background(.white)
+                .overlay(RoundedRectangle(cornerRadius: 10).stroke(EnigmaTheme.line))
+            Button("Queue video") { Task { await model.queueVideo(prompt: prompt, model: selectedModel) } }
+                .buttonStyle(PrimaryButtonStyle())
+                .disabled(prompt.isEmpty || selectedModel.isEmpty || model.isBusy)
+            if let job = model.videoJob {
+                VStack(alignment: .leading, spacing: 9) {
+                    HStack { Text(job.status.capitalized).font(.subheadline.weight(.semibold)); Spacer(); Text("\(Int(job.progress))%") }
+                    ProgressView(value: job.progress, total: 100).tint(EnigmaTheme.ember)
+                    if let error = job.error { Text(error).foregroundStyle(.red).font(.footnote) }
+                }
+                .enigmaSurface()
+            }
+            if let value = model.videoAsset?.url, let url = URL(string: value) {
+                VideoPlayer(player: AVPlayer(url: url)).frame(height: 230).clipShape(RoundedRectangle(cornerRadius: 12))
+            }
+        }
+        .onAppear { if selectedModel.isEmpty { selectedModel = model.videoModels.first?.id ?? "" } }
+    }
+}
+
+private struct CodeToolView: View {
+    @EnvironmentObject private var model: AppModel
+    @State private var source = "console.log('Enigma sandbox ready')"
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 18) {
+            intro("ENIGMA CODE", "Run below an OCI boundary.", "No network. Read-only root. No Linux capabilities. The session is burned after every run.")
+            TextEditor(text: $source)
+                .font(.system(.body, design: .monospaced))
+                .frame(minHeight: 240)
+                .padding(10)
+                .scrollContentBackground(.hidden)
+                .background(Color(red: 0.07, green: 0.065, blue: 0.06))
+                .foregroundStyle(Color(red: 0.93, green: 0.91, blue: 0.86))
+                .clipShape(RoundedRectangle(cornerRadius: 10))
+            Button("Create, run, and burn") { Task { await model.executeCode(source) } }
+                .buttonStyle(PrimaryButtonStyle())
+                .disabled(source.isEmpty || model.isBusy)
+            Text(model.codeOutput.isEmpty ? "No sandbox output." : model.codeOutput)
+                .font(.system(.footnote, design: .monospaced))
+                .textSelection(.enabled)
+                .frame(maxWidth: .infinity, minHeight: 120, alignment: .topLeading)
+                .enigmaSurface()
+        }
+    }
+}
+
+@ViewBuilder private func intro(_ eyebrow: String, _ title: String, _ description: String) -> some View {
+    VStack(alignment: .leading, spacing: 8) {
+        SectionEyebrow(text: eyebrow)
+        Text(title).font(EnigmaTheme.title)
+        Text(description).font(.subheadline).foregroundStyle(EnigmaTheme.secondary)
+    }
+}

package/apps/ios/EnigmaIOS/Enigma/EnigmaApp.swift

@@ -0,0 +1,52 @@
+import SwiftUI
+
+@main
+struct EnigmaApp: App {
+    @StateObject private var model = AppModel()
+
+    var body: some Scene {
+        WindowGroup {
+            RootView()
+                .environmentObject(model)
+                .preferredColorScheme(.light)
+        }
+    }
+}
+
+struct RootView: View {
+    @EnvironmentObject private var model: AppModel
+
+    var body: some View {
+        Group {
+            if model.isConnected {
+                TabView {
+                    NavigationStack { ChatView() }
+                        .tabItem { Label("Chat", systemImage: "bubble.left") }
+                    NavigationStack { CouncilView() }
+                        .tabItem { Label("Council", systemImage: "point.3.connected.trianglepath.dotted") }
+                    NavigationStack { CreateView() }
+                        .tabItem { Label("Create", systemImage: "sparkles.rectangle.stack") }
+                    NavigationStack { PrivateVaultView() }
+                        .tabItem { Label("Private", systemImage: "lock.square") }
+                }
+                .tint(EnigmaTheme.ember)
+            } else {
+                OnboardingView()
+            }
+        }
+        .enigmaCanvas()
+        .overlay(alignment: .top) {
+            if model.isBusy {
+                ProgressView().tint(EnigmaTheme.ember).padding(.top, 8)
+            }
+        }
+        .alert("Enigma", isPresented: Binding(
+            get: { model.errorMessage != nil },
+            set: { if !$0 { model.errorMessage = nil } }
+        )) {
+            Button("Dismiss", role: .cancel) { model.errorMessage = nil }
+        } message: {
+            Text(model.errorMessage ?? "")
+        }
+    }
+}

package/apps/ios/EnigmaIOS/Enigma/Info.plist

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDisplayName</key>
+  <string>Enigma</string>
+  <key>CFBundleIdentifier</key>
+  <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>$(PRODUCT_NAME)</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleTypeRole</key>
+      <string>Editor</string>
+      <key>CFBundleURLName</key>
+      <string>com.enigmamemory.ios.oauth</string>
+      <key>CFBundleURLSchemes</key>
+      <array><string>enigma-ios</string></array>
+    </dict>
+  </array>
+  <key>LSRequiresIPhoneOS</key>
+  <true/>
+  <key>NSAppTransportSecurity</key>
+  <dict>
+    <key>NSAllowsLocalNetworking</key>
+    <true/>
+  </dict>
+  <key>UIApplicationSceneManifest</key>
+  <dict>
+    <key>UIApplicationSupportsMultipleScenes</key>
+    <false/>
+  </dict>
+  <key>UILaunchScreen</key>
+  <dict>
+    <key>UIColorName</key>
+    <string>LaunchBackground</string>
+  </dict>
+  <key>UISupportedInterfaceOrientations</key>
+  <array>
+    <string>UIInterfaceOrientationPortrait</string>
+  </array>
+</dict>
+</plist>

package/apps/ios/EnigmaIOS/Enigma/NaturalLanguagePrivacyTagger.swift

@@ -0,0 +1,26 @@
+import EnigmaCore
+import Foundation
+import NaturalLanguage
+
+struct NaturalLanguagePrivacyTagger: SemanticPrivacyTagging {
+    private let fallback = HeuristicSemanticPrivacyTagger()
+
+    func findings(in text: String) -> [SemanticPrivacyFinding] {
+        var output = fallback.findings(in: text)
+        let tagger = NLTagger(tagSchemes: [.nameType])
+        tagger.string = text
+        let options: NLTagger.Options = [.omitWhitespace, .omitPunctuation, .joinNames]
+        tagger.enumerateTags(in: text.startIndex..<text.endIndex, unit: .word, scheme: .nameType, options: options) { tag, range in
+            let category: PrivacyCategory?
+            switch tag {
+            case .personalName: category = .person
+            case .placeName: category = .location
+            case .organizationName: category = .organization
+            default: category = nil
+            }
+            if let category { output.append(.init(range: range, category: category)) }
+            return true
+        }
+        return output
+    }
+}

package/apps/ios/EnigmaIOS/Enigma/OAuthClient.swift

@@ -0,0 +1,321 @@
+import AuthenticationServices
+import EnigmaCore
+import Foundation
+import UIKit
+
+private final class WebAuthenticationAnchor: NSObject, ASWebAuthenticationPresentationContextProviding {
+    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
+        let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
+        return scenes.flatMap(\.windows).first(where: \.isKeyWindow) ?? ASPresentationAnchor()
+    }
+}
+
+
+@MainActor
+private final class WebAuthenticationRunner {
+    private let anchor = WebAuthenticationAnchor()
+    private var session: ASWebAuthenticationSession?
+
+    func run(url: URL) async throws -> URL {
+        try await withCheckedThrowingContinuation { continuation in
+            session = ASWebAuthenticationSession(url: url, callbackURLScheme: "enigma-ios") { [weak self] url, error in
+                self?.session = nil
+                if let error { continuation.resume(throwing: error) }
+                else if let url { continuation.resume(returning: url) }
+                else { continuation.resume(throwing: OAuthClientError.invalidCallback) }
+            }
+            session?.presentationContextProvider = anchor
+            session?.prefersEphemeralWebBrowserSession = true
+            if session?.start() != true {
+                session = nil
+                continuation.resume(throwing: OAuthClientError.invalidCallback)
+            }
+        }
+    }
+}
+enum OAuthClientError: LocalizedError {
+    case invalidIssuer
+    case invalidResource
+    case invalidMetadata
+    case invalidCallback
+    case stateMismatch
+    case unsupportedScopes([String])
+    case registrationUnavailable
+    case registrationFailed(String)
+    case authorizationDenied(String)
+    case tokenExchangeFailed(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidIssuer: return "The OAuth issuer must use HTTPS, or loopback HTTP for local development."
+        case .invalidResource: return "The protected resource must be a canonical HTTPS URL, or loopback HTTP URL for local development."
+        case .invalidMetadata: return "The authorization server metadata is invalid."
+        case .invalidCallback: return "The OAuth callback was invalid."
+        case .stateMismatch: return "OAuth state verification failed."
+        case let .unsupportedScopes(scopes): return "The authorization server does not support: \(scopes.joined(separator: ", "))."
+        case .registrationUnavailable: return "Enter a registered public client ID; this authorization server does not offer approved dynamic registration."
+        case let .registrationFailed(reason): return reason
+        case let .authorizationDenied(reason): return reason
+        case let .tokenExchangeFailed(reason): return reason
+        }
+    }
+}
+
+private struct OAuthPublicClientRegistrationRequest: Encodable {
+    let clientName: String
+    let redirectURIs: [String]
+    let grantTypes: [String]
+    let responseTypes: [String]
+    let tokenEndpointAuthMethod: String
+    let scope: String
+
+    enum CodingKeys: String, CodingKey {
+        case clientName = "client_name"
+        case redirectURIs = "redirect_uris"
+        case grantTypes = "grant_types"
+        case responseTypes = "response_types"
+        case tokenEndpointAuthMethod = "token_endpoint_auth_method"
+        case scope
+    }
+}
+
+private struct OAuthPublicClientRegistrationResponse: Decodable {
+    let clientID: String
+    let redirectURIs: [String]
+    let tokenEndpointAuthMethod: String
+    let scope: String
+
+    enum CodingKeys: String, CodingKey {
+        case clientID = "client_id"
+        case redirectURIs = "redirect_uris"
+        case tokenEndpointAuthMethod = "token_endpoint_auth_method"
+        case scope
+    }
+}
+
+struct OAuthClient {
+    static let redirectURI = "enigma-ios://oauth/callback"
+    static let platformScopes = EnigmaOAuthScopes.iOSPlatform
+
+    @MainActor
+    func authorize(issuer: URL, clientID: String?, resource: URL, scopes: [String] = platformScopes) async throws -> OAuthCredential {
+        guard let protectedResource = Self.canonicalResource(resource) else { throw OAuthClientError.invalidResource }
+        let metadata = try await Self.metadata(issuer: issuer)
+        let requestedScopes = Array(Set(scopes)).sorted()
+        if let supportedScopes = metadata.scopesSupported {
+            let missing = requestedScopes.filter { !supportedScopes.contains($0) }
+            if !missing.isEmpty { throw OAuthClientError.unsupportedScopes(missing) }
+        }
+        let suppliedClientID = clientID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let resolvedClientID: String
+        if suppliedClientID.isEmpty {
+            resolvedClientID = try await Self.registerPublicClient(metadata: metadata, scopes: requestedScopes)
+        } else {
+            resolvedClientID = suppliedClientID
+        }
+        let pkce = PKCE.create()
+        let state = UUID().uuidString
+        guard let endpoint = Self.secureEndpoint(metadata.authorizationEndpoint),
+              var components = URLComponents(url: endpoint, resolvingAgainstBaseURL: false) else {
+            throw OAuthClientError.invalidMetadata
+        }
+        components.queryItems = [
+            URLQueryItem(name: "response_type", value: "code"),
+            URLQueryItem(name: "client_id", value: resolvedClientID),
+            URLQueryItem(name: "redirect_uri", value: Self.redirectURI),
+            URLQueryItem(name: "scope", value: requestedScopes.joined(separator: " ")),
+            URLQueryItem(name: "state", value: state),
+            URLQueryItem(name: "code_challenge", value: pkce.challenge),
+            URLQueryItem(name: "code_challenge_method", value: "S256"),
+            URLQueryItem(name: "resource", value: protectedResource.absoluteString),
+        ]
+        guard let authorizationURL = components.url else { throw OAuthClientError.invalidMetadata }
+        let callback = try await WebAuthenticationRunner().run(url: authorizationURL)
+        guard let callbackComponents = URLComponents(url: callback, resolvingAgainstBaseURL: false) else { throw OAuthClientError.invalidCallback }
+        let values = Dictionary(uniqueKeysWithValues: callbackComponents.queryItems?.map { ($0.name, $0.value ?? "") } ?? [])
+        if let error = values["error"] { throw OAuthClientError.authorizationDenied(values["error_description"] ?? error) }
+        guard values["state"] == state else { throw OAuthClientError.stateMismatch }
+        guard let code = values["code"], !code.isEmpty else { throw OAuthClientError.invalidCallback }
+        if let responseIssuer = values["iss"], responseIssuer != metadata.issuer { throw OAuthClientError.invalidCallback }
+        let tokens = try await Self.tokenRequest(
+            endpoint: metadata.tokenEndpoint,
+            fields: [
+                "grant_type": "authorization_code",
+                "client_id": resolvedClientID,
+                "code": code,
+                "redirect_uri": Self.redirectURI,
+                "code_verifier": pkce.verifier,
+                "resource": protectedResource.absoluteString,
+            ]
+        )
+        return OAuthCredential(
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: Date().addingTimeInterval(TimeInterval(tokens.expiresIn)),
+            clientID: resolvedClientID,
+            issuer: issuer,
+            resource: protectedResource
+        )
+    }
+
+    private static func registerPublicClient(metadata: OAuthAuthorizationServerMetadata, scopes: [String]) async throws -> String {
+        guard let value = metadata.registrationEndpoint, let endpoint = secureEndpoint(value) else {
+            throw OAuthClientError.registrationUnavailable
+        }
+        var request = URLRequest(url: endpoint, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 30)
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.setValue("application/json", forHTTPHeaderField: "Accept")
+        request.httpBody = try JSONEncoder().encode(OAuthPublicClientRegistrationRequest(
+            clientName: "Enigma for iOS",
+            redirectURIs: [redirectURI],
+            grantTypes: ["authorization_code", "refresh_token"],
+            responseTypes: ["code"],
+            tokenEndpointAuthMethod: "none",
+            scope: scopes.joined(separator: " ")
+        ))
+        let (data, response) = try await URLSession.shared.data(for: request)
+        guard let http = response as? HTTPURLResponse else { throw OAuthClientError.invalidMetadata }
+        guard (200..<300).contains(http.statusCode),
+              let registration = try? JSONDecoder().decode(OAuthPublicClientRegistrationResponse.self, from: data) else {
+            let reason = (try? JSONSerialization.jsonObject(with: data) as? [String: Any])?["error_description"] as? String
+            throw OAuthClientError.registrationFailed(reason ?? "OAuth public-client registration failed.")
+        }
+        let registeredScopes = Set(registration.scope.split(separator: " ").map(String.init))
+        guard !registration.clientID.isEmpty,
+              registration.redirectURIs.contains(redirectURI),
+              registration.tokenEndpointAuthMethod == "none",
+              Set(scopes).isSubset(of: registeredScopes) else {
+            throw OAuthClientError.registrationFailed("OAuth server returned an unsafe or incomplete public-client registration.")
+        }
+        return registration.clientID
+    }
+
+    private static func secureEndpoint(_ value: String) -> URL? {
+        guard let url = URL(string: value),
+              let scheme = url.scheme?.lowercased(),
+              let host = url.host?.lowercased(),
+              url.user == nil,
+              url.password == nil,
+              url.fragment == nil else { return nil }
+        let loopback = ["localhost", "127.0.0.1", "::1"].contains(host)
+        return scheme == "https" || (scheme == "http" && loopback) ? url : nil
+    }
+
+    private static func canonicalResource(_ value: URL) -> URL? {
+        guard let secured = secureEndpoint(value.absoluteString),
+              var components = URLComponents(url: secured, resolvingAgainstBaseURL: false),
+              components.query == nil else { return nil }
+        if components.path == "/" { components.path = "" }
+        return components.url
+    }
+
+    static func refresh(_ credential: OAuthCredential) async throws -> OAuthCredential {
+        guard let refreshToken = credential.refreshToken else { throw EnigmaAPIError.unauthenticated }
+        guard let protectedResource = canonicalResource(credential.resource) else { throw OAuthClientError.invalidResource }
+        let metadata = try await metadata(issuer: credential.issuer)
+        let tokens = try await tokenRequest(
+            endpoint: metadata.tokenEndpoint,
+            fields: [
+                "grant_type": "refresh_token",
+                "client_id": credential.clientID,
+                "refresh_token": refreshToken,
+                "resource": protectedResource.absoluteString,
+            ]
+        )
+        return OAuthCredential(
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken ?? refreshToken,
+            expiresAt: Date().addingTimeInterval(TimeInterval(tokens.expiresIn)),
+            clientID: credential.clientID,
+            issuer: credential.issuer,
+            resource: protectedResource
+        )
+    }
+
+    static func metadata(issuer: URL) async throws -> OAuthAuthorizationServerMetadata {
+        guard let securedIssuer = secureEndpoint(issuer.absoluteString),
+              var components = URLComponents(url: securedIssuer, resolvingAgainstBaseURL: false),
+              components.query == nil,
+              components.path.isEmpty || components.path == "/" else {
+            throw OAuthClientError.invalidIssuer
+        }
+        components.path = ""
+        guard let canonicalIssuer = components.url else { throw OAuthClientError.invalidIssuer }
+        let url = canonicalIssuer.appending(path: ".well-known/oauth-authorization-server")
+        var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 20)
+        request.setValue("application/json", forHTTPHeaderField: "Accept")
+        let (data, response) = try await URLSession.shared.data(for: request)
+        guard let http = response as? HTTPURLResponse, http.statusCode == 200,
+              let metadata = try? JSONDecoder().decode(OAuthAuthorizationServerMetadata.self, from: data),
+              metadata.issuer == canonicalIssuer.absoluteString.trimmingCharacters(in: CharacterSet(charactersIn: "/")) else {
+            throw OAuthClientError.invalidMetadata
+        }
+        return metadata
+    }
+
+    private static func tokenRequest(endpoint: String, fields: [String: String]) async throws -> OAuthTokenResponse {
+        guard let url = secureEndpoint(endpoint) else { throw OAuthClientError.invalidMetadata }
+        var request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: 30)
+        request.httpMethod = "POST"
+        request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
+        request.setValue("application/json", forHTTPHeaderField: "Accept")
+        var form = URLComponents()
+        form.queryItems = fields.sorted { $0.key < $1.key }.map { URLQueryItem(name: $0.key, value: $0.value) }
+        request.httpBody = form.percentEncodedQuery?.data(using: .utf8)
+        let (data, response) = try await URLSession.shared.data(for: request)
+        guard let http = response as? HTTPURLResponse else { throw OAuthClientError.invalidMetadata }
+        guard (200..<300).contains(http.statusCode), let tokens = try? JSONDecoder().decode(OAuthTokenResponse.self, from: data) else {
+            let reason = (try? JSONSerialization.jsonObject(with: data) as? [String: Any])?["error_description"] as? String
+            throw OAuthClientError.tokenExchangeFailed(reason ?? "OAuth token exchange failed.")
+        }
+        guard tokens.tokenType.lowercased() == "bearer" else { throw OAuthClientError.tokenExchangeFailed("OAuth server returned an unsupported token type.") }
+        return tokens
+    }
+}
+
+actor CredentialBroker {
+    private let store = SecureStore()
+    private let account = "oauth-credential"
+    private var credential: OAuthCredential?
+    private var directToken: String?
+
+    init() {
+        if let data = try? store.data(account: account) {
+            credential = try? JSONDecoder().decode(OAuthCredential.self, from: data)
+        }
+        directToken = try? store.string(account: "direct-token")
+    }
+
+    func accessToken() async throws -> String? {
+        if let directToken { return directToken }
+        guard var credential else { return nil }
+        if credential.expiresAt.timeIntervalSinceNow < 60 {
+            credential = try await OAuthClient.refresh(credential)
+            self.credential = credential
+            try store.set(JSONEncoder().encode(credential), account: account)
+        }
+        return credential.accessToken
+    }
+
+    func save(_ credential: OAuthCredential) throws {
+        self.credential = credential
+        directToken = nil
+        try store.remove(account: "direct-token")
+        try store.set(JSONEncoder().encode(credential), account: account)
+    }
+
+    func saveDirectToken(_ value: String) throws {
+        credential = nil
+        directToken = value
+        try store.remove(account: account)
+        try store.setString(value, account: "direct-token")
+    }
+
+    func clear() throws {
+        credential = nil
+        directToken = nil
+        try store.remove(account: account)
+        try store.remove(account: "direct-token")
+    }
+}