@novastera-oss/nitro-metamask 0.6.3 → 0.7.2

package/ios/HybridNitroMetamask.swift

@@ -1,6 +1,12 @@
 import NitroModules
-import metamask_ios_sdk
 import Foundation
+import UIKit
+
+// Posted by the app's AppDelegate when a MetaMask deep link is received.
+// This avoids importing NitroMetamask (a C++ module) from the app target.
+extension Notification.Name {
+  static let metamaskDeepLink = Notification.Name("io.metamask.deeplink")
+}
 
 final class HybridNitroMetamask: HybridNitroMetamaskSpec {
   // SDK instance - can be recreated when configure() is called
@@ -9,10 +15,47 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
   private var lastUsedUrl: String? = nil
   private var lastUsedScheme: String? = nil
   
+  // Pending cancellation handler — set while an SDK operation is in-flight,
+  // cleared when the SDK responds or when the user returns to the app.
+  private var pendingCancellationHandler: (() -> Void)?
+  
+  override init() {
+    super.init()
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(appDidBecomeActive),
+      name: UIApplication.didBecomeActiveNotification,
+      object: nil
+    )
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(handleDeepLinkNotification(_:)),
+      name: .metamaskDeepLink,
+      object: nil
+    )
+  }
+  
+  deinit {
+    NotificationCenter.default.removeObserver(self)
+  }
+  
+  @objc private func appDidBecomeActive() {
+    if let handler = pendingCancellationHandler {
+      pendingCancellationHandler = nil
+      handler()
+    }
+  }
+
+  @objc private func handleDeepLinkNotification(_ notification: Notification) {
+    if let url = notification.userInfo?["url"] as? URL {
+      sdk.handleUrl(url)
+    }
+  }
+  
   // Get or create MetaMask SDK instance
   // Aligned with Android: SDK is recreated when configure() changes values
   private var sdk: MetaMaskSDK {
-    let currentUrl = dappUrl ?? "https://metamask.io"
+    let currentUrl = dappUrl ?? "https://novastera.com"
     let currentScheme = deepLinkScheme ?? getDefaultDappScheme()
     
     // Check if we need to recreate the SDK
@@ -22,14 +65,6 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
       return existing
     }
     
