Phase 0 fingerprinting, R8-resistant extraction, Ktor/Apollo/Koin/HMAC patterns

plugins/android-reverse-engineering/skills/android-reverse-engineering/SKILL.md

@@ -24,6 +24,31 @@ If anything is missing, follow the installation instructions in `${CLAUDE_PLUGIN
 
 ## Workflow
 
+### Phase 0: Fingerprint the App (recommended before anything else)
+
+Before installing tools or decompiling, run a fast triage to determine what
+kind of app you are looking at. **Decompiling Java is mostly useless for
+Flutter, React Native, Cordova/Capacitor, and Xamarin apps** — the real code
+lives elsewhere. The fingerprint script tells you which.
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/scripts/fingerprint.sh <file.apk|file.xapk>
+```
+
+It prints, in one screen:
+
+- **Mobile framework** (Flutter / React Native / Cordova / Xamarin / Native Kotlin / etc.) with the file marker that triggered the verdict.
+- **HTTP stack** (Retrofit, OkHttp, Ktor, Apollo, Volley) detected via DEX string scan — works even when class names are obfuscated.
+- **DI / serialization** signals (Hilt, Dagger, Koin, kotlinx.serialization, Moshi, Gson, Jackson).
+- **Obfuscation level** estimate based on root-level short-named packages.
+- **Notable third-party SDKs** (AppsFlyer, Datadog, Sentry, Firebase, payment SDKs, support/chat SDKs, etc.).
+- **Consolidated native libraries** across the base APK and all splits — XAPK split bundles often place `.so` files in `config.<abi>.apk`, not in `base.apk`.
+- **Recommended next step**, which differs by framework (e.g. for Flutter the script suggests `blutter` / `strings libapp.so` rather than jadx).
+
+If the fingerprint says the app is Flutter / RN / Cordova / Xamarin, **stop**
+and switch to the framework-appropriate tooling. Phases 1–5 below assume a
+native (Java/Kotlin) Android app.
+
 ### Phase 1: Verify and Install Dependencies
 
 Before decompiling, confirm that the required tools are available — and install any that are missing.
@@ -123,12 +148,45 @@ Navigate the decompiled output to understand the app's architecture.
    - Distinguish app code from third-party libraries
    - Look for packages named `api`, `network`, `data`, `repository`, `service`, `retrofit`, `http` — these are where API calls live
 
-3. **Identify the architecture pattern**:
+3. **Read every `BuildConfig.java`** — these are almost never obfuscated and frequently leak the highest-signal constants in the entire APK (base URLs, flavor names, build type, third-party API keys, feature flags):
+   ```bash
+   find <output>/sources -name BuildConfig.java -exec grep -H '=' {} \;
+   ```
+   Each Gradle module emits its own `BuildConfig`, so expect 1–N hits. Read all of them.
+
+4. **Identify the architecture pattern**:
    - MVP: look for `Presenter` classes
    - MVVM: look for `ViewModel` classes and `LiveData`/`StateFlow`
    - Clean Architecture: look for `domain`, `data`, `presentation` packages
    - This informs where to look for network calls in the next phases
 
+### Phase 3.5: Recover Kotlin Class Names (only for obfuscated Kotlin apps)
+
+If Phase 0 reported moderate / high obfuscation **and** the app is Kotlin
+(Compose / kotlin_module markers detected), run the metadata recovery
+script before tracing call flows. R8 obfuscates JVM symbols but cannot
+strip Kotlin metadata strings, so original FQNs leak through
+`@DebugMetadata` and `@Metadata.d2`.
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/scripts/recover-kotlin-names.sh \
+    <output>/sources <output>/mapping
+```
+
+Then use the lookup helper instead of plain grep — every hit comes
+annotated with the owning class's real name:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/scripts/lookup-name.sh \
+    <output>/mapping --grep '"/api/' <output>/sources
+```
+
+Typical recovery on a real-world Kotlin app: ~100% of `*Repository` /
+`*ViewModel` / `*UseCase` / `*Impl` classes, ~80% of DTOs.
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/references/kotlin-name-recovery.md`
+for the full technique and limitations.
+
 ### Phase 4: Trace Call Flows
 
 Follow execution paths from user-facing entry points down to network calls.
@@ -190,15 +248,32 @@ On Windows (PowerShell):
 & "${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/scripts/find-api-calls.ps1" <output>/sources/ -Auth
 ```
 
-Then, for each discovered endpoint, read the surrounding source code to extract:
-- HTTP method and path
-- Base URL
-- Path parameters, query parameters, request body
-- Headers (especially authentication)
-- Response type
-- Where it's called from (the call chain from Phase 4)
+Document the endpoints in **two tiers** — going deep on every endpoint is
+prohibitively expensive on apps with 100+ paths, and most of them do not
+warrant it. Always produce Tier 1; expand Tier 2 only for the endpoints
+that matter.
+
+#### Tier 1 — flat inventory (always)
 
