Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(flutter): identify Dart snapshot builds and inspect AOT payloads by pure APK parsing (#1582)
Quentin Limoe4d3e1399d9c
diff --git a/README.md b/README.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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 andbudgets.+## 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 ordiff --git a/package.json b/package.jsonindex 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.jsonnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 5a9fac0db..ec7a9f231 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -75,6 +75,7 @@ import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnalyimport { 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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,