fix(esp): disclose partition entries outside the table checksum (#12384)

* fix(esp): disclose partition entries outside the table checksum

* fix(esp): label the partition checksum offset origin

* fix(esp): count partition entries outside the table MD5

The coverage warning was only prose, and it presented the MD5 entry's
table-relative offset without a structured fact. Record
entriesAfterChecksum on the MD5 result, project it as
entries_after_checksum, and keep the warning as presentation.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(esp): accept saved flash inventories without the checksum count

A required entries_after_checksum rejected ESP flash Evidence written
before the field existed. Keep the count exactOptional so omission
stays unknown, and still emit it for new inventories.

Co-authored-by: morluto <morluto@users.noreply.github.com>

---------

Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
Co-authored-by: ShuaixinHuang <ShuaixinHuang@users.noreply.github.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-19 11:59:02 -05:00
1 parent 8c3dbd99e1
commit ebd709cef5
7 files changed
+232 -6

No files matched your search

+11 -2
View File
@@ -23,7 +23,10 @@ before it, and a terminating entry within `0xC00` bytes. ESP-IDF accepts a
table with no partition entries, but REA requires one, so that neither
erased flash nor a lone MD5 entry is read as a table. A table whose MD5 does not match, or that has a second MD5 entry, is
still read, with `md5.status` `invalid` and a limitation, because the
bootloader would refuse it. The table is located in this order:
bootloader would refuse it. Partition entries after the MD5 record are
kept. The digest covers only the entries before it, and
`entries_after_checksum` counts the later ones. The table is located in
this order:
1. at the caller's `partition_table_offset`, when given; no scan follows;
2. at the default `0x8000`;
@@ -89,7 +92,13 @@ The root `format_metadata` (`esp-flash-image`) records:
table, with its ESP image facts;
- `partition_table`: its flash address, the `method` that found it
(`default`, `caller` or `scan`), the partition count and the MD5 `status`
(`valid`, `invalid` or `absent`) with the stored and computed digests;
(`valid`, `invalid` or `absent`) with the stored and computed digests.
`entries_after_checksum`, when present, is how many partition entries
follow the MD5 record and sit outside its digest. New inventories emit
0 when the record is absent or every partition entry precedes it.
Evidence saved before the field omits it, and that omission leaves the
count unknown. When the count is greater than zero, a limitation names
it and the MD5 entry's offset from the start of the table;
- `apps`: ESP image facts for each app partition the dump holds; app
partitions declared over the same bytes share one decode;
- `otadata`: the otadata partition's records, or null without one;
@@ -18,6 +18,7 @@ import {
espFlashDump,
otaData,
otaRecord,
partitionEntry,
partitionTable,
} from "../domain/firmware/espFlash.fixture.js";
import {
@@ -106,7 +107,7 @@ describe("ESP flash layout inventory", () => {
flash_address: 0x8000,
method: "default",
partition_count: 6,
md5: { status: "valid" },
md5: { status: "valid", entries_after_checksum: 0 },
},
partitions_outside_dump: [],
otadata: { partition_index: 1 },
@@ -174,6 +175,30 @@ describe("ESP flash layout inventory", () => {
expect.stringMatching(/0xa000.*0x1000.*MD5.*does not record/iu),
);
});
it("reports partition entries after the MD5 record as a count", async () => {
const [first, second, third] = TWO_OTA_PARTITIONS;
const prefix = partitionTable([first!]);
const snapshot = await scanCanonicalArtifactInventory(
await writeDump(
espFlashDump({
bootloader: { at: 0, bytes: BOOTLOADER },
table: Buffer.concat([
prefix.subarray(0, 64),
partitionEntry(second!),
partitionEntry(third!),
prefix.subarray(64),
]),
}),
),
);
expect(root(snapshot)).toMatchObject({
partition_table: {
flash_address: 0x8000,
md5: { status: "valid", entries_after_checksum: 2 },
},
});
});
});
it("inventories a zero-byte partition without reporting missing bytes", async () => {
@@ -334,6 +334,7 @@ const layoutMetadata = (
status: table.md5.status,
stored: table.md5.stored,
computed: table.md5.computed,
entries_after_checksum: table.md5.entriesAfterChecksum,
},
},
partitions_outside_dump: table.partitions
+130
View File
@@ -0,0 +1,130 @@
import { expect, it } from "vitest";
import { artifactInventoryResultSchema } from "./artifactGraph.js";
const digest = (character: string) => character.repeat(64);
const MD5 = "ab".repeat(16);
/** The MD5 object Evidence stored before `entries_after_checksum` existed. */
const historicalMd5 = {
status: "valid" as const,
stored: MD5,
computed: MD5,
};
const flashMetadata = (md5: {
readonly status: "valid";
readonly stored: string;
readonly computed: string;
readonly entries_after_checksum?: number | undefined;
}) => ({
kind: "esp-flash-image" as const,
flash_offset: { value: 0, source: "default" as const },
chip: null,
bootloader: null,
partition_table: {
flash_address: 0x8000,
method: "default" as const,
partition_count: 1,
md5,
},
partitions_outside_dump: [],
apps: [],
otadata: null,
boot_selection: {
basis: "none" as const,
active_record: null,
slot: null,
partition_index: null,
assumptions: [],
running_partition: "unknown" as const,
},
undescribed: [],
});
/** One inventory page, the payload `inspect_analysis_view` parses. */
const inventory = (
metadata: ReturnType<typeof flashMetadata>,
): Record<string, unknown> => ({
manifest: {
manifest_id: `agm_${digest("b")}`,
root_artifact_id: `art_${digest("a")}`,
root_sha256: digest("c"),
root_format: "esp-flash-image",
graph_sha256: digest("d"),
node_count: 1,
occurrence_count: 1,
edge_count: 0,
},
nodes: [
{
artifact_id: `art_${digest("a")}`,
format: "file",
sha256: digest("c"),
size: 0,
media_type: null,
architecture: null,
content_state: "materialized",
limitations: [],
},
],
occurrences: [
{
occurrence_id: `occ_${digest("e")}`,
artifact_id: `art_${digest("a")}`,
parent_occurrence_id: null,
logical_path: ".",
entry_kind: "file",
artifact_kind: "container",
artifact_format: "esp-flash-image",
declared_size: 0,
compressed_size: 0,
executable: false,
encrypted: false,
hash_status: "not-hashed",
source_location: null,
format_metadata: metadata,
limitations: [],
},
],
edges: [],
provenance: [],
coverage: { scope: "container-entries", status: "complete" },
integrity_contradictions: [],
limitations: [],
});
const parsedMd5 = (input: Record<string, unknown>) => {
const metadata =
artifactInventoryResultSchema.parse(input).occurrences[0]?.format_metadata;
if (metadata?.kind !== "esp-flash-image")
throw new Error("expected ESP flash metadata");
return metadata.partition_table.md5;
};
it("parses ESP flash Evidence saved before the checksum entry count", () => {
const md5 = parsedMd5(inventory(flashMetadata(historicalMd5)));
expect(md5).toEqual(historicalMd5);
expect(md5).not.toHaveProperty("entries_after_checksum");
});
it("keeps a recorded checksum entry count on current ESP flash Evidence", () => {
expect(
parsedMd5(
inventory(flashMetadata({ ...historicalMd5, entries_after_checksum: 2 })),
),
).toEqual({ ...historicalMd5, entries_after_checksum: 2 });
});
it("rejects an explicit undefined checksum entry count", () => {
expect(
artifactInventoryResultSchema.safeParse(
inventory(
flashMetadata({
...historicalMd5,
entries_after_checksum: undefined,
}),
),
).success,
).toBe(false);
});
+7
View File
@@ -697,6 +697,13 @@ export const espFlashImageMetadataSchema = z.strictObject({
.string()
.regex(/^[0-9a-f]{32}$/u)
.nullable(),
/**
* Partition entries after the MD5 record, outside its digest. New
* inventories emit 0 when the record is absent or every partition
* entry precedes it. Omission is Evidence saved before this field
* and leaves the count unknown.
*/
entries_after_checksum: uint8.exactOptional(),
}),
}),
/**
@@ -48,6 +48,7 @@ describe("ESP partition tables", () => {
);
expect(decoded.md5.status).toBe("valid");
expect(decoded.md5.entryOffset).toBe(7 * 32);
expect(decoded.md5.entriesAfterChecksum).toBe(0);
expect(decoded.length).toBe(9 * 32);
expect(decoded.limitations).toEqual([]);
expect(decoded.partitions.map(({ label }) => label)).toEqual([
@@ -79,6 +80,7 @@ describe("ESP partition tables", () => {
expect(decoded.md5).toEqual({
status: "absent",
entryOffset: null,
entriesAfterChecksum: 0,
stored: null,
computed: null,
});
@@ -90,6 +92,7 @@ describe("ESP partition tables", () => {
partitionTable(TWO_OTA_PARTITIONS, { md5: "corrupt" }),
);
expect(decoded.md5.status).toBe("invalid");
expect(decoded.md5.entriesAfterChecksum).toBe(0);
expect(decoded.partitions).toHaveLength(6);
expect(decoded.limitations).toEqual([
expect.stringMatching(/MD5.*0xc0.*does not match.*bootloader rejects/iu),
@@ -491,3 +494,27 @@ describe("ESP bootloader location", () => {
]);
});
});
it("keeps and discloses partitions after a matching prefix MD5", () => {
const [first, second, third] = TWO_OTA_PARTITIONS;
const prefix = partitionTable([first!]);
const decoded = table(
Buffer.concat([
prefix.subarray(0, 64),
partitionEntry(second!),
partitionEntry(third!),
prefix.subarray(64),
]),
);
expect(decoded.md5).toMatchObject({
status: "valid",
entryOffset: 32,
entriesAfterChecksum: 2,
});
expect(decoded.md5.stored).toBe(decoded.md5.computed);
expect(decoded.partitions.map(({ label }) => label)).toEqual([
first?.label,
second?.label,
third?.label,
]);
});
+30 -3
View File
@@ -53,7 +53,13 @@ export interface EspPartition {
export interface EspPartitionTableMd5 {
readonly status: "valid" | "invalid" | "absent";
/** Byte offset of the MD5 entry from the start of the table, or null when absent. */
readonly entryOffset: number | null;
/**
* Partition entries that follow the MD5 record and are outside its digest.
* Zero when the record is absent or every partition entry precedes it.
*/
readonly entriesAfterChecksum: number;
readonly stored: string | null;
readonly computed: string | null;
}
@@ -95,7 +101,10 @@ const partition = (
* over the entries before it, and a terminator whose magic, type and subtype
* are all `0xFF`. A structural fault means the bytes are not a table. An MD5
* mismatch or a second MD5 entry, which the bootloader rejects, is reported
* as an integrity fact so that the declared entries stay visible. ESP-IDF
* as an integrity fact so that the declared entries stay visible. Partition
* entries after the MD5 record stay in the table. The digest covers only the
* entries before it; `entriesAfterChecksum` counts the later ones, and a
* limitation names that count and the record's table-relative offset. ESP-IDF
* accepts a table with no partition entries, but REA requires one before
* the terminator, so that neither erased flash nor a lone MD5 entry is read
* as a table.
@@ -108,9 +117,11 @@ export const decodeEspPartitionTable = (
let md5: EspPartitionTableMd5 = {
status: "absent",
entryOffset: null,
entriesAfterChecksum: 0,
stored: null,
computed: null,
};
let partitionsAfterMd5 = 0;
for (let slot = 0; slot < MAX_ENTRIES; slot += 1) {
const at = slot * ENTRY_BYTES;
const entry = bytes.subarray(at, at + ENTRY_BYTES);
@@ -120,6 +131,7 @@ export const decodeEspPartitionTable = (
);
const magic = u16(entry, 0);
if (magic === PARTITION_MAGIC) {
if (md5.entryOffset !== null) partitionsAfterMd5 += 1;
partitions.push(partition(entry, partitions.length, at));
continue;
}
@@ -138,6 +150,7 @@ export const decodeEspPartitionTable = (
md5 = {
status: stored === computed ? "valid" : "invalid",
entryOffset: at,
entriesAfterChecksum: 0,
stored,
computed,
};
@@ -150,8 +163,22 @@ export const decodeEspPartitionTable = (
const terminator =
magic === END_MAGIC && entry[2] === END_TYPE && entry[3] === END_TYPE;
// An MD5 entry is not a partition: a table declares at least one.
if (terminator && partitions.length > 0)
return ok({ partitions, md5, length: at + ENTRY_BYTES, limitations });
if (terminator && partitions.length > 0) {
const reported: EspPartitionTableMd5 = {
...md5,
entriesAfterChecksum: partitionsAfterMd5,
};
if (reported.entryOffset !== null && reported.entriesAfterChecksum > 0)
limitations.push(
`${String(reported.entriesAfterChecksum)} partition entries after the MD5 record at table-relative offset ${offsetText(reported.entryOffset)} are outside its checksum coverage.`,
);
return ok({
partitions,
md5: reported,
length: at + ENTRY_BYTES,
limitations,
});
}
return err(
slot === 0 && magic === END_MAGIC
? "the first entry is empty"