From 51459cf203ae1eb6b586a95b21899eaa0f631823 Mon Sep 17 00:00:00 2001 From: Matt Van Horn Date: Tue, 17 Nov 2026 06:01:23 -0800 Subject: [PATCH] feat(artifacts): inventory Android OTA update payloads offline (#11378) --- .../references/native-and-artifacts.md | 7 + .../references/native-and-artifacts.md | 7 + docs/.vitepress/documentation.ts | 5 + docs/README.md | 1 + docs/getting-started/cli.md | 10 + docs/guides/android/android-analysis.md | 3 + docs/guides/firmware/android-ota-payload.md | 93 + docs/guides/firmware/firmware-analysis.md | 9 + docs/index.md | 26 +- .../firmware/android-ota-payload/plan.md | 43 + .../firmware/android-ota-payload/spec.md | 49 + .../firmware/android-ota-payload/tasks.md | 11 + .../advertised-schemas/tools/open_binary.json | 5 +- .../binary/TargetFormatVocabularies.test.ts | 1 + ...taPayloadArtifactReader.boundaries.test.ts | 174 ++ .../AndroidOtaPayloadArtifactReader.test.ts | 342 ++++ .../AndroidOtaPayloadArtifactReader.ts | 461 +++++ src/artifacts/artifactFormats.test.ts | 1 + src/artifacts/artifactFormats.ts | 11 + .../ArtifactGraphConstruction.test.ts | 19 + src/domain/analysisSnapshot.ts | 1 + .../androidOtaPayloadSummary.test.ts | 87 + .../analysisView/androidOtaPayloadSummary.ts | 41 + .../analysisView/artifactInventoryView.ts | 15 +- .../analysisView/espFlashImageSummary.ts | 13 +- src/domain/artifactFormatMetadata.ts | 114 ++ src/domain/artifactFormatRecognition.test.ts | 18 + src/domain/artifactFormatRecognition.ts | 13 + src/domain/artifactGraph.ts | 2 + src/domain/binaryTargetTypes.ts | 2 + src/domain/evidenceSubject.ts | 1 + .../firmware/androidOtaPayload.fixture.ts | 497 ++++++ src/domain/firmware/androidOtaPayload.test.ts | 732 ++++++++ src/domain/firmware/androidOtaPayload.ts | 1496 +++++++++++++++++ src/domain/liveBinaryTargetSummary.ts | 1 + src/resources/ArtifactReader.ts | 1 + tests/acceptance/androidOtaPayloadCli.test.ts | 104 ++ .../boundary/mcp/androidOtaPayloadMcp.test.ts | 90 + 38 files changed, 4485 insertions(+), 21 deletions(-) create mode 100644 docs/guides/firmware/android-ota-payload.md create mode 100644 docs/specs/firmware/android-ota-payload/plan.md create mode 100644 docs/specs/firmware/android-ota-payload/spec.md create mode 100644 docs/specs/firmware/android-ota-payload/tasks.md create mode 100644 src/artifacts/AndroidOtaPayloadArtifactReader.boundaries.test.ts create mode 100644 src/artifacts/AndroidOtaPayloadArtifactReader.test.ts create mode 100644 src/artifacts/AndroidOtaPayloadArtifactReader.ts create mode 100644 src/domain/analysisView/androidOtaPayloadSummary.test.ts create mode 100644 src/domain/analysisView/androidOtaPayloadSummary.ts create mode 100644 src/domain/firmware/androidOtaPayload.fixture.ts create mode 100644 src/domain/firmware/androidOtaPayload.test.ts create mode 100644 src/domain/firmware/androidOtaPayload.ts create mode 100644 tests/acceptance/androidOtaPayloadCli.test.ts create mode 100644 tests/boundary/mcp/androidOtaPayloadMcp.test.ts diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index 4fa70a2969..a53ee6e940 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -932,6 +932,13 @@ stored. The v4 signature and any AVB footer are reported with sizes and are not verified. Extract `dtb` and pass that file to `inspect_devicetree`. See [Android boot images](https://github.com/morluto/rea/blob/main/docs/android-boot-image.md). +Android A/B OTA `payload.bin` files (CrAU v2) use the same +inspection/extraction workflows. Prefer a retained summary for header, +partition table, dynamic groups and signature counts. Signatures are not +verified. Reconstruct REPLACE, ZERO and REPLACE_ZSTD images only; delta +operations stay inventoried with unavailable content. See +[Android OTA update payloads](https://github.com/morluto/rea/blob/main/docs/guides/firmware/android-ota-payload.md). + ## ESP images For an ESP32-family app or bootloader image, `open_binary` then diff --git a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md index 4fa70a2969..a53ee6e940 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -932,6 +932,13 @@ stored. The v4 signature and any AVB footer are reported with sizes and are not verified. Extract `dtb` and pass that file to `inspect_devicetree`. See [Android boot images](https://github.com/morluto/rea/blob/main/docs/android-boot-image.md). +Android A/B OTA `payload.bin` files (CrAU v2) use the same +inspection/extraction workflows. Prefer a retained summary for header, +partition table, dynamic groups and signature counts. Signatures are not +verified. Reconstruct REPLACE, ZERO and REPLACE_ZSTD images only; delta +operations stay inventoried with unavailable content. See +[Android OTA update payloads](https://github.com/morluto/rea/blob/main/docs/guides/firmware/android-ota-payload.md). + ## ESP images For an ESP32-family app or bootloader image, `open_binary` then diff --git a/docs/.vitepress/documentation.ts b/docs/.vitepress/documentation.ts index 19ae784bfb..9465aa9b35 100644 --- a/docs/.vitepress/documentation.ts +++ b/docs/.vitepress/documentation.ts @@ -553,6 +553,11 @@ export const documentationSections = [ source: "apk-signature.md", route: "/apk-signature", }, + { + text: "Android OTA update payloads", + source: "guides/firmware/android-ota-payload.md", + route: "/android-ota-payload", + }, { text: "Apple IPS crash reports", source: "apple-ips.md", diff --git a/docs/README.md b/docs/README.md index 01569ded37..5a23dea4b9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -175,6 +175,7 @@ the exact commit messages and references from the release they describe. - [Agent environments from recorded captures](agent-environments.md) - [Android boot and vendor_boot images](android-boot-image.md) - [APK signature schemes](apk-signature.md) +- [Android OTA update payloads](guides/firmware/android-ota-payload.md) - [Apple IPS crash reports](apple-ips.md) - [Static analysis in GitHub Actions](ci-analysis.md) - [Desktop installation directories](desktop-applications.md) diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md index 2979fa694b..e0ecee7365 100644 --- a/docs/getting-started/cli.md +++ b/docs/getting-started/cli.md @@ -374,6 +374,16 @@ rea extract-artifact ./firmware.bin --json See [U-Boot uImage](../uimage.md) for verified CRCs, physical component ranges, unknown names, resource limits and retained views. Compressed bytes stay stored. +Inspect an Android A/B OTA `payload.bin` (CrAU v2) without applying the update: + +```sh +rea inspect-artifact ./payload.bin --detail summary --evidence_output payload.json --json +rea extract-artifact ./payload.bin --json +``` + +See [Android OTA update payloads](../guides/firmware/android-ota-payload.md) for manifest +facts, signature counting, REPLACE/ZERO reconstruction and delta limits. + `inspect-artifact` and `extract-artifact` also read ZIP members compressed with Zstandard (standard method 93). They retain the shared ZIP CRC, declared-size, overlap and archive expansion checks. The native streaming decoder keeps the diff --git a/docs/guides/android/android-analysis.md b/docs/guides/android/android-analysis.md index 668745826e..ba7bb78447 100644 --- a/docs/guides/android/android-analysis.md +++ b/docs/guides/android/android-analysis.md @@ -13,6 +13,9 @@ On Linux, JADX launches an REA-owned process and requires a procps-compatible system `ps`; see the shared [Linux process prerequisite](../../getting-started/installation.md#linux-owned-process-prerequisite). +A/B OTA `payload.bin` files are a separate offline artifact, not a JADX +package. See [Android OTA update payloads](../firmware/android-ota-payload.md). + ## Optional package delivery The MCP `inspect_android_package` request keeps complete output when `detail` is diff --git a/docs/guides/firmware/android-ota-payload.md b/docs/guides/firmware/android-ota-payload.md new file mode 100644 index 0000000000..c1a6754440 --- /dev/null +++ b/docs/guides/firmware/android-ota-payload.md @@ -0,0 +1,93 @@ +# Android OTA update payloads + +`inspect-artifact` and `extract-artifact` recognize a CrAU v2 `payload.bin` +from Android A/B and virtual A/B OTA packages by the four-byte `CrAU` magic, +independent of the file name. They read the local header and +`DeltaArchiveManifest` protobuf without applying the update, verifying +signatures, or executing postinstall. + +The same domain facts and artifact reader serve CLI and MCP. The root is an +archive with unknown executable architecture. Major version 2 is supported; +a readable major version other than 2 is refused. Version 1 Chrome OS-style +headers are that refusal, not a different container. + +```sh +rea inspect-artifact ./payload.bin --detail summary \ + --evidence_output payload.evidence.json --json +rea extract-artifact ./payload.bin --json +``` + +With MCP, `open_binary` then `inspect_artifact` with `detail: "summary"` +retains the complete Evidence. Use `inspect_analysis_view` and its +`parent_evidence_id` for exact logical paths and selected fields. + +## Header, manifest and signatures + +Root `format_metadata` records the 24-byte v2 header (magic, major version, +manifest size, metadata signature size, manifest and blob offsets) and the +decoded manifest: `block_size`, `minor_version` (`0` is a full payload; +greater than `0` is a delta), `max_timestamp`, `partial_update`, +`security_patch_level` when present, dynamic partition groups, Virtual A/B +flags (`snapshot_enabled`, `vabc_enabled`, `vabc_compression_param`) and +`apex_info` entries. + +The summary view keeps those header and manifest scalars under kind +`android-ota-payload-summary` and replaces the partition, dynamic partition +group and `apex_info` arrays with `partition_count`, +`extractable_partition_count`, `dynamic_partition_group_count` and +`apex_info_count`. The complete Evidence and the paged inventory views keep +every array. + +Each partition is an occurrence (`boot.img`, `system.img`, …) with its +`new_partition_info` size and SHA-256 hex, optional `old_partition_info` for +deltas, version, postinstall fields, operation counts by type (unknown +enumerators stay `unknown`), total blob data length, merge operation count +and `estimate_cow_size`. Operation types include REPLACE, ZERO, +REPLACE_BZ/XZ/ZSTD, SOURCE_COPY, BSDIFF family, PUFFDIFF, ZUCCHINI and +LZ4DIFF. + +Metadata and payload signature blobs are counted from the `Signatures` +protobuf. `signatures_verified` is always `false`: sizes and counts are +facts, not a cryptographic check. `payload_properties.txt` and +`META-INF/com/android/metadata` beside a zip member are out of scope. A zip +that already lists `payload.bin` still classifies that member by `CrAU` +magic; zip inventory does not recurse into its partitions. + +## Extraction + +A partition is reconstructed only when every install operation is REPLACE, +ZERO or REPLACE_ZSTD (via `node:zlib` zstd), the new size is known and at +most 32 MiB, and every needed blob extent is present. The reconstructed +image is checked against `new_partition_info.hash` when that hash is +present. Any other operation type leaves the occurrence inventoried with +`hash_status: unavailable` and refuses extraction of that member. +Delta payloads therefore inventory completely and fail a full extract. + +A truncated file whose header and manifest still fit keeps the partition +table and records that the blob was truncated. Bytes past end of file are +not invented as zeros. + +## Bounded work + +The reader admits at most 16 MiB of manifest, 4096 partitions, 65,536 +operations per partition, 262,144 operations in total, 1,048,576 source +and destination extents in total, 1 MiB per signature blob, 64 +signatures, 256 dynamic groups and 4096 apex entries. Those ceilings are +resource policy. Shared artifact identity hashing has separate +cost. Partition reconstruction is bounded at 32 MiB per image and runs when +a member is opened, not during inventory of the manifest. REPLACE_ZSTD +decode is bounded to destination extent bytes, never above that 32 MiB +extract ceiling. Opening a partition refuses when distinct operation blob +bytes exceed the 32 MiB operation-data budget. + +## Verification scope + +Source and compiled CLI/MCP tests cover synthesized CrAU v2 full and delta +payloads, Virtual A/B and apex fields, unknown operation types, v1 +refusal, truncated blobs with a complete manifest, oversize counts, +malformed protobuf, hash match and mismatch, nested zip member +classification, REPLACE_ZSTD output past destination extents, and +distinct operation blob data past the read budget. Signatures are not +verified against device keys. Delta and compressed operations other than +REPLACE_ZSTD are not applied. A public factory OTA image is not required +for these fixtures. diff --git a/docs/guides/firmware/firmware-analysis.md b/docs/guides/firmware/firmware-analysis.md index bb584d2bdf..d5a1639db5 100644 --- a/docs/guides/firmware/firmware-analysis.md +++ b/docs/guides/firmware/firmware-analysis.md @@ -359,6 +359,15 @@ payloads stay as stored. Intel HEX/S-record and FIT images are separate readers and are not covered here. See [U-Boot legacy uImage](../../uimage.md) for component padding, preserved names, resource policies and verification scope. +## Inspect Android OTA update payloads + +`inspect-artifact` / `extract-artifact` recognize a CrAU v2 `payload.bin` by +magic and inventory its DeltaArchiveManifest without applying the update or +verifying signatures. Full payloads can reconstruct REPLACE, ZERO and +REPLACE_ZSTD partition images; delta operations stay inventoried and refuse +extraction. See [Android OTA update payloads](android-ota-payload.md) +for header facts, operation types, limits and verification scope. + ## Inspect UF2 and DfuSe images Use `inspect-artifact` / `inspect_artifact` on a UF2 file for each familyID's diff --git a/docs/index.md b/docs/index.md index 902adbe85f..a787a3758e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,19 +49,19 @@ For runtime instrumentation, see the [Frida guide](guides/runtime/frida-instrume The [documentation directory](README.md) lists every guide by domain. -| Task | Guides | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) | -| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) | -| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) | -| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) | -| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) | -| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [Android boot images](android-boot-image.md), [.NET](guides/managed/managed-code-analysis.md), [NuGet packages](guides/managed/nuget-nupkg.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) | -| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) | -| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) | -| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) | -| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) | -| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) | +| Task | Guides | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) | +| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) | +| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) | +| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) | +| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) | +| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [Android boot images](android-boot-image.md), [.NET](guides/managed/managed-code-analysis.md), [NuGet packages](guides/managed/nuget-nupkg.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [Android OTA payloads](guides/firmware/android-ota-payload.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) | +| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) | +| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) | +| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) | +| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) | +| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) | For development, use [testing](development/testing.md), [client verification](development/client-verification.md), [tool design](development/tool-design.md), [admission limits and recovery](design/limits-and-recovery.md), diff --git a/docs/specs/firmware/android-ota-payload/plan.md b/docs/specs/firmware/android-ota-payload/plan.md new file mode 100644 index 0000000000..a56d908257 --- /dev/null +++ b/docs/specs/firmware/android-ota-payload/plan.md @@ -0,0 +1,43 @@ +# Implementation plan + +## Boundary and contract + +Follow the existing artifact readers. `src/domain/firmware/androidOtaPayload.ts` +owns CrAU header and `DeltaArchiveManifest` decode, recognition, reconstruction +and capacity ceilings. `src/domain/artifactFormatMetadata.ts` owns the +`android-ota-payload` and `android-ota-partition` result schemas. +`AndroidOtaPayloadArtifactReader` reads the admitted file through +`ArtifactFileSource`, inventories partitions from the manifest, and +reconstructs extractable images on `open()`. + +Recognition lives in `recognizeAndroidOtaPayload` and is applied in the +shared `ARTIFACT_FORMAT_RECOGNIZERS` table immediately after uImage, so +inventory classification and binary target resolution share one verdict. +A v1 (or other non-v2) header is refused like an ESP8266 image: nested +classification keeps a plain file; `open_binary` reports the unsupported +version. + +Field numbers are taken from AOSP `system/update_engine/update_metadata.proto` +(`chromeos_update_engine`). Unknown protobuf fields are skipped. The proto +is not vendored. + +## Incremental work and validation + +1. Define header, manifest, signature-count and reconstruction contracts with + synthesized CrAU fixtures. +2. Implement parse, recognition and REPLACE/ZERO/REPLACE_ZSTD reconstruction + with typed format, unsupported-version, capacity, unsupported-operation + and integrity failures. +3. Add the reader, format descriptor and byte classification. +4. Wire CLI/MCP through the existing inspect/extract artifact contracts. +5. Document the workflow and limits. + +## Effects and compatibility + +The inventory reads one caller-selected payload file. Nested zip members +named `payload.bin` classify by magic when the zip reader already surfaces +them; zip inventory does not recurse into partitions. The change adds no +target execution, injection, mutation, protection recovery, network access +or live device update, so no maintainer scope decision is required. +Existing format routing is unchanged; the new format id appears only for +CrAU v2 bytes. diff --git a/docs/specs/firmware/android-ota-payload/spec.md b/docs/specs/firmware/android-ota-payload/spec.md new file mode 100644 index 0000000000..f51ce18d3d --- /dev/null +++ b/docs/specs/firmware/android-ota-payload/spec.md @@ -0,0 +1,49 @@ +# Android OTA payload inspection + +This specification records an implementation increment and its original +problem statement. For current behavior and limitations, see +[Android OTA update payloads](../../../guides/firmware/android-ota-payload.md). + +## Problem and outcome + +REA has no reader for Android A/B OTA `payload.bin` files (update_engine, +magic `CrAU`). An analyst holding a payload cannot ask which partitions it +writes, what sizes and hashes the manifest declares, whether the payload is +full or delta, or which operations are present. Add a read-only inspector +that inventories the header and `DeltaArchiveManifest` and, when cheap, +reconstructs REPLACE/ZERO/REPLACE_ZSTD partition images. + +## Requirements + +- Recognize CrAU v2 from leading bytes under any file name. Report a + readable major version other than 2 as an unsupported-version refusal. +- Decode the v2 header and the manifest fields listed in the product guide: + block size, minor version, timestamps, partial update, security patch, + per-partition identities, operation counts, Virtual A/B groups and + apex_info. +- Count metadata and payload signature blobs without verifying them. +- Reconstruct a partition only when every operation is REPLACE, ZERO or + REPLACE_ZSTD, the new size is known and within the extract ceiling, and + needed blob extents are present. Bound REPLACE_ZSTD decode to destination + extent bytes, never above the extract ceiling, and refuse a partition + open when distinct operation blob bytes exceed the operation-data + budget. Verify the image against the declared hash when present. Other + operation types stay inventoried and refuse content reads. +- Keep a complete manifest inventory when the blob is truncated. Refuse + malformed magic, truncated headers or manifests, oversize counts, and + operation extents that overrun the blob, without inventing zeros. + +## Acceptance + +Synthesized fixtures cover a full payload with REPLACE and ZERO operations, +dynamic groups and apex_info; a delta payload with SOURCE_COPY and +BROTLI_BSDIFF; an unknown operation type; v1 refusal; truncated blob with +complete manifest; oversize manifest; malformed protobuf; and hash +match/mismatch. Reader, CLI and MCP tests use those fixtures. Nested zip +`payload.bin` members classify by magic. + +## Non-goals + +Signature verification, applying delta or compressed operations other than +REPLACE_ZSTD, reading `payload_properties.txt` or zip metadata, recursive +zip inventory of partitions, and device-side update_engine execution. diff --git a/docs/specs/firmware/android-ota-payload/tasks.md b/docs/specs/firmware/android-ota-payload/tasks.md new file mode 100644 index 0000000000..df97e4745b --- /dev/null +++ b/docs/specs/firmware/android-ota-payload/tasks.md @@ -0,0 +1,11 @@ +# Tasks + +- [x] Define the first-step scope, contract and limits. +- [x] Parse the CrAU v2 header and DeltaArchiveManifest with synthesized + fixtures and explicit limitations. +- [x] Reconstruct REPLACE, ZERO and REPLACE_ZSTD partitions with hash + verification; refuse other operation types. +- [x] Add the reader, format descriptor and byte classification. +- [x] Cover CLI inspect/extract and MCP open/inspect/extract on fixtures, + including v1 refusal and truncated-blob inventory. +- [x] Document the workflow, limits and verification scope. diff --git a/scripts/verify/advertised-schemas/tools/open_binary.json b/scripts/verify/advertised-schemas/tools/open_binary.json index cb11208ca2..b2b48403f7 100644 --- a/scripts/verify/advertised-schemas/tools/open_binary.json +++ b/scripts/verify/advertised-schemas/tools/open_binary.json @@ -1,7 +1,7 @@ { "schemas": { "input compact": "706f1985ca397688", - "output compact": "c100ceae46994f08" + "output compact": "9cda19dfa1310afa" }, "patterns": { "input": [ @@ -9,7 +9,6 @@ "^0x[0-9A-Fa-f]{1,8}$", "^[^\\x00]*$", "^[a-z][\\-0-9a-z]*$" - ], - "output": ["^0x[0-9A-Fa-f]{1,16}$", "^[0-9a-f]{64}$"] + ] } } diff --git a/src/application/binary/TargetFormatVocabularies.test.ts b/src/application/binary/TargetFormatVocabularies.test.ts index 8278e1fb83..3bc8ad0df4 100644 --- a/src/application/binary/TargetFormatVocabularies.test.ts +++ b/src/application/binary/TargetFormatVocabularies.test.ts @@ -123,6 +123,7 @@ const TARGETS: TargetFixtures = { wxapkg: { ...archive, format: "wxapkg" }, uimage: { ...archive, format: "uimage" }, "android-boot-image": { ...archive, format: "android-boot-image" }, + "android-ota-payload": { ...archive, format: "android-ota-payload" }, uf2: { ...archive, format: "uf2" }, dfuse: { ...archive, format: "dfuse" }, dmg: { ...archive, format: "dmg" }, diff --git a/src/artifacts/AndroidOtaPayloadArtifactReader.boundaries.test.ts b/src/artifacts/AndroidOtaPayloadArtifactReader.boundaries.test.ts new file mode 100644 index 0000000000..c4371d5ff8 --- /dev/null +++ b/src/artifacts/AndroidOtaPayloadArtifactReader.boundaries.test.ts @@ -0,0 +1,174 @@ +import { artifactPreparationRecoveryCases } from "../../tests/fixtures/artifactReaderLifecycle.js"; +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { buffer } from "node:stream/consumers"; +import { expect, it, vi } from "vitest"; + +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; +import { openRegularFile } from "../filesystem/RegularFile.js"; +import { AndroidOtaPayloadArtifactReader } from "./AndroidOtaPayloadArtifactReader.js"; +import { + buildAndroidOtaPayload, + fullAndroidOtaPayload, + v1AndroidOtaPayload, +} from "../domain/firmware/androidOtaPayload.fixture.js"; +import { + ANDROID_OTA_MAX_MANIFEST_BYTES, + ANDROID_OTA_MAX_OPERATION_DATA_BYTES, +} from "../domain/firmware/androidOtaPayload.js"; + +const fixture = async (bytes: Buffer): Promise => { + const path = join( + await createTestTempDirectory("rea-android-ota-boundary-"), + "payload.bin", + ); + await writeFile(path, bytes); + return path; +}; + +const entries = async (reader: AndroidOtaPayloadArtifactReader) => { + const result = []; + for await (const entry of reader.entries()) result.push(entry); + return result; +}; + +it("refuses a v1 payload as unavailable rather than as a container", async () => { + const reader = new AndroidOtaPayloadArtifactReader( + await fixture(v1AndroidOtaPayload()), + ); + try { + await expect(entries(reader)).rejects.toMatchObject({ + reason: "unavailable", + }); + } finally { + await reader.close(); + } +}); + +it("reports an oversize declared manifest as a capacity limit", async () => { + const bytes = Buffer.alloc(24); + bytes.write("CrAU", 0, "latin1"); + bytes.writeBigUInt64BE(2n, 4); + bytes.writeBigUInt64BE(BigInt(ANDROID_OTA_MAX_MANIFEST_BYTES + 1), 12); + const reader = new AndroidOtaPayloadArtifactReader(await fixture(bytes)); + try { + await expect(entries(reader)).rejects.toMatchObject({ + reason: "limit", + boundary: "capacity", + }); + } finally { + await reader.close(); + } +}); + +it("streams a mismatched REPLACE partition and leaves its declared hash to the scanner", async () => { + const reader = new AndroidOtaPayloadArtifactReader( + await fixture( + buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + newHash: Buffer.alloc(32, 0xaa), + operations: [{ type: 0, data: Buffer.from("BOOT") }], + }, + ], + }), + ), + ); + try { + const [entry] = await entries(reader); + expect(entry?.declaredIntegrity).toEqual({ + algorithm: "sha256", + digest: "aa".repeat(32), + }); + const bytes = await buffer(await reader.open(entry!)); + expect(bytes.subarray(0, 4).toString("latin1")).toBe("BOOT"); + } finally { + await reader.close(); + } +}); + +it("refuses to open a partition whose distinct operation data exceeds the read budget", async () => { + const reader = new AndroidOtaPayloadArtifactReader( + await fixture( + buildAndroidOtaPayload({ + partitions: [ + { + name: "system", + newSize: 4096, + operations: [ + { + type: 0, + data: Buffer.alloc( + ANDROID_OTA_MAX_OPERATION_DATA_BYTES + 1, + 0x41, + ), + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ], + }, + ], + }), + ), + ); + try { + const listed = await entries(reader); + await expect(reader.open(listed[0]!)).rejects.toMatchObject({ + reason: "limit", + boundary: "capacity", + }); + } finally { + await reader.close(); + } +}); + +it("preserves cancellation while reconstructing a partition", async () => { + const path = await fixture( + buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + operations: [{ type: 0, data: Buffer.alloc(64 * 1024, 0x61) }], + }, + ], + }), + ); + const admitted = await openRegularFile(path, { symlinks: "reject" }); + const reader = new AndroidOtaPayloadArtifactReader(path, admitted); + const controller = new AbortController(); + const reason = new Error("cancel reconstruction"); + const nativeRead = admitted.handle.read.bind(admitted.handle); + const reads = vi.spyOn(admitted.handle, "read").mockImplementation((async ( + ...args: unknown[] + ) => { + const result = await Reflect.apply(nativeRead, admitted.handle, args); + if (args[3] !== 0) controller.abort(reason); + return result; + }) as typeof admitted.handle.read); + try { + const [entry] = await entries(reader); + await expect(reader.open(entry!, controller.signal)).rejects.toMatchObject({ + reason: "cancelled", + cause: reason, + }); + reads.mockRestore(); + const recovered = await entries(reader); + expect(recovered).toHaveLength(1); + expect( + (await buffer(await reader.open(recovered[0]!))).subarray(0, 1)[0], + ).toBe(0x61); + } finally { + try { + await reader.close(); + } finally { + reads.mockRestore(); + await admitted.handle.close(); + } + } +}); + +artifactPreparationRecoveryCases({ + image: () => fullAndroidOtaPayload(), + createReader: (path, admitted) => + new AndroidOtaPayloadArtifactReader(path, admitted), +}); diff --git a/src/artifacts/AndroidOtaPayloadArtifactReader.test.ts b/src/artifacts/AndroidOtaPayloadArtifactReader.test.ts new file mode 100644 index 0000000000..58ebdc8ee1 --- /dev/null +++ b/src/artifacts/AndroidOtaPayloadArtifactReader.test.ts @@ -0,0 +1,342 @@ +import { createHash } from "node:crypto"; +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { buffer } from "node:stream/consumers"; + +import { expect, it } from "vitest"; + +import { AndroidOtaPayloadArtifactReader } from "./AndroidOtaPayloadArtifactReader.js"; +import { ArtifactEntryContentUnavailable } from "../resources/ArtifactReader.js"; +import { ArtifactResourceScope } from "../resources/ArtifactResourceScope.js"; +import { extractArtifact } from "./extraction/ArtifactExtraction.js"; +import { + buildAndroidOtaPayload, + deltaAndroidOtaPayload, + fullAndroidOtaPayload, + v1AndroidOtaPayload, +} from "../domain/firmware/androidOtaPayload.fixture.js"; +import { zipArchive } from "../domain/desktop/zipArchive.fixture.js"; +import { classifyArtifactBytesAtPath } from "../../tests/fixtures/artifactClassification.js"; +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; +import { scanCanonicalArtifactInventory } from "../../tests/fixtures/artifactInventory.js"; + +const writeCarrier = async (name: string, bytes: Buffer): Promise => { + const path = join(await createTestTempDirectory("rea-android-ota-"), name); + await writeFile(path, bytes); + return path; +}; + +it("classifies OTA payload bytes as a container by magic, not by suffix", () => { + expect( + classifyArtifactBytesAtPath("update.bin", fullAndroidOtaPayload()), + ).toEqual({ + kind: "container", + format: "android-ota-payload", + }); + expect( + classifyArtifactBytesAtPath("payload.bin", Buffer.from("nope")), + ).toEqual({ + kind: "resource", + format: "file", + }); + expect( + classifyArtifactBytesAtPath("payload.bin", v1AndroidOtaPayload()), + ).toEqual({ + kind: "resource", + format: "file", + }); +}); + +it("classifies a nested payload.bin member by CrAU magic", async () => { + const nested = fullAndroidOtaPayload(); + expect(classifyArtifactBytesAtPath("ota/payload.bin", nested)).toEqual({ + kind: "container", + format: "android-ota-payload", + }); + const archive = zipArchive([ + { name: "payload.bin", data: nested, method: 0 }, + ]); + expect(classifyArtifactBytesAtPath("update.zip", archive)).toEqual({ + kind: "container", + format: "zip", + }); + const snapshot = await scanCanonicalArtifactInventory( + await writeCarrier("update.zip", archive), + ); + expect(snapshot.manifest.root_format).toBe("zip"); + expect( + snapshot.occurrences.find((row) => row.logical_path === "payload.bin"), + ).toMatchObject({ + artifact_format: "android-ota-payload", + artifact_kind: "container", + }); +}); + +it("inventories full-payload partitions, groups, signatures and extractable images", async () => { + const bytes = fullAndroidOtaPayload(); + const snapshot = await scanCanonicalArtifactInventory( + await writeCarrier("payload.bin", bytes), + ); + expect(snapshot.manifest.root_format).toBe("android-ota-payload"); + expect(snapshot.coverage.status).toBe("complete"); + expect(snapshot.limitations.join(" ")).toContain("not verified"); + const root = snapshot.occurrences.find((row) => row.logical_path === "."); + expect(root).toMatchObject({ + artifact_kind: "container", + format_metadata: { + kind: "android-ota-payload", + magic: "CrAU", + major_version: 2, + payload_kind: "full", + signatures_verified: false, + snapshot_enabled: true, + vabc_enabled: true, + security_patch_level: "2024-01-05", + }, + }); + expect(root?.format_metadata).toMatchObject({ + kind: "android-ota-payload", + dynamic_partition_groups: [{ name: "super", partition_names: ["system"] }], + apex_info: [{ package_name: "com.android.runtime" }], + }); + const members = snapshot.occurrences.filter( + (row) => row.logical_path !== ".", + ); + expect(members.map((row) => [row.logical_path, row.hash_status])).toEqual([ + ["boot.img", "verified"], + ["system.img", "verified"], + ]); + expect(members[0]?.format_metadata).toMatchObject({ + kind: "android-ota-partition", + name: "boot", + extractable: true, + }); +}); + +it("inventories a delta payload and leaves non-extractable partitions unread", async () => { + const snapshot = await scanCanonicalArtifactInventory( + await writeCarrier("delta.bin", deltaAndroidOtaPayload()), + ); + expect(snapshot.manifest.root_format).toBe("android-ota-payload"); + const vendor = snapshot.occurrences.find( + (row) => row.logical_path === "vendor.img", + ); + expect(vendor).toMatchObject({ + hash_status: "unavailable", + format_metadata: { + kind: "android-ota-partition", + extractable: false, + operation_counts: [ + { type: "SOURCE_COPY", type_code: 4, count: 1 }, + { type: "BROTLI_BSDIFF", type_code: 10, count: 1 }, + ], + }, + }); + expect(vendor?.limitations.join(" ")).toContain("not applied"); +}); + +it("extracts reconstructed REPLACE and ZERO images", async () => { + const path = await writeCarrier("payload.bin", fullAndroidOtaPayload()); + const resourceScope = new ArtifactResourceScope(); + try { + const extracted = await extractArtifact({ + inputPath: path, + inputFormat: "android-ota-payload", + outputRoot: join(path, "..", "out"), + environment: process.env, + integrityPolicy: "fail", + resourceScope, + }); + expect(extracted.containment_verified).toBe(true); + const boot = await readFile(join(extracted.output_root, "boot.img")); + expect(boot.subarray(0, 7).toString("latin1")).toBe("BOOTIMG"); + const system = await readFile(join(extracted.output_root, "system.img")); + expect(system.equals(Buffer.alloc(8192))).toBe(true); + } finally { + await resourceScope.close(); + } +}); + +it("refuses to extract a delta partition", async () => { + const path = await writeCarrier("delta.bin", deltaAndroidOtaPayload()); + const reader = new AndroidOtaPayloadArtifactReader(path); + try { + const entries = []; + for await (const entry of reader.entries()) entries.push(entry); + await expect(reader.open(entries[0]!)).rejects.toBeInstanceOf( + ArtifactEntryContentUnavailable, + ); + } finally { + await reader.close(); + } + const resourceScope = new ArtifactResourceScope(); + try { + await expect( + extractArtifact({ + inputPath: path, + inputFormat: "android-ota-payload", + outputRoot: join(path, "..", "out"), + environment: process.env, + integrityPolicy: "fail", + resourceScope, + }), + ).rejects.toMatchObject({ + reason: "unavailable", + message: expect.stringContaining("vendor.img"), + }); + } finally { + await resourceScope.close(); + } +}); + +it("keeps the manifest when a partition exceeds the extraction limit", async () => { + const path = await writeCarrier( + "large.bin", + buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + operations: [{ type: 0, data: Buffer.from("KERNEL") }], + }, + { + name: "system", + newSize: 64 * 1024 * 1024, + newHash: Buffer.alloc(32, 0xaa), + operations: [ + { type: 6, dstExtents: [{ startBlock: 0, numBlocks: 1 }] }, + ], + }, + ], + }), + ); + const reader = new AndroidOtaPayloadArtifactReader(path); + try { + const entries = []; + for await (const entry of reader.entries()) entries.push(entry); + const system = entries.find((entry) => entry.path === "system.img"); + await expect(reader.open(system!)).rejects.toBeInstanceOf( + ArtifactEntryContentUnavailable, + ); + } finally { + await reader.close(); + } + const kept = await scanCanonicalArtifactInventory(path); + expect(kept.manifest.root_format).toBe("android-ota-payload"); + expect( + kept.occurrences.find((row) => row.logical_path === ".")?.format_metadata, + ).toMatchObject({ + kind: "android-ota-payload", + partitions: [{ name: "boot" }, { name: "system" }], + }); + expect( + kept.occurrences.find((row) => row.logical_path === "system.img") + ?.hash_status, + ).toBe("unavailable"); +}); + +it("keeps partition inventory when the blob is truncated", async () => { + const full = fullAndroidOtaPayload(); + const snapshot = await scanCanonicalArtifactInventory( + await writeCarrier("payload.bin", full), + ); + const blobOffset = snapshot.occurrences.find( + (row) => row.logical_path === ".", + )?.format_metadata; + expect(blobOffset?.kind).toBe("android-ota-payload"); + if (blobOffset?.kind !== "android-ota-payload") return; + const truncated = full.subarray(0, blobOffset.blob_offset + 1); + const kept = await scanCanonicalArtifactInventory( + await writeCarrier("truncated.bin", truncated), + ); + expect(kept.manifest.root_format).toBe("android-ota-payload"); + expect(kept.coverage.status).toBe("unknown"); + expect(kept.limitations.join(" ")).toContain("truncated"); + expect( + kept.occurrences.find((row) => row.logical_path === ".")?.format_metadata, + ).toMatchObject({ + kind: "android-ota-payload", + blob_truncated: true, + partitions: [{ name: "boot" }, { name: "system" }], + }); + expect( + kept.occurrences.find((row) => row.logical_path === "boot.img") + ?.hash_status, + ).toBe("unavailable"); +}); + +it("streams a reconstructed partition whose hash matches the manifest", async () => { + const path = await writeCarrier( + "boot.bin", + buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + operations: [{ type: 0, data: Buffer.from("KERNEL") }], + }, + ], + }), + ); + const reader = new AndroidOtaPayloadArtifactReader(path); + try { + const listed = []; + for await (const item of reader.entries()) listed.push(item); + const [entry] = listed; + const bytes = await buffer(await reader.open(entry!)); + expect(bytes.subarray(0, 6).toString("latin1")).toBe("KERNEL"); + expect(createHash("sha256").update(bytes).digest("hex")).toBe( + entry?.declaredIntegrity && "digest" in entry.declaredIntegrity + ? entry.declaredIntegrity.digest + : "", + ); + } finally { + await reader.close(); + } +}); + +it("applies the caller's integrity policy to a partition hash mismatch", async () => { + const path = await writeCarrier( + "mismatch.bin", + buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + newHash: Buffer.alloc(32, 0xff), + operations: [{ type: 0, data: Buffer.from("KERNEL") }], + }, + ], + }), + ); + await expect(scanCanonicalArtifactInventory(path)).rejects.toMatchObject({ + reason: "integrity", + }); + const recorded = await scanCanonicalArtifactInventory(path, { + integrity: "record-and-continue", + }); + expect( + recorded.occurrences.find((row) => row.logical_path === "boot.img"), + ).toMatchObject({ hash_status: "mismatched" }); + expect(recorded.integrity_contradictions).toEqual([ + expect.objectContaining({ + logical_path: "boot.img", + trust: "observed-untrusted", + }), + ]); + const resourceScope = new ArtifactResourceScope(); + try { + const extracted = await extractArtifact({ + inputPath: path, + inputFormat: "android-ota-payload", + outputRoot: join(path, "..", "out"), + environment: process.env, + integrityPolicy: "record-and-continue", + resourceScope, + }); + const boot = await readFile(join(extracted.output_root, "boot.img")); + expect(boot.subarray(0, 6).toString("latin1")).toBe("KERNEL"); + expect(extracted.integrity_contradictions).toEqual([ + expect.objectContaining({ logical_path: "boot.img" }), + ]); + } finally { + await resourceScope.close(); + } +}); diff --git a/src/artifacts/AndroidOtaPayloadArtifactReader.ts b/src/artifacts/AndroidOtaPayloadArtifactReader.ts new file mode 100644 index 0000000000..b36f9a4a9d --- /dev/null +++ b/src/artifacts/AndroidOtaPayloadArtifactReader.ts @@ -0,0 +1,461 @@ +import { ArtifactPreparation } from "./ArtifactPreparation.js"; +import { Readable, Transform } from "node:stream"; +import { setImmediate } from "node:timers/promises"; + +import type { + AndroidOtaPartitionMetadata, + AndroidOtaPayloadMetadata, +} from "../domain/artifactFormatMetadata.js"; +import { readArtifactFileBytes } from "./ArtifactFileRange.js"; +import { + assertArtifactReadActive, + ArtifactEntryContentUnavailable, + ArtifactReaderFailure, + copyArtifactEntry, + assertProducedEntry, + type ArtifactEntry, + type ArtifactReader, + type ArtifactTraversalOptions, + ArtifactResourceScope, + ArtifactFileSource, +} from "../resources/index.js"; +import { ownArtifactStream } from "./OwnedArtifactStream.js"; +import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js"; +import { + ANDROID_OTA_HEADER_V2_BYTES, + androidOtaDistinctOperationDataBytes, + androidOtaExtractRefusalError, + androidOtaExtractRefusalLimitation, + parseAndroidOtaHeader, + parseAndroidOtaPayload, + reconstructAndroidOtaPartition, + type AndroidOtaPartition, + type AndroidOtaPayload, + type AndroidOtaPayloadParseError, + type AndroidOtaPayloadReconstructError, +} from "../domain/firmware/androidOtaPayload.js"; + +const LABEL = "Android OTA payload"; + +type AndroidOtaEntry = ArtifactEntry & { + readonly partition: AndroidOtaPartition; + readonly formatMetadata: AndroidOtaPartitionMetadata; +}; + +/** Inventory a CrAU v2 payload without applying delta operations or verifying signatures. */ +export class AndroidOtaPayloadArtifactReader implements ArtifactReader { + readonly format = "android-ota-payload" as const; + readonly #scope = new ArtifactResourceScope(); + readonly #entries = new Map(); + readonly #streams = new Set(); + readonly #source: ArtifactFileSource; + readonly #preparation = new ArtifactPreparation(); + #payload: AndroidOtaPayload | undefined; + #closing = false; + + constructor(path: string, admitted?: StableRegularFileDescriptor) { + this.#source = new ArtifactFileSource(path, LABEL, admitted); + } + + formatMetadata(): AndroidOtaPayloadMetadata | undefined { + return this.#payload === undefined ? undefined : toMetadata(this.#payload); + } + + async prepareContainer( + expectedSha256: string, + signal?: AbortSignal, + ): Promise { + await this.#scope.run(async () => { + this.#assertOpen(signal); + await this.#source.bindSha256(expectedSha256, signal); + }); + } + + async *entries( + signal?: AbortSignal, + options?: ArtifactTraversalOptions, + ): AsyncIterable { + await this.#scope.run(async () => { + this.#assertOpen(signal); + await this.#preparation.run( + signal, + () => this.#prepare(signal), + () => this.#assertOpen(signal), + ); + await this.#source.read(signal); + }); + this.#assertOpen(signal); + options?.onCoverage?.({ + status: "complete", + limitations: this.#payload?.limitations ?? [], + }); + let index = 0; + for (const entry of this.#entries.values()) { + if (index % 256 === 0) await setImmediate(); + index += 1; + this.#assertOpen(signal); + yield copyArtifactEntry(entry); + } + this.#assertOpen(signal); + } + + async open(entry: ArtifactEntry, signal?: AbortSignal): Promise { + return this.#scope.run(async () => { + this.#assertOpen(signal); + const stored = this.#entries.get(entry.adapterKey); + assertProducedEntry( + entry, + stored, + "Android OTA partition does not match its owning inventory", + ); + const { handle, initial } = await this.#source.read(signal); + this.#assertOpen(signal); + const refused = androidOtaExtractRefusalError(stored.partition); + if (refused !== null && stored.partition.extractRefusal !== null) + throw refusedContent(stored.partition.extractRefusal, refused); + const payload = this.#payload; + if (payload === undefined) + throw new ArtifactReaderFailure( + "unavailable", + "Android OTA payload reader has no prepared inventory", + ); + const operationData = androidOtaDistinctOperationDataBytes( + stored.partition.operations, + ); + if (!operationData.ok) throw reconstructFailure(operationData.error); + const blob = new Map(); + for (const operation of stored.partition.operations) { + if (operation.dataLength === 0) continue; + const key = `${String(operation.dataOffset)}:${String(operation.dataLength)}`; + if (blob.has(key)) continue; + blob.set( + key, + await readArtifactFileBytes( + handle, + payload.header.blobOffset + operation.dataOffset, + operation.dataLength, + initial.size, + signal, + ), + ); + this.#assertOpen(signal); + } + await this.#source.read(signal); + this.#assertOpen(signal); + const reconstructed = reconstructAndroidOtaPartition( + stored.partition, + payload.blockSize, + (offset, length) => + blob.get(`${String(offset)}:${String(length)}`) ?? new Uint8Array(), + // A SHA-256 claim on the entry is checked by the shared scanner under + // the caller's integrity policy, so record-and-continue can keep the + // observed bytes. Without that claim the reader checks it here. + { verifyDeclaredHash: stored.declaredIntegrity === null }, + ); + if (!reconstructed.ok) throw reconstructFailure(reconstructed.error); + const cancellationFailure = (reason: unknown): ArtifactReaderFailure => + new ArtifactReaderFailure("cancelled", `${LABEL} read cancelled`, { + cause: reason, + }); + const image = Buffer.from(reconstructed.value); + const source = + image.length === 0 ? Readable.from([]) : Readable.from([image]); + const output = this.#memberStream(stored, image.length, signal); + ownArtifactStream(source, output, { + scope: this.#scope, + streams: this.#streams, + signal, + cancellationFailure, + label: LABEL, + }); + return output; + }); + } + + async close(): Promise { + this.#closing = true; + for (const stream of this.#streams) + stream.destroy( + new ArtifactReaderFailure("unavailable", `${LABEL} reader closed`), + ); + await this.#scope.close(); + await this.#source.close(); + this.#entries.clear(); + this.#payload = undefined; + } + + provenance(): readonly [] { + return []; + } + + #assertOpen(signal?: AbortSignal): void { + assertArtifactReadActive(signal); + if (this.#closing) + throw new ArtifactReaderFailure("unavailable", `${LABEL} reader closed`); + } + + async #prepare(signal?: AbortSignal): Promise { + const { handle, initial } = await this.#source.read(signal); + const headerBytes = await readArtifactFileBytes( + handle, + 0, + Math.min(initial.size, ANDROID_OTA_HEADER_V2_BYTES), + initial.size, + signal, + ); + const header = parseAndroidOtaHeader(headerBytes, initial.size); + if (!header.ok) throw parseFailure(header.error); + const prefixEnd = Math.min(initial.size, header.value.blobOffset); + const prefix = await readArtifactFileBytes( + handle, + 0, + prefixEnd, + initial.size, + signal, + ); + const first = parseAndroidOtaPayload(prefix, initial.size); + if (!first.ok) throw parseFailure(first.error); + let payloadSignature: Uint8Array | undefined; + if ( + first.value.signaturesOffset !== null && + first.value.signaturesSize !== null && + first.value.signaturesSize > 0 + ) { + const start = header.value.blobOffset + first.value.signaturesOffset; + const end = start + first.value.signaturesSize; + if (Number.isSafeInteger(end) && end <= initial.size) { + payloadSignature = await readArtifactFileBytes( + handle, + start, + first.value.signaturesSize, + initial.size, + signal, + ); + } + } + await this.#source.read(signal); + this.#assertOpen(signal); + const parsed = parseAndroidOtaPayload( + prefix, + initial.size, + payloadSignature, + ); + if (!parsed.ok) throw parseFailure(parsed.error); + this.#payload = parsed.value; + this.#entries.clear(); + for (const partition of parsed.value.partitions) { + const entry = entryFor(partition); + this.#entries.set(entry.adapterKey, entry); + } + } + + #memberStream( + entry: AndroidOtaEntry, + expectedSize: number, + signal?: AbortSignal, + ): Transform { + let bytes = 0; + const check = async (): Promise => { + if (bytes !== expectedSize) + throw formatFailure(`member ended early: ${entry.path}`); + await this.#source.read(signal); + }; + return new Transform({ + transform(chunk: Buffer, _encoding, callback) { + bytes += chunk.length; + callback(null, chunk); + }, + flush(callback) { + void check().then( + () => callback(), + (cause: unknown) => + callback( + cause instanceof Error + ? cause + : new Error("Android OTA payload read failed", { cause }), + ), + ); + }, + }); + } +} + +const formatFailure = ( + detail: string, + options?: ErrorOptions, +): ArtifactReaderFailure => + new ArtifactReaderFailure( + "format", + `${LABEL} is malformed: ${detail}`, + options, + ); + +const parseFailure = ( + failure: AndroidOtaPayloadParseError, +): ArtifactReaderFailure => { + switch (failure.kind) { + case "limit": + return new ArtifactReaderFailure("limit", failure.message, { + boundary: "capacity", + cause: failure, + }); + case "unsupported": + return new ArtifactReaderFailure("unavailable", failure.message, { + cause: failure, + }); + case "truncated": + return new ArtifactReaderFailure("format", failure.message, { + cause: failure, + }); + case "malformed": + return formatFailure(failure.message, { cause: failure }); + } +}; + +/** + * The inventory already recorded why it will not rebuild this partition, so + * every refusal stays per-member content that is unavailable. Inventory keeps + * the partition table and the reason instead of failing the whole scan. + */ +const refusedContent = ( + refusal: NonNullable, + failure: AndroidOtaPayloadReconstructError, +): ArtifactEntryContentUnavailable => { + const limitation = androidOtaExtractRefusalLimitation(refusal); + return new ArtifactEntryContentUnavailable(failure.message, limitation, { + traversal: { status: "unknown", limitations: [limitation] }, + cause: failure, + }); +}; + +const reconstructFailure = ( + failure: AndroidOtaPayloadReconstructError, +): ArtifactReaderFailure => { + if ( + failure._tag === "AndroidOtaPayloadUnsupportedOperation" || + failure._tag === "AndroidOtaPayloadBlobTruncated" + ) { + const limitation = androidOtaExtractRefusalLimitation( + failure._tag === "AndroidOtaPayloadBlobTruncated" + ? "blob_truncated" + : "unsupported_operations", + ); + return new ArtifactEntryContentUnavailable(failure.message, limitation, { + traversal: { status: "unknown", limitations: [limitation] }, + cause: failure, + }); + } + if (failure._tag === "AndroidOtaPayloadIntegrityFailure") + return new ArtifactReaderFailure("integrity", failure.message, { + cause: failure, + integrityCheck: "declared-digest", + }); + return parseFailure(failure); +}; + +const partitionInfo = (info: AndroidOtaPartition["newPartitionInfo"]) => ({ + size: info.size, + hash_hex: info.hashHex, +}); + +const entryFor = (partition: AndroidOtaPartition): AndroidOtaEntry => { + const hash = partition.newPartitionInfo.hashHex; + const sha256 = + hash !== null && /^[0-9a-f]{64}$/u.test(hash) + ? ({ algorithm: "sha256", digest: hash } as const) + : null; + return { + path: partition.path, + kind: "file", + declaredSize: partition.newPartitionInfo.size, + compressedSize: partition.totalDataLength, + executable: false, + encrypted: false, + byteOffset: null, + declaredIntegrity: partition.extractable ? sha256 : null, + unpacked: false, + limitations: + partition.extractRefusal === null + ? [] + : [androidOtaExtractRefusalLimitation(partition.extractRefusal)], + adapterKey: `android-ota-payload:partition:${String(partition.index)}`, + formatMetadata: { + kind: "android-ota-partition", + index: partition.index, + name: partition.name, + extractable: partition.extractable, + new_partition_info: partitionInfo(partition.newPartitionInfo), + old_partition_info: + partition.oldPartitionInfo === null + ? null + : partitionInfo(partition.oldPartitionInfo), + version: partition.version, + run_postinstall: partition.runPostinstall, + postinstall_path: partition.postinstallPath, + filesystem_type: partition.filesystemType, + operation_counts: [...partition.operationCounts], + total_data_length: partition.totalDataLength, + merge_operation_count: partition.mergeOperationCount, + estimate_cow_size: partition.estimateCowSize, + }, + sourcePath: partition.path, + partition, + }; +}; + +const toMetadata = (payload: AndroidOtaPayload): AndroidOtaPayloadMetadata => ({ + kind: "android-ota-payload", + magic: payload.header.magic, + major_version: payload.header.majorVersion, + manifest_size: payload.header.manifestSize, + metadata_signature_size: payload.header.metadataSignatureSize, + manifest_offset: payload.header.manifestOffset, + blob_offset: payload.header.blobOffset, + block_size: payload.blockSize, + minor_version: payload.minorVersion, + payload_kind: payload.payloadKind, + max_timestamp: payload.maxTimestamp, + partial_update: payload.partialUpdate, + security_patch_level: payload.securityPatchLevel, + signatures_offset: payload.signaturesOffset, + signatures_size: payload.signaturesSize, + metadata_signature_blob_size: payload.metadataSignatureBlobSize, + metadata_signature_count: payload.metadataSignatureCount, + payload_signature_blob_size: payload.payloadSignatureBlobSize, + payload_signature_count: payload.payloadSignatureCount, + signatures_verified: false, + snapshot_enabled: payload.snapshotEnabled, + vabc_enabled: payload.vabcEnabled, + vabc_compression_param: payload.vabcCompressionParam, + blob_truncated: payload.blobTruncated, + partitions: payload.partitions.map((partition) => ({ + index: partition.index, + name: partition.name, + path: partition.path, + new_partition_info: partitionInfo(partition.newPartitionInfo), + old_partition_info: + partition.oldPartitionInfo === null + ? null + : partitionInfo(partition.oldPartitionInfo), + version: partition.version, + run_postinstall: partition.runPostinstall, + postinstall_path: partition.postinstallPath, + filesystem_type: partition.filesystemType, + operation_counts: [...partition.operationCounts], + total_data_length: partition.totalDataLength, + merge_operation_count: partition.mergeOperationCount, + estimate_cow_size: partition.estimateCowSize, + extractable: partition.extractable, + })), + dynamic_partition_groups: payload.dynamicPartitionGroups.map((group) => ({ + name: group.name, + size: group.size, + partition_names: [...group.partitionNames], + })), + apex_info: payload.apexInfo.map((apex) => ({ + package_name: apex.packageName, + version: apex.version, + is_compressed: apex.isCompressed, + decompressed_size: apex.decompressedSize, + })), +}); diff --git a/src/artifacts/artifactFormats.test.ts b/src/artifacts/artifactFormats.test.ts index aa133bad0a..7d0e50794a 100644 --- a/src/artifacts/artifactFormats.test.ts +++ b/src/artifacts/artifactFormats.test.ts @@ -31,6 +31,7 @@ type FormatsWithReaders = | "wxapkg" | "uimage" | "android-boot-image" + | "android-ota-payload" | "mach-o-universal" | "directory" | "pyinstaller" diff --git a/src/artifacts/artifactFormats.ts b/src/artifacts/artifactFormats.ts index c406fe75e4..e3c7883e80 100644 --- a/src/artifacts/artifactFormats.ts +++ b/src/artifacts/artifactFormats.ts @@ -5,6 +5,7 @@ import { type ArtifactFormatId, } from "../domain/artifactGraph.js"; import type { EspFlashSelection } from "../domain/firmware/espFlashLocation.js"; +import { ANDROID_OTA_PAYLOAD_LIMITATIONS } from "../domain/firmware/androidOtaPayload.js"; import { ESP_IMAGE_LIMITATIONS } from "../domain/firmware/espImageFacts.js"; import { ZIP_PACKAGE_FORMATS, @@ -44,6 +45,7 @@ import type { PyInstallerAdmission } from "./pyinstaller/PyInstallerAdmission.js import { PyInstallerArtifactReader } from "./PyInstallerArtifactReader.js"; import { Uf2ArtifactReader } from "./Uf2ArtifactReader.js"; import { NtfsMftArtifactReader } from "./NtfsMftArtifactReader.js"; +import { AndroidOtaPayloadArtifactReader } from "./AndroidOtaPayloadArtifactReader.js"; import { UImageArtifactReader } from "./UImageArtifactReader.js"; import { UnityFsArtifactReader } from "./UnityFsArtifactReader.js"; import { WxapkgArtifactReader } from "./WxapkgArtifactReader.js"; @@ -360,6 +362,15 @@ const NON_ZIP_FORMATS = { createReader: (path, options) => new AndroidBootImageArtifactReader(path, sourceOf(options)), }), + "android-ota-payload": container("android-ota-payload", { + roleContainer: true, + retainClassifiedSource: true, + extractable: true, + absentInventory: "unavailable", + readerLimitation: ANDROID_OTA_PAYLOAD_LIMITATIONS.inventoryScope, + createReader: (path, options) => + new AndroidOtaPayloadArtifactReader(path, sourceOf(options)), + }), "javascript-bundle": described("javascript-bundle", plain), "source-map": described("source-map", plain), "mach-o-universal": described("mach-o-universal", { diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.test.ts b/src/artifacts/inventory/ArtifactGraphConstruction.test.ts index e246576bae..aa0cdbe465 100644 --- a/src/artifacts/inventory/ArtifactGraphConstruction.test.ts +++ b/src/artifacts/inventory/ArtifactGraphConstruction.test.ts @@ -45,6 +45,10 @@ import { } from "../../../tests/fixtures/espImage.js"; import { devicetreeFixture } from "../../domain/firmware/devicetree.fixture.js"; import { fitFixture } from "../fit/FitImage.fixture.js"; +import { + fullAndroidOtaPayload, + v1AndroidOtaPayload, +} from "../../domain/firmware/androidOtaPayload.fixture.js"; it("joins only observed PE signature bytes across stream chunks", () => { const bytes = pe(0x8664, 8190); @@ -576,6 +580,21 @@ it("classifies nested HEX and S-record content as containers by bytes", () => { ).toEqual({ kind: "resource", format: "file" }); }); +it("classifies nested Android OTA payloads as containers by CrAU magic", () => { + expect( + classifyArtifactBytesAtPath("ota/payload.bin", fullAndroidOtaPayload()), + ).toEqual({ + kind: "container", + format: "android-ota-payload", + }); + expect( + classifyArtifactBytesAtPath("ota/payload.bin", v1AndroidOtaPayload()), + ).toEqual({ + kind: "resource", + format: "file", + }); +}); + it("classifies nested ESP images as containers by bytes", () => { const image = espImage({ segments: ESP32C3_APP_SEGMENTS }); expect(classifyArtifactBytesAtPath("ota/update.dat", image)).toEqual({ diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts index e7592e9b66..50f9ecc9a1 100644 --- a/src/domain/analysisSnapshot.ts +++ b/src/domain/analysisSnapshot.ts @@ -92,6 +92,7 @@ const formatSchema = z.enum([ "source-map", "uimage", "android-boot-image", + "android-ota-payload", ]); const kindSchema = z.enum(["executable", "database", "archive", "artifact"]); type SnapshotFormat = z.infer; diff --git a/src/domain/analysisView/androidOtaPayloadSummary.test.ts b/src/domain/analysisView/androidOtaPayloadSummary.test.ts new file mode 100644 index 0000000000..a09e06859c --- /dev/null +++ b/src/domain/analysisView/androidOtaPayloadSummary.test.ts @@ -0,0 +1,87 @@ +import { expect, it } from "vitest"; + +import { + androidOtaPayloadMetadataSchema, + type AndroidOtaPayloadMetadata, +} from "../artifactFormatMetadata.js"; +import { androidOtaPayloadSummaryMetadataSchema } from "./androidOtaPayloadSummary.js"; +import { summaryRootMetadata } from "./espFlashImageSummary.js"; + +const partition = ( + index: number, + extractable: boolean, +): AndroidOtaPayloadMetadata["partitions"][number] => ({ + index, + name: `p${String(index)}`, + path: `p${String(index)}.img`, + new_partition_info: { size: 4096, hash_hex: "00" }, + old_partition_info: null, + version: null, + run_postinstall: null, + postinstall_path: null, + filesystem_type: null, + operation_counts: [{ type: "REPLACE", type_code: 0, count: 1 }], + total_data_length: 4096, + merge_operation_count: 0, + estimate_cow_size: null, + extractable, +}); + +const metadata = androidOtaPayloadMetadataSchema.parse({ + kind: "android-ota-payload", + magic: "CrAU", + major_version: 2, + manifest_size: 128, + metadata_signature_size: 0, + manifest_offset: 24, + blob_offset: 152, + block_size: 4096, + minor_version: 0, + payload_kind: "full", + max_timestamp: null, + partial_update: null, + security_patch_level: "2024-01-05", + signatures_offset: null, + signatures_size: null, + metadata_signature_blob_size: 0, + metadata_signature_count: null, + payload_signature_blob_size: null, + payload_signature_count: null, + signatures_verified: false, + snapshot_enabled: null, + vabc_enabled: null, + vabc_compression_param: null, + blob_truncated: false, + partitions: Array.from({ length: 300 }, (_, index) => + partition(index, index % 3 !== 0), + ), + dynamic_partition_groups: [ + { name: "group", size: null, partition_names: ["p1", "p2"] }, + ], + apex_info: Array.from({ length: 5 }, () => ({ + package_name: "com.android.example", + version: 1, + is_compressed: false, + decompressed_size: null, + })), +}); + +it("summarizes an Android OTA payload's arrays as counts", () => { + const summary = androidOtaPayloadSummaryMetadataSchema.parse( + summaryRootMetadata(metadata), + ); + expect(summary).toMatchObject({ + kind: "android-ota-payload-summary", + payload_kind: "full", + security_patch_level: "2024-01-05", + signatures_verified: false, + partition_count: 300, + extractable_partition_count: 200, + dynamic_partition_group_count: 1, + apex_info_count: 5, + }); + expect(summary).not.toHaveProperty("partitions"); + expect(summary).not.toHaveProperty("dynamic_partition_groups"); + expect(summary).not.toHaveProperty("apex_info"); + expect(JSON.stringify(summary).length).toBeLessThan(1024); +}); diff --git a/src/domain/analysisView/androidOtaPayloadSummary.ts b/src/domain/analysisView/androidOtaPayloadSummary.ts new file mode 100644 index 0000000000..cf2337c708 --- /dev/null +++ b/src/domain/analysisView/androidOtaPayloadSummary.ts @@ -0,0 +1,41 @@ +import { z } from "zod"; + +import { + androidOtaPayloadMetadataSchema, + uint32, + type AndroidOtaPayloadMetadata, +} from "../artifactFormatMetadata.js"; + +/** + * An Android OTA payload's root facts in the summary view, under their own + * kind: header and manifest scalars with counts in place of the partition, + * dynamic partition group and APEX arrays. Each partition stays an + * occurrence, and the complete Evidence keeps every array. + */ +export const androidOtaPayloadSummaryMetadataSchema = + androidOtaPayloadMetadataSchema + .omit({ partitions: true, dynamic_partition_groups: true, apex_info: true }) + .extend({ + kind: z.literal("android-ota-payload-summary"), + partition_count: uint32, + extractable_partition_count: uint32, + dynamic_partition_group_count: uint32, + apex_info_count: uint32, + }); + +/** Compact root facts for an Android OTA payload's summary view. */ +export const summarizeAndroidOtaPayload = ( + metadata: AndroidOtaPayloadMetadata, +): z.infer => { + const { partitions, dynamic_partition_groups, apex_info, ...rest } = metadata; + return { + ...rest, + kind: "android-ota-payload-summary", + partition_count: partitions.length, + extractable_partition_count: partitions.filter( + ({ extractable }) => extractable, + ).length, + dynamic_partition_group_count: dynamic_partition_groups.length, + apex_info_count: apex_info.length, + }; +}; diff --git a/src/domain/analysisView/artifactInventoryView.ts b/src/domain/analysisView/artifactInventoryView.ts index edb681071b..15a04caeff 100644 --- a/src/domain/analysisView/artifactInventoryView.ts +++ b/src/domain/analysisView/artifactInventoryView.ts @@ -41,6 +41,7 @@ import { } from "./analysisViewCoverage.js"; import { analysisViewResultInputError } from "./analysisViewParent.js"; import { ARTIFACT_INVENTORY_VIEW_CAVEATS } from "./artifactInventoryViewCaveats.js"; +import { androidOtaPayloadSummaryMetadataSchema } from "./androidOtaPayloadSummary.js"; import { espFlashImageSummaryMetadataSchema, summaryRootMetadata, @@ -106,9 +107,16 @@ export const artifactInventorySummarySchema = z.strictObject({ }) .exactOptional(), manifest: artifactGraphManifestSchema, - /** An ESP flash layout's nested images appear as summaries here. */ + /** + * An ESP flash layout's nested images appear as summaries here, and an + * Android OTA payload's partition, group and APEX arrays as counts. + */ root_format_metadata: z - .union([artifactFormatMetadataSchema, espFlashImageSummaryMetadataSchema]) + .union([ + artifactFormatMetadataSchema, + espFlashImageSummaryMetadataSchema, + androidOtaPayloadSummaryMetadataSchema, + ]) .exactOptional(), available_counts: z.strictObject({ nodes: z.number().int().nonnegative(), @@ -289,7 +297,8 @@ export const projectArtifactInventoryView = ( inventory.manifest.root_format === "uf2" || inventory.manifest.root_format === "dfuse" || inventory.manifest.root_format === "esp-flash-image" || - inventory.manifest.root_format === "fit"; + inventory.manifest.root_format === "fit" || + inventory.manifest.root_format === "android-ota-payload"; const counts = inventoryCounts(source); const limitations = uniqueSorted([ ...parent.limitations, diff --git a/src/domain/analysisView/espFlashImageSummary.ts b/src/domain/analysisView/espFlashImageSummary.ts index e09298ebbf..80c897b14c 100644 --- a/src/domain/analysisView/espFlashImageSummary.ts +++ b/src/domain/analysisView/espFlashImageSummary.ts @@ -11,6 +11,7 @@ import { uint32, type ArtifactFormatMetadata, } from "../artifactFormatMetadata.js"; +import { summarizeAndroidOtaPayload } from "./androidOtaPayloadSummary.js"; type EspFlashImageFacts = z.infer; @@ -124,10 +125,18 @@ const summarizeImage = ( limitations: [...facts.limitations], }); -/** Root facts for the summary view: compact for an ESP flash layout. */ +/** + * Root facts for the summary view: compact for an ESP flash layout and an + * Android OTA payload. + */ export const summaryRootMetadata = ( metadata: ArtifactFormatMetadata, -): ArtifactFormatMetadata | EspFlashImageSummaryMetadata => { +): + | ArtifactFormatMetadata + | EspFlashImageSummaryMetadata + | ReturnType => { + if (metadata.kind === "android-ota-payload") + return summarizeAndroidOtaPayload(metadata); if (metadata.kind !== "esp-flash-image") return metadata; const { bootloader, apps, ...rest } = metadata; return { diff --git a/src/domain/artifactFormatMetadata.ts b/src/domain/artifactFormatMetadata.ts index 5cf07d483c..cefd6f5822 100644 --- a/src/domain/artifactFormatMetadata.ts +++ b/src/domain/artifactFormatMetadata.ts @@ -791,6 +791,110 @@ export const uImageEntryMetadataSchema = z.strictObject({ }); export type UImageEntryMetadata = z.infer; +const androidOtaHash = z + .string() + .regex(/^[0-9a-f]*$/u) + .nullable(); + +const androidOtaPartitionInfoSchema = z.strictObject({ + size: offset.nullable(), + hash_hex: androidOtaHash, +}); + +const androidOtaOperationCountSchema = z.strictObject({ + type: z.string(), + type_code: z.number().int().min(0), + count: uint32, +}); + +/** + * CrAU v2 DeltaArchiveManifest facts. Signatures are counted, not verified. + * Partition images are reconstructed only from REPLACE, ZERO and REPLACE_ZSTD. + */ +export const androidOtaPayloadMetadataSchema = z.strictObject({ + kind: z.literal("android-ota-payload"), + magic: z.literal("CrAU"), + major_version: z.literal(2), + manifest_size: offset, + metadata_signature_size: uint32, + manifest_offset: offset, + blob_offset: offset, + block_size: offset, + minor_version: uint32, + payload_kind: z.enum(["full", "delta"]), + max_timestamp: z.number().int().nullable(), + partial_update: z.boolean().nullable(), + security_patch_level: z.string().nullable(), + signatures_offset: offset.nullable(), + signatures_size: offset.nullable(), + metadata_signature_blob_size: uint32, + metadata_signature_count: uint32.nullable(), + payload_signature_blob_size: offset.nullable(), + payload_signature_count: uint32.nullable(), + signatures_verified: z.literal(false), + snapshot_enabled: z.boolean().nullable(), + vabc_enabled: z.boolean().nullable(), + vabc_compression_param: z.string().nullable(), + blob_truncated: z.boolean(), + partitions: z.array( + z.strictObject({ + index: uint32, + name: z.string(), + path: z.string(), + new_partition_info: androidOtaPartitionInfoSchema, + old_partition_info: androidOtaPartitionInfoSchema.nullable(), + version: z.string().nullable(), + run_postinstall: z.boolean().nullable(), + postinstall_path: z.string().nullable(), + filesystem_type: z.string().nullable(), + operation_counts: z.array(androidOtaOperationCountSchema), + total_data_length: offset, + merge_operation_count: uint32, + estimate_cow_size: offset.nullable(), + extractable: z.boolean(), + }), + ), + dynamic_partition_groups: z.array( + z.strictObject({ + name: z.string(), + size: offset.nullable(), + partition_names: z.array(z.string()), + }), + ), + apex_info: z.array( + z.strictObject({ + package_name: z.string().nullable(), + version: z.number().int().nullable(), + is_compressed: z.boolean().nullable(), + decompressed_size: z.number().int().nullable(), + }), + ), +}); +export type AndroidOtaPayloadMetadata = z.infer< + typeof androidOtaPayloadMetadataSchema +>; + +/** One partition the payload writes; reconstructed bytes are not a file range. */ +export const androidOtaPartitionMetadataSchema = z.strictObject({ + kind: z.literal("android-ota-partition"), + index: uint32, + name: z.string(), + extractable: z.boolean(), + new_partition_info: androidOtaPartitionInfoSchema, + old_partition_info: androidOtaPartitionInfoSchema.nullable(), + version: z.string().nullable(), + run_postinstall: z.boolean().nullable(), + postinstall_path: z.string().nullable(), + filesystem_type: z.string().nullable(), + operation_counts: z.array(androidOtaOperationCountSchema), + total_data_length: offset, + merge_operation_count: uint32, + estimate_cow_size: offset.nullable(), +}); +export type AndroidOtaPartitionMetadata = z.infer< + typeof androidOtaPartitionMetadataSchema +>; + const bunHex = z .string() .regex(/^[0-9a-f]+$/u) @@ -1047,6 +1151,8 @@ export const artifactFormatMetadataSchema = z.discriminatedUnion("kind", [ hexRecordRegionMetadataSchema, uImageMetadataSchema, uImageEntryMetadataSchema, + androidOtaPayloadMetadataSchema, + androidOtaPartitionMetadataSchema, espImageMetadataSchema, espImageSegmentMetadataSchema, espImageSignatureBlockMetadataSchema, @@ -1187,6 +1293,14 @@ const declarationsByKind: { notCompared: "role and index restate the entry's path, compression is observed from its bytes, and load addresses, names and board IDs come from the image header or vendor ramdisk table, which the image's content comparison covers.", }, + "android-ota-payload": { + notCompared: + "Its header and manifest facts come from the payload's own bytes, which content comparison covers. Signatures are counted, not verified.", + }, + "android-ota-partition": { + notCompared: + "name and index restate the entry's path; reconstructed partition bytes are compared by content when they are extractable.", + }, "esp-image": { notCompared: "Its fields come from the image's own bytes, which content comparison covers.", diff --git a/src/domain/artifactFormatRecognition.test.ts b/src/domain/artifactFormatRecognition.test.ts index 91b5e74b61..d939ec8538 100644 --- a/src/domain/artifactFormatRecognition.test.ts +++ b/src/domain/artifactFormatRecognition.test.ts @@ -6,6 +6,11 @@ import { espImage, } from "../../tests/fixtures/espImage.js"; import { recognizeArtifactFormat } from "./artifactFormatRecognition.js"; +import { androidOtaUnsupportedVersion } from "./firmware/androidOtaPayload.js"; +import { + fullAndroidOtaPayload, + v1AndroidOtaPayload, +} from "./firmware/androidOtaPayload.fixture.js"; import { dfuseFile } from "./firmware/dfuse.fixture.js"; import { DFUSE_SUFFIX_BYTES } from "./firmware/dfuse.js"; import { ESP8266_REFUSAL } from "./firmware/espImage.js"; @@ -40,6 +45,12 @@ it.each([ format: "esp-image", reason: ESP8266_REFUSAL, }, + { + label: "an Android OTA payload v1 header", + bytes: v1AndroidOtaPayload(), + format: "android-ota-payload", + reason: androidOtaUnsupportedVersion(1n), + }, ])("refuses $label in one place", (row) => { expect(recognize(row.bytes)).toEqual({ state: "refused", @@ -85,3 +96,10 @@ it("decides an ESP flash layout before the bootloader image it begins with", () it("leaves bytes no recognizer claims to the native and named-format routes", () => { expect(recognize(Buffer.from("plain text content\n"))).toBeUndefined(); }); + +it("recognizes a CrAU v2 payload after the uImage magic check", () => { + expect(recognize(fullAndroidOtaPayload())).toMatchObject({ + state: "recognized", + format: "android-ota-payload", + }); +}); diff --git a/src/domain/artifactFormatRecognition.ts b/src/domain/artifactFormatRecognition.ts index 9551e493c1..c3bd5510b7 100644 --- a/src/domain/artifactFormatRecognition.ts +++ b/src/domain/artifactFormatRecognition.ts @@ -8,6 +8,7 @@ import { detectHexRecordEncoding } from "./firmware/hexRecords.js"; import { hasUf2Block } from "./firmware/uf2.js"; import { hasGodotPckHeader } from "./godotPckFormat.js"; import { nesContainerFormat, parseInesLayout } from "./inesContainer.js"; +import { recognizeAndroidOtaPayload } from "./firmware/androidOtaPayload.js"; import { hasUImageMagic } from "./uimageFormat.js"; import { hasUnityFsHeader } from "./unityfsFormat.js"; import { hasMftFileRecordHeader } from "./windows/ntfsMft.js"; @@ -24,6 +25,7 @@ export type RecognizedArtifactFormat = Extract< | "wxapkg" | "uimage" | "android-boot-image" + | "android-ota-payload" | "intel-hex" | "srec" | "uf2" @@ -105,6 +107,17 @@ export const ARTIFACT_FORMAT_RECOGNIZERS: readonly ArtifactFormatRecognizer[] = ), when("uimage", hasUImageMagic), when("android-boot-image", hasAndroidBootImageMagic), + ({ prefix }) => { + const ota = recognizeAndroidOtaPayload(prefix); + if (ota === undefined) return undefined; + return ota.state === "recognized" + ? { state: "recognized", format: "android-ota-payload" } + : { + state: "refused", + format: "android-ota-payload", + reason: ota.reason, + }; + }, ({ prefix }) => { const format = detectHexRecordEncoding(prefix); return format === undefined ? undefined : { state: "recognized", format }; diff --git a/src/domain/artifactGraph.ts b/src/domain/artifactGraph.ts index 4d740ddab9..75a3939085 100644 --- a/src/domain/artifactGraph.ts +++ b/src/domain/artifactGraph.ts @@ -73,6 +73,7 @@ export const ARTIFACT_FORMAT_IDS = [ "wxapkg", "uimage", "android-boot-image", + "android-ota-payload", "javascript-bundle", "source-map", "mach-o-universal", @@ -122,6 +123,7 @@ const artifactContentFormatSchema = artifactFormatSchema.extract([ "wxapkg", "uimage", "android-boot-image", + "android-ota-payload", "intel-hex", "srec", "esp-image", diff --git a/src/domain/binaryTargetTypes.ts b/src/domain/binaryTargetTypes.ts index 4f233af215..e872e52b8c 100644 --- a/src/domain/binaryTargetTypes.ts +++ b/src/domain/binaryTargetTypes.ts @@ -317,6 +317,7 @@ export type BinaryTarget = | "wxapkg" | "uimage" | "android-boot-image" + | "android-ota-payload" | "dmg" | "pkg" | "intel-hex" @@ -373,6 +374,7 @@ export const BINARY_TARGET_FORMAT_KINDS = { wxapkg: "archive", uimage: "archive", "android-boot-image": "archive", + "android-ota-payload": "archive", dmg: "archive", pkg: "archive", "intel-hex": "archive", diff --git a/src/domain/evidenceSubject.ts b/src/domain/evidenceSubject.ts index bb65458c1d..8a5af99a76 100644 --- a/src/domain/evidenceSubject.ts +++ b/src/domain/evidenceSubject.ts @@ -30,6 +30,7 @@ export const evidenceSubjectFormatSchema = z.enum([ "wxapkg", "uimage", "android-boot-image", + "android-ota-payload", "dmg", "pkg", "plist", diff --git a/src/domain/firmware/androidOtaPayload.fixture.ts b/src/domain/firmware/androidOtaPayload.fixture.ts new file mode 100644 index 0000000000..4c54b99562 --- /dev/null +++ b/src/domain/firmware/androidOtaPayload.fixture.ts @@ -0,0 +1,497 @@ +import { createHash } from "node:crypto"; +import { zstdDecompressSync } from "node:zlib"; + +import { BinaryWriter, WireType } from "@bufbuild/protobuf/wire"; + +import { + ANDROID_OTA_DEFAULT_BLOCK_SIZE, + ANDROID_OTA_HEADER_V1_BYTES, + ANDROID_OTA_HEADER_V2_BYTES, + ANDROID_OTA_MAGIC, +} from "./androidOtaPayload.js"; + +export interface AndroidOtaExtentFixture { + readonly startBlock: number; + readonly numBlocks: number; +} + +export interface AndroidOtaOperationFixture { + readonly type: number; + readonly data?: Uint8Array; + readonly dataOffset?: number; + readonly dataLength?: number; + readonly dstExtents?: readonly AndroidOtaExtentFixture[]; + readonly srcExtents?: readonly AndroidOtaExtentFixture[]; +} + +export interface AndroidOtaPartitionFixture { + readonly name: string; + readonly newSize?: number; + readonly newHash?: Uint8Array; + readonly oldSize?: number; + readonly oldHash?: Uint8Array; + readonly version?: string; + readonly runPostinstall?: boolean; + readonly postinstallPath?: string; + readonly filesystemType?: string; + readonly operations: readonly AndroidOtaOperationFixture[]; + readonly mergeOperations?: number; + readonly estimateCowSize?: number; + readonly omitNewHash?: boolean; +} + +export interface AndroidOtaGroupFixture { + readonly name: string; + readonly size?: number; + readonly partitionNames: readonly string[]; +} + +export interface AndroidOtaApexFixture { + readonly packageName: string; + readonly version: number; + readonly isCompressed?: boolean; + readonly decompressedSize?: number; +} + +export interface AndroidOtaPayloadFixture { + readonly majorVersion?: number; + readonly minorVersion?: number; + readonly blockSize?: number; + readonly maxTimestamp?: number; + readonly partialUpdate?: boolean; + readonly securityPatchLevel?: string; + readonly partitions: readonly AndroidOtaPartitionFixture[]; + readonly groups?: readonly AndroidOtaGroupFixture[]; + readonly snapshotEnabled?: boolean; + readonly vabcEnabled?: boolean; + readonly vabcCompressionParam?: string; + readonly apex?: readonly AndroidOtaApexFixture[]; + readonly metadataSignature?: Uint8Array; + readonly payloadSignature?: Uint8Array; + readonly signaturesOffset?: number; + readonly signaturesSize?: number; + readonly truncateTo?: number; +} + +const encodeExtent = ( + writer: BinaryWriter, + extent: AndroidOtaExtentFixture, +): void => { + writer.tag(1, WireType.Varint).uint64(extent.startBlock); + writer.tag(2, WireType.Varint).uint64(extent.numBlocks); +}; + +const encodePartitionInfo = ( + writer: BinaryWriter, + size: number | undefined, + hash: Uint8Array | undefined, +): void => { + if (size !== undefined) writer.tag(1, WireType.Varint).uint64(size); + if (hash !== undefined) writer.tag(2, WireType.LengthDelimited).bytes(hash); +}; + +const extentForData = ( + dataLength: number, + blockSize: number, +): AndroidOtaExtentFixture => ({ + startBlock: 0, + numBlocks: Math.max(1, Math.ceil(dataLength / blockSize)), +}); + +const partitionImage = ( + partition: AndroidOtaPartitionFixture, + blockSize: number, +): Buffer | undefined => { + const extractable = partition.operations.every( + (operation) => + operation.type === 0 || operation.type === 6 || operation.type === 14, + ); + if (!extractable) return undefined; + const size = + partition.newSize ?? + partition.operations.reduce((largest, operation) => { + const stored = operation.data ?? new Uint8Array(); + const dataLength = + operation.type === 14 && stored.length > 0 + ? zstdDecompressSync(stored).length + : stored.length; + const extents = + operation.dstExtents ?? + (dataLength === 0 ? [] : [extentForData(dataLength, blockSize)]); + // Size the image so the operation data covers every destination byte; + // only the final block may be partial. + let remaining = operation.type === 6 ? Infinity : dataLength; + let end = 0; + for (const extent of extents) { + if (remaining <= 0) break; + const start = extent.startBlock * blockSize; + const extentBytes = extent.numBlocks * blockSize; + end = Math.max(end, start + Math.min(extentBytes, remaining)); + remaining -= extentBytes; + } + return Math.max(largest, end); + }, 0); + const image = Buffer.alloc(size); + for (const operation of partition.operations) { + if (operation.type === 6) continue; + const stored = operation.data ?? new Uint8Array(); + const data = operation.type === 14 ? zstdDecompressSync(stored) : stored; + const extents = operation.dstExtents ?? [ + extentForData(data.length || size, blockSize), + ]; + let cursor = 0; + for (const extent of extents) { + const start = extent.startBlock * blockSize; + if (start >= image.length) continue; + const length = Math.min( + extent.numBlocks * blockSize, + image.length - start, + ); + const available = Math.min(length, Math.max(0, data.length - cursor)); + if (available > 0) + image.set(data.subarray(cursor, cursor + available), start); + cursor += available; + } + } + return image; +}; + +const encodeOperation = ( + writer: BinaryWriter, + operation: AndroidOtaOperationFixture, + dataOffset: number, + blockSize: number, +): void => { + writer.tag(1, WireType.Varint).int32(operation.type); + const dataLength = operation.dataLength ?? operation.data?.length ?? 0; + const offset = operation.dataOffset ?? dataOffset; + if (dataLength > 0 || operation.dataOffset !== undefined) { + writer.tag(2, WireType.Varint).uint64(offset); + writer.tag(3, WireType.Varint).uint64(dataLength); + } + for (const extent of operation.srcExtents ?? []) { + writer.tag(4, WireType.LengthDelimited).fork(); + encodeExtent(writer, extent); + writer.join(); + } + const dst = + operation.dstExtents ?? + (operation.type === 6 + ? [{ startBlock: 0, numBlocks: 1 }] + : [extentForData(dataLength || 1, blockSize)]); + for (const extent of dst) { + writer.tag(6, WireType.LengthDelimited).fork(); + encodeExtent(writer, extent); + writer.join(); + } +}; + +const encodePartition = ( + writer: BinaryWriter, + partition: AndroidOtaPartitionFixture, + blob: { offset: number; chunks: Uint8Array[] }, + blockSize: number, +): void => { + writer.tag(1, WireType.LengthDelimited).string(partition.name); + if (partition.runPostinstall !== undefined) + writer.tag(2, WireType.Varint).bool(partition.runPostinstall); + if (partition.postinstallPath !== undefined) + writer.tag(3, WireType.LengthDelimited).string(partition.postinstallPath); + if (partition.filesystemType !== undefined) + writer.tag(4, WireType.LengthDelimited).string(partition.filesystemType); + if (partition.oldSize !== undefined || partition.oldHash !== undefined) { + writer.tag(6, WireType.LengthDelimited).fork(); + encodePartitionInfo(writer, partition.oldSize, partition.oldHash); + writer.join(); + } + const image = partitionImage(partition, blockSize); + const newSize = partition.newSize ?? image?.length; + const newHash = partition.omitNewHash + ? undefined + : (partition.newHash ?? + (image === undefined + ? undefined + : createHash("sha256").update(image).digest())); + if (newSize !== undefined || newHash !== undefined) { + writer.tag(7, WireType.LengthDelimited).fork(); + encodePartitionInfo(writer, newSize, newHash); + writer.join(); + } + for (const operation of partition.operations) { + const data = operation.data; + const assignedOffset = blob.offset; + if ( + data !== undefined && + data.length > 0 && + operation.dataOffset === undefined + ) { + blob.chunks.push(data); + blob.offset += data.length; + } + writer.tag(8, WireType.LengthDelimited).fork(); + encodeOperation( + writer, + operation, + operation.dataOffset ?? assignedOffset, + blockSize, + ); + writer.join(); + } + if (partition.version !== undefined) + writer.tag(17, WireType.LengthDelimited).string(partition.version); + for (let index = 0; index < (partition.mergeOperations ?? 0); index += 1) { + writer.tag(18, WireType.LengthDelimited).fork(); + writer.tag(1, WireType.Varint).int32(0); + writer.join(); + } + if (partition.estimateCowSize !== undefined) + writer.tag(19, WireType.Varint).uint64(partition.estimateCowSize); +}; + +const encodeGroup = ( + writer: BinaryWriter, + group: AndroidOtaGroupFixture, +): void => { + writer.tag(1, WireType.LengthDelimited).string(group.name); + if (group.size !== undefined) + writer.tag(2, WireType.Varint).uint64(group.size); + for (const name of group.partitionNames) + writer.tag(3, WireType.LengthDelimited).string(name); +}; + +const encodeApex = ( + writer: BinaryWriter, + apex: AndroidOtaApexFixture, +): void => { + writer.tag(1, WireType.LengthDelimited).string(apex.packageName); + writer.tag(2, WireType.Varint).int64(apex.version); + if (apex.isCompressed !== undefined) + writer.tag(3, WireType.Varint).bool(apex.isCompressed); + if (apex.decompressedSize !== undefined) + writer.tag(4, WireType.Varint).int64(apex.decompressedSize); +}; + +const encodeManifest = ( + fixture: AndroidOtaPayloadFixture, + blob: { offset: number; chunks: Uint8Array[] }, + signaturesOffset: number, + signaturesSize: number, +): Uint8Array => { + const writer = new BinaryWriter(); + const blockSize = fixture.blockSize ?? ANDROID_OTA_DEFAULT_BLOCK_SIZE; + writer.tag(3, WireType.Varint).uint32(blockSize); + writer.tag(4, WireType.Varint).uint64(signaturesOffset); + writer.tag(5, WireType.Varint).uint64(signaturesSize); + if (fixture.minorVersion !== undefined) + writer.tag(12, WireType.Varint).uint32(fixture.minorVersion); + for (const partition of fixture.partitions) { + writer.tag(13, WireType.LengthDelimited).fork(); + encodePartition(writer, partition, blob, blockSize); + writer.join(); + } + if (fixture.maxTimestamp !== undefined) + writer.tag(14, WireType.Varint).int64(fixture.maxTimestamp); + if ( + fixture.groups !== undefined || + fixture.snapshotEnabled !== undefined || + fixture.vabcEnabled !== undefined || + fixture.vabcCompressionParam !== undefined + ) { + writer.tag(15, WireType.LengthDelimited).fork(); + for (const group of fixture.groups ?? []) { + writer.tag(1, WireType.LengthDelimited).fork(); + encodeGroup(writer, group); + writer.join(); + } + if (fixture.snapshotEnabled !== undefined) + writer.tag(2, WireType.Varint).bool(fixture.snapshotEnabled); + if (fixture.vabcEnabled !== undefined) + writer.tag(3, WireType.Varint).bool(fixture.vabcEnabled); + if (fixture.vabcCompressionParam !== undefined) + writer + .tag(4, WireType.LengthDelimited) + .string(fixture.vabcCompressionParam); + writer.join(); + } + if (fixture.partialUpdate !== undefined) + writer.tag(16, WireType.Varint).bool(fixture.partialUpdate); + for (const apex of fixture.apex ?? []) { + writer.tag(17, WireType.LengthDelimited).fork(); + encodeApex(writer, apex); + writer.join(); + } + if (fixture.securityPatchLevel !== undefined) + writer.tag(18, WireType.LengthDelimited).string(fixture.securityPatchLevel); + return writer.finish(); +}; + +const encodeSignatures = ( + count = 1, + payload = Buffer.from("sig"), +): Uint8Array => { + const writer = new BinaryWriter(); + for (let index = 0; index < count; index += 1) { + writer.tag(1, WireType.LengthDelimited).fork(); + writer.tag(2, WireType.LengthDelimited).bytes(payload); + writer.join(); + } + return writer.finish(); +}; + +/** One Signatures protobuf with a single unsigned blob. */ +export const androidOtaSignatureBlob = ( + payload = Buffer.from("sig"), +): Uint8Array => encodeSignatures(1, payload); + +export const buildAndroidOtaPayload = ( + fixture: AndroidOtaPayloadFixture, +): Buffer => { + const major = fixture.majorVersion ?? 2; + const layout = { offset: 0, chunks: [] as Uint8Array[] }; + const metadataSignature = + fixture.metadataSignature ?? androidOtaSignatureBlob(); + const payloadSignature = + fixture.payloadSignature ?? + androidOtaSignatureBlob(Buffer.from("payload-sig")); + encodeManifest(fixture, layout, 0, payloadSignature.length); + const data = Buffer.concat(layout.chunks); + const signaturesOffset = fixture.signaturesOffset ?? data.length; + const signaturesSize = fixture.signaturesSize ?? payloadSignature.length; + const laidOut = { offset: 0, chunks: [] as Uint8Array[] }; + const manifest = encodeManifest( + fixture, + laidOut, + signaturesOffset, + signaturesSize, + ); + if (major === 1) { + const header = Buffer.alloc(ANDROID_OTA_HEADER_V1_BYTES); + header.write(ANDROID_OTA_MAGIC, 0, "latin1"); + header.writeBigUInt64BE(1n, 4); + header.writeBigUInt64BE(BigInt(manifest.length), 12); + const bytes = Buffer.concat([header, Buffer.from(manifest)]); + return fixture.truncateTo === undefined + ? bytes + : bytes.subarray(0, fixture.truncateTo); + } + const header = Buffer.alloc(ANDROID_OTA_HEADER_V2_BYTES); + header.write(ANDROID_OTA_MAGIC, 0, "latin1"); + header.writeBigUInt64BE(BigInt(major), 4); + header.writeBigUInt64BE(BigInt(manifest.length), 12); + header.writeUInt32BE(metadataSignature.length, 20); + const bytes = Buffer.concat([ + header, + Buffer.from(manifest), + Buffer.from(metadataSignature), + Buffer.concat(laidOut.chunks), + Buffer.from(payloadSignature), + ]); + return fixture.truncateTo === undefined + ? bytes + : bytes.subarray(0, fixture.truncateTo); +}; + +export const fullAndroidOtaPayload = (): Buffer => + buildAndroidOtaPayload({ + minorVersion: 0, + blockSize: 4096, + maxTimestamp: 1_700_000_000, + partialUpdate: false, + securityPatchLevel: "2024-01-05", + partitions: [ + { + name: "boot", + version: "boot-1", + runPostinstall: false, + filesystemType: "raw", + operations: [ + { + type: 0, + data: Buffer.from("BOOTIMG"), + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ], + }, + { + name: "system", + version: "system-1", + runPostinstall: true, + postinstallPath: "system/bin/otapreopt_script", + filesystemType: "ext4", + newSize: 8192, + operations: [ + { type: 6, dstExtents: [{ startBlock: 0, numBlocks: 2 }] }, + ], + mergeOperations: 2, + estimateCowSize: 4096, + }, + ], + groups: [ + { + name: "super", + size: 64 * 1024 * 1024, + partitionNames: ["system"], + }, + ], + snapshotEnabled: true, + vabcEnabled: true, + vabcCompressionParam: "gz", + apex: [ + { + packageName: "com.android.runtime", + version: 340090000, + isCompressed: true, + decompressedSize: 12_000_000, + }, + ], + }); + +export const deltaAndroidOtaPayload = (): Buffer => + buildAndroidOtaPayload({ + minorVersion: 4, + partitions: [ + { + name: "vendor", + oldSize: 4096, + oldHash: createHash("sha256").update("old-vendor").digest(), + newSize: 4096, + operations: [ + { + type: 4, + srcExtents: [{ startBlock: 0, numBlocks: 1 }], + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + { + type: 10, + data: Buffer.from("brotli-diff"), + srcExtents: [{ startBlock: 1, numBlocks: 1 }], + dstExtents: [{ startBlock: 1, numBlocks: 1 }], + }, + ], + }, + ], + }); + +export const unknownOperationAndroidOtaPayload = (): Buffer => + buildAndroidOtaPayload({ + partitions: [ + { + name: "misc", + newSize: 4096, + operations: [ + { type: 99, dstExtents: [{ startBlock: 0, numBlocks: 1 }] }, + ], + }, + ], + }); + +export const v1AndroidOtaPayload = (): Buffer => + buildAndroidOtaPayload({ + majorVersion: 1, + partitions: [ + { + name: "root", + operations: [{ type: 0, data: Buffer.from("x") }], + }, + ], + }); diff --git a/src/domain/firmware/androidOtaPayload.test.ts b/src/domain/firmware/androidOtaPayload.test.ts new file mode 100644 index 0000000000..128c266f91 --- /dev/null +++ b/src/domain/firmware/androidOtaPayload.test.ts @@ -0,0 +1,732 @@ +import { createHash } from "node:crypto"; +import { zstdCompressSync } from "node:zlib"; + +import { BinaryWriter, WireType } from "@bufbuild/protobuf/wire"; +import { expect, it } from "vitest"; + +import { + ANDROID_OTA_HEADER_V2_BYTES, + ANDROID_OTA_MAGIC, + ANDROID_OTA_MAX_EXTENTS_TOTAL, + ANDROID_OTA_MAX_EXTRACT_BYTES, + ANDROID_OTA_MAX_GROUP_PARTITION_NAMES, + ANDROID_OTA_MAX_MANIFEST_BYTES, + ANDROID_OTA_MAX_OPERATION_DATA_BYTES, + ANDROID_OTA_MAX_PARTITIONS, + ANDROID_OTA_MAX_SIGNATURE_BYTES, + ANDROID_OTA_PAYLOAD_LIMITATIONS, + parseAndroidOtaHeader, + parseAndroidOtaPayload, + recognizeAndroidOtaPayload, + reconstructAndroidOtaPartition, + androidOtaDistinctOperationDataBytes, + androidOtaUnsupportedVersion, +} from "./androidOtaPayload.js"; +import { + buildAndroidOtaPayload, + deltaAndroidOtaPayload, + fullAndroidOtaPayload, + unknownOperationAndroidOtaPayload, + v1AndroidOtaPayload, +} from "./androidOtaPayload.fixture.js"; + +const parse = (bytes: Uint8Array) => + parseAndroidOtaPayload(bytes, bytes.length); + +const header = (fields: { + readonly version?: bigint; + readonly manifestSize?: bigint; + readonly metadataSignatureSize?: number; + readonly length?: number; +}): Buffer => { + const bytes = Buffer.alloc(fields.length ?? ANDROID_OTA_HEADER_V2_BYTES); + bytes.write(ANDROID_OTA_MAGIC, 0, "latin1"); + if (bytes.length >= 12) bytes.writeBigUInt64BE(fields.version ?? 2n, 4); + if (bytes.length >= 20) bytes.writeBigUInt64BE(fields.manifestSize ?? 0n, 12); + if (bytes.length >= 24) + bytes.writeUInt32BE(fields.metadataSignatureSize ?? 0, 20); + return bytes; +}; + +it("recognizes CrAU v2 and refuses any other readable major version", () => { + expect(recognizeAndroidOtaPayload(Buffer.from("nope"))).toBeUndefined(); + expect(recognizeAndroidOtaPayload(Buffer.from("CrAU"))).toEqual({ + state: "recognized", + }); + expect(recognizeAndroidOtaPayload(header({}))).toEqual({ + state: "recognized", + }); + expect(recognizeAndroidOtaPayload(header({ version: 1n }))).toEqual({ + state: "refused", + reason: androidOtaUnsupportedVersion(1n), + }); + expect(recognizeAndroidOtaPayload(header({ version: 3n }))).toEqual({ + state: "refused", + reason: androidOtaUnsupportedVersion(3n), + }); +}); + +it("inventories a full payload with REPLACE, ZERO, dynamic groups and apex_info", () => { + const bytes = fullAndroidOtaPayload(); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + expect(parsed.value).toMatchObject({ + header: { magic: "CrAU", majorVersion: 2 }, + payloadKind: "full", + minorVersion: 0, + blockSize: 4096, + maxTimestamp: 1_700_000_000, + partialUpdate: false, + securityPatchLevel: "2024-01-05", + snapshotEnabled: true, + vabcEnabled: true, + vabcCompressionParam: "gz", + blobTruncated: false, + metadataSignatureCount: 1, + payloadSignatureCount: 1, + }); + expect(parsed.value.partitions.map((partition) => partition.name)).toEqual([ + "boot", + "system", + ]); + expect(parsed.value.partitions[0]).toMatchObject({ + extractable: true, + filesystemType: "raw", + operationCounts: [{ type: "REPLACE", type_code: 0, count: 1 }], + }); + expect(parsed.value.partitions[1]).toMatchObject({ + extractable: true, + runPostinstall: true, + postinstallPath: "system/bin/otapreopt_script", + mergeOperationCount: 2, + estimateCowSize: 4096, + operationCounts: [{ type: "ZERO", type_code: 6, count: 1 }], + }); + expect(parsed.value.dynamicPartitionGroups).toEqual([ + { name: "super", size: 64 * 1024 * 1024, partitionNames: ["system"] }, + ]); + expect(parsed.value.apexInfo).toEqual([ + { + packageName: "com.android.runtime", + version: 340090000, + isCompressed: true, + decompressedSize: 12_000_000, + }, + ]); + expect(parsed.value.limitations.join(" ")).toContain("not verified"); +}); + +it("reconstructs REPLACE and ZERO partitions against the declared hash", () => { + const bytes = fullAndroidOtaPayload(); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + const blob = bytes.subarray(parsed.value.header.blobOffset); + for (const partition of parsed.value.partitions) { + const reconstructed = reconstructAndroidOtaPartition( + partition, + parsed.value.blockSize, + (offset, length) => blob.subarray(offset, offset + length), + ); + if (!reconstructed.ok) throw reconstructed.error; + expect(createHash("sha256").update(reconstructed.value).digest("hex")).toBe( + partition.newPartitionInfo.hashHex, + ); + } +}); + +it("inventories a delta payload without applying SOURCE_COPY or BROTLI_BSDIFF", () => { + const parsed = parse(deltaAndroidOtaPayload()); + if (!parsed.ok) throw parsed.error; + expect(parsed.value.payloadKind).toBe("delta"); + expect(parsed.value.minorVersion).toBe(4); + expect(parsed.value.partitions[0]).toMatchObject({ + name: "vendor", + extractable: false, + oldPartitionInfo: { size: 4096 }, + operationCounts: [ + { type: "SOURCE_COPY", type_code: 4, count: 1 }, + { type: "BROTLI_BSDIFF", type_code: 10, count: 1 }, + ], + }); + const reconstructed = reconstructAndroidOtaPartition( + parsed.value.partitions[0]!, + parsed.value.blockSize, + () => new Uint8Array(), + ); + expect(reconstructed).toMatchObject({ + ok: false, + error: { _tag: "AndroidOtaPayloadUnsupportedOperation", typeCode: 4 }, + }); +}); + +it("counts an unknown InstallOperation type as unknown", () => { + const parsed = parse(unknownOperationAndroidOtaPayload()); + if (!parsed.ok) throw parsed.error; + expect(parsed.value.partitions[0]?.operationCounts).toEqual([ + { type: "unknown", type_code: 99, count: 1 }, + ]); +}); + +it("reconstructs REPLACE_ZSTD payloads", () => { + const plain = Buffer.from("zstd-partition-bytes"); + const bytes = buildAndroidOtaPayload({ + partitions: [ + { + name: "vendor", + operations: [ + { + type: 14, + data: zstdCompressSync(plain), + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ], + }, + ], + }); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + expect(parsed.value.partitions[0]?.extractable).toBe(true); + const blob = bytes.subarray(parsed.value.header.blobOffset); + const reconstructed = reconstructAndroidOtaPartition( + parsed.value.partitions[0]!, + parsed.value.blockSize, + (offset, length) => blob.subarray(offset, offset + length), + ); + if (!reconstructed.ok) throw reconstructed.error; + expect( + Buffer.from(reconstructed.value.subarray(0, plain.length)).equals(plain), + ).toBe(true); +}); + +it("refuses REPLACE_ZSTD output past destination extents as a capacity limit", () => { + const plain = Buffer.alloc(8192, 0x61); + const bytes = buildAndroidOtaPayload({ + partitions: [ + { + name: "vendor", + newSize: 4096, + operations: [ + { + type: 14, + data: zstdCompressSync(plain), + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ], + }, + ], + }); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + const blob = bytes.subarray(parsed.value.header.blobOffset); + expect( + reconstructAndroidOtaPartition( + parsed.value.partitions[0]!, + parsed.value.blockSize, + (offset, length) => blob.subarray(offset, offset + length), + ), + ).toMatchObject({ + ok: false, + error: { + failure: { kind: "limit", limit: { maximum: 4096 } }, + }, + }); +}); + +it("refuses distinct operation data past the read budget as a capacity limit", () => { + expect( + androidOtaDistinctOperationDataBytes([ + { + typeCode: 0, + typeName: "REPLACE", + dataOffset: 0, + dataLength: ANDROID_OTA_MAX_OPERATION_DATA_BYTES + 1, + srcExtents: [], + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ]), + ).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { + maximum: ANDROID_OTA_MAX_OPERATION_DATA_BYTES, + }, + }, + }, + }); +}); + +it("refuses a v1 header as an unsupported version", () => { + const bytes = v1AndroidOtaPayload(); + expect(recognizeAndroidOtaPayload(bytes)).toMatchObject({ + state: "refused", + reason: androidOtaUnsupportedVersion(1n), + }); + expect(parseAndroidOtaHeader(bytes, bytes.length)).toMatchObject({ + ok: false, + error: { + kind: "unsupported", + failure: { field: "major_version" }, + }, + }); +}); + +it("refuses a bad magic, truncated header, and a truncated manifest", () => { + expect(parse(Buffer.from("XXXX"))).toMatchObject({ + ok: false, + error: { kind: "malformed" }, + }); + expect(parse(header({ length: 12 }))).toMatchObject({ + ok: false, + error: { kind: "truncated" }, + }); + const full = fullAndroidOtaPayload(); + const parsed = parse(full); + if (!parsed.ok) throw parsed.error; + const cut = full.subarray( + 0, + parsed.value.header.manifestOffset + + Math.min(8, parsed.value.header.manifestSize), + ); + expect(parse(cut)).toMatchObject({ + ok: false, + error: { kind: "truncated" }, + }); +}); + +it("keeps a complete manifest when the blob is truncated", () => { + const full = fullAndroidOtaPayload(); + const parsed = parse(full); + if (!parsed.ok) throw parsed.error; + const truncated = full.subarray(0, parsed.value.header.blobOffset + 1); + const kept = parse(truncated); + if (!kept.ok) throw kept.error; + expect(kept.value.blobTruncated).toBe(true); + expect(kept.value.partitions.map((partition) => partition.name)).toEqual([ + "boot", + "system", + ]); + expect(kept.value.partitions[0]?.extractable).toBe(false); + expect(kept.value.partitions[0]?.extractRefusal).toBe("blob_truncated"); + expect(kept.value.limitations.join(" ")).toContain("truncated"); + expect( + reconstructAndroidOtaPartition( + kept.value.partitions[0]!, + kept.value.blockSize, + () => new Uint8Array(), + ), + ).toMatchObject({ + ok: false, + error: { _tag: "AndroidOtaPayloadBlobTruncated" }, + }); +}); + +it("names the extraction ceiling, not unsupported operations, for a large REPLACE partition", () => { + const blockSize = 4096; + const newSize = ANDROID_OTA_MAX_EXTRACT_BYTES + blockSize; + const parsed = parse( + buildAndroidOtaPayload({ + blockSize, + partitions: [ + { + name: "super", + newSize, + operations: [ + { + type: 0, + data: Buffer.from("SUPER"), + dstExtents: [{ startBlock: 0, numBlocks: newSize / blockSize }], + }, + ], + }, + ], + }), + ); + if (!parsed.ok) throw parsed.error; + const [partition] = parsed.value.partitions; + expect(partition).toMatchObject({ + extractable: false, + extractRefusal: "size_limit", + }); + expect(parsed.value.limitations).toContain( + ANDROID_OTA_PAYLOAD_LIMITATIONS.partitionSizeLimit, + ); + expect(parsed.value.limitations).not.toContain( + ANDROID_OTA_PAYLOAD_LIMITATIONS.unsupportedOperations, + ); + expect( + reconstructAndroidOtaPartition(partition!, blockSize, () => { + throw new Error("a refused partition reads no operation data"); + }), + ).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { maximum: ANDROID_OTA_MAX_EXTRACT_BYTES }, + }, + }, + }); +}); + +it("refuses operation data that overruns the payload blob", () => { + const bytes = buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + operations: [ + { + type: 0, + dataOffset: 50, + dataLength: 10, + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ], + }, + ], + }); + expect(parse(bytes)).toMatchObject({ + ok: false, + error: { kind: "malformed" }, + }); +}); + +it("refuses an explicit zero manifest block_size as malformed", () => { + const bytes = buildAndroidOtaPayload({ + blockSize: 0, + partitions: [], + }); + expect(parse(bytes)).toMatchObject({ + ok: false, + error: { kind: "malformed" }, + }); +}); + +it("refuses a truncated protobuf field in the manifest", () => { + const writer = new BinaryWriter(); + writer.tag(13, WireType.LengthDelimited).bytes(Uint8Array.of(0x80)); + const manifest = writer.finish(); + const bytes = Buffer.concat([ + header({ manifestSize: BigInt(manifest.length) }), + Buffer.from(manifest), + ]); + expect(parse(bytes)).toMatchObject({ + ok: false, + error: { kind: "malformed" }, + }); +}); + +it("refuses an oversize manifest and metadata signature as capacity limits", () => { + expect( + parseAndroidOtaHeader( + header({ manifestSize: BigInt(ANDROID_OTA_MAX_MANIFEST_BYTES + 1) }), + ANDROID_OTA_HEADER_V2_BYTES, + ), + ).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { maximum: ANDROID_OTA_MAX_MANIFEST_BYTES }, + }, + }, + }); + expect( + parseAndroidOtaHeader( + header({ metadataSignatureSize: ANDROID_OTA_MAX_SIGNATURE_BYTES + 1 }), + ANDROID_OTA_HEADER_V2_BYTES, + ), + ).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { maximum: ANDROID_OTA_MAX_SIGNATURE_BYTES }, + }, + }, + }); +}); + +it("refuses an oversize manifest signatures_size before any signature read", () => { + const bytes = buildAndroidOtaPayload({ + partitions: [], + signaturesSize: ANDROID_OTA_MAX_SIGNATURE_BYTES + 1, + }); + expect(parse(bytes)).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { maximum: ANDROID_OTA_MAX_SIGNATURE_BYTES }, + }, + }, + }); +}); + +it("refuses manifest extents past the total extent budget as a capacity limit", () => { + const extents = new Uint8Array((ANDROID_OTA_MAX_EXTENTS_TOTAL + 1) * 2); + for (let at = 0; at < extents.length; at += 2) extents[at] = 0x32; + const operation = new BinaryWriter() + .tag(1, WireType.Varint) + .int32(0) + .finish(); + const partition = new BinaryWriter() + .tag(1, WireType.LengthDelimited) + .string("system") + .tag(8, WireType.LengthDelimited) + .bytes(Buffer.concat([operation, extents])) + .finish(); + const manifest = new BinaryWriter() + .tag(13, WireType.LengthDelimited) + .bytes(partition) + .finish(); + const bytes = Buffer.concat([ + header({ manifestSize: BigInt(manifest.length) }), + Buffer.from(manifest), + ]); + expect(parse(bytes)).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { maximum: ANDROID_OTA_MAX_EXTENTS_TOTAL }, + }, + }, + }); +}); + +it("refuses group partition names past the manifest-wide budget as a capacity limit", () => { + const group = (names: number) => { + const writer = new BinaryWriter() + .tag(1, WireType.LengthDelimited) + .string("super"); + for (let index = 0; index < names; index += 1) + writer.tag(3, WireType.LengthDelimited).string(""); + return writer.finish(); + }; + const half = ANDROID_OTA_MAX_GROUP_PARTITION_NAMES / 2; + const metadata = new BinaryWriter() + .tag(1, WireType.LengthDelimited) + .bytes(group(half)) + .tag(1, WireType.LengthDelimited) + .bytes(group(half + 1)) + .finish(); + const manifest = new BinaryWriter() + .tag(15, WireType.LengthDelimited) + .bytes(metadata) + .finish(); + const bytes = Buffer.concat([ + header({ manifestSize: BigInt(manifest.length) }), + Buffer.from(manifest), + ]); + expect(parse(bytes)).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { maximum: ANDROID_OTA_MAX_GROUP_PARTITION_NAMES }, + }, + }, + }); +}); + +it("reports a reconstructed hash mismatch without inventing a matching digest", () => { + const bytes = buildAndroidOtaPayload({ + partitions: [ + { + name: "boot", + newHash: Buffer.alloc(32, 0xff), + operations: [{ type: 0, data: Buffer.from("BOOT") }], + }, + ], + }); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + const blob = bytes.subarray(parsed.value.header.blobOffset); + expect( + reconstructAndroidOtaPartition( + parsed.value.partitions[0]!, + parsed.value.blockSize, + (offset, length) => blob.subarray(offset, offset + length), + ), + ).toMatchObject({ + ok: false, + error: { + _tag: "AndroidOtaPayloadIntegrityFailure", + declaredHashHex: "ff".repeat(32), + }, + }); +}); + +it("charges repeated operations on one blob against the reconstruction budget", () => { + const blockSize = 4096; + const bytes = buildAndroidOtaPayload({ + blockSize, + partitions: [ + { + name: "boot", + newSize: blockSize, + operations: [ + { + type: 0, + data: Buffer.from("BOOT"), + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ], + }, + ], + }); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + const [partition] = parsed.value.partitions; + const [operation] = partition!.operations; + const repeats = ANDROID_OTA_MAX_EXTRACT_BYTES / blockSize + 1; + expect( + reconstructAndroidOtaPartition( + { + ...partition!, + operations: Array.from({ length: repeats }, () => operation!), + }, + blockSize, + () => { + throw new Error("an over-budget partition reads no operation data"); + }, + ), + ).toMatchObject({ + ok: false, + error: { + failure: { + kind: "limit", + limit: { maximum: ANDROID_OTA_MAX_EXTRACT_BYTES }, + }, + }, + }); +}); + +it("refuses destination extents outside the image and short operation data", () => { + const blockSize = 4096; + const reconstruct = ( + dstExtents: readonly { startBlock: number; numBlocks: number }[], + data: Buffer, + ) => { + const bytes = buildAndroidOtaPayload({ + blockSize, + partitions: [ + { + name: "boot", + newSize: blockSize, + operations: [{ type: 0, data, dstExtents }], + }, + ], + }); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + const blob = bytes.subarray(parsed.value.header.blobOffset); + return reconstructAndroidOtaPartition( + parsed.value.partitions[0]!, + blockSize, + (offset, length) => blob.subarray(offset, offset + length), + { verifyDeclaredHash: false }, + ); + }; + const refused = { + ok: false, + error: { kind: "malformed" }, + }; + expect( + reconstruct( + [{ startBlock: 1, numBlocks: 1 }], + Buffer.alloc(blockSize, 0x41), + ), + ).toMatchObject(refused); + expect( + reconstruct( + [{ startBlock: 0, numBlocks: 2 }], + Buffer.alloc(blockSize * 2, 0x41), + ), + ).toMatchObject(refused); + expect( + reconstruct([{ startBlock: 0, numBlocks: 1 }], Buffer.from("BOOT")), + ).toMatchObject(refused); + expect( + reconstruct( + [{ startBlock: 0, numBlocks: 1 }], + Buffer.alloc(blockSize, 0x41), + ), + ).toMatchObject({ ok: true }); +}); + +it("refuses reconstruction when destination extents leave blocks unwritten", () => { + const blockSize = 4096; + const bytes = buildAndroidOtaPayload({ + blockSize, + partitions: [ + { + name: "boot", + newSize: blockSize * 2, + operations: [ + { + type: 0, + data: Buffer.alloc(blockSize, 0x41), + dstExtents: [{ startBlock: 0, numBlocks: 1 }], + }, + ], + }, + ], + }); + const parsed = parse(bytes); + if (!parsed.ok) throw parsed.error; + const blob = bytes.subarray(parsed.value.header.blobOffset); + expect( + reconstructAndroidOtaPartition( + parsed.value.partitions[0]!, + blockSize, + (offset, length) => blob.subarray(offset, offset + length), + { verifyDeclaredHash: false }, + ), + ).toMatchObject({ + ok: false, + error: { kind: "malformed" }, + }); +}); + +it("names duplicate partitions with a per-name suffix that skips taken names", () => { + const parsed = parse( + buildAndroidOtaPayload({ + partitions: ["boot", "boot-2", "boot", "boot", "boot"].map((name) => ({ + name, + operations: [], + })), + }), + ); + if (!parsed.ok) throw parsed.error; + expect(parsed.value.partitions.map((partition) => partition.path)).toEqual([ + "boot.img", + "boot-2.img", + "boot-1.img", + "boot-3.img", + "boot-4.img", + ]); +}); + +it("keeps duplicate partition naming linear at the partition count limit", () => { + const name = "d".repeat(1024); + const bytes = buildAndroidOtaPayload({ + partitions: Array.from({ length: ANDROID_OTA_MAX_PARTITIONS }, () => ({ + name, + operations: [], + })), + }); + const started = performance.now(); + const parsed = parse(bytes); + // This parse takes tens of milliseconds; restarting the suffix search at 1 + // for every collision took over 4 seconds. + expect(performance.now() - started).toBeLessThan(1000); + if (!parsed.ok) throw parsed.error; + const paths = parsed.value.partitions.map((partition) => partition.path); + expect(new Set(paths).size).toBe(ANDROID_OTA_MAX_PARTITIONS); + expect(paths.at(-1)).toBe( + `${name}-${String(ANDROID_OTA_MAX_PARTITIONS - 1)}.img`, + ); +}); diff --git a/src/domain/firmware/androidOtaPayload.ts b/src/domain/firmware/androidOtaPayload.ts new file mode 100644 index 0000000000..b51f476bc0 --- /dev/null +++ b/src/domain/firmware/androidOtaPayload.ts @@ -0,0 +1,1496 @@ +import { zstdDecompressSync } from "node:zlib"; + +import { BinaryReader, WireType } from "@bufbuild/protobuf/wire"; + +import { sha256Hex } from "../../kernel/sha256Hex.js"; +import { + decodeLimit, + hostRangeErrorKind, + malformedInput, + ParseFailureError, + truncatedInput, + unsupportedInput, +} from "../parseFailure.js"; +import { err, ok, type Result } from "../result.js"; + +/** + * Field numbers are from AOSP `system/update_engine/update_metadata.proto` + * (`chromeos_update_engine.DeltaArchiveManifest` and nested messages). Only + * the fields this reader reports are decoded; unknown fields are skipped. + * + * DeltaArchiveManifest: block_size=3, signatures_offset=4, signatures_size=5, + * minor_version=12, partitions=13, max_timestamp=14, + * dynamic_partition_metadata=15, partial_update=16, apex_info=17, + * security_patch_level=18. + * PartitionUpdate: partition_name=1, run_postinstall=2, postinstall_path=3, + * filesystem_type=4, old_partition_info=6, new_partition_info=7, + * operations=8, version=17, merge_operations=18, estimate_cow_size=19. + * InstallOperation: type=1, data_offset=2, data_length=3, src_extents=4, + * dst_extents=6. + * Extent: start_block=1, num_blocks=2. + * PartitionInfo: size=1, hash=2. + * DynamicPartitionMetadata: groups=1, snapshot_enabled=2, vabc_enabled=3, + * vabc_compression_param=4. + * DynamicPartitionGroup: name=1, size=2, partition_names=3. + * ApexInfo: package_name=1, version=2, is_compressed=3, decompressed_size=4. + * Signatures: signatures=1. + */ +export const ANDROID_OTA_MAGIC = "CrAU"; +export const ANDROID_OTA_MAGIC_BYTES = Buffer.from(ANDROID_OTA_MAGIC, "latin1"); +export const ANDROID_OTA_MAJOR_VERSION = 2n; +export const ANDROID_OTA_HEADER_V1_BYTES = 20; +export const ANDROID_OTA_HEADER_V2_BYTES = 24; +export const ANDROID_OTA_MAX_MANIFEST_BYTES = 16 * 1024 * 1024; +export const ANDROID_OTA_MAX_PARTITIONS = 4096; +export const ANDROID_OTA_MAX_OPERATIONS = 65_536; +export const ANDROID_OTA_MAX_OPERATIONS_TOTAL = 262_144; +export const ANDROID_OTA_MAX_EXTENTS_TOTAL = 1_048_576; +export const ANDROID_OTA_MAX_SIGNATURE_BYTES = 1024 * 1024; +export const ANDROID_OTA_MAX_SIGNATURES = 64; +export const ANDROID_OTA_MAX_GROUPS = 256; +export const ANDROID_OTA_MAX_GROUP_PARTITION_NAMES = 4096; +export const ANDROID_OTA_MAX_APEX = 4096; +export const ANDROID_OTA_MAX_EXTRACT_BYTES = 32 * 1024 * 1024; +export const ANDROID_OTA_MAX_OPERATION_DATA_BYTES = 32 * 1024 * 1024; +export const ANDROID_OTA_DEFAULT_BLOCK_SIZE = 4096; + +export const ANDROID_OTA_PAYLOAD_LIMITATIONS = { + inventoryScope: + "Android OTA payload inventory reads the CrAU header and DeltaArchiveManifest. Signatures are not verified, delta operations are not applied, and partition images are reconstructed only from REPLACE, ZERO, and REPLACE_ZSTD operations.", + signaturesUnverified: + "Metadata and payload signatures were parsed for size and signature count only; they were not verified.", + blobTruncated: + "The payload blob is truncated; partition inventory comes from the manifest and operation data past the end of the file was not read.", + unsupportedOperations: + "Delta and compressed operations other than REPLACE_ZSTD are not applied; those partitions cannot be reconstructed.", + missingPartitionSize: + "A partition without a new_partition_info size cannot be reconstructed.", + partitionSizeLimit: `A partition larger than the fixed ${String(32 * 1024 * 1024)}-byte extraction ceiling is inventoried but not reconstructed.`, + partitionBlobTruncated: + "A partition whose operation data extends past the end of the payload file cannot be reconstructed.", +} as const; + +/** Why a partition image cannot be reconstructed, or null when it can. */ +export type AndroidOtaExtractRefusal = + | "unsupported_operations" + | "missing_size" + | "size_limit" + | "blob_truncated"; + +/** The limitation text that names one extraction refusal. */ +export const androidOtaExtractRefusalLimitation = ( + refusal: AndroidOtaExtractRefusal, +): string => + ({ + unsupported_operations: + ANDROID_OTA_PAYLOAD_LIMITATIONS.unsupportedOperations, + missing_size: ANDROID_OTA_PAYLOAD_LIMITATIONS.missingPartitionSize, + size_limit: ANDROID_OTA_PAYLOAD_LIMITATIONS.partitionSizeLimit, + blob_truncated: ANDROID_OTA_PAYLOAD_LIMITATIONS.partitionBlobTruncated, + })[refusal]; + +/** InstallOperation.Type names keyed by the proto enumerator. */ +export const INSTALL_OPERATION_NAMES: Readonly> = { + 0: "REPLACE", + 1: "REPLACE_BZ", + 2: "MOVE", + 3: "BSDIFF", + 4: "SOURCE_COPY", + 5: "SOURCE_BSDIFF", + 6: "ZERO", + 7: "DISCARD", + 8: "REPLACE_XZ", + 9: "PUFFDIFF", + 10: "BROTLI_BSDIFF", + 11: "ZUCCHINI", + 12: "LZ4DIFF_BSDIFF", + 13: "LZ4DIFF_PUFFDIFF", + 14: "REPLACE_ZSTD", +}; + +const EXTRACTABLE_TYPES = new Set([0, 6, 14]); + +/** + * How parsing a payload failed: the shared byte-format failure, so a short + * header is `truncated`, an unsupported major version `unsupported`, and a + * fixed ceiling `limit`. + */ +export type AndroidOtaPayloadParseError = + | ParseFailureError<"malformed"> + | ParseFailureError<"truncated"> + | ParseFailureError<"unsupported"> + | ParseFailureError<"limit">; + +export type AndroidOtaPayloadReconstructError = + | AndroidOtaPayloadParseError + | { + readonly _tag: "AndroidOtaPayloadUnsupportedOperation"; + readonly message: string; + readonly typeCode: number; + } + | { + readonly _tag: "AndroidOtaPayloadIntegrityFailure"; + readonly message: string; + readonly declaredHashHex: string; + readonly observedHashHex: string; + } + | { + readonly _tag: "AndroidOtaPayloadBlobTruncated"; + readonly message: string; + }; + +const ANDROID_OTA_FORMAT = "android-ota-payload"; + +const malformed = (message: string): AndroidOtaPayloadParseError => + malformedInput(ANDROID_OTA_FORMAT, message); + +const truncated = (message: string): AndroidOtaPayloadParseError => + truncatedInput(ANDROID_OTA_FORMAT, message); + +const unsupportedVersion = ( + majorVersion: bigint, +): AndroidOtaPayloadParseError => + unsupportedInput( + ANDROID_OTA_FORMAT, + androidOtaUnsupportedVersion(majorVersion), + { offset: 4, field: "major_version" }, + ); + +const capacity = ( + name: string, + maximum: number, + unit: string, +): AndroidOtaPayloadParseError => + decodeLimit( + ANDROID_OTA_FORMAT, + `Android OTA payload ${name} exceeds the fixed ${String(maximum)}-${unit} ceiling`, + { name: `Android OTA payload ${name}`, maximum }, + ); + +export const androidOtaUnsupportedVersion = ( + version: bigint | number | string, +): string => + `Android OTA payload major version ${String(version)} is unsupported; this reader supports version 2 only`; + +const u32be = (bytes: Uint8Array, at: number): number => + (((bytes[at] ?? 0) << 24) | + ((bytes[at + 1] ?? 0) << 16) | + ((bytes[at + 2] ?? 0) << 8) | + (bytes[at + 3] ?? 0)) >>> + 0; + +const u64be = (bytes: Uint8Array, at: number): bigint => + (BigInt(u32be(bytes, at)) << 32n) | BigInt(u32be(bytes, at + 4)); + +export const hasAndroidOtaPayloadMagic = (prefix: Buffer): boolean => + prefix.length >= 4 && prefix.subarray(0, 4).equals(ANDROID_OTA_MAGIC_BYTES); + +export type AndroidOtaPayloadRecognition = + | { readonly state: "recognized" } + | { readonly state: "refused"; readonly reason: string }; + +/** Recognize CrAU; version 2 is supported, any other readable version is refused. */ +export const recognizeAndroidOtaPayload = ( + prefix: Buffer, +): AndroidOtaPayloadRecognition | undefined => { + if (!hasAndroidOtaPayloadMagic(prefix)) return undefined; + if (prefix.length < 12) return { state: "recognized" }; + const version = u64be(prefix, 4); + return version === ANDROID_OTA_MAJOR_VERSION + ? { state: "recognized" } + : { state: "refused", reason: androidOtaUnsupportedVersion(version) }; +}; + +export interface AndroidOtaPayloadHeader { + readonly magic: typeof ANDROID_OTA_MAGIC; + readonly majorVersion: 2; + readonly manifestSize: number; + readonly metadataSignatureSize: number; + readonly manifestOffset: number; + readonly blobOffset: number; +} + +export interface AndroidOtaExtent { + readonly startBlock: number | null; + readonly numBlocks: number; +} + +export interface AndroidOtaInstallOperation { + readonly typeCode: number; + readonly typeName: string; + readonly dataOffset: number; + readonly dataLength: number; + readonly srcExtents: readonly AndroidOtaExtent[]; + readonly dstExtents: readonly AndroidOtaExtent[]; +} + +export interface AndroidOtaPartitionInfo { + readonly size: number | null; + readonly hashHex: string | null; +} + +export interface AndroidOtaPartition { + readonly index: number; + readonly name: string; + readonly path: string; + readonly newPartitionInfo: AndroidOtaPartitionInfo; + readonly oldPartitionInfo: AndroidOtaPartitionInfo | null; + readonly version: string | null; + readonly runPostinstall: boolean | null; + readonly postinstallPath: string | null; + readonly filesystemType: string | null; + readonly operations: readonly AndroidOtaInstallOperation[]; + readonly operationCounts: readonly { + readonly type: string; + readonly type_code: number; + readonly count: number; + }[]; + readonly totalDataLength: number; + readonly mergeOperationCount: number; + readonly estimateCowSize: number | null; + readonly extractable: boolean; + /** The reason `extractable` is false, or null when the image can be rebuilt. */ + readonly extractRefusal: AndroidOtaExtractRefusal | null; +} + +export interface AndroidOtaDynamicGroup { + readonly name: string; + readonly size: number | null; + readonly partitionNames: readonly string[]; +} + +export interface AndroidOtaApexInfo { + readonly packageName: string | null; + readonly version: number | null; + readonly isCompressed: boolean | null; + readonly decompressedSize: number | null; +} + +export interface AndroidOtaPayload { + readonly header: AndroidOtaPayloadHeader; + readonly fileSize: number; + readonly blockSize: number; + readonly minorVersion: number; + readonly payloadKind: "full" | "delta"; + readonly maxTimestamp: number | null; + readonly partialUpdate: boolean | null; + readonly securityPatchLevel: string | null; + readonly signaturesOffset: number | null; + readonly signaturesSize: number | null; + readonly metadataSignatureBlobSize: number; + readonly metadataSignatureCount: number | null; + readonly payloadSignatureBlobSize: number | null; + readonly payloadSignatureCount: number | null; + readonly partitions: readonly AndroidOtaPartition[]; + readonly dynamicPartitionGroups: readonly AndroidOtaDynamicGroup[]; + readonly snapshotEnabled: boolean | null; + readonly vabcEnabled: boolean | null; + readonly vabcCompressionParam: string | null; + readonly apexInfo: readonly AndroidOtaApexInfo[]; + readonly blobTruncated: boolean; + readonly limitations: readonly string[]; +} + +const toBigInt = (value: bigint | string | number): bigint => + typeof value === "bigint" + ? value + : typeof value === "number" + ? BigInt(value) + : BigInt(value); + +const asSafeUint = ( + value: bigint | string | number, + label: string, +): Result => { + const numeric = toBigInt(value); + if (numeric < 0n || numeric > BigInt(Number.MAX_SAFE_INTEGER)) + return err(malformed(`${label} is not an exact nonnegative extent`)); + return ok(Number(numeric)); +}; + +const asSafeInt = (value: bigint | string | number): number | null => { + const numeric = toBigInt(value); + if ( + numeric < BigInt(Number.MIN_SAFE_INTEGER) || + numeric > BigInt(Number.MAX_SAFE_INTEGER) + ) + return null; + return Number(numeric); +}; + +const hex = (bytes: Uint8Array): string => Buffer.from(bytes).toString("hex"); + +const protobufFailure = (cause: unknown): AndroidOtaPayloadParseError => + malformed( + cause instanceof Error + ? `DeltaArchiveManifest protobuf is truncated or malformed: ${cause.message}` + : "DeltaArchiveManifest protobuf is truncated or malformed", + ); + +const fail = (failure: AndroidOtaPayloadParseError): never => { + throw failure; +}; + +const unwrap = (result: Result): T => { + if (result.ok) return result.value; + return fail(result.error); +}; + +const walk = ( + bytes: Uint8Array, + visit: (field: number, wire: WireType, reader: BinaryReader) => void, +): Result => { + try { + const reader = new BinaryReader(bytes); + while (reader.pos < reader.len) { + const [field, wire] = reader.tag(); + visit(field, wire, reader); + } + return ok(undefined); + } catch (cause: unknown) { + return err( + cause instanceof ParseFailureError ? cause : protobufFailure(cause), + ); + } +}; + +export const parseAndroidOtaHeader = ( + bytes: Uint8Array, + fileSize: number, +): Result => { + if (!Number.isSafeInteger(fileSize) || fileSize < 0) + return err( + malformed("Android OTA payload size is not an exact nonnegative extent"), + ); + if ( + bytes.length < 4 || + Buffer.from(bytes.subarray(0, 4)).toString("latin1") !== ANDROID_OTA_MAGIC + ) + return err(malformed("Android OTA payload magic mismatch: expected CrAU")); + if (bytes.length < 12) + return err( + truncated( + `Android OTA payload header is truncated: ${String(bytes.length)} bytes, expected ${String(ANDROID_OTA_HEADER_V2_BYTES)}`, + ), + ); + const majorVersion = u64be(bytes, 4); + if (majorVersion !== ANDROID_OTA_MAJOR_VERSION) + return err(unsupportedVersion(majorVersion)); + if (bytes.length < ANDROID_OTA_HEADER_V2_BYTES) + return err( + truncated( + `Android OTA payload header is truncated: ${String(bytes.length)} bytes, expected ${String(ANDROID_OTA_HEADER_V2_BYTES)}`, + ), + ); + const manifestSize = u64be(bytes, 12); + const metadataSignatureSize = u32be(bytes, 20); + const size = asSafeUint(manifestSize, "manifest_size"); + if (!size.ok) return size; + if (size.value > ANDROID_OTA_MAX_MANIFEST_BYTES) + return err( + capacity("manifest size", ANDROID_OTA_MAX_MANIFEST_BYTES, "byte"), + ); + if (metadataSignatureSize > ANDROID_OTA_MAX_SIGNATURE_BYTES) + return err( + capacity( + "metadata signature size", + ANDROID_OTA_MAX_SIGNATURE_BYTES, + "byte", + ), + ); + const blobOffset = + ANDROID_OTA_HEADER_V2_BYTES + size.value + metadataSignatureSize; + if ( + !Number.isSafeInteger(blobOffset) || + blobOffset < ANDROID_OTA_HEADER_V2_BYTES + ) + return err(malformed("Android OTA payload header extents overflow")); + if (fileSize < ANDROID_OTA_HEADER_V2_BYTES + size.value) + return err( + truncated( + `Android OTA payload manifest is truncated: header declares ${String(size.value)} manifest bytes but the file ends at ${String(fileSize)}`, + ), + ); + return ok({ + magic: ANDROID_OTA_MAGIC, + majorVersion: 2, + manifestSize: size.value, + metadataSignatureSize, + manifestOffset: ANDROID_OTA_HEADER_V2_BYTES, + blobOffset, + }); +}; + +interface ExtentDraft { + startBlock: number | null; + numBlocks: number; +} + +interface OperationDraft { + hasType: boolean; + typeCode: number; + dataOffset: number; + dataLength: number; + srcExtents: ExtentDraft[]; + dstExtents: ExtentDraft[]; +} + +interface PartitionInfoDraft { + size: number | null; + hashHex: string | null; +} + +interface PartitionDraft { + name: string | undefined; + runPostinstall: boolean | null; + postinstallPath: string | null; + filesystemType: string | null; + oldPartitionInfo: PartitionInfoDraft | null; + newPartitionInfo: PartitionInfoDraft; + operations: OperationDraft[]; + version: string | null; + mergeOperationCount: number; + estimateCowSize: number | null; +} + +interface GroupDraft { + name: string | undefined; + size: number | null; + partitionNames: string[]; +} + +interface ManifestDraft { + blockSize: number; + signaturesOffset: number | null; + signaturesSize: number | null; + minorVersion: number; + partitions: PartitionDraft[]; + maxTimestamp: number | null; + maxTimestampOutOfRange: boolean; + partialUpdate: boolean | null; + securityPatchLevel: string | null; + groups: GroupDraft[]; + snapshotEnabled: boolean | null; + vabcEnabled: boolean | null; + vabcCompressionParam: string | null; + hasDynamicMetadata: boolean; + apex: AndroidOtaApexInfo[]; + operationTotal: number; + groupPartitionNameTotal: { count: number }; +} + +const emptyPartitionInfo = (): PartitionInfoDraft => ({ + size: null, + hashHex: null, +}); + +const decodeExtent = ( + bytes: Uint8Array, +): Result => { + const extent: ExtentDraft = { startBlock: null, numBlocks: 0 }; + const walked = walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.Varint) { + const start = toBigInt(reader.uint64()); + extent.startBlock = + start === 0xffff_ffff_ffff_ffffn ? null : Number(start); + if ( + extent.startBlock !== null && + !Number.isSafeInteger(extent.startBlock) + ) + fail( + malformed("extent start_block is not an exact nonnegative extent"), + ); + return; + } + if (field === 2 && wire === WireType.Varint) { + extent.numBlocks = unwrap( + asSafeUint(reader.uint64(), "extent num_blocks"), + ); + return; + } + reader.skip(wire); + }); + return walked.ok ? ok(extent) : walked; +}; + +const decodePartitionInfo = ( + bytes: Uint8Array, +): Result => { + const info = emptyPartitionInfo(); + const walked = walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.Varint) { + info.size = unwrap(asSafeUint(reader.uint64(), "partition size")); + return; + } + if (field === 2 && wire === WireType.LengthDelimited) { + info.hashHex = hex(reader.bytes()); + return; + } + reader.skip(wire); + }); + return walked.ok ? ok(info) : walked; +}; + +const decodeOperation = ( + bytes: Uint8Array, + extentTotal: { count: number }, +): Result => { + const operation: OperationDraft = { + hasType: false, + typeCode: 0, + dataOffset: 0, + dataLength: 0, + srcExtents: [], + dstExtents: [], + }; + const walked = walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.Varint) { + operation.hasType = true; + operation.typeCode = reader.int32(); + if (operation.typeCode < 0) + fail(malformed("InstallOperation type is negative")); + return; + } + if (field === 2 && wire === WireType.Varint) { + operation.dataOffset = unwrap( + asSafeUint(reader.uint64(), "operation data_offset"), + ); + return; + } + if (field === 3 && wire === WireType.Varint) { + operation.dataLength = unwrap( + asSafeUint(reader.uint64(), "operation data_length"), + ); + return; + } + if ((field === 4 || field === 6) && wire === WireType.LengthDelimited) { + if (extentTotal.count >= ANDROID_OTA_MAX_EXTENTS_TOTAL) + fail(capacity("extent total", ANDROID_OTA_MAX_EXTENTS_TOTAL, "extent")); + extentTotal.count += 1; + (field === 4 ? operation.srcExtents : operation.dstExtents).push( + unwrap(decodeExtent(reader.bytes())), + ); + return; + } + reader.skip(wire); + }); + if (!walked.ok) return walked; + if (!operation.hasType) + return err(malformed("InstallOperation is missing type")); + return ok(operation); +}; + +const decodePartition = ( + bytes: Uint8Array, + operationTotal: { count: number }, + extentTotal: { count: number }, +): Result => { + const partition: PartitionDraft = { + name: undefined, + runPostinstall: null, + postinstallPath: null, + filesystemType: null, + oldPartitionInfo: null, + newPartitionInfo: emptyPartitionInfo(), + operations: [], + version: null, + mergeOperationCount: 0, + estimateCowSize: null, + }; + const walked = walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.LengthDelimited) { + partition.name = reader.string(); + return; + } + if (field === 2 && wire === WireType.Varint) { + partition.runPostinstall = reader.bool(); + return; + } + if (field === 3 && wire === WireType.LengthDelimited) { + partition.postinstallPath = reader.string(); + return; + } + if (field === 4 && wire === WireType.LengthDelimited) { + partition.filesystemType = reader.string(); + return; + } + if (field === 6 && wire === WireType.LengthDelimited) { + partition.oldPartitionInfo = unwrap(decodePartitionInfo(reader.bytes())); + return; + } + if (field === 7 && wire === WireType.LengthDelimited) { + partition.newPartitionInfo = unwrap(decodePartitionInfo(reader.bytes())); + return; + } + if (field === 8 && wire === WireType.LengthDelimited) { + if (partition.operations.length >= ANDROID_OTA_MAX_OPERATIONS) + fail( + capacity( + "operations per partition", + ANDROID_OTA_MAX_OPERATIONS, + "operation", + ), + ); + if (operationTotal.count >= ANDROID_OTA_MAX_OPERATIONS_TOTAL) + fail( + capacity( + "operation total", + ANDROID_OTA_MAX_OPERATIONS_TOTAL, + "operation", + ), + ); + partition.operations.push( + unwrap(decodeOperation(reader.bytes(), extentTotal)), + ); + operationTotal.count += 1; + return; + } + if (field === 17 && wire === WireType.LengthDelimited) { + partition.version = reader.string(); + return; + } + if (field === 18 && wire === WireType.LengthDelimited) { + reader.skip(wire); + partition.mergeOperationCount += 1; + return; + } + if (field === 19 && wire === WireType.Varint) { + partition.estimateCowSize = unwrap( + asSafeUint(reader.uint64(), "estimate_cow_size"), + ); + return; + } + reader.skip(wire); + }); + if (!walked.ok) { + const cause = walked.error; + return err(cause); + } + if (partition.name === undefined) + return err(malformed("PartitionUpdate is missing partition_name")); + return ok(partition); +}; + +const decodeGroup = ( + bytes: Uint8Array, + partitionNameTotal: { count: number }, +): Result => { + const group: GroupDraft = { + name: undefined, + size: null, + partitionNames: [], + }; + const walked = walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.LengthDelimited) { + group.name = reader.string(); + return; + } + if (field === 2 && wire === WireType.Varint) { + group.size = unwrap( + asSafeUint(reader.uint64(), "dynamic partition group size"), + ); + return; + } + if (field === 3 && wire === WireType.LengthDelimited) { + if (partitionNameTotal.count >= ANDROID_OTA_MAX_GROUP_PARTITION_NAMES) + fail( + capacity( + "dynamic partition group partition_names total", + ANDROID_OTA_MAX_GROUP_PARTITION_NAMES, + "name", + ), + ); + partitionNameTotal.count += 1; + group.partitionNames.push(reader.string()); + return; + } + reader.skip(wire); + }); + if (!walked.ok) return walked; + if (group.name === undefined) + return err(malformed("DynamicPartitionGroup is missing name")); + return ok(group); +}; + +const decodeApex = ( + bytes: Uint8Array, +): Result => { + const apex: { + packageName: string | null; + version: number | null; + isCompressed: boolean | null; + decompressedSize: number | null; + } = { + packageName: null, + version: null, + isCompressed: null, + decompressedSize: null, + }; + const walked = walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.LengthDelimited) { + apex.packageName = reader.string(); + return; + } + if (field === 2 && wire === WireType.Varint) { + apex.version = asSafeInt(reader.int64()); + return; + } + if (field === 3 && wire === WireType.Varint) { + apex.isCompressed = reader.bool(); + return; + } + if (field === 4 && wire === WireType.Varint) { + apex.decompressedSize = asSafeInt(reader.int64()); + return; + } + reader.skip(wire); + }); + return walked.ok ? ok(apex) : walked; +}; + +const decodeDynamicMetadata = ( + bytes: Uint8Array, + draft: ManifestDraft, +): Result => { + draft.hasDynamicMetadata = true; + return walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.LengthDelimited) { + if (draft.groups.length >= ANDROID_OTA_MAX_GROUPS) + fail( + capacity("dynamic partition groups", ANDROID_OTA_MAX_GROUPS, "group"), + ); + draft.groups.push( + unwrap(decodeGroup(reader.bytes(), draft.groupPartitionNameTotal)), + ); + return; + } + if (field === 2 && wire === WireType.Varint) { + draft.snapshotEnabled = reader.bool(); + return; + } + if (field === 3 && wire === WireType.Varint) { + draft.vabcEnabled = reader.bool(); + return; + } + if (field === 4 && wire === WireType.LengthDelimited) { + draft.vabcCompressionParam = reader.string(); + return; + } + reader.skip(wire); + }); +}; + +export const countAndroidOtaSignatures = ( + bytes: Uint8Array, +): Result => { + let count = 0; + const walked = walk(bytes, (field, wire, reader) => { + if (field === 1 && wire === WireType.LengthDelimited) { + reader.skip(wire); + count += 1; + if (count > ANDROID_OTA_MAX_SIGNATURES) + fail( + capacity("signature count", ANDROID_OTA_MAX_SIGNATURES, "signature"), + ); + return; + } + reader.skip(wire); + }); + return walked.ok ? ok(count) : walked; +}; + +const decodeManifest = ( + bytes: Uint8Array, +): Result => { + const draft: ManifestDraft = { + blockSize: ANDROID_OTA_DEFAULT_BLOCK_SIZE, + signaturesOffset: null, + signaturesSize: null, + minorVersion: 0, + partitions: [], + maxTimestamp: null, + maxTimestampOutOfRange: false, + partialUpdate: null, + securityPatchLevel: null, + groups: [], + snapshotEnabled: null, + vabcEnabled: null, + vabcCompressionParam: null, + hasDynamicMetadata: false, + apex: [], + operationTotal: 0, + groupPartitionNameTotal: { count: 0 }, + }; + const operationTotal = { count: 0 }; + const extentTotal = { count: 0 }; + const walked = walk(bytes, (field, wire, reader) => { + if (field === 3 && wire === WireType.Varint) { + const size = unwrap(asSafeUint(reader.uint64(), "block_size")); + if (size === 0) fail(malformed("manifest block_size is zero")); + draft.blockSize = size; + return; + } + if (field === 4 && wire === WireType.Varint) { + draft.signaturesOffset = unwrap( + asSafeUint(reader.uint64(), "signatures_offset"), + ); + return; + } + if (field === 5 && wire === WireType.Varint) { + const size = unwrap(asSafeUint(reader.uint64(), "signatures_size")); + if (size > ANDROID_OTA_MAX_SIGNATURE_BYTES) + fail( + capacity( + "payload signature size", + ANDROID_OTA_MAX_SIGNATURE_BYTES, + "byte", + ), + ); + draft.signaturesSize = size; + return; + } + if (field === 12 && wire === WireType.Varint) { + draft.minorVersion = unwrap(asSafeUint(reader.uint64(), "minor_version")); + return; + } + if (field === 13 && wire === WireType.LengthDelimited) { + if (draft.partitions.length >= ANDROID_OTA_MAX_PARTITIONS) + fail( + capacity("partition count", ANDROID_OTA_MAX_PARTITIONS, "partition"), + ); + draft.partitions.push( + unwrap(decodePartition(reader.bytes(), operationTotal, extentTotal)), + ); + return; + } + if (field === 14 && wire === WireType.Varint) { + const timestamp = asSafeInt(reader.int64()); + if (timestamp === null) draft.maxTimestampOutOfRange = true; + else draft.maxTimestamp = timestamp; + return; + } + if (field === 15 && wire === WireType.LengthDelimited) { + unwrap(decodeDynamicMetadata(reader.bytes(), draft)); + return; + } + if (field === 16 && wire === WireType.Varint) { + draft.partialUpdate = reader.bool(); + return; + } + if (field === 17 && wire === WireType.LengthDelimited) { + if (draft.apex.length >= ANDROID_OTA_MAX_APEX) + fail(capacity("apex_info count", ANDROID_OTA_MAX_APEX, "entry")); + draft.apex.push(unwrap(decodeApex(reader.bytes()))); + return; + } + if (field === 18 && wire === WireType.LengthDelimited) { + draft.securityPatchLevel = reader.string(); + return; + } + reader.skip(wire); + }); + if (!walked.ok) return walked; + draft.operationTotal = operationTotal.count; + return ok(draft); +}; + +interface PartitionNameState { + readonly used: Set; + /** Next suffix to try per stem, so collision resolution stays linear. */ + readonly nextSuffix: Map; +} + +const partitionFileName = ( + name: string, + index: number, + state: PartitionNameState, +): string => { + const stem = + name.replace(/[^A-Za-z0-9._-]+/gu, "_").replace(/^\.+/u, "") || + `partition-${String(index)}`; + const withExt = stem.endsWith(".img") ? stem : `${stem}.img`; + let candidate = withExt; + if (state.used.has(candidate)) { + let suffix = state.nextSuffix.get(stem) ?? 1; + do { + candidate = `${stem}-${String(suffix)}.img`; + suffix += 1; + } while (state.used.has(candidate)); + state.nextSuffix.set(stem, suffix); + } + state.used.add(candidate); + return candidate; +}; + +const operationCountsOf = ( + operations: readonly OperationDraft[], +): AndroidOtaPartition["operationCounts"] => { + const counts = new Map(); + for (const operation of operations) + counts.set(operation.typeCode, (counts.get(operation.typeCode) ?? 0) + 1); + return [...counts.entries()] + .sort((left, right) => left[0] - right[0]) + .map(([type_code, count]) => ({ + type: INSTALL_OPERATION_NAMES[type_code] ?? "unknown", + type_code, + count, + })); +}; + +const isExtractable = (operations: readonly OperationDraft[]): boolean => + operations.length > 0 && + operations.every((operation) => EXTRACTABLE_TYPES.has(operation.typeCode)); + +export const parseAndroidOtaPayload = ( + bytes: Uint8Array, + fileSize = bytes.length, + payloadSignatureBytes?: Uint8Array, +): Result => { + const header = parseAndroidOtaHeader(bytes, fileSize); + if (!header.ok) return header; + const manifestEnd = header.value.manifestOffset + header.value.manifestSize; + if (bytes.length < manifestEnd) + return err( + truncated( + `Android OTA payload manifest is truncated: header declares ${String(header.value.manifestSize)} bytes starting at ${String(header.value.manifestOffset)}`, + ), + ); + const manifest = decodeManifest( + bytes.subarray(header.value.manifestOffset, manifestEnd), + ); + if (!manifest.ok) return manifest; + const metadataSlice = bytes.subarray( + manifestEnd, + Math.min(bytes.length, header.value.blobOffset), + ); + let metadataSignatureCount: number | null = null; + if (header.value.metadataSignatureSize > 0) { + if (header.value.metadataSignatureSize > ANDROID_OTA_MAX_SIGNATURE_BYTES) + return err( + capacity( + "metadata signature size", + ANDROID_OTA_MAX_SIGNATURE_BYTES, + "byte", + ), + ); + if (metadataSlice.length === header.value.metadataSignatureSize) { + const counted = countAndroidOtaSignatures(metadataSlice); + if (!counted.ok) return counted; + metadataSignatureCount = counted.value; + } + } + let payloadSignatureCount: number | null = null; + let payloadSignatureBlobSize: number | null = manifest.value.signaturesSize; + const signatureSlice = (): Uint8Array | undefined => { + if (payloadSignatureBytes !== undefined) return payloadSignatureBytes; + if ( + manifest.value.signaturesOffset === null || + manifest.value.signaturesSize === null || + manifest.value.signaturesSize === 0 + ) + return undefined; + const start = header.value.blobOffset + manifest.value.signaturesOffset; + const end = start + manifest.value.signaturesSize; + if (!Number.isSafeInteger(end) || end > bytes.length) return undefined; + return bytes.subarray(start, end); + }; + const payloadSignatureSlice = signatureSlice(); + if ( + payloadSignatureSlice !== undefined && + manifest.value.signaturesSize !== null + ) { + if (payloadSignatureSlice.length !== manifest.value.signaturesSize) + return err( + malformed( + "payload signature blob length does not match signatures_size", + ), + ); + const counted = countAndroidOtaSignatures(payloadSignatureSlice); + if (!counted.ok) return counted; + payloadSignatureCount = counted.value; + } else if ( + payloadSignatureSlice !== undefined && + payloadSignatureSlice.length > 0 + ) { + const counted = countAndroidOtaSignatures(payloadSignatureSlice); + if (!counted.ok) return counted; + payloadSignatureCount = counted.value; + payloadSignatureBlobSize = payloadSignatureSlice.length; + } + + const blobAvailable = Math.max(0, fileSize - header.value.blobOffset); + let blobTruncated = fileSize < header.value.blobOffset; + for (const partition of manifest.value.partitions) { + for (const operation of partition.operations) { + if (operation.dataLength === 0) continue; + const end = operation.dataOffset + operation.dataLength; + if (!Number.isSafeInteger(end) || end < operation.dataOffset) + return err(malformed("operation data extent overflows")); + if ( + manifest.value.signaturesOffset !== null && + end > manifest.value.signaturesOffset + ) + return err( + malformed( + `operation data extent ${String(operation.dataOffset)}+${String(operation.dataLength)} overruns the ${String(manifest.value.signaturesOffset)}-byte payload blob`, + ), + ); + if (end > blobAvailable) blobTruncated = true; + } + } + if ( + manifest.value.signaturesOffset !== null && + manifest.value.signaturesSize !== null + ) { + const declaredEnd = + header.value.blobOffset + + manifest.value.signaturesOffset + + manifest.value.signaturesSize; + if (fileSize < declaredEnd) blobTruncated = true; + } + + const nameState: PartitionNameState = { + used: new Set(), + nextSuffix: new Map(), + }; + const partitions: AndroidOtaPartition[] = manifest.value.partitions.map( + (partition, index) => { + const operations: AndroidOtaInstallOperation[] = partition.operations.map( + (operation) => ({ + typeCode: operation.typeCode, + typeName: INSTALL_OPERATION_NAMES[operation.typeCode] ?? "unknown", + dataOffset: operation.dataOffset, + dataLength: operation.dataLength, + srcExtents: operation.srcExtents.map((extent) => ({ + startBlock: extent.startBlock, + numBlocks: extent.numBlocks, + })), + dstExtents: operation.dstExtents.map((extent) => ({ + startBlock: extent.startBlock, + numBlocks: extent.numBlocks, + })), + }), + ); + const needsBlob = operations.some( + (operation) => operation.dataLength > 0, + ); + const blobFits = operations.every( + (operation) => + operation.dataLength === 0 || + operation.dataOffset + operation.dataLength <= blobAvailable, + ); + const size = partition.newPartitionInfo.size; + const extractRefusal: AndroidOtaExtractRefusal | null = !isExtractable( + partition.operations, + ) + ? "unsupported_operations" + : size === null + ? "missing_size" + : size > ANDROID_OTA_MAX_EXTRACT_BYTES + ? "size_limit" + : needsBlob && !blobFits + ? "blob_truncated" + : null; + return { + index, + name: partition.name!, + path: partitionFileName(partition.name!, index, nameState), + newPartitionInfo: { + size: partition.newPartitionInfo.size, + hashHex: partition.newPartitionInfo.hashHex, + }, + oldPartitionInfo: + partition.oldPartitionInfo === null + ? null + : { + size: partition.oldPartitionInfo.size, + hashHex: partition.oldPartitionInfo.hashHex, + }, + version: partition.version, + runPostinstall: partition.runPostinstall, + postinstallPath: partition.postinstallPath, + filesystemType: partition.filesystemType, + operations, + operationCounts: operationCountsOf(partition.operations), + totalDataLength: operations.reduce( + (total, operation) => total + operation.dataLength, + 0, + ), + mergeOperationCount: partition.mergeOperationCount, + estimateCowSize: partition.estimateCowSize, + extractable: extractRefusal === null, + extractRefusal, + }; + }, + ); + + const limitations: string[] = [ + ANDROID_OTA_PAYLOAD_LIMITATIONS.inventoryScope, + ANDROID_OTA_PAYLOAD_LIMITATIONS.signaturesUnverified, + ]; + if (blobTruncated) + limitations.push(ANDROID_OTA_PAYLOAD_LIMITATIONS.blobTruncated); + for (const refusal of new Set( + partitions.flatMap((partition) => + partition.extractRefusal === null ? [] : [partition.extractRefusal], + ), + )) + limitations.push(androidOtaExtractRefusalLimitation(refusal)); + if (manifest.value.maxTimestampOutOfRange) + limitations.push( + "max_timestamp is outside the exact integer range this reader reports.", + ); + + return ok({ + header: header.value, + fileSize, + blockSize: manifest.value.blockSize, + minorVersion: manifest.value.minorVersion, + payloadKind: manifest.value.minorVersion === 0 ? "full" : "delta", + maxTimestamp: manifest.value.maxTimestamp, + partialUpdate: manifest.value.partialUpdate, + securityPatchLevel: manifest.value.securityPatchLevel, + signaturesOffset: manifest.value.signaturesOffset, + signaturesSize: manifest.value.signaturesSize, + metadataSignatureBlobSize: header.value.metadataSignatureSize, + metadataSignatureCount, + payloadSignatureBlobSize, + payloadSignatureCount, + partitions, + dynamicPartitionGroups: manifest.value.groups.map((group) => ({ + name: group.name!, + size: group.size, + partitionNames: group.partitionNames, + })), + snapshotEnabled: manifest.value.hasDynamicMetadata + ? manifest.value.snapshotEnabled + : null, + vabcEnabled: manifest.value.hasDynamicMetadata + ? manifest.value.vabcEnabled + : null, + vabcCompressionParam: manifest.value.hasDynamicMetadata + ? manifest.value.vabcCompressionParam + : null, + apexInfo: manifest.value.apex, + blobTruncated, + limitations, + }); +}; + +const writeExtents = ( + image: Buffer, + extents: readonly AndroidOtaExtent[], + blockSize: number, + data: Uint8Array, + fillZero: boolean, +): Result => { + // The last block of a partition whose size is not block aligned may be + // partially outside the image; every other destination byte must land + // inside it, and every written byte must come from the operation data. + const blockAlignedEnd = Math.ceil(image.length / blockSize) * blockSize; + let cursor = 0; + let span = 0; + for (const extent of extents) { + if (extent.numBlocks === 0) continue; + if (extent.startBlock === null) + return err( + malformed("InstallOperation destination extent has no start_block"), + ); + const start = extent.startBlock * blockSize; + const extentBytes = extent.numBlocks * blockSize; + if ( + !Number.isSafeInteger(start) || + start < 0 || + start >= image.length || + extentBytes > blockAlignedEnd - start + ) + return err( + malformed( + "InstallOperation destination extent overruns the partition image", + ), + ); + const length = Math.min(extentBytes, image.length - start); + span += extentBytes; + if (fillZero) { + image.fill(0, start, start + length); + continue; + } + if (data.length - cursor < length) + return err( + malformed( + "InstallOperation data is shorter than its destination extents", + ), + ); + image.set(data.subarray(cursor, cursor + length), start); + cursor += extentBytes; + } + if (!fillZero && data.length > span) + return err( + malformed("InstallOperation data is longer than its destination extents"), + ); + return ok(undefined); +}; + +const destinationExtentBytes = ( + extents: readonly AndroidOtaExtent[], + blockSize: number, +): Result => { + let total = 0; + for (const extent of extents) { + if (!Number.isSafeInteger(extent.numBlocks) || extent.numBlocks < 0) + return err( + capacity( + "REPLACE_ZSTD decoded output", + ANDROID_OTA_MAX_EXTRACT_BYTES, + "byte", + ), + ); + if ( + extent.numBlocks > 0 && + blockSize > Math.floor(Number.MAX_SAFE_INTEGER / extent.numBlocks) + ) + return err( + capacity( + "REPLACE_ZSTD decoded output", + ANDROID_OTA_MAX_EXTRACT_BYTES, + "byte", + ), + ); + const bytes = extent.numBlocks * blockSize; + if (total > Number.MAX_SAFE_INTEGER - bytes) + return err( + capacity( + "REPLACE_ZSTD decoded output", + ANDROID_OTA_MAX_EXTRACT_BYTES, + "byte", + ), + ); + total += bytes; + } + return ok(total); +}; + +/** Distinct operation blob bytes one partition open would retain. */ +export const androidOtaDistinctOperationDataBytes = ( + operations: readonly AndroidOtaInstallOperation[], +): Result => { + const seen = new Set(); + let total = 0; + for (const operation of operations) { + if (operation.dataLength === 0) continue; + const key = `${String(operation.dataOffset)}:${String(operation.dataLength)}`; + if (seen.has(key)) continue; + seen.add(key); + if ( + !Number.isSafeInteger(operation.dataLength) || + operation.dataLength < 0 || + total > Number.MAX_SAFE_INTEGER - operation.dataLength + ) + return err( + capacity( + "partition operation data", + ANDROID_OTA_MAX_OPERATION_DATA_BYTES, + "byte", + ), + ); + total += operation.dataLength; + } + if (total > ANDROID_OTA_MAX_OPERATION_DATA_BYTES) + return err( + capacity( + "partition operation data", + ANDROID_OTA_MAX_OPERATION_DATA_BYTES, + "byte", + ), + ); + return ok(total); +}; + +/** The typed failure for a partition the inventory refused to reconstruct. */ +export const androidOtaExtractRefusalError = ( + partition: AndroidOtaPartition, +): AndroidOtaPayloadReconstructError | null => { + switch (partition.extractRefusal) { + case null: + return null; + case "unsupported_operations": { + const unsupported = partition.operations.find( + (operation) => !EXTRACTABLE_TYPES.has(operation.typeCode), + ); + return { + _tag: "AndroidOtaPayloadUnsupportedOperation", + message: `Android OTA partition ${partition.name} uses unsupported operation ${unsupported?.typeName ?? "unknown"}`, + typeCode: unsupported?.typeCode ?? -1, + }; + } + case "missing_size": + return malformed( + `Android OTA partition ${partition.name} has no new_partition_info size`, + ); + case "size_limit": + return capacity( + "extracted partition size", + ANDROID_OTA_MAX_EXTRACT_BYTES, + "byte", + ); + case "blob_truncated": + return { + _tag: "AndroidOtaPayloadBlobTruncated", + message: `Android OTA partition ${partition.name} reads operation data past the end of the payload file`, + }; + } +}; + +/** + * Validate the block size and charge the whole reconstruction against one + * budget before any work starts. Each operation decodes or writes up to its + * destination extent bytes, and repeated blob references are decoded again + * per operation, so a per-decode bound alone does not bound the loop. + */ +const chargeReconstructionWork = ( + operations: readonly AndroidOtaInstallOperation[], + blockSize: number, +): Result => { + if (blockSize <= 0 || !Number.isSafeInteger(blockSize)) + return err(malformed("block_size is not a positive extent")); + let work = 0; + for (const operation of operations) { + const dstBytes = destinationExtentBytes(operation.dstExtents, blockSize); + if (!dstBytes.ok) return dstBytes; + work += dstBytes.value; + if (work > ANDROID_OTA_MAX_EXTRACT_BYTES) + return err( + capacity( + "partition reconstruction work", + ANDROID_OTA_MAX_EXTRACT_BYTES, + "byte", + ), + ); + } + return ok(work); +}; + +const hasCompleteExtentCoverage = ( + operations: readonly AndroidOtaInstallOperation[], + imageSize: number, + blockSize: number, +): boolean => { + const blockCount = Math.ceil(imageSize / blockSize); + if (blockCount === 0) return true; + const spans: [number, number][] = []; + for (const operation of operations) { + for (const extent of operation.dstExtents) { + if (extent.numBlocks === 0) continue; + if (extent.startBlock === null) return false; + spans.push([extent.startBlock, extent.startBlock + extent.numBlocks]); + } + } + spans.sort((left, right) => left[0] - right[0]); + let coveredUntil = 0; + for (const [start, end] of spans) { + if (start > coveredUntil) return false; + if (end > coveredUntil) coveredUntil = end; + if (coveredUntil >= blockCount) return true; + } + return false; +}; + +/** + * Rebuild a full-payload partition image. A declared-hash mismatch fails + * unless `verifyDeclaredHash` is false, which leaves that decision to a caller + * that applies its own integrity policy to the returned bytes. + */ +export const reconstructAndroidOtaPartition = ( + partition: AndroidOtaPartition, + blockSize: number, + readBlob: (offset: number, length: number) => Uint8Array, + options: { readonly verifyDeclaredHash?: boolean } = {}, +): Result => { + const refused = androidOtaExtractRefusalError(partition); + if (refused !== null) return err(refused); + const size = partition.newPartitionInfo.size!; + const budget = chargeReconstructionWork(partition.operations, blockSize); + if (!budget.ok) return budget; + const image = Buffer.alloc(size); + try { + for (const operation of partition.operations) { + if (operation.typeCode === 6) { + const written = writeExtents( + image, + operation.dstExtents, + blockSize, + new Uint8Array(), + true, + ); + if (!written.ok) return written; + continue; + } + const raw = + operation.dataLength === 0 + ? new Uint8Array() + : readBlob(operation.dataOffset, operation.dataLength); + if (raw.length !== operation.dataLength) + return err( + truncated( + `operation data for ${partition.name} is truncated: expected ${String(operation.dataLength)} bytes`, + ), + ); + let payload: Uint8Array = raw; + if (operation.typeCode === 14) { + const dstBytes = destinationExtentBytes( + operation.dstExtents, + blockSize, + ); + if (!dstBytes.ok) return dstBytes; + const maxOutputLength = Math.max( + 1, + Math.min(dstBytes.value, ANDROID_OTA_MAX_EXTRACT_BYTES), + ); + try { + payload = zstdDecompressSync(raw, { maxOutputLength }); + } catch (cause: unknown) { + return err( + hostRangeErrorKind(cause) === "host-capacity" + ? capacity("REPLACE_ZSTD decoded output", maxOutputLength, "byte") + : malformed( + "REPLACE_ZSTD operation payload is not a valid Zstandard frame", + ), + ); + } + } + const written = writeExtents( + image, + operation.dstExtents, + blockSize, + payload, + false, + ); + if (!written.ok) return written; + } + } catch (cause: unknown) { + return err( + malformed( + cause instanceof Error + ? `Android OTA partition ${partition.name} could not be reconstructed: ${cause.message}` + : `Android OTA partition ${partition.name} could not be reconstructed`, + ), + ); + } + if (!hasCompleteExtentCoverage(partition.operations, size, blockSize)) + return err( + malformed( + `Android OTA partition ${partition.name} destination extents do not cover the full ${String(size)}-byte image`, + ), + ); + if (options.verifyDeclaredHash === false) return ok(image); + const observed = sha256Hex(image); + const declared = partition.newPartitionInfo.hashHex; + if (declared !== null && declared !== observed) + return err({ + _tag: "AndroidOtaPayloadIntegrityFailure", + message: `Android OTA partition ${partition.name} hash mismatch`, + declaredHashHex: declared, + observedHashHex: observed, + }); + return ok(image); +}; diff --git a/src/domain/liveBinaryTargetSummary.ts b/src/domain/liveBinaryTargetSummary.ts index f5ada430c6..cc056ff8b1 100644 --- a/src/domain/liveBinaryTargetSummary.ts +++ b/src/domain/liveBinaryTargetSummary.ts @@ -73,6 +73,7 @@ export const liveBinaryTargetSummaryVariants = [ "wxapkg", "uimage", "android-boot-image", + "android-ota-payload", "dmg", "pkg", "intel-hex", diff --git a/src/resources/ArtifactReader.ts b/src/resources/ArtifactReader.ts index acea3a7bdc..8580d9e61e 100644 --- a/src/resources/ArtifactReader.ts +++ b/src/resources/ArtifactReader.ts @@ -235,6 +235,7 @@ export interface ArtifactReader { | "wxapkg" | "uimage" | "android-boot-image" + | "android-ota-payload" | "pyinstaller" | "dotnet-bundle" | "bun-standalone" diff --git a/tests/acceptance/androidOtaPayloadCli.test.ts b/tests/acceptance/androidOtaPayloadCli.test.ts new file mode 100644 index 0000000000..a56277597a --- /dev/null +++ b/tests/acceptance/androidOtaPayloadCli.test.ts @@ -0,0 +1,104 @@ +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect } from "vitest"; + +import { cliTest } from "../support/cli/cliFixture.js"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; +import { parseEvidence } from "../../src/domain/evidence.js"; +import { artifactInspectionResultSchema } from "../../src/domain/artifactInspection.js"; +import { + artifactExtractionResultSchema, + artifactInventoryResultSchema, +} from "../../src/domain/artifactGraph.js"; +import { + deltaAndroidOtaPayload, + fullAndroidOtaPayload, + v1AndroidOtaPayload, +} from "../../src/domain/firmware/androidOtaPayload.fixture.js"; + +cliTest( + "inspects and extracts a full Android OTA payload through the compiled CLI", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-android-ota-cli-"); + const source = join(root, "payload.bin"); + await writeFile(source, fullAndroidOtaPayload()); + const inspected = await cli.run({ + arguments: ["inspect-artifact", source, "--json"], + }); + expect(inspected.exitCode, inspected.stdout + inspected.stderr).toBe(0); + const inspection = artifactInspectionResultSchema.parse( + parseEvidence(inspected.json).normalized_result, + ); + const graph = artifactInventoryResultSchema.parse( + inspection.substeps[0]?.evidence.normalized_result, + ); + expect(graph.manifest.root_format).toBe("android-ota-payload"); + expect(graph.coverage.status).toBe("complete"); + expect( + graph.occurrences.find((row) => row.logical_path === ".") + ?.format_metadata, + ).toMatchObject({ + kind: "android-ota-payload", + payload_kind: "full", + signatures_verified: false, + security_patch_level: "2024-01-05", + }); + const extracted = await cli.run({ + arguments: ["extract-artifact", source, "--json"], + environment: { TMPDIR: root, TMP: root, TEMP: root }, + }); + expect(extracted.exitCode, extracted.stdout + extracted.stderr).toBe(0); + const result = artifactExtractionResultSchema.parse( + parseEvidence(extracted.json).normalized_result, + ); + expect(result.containment_verified).toBe(true); + expect( + (await readFile(join(result.output_root, "boot.img"))) + .subarray(0, 7) + .toString("latin1"), + ).toBe("BOOTIMG"); + }, +); + +cliTest( + "refuses a v1 Android OTA payload through the compiled CLI", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-android-ota-cli-v1-"); + const source = join(root, "payload.bin"); + await writeFile(source, v1AndroidOtaPayload()); + const inspected = await cli.run({ + arguments: ["inspect-artifact", source, "--json"], + }); + expect(inspected.exitCode).not.toBe(0); + expect(`${inspected.stdout}\n${inspected.stderr}`).toContain("unsupported"); + }, +); + +cliTest( + "inventories a delta Android OTA payload without extracting it", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-android-ota-cli-delta-"); + const source = join(root, "payload.bin"); + await writeFile(source, deltaAndroidOtaPayload()); + const inspected = await cli.run({ + arguments: ["inspect-artifact", source, "--json"], + }); + expect(inspected.exitCode, inspected.stdout + inspected.stderr).toBe(0); + const inspection = artifactInspectionResultSchema.parse( + parseEvidence(inspected.json).normalized_result, + ); + const graph = artifactInventoryResultSchema.parse( + inspection.substeps[0]?.evidence.normalized_result, + ); + expect(graph.manifest.root_format).toBe("android-ota-payload"); + expect( + graph.occurrences.find((row) => row.logical_path === "vendor.img"), + ).toMatchObject({ hash_status: "unavailable" }); + const extracted = await cli.run({ + arguments: ["extract-artifact", source, "--json"], + environment: { TMPDIR: root, TMP: root, TEMP: root }, + }); + expect(extracted.exitCode).not.toBe(0); + }, +); diff --git a/tests/boundary/mcp/androidOtaPayloadMcp.test.ts b/tests/boundary/mcp/androidOtaPayloadMcp.test.ts new file mode 100644 index 0000000000..fcc3499193 --- /dev/null +++ b/tests/boundary/mcp/androidOtaPayloadMcp.test.ts @@ -0,0 +1,90 @@ +import { readFile, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { expect, it } from "vitest"; + +import { parseEvidence } from "../../../src/domain/evidence.js"; +import { artifactInspectionResultSchema } from "../../../src/domain/artifactInspection.js"; +import { artifactExtractionResultSchema } from "../../../src/domain/artifactGraph.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js"; +import { + fullAndroidOtaPayload, + v1AndroidOtaPayload, +} from "../../../src/domain/firmware/androidOtaPayload.fixture.js"; + +it.each(["compact"] as const)( + "retains Android OTA payload facts through compiled MCP (%s)", + async (profile) => { + const root = await createTestTempDirectory("rea-android-ota-mcp-"); + const path = join(root, "payload.bin"); + await writeFile(path, fullAndroidOtaPayload()); + const { call } = await connectLocalToolsMcp({ + REA_MCP_TOOL_FAMILIES: "session,artifact", + REA_MCP_INPUT_SCHEMA_PROFILE: profile, + REA_MCP_OUTPUT_SCHEMA_PROFILE: profile, + }); + let outputRoot: string | undefined; + try { + const opened = await call("open_binary", { path }); + expect(opened.isError, JSON.stringify(opened)).not.toBe(true); + expect(opened.structuredContent).toMatchObject({ + result: { + kind: "archive", + format: "android-ota-payload", + architecture: null, + }, + }); + const reply = await call("inspect_artifact", {}); + expect(reply.isError, JSON.stringify(reply)).not.toBe(true); + const inspection = artifactInspectionResultSchema.parse( + parseEvidence(reply.structuredContent).normalized_result, + ); + const inventory = inspection.substeps[0]!.evidence.normalized_result; + expect(inventory.coverage.status).toBe("complete"); + expect(inventory.occurrences).toContainEqual( + expect.objectContaining({ + logical_path: ".", + format_metadata: expect.objectContaining({ + kind: "android-ota-payload", + payload_kind: "full", + signatures_verified: false, + security_patch_level: "2024-01-05", + }), + }), + ); + const summary = await call("inspect_artifact", { detail: "summary" }); + expect(summary.isError, JSON.stringify(summary)).not.toBe(true); + const summaryRoot = JSON.stringify( + parseEvidence(summary.structuredContent).normalized_result, + ); + expect(summaryRoot).toContain('"kind":"android-ota-payload-summary"'); + expect(summaryRoot).not.toContain('"operation_counts"'); + const extracted = await call("extract_artifact", {}); + expect(extracted.isError, JSON.stringify(extracted)).not.toBe(true); + const result = artifactExtractionResultSchema.parse( + parseEvidence(extracted.structuredContent).normalized_result, + ); + outputRoot = result.output_root; + expect(result.containment_verified).toBe(true); + expect( + (await readFile(join(result.output_root, "boot.img"))) + .subarray(0, 7) + .toString("latin1"), + ).toBe("BOOTIMG"); + } finally { + if (outputRoot !== undefined) await rm(outputRoot, { recursive: true }); + } + }, +); + +it("refuses a v1 Android OTA payload through compiled MCP open_binary", async () => { + const root = await createTestTempDirectory("rea-android-ota-mcp-v1-"); + const path = join(root, "payload.bin"); + await writeFile(path, v1AndroidOtaPayload()); + const { call } = await connectLocalToolsMcp({ + REA_MCP_TOOL_FAMILIES: "session,artifact", + }); + const opened = await call("open_binary", { path }); + expect(opened.isError).toBe(true); + expect(JSON.stringify(opened)).toContain("unsupported"); +});