-    // Check if there's a shared instance we should use (only if it matches our config)
-    if let existing = MetaMaskSDK.sharedInstance,
-       lastUsedUrl == currentUrl,
-       lastUsedScheme == currentScheme {
-      sdkInstance = existing
-      return existing
-    }
-    
     // Create new SDK instance with current configuration
     let appMetadata = AppMetadata(
       name: "NitroMetamask",
@@ -60,7 +95,7 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
   private var deepLinkScheme: String? = nil
   
   func configure(dappUrl: String?, deepLinkScheme: String?) {
-    let urlToUse = dappUrl ?? "https://metamask.io"
+    let urlToUse = dappUrl ?? "https://novastera.com"
     let schemeToUse = deepLinkScheme ?? getDefaultDappScheme()
     
     var changed = false
@@ -99,33 +134,47 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
   }
 
   func connect() -> Promise<ConnectResult> {
-    // Use Promise.async with Swift async/await for best practice in Nitro modules
-    // Reference: https://nitro.margelo.com/docs/types/promises
     return Promise.async {
       NSLog("NitroMetamask: connect() called")
       
       // Check if MetaMask is installed before attempting to connect
       if !self.sdk.isMetaMaskInstalled {
-        let errorMessage = "MetaMask is not installed. Please install MetaMask from the App Store to continue."
-        NSLog("NitroMetamask: MetaMask not installed - \(errorMessage)")
+        NSLog("NitroMetamask: MetaMask not installed")
         throw NSError(
           domain: "MetamaskConnector",
-          code: -2,
-          userInfo: [NSLocalizedDescriptionKey: errorMessage]
+          code: 2,
+          userInfo: [NSLocalizedDescriptionKey: "[2] MetaMask is not installed"]
         )
       }
       
-      // Based on MetaMask iOS SDK docs: connect() returns Result<[String], RequestError>
-      // Reference: https://github.com/MetaMask/metamask-ios-sdk
-      let connectResult = await self.sdk.connect()
+      // Bridge the async SDK call with a cancellation handler using CheckedContinuation.
+      // The cancellation handler fires when the user returns to the app (appDidBecomeActive)
+      // without completing the MetaMask request.
+      let connectResult: Result<[String], RequestError> = try await withCheckedThrowingContinuation { continuation in
+        var resumed = false
+        self.pendingCancellationHandler = {
+          guard !resumed else { return }
+          resumed = true
+          self.pendingCancellationHandler = nil
+          continuation.resume(throwing: NSError(
+            domain: "MetamaskConnector",
+            code: -3,
+            userInfo: [NSLocalizedDescriptionKey: "MetaMask operation cancelled: user returned to app without completing the request"]
+          ))
+        }
+        Task {
+          let result = await self.sdk.connect()
+          guard !resumed else { return }
+          resumed = true
+          self.pendingCancellationHandler = nil
+          continuation.resume(returning: result)
+        }
+      }
       
       NSLog("NitroMetamask: connect() result: \(connectResult)")
       
       switch connectResult {
       case .success:
-        // After successful connection, get account info from SDK
-        // Note: sdk.account is a String (not optional), check if empty
-        // Reference: https://raw.githubusercontent.com/MetaMask/metamask-ios-sdk/924d91bb3e98a5383c3082d6d5ba3ddac9e1c565/README.md
         let address = self.sdk.account
         guard !address.isEmpty else {
           throw NSError(
@@ -135,8 +184,6 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
           )
         }
         
-        // Parse chainId from hex string (e.g., "0x1") to number
-        // Nitro requires chainId to be a number, not a string, for type safety
         let chainIdHex = self.sdk.chainId
         guard !chainIdHex.isEmpty,
               let chainIdInt = Int(chainIdHex.replacingOccurrences(of: "0x", with: ""), radix: 16) else {
@@ -160,12 +207,7 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
   }
 
   func signMessage(message: String) -> Promise<String> {
-    // Use Promise.async with Swift async/await for best practice in Nitro modules
-    // Reference: https://nitro.margelo.com/docs/types/promises
     return Promise.async {
-      // Use explicit sign() method (requires connection first via connect())
-      // This is more explicit and predictable than connectAndSign() which forces connection
-      // Nitro encourages explicit object state, not convenience shortcuts
       let account = self.sdk.account
       guard !account.isEmpty else {
         throw NSError(
@@ -175,23 +217,38 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
         )
       }
       
-      // Create EthereumRequest for personal_sign
-      // Based on MetaMask iOS SDK docs: params are [account, message]
-      // Reference: https://raw.githubusercontent.com/MetaMask/metamask-ios-sdk/924d91bb3e98a5383c3082d6d5ba3ddac9e1c565/README.md
       let params: [String] = [account, message]
       let request = EthereumRequest(
         method: .personalSign,
         params: params
       )
       
-      // Make the request using the SDK's async request method
-      // request() returns Result<String, RequestError>
       NSLog("NitroMetamask: signMessage() calling request")
-      let result = await self.sdk.request(request)
+      
+      // Bridge the async SDK call with a cancellation handler.
+      let result: Result<String, RequestError> = try await withCheckedThrowingContinuation { continuation in
+        var resumed = false
+        self.pendingCancellationHandler = {
+          guard !resumed else { return }
+          resumed = true
+          self.pendingCancellationHandler = nil
+          continuation.resume(throwing: NSError(
+            domain: "MetamaskConnector",
+            code: -3,
+            userInfo: [NSLocalizedDescriptionKey: "MetaMask operation cancelled: user returned to app without completing the request"]
+          ))
+        }
+        Task {
+          let r = await self.sdk.request(request)
+          guard !resumed else { return }
+          resumed = true
+          self.pendingCancellationHandler = nil
+          continuation.resume(returning: r)
+        }
+      }
       
       NSLog("NitroMetamask: signMessage() result: \(result)")
       
-      // Extract signature from response
       switch result {
       case .success(let signature):
         return signature
@@ -203,13 +260,8 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
   }
 
   func connectSign(nonce: String, exp: Int64) -> Promise<ConnectSignResult> {
-    // Use Promise.async with Swift async/await for best practice in Nitro modules
-    // Reference: https://nitro.margelo.com/docs/types/promises
-    // Based on MetaMask iOS SDK: connectAndSign(message:) convenience method
-    // Reference: https://github.com/MetaMask/metamask-ios-sdk
     return Promise.async {
       // Construct JSON message with only nonce and exp
-      // We don't include address or chainID - just encrypt nonce and exp
       let messageDict: [String: Any] = [
         "nonce": nonce,
         "exp": exp
@@ -226,28 +278,44 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
       
       NSLog("NitroMetamask: connectSign: Constructed message with nonce and exp: \(message)")
       
-      // Use the SDK's connectAndSign convenience method - it will connect if needed and sign the message
-      // This is the recommended approach per MetaMask iOS SDK documentation
-      // Reference: https://github.com/MetaMask/metamask-ios-sdk
       // Check if MetaMask is installed before attempting to connect and sign
       if !self.sdk.isMetaMaskInstalled {
-        let errorMessage = "MetaMask is not installed. Please install MetaMask from the App Store to continue."
-        NSLog("NitroMetamask: MetaMask not installed - \(errorMessage)")
+        NSLog("NitroMetamask: MetaMask not installed")
         throw NSError(
           domain: "MetamaskConnector",
-          code: -2,
-          userInfo: [NSLocalizedDescriptionKey: errorMessage]
+          code: 2,
+          userInfo: [NSLocalizedDescriptionKey: "[2] MetaMask is not installed"]
         )
       }
       
       NSLog("NitroMetamask: connectSign() calling connectAndSign")
-      let connectSignResult = await self.sdk.connectAndSign(message: message)
+      
+      // Bridge the async SDK call with a cancellation handler.
+      let connectSignResult: Result<String, RequestError> = try await withCheckedThrowingContinuation { continuation in
+        var resumed = false
+        self.pendingCancellationHandler = {
+          guard !resumed else { return }
+          resumed = true
+          self.pendingCancellationHandler = nil
+          continuation.resume(throwing: NSError(
+            domain: "MetamaskConnector",
+            code: -3,
+            userInfo: [NSLocalizedDescriptionKey: "MetaMask operation cancelled: user returned to app without completing the request"]
+          ))
+        }
+        Task {
+          let result = await self.sdk.connectAndSign(message: message)
+          guard !resumed else { return }
+          resumed = true
+          self.pendingCancellationHandler = nil
+          continuation.resume(returning: result)
+        }
+      }
       
       NSLog("NitroMetamask: connectSign() result: \(connectSignResult)")
       
       switch connectSignResult {
       case .success(let signature):
-        // After connectSign completes, get the address and chainId from the SDK
         let address = self.sdk.account
         guard !address.isEmpty else {
           throw NSError(
@@ -266,7 +334,6 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
           )
         }
         
-        // Parse chainId from hex string (e.g., "0x1") to Int64
         guard let chainId = Int64(chainIdHex.replacingOccurrences(of: "0x", with: ""), radix: 16) else {
           throw NSError(
             domain: "MetamaskConnector",
@@ -276,8 +343,6 @@ final class HybridNitroMetamask: HybridNitroMetamaskSpec {
         }
         
         NSLog("NitroMetamask: connectSign: Signature received successfully, address=\(address), chainId=\(chainId)")
-        
-        // Return ConnectSignResult with signature, address, and chainId
         return ConnectSignResult(signature: signature, address: address, chainId: chainId)
         
       case .failure(let error):

package/ios/NitroMetamaskTests/CancellationStateMachineTests.swift

@@ -0,0 +1,150 @@
+import XCTest
+
+// CancellationStateMachineTests
+//
+// Validates: Requirements 11.5, 11.6
+// "WHEN no operation is pending, THE Nitro_Module SHALL ignore app foreground transitions."
+// "WHEN a pending operation is cancelled via foreground detection, THE Nitro_Module SHALL
+//  clean up the pending operation state so subsequent calls work correctly."
+//
+// These tests verify the cancellation state machine logic in isolation using a minimal
+// test double that mirrors the pendingCancellationHandler pattern in HybridNitroMetamask.
+// Because HybridNitroMetamask depends on the full MetaMask iOS SDK and Nitro runtime,
+// the state machine is extracted into a testable helper class below.
+
+// MARK: - Minimal test double for the cancellation state machine
+
+/// CancellationStateMachine mirrors the pendingCancellationHandler logic in
+/// HybridNitroMetamask without any SDK or Nitro dependencies.
+final class CancellationStateMachine {
+    var pendingCancellationHandler: (() -> Void)?
+
+    /// Called when the app returns to the foreground (mirrors appDidBecomeActive).
+    func appDidBecomeActive() {
+        if let handler = pendingCancellationHandler {
+            pendingCancellationHandler = nil
+            handler()
+        }
+    }
+}
+
+// MARK: - Tests
+
+final class CancellationStateMachineTests: XCTestCase {
+
+    // MARK: - Handler lifecycle
+
+    /// After setting and then clearing the handler (simulating a successful SDK response),
+    /// the state must be nil — no stale handler remains.
+    ///
+    /// Validates: Requirement 11.6
+    func testHandlerIsNilAfterSuccessfulOperation() {
+        let sm = CancellationStateMachine()
+
+        // Simulate: operation starts — set handler
+        sm.pendingCancellationHandler = { /* would reject continuation */ }
+        XCTAssertNotNil(sm.pendingCancellationHandler, "Handler should be set while operation is in-flight")
+
+        // Simulate: SDK responds successfully — clear handler
+        sm.pendingCancellationHandler = nil
+        XCTAssertNil(sm.pendingCancellationHandler, "Handler must be nil after a successful operation")
+    }
+
+    /// appDidBecomeActive with no pending handler must be a no-op — it must not crash
+    /// and must leave state unchanged.
+    ///
+    /// Validates: Requirement 11.5
+    func testAppDidBecomeActiveWithNoPendingHandlerIsNoOp() {
+        let sm = CancellationStateMachine()
+        XCTAssertNil(sm.pendingCancellationHandler, "Precondition: no pending handler")
+
+        // Must not crash and must leave state as nil
+        sm.appDidBecomeActive()
+
+        XCTAssertNil(sm.pendingCancellationHandler, "State must remain nil after no-op foreground transition")
+    }
+
+    /// appDidBecomeActive fires the handler and clears it (nil-before-invoke pattern).
+    ///
+    /// Validates: Requirements 11.2, 11.6
+    func testAppDidBecomeActiveFiresAndClearsHandler() {
+        let sm = CancellationStateMachine()
+        var handlerFired = false
+
+        sm.pendingCancellationHandler = {
+            handlerFired = true
+        }
+
+        sm.appDidBecomeActive()
+
+        XCTAssertTrue(handlerFired, "Handler must be invoked when app becomes active with a pending operation")
+        XCTAssertNil(sm.pendingCancellationHandler, "Handler must be cleared before/after invocation")
+    }
+
+    /// A second appDidBecomeActive after the first has already fired must be a no-op.
+    /// This guards against double-rejection if the notification fires more than once.
+    ///
+    /// Validates: Requirement 11.5
+    func testSecondAppDidBecomeActiveIsNoOp() {
+        let sm = CancellationStateMachine()
+        var callCount = 0
+
+        sm.pendingCancellationHandler = {
+            callCount += 1
+        }
+
+        sm.appDidBecomeActive() // first — fires handler
+        sm.appDidBecomeActive() // second — must be no-op
+
+        XCTAssertEqual(callCount, 1, "Handler must be invoked exactly once even if appDidBecomeActive fires multiple times")
+        XCTAssertNil(sm.pendingCancellationHandler, "Handler must remain nil after second foreground transition")
+    }
+
+    /// After a cancellation fires, the state machine must be clean so a subsequent
+    /// operation can set a new handler without interference.
+    ///
+    /// Validates: Requirement 11.6
+    func testStateIsCleanAfterCancellationForSubsequentOperation() {
+        let sm = CancellationStateMachine()
+        var firstFired = false
+        var secondFired = false
+
+        // First operation
+        sm.pendingCancellationHandler = { firstFired = true }
+        sm.appDidBecomeActive() // cancels first operation
+
+        XCTAssertTrue(firstFired, "First handler must fire")
+        XCTAssertNil(sm.pendingCancellationHandler, "State must be clean after first cancellation")
+
+        // Second operation — must work correctly
+        sm.pendingCancellationHandler = { secondFired = true }
+        sm.appDidBecomeActive() // cancels second operation
+
+        XCTAssertTrue(secondFired, "Second handler must fire independently")
+        XCTAssertNil(sm.pendingCancellationHandler, "State must be clean after second cancellation")
+    }
+
+    // MARK: - Race-condition guard (nil-before-invoke)
+
+    /// The nil-before-invoke pattern ensures the handler is cleared before being called,
+    /// preventing re-entrant invocation if the handler itself triggers appDidBecomeActive.
+    ///
+    /// Validates: Requirement 11.6
+    func testHandlerIsNilWhenInvokedNilBeforeInvokePattern() {
+        let sm = CancellationStateMachine()
+        var observedHandlerDuringInvocation: (() -> Void)? = { /* sentinel */ }
+
+        sm.pendingCancellationHandler = {
+            // Capture the state of pendingCancellationHandler at the moment the handler runs.
+            // It must already be nil (nil-before-invoke).
+            observedHandlerDuringInvocation = sm.pendingCancellationHandler
+        }
+
+        sm.appDidBecomeActive()
+
+        XCTAssertNil(
+            observedHandlerDuringInvocation,
+            "pendingCancellationHandler must be nil before the handler is invoked (nil-before-invoke pattern)"
+        )
+    }
+}

package/ios/NitroMetamaskTests/ChainIdParsingTests.swift

@@ -0,0 +1,117 @@
+import XCTest
+
+// ChainIdParsingTests
+//
+// Property 1: ChainId hex parsing round-trip
+// Validates: Requirements 2.6, 5.5
+//
+// "WHEN connect() succeeds, THE Nitro_Module SHALL return a chainId parsed from
+//  the hex string returned by the SDK (e.g., "0x1" → 1n)."
+// "WHEN getChainId() is called and a wallet is connected, THE Nitro_Module SHALL
+//  resolve the promise with the chain ID as a bigint parsed from the SDK's hex string."
+//
+// These tests verify the hex-to-Int64 parsing logic used in HybridNitroMetamask.swift.
+// The helper below mirrors the parsing logic exactly so tests remain independent of
+// the full SDK and Nitro runtime.
+
+// MARK: - Parsing helper (mirrors HybridNitroMetamask.swift)
+
+/// Mirrors the chainId parsing logic used in HybridNitroMetamask.swift:
+///
+///   Int64(chainIdHex.replacingOccurrences(of: "0x", with: ""), radix: 16)
+///
+/// Both lowercase "0x" and uppercase "0X" prefixes are stripped.
+func parseChainId(_ hex: String) -> Int64? {
+    let stripped = hex
+        .replacingOccurrences(of: "0x", with: "")
+        .replacingOccurrences(of: "0X", with: "")
+    return Int64(stripped, radix: 16)
+}
+
+// MARK: - Tests
+
+final class ChainIdParsingTests: XCTestCase {
+
+    // MARK: - Known values
+
+    /// "0x1" is Ethereum Mainnet — the most common chain.
+    func testMainnet_0x1_parsesTo1() {
+        XCTAssertEqual(parseChainId("0x1"), 1)
+    }
+
+    /// "0x89" is Polygon Mainnet (137 decimal).
+    func testPolygon_0x89_parsesTo137() {
+        XCTAssertEqual(parseChainId("0x89"), 137)
+    }
+
+    /// "0xa" is Optimism Mainnet (10 decimal).
+    func testOptimism_0xa_parsesTo10() {
+        XCTAssertEqual(parseChainId("0xa"), 10)
+    }
+
+    /// "0x38" is BNB Smart Chain (56 decimal).
+    func testBNBChain_0x38_parsesTo56() {
+        XCTAssertEqual(parseChainId("0x38"), 56)
+    }
+
+    /// "0xa4b1" is Arbitrum One (42161 decimal).
+    func testArbitrum_0xa4b1_parsesTo42161() {
+        XCTAssertEqual(parseChainId("0xa4b1"), 42161)
+    }
+
+    // MARK: - Case insensitivity
+
+    /// Uppercase "0X" prefix must be stripped correctly.
+    func testUppercasePrefix_0X1_parsesTo1() {
+        XCTAssertEqual(parseChainId("0X1"), 1)
+    }
+
+    /// Mixed-case hex digits must parse correctly.
+    func testMixedCase_0xA4B1_parsesTo42161() {
+        XCTAssertEqual(parseChainId("0xA4B1"), 42161)
+    }
+
+    // MARK: - Round-trip property
+
+    /// For any parsed value, converting back to hex and re-parsing must yield the same Int64.
+    /// This is the core round-trip property.
+    func testRoundTrip_parseThenFormat_yieldsOriginalValue() {
+        let testCases: [(hex: String, expected: Int64)] = [
+            ("0x1",    1),
+            ("0x89",   137),
+            ("0xa",    10),
+            ("0x38",   56),
+            ("0xa4b1", 42161),
+        ]
+
+        for (hex, expected) in testCases {
+            guard let parsed = parseChainId(hex) else {
+                XCTFail("parseChainId(\"\(hex)\") returned nil — expected \(expected)")
+                continue
+            }
+            XCTAssertEqual(parsed, expected, "parseChainId(\"\(hex)\") should equal \(expected)")
+
+            // Round-trip: format back to hex and re-parse
+            let reformatted = "0x" + String(parsed, radix: 16)
+            let reparsed = parseChainId(reformatted)
+            XCTAssertEqual(reparsed, parsed, "Round-trip failed for \"\(hex)\": reformatted=\"\(reformatted)\"")
+        }
+    }
+
+    // MARK: - Invalid inputs
+
+    /// An empty string must return nil (not crash).
+    func testEmptyString_returnsNil() {
+        XCTAssertNil(parseChainId(""))
+    }
+
+    /// A bare "0x" with no digits must return nil.
+    func testBarePrefix_0x_returnsNil() {
+        XCTAssertNil(parseChainId("0x"))
+    }
+
+    /// A non-hex string must return nil.
+    func testNonHex_returnsNil() {
+        XCTAssertNil(parseChainId("0xGGGG"))
+    }
+}