fix(evidence)!: require ESP flash_dump and PE unsigned attribute OIDs (#11595)

* fix(evidence)!: require ESP flash_dump and PE unsigned attribute OIDs

Both fields were optional only for Evidence recorded before REA reported
them (6.8.0 and earlier). Every producer writes them: the ESP image reader
and facts builder write `flash_dump` (null unless the file is a flash dump
read from a later address), and the PE certificate parser writes
`unsigned_attribute_oids` (null when the signer has none). They are now
required and nullable, and the inspection hint no longer branches on an
absent `flash_dump`. The ESP acceptance test that read pre-6.9 inventory
Evidence now checks that such Evidence is refused.

A call-path comment called Evidence without relationship coverage "legacy";
providers that report no coverage still produce it, so the comment now says
so.

BREAKING CHANGE: inline inventory Evidence for an ESP image root without
`format_metadata.flash_dump`, and PE certificate Evidence whose signers lack
`unsigned_attribute_oids`, are refused as invalid input. Recreate the
observation with the current REA.

Refs #10510

* test(certificates): refuse a signer without unsigned_attribute_oids; update the guide
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 07:53:42 +08:00
1 parent d15304b928
commit 459553b901
7 files changed
+51 -49

No files matched your search

+3 -3
View File
@@ -53,9 +53,9 @@ Encoded order is kept, and values are copied as decoded, without RFC 4514
escaping or RDN reversal, so a name of only single-valued RDNs still places
`, ` between attributes.
Each signer reports `unsigned_attribute_oids`: null means the field was absent,
and an array lists the types when present. Older retained Evidence may omit the
field. Unsigned attribute contents, including nested signatures and timestamp
Each signer reports `unsigned_attribute_oids`: null means the signer has no
unsigned attributes, and an array lists their types. Evidence that omits the
field (written before REA 6.9.0) is refused; recreate the observation. Unsigned attribute contents, including nested signatures and timestamp
tokens, are not decoded; their presence makes coverage partial and adds a
limitation. Certificate and signer counts refer to the outer SignedData.
+2 -4
View File
@@ -547,13 +547,11 @@ export const espImageMetadataSchema = z.strictObject({
* `flash_offset`, and a partition table sits at `table_file_offset`, where
* that origin puts the default `0x8000`. Reopen the file as
* `esp-flash-image` with that `flash_offset`. Null otherwise, and in the
* nested facts of a flash layout. Absent from Evidence recorded before REA
* reported it; its graph digest covers the record without the field.
* nested facts of a flash layout.
*/
flash_dump: z
.strictObject({ flash_offset: uint32, table_file_offset: offset })
.nullable()
.exactOptional(),
.nullable(),
});
export type EspImageMetadata = z.infer<typeof espImageMetadataSchema>;
+1 -2
View File
@@ -382,9 +382,8 @@ const espFlashDumpProbes = (
({ logical_path }) => logical_path === ".",
)?.format_metadata;
if (root?.kind !== "esp-image") return [];
// Evidence recorded before REA reported the origin has no hint to offer.
const dump = root.flash_dump;
if (dump === null || dump === undefined) return [];
if (dump === null) return [];
const offset = offsetText(dump.flash_offset);
return [
{
+3 -2
View File
@@ -314,8 +314,9 @@ const inspectSearch = ({
incompleteExpandedCoverage = true;
}
// Explicit, Evidence-bound relationship coverage owns completeness;
// generic provider/dossier limitations remain contextual. Legacy Evidence
// without that metadata retains its conservative limitation-based rule.
// generic provider/dossier limitations remain contextual. Evidence from
// a provider that reports no relationship coverage keeps the
// conservative limitation-based rule.
// The search only expands callee edges, so coverage that is unknown
// solely because callers are unobservable does not make the searched
// callee closure incomplete; the caller caveat stays in limitations.
+2 -3
View File
@@ -100,9 +100,8 @@ const signerInfoSchema = z.strictObject({
.regex(/^[0-9a-f]*$/)
.nullable(),
authenticated_attributes: z.boolean(),
// Optional for Evidence recorded before unsigned attributes were observed.
// Null means the field was absent; an array means it was present.
unsigned_attribute_oids: z.array(z.string()).nullable().optional(),
// Null means the signer has no unsigned attributes; an array lists them.
unsigned_attribute_oids: z.array(z.string()).nullable(),
});
const pkcs7Schema = z.strictObject({
+21
View File
@@ -106,6 +106,27 @@ it("reports unsigned attribute OIDs and incomplete nested coverage", () => {
}
});
// The parser always reports the field (null when absent), so a report that
// omits it is refused at that field rather than read as unknown.
it("refuses a signer that omits unsigned_attribute_oids", () => {
const report = parse(peCertificateFixture(false));
const [entry] = report.entries;
const [signer] = entry?.pkcs7?.signers ?? [];
if (entry?.pkcs7 === undefined || entry.pkcs7 === null || !signer)
throw new Error("Fixture has no PKCS#7 signer");
const { unsigned_attribute_oids: _omitted, ...withoutField } = signer;
const refused = peCertificatesSchema.safeParse({
...report,
entries: [{ ...entry, pkcs7: { ...entry.pkcs7, signers: [withoutField] } }],
});
expect(refused.success).toBe(false);
expect(refused.error?.issues).toContainEqual(
expect.objectContaining({
path: ["entries", 0, "pkcs7", "signers", 0, "unsigned_attribute_oids"],
}),
);
});
it.each([false, true])(
"rejects a misaligned certificate table (PE32+ = %s)",
(plus) => {
@@ -71,20 +71,27 @@ it("reports an ESP segment whose load address alone changed", async () => {
expect(same.changes).toEqual([]);
});
/** The inventory as REA recorded it before ESP image roots had `flash_dump`. */
/** An ESP image inventory without `flash_dump`, as releases before 6.9 wrote it. */
const withoutFlashDump = (source: Evidence): Evidence => {
return historicalInventoryEvidence(
source,
(occurrence) => {
if (occurrence.format_metadata?.kind !== "esp-image") return occurrence;
const { flash_dump: _dump, ...historical } = occurrence.format_metadata;
return { ...occurrence, format_metadata: historical };
// The current type requires the field this record omits.
return {
...occurrence,
format_metadata: historical as typeof occurrence.format_metadata,
};
},
"observed",
);
};
it("reads and compares ESP image Evidence recorded before flash_dump", async () => {
// Every ESP image root records `flash_dump` (null when the file is not a
// flash dump read from a later address), so an inventory without it is
// refused rather than read as one with unknown origin.
it("refuses ESP image inventory Evidence without flash_dump", async () => {
const root = await createTestTempDirectory("rea-esp-historical-");
const path = join(root, "app.bin");
await writeFile(path, espImage({ segments: ESP32C3_APP_SEGMENTS }));
@@ -99,40 +106,17 @@ it("reads and compares ESP image Evidence recorded before flash_dump", async ()
.substeps.find(({ operation }) => operation === "inventory_artifact")
?.evidence,
);
const historical = withoutFlashDump(current);
const recorded = JSON.stringify(historical);
const rootMetadata = (evidence: Evidence) =>
artifactInventoryResultSchema
.parse(evidence.normalized_result)
.occurrences.find(({ logical_path }) => logical_path === ".")
?.format_metadata;
expect(rootMetadata(current)).toMatchObject({
kind: "esp-image",
flash_dump: null,
});
expect(rootMetadata(historical)).not.toHaveProperty("flash_dump");
const rootMetadata = artifactInventoryResultSchema
.parse(current.normalized_result)
.occurrences.find(
({ logical_path }) => logical_path === ".",
)?.format_metadata;
expect(rootMetadata).toMatchObject({ kind: "esp-image", flash_dump: null });
const compared = await call("compare_artifacts", {
left: historical,
left: withoutFlashDump(current),
right: current,
});
expect(compared.isError, JSON.stringify(compared)).not.toBe(true);
expect(
artifactComparisonResultSchema.parse(
parseEvidence(compared.structuredContent).normalized_result,
),
).toMatchObject({ status: "unchanged", changes: [] });
const viewed = await call("inspect_analysis_view", {
source: { kind: "inline", evidence: historical },
view: { kind: "summary" },
});
expect(viewed.isError, JSON.stringify(viewed)).not.toBe(true);
const summary = artifactInventorySummaryViewResultSchema.parse(
parseEvidence(viewed.structuredContent).normalized_result,
).summary;
expect(summary.root_format_metadata).toMatchObject({ kind: "esp-image" });
expect(summary.root_format_metadata).not.toHaveProperty("flash_dump");
// Reading the record leaves the graph its digest covers unchanged.
expect(JSON.stringify(historical)).toBe(recorded);
expect(compared.isError).toBe(true);
expect(JSON.stringify(compared.content)).toContain("flash_dump");
});