catalyst-core-internal 0.1.2 → 0.1.4

package/README.md

@@ -7,8 +7,8 @@
 
 ## Table of Contents
 
--   Overview
--   Installation
+- Overview
+- Installation
 
 ## Overview
 
@@ -20,8 +20,8 @@ This version adds support for Universal app for both Android and iOS. Please che
 
 **System Requirements**
 
--   Node version 20.4.0 or later
--   Compatible with **macOS** and **Linux**
+- Node version 20.4.0 or later
+- Compatible with **macOS** and **Linux**
 
 **Automatic Installation**
 

package/bin/catalyst.js

@@ -13,6 +13,8 @@ const validCommands = [
     "serve",
     "devBuild",
     "devServe",
+    "plugin",
+    "plugins",
     "buildApp",
     "buildApp:ios",
     "buildApp:android",
@@ -67,11 +69,14 @@ const scriptIndex = args.findIndex(
         x === "serve" ||
         x === "devBuild" ||
         x === "devServe" ||
+        x === "plugin" ||
+        x === "plugins" ||
         isPlatformCommand(x, "buildApp") ||
         isPlatformCommand(x, "setupEmulator")
 )
 const script = scriptIndex === -1 ? args[0] : args[scriptIndex]
 const nodeArgs = scriptIndex > 0 ? args.slice(0, scriptIndex) : []
+const resolvedScript = script === "plugin" ? "plugins" : script
 
 if (validCommands.includes(script)) {
     // Handle platform-specific or combined commands
@@ -90,7 +95,9 @@ if (validCommands.includes(script)) {
         // Original commands
         const result = spawnSync(
             process.execPath,
-            nodeArgs.concat(require.resolve("../dist/scripts/" + script)).concat(args.slice(scriptIndex + 1)),
+            nodeArgs
+                .concat(require.resolve("../dist/scripts/" + resolvedScript))
+                .concat(args.slice(scriptIndex + 1)),
             { stdio: "inherit" }
         )
         handleProcessResult(result)

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/BridgeMessageValidator.kt

@@ -60,18 +60,10 @@ data class SchemaDefinition(
 object BridgeMessageValidator {
 
     private const val TAG = "BridgeMessageValidator"
-    private const val MAX_MESSAGE_SIZE = 10 * 1024 * 1024 // 10MB (match iOS)
+    private const val MAX_MESSAGE_SIZE = CatalystConstants.Bridge.MAX_MESSAGE_SIZE
 
-    // Valid commands (should match iOS CatalystConstants.Bridge.validCommands)
-    private val validCommands = setOf(
-        "openCamera",
-        "requestCameraPermission",
-        "pickFile",
-        "requestHapticFeedback",
-        "openFileWithIntent",
-        "getDeviceInfo",
-        "logger"
-    )
+    // Valid commands — single source of truth from CatalystConstants
+    private val validCommands = CatalystConstants.Bridge.VALID_COMMANDS
 
     // MARK: - Schema Definitions (mirror iOS schemas)
 

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/CustomWebview.kt

@@ -233,7 +233,7 @@ class CustomWebView(
         }
 
         // Additional security check: only allow whitelisted interface names
-        val allowedInterfaces = setOf("NativeBridge", "AndroidBridge")
+        val allowedInterfaces = setOf("NativeBridge", "AndroidBridge", "PluginBridge")
         if (name !in allowedInterfaces) {
             Log.e(TAG, "❌ Security: Interface name '$name' is not in whitelist. Refusing to add interface.")
             return
@@ -246,6 +246,17 @@ class CustomWebView(
         }
     }
 
+    fun removeJavascriptInterface(name: String) {
+        try {
+            webView.removeJavascriptInterface(name)
+            if (BuildConfig.DEBUG) {
+                Log.d(TAG, "🔌 Removed JavaScript interface: $name")
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "⚠️ Failed to remove JavaScript interface '$name': ${e.message}")
+        }
+    }
+
     fun destroy() {
         job.cancel()
         webView.destroy()

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/MainActivity.kt

@@ -14,6 +14,7 @@ import org.json.JSONObject
 import java.util.Properties
 import io.yourname.androidproject.databinding.ActivityMainBinding
 import io.yourname.androidproject.NativeBridge
+import io.yourname.androidproject.plugins.PluginBridge
 import io.yourname.androidproject.utils.BridgeUtils
 import io.yourname.androidproject.utils.KeyboardUtil
 import io.yourname.androidproject.utils.NetworkUtils
@@ -39,6 +40,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
 
     private lateinit var binding: ActivityMainBinding
     private lateinit var nativeBridge: NativeBridge
+    private lateinit var pluginBridge: PluginBridge
     private lateinit var customWebView: CustomWebView
     lateinit var properties: Properties
     private lateinit var metricsMonitor: MetricsMonitor
@@ -328,6 +330,14 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
             Log.e(TAG, "Failed to initialize NativeBridge: ${e.message}")
         }
 
+        // Setup isolated PluginBridge
+        try {
+            pluginBridge = PluginBridge(this, customWebView.getWebView(), properties)
+            customWebView.addJavascriptInterface(pluginBridge, "PluginBridge")
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to initialize PluginBridge: ${e.message}")
+        }
+
         setupSafeAreaHandling()
 
         // Setup back press handler (modern API)
@@ -445,11 +455,16 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
         if (::keyboardUtil.isInitialized) {
             keyboardUtil.cleanup()
         }
-        if (::nativeBridge.isInitialized) {
-            nativeBridge.cleanup()
+        if (::customWebView.isInitialized) {
+            if (::pluginBridge.isInitialized) {
+                customWebView.removeJavascriptInterface("PluginBridge")
+            }
+            if (::nativeBridge.isInitialized) {
+                customWebView.removeJavascriptInterface("NativeBridge")
+            }
+            customWebView.destroy()
         }
         coroutineContext.cancelChildren()
-        customWebView.destroy()
         super.onDestroy()
     }
 

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/plugins/CatalystPlugin.kt

@@ -0,0 +1,7 @@
+package io.yourname.androidproject.plugins
+
+import org.json.JSONObject
+
+interface CatalystPlugin {
+    fun handle(command: String, data: JSONObject?, bridge: PluginBridgeContext)
+}

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/plugins/GeneratedPluginIndex.kt

@@ -0,0 +1,6 @@
+package io.yourname.androidproject.plugins
+
+object GeneratedPluginIndex {
+    val pluginIdToClassName: Map<String, String> = emptyMap()
+    val pluginToCommands: Map<String, Set<String>> = emptyMap()
+}

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/plugins/PluginBridge.kt

@@ -0,0 +1,253 @@
+package io.yourname.androidproject.plugins
+
+import android.app.Activity
+import android.content.Context
+import android.util.Log
+import android.webkit.JavascriptInterface
+import android.webkit.WebView
+import io.yourname.androidproject.CatalystConstants
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+import java.util.Properties
+
+internal data class PluginRequest(
+    val pluginId: String,
+    val command: String,
+    val data: JSONObject?,
+    val requestId: String?
+)
+
+private class PluginBridgeRuntimeError(
+    val publicMessage: String,
+    val code: String,
+    cause: Throwable? = null
+) : Exception(publicMessage, cause)
+
+class PluginBridge(
+    private val activity: Activity,
+    private val webView: WebView,
+    private val properties: Properties
+) {
+    companion object {
+        private const val TAG = "PluginBridge"
+        private const val ERROR_EVENT = "PLUGIN_BRIDGE_ERROR"
+        private const val SYSTEM_PLUGIN_ID = "__bridge__"
+        private const val ERROR_CODE_INVALID_PAYLOAD = "INVALID_PAYLOAD"
+        private const val ERROR_CODE_PLUGIN_NOT_FOUND = "PLUGIN_NOT_FOUND"
+        private const val ERROR_CODE_COMMAND_NOT_SUPPORTED = "COMMAND_NOT_SUPPORTED"
+        private const val ERROR_CODE_PLUGIN_NOT_REGISTERED = "PLUGIN_NOT_REGISTERED"
+        private const val ERROR_CODE_PLUGIN_INSTANTIATION_FAILED = "PLUGIN_INSTANTIATION_FAILED"
+        private const val ERROR_CODE_PLUGIN_EXECUTION_FAILED = "PLUGIN_EXECUTION_FAILED"
+
+        private fun readRequiredString(body: JSONObject, key: String): String {
+            if (!body.has(key) || body.isNull(key)) {
+                return ""
+            }
+
+            val rawValue = body.get(key)
+            if (rawValue !is String) {
+                throw IllegalArgumentException("$key must be a string")
+            }
+
+            return rawValue.trim()
+        }
+
+        private fun readOptionalString(body: JSONObject, key: String): String? {
+            if (!body.has(key) || body.isNull(key)) {
+                return null
+            }
+
+            val rawValue = body.get(key)
+            if (rawValue !is String) {
+                throw IllegalArgumentException("$key must be a string when provided")
+            }
+
+            return rawValue.trim().ifEmpty { null }
+        }
+
+        private fun readOptionalObject(body: JSONObject, key: String): JSONObject? {
+            if (!body.has(key) || body.isNull(key)) {
+                return null
+            }
+
+            val rawValue = body.get(key)
+            if (rawValue !is JSONObject) {
+                throw IllegalArgumentException("$key must be an object when provided")
+            }
+
+            return rawValue
+        }
+
+        internal fun parseRequest(payload: String?): PluginRequest {
+            if (payload.isNullOrBlank()) {
+                throw IllegalArgumentException("Payload is required")
+            }
+            val messageSize = payload.toByteArray(Charsets.UTF_8).size
+            if (messageSize > CatalystConstants.Bridge.MAX_MESSAGE_SIZE) {
+                throw IllegalArgumentException("Payload exceeds maximum size")
+            }
+
+            val body = JSONObject(payload)
+            return PluginRequest(
+                pluginId = readRequiredString(body, "pluginId"),
+                command = readRequiredString(body, "command"),
+                data = readOptionalObject(body, "data"),
+                requestId = readOptionalString(body, "requestId")
+            )
+        }
+    }
+
+    private val pluginIdToClassName = GeneratedPluginIndex.pluginIdToClassName
+    private val pluginToCommands = GeneratedPluginIndex.pluginToCommands
+
+    @JavascriptInterface
+    fun emit(payload: String?) {
+        var request: PluginRequest? = null
+
+        try {
+            request = parseRequest(payload)
+
+            if (request.pluginId.isEmpty()) {
+                sendBridgeError("pluginId is required", ERROR_CODE_INVALID_PAYLOAD, request)
+                return
+            }
+            if (request.command.isEmpty()) {
+                sendBridgeError("command is required", ERROR_CODE_INVALID_PAYLOAD, request)
+                return
+            }
+
+            if (!hasPlugin(request.pluginId)) {
+                sendBridgeError("Unsupported plugin: ${request.pluginId}", ERROR_CODE_PLUGIN_NOT_FOUND, request)
+                return
+            }
+
+            if (!hasCommand(request.pluginId, request.command)) {
+                sendBridgeError(
+                    "Unsupported command '${request.command}' for plugin '${request.pluginId}'",
+                    ERROR_CODE_COMMAND_NOT_SUPPORTED,
+                    request
+                )
+                return
+            }
+
+            val plugin = try {
+                getPluginForId(request.pluginId)
+            } catch (error: PluginBridgeRuntimeError) {
+                sendBridgeError(error.publicMessage, error.code, request)
+                return
+            }
+
+            val callbackContext = PluginBridgeContext(
+                activity = activity,
+                webView = webView,
+                properties = properties,
+                pluginId = request.pluginId,
+                command = request.command,
+                requestId = request.requestId
+            )
+
+            plugin.handle(request.command, request.data, callbackContext)
+        } catch (error: IllegalArgumentException) {
+            sendBridgeError(error.message ?: "Invalid payload", ERROR_CODE_INVALID_PAYLOAD, request)
+        } catch (error: JSONException) {
+            sendBridgeError("Invalid JSON payload", ERROR_CODE_INVALID_PAYLOAD, request)
+        } catch (error: Exception) {
+            Log.e(TAG, "Plugin command failed for ${request?.pluginId ?: "<unknown>"}.${request?.command ?: "<unknown>"}", error)
+            sendBridgeError("Plugin execution failed", ERROR_CODE_PLUGIN_EXECUTION_FAILED, request)
+        }
+    }
+
+    private fun sendBridgeError(message: String, code: String, request: PluginRequest?) {
+        PluginBridgeContext(
+            activity = activity,
+            webView = webView,
+            properties = properties,
+            pluginId = SYSTEM_PLUGIN_ID,
+            command = request?.command,
+            requestId = request?.requestId
+        ).callback(
+            ERROR_EVENT,
+            JSONObject().apply {
+                put("message", message)
+                put("code", code)
+                put("pluginId", request?.pluginId ?: SYSTEM_PLUGIN_ID)
+                request?.command?.takeIf { it.isNotEmpty() }?.let { put("command", it) }
+            }
+        )
+    }
+
+    private fun hasPlugin(pluginId: String): Boolean {
+        return pluginIdToClassName.containsKey(pluginId)
+    }
+
+    private fun hasCommand(pluginId: String, command: String): Boolean {
+        return pluginToCommands[pluginId]?.contains(command) ?: false
+    }
+
+    private fun getPluginForId(pluginId: String): CatalystPlugin {
+        val className = pluginIdToClassName[pluginId]
+            ?: throw PluginBridgeRuntimeError(
+                "Plugin is not registered",
+                ERROR_CODE_PLUGIN_NOT_REGISTERED
+            )
+
+        return try {
+            val clazz = Class.forName(className)
+            val instance = clazz.getDeclaredConstructor().newInstance()
+            instance as? CatalystPlugin
+                ?: throw IllegalStateException("Plugin class '$className' must implement CatalystPlugin")
+        } catch (error: Exception) {
+            Log.e(TAG, "Failed to instantiate plugin class $className for plugin $pluginId", error)
+            throw PluginBridgeRuntimeError(
+                "Plugin could not be initialized",
+                ERROR_CODE_PLUGIN_INSTANTIATION_FAILED,
+                error
+            )
+        }
+    }
+}
+
+class PluginBridgeContext(
+    val activity: Activity,
+    val webView: WebView,
+    val properties: Properties,
+    val pluginId: String,
+    val command: String?,
+    val requestId: String?
+) {
+    val context: Context
+        get() = activity
+
+    fun callback(
+        eventName: String,
+        data: Any?,
+        command: String? = this.command
+    ) {
+        require(eventName.isNotBlank()) { "Callback eventName is required" }
+
+        val pluginLiteral = JSONObject.quote(pluginId)
+        val eventLiteral = JSONObject.quote(eventName)
+        val dataLiteral = toJavaScriptLiteral(data)
+        val requestLiteral = requestId?.let(JSONObject::quote) ?: "null"
+        val commandLiteral = command?.takeIf { it.isNotBlank() }?.let(JSONObject::quote) ?: "null"
+
+        webView.post {
+            webView.evaluateJavascript(
+                "window.PluginBridgeWeb && window.PluginBridgeWeb.callback($pluginLiteral, $eventLiteral, $dataLiteral, $requestLiteral, $commandLiteral);",
+                null
+            )
+        }
+    }
+
+    private fun toJavaScriptLiteral(value: Any?): String {
+        return when (value) {
+            null -> "null"
+            is JSONObject -> value.toString()
+            is JSONArray -> value.toString()
+            is Number, is Boolean -> value.toString()
+            is String -> JSONObject.quote(value)
+            else -> JSONObject.wrap(value)?.toString() ?: "null"
+        }
+    }
+}

package/dist/native/androidProject/app/src/test/java/io/yourname/androidproject/SecurityBridgeTest.kt

@@ -0,0 +1,199 @@
+package io.yourname.androidproject
+
+import org.json.JSONObject
+import org.junit.Assert.*
+import org.junit.Test
+
+/**
+ * Unit tests for security bridge command routing and JSON injection safety.
+ *
+ * Coverage:
+ * - setScreenSecure command routing (5 tests)
+ * - getScreenSecure command routing (2 tests)
+ * - clearWebData command routing (2 tests)
+ * - JSON injection safety in error responses (3 tests)
+ *
+ * Total: 12 tests
+ *
+ * Note: These tests operate on static parsing/validation logic and JSON data
+ * structures. Full lifecycle (FLAG_SECURE, CookieManager) is exercised in
+ * device integration tests; here we confirm command acceptance, param parsing,
+ * and that error payloads produced via JSONObject cannot carry injected content.
+ */
+class SecurityBridgeTest {
+
+    // ============================================================
+    // CATEGORY 1: setScreenSecure COMMAND ROUTING (5 tests)
+    // ============================================================
+
+    @Test
+    fun `test setScreenSecure command is accepted by validator`() {
+        val messageJson = """{"command": "setScreenSecure", "data": {"enable": true}}"""
+
+        val result = NativeBridge.parseAndValidateMessage(messageJson)
+
+        assertTrue("setScreenSecure should be a valid command", result.isValid)
+        assertEquals("setScreenSecure", result.command)
+        assertNull(result.error)
+    }
+
+    @Test
+    fun `test setScreenSecure enable true parsed from params`() {
+        val params = JSONObject().apply { put("enable", true) }
+
+        val enable = params.optBoolean("enable", false)
+
+        assertTrue("enable should be true", enable)
+    }
+
+    @Test
+    fun `test setScreenSecure enable false parsed from params`() {
+        val params = JSONObject().apply { put("enable", false) }
+
+        val enable = params.optBoolean("enable", true)
+
+        assertFalse("enable should be false", enable)
+    }
+
+    @Test
+    fun `test setScreenSecure defaults to true when params are malformed`() {
+        // NativeBridge.setScreenSecure falls back to true when JSON parse fails
+        val malformedParams = "not-json"
+        val enable = try {
+            JSONObject(malformedParams).optBoolean("enable", true)
+        } catch (e: Exception) {
+            true
+        }
+
+        assertTrue("Malformed params should default to enable=true", enable)
+    }
+
+    @Test
+    fun `test setScreenSecure success response shape`() {
+        val enable = true
+        val response = JSONObject().apply {
+            put("secure", enable)
+            put("success", true)
+        }
+
+        assertTrue(response.getBoolean("secure"))
+        assertTrue(response.getBoolean("success"))
+        // Verify no extra fields bleed in
+        assertEquals(2, response.length())
+    }
+
+    // ============================================================
+    // CATEGORY 2: getScreenSecure COMMAND ROUTING (2 tests)
+    // ============================================================
+
+    @Test
+    fun `test getScreenSecure command is accepted by validator`() {
+        val messageJson = """{"command": "getScreenSecure", "data": {}}"""
+
+        val result = NativeBridge.parseAndValidateMessage(messageJson)
+
+        assertTrue("getScreenSecure should be a valid command", result.isValid)
+        assertEquals("getScreenSecure", result.command)
+        assertNull(result.error)
+    }
+
+    @Test
+    fun `test getScreenSecure status response shape`() {
+        // Validate that the JSON payload produced by getScreenSecure is well-formed
+        val isSecure = false
+        val response = JSONObject().apply {
+            put("secure", isSecure)
+            put("success", true)
+        }
+
+        assertFalse(response.getBoolean("secure"))
+        assertTrue(response.getBoolean("success"))
+        assertEquals(2, response.length())
+    }
+
+    // ============================================================
+    // CATEGORY 3: clearWebData COMMAND ROUTING (2 tests)
+    // ============================================================
+
+    @Test
+    fun `test clearWebData command is accepted by validator`() {
+        val messageJson = """{"command": "clearWebData", "data": {}}"""
+
+        val result = NativeBridge.parseAndValidateMessage(messageJson)
+
+        assertTrue("clearWebData should be a valid command", result.isValid)
+        assertEquals("clearWebData", result.command)
+        assertNull(result.error)
+    }
+
+    @Test
+    fun `test clearWebData success response shape`() {
+        val cookiesRemoved = true
+        val response = JSONObject().apply {
+            put("success", true)
+            put("cookiesRemoved", cookiesRemoved)
+        }
+
+        assertTrue(response.getBoolean("success"))
+        assertTrue(response.getBoolean("cookiesRemoved"))
+        assertEquals(2, response.length())
+    }
+
+    // ============================================================
+    // CATEGORY 4: JSON INJECTION SAFETY (3 tests)
+    // ============================================================
+
+    @Test
+    fun `test error message with injection characters is safe via JSONObject`() {
+        // Simulate an exception message that contains characters dangerous in naive JS
+        // string interpolation: double-quotes and backslashes.
+        // JSONObject must escape them so the serialized JSON stays valid and cannot
+        // break out of the surrounding JS string literal in notifyWebJson.
+        val injectionPayload = "failed\"; window[\"evil\"]=\"injected"
+
+        val response = JSONObject().apply {
+            put("success", false)
+            put("error", injectionPayload)
+        }
+
+        val serialized = response.toString()
+
+        // The raw unescaped double-quote sequence that would break JS must not appear
+        assertFalse(
+            "Unescaped double-quote injection sequence must not appear in serialized JSON",
+            serialized.contains("\"evil\"")
+        )
+        // The value must survive a round-trip intact
+        assertEquals(injectionPayload, JSONObject(serialized).getString("error"))
+    }
+
+    @Test
+    fun `test error message with backslash sequences is safe via JSONObject`() {
+        val backslashPayload = "err\\\"injected\\\""
+
+        val response = JSONObject().apply {
+            put("success", false)
+            put("error", backslashPayload)
+        }
+
+        // Round-trip must survive without throwing
+        val roundTripped = JSONObject(response.toString()).getString("error")
+        assertEquals(backslashPayload, roundTripped)
+    }
+
+    @Test
+    fun `test setScreenSecure and clearWebData commands are in VALID_COMMANDS whitelist`() {
+        assertTrue(
+            "setScreenSecure must be whitelisted",
+            CatalystConstants.Bridge.VALID_COMMANDS.contains("setScreenSecure")
+        )
+        assertTrue(
+            "getScreenSecure must be whitelisted",
+            CatalystConstants.Bridge.VALID_COMMANDS.contains("getScreenSecure")
+        )
+        assertTrue(
+            "clearWebData must be whitelisted",
+            CatalystConstants.Bridge.VALID_COMMANDS.contains("clearWebData")
+        )
+    }
+}