-**Document each endpoint** using this format:
+A single table covering every discovered endpoint. Aim for one line each;
+if you cannot determine a column, write `?`.
+
+| Host | Method | Path | Auth | Source file |
+|------|--------|------|------|-------------|
+| `api.example.com` | GET | `/v1/users/profile` | Bearer | `com/example/api/UserApi.java` |
+| `api.example.com` | POST | `/v1/auth/login` | none | `com/example/api/AuthApi.java` |
+
+This table answers "what does the backend look like" in one screen and
+takes ~5 minutes to produce from the `--paths` output even on a large app.
+
+#### Tier 2 — per-endpoint detail (only for high-value endpoints)
+
+Reserve the detailed format for the few endpoints that actually need it:
+
+- the entire authentication flow (login, refresh, logout, OTP/SMS, anonymous, registration)
+- payment / checkout / order-creation endpoints
+- anything the user explicitly asked about
+- anything that looked unusual during the scan (custom signing, undocumented headers, etc.)
 
 ```markdown
 ### `METHOD /path`
@@ -213,6 +288,10 @@ Then, for each discovered endpoint, read the surrounding source code to extract:
 - **Called from**: `LoginActivity → LoginViewModel → UserRepository → ApiService`
 ```
 
+As a default, do not produce Tier 2 entries for more than ~10 endpoints
+unless the user explicitly asks for more — Tier 1 plus a Tier 2 deep dive
+on auth + 1-2 key flows is what most consumers of this work actually want.
+
 See `${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/references/api-extraction-patterns.md` for library-specific search patterns and the full documentation template.
 
 ## Output

plugins/android-reverse-engineering/skills/android-reverse-engineering/references/api-extraction-patterns.md

