From ebab820125a6615ead06bda25bf5143f6decd43e Mon Sep 17 00:00:00 2001 From: Kevin McKee Date: Thu, 3 Jul 2025 15:29:07 -0700 Subject: [PATCH] Improving documentation. --- .../OAuthKit/OAuthKit.docc/Configuration.md | 81 +++++++++++++++++++ .../Extensions/EnvironmentValues.md | 9 +++ .../OAuthKit.docc/Extensions/OAWebView.md | 10 +++ .../Extensions/OAWebViewCoordinator.md | 10 +++ .../OAuthKit/OAuthKit.docc/GettingStarted.md | 3 +- Sources/OAuthKit/OAuthKit.docc/OAuthKit.md | 8 +- Sources/OAuthKit/OAuthKit.docc/SampleCode.md | 2 +- Sources/OAuthKit/Views/OAWebView.swift | 2 +- 8 files changed, 121 insertions(+), 4 deletions(-) create mode 100644 Sources/OAuthKit/OAuthKit.docc/Configuration.md create mode 100644 Sources/OAuthKit/OAuthKit.docc/Extensions/EnvironmentValues.md create mode 100644 Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebView.md create mode 100644 Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebViewCoordinator.md diff --git a/Sources/OAuthKit/OAuthKit.docc/Configuration.md b/Sources/OAuthKit/OAuthKit.docc/Configuration.md new file mode 100644 index 0000000..45d3108 --- /dev/null +++ b/Sources/OAuthKit/OAuthKit.docc/Configuration.md @@ -0,0 +1,81 @@ +# OAuthKit Configuration + +Explore advanced OAuth configuration options such as Keychain protection and private browsing. + +@Metadata { + @PageKind(article) + @PageColor(red) + @Available(iOS, introduced: "18.0") + @Available(macOS, introduced: "15.0") + @Available(tvOS, introduced: "18.0") + @Available(visionOS, introduced: "2.0") + @Available(watchOS, introduced: "11.0") +} + +## Overview + +Both of the ``OAuth`` initializers ``OAuth/init(providers:options:)`` and ``OAuth/init(_:options:)`` accept a dictionary of `[OAuth.Option:Any]` which can be used to configure the loading and runtime options. + +### Application Tag +The ``OAuth/Option/applicationTag`` option is used to create unique keys for access tokens that are stored inside the Keychain. Typically, an app would set this value to be the same as their Bundle identifier. + +```swift +let options: [OAuth.Option: Any] = [ + .applicationTag: "com.oauthkit.Sampler", +] +let oauth: OAuth = .init(.main, options: options) +``` + +### Auto Refresh +The ``OAuth/Option/autoRefresh`` option is used to determine if tokens should be auto refreshed when they expire or not. This value is true by default. + +```swift +let options: [OAuth.Option: Any] = [ + .autoRefresh: false, +] +let oauth: OAuth = .init(.main, options: options) +``` + +### URL Session +The ``OAuth/Option/urlSession`` option is used to pass in a custom URLSession that will be used by your ``OAuth`` object to support any custom protocols or URL schemes that your app supports.This allows developers to register any custom URLProtocol classes that can handle the loading of protocol-specific URL data. + +```swift +// Custom URLSession +let configuration: URLSessionConfiguration = .ephemeral +configuration.protocolClasses = [CustomURLProtocol.self] +let urlSession: URLSession = .init(configuration: configuration) + +let options: [OAuth.Option: Any] = [.urlSession: urlSession] +``` + +### Private Browsing +The ``OAuth/Option/useNonPersistentWebDataStore`` option allows developers to implement private browsing inside the ``OAWebView``. Setting this value to true forces the ``OAWebView`` to use a non-persistent data store, preventing data from being written to the file system. + +```swift +let options: [OAuth.Option: Any] = [ + .useNonPersistentWebDataStore: true, +] +let oauth: OAuth = .init(.module, options: options) +``` + +### Keychain Protection +The ``OAuth/Option/requireAuthenticationWithBiometricsOrCompanion`` option allows you to protect access to your keychain items with biometrics until successful local authentication. If the ``OAuth/Option/requireAuthenticationWithBiometricsOrCompanion`` option is set to true, the device owner will need to be authenticated by biometry or a companion device before keychain items (tokens) can be accessed. OAuthKit uses a default LAContext, but if you need fine-grained control while evaluating a user’s identity, pass your own custom LAContext to the options via the ``OAuth/Option/localAuthentication`` option. + +```swift +// Custom LAContext +let localAuthentication: LAContext = .init() +localAuthentication.localizedReason = "read tokens from keychain" +localAuthentication.localizedFallbackTitle = "Use password" +localAuthentication.touchIDAuthenticationAllowableReuseDuration = 10 + +let options: [OAuth.Option: Any] = [ + .localAuthentication: localAuthentication, + .requireAuthenticationWithBiometricsOrCompanion: true +] +let oauth: OAuth = .init(.module, options: options) +``` + +> Important: The ``OAuth/Option/requireAuthenticationWithBiometricsOrCompanion`` is only available on iOS, macOS, and visionOS. + +> Tip: See ``OAuth/Option`` for a complete list of configuration options. + diff --git a/Sources/OAuthKit/OAuthKit.docc/Extensions/EnvironmentValues.md b/Sources/OAuthKit/OAuthKit.docc/Extensions/EnvironmentValues.md new file mode 100644 index 0000000..d44de33 --- /dev/null +++ b/Sources/OAuthKit/OAuthKit.docc/Extensions/EnvironmentValues.md @@ -0,0 +1,9 @@ +# ``OAuthKit/SwiftUICore/EnvironmentValues`` +@Metadata { + @Available(iOS, introduced: "18.0") + @Available(macOS, introduced: "15.0") + @Available(tvOS, introduced: "18.0") + @Available(visionOS, introduced: "2.0") + @Available(watchOS, introduced: "11.0") +} + diff --git a/Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebView.md b/Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebView.md new file mode 100644 index 0000000..aedde86 --- /dev/null +++ b/Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebView.md @@ -0,0 +1,10 @@ +# ``OAuthKit/OAWebView`` +@Metadata { + @Available(iOS, introduced: "18.0") + @Available(macOS, introduced: "15.0") + @Available(visionOS, introduced: "2.0") +} + +> Important: The ``OAWebView`` is only available for Apple operating systems with browsers. If you want to start +an ``OAuth/authorize(provider:grantType:)`` flow on tvOS or watchOS, be sure to use the +``OAuth/GrantType/deviceCode`` grant Type. See for more details. diff --git a/Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebViewCoordinator.md b/Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebViewCoordinator.md new file mode 100644 index 0000000..cad5e55 --- /dev/null +++ b/Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebViewCoordinator.md @@ -0,0 +1,10 @@ +# ``OAuthKit/OAWebViewCoordinator`` +@Metadata { + @Available(iOS, introduced: "18.0") + @Available(macOS, introduced: "15.0") + @Available(visionOS, introduced: "2.0") +} + +> Important: The ``OAWebViewCoordinator`` is only available for Apple operating systems with browsers. If you want to start +an ``OAuth/authorize(provider:grantType:)`` flow on tvOS or watchOS, be sure to use the +``OAuth/GrantType/deviceCode`` grant Type. See for more details. diff --git a/Sources/OAuthKit/OAuthKit.docc/GettingStarted.md b/Sources/OAuthKit/OAuthKit.docc/GettingStarted.md index 84d01ba..df3b4c5 100644 --- a/Sources/OAuthKit/OAuthKit.docc/GettingStarted.md +++ b/Sources/OAuthKit/OAuthKit.docc/GettingStarted.md @@ -1,9 +1,10 @@ # Getting Started with OAuthKit -Create an ``OAuth`` instance and start an authorization flow. +Learn how to create an observable OAuth instance and start an authorization flow. @Metadata { @PageKind(article) + @PageColor(yellow) @Available(iOS, introduced: "18.0") @Available(macOS, introduced: "15.0") @Available(tvOS, introduced: "18.0") diff --git a/Sources/OAuthKit/OAuthKit.docc/OAuthKit.md b/Sources/OAuthKit/OAuthKit.docc/OAuthKit.md index fd294b2..cba9fc8 100644 --- a/Sources/OAuthKit/OAuthKit.docc/OAuthKit.md +++ b/Sources/OAuthKit/OAuthKit.docc/OAuthKit.md @@ -17,10 +17,16 @@ OAuthKit offers a robust, type-safe, and performant OAuth 2.0 implementation usi This has the advantage of avoiding direct coupling with an authorization flow, enabling highly flexible and fine-grained control when interacting with an ``OAuth/Provider``. It also allows updates across multiple observers. -### Featured +### Articles @Links(visualStyle: detailedGrid) { - + - +} + +### Sample code + +@Links(visualStyle: detailedGrid) { - } diff --git a/Sources/OAuthKit/OAuthKit.docc/SampleCode.md b/Sources/OAuthKit/OAuthKit.docc/SampleCode.md index 4d22238..0da2eda 100644 --- a/Sources/OAuthKit/OAuthKit.docc/SampleCode.md +++ b/Sources/OAuthKit/OAuthKit.docc/SampleCode.md @@ -1,4 +1,4 @@ -# OAuthKit Sample: Integrating OAuthKit into an App +# OAuthSample: Integrating OAuthKit into an App Integrate OAuthKit into a multiplatform app with support for iOS, macOS, tvOS, visionOS, and watchOS. diff --git a/Sources/OAuthKit/Views/OAWebView.swift b/Sources/OAuthKit/Views/OAWebView.swift index 7e9069b..1a4cdfd 100644 --- a/Sources/OAuthKit/Views/OAWebView.swift +++ b/Sources/OAuthKit/Views/OAWebView.swift @@ -17,7 +17,7 @@ public struct OAWebView { let oauth: OAuth let view: WKWebView - /// Initializer with the speciifed oauth object, + /// Initializer with the speciifed oauth object. /// - Parameter oauth: the oauth object to use public init(oauth: OAuth) { self.oauth = oauth