Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

feat(flutter): identify Dart snapshot builds and inspect AOT payloads by pure APK parsing (#1582)

Quentin Limoe4d3e1399d9c
diff --git a/README.md b/README.md
index fe061ddcf..83b8f03bc 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,7 @@ Additional tools and host support depend on the target:
| Android devices | Devices, packages, processes, logs, dumps, screen captures, and APK/file transfers | Caller-supplied adb (emulator or hardware); [ADB guide](docs/adb-device-analysis.md) |
| JEB projects | Engine-backed project units, artifact digests and type/method pseudo-code | A caller-started JEB client serving MCP, selected with REA_JEB_MCP_URL; [JEB guide](docs/jeb-analysis.md) |
| Android resources | Decoded manifest, string tables, locales and version facts | Caller-supplied Apktool launcher; [resource guide](docs/apktool-resource-analysis.md) |
+| Flutter apps | Dart snapshot hash, per-ABI library digests and engine build provenance | None (static APK parsing); [Flutter guide](docs/flutter-analysis.md) |
| Firmware | Regions, extraction results and native-analysis handoffs | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md) |
| Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) |
| Process behavior | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md) |
diff --git a/README_ar.md b/README_ar.md
index d45af6edc..6b050084f 100644
--- a/README_ar.md
+++ b/README_ar.md
@@ -144,6 +144,7 @@ npx rea-agents@latest setup
| أجهزة Android | الأجهزة والحزم والعمليات والسجلات والدامبات ولقطات الشاشة ونقل APK/الملفات | adb يوفّره المُستدعي (محاكي أو جهاز)؛ [دليل ADB](docs/adb-device-analysis.md) |
| مشاريع JEB | وحدات المشروع من المحرك وبصمات المصنّفات والكود الزائف للأنواع/الدوال | عميل JEB يبدأه المُستدعي ويقدّم MCP، ويُختار عبر REA_JEB_MCP_URL؛ [دليل JEB](docs/jeb-analysis.md) |
| موارد Android | البيان المفكوك الترميز وجداول السلاسل واللغات وحقائق الإصدار | مُشغّل Apktool يوفّره المُستدعي؛ [دليل الموارد](docs/apktool-resource-analysis.md) |
+| تطبيقات Flutter | بصمة لقطة Dart وهشوش المكتبات لكل ABI وأصل بناء المحرك | لا شيء (تحليل APK ساكن)؛ [دليل Flutter](docs/flutter-analysis.md) |
| البرامج الثابتة | المناطق، ونتائج الاستخراج، وما يُمرّر إلى تحليل الشيفرة الأصلية | Binwalk / Unblob على Linux؛ [دليل البرامج الثابتة](docs/firmware-analysis.md) |
| الحزم والموارد | قوائم الملفات، والبصمات، وملفات plist، وبنية حزم Apple، والموارد المستخرجة | [دليل تحليل الملفات وJavaScript](docs/javascript-artifact-reconstruction.md)، [تطبيقات Apple](docs/apple-application-analysis.md) |
| سلوك العمليات | مخرجات الطرفية، والتفاعلات، وملاحظات الخروج ونظام الملفات، ومقارنات التشغيل | Linux/macOS مع PTY أصلي؛ [تسجيل سلوك العمليات](docs/process-capture.md) |
diff --git a/README_de.md b/README_de.md
index 530527b89..d10f5f4b7 100644
--- a/README_de.md
+++ b/README_de.md
@@ -144,6 +144,7 @@ REA benötigt Node.js 22.x (>=22.19), 24.x (>=24.11) oder 26+ sowie npm. Zusätz
| Android-Geräte | Geräte, Pakete, Prozesse, Logs, Dumps, Bildschirmaufnahmen sowie APK- und Dateiübertragungen | Vom Aufrufer bereitgestelltes adb (Emulator oder Gerät); [ADB-Leitfaden](docs/adb-device-analysis.md) |
| JEB-Projekte | Engine-gestützte Projekteinheiten, Artefakt-Prüfsummen und Pseudokode von Typen/Methoden | Ein vom Aufrufer gestarteter JEB-Client mit MCP, ausgewählt über REA_JEB_MCP_URL; [JEB-Leitfaden](docs/jeb-analysis.md) |
| Android-Ressourcen | Dekodiertes Manifest, String-Tabellen, Sprachen und Versionsfakten | Vom Aufrufer bereitgestellter Apktool-Starter; [Ressourcen-Leitfaden](docs/apktool-resource-analysis.md) |
+| Flutter-Apps | Dart-Snapshot-Hash, Per-ABI-Bibliotheksprüfsummen und Engine-Build-Provenienz | Keine (statische APK-Analyse); [Flutter-Leitfaden](docs/flutter-analysis.md) |
| Firmware | Bereiche, Extraktionsergebnisse und Übergaben an die native Analyse | Binwalk / Unblob unter Linux; [Firmware-Leitfaden](docs/firmware-analysis.md) |
| Pakete und Ressourcen | Dateiinventare, Hashwerte, plists, Aufbau von Apple-Bundles und extrahierte Ressourcen | [Artefakt- und JavaScript-Leitfaden](docs/javascript-artifact-reconstruction.md), [Apple-Anwendungen](docs/apple-application-analysis.md) |
| Prozessverhalten | Terminalausgabe, Interaktionen, Beobachtungen zu Prozessende und Dateisystem sowie Laufvergleiche | Linux/macOS mit nativer PTY; [Prozessaufzeichnung](docs/process-capture.md) |
diff --git a/README_es.md b/README_es.md
index f23bd2df7..883cef863 100644
--- a/README_es.md
+++ b/README_es.md
@@ -144,6 +144,7 @@ REA requiere Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, además de npm. Las h
| Dispositivos Android | Dispositivos, paquetes, procesos, registros, volcados, capturas de pantalla y transferencias de APK/archivos | adb suministrado por el autor de la llamada (emulador o dispositivo); [guía de ADB](docs/adb-device-analysis.md) |
| Proyectos JEB | Unidades de proyecto del motor, resúmenes de artefactos y pseudocódigo de tipos/métodos | Un cliente JEB iniciado por el autor de la llamada que sirve MCP, seleccionado con REA_JEB_MCP_URL; [guía de JEB](docs/jeb-analysis.md) |
| Recursos de Android | Manifiesto decodificado, tablas de cadenas, idiomas y datos de versión | Lanzador de Apktool suministrado por el autor de la llamada; [guía de recursos](docs/apktool-resource-analysis.md) |
+| Aplicaciones Flutter | Hash de snapshot de Dart, resúmenes de bibliotecas por ABI y procedencia de compilación del motor | Ninguna (análisis APK estático); [guía de Flutter](docs/flutter-analysis.md) |
| Firmware | Regiones, resultados de extracción y derivaciones al análisis nativo | Binwalk / Unblob en Linux; [guía de firmware](docs/firmware-analysis.md) |
| Paquetes y recursos | Inventarios de archivos, resúmenes criptográficos, plists, estructura de paquetes de Apple y recursos extraídos | [Guía de artefactos y JavaScript](docs/javascript-artifact-reconstruction.md), [aplicaciones de Apple](docs/apple-application-analysis.md) |
| Comportamiento de procesos | Salida de la terminal, interacciones, observaciones de salida y del sistema de archivos, y comparaciones entre ejecuciones | Linux/macOS con una PTY nativa; [captura de procesos](docs/process-capture.md) |
diff --git a/README_fa.md b/README_fa.md
index 4a9885eef..21ab30fae 100644
--- a/README_fa.md
+++ b/README_fa.md
@@ -136,6 +136,7 @@ REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، به‌همراه np
| دستگاه‌های اندروید | دستگاه‌ها، بسته‌ها، فرایندها، لاگ‌ها، دامپ‌ها، اسکرین‌شات‌ها و انتقال APK/فایل | adb تأمین‌شده توسط فراخوان‌کننده (شبیه‌ساز یا دستگاه)؛ [راهنمای ADB](docs/adb-device-analysis.md) |
| پروژه‌های JEB | واحدهای پروژه از موتور، هش‌های مصنوع و شبه‌کدِ نوع/متد | یک کلاینت JEB که توسط فراخوان‌کننده اجرا شده و MCP ارائه می‌دهد و با REA_JEB_MCP_URL انتخاب می‌شود؛ [راهنمای JEB](docs/jeb-analysis.md) |
| منابع اندروید | مانیفست رمزگشایی‌شده، جداول رشته‌ها، زبان‌ها و اطلاعات نسخه | راه‌انداز Apktool تأمین‌شده توسط فراخوان‌کننده؛ [راهنمای منابع](docs/apktool-resource-analysis.md) |
+| برنامه‌های فلاتر | هش اسنپ‌شات دارت، هش کتابخانه‌ها به تفکیک ABI و اصالت بیلد موتور | هیچ (تحلیل ایستا APK)؛ [راهنمای فلاتر](docs/flutter-analysis.md) |
| Firmware | ناحیه‌ها، نتایج استخراج و تحویل به ابزارهای تحلیل بومی | Binwalk / Unblob در لینوکس؛ [راهنمای Firmware](docs/firmware-analysis.md) |
| بسته‌ها و منابع | فهرست فایل‌ها، digestها، فایل‌های plist، ساختار bundle اپل و منابع استخراج‌شده | [راهنمای آرتیفکت و JavaScript](docs/javascript-artifact-reconstruction.md)، [برنامه‌های اپل](docs/apple-application-analysis.md) |
| رفتار فرایند | خروجی ترمینال، تعاملات، وضعیت خروج، مشاهدات سیستم فایل و مقایسهٔ اجراها | Linux/macOS با PTY بومی؛ [ضبط فرایند](docs/process-capture.md) |
diff --git a/README_fr.md b/README_fr.md
index c025cd14f..5282fdc72 100644
--- a/README_fr.md
+++ b/README_fr.md
@@ -148,6 +148,7 @@ REA nécessite Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, ainsi que npm. Les
| Appareils Android | Appareils, paquets, processus, journaux, dumps, captures d'écran et transferts d'APK/fichiers | adb fourni par l'appelant (émulateur ou appareil) ; [guide ADB](docs/adb-device-analysis.md) |
| Projets JEB | Unités de projet fournies par le moteur, condensés d'artefacts et pseudo-code de types/méthodes | Un client JEB démarré par l'appelant servant MCP, sélectionné via REA_JEB_MCP_URL ; [guide JEB](docs/jeb-analysis.md) |
| Ressources Android | Manifeste décodé, tables de chaînes, langues et faits de version | Lanceur Apktool fourni par l'appelant ; [guide des ressources](docs/apktool-resource-analysis.md) |
+| Applications Flutter | Empreinte de snapshot Dart, condensés de bibliothèques par ABI et provenance de build du moteur | Aucune (analyse APK statique) ; [guide Flutter](docs/flutter-analysis.md) |
| Firmware | Régions, résultats d'extraction et passage de relais vers l'analyse native | Binwalk / Unblob sous Linux ; [guide firmware](docs/firmware-analysis.md) |
| Paquets et ressources | Inventaires de fichiers, empreintes, plists, anatomie des bundles Apple et ressources extraites | [Guide artefacts et JavaScript](docs/javascript-artifact-reconstruction.md), [applications Apple](docs/apple-application-analysis.md) |
| Comportement des processus | Sortie du terminal, interactions, code de sortie, observations du système de fichiers et comparaisons | Linux/macOS avec un PTY natif ; [capture de processus](docs/process-capture.md) |
diff --git a/README_id.md b/README_id.md
index 0ca871312..7dc588fa0 100644
--- a/README_id.md
+++ b/README_id.md
@@ -151,6 +151,7 @@ Alat tambahan dan dukungan sistem host bergantung pada target yang dianalisis:
| Perangkat Android | Perangkat, paket, proses, log, dump, tangkapan layar, serta transfer APK/berkas | adb buatan pemanggil (emulator atau perangkat); [panduan ADB](docs/adb-device-analysis.md) |
| Proyek JEB | Unit proyek bertenaga mesin, hash artefak, dan pseudokode tipe/metode | Klien JEB yang dijalankan pemanggil dan menyajikan MCP, dipilih dengan REA_JEB_MCP_URL; [panduan JEB](docs/jeb-analysis.md) |
| Resource Android | Manifest terdekode, tabel string, lokal, dan fakta versi | Peluncur Apktool buatan pemanggil; [panduan resource](docs/apktool-resource-analysis.md) |
+| Aplikasi Flutter | Hash snapshot Dart, hash pustaka per ABI, dan asal build engine | Tidak ada (parsing APK statis); [panduan Flutter](docs/flutter-analysis.md) |
| Firmware | Wilayah, hasil ekstraksi, dan pengalihan ke analisis native | Binwalk / Unblob di Linux; [panduan firmware](docs/firmware-analysis.md) |
| Paket dan sumber daya | Inventaris berkas, digest, plist, struktur paket Apple, dan sumber daya yang diekstrak | [Panduan artefak dan JavaScript](docs/javascript-artifact-reconstruction.md), [aplikasi Apple](docs/apple-application-analysis.md) |
| Perilaku proses | Keluaran terminal, interaksi, pengamatan proses keluar dan sistem berkas, serta perbandingan eksekusi | Linux/macOS dengan PTY native; [perekaman proses](docs/process-capture.md) |
diff --git a/README_it.md b/README_it.md
index af908746d..fe9a6eb76 100644
--- a/README_it.md
+++ b/README_it.md
@@ -148,6 +148,7 @@ REA richiede Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, oltre a npm. Strument
| Dispositivi Android | Dispositivi, pacchetti, processi, log, dump, screenshot e trasferimenti APK/file | adb fornito dal chiamante (emulatore o hardware); [guida ADB](docs/adb-device-analysis.md) |
| Progetti JEB | Unità di progetto dal motore, digest degli artifact e pseudocodice di tipi/metodi | Client JEB avviato dal chiamante via MCP, selezionato con REA_JEB_MCP_URL; [guida JEB](docs/jeb-analysis.md) |
| Risorse Android | Manifest decodificato, tabelle stringhe, lingue e dati di versione | Launcher Apktool fornito dal chiamante; [guida alle risorse](docs/apktool-resource-analysis.md) |
+| App Flutter | Hash dello snapshot Dart, digest delle librerie per ABI e provenienza della build del motore | Nessuno (analisi APK statica); [guida Flutter](docs/flutter-analysis.md) |
| Firmware | Regioni, risultati di estrazione e passaggi all'analisi nativa | Binwalk / Unblob su Linux; [guida firmware](docs/firmware-analysis.md) |
| Pacchetti e risorse | Inventari file, digest, plist, anatomia dei bundle Apple e risorse estratte | [Guida artifact e JavaScript](docs/javascript-artifact-reconstruction.md), [Applicazioni Apple](docs/apple-application-analysis.md) |
| Comportamento dei processi | Output del terminale, interazioni, osservazioni su uscita e filesystem ed confronti di esecuzione | Linux/macOS con un PTY nativo; [cattura dei processi](docs/process-capture.md) |
diff --git a/README_ja.md b/README_ja.md
index 370fb591d..607315297 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -144,6 +144,7 @@ REA には Node.js 22.x(>=22.19)、24.x(>=24.11)、または 26+ と npm
| Android デバイス | デバイス、パッケージ、プロセス、ログ、ダンプ、スクリーンキャプチャ、APK/ファイル転送 | 呼び出し側が用意した adb(エミュレーターまたは実機);[ADB ガイド](docs/adb-device-analysis.md) |
| JEBプロジェクト | エンジンによるプロジェクトユニット、アーティファクトのダイジェスト、型/メソッドの擬似コード | 呼び出し側が起動し MCP を提供する JEB クライアント(REA_JEB_MCP_URL で選択);[JEB ガイド](docs/jeb-analysis.md) |
| Android リソース | デコードされたマニフェスト、文字列テーブル、ロケール、バージョン情報 | 呼び出し側が用意した Apktool ランチャー;[リソースガイド](docs/apktool-resource-analysis.md) |
+| Flutter アプリ | Dart スナップショットハッシュ、ABI ごとのライブラリダイジェスト、エンジンビルドの来歴 | 不要(静的 APK 解析);[Flutter ガイド](docs/flutter-analysis.md) |
| ファームウェア | 領域、抽出結果、ネイティブ分析への引き継ぎ | Linux 上の Binwalk / Unblob;[ファームウェアガイド](docs/firmware-analysis.md) |
| パッケージとリソース | ファイル一覧、ダイジェスト、plist、Apple バンドルの構造、抽出されたリソース | [アーティファクトと JavaScript のガイド](docs/javascript-artifact-reconstruction.md)、[Apple アプリケーション](docs/apple-application-analysis.md) |
| プロセスの動作 | ターミナル出力、対話、終了とファイルシステムの観測結果、実行の比較 | ネイティブ PTY を備えた Linux/macOS;[プロセスキャプチャ](docs/process-capture.md) |
diff --git a/README_ko.md b/README_ko.md
index 70301cfbc..d2df0703c 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -144,6 +144,7 @@ REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니
| Android 기기 | 기기, 패키지, 프로세스, 로그, 덤프, 화면 캡처, APK/파일 전송 | 호출자 제공 adb(에뮬레이터 또는 실제 기기); [ADB 가이드](docs/adb-device-analysis.md) |
| JEB 프로젝트 | 엔진 기반 프로젝트 유닛, 아티팩트 해시, 타입/메서드 의사코드 | 호출자가 시작하고 MCP를 제공하는 JEB 클라이언트(REA_JEB_MCP_URL로 선택); [JEB 가이드](docs/jeb-analysis.md) |
| Android 리소스 | 디코딩된 매니페스트, 문자열 테이블, 로캘, 버전 정보 | 호출자 제공 Apktool 런처; [리소스 가이드](docs/apktool-resource-analysis.md) |
+| Flutter 앱 | Dart 스냅샷 해시, ABI별 라이브러리 해시, 엔진 빌드 출처 | 없음 (정적 APK 파싱); [Flutter 가이드](docs/flutter-analysis.md) |
| 펌웨어 | 영역, 추출 결과, 네이티브 분석으로 전달할 정보 | Linux의 Binwalk / Unblob; [펌웨어 가이드](docs/firmware-analysis.md) |
| 패키지 및 리소스 | 파일 목록, 다이제스트, plist, Apple 번들 구조, 추출한 리소스 | [아티팩트 및 JavaScript 가이드](docs/javascript-artifact-reconstruction.md), [Apple 애플리케이션](docs/apple-application-analysis.md) |
| 프로세스 동작 | 터미널 출력, 상호작용, 종료 및 파일 시스템 관찰 결과, 실행 비교 | 네이티브 PTY를 지원하는 Linux/macOS; [프로세스 캡처](docs/process-capture.md) |
diff --git a/README_pl.md b/README_pl.md
index f3db2fbd2..30ea43eda 100644
--- a/README_pl.md
+++ b/README_pl.md
@@ -144,6 +144,7 @@ REA wymaga Node.js 22.x (>=22.19), 24.x (>=24.11) lub 26+ oraz npm. Dodatkowe na
| Urządzenia z Androidem | Urządzenia, pakiety, procesy, logi, zrzuty, zrzuty ekranu oraz transfery APK/plików | adb dostarczony przez wywołującego (emulator lub urządzenie); [przewodnik ADB](docs/adb-device-analysis.md) |
| Projekty JEB | Jednostki projektu obsługiwane przez silnik, skróty artefaktów i pseudokod typów/metod | Uruchomiony przez wywołującego klient JEB udostępniający MCP, wybrany przez REA_JEB_MCP_URL; [przewodnik JEB](docs/jeb-analysis.md) |
| Zasoby Androida | Zdekodowany manifest, tablice ciągów, języki i informacje o wersji | Należący do wywołującego launcher Apktool; [przewodnik zasobów](docs/apktool-resource-analysis.md) |
+| Aplikacje Flutter | Hash migawki Dart, sumy bibliotek per ABI i pochodzenie kompilacji silnika | Brak (statyczna analiza APK); [przewodnik Flutter](docs/flutter-analysis.md) |
| Oprogramowanie układowe | Regiony, wyniki wyodrębniania i przekazanie do analizy kodu natywnego | Binwalk / Unblob w systemie Linux; [przewodnik oprogramowania układowego](docs/firmware-analysis.md) |
| Pakiety i zasoby | Spisy plików, skróty, pliki plist, struktura pakietów Apple i wyodrębnione zasoby | [Przewodnik artefaktów i JavaScript](docs/javascript-artifact-reconstruction.md), [aplikacje Apple](docs/apple-application-analysis.md) |
| Zachowanie procesów | Wyjście terminala, interakcje, obserwacje zakończenia i systemu plików oraz porównania uruchomień | Linux/macOS z natywnym PTY; [przechwytywanie procesów](docs/process-capture.md) |
diff --git a/README_pt-BR.md b/README_pt-BR.md
index 662225a21..a84f6e0db 100644
--- a/README_pt-BR.md
+++ b/README_pt-BR.md
@@ -144,6 +144,7 @@ O REA requer Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, além do npm. As fer
| Dispositivos Android | Dispositivos, pacotes, processos, logs, despejos, capturas de tela e transferências de APK/arquivos | adb fornecido pelo chamador (emulador ou aparelho); [guia de ADB](docs/adb-device-analysis.md) |
| Projetos JEB | Unidades de projeto do motor, hashes de artefatos e pseudocódigo de tipos/métodos | Um cliente JEB iniciado pelo chamador servindo MCP, selecionado com REA_JEB_MCP_URL; [guia de JEB](docs/jeb-analysis.md) |
| Recursos do Android | Manifesto decodificado, tabelas de strings, idiomas e fatos de versão | Lançador do Apktool fornecido pelo chamador; [guia de recursos](docs/apktool-resource-analysis.md) |
+| Aplicativos Flutter | Hash de snapshot Dart, hashes de bibliotecas por ABI e procedência de build do motor | Nenhuma (análise estática de APK); [guia Flutter](docs/flutter-analysis.md) |
| Firmware | Regiões, resultados de extração e encaminhamentos à análise nativa | Binwalk / Unblob no Linux; [guia de firmware](docs/firmware-analysis.md) |
| Pacotes e recursos | Inventários de arquivos, digests, plists, estrutura de bundles Apple e recursos extraídos | [Guia de artefatos e JavaScript](docs/javascript-artifact-reconstruction.md), [aplicativos Apple](docs/apple-application-analysis.md) |
| Comportamento de processos | Saída do terminal, interações, observações de encerramento e do sistema de arquivos, e comparações entre execuções | Linux/macOS com PTY nativo; [captura de processos](docs/process-capture.md) |
diff --git a/README_ru.md b/README_ru.md
index a22c620ce..914ef09da 100644
--- a/README_ru.md
+++ b/README_ru.md
@@ -144,6 +144,7 @@ REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а так
| Устройства Android | Устройства, пакеты, процессы, журналы, дампы, снимки экрана и передача APK/файлов | adb, предоставленный вызывающей стороной (эмулятор или устройство); [руководство по ADB](docs/adb-device-analysis.md) |
| Проекты JEB | Единицы проекта от движка, дайджесты артефактов и псевдокод типов/методов | Запущенный вызывающей стороной клиент JEB с интерфейсом MCP, выбирается через REA_JEB_MCP_URL; [руководство по JEB](docs/jeb-analysis.md) |
| Ресурсы Android | Декодированный манифест, таблицы строк, языки и сведения о версии | Запуск Apktool, предоставленный вызывающей стороной; [руководство по ресурсам](docs/apktool-resource-analysis.md) |
+| Приложения Flutter | Хеш снапшота Dart, дайджесты библиотек по ABI и происхождение сборки движка | Не требуется (статический разбор APK); [руководство по Flutter](docs/flutter-analysis.md) |
| Прошивки | Области, результаты извлечения и передача в нативный анализ | Binwalk / Unblob в Linux; [руководство по прошивкам](docs/firmware-analysis.md) |
| Пакеты и ресурсы | Списки файлов, хеши, plist, структура пакетов Apple и извлечённые ресурсы | [Руководство по артефактам и JavaScript](docs/javascript-artifact-reconstruction.md), [приложения Apple](docs/apple-application-analysis.md) |
| Поведение процессов | Вывод терминала, взаимодействия, наблюдения за завершением и файловой системой, сравнения запусков | Linux/macOS с нативным PTY; [захват процессов](docs/process-capture.md) |
diff --git a/README_th.md b/README_th.md
index 7f87a81cf..2abe5a078 100644
--- a/README_th.md
+++ b/README_th.md
@@ -144,6 +144,7 @@ REA ต้องใช้ Node.js 22.x (>=22.19), 24.x (>=24.11) หรือ 26
| อุปกรณ์ Android | อุปกรณ์ แพ็กเกจ โพรเซส บันทึก ดัมพ์ ภาพหน้าจอ และการถ่ายโอน APK/ไฟล์ | adb ที่ผู้เรียกจัดเตรียม (โปรแกรมจำลองหรืออุปกรณ์จริง); [คู่มือ ADB](docs/adb-device-analysis.md) |
| โปรเจกต์ JEB | หน่วยโปรเจกต์จากเอนจิน, แฮชของอาร์ติแฟกต์ และซูโดโค้ดของไทป์/เมท็อด | ไคลเอนต์ JEB ที่ผู้เรียกเริ่มและให้บริการ MCP เลือกด้วย REA_JEB_MCP_URL; [คู่มือ JEB](docs/jeb-analysis.md) |
| ทรัพยากร Android | ไฟล์ manifest ที่ถอดรหัสแล้ว ตารางสตริง ภาษา และข้อมูลเวอร์ชัน | ตัวเรียก Apktool ที่ผู้เรียกจัดเตรียม; [คู่มือทรัพยากร](docs/apktool-resource-analysis.md) |
+| แอป Flutter | แฮชสแนปชอต Dart, แฮชไลบรารีราย ABI และที่มาของบิลด์เอนจิน | ไม่ต้อง (วิเคราะห์ APK แบบ static); [คู่มือ Flutter](docs/flutter-analysis.md) |
| เฟิร์มแวร์ | พื้นที่ข้อมูล ผลการแตกไฟล์ และการส่งต่อไปวิเคราะห์เนทีฟ | Binwalk / Unblob บน Linux; [คู่มือเฟิร์มแวร์](docs/firmware-analysis.md) |
| แพ็กเกจและทรัพยากร | รายการไฟล์ ค่าแฮช plist โครงสร้างบันเดิลของ Apple และทรัพยากรที่แตกออกมา | [คู่มืออาร์ติแฟกต์และ JavaScript](docs/javascript-artifact-reconstruction.md), [แอปพลิเคชัน Apple](docs/apple-application-analysis.md) |
| พฤติกรรมของโปรเซส | เอาต์พุตเทอร์มินัล การโต้ตอบ ข้อมูลการสิ้นสุดและระบบไฟล์ที่สังเกตได้ และการเปรียบเทียบการรัน | Linux/macOS ที่มี PTY เนทีฟ; [การบันทึกโปรเซส](docs/process-capture.md) |
diff --git a/README_tr.md b/README_tr.md
index abc40f088..28caee260 100644
--- a/README_tr.md
+++ b/README_tr.md
@@ -144,6 +144,7 @@ REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araç
| Android cihazları | Cihazlar, paketler, süreçler, günlükler, dökümler, ekran görüntüleri ve APK/dosya aktarımları | Çağıranın sağladığı adb (emülatör veya cihaz); [ADB rehberi](docs/adb-device-analysis.md) |
| JEB projeleri | Motor destekli proje birimleri, artefakt özetleri ve tür/metot sözdekodu | Çağıranın başlattığı, MCP sunan bir JEB istemcisi, REA_JEB_MCP_URL ile seçilir; [JEB rehberi](docs/jeb-analysis.md) |
| Android kaynakları | Çözülmüş manifest, dize tabloları, diller ve sürüm bilgileri | Çağıranın sağladığı Apktool başlatıcısı; [kaynak rehberi](docs/apktool-resource-analysis.md) |
+| Flutter uygulamaları | Dart anlık görüntü karması, ABI başına kitaplık özetleri ve motor derleme kökeni | Yok (statik APK çözümleme); [Flutter rehberi](docs/flutter-analysis.md) |
| Donanım yazılımı | Bölgeler, çıkarma sonuçları ve yerel kod analizine devirler | Linux üzerinde Binwalk / Unblob; [donanım yazılımı rehberi](docs/firmware-analysis.md) |
| Paketler ve kaynaklar | Dosya envanterleri, özet değerleri, plist'ler, Apple paket yapısı ve çıkarılmış kaynaklar | [Artefakt ve JavaScript rehberi](docs/javascript-artifact-reconstruction.md), [Apple uygulamaları](docs/apple-application-analysis.md) |
| Süreç davranışı | Terminal çıktısı, etkileşimler, sonlanma ve dosya sistemi gözlemleri, çalıştırma karşılaştırmaları | Yerel PTY ile Linux/macOS; [süreç yakalama](docs/process-capture.md) |
diff --git a/README_uk.md b/README_uk.md
index bf824a4f1..a97624ec8 100644
--- a/README_uk.md
+++ b/README_uk.md
@@ -144,6 +144,7 @@ REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а та
| Пристрої Android | Пристрої, пакети, процеси, журнали, дампи, знімки екрана та передавання APK/файлів | adb, наданий викликаючою стороною (емулятор або пристрій); [підручник ADB](docs/adb-device-analysis.md) |
| Проєкти JEB | Єдиниці проєкту від рушія, дайджести артефактів і псевдокод типів/методів | Запущений викликаною стороною клієнт JEB з MCP, обирається через REA_JEB_MCP_URL; [посібник JEB](docs/jeb-analysis.md) |
| Ресурси Android | Декодований маніфест, таблиці рядків, мови та відомості про версію | Засіб запуску Apktool, наданий викликаючою стороною; [підручник ресурсів](docs/apktool-resource-analysis.md) |
+| Додатки Flutter | Хеш знімка Dart, дайджести бібліотек за ABI та походження збірки рушія | Не потрібні (статичний розбір APK); [підручник Flutter](docs/flutter-analysis.md) |
| Прошивки | Області, результати видобування й передавання до нативного аналізу | Binwalk / Unblob у Linux; [посібник прошивок](docs/firmware-analysis.md) |
| Пакети й ресурси | Переліки файлів, хеші, plist, структура пакетів Apple та видобуті ресурси | [Посібник артефактів і JavaScript](docs/javascript-artifact-reconstruction.md), [застосунки Apple](docs/apple-application-analysis.md) |
| Поведінка процесів | Вивід термінала, взаємодії, спостереження за завершенням і файловою системою та порівняння запусків | Linux/macOS із нативним PTY; [захоплення процесів](docs/process-capture.md) |
diff --git a/README_vi.md b/README_vi.md
index 9bb23d09a..be4eac7c2 100644
--- a/README_vi.md
+++ b/README_vi.md
@@ -144,6 +144,7 @@ REA yêu cầu Node.js 22.x (>=22.19), 24.x (>=24.11) hoặc 26+, cùng với np
| Thiết bị Android | Thiết bị, gói, tiến trình, nhật ký, dump, ảnh chụp màn hình và truyền APK/tệp | adb do nơi gọi cung cấp (trình giả lập hoặc thiết bị); [hướng dẫn ADB](docs/adb-device-analysis.md) |
| Dự án JEB | Đơn vị dự án từ engine, hash của artifact và mã giả của kiểu/phương thức | Một ứng dụng JEB do nơi gọi khởi động, phục vụ MCP, chọn bằng REA_JEB_MCP_URL; [hướng dẫn JEB](docs/jeb-analysis.md) |
| Tài nguyên Android | Manifest đã giải mã, bảng chuỗi, ngôn ngữ và thông tin phiên bản | Trình khởi chạy Apktool do nơi gọi cung cấp; [hướng dẫn tài nguyên](docs/apktool-resource-analysis.md) |
+| Ứng dụng Flutter | Băm snapshot Dart, hash thư viện theo ABI và nguồn gốc build engine | Không cần (phân tích APK tĩnh); [hướng dẫn Flutter](docs/flutter-analysis.md) |
| Phần sụn | Các vùng, kết quả trích xuất và dữ liệu chuyển sang phân tích mã máy | Binwalk / Unblob trên Linux; [hướng dẫn phần sụn](docs/firmware-analysis.md) |
| Gói và tài nguyên | Danh sách tệp, giá trị băm, plist, cấu trúc bundle Apple và tài nguyên được trích xuất | [Hướng dẫn hiện vật phần mềm và JavaScript](docs/javascript-artifact-reconstruction.md), [ứng dụng Apple](docs/apple-application-analysis.md) |
| Hành vi tiến trình | Đầu ra terminal, tương tác, quan sát khi thoát và hệ thống tệp, cùng so sánh các lần chạy | Linux/macOS có PTY gốc; [ghi lại tiến trình](docs/process-capture.md) |
diff --git a/README_zh-TW.md b/README_zh-TW.md
index 6c80ce6f2..841e4d479 100644
--- a/README_zh-TW.md
+++ b/README_zh-TW.md
@@ -144,6 +144,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
| Android 裝置 | 裝置、套件、程序、日誌、傾印、螢幕擷取以及 APK/檔案傳輸 | 呼叫端提供的 adb(模擬器或實體裝置);[ADB 指南](docs/adb-device-analysis.md) |
| JEB 專案 | 引擎支援的專案單元、成品摘要和型別/方法的虛擬碼 | 由呼叫端啟動、提供 MCP 的 JEB 用戶端,透過 REA_JEB_MCP_URL 選擇;[JEB 指南](docs/jeb-analysis.md) |
| Android 資源 | 解碼後的清單、字串表、語系和版本資訊 | 呼叫端提供的 Apktool 啟動器;[資源指南](docs/apktool-resource-analysis.md) |
+| Flutter 應用 | Dart 快照雜湊、依 ABI 的程式庫雜湊及引擎建置來源 | 無(靜態 APK 解析);[Flutter 指南](docs/flutter-analysis.md) |
| 韌體 | 區域、提取結果和轉交原生分析的內容 | Linux 上的 Binwalk / Unblob;[韌體指南](docs/firmware-analysis.md) |
| 軟體包與資源 | 檔案清單、摘要、plist、Apple bundle 結構和提取的資源 | [製品與 JavaScript 指南](docs/javascript-artifact-reconstruction.md)、[Apple 應用](docs/apple-application-analysis.md) |
| 處理程序行為 | 終端輸出、互動、退出和檔案系統觀察結果,以及執行對比 | 支援原生 PTY 的 Linux/macOS;[處理程序擷取](docs/process-capture.md) |
diff --git a/README_zh.md b/README_zh.md
index e47aac3bc..3d079c970 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -144,6 +144,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
| Android 设备 | 设备、软件包、进程、日志、转储、屏幕截图以及 APK/文件传输 | 调用方提供的 adb(模拟器或实体设备);[ADB 指南](docs/adb-device-analysis.md) |
| JEB 项目 | 引擎支持的项目单元、工件摘要和类型/方法的伪代码 | 由调用方启动、提供 MCP 的 JEB 客户端,通过 REA_JEB_MCP_URL 选择;[JEB 指南](docs/jeb-analysis.md) |
| Android 资源 | 解码后的清单、字符串表、语言区域和版本信息 | 调用方提供的 Apktool 启动器;[资源指南](docs/apktool-resource-analysis.md) |
+| Flutter 应用 | Dart 快照哈希、按 ABI 的库摘要及引擎构建溯源 | 无(静态 APK 解析);[Flutter 指南](docs/flutter-analysis.md) |
| 固件 | 区域、提取结果和转交原生分析的内容 | Linux 上的 Binwalk / Unblob;[固件指南](docs/firmware-analysis.md) |
| 软件包与资源 | 文件清单、摘要、plist、Apple bundle 结构和提取的资源 | [制品与 JavaScript 指南](docs/javascript-artifact-reconstruction.md)、[Apple 应用](docs/apple-application-analysis.md) |
| 进程行为 | 终端输出、交互、退出和文件系统观察结果,以及运行对比 | 支持原生 PTY 的 Linux/macOS;[进程捕获](docs/process-capture.md) |
diff --git a/docs/flutter-analysis.md b/docs/flutter-analysis.md
new file mode 100644
index 000000000..75c23dd66
--- /dev/null
+++ b/docs/flutter-analysis.md
@@ -0,0 +1,156 @@
+# Flutter build identification
+
+REA identifies a Flutter app's build facts by **pure parsing** of its APK:
+the Dart VM snapshot hash, per-ABI library digests, the engine's GNU
+build-id, and any labeled version strings. No engine, no tool installation,
+no execution, and no external lookups — this family answers "which Dart SDK
+build is this, and what exactly is in the payload?" before any deeper
+native analysis.
+
+This is the triage step for Flutter reversing: the snapshot hash is the
+artifact that maps to a Dart SDK release through an external dataset (such
+as the one reFlutter maintains), and knowing the SDK version is what makes
+SDK-layout-specific snapshot parsers applicable.
+
+## Answer an analyst question
+
+```sh
+rea identify-flutter-build /targets/Example.apk
+rea inspect-dart-aot /targets/Example.apk
+rea inspect-dart-aot /targets/Example.apk --abi armeabi-v7a
+```
+
+The equivalent MCP methods are `identify_flutter_build` (with `path`) and
+`inspect_dart_aot` (with `path` and an optional `abi`; the default prefers
+arm64-v8a, then x86_64, then x86, then armeabi-v7a, then the remaining
+ABIs alphabetically).
+
+## What the AOT inspection returns
+
+`inspect_dart_aot` reads one ABI's `libapp.so` in full and reports:
+
+- **Snapshot sections** — the four `_kDart*Snapshot*` symbols located
+ through the ELF **dynamic symbol table** (ELF32 and ELF64, little-endian,
+ every read bounds-checked), each with file offset, size, and — for data
+ sections, which carry the `f5f5dcdc` magic — the parsed header kind and
+ length (the stored length excludes the four magic bytes). Data headers
+ whose declared snapshot length does not fit their symbol retain their
+ observed fields and report partial coverage. Complete structural coverage
+ currently requires kind 3, the FullAOT value in the supported
+ [Dart 2.14 layout](https://github.com/dart-lang/sdk/blob/2.14.0/runtime/vm/snapshot.h).
+ Kind numbers vary across Dart releases; other values are preserved with
+ partial coverage, without guessing their interpretation.
+ A payload without exported snapshot symbols is refused rather
+ than guessed at.
+- **The snapshot hash** from the header at the start of each exported data
+ symbol. Complete hash coverage requires a valid header from both the VM
+ and isolate; duplicate records inside one symbol cannot stand in for the
+ other's header. Aliased or overlapping data symbols report partial coverage.
+- **A string-pool projection from the isolate data section**: distinct
+ `package:` source URIs (the app's own and its dependencies' Dart files —
+ a dependency inventory), `dart:` SDK URIs (which SDK libraries the app
+ uses), and identifier-shaped tokens, each bounded with counts and
+ `coverage: "partial"` when truncated. On the reference target this counts
+ 756 package URIs and 201 dart URIs on arm64-v8a and x86_64, and 212 / 48
+ on armeabi-v7a, retaining up to 500 of each in the response.
+ `libapp.coverage` describes structural snapshot checks;
+ `string_pool.coverage` describes the bounded projection. Overall coverage
+ is partial when either facet is partial.
+
+## Interpret the result
+
+- **`flutter_detected`** is true when any `lib/<abi>/libapp.so` exists. A
+ negative answer reports complete coverage: absence is an answer.
+- **`snapshot_hash`** is the Dart build hash observed 20 bytes after the
+ snapshot magic (`f5 f5 dc dc`) inside `libapp.so`. Identification scans
+ byte patterns; AOT inspection reads the exported VM and isolate headers.
+ `snapshot_hash_sources` counts the valid records observed by the chosen
+ operation, and when they **disagree** the distinct values are
+ kept in `snapshot_hash_candidates` with `snapshot_hash: null` and
+ `coverage: "partial"` rather than silently picking one.
+- **`elf_header_valid`** checks the supported little-endian ELF32/ELF64
+ header, table entry widths, and full table extents against the library's
+ actual byte length. Truncated, malformed, or unsupported headers report
+ false and partial coverage while retaining byte-scanned hashes. This
+ header check does not establish valid table contents or exported symbols.
+- **`libflutter` facts** are per-ABI observations: byte size, SHA-256
+ digest, GNU build IDs from ELF-declared `PT_NOTE` / `SHT_NOTE` ranges,
+ and any _labeled_ strings the build
+ carries. Release engine builds often strip the `Dart VM version` string —
+ absence is reported as `null`, not guessed. Android clang/LLVM toolchain
+ lines are reported verbatim as build provenance.
+ `build_id_candidates` preserves distinct IDs. `build_id` is populated only
+ when all declared note ranges were examined and one ID was found;
+ conflicting IDs or malformed/bounded note metadata make coverage partial.
+ Matching bytes outside declared note ranges cannot supply a build ID.
+- Labeled strings must fit their complete grammar. `dart_version_capped`
+ and `toolchain_capped` independently report labels omitted by grammar or
+ projection bounds; either makes identification coverage partial. Values
+ split across read chunks are retained without publishing truncated prefixes.
+- **`coverage: "partial"`** also appears when an ABI carries `libapp.so`
+ without `libflutter.so` (or vice versa).
+- The APK itself is digested before parsing, so `target.sha256` binds the
+ observation to the exact input.
+
+## Limits
+
+- **Owned snapshots.** Both operations copy the admitted APK into a
+ provider-owned, read-only snapshot before digesting and parsing, so a
+ concurrently modified original cannot mix into one observation; failed
+ reader closure and snapshot cleanup are retained and retried on `close()`.
+ The snapshot is removed only after all owned readers and file descriptors
+ close successfully. Copying pins one admitted descriptor and compares its
+ identity, size, mode and timestamps after the copy. Source permission
+ failures remain `access_denied`, and source identity changes remain
+ `artifact_changed`. Provider-owned storage failures report a
+ `resource_constraint` with their native I/O cause. Cancellation is checked
+ during copying, metadata/symbol walks, string scanning, and after cleanup.
+- **Bounded reads.** APK snapshots are bounded at 2 GiB, including while
+ copying. Identification permits 768 MiB of cumulative library extraction;
+ declared sizes are checked before extraction. Library reads are bounded at 256 MiB each and ZIP
+ metadata at 8 MiB; the AOT image buffer is allocated at exactly the
+ declared size before reading. Exceeded budgets report
+ `resource_constraint`.
+- **Engine notes.** Engine libraries are spooled into the owned root. ELF
+ headers, note tables and note payloads share an 8 MiB metadata budget;
+ up to 64 distinct build IDs are retained. Exceeding either bound preserves
+ the candidates already examined and reports partial coverage.
+- **Metadata and candidate capacity.** Both operations refuse duplicate
+ relevant library paths. Inventory is limited to 32 ABIs and 1024 bytes per
+ relevant library path, independently of compressed size. Identification
+ refuses more than 64 distinct snapshot hashes with `resource_constraint`
+ rather than silently dropping conflicting evidence.
+- **Selected ABI.** AOT inspection applies the library budget to the selected
+ ABI after selection; an oversized unselected library does not block it.
+ Undefined dynamic-symbol imports are not treated as snapshot exports.
+ Section-stripped images require a bounded symbol count from `DT_HASH` or
+ `DT_GNU_HASH`; layouts without either are refused. Symbol names and their
+ terminators must fit their linked string table.
+- REA performs **no hash-to-SDK lookup**: mapping the snapshot hash to a
+ Dart SDK release requires an external dataset and is deliberately out of
+ scope for this family.
+- The AOT string pool is a **byte-pattern projection, not deserialized
+ cluster semantics**: typed class and function recovery requires an
+ SDK-specific parser (the snapshot layout changes per release — exactly
+ why the hash is the key), and `class_like_tokens` include incidental
+ matches. JEB's GUI Dart unit and native analysis of `libapp.so` cover
+ some ground today.
+
+## Real verification
+
+`npm run verify:flutter -- --apk PATH [--plain-apk PATH]` runs both tools
+through compiled CLI and stdio MCP, compares Evidence, and checks every ABI.
+Use `--expectations scripts/fixtures/flutter-gallery-expectations.json` with
+the Gallery 2.9.2 release APK to check exact per-ABI engine labels,
+URI counts and the snapshot hash against its pinned SHA-256. The verifier
+requires complete structural snapshot coverage on every ABI and explicitly
+reports the bounded pool projection as partial/unverified when truncated.
+Other APKs need their own expectations file to verify exact engine labels
+and URI counts; otherwise those facets are reported unverified.
+The optional plain APK checks negative detection. Record: Flutter Gallery 2.9.2 (112 MB, three
+ABIs) — every ABI reports the same agreeing hash
+`65817c30a78bb44c3dc3771876b6010a` from two snapshot sections, per-ABI
+engine build-ids, no labeled Dart version (as expected for a release
+engine), and the Android clang toolchain line; a plain aapt2-built APK
+reports not-detected with complete coverage. The suite uses self-contained
+synthetic ELF images and scanner payloads; it does not read private local files.
diff --git a/docs/testing.md b/docs/testing.md
index ec065b14d..d0748b760 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -497,6 +497,36 @@ with the reported target identity, apktool.yml metadata projection
[Apktool resource analysis](apktool-resource-analysis.md) for boundaries and
budgets.
+## Flutter build identification
+
+`npm run verify:flutter -- --apk PATH [--plain-apk PATH]` runs both pure
+static operations against a real Flutter APK, plus an optional non-Flutter
+APK for the negative check. No engine or external tool is involved. Record:
+Flutter Gallery 2.9.2 (112 MB, arm64-v8a / armeabi-v7a / x86_64) — every
+ABI reports the same agreeing snapshot hash
+(`65817c30a78bb44c3dc3771876b6010a`, two sections each) read 20 bytes after
+the Dart snapshot magic, per-ABI engine GNU build-ids, no labeled Dart
+version string (expected for a release engine build), and the Android
+clang/LLVM toolchain line; the AOT inspection locates all four snapshot
+symbols through the dynamic symbol table on both ELF64 and ELF32 images,
+validates the data-section headers, agrees with the identification hash,
+and counts 756 `package:` and 201 `dart:` URIs on arm64-v8a and x86_64,
+and 212 / 48 on armeabi-v7a, from each isolate data section. Responses
+retain at most 500 URIs per family and 2000 class-like tokens. Gallery's
+pool projection and overall AOT coverage are partial while its structural
+`libapp.coverage` is complete. A plain aapt2-built APK reports not-detected with
+complete coverage. The suite uses self-contained synthetic ELF images and recorded scanner
+prefixes, with no private local-file dependency. The verifier now compares
+compiled CLI and stdio MCP Evidence on every ABI, including data-header kind
+and declared lengths. Add
+`--expectations scripts/fixtures/flutter-gallery-expectations.json` for the
+documented Gallery APK to assert its pinned digest, hash, exact engine labels
+and per-ABI URI counts. The verifier requires complete structural snapshot
+coverage, reports bounded pool coverage as partial/unverified, and reports
+exact labels/counts on other APKs unverified without an expectations file.
+See [Flutter build identification](flutter-analysis.md) for boundaries and
+budgets.
+
## ADB device acquisition
`npm run verify:adb` exercises every ADB operation against a live device or
diff --git a/package.json b/package.json
index 0393f84c3..ea47ce850 100644
--- a/package.json
+++ b/package.json
@@ -164,6 +164,7 @@
"verify:legacy-simulator": "npm run build:cached && node scripts/verify/apple/legacy-simulator.mjs",
"verify:architecture-guards": "node scripts/verify/architecture-guards.mjs",
"verify:apktool": "npm run build:cached && node scripts/verify-apktool.mjs",
+ "verify:flutter": "npm run build:cached && node scripts/verify-flutter.mjs",
"verify:adb": "npm run build:cached && node scripts/verify-adb.mjs",
"verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
"verify:ghidra:seeds": "npm run build:cached && node scripts/verify/ghidra/seeds.mjs",
diff --git a/scripts/fixtures/flutter-gallery-expectations.json b/scripts/fixtures/flutter-gallery-expectations.json
new file mode 100644
index 000000000..909d86e66
--- /dev/null
+++ b/scripts/fixtures/flutter-gallery-expectations.json
@@ -0,0 +1,38 @@
+{
+ "target_sha256": "659b5fc6a4319dfe4f117d00ad4e7ec004915ebcadcb96628797fb3544040e29",
+ "snapshot_hash": "65817c30a78bb44c3dc3771876b6010a",
+ "engines": {
+ "x86_64": {
+ "dart_version": null,
+ "toolchain_lines": [
+ "Android (5900059 based on r365631c) clang version 9.0.8 (https://android.googlesource.com/toolchain/llvm-project 207d7abc1a2abf3ef8d4301736d6a7ebc224a290) (based on LLVM 9.0.8svn)"
+ ]
+ },
+ "armeabi-v7a": {
+ "dart_version": null,
+ "toolchain_lines": [
+ "Android (5900059 based on r365631c) clang version 9.0.8 (https://android.googlesource.com/toolchain/llvm-project 207d7abc1a2abf3ef8d4301736d6a7ebc224a290) (based on LLVM 9.0.8svn)"
+ ]
+ },
+ "arm64-v8a": {
+ "dart_version": null,
+ "toolchain_lines": [
+ "Android (5900059 based on r365631c) clang version 9.0.8 (https://android.googlesource.com/toolchain/llvm-project 207d7abc1a2abf3ef8d4301736d6a7ebc224a290) (based on LLVM 9.0.8svn)"
+ ]
+ }
+ },
+ "string_pools": {
+ "x86_64": {
+ "package_uri_count_at_least": 756,
+ "dart_uri_count_at_least": 201
+ },
+ "armeabi-v7a": {
+ "package_uri_count_at_least": 212,
+ "dart_uri_count_at_least": 48
+ },
+ "arm64-v8a": {
+ "package_uri_count_at_least": 756,
+ "dart_uri_count_at_least": 201
+ }
+ }
+}
diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjs
index 787d6255d..2ecafd9ae 100644
--- a/scripts/lib/catalog-builders.mjs
+++ b/scripts/lib/catalog-builders.mjs
@@ -49,6 +49,11 @@ export const toolFamilyCatalog = (sources) => {
surface: "android-provider",
contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,
},
+ {
+ id: "flutter",
+ surface: "flutter-provider",
+ contracts: sources.flutterContracts.FLUTTER_TOOL_CONTRACTS,
+ },
{
id: "frida",
surface: "instrumentation-provider",
@@ -231,6 +236,10 @@ export const providerCatalog = (sources) => {
identity: sources.androidProvider.JADX_PROVIDER_IDENTITY,
contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,
},
+ {
+ identity: sources.flutterProvider.FLUTTER_PROVIDER_IDENTITY,
+ contracts: sources.flutterContracts.FLUTTER_TOOL_CONTRACTS,
+ },
{
identity: sources.apktoolProvider.APKTOOL_PROVIDER_IDENTITY,
contracts: sources.apktoolContracts.APKTOOL_TOOL_CONTRACTS,
diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjs
index 546b7359c..6287f257b 100644
--- a/scripts/lib/catalog-core.mjs
+++ b/scripts/lib/catalog-core.mjs
@@ -58,8 +58,12 @@ const SOURCE_PATHS = {
firmwareContracts: "dist/contracts/firmware/firmwareToolContracts.js",
firmwareProvider: "dist/firmware/FirmwareRelease.js",
androidContracts: "dist/contracts/android/androidToolContracts.js",
+ flutterContracts: "dist/contracts/flutter/flutterToolContracts.js",
+ flutterProvider: "dist/flutter/FlutterBuildProvider.js",
androidProvider: "dist/android/JadxRelease.js",
apktoolContracts: "dist/contracts/apktool/apktoolToolContracts.js",
+ flutterContracts: "dist/contracts/flutter/flutterToolContracts.js",
+ flutterProvider: "dist/flutter/FlutterBuildProvider.js",
apktoolProvider: "dist/apktool/ApktoolProvider.js",
jebContracts: "dist/contracts/jeb/jebToolContracts.js",
jebProvider: "dist/jeb/JebProvider.js",
diff --git a/scripts/verify-flutter.mjs b/scripts/verify-flutter.mjs
new file mode 100644
index 000000000..061ad8b20
--- /dev/null
+++ b/scripts/verify-flutter.mjs
@@ -0,0 +1,259 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { toolContract } from "../dist/contracts/toolContracts.js";
+import { PrivateRuntimeRoot } from "../dist/process/PrivateRuntimeRoot.js";
+import { hashStableFile } from "../dist/filesystem/StableFileHash.js";
+import { mcpTextValue } from "./lib/mcp-verifier-results.mjs";
+
+const options = parseArguments(process.argv.slice(2));
+if (options.help) {
+ process.stdout.write(
+ "Usage: npm run verify:flutter -- --apk PATH [--plain-apk PATH] [--expectations JSON]\n" +
+ "Checks real APK parsing through compiled CLI and stdio MCP. Optional\n" +
+ "expectations bind exact engine labels, URI counts and snapshot hash to an APK digest.\n",
+ );
+ process.exit(0);
+}
+if (options.apk === null) {
+ process.stderr.write("No Flutter APK was provided; pass --apk PATH.\n");
+ process.exit(2);
+}
+const expectations =
+ options.expectations === null
+ ? null
+ : JSON.parse(await readFile(options.expectations, "utf8"));
+const root = await PrivateRuntimeRoot.create({
+ prefix: "rea-flutter-verifier-",
+});
+const entrypoint = resolve("scripts/rea.mjs");
+const environment = Object.fromEntries(
+ Object.entries(process.env).filter(([, value]) => typeof value === "string"),
+);
+Object.assign(environment, {
+ TMPDIR: root.path,
+ TMP: root.path,
+ TEMP: root.path,
+});
+const client = new Client({ name: "flutter-verifier", version: "1" });
+const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [entrypoint, "mcp"],
+ env: environment,
+ stderr: "pipe",
+});
+const execute = promisify(execFile);
+try {
+ await client.connect(transport);
+ const apk = resolve(options.apk);
+ const identity = await hashStableFile(apk);
+ const identified = await run("identify_flutter_build", { path: apk });
+ assert.deepEqual(identified.target, { path: apk, ...identity });
+ assert.equal(identified.flutter_detected, true);
+ assert.equal(identified.coverage, "complete");
+ const abis = identified.abis.filter((abi) => abi.libapp.present);
+ assert.ok(abis.length > 0);
+ const hashes = new Set();
+ for (const abi of abis) {
+ assert.equal(abi.libapp.elf_header_valid, true);
+ assert.equal(abi.libapp.snapshot_hash_sources, 2);
+ assert.ok(abi.libapp.snapshot_hash);
+ hashes.add(abi.libapp.snapshot_hash);
+ assert.equal(abi.libflutter.present, true);
+ assert.match(abi.libflutter.build_id ?? "", /^(?:[0-9a-f]{2}){4,64}$/u);
+ assert.deepEqual(abi.libflutter.build_id_candidates, [
+ abi.libflutter.build_id,
+ ]);
+ }
+ assert.equal(hashes.size, 1, "Every ABI must agree on the snapshot hash");
+ if (expectations !== null) {
+ assert.equal(identity.sha256, expectations.target_sha256);
+ assert.deepEqual([...hashes], [expectations.snapshot_hash]);
+ assert.deepEqual(
+ abis.map((abi) => abi.abi).sort(),
+ Object.keys(expectations.engines).sort(),
+ );
+ for (const abi of abis) {
+ assert.deepEqual(
+ {
+ dart_version: abi.libflutter.dart_version,
+ toolchain_lines: abi.libflutter.toolchain_lines,
+ },
+ expectations.engines[abi.abi],
+ );
+ assert.equal(abi.libflutter.dart_version_capped, false);
+ assert.equal(abi.libflutter.toolchain_capped, false);
+ }
+ process.stdout.write(
+ "[ok] Exact per-ABI engine labels match digest-bound expectations\n",
+ );
+ } else {
+ process.stdout.write(
+ "[unverified] Exact engine labels and their absence need --expectations JSON\n",
+ );
+ }
+ // The same checks apply to the default selection and each remaining ABI.
+ const preferred = await run("inspect_dart_aot", { path: apk });
+ for (const abi of abis) {
+ const aot =
+ abi.abi === preferred.abi
+ ? preferred
+ : await run("inspect_dart_aot", { path: apk, abi: abi.abi });
+ assert.equal(aot.abi, abi.abi);
+ assert.equal(
+ aot.libapp.coverage,
+ "complete",
+ `Snapshot decoding must be complete on ${abi.abi}`,
+ );
+ assert.equal(aot.coverage, aot.string_pool.coverage);
+ if (aot.coverage !== "complete") {
+ process.stdout.write(
+ `[unverified] ${abi.abi}: full string-pool projection (returned pool is bounded and partial)\n`,
+ );
+ }
+ assert.deepEqual(aot.target, identified.target);
+ assert.equal(aot.libapp.sha256, abi.libapp.sha256);
+ assert.equal(aot.libapp.bytes, abi.libapp.bytes);
+ assert.equal(aot.libapp.snapshot_hash_sources, 2);
+ assert.equal(aot.libapp.snapshot_hash, abi.libapp.snapshot_hash);
+ assert.deepEqual(
+ aot.libapp.sections.map((section) => section.name).sort(),
+ [
+ "_kDartVmSnapshotData",
+ "_kDartVmSnapshotInstructions",
+ "_kDartIsolateSnapshotData",
+ "_kDartIsolateSnapshotInstructions",
+ ].sort(),
+ );
+ for (const section of aot.libapp.sections) {
+ assert.ok(section.offset + section.size <= aot.libapp.bytes);
+ if (!section.name.endsWith("Data")) continue;
+ assert.equal(section.magic_valid, true);
+ assert.equal(
+ section.kind,
+ 3,
+ "This verifier requires an AOT app snapshot",
+ );
+ assert.ok(
+ section.header_length >= 48 &&
+ section.header_length + 4 <= section.size,
+ `Snapshot extent must fit ${section.name} on ${abi.abi}`,
+ );
+ }
+ assert.ok(aot.string_pool.package_uri_count_at_least > 0);
+ assert.ok(aot.string_pool.dart_uri_count_at_least > 0);
+ if (expectations?.string_pools !== undefined) {
+ const expected = expectations.string_pools[abi.abi];
+ assert.ok(
+ expected,
+ `Pinned string-pool counts are required on ${abi.abi}`,
+ );
+ assert.equal(
+ aot.string_pool.package_uri_count_at_least,
+ expected.package_uri_count_at_least,
+ );
+ assert.equal(
+ aot.string_pool.dart_uri_count_at_least,
+ expected.dart_uri_count_at_least,
+ );
+ process.stdout.write(
+ `[ok] ${abi.abi}: exact pinned package and Dart URI counts\n`,
+ );
+ } else {
+ process.stdout.write(
+ `[unverified] ${abi.abi}: exact string-pool counts need --expectations JSON\n`,
+ );
+ }
+ process.stdout.write(
+ `[ok] ${abi.abi}: four symbols, bounded AOT headers, agreeing hashes and string pool\n`,
+ );
+ }
+ if (options.plainApk !== null) {
+ const plain = resolve(options.plainApk);
+ const negative = await run("identify_flutter_build", { path: plain });
+ assert.deepEqual(negative.target, {
+ path: plain,
+ ...(await hashStableFile(plain)),
+ });
+ assert.equal(negative.flutter_detected, false);
+ assert.equal(negative.coverage, "complete");
+ }
+ assert.deepEqual(
+ await hashStableFile(apk),
+ identity,
+ "Verification must preserve its input",
+ );
+} finally {
+ // Server shutdown retries retained provider cleanup and must settle before success.
+ try {
+ await client.close();
+ await transport.close();
+ assert.deepEqual(
+ await readdir(root.path),
+ [],
+ "Provider snapshots must be released before verification succeeds",
+ );
+ } finally {
+ await root.close();
+ }
+}
+process.stdout.write(
+ "all asserted Flutter CLI/MCP checks passed; unverified facets are reported above\n",
+);
+
+async function run(operation, input) {
+ const contract = toolContract(operation);
+ const args = [
+ entrypoint,
+ operation.replaceAll("_", "-"),
+ input.path,
+ "--json",
+ ];
+ if (input.abi !== undefined) args.push("--abi", input.abi);
+ const { stdout } = await execute(process.execPath, args, {
+ env: environment,
+ timeout: 60_000,
+ maxBuffer: 8 * 1024 * 1024,
+ });
+ const cli = contract.outputSchema.parse(JSON.parse(stdout));
+ const response = await client.callTool(
+ { name: operation, arguments: input },
+ { timeout: 60_000 },
+ );
+ assert.notEqual(response.isError, true, mcpTextValue(response));
+ const mcp = contract.outputSchema.parse(JSON.parse(mcpTextValue(response)));
+ assert.deepEqual(cli.normalized_result, mcp.normalized_result);
+ assert.deepEqual(cli.subject, mcp.subject);
+ assert.equal(cli.subject.local_path, input.path);
+ assert.equal(cli.subject.digest.sha256, cli.normalized_result.target.sha256);
+ assert.deepEqual(cli.limitations, mcp.limitations);
+ process.stdout.write(
+ `[ok] ${operation}${input.abi === undefined ? "" : ` ${input.abi}`}: CLI/MCP Evidence parity\n`,
+ );
+ return cli.normalized_result;
+}
+
+function parseArguments(argv) {
+ const parsed = { help: false, apk: null, plainApk: null, expectations: null };
+ const names = {
+ "--apk": "apk",
+ "--plain-apk": "plainApk",
+ "--expectations": "expectations",
+ };
+ for (let index = 0; index < argv.length; index += 1) {
+ const argument = argv[index];
+ if (argument === "--help" || argument === "-h") parsed.help = true;
+ else if (
+ Object.hasOwn(names, argument) &&
+ typeof argv[index + 1] === "string" &&
+ !argv[index + 1].startsWith("--")
+ ) {
+ parsed[names[argument]] = argv[++index];
+ } else throw new Error(`Unknown argument or missing value: ${argument}`);
+ }
+ return parsed;
+}
diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts
index 76c5cafbb..ac825bc04 100644
--- a/src/application/CapabilityInventory.ts
+++ b/src/application/CapabilityInventory.ts
@@ -453,6 +453,8 @@ const workflowAvailabilityFor = ({
remediation: "Run process capture on a supported Linux or macOS host.",
};
if (kind === "application") return { reason: "available", remediation: null };
+ if (kind === "flutter-provider")
+ return { reason: "available", remediation: null };
const electron = electronProviderAvailability(name, kind, policy);
if (electron !== null) return electron;
if (kind === "runtime-provider")
diff --git a/src/application/flutter/FlutterBuildAnalysisPort.ts b/src/application/flutter/FlutterBuildAnalysisPort.ts
new file mode 100644
index 000000000..2a52d060e
--- /dev/null
+++ b/src/application/flutter/FlutterBuildAnalysisPort.ts
@@ -0,0 +1,23 @@
+import type {
+ AnalysisExecution,
+ ExecutionOptions,
+ ProviderAvailability,
+} from "../AnalysisProvider.js";
+import type { FlutterRequest } from "../../domain/flutter/flutterBuildAnalysis.js";
+import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { Result } from "../../domain/result.js";
+
+/**
+ * Flutter build-identification boundary by pure APK parsing.
+ * Implementation details belong to the provider adapter.
+ */
+export interface FlutterBuildAnalysisPort {
+ /** Pure parsing; always available. */
+ inspectAvailability(signal?: AbortSignal): Promise<ProviderAvailability>;
+ /** The provider holds no long-lived resources; safe to call always. */
+ close(): Promise<void>;
+ execute(
+ request: FlutterRequest,
+ options?: ExecutionOptions,
+ ): Promise<Result<AnalysisExecution, AnalysisError>>;
+}
diff --git a/src/application/flutter/FlutterBuildAnalysisService.test.ts b/src/application/flutter/FlutterBuildAnalysisService.test.ts
new file mode 100644
index 000000000..1ecf31483
--- /dev/null
+++ b/src/application/flutter/FlutterBuildAnalysisService.test.ts
@@ -0,0 +1,93 @@
+import { expect, it } from "vitest";
+
+import { FlutterBuildAnalysisService } from "./FlutterBuildAnalysisService.js";
+import type { FlutterBuildAnalysisPort } from "./FlutterBuildAnalysisPort.js";
+import { createAnalysisExecution } from "../AnalysisProvider.js";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { parseEvidence } from "../../domain/evidence.js";
+import { ok } from "../../domain/result.js";
+
+const identity = {
+ id: "flutter",
+ name: "Flutter build identification",
+ version: null,
+};
+
+const execution = createAnalysisExecution(
+ {
+ target: { path: "/targets/app.apk", bytes: 10, sha256: "a".repeat(64) },
+ flutter_detected: true,
+ abis: [],
+ coverage: "complete",
+ },
+ identity,
+);
+
+const refusing: FlutterBuildAnalysisPort = {
+ async inspectAvailability() {
+ throw new Error("must not probe");
+ },
+ async close() {},
+ async execute() {
+ throw new Error("must not execute");
+ },
+};
+
+const malformedSelections: readonly unknown[] = [
+ { path: "/targets/app.apk", extra: true },
+ { path: 7 },
+ {},
+ { path: "/targets/app.apk", abi: "not a locale" },
+];
+it.each(malformedSelections)("refuses %j at admission", async (input) => {
+ const settled = await new FlutterBuildAnalysisService(refusing).execute(
+ "identify_flutter_build",
+ input,
+ );
+ expect(settled.ok).toBe(false);
+ if (settled.ok) return;
+ expect(settled.error._tag).toBe("AnalysisInputError");
+});
+
+it("passes the validated request to the provider and seals Evidence", async () => {
+ const seen: unknown[] = [];
+ const recording: FlutterBuildAnalysisPort = {
+ async inspectAvailability() {
+ return { status: "available", code: null, reason: null, diagnostics: {} };
+ },
+ async close() {},
+ async execute(request) {
+ seen.push(request);
+ return ok(execution);
+ },
+ };
+ const result = await new FlutterBuildAnalysisService(recording).execute(
+ "identify_flutter_build",
+ { path: "/targets/app.apk" },
+ );
+ expect(seen).toEqual([
+ {
+ operation: "identify_flutter_build",
+ input: { path: "/targets/app.apk" },
+ },
+ ]);
+ if (!result.ok) throw new Error(result.error.message);
+ const evidence = parseEvidence(result.value);
+ expect(evidence.provider).toEqual(identity);
+ expect(evidence.confidence).toBe("observed");
+});
+
+it("settles an already-aborted call as cancellation before execution", async () => {
+ const controller = new AbortController();
+ controller.abort();
+ const settled = await new FlutterBuildAnalysisService(refusing).execute(
+ "identify_flutter_build",
+ { path: "/targets/app.apk" },
+ {
+ signal: controller.signal,
+ },
+ );
+ expect(settled.ok).toBe(false);
+ if (settled.ok) return;
+ expect(settled.error).toBeInstanceOf(AnalysisCancelledError);
+});
diff --git a/src/application/flutter/FlutterBuildAnalysisService.ts b/src/application/flutter/FlutterBuildAnalysisService.ts
new file mode 100644
index 000000000..13ddfbba4
--- /dev/null
+++ b/src/application/flutter/FlutterBuildAnalysisService.ts
@@ -0,0 +1,31 @@
+import type { FlutterBuildAnalysisPort } from "./FlutterBuildAnalysisPort.js";
+import type { ExecutionOptions } from "../AnalysisProvider.js";
+import {
+ flutterRequestSchema,
+ type FlutterOperation,
+} from "../../domain/flutter/flutterBuildAnalysis.js";
+import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { Evidence } from "../../domain/evidence.js";
+import { executeProviderOperation } from "../ProviderOperationExecution.js";
+import type { Result } from "../../domain/result.js";
+
+/** Shared CLI/MCP admission, execution, and Evidence composition for Flutter. */
+export class FlutterBuildAnalysisService {
+ constructor(readonly provider: FlutterBuildAnalysisPort) {}
+
+ /** Run one caller-selected Flutter request and retain target identity inline. */
+ execute(
+ operation: FlutterOperation,
+ input: unknown,
+ options?: ExecutionOptions,
+ ): Promise<Result<Evidence, AnalysisError>> {
+ return executeProviderOperation(
+ operation,
+ input,
+ options,
+ flutterRequestSchema,
+ this.provider,
+ "observed",
+ );
+ }
+}
diff --git a/src/artifacts/RegularFileAdmission.test.ts b/src/artifacts/RegularFileAdmission.test.ts
index 818e75ef1..17926799a 100644
--- a/src/artifacts/RegularFileAdmission.test.ts
+++ b/src/artifacts/RegularFileAdmission.test.ts
@@ -1,4 +1,4 @@
-import type { Stats } from "node:fs";
+import type { BigIntStats, Stats } from "node:fs";
import type { FileHandle } from "node:fs/promises";
import { afterEach, expect, it, vi } from "vitest";
@@ -6,6 +6,7 @@ import {
NonRegularFileReadError,
openRegularFile,
RegularFileAdmissionFailure,
+ sameRegularFileState,
} from "../filesystem/RegularFile.js";
const { mockOpen } = vi.hoisted(() => ({ mockOpen: vi.fn() }));
@@ -66,3 +67,24 @@ it.each(["cancellation after open", "non-regular metadata", "stat failure"])(
else expect(cause.cause).toBe(cancellation);
},
);
+
+it("compares available nanosecond timestamps without rounding away source changes", () => {
+ const before = {
+ dev: 1n,
+ ino: 2n,
+ size: 3n,
+ mode: 0o100400n,
+ mtimeMs: 10n,
+ ctimeMs: 20n,
+ mtimeNs: 10_000_001n,
+ ctimeNs: 20_000_001n,
+ isFile: () => true,
+ } as BigIntStats;
+ expect(sameRegularFileState(before, { ...before })).toBe(true);
+ expect(
+ sameRegularFileState(before, { ...before, mtimeNs: before.mtimeNs + 1n }),
+ ).toBe(false);
+ expect(
+ sameRegularFileState(before, { ...before, ctimeNs: before.ctimeNs + 1n }),
+ ).toBe(false);
+});
diff --git a/src/cli.ts b/src/cli.ts
index 0ad7613d8..36c05f6c9 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -21,6 +21,7 @@ import { registerManagedCommands } from "./cli/managedCommands.js";
import { registerFirmwareCommands } from "./cli/firmwareCommands.js";
import { registerAndroidCommands } from "./cli/androidCommands.js";
import { registerApktoolCommands } from "./cli/apktoolCommands.js";
+import { registerFlutterCommands } from "./cli/flutterCommands.js";
import { registerJebCommands } from "./cli/jebCommands.js";
import { registerAdbCommands } from "./cli/adbCommands.js";
import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
@@ -98,6 +99,7 @@ export const createCli = (
registerManagedCommands(cli, logger, analysis.runProviderAnalysis);
registerAndroidCommands(cli, logger, environment);
registerApktoolCommands(cli, logger, environment);
+ registerFlutterCommands(cli, logger);
registerJebCommands(cli, logger, environment);
registerAdbCommands(cli, logger, environment);
registerFirmwareCommands(cli, logger, environment);
diff --git a/src/cli/flutterCommands.ts b/src/cli/flutterCommands.ts
new file mode 100644
index 000000000..a1be8e648
--- /dev/null
+++ b/src/cli/flutterCommands.ts
@@ -0,0 +1,97 @@
+import { z } from "incur";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { FlutterBuildAnalysisService } from "../application/flutter/FlutterBuildAnalysisService.js";
+import type { FlutterBuildAnalysisPort } from "../application/flutter/FlutterBuildAnalysisPort.js";
+import { createFlutterBuildAnalysisProvider } from "../composition/flutter.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import type { FlutterOperation } from "../domain/flutter/flutterBuildAnalysis.js";
+import type { Logger } from "pino";
+import type { CliInstance } from "./types.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+
+/** One flutter command: CLI shape and the request it produces. */
+interface FlutterCommandSpec {
+ readonly command: string;
+ readonly description: string;
+ readonly argumentSchema: z.ZodObject<z.ZodRawShape>;
+ readonly optionSchema?: z.ZodObject<z.ZodRawShape>;
+ readonly operation: FlutterOperation;
+ readonly toInput: (
+ arguments_: Record<string, unknown>,
+ options: Record<string, unknown>,
+ ) => unknown;
+}
+
+/** Expose the same explicit Flutter requests through one-shot CLI commands. */
+export const registerFlutterCommands = (
+ cli: CliInstance,
+ logger: Logger,
+ provider: FlutterBuildAnalysisPort = createFlutterBuildAnalysisProvider(),
+): void => {
+ const specs: readonly FlutterCommandSpec[] = [
+ {
+ command: CLI_COMMANDS.identifyFlutterBuild,
+ description:
+ "Identify a Flutter build's Dart snapshot hash and engine facts by pure APK parsing",
+ argumentSchema: z.object({
+ path: z.string().min(1).describe("Local APK file to inspect"),
+ }),
+ operation: "identify_flutter_build",
+ toInput: (arguments_) => arguments_,
+ },
+ {
+ command: CLI_COMMANDS.inspectDartAot,
+ description:
+ "Inspect one ABI's Dart AOT snapshot: sections, headers, and the string pool",
+ argumentSchema: z.object({
+ path: z
+ .string()
+ .min(1)
+ .describe("Local APK carrying a Flutter payload"),
+ }),
+ optionSchema: z.object({
+ abi: z
+ .string()
+ .min(2)
+ .max(16)
+ .optional()
+ .describe("ABI under lib/ to inspect; defaults to the preferred one"),
+ }),
+ operation: "inspect_dart_aot",
+ toInput: (arguments_, options) => ({
+ path: arguments_.path,
+ ...(options.abi === undefined ? {} : { abi: options.abi }),
+ }),
+ },
+ ];
+ for (const spec of specs) {
+ cli.command(spec.command, {
+ description: spec.description,
+ ...(spec.optionSchema === undefined
+ ? { args: spec.argumentSchema }
+ : { args: spec.argumentSchema, options: spec.optionSchema }),
+ run: ({ args, options }) =>
+ withCommandCancellation((signal) =>
+ logCliCommand(logger, spec.command, async () => {
+ const settled = await new FlutterBuildAnalysisService(
+ provider,
+ ).execute(spec.operation, spec.toInput(args, options ?? {}), {
+ signal,
+ });
+ try {
+ await provider.close();
+ } catch (cause) {
+ if (cause instanceof AnalysisError)
+ return projectAnalysisError(cause);
+ throw cause;
+ }
+ return settled.ok
+ ? settled.value
+ : projectAnalysisError(settled.error);
+ }),
+ ),
+ });
+ }
+};
diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.ts
index 3994100af..8fa0505f1 100644
--- a/src/cliCommandNames.ts
+++ b/src/cliCommandNames.ts
@@ -52,6 +52,8 @@ export const CLI_COMMANDS = Object.freeze({
inspectFirmwareRegions: "inspect-firmware-regions",
extractFirmware: "extract-firmware",
inspectAndroidPackage: "inspect-android-package",
+ identifyFlutterBuild: "identify-flutter-build",
+ inspectDartAot: "inspect-dart-aot",
inspectApktoolClient: "inspect-apktool-client",
decodeAndroidResources: "decode-android-resources",
inspectAdbClient: "inspect-adb-client",
diff --git a/src/composition/flutter.ts b/src/composition/flutter.ts
new file mode 100644
index 000000000..75013f77a
--- /dev/null
+++ b/src/composition/flutter.ts
@@ -0,0 +1,6 @@
+import type { FlutterBuildAnalysisPort } from "../application/flutter/FlutterBuildAnalysisPort.js";
+import { FlutterBuildProvider } from "../flutter/FlutterBuildProvider.js";
+
+/** Construct one Flutter provider; it needs no external tools. */
+export const createFlutterBuildAnalysisProvider =
+ (): FlutterBuildAnalysisPort => new FlutterBuildProvider();
diff --git a/src/contracts/flutter/flutterToolContracts.ts b/src/contracts/flutter/flutterToolContracts.ts
new file mode 100644
index 000000000..9a663d492
--- /dev/null
+++ b/src/contracts/flutter/flutterToolContracts.ts
@@ -0,0 +1,45 @@
+import {
+ flutterInputSchemas,
+ flutterResultSchemas,
+} from "../../domain/flutter/flutterBuildAnalysis.js";
+import type { ToolContract } from "../toolContractTypes.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+
+/** Flutter build identification by pure APK parsing. */
+export const FLUTTER_TOOL_CONTRACTS = [
+ {
+ name: "identify_flutter_build",
+ ...toolContractMetadata("identify_flutter_build"),
+ description:
+ "Identify a Flutter app's build facts by pure parsing: the Dart VM snapshot hash from every lib/<abi>/libapp.so AOT section (vm and isolate, cross-checked), per-ABI library digests, the engine library's GNU build-id, and any labeled Dart version or toolchain strings libflutter.so carries. The snapshot hash is the artifact that maps to a Dart SDK release through an external dataset; REA performs no lookup. No engine, no execution, no external tools.",
+ kind: "flutter-provider",
+ inputSchema: flutterInputSchemas.identify_flutter_build,
+ outputSchema: evidenceResultOf(flutterResultSchemas.identify_flutter_build),
+ examples: [
+ {
+ title: "Identify a Flutter build",
+ input: { path: "/targets/Example.apk" },
+ },
+ ],
+ },
+ {
+ name: "inspect_dart_aot",
+ ...toolContractMetadata("inspect_dart_aot"),
+ description:
+ "Inspect one ABI's Dart AOT snapshot inside an APK: the four snapshot symbols located through the ELF dynamic symbol table with their offsets, sizes, and section headers (magic, kind, length), the snapshot hash, and a bounded string-pool projection from the isolate data section (package: source URIs, dart: SDK URIs, identifier-like tokens) exposing the app's dependency structure. String-pool entries are byte-pattern observations, not deserialized cluster semantics; typed class and function recovery needs an SDK-specific parser. No engine, no execution.",
+ kind: "flutter-provider",
+ inputSchema: flutterInputSchemas.inspect_dart_aot,
+ outputSchema: evidenceResultOf(flutterResultSchemas.inspect_dart_aot),
+ examples: [
+ {
+ title: "Inspect the preferred ABI's AOT snapshot",
+ input: { path: "/targets/Example.apk" },
+ },
+ {
+ title: "Inspect one ABI explicitly",
+ input: { path: "/targets/Example.apk", abi: "arm64-v8a" },
+ },
+ ],
+ },
+] as const satisfies readonly ToolContract[];
diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts
index 832660d04..0ba2ca321 100644
--- a/src/contracts/toolContractTypes.ts
+++ b/src/contracts/toolContractTypes.ts
@@ -26,6 +26,7 @@ export const TOOL_KINDS = [
"managed-provider",
"android-provider",
"apktool-provider",
+ "flutter-provider",
"jeb-provider",
"adb-provider",
"firmware-provider",
diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts
index fb0b7d660..8725f3040 100644
--- a/src/contracts/toolContracts.ts
+++ b/src/contracts/toolContracts.ts
@@ -9,6 +9,7 @@ import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";
import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";
import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";
import { APKTOOL_TOOL_CONTRACTS } from "./apktool/apktoolToolContracts.js";
+import { FLUTTER_TOOL_CONTRACTS } from "./flutter/flutterToolContracts.js";
import { JEB_TOOL_CONTRACTS } from "./jeb/jebToolContracts.js";
import { ADB_TOOL_CONTRACTS } from "./adb/adbToolContracts.js";
import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managed/managedWorkflowToolContracts.js";
@@ -39,6 +40,7 @@ export const TOOL_CONTRACTS = [
...MANAGED_TOOL_CONTRACTS,
...ANDROID_TOOL_CONTRACTS,
...APKTOOL_TOOL_CONTRACTS,
+ ...FLUTTER_TOOL_CONTRACTS,
...JEB_TOOL_CONTRACTS,
...ADB_TOOL_CONTRACTS,
...FIRMWARE_TOOL_CONTRACTS,
diff --git a/src/contracts/toolEffects.test.ts b/src/contracts/toolEffects.test.ts
index bc9632740..151c7d5f4 100644
--- a/src/contracts/toolEffects.test.ts
+++ b/src/contracts/toolEffects.test.ts
@@ -27,6 +27,9 @@ const EXECUTION_WORDING_EXCEPTIONS: Readonly<Record<string, string>> = {
"decodes bytecode in REA's bundled worker without executing it",
inspect_wasm_artifact:
"WABT validates and decompiles the module without executing it",
+ identify_flutter_build:
+ "identifies the build through execution-free APK parsing",
+ inspect_dart_aot: "inspects snapshot bytes without executing them",
inspect_analysis_view:
"reports retained WASM execution/network states without performing execution",
inspect_managed_artifact: "reads metadata without executing target code",
diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.ts
index 8169e10e9..11a268c0e 100644
--- a/src/contracts/toolEffects.ts
+++ b/src/contracts/toolEffects.ts
@@ -167,6 +167,14 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
launchesProcess: true,
writesFilesystem: true,
}),
+ identify_flutter_build: effects({
+ mutatesSession: true,
+ writesFilesystem: true,
+ }),
+ inspect_dart_aot: effects({
+ mutatesSession: true,
+ writesFilesystem: true,
+ }),
inspect_apktool_client: effects({
mutatesSession: true,
launchesProcess: true,
diff --git a/src/domain/flutter/flutterBuildAnalysis.ts b/src/domain/flutter/flutterBuildAnalysis.ts
new file mode 100644
index 000000000..068149f68
--- /dev/null
+++ b/src/domain/flutter/flutterBuildAnalysis.ts
@@ -0,0 +1,173 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { digestSchema } from "../digests.js";
+
+/**
+ * Caller intent for Flutter build identification. This family is pure
+ * parsing: it reads an APK's `lib/<abi>/libapp.so` and `libflutter.so`
+ * directly and runs no engine, tool, or device.
+ */
+export const flutterInputSchemas = {
+ identify_flutter_build: z.strictObject({
+ path: localPathStringSchema.describe("Local APK file to inspect"),
+ }),
+ inspect_dart_aot: z.strictObject({
+ path: localPathStringSchema.describe(
+ "Local APK file carrying a Flutter AOT payload",
+ ),
+ abi: z
+ .string()
+ .min(2)
+ .max(16)
+ .regex(
+ /^[a-z0-9_\x2d]+$/u,
+ "ABI name as it appears under lib/, e.g. arm64-v8a",
+ )
+ .optional()
+ .describe(
+ "ABI to inspect; defaults to arm64-v8a, x86_64, x86, armeabi-v7a, then remaining ABIs alphabetically",
+ ),
+ }),
+} as const;
+
+/** Supported Flutter-backed operations. */
+export type FlutterOperation = keyof typeof flutterInputSchemas;
+/** Validated Flutter requests carry their selected operation. */
+export type FlutterRequest = {
+ [Name in FlutterOperation]: {
+ operation: Name;
+ input: z.infer<(typeof flutterInputSchemas)[Name]>;
+ };
+}[FlutterOperation];
+
+/** Validate operation and input together so their types remain correlated. */
+export const flutterRequestSchema = z.discriminatedUnion("operation", [
+ z.strictObject({
+ operation: z.literal("identify_flutter_build"),
+ input: flutterInputSchemas.identify_flutter_build,
+ }),
+ z.strictObject({
+ operation: z.literal("inspect_dart_aot"),
+ input: flutterInputSchemas.inspect_dart_aot,
+ }),
+]);
+
+/** One hardware ABI's Flutter payload inside the APK. */
+export const flutterResultSchemas = {
+ identify_flutter_build: z.strictObject({
+ target: z.strictObject({
+ path: localPathStringSchema,
+ bytes: z.number().int().nonnegative(),
+ sha256: digestSchema,
+ }),
+ flutter_detected: z.boolean(),
+ abis: z.array(
+ z.strictObject({
+ abi: z.string().min(1),
+ libapp: z.strictObject({
+ present: z.boolean(),
+ bytes: z.number().int().nonnegative().nullable(),
+ sha256: digestSchema.nullable(),
+ /** Supported ELF header with table extents inside the library; table contents are not validated. */
+ elf_header_valid: z.boolean().nullable(),
+ /** Number of Dart snapshot sections found (vm + isolate). */
+ snapshot_hash_sources: z.number().int().nonnegative(),
+ /** Distinct hashes found; more than one means the sections disagree. */
+ snapshot_hash_candidates: z.array(
+ z.string().regex(/^[0-9a-f]{32}$/u),
+ ),
+ /** The single hash when every snapshot section agrees. */
+ snapshot_hash: z
+ .string()
+ .regex(/^[0-9a-f]{32}$/u)
+ .nullable(),
+ }),
+ libflutter: z.strictObject({
+ present: z.boolean(),
+ bytes: z.number().int().nonnegative().nullable(),
+ sha256: digestSchema.nullable(),
+ build_id: z
+ .string()
+ .regex(/^[0-9a-f]{8,128}$/u)
+ .nullable()
+ .describe(
+ "The single GNU build ID when ELF note coverage is complete and unambiguous",
+ ),
+ build_id_candidates: z
+ .array(z.string().regex(/^[0-9a-f]{8,128}$/u))
+ .max(64)
+ .describe(
+ "Distinct GNU build IDs observed in ELF-owned note ranges; conflicting IDs remain explicit",
+ ),
+ dart_version: z
+ .string()
+ .nullable()
+ .describe(
+ "Labeled 'Dart VM version' string, when a build carries one",
+ ),
+ toolchain_lines: z.array(z.string().min(1)),
+ /** Dart labels omitted by grammar or single-version projection bounds. */
+ dart_version_capped: z.boolean(),
+ /** Toolchain labels omitted by grammar or projection bounds. */
+ toolchain_capped: z.boolean(),
+ }),
+ }),
+ ),
+ coverage: z.enum(["complete", "partial"]),
+ }),
+ inspect_dart_aot: z.strictObject({
+ target: z.strictObject({
+ path: localPathStringSchema,
+ bytes: z.number().int().nonnegative(),
+ sha256: digestSchema,
+ }),
+ abi: z.string().min(1),
+ libapp: z.strictObject({
+ coverage: z
+ .enum(["complete", "partial"])
+ .describe(
+ "Coverage of ELF symbols, independent data headers, AOT kind, extents and agreeing hashes",
+ ),
+ bytes: z.number().int().nonnegative(),
+ sha256: digestSchema,
+ snapshot_hash: z
+ .string()
+ .regex(/^[0-9a-f]{32}$/u)
+ .nullable(),
+ /** Distinct hashes found; more than one means the sections disagree. */
+ snapshot_hash_candidates: z.array(z.string().regex(/^[0-9a-f]{32}$/u)),
+ /** Distinct exported data headers with a valid hash at the header's fixed offset. */
+ snapshot_hash_sources: z.number().int().nonnegative(),
+ /** Snapshot symbols read from the dynamic symbol table. */
+ sections: z.array(
+ z.strictObject({
+ name: z.string().min(1),
+ offset: z.number().int().nonnegative(),
+ size: z.number().int().nonnegative(),
+ magic_valid: z.boolean(),
+ kind: z.number().int().nonnegative().nullable(),
+ /** Raw declared snapshot length, excluding the four magic bytes. */
+ header_length: z.number().int().nonnegative().nullable(),
+ }),
+ ),
+ }),
+ string_pool: z.strictObject({
+ coverage: z
+ .enum(["complete", "partial"])
+ .describe(
+ "Coverage of the bounded printable-run projection; independent of snapshot header validity",
+ ),
+ /** Distinct package: source URIs, sorted, bounded. */
+ package_uris: z.array(z.string().min(1)),
+ package_uri_count_at_least: z.number().int().nonnegative(),
+ /** Distinct dart: SDK URIs, sorted, bounded. */
+ dart_uris: z.array(z.string().min(1)),
+ dart_uri_count_at_least: z.number().int().nonnegative(),
+ /** Identifier-like tokens, bounded; includes incidental matches. */
+ class_like_tokens: z.array(z.string().min(1)),
+ class_like_token_count_at_least: z.number().int().nonnegative(),
+ printable_run_count: z.number().int().nonnegative(),
+ }),
+ coverage: z.enum(["complete", "partial"]),
+ }),
+} as const;
diff --git a/src/filesystem/RegularFile.ts b/src/filesystem/RegularFile.ts
index a5c2391cf..a3037c728 100644
--- a/src/filesystem/RegularFile.ts
+++ b/src/filesystem/RegularFile.ts
@@ -95,5 +95,8 @@ export const sameRegularFileState = (
expected.ino === observed.ino &&
expected.size === observed.size &&
expected.mode === observed.mode &&
- expected.mtimeMs === observed.mtimeMs &&
- expected.ctimeMs === observed.ctimeMs;
+ ("mtimeNs" in expected && "mtimeNs" in observed
+ ? expected.mtimeNs === observed.mtimeNs &&
+ expected.ctimeNs === observed.ctimeNs
+ : expected.mtimeMs === observed.mtimeMs &&
+ expected.ctimeMs === observed.ctimeMs);
diff --git a/src/flutter/DartElf.test.ts b/src/flutter/DartElf.test.ts
new file mode 100644
index 000000000..b2b777de3
--- /dev/null
+++ b/src/flutter/DartElf.test.ts
@@ -0,0 +1,228 @@
+import { describe, expect, it } from "vitest";
+
+import { readElfSymbols, readSnapshotHeader } from "./DartElf.js";
+import {
+ REFERENCE_HASH,
+ buildElf64Image,
+ buildStrippedElf64Image,
+ snapshotSection,
+} from "./FlutterBuild.fixture.js";
+
+const readElfSymbol = async (bytes: Buffer, name: string) => {
+ const result = await readElfSymbols(bytes, [name]);
+ return result.symbols[0] === undefined
+ ? { failure: result.failures[0]! }
+ : { symbol: result.symbols[0] };
+};
+
+/**
+ * Build a synthetic ELF64 little-endian image with one PT_LOAD segment
+ * and a dynamic symbol table naming the Dart snapshot sections. This keeps
+ * the golden tests self-contained instead of reading the author's disk.
+ */
+const GALLERY_HASH = REFERENCE_HASH;
+
+const imageWithSections = (): Buffer => {
+ const elf = buildElf64Image([
+ { name: "_kDartVmSnapshotData", value: 0x400, size: 52 },
+ { name: "_kDartIsolateSnapshotData", value: 0x800, size: 52 },
+ ]);
+ const section = snapshotSection(GALLERY_HASH);
+ return Buffer.concat([
+ elf,
+ Buffer.alloc(0x400 - elf.length),
+ section,
+ Buffer.alloc(0x800 - 0x400 - section.length),
+ section,
+ ]);
+};
+
+/** The same layout without section headers: symbols live in PT_DYNAMIC. */
+const strippedImageWithSections = (): Buffer => {
+ const elf = buildStrippedElf64Image([
+ { name: "_kDartVmSnapshotData", value: 0x400, size: 52 },
+ { name: "_kDartIsolateSnapshotData", value: 0x800, size: 52 },
+ ]);
+ const section = snapshotSection(GALLERY_HASH);
+ return Buffer.concat([
+ elf,
+ Buffer.alloc(0x400 - elf.length),
+ section,
+ Buffer.alloc(0x800 - 0x400 - section.length),
+ section,
+ ]);
+};
+
+describe("readElfSymbol", () => {
+ it("locates snapshot symbols in a synthetic ELF64 image", async () => {
+ const image = imageWithSections();
+ const isolateData = await readElfSymbol(image, "_kDartIsolateSnapshotData");
+ if ("failure" in isolateData) throw new Error(isolateData.failure.reason);
+ expect(isolateData.symbol.offset).toBe(0x800);
+ expect(isolateData.symbol.size).toBe(52);
+ const header = readSnapshotHeader(image, isolateData.symbol.offset);
+ expect(header.magicValid).toBe(true);
+ expect(header.kind).toBe(3);
+ });
+
+ it("refuses a non-ELF image instead of guessing", async () => {
+ const result = await readElfSymbol(Buffer.from("not an elf at all"), "x");
+ expect("failure" in result && result.failure.reason).toBe(
+ "not an ELF image",
+ );
+ });
+
+ it("refuses an unknown symbol", async () => {
+ const result = await readElfSymbol(buildElf64Image([]), "_kDartAbsent");
+ expect("failure" in result).toBe(true);
+ });
+
+ it("locates snapshot symbols in a section-stripped ET_DYN image", async () => {
+ const image = strippedImageWithSections();
+ const isolateData = await readElfSymbol(image, "_kDartIsolateSnapshotData");
+ if ("failure" in isolateData) throw new Error(isolateData.failure.reason);
+ expect(isolateData.symbol.offset).toBe(0x800);
+ expect(isolateData.symbol.size).toBe(52);
+ const header = readSnapshotHeader(image, isolateData.symbol.offset);
+ expect(header.magicValid).toBe(true);
+ expect(header.kind).toBe(3);
+ });
+
+ it("refuses a stripped image whose PT_DYNAMIC carries no symbols", async () => {
+ // Drop the PT_DYNAMIC program header by leaving only PT_LOAD.
+ const image = strippedImageWithSections();
+ image.writeUInt16LE(1, 0x38); // e_phnum
+ const result = await readElfSymbol(image, "_kDartVmSnapshotData");
+ expect("failure" in result && result.failure.reason).toBe(
+ "symbol _kDartVmSnapshotData is not in the dynamic symbol table",
+ );
+ });
+
+ it("keeps refusing a stripped image that is not ET_DYN", async () => {
+ const image = buildStrippedElf64Image([]);
+ image.writeUInt16LE(1, 0x10); // ET_REL: the dynamic fallback must not apply
+ const result = await readElfSymbol(image, "_kDartVmSnapshotData");
+ expect("failure" in result && result.failure.reason).toBe(
+ "ELF section header table is missing or out of bounds",
+ );
+ });
+
+ it.each([false, true])(
+ "ignores undefined entries with loadable values (stripped: %s)",
+ async (stripped) => {
+ const image = stripped
+ ? strippedImageWithSections()
+ : imageWithSections();
+ const table = stripped
+ ? Number(
+ image.readBigUInt64LE(
+ Number(image.readBigUInt64LE(64 + 56 + 8)) + 8,
+ ),
+ )
+ : Number(
+ image.readBigUInt64LE(
+ Number(image.readBigUInt64LE(0x28)) + 64 + 0x18,
+ ),
+ );
+ for (const sectionIndex of [
+ 0,
+ 0xfff2,
+ 0xffff,
+ ...(stripped ? [] : [0x1234]),
+ ]) {
+ image.writeUInt16LE(sectionIndex, table + 6);
+ expect(
+ await readElfSymbol(image, "_kDartVmSnapshotData"),
+ ).toHaveProperty("failure");
+ expect(
+ await readElfSymbol(image, "_kDartIsolateSnapshotData"),
+ ).toMatchObject({ symbol: { offset: 0x800, size: 52 } });
+ }
+ },
+ );
+});
+
+describe("ELF symbol-table ownership", () => {
+ it.each([false, true])(
+ "keeps a symbol terminator inside dynstr (stripped: %s)",
+ async (stripped) => {
+ const image = stripped
+ ? strippedImageWithSections()
+ : imageWithSections();
+ const name = "_kDartVmSnapshotData";
+ if (stripped) {
+ const dynamic = Number(image.readBigUInt64LE(64 + 56 + 8));
+ image.writeBigUInt64LE(BigInt(name.length + 1), dynamic + 2 * 16 + 8); // DT_STRSZ, leading NUL included.
+ } else {
+ const shoff = Number(image.readBigUInt64LE(0x28));
+ image.writeBigUInt64LE(BigInt(name.length + 1), shoff + 2 * 64 + 0x20);
+ }
+ expect((await readElfSymbols(image, [name])).symbols).toEqual([]);
+ },
+ );
+
+ it("uses DT_HASH's count when strings precede symbols instead of reading following payload", async () => {
+ const image = strippedImageWithSections();
+ const dynamic = Number(image.readBigUInt64LE(64 + 56 + 8));
+ const symbols = Number(image.readBigUInt64LE(dynamic + 8));
+ image.copy(image, 0x300, symbols, symbols + 48);
+ image.writeBigUInt64LE(0x300n, dynamic + 8);
+ const hash = Number(image.readBigUInt64LE(dynamic + 4 * 16 + 8));
+ image.writeUInt32LE(1, hash + 4); // Only the VM entry belongs to dynsym.
+ const result = await readElfSymbols(image, [
+ "_kDartVmSnapshotData",
+ "_kDartIsolateSnapshotData",
+ ]);
+ expect(result.symbols).toEqual([
+ { name: "_kDartVmSnapshotData", offset: 0x400, size: 52 },
+ ]);
+ expect(result.failures).toContainEqual({
+ reason:
+ "symbol _kDartIsolateSnapshotData is not in the dynamic symbol table",
+ });
+ image.writeBigUInt64LE(0x60000001n, dynamic + 4 * 16); // No recognized count table.
+ expect(
+ (await readElfSymbols(image, ["_kDartVmSnapshotData"])).failures,
+ ).toContainEqual({
+ reason: "Stripped ELF has no DT_HASH or DT_GNU_HASH symbol count",
+ });
+ });
+
+ it("bounds GNU hash chains and resolves both requested symbols in one inventory", async () => {
+ const image = strippedImageWithSections();
+ const dynamic = Number(image.readBigUInt64LE(64 + 56 + 8));
+ const hash = Number(image.readBigUInt64LE(dynamic + 4 * 16 + 8));
+ image.writeBigUInt64LE(0x6ffffef5n, dynamic + 4 * 16);
+ image.fill(0, hash, hash + 32);
+ image.writeUInt32LE(1, hash); // nbuckets
+ image.writeUInt32LE(1, hash + 4); // symoffset
+ image.writeUInt32LE(1, hash + 8); // bloom words
+ image.writeUInt32LE(1, hash + 24); // bucket: last chain begins at symbol 1
+ image.writeUInt32LE(1, hash + 28); // chain terminator; count is 2
+ const names = ["_kDartVmSnapshotData", "_kDartIsolateSnapshotData"];
+ expect(
+ (await readElfSymbols(image, names)).symbols.map((symbol) => symbol.name),
+ ).toEqual(names);
+ image.writeUInt32LE(0xffffffff, hash + 24);
+ expect((await readElfSymbols(image, names)).symbols).toEqual([]);
+ });
+});
+
+describe("readSnapshotHeader", () => {
+ it("reads a synthesized data header", async () => {
+ const header = readSnapshotHeader(snapshotSection(GALLERY_HASH), 0);
+ expect(header.magicValid).toBe(true);
+ expect(header.kind).toBe(3);
+ });
+
+ it("reports nulls for sections without the data magic", async () => {
+ const header = readSnapshotHeader(Buffer.from([0, 0, 0, 0, 0, 0, 0, 0]), 0);
+ expect(header).toEqual({
+ magicValid: false,
+ kind: null,
+ headerLength: null,
+ hash: null,
+ complete: false,
+ });
+ });
+});
diff --git a/src/flutter/DartElf.ts b/src/flutter/DartElf.ts
new file mode 100644
index 000000000..48285737d
--- /dev/null
+++ b/src/flutter/DartElf.ts
@@ -0,0 +1,506 @@
+import { Buffer } from "node:buffer";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import {
+ SNAPSHOT_HASH_LENGTH,
+ SNAPSHOT_HASH_OFFSET,
+ SNAPSHOT_HASH_PATTERN,
+} from "./FlutterPayloadScan.js";
+
+/** Bounds-checked little-endian reader over one loaded buffer. */
+class BoundedReader {
+ constructor(private readonly bytes: Buffer) {}
+
+ u8(offset: number): number | null {
+ return offset < this.bytes.length ? this.bytes.readUInt8(offset) : null;
+ }
+
+ u16(offset: number): number | null {
+ return offset + 2 <= this.bytes.length
+ ? this.bytes.readUInt16LE(offset)
+ : null;
+ }
+
+ u32(offset: number): number | null {
+ return offset + 4 <= this.bytes.length
+ ? this.bytes.readUInt32LE(offset)
+ : null;
+ }
+
+ u64(offset: number): number | null {
+ const low = this.u32(offset);
+ const high = this.u32(offset + 4);
+ if (low === null || high === null || high > 0x001fffff) return null;
+ return high * 0x1_0000_0000 + low;
+ }
+
+ cString(offset: number, tableEnd: number): string | null {
+ if (offset < 0 || offset >= tableEnd || tableEnd > this.bytes.length)
+ return null;
+ const end = this.bytes
+ .subarray(offset, Math.min(tableEnd, offset + 257))
+ .indexOf(0);
+ return end < 0
+ ? null
+ : this.bytes.subarray(offset, offset + end).toString("latin1");
+ }
+}
+
+export interface ElfSymbol {
+ readonly name: string;
+ /** File offset mapped from the virtual address through PT_LOAD. */
+ readonly offset: number;
+ readonly size: number;
+}
+
+export interface ElfParseFailure {
+ readonly reason: string;
+}
+
+const SHT_DYNSYM = 11;
+const PT_LOAD = 1;
+const PT_DYNAMIC = 2;
+/** Position-independent executable images carry PT_DYNAMIC. */
+const ET_DYN = 3;
+const DT_NULL = 0;
+const DT_STRTAB = 5;
+const DT_SYMTAB = 6;
+const DT_STRSZ = 10;
+const DT_SYMENT = 11;
+
+/** ELF32 needs 52 bytes, ELF64 needs 64; retain at most this prefix. */
+export const ELF_HEADER_MAX_BYTES = 64;
+
+/**
+ * Decode the supported ELF header and validate its table extents against
+ * the complete image size. The buffer may contain only the header prefix;
+ * this does not validate table contents or symbol availability.
+ */
+export const readElfHeader = (
+ bytes: Buffer,
+ totalBytes: number = bytes.length,
+) => {
+ const reader = new BoundedReader(bytes);
+ const magic = reader.u32(0);
+ if (magic !== 0x464c457f) return { failure: { reason: "not an ELF image" } };
+ const elfClass = reader.u8(4);
+ if (elfClass !== 1 && elfClass !== 2)
+ return { failure: { reason: `unsupported ELF class ${String(elfClass)}` } };
+ const is64 = elfClass === 2;
+ const headerBytes = is64 ? ELF_HEADER_MAX_BYTES : 52;
+ if (
+ bytes.length < headerBytes ||
+ !Number.isSafeInteger(totalBytes) ||
+ totalBytes < headerBytes
+ )
+ return { failure: { reason: "ELF header is truncated" } };
+ if (reader.u8(5) !== 1)
+ return { failure: { reason: "unsupported ELF byte order" } };
+ if (reader.u8(6) !== 1 || reader.u32(0x14) !== 1)
+ return { failure: { reason: "unsupported ELF version" } };
+ if (reader.u16(is64 ? 0x34 : 0x28) !== headerBytes)
+ return { failure: { reason: "unsupported ELF header size" } };
+ const e_type = reader.u16(0x10);
+ if (e_type !== 1 && e_type !== 2 && e_type !== ET_DYN)
+ return { failure: { reason: "unsupported ELF type" } };
+ const e_shoff = is64 ? reader.u64(0x28) : reader.u32(0x20);
+ const e_shentsize = reader.u16(is64 ? 0x3a : 0x2e);
+ const e_shnum = reader.u16(is64 ? 0x3c : 0x30);
+ const e_phoff = is64 ? reader.u64(0x20) : reader.u32(0x1c);
+ const e_phentsize = reader.u16(is64 ? 0x36 : 0x2a);
+ const e_phnum = reader.u16(is64 ? 0x38 : 0x2c);
+ const tableFits = (
+ offset: number | null,
+ width: number | null,
+ count: number | null,
+ minimumWidth: number,
+ ): boolean =>
+ offset !== null &&
+ width !== null &&
+ count !== null &&
+ offset >= headerBytes &&
+ offset <= totalBytes &&
+ width >= minimumWidth &&
+ count > 0 &&
+ count <= Math.floor((totalBytes - offset) / width);
+ const MIN_SHENT = is64 ? 64 : 40;
+ // Section-stripped ET_DYN images keep their exported symbols reachable
+ // through PT_DYNAMIC instead of section headers; every other shape still
+ // needs a usable section header table.
+ // A nonzero shoff with shnum=0 uses extended numbering, which this
+ // parser does not support; it must not masquerade as a stripped image.
+ const dynamicFallback = e_type === ET_DYN && e_shoff === 0 && e_shnum === 0;
+ if (
+ e_shoff === null ||
+ e_shentsize === null ||
+ e_shnum === null ||
+ (!dynamicFallback && !tableFits(e_shoff, e_shentsize, e_shnum, MIN_SHENT))
+ )
+ return {
+ failure: {
+ reason: "ELF section header table is missing or out of bounds",
+ },
+ };
+ const MIN_PHENT = is64 ? 56 : 32;
+ if (
+ e_phoff === null ||
+ e_phentsize === null ||
+ e_phnum === null ||
+ e_phnum === 0xffff ||
+ !tableFits(e_phoff, e_phentsize, e_phnum, MIN_PHENT)
+ )
+ return {
+ failure: {
+ reason: "ELF program header table is missing or out of bounds",
+ },
+ };
+
+ return {
+ header: {
+ is64,
+ dynamicFallback,
+ e_shoff,
+ e_shentsize,
+ e_shnum,
+ e_phoff,
+ e_phentsize,
+ e_phnum,
+ },
+ };
+};
+
+export interface ElfSymbolInventory {
+ readonly symbols: readonly ElfSymbol[];
+ readonly failures: readonly ElfParseFailure[];
+}
+
+/** Decode the ELF tables once and resolve only the requested definitions. */
+export const readElfSymbols = async (
+ bytes: Buffer,
+ symbolNames: readonly string[],
+ signal?: AbortSignal,
+): Promise<ElfSymbolInventory> => {
+ signal?.throwIfAborted();
+ const failure = (reason: string): ElfSymbolInventory => ({
+ symbols: [],
+ failures: [{ reason }],
+ });
+ const parsed = readElfHeader(bytes);
+ if (parsed.failure !== undefined) return failure(parsed.failure.reason);
+ const {
+ is64,
+ dynamicFallback,
+ e_shoff,
+ e_shentsize,
+ e_shnum,
+ e_phoff,
+ e_phentsize,
+ e_phnum,
+ } = parsed.header;
+ const reader = new BoundedReader(bytes);
+ const entrySize = is64 ? 24 : 16;
+ const segments: { vaddr: number; offset: number; filesz: number }[] = [];
+ let dynamicSegment: { offset: number; filesz: number } | null = null;
+ for (let index = 0; index < e_phnum; index += 1) {
+ if (index % 4096 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const base = e_phoff + index * e_phentsize;
+ const type = reader.u32(base);
+ if (type !== PT_LOAD && type !== PT_DYNAMIC) continue;
+ const vaddr = is64 ? reader.u64(base + 0x10) : reader.u32(base + 8);
+ const offset = is64 ? reader.u64(base + 8) : reader.u32(base + 4);
+ const filesz = is64 ? reader.u64(base + 0x20) : reader.u32(base + 0x10);
+ if (
+ vaddr === null ||
+ offset === null ||
+ filesz === null ||
+ offset > bytes.length ||
+ filesz > bytes.length - offset
+ )
+ return failure(`ELF segment ${String(index)} is not file-backed`);
+ if (type === PT_LOAD) segments.push({ vaddr, offset, filesz });
+ else if (dynamicSegment !== null)
+ return failure("Multiple PT_DYNAMIC segments are ambiguous");
+ else dynamicSegment = { offset, filesz };
+ }
+ const toOffset = (vaddr: number, size: number): number | null => {
+ const segment = segments.find(
+ (candidate) =>
+ vaddr >= candidate.vaddr &&
+ vaddr - candidate.vaddr <= candidate.filesz &&
+ size <= candidate.filesz - (vaddr - candidate.vaddr),
+ );
+ return segment === undefined
+ ? null
+ : segment.offset + vaddr - segment.vaddr;
+ };
+ if (segments.length === 0)
+ return failure("ELF image has no PT_LOAD segments");
+ const tables: {
+ offset: number;
+ count: number;
+ stringOffset: number;
+ stringSize: number;
+ }[] = [];
+ if (!dynamicFallback) {
+ for (let index = 0; index < e_shnum; index += 1) {
+ if (index % 4096 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const header = e_shoff + index * e_shentsize;
+ if (reader.u32(header + 4) !== SHT_DYNSYM) continue;
+ const offset = is64
+ ? reader.u64(header + 0x18)
+ : reader.u32(header + 0x10);
+ const size = is64 ? reader.u64(header + 0x20) : reader.u32(header + 0x14);
+ const width = is64
+ ? reader.u64(header + 0x38)
+ : reader.u32(header + 0x24);
+ const link = reader.u32(header + (is64 ? 0x28 : 0x18));
+ if (
+ offset === null ||
+ size === null ||
+ width !== entrySize ||
+ offset > bytes.length ||
+ size > bytes.length - offset ||
+ size % entrySize !== 0
+ )
+ return failure("Dynamic symbol table is malformed");
+ if (link === null || link >= e_shnum)
+ return failure("Dynamic symbol string section link is invalid");
+ const stringHeader = e_shoff + link * e_shentsize;
+ const stringOffset = is64
+ ? reader.u64(stringHeader + 0x18)
+ : reader.u32(stringHeader + 0x10);
+ const stringSize = is64
+ ? reader.u64(stringHeader + 0x20)
+ : reader.u32(stringHeader + 0x14);
+ if (
+ reader.u32(stringHeader + 4) !== 3 ||
+ stringOffset === null ||
+ stringSize === null ||
+ stringOffset > bytes.length ||
+ stringSize > bytes.length - stringOffset
+ )
+ return failure(
+ "Dynamic symbol strings are out of bounds or not a string table",
+ );
+ tables.push({
+ offset,
+ count: size / entrySize,
+ stringOffset,
+ stringSize,
+ });
+ }
+ } else if (dynamicSegment !== null) {
+ const tags = new Map<number, number>();
+ const dynamicEntrySize = is64 ? 16 : 8;
+ let terminated = false;
+ for (
+ let base = dynamicSegment.offset;
+ base + dynamicEntrySize <= dynamicSegment.offset + dynamicSegment.filesz;
+ base += dynamicEntrySize
+ ) {
+ if ((base - dynamicSegment.offset) % (4096 * dynamicEntrySize) === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const tag = is64 ? reader.u64(base) : reader.u32(base);
+ const value = is64 ? reader.u64(base + 8) : reader.u32(base + 4);
+ if (tag === null || value === null)
+ return failure("Dynamic entry is not representable");
+ if (tag === DT_NULL) {
+ terminated = true;
+ break;
+ }
+ if (
+ ![DT_SYMTAB, DT_STRTAB, DT_STRSZ, DT_SYMENT, 4, 0x6ffffef5].includes(
+ tag,
+ )
+ )
+ continue;
+ if (tags.has(tag) && tags.get(tag) !== value)
+ return failure("Conflicting dynamic table tags");
+ tags.set(tag, value);
+ }
+ const sym = tags.get(DT_SYMTAB);
+ const str = tags.get(DT_STRTAB);
+ const stringSize = tags.get(DT_STRSZ);
+ if (
+ !terminated ||
+ sym === undefined ||
+ str === undefined ||
+ stringSize === undefined ||
+ tags.get(DT_SYMENT) !== entrySize
+ )
+ return failure(
+ "Stripped ELF lacks a complete dynamic symbol-table description",
+ );
+ // DT_HASH's nchain is the dynsym count. GNU hash instead records the
+ // first hashed index and bounded buckets/chains. No payload-to-EOF walk.
+ let count: number;
+ const sysv = tags.get(4);
+ const gnu = tags.get(0x6ffffef5);
+ if (sysv !== undefined) {
+ const at = toOffset(sysv, 8);
+ if (at === null) return failure("DT_HASH header is not file-backed");
+ const buckets = reader.u32(at)!;
+ count = reader.u32(at + 4)!;
+ if (toOffset(sysv, 8 + 4 * (buckets + count)) === null)
+ return failure("DT_HASH table is truncated");
+ } else if (gnu !== undefined) {
+ const at = toOffset(gnu, 16);
+ if (at === null) return failure("DT_GNU_HASH header is not file-backed");
+ const buckets = reader.u32(at)!;
+ const firstSymbol = reader.u32(at + 4)!;
+ const bloomWords = reader.u32(at + 8)!;
+ const prefixBytes = 16 + bloomWords * (is64 ? 8 : 4) + buckets * 4;
+ if (
+ buckets === 0 ||
+ bloomWords === 0 ||
+ toOffset(gnu, prefixBytes) === null
+ )
+ return failure("DT_GNU_HASH buckets are malformed");
+ let last = 0;
+ const bucketsAt = at + 16 + bloomWords * (is64 ? 8 : 4);
+ for (let index = 0; index < buckets; index += 1) {
+ if (index % 4096 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const value = reader.u32(bucketsAt + index * 4)!;
+ if (value !== 0 && value < firstSymbol)
+ return failure("DT_GNU_HASH bucket precedes its first symbol");
+ last = Math.max(last, value);
+ }
+ count = firstSymbol;
+ if (last !== 0) {
+ let index = last;
+ while (true) {
+ if ((index - last) % 4096 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const span = prefixBytes + (index - firstSymbol + 1) * 4;
+ if (toOffset(gnu, span) === null)
+ return failure("DT_GNU_HASH chain is unterminated");
+ const chain = reader.u32(at + span - 4)!;
+ index += 1;
+ if ((chain & 1) !== 0) {
+ count = index;
+ break;
+ }
+ }
+ }
+ } else
+ return failure("Stripped ELF has no DT_HASH or DT_GNU_HASH symbol count");
+ const offset = toOffset(sym, count * entrySize);
+ const stringOffset = toOffset(str, stringSize);
+ if (offset === null || stringOffset === null)
+ return failure("Dynamic symbol or string table is not file-backed");
+ tables.push({ offset, count, stringOffset, stringSize });
+ }
+ const wanted = new Set(symbolNames);
+ const symbols = new Map<string, ElfSymbol>();
+ const ambiguous = new Set<string>();
+ const failures: ElfParseFailure[] = [];
+ for (const table of tables) {
+ for (let index = 0; index < table.count; index += 1) {
+ if (index % 4096 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const base = table.offset + index * entrySize;
+ const nameOffset = reader.u32(base)!;
+ const sectionIndex = reader.u16(base + (is64 ? 6 : 14))!;
+ const defined =
+ sectionIndex === 0xfff1 ||
+ (sectionIndex > 0 &&
+ sectionIndex < 0xff00 &&
+ (dynamicFallback || sectionIndex < e_shnum));
+ if (!defined || nameOffset >= table.stringSize) continue;
+ const name = reader.cString(
+ table.stringOffset + nameOffset,
+ table.stringOffset + table.stringSize,
+ );
+ if (name === null || !wanted.has(name)) continue;
+ const value = is64 ? reader.u64(base + 8) : reader.u32(base + 4);
+ const size = is64 ? reader.u64(base + 16) : reader.u32(base + 8);
+ if (value === null || size === null) {
+ failures.push({ reason: `Symbol ${name} has unrepresentable bounds` });
+ continue;
+ }
+ const offset = toOffset(value, size);
+ if (offset === null) {
+ failures.push({ reason: `Symbol ${name} has no file-backed range` });
+ continue;
+ }
+ const previous = symbols.get(name);
+ if (
+ previous !== undefined &&
+ (previous.offset !== offset || previous.size !== size)
+ )
+ ambiguous.add(name);
+ else symbols.set(name, { name, offset, size });
+ }
+ }
+ for (const name of ambiguous) {
+ symbols.delete(name);
+ failures.push({ reason: `Symbol ${name} has conflicting definitions` });
+ }
+ for (const name of wanted)
+ if (!symbols.has(name))
+ failures.push({
+ reason: `symbol ${name} is not in the dynamic symbol table`,
+ });
+ return { symbols: [...symbols.values()], failures };
+};
+
+/** Read one Dart snapshot section header from its file offset. */
+export const readSnapshotHeader = (
+ bytes: Buffer,
+ offset: number,
+): {
+ magicValid: boolean;
+ kind: number | null;
+ headerLength: number | null;
+ hash: string | null;
+ complete: boolean;
+} => {
+ const reader = new BoundedReader(bytes);
+ // The Dart magic bytes f5 f5 dc dc read little-endian. Kind and length
+ // fields are only meaningful in data-section headers; sections without
+ // the magic (instructions carry a different layout) report nulls.
+ const magic = reader.u32(offset);
+ if (magic !== 0xdcdcf5f5)
+ return {
+ magicValid: false,
+ kind: null,
+ headerLength: null,
+ hash: null,
+ complete: false,
+ };
+ const headerLength = reader.u64(offset + 4);
+ const kind = reader.u64(offset + 12);
+ const candidate = bytes
+ .subarray(
+ offset + SNAPSHOT_HASH_OFFSET,
+ offset + SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH,
+ )
+ .toString("latin1");
+ const hash = SNAPSHOT_HASH_PATTERN.test(candidate) ? candidate : null;
+ // Dart's stored length excludes the four magic bytes and includes the
+ // 20-byte fixed header and the version hash. Aligned data may follow it
+ // inside the exported symbol, but the serialized snapshot must fit.
+ // Kind 3 is FullAOT in the supported Dart 2.14 layout; enum values change
+ // across SDK versions, so other kinds remain uninterpreted observations.
+ const complete =
+ headerLength !== null &&
+ headerLength >= SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH - 4 &&
+ headerLength <= bytes.length - offset - 4 &&
+ kind === 3 &&
+ hash !== null;
+ return { magicValid: true, kind, headerLength, hash, complete };
+};
diff --git a/src/flutter/ElfBuildId.ts b/src/flutter/ElfBuildId.ts
new file mode 100644
index 000000000..3c04d0473
--- /dev/null
+++ b/src/flutter/ElfBuildId.ts
@@ -0,0 +1,158 @@
+import type { FileHandle } from "node:fs/promises";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import {
+ readElfHeader,
+ ELF_HEADER_MAX_BYTES,
+ type ElfParseFailure,
+} from "./DartElf.js";
+
+const MAX_METADATA_BYTES = 8 * 1024 * 1024;
+const MAX_BUILD_IDS = 64;
+
+export interface ElfBuildIds {
+ readonly candidates: readonly string[];
+ readonly failures: readonly ElfParseFailure[];
+}
+
+/** Read only ELF-declared PT_NOTE/SHT_NOTE ranges from one owned engine image. */
+export const readElfBuildIds = async (
+ file: FileHandle,
+ totalBytes: number,
+ signal: AbortSignal | undefined,
+): Promise<ElfBuildIds> => {
+ const candidates = new Set<string>();
+ const failure = (reason: string): ElfBuildIds => ({
+ candidates: [...candidates],
+ failures: [{ reason }],
+ });
+ let examined = 0;
+ const read = async (offset: number, size: number): Promise<Buffer | null> => {
+ signal?.throwIfAborted();
+ if (
+ !Number.isSafeInteger(offset) ||
+ !Number.isSafeInteger(size) ||
+ offset < 0 ||
+ size < 0 ||
+ size > totalBytes - offset ||
+ size > MAX_METADATA_BYTES - examined
+ )
+ return null;
+ examined += size;
+ const bytes = Buffer.alloc(size);
+ let copied = 0;
+ while (copied < size) {
+ const result = await file.read(
+ bytes,
+ copied,
+ size - copied,
+ offset + copied,
+ );
+ signal?.throwIfAborted();
+ if (result.bytesRead === 0) return null;
+ copied += result.bytesRead;
+ }
+ return bytes;
+ };
+ const prefix = await read(0, Math.min(totalBytes, ELF_HEADER_MAX_BYTES));
+ if (prefix === null) return failure("ELF header could not be read");
+ const parsed = readElfHeader(prefix, totalBytes);
+ if (parsed.failure !== undefined) return failure(parsed.failure.reason);
+ const h = parsed.header;
+ const ranges = new Map<string, { offset: number; size: number }>();
+ for (const table of [
+ {
+ offset: h.e_phoff,
+ width: h.e_phentsize,
+ count: h.e_phnum,
+ program: true,
+ },
+ {
+ offset: h.e_shoff,
+ width: h.e_shentsize,
+ count: h.e_shnum,
+ program: false,
+ },
+ ]) {
+ const bytes = await read(table.offset, table.width * table.count);
+ if (bytes === null)
+ return failure(
+ "ELF note tables exceed the 8 MiB metadata budget or are truncated",
+ );
+ for (let index = 0; index < table.count; index += 1) {
+ if (index % 4096 === 0) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ }
+ const base = index * table.width;
+ if (
+ bytes.readUInt32LE(base + (table.program ? 0 : 4)) !==
+ (table.program ? 4 : 7)
+ )
+ continue;
+ const offsetAt =
+ base + (table.program ? (h.is64 ? 8 : 4) : h.is64 ? 0x18 : 0x10);
+ const sizeAt =
+ base + (table.program ? (h.is64 ? 0x20 : 0x10) : h.is64 ? 0x20 : 0x14);
+ const offset = h.is64
+ ? Number(bytes.readBigUInt64LE(offsetAt))
+ : bytes.readUInt32LE(offsetAt);
+ const size = h.is64
+ ? Number(bytes.readBigUInt64LE(sizeAt))
+ : bytes.readUInt32LE(sizeAt);
+ if (
+ !Number.isSafeInteger(offset) ||
+ !Number.isSafeInteger(size) ||
+ size > totalBytes - offset
+ )
+ return failure("ELF note range is not file-backed");
+ ranges.set(`${offset}:${size}`, { offset, size });
+ }
+ }
+ const align4 = (value: number): number => Math.ceil(value / 4) * 4;
+ for (const range of ranges.values()) {
+ const notes = await read(range.offset, range.size);
+ if (notes === null)
+ return failure(
+ "ELF notes exceed the 8 MiB metadata budget or are truncated",
+ );
+ let yieldedAt = 0;
+ for (let at = 0; at < notes.length;) {
+ if (at - yieldedAt >= 64 * 1024) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ yieldedAt = at;
+ }
+ if (notes.length - at < 12) {
+ if (notes.subarray(at).some((byte) => byte !== 0))
+ return failure("ELF note header is truncated");
+ break;
+ }
+ const namesz = notes.readUInt32LE(at);
+ const descsz = notes.readUInt32LE(at + 4);
+ const type = notes.readUInt32LE(at + 8);
+ const descriptor = at + 12 + align4(namesz);
+ const end = descriptor + descsz;
+ if (end > notes.length)
+ return failure("ELF note descriptor exceeds its declared note range");
+ if (
+ namesz === 4 &&
+ type === 3 &&
+ notes.subarray(at + 12, at + 16).equals(Buffer.from("GNU\0"))
+ ) {
+ if (descsz < 4 || descsz > 64)
+ return failure(
+ "GNU build-id descriptor exceeds the 4–64 byte projection",
+ );
+ const candidate = notes.subarray(descriptor, end).toString("hex");
+ if (!candidates.has(candidate) && candidates.size === MAX_BUILD_IDS)
+ return failure(
+ "ELF build-id candidates exceed the 64-value evidence budget",
+ );
+ candidates.add(candidate);
+ }
+ at = align4(end);
+ }
+ }
+ signal?.throwIfAborted();
+ return { candidates: [...candidates], failures: [] };
+};
diff --git a/src/flutter/FlutterBuild.fixture.ts b/src/flutter/FlutterBuild.fixture.ts
new file mode 100644
index 000000000..635ea04fb
--- /dev/null
+++ b/src/flutter/FlutterBuild.fixture.ts
@@ -0,0 +1,267 @@
+import { Buffer } from "node:buffer";
+
+/** The reference Gallery snapshot hash for synthetic fixtures. */
+export const REFERENCE_HASH = "65817c30a78bb44c3dc3771876b6010a";
+
+/** A synthetic AOT image with four symbols, two data sections, and a pool. */
+export const aotFixtureImage = (hash: string = REFERENCE_HASH): Buffer => {
+ const elf = buildElf64Image([
+ { name: "_kDartVmSnapshotData", value: 0x1000, size: 52 },
+ { name: "_kDartVmSnapshotInstructions", value: 0x1800, size: 16 },
+ { name: "_kDartIsolateSnapshotData", value: 0x2000, size: 0x600 },
+ { name: "_kDartIsolateSnapshotInstructions", value: 0x2600, size: 16 },
+ ]);
+ const pool = Buffer.concat([
+ Buffer.from(
+ "package:adaptive_breakpoints/src/adaptive_breakpoints.dart\x00",
+ ),
+ Buffer.from("package:animations/src/fade_scale_transition.dart\x00"),
+ Buffer.from("dart:_http\x00dart:_http/crypto.dart\x00"),
+ Buffer.from("AdaptiveBreakpoint\x00FadeScaleTransition\x00"),
+ ]);
+ const vmSection = snapshotSection(hash);
+ const isolateSection = Buffer.concat([
+ snapshotSection(hash),
+ Buffer.from([0]),
+ pool,
+ ]);
+ return Buffer.concat([
+ elf,
+ Buffer.alloc(0x1000 - elf.length),
+ vmSection,
+ Buffer.alloc(0x1800 - 0x1000 - vmSection.length),
+ Buffer.alloc(16),
+ Buffer.alloc(0x2000 - 0x1800 - 16),
+ isolateSection,
+ Buffer.alloc(0x600 - isolateSection.length),
+ Buffer.alloc(16),
+ ]);
+};
+
+export const buildElf64Image = (
+ symbols: ReadonlyArray<{ name: string; value: number; size: number }>,
+): Buffer => {
+ const ELF_HEADER = 64;
+ const PHENT = 56;
+ const PHNUM = 1;
+ const SHENT = 64;
+ const phoff = ELF_HEADER;
+ const shoffAligned = phoff + PHENT * PHNUM;
+ // Place payload data after the three section headers so nothing overlaps.
+ const dynsymOff = shoffAligned + 3 * SHENT + 16;
+ const dynstrOff = dynsymOff + symbols.length * 24;
+ const image = Buffer.alloc(dynstrOff + 256);
+ // ELF header
+ image.writeUInt32LE(0x464c457f, 0);
+ image[4] = 2; // ELFCLASS64
+ image[5] = 1; // little-endian
+ image[6] = 1; // ELF identification version
+ image.writeUInt16LE(3, 0x10);
+ image.writeUInt16LE(0x003e, 0x12); // e_machine x86_64
+ image.writeUInt32LE(1, 0x14); // e_version
+ image.writeUInt16LE(ELF_HEADER, 0x34);
+ image.writeBigUInt64LE(BigInt(phoff), 0x20);
+ image.writeBigUInt64LE(BigInt(shoffAligned), 0x28);
+ image.writeUInt16LE(PHENT, 0x36);
+ image.writeUInt16LE(PHNUM, 0x38);
+ image.writeUInt16LE(SHENT, 0x3a);
+ image.writeUInt16LE(2, 0x3c); // e_shnum: null + dynsym
+ // Program header: one PT_LOAD mapping identity
+ const ph = phoff;
+ image.writeUInt32LE(1, ph); // PT_LOAD
+ image.writeBigUInt64LE(BigInt(0), ph + 8); // offset
+ image.writeBigUInt64LE(BigInt(0), ph + 0x10); // vaddr
+ image.writeBigUInt64LE(
+ BigInt(
+ Math.max(
+ image.length,
+ ...symbols.map((symbol) => symbol.value + symbol.size),
+ ),
+ ),
+ ph + 0x20,
+ ); // p_filesz covers the materialized payload
+ // Section headers
+ const sh = shoffAligned;
+ // null section stays zero
+ const dyn = sh + SHENT;
+ image.writeUInt32LE(11, dyn + 4); // SHT_DYNSYM
+ image.writeBigUInt64LE(BigInt(dynsymOff), dyn + 0x18);
+ image.writeBigUInt64LE(BigInt(symbols.length * 24), dyn + 0x20);
+ image.writeBigUInt64LE(BigInt(24), dyn + 0x38);
+ image.writeUInt32LE(2, dyn + 0x28); // sh_link -> strtab section index
+ // dynstr section header
+ const str = dyn + SHENT;
+ image.writeUInt32LE(3, str + 4); // SHT_STRTAB
+ image.writeBigUInt64LE(BigInt(dynstrOff), str + 0x18);
+ image.writeBigUInt64LE(BigInt(256), str + 0x20);
+ image.writeUInt16LE(3, 0x3c); // e_shnum includes strtab
+ // dynstr: leading NUL then names
+ let strCursor = dynstrOff + 1;
+ const nameOffsets = symbols.map((symbol) => {
+ image.write(symbol.name, strCursor, "latin1");
+ const at = strCursor - dynstrOff;
+ strCursor += symbol.name.length + 1;
+ return at;
+ });
+ // dynsym entries
+ symbols.forEach((symbol, index) => {
+ const base = dynsymOff + index * 24;
+ image.writeUInt32LE(nameOffsets[index]!, base);
+ image.writeBigUInt64LE(BigInt(symbol.value), base + 8);
+ image.writeBigUInt64LE(BigInt(symbol.size), base + 16);
+ image.writeUInt16LE(1, base + 6); // Defined export (not SHN_UNDEF).
+ image[base + 4] = 0x10; // GLOBAL FUNC
+ });
+ return image;
+};
+
+/**
+ * Build a section-stripped ELF64 image (e_shnum 0, ET_DYN) whose exported
+ * symbols are reachable only through the PT_DYNAMIC tag-value pairs, the
+ * way release toolchains ship `libapp.so`.
+ */
+export const buildStrippedElf64Image = (
+ symbols: ReadonlyArray<{ name: string; value: number; size: number }>,
+): Buffer => {
+ const ELF_HEADER = 64;
+ const PHENT = 56;
+ const PHNUM = 2;
+ const dynamicEntry = 16;
+ // DT_SYMTAB, DT_STRTAB, DT_STRSZ, DT_SYMENT, DT_HASH, DT_NULL.
+ const DYNAMIC_ENTRIES = 6;
+ const phoff = ELF_HEADER;
+ const dynamicOff = phoff + PHENT * PHNUM;
+ const dynsymOff = dynamicOff + DYNAMIC_ENTRIES * dynamicEntry;
+ const dynstrOff = dynsymOff + symbols.length * 24;
+ const strtabBytes = 256;
+ const hashOff = dynstrOff + strtabBytes;
+ const image = Buffer.alloc(hashOff + 8 + 4 * (1 + symbols.length));
+ image.writeUInt32LE(1, hashOff);
+ image.writeUInt32LE(symbols.length, hashOff + 4);
+ // ELF header
+ image.writeUInt32LE(0x464c457f, 0);
+ image[4] = 2; // ELFCLASS64
+ image[5] = 1; // little-endian
+ image[6] = 1;
+ image.writeUInt16LE(3, 0x10);
+ image.writeUInt16LE(0x003e, 0x12); // e_machine x86_64
+ image.writeUInt32LE(1, 0x14);
+ image.writeUInt16LE(ELF_HEADER, 0x34);
+ image.writeBigUInt64LE(BigInt(phoff), 0x20);
+ image.writeUInt16LE(PHENT, 0x36);
+ image.writeUInt16LE(PHNUM, 0x38);
+ // e_shoff, e_shentsize, and e_shnum stay zero: no section headers exist.
+ // PT_LOAD identity-maps the file so symbol vaddrs resolve to offsets.
+ const load = phoff;
+ image.writeUInt32LE(1, load);
+ image.writeBigUInt64LE(BigInt(0), load + 8);
+ image.writeBigUInt64LE(BigInt(0), load + 0x10);
+ image.writeBigUInt64LE(
+ BigInt(
+ Math.max(
+ image.length,
+ ...symbols.map((symbol) => symbol.value + symbol.size),
+ ),
+ ),
+ load + 0x20,
+ ); // p_filesz covers fixture symbols
+ // PT_DYNAMIC locates the symbol table for stripped images.
+ const dyn = phoff + PHENT;
+ image.writeUInt32LE(2, dyn);
+ image.writeBigUInt64LE(BigInt(dynamicOff), dyn + 8); // p_offset
+ image.writeBigUInt64LE(BigInt(dynamicOff), dyn + 0x10); // p_vaddr
+ image.writeBigUInt64LE(BigInt(DYNAMIC_ENTRIES * dynamicEntry), dyn + 0x20);
+ const pairs: ReadonlyArray<readonly [number, number]> = [
+ [6, dynsymOff],
+ [5, dynstrOff],
+ [10, strtabBytes],
+ [11, 24],
+ [4, hashOff],
+ ];
+ pairs.forEach(([tag, value], index) => {
+ const base = dynamicOff + index * dynamicEntry;
+ image.writeBigUInt64LE(BigInt(tag), base);
+ image.writeBigUInt64LE(BigInt(value), base + 8);
+ });
+ // The final entry stays zero: DT_NULL terminates the walk.
+ // dynstr: leading NUL then names
+ let strCursor = dynstrOff + 1;
+ const nameOffsets = symbols.map((symbol) => {
+ image.write(symbol.name, strCursor, "latin1");
+ const at = strCursor - dynstrOff;
+ strCursor += symbol.name.length + 1;
+ return at;
+ });
+ symbols.forEach((symbol, index) => {
+ const base = dynsymOff + index * 24;
+ image.writeUInt32LE(nameOffsets[index]!, base);
+ image.writeBigUInt64LE(BigInt(symbol.value), base + 8);
+ image.writeBigUInt64LE(BigInt(symbol.size), base + 16);
+ image.writeUInt16LE(1, base + 6); // Defined even when section headers are stripped.
+ });
+ return image;
+};
+
+/** A minimal Dart snapshot data section carrying a 32-hex hash. */
+export const snapshotSection = (hash: string): Buffer =>
+ Buffer.concat([
+ Buffer.from([
+ 0xf5, 0xf5, 0xdc, 0xdc, 48, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0,
+ ]),
+ Buffer.from(hash, "latin1"),
+ ]);
+
+/** A real ELF container declaring GNU note ownership, with an unrelated payload prefix. */
+export const engineFixtureImage = (options: {
+ readonly notes: Buffer;
+ readonly prefix?: Buffer;
+ readonly labels?: readonly string[];
+ readonly bits?: 32 | 64;
+ readonly ownership?: "program" | "section" | "both";
+}): Buffer => {
+ const is64 = options.bits !== 32;
+ const ownership = options.ownership ?? "program";
+ const program = ownership !== "section";
+ const section = ownership !== "program";
+ const header = is64 ? 64 : 52;
+ const phent = is64 ? 56 : 32;
+ const shent = is64 ? 64 : 40;
+ const noteAt = 0x400;
+ const labels = Buffer.from(`\0${(options.labels ?? []).join("\0")}\0`);
+ const image = Buffer.alloc(noteAt + options.notes.length + labels.length);
+ image.writeUInt32LE(0x464c457f);
+ image[4] = is64 ? 2 : 1;
+ image[5] = 1;
+ image[6] = 1;
+ image.writeUInt16LE(3, 0x10);
+ image.writeUInt32LE(1, 0x14);
+ image.writeUInt16LE(header, is64 ? 0x34 : 0x28);
+ const word = (value: number, offset: number): void => {
+ if (is64) image.writeBigUInt64LE(BigInt(value), offset);
+ else image.writeUInt32LE(value, offset);
+ };
+ word(header, is64 ? 0x20 : 0x1c);
+ image.writeUInt16LE(phent, is64 ? 0x36 : 0x2a);
+ image.writeUInt16LE(program ? 2 : 1, is64 ? 0x38 : 0x2c);
+ image.writeUInt32LE(1, header); // PT_LOAD
+ word(image.length, header + (is64 ? 0x20 : 0x10));
+ if (program) {
+ const ph = header + phent;
+ image.writeUInt32LE(4, ph); // PT_NOTE
+ word(noteAt, ph + (is64 ? 8 : 4));
+ word(options.notes.length, ph + (is64 ? 0x20 : 0x10));
+ }
+ if (section) {
+ word(0x100, is64 ? 0x28 : 0x20);
+ image.writeUInt16LE(shent, is64 ? 0x3a : 0x2e);
+ image.writeUInt16LE(2, is64 ? 0x3c : 0x30);
+ const sh = 0x100 + shent;
+ image.writeUInt32LE(7, sh + 4); // SHT_NOTE
+ word(noteAt, sh + (is64 ? 0x18 : 0x10));
+ word(options.notes.length, sh + (is64 ? 0x20 : 0x14));
+ }
+ options.prefix?.copy(image, 0x300, 0, 0x100);
+ options.notes.copy(image, noteAt);
+ labels.copy(image, noteAt + options.notes.length);
+ return image;
+};
diff --git a/src/flutter/FlutterBuildProvider.ts b/src/flutter/FlutterBuildProvider.ts
new file mode 100644
index 000000000..2c088b2c9
--- /dev/null
+++ b/src/flutter/FlutterBuildProvider.ts
@@ -0,0 +1,1230 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdtemp, open as openFile, rm, stat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+
+import type {
+ ExecutionOptions,
+ ProviderAvailability,
+} from "../application/AnalysisProvider.js";
+import {
+ createAnalysisExecution,
+ type AnalysisExecution,
+} from "../application/AnalysisProvider.js";
+import type { FlutterRequest } from "../domain/flutter/flutterBuildAnalysis.js";
+import {
+ AnalysisAccessDeniedError,
+ AnalysisArtifactChangedError,
+ AnalysisCancelledError,
+ AnalysisInputError,
+ AnalysisResourceConstraintError,
+ AnalysisUnsupportedTargetError,
+} from "../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { err, ok, type Result } from "../domain/result.js";
+import {
+ ArtifactReaderFailure,
+ type ArtifactEntry,
+} from "../artifacts/ArtifactReader.js";
+import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import {
+ openRegularFile,
+ RegularFileAdmissionFailure,
+ sameRegularFileState,
+} from "../filesystem/RegularFile.js";
+import {
+ MAX_SNAPSHOT_HASH_CANDIDATES,
+ LabeledStringScanner,
+ SnapshotHashScanner,
+} from "./FlutterPayloadScan.js";
+import {
+ ELF_HEADER_MAX_BYTES,
+ readElfHeader,
+ readElfSymbols,
+ readSnapshotHeader,
+} from "./DartElf.js";
+import { readElfBuildIds } from "./ElfBuildId.js";
+
+/** Stable identity for the Flutter build-identification provider. */
+export const FLUTTER_PROVIDER_IDENTITY = {
+ id: "flutter",
+ name: "Flutter build identification",
+ version: null,
+} as const;
+
+const APK_METADATA_READ_MAX_BYTES = 8 * 1024 * 1024;
+const LIBRARY_MAX_BYTES = 256 * 1024 * 1024;
+/** Cumulative cap across every library entry in one identification. */
+const TOTAL_EXTRACTION_MAX_BYTES = 768 * 1024 * 1024;
+/** The APK itself must fit within this budget before any copy. */
+const APK_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+// At most 32 ABI projections (two libraries each). With bounded hashes and
+// engine labels this keeps expanded result metadata below 512 KiB for ordinary
+// ABI names, independently of the archive's compressed-byte budget.
+const MAX_FLUTTER_ABIS = 32;
+const MAX_LIBRARY_PATH_BYTES = 1024;
+const MAX_POOL_URIS = 500;
+const MAX_POOL_TOKENS = 2_000;
+/** A complete AOT image carries exactly one VM and one isolate section. */
+const SYMBOL_PAIR_COUNT = 2;
+const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+
+/**
+ * Stream a local file digest without retaining large files in memory.
+ * Aborts between chunks so a cancellation cannot run a digest to completion.
+ */
+const sha256File = async (
+ operation: string,
+ path: string,
+ signal: AbortSignal | undefined,
+): Promise<string> => {
+ const hash = createHash("sha256");
+ const stream = createReadStream(path, signal === undefined ? {} : { signal });
+ for await (const chunk of stream) {
+ if (signal?.aborted === true)
+ throw new AnalysisCancelledError(operation, { cause: signal.reason });
+ hash.update(chunk as Buffer);
+ }
+ return hash.digest("hex");
+};
+
+/** One owned snapshot root: a read-only copy of the admitted input. */
+interface OwnedSnapshot {
+ readonly root: string;
+ readonly path: string;
+ readonly bytes: number;
+ readonly sha256: string;
+}
+
+interface LibraryFacts {
+ readonly libapp: {
+ present: boolean;
+ bytes: number | null;
+ sha256: string | null;
+ elfHeaderValid: boolean | null;
+ sources: number;
+ candidates: readonly string[];
+ };
+ readonly libflutter: {
+ present: boolean;
+ bytes: number | null;
+ sha256: string | null;
+ buildId: string | null;
+ buildIdCandidates: readonly string[];
+ buildIdFailures: readonly string[];
+ dartVersion: string | null;
+ dartVersionCapped: boolean;
+ toolchainLines: readonly string[];
+ toolchainCapped: boolean;
+ };
+}
+
+const emptyFacts = (): LibraryFacts => ({
+ libapp: {
+ present: false,
+ bytes: null,
+ sha256: null,
+ elfHeaderValid: null,
+ sources: 0,
+ candidates: [],
+ },
+ libflutter: {
+ present: false,
+ bytes: null,
+ sha256: null,
+ buildId: null,
+ buildIdCandidates: [],
+ buildIdFailures: [],
+ dartVersion: null,
+ dartVersionCapped: false,
+ toolchainLines: [],
+ toolchainCapped: false,
+ },
+});
+
+/** Translate a ZIP reader rejection into the typed analysis error algebra. */
+const isCancellation = (cause: unknown): boolean =>
+ cause instanceof AnalysisCancelledError ||
+ (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled") ||
+ (cause instanceof Error && cause.name === "AbortError") ||
+ (typeof cause === "object" &&
+ cause !== null &&
+ "code" in cause &&
+ cause.code === "ABORT_ERR");
+
+const mapInputFailure = (
+ operation: string,
+ path: string,
+ cause: unknown,
+): AnalysisError => {
+ if (cause instanceof AnalysisError) return cause;
+ if (isCancellation(cause))
+ return new AnalysisCancelledError(operation, { cause });
+ if (
+ cause instanceof Error &&
+ "code" in cause &&
+ (cause.code === "EACCES" || cause.code === "EPERM")
+ )
+ return new AnalysisAccessDeniedError(operation, path, cause.code, {
+ cause,
+ });
+ if (cause instanceof ArtifactReaderFailure && cause.reason === "limit")
+ return new AnalysisResourceConstraintError(
+ operation,
+ "memory",
+ cause.message,
+ { max_metadata_read_bytes: APK_METADATA_READ_MAX_BYTES },
+ { cause },
+ );
+ const message = cause instanceof Error ? cause.message : String(cause);
+ return new AnalysisInputError(operation, { cause }, [
+ {
+ path: ["path"],
+ reason: "invalid_format",
+ message: `The APK could not be read as a package: ${path}: ${message}`,
+ },
+ ]);
+};
+
+/** Provider-owned storage failures must never be attributed to caller input. */
+const mapOwnedIoFailure = (
+ operation: string,
+ cause: unknown,
+): AnalysisError => {
+ if (cause instanceof AnalysisError) return cause;
+ if (isCancellation(cause))
+ return new AnalysisCancelledError(operation, { cause });
+ if (
+ cause instanceof Error &&
+ "code" in cause &&
+ typeof cause.code === "string"
+ )
+ return new AnalysisResourceConstraintError(
+ operation,
+ "file-size",
+ `Provider-owned Flutter snapshot storage failed (${cause.code}): ${cause.message}`,
+ null,
+ { cause },
+ );
+ return new AnalysisProtocolError(operation, { cause });
+};
+
+/** ZIP format failures describe caller bytes; its descriptor is provider-owned. */
+const mapPackageFailure = (
+ operation: string,
+ path: string,
+ cause: unknown,
+): AnalysisError =>
+ cause instanceof Error && "code" in cause && typeof cause.code === "string"
+ ? mapOwnedIoFailure(operation, cause)
+ : mapInputFailure(operation, path, cause);
+
+interface FlutterLibrary {
+ readonly entry: ArtifactEntry;
+ readonly abi: string;
+ readonly kind: "libapp" | "libflutter";
+}
+
+/** One inventory owns occurrence ambiguity and metadata expansion for both tools. */
+const collectFlutterLibraries = async (
+ reader: ZipArtifactReader,
+ operation: string,
+ path: string,
+ signal: AbortSignal | undefined,
+): Promise<FlutterLibrary[]> => {
+ const libraries: FlutterLibrary[] = [];
+ const paths = new Set<string>();
+ const abis = new Set<string>();
+ try {
+ for await (const entry of reader.entries(signal)) {
+ if (entry.kind !== "file") continue;
+ const match = /^lib\/([^/]+)\/(libapp|libflutter)\.so$/u.exec(entry.path);
+ if (match === null) continue;
+ if (paths.has(entry.path))
+ throw new AnalysisInputError(operation, undefined, [
+ {
+ path: ["path"],
+ reason: "invalid_format",
+ message: `The selected APK has duplicate Flutter library members: ${path}: ${entry.path}`,
+ },
+ ]);
+ paths.add(entry.path);
+ abis.add(match[1]!);
+ if (
+ abis.size > MAX_FLUTTER_ABIS ||
+ Buffer.byteLength(entry.path) > MAX_LIBRARY_PATH_BYTES
+ )
+ throw new AnalysisResourceConstraintError(
+ operation,
+ "memory",
+ "Flutter library inventory exceeds the bounded ABI projection budget",
+ {
+ max_flutter_abis: MAX_FLUTTER_ABIS,
+ max_library_path_bytes: MAX_LIBRARY_PATH_BYTES,
+ },
+ );
+ libraries.push({
+ entry,
+ abi: match[1]!,
+ kind: match[2] === "libapp" ? "libapp" : "libflutter",
+ });
+ }
+ return libraries;
+ } catch (cause) {
+ throw mapPackageFailure(operation, path, cause);
+ }
+};
+
+/** The generator owns iterator closure, including early extraction failures. */
+async function* openEntrySafely(
+ reader: ZipArtifactReader,
+ entry: ArtifactEntry,
+ operation: string,
+ path: string,
+ signal: AbortSignal | undefined,
+): AsyncGenerator<Buffer> {
+ try {
+ yield* await reader.open(entry, signal);
+ } catch (cause) {
+ throw mapPackageFailure(operation, path, cause);
+ }
+}
+
+const checkApkSize = (operation: string, bytes: number): void => {
+ if (bytes > APK_MAX_BYTES)
+ throw new AnalysisResourceConstraintError(
+ operation,
+ "file-size",
+ `The selected APK exceeds the ${String(APK_MAX_BYTES)}-byte snapshot budget`,
+ { max_apk_bytes: APK_MAX_BYTES, observed_bytes: bytes },
+ );
+};
+
+export interface FlutterProviderOptions {
+ /** Deterministic root removal for tests; production removes recursively. */
+ readonly removeRoot?: (path: string) => Promise<void>;
+}
+
+/**
+ * Flutter build identification by pure parsing: reads `lib/<abi>/libapp.so`
+ * and `libflutter.so` through the hardened ZIP reader and reports the Dart
+ * snapshot hash, GNU build-id, and any labeled version strings verbatim.
+ * Runs no engine, installs nothing, and performs no external lookups.
+ */
+export class FlutterBuildProvider {
+ private readonly ownedRoots = new Map<
+ string,
+ Set<{ close(): Promise<void> }>
+ >();
+ private readonly removeRoot: (path: string) => Promise<void>;
+ private readonly cleanupFailures = new Map<string, readonly unknown[]>();
+
+ constructor(options: FlutterProviderOptions = {}) {
+ this.removeRoot =
+ options.removeRoot ??
+ ((path) => rm(path, { recursive: true, force: true }));
+ }
+
+ /**
+ * Snapshot the admitted input into a provider-owned, read-only copy so a
+ * concurrently modified original cannot mix into one observation. The
+ * digest is taken from the snapshot, and every later read uses the
+ * snapshot path.
+ */
+ private async ownSnapshot(
+ operation: string,
+ path: string,
+ signal: AbortSignal | undefined,
+ ): Promise<OwnedSnapshot> {
+ let root: string;
+ try {
+ root = await mkdtemp(join(tmpdir(), "rea-flutter-"));
+ } catch (cause) {
+ throw mapOwnedIoFailure(operation, cause);
+ }
+ this.ownedRoots.set(root, new Set());
+ const snapshotPath = join(root, "input.apk");
+ const readSource = async <T>(read: () => Promise<T>): Promise<T> => {
+ try {
+ return await read();
+ } catch (cause) {
+ throw mapInputFailure(operation, path, cause);
+ }
+ };
+ try {
+ // Pin the admitted source: capture its identity before the copy and
+ // revalidate after, so an in-place replacement or swap mid-copy is
+ // refused instead of publishing mixed bytes under the original path.
+ // The copy itself is streamed and abort-checked so cancellation
+ // stops the write promptly instead of draining the whole file.
+ let source: OwnedFileHandle;
+ try {
+ source = this.ownResource(
+ root,
+ new OwnedFileHandle(
+ await openRegularFile(path, { symlinks: "follow", signal }),
+ ),
+ );
+ } catch (cause) {
+ if (cause instanceof RegularFileAdmissionFailure) {
+ this.ownResource(root, cause.owner);
+ throw mapInputFailure(operation, path, cause.cause);
+ }
+ throw mapInputFailure(operation, path, cause);
+ }
+ const before = await readSource(() =>
+ source.handle.stat({ bigint: true }),
+ );
+ checkApkSize(operation, Number(before.size));
+ const output = this.ownResource(
+ root,
+ new OwnedFileHandle(await openFile(snapshotPath, "wx")),
+ );
+ const chunk = Buffer.alloc(64 * 1024);
+ let copiedBytes = 0;
+ while (copiedBytes <= Number(before.size)) {
+ signal?.throwIfAborted();
+ const { bytesRead } = await readSource(() =>
+ source.handle.read(
+ chunk,
+ 0,
+ Math.min(chunk.length, Number(before.size) - copiedBytes + 1),
+ copiedBytes,
+ ),
+ );
+ signal?.throwIfAborted();
+ if (bytesRead === 0) break;
+ copiedBytes += bytesRead;
+ if (BigInt(copiedBytes) > before.size)
+ throw new AnalysisArtifactChangedError(
+ operation,
+ path,
+ "Selected file grew during snapshotting",
+ );
+ await output.handle.writeFile(chunk.subarray(0, bytesRead));
+ }
+ await this.releaseResource(root, output);
+ const [after, currentPath] = await Promise.all([
+ readSource(() => source.handle.stat({ bigint: true })),
+ stat(path, { bigint: true }).catch((cause: unknown) => {
+ if (
+ cause instanceof Error &&
+ "code" in cause &&
+ (cause.code === "EACCES" || cause.code === "EPERM")
+ )
+ throw mapInputFailure(operation, path, cause);
+ throw new AnalysisArtifactChangedError(
+ operation,
+ path,
+ "Selected path became unavailable during snapshotting",
+ { cause },
+ );
+ }),
+ ]);
+ if (
+ BigInt(copiedBytes) !== before.size ||
+ !sameRegularFileState(before, after) ||
+ !sameRegularFileState(before, currentPath)
+ )
+ throw new AnalysisArtifactChangedError(
+ operation,
+ path,
+ "Selected file identity or contents changed during snapshotting",
+ );
+ await this.releaseResource(root, source);
+ await chmod(snapshotPath, 0o400);
+ const info = await stat(snapshotPath);
+ const sha256 = await sha256File(operation, snapshotPath, signal);
+ return { root, path: snapshotPath, bytes: info.size, sha256 };
+ } catch (cause) {
+ await this.discardRoot(root);
+ if (signal?.aborted === true)
+ throw new AnalysisCancelledError(operation, { cause });
+ throw mapOwnedIoFailure(operation, cause);
+ }
+ }
+
+ private readerFor(snapshot: OwnedSnapshot): ZipArtifactReader {
+ return this.ownResource(
+ snapshot.root,
+ new ZipArtifactReader(snapshot.path, "apk", APK_METADATA_READ_MAX_BYTES),
+ );
+ }
+
+ private ownResource<T extends { close(): Promise<void> }>(
+ root: string,
+ resource: T,
+ ): T {
+ this.ownedRoots.get(root)!.add(resource);
+ return resource;
+ }
+
+ private async releaseResource(
+ root: string,
+ resource: { close(): Promise<void> },
+ ): Promise<void> {
+ await resource.close();
+ this.ownedRoots.get(root)?.delete(resource);
+ }
+
+ /** Close every owned handle before removing its root; retain any failure. */
+ private async discardRoot(root: string): Promise<boolean> {
+ const resources = this.ownedRoots.get(root);
+ if (resources === undefined) return true;
+ const attempts = await Promise.allSettled(
+ [...resources].map((resource) => this.releaseResource(root, resource)),
+ );
+ const failures = attempts.flatMap((attempt) =>
+ attempt.status === "rejected" ? [attempt.reason as unknown] : [],
+ );
+ if (failures.length > 0) {
+ this.cleanupFailures.set(root, failures);
+ return false;
+ }
+ try {
+ await this.removeRoot(root);
+ this.ownedRoots.delete(root);
+ this.cleanupFailures.delete(root);
+ return true;
+ } catch (cause) {
+ this.cleanupFailures.set(root, [cause]);
+ return false;
+ }
+ }
+
+ /** Pure parsing; the provider is always available. */
+ async inspectAvailability(): Promise<ProviderAvailability> {
+ return {
+ status: "available",
+ code: null,
+ reason: null,
+ diagnostics: { engine: "static-apk-parsing" },
+ };
+ }
+
+ /** Retain failed snapshot cleanup ownership and retry it on close. */
+ async close(): Promise<void> {
+ const failures: unknown[] = [];
+ for (const root of [...this.ownedRoots.keys()]) {
+ if (!(await this.discardRoot(root)))
+ failures.push(
+ new AggregateError(
+ this.cleanupFailures.get(root)!,
+ `snapshot root retained: ${root}`,
+ ),
+ );
+ }
+ if (failures.length > 0)
+ throw new AggregateError(failures, "Flutter snapshot cleanup failed");
+ }
+
+ async execute(
+ request: FlutterRequest,
+ options?: ExecutionOptions,
+ ): Promise<Result<AnalysisExecution, AnalysisError>> {
+ if (options?.signal?.aborted === true)
+ return err(new AnalysisCancelledError(request.operation));
+ const { path } = request.input;
+ const signal = options?.signal;
+ let snapshot: OwnedSnapshot | undefined;
+ let result: Result<AnalysisExecution, AnalysisError>;
+ try {
+ snapshot = await this.ownSnapshot(request.operation, path, signal);
+ const reader = this.readerFor(snapshot);
+ const libraries = await collectFlutterLibraries(
+ reader,
+ request.operation,
+ path,
+ signal,
+ );
+ result =
+ request.operation === "inspect_dart_aot"
+ ? await this.inspectDartAot(
+ path,
+ request.input.abi,
+ signal,
+ snapshot,
+ reader,
+ libraries,
+ )
+ : await this.identifyFlutterBuild(
+ path,
+ signal,
+ snapshot,
+ reader,
+ libraries,
+ );
+ } catch (cause) {
+ result = err(mapOwnedIoFailure(request.operation, cause));
+ } finally {
+ if (snapshot !== undefined) await this.discardRoot(snapshot.root);
+ }
+ if (signal?.aborted === true)
+ return err(
+ new AnalysisCancelledError(request.operation, { cause: signal.reason }),
+ );
+ return result;
+ }
+
+ private async identifyFlutterBuild(
+ path: string,
+ signal: AbortSignal | undefined,
+ snapshot: OwnedSnapshot,
+ reader: ZipArtifactReader,
+ flutterEntries: readonly FlutterLibrary[],
+ ): Promise<Result<AnalysisExecution, AnalysisError>> {
+ const operation = "identify_flutter_build";
+ for (const { entry } of flutterEntries) {
+ if (entry.declaredSize !== null && entry.declaredSize > LIBRARY_MAX_BYTES)
+ return err(
+ new AnalysisResourceConstraintError(
+ operation,
+ "file-size",
+ `${entry.path} exceeds the library read budget`,
+ { max_library_bytes: LIBRARY_MAX_BYTES, entry_path: entry.path },
+ ),
+ );
+ }
+ // Preflight: refuse before any I/O when the declared entry sizes
+ // already exceed the cumulative budget, even though streaming might
+ // discover smaller actual sizes.
+ const declaredTotal = flutterEntries.reduce(
+ (total, { entry }) => total + (entry.declaredSize ?? 0),
+ 0,
+ );
+ if (declaredTotal > TOTAL_EXTRACTION_MAX_BYTES)
+ return err(
+ new AnalysisResourceConstraintError(
+ operation,
+ "file-size",
+ `declared library sizes total ${String(declaredTotal)} bytes, exceeding the ${String(TOTAL_EXTRACTION_MAX_BYTES)}-byte cumulative budget before any extraction`,
+ {
+ max_total_bytes: TOTAL_EXTRACTION_MAX_BYTES,
+ declared_total: declaredTotal,
+ },
+ ),
+ );
+
+ const facts = new Map<string, LibraryFacts>();
+ let extractedTotal = 0;
+ let libraryIndex = 0;
+ for (const { entry, abi, kind } of flutterEntries) {
+ const stream = openEntrySafely(reader, entry, operation, path, signal);
+ const hash = createHash("sha256");
+ const snapshotScanner = new SnapshotHashScanner();
+ const labeledScanner = new LabeledStringScanner();
+ const engineFile =
+ kind === "libflutter"
+ ? this.ownResource(
+ snapshot.root,
+ new OwnedFileHandle(
+ await openFile(
+ join(snapshot.root, `engine-${libraryIndex++}.so`),
+ "wx+",
+ ),
+ ),
+ )
+ : null;
+ let bytes = 0;
+ const headerPrefix = Buffer.alloc(ELF_HEADER_MAX_BYTES);
+ let headerBytes = 0;
+ for await (const chunk of stream) {
+ if (signal?.aborted === true)
+ return err(
+ new AnalysisCancelledError(operation, {
+ cause: signal.reason,
+ }),
+ );
+ const view = chunk as Buffer;
+ headerBytes += view.copy(
+ headerPrefix,
+ headerBytes,
+ 0,
+ Math.min(view.length, headerPrefix.length - headerBytes),
+ );
+ bytes += view.byteLength;
+ if (bytes > LIBRARY_MAX_BYTES)
+ return err(
+ new AnalysisResourceConstraintError(
+ operation,
+ "file-size",
+ `${entry.path} exceeds the ${String(LIBRARY_MAX_BYTES)}-byte read budget while streaming`,
+ {
+ max_library_bytes: LIBRARY_MAX_BYTES,
+ entry_path: entry.path,
+ },
+ ),
+ );
+ hash.update(view);
+ if (kind === "libapp") snapshotScanner.push(view);
+ else {
+ labeledScanner.push(view);
+ await engineFile!.handle.writeFile(view);
+ }
+ // Enforce the cumulative cap inside the chunk loop so refusal
+ // happens before the remaining bytes are streamed and hashed.
+ if (extractedTotal + bytes > TOTAL_EXTRACTION_MAX_BYTES)
+ return err(
+ new AnalysisResourceConstraintError(
+ operation,
+ "file-size",
+ `cumulative library extraction across ${String(flutterEntries.length)} entries exceeds the ${String(TOTAL_EXTRACTION_MAX_BYTES)}-byte budget`,
+ { max_total_bytes: TOTAL_EXTRACTION_MAX_BYTES },
+ ),
+ );
+ }
+ extractedTotal += bytes;
+ const digest = hash.digest("hex");
+ const current = facts.get(abi) ?? emptyFacts();
+ if (kind === "libapp") {
+ const scan = snapshotScanner.result();
+ if (scan.capped)
+ return err(
+ new AnalysisResourceConstraintError(
+ operation,
+ "memory",
+ "Snapshot hash candidates exceed the retained evidence budget",
+ {
+ max_snapshot_hash_candidates: MAX_SNAPSHOT_HASH_CANDIDATES,
+ entry_path: entry.path,
+ },
+ ),
+ );
+ facts.set(abi, {
+ ...current,
+ libapp: {
+ present: true,
+ bytes,
+ sha256: digest,
+ elfHeaderValid:
+ readElfHeader(headerPrefix.subarray(0, headerBytes), bytes)
+ .header !== undefined,
+ sources: scan.sources,
+ candidates: scan.candidates,
+ },
+ });
+ } else {
+ const labeled = labeledScanner.result();
+ const buildIds = await readElfBuildIds(
+ engineFile!.handle,
+ bytes,
+ signal,
+ );
+ await this.releaseResource(snapshot.root, engineFile!);
+ facts.set(abi, {
+ ...current,
+ libflutter: {
+ present: true,
+ bytes,
+ sha256: digest,
+ buildId:
+ buildIds.failures.length === 0 && buildIds.candidates.length === 1
+ ? buildIds.candidates[0]!
+ : null,
+ buildIdCandidates: buildIds.candidates,
+ buildIdFailures: buildIds.failures.map((failure) => failure.reason),
+ ...labeled,
+ },
+ });
+ }
+ }
+ const abis = [...facts.entries()]
+ .map(([abi, value]) => ({
+ abi,
+ libapp: {
+ present: value.libapp.present,
+ bytes: value.libapp.bytes,
+ sha256: value.libapp.sha256,
+ elf_header_valid: value.libapp.elfHeaderValid,
+ snapshot_hash_sources: value.libapp.sources,
+ snapshot_hash_candidates: [...value.libapp.candidates],
+ snapshot_hash:
+ value.libapp.candidates.length === 1
+ ? value.libapp.candidates[0]!
+ : null,
+ },
+ libflutter: {
+ present: value.libflutter.present,
+ bytes: value.libflutter.bytes,
+ sha256: value.libflutter.sha256,
+ build_id: value.libflutter.buildId,
+ build_id_candidates: [...value.libflutter.buildIdCandidates],
+ dart_version: value.libflutter.dartVersion,
+ dart_version_capped: value.libflutter.dartVersionCapped,
+ toolchain_lines: [...value.libflutter.toolchainLines],
+ toolchain_capped: value.libflutter.toolchainCapped,
+ },
+ }))
+ .sort((left, right) => left.abi.localeCompare(right.abi));
+ const flutterDetected = abis.some((entry) => entry.libapp.present);
+ const partial =
+ abis.some(
+ (entry) =>
+ (entry.libapp.present &&
+ (entry.libapp.snapshot_hash === null ||
+ entry.libapp.snapshot_hash_sources !== 2 ||
+ entry.libapp.elf_header_valid !== true)) ||
+ entry.libflutter.toolchain_capped ||
+ entry.libflutter.dart_version_capped ||
+ entry.libapp.present !== entry.libflutter.present,
+ ) ||
+ [...facts.values()].some(
+ (value) =>
+ value.libflutter.buildIdFailures.length > 0 ||
+ value.libflutter.buildIdCandidates.length > 1,
+ );
+ return ok(
+ createAnalysisExecution(
+ {
+ target: { path, bytes: snapshot.bytes, sha256: snapshot.sha256 },
+ flutter_detected: flutterDetected,
+ abis,
+ coverage: partial ? "partial" : "complete",
+ },
+ FLUTTER_PROVIDER_IDENTITY,
+ {
+ subject: { path, format: "apk", sha256: snapshot.sha256 },
+ locations: [{ kind: "artifact-path", path }],
+ limitations: [
+ "The APK is read through an owned read-only snapshot; concurrent changes to the original cannot mix into this observation",
+ "The snapshot hash identifies a Dart SDK build only against an external mapping dataset; REA performs no lookup",
+ "Release engine builds often carry no labeled Dart version string; absence is reported, not guessed",
+ "Engine build IDs come only from ELF-declared PT_NOTE/SHT_NOTE records; conflicting or incompletely examined notes preserve candidates and report partial coverage",
+ ...[...facts].flatMap(([abi, value]) => [
+ ...value.libflutter.buildIdFailures.map(
+ (reason) => `lib/${abi}/libflutter.so: ${reason}`,
+ ),
+ ...(value.libflutter.buildIdCandidates.length > 1
+ ? [`lib/${abi}/libflutter.so has conflicting GNU build IDs`]
+ : []),
+ ]),
+ ...abis
+ .filter((entry) => entry.libflutter.toolchain_capped)
+ .map(
+ (entry) =>
+ `lib/${entry.abi}/libflutter.so has toolchain labels omitted by the complete-label grammar or the 4-line projection`,
+ ),
+ ...abis
+ .filter((entry) => entry.libflutter.dart_version_capped)
+ .map(
+ (entry) =>
+ `lib/${entry.abi}/libflutter.so has Dart version labels omitted by the complete-label grammar or the single-version projection`,
+ ),
+ "The snapshot hash sits 20 bytes after each snapshot magic in the AOT payload; findings are observations of that layout",
+ "ELF header validity checks the supported header layout and declared table extents; identification does not resolve symbols or validate table contents",
+ ...abis
+ .filter(
+ (entry) =>
+ entry.libapp.present &&
+ entry.libapp.snapshot_hash_sources !== 2,
+ )
+ .map(
+ (entry) =>
+ `lib/${entry.abi}/libapp.so carries ${String(entry.libapp.snapshot_hash_sources)} snapshot section(s); a complete AOT payload carries two, so the library is truncated or nonstandard`,
+ ),
+ ...abis
+ .filter(
+ (entry) =>
+ entry.libapp.present &&
+ entry.libapp.elf_header_valid !== true,
+ )
+ .map(
+ (entry) =>
+ `lib/${entry.abi}/libapp.so has a truncated, malformed, or unsupported ELF header or table extent; byte-scanned hashes remain observations only`,
+ ),
+ ...(flutterDetected
+ ? []
+ : [
+ "No lib/*/libapp.so was found; the target does not carry a Flutter AOT payload",
+ ]),
+ ],
+ },
+ ),
+ );
+ }
+
+ private async inspectDartAot(
+ path: string,
+ abi: string | undefined,
+ signal: AbortSignal | undefined,
+ snapshot: OwnedSnapshot,
+ reader: ZipArtifactReader,
+ libraries: readonly FlutterLibrary[],
+ ): Promise<Result<AnalysisExecution, AnalysisError>> {
+ const candidates = libraries.filter((library) => library.kind === "libapp");
+ if (candidates.length === 0)
+ return err(
+ new AnalysisUnsupportedTargetError(
+ "inspect_dart_aot",
+ path,
+ "No lib/<abi>/libapp.so was found; the target carries no Dart AOT payload",
+ ),
+ );
+ const preference = ["arm64-v8a", "x86_64", "x86", "armeabi-v7a"];
+ const selected =
+ abi === undefined
+ ? [...candidates].sort(
+ (left, right) =>
+ (preference.indexOf(left.abi) + 1 || preference.length + 1) -
+ (preference.indexOf(right.abi) + 1 || preference.length + 1) ||
+ left.abi.localeCompare(right.abi),
+ )[0]!
+ : candidates.find((candidate) => candidate.abi === abi);
+ if (selected === undefined)
+ return err(
+ new AnalysisUnsupportedTargetError(
+ "inspect_dart_aot",
+ path,
+ `No libapp.so was found for ABI ${abi ?? "(none)"}; available: ${candidates
+ .map((candidate) => candidate.abi)
+ .join(", ")}`,
+ ),
+ );
+ const declared = selected.entry.declaredSize ?? LIBRARY_MAX_BYTES + 1;
+ if (declared > LIBRARY_MAX_BYTES)
+ return err(
+ new AnalysisResourceConstraintError(
+ "inspect_dart_aot",
+ "file-size",
+ `lib/${selected.abi}/libapp.so declares ${String(declared)} bytes, exceeding the ${String(LIBRARY_MAX_BYTES)}-byte read budget`,
+ { max_library_bytes: LIBRARY_MAX_BYTES },
+ ),
+ );
+ const imagePath = join(snapshot.root, "libapp.so");
+ const imageHash = createHash("sha256");
+ const imageWriter = this.ownResource(
+ snapshot.root,
+ new OwnedFileHandle(await openFile(imagePath, "wx")),
+ );
+ {
+ const stream = openEntrySafely(
+ reader,
+ selected.entry,
+ "inspect_dart_aot",
+ path,
+ signal,
+ );
+ let total = 0;
+ for await (const chunk of stream) {
+ if (signal?.aborted === true)
+ return err(new AnalysisCancelledError("inspect_dart_aot"));
+ const view = chunk as Buffer;
+ total += view.byteLength;
+ if (total > LIBRARY_MAX_BYTES)
+ return err(
+ new AnalysisResourceConstraintError(
+ "inspect_dart_aot",
+ "file-size",
+ `lib/${selected.abi}/libapp.so exceeds the ${String(LIBRARY_MAX_BYTES)}-byte read budget while streaming`,
+ { max_library_bytes: LIBRARY_MAX_BYTES },
+ ),
+ );
+ imageHash.update(view);
+ await imageWriter.handle.writeFile(view);
+ }
+ }
+ await this.releaseResource(snapshot.root, imageWriter);
+ const imageSha256 = imageHash.digest("hex");
+ // Allocate exactly the budget-checked size before reading, so the
+ // buffer cannot exceed the declared library size plus one byte.
+ const image = Buffer.alloc(declared + 1);
+ let imageLength = 0;
+ {
+ const file = this.ownResource(
+ snapshot.root,
+ new OwnedFileHandle(await openFile(imagePath, "r")),
+ );
+ while (imageLength < image.length) {
+ if (signal?.aborted === true)
+ return err(new AnalysisCancelledError("inspect_dart_aot"));
+ const result = await file.handle.read(
+ image,
+ imageLength,
+ image.length - imageLength,
+ null,
+ );
+ signal?.throwIfAborted();
+ if (result.bytesRead === 0) break;
+ imageLength += result.bytesRead;
+ }
+ await this.releaseResource(snapshot.root, file);
+ }
+ signal?.throwIfAborted();
+ const bounded = image.subarray(0, imageLength);
+ const symbolNames = [
+ "_kDartVmSnapshotData",
+ "_kDartVmSnapshotInstructions",
+ "_kDartIsolateSnapshotData",
+ "_kDartIsolateSnapshotInstructions",
+ ];
+ const sections: {
+ name: string;
+ offset: number;
+ size: number;
+ magic_valid: boolean;
+ kind: number | null;
+ header_length: number | null;
+ }[] = [];
+ const dataHeaders: {
+ name: string;
+ offset: number;
+ size: number;
+ header: ReturnType<typeof readSnapshotHeader>;
+ }[] = [];
+ let isolateData: Buffer | null = null;
+ const inventory = await readElfSymbols(bounded, symbolNames, signal);
+ for (const symbol of inventory.symbols) {
+ const name = symbol.name;
+ const header = name.endsWith("Data")
+ ? readSnapshotHeader(
+ bounded.subarray(symbol.offset, symbol.offset + symbol.size),
+ 0,
+ )
+ : null;
+ sections.push({
+ name,
+ offset: symbol.offset,
+ size: symbol.size,
+ magic_valid: header?.magicValid ?? false,
+ kind: header?.kind ?? null,
+ header_length: header?.headerLength ?? null,
+ });
+ if (header !== null) dataHeaders.push({ ...symbol, header });
+ if (name === "_kDartIsolateSnapshotData")
+ isolateData = image.subarray(
+ symbol.offset,
+ symbol.offset + symbol.size,
+ );
+ }
+ // Each exported data symbol owns one header at its start. Matching
+ // records elsewhere in a symbol are not evidence for the other
+ // symbol's hash. Count a physical header only once for aliased exports.
+ const observedOffsets = new Set<number>();
+ let aliasedDataSymbols = false;
+ const hashes: string[] = [];
+ for (const section of dataHeaders) {
+ if (observedOffsets.has(section.offset)) {
+ aliasedDataSymbols = true;
+ continue;
+ }
+ observedOffsets.add(section.offset);
+ if (section.header.hash !== null) hashes.push(section.header.hash);
+ }
+ const hashScan = {
+ sources: hashes.length,
+ candidates: [...new Set(hashes)],
+ };
+ const overlappingDataSymbols = dataHeaders.some((section, index) =>
+ dataHeaders
+ .slice(0, index)
+ .some(
+ (previous) =>
+ previous.offset < section.offset + section.size &&
+ section.offset < previous.offset + previous.size,
+ ),
+ );
+ if (sections.length === 0)
+ return err(
+ new AnalysisUnsupportedTargetError(
+ "inspect_dart_aot",
+ path,
+ `No recognizable Dart snapshot symbols were found: ${inventory.failures.map((failure) => failure.reason).join("; ")}`,
+ ),
+ );
+ const pool = await projectStringPool(isolateData, signal);
+ const snapshotPartial =
+ inventory.failures.length > 0 ||
+ aliasedDataSymbols ||
+ overlappingDataSymbols ||
+ sections.length < symbolNames.length ||
+ dataHeaders.length !== SYMBOL_PAIR_COUNT ||
+ dataHeaders.some((section) => !section.header.complete) ||
+ hashScan.candidates.length !== 1 ||
+ hashScan.sources !== SYMBOL_PAIR_COUNT;
+ const poolPartial =
+ isolateData === null ||
+ pool.collectionCapped ||
+ pool.packageUriCount > MAX_POOL_URIS ||
+ pool.dartUriCount > MAX_POOL_URIS ||
+ pool.classLikeTokenCount > MAX_POOL_TOKENS;
+ return ok(
+ createAnalysisExecution(
+ {
+ target: { path, bytes: snapshot.bytes, sha256: snapshot.sha256 },
+ abi: selected.abi,
+ libapp: {
+ coverage: snapshotPartial ? "partial" : "complete",
+ bytes: imageLength,
+ sha256: imageSha256,
+ snapshot_hash:
+ hashScan.candidates.length === 1 ? hashScan.candidates[0]! : null,
+ snapshot_hash_candidates: [...hashScan.candidates],
+ snapshot_hash_sources: hashScan.sources,
+ sections,
+ },
+ string_pool: {
+ coverage: poolPartial ? "partial" : "complete",
+ package_uris: pool.packageUris.slice(0, MAX_POOL_URIS),
+ package_uri_count_at_least: pool.packageUriCount,
+ dart_uris: pool.dartUris.slice(0, MAX_POOL_URIS),
+ dart_uri_count_at_least: pool.dartUriCount,
+ class_like_tokens: pool.classLikeTokens.slice(0, MAX_POOL_TOKENS),
+ class_like_token_count_at_least: pool.classLikeTokenCount,
+ printable_run_count: pool.printableRunCount,
+ },
+ coverage: snapshotPartial || poolPartial ? "partial" : "complete",
+ },
+ FLUTTER_PROVIDER_IDENTITY,
+ {
+ subject: { path, format: "apk", sha256: snapshot.sha256 },
+ locations: [{ kind: "artifact-path", path }],
+ limitations: [
+ "The APK is read through an owned read-only snapshot; concurrent changes to the original cannot mix into this observation",
+ "Snapshot sections are located through the ELF dynamic symbol table; a payload without exported snapshot symbols is refused rather than guessed",
+ "Snapshot hash sources are the headers at the start of the VM and isolate data symbols; complete decoding supports kind 3 (the Dart 2.14 FullAOT layout), a valid hash and a declared length that fits its symbol, including the four magic bytes; other kind values remain observed with partial coverage",
+ "String-pool entries are byte-pattern observations from the isolate data section, not deserialized cluster semantics; typed class and function recovery needs an SDK-specific parser",
+ "class_like_tokens are identifier-shaped runs and include incidental matches",
+ "string-pool counts are lower bounds: collection stops at twice each projection bound, and any value beyond that is counted only through the capped flag",
+ ...inventory.failures.map((failure) => failure.reason),
+ ...(sections.length < symbolNames.length
+ ? [
+ `Only ${String(sections.length)} of 4 snapshot symbols were present`,
+ ]
+ : []),
+ ...(aliasedDataSymbols
+ ? [
+ "Two or more snapshot data symbols share one header offset; its hash counts as one source instead of two agreeing ones",
+ ]
+ : []),
+ ...(overlappingDataSymbols && !aliasedDataSymbols
+ ? [
+ "Snapshot data symbol ranges overlap; independent VM/isolate coverage is not established",
+ ]
+ : []),
+ ...dataHeaders
+ .filter((section) => !section.header.complete)
+ .map(
+ (section) =>
+ `${section.name} has an incomplete or invalid snapshot header: kind ${String(section.header.kind)} (AOT app requires 3), declared length ${String(section.header.headerLength)} excludes the four magic bytes, symbol size ${String(section.size)}, valid hash ${String(section.header.hash !== null)}`,
+ ),
+ ...(pool.collectionCapped
+ ? [
+ "String-pool collection or printable-run capacity was exceeded; counts are lower bounds and overflowed runs are omitted",
+ ]
+ : []),
+ ...(pool.dartUriCount > MAX_POOL_URIS
+ ? [
+ `dart_uris reports ${String(MAX_POOL_URIS)} of at least ${String(pool.dartUriCount)} distinct URIs`,
+ ]
+ : []),
+ ...(pool.packageUriCount > MAX_POOL_URIS
+ ? [
+ `package_uris reports ${String(MAX_POOL_URIS)} of at least ${String(pool.packageUriCount)} distinct URIs`,
+ ]
+ : []),
+ ...(pool.classLikeTokenCount > MAX_POOL_TOKENS
+ ? [
+ `class_like_tokens reports ${String(MAX_POOL_TOKENS)} of at least ${String(pool.classLikeTokenCount)} distinct tokens`,
+ ]
+ : []),
+ ],
+ },
+ ),
+ );
+ }
+}
+
+/**
+ * Categorize printable runs from one snapshot data section. Collection stops
+ * admitting new distinct entries once each category reaches its projection
+ * bound times a slack factor, so allocation and sorting stay proportional to
+ * the response rather than to an adversarial payload; counts still reflect
+ * how far scanning proceeded before the collection cap tripped.
+ */
+const projectStringPool = async (
+ section: Buffer | null,
+ signal: AbortSignal | undefined,
+): Promise<{
+ packageUris: string[];
+ packageUriCount: number;
+ dartUris: string[];
+ dartUriCount: number;
+ classLikeTokens: string[];
+ classLikeTokenCount: number;
+ printableRunCount: number;
+ collectionCapped: boolean;
+}> => {
+ const packages = new Set<string>();
+ const darts = new Set<string>();
+ const tokens = new Set<string>();
+ let runCount = 0;
+ let collectionCapped = false;
+ const COLLECTION_SLACK = 2;
+ /** One printable run never materializes beyond this length. */
+ const MAX_RUN_BYTES = 1024;
+ const packageBudget = MAX_POOL_URIS * COLLECTION_SLACK;
+ const dartBudget = MAX_POOL_URIS * COLLECTION_SLACK;
+ const tokenBudget = MAX_POOL_TOKENS * COLLECTION_SLACK;
+ if (section !== null) {
+ let run = "";
+ const consider = (text: string): void => {
+ if (text.length < 5) return;
+ runCount += 1;
+ if (text.startsWith("package:")) {
+ if (!packages.has(text) && packages.size >= packageBudget)
+ collectionCapped = true;
+ else packages.add(text);
+ } else if (text.startsWith("dart:")) {
+ if (!darts.has(text) && darts.size >= dartBudget)
+ collectionCapped = true;
+ else darts.add(text);
+ } else if (
+ text.length <= 128 &&
+ text.length >= 5 &&
+ IDENTIFIER_PATTERN.test(text)
+ ) {
+ if (!tokens.has(text) && tokens.size >= tokenBudget)
+ collectionCapped = true;
+ else tokens.add(text);
+ }
+ };
+ let overflowed = false;
+ for (let start = 0; start < section.length; start += 64 * 1024) {
+ await yieldToEventLoop();
+ signal?.throwIfAborted();
+ for (const byte of section.subarray(start, start + 64 * 1024)) {
+ if (byte >= 0x20 && byte < 0x7f) {
+ // A single unbounded run (an adversarial NUL-free section) never
+ // materializes: growth stops at the cap and the entire run is
+ // discarded at its delimiter, since a truncated prefix would be
+ // fabricated evidence rather than an observation.
+ if (run.length < MAX_RUN_BYTES) run += String.fromCharCode(byte);
+ else {
+ overflowed = true;
+ collectionCapped = true;
+ }
+ } else {
+ if (!overflowed) consider(run);
+ overflowed = false;
+ run = "";
+ }
+ }
+ }
+ if (!overflowed) consider(run);
+ }
+ signal?.throwIfAborted();
+ return {
+ packageUris: [...packages].sort(),
+ packageUriCount: packages.size,
+ dartUris: [...darts].sort(),
+ dartUriCount: darts.size,
+ classLikeTokens: [...tokens].sort(),
+ classLikeTokenCount: tokens.size,
+ printableRunCount: runCount,
+ collectionCapped,
+ };
+};
diff --git a/src/flutter/FlutterPayloadScan.test.ts b/src/flutter/FlutterPayloadScan.test.ts
new file mode 100644
index 000000000..681a373a1
--- /dev/null
+++ b/src/flutter/FlutterPayloadScan.test.ts
@@ -0,0 +1,209 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ LabeledStringScanner,
+ SnapshotHashScanner,
+} from "./FlutterPayloadScan.js";
+
+/** Real payload prefix from Flutter Gallery 2.9.2's arm64 libapp.so. */
+const realSnapshotSection = (hash: string): Uint8Array =>
+ Uint8Array.from([
+ 0xf5,
+ 0xf5,
+ 0xdc,
+ 0xdc,
+ 0x49,
+ 0x0d,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x03,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ ...Array.from(hash, (character) => character.charCodeAt(0)),
+ ]);
+
+describe("SnapshotHashScanner", () => {
+ it("reads the hash from real vm and isolate sections that agree", () => {
+ const scanner = new SnapshotHashScanner();
+ scanner.push(realSnapshotSection("65817c30a78bb44c3dc3771876b6010a"));
+ scanner.push(Uint8Array.from([0, 0, 0]));
+ scanner.push(realSnapshotSection("65817c30a78bb44c3dc3771876b6010a"));
+ expect(scanner.result()).toEqual({
+ capped: false,
+ sources: 2,
+ candidates: ["65817c30a78bb44c3dc3771876b6010a"],
+ });
+ });
+
+ it("keeps both hashes when sections disagree", () => {
+ const scanner = new SnapshotHashScanner();
+ scanner.push(realSnapshotSection("11111111111111111111111111111111"));
+ scanner.push(realSnapshotSection("22222222222222222222222222222222"));
+ expect(scanner.result()).toEqual({
+ capped: false,
+ sources: 2,
+ candidates: [
+ "11111111111111111111111111111111",
+ "22222222222222222222222222222222",
+ ],
+ });
+ });
+
+ it("survives chunk boundaries that split the magic and hash", () => {
+ const scanner = new SnapshotHashScanner();
+ const payload = realSnapshotSection("65817c30a78bb44c3dc3771876b6010a");
+ for (let offset = 0; offset < payload.length; offset += 7)
+ scanner.push(payload.subarray(offset, offset + 7));
+ expect(scanner.result()).toEqual({
+ capped: false,
+ sources: 1,
+ candidates: ["65817c30a78bb44c3dc3771876b6010a"],
+ });
+ });
+
+ it("ignores a magic without a following hash", () => {
+ const scanner = new SnapshotHashScanner();
+ scanner.push(Uint8Array.from([0xf5, 0xf5, 0xdc, 0xdc, 0xff, 0xff, 0xff]));
+ expect(scanner.result()).toEqual({
+ capped: false,
+ sources: 0,
+ candidates: [],
+ });
+ });
+});
+
+it("distinguishes a full candidate set from omitted conflicts", () => {
+ const scanner = new SnapshotHashScanner();
+ for (let index = 0; index < 64; index += 1)
+ scanner.push(realSnapshotSection(index.toString(16).padStart(32, "0")));
+ expect(scanner.result().capped).toBe(false);
+ scanner.push(realSnapshotSection("0".repeat(32)));
+ expect(scanner.result().capped).toBe(false);
+ scanner.push(realSnapshotSection("f".repeat(32)));
+ expect(scanner.result()).toMatchObject({ sources: 66, capped: true });
+ expect(scanner.result().candidates).toHaveLength(64);
+});
+
+describe("LabeledStringScanner", () => {
+ const assertSingleToolchainLine = (line: string): void => {
+ const scanner = new LabeledStringScanner();
+ scanner.push(
+ Uint8Array.from(
+ Array.from(`\x00${line}\x00`, (character) => character.charCodeAt(0)),
+ ),
+ );
+ expect(scanner.result().toolchainLines).toEqual([line]);
+ };
+ it("collects a full clang line within the 500-character bound", () => {
+ assertSingleToolchainLine(
+ "Android (5900059 based on r365631c1) clang version 9.0.8 (https://android.googlesource.com/toolchain/llvm-project 207d7abc1a2abf3ef8d4301736d6a7ebc224a290) (based on LLVM 9.0.8svn)",
+ );
+ });
+
+ it("reads a labeled Dart VM version string when a build carries one", () => {
+ const scanner = new LabeledStringScanner();
+ scanner.push(
+ Uint8Array.from(
+ Array.from(
+ "\x00Dart VM version: 3.1.0 (stable) somewhere\x00",
+ (character) => character.charCodeAt(0),
+ ),
+ ),
+ );
+ expect(scanner.result().dartVersion).toBe(
+ "Dart VM version: 3.1.0 (stable) somewhere",
+ );
+ });
+
+ it("collects the labeled Android clang line", () => {
+ assertSingleToolchainLine(
+ "Android (5900059 based on r365631c) clang version 9.0.8 (https://android.googlesource.com/toolchain/llvm-project 207d7abc) (based on LLVM 9.0.8svn)",
+ );
+ });
+
+ it("does not claim a toolchain cap for unrelated overlong strings", () => {
+ const scanner = new LabeledStringScanner();
+ const license = `Apache License Version 2.0 ${"x".repeat(700)}`;
+ scanner.push(
+ Uint8Array.from(
+ Array.from(`\x00${license}\x00`, (character) =>
+ character.charCodeAt(0),
+ ),
+ ),
+ );
+ const result = scanner.result();
+ expect(result.toolchainCapped).toBe(false);
+ expect(result.toolchainLines).toEqual([]);
+ });
+
+ it("claims the cap only for an overlong run shaped like a toolchain line", () => {
+ const overlongToolchain = `Android (${"r".repeat(700)}) clang version 9`;
+ for (const [text, toolchainCapped, dartVersionCapped] of [
+ [overlongToolchain, true, false],
+ [`Dart VM version: ${"3".repeat(700)}`, false, true],
+ [`based on LLVM 9 ${"x".repeat(700)}`, true, false],
+ ] as const) {
+ const scanner = new LabeledStringScanner();
+ scanner.push(
+ Uint8Array.from(
+ Array.from(`\x00${text}\x00`, (character) => character.charCodeAt(0)),
+ ),
+ );
+ expect(scanner.result()).toMatchObject({
+ toolchainCapped,
+ dartVersionCapped,
+ dartVersion: null,
+ toolchainLines: [],
+ });
+ }
+ });
+
+ it.each([
+ { label: "Dart", line: `Dart VM version:${"x".repeat(200)}`, dart: true },
+ {
+ label: "Android clang",
+ line: `Android (${"r".repeat(80)}) clang version ${"x".repeat(500)}`,
+ dart: false,
+ },
+ { label: "LLVM", line: `based on LLVM 9${"x".repeat(80)}`, dart: false },
+ ])(
+ "requires the complete $label run at its own grammar boundary",
+ ({ line, dart }) => {
+ for (const suffix of ["", "x", "x".repeat(1000)]) {
+ const payload = Buffer.from(`${line}${suffix}\x00`);
+ for (const chunkSize of [1, 7, payload.length]) {
+ const scanner = new LabeledStringScanner();
+ for (let offset = 0; offset < payload.length; offset += chunkSize)
+ scanner.push(payload.subarray(offset, offset + chunkSize));
+ const valid = suffix === "";
+ expect(scanner.result()).toEqual({
+ dartVersion: dart && valid ? line : null,
+ dartVersionCapped: dart && !valid,
+ toolchainLines: !dart && valid ? [line] : [],
+ toolchainCapped: !dart && !valid,
+ });
+ }
+ }
+ },
+ );
+
+ it("preserves whitespace and separates distinct Dart-label omissions", () => {
+ assertSingleToolchainLine("based on LLVM 9 ");
+ const scanner = new LabeledStringScanner();
+ scanner.push(Buffer.from("Dart VM version: 3.1\0Dart VM version: 3.2\0"));
+ expect(scanner.result()).toMatchObject({
+ dartVersion: "Dart VM version: 3.1",
+ dartVersionCapped: true,
+ toolchainCapped: false,
+ });
+ });
+});
diff --git a/src/flutter/FlutterPayloadScan.ts b/src/flutter/FlutterPayloadScan.ts
new file mode 100644
index 000000000..e1a69d594
--- /dev/null
+++ b/src/flutter/FlutterPayloadScan.ts
@@ -0,0 +1,217 @@
+import { Buffer } from "node:buffer";
+
+/**
+ * Streaming scanners for Flutter payload libraries inside an APK.
+ *
+ * All facts are observations of byte patterns at read time: the Dart
+ * snapshot hash sits 20 bytes after each snapshot magic, the GNU build-id
+ * is an ELF note, and version facts are labeled ASCII strings. Nothing is
+ * inferred or looked up externally.
+ */
+
+/** First index of `needle` in `haystack` at or after `from`, or -1. */
+const findBytes = (
+ haystack: Uint8Array,
+ needle: Uint8Array,
+ from: number,
+): number => {
+ if (needle.length === 0) return from;
+ const last = haystack.length - needle.length;
+ for (let index = from; index <= last; index += 1) {
+ let matched = true;
+ for (let probe = 0; probe < needle.length; probe += 1) {
+ if (haystack[index + probe] !== needle[probe]) {
+ matched = false;
+ break;
+ }
+ }
+ if (matched) return index;
+ }
+ return -1;
+};
+
+/** Magic starting every Dart VM and isolate snapshot section. */
+export const DART_SNAPSHOT_MAGIC = Uint8Array.from([0xf5, 0xf5, 0xdc, 0xdc]);
+export const SNAPSHOT_HASH_OFFSET = 20;
+export const SNAPSHOT_HASH_LENGTH = 32;
+export const SNAPSHOT_HASH_PATTERN = /^[0-9a-f]{32}$/u;
+
+export interface SnapshotHashScan {
+ /** Snapshot sections found. */
+ readonly sources: number;
+ readonly capped: boolean;
+ /** Distinct 32-hex hashes following the magic, in first-seen order. */
+ readonly candidates: readonly string[];
+}
+
+/**
+ * Incremental scanner for Dart snapshot magics and the hash that follows.
+ * Feed chunks in order; a trailing carry keeps a magic-to-hash span that a
+ * chunk boundary would otherwise split.
+ */
+/** Hard cap on distinct hashes retained before partial coverage reports. */
+export const MAX_SNAPSHOT_HASH_CANDIDATES = 64;
+
+export class SnapshotHashScanner {
+ #sources = 0;
+ #capped = false;
+ private readonly candidates: string[] = [];
+ private readonly candidateSet = new Set<string>();
+ #buffer = new Uint8Array(0);
+ /** Absolute stream offset from which unprocessed bytes begin. */
+ #base = 0;
+ #absoluteScanFrom = 0;
+
+ push(chunk: Uint8Array): void {
+ const joined = new Uint8Array(this.#buffer.length + chunk.length);
+ joined.set(this.#buffer, 0);
+ joined.set(chunk, this.#buffer.length);
+ // Resume after the last fully processed hash so carried bytes are not
+ // counted twice across chunk boundaries.
+ let offset = Math.max(0, this.#absoluteScanFrom - this.#base);
+ let pendingMagic: number | null = null;
+ for (;;) {
+ const magic = findBytes(joined, DART_SNAPSHOT_MAGIC, offset);
+ if (magic === -1) break;
+ if (magic + SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH > joined.length) {
+ pendingMagic = magic;
+ break;
+ }
+ const candidate = Buffer.from(
+ joined.slice(
+ magic + SNAPSHOT_HASH_OFFSET,
+ magic + SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH,
+ ),
+ ).toString("latin1");
+ const isValidHash = SNAPSHOT_HASH_PATTERN.test(candidate);
+ if (isValidHash && !this.candidateSet.has(candidate)) {
+ if (this.candidates.length === MAX_SNAPSHOT_HASH_CANDIDATES)
+ this.#capped = true;
+ else {
+ this.candidateSet.add(candidate);
+ this.candidates.push(candidate);
+ }
+ }
+ // Only valid hash records count toward source agreement; a complete
+ // magic record whose field is not lowercase hex is not a source.
+ if (isValidHash) this.#sources += 1;
+ offset = magic + DART_SNAPSHOT_MAGIC.length;
+ this.#absoluteScanFrom =
+ this.#base + magic + SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH;
+ }
+ // Keep a pending magic for the next chunk; otherwise keep only the
+ // trailing bytes where a magic could still begin, so magic-free
+ // streams never accumulate.
+ const keepFrom =
+ pendingMagic ??
+ Math.max(
+ this.#absoluteScanFrom - this.#base,
+ joined.length - (DART_SNAPSHOT_MAGIC.length - 1),
+ );
+ this.#buffer = joined.slice(keepFrom);
+ this.#base += keepFrom;
+ if (pendingMagic !== null) this.#absoluteScanFrom = this.#base;
+ }
+
+ result(): SnapshotHashScan {
+ return {
+ sources: this.#sources,
+ candidates: [...this.candidates],
+ capped: this.#capped,
+ };
+ }
+}
+
+/** Labeled strings worth reporting when a build carries them. */
+export interface LabeledStringScan {
+ readonly dartVersion: string | null;
+ readonly dartVersionCapped: boolean;
+ readonly toolchainLines: readonly string[];
+ /** True when further distinct matching lines were observed past the cap. */
+ readonly toolchainCapped: boolean;
+}
+
+const DART_VERSION_PATTERN = /^Dart VM version:[^\x00\n]{0,200}$/u;
+const TOOLCHAIN_PATTERN =
+ /^(?:Android \([^)\x00\n]{0,80}\) clang version [^\x00\n]{0,500}|based on LLVM \d[^\x00\n]{0,80})$/u;
+const MAX_TOOLCHAIN_LINES = 4;
+/**
+ * Carry spans chunk boundaries for either accepted pattern. The toolchain
+ * pattern accepts up to 605 printable bytes (9 + 80 + 16 + 500), so the
+ * carry must hold at least that to preserve a line split at a boundary.
+ */
+const CARRY_BYTES = 640;
+
+/**
+ * Incremental ASCII string collector that keeps only labeled version and
+ * toolchain facts. A match is committed only when a printable run is
+ * terminated by a delimiter, so a value split across chunk boundaries is
+ * never committed truncated; the carry holds the longest accepted match
+ * so boundaries in either pattern survive.
+ */
+export class LabeledStringScanner {
+ #dartVersion: string | null = null;
+ #dartVersionCapped = false;
+ private readonly toolchainLines: string[] = [];
+ private carry = "";
+ private overflowed = false;
+ #ended = false;
+ #toolchainCapped = false;
+
+ push(chunk: Uint8Array): void {
+ for (const byte of chunk) {
+ if (byte >= 0x20 && byte < 0x7f) {
+ if (this.carry.length < CARRY_BYTES)
+ this.carry += String.fromCharCode(byte);
+ else this.overflowed = true;
+ } else {
+ this.#consider(this.carry);
+ this.carry = "";
+ this.overflowed = false;
+ }
+ }
+ }
+
+ /** Commit any retained tail, e.g. when the stream ends mid-string. */
+ end(): void {
+ if (this.#ended) return;
+ this.#ended = true;
+ this.#consider(this.carry);
+ this.carry = "";
+ this.overflowed = false;
+ }
+
+ #consider(text: string): void {
+ // Keep a bounded prefix plus overflow state, never a sliding suffix.
+ // Every accepted label must consume its whole printable run so a
+ // pattern's shorter grammar cannot publish a fabricated prefix.
+ if (text.startsWith("Dart VM version:")) {
+ if (this.overflowed || !DART_VERSION_PATTERN.test(text))
+ this.#dartVersionCapped = true;
+ else if (this.#dartVersion === null) this.#dartVersion = text;
+ else if (this.#dartVersion !== text) this.#dartVersionCapped = true;
+ return;
+ }
+ if (!text.startsWith("Android (") && !text.startsWith("based on LLVM "))
+ return;
+ if (this.overflowed || !TOOLCHAIN_PATTERN.test(text)) {
+ this.#toolchainCapped = true;
+ return;
+ }
+ const line = text;
+ if (this.toolchainLines.includes(line)) return;
+ if (this.toolchainLines.length < MAX_TOOLCHAIN_LINES)
+ this.toolchainLines.push(line);
+ else this.#toolchainCapped = true;
+ }
+
+ result(): LabeledStringScan {
+ if (!this.#ended) this.end();
+ return {
+ dartVersion: this.#dartVersion,
+ dartVersionCapped: this.#dartVersionCapped,
+ toolchainLines: [...this.toolchainLines],
+ toolchainCapped: this.#toolchainCapped,
+ };
+ }
+}
diff --git a/src/server/createServer.ts b/src/server/createServer.ts
index 5a9fac0db..ec7a9f231 100644
--- a/src/server/createServer.ts
+++ b/src/server/createServer.ts
@@ -75,6 +75,7 @@ import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnaly
import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
import { registerAndroidTools } from "./registerAndroidTools.js";
import { registerApktoolTools } from "./registerApktoolTools.js";
+import { registerFlutterTools } from "./registerFlutterTools.js";
import { registerJebTools } from "./registerJebTools.js";
import { registerAdbTools } from "./registerAdbTools.js";
import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
@@ -82,8 +83,11 @@ import { JebAnalysisService } from "../application/jeb/JebAnalysisService.js";
import type { AndroidAnalysisPort } from "../application/android/AndroidAnalysisPort.js";
import type { ApktoolResourceAnalysisPort } from "../application/apktool/ApktoolResourceAnalysisPort.js";
import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";
+import type { FlutterBuildAnalysisPort } from "../application/flutter/FlutterBuildAnalysisPort.js";
+import { FlutterBuildAnalysisService } from "../application/flutter/FlutterBuildAnalysisService.js";
import { createAndroidAnalysisProvider } from "../composition/android.js";
import { createApktoolResourceAnalysisProvider } from "../composition/apktool.js";
+import { createFlutterBuildAnalysisProvider } from "../composition/flutter.js";
import type { JebAnalysisPort } from "../application/jeb/JebAnalysisPort.js";
import { createJebAnalysisProvider } from "../composition/jeb.js";
import type { AdbDeviceAnalysisPort } from "../application/adb/AdbDeviceAnalysisPort.js";
@@ -126,6 +130,7 @@ export interface CreateServerOptions {
readonly webNetworkCapture?: WebNetworkCaptureService;
readonly androidAnalysis?: AndroidAnalysisPort;
readonly apktoolAnalysis?: ApktoolResourceAnalysisPort;
+ readonly flutterAnalysis?: FlutterBuildAnalysisPort;
readonly jebAnalysis?: JebAnalysisPort;
readonly adbDeviceAnalysis?: AdbDeviceAnalysisPort;
readonly browserObservation?: BrowserObservationPort;
@@ -266,6 +271,8 @@ export const createServer = (
);
const android =
options.androidAnalysis ?? createAndroidAnalysisProvider(environment);
+ const flutter =
+ options.flutterAnalysis ?? createFlutterBuildAnalysisProvider();
const fridaInstrumentation =
options.fridaInstrumentation ?? new FridaInstrumentationManager();
const wasmArtifact = wasmArtifactModule.create(
@@ -287,6 +294,7 @@ export const createServer = (
apktool.close(),
jeb.close(),
adbDevice.close(),
+ flutter.close(),
evmInterface.close(),
webSourceLocation.close(),
webModuleTrace.close(),
@@ -374,6 +382,13 @@ export const createServer = (
recordEvidence,
analysisAdmission,
);
+ registerFlutterTools(
+ server,
+ new FlutterBuildAnalysisService(flutter),
+ toolLogger,
+ recordEvidence,
+ analysisAdmission,
+ );
registerApktoolTools(
server,
new ApktoolResourceAnalysisService(apktool),
diff --git a/src/server/registerFlutterTools.ts b/src/server/registerFlutterTools.ts
new file mode 100644
index 000000000..5b601c5f7
--- /dev/null
+++ b/src/server/registerFlutterTools.ts
@@ -0,0 +1,35 @@
+import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
+import { FlutterBuildAnalysisService } from "../application/flutter/FlutterBuildAnalysisService.js";
+import { toolContract } from "../contracts/toolContracts.js";
+import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
+import type { Logger } from "pino";
+import { createContractToolHandler } from "./contractToolHandler.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+
+/** Bind Flutter handlers to their exact named contracts through admission. */
+export const registerFlutterTools = (
+ server: EvidenceMcpServer,
+ service: FlutterBuildAnalysisService,
+ logger: Logger,
+ recordEvidence?: EvidenceWriter["recordEvidence"],
+ withAdmittedAnalysis?: WithAdmittedAnalysis,
+): void => {
+ const handler = createContractToolHandler(
+ server,
+ service,
+ logger,
+ recordEvidence,
+ withAdmittedAnalysis,
+ );
+ for (const contract of [
+ toolContract("identify_flutter_build"),
+ toolContract("inspect_dart_aot"),
+ ] as const) {
+ server.registerTool(
+ contract.name,
+ toolRegistrationOptions(contract),
+ handler(contract),
+ );
+ }
+};
diff --git a/tests/acceptance/flutterAnalysis.test.ts b/tests/acceptance/flutterAnalysis.test.ts
new file mode 100644
index 000000000..457dce96b
--- /dev/null
+++ b/tests/acceptance/flutterAnalysis.test.ts
@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { expect } from "vitest";
+import { toolContract } from "../../src/contracts/toolContracts.js";
+import { parseEvidence } from "../../src/domain/evidence.js";
+import {
+ aotFixtureImage,
+ engineFixtureImage,
+ REFERENCE_HASH,
+} from "../../src/flutter/FlutterBuild.fixture.js";
+import {
+ createFlutterApk,
+ createDuplicateFlutterApk,
+} from "../fixtures/flutterApk.js";
+import { connectLocalToolsMcp } from "../fixtures/localToolsMcp.js";
+import { parseMcpToolError } from "../fixtures/mcpToolError.js";
+import { cliTest } from "../support/cli/cliFixture.js";
+
+cliTest(
+ "CLI and stdio MCP retain Flutter identity, selected ABI and duplicate-member refusals",
+ async ({ cli }) => {
+ const image = aotFixtureImage();
+ Buffer.from("Login\0").copy(image, 0x2300);
+ const engine = engineFixtureImage({
+ notes: Buffer.from(
+ "040000000800000003000000474e55000123456789abcdef",
+ "hex",
+ ),
+ prefix: Buffer.from(
+ "040000000800000003000000474e55001111111111111111",
+ "hex",
+ ),
+ labels: ["Android (test) clang version 9.0.8"],
+ });
+ const path = await createFlutterApk("selected target.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: image },
+ {
+ path: "lib/arm64-v8a/libflutter.so",
+ bytes: engine,
+ },
+ { path: "lib/x86_64/libapp.so", bytes: image },
+ {
+ path: "lib/x86_64/libflutter.so",
+ bytes: engine,
+ },
+ ]);
+ const { call } = await connectLocalToolsMcp();
+ for (const [name, abi] of [
+ ["identify_flutter_build", undefined],
+ ["inspect_dart_aot", undefined],
+ ["inspect_dart_aot", "x86_64"],
+ ] as const) {
+ const result = await cli.run({
+ arguments: [
+ name.replaceAll("_", "-"),
+ path,
+ "--json",
+ ...(abi === undefined ? [] : ["--abi", abi]),
+ ],
+ });
+ expect(result.exitCode, result.stderr).toBe(0);
+ const evidence = toolContract(name).outputSchema.parse(result.json);
+ const response = await call(name, {
+ path,
+ ...(abi === undefined ? {} : { abi }),
+ });
+ expect(response.isError, JSON.stringify(response)).not.toBe(true);
+ const mcp = parseEvidence(response.structuredContent);
+ expect(mcp.normalized_result).toEqual(evidence.normalized_result);
+ expect(mcp.subject).toEqual(evidence.subject);
+ expect(mcp.subject).toMatchObject({
+ local_path: path,
+ format: "apk",
+ digest: { sha256: evidence.normalized_result.target.sha256 },
+ });
+ expect(mcp.evidence_id).toBe(evidence.evidence_id);
+ if (name === "inspect_dart_aot") {
+ expect(evidence.normalized_result).toMatchObject({
+ abi: abi ?? "arm64-v8a",
+ libapp: {
+ coverage: "complete",
+ snapshot_hash: REFERENCE_HASH,
+ sha256: createHash("sha256").update(image).digest("hex"),
+ },
+ string_pool: {
+ coverage: "complete",
+ class_like_tokens: expect.arrayContaining(["Login"]),
+ },
+ });
+ } else {
+ const identified = toolContract(
+ "identify_flutter_build",
+ ).outputSchema.parse(result.json).normalized_result;
+ expect(identified.coverage).toBe("complete");
+ for (const abi of identified.abis) {
+ expect(abi.libflutter).toMatchObject({
+ build_id: "0123456789abcdef",
+ build_id_candidates: ["0123456789abcdef"],
+ });
+ }
+ }
+ }
+ const duplicate = await createDuplicateFlutterApk();
+ for (const name of [
+ "identify_flutter_build",
+ "inspect_dart_aot",
+ ] as const) {
+ const result = await cli.run({
+ arguments: [name.replaceAll("_", "-"), duplicate, "--json"],
+ });
+ expect(result.exitCode).toBe(1);
+ const mcp = parseMcpToolError(await call(name, { path: duplicate }));
+ expect(mcp.error).toEqual(result.json);
+ expect(mcp.error).toMatchObject({
+ code: "invalid_request",
+ details: { issues: [{ message: expect.stringContaining(duplicate) }] },
+ });
+ }
+ },
+);
+
+cliTest(
+ "CLI and MCP retain unsupported snapshot kinds as partial evidence",
+ async ({ cli }) => {
+ const image = aotFixtureImage();
+ for (const offset of [0x1000, 0x2000])
+ image.writeBigUInt64LE(4n, offset + 12);
+ const path = await createFlutterApk("unsupported-kind.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: image },
+ ]);
+ const result = await cli.run({
+ arguments: ["inspect-dart-aot", path, "--json"],
+ });
+ expect(result.exitCode, result.stderr).toBe(0);
+ const evidence = toolContract("inspect_dart_aot").outputSchema.parse(
+ result.json,
+ );
+ const { call } = await connectLocalToolsMcp();
+ const response = await call("inspect_dart_aot", { path });
+ expect(response.isError, JSON.stringify(response)).not.toBe(true);
+ expect(parseEvidence(response.structuredContent).normalized_result).toEqual(
+ evidence.normalized_result,
+ );
+ expect(evidence.normalized_result).toMatchObject({
+ coverage: "partial",
+ libapp: { coverage: "partial", snapshot_hash: REFERENCE_HASH },
+ string_pool: { coverage: "complete" },
+ });
+ expect(
+ evidence.normalized_result.libapp.sections
+ .filter((section) => section.name.endsWith("Data"))
+ .map((section) => section.kind),
+ ).toEqual([4, 4]);
+ },
+);
diff --git a/tests/boundary/cli/flutterCli.test.ts b/tests/boundary/cli/flutterCli.test.ts
new file mode 100644
index 000000000..e9e32c99d
--- /dev/null
+++ b/tests/boundary/cli/flutterCli.test.ts
@@ -0,0 +1,21 @@
+import { expect, it } from "vitest";
+
+import { serveCli } from "./cliServeHarness.js";
+
+it.each(["identify-flutter-build", "inspect-dart-aot"])(
+ "%s advertises a schema through the public CLI",
+ async (command) => {
+ const result = await serveCli([command, "--schema", "--json"]);
+ expect(result.exitCode).toBe(0);
+ expect(JSON.parse(result.stdout)).toBeTruthy();
+ },
+);
+
+it("reports an unreadable target with an input refusal", async () => {
+ const result = await serveCli([
+ "identify-flutter-build",
+ "/nonexistent/app.apk",
+ "--json",
+ ]);
+ expect(result.stdout).toContain("invalid_request");
+});
diff --git a/tests/boundary/filesystem/flutterBuildProvider.test.ts b/tests/boundary/filesystem/flutterBuildProvider.test.ts
new file mode 100644
index 000000000..4a1c8248f
--- /dev/null
+++ b/tests/boundary/filesystem/flutterBuildProvider.test.ts
@@ -0,0 +1,1332 @@
+import { createReadStream } from "node:fs";
+import { open, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { Uint8ArrayReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js";
+import { expect, it, onTestFinished, vi } from "vitest";
+
+import {
+ aotFixtureImage,
+ engineFixtureImage,
+ buildElf64Image,
+ REFERENCE_HASH,
+} from "../../../src/flutter/FlutterBuild.fixture.js";
+import { snapshotSection } from "../../../src/flutter/FlutterBuild.fixture.js";
+import { FlutterBuildProvider } from "../../../src/flutter/FlutterBuildProvider.js";
+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
+import {
+ AnalysisCancelledError,
+ AnalysisResourceConstraintError,
+} from "../../../src/domain/analysisErrorCore.js";
+import {
+ flutterResultSchemas,
+ type FlutterOperation,
+} from "../../../src/domain/flutter/flutterBuildAnalysis.js";
+import { ZipArtifactReader } from "../../../src/artifacts/ZipArtifactReader.js";
+import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
+import {
+ createFlutterApk as buildApk,
+ createDuplicateFlutterApk,
+} from "../../fixtures/flutterApk.js";
+import * as regularFile from "../../../src/filesystem/RegularFile.js";
+import * as fsPromises from "node:fs/promises";
+import * as dartElf from "../../../src/flutter/DartElf.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+
+vi.mock("node:fs", async (importOriginal) => {
+ const original = await importOriginal<typeof import("node:fs")>();
+ return { ...original, createReadStream: vi.fn(original.createReadStream) };
+});
+vi.mock("node:fs/promises", async (importOriginal) => {
+ const original = await importOriginal<typeof import("node:fs/promises")>();
+ return { ...original };
+});
+
+const buildIdNote = (): Buffer =>
+ Buffer.concat([
+ Buffer.from([4, 0, 0, 0, 20, 0, 0, 0, 3, 0, 0, 0, 0x47, 0x4e, 0x55, 0]),
+ Buffer.from([
+ 0xe8, 0xd9, 0x07, 0xef, 0x7c, 0x17, 0x5e, 0xc4, 0x31, 0x3f, 0x47, 0x11,
+ 0x10, 0x19, 0xad, 0xc9, 0x58, 0x8c, 0x5f, 0x61,
+ ]),
+ ]);
+
+const TOOLCHAIN_LINE =
+ "Android (5900059 based on r365631c) clang version 9.0.8 (based on LLVM 9.0.8svn)";
+
+const libapp = aotFixtureImage;
+
+const libflutter = (): Buffer =>
+ engineFixtureImage({ notes: buildIdNote(), labels: [TOOLCHAIN_LINE] });
+
+/**
+ * Self-contained Dart AOT image: a synthetic ELF64 carrying the four
+ * snapshot symbols, two snapshot sections, and a string pool, so goldens
+ * do not depend on any file outside the repository.
+ */
+const aotImage = aotFixtureImage;
+
+/** Two data symbols at one offset and size: aliased exports. */
+const aliasedDataImage = (): Buffer => {
+ const elf = buildElf64Image([
+ { name: "_kDartVmSnapshotData", value: 0x1000, size: 52 },
+ { name: "_kDartIsolateSnapshotData", value: 0x1000, size: 52 },
+ ]);
+ return Buffer.concat([
+ elf,
+ Buffer.alloc(0x1000 - elf.length),
+ snapshotSection(REFERENCE_HASH),
+ ]);
+};
+
+/** Two data symbols whose snapshot hashes disagree. */
+const conflictingHashImage = (): Buffer => {
+ const elf = buildElf64Image([
+ { name: "_kDartVmSnapshotData", value: 0x1000, size: 52 },
+ { name: "_kDartIsolateSnapshotData", value: 0x1200, size: 52 },
+ ]);
+ const vm = snapshotSection("11111111111111111111111111111111");
+ const isolate = snapshotSection("22222222222222222222222222222222");
+ return Buffer.concat([
+ elf,
+ Buffer.alloc(0x1000 - elf.length),
+ vm,
+ Buffer.alloc(0x1200 - 0x1000 - vm.length),
+ isolate,
+ ]);
+};
+
+const analyzeImage = async (bytes: Buffer, operation: FlutterOperation) => {
+ const path = await buildApk("image.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes },
+ { path: "lib/arm64-v8a/libflutter.so", bytes: libflutter() },
+ ]);
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({ operation, input: { path } });
+ if (!result.ok) throw result.error;
+ return result.value;
+};
+
+it.each([32, 64] as const)(
+ "reads only ELF-owned notes in an ELF%s engine",
+ async (bits) => {
+ const fake = Buffer.from(buildIdNote());
+ fake.fill(0x11, 16);
+ for (const ownership of ["program", "section", "both"] as const) {
+ const path = await buildApk("owned-notes.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ {
+ path: "lib/arm64-v8a/libflutter.so",
+ bytes: engineFixtureImage({
+ bits,
+ ownership,
+ prefix: fake,
+ notes: buildIdNote(),
+ }),
+ },
+ ]);
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (!result.ok) throw result.error;
+ const value = flutterResultSchemas.identify_flutter_build.parse(
+ result.value.result,
+ );
+ expect(value.coverage).toBe("complete");
+ expect(value.abis[0]!.libflutter).toMatchObject({
+ build_id: "e8d907ef7c175ec4313f47111019adc9588c5f61",
+ build_id_candidates: ["e8d907ef7c175ec4313f47111019adc9588c5f61"],
+ });
+ }
+ },
+);
+
+it.each(["conflicting", "truncated", "capacity"] as const)(
+ "preserves %s engine-note uncertainty",
+ async (shape) => {
+ const second = Buffer.from(buildIdNote());
+ second.fill(0x11, 16);
+ const notes =
+ shape === "conflicting"
+ ? Buffer.concat([buildIdNote(), second])
+ : shape === "truncated"
+ ? Buffer.concat([buildIdNote(), Buffer.from([1])])
+ : Buffer.concat(
+ Array.from({ length: 65 }, (_, index) => {
+ const note = Buffer.from(buildIdNote());
+ note.writeUInt32LE(index, 16);
+ return note;
+ }),
+ );
+ const path = await buildApk("uncertain-notes.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ {
+ path: "lib/arm64-v8a/libflutter.so",
+ bytes: engineFixtureImage({ notes }),
+ },
+ ]);
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (!result.ok) throw result.error;
+ const value = flutterResultSchemas.identify_flutter_build.parse(
+ result.value.result,
+ );
+ expect(value.coverage).toBe("partial");
+ expect(value.abis[0]!.libflutter.build_id).toBeNull();
+ expect(value.abis[0]!.libflutter.build_id_candidates).toHaveLength(
+ shape === "conflicting" ? 2 : shape === "truncated" ? 1 : 64,
+ );
+ },
+);
+
+it.each([0, 1, 2, 4, 0xffff])(
+ "retains snapshot kind %s with partial decoding coverage",
+ async (kind) => {
+ const image = aotImage();
+ image.writeBigUInt64LE(BigInt(kind), 0x1000 + 12);
+ image.writeBigUInt64LE(BigInt(kind), 0x2000 + 12);
+ const execution = await analyzeImage(image, "inspect_dart_aot");
+ const value = flutterResultSchemas.inspect_dart_aot.parse(execution.result);
+ expect(value).toMatchObject({
+ coverage: "partial",
+ libapp: { coverage: "partial" },
+ string_pool: { coverage: "complete" },
+ });
+ expect(
+ value.libapp.sections
+ .filter((section) => section.name.endsWith("Data"))
+ .map((section) => section.kind),
+ ).toEqual([kind, kind]);
+ expect(value.libapp.snapshot_hash).toBe(REFERENCE_HASH);
+ },
+);
+
+it.each(["absent", "range", "metadata-budget"] as const)(
+ "preserves %s engine-note coverage at the ELF boundary",
+ async (shape) => {
+ const engine = engineFixtureImage({
+ notes:
+ shape === "metadata-budget"
+ ? Buffer.alloc(8 * 1024 * 1024)
+ : Buffer.alloc(0),
+ });
+ if (shape === "range")
+ engine.writeBigUInt64LE(BigInt(engine.length + 1), 64 + 56 + 8);
+ const path = await buildApk("note-bounds.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ { path: "lib/arm64-v8a/libflutter.so", bytes: engine },
+ ]);
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (!result.ok) throw result.error;
+ const value = flutterResultSchemas.identify_flutter_build.parse(
+ result.value.result,
+ );
+ expect(value.coverage).toBe(shape === "absent" ? "complete" : "partial");
+ expect(value.abis[0]!.libflutter).toMatchObject({
+ build_id: null,
+ build_id_candidates: [],
+ });
+ if (shape !== "absent")
+ expect(result.value.limitations.join(" ")).toContain(
+ shape === "range" ? "not file-backed" : "metadata budget",
+ );
+ },
+);
+
+it.each([
+ ["root", "EACCES"],
+ ["open", "EPERM"],
+ ["write", "ENOSPC"],
+ ["close", "EIO"],
+ ["chmod", "EACCES"],
+ ["stat", "EIO"],
+ ["digest", "EACCES"],
+ ["zip-library", "EIO"],
+] as const)(
+ "classifies owned snapshot %s failure (%s) separately from source input",
+ async (stage, code) => {
+ const path = await buildApk("owned-io.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const cause = Object.assign(new Error("owned snapshot failure"), { code });
+ const native =
+ await vi.importActual<typeof import("node:fs/promises")>(
+ "node:fs/promises",
+ );
+ if (stage === "zip-library")
+ vi.spyOn(ZipArtifactReader.prototype, "open").mockRejectedValueOnce(
+ cause,
+ );
+ if (stage === "root")
+ vi.spyOn(fsPromises, "mkdtemp").mockRejectedValueOnce(cause);
+ if (stage === "chmod")
+ vi.spyOn(fsPromises, "chmod").mockRejectedValueOnce(cause);
+ if (stage === "stat")
+ vi.spyOn(fsPromises, "stat").mockImplementation((...args) => {
+ if (args[0] !== path) return Promise.reject(cause);
+ return native.stat(...args);
+ });
+ if (["open", "write", "close"].includes(stage))
+ vi.spyOn(fsPromises, "open").mockImplementation(async (...args) => {
+ if (args[1] === "wx" && stage === "open") throw cause;
+ const handle = await native.open(...args);
+ if (args[1] === "wx") {
+ if (stage === "write")
+ vi.spyOn(handle, "writeFile").mockRejectedValueOnce(cause);
+ if (stage === "close")
+ vi.spyOn(handle, "close").mockRejectedValueOnce(cause);
+ }
+ return handle;
+ });
+ if (stage === "digest")
+ vi.mocked(createReadStream).mockImplementation(
+ () =>
+ Readable.from(
+ (async function* () {
+ yield Buffer.alloc(0);
+ throw cause;
+ })(),
+ ) as ReturnType<typeof createReadStream>,
+ );
+ onTestFinished(() => {
+ vi.restoreAllMocks();
+ vi.mocked(createReadStream).mockReset();
+ });
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (result.ok) throw new Error("expected owned I/O failure");
+ expect(projectAnalysisError(result.error).code).toBe("resource_constraint");
+ expect(result.error.cause).toBe(cause);
+ expect(result.error.message).toContain(
+ "Provider-owned Flutter snapshot storage",
+ );
+ },
+);
+
+it.each(["close", "elf", "pool", "cleanup"] as const)(
+ "honors cancellation during final %s work",
+ async (stage) => {
+ const path = await buildApk("late-cancellation.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const controller = new AbortController();
+ const originalClose = OwnedFileHandle.prototype.close;
+ let closed = 0;
+ vi.spyOn(OwnedFileHandle.prototype, "close").mockImplementation(
+ async function (this: OwnedFileHandle) {
+ await originalClose.call(this);
+ if (++closed === 4) {
+ if (stage === "close") controller.abort();
+ if (stage === "elf") setImmediate(() => controller.abort());
+ }
+ },
+ );
+ if (stage === "pool") {
+ const original = dartElf.readElfSymbols;
+ vi.spyOn(dartElf, "readElfSymbols").mockImplementation(
+ async (...args) => {
+ const value = await original(...args);
+ setImmediate(() => controller.abort());
+ return value;
+ },
+ );
+ }
+ onTestFinished(() => {
+ vi.restoreAllMocks();
+ });
+ const provider = new FlutterBuildProvider({
+ removeRoot: async (root) => {
+ await rm(root, { recursive: true, force: true });
+ if (stage === "cleanup") controller.abort();
+ },
+ });
+ onTestFinished(() => provider.close());
+ const result = await provider.execute(
+ { operation: "inspect_dart_aot", input: { path } },
+ { signal: controller.signal },
+ );
+ if (result.ok) throw new Error("late cancellation must prevent success");
+ expect(projectAnalysisError(result.error).code).toBe("cancelled");
+ },
+);
+
+it("projects each payload shape through the owned snapshot", async () => {
+ const hash = REFERENCE_HASH;
+ const agreeBoth = await buildApk("agree.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: libapp(hash) },
+ { path: "lib/arm64-v8a/libflutter.so", bytes: libflutter() },
+ { path: "lib/x86_64/libapp.so", bytes: libapp(hash) },
+ { path: "lib/x86_64/libflutter.so", bytes: libflutter() },
+ ]);
+ const half = await buildApk("half.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: libapp(hash) },
+ ]);
+ const disagree = await buildApk("disagree.apk", [
+ {
+ path: "lib/arm64-v8a/libapp.so",
+ bytes: Buffer.concat([
+ snapshotSection("11111111111111111111111111111111"),
+ snapshotSection("22222222222222222222222222222222"),
+ ]),
+ },
+ { path: "lib/arm64-v8a/libflutter.so", bytes: libflutter() },
+ ]);
+ const plain = await buildApk("plain.apk", [
+ { path: "classes.dex", bytes: Buffer.from("dex\n0123456789") },
+ { path: "lib/arm64-v8a/libnative.so", bytes: Buffer.from("plain-elf") },
+ ]);
+ const provider = new FlutterBuildProvider();
+ const identify = async (apk: string) => {
+ const outcome = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path: apk },
+ });
+ if (!outcome.ok) throw new Error(outcome.error.message);
+ return outcome.value.result as {
+ flutter_detected: boolean;
+ coverage: string;
+ abis: {
+ abi: string;
+ libapp: {
+ present: boolean;
+ snapshot_hash: string | null;
+ snapshot_hash_sources: number;
+ snapshot_hash_candidates: string[];
+ };
+ libflutter: { present: boolean; build_id: string | null };
+ }[];
+ };
+ };
+
+ const both = await identify(agreeBoth);
+ expect(both.flutter_detected).toBe(true);
+ expect(both.coverage).toBe("complete");
+ expect(both.abis.map((abi) => abi.abi)).toEqual(["arm64-v8a", "x86_64"]);
+ for (const abi of both.abis) {
+ expect(abi.libapp.snapshot_hash).toBe(hash);
+ expect(abi.libapp.snapshot_hash_sources).toBe(2);
+ expect(abi.libflutter.build_id).toBe(
+ "e8d907ef7c175ec4313f47111019adc9588c5f61",
+ );
+ }
+
+ const engineless = await identify(half);
+ expect(engineless.coverage).toBe("partial");
+ expect(engineless.abis[0]?.libapp.present).toBe(true);
+ expect(engineless.abis[0]?.libflutter.present).toBe(false);
+
+ const conflicted = await identify(disagree);
+ expect(conflicted.coverage).toBe("partial");
+ expect(conflicted.abis[0]?.libapp.snapshot_hash).toBeNull();
+ expect(conflicted.abis[0]?.libapp.snapshot_hash_candidates).toEqual([
+ "11111111111111111111111111111111",
+ "22222222222222222222222222222222",
+ ]);
+
+ const negative = await identify(plain);
+ expect(negative.flutter_detected).toBe(false);
+ expect(negative.abis).toEqual([]);
+ expect(negative.coverage).toBe("complete");
+});
+
+it("rejects a target that is not a readable file", async () => {
+ const projected = await (async () => {
+ const result = await new FlutterBuildProvider().execute({
+ operation: "identify_flutter_build",
+ input: { path: "/nonexistent/app.apk" },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) throw new Error("expected a refusal");
+ return projectAnalysisError(result.error);
+ })();
+ expect(projected).toMatchObject({ code: "invalid_request" });
+});
+
+it("refuses an APK without a Dart payload", async () => {
+ const apk = await buildApk("noflutter.apk", [
+ { path: "classes.dex", bytes: Buffer.from("dex\n0123456789") },
+ ]);
+ const result = await new FlutterBuildProvider().execute({
+ operation: "inspect_dart_aot",
+ input: { path: apk },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "unsupported_target",
+ });
+});
+
+it("refuses a requested ABI the payload does not carry", async () => {
+ const apk = await buildApk("oneabi.apk", [
+ {
+ path: "lib/arm64-v8a/libapp.so",
+ bytes: libapp(REFERENCE_HASH),
+ },
+ ]);
+ const result = await new FlutterBuildProvider().execute({
+ operation: "inspect_dart_aot",
+ input: { path: apk, abi: "x86_64" },
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "unsupported_target",
+ });
+ expect(result.error.message).toContain("arm64-v8a");
+});
+
+it("inspects a full synthetic AOT image end to end", async () => {
+ const apk = await buildApk("realgallery.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const result = await new FlutterBuildProvider().execute({
+ operation: "inspect_dart_aot",
+ input: { path: apk },
+ });
+ if (!result.ok) throw new Error(result.error.message);
+ const value = result.value.result as {
+ abi: string;
+ libapp: {
+ snapshot_hash: string | null;
+ snapshot_hash_candidates: string[];
+ snapshot_hash_sources: number;
+ sections: { name: string; magic_valid: boolean }[];
+ };
+ string_pool: {
+ package_uri_count_at_least: number;
+ dart_uri_count_at_least: number;
+ };
+ coverage: string;
+ };
+ expect(value.abi).toBe("arm64-v8a");
+ expect(value.libapp.snapshot_hash).toBe(REFERENCE_HASH);
+ expect(value.libapp.snapshot_hash_candidates).toEqual([REFERENCE_HASH]);
+ expect(value.libapp.snapshot_hash_sources).toBe(2);
+ expect(value.libapp.sections.map((section) => section.name)).toEqual([
+ "_kDartVmSnapshotData",
+ "_kDartVmSnapshotInstructions",
+ "_kDartIsolateSnapshotData",
+ "_kDartIsolateSnapshotInstructions",
+ ]);
+ expect(
+ value.libapp.sections
+ .filter((section) => section.name.endsWith("Data"))
+ .every((section) => section.magic_valid),
+ ).toBe(true);
+ expect(value.string_pool.package_uri_count_at_least).toBe(2);
+ expect(value.string_pool.dart_uri_count_at_least).toBe(2);
+ // All four symbols present, both data magics valid, pool under budget:
+ // the honest answer for a complete payload is complete coverage.
+ expect(value.coverage).toBe("complete");
+});
+
+it("reports aliased snapshot data symbols as partial coverage", async () => {
+ const apk = await buildApk("aliased.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aliasedDataImage() },
+ ]);
+ const result = await new FlutterBuildProvider().execute({
+ operation: "inspect_dart_aot",
+ input: { path: apk },
+ });
+ if (!result.ok) throw new Error(result.error.message);
+ const value = result.value.result as {
+ coverage: string;
+ libapp: {
+ snapshot_hash: string | null;
+ snapshot_hash_candidates: string[];
+ snapshot_hash_sources: number;
+ };
+ };
+ // The aliased range is scanned once, so one candidate no longer counts
+ // as two agreeing sources.
+ expect(value.coverage).toBe("partial");
+ expect(value.libapp.snapshot_hash_sources).toBe(1);
+ expect(value.libapp.snapshot_hash_candidates).toEqual([REFERENCE_HASH]);
+ expect(result.value.limitations).toContain(
+ "Two or more snapshot data symbols share one header offset; its hash counts as one source instead of two agreeing ones",
+ );
+});
+
+it("preserves conflicting snapshot hash candidates from the AOT image", async () => {
+ const apk = await buildApk("conflicted.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: conflictingHashImage() },
+ ]);
+ const result = await new FlutterBuildProvider().execute({
+ operation: "inspect_dart_aot",
+ input: { path: apk },
+ });
+ if (!result.ok) throw new Error(result.error.message);
+ const value = result.value.result as {
+ coverage: string;
+ libapp: {
+ snapshot_hash: string | null;
+ snapshot_hash_candidates: string[];
+ snapshot_hash_sources: number;
+ };
+ };
+ expect(value.coverage).toBe("partial");
+ expect(value.libapp.snapshot_hash).toBeNull();
+ expect(value.libapp.snapshot_hash_sources).toBe(2);
+ expect(value.libapp.snapshot_hash_candidates).toEqual([
+ "11111111111111111111111111111111",
+ "22222222222222222222222222222222",
+ ]);
+});
+
+it("accepts an APK whose path contains spaces through the owned snapshot", async () => {
+ const apk = await buildApk("flutter spaced.apk", [
+ {
+ path: "lib/arm64-v8a/libapp.so",
+ bytes: libapp(REFERENCE_HASH),
+ },
+ { path: "lib/arm64-v8a/libflutter.so", bytes: libflutter() },
+ ]);
+ expect(apk).toContain(" ");
+ const result = await new FlutterBuildProvider().execute({
+ operation: "identify_flutter_build",
+ input: { path: apk },
+ });
+ if (!result.ok) throw new Error(result.error.message);
+ const value = result.value.result as { flutter_detected: boolean };
+ expect(value.flutter_detected).toBe(true);
+});
+
+it("retains failed snapshot cleanup and retries it on close", async () => {
+ const apk = await buildApk("cleanup.apk", [
+ {
+ path: "lib/arm64-v8a/libapp.so",
+ bytes: libapp(REFERENCE_HASH),
+ },
+ ]);
+ const spaces: string[] = [];
+ let failing = true;
+ const provider = new FlutterBuildProvider({
+ removeRoot: async (path) => {
+ if (failing) throw new Error("cleanup refused");
+ spaces.push(path);
+ await rm(path, { recursive: true, force: true });
+ },
+ });
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path: apk },
+ });
+ expect(result.ok).toBe(true);
+ await expect(provider.close()).rejects.toThrow(/snapshot cleanup failed/u);
+ failing = false;
+ await provider.close();
+ expect(spaces.length).toBeGreaterThanOrEqual(1);
+});
+
+it("cancels before creating any snapshot root", async () => {
+ const apk = await buildApk("cancel.apk", [
+ {
+ path: "lib/arm64-v8a/libapp.so",
+ bytes: libapp(REFERENCE_HASH),
+ },
+ ]);
+ const controller = new AbortController();
+ controller.abort();
+ const provider = new FlutterBuildProvider();
+ const result = await provider.execute(
+ { operation: "identify_flutter_build", input: { path: apk } },
+ { signal: controller.signal },
+ );
+ expect(result.ok).toBe(false);
+ await provider.close();
+});
+
+it.each([1, 20, 47, 48, 61])(
+ "identifies a valid ELF when ZIP chunks are only %i bytes",
+ async (chunkBytes) => {
+ const originalOpen = ZipArtifactReader.prototype.open;
+ const spy = vi
+ .spyOn(ZipArtifactReader.prototype, "open")
+ .mockImplementation(async function (
+ this: ZipArtifactReader,
+ entry,
+ signal,
+ ) {
+ const source = await originalOpen.call(this, entry, signal);
+ return Readable.from(
+ (async function* () {
+ for await (const chunk of source) {
+ const bytes = chunk as Buffer;
+ for (let offset = 0; offset < bytes.length; offset += chunkBytes)
+ yield bytes.subarray(offset, offset + chunkBytes);
+ }
+ })(),
+ );
+ });
+ onTestFinished(() => spy.mockRestore());
+ const execution = await analyzeImage(aotImage(), "identify_flutter_build");
+ const value = flutterResultSchemas.identify_flutter_build.parse(
+ execution.result,
+ );
+ expect(value.coverage).toBe("complete");
+ expect(value.abis[0]?.libapp).toMatchObject({
+ elf_header_valid: true,
+ snapshot_hash: REFERENCE_HASH,
+ snapshot_hash_sources: 2,
+ });
+ },
+);
+
+it.each([
+ {
+ name: "zeroed offsets",
+ corrupt: (image: Buffer) => image.fill(0, 0x20, 0x30),
+ },
+ {
+ name: "program table past EOF",
+ corrupt: (image: Buffer) =>
+ image.writeBigUInt64LE(BigInt(image.length + 1), 0x20),
+ },
+ {
+ name: "section table past EOF",
+ corrupt: (image: Buffer) =>
+ image.writeBigUInt64LE(BigInt(image.length - 1), 0x28),
+ },
+ {
+ name: "zero program entry width",
+ corrupt: (image: Buffer) => image.writeUInt16LE(0, 0x36),
+ },
+ {
+ name: "short section entry width",
+ corrupt: (image: Buffer) => image.writeUInt16LE(1, 0x3a),
+ },
+ {
+ name: "absent program table",
+ corrupt: (image: Buffer) => image.writeUInt16LE(0, 0x38),
+ },
+ {
+ name: "unsupported class",
+ corrupt: (image: Buffer) => image.writeUInt8(3, 4),
+ },
+ {
+ name: "unsupported byte order",
+ corrupt: (image: Buffer) => image.writeUInt8(2, 5),
+ },
+ {
+ name: "unsafe table offset",
+ corrupt: (image: Buffer) => image.writeBigUInt64LE(1n << 63n, 0x20),
+ },
+ {
+ name: "table inside header",
+ corrupt: (image: Buffer) => image.writeBigUInt64LE(1n, 0x20),
+ },
+ {
+ name: "extended section count",
+ corrupt: (image: Buffer) => image.writeUInt16LE(0, 0x3c),
+ },
+])(
+ "retains hash observations with partial coverage for $name",
+ async ({ corrupt }) => {
+ const image = aotImage();
+ corrupt(image);
+ const execution = await analyzeImage(image, "identify_flutter_build");
+ const value = flutterResultSchemas.identify_flutter_build.parse(
+ execution.result,
+ );
+ expect(value.coverage).toBe("partial");
+ expect(value.abis[0]?.libapp).toMatchObject({
+ elf_header_valid: false,
+ snapshot_hash: REFERENCE_HASH,
+ snapshot_hash_sources: 2,
+ });
+ expect(execution.limitations.join("\n")).toContain(
+ "ELF header or table extent",
+ );
+ },
+);
+
+it.each([0, 4, 20, 47, 61])(
+ "reports a %i-byte ELF prefix as partial without throwing",
+ async (length) => {
+ const execution = await analyzeImage(
+ aotImage().subarray(0, length),
+ "identify_flutter_build",
+ );
+ const value = flutterResultSchemas.identify_flutter_build.parse(
+ execution.result,
+ );
+ expect(value.coverage).toBe("partial");
+ expect(value.abis[0]?.libapp.elf_header_valid).toBe(false);
+ },
+);
+
+it("accepts a section-stripped ELF32 header and bounds its program table", async () => {
+ const image = Buffer.alloc(52 + 32 + 104);
+ image.writeUInt32LE(0x464c457f);
+ image.set([1, 1, 1], 4); // ELF32, little-endian, version 1
+ image.writeUInt16LE(3, 0x10); // ET_DYN
+ image.writeUInt32LE(1, 0x14);
+ image.writeUInt32LE(52, 0x1c);
+ image.writeUInt16LE(52, 0x28);
+ image.writeUInt16LE(32, 0x2a);
+ image.writeUInt16LE(1, 0x2c);
+ image.writeUInt32LE(1, 52); // PT_LOAD
+ image.writeUInt32LE(image.length, 52 + 16);
+ snapshotSection(REFERENCE_HASH).copy(image, 84);
+ snapshotSection(REFERENCE_HASH).copy(image, 136);
+ const good = await analyzeImage(image, "identify_flutter_build");
+ expect(
+ flutterResultSchemas.identify_flutter_build.parse(good.result).coverage,
+ ).toBe("complete");
+ image.writeUInt32LE(image.length - 31, 0x1c); // One byte short of the table.
+ const bad = await analyzeImage(image, "identify_flutter_build");
+ expect(
+ flutterResultSchemas.identify_flutter_build.parse(bad.result).coverage,
+ ).toBe("partial");
+});
+
+it.each([0n, 15n, 47n, 49n, 1n << 63n])(
+ "retains malformed snapshot length %s as partial evidence",
+ async (length) => {
+ const image = aotImage();
+ image.writeBigUInt64LE(length, 0x1004);
+ const execution = await analyzeImage(image, "inspect_dart_aot");
+ const value = flutterResultSchemas.inspect_dart_aot.parse(execution.result);
+ expect(value.coverage).toBe("partial");
+ expect(value.libapp.snapshot_hash).toBe(REFERENCE_HASH);
+ expect(value.libapp.sections[0]).toMatchObject({
+ magic_valid: true,
+ header_length:
+ length > BigInt(Number.MAX_SAFE_INTEGER) ? null : Number(length),
+ });
+ expect(execution.limitations.join("\n")).toContain(
+ "_kDartVmSnapshotData has an incomplete or invalid snapshot header",
+ );
+ },
+);
+
+it("does not let two VM records replace a missing isolate header hash", async () => {
+ const image = aotImage();
+ const elf = buildElf64Image([
+ { name: "_kDartVmSnapshotData", value: 0x1000, size: 104 },
+ { name: "_kDartVmSnapshotInstructions", value: 0x1800, size: 16 },
+ { name: "_kDartIsolateSnapshotData", value: 0x2000, size: 0x600 },
+ { name: "_kDartIsolateSnapshotInstructions", value: 0x2600, size: 16 },
+ ]);
+ elf.copy(image);
+ snapshotSection(REFERENCE_HASH).copy(image, 0x1000 + 52);
+ image[0x2000 + 20] = 0x78; // Keep the isolate magic but invalidate its hash.
+ const execution = await analyzeImage(image, "inspect_dart_aot");
+ const value = flutterResultSchemas.inspect_dart_aot.parse(execution.result);
+ expect(value.libapp.sections).toHaveLength(4);
+ expect(value.coverage).toBe("partial");
+ expect(value.libapp.snapshot_hash_sources).toBe(1);
+ expect(value.libapp.snapshot_hash_candidates).toEqual([REFERENCE_HASH]);
+ expect(execution.limitations.join("\n")).toContain(
+ "_kDartIsolateSnapshotData has an incomplete or invalid snapshot header",
+ );
+});
+
+it.each(["identify_flutter_build", "inspect_dart_aot"] as const)(
+ "%s preserves an oversized APK refusal as a resource constraint",
+ async (operation) => {
+ const root = await createTestTempDirectory("rea-flutter-size-");
+ const path = join(root, "oversized.apk");
+ const file = await open(path, "wx");
+ try {
+ await file.truncate(2 * 1024 ** 3 + 1); // Sparse file: no multi-GiB allocation.
+ } finally {
+ await file.close();
+ }
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({ operation, input: { path } });
+ if (result.ok) throw new Error("expected a size refusal");
+ expect(result.error).toBeInstanceOf(AnalysisResourceConstraintError);
+ expect(projectAnalysisError(result.error).code).toBe("resource_constraint");
+ expect(result.error).toMatchObject({
+ operation,
+ reportedLimits: {
+ max_apk_bytes: 2 * 1024 ** 3,
+ observed_bytes: 2 * 1024 ** 3 + 1,
+ },
+ });
+ },
+);
+
+it.each([
+ { operation: "identify_flutter_build" },
+ { operation: "inspect_dart_aot" },
+] as const)(
+ "preserves native stream aborts during $operation digest",
+ async ({ operation }) => {
+ const path = await buildApk("abort.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const controller = new AbortController();
+ const nativeFs = await vi.importActual<typeof import("node:fs")>("node:fs");
+ const streamMock = vi.mocked(createReadStream);
+ let abortCode: string | undefined;
+ streamMock.mockImplementation((streamPath, options) => {
+ const stream = nativeFs.createReadStream(streamPath, options);
+ if (streamPath !== path) {
+ stream.once("error", (cause: NodeJS.ErrnoException) => {
+ abortCode = cause.code;
+ });
+ stream.once("readable", () =>
+ controller.abort(new Error("caller requested stop")),
+ );
+ }
+ return stream;
+ });
+ onTestFinished(() => {
+ streamMock.mockReset();
+ });
+ const removedRoots: string[] = [];
+ const provider = new FlutterBuildProvider({
+ removeRoot: async (root) => {
+ await rm(root, { recursive: true, force: true });
+ removedRoots.push(root);
+ },
+ });
+ onTestFinished(() => provider.close());
+ const result = await provider.execute(
+ { operation, input: { path } },
+ { signal: controller.signal },
+ );
+ if (result.ok) throw new Error("expected cancellation");
+ expect(abortCode).toBe("ABORT_ERR");
+ expect(result.error).toBeInstanceOf(AnalysisCancelledError);
+ expect(result.error).toMatchObject({ operation });
+ expect(projectAnalysisError(result.error).code).toBe("cancelled");
+ expect(removedRoots).toHaveLength(1);
+ },
+);
+
+it.each([undefined, "arm64-v8a", "x86_64", "mips"])(
+ "applies the library cap only to selected ABI %s",
+ async (abi) => {
+ const path = await buildApk("mixed-sizes.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ { path: "lib/x86_64/libapp.so", bytes: aotImage() },
+ ]);
+ const originalEntries = ZipArtifactReader.prototype.entries;
+ const inventory = vi
+ .spyOn(ZipArtifactReader.prototype, "entries")
+ .mockImplementation(async function* (this: ZipArtifactReader, signal) {
+ for await (const entry of originalEntries.call(this, signal))
+ yield entry.path.includes("x86_64")
+ ? { ...entry, declaredSize: 256 * 1024 ** 2 + 1 }
+ : entry;
+ });
+ const reads = vi.spyOn(ZipArtifactReader.prototype, "open");
+ onTestFinished(() => {
+ inventory.mockRestore();
+ reads.mockRestore();
+ });
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "inspect_dart_aot",
+ input: { path, ...(abi === undefined ? {} : { abi }) },
+ });
+ if (abi === "x86_64" || abi === "mips") {
+ if (result.ok) throw new Error("expected selected-ABI refusal");
+ expect(projectAnalysisError(result.error).code).toBe(
+ abi === "x86_64" ? "resource_constraint" : "unsupported_target",
+ );
+ expect(reads).not.toHaveBeenCalled();
+ } else {
+ if (!result.ok) throw result.error;
+ expect(
+ flutterResultSchemas.inspect_dart_aot.parse(result.value.result).abi,
+ ).toBe("arm64-v8a");
+ expect(reads.mock.calls.map(([entry]) => entry.path)).toEqual([
+ "lib/arm64-v8a/libapp.so",
+ ]);
+ }
+ },
+);
+
+it.each(["identify_flutter_build", "inspect_dart_aot"] as const)(
+ "%s preserves a real ZIP metadata budget refusal",
+ async (operation) => {
+ const root = await createTestTempDirectory("rea-flutter-metadata-");
+ const path = join(root, "large-directory.apk");
+ const writer = new ZipWriter(new Uint8ArrayWriter(), {
+ useWebWorkers: false,
+ });
+ const comment = "x".repeat(65535);
+ for (let index = 0; index < 129; index += 1)
+ await writer.add(
+ `assets/empty-${String(index)}`,
+ new Uint8ArrayReader(new Uint8Array()),
+ { comment, level: 0 },
+ );
+ await writeFile(path, await writer.close());
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({ operation, input: { path } });
+ if (result.ok) throw new Error("expected metadata capacity refusal");
+ expect(projectAnalysisError(result.error).code).toBe("resource_constraint");
+ expect(result.error).toMatchObject({
+ operation,
+ reportedLimits: { max_metadata_read_bytes: 8 * 1024 ** 2 },
+ });
+ expect(result.error.message).toContain("ZIP metadata read requires");
+ },
+);
+
+it("refuses an AOT image whose snapshot names are all undefined imports", async () => {
+ const image = aotImage();
+ const table = Number(
+ image.readBigUInt64LE(Number(image.readBigUInt64LE(0x28)) + 64 + 0x18),
+ );
+ for (let index = 0; index < 4; index += 1)
+ image.writeUInt16LE(0, table + index * 24 + 6);
+ await expect(analyzeImage(image, "inspect_dart_aot")).rejects.toMatchObject({
+ _tag: "AnalysisUnsupportedTargetError",
+ });
+});
+
+it.each(["identify_flutter_build", "inspect_dart_aot"] as const)(
+ "%s retains a reader whose close failed before removing its root",
+ async (operation) => {
+ const path = await buildApk("reader-close.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const readers = new Set<ZipArtifactReader>();
+ const originalClose = ZipArtifactReader.prototype.close;
+ let failClose = true;
+ const close = vi
+ .spyOn(ZipArtifactReader.prototype, "close")
+ .mockImplementation(async function (this: ZipArtifactReader) {
+ readers.add(this);
+ if (failClose) throw new Error("file handle close refused");
+ await originalClose.call(this);
+ });
+ const removeRoot = vi.fn((root: string) =>
+ rm(root, { recursive: true, force: true }),
+ );
+ const provider = new FlutterBuildProvider({ removeRoot });
+ onTestFinished(async () => {
+ failClose = false;
+ await provider.close();
+ for (const reader of readers) await originalClose.call(reader);
+ close.mockRestore();
+ });
+ const result = await provider.execute({ operation, input: { path } });
+ if (!result.ok) throw result.error;
+ expect(removeRoot).not.toHaveBeenCalled();
+ await expect(provider.close()).rejects.toThrow("snapshot cleanup failed");
+ expect(removeRoot).not.toHaveBeenCalled();
+ failClose = false;
+ await provider.close();
+ expect(close).toHaveBeenCalledTimes(3);
+ expect(removeRoot).toHaveBeenCalledTimes(1);
+ },
+);
+
+it("reports omitted Dart labels independently of toolchain labels", async () => {
+ const path = await buildApk("dart-label.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ {
+ path: "lib/arm64-v8a/libflutter.so",
+ bytes: Buffer.concat([
+ libflutter(),
+ Buffer.from(`Dart VM version:${"x".repeat(201)}\0`),
+ ]),
+ },
+ ]);
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (!result.ok) throw result.error;
+ const value = flutterResultSchemas.identify_flutter_build.parse(
+ result.value.result,
+ );
+ expect(value.coverage).toBe("partial");
+ expect(value.abis[0]?.libflutter).toMatchObject({
+ dart_version: null,
+ dart_version_capped: true,
+ toolchain_capped: false,
+ });
+});
+
+it.each([0, 1, 2, 3])(
+ "retains failed local file-handle closure at acquisition stage %i",
+ async (stage) => {
+ const path = await buildApk("file-close.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ // Close order: snapshot writer, admitted source, extracted-image writer, image reader.
+ const owners: OwnedFileHandle[] = [];
+ const originalClose = OwnedFileHandle.prototype.close;
+ let failing = true;
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockImplementation(async function (this: OwnedFileHandle) {
+ if (!owners.includes(this)) owners.push(this);
+ if (failing && owners[stage] === this)
+ throw new Error("handle close refused");
+ await originalClose.call(this);
+ });
+ const removeRoot = vi.fn((root: string) =>
+ rm(root, { recursive: true, force: true }),
+ );
+ const provider = new FlutterBuildProvider({ removeRoot });
+ onTestFinished(async () => {
+ failing = false;
+ await provider.close();
+ for (const owner of owners) await originalClose.call(owner);
+ close.mockRestore();
+ });
+ const result = await provider.execute({
+ operation: "inspect_dart_aot",
+ input: { path },
+ });
+ expect(result.ok).toBe(false);
+ expect(removeRoot).not.toHaveBeenCalled();
+ await expect(provider.close()).rejects.toThrow("snapshot cleanup failed");
+ failing = false;
+ await provider.close();
+ expect(removeRoot).toHaveBeenCalledTimes(1);
+ },
+);
+
+it.each(["identify_flutter_build", "inspect_dart_aot"] as const)(
+ "%s rejects duplicate real ZIP members before extracting either occurrence",
+ async (operation) => {
+ const path = await createDuplicateFlutterApk();
+ const extract = vi.spyOn(ZipArtifactReader.prototype, "open");
+ onTestFinished(() => extract.mockRestore());
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({ operation, input: { path } });
+ if (result.ok) throw new Error("Duplicate libraries must be refused");
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "invalid_request",
+ });
+ expect(JSON.stringify(projectAnalysisError(result.error))).toContain(
+ "duplicate Flutter library members",
+ );
+ expect(JSON.stringify(projectAnalysisError(result.error))).toContain(path);
+ expect(extract).not.toHaveBeenCalled();
+ },
+);
+
+it.each(["identify_flutter_build", "inspect_dart_aot"] as const)(
+ "%s refuses ABI metadata expansion before opening empty libraries",
+ async (operation) => {
+ const path = await buildApk(
+ "many-abis.apk",
+ Array.from({ length: 33 }, (_, index) => ({
+ path: `lib/abi_${String(index)}/libapp.so`,
+ bytes: Buffer.alloc(0),
+ })),
+ );
+ const extract = vi.spyOn(ZipArtifactReader.prototype, "open");
+ onTestFinished(() => extract.mockRestore());
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({ operation, input: { path } });
+ if (result.ok) throw new Error("ABI expansion must be refused");
+ expect(projectAnalysisError(result.error).code).toBe("resource_constraint");
+ expect(extract).not.toHaveBeenCalled();
+ },
+);
+
+it.each(["identify_flutter_build", "inspect_dart_aot"] as const)(
+ "%s uses the selected path in malformed-APK diagnostics",
+ async (operation) => {
+ const root = await createTestTempDirectory("rea-flutter-malformed-");
+ const path = join(root, "selected.apk");
+ await writeFile(path, "not a ZIP");
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({ operation, input: { path } });
+ if (result.ok) throw new Error("Malformed APK must be refused");
+ const error = projectAnalysisError(result.error);
+ expect(error).toMatchObject({
+ code: "invalid_request",
+ details: { issues: [{ message: expect.stringContaining(path) }] },
+ });
+ expect(JSON.stringify(error)).not.toContain("input.apk");
+ },
+);
+
+it.each(["EACCES", "EPERM"] as const)(
+ "preserves %s at the shared source admission boundary",
+ async (code) => {
+ const admitted = vi
+ .spyOn(regularFile, "openRegularFile")
+ .mockRejectedValue(Object.assign(new Error("denied"), { code }));
+ onTestFinished(() => admitted.mockRestore());
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ for (const operation of [
+ "identify_flutter_build",
+ "inspect_dart_aot",
+ ] as const) {
+ const result = await provider.execute({
+ operation,
+ input: { path: "/selected.apk" },
+ });
+ if (result.ok) throw new Error("Denied read must fail");
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "access_denied",
+ });
+ }
+ },
+);
+
+it.each(["EACCES", "EPERM"] as const)(
+ "preserves %s during opened-source reads and path revalidation",
+ async (code) => {
+ const path = await buildApk("source-denied.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const original = regularFile.openRegularFile;
+ const cause = Object.assign(new Error("source denied"), { code });
+ for (const stage of ["read", "revalidate"] as const) {
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const admitted = vi
+ .spyOn(regularFile, "openRegularFile")
+ .mockImplementation(async (...args) => {
+ const handle = await original(...args);
+ if (stage === "read")
+ vi.spyOn(handle, "read").mockRejectedValueOnce(cause);
+ return handle;
+ });
+ const pathStat =
+ stage === "revalidate"
+ ? vi.spyOn(fsPromises, "stat").mockRejectedValueOnce(cause)
+ : undefined;
+ try {
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (result.ok) throw new Error("Denied source must fail");
+ expect(projectAnalysisError(result.error).code).toBe("access_denied");
+ expect(result.error.cause).toBe(cause);
+ } finally {
+ admitted.mockRestore();
+ pathStat?.mockRestore();
+ }
+ }
+ },
+);
+
+it("detects same-size source rewrites with restored mtime through the opened descriptor", async () => {
+ const path = await buildApk("changing.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const before = await stat(path);
+ const content = await readFile(path);
+ const nativeAdmission = regularFile.openRegularFile;
+ const admitted = vi
+ .spyOn(regularFile, "openRegularFile")
+ .mockImplementation(async (...args) => {
+ const handle = await nativeAdmission(...args);
+ // Admission returns an open descriptor; mutate its file before the final
+ // descriptor stat, preserving the size and restoring the visible mtime.
+ const nativeStat = handle.stat.bind(handle);
+ let calls = 0;
+ vi.spyOn(handle, "stat").mockImplementation(async (...statArgs) => {
+ calls += 1;
+ if (calls === 2) {
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ await writeFile(path, content);
+ await utimes(path, before.atime, before.mtime);
+ }
+ return nativeStat(...statArgs);
+ });
+ return handle;
+ });
+ onTestFinished(() => admitted.mockRestore());
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (result.ok) throw new Error("Concurrent source rewrite must fail");
+ expect(projectAnalysisError(result.error).code).toBe("artifact_changed");
+});
+
+it("refuses truncated hash-candidate evidence and includes five-character tokens", async () => {
+ const image = aotImage();
+ Buffer.from("Login\0").copy(image, 0x2300);
+ const aot = await analyzeImage(image, "inspect_dart_aot");
+ expect(
+ flutterResultSchemas.inspect_dart_aot.parse(aot.result).string_pool
+ .class_like_tokens,
+ ).toContain("Login");
+ const bytes = Buffer.concat(
+ Array.from({ length: 65 }, (_, index) =>
+ snapshotSection(index.toString(16).padStart(32, "0")),
+ ),
+ );
+ const path = await buildApk("many-hashes.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes },
+ ]);
+ const provider = new FlutterBuildProvider();
+ onTestFinished(() => provider.close());
+ const result = await provider.execute({
+ operation: "identify_flutter_build",
+ input: { path },
+ });
+ if (result.ok) throw new Error("Incomplete candidate set must be explicit");
+ expect(projectAnalysisError(result.error).code).toBe("resource_constraint");
+});
+
+it("stops a cancelled descriptor copy before writing its next chunk and releases every owner", async () => {
+ const path = await buildApk("copy-cancel.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotImage() },
+ ]);
+ const controller = new AbortController();
+ const nativeAdmission = regularFile.openRegularFile;
+ const admitted = vi
+ .spyOn(regularFile, "openRegularFile")
+ .mockImplementation(async (...args) => {
+ const handle = await nativeAdmission(...args);
+ const nativeRead = handle.read.bind(handle);
+ vi.spyOn(handle, "read").mockImplementation(async (...readArgs) => {
+ const result = await nativeRead(...readArgs);
+ controller.abort(new Error("cancelled while copy read was pending"));
+ return result;
+ });
+ return handle;
+ });
+ onTestFinished(() => admitted.mockRestore());
+ const removeRoot = vi.fn((root: string) =>
+ rm(root, { recursive: true, force: true }),
+ );
+ const provider = new FlutterBuildProvider({ removeRoot });
+ onTestFinished(() => provider.close());
+ const result = await provider.execute(
+ { operation: "identify_flutter_build", input: { path } },
+ { signal: controller.signal },
+ );
+ if (result.ok) throw new Error("Cancelled copying must fail");
+ expect(projectAnalysisError(result.error).code).toBe("cancelled");
+ expect(removeRoot).toHaveBeenCalledTimes(1);
+});
diff --git a/tests/boundary/mcp/flutterMcp.test.ts b/tests/boundary/mcp/flutterMcp.test.ts
new file mode 100644
index 000000000..646f54511
--- /dev/null
+++ b/tests/boundary/mcp/flutterMcp.test.ts
@@ -0,0 +1,183 @@
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { expect, it, onTestFinished } from "vitest";
+
+import type { FlutterBuildAnalysisPort } from "../../../src/application/flutter/FlutterBuildAnalysisPort.js";
+import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
+import { assertAdvertisedMcpContracts } from "./mcpContractHarness.js";
+import { parseEvidence } from "../../../src/domain/evidence.js";
+import { ok } from "../../../src/domain/result.js";
+import { createServer } from "../../../src/server/createServer.js";
+import { createTestBinarySession } from "../../fixtures/binarySession.js";
+
+const identity = {
+ id: "flutter",
+ name: "Flutter build identification",
+ version: null,
+};
+
+const SNAPSHOT_HASH = "65817c30a78bb44c3dc3771876b6010a";
+
+/** One shared target identity for both fake operation results. */
+const target = {
+ path: "/targets/gallery.apk",
+ bytes: 117817550,
+ sha256: "a".repeat(64),
+};
+
+const inspectExecution = () =>
+ createAnalysisExecution(
+ {
+ target,
+ abi: "arm64-v8a",
+ libapp: {
+ coverage: "complete",
+ bytes: 24691632,
+ sha256: "b".repeat(64),
+ snapshot_hash: SNAPSHOT_HASH,
+ snapshot_hash_candidates: [SNAPSHOT_HASH],
+ snapshot_hash_sources: 2,
+ sections: [
+ {
+ name: "_kDartVmSnapshotData",
+ offset: 4096,
+ size: 52,
+ magic_valid: true,
+ kind: 3,
+ header_length: 48,
+ },
+ {
+ name: "_kDartIsolateSnapshotData",
+ offset: 8192,
+ size: 1536,
+ magic_valid: true,
+ kind: 3,
+ header_length: 48,
+ },
+ ],
+ },
+ string_pool: {
+ coverage: "complete",
+ package_uris: [
+ "package:adaptive_breakpoints/src/adaptive_breakpoints.dart",
+ ],
+ package_uri_count_at_least: 1,
+ dart_uris: ["dart:_http"],
+ dart_uri_count_at_least: 1,
+ class_like_tokens: ["AdaptiveBreakpoint"],
+ class_like_token_count_at_least: 1,
+ printable_run_count: 4,
+ },
+ coverage: "complete",
+ },
+ identity,
+ );
+
+const identifyExecution = () =>
+ createAnalysisExecution(
+ {
+ target,
+ flutter_detected: true,
+ abis: [
+ {
+ abi: "arm64-v8a",
+ libapp: {
+ present: true,
+ bytes: 24691632,
+ sha256: "b".repeat(64),
+ elf_header_valid: true,
+ snapshot_hash_sources: 2,
+ snapshot_hash_candidates: [SNAPSHOT_HASH],
+ snapshot_hash: SNAPSHOT_HASH,
+ },
+ libflutter: {
+ present: true,
+ bytes: 9073432,
+ sha256: "c".repeat(64),
+ build_id: "e8d907ef7c175ec4313f47111019adc9588c5f61",
+ build_id_candidates: ["e8d907ef7c175ec4313f47111019adc9588c5f61"],
+ dart_version: null,
+ dart_version_capped: false,
+ toolchain_lines: ["Android (5900059) clang version 9.0.8"],
+ toolchain_capped: false,
+ },
+ },
+ ],
+ coverage: "complete",
+ },
+ identity,
+ );
+
+/** A recording-free provider answering both Flutter operations inline. */
+const fakeProvider = (): FlutterBuildAnalysisPort => ({
+ async inspectAvailability() {
+ return { status: "available", code: null, reason: null, diagnostics: {} };
+ },
+ async close() {},
+ async execute(request) {
+ return ok(
+ request.operation === "inspect_dart_aot"
+ ? inspectExecution()
+ : identifyExecution(),
+ );
+ },
+});
+
+it("advertises an exact valid Flutter schema and records inline evidence through MCP", async () => {
+ const session = createTestBinarySession(() => {
+ throw new Error("deep provider must not start");
+ });
+ const server = createServer(
+ { kind: "session", session },
+ { flutterAnalysis: fakeProvider() },
+ );
+ onTestFinished(() => server.close());
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ const client = new Client({ name: "flutter-boundary", version: "0.0.0" });
+ onTestFinished(() => client.close());
+ await client.connect(clientTransport);
+
+ const { tools } = await client.listTools();
+ assertAdvertisedMcpContracts(
+ ["identify_flutter_build", "inspect_dart_aot"],
+ tools,
+ );
+
+ const identified = await client.callTool({
+ name: "identify_flutter_build",
+ arguments: { path: "/targets/gallery.apk" },
+ });
+ expect(identified.isError).not.toBe(true);
+ const text = (identified.content as { readonly text?: string }[])
+ .map((part) => part.text ?? "")
+ .join("");
+ const evidence = parseEvidence(JSON.parse(text));
+ expect(evidence.normalized_result).toMatchObject({
+ flutter_detected: true,
+ abis: [
+ {
+ abi: "arm64-v8a",
+ libapp: { snapshot_hash: SNAPSHOT_HASH },
+ },
+ ],
+ });
+
+ const inspected = await client.callTool({
+ name: "inspect_dart_aot",
+ arguments: { path: "/targets/gallery.apk", abi: "arm64-v8a" },
+ });
+ expect(inspected.isError).not.toBe(true);
+ const inspectedText = (inspected.content as { readonly text?: string }[])
+ .map((part) => part.text ?? "")
+ .join("");
+ const inspectedEvidence = parseEvidence(JSON.parse(inspectedText));
+ expect(inspectedEvidence.normalized_result).toMatchObject({
+ abi: "arm64-v8a",
+ libapp: {
+ snapshot_hash: SNAPSHOT_HASH,
+ snapshot_hash_candidates: [SNAPSHOT_HASH],
+ snapshot_hash_sources: 2,
+ },
+ });
+});
diff --git a/tests/fixtures/flutterApk.ts b/tests/fixtures/flutterApk.ts
new file mode 100644
index 000000000..068dee929
--- /dev/null
+++ b/tests/fixtures/flutterApk.ts
@@ -0,0 +1,39 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Uint8ArrayReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js";
+import { aotFixtureImage } from "../../src/flutter/FlutterBuild.fixture.js";
+import { createTestTempDirectory } from "./temporaryDirectory.js";
+
+/** Materialize real ZIP members with test-scoped exact-path cleanup. */
+export const createFlutterApk = async (
+ name: string,
+ files: ReadonlyArray<{ readonly path: string; readonly bytes: Buffer }>,
+): Promise<string> => {
+ const root = await createTestTempDirectory("rea-flutter-");
+ const writer = new ZipWriter(new Uint8ArrayWriter(), {
+ useWebWorkers: false,
+ });
+ for (const file of files)
+ await writer.add(file.path, new Uint8ArrayReader(file.bytes));
+ const path = join(root, name);
+ await writeFile(path, await writer.close());
+ return path;
+};
+
+/** ZIP permits repeated names; the writer refuses them, so rewrite both records. */
+export const createDuplicateFlutterApk = async (): Promise<string> => {
+ const path = await createFlutterApk("duplicates.apk", [
+ { path: "lib/arm64-v8a/libapp.so", bytes: aotFixtureImage() },
+ { path: "lib/arm64-v8a/libxxx.so", bytes: Buffer.alloc(64) },
+ ]);
+ const bytes = await readFile(path);
+ const from = Buffer.from("lib/arm64-v8a/libxxx.so");
+ for (
+ let at = bytes.indexOf(from);
+ at >= 0;
+ at = bytes.indexOf(from, at + from.length)
+ )
+ bytes.write("lib/arm64-v8a/libapp.so", at);
+ await writeFile(path, bytes);
+ return path;
+};
diff --git a/vitest.config.ts b/vitest.config.ts
index 716b3b0e5..74dbf5305 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -51,7 +51,7 @@ const TEST_PROJECTS = [
name: "adapters",
include: [
"src/*.test.ts",
- "src/{apktool,jeb,adb,artifacts,browser,dotnet,evm,firmware,ghidra,go,hopper,ida,inspector,javascript,native,process,reference,server,wasm,windows}/**/*.test.ts",
+ "src/{apktool,jeb,adb,artifacts,browser,dotnet,evm,firmware,flutter,ghidra,go,hopper,ida,inspector,javascript,native,process,reference,server,wasm,windows}/**/*.test.ts",
],
pool: "forks" as const,
maxWorkers: MAX_TEST_WORKERS,