Merge branch 'master' into par-poc

Author: AlexNachbaur

.gitignore

@@ -44,7 +44,7 @@ playground.xcworkspace
 # Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
 # Packages/
 # Package.pins
-# Package.resolved
+Package.resolved
 .build/
 .swiftpm/
 

OktaAuthFoundation.podspec

@@ -1,7 +1,7 @@
 Pod::Spec.new do |s|
     s.name             = "OktaAuthFoundation"
     s.module_name      = "AuthFoundation"
-    s.version          = "2.1.4"
+    s.version          = "2.1.5"
     s.summary          = "Okta Authentication Foundation"
     s.description      = <<-DESC
 Provides the foundation and common features used to authenticate users, managing the lifecycle and storage of tokens and credentials, and provide a base for other Okta SDKs to build upon.

OktaBrowserSignin.podspec

@@ -1,7 +1,7 @@
 Pod::Spec.new do |s|
     s.name             = "OktaBrowserSignin"
     s.module_name      = "BrowserSignin"
-    s.version          = "2.1.4"
+    s.version          = "2.1.5"
     s.summary          = "Okta Browser Sign In UI"
     s.description      = <<-DESC
 Authenticate users using web-based OIDC.

OktaClient.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
     s.name         = "OktaClient"
-    s.version      = "2.1.4"
+    s.version      = "2.1.5"
     s.summary      = "Secure client authentication, request authorization, and user management capabilities for Swift."
     s.description  = <<-DESC
 Provides a modularized set of libraries that provide the building blocks and convenience features used to authenticate users, manage the lifecycle and storage of tokens and user credentials, and provide a base for other libraries and applications to build upon.

OktaDirectAuth.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
     s.name             = "OktaDirectAuth"
-    s.version          = "2.1.4"
+    s.version          = "2.1.5"
     s.summary          = "Okta Direct Authentication"
     s.description      = <<-DESC
 Enables application developers to build native sign in experiences using the Okta Direct Authentication API.

OktaIdxAuth.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
     s.name             = 'OktaIdxAuth'
-    s.version          = '2.1.4'
+    s.version          = '2.1.5'
     s.summary          = 'SDK to easily integrate the Okta Identity Engine'
     s.description      = <<-DESC
 Integrate your native app with Okta using the Okta Identity Engine library.

OktaOAuth2.podspec

@@ -1,7 +1,7 @@
 Pod::Spec.new do |s|
     s.name             = "OktaOAuth2"
     s.module_name      = "OAuth2Auth"
-    s.version          = "2.1.4"
+    s.version          = "2.1.5"
     s.summary          = "Okta OAuth2 Authentication"
     s.description      = <<-DESC
 Enables application developers to authenticate users utilizing a variety of OAuth2 authentication flows.

README.md

@@ -182,6 +182,53 @@ pod 'OktaIdxAuth'
 
 ## Usage Guide
 
