Support to Partner App authentication

Author: tiagocandido

README.md

@@ -36,6 +36,7 @@
     - [Shop Pay](#shop-pay)
     - [Customer Account API](#customer-account-api)
   - [Offsite Payments](#offsite-payments)
+  - [App Authentication](#app-authentication)
   - [Explore the sample apps](#explore-the-sample-apps)
   - [Contributing](#contributing)
   - [License](#license)
@@ -114,7 +115,9 @@ import ShopifyCheckoutSheetKit
 class MyViewController: UIViewController {
   func presentCheckout() {
     let checkoutURL: URL = // from cart object
-    ShopifyCheckoutSheetKit.present(checkout: checkoutURL, from: self, delegate: self)
+    let appAuth = CheckoutOptions.AppAuthentication(token: "<JWT_TOKEN>")
+    let checkoutOptions = CheckoutOptions(appAuthentication: appAuth)
+    ShopifyCheckoutSheetKit.present(checkout: checkoutURL, from: self, delegate: self, options: checkoutOptions)
   }
 }
 ```
@@ -545,7 +548,79 @@ public func checkoutDidClickLink(url: URL) {
 }
 ```
 
----
+## App Authentication
+
+App Authentication allows your app to securely identify itself to Shopify Checkout Kit and access additional permissions or features granted by Shopify. If your integration requires App Authentication, you must generate a JWT (JSON Web Token) on your secure server and pass it to the SDK.
+
+### How to generate the JWT
+
+**Prerequisites:**
+1. Create a Shopify app in the [Shopify Partners Dashboard](https://partners.shopify.com/organizations) or CLI to obtain your `api_key` and `shared_secret`.
+2. Install the app on a merchant's shop to obtain an `access_token` via the OAuth flow.
+
+**Encrypt your access token:**
+- Use AES-128-CBC with your `shared_secret` to encrypt the `access_token`.
+- Derive encryption and signing keys from the SHA-256 hash of your `shared_secret`.
+- Base64 encode the result.
+
+<details>
+<summary>Pseudo-code (Ruby) for encrypting your access_token</summary>
+
+```ruby
+shared_secret = <your_shared_secret>
+access_token = <your_access_token>
+
+key_material = OpenSSL::Digest.new("sha256").digest(shared_secret)
+encryption_key = key_material[0,16]
+signature_key  = key_material[16,16]
+
+cipher = OpenSSL::Cipher.new("aes-128-cbc")
+cipher.encrypt
+cipher.key = encryption_key
+cipher.iv = iv = cipher.random_iv
+raw_encrypted_token = iv + cipher.update(access_token) + cipher.final
+
+signature = OpenSSL::HMAC.digest("sha256", signature_key, raw_encrypted_token)
+encrypted_access_token = Base64.urlsafe_encode64(raw_encrypted_token + signature)
+```
+</details>
+
+**Create the JWT payload:**
+
+```json
+{
+  "api_key": "<your_api_key>",
+  "access_token": "<your_encrypted_access_token>",
+  "iat": <epoch_seconds>,
+  "jti": "<unique_id>"
+}
+```
+
+**Sign the JWT:**
+
+```ruby
+require 'jwt'
+require 'securerandom'
+
+payload = {
+  api_key: '<your_api_key>',
+  access_token: '<your_encrypted_access_token>',
+  iat: Time.now.utc.to_i,
+  jti: SecureRandom.uuid
+}
+
+token = JWT.encode(payload, '<your_shared_secret>', 'HS256')
+```
+
+**Use the JWT in your iOS app:**
+
+```swift
+let appAuth = CheckoutOptions.AppAuthentication(token: "<JWT_TOKEN>")
+let checkoutOptions = CheckoutOptions(appAuthentication: appAuth)
+ShopifyCheckoutSheetKit.present(checkout: checkoutURL, from: self, delegate: self, options: checkoutOptions)
+```
+
+> **Note:** The JWT should always be generated on a secure server, never on the device.
 
 ## Explore the sample apps
 

Sources/ShopifyCheckoutSheetKit/CheckoutViewController.swift

@@ -25,8 +25,8 @@ import UIKit
 import SwiftUI
 
 public class CheckoutViewController: UINavigationController {
-	public init(checkout url: URL, delegate: CheckoutDelegate? = nil) {
-		let rootViewController = CheckoutWebViewController(checkoutURL: url, delegate: delegate)
+	public init(checkout url: URL, delegate: CheckoutDelegate? = nil, options: CheckoutOptions? = nil) {
+		let rootViewController = CheckoutWebViewController(checkoutURL: url, delegate: delegate, options: options)
 		rootViewController.notifyPresented()
 		super.init(rootViewController: rootViewController)
 		presentationController?.delegate = rootViewController
@@ -60,7 +60,7 @@ extension CheckoutViewController {
 	}
 }
 
-public struct CheckoutSheet: UIViewControllerRepresentable, CheckoutConfigurable {
+public struct CheckoutSheet: UIViewControllerRepresentable, CheckoutOptionsConfigurable {
 	public typealias UIViewControllerType = CheckoutViewController
 
 	var checkoutURL: URL
@@ -144,14 +144,14 @@ public class CheckoutDelegateWrapper: CheckoutDelegate {
 	}
 }
 
-public protocol CheckoutConfigurable {
+public protocol CheckoutOptionsConfigurable {
 	func backgroundColor(_ color: UIColor) -> Self
 	func colorScheme(_ colorScheme: ShopifyCheckoutSheetKit.Configuration.ColorScheme) -> Self
 	func tintColor(_ color: UIColor) -> Self
 	func title(_ title: String) -> Self
 }
 
-extension CheckoutConfigurable {
+extension CheckoutOptionsConfigurable {
 	@discardableResult public func backgroundColor(_ color: UIColor) -> Self {
 		ShopifyCheckoutSheetKit.configuration.backgroundColor = color
 		return self

Sources/ShopifyCheckoutSheetKit/CheckoutWebView.swift

@@ -22,7 +22,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SO
 */
 
 import UIKit
-import WebKit
+@preconcurrency import WebKit
 
 protocol CheckoutWebViewDelegate: AnyObject {
 	func checkoutViewDidStartNavigation()
@@ -126,6 +126,8 @@ class CheckoutWebView: WKWebView {
 	}
 	var isPreloadRequest: Bool = false
 
+	var checkoutOptions: CheckoutOptions?
+
 	// MARK: Initializers
 	init(frame: CGRect = .zero, configuration: WKWebViewConfiguration = WKWebViewConfiguration(), recovery: Bool = false) {
 		OSLogger.shared.debug("Initializing webview, recovery: \(recovery)")
@@ -231,6 +233,13 @@ class CheckoutWebView: WKWebView {
 			request.setValue("prefetch", forHTTPHeaderField: "Sec-Purpose")
 		}
 
+		// Add app authentication header if config is provided
+		if let appAuth = checkoutOptions?.appAuthentication {
+			let headerValue = "{payload: \(appAuth.token), version: v2}"
+			request.setValue(headerValue, forHTTPHeaderField: "Shopify-Checkout-Kit-Consumer")
+			OSLogger.shared.debug("Added app authentication header for checkout")
+		}
+
 		load(request)
 	}
 

Sources/ShopifyCheckoutSheetKit/CheckoutWebViewController.swift

@@ -49,7 +49,7 @@ class CheckoutWebViewController: UIViewController, UIAdaptivePresentationControl
 
 	// MARK: Initializers
 
-	public init(checkoutURL url: URL, delegate: CheckoutDelegate? = nil) {
+	public init(checkoutURL url: URL, delegate: CheckoutDelegate? = nil, options: CheckoutOptions? = nil) {
 		self.checkoutURL = url
 		self.delegate = delegate
 
@@ -58,6 +58,9 @@ class CheckoutWebViewController: UIViewController, UIAdaptivePresentationControl
 		checkoutView.scrollView.contentInsetAdjustmentBehavior = .never
 		self.checkoutView = checkoutView
 
+        // Store checkout configuration for use when loading the checkout
+        checkoutView.checkoutOptions = options
+
 		super.init(nibName: nil, bundle: nil)
 
 		title = ShopifyCheckoutSheetKit.configuration.title

Sources/ShopifyCheckoutSheetKit/ShopifyCheckoutSheetKit.swift

@@ -42,14 +42,40 @@ public func configure(_ block: (inout Configuration) -> Void) {
 	block(&configuration)
 }
 
+/// Configuration for partner authentication.
+public struct CheckoutOptions {
+	public struct AppAuthentication {
+		/// The JWT authentication token.
+		public let token: String
+		public init(token: String) {
+			self.token = token
+		}
+	}
+
+	/// App authentication configuration for partner identification.
+	public let appAuthentication: AppAuthentication?
+
+	/// Initialize with app authentication configuration.
+	public init(appAuthentication: AppAuthentication? = nil) {
+		self.appAuthentication = appAuthentication
+	}
+
+	// In the future, other configurations can be added here:
+	// public let branding: BrandingConfig?
+	// public let analytics: AnalyticsConfig?
+	// etc.
+}
+
 /// Preloads the checkout for faster presentation.
-public func preload(checkout url: URL) {
+public func preload(checkout url: URL, options: CheckoutOptions? = nil) {
 	guard configuration.preloading.enabled else {
 		return
 	}
 
 	CheckoutWebView.preloadingActivatedByClient = true
-	CheckoutWebView.for(checkout: url).load(checkout: url, isPreload: true)
+	let webView = CheckoutWebView.for(checkout: url)
+	webView.checkoutOptions = options
+	webView.load(checkout: url, isPreload: true)
 }
 
 /// Invalidate the checkout cache from preload calls
@@ -59,8 +85,8 @@ public func invalidate() {
 
 /// Presents the checkout from a given `UIViewController`.
 @discardableResult
-public func present(checkout url: URL, from: UIViewController, delegate: CheckoutDelegate? = nil) -> CheckoutViewController {
-	let viewController = CheckoutViewController(checkout: url, delegate: delegate)
+public func present(checkout url: URL, from: UIViewController, delegate: CheckoutDelegate? = nil, options: CheckoutOptions? = nil) -> CheckoutViewController {
+	let viewController = CheckoutViewController(checkout: url, delegate: delegate, options: options)
 	from.present(viewController, animated: true)
 	return viewController
 }

Tests/ShopifyCheckoutSheetKitTests/CheckoutWebViewTests.swift

@@ -480,6 +480,32 @@ class CheckoutWebViewTests: XCTestCase {
 
 		XCTAssertNil(self.mockDelegate.errorReceived)
     }
+
+	func testAppAuthenticationHeaderIsAddedWithConfig() {
+		let webView = LoadedRequestObservableWebView()
+        let appAuthConfig = CheckoutOptions.AppAuthentication(token: "jwt-token-example")
+		webView.checkoutOptions = CheckoutOptions(appAuthentication: appAuthConfig)
+
+		webView.load(
+			checkout: URL(string: "https://checkout-sdk.myshopify.io")!,
+			isPreload: false
+		)
+
+		let authHeader = webView.lastLoadedURLRequest?.value(forHTTPHeaderField: "Shopify-Checkout-Kit-Consumer")
+		XCTAssertEqual(authHeader, "{payload: jwt-token-example, version: v2}")
+	}
+
+	func testAppAuthenticationHeaderNotAddedWithoutConfig() {
+		let webView = LoadedRequestObservableWebView()
+
+		webView.load(
+			checkout: URL(string: "https://checkout-sdk.myshopify.io")!,
+			isPreload: false
+		)
+
+		let authHeader = webView.lastLoadedURLRequest?.value(forHTTPHeaderField: "Shopify-Checkout-Kit-Consumer")
+		XCTAssertNil(authHeader)
+	}
 }
 
 class LoadedRequestObservableWebView: CheckoutWebView {

Tests/ShopifyCheckoutSheetKitTests/SwiftUITests.swift

@@ -121,7 +121,7 @@ class CheckoutSheetTests: XCTestCase {
 	}
 }
 
-class CheckoutConfigurableTests: XCTestCase {
+class CheckoutOptionsConfigurableTests: XCTestCase {
 	var checkoutURL: URL!
 	var checkoutSheet: CheckoutSheet!