@cap-kit/integrity 8.0.0-next.6

package/android/src/main/java/io/capkit/integrity/IntegrityPlugin.kt

@@ -0,0 +1,475 @@
+package io.capkit.integrity
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.net.Uri
+import android.os.Build
+import androidx.core.content.ContextCompat
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.getcapacitor.annotation.Permission
+import io.capkit.integrity.utils.IntegrityLogger
+import io.capkit.integrity.utils.IntegrityUtils
+
+/**
+ * Capacitor bridge for the Integrity plugin (Android).
+ *
+ * CONTRACT:
+ * - This class is the ONLY entry point from JavaScript.
+ * - All PluginCall instances MUST be resolved or rejected exactly once.
+ *
+ * Responsibilities:
+ * - Parse JavaScript input
+ * - Invoke the native implementation
+ * - Resolve or reject PluginCall exactly once
+ * - Map native IntegrityError to JS-facing error codes
+ *
+ * Forbidden:
+ * - Platform-specific business logic
+ * - Direct system API usage outside lifecycle-bound orchestration
+ * - Throwing uncaught exceptions
+ */
+@CapacitorPlugin(
+  name = "Integrity",
+  permissions = [
+    Permission(
+      alias = "network",
+      strings = [android.Manifest.permission.INTERNET],
+    ),
+  ],
+)
+class IntegrityPlugin : Plugin() {
+  // ---------------------------------------------------------------------------
+  // Properties
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Immutable plugin configuration.
+   *
+   * CONTRACT:
+   * - Initialized exactly once in `load()`
+   * - Treated as read-only afterwards
+   * - MUST NOT be mutated at runtime
+   * - MUST NOT be accessed by the Impl layer
+   */
+  private lateinit var config: IntegrityConfig
+
+  /**
+   * Native implementation layer.
+   *
+   * CONTRACT:
+   * - Owned by the Plugin layer
+   * - Lifetime == plugin lifetime
+   * - MUST NOT access PluginCall or Capacitor APIs
+   * - MUST NOT perform UI operations
+   */
+  private lateinit var implementation: IntegrityImpl
+
+  // ---------------------------------------------------------------------------
+  // Event-related properties
+  // ---------------------------------------------------------------------------
+
+  /**
+   * In-memory buffer for integrity signals detected before
+   * a JavaScript listener is registered.
+   *
+   * Thread-safe implementation to prevent race conditions during
+   * asynchronous event emission.
+   */
+  private val bufferedSignals = java.util.Collections.synchronizedList(mutableListOf<JSObject>())
+
+  /**
+   * BroadcastReceiver used to observe passive system events
+   * relevant for integrity monitoring.
+   */
+  private lateinit var eventReceiver: IntegrityEventReceiver
+
+  private companion object {
+    /**
+     * Canonical event name emitted to the JavaScript layer.
+     *
+     * CONTRACT:
+     * - MUST remain stable across releases
+     * - MUST match the JS-side event subscription name
+     */
+    private const val EVENT_INTEGRITY_SIGNAL = "integritySignal"
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Called once when the plugin is loaded by the Capacitor bridge.
+   *
+   * CONTRACT:
+   * - Called exactly once
+   * - This is the ONLY valid place to:
+   *   - read static configuration
+   *   - initialize the native implementation
+   *   - inject configuration into the implementation
+   *   - register system event listeners (BroadcastReceivers)
+   *
+   * WARNING:
+   * - Re-initializing config or implementation outside this method
+   *   is considered a plugin defect.
+   */
+  override fun load() {
+    super.load()
+
+    config = IntegrityConfig(this)
+    implementation = IntegrityImpl(context)
+    implementation.updateConfig(config)
+    registerEventReceiver()
+  }
+
+  /**
+   * Custom addListener implementation to flush early boot signals.
+   *
+   * PURPOSE:
+   * - Ensures that signals captured during the early boot phase or
+   * while the app was in the background are delivered as soon as
+   * the JavaScript side registers a listener.
+   */
+  @PluginMethod
+  override fun addListener(call: PluginCall) {
+    val eventName = call.getString("eventName")
+    super.addListener(call)
+
+    if (eventName == EVENT_INTEGRITY_SIGNAL) {
+      flushBufferedSignals()
+    }
+  }
+
+  /**
+   * Called when the host Activity resumes.
+   *
+   * PURPOSE:
+   * - Flush any integrity signals captured while no JS listeners
+   * were registered.
+   * - Perform a targeted check for debugger attachment during resume.
+   */
+  override fun handleOnResume() {
+    super.handleOnResume()
+    flushBufferedSignals()
+
+    // Immediate check for debugger attachment upon resume (Real-time monitor)
+    if (android.os.Debug.isDebuggerConnected()) {
+      val options = IntegrityCheckOptions(level = "standard", includeDebugInfo = false)
+      execute {
+        try {
+          val result = implementation.performCheck(options)
+          val jsResult = IntegrityUtils.toJSObject(result)
+          emitOrBufferSignal(jsResult)
+        } catch (e: Exception) {
+          IntegrityLogger.error("Real-time monitor: Debugger check failed: ${e.message}")
+        }
+      }
+    }
+  }
+
+  /**
+   * Flushes all buffered integrity signals to JavaScript listeners.
+   * Ensures FIFO delivery and prevents duplicate emissions.
+   *
+   * NOTE:
+   * - This method is thread-safe and idempotent.
+   * - Buffer is cleared immediately after dispatch.
+   */
+  private fun flushBufferedSignals() {
+    synchronized(bufferedSignals) {
+      if (hasListeners(EVENT_INTEGRITY_SIGNAL) && bufferedSignals.isNotEmpty()) {
+        IntegrityLogger.debug("Flushing ${bufferedSignals.size} buffered signals to JS")
+        val iterator = bufferedSignals.iterator()
+        while (iterator.hasNext()) {
+          val signal = iterator.next()
+          notifyListeners(EVENT_INTEGRITY_SIGNAL, signal, true)
+          iterator.remove()
+        }
+      }
+    }
+  }
+
+  /**
+   * Called when the plugin is being destroyed.
+   *
+   * CONTRACT:
+   * - All BroadcastReceivers registered by this plugin
+   *   MUST be unregistered here.
+   */
+  override fun handleOnDestroy() {
+    super.handleOnDestroy()
+    unregisterEventReceiver()
+  }
+
+  // ---------------------------------------------------------------------------
+  // Event emission and buffering
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Emits an integrity signal to JavaScript or buffers it
+   * if no listeners are currently registered.
+   *
+   * @param signal Fully-formed integrity signal payload.
+   */
+  private fun emitOrBufferSignal(signal: JSObject) {
+    synchronized(bufferedSignals) {
+      if (hasListeners(EVENT_INTEGRITY_SIGNAL)) {
+        notifyListeners(EVENT_INTEGRITY_SIGNAL, signal, true)
+      } else {
+        bufferedSignals.add(signal)
+      }
+    }
+  }
+
+  /**
+   * Registers the BroadcastReceiver used for passive integrity signals.
+   *
+   * NOTE:
+   * - No polling or background services are introduced.
+   * - Observers are scoped strictly to the plugin lifecycle.
+   */
+  private fun registerEventReceiver() {
+    eventReceiver =
+      IntegrityEventReceiver { signal ->
+        emitOrBufferSignal(signal)
+      }
+
+    val intentFilter =
+      IntentFilter().apply {
+        addAction(Intent.ACTION_PACKAGE_ADDED)
+        addAction(Intent.ACTION_PACKAGE_REPLACED)
+        addDataScheme("package")
+      }
+
+    val flags =
+      // UPSIDE_DOWN_CAKE API LEVEL 34
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+        ContextCompat.RECEIVER_NOT_EXPORTED
+      } else {
+        0
+      }
+
+    // TIRAMISU API LEVEL 33
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+      context.registerReceiver(eventReceiver, intentFilter, flags)
+    } else {
+      context.registerReceiver(eventReceiver, intentFilter)
+    }
+  }
+
+  /**
+   * Unregisters the integrity BroadcastReceiver.
+   *
+   * NOTE:
+   * - It is safe to call this method even if the receiver
+   *   was never registered.
+   */
+  private fun unregisterEventReceiver() {
+    // It's safe to call unregisterReceiver even if the receiver was never registered
+    try {
+      context.unregisterReceiver(eventReceiver)
+    } catch (e: IllegalArgumentException) {
+      // Receiver wasn't registered, ignore
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Error mapping
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Maps native IntegrityError values to JavaScript-facing error codes.
+   *
+   * CONTRACT:
+   * - This method is the ONLY place where native errors
+   *   are translated into JS-visible failures.
+   * - Error codes MUST be:
+   *   - stable
+   *   - documented
+   *   - identical across platforms
+   */
+  private fun reject(
+    call: PluginCall,
+    error: IntegrityError,
+  ) {
+    val code =
+      when (error) {
+        is IntegrityError.Unavailable -> "UNAVAILABLE"
+        is IntegrityError.PermissionDenied -> "PERMISSION_DENIED"
+        is IntegrityError.InitFailed -> "INIT_FAILED"
+        is IntegrityError.UnknownType -> "UNKNOWN_TYPE"
+      }
+
+    call.reject(error.message, code)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Check
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Executes an integrity check.
+   *
+   * CONTRACT:
+   * - Resolves exactly once on success
+   * - Rejects exactly once on failure
+   * - Never throws outside this method
+   *
+   * NOTE:
+   * - Option defaulting happens here by design.
+   * - The Impl layer MUST receive fully normalized options.
+   */
+  @PluginMethod
+  fun check(call: PluginCall) {
+    val options =
+      IntegrityCheckOptions(
+        level = call.getString("level") ?: "basic",
+        includeDebugInfo = call.getBoolean("includeDebugInfo") ?: false,
+      )
+
+    // Execute integrity checks off the plugin thread to avoid future ANR risks.
+    execute {
+      try {
+        val result = implementation.performCheck(options)
+        val jsResult = IntegrityUtils.toJSObject(result)
+        call.resolve(jsResult)
+      } catch (e: IntegrityError) {
+        reject(call, e)
+      } catch (e: Exception) {
+        call.reject(
+          "Unexpected native error during integrity check.",
+          "INIT_FAILED",
+        )
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // PresentBlockPage
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Presents the configured integrity block page, if enabled.
+   *
+   * CONTRACT:
+   * - This method NEVER decides when it should be called.
+   * - The decision is fully delegated to the host application.
+   *
+   * NOTE:
+   * - Returning `{ presented: false }` is NOT an error.
+   * - This allows deterministic branching on the JS side.
+   *
+   * WARNING:
+   * - UI navigation is allowed ONLY in the Plugin layer.
+   * - The Impl layer MUST NEVER start Activities.
+   */
+  @PluginMethod
+  fun presentBlockPage(call: PluginCall) {
+    if (!config.blockPageEnabled || config.blockPageUrl == null) {
+      call.resolve(JSObject().put("presented", false))
+      return
+    }
+
+    val reason = call.getString("reason")
+    val dismissible = call.getBoolean("dismissible") ?: false
+
+    val url =
+      if (reason != null) {
+        "${config.blockPageUrl}?reason=${Uri.encode(reason)}"
+      } else {
+        config.blockPageUrl
+      }
+
+    val intent =
+      Intent(
+        context,
+        io.capkit.integrity.ui.IntegrityBlockActivity::class.java,
+      ).apply {
+        putExtra("url", url)
+        putExtra("dismissible", dismissible)
+        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+
+        // If not dismissible, clear the back stack
+        if (!dismissible) {
+          addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK)
+        }
+      }
+
+    context.startActivity(intent)
+
+    call.resolve(JSObject().put("presented", true))
+  }
+
+  // ---------------------------------------------------------------------------
+  // Version
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the native plugin version.
+   *
+   * NOTE:
+   * - Used exclusively for diagnostics and compatibility checks.
+   * - Must not be used for feature detection.
+   */
+  @PluginMethod
+  fun getPluginVersion(call: PluginCall) {
+    val ret = JSObject()
+    ret.put("version", BuildConfig.PLUGIN_VERSION)
+    call.resolve(ret)
+  }
+
+  // ---------------------------------------------------------------------------
+  // BroadcastReceiver implementation
+  // ---------------------------------------------------------------------------
+
+  /**
+   * BroadcastReceiver for passive system integrity signals.
+   *
+   * PURPOSE:
+   * - Reacts to system-level events that may indicate integrity changes
+   *   (e.g. package installation or replacement).
+   *
+   * NOTE:
+   * - Failures are logged but NOT propagated to JavaScript.
+   * - This receiver is observational and non-blocking.
+   */
+  private inner class IntegrityEventReceiver(private val onSignalDetected: (JSObject) -> Unit) : BroadcastReceiver() {
+    override fun onReceive(
+      context: Context?,
+      intent: Intent?,
+    ) {
+      when (intent?.action) {
+        Intent.ACTION_PACKAGE_ADDED, Intent.ACTION_PACKAGE_REPLACED -> {
+          val options =
+            IntegrityCheckOptions(
+              level = "standard",
+              includeDebugInfo = false,
+            )
+
+          // Execute integrity checks off the main/plugin thread to avoid blocking
+          execute {
+            try {
+              val result = implementation.performCheck(options)
+              val jsResult = IntegrityUtils.toJSObject(result)
+              onSignalDetected(jsResult)
+            } catch (e: IntegrityError) {
+              IntegrityLogger.error(
+                "IntegrityEventReceiver: Error during package change check: ${e.message}",
+              )
+            } catch (e: Exception) {
+              IntegrityLogger.error(
+                "IntegrityEventReceiver: Unexpected error during package change check: ${e.message}",
+              )
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/android/src/main/java/io/capkit/integrity/IntegrityReportBuilder.kt

@@ -0,0 +1,130 @@
+package io.capkit.integrity
+
+/**
+ * Helper responsible for assembling the final integrity report payload.
+ *
+ * Responsibilities:
+ * - Aggregate signals
+ * - Compute integrity score based on signal confidence
+ * - Build environment metadata
+ * - Produce a JS-bridge-safe map
+ *
+ * This builder contains NO platform-specific logic.
+ */
+object IntegrityReportBuilder {
+  /**
+   * Default compromise threshold.
+   *
+   * POLICY:
+   * - A single high-confidence signal is sufficient to mark
+   *   the environment as compromised.
+   *
+   * NOTE:
+   * - This value MUST remain aligned across platforms.
+   */
+  private const val COMPROMISE_THRESHOLD = 30
+
+  /**
+   * Builds the final integrity report returned to the JavaScript layer.
+   *
+   * CONTRACT:
+   * - Output structure MUST remain platform-agnostic
+   * - Scoring MUST be deterministic
+   * - No enforcement logic may be introduced here
+   */
+  fun buildReport(
+    signals: List<Map<String, Any>>,
+    isEmulator: Boolean,
+    platform: String = "android",
+  ): Map<String, Any> {
+    val score = computeScore(signals)
+    val scoreExplanation = buildScoreExplanation(signals)
+
+    return mapOf(
+      // Ordered list of all detected integrity signals.
+      "signals" to signals,
+      // Numeric integrity score derived from signal confidence.
+      "score" to score,
+      // Convenience flag indicating whether the device
+      // should be considered compromised.
+      "compromised" to (score >= COMPROMISE_THRESHOLD),
+      // Static environment metadata describing the runtime context.
+      "environment" to
+        mapOf(
+          "platform" to platform,
+          "isEmulator" to isEmulator,
+          // Reserved for future use
+          "isDebugBuild" to false,
+        ),
+      // Informational explanation describing how the score was derived.
+      // This metadata MUST NOT be treated as a security decision.
+      "scoreExplanation" to scoreExplanation,
+      // Millisecond-precision UNIX timestamp of report generation.
+      "timestamp" to System.currentTimeMillis(),
+    )
+  }
+
+  // ---------------------------------------------------------------------------
+  // Scoring
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Computes a heuristic risk score from collected signals.
+   *
+   * Scoring policy (aligned with iOS):
+   * - high   -> 30 points
+   * - medium -> 15 points
+   * - low    -> 5 points
+   */
+  private fun computeScore(signals: List<Map<String, Any>>): Int {
+    return signals.sumOf {
+      when (it["confidence"]) {
+        "high" -> 30
+        "medium" -> 15
+        "low" -> 5
+        else -> 0
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Score explanation
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Builds an informational explanation describing how the integrity
+   * score was derived from the detected signals.
+   *
+   * IMPORTANT:
+   * - This metadata is informational only.
+   * - It MUST NOT influence scoring or enforcement.
+   */
+  private fun buildScoreExplanation(signals: List<Map<String, Any>>): Map<String, Any> {
+    var high = 0
+    var medium = 0
+    var low = 0
+
+    val contributors = mutableListOf<String>()
+
+    for (signal in signals) {
+      (signal["id"] as? String)?.let { contributors.add(it) }
+
+      when (signal["confidence"]) {
+        "high" -> high++
+        "medium" -> medium++
+        "low" -> low++
+      }
+    }
+
+    return mapOf(
+      "totalSignals" to signals.size,
+      "byConfidence" to
+        mapOf(
+          "high" to high,
+          "medium" to medium,
+          "low" to low,
+        ),
+      "contributors" to contributors,
+    )
+  }
+}

package/android/src/main/java/io/capkit/integrity/IntegritySignalBuilder.kt

@@ -0,0 +1,72 @@
+package io.capkit.integrity
+
+/**
+ * Helper responsible for constructing standardized integrity signal maps.
+ *
+ * This mirrors the logic found in iOS IntegrityUtils to ensure
+ * cross-platform payload consistency.
+ */
+object IntegritySignalBuilder {
+  /**
+   * Builds a JSON-serializable integrity signal.
+   *
+   * CONTRACT:
+   * - id MUST be stable across platforms
+   * - category MUST be platform-agnostic
+   * - confidence MUST be one of: low | medium | high
+   */
+  fun build(
+    id: String,
+    category: String,
+    confidence: String,
+    description: String? = null,
+    metadata: Map<String, Any>? = null,
+    options: IntegrityCheckOptions,
+  ): Map<String, Any> {
+    val signal =
+      mutableMapOf<String, Any>(
+        "id" to id,
+        "category" to category,
+        "confidence" to confidence,
+      )
+
+    // Include description only if requested in options to avoid leaking diagnostics
+    if (options.includeDebugInfo && description != null) {
+      signal["description"] = description
+    }
+
+    // Include metadata if present
+    if (metadata != null) {
+      signal["metadata"] = metadata
+    }
+
+    return signal
+  }
+}
+
+object IntegritySignalIds {
+  // Remote Attestation
+  const val ANDROID_PLAY_INTEGRITY_VERDICT = "android_play_integrity_verdict"
+
+  // Root
+  const val ANDROID_ROOT_SU = "android_root_su"
+  const val ANDROID_TEST_KEYS = "android_test_keys"
+  const val ANDROID_ROOT_PACKAGE = "android_root_package"
+
+  // Emulator
+  const val ANDROID_EMULATOR = "android_emulator"
+
+  // Debug
+  const val ANDROID_DEBUGGER_ATTACHED = "android_debugger_attached"
+  const val ANDROID_RUNTIME_DEBUGGABLE = "android_runtime_debuggable"
+
+  // Hook / Instrumentation
+  const val ANDROID_FRIDA_MEMORY = "android_frida_memory"
+  const val ANDROID_FRIDA_PORT = "android_frida_port"
+  const val ANDROID_FRIDA_CORRELATION = "android_frida_correlation_confirmed"
+
+  // Tamper / RASP
+  const val ANDROID_SANDBOX_ESCAPED = "android_sandbox_escaped"
+  const val ANDROID_SIGNATURE_INVALID = "android_signature_invalid"
+  const val ANDROID_OVERLAY_DETECTED = "android_overlay_detected"
+}

package/android/src/main/java/io/capkit/integrity/emulator/IntegrityEmulatorChecks.kt

@@ -0,0 +1,38 @@
+package io.capkit.integrity.emulator
+
+import android.os.Build
+
+/**
+ * Detects emulators using correlated build properties.
+ */
+object IntegrityEmulatorChecks {
+  /**
+   * Determines if the current environment matches known emulator characteristics.
+   *
+   * NOTE: This is a best-effort heuristic approach where no single signal is
+   * authoritative on its own.
+   */
+  fun isEmulator(): Boolean {
+    return try {
+      val fingerprint = Build.FINGERPRINT
+      val model = Build.MODEL
+      val manufacturer = Build.MANUFACTURER
+      val hardware = Build.HARDWARE
+      val product = Build.PRODUCT
+
+      fingerprint.contains("generic") ||
+        fingerprint.startsWith("unknown") ||
+        model.contains("google_sdk") ||
+        model.contains("Emulator", ignoreCase = true) ||
+        model.contains("Android SDK built for x86") ||
+        manufacturer.contains("Genymotion", ignoreCase = true) ||
+        hardware.contains("goldfish") ||
+        hardware.contains("ranchu") ||
+        product.contains("sdk_google") ||
+        product.contains("google_sdk") ||
+        product.contains("vbox86p")
+    } catch (_: Exception) {
+      false
+    }
+  }
+}