+Every authentication flow follows the same two-method pattern defined by the
+`AuthenticationFlow` protocol:
+
+1. **`start()`** — initiates the flow (builds an authorize URL, sends
+   credentials, etc.) and returns either a token or an intermediate value
+   needed by the next step.
+2. **`resume()`** _(optional)_ — completes a multi-step flow by exchanging the
+   intermediate value for tokens (e.g., trading an authorization code for an
+   access token, polling for device authorization, etc.).
+
+Single-step flows such as Resource Owner, JWT Bearer, and Token Exchange
+resolve entirely in `start()`. Multi-step flows like Authorization Code and
+Device Authorization require a subsequent call to `resume()`.
+
+All flows accept an optional **authentication context** that carries
+cross-cutting parameters such as `audience`, `resource`, `nonce`, and
+`maxAge`. See [Authentication Context](#authentication-context) below for
+details.
+
+### Authentication Context
+
+All authentication flows accept an optional `context` parameter that carries cross-cutting authentication properties. Some flows require a specific context type (e.g., `AuthorizationCodeFlow.Context` for the Authorization Code flow), while simpler flows use `StandardAuthenticationContext`:
+
+```swift
+let flow = ResourceOwnerFlow(issuerURL: URL(string: "https://example.okta.com")!,
+                             clientId: "abc123client",
+                             scope: "openid offline_access email profile")
+let token = try await flow.start(
+    username: "jane@example.com",
+    password: "secretPassword",
+    context: .init(
+        audience: "api://my-resource-server",
+        resource: "https://api.example.com/v1",  // or an array of URIs
+        maxAge: 3600,
+        nonce: "custom-nonce"
+    )))
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `nonce` | `String?` | Custom nonce for ID token replay protection. |
+| `maxAge` | `TimeInterval?` | Maximum authentication age (seconds). |
+| `audience` | `String?` | Target resource server ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)). Sent in the token request. |
+| `resource` | `[String]?` | Target resource URI(s) ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)). Sent in the token request. Accepts a string literal or an array of strings. |
+| `acrValues` | `[String]?` | Requested Authentication Context Class Reference values. |
+| `additionalParameters` | `[String: String]?` | Extra parameters forwarded to the token request. |
+
 ### Web Authentication using OIDC
 
 The simplest way to integrate authentication in your app is with OIDC through a web browser, using the Authorization Code Flow grant.
@@ -263,8 +310,7 @@ When using the `device_sso` scope, your application can receive a "device secret
 let flow = TokenExchangeFlow(
     issuerURL: URL(string: "https://example.okta.com")!,
     clientId: "abc123client",
-    scope: "openid offline_access email profile",
-    audience: .default)
+    scope: "openid offline_access email profile")
 
 let token = try await flow.start(with: [
     .actor(type: .deviceSecret, value: "DeviceToken"),
@@ -317,7 +363,7 @@ let flow = try InteractionCodeFlow(issuerURL: URL(string: "https://example.okta.
 ```
 
 For more information, see the [OktaIdxAuth API documentation][oktaidxauth-docs].
- 
+
 ## Storing and using tokens
 
 Once your user has authenticated and you have a `Token` object, your application can store and use those credentials. The most direct approach is to use the `Credential.store(_:tags:security:)` function.

Samples/AuthenticationFlows.swift

@@ -93,8 +93,7 @@ func signInUsingDeviceSSO(deviceToken: String, idToken: String) async throws {
     // Create the flow
     let flow = TokenExchangeFlow(issuerURL: issuerUrl,
                                  clientId: clientId,
-                                 scope: "openid profile offline_access",
-                                 audience: .default)
+                                 scope: "openid profile offline_access")
 
     // Exchange the ID and Device tokens for access tokens.
     let token = try await flow.start(with: [

Sources/AuthFoundation/Migration/SDKVersion.swift

@@ -16,22 +16,18 @@ import Foundation
 import CommonSupport
 #endif
 
-#if canImport(UIKit)
-import UIKit
-#endif
-
-#if os(watchOS)
-import WatchKit
-#endif
-
 #if canImport(Android)
 import Android
 #endif
 
 private let deviceModel: String = {
     var system = utsname()
     uname(&system)
-    let model = withUnsafePointer(to: &system.machine.0) { ptr in
+    let model = withUnsafeBytes(of: &system.machine) { buf in
+        guard let ptr = buf.baseAddress?.assumingMemoryBound(to: CChar.self)
+        else {
+            return "unknown"
+        }
         return String(cString: ptr)
     }
     return model
@@ -52,22 +48,16 @@ private let systemName: String = {
         return "android"
     #elseif os(Linux)
         return "linux"
-    #elseif os(Android)
-        return "android"
+    #elseif os(Windows)
+        return "windows"
+    #else
+        return "unknown"
     #endif
 }()
 
 private let systemVersion: String = {
-    #if os(iOS) || os(tvOS) || (swift(>=5.10) && os(visionOS))
-    return MainActor.nonisolatedUnsafe {
-        UIDevice.current.systemVersion
-    }
-    #elseif os(watchOS)
-        return WKInterfaceDevice.current().systemVersion
-    #else
-        let osVersion = ProcessInfo.processInfo.operatingSystemVersion
-        return "\(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
-    #endif
+    let osVersion = ProcessInfo.processInfo.operatingSystemVersion
+    return "\(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
 }()
 
 /// Utility class that allows SDK components to register their name and version for use in HTTP User-Agent values.
@@ -101,47 +91,56 @@ public struct SDKVersion: Sendable {
     @discardableResult
     public static func register(sdk: SDKVersion) -> SDKVersion {
         lock.withLock {
-            guard _sdkVersions.filter({ $0.name == sdk.name }).isEmpty else {
-                return sdk
-            }
-
-            _sdkVersions.append(sdk)
-
-            let sdkVersionString = _sdkVersions
-                .sorted(by: { $0.name.rawValue < $1.name.rawValue })
-                .map(\.displayName)
-                .joined(separator: " ")
-            _userAgent = "\(sdkVersionString) \(systemName)/\(systemVersion) Device/\(deviceModel)"
+            _register(sdk: sdk)
+        }
+    }
 
+    private static func _register(sdk: SDKVersion) -> SDKVersion {
+        guard _sdkVersions.filter({ $0.name == sdk.name }).isEmpty else {
             return sdk
         }
+        
+        _sdkVersions.append(sdk)
+        
+        let sdkVersionString = _sdkVersions
+            .sorted(by: { $0.name.rawValue < $1.name.rawValue })
+            .map(\.displayName)
+            .joined(separator: " ")
+        _userAgent = "\(sdkVersionString) \(systemName)/\(systemVersion) Device/\(deviceModel)"
+        
+        return sdk
     }
 
     /// Convenience function used to register an SDK
     /// - Parameters:
     ///   - name: SDK name.
     ///   - versionString: SDK version.
     /// - Returns: The resulting SDKVersion object.
-    @inlinable
     @discardableResult
     public static func register(_ name: Name, version versionString: String) -> SDKVersion? {
-        let sdk = version(for: name) ?? register(sdk: SDKVersion(sdk: name, version: versionString))
-        guard sdk.version == versionString
-        else {
-            return nil
+        lock.withLock {
+            let sdk = _version(for: name) ?? _register(sdk: SDKVersion(sdk: name, version: versionString))
+            guard sdk.version == versionString
+            else {
+                return nil
+            }
+            return sdk
         }
-        return sdk
     }
 
     /// Returns the version information for the given SDK.
     /// - Parameter sdkName: SDK name to search for.
     /// - Returns: Version information for the given SDK name.
     public static func version(for sdkName: Name) -> SDKVersion? {
         lock.withLock {
-            _sdkVersions.first(where: { $0.name == sdkName })
+            _version(for: sdkName)
         }
     }
 
+    private static func _version(for sdkName: Name) -> SDKVersion? {
+        _sdkVersions.first(where: { $0.name == sdkName })
+    }
+
     // MARK: Private properties / methods
     private static let lock = Lock()
     nonisolated(unsafe) private static var _sdkVersions: [SDKVersion] = []