android-sdd 1.0.0

package/skills/Build System/Specialized/JNI/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: jni
+description: >
+  Java Native Interface (JNI) for Android — calling native C/C++ code from Kotlin.
+  Load this skill when bridging Kotlin and native code, declaring native methods,
+  handling JNI types, managing memory across the JNI boundary,
+  or passing complex objects between Kotlin and C/C++.
+---
+
+# JNI
+
+## Overview
+JNI (Java Native Interface) is the bridge between Kotlin/Java code and native C/C++ code in Android. It allows calling C/C++ functions from Kotlin and vice versa. JNI is used for performance-critical code, hardware access, reusing existing C/C++ libraries, or code that must resist reverse engineering.
+
+---
+
+## Core Principles
+
+- **Minimize JNI boundary crossings** — each call has overhead; batch operations
+- **JNI calls are synchronous** — run on the calling thread; use coroutines/threads on the Kotlin side
+- **Memory is manual in native code** — no GC; always release resources
+- **JNI types map to Java types** — `jstring` not `String`, `jint` not `Int`
+- **Avoid storing JNI objects across calls** — use Global References when needed
+
+---
+
+## Basic Setup
+
+```kotlin
+// build.gradle.kts
+android {
+    defaultConfig {
+        externalNativeBuild {
+            cmake {
+                cppFlags("-std=c++17", "-O2")
+            }
+        }
+    }
+    externalNativeBuild {
+        cmake {
+            path("src/main/cpp/CMakeLists.txt")
+            version("3.22.1")
+        }
+    }
+}
+```
+
+```cmake
+# src/main/cpp/CMakeLists.txt
+cmake_minimum_required(VERSION 3.22.1)
+project("myapp")
+
+add_library(
+    myapp-native
+    SHARED
+    native_lib.cpp
+)
+
+find_library(log-lib log)
+
+target_link_libraries(
+    myapp-native
+    ${log-lib}
+)
+```
+
+---
+
+## Declaring Native Methods
+
+```kotlin
+// ✅ Kotlin side — declare native functions
+class NativeCrypto {
+    external fun encrypt(data: ByteArray, key: ByteArray): ByteArray
+    external fun decrypt(data: ByteArray, key: ByteArray): ByteArray
+    external fun generateKey(): ByteArray
+
+    companion object {
+        init {
+            System.loadLibrary("myapp-native")
+        }
+    }
+}
+```
+
+```cpp
+// ✅ C++ side — implement with JNI naming convention
+// Package: com.example.app.security
+// Class: NativeCrypto
+// Function name format: Java_<package>_<class>_<method>
+
+#include <jni.h>
+#include <string>
+
+extern "C" {
+
+JNIEXPORT jbyteArray JNICALL
+Java_com_example_app_security_NativeCrypto_encrypt(
+    JNIEnv* env,
+    jobject /* this */,
+    jbyteArray data,
+    jbyteArray key
+) {
+    // Get data from Java
+    jsize dataLen = env->GetArrayLength(data);
+    jbyte* dataBytes = env->GetByteArrayElements(data, nullptr);
+    jbyte* keyBytes = env->GetByteArrayElements(key, nullptr);
+
+    // Perform encryption (simplified)
+    jbyteArray result = env->NewByteArray(dataLen);
+    jbyte* resultBytes = env->GetByteArrayElements(result, nullptr);
+
+    for (jsize i = 0; i < dataLen; i++) {
+        resultBytes[i] = dataBytes[i] ^ keyBytes[i % env->GetArrayLength(key)];
+    }
+
+    // ✅ Always release elements
+    env->ReleaseByteArrayElements(data, dataBytes, JNI_ABORT);
+    env->ReleaseByteArrayElements(key, keyBytes, JNI_ABORT);
+    env->ReleaseByteArrayElements(result, resultBytes, 0);  // 0 = copy back + free
+
+    return result;
+}
+
+} // extern "C"
+```
+
+---
+
+## JNI Type Mapping
+
+| Kotlin/Java | JNI Type | Array Type |
+|---|---|---|
+| `Boolean` | `jboolean` | `jbooleanArray` |
+| `Int` | `jint` | `jintArray` |
+| `Long` | `jlong` | `jlongArray` |
+| `Float` | `jfloat` | `jfloatArray` |
+| `Double` | `jdouble` | `jdoubleArray` |
+| `Byte` | `jbyte` | `jbyteArray` |
+| `String` | `jstring` | — |
+| `Object` | `jobject` | `jobjectArray` |
+| `void` | `void` | — |
+
+---
+
+## Handling Strings
+
+```cpp
+// ✅ Convert jstring to std::string
+std::string jstringToString(JNIEnv* env, jstring jStr) {
+    if (jStr == nullptr) return "";
+    const char* chars = env->GetStringUTFChars(jStr, nullptr);
+    std::string result(chars);
+    env->ReleaseStringUTFChars(jStr, chars);   // ✅ always release
+    return result;
+}
+
+// ✅ Convert std::string to jstring
+jstring stringToJstring(JNIEnv* env, const std::string& str) {
+    return env->NewStringUTF(str.c_str());
+}
+
+JNIEXPORT jstring JNICALL
+Java_com_example_app_NativeUtils_processText(
+    JNIEnv* env, jobject, jstring input
+) {
+    std::string text = jstringToString(env, input);
+    std::string result = /* process */ text + "_processed";
+    return stringToJstring(env, result);
+}
+```
+
+---
+
+## Global References (Persistent JNI Objects)
+
+```cpp
+// ✅ Use Global Reference to hold a Java object across JNI calls
+static jobject gCallback = nullptr;
+
+JNIEXPORT void JNICALL
+Java_com_example_app_NativeLib_registerCallback(
+    JNIEnv* env, jobject, jobject callback
+) {
+    // ✅ Delete old reference if exists
+    if (gCallback != nullptr) {
+        env->DeleteGlobalRef(gCallback);
+    }
+    // ✅ Create global reference — survives across JNI calls
+    gCallback = env->NewGlobalRef(callback);
+}
+
+JNIEXPORT void JNICALL
+Java_com_example_app_NativeLib_unregisterCallback(
+    JNIEnv* env, jobject
+) {
+    if (gCallback != nullptr) {
+        env->DeleteGlobalRef(gCallback);
+        gCallback = nullptr;
+    }
+}
+```
+
+---
+
+## Calling Kotlin from C++ (Callbacks)
+
+```cpp
+// ✅ Call a Kotlin method from native code
+void callKotlinCallback(JNIEnv* env, jobject callback, int progress) {
+    jclass callbackClass = env->GetObjectClass(callback);
+
+    // Find the method: void onProgress(int progress)
+    jmethodID onProgressMethod = env->GetMethodID(
+        callbackClass,
+        "onProgress",
+        "(I)V"           // method signature: (int) returns void
+    );
+
+    if (onProgressMethod != nullptr) {
+        env->CallVoidMethod(callback, onProgressMethod, (jint)progress);
+    }
+    env->DeleteLocalRef(callbackClass);
+}
+```
+
+---
+
+## JNI Method Signatures
+
+```
+Type     Signature
+void     V
+boolean  Z
+byte     B
+char     C
+short    S
+int      I
+long     J
+float    F
+double   D
+String   Ljava/lang/String;
+int[]    [I
+Object   Ljava/lang/Object;
+
+Method: void foo(int, String) → (ILjava/lang/String;)V
+Method: int bar(byte[])      → ([B)I
+```
+
+---
+
+## Error Handling
+
+```cpp
+// ✅ Check for exceptions after calling Java methods
+env->CallVoidMethod(obj, method, arg);
+if (env->ExceptionCheck()) {
+    env->ExceptionDescribe();  // prints to logcat
+    env->ExceptionClear();
+    // handle error
+    return nullptr;
+}
+
+// ✅ Throw a Java exception from native code
+void throwException(JNIEnv* env, const char* message) {
+    jclass exceptionClass = env->FindClass("java/lang/RuntimeException");
+    if (exceptionClass != nullptr) {
+        env->ThrowNew(exceptionClass, message);
+        env->DeleteLocalRef(exceptionClass);
+    }
+}
+```
+
+---
+
+## Logging from Native Code
+
+```cpp
+#include <android/log.h>
+
+#define TAG "NativeLib"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, TAG, __VA_ARGS__)
+
+// Usage
+LOGI("Processing %d bytes", dataLen);
+LOGE("Encryption failed: %s", errorMsg);
+```
+
+---
+
+## Anti-Patterns
+
+- Not releasing `GetByteArrayElements` / `GetStringUTFChars` — memory leak
+- Storing `JNIEnv*` across threads — `JNIEnv` is thread-local; each thread needs its own
+- Using Local References after the JNI call returns — they become invalid
+- Crossing the JNI boundary on every frame — batch operations; minimize round-trips
+- Forgetting `extern "C"` in C++ files — C++ name mangling breaks JNI lookup
+
+---
+
+## Related Skills
+- `ndk` — NDK build system and toolchain setup
+- `c++` — C++ patterns for Android native code
+- `cryptography` — using JNI for native crypto implementations
+- `reverse-engineering-resistance` — native code as a hardening technique

