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

@@ -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"