@@ -55,6 +55,65 @@ grep -rn 'Interceptor\|addInterceptor\|addNetworkInterceptor\|intercept(' source
 grep -rn '\.execute()\|\.enqueue(' sources/
 ```
 
+## Ktor (Kotlin)
+
+Ktor is the dominant HTTP client in Kotlin Multiplatform and modern
+Kotlin-only Android apps. Unlike Retrofit, Ktor does **not** use annotations
+to declare endpoints — paths appear as plain string arguments to
+`client.get(...)` / `client.post(...)`, often inside an extension function.
+
+```bash
+# Calls
+grep -rn '\b\(client\|httpClient\|HttpClient\)\.\(get\|post\|put\|delete\|patch\|head\|request\)\s*[<(]' sources/
+
+# Default request / base URL configuration
+grep -rn 'HttpRequestBuilder\|defaultRequest\s*{\|\burl\s*(\s*"\|URLBuilder' sources/
+
+# Auth plugin (bearer / refresh)
+grep -rn '\bbearer\s*{\|BearerTokens\s*(\|loadTokens\s*{\|refreshTokens\s*{' sources/
+```
+
+Typical Ktor call (after decompile):
+
+```java
+client.get("api/v1/users/profile") {
+    parameter("locale", "en-US");
+}
+```
+
+The base URL is usually applied via `defaultRequest { url { host = "..." } }`
+in the client builder. Search for `host =` and `URLProtocol.HTTPS` references
+to pin it down.
+
+**Note on obfuscation:** in heavily R8-shrunk apps the call site
+`client.get("path")` is inlined to something like `aVar.a(dVar, "path")`
+and the `client.<verb>(` regex misses it. The path string itself is **not**
+obfuscated, however — fall back to the generic path-literal search
+(`--paths`) for the endpoint inventory in those cases. Ktor library
+internals (`BearerTokens`, `loadTokens`, `refreshTokens`, `URLProtocol`)
+remain searchable because Ktor keeps these on its public API.
+
+Ktor's authentication plugin uses the
+[`Auth { bearer { loadTokens { ... }; refreshTokens { ... } } }`](https://ktor.io/docs/auth.html)
+DSL — bearer access tokens with automatic refresh. After R8, the DSL
+lambdas appear as `Function2`/`Function3` impls referencing
+`BearerTokens(...)` calls.
+
+## Apollo Kotlin (GraphQL)
+
+```bash
+# Client setup
+grep -rn 'ApolloClient\|\.serverUrl(\|HttpNetworkTransport' sources/
+
+# Operations (queries / mutations / subscriptions)
+grep -rn '\.query(\s*[A-Z]\|\.mutation(\s*[A-Z]\|\.subscription(\s*[A-Z]' sources/
+```
+
+Apollo generates one class per operation under a generated package; once you
+find the GraphQL endpoint URL via `ApolloClient.serverUrl("...")`, use the
+operation classes themselves as the API documentation — each carries its
+GraphQL document text in `OPERATION_DOCUMENT`.
+
 ## Volley
 
 ```bash
@@ -77,6 +136,25 @@ grep -rn 'loadUrl\|evaluateJavascript\|addJavascriptInterface\|WebViewClient\|sh
 
 WebView-based apps may load API endpoints via JavaScript bridges. Look for `@JavascriptInterface` annotated methods.
 
+## Endpoint-Shaped Path Literals (obfuscation-resistant)
+
+When the HTTP client cannot be identified (custom abstraction, heavy
+inlining, KMP shared module), or the call sites are obfuscated to
+`a.b(c, "path")`, fall back to extracting the path string literals
+themselves. R8 does not obfuscate string contents, so paths leak through.
+
+```bash
+# All quoted strings shaped like an API path, deduplicated
+grep -rhoE '"(/[A-Za-z0-9_{}.\-]+(/[A-Za-z0-9_{}.\-]+)+/?|(api|v[0-9]+|graphql|users?|account|auth|sso|oauth|profile|cart|basket|order|product|inventory|search|category|address|location|delivery|payment|invoice|favo[u]?rites?)(/[A-Za-z0-9_{}.\-]+)+/?)"' sources/ \
+    | grep -Ev '^"(image|video|audio|text|application|content)/|^"/(proc|sys|dev|tmp|etc)/' \
+    | sort -u
+```
+
+The skill ships this as `find-api-calls.sh --paths`, which prints both a
+deduplicated inventory and the full list of call sites. On real-world
+Kotlin apps this single command typically produces 100–300 distinct
+endpoint paths, which is the most useful first artifact for documentation.
+
 ## Hardcoded URLs and Secrets
 
 ```bash

plugins/android-reverse-engineering/skills/android-reverse-engineering/references/call-flow-analysis.md

@@ -84,9 +84,9 @@ Look for:
 - Firebase/analytics initialization
 - Base URL configuration
 
-## 5. Dependency Injection (Dagger / Hilt)
+## 5. Dependency Injection
 
-Modern Android apps use DI. Trace bindings to find implementations:
+### Dagger / Hilt
 
 ```bash
 # Hilt modules
@@ -102,10 +102,43 @@ grep -rn '@Component\|@Subcomponent' sources/
 grep -rn '@Inject' sources/
 ```
 
-To trace a call flow through DI:
-1. Find where an interface is used (e.g., `ApiService` injected into a repository)
-2. Find the `@Provides` or `@Binds` method that creates the implementation
-3. Follow the implementation to the actual HTTP call
+### Koin
+
+Koin is the dominant DI framework in Kotlin Multiplatform and a large
+share of Kotlin-only Android apps. It uses a runtime DSL rather than
+compile-time generated factories, so the search patterns are different:
+
+```bash
+# Confirm Koin is actually wired up
+grep -rn 'org\.koin\.' sources/
+
+# DI module declarations
+grep -rn 'fun [A-Za-z]\+Module\|module\s*{\|module(' sources/
+
+# Bindings inside a module DSL
+grep -rn 'single\s*[<{(]\|factory\s*[<{(]\|viewModel\s*[<{(]\|scoped\s*[<{(]\|singleOf\|factoryOf' sources/
+
+# Resolution call-sites (where a binding is consumed)
+grep -rn '\bget\s*<\|\binject\s*<\|by\s\+inject\b\|by\s\+viewModel\b\|getKoin' sources/
+```
+
+After R8, every binding lambda becomes an anonymous
+`Function2<Scope, ParametersHolder, T>` impl. To find the binding for an
+interface `Foo`, look for files that contain both a Koin import / module
+DSL marker and a reference to `Foo`:
+
+```bash
+grep -rln 'org\.koin\.core\.module' sources/ | xargs grep -l 'Foo'
+```
+
+### Trace through DI
+
+1. Find where an interface is used (e.g. `ApiService` injected into a
+   repository).
+2. Find the `@Provides` / `@Binds` method (Hilt) **or** the
+   `single { ... }` / `factory { ... }` block (Koin) that creates the
+   implementation.
+3. Follow the implementation to the actual HTTP call.
 
 ## 6. Find Constants and Configuration
 
@@ -145,8 +178,9 @@ When code is obfuscated (ProGuard/R8):
 1. **Start from strings**: Search for URLs, error messages, and known constants
 2. **Start from framework classes**: Activities and Fragments are named in the manifest
 3. **Follow library calls**: Retrofit `@GET`/`@POST` annotations are readable even when the interface class name is obfuscated
-4. **Use `--deobf`**: jadx can generate readable replacement names
+4. **Recover original Kotlin names from metadata**: `@DebugMetadata` and `@Metadata.d2` strings preserve the original FQNs even after R8 obfuscation. Run `scripts/recover-kotlin-names.sh` to build an `obf -> real` map (typically recovers 30-50% of classes — and almost 100% of `*Repository` / `*ViewModel` / `*Impl`). See [`kotlin-name-recovery.md`](./kotlin-name-recovery.md). This is the single highest-leverage step on any Kotlin app.
 5. **Cross-reference**: If `class a` calls `Retrofit.create(b.class)`, then `b` is a Retrofit service interface
+6. **`--deobf` is rarely enough on its own**: jadx's `--deobf` renames obfuscated symbols with synthetic placeholders (`p001a`, `C0123Foo`) — useful for disambiguation but it does **not** recover original names. Pair it with the metadata recovery above.
 
 ## 8. Tracing a Complete Call Flow: Example