@cap-kit/integrity 8.0.0-next.6

package/android/build.gradle

@@ -0,0 +1,104 @@
+buildscript {
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+plugins {
+    id "org.jlleitschuh.gradle.ktlint" version "12.1.1" apply false
+}
+
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    androidxCoreKTXVersion = project.hasProperty('androidxCoreKTXVersion') ? rootProject.ext.androidxCoreKTXVersion : '1.17.0'
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'kotlin-parcelize'
+apply plugin: 'org.jlleitschuh.gradle.ktlint'
+
+import groovy.json.JsonSlurper
+
+def getPluginVersion() {
+    try {
+        def packageJsonFile = file('../package.json')
+        if (packageJsonFile.exists()) {
+            def packageJson = new JsonSlurper().parseText(packageJsonFile.text)
+            return packageJson.version
+        }
+    } catch (Exception e) {
+        // Ignore errors and fallback
+        logger.info("Exception", e)
+    }
+    return "8.0.0"
+}
+
+def pluginVersion = getPluginVersion()
+
+android {
+    namespace = "io.capkit.integrity"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion as Integer  : 36
+
+    // AGP 8.0+ disables BuildConfig by default for libraries.
+    // We need to enable it to inject the plugin version.
+    buildFeatures {
+        buildConfig = true
+    }
+
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion as Integer  : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion as Integer  : 36
+        versionCode 1
+
+        // Dynamic versioning (feature enabled)
+        versionName = pluginVersion
+
+        // Injects the version into the BuildConfig class ONLY if feature is enabled
+        buildConfigField "String", "PLUGIN_VERSION", "\"${pluginVersion}\""
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled = false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lint {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation "androidx.core:core-ktx:$androidxCoreKTXVersion"
+
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,21 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <queries>
+        <package android:name="com.noshufou.android.su" />
+        <package android:name="com.thirdparty.superuser" />
+        <package android:name="eu.chainfire.supersu" />
+        <package android:name="com.koushikdutta.superuser" />
+        <package android:name="com.zachareew.systemuituner" />
+        <package android:name="com.topjohnwu.magisk" />
+        <package android:name="com.alephzain.framaroot" />
+        <package android:name="org.adaway" />
+    </queries>
+
+    <application>
+        <activity
+            android:name=".ui.IntegrityBlockActivity"
+            android:exported="false"
+            android:theme="@style/IntegrityBlockTheme" />
+    </application>
+</manifest>

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

@@ -0,0 +1,37 @@
+package io.capkit.integrity
+
+/**
+ * Native representation of `Integrity.check()` options.
+ *
+ * This model mirrors the JavaScript options object and is used
+ * to control how integrity checks are executed.
+ *
+ * Design principles:
+ * - Independent from the Plugin (Bridge) layer
+ * - Safe to use inside the native Implementation layer
+ * - Derived exclusively from JS input
+ * - Does NOT alter the public JS API shape
+ *
+ * Notes:
+ * - Default values are applied in the Plugin layer
+ * - The Implementation layer assumes normalized values
+ */
+data class IntegrityCheckOptions(
+  /**
+   * Desired strictness level for integrity checks.
+   *
+   * Supported values:
+   * - "basic": minimal checks (root, emulator)
+   * - "standard": adds debug and instrumentation checks
+   * - "strict": enables all available heuristics
+   */
+  val level: String,
+  /**
+   * Whether debug-only information should be included
+   * in returned integrity signals.
+   *
+   * When true, signals MAY contain a human-readable
+   * `description` field for diagnostic purposes.
+   */
+  val includeDebugInfo: Boolean,
+)

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

@@ -0,0 +1,59 @@
+package io.capkit.integrity
+
+import android.content.Context
+import com.getcapacitor.Plugin
+
+/**
+ * Plugin configuration container.
+ *
+ * This class is responsible for reading and exposing
+ * static configuration values defined under the
+ * `Integrity` key in capacitor.config.ts.
+ *
+ * Configuration rules:
+ * - Read once during plugin initialization
+ * - Treated as immutable runtime input
+ * - Accessible only from native code
+ */
+class IntegrityConfig(plugin: Plugin) {
+  /**
+   * Android application context.
+   * Exposed for native components that may require it.
+   */
+  val context: Context = plugin.context
+
+  /**
+   * Enables verbose native logging.
+   *
+   * When enabled, additional debug information
+   * is printed to Logcat.
+   *
+   * Default: false
+   */
+  val verboseLogging: Boolean
+
+  /**
+   *
+   * Default: false
+   */
+  val blockPageEnabled: Boolean
+
+  /**
+   *
+   */
+  val blockPageUrl: String?
+
+  init {
+    val config = plugin.getConfig()
+
+    // Verbose logging flag
+    verboseLogging =
+      config.getBoolean("verboseLogging", false)
+
+    val blockPage = config.getObject("blockPage")
+
+    blockPageEnabled = blockPage?.getBoolean("enabled") ?: false
+
+    blockPageUrl = blockPage?.getString("url")
+  }
+}

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

@@ -0,0 +1,40 @@
+package io.capkit.integrity
+
+/**
+ * Native error model for the Integrity plugin (Android).
+ *
+ * Architectural rules:
+ * - Must NOT reference Capacitor APIs
+ * - Must NOT reference JavaScript
+ * - Must be throwable from the Impl layer
+ * - Mapping to JS-facing error codes happens ONLY in the Plugin layer
+ */
+sealed class IntegrityError(
+  message: String,
+) : Throwable(message) {
+  /**
+   * Feature or capability is not available
+   * due to device or configuration limitations.
+   */
+  class Unavailable(message: String) :
+    IntegrityError(message)
+
+  /**
+   * Required permission was denied or not granted.
+   */
+  class PermissionDenied(message: String) :
+    IntegrityError(message)
+
+  /**
+   * Plugin failed to initialize or perform
+   * a required operation.
+   */
+  class InitFailed(message: String) :
+    IntegrityError(message)
+
+  /**
+   * Invalid or unsupported input was provided.
+   */
+  class UnknownType(message: String) :
+    IntegrityError(message)
+}

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

@@ -0,0 +1,319 @@
+package io.capkit.integrity
+
+import android.content.Context
+import io.capkit.integrity.emulator.IntegrityEmulatorChecks
+import io.capkit.integrity.filesystem.IntegrityFilesystemChecks
+import io.capkit.integrity.hook.IntegrityHookChecks
+import io.capkit.integrity.remote.IntegrityRemoteAttestor
+import io.capkit.integrity.root.IntegrityRootDetector
+import io.capkit.integrity.runtime.IntegrityRuntimeChecks
+import io.capkit.integrity.ui.IntegrityUISignals
+import io.capkit.integrity.utils.IntegrityLogger
+import java.util.Collections
+
+/**
+ * Native Android implementation for the Integrity plugin.
+ *
+ * CONTRACT:
+ * - This class MUST NOT reference:
+ *   - PluginCall
+ *   - Capacitor APIs
+ *   - Activities or UI components
+ *
+ * Responsibilities:
+ * - Perform platform-specific integrity checks
+ * - Interact with Android system APIs
+ * - Produce platform-agnostic integrity signals
+ *
+ * Error handling:
+ * - MUST throw typed IntegrityError on unrecoverable failures
+ * - MUST NOT swallow fatal initialization errors
+ */
+class IntegrityImpl(
+  private val context: Context,
+) {
+  // ---------------------------------------------------------------------------
+  // Signal lifecycle & execution model
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Signal production in this implementation follows a two-phase model:
+   *
+   * 1. Early boot phase (optional, best-effort)
+   *    - Signals may be captured before the Capacitor bridge is initialized.
+   *    - Early signals are collected via the static `onApplicationCreate` entry point.
+   *    - Captured signals are stored in a volatile in-memory buffer (`bootSignals`).
+   *    - Early boot detection is opportunistic and NOT guaranteed.
+   *
+   * 2. Runtime phase (authoritative)
+   *    - Signals are produced when `check(...)` is invoked from JavaScript.
+   *    - Any previously captured boot signals are merged into the first report.
+   *    - Subsequent checks operate exclusively on runtime detection.
+   *
+   * IMPORTANT SEMANTICS:
+   * - Boot signals are best-effort and may be absent depending on
+   *   process lifecycle, OS behavior, or warm starts.
+   * - Boot signals do NOT provide stronger guarantees than runtime signals.
+   * - The absence of boot signals does NOT indicate a clean environment.
+   *
+   * This design improves detection timing, not detection coverage.
+   */
+  companion object {
+    /**
+     * Volatile buffer for signals captured during early boot.
+     */
+    private val bootSignals = Collections.synchronizedList(mutableListOf<Map<String, Any>>())
+
+    /**
+     * Native entry point for MainActivity.onCreate.
+     * Captures security signals before the Capacitor bridge is initialized.
+     */
+    @JvmStatic
+    fun onApplicationCreate(context: Context) {
+      // Capture basic root signals immediately at boot using the dedicated detector
+      val signals =
+        IntegrityRootDetector.checkRootSignals(
+          IntegrityCheckOptions(
+            level = "basic",
+            includeDebugInfo = false,
+          ),
+          allowCache = false,
+        )
+      bootSignals.addAll(signals)
+    }
+  }
+
+  // Negative cache for expensive integrity checks.
+  // Caches only "no-signal" results for a short time window.
+  private data class NegativeCacheEntry(
+    val timestampMs: Long,
+  )
+
+  private val negativeCache = mutableMapOf<String, NegativeCacheEntry>()
+
+  private val negativeCacheTtlMs = 30_000L
+
+  // ---------------------------------------------------------------------------
+  // Remote Attestation
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Stub for Google Play Integrity integration.
+   * To be implemented in a future evolution step.
+   */
+  fun getPlayIntegritySignal(options: IntegrityCheckOptions): Map<String, Any>? {
+    return IntegrityRemoteAttestor.getPlayIntegritySignal(context, options)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Configuration
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Cached immutable plugin configuration.
+   */
+  private lateinit var config: IntegrityConfig
+
+  /**
+   * Applies static plugin configuration.
+   */
+  fun updateConfig(newConfig: IntegrityConfig) {
+    this.config = newConfig
+    IntegrityLogger.verbose = newConfig.verboseLogging
+
+    IntegrityLogger.debug(
+      "Integrity configuration applied. Verbose logging:",
+      newConfig.verboseLogging.toString(),
+    )
+  }
+
+  // ---------------------------------------------------------------------------
+  // Options orchestrator
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Executes the requested integrity checks and aggregates signals.
+   */
+  fun performCheck(options: IntegrityCheckOptions): Map<String, Any> {
+    // Apply negative cache only for standard / strict levels.
+    // Cached results represent a recent "no-signal" execution.
+    if (options.level != "basic" && isNegativeCacheValid(options.level)) {
+      IntegrityLogger.debug(
+        "Negative cache hit for integrity check:",
+        options.level,
+      )
+
+      return IntegrityReportBuilder.buildReport(
+        emptyList(),
+        isEmulator = false,
+      )
+    }
+
+    val signals = mutableListOf<Map<String, Any>>()
+
+    // --- BOOT SIGNALS ----------------------------------------------------
+    // Merge signals captured during early boot and clear the buffer.
+    synchronized(bootSignals) {
+      signals.addAll(bootSignals)
+      bootSignals.clear()
+    }
+
+    // --- BASIC -----------------------------------------------------------
+
+    // Root filesystem & build-tag detection (cached, runtime)
+    signals.addAll(
+      IntegrityRootDetector.checkRootSignals(
+        options = options,
+        allowCache = true,
+      ),
+    )
+
+    // Known root management packages (runtime-only)
+    signals.addAll(
+      IntegrityRootDetector.checkRootPackages(
+        context = context,
+        options = options,
+      ),
+    )
+
+    // Sandbox escape heuristics (non-deterministic, filesystem-based)
+    IntegrityFilesystemChecks
+      .checkSandboxEscape(options)
+      ?.let { signals.add(it) }
+
+    val isEmulator = IntegrityEmulatorChecks.isEmulator()
+    if (isEmulator) {
+      signals.add(
+        IntegritySignalBuilder.build(
+          id = "android_emulator",
+          category = "emulator",
+          confidence = "high",
+          description = "Execution environment matches known emulator characteristics",
+          // Added metadata to identify common emulator properties
+          metadata =
+            mapOf(
+              "model" to android.os.Build.MODEL,
+              "manufacturer" to android.os.Build.MANUFACTURER,
+              "hardware" to android.os.Build.HARDWARE,
+            ),
+          options = options,
+        ),
+      )
+    }
+
+    // --- STANDARD & STRICT -----------------------------------------------
+
+    if (options.level != "basic") {
+      // checkDebug returns a list of signals
+      signals.addAll(IntegrityRuntimeChecks.checkDebugSignals(context, options))
+
+      // UI and Overlay detection (RASP)
+      IntegrityUISignals
+        .checkOverlaySignals(context, options)
+        ?.let { signals.add(it) }
+
+      // --- HOOKING DETECTION --------------------------------------------
+
+      // Frida detection via memory maps
+      val memHook = IntegrityHookChecks.checkFridaMemory()
+
+      if (memHook) {
+        signals.add(
+          IntegritySignalBuilder.build(
+            id = "android_frida_memory",
+            category = "hook",
+            confidence = "high",
+            description = "Process memory contains known instrumentation artifacts",
+            options = options,
+          ),
+        )
+      }
+
+      // Frida detection via known ports
+      val portHook = IntegrityHookChecks.checkFridaPorts()
+      if (portHook) {
+        signals.add(
+          IntegritySignalBuilder.build(
+            id = "android_frida_port",
+            category = "hook",
+            confidence = "medium",
+            description = "Known instrumentation ports are reachable on localhost",
+            options = options,
+          ),
+        )
+      }
+
+      // Signal correlation logic
+      if (memHook && portHook) {
+        signals.add(
+          IntegritySignalBuilder.build(
+            id = "android_frida_correlation_confirmed",
+            category = "hook",
+            confidence = "high",
+            description = "Multiple instrumentation indicators detected simultaneously",
+            metadata = mapOf("source" to "memory+port"),
+            options = options,
+          ),
+        )
+      }
+    }
+
+    // --- STRICT --------------------------------------------------------------
+
+    if (options.level == "strict") {
+      // Google Play Integrity (future remote attestation)
+      IntegrityRemoteAttestor
+        .getPlayIntegritySignal(context, options)
+        ?.let { signals.add(it) }
+
+      // Verify application signature integrity
+      if (!IntegrityRuntimeChecks.checkAppSignature(context)) {
+        signals.add(
+          IntegritySignalBuilder.build(
+            id = "android_signature_invalid",
+            category = "tamper",
+            confidence = "high",
+            description = "Application signing information does not match expected format",
+            // Added metadata to specify the source of the signature check failure
+            metadata = mapOf("package" to context.packageName),
+            options = options,
+          ),
+        )
+      }
+    }
+
+    // Update negative cache only when no integrity signals are detected.
+    // Any detected signal invalidates the cached clean state.
+    if (options.level != "basic") {
+      if (signals.isEmpty()) {
+        updateNegativeCache(options.level)
+      } else {
+        clearNegativeCache(options.level)
+      }
+    }
+
+    // Final report assembly using the dedicated builder
+    return IntegrityReportBuilder.buildReport(
+      signals,
+      isEmulator,
+    )
+  }
+
+  private fun cacheKey(level: String): String {
+    return "android:$level"
+  }
+
+  private fun isNegativeCacheValid(level: String): Boolean {
+    val entry = negativeCache[cacheKey(level)] ?: return false
+    return System.currentTimeMillis() - entry.timestampMs <= negativeCacheTtlMs
+  }
+
+  private fun updateNegativeCache(level: String) {
+    negativeCache[cacheKey(level)] =
+      NegativeCacheEntry(System.currentTimeMillis())
+  }
+
+  private fun clearNegativeCache(level: String) {
+    negativeCache.remove(cacheKey(level))
+  }
+}