package/skills/Build System/Specialized/NDK/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: ndk
+description: >
+  Android NDK build system, toolchain, and project setup.
+  Load this skill when configuring the NDK version, setting up CMake
+  or ndk-build, managing ABI splits, linking third-party native libraries,
+  debugging native crashes, or configuring native build flags.
+---
+
+# NDK
+
+## Overview
+The Android NDK (Native Development Kit) provides the toolchain for compiling C/C++ code into native libraries (`.so` files) that run on Android. It includes the compiler (Clang), standard libraries, Android-specific headers, and the build system integration with Gradle via CMake or ndk-build.
+
+---
+
+## Core Principles
+
+- **Pin the NDK version** in `build.gradle.kts` — NDK updates can break builds
+- **CMake is preferred** over ndk-build for new projects — better IDE support
+- **ABI filters** reduce APK size — only include the ABIs your app supports
+- **STL selection** matters — use `c++_shared` for shared libraries, `c++_static` for single `.so`
+- **Symbols** — strip debug symbols from release builds for size; keep for crash analysis
+
+---
+
+## Gradle Setup
+
+```kotlin
+// app/build.gradle.kts
+android {
+    ndkVersion = "26.1.10909125"    // ✅ pin exact version
+
+    defaultConfig {
+        externalNativeBuild {
+            cmake {
+                cppFlags("-std=c++17", "-fexceptions", "-frtti")
+                arguments(
+                    "-DANDROID_STL=c++_shared",
+                    "-DANDROID_PLATFORM=android-26"
+                )
+            }
+        }
+
+        // ✅ Only build for ABIs you support
+        ndk {
+            abiFilters += listOf("arm64-v8a", "x86_64")  // drop x86 for production
+        }
+    }
+
+    externalNativeBuild {
+        cmake {
+            path("src/main/cpp/CMakeLists.txt")
+            version("3.22.1")
+        }
+    }
+
+    // ✅ Split APKs by ABI (Play Store handles delivery)
+    splits {
+        abi {
+            isEnable = true
+            reset()
+            include("arm64-v8a", "armeabi-v7a", "x86_64")
+            isUniversalApk = false
+        }
+    }
+}
+```
+
+---
+
+## CMakeLists.txt — Full Example
+
+```cmake
+cmake_minimum_required(VERSION 3.22.1)
+project("myapp" VERSION 1.0.0)
+
+# ✅ Set C++ standard
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# ✅ Source files
+set(SOURCES
+    src/native_lib.cpp
+    src/crypto/aes_gcm.cpp
+    src/utils/string_utils.cpp
+)
+
+# ✅ Create shared library
+add_library(myapp-native SHARED ${SOURCES})
+
+# ✅ Find Android system libraries
+find_library(log-lib log)
+find_library(android-lib android)
+
+# ✅ Include headers
+target_include_directories(myapp-native PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+# ✅ Link libraries
+target_link_libraries(myapp-native
+    ${log-lib}
+    ${android-lib}
+)
+
+# ✅ Compiler flags
+target_compile_options(myapp-native PRIVATE
+    -Wall
+    -Wextra
+    -O2
+    $<$<CONFIG:Debug>:-g>
+    $<$<CONFIG:Release>:-Os -fvisibility=hidden>
+)
+
+# ✅ Strip symbols in release (reduces .so size)
+set_target_properties(myapp-native PROPERTIES
+    $<$<CONFIG:Release>:LINK_FLAGS "-Wl,--strip-all">
+)
+```
+
+---
+
+## Linking Pre-built Libraries
+
+```cmake
+# ✅ Link a pre-built .so from a third-party SDK
+add_library(third-party-lib SHARED IMPORTED)
+set_target_properties(third-party-lib PROPERTIES
+    IMPORTED_LOCATION ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libthirdparty.so
+)
+
+target_link_libraries(myapp-native
+    third-party-lib
+    ${log-lib}
+)
+
+# ✅ Copy the .so to jniLibs so it's packaged in the APK
+# Place in: src/main/jniLibs/<abi>/libthirdparty.so
+```
+
+---
+
+## ABI Reference
+
+| ABI | Architecture | Notes |
+|---|---|---|
+| `arm64-v8a` | 64-bit ARM | Most modern Android devices |
+| `armeabi-v7a` | 32-bit ARM | Older devices; still ~15% of installs |
+| `x86_64` | 64-bit x86 | Emulators, some Chrome OS |
+| `x86` | 32-bit x86 | Legacy emulators; safe to drop |
+
+```kotlin
+// ✅ Production — include arm64-v8a + armeabi-v7a for device coverage
+ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a") }
+
+// ✅ During development — add x86_64 for emulator
+ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64") }
+```
+
+---
+
+## Debugging Native Crashes (Tombstones)
+
+```bash
+# ✅ Symbolicate a native crash from logcat
+# The crash shows: #00 pc 0000abcd  /data/app/.../libmyapp.so
+
+# 1. Find your .so with debug symbols (from build/intermediates/)
+# 2. Use ndk-stack:
+adb logcat | ndk-stack -sym app/build/intermediates/cmake/debug/obj/arm64-v8a/
+
+# ✅ Or use addr2line to decode a single address
+$NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-addr2line \
+  -e libmyapp.so \
+  0x0000abcd
+
+# ✅ Use Android Studio's LLDB debugger for live native debugging
+# Run/Debug Configurations → Debugger → Debug type: Dual
+```
+
+---
+
+## Accessing Android APIs from Native Code
+
+```cpp
+// ✅ Android-specific native APIs
+#include <android/asset_manager.h>
+#include <android/asset_manager_jni.h>
+#include <android/log.h>
+#include <android/bitmap.h>
+#include <GLES3/gl3.h>       // OpenGL ES 3.0
+#include <EGL/egl.h>
+
+// ✅ Read asset from native code
+JNIEXPORT jbyteArray JNICALL
+Java_com_example_NativeAssets_readAsset(
+    JNIEnv* env, jobject,
+    jobject assetManager, jstring filename
+) {
+    AAssetManager* mgr = AAssetManager_fromJava(env, assetManager);
+    const char* file = env->GetStringUTFChars(filename, nullptr);
+
+    AAsset* asset = AAssetManager_open(mgr, file, AASSET_MODE_BUFFER);
+    env->ReleaseStringUTFChars(filename, file);
+
+    if (asset == nullptr) return nullptr;
+
+    off_t size = AAsset_getLength(asset);
+    jbyteArray result = env->NewByteArray(size);
+    jbyte* buf = env->GetByteArrayElements(result, nullptr);
+    AAsset_read(asset, buf, size);
+    AAsset_close(asset);
+
+    env->ReleaseByteArrayElements(result, buf, 0);
+    return result;
+}
+```
+
+---
+
+## Build Variants for Native
+
+```kotlin
+// ✅ Different native flags per build type
+android {
+    buildTypes {
+        debug {
+            externalNativeBuild {
+                cmake {
+                    cppFlags("-DDEBUG_BUILD", "-g")
+                    arguments("-DCMAKE_BUILD_TYPE=Debug")
+                }
+            }
+        }
+        release {
+            externalNativeBuild {
+                cmake {
+                    cppFlags("-DNDEBUG", "-O2", "-fvisibility=hidden")
+                    arguments("-DCMAKE_BUILD_TYPE=Release")
+                }
+            }
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Not pinning `ndkVersion` — CI builds may use different NDK than local builds
+- Building for all 4 ABIs — `x86` is dead; `x86_64` only needed for emulators
+- `c++_static` STL with multiple `.so` files — causes ODR violations and crashes
+- Storing debug `.so` in the release APK — exposes symbols; strip in release
+- Not checking `env->ExceptionCheck()` after calling back into Java — silent crashes
+
+---
+
+## Related Skills
+- `jni` — JNI bridge between Kotlin and native code
+- `c++` — C++ patterns for native Android code
+- `gradle` — Gradle build configuration
+- `reverse-engineering-resistance` — native code hardening