Expose a read container's raw blocks for hashing

[sehkone]

Why

bootler's recorded install attempts bind every attempt to the exact installer payload it ran from (aicers/bootler#412, a leaf of the recovery tree under aicers/bootler#422). The binding is a fingerprint over the container's format version and its raw manifest, archive, signature and key-ID blocks, computed so that it survives bootler-release rewrap (which relocates the trailer onto a different base executable). bootler must not grow a second footer parser, so the blocks have to come from deploy-core's container reader.

deploy-core's reader already holds all three missing pieces, but none is public. At 427330ae52fddcb0f6a9bedb6666397fb7593363, read_package_container (src/payload.rs, around line 1999) returns an UnparsedContainer, whose footer_version() (around :1691) and manifest_bytes() (around :1699) are pub(crate), and whose archive_block() (around :1705) is pub(crate) and returns only an offset and a length. signature() and key_id() are already public and cover the envelope half. Nothing public streams a read container's archive block: Payload keeps its archive offsets private and only extract_to consumes them, and verify_package / verify_contents are signed single-build package verifiers that bootler#412 explicitly may not use.

deploy-core #72 considered widening these accessors and kept them pub(crate), because handing out the signed bytes "with no accompanying way to parse them under this crate's rules" invites serde_json::from_slice at the call site; it added parse_unverified_manifest instead. This consumer answers that concern differently: it only hashes the bytes, never parses them, and a parsed manifest cannot serve it, because the fingerprint is defined over the exact bytes and re-serialization is forbidden. deploy-core's own RFC 0001 (docs/rfcs/0001-image-evidence-and-package-writer.md, around line 303) records this need as a separate piece of work that must preserve signature and framing policy.

Scope

Add read-only accessors to UnparsedContainer<R: Read + Seek>, the type read_package_container already returns. Names carry the trust status, following the crate's style:

impl<R: Read + Seek> UnparsedContainer<R> {
    /// The container format version the selected footer recorded
    /// (currently 1 or 2). Not the manifest's `format_version`.
    #[must_use]
    pub fn container_version(&self) -> u8;

    /// The manifest block exactly as it sits in the container: unparsed,
    /// unauthenticated, never re-serialized. For hashing or signature
    /// checks only; decode through `parse_unverified_manifest` or
    /// `verify::verify_package`, never `serde_json` directly.
    #[must_use]
    pub fn raw_manifest_block(&self) -> &[u8];

    /// Length in bytes of the raw (compressed) archive block, as the
    /// validated footer records it.
    #[must_use]
    pub fn archive_block_len(&self) -> u64;

    /// A reader over exactly the raw archive block.
    ///
    /// # Errors
    /// `PayloadError::Io` when the seek fails.
    pub fn raw_archive_block(&mut self) -> Result<RawArchiveBlock<'_, R>, PayloadError>;
}

/// Exactly one container's archive block. `Read` only; no `Seek`.
pub struct RawArchiveBlock<'a, R> { /* borrows the source, tracks remaining */ }
impl<R: Read> Read for RawArchiveBlock<'_, R> { /* bounded by remaining */ }

Semantics:

• container_version is the footer version (FORMAT_VERSION is 2; version-1 containers remain readable), not the manifest schema version (3–6), and requires no manifest parse.
• raw_manifest_block returns the same bytes manifest_bytes() returns today. The rustdoc states that the bytes are unauthenticated and points decoding at parse_unverified_manifest / verify::verify_package, keeping Expose the bounded container's manifest to callers outside the crate #72's intent. manifest_bytes(), footer_version() and into_payload() may stay pub(crate) or be re-expressed through the new methods; their existing crate-internal callers keep working.
• raw_archive_block seeks the source to the block's start once and then yields exactly archive_block_len() bytes followed by EOF. It never reads outside the block, never allocates the block and never decompresses it. A source that ends before the recorded length surfaces from read as io::ErrorKind::UnexpectedEof, never as a short successful stream.
• The accessors work whatever the envelope state (EnvelopeBlock::Absent, Present or WrongLength) and whether or not the manifest would parse. Refusing WrongLength or an unparsable manifest remains the caller's decision.
• Document that read_package_container reports a file without a trailer as PayloadError::NoTrailer, which is how an installer-side caller recognises an empty payload.

No existing public signature, verdict or verdict order changes: read_package_container's framing checks, signature()/key_id(), parse_unverified_manifest, open / open_path / open_current_exe, open_package*, verify_package, verify_contents, the writers and rewrap_trailer behave exactly as before. verification_never_reads_the_archive_block (src/verify.rs) stays true, because only the new method reads that block.

Add, gated like widen_envelope_blocks (#[cfg(any(test, feature = "test-support"))]), a writer for a version-1 container fixture so consumers can test version-1 input through the real reader without hand-building footers.

Acceptance criteria

• UnparsedContainer exposes container_version, raw_manifest_block, archive_block_len and raw_archive_block with the semantics above, and RawArchiveBlock is public and Read-only.
• A version-1 container reports 1 and an append_trailer output reports 2.
• raw_manifest_block() equals the manifest bytes the writer emitted, byte for byte, for an unsigned container and for one written by append_trailer_signed (where it also equals the bytes handed to the signer).
• raw_archive_block() yields exactly the archive bytes the writer emitted, and the same bytes on a rewrap_trailer output over a base of different length.
• A counting source shows the reader reads exactly archive_block_len() bytes from the block's offset and nothing before or after it; a source truncated after validation yields UnexpectedEof.
• The accessors work on containers whose envelope blocks are WrongLength, and on a container whose manifest does not parse.
• The test-support version-1 writer exists and its output is accepted by read_package_container.
• No existing public API changes; the full CI matrix (fmt, clippy with and without test-support, tests) passes.

Test plan

• Unit tests in src/payload.rs for each acceptance item, using the crate's existing writers (append_trailer, append_trailer_signed, rewrap_trailer) and the new version-1 fixture writer.
• A counting Read + Seek wrapper that records every seek and read range, for the bounded-stream assertion.
• A truncating wrapper that validates normally and then ends early, for the UnexpectedEof assertion.
• The existing verify.rs archive-block test runs unchanged.

Out of scope

• Any bootler change (bootler#412 adopts the revision this issue lands, through its own pin move).
• A fingerprint or hashing helper in deploy-core; the consumer hashes.
• Changing manifest parsing, verification, the writers, EnvelopeBounds, or making read_package_container_bounded public.
• Session, executor or spawn APIs.

Pointers

• src/payload.rs at 427330a: UnparsedContainer and its footer_version / manifest_bytes / archive_block (around 1691–1705), parse_unverified_manifest (around 1722), signature / key_id (around 1735–1742), EnvelopeBlock (around 1779), read_package_container (around 1999), validate_footer (around 826), FORMAT_VERSION (around 126), widen_envelope_blocks (around 932), rewrap_trailer (around 1587).
• src/verify.rs: ENVELOPE_BOUNDS, verification_never_reads_the_archive_block.
• deploy-core Expose the bounded container's manifest to callers outside the crate #72 (the decision to keep the raw accessors private) and docs/rfcs/0001-image-evidence-and-package-writer.md around line 303.
• aicers/bootler#412 (the consumer contract).

[sehkone]

Verification summary

• Delivery: COMPLETE — the merged code delivers what the issue asked for. (the auditor's own verdict)
• Extra changes: NO_EXTRA_CHANGES — the merged code changed nothing beyond what the issue asked for. (the auditor's own verdict)
• Defects: NO_DEFECT — the merged pull requests left no defect of their own behind. (the auditor's own verdict)

Delivery decides whether this issue is closed or reopened. Defects widens what the follow-up filing considers. Extra changes gates nothing — it is an observation for a human; the report names what went beyond the issue.

Implementing pull requests, at the merge commits this audit read:

• Expose a read container's raw blocks for hashing (#131) #134 — 3e49e1964d7569f7a2e3e02a462f96a33c482f90 (the tree the audit read)

The full report — the assessment included verbatim — stays local, at:
~/.agentcoop/runs/aicers/deploy-core/verify/MTMx/report.md

Findings this run did not file:

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
The four raw-block accessors and Read-only RawArchiveBlock are present
Explanation (the auditor's whole response):
The four requested accessors are present on `UnparsedContainer`: `container_version`, `raw_manifest_block`, `archive_block_len`, and `raw_archive_block` (`src/payload.rs:1766`, `src/payload.rs:1780`, `src/payload.rs:1787`, `src/payload.rs:1806`). `RawArchiveBlock` is public, borrows the source, and implements `Read` without exposing `Seek` (`src/payload.rs:1919`, `src/payload.rs:1931`). This was not filed because it satisfies the issue’s API requirement; the audit found no shortfall or defect in it.
Interpretation (the auditor's accepted statement):
The issue requires four public read-only accessors, and the merged code provides them; this finding records compliance.
Interpretation (the auditor's accepted statement):
Treating this finding as a shortfall would require a missing accessor or violated behavior, but the audit found neither, so a violation cannot be established.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
Container versions 1 and 2 are reported from their footers
Explanation (the auditor's whole response):
`container_version()` returns the selected footer’s version without parsing the manifest (`src/payload.rs:1766`). The test `a_version_1_container_reports_1_and_a_current_one_reports_2` checks that a version-1 fixture reports `1` and an `append_trailer` container reports `2` (`src/payload/raw_block_tests.rs:238`). This finding records a delivered requirement, so there is no shortfall to file.
Interpretation (the auditor's accepted statement):
The issue requires the footer version, and the implementation and named test show that version-1 and version-2 containers report the requested values.
Interpretation (the auditor's accepted statement):
Reading this observation as a shortfall would require evidence that the accessor reports the wrong version or parses the manifest first; the audit found no such evidence.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
Raw manifest bytes match unsigned output, signed output, and signer input
Explanation (the auditor's whole response):
`raw_manifest_block()` returns the stored manifest bytes without parsing or re-serializing them (`src/payload.rs:1780`). The tests `the_raw_manifest_block_is_the_one_the_unsigned_writer_emitted` and `the_raw_manifest_block_is_the_one_the_signer_was_handed` compare those bytes with unsigned output, signed output, and the signer’s input (`src/payload/raw_block_tests.rs:255`, `src/payload/raw_block_tests.rs:279`). This satisfies the issue’s byte-for-byte requirement, so there is no shortfall to file.
Interpretation (the auditor's accepted statement):
The accessor returns the stored manifest bytes, and the tests show they match unsigned output, signed output, and signer input; the requirement is met.
Interpretation (the auditor's accepted statement):
Calling this a shortfall would require a byte mismatch or re-serialization path, neither of which the audit found.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
Raw archive bytes match writer output and survive rewrapping
Explanation (the auditor's whole response):
`raw_archive_block()` streams the archive bytes recorded by the footer (`src/payload.rs:1806`, `src/payload.rs:1931`). `the_raw_archive_block_is_the_one_the_writer_emitted_and_survives_a_rewrap` checks those bytes against writer output before and after rewrapping onto a base of different length (`src/payload/raw_block_tests.rs:296`). This is a fulfilled requirement, with no shortfall to file.
Interpretation (the auditor's accepted statement):
The accessor streams the recorded archive bytes, and the named test shows the same bytes after rewrapping onto a different base; the requirement is met.
Interpretation (the auditor's accepted statement):
Treating this as a shortfall would require a changed or truncated archive stream after rewrapping, but the audit found no such behavior.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
Archive reads stay within the block and report truncation or seek failure
Explanation (the auditor's whole response):
The archive reader seeks to the block start, limits each read to the remaining block length, and returns `UnexpectedEof` if the source ends early (`src/payload.rs:1806`, `src/payload.rs:1938`, `src/payload.rs:1941`). `the_archive_reader_reads_exactly_the_block_and_nothing_around_it` checks the seek and read ranges; `a_source_that_ends_inside_the_block_is_unexpected_eof` and `a_failed_seek_to_the_archive_block_is_an_io_error` cover the two failure cases (`src/payload/raw_block_tests.rs:329`, `src/payload/raw_block_tests.rs:377`, `src/payload/raw_block_tests.rs:543`). These are the behaviors the issue requested, so there is no shortfall to file.
Interpretation (the auditor's accepted statement):
The implementation bounds reads to the archive block and reports early EOF or seek failure as requested; the finding records compliance.
Interpretation (the auditor's accepted statement):
Reading this as a defect would require an out-of-block read, a successful short stream, or a mishandled seek failure; the audit found none.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
The accessors work across envelope states and unparseable manifests
Explanation (the auditor's whole response):
The raw accessors remain available when envelope blocks are `Absent`, `Present`, or `WrongLength`, and when the manifest cannot be parsed (`src/payload.rs:1747`). The named tests exercise those states and unparseable manifests at both container versions (`src/payload/raw_block_tests.rs:403`, `src/payload/raw_block_tests.rs:446`). This matches the issue’s requirement to leave refusal to the caller, so there is no shortfall to file.
Interpretation (the auditor's accepted statement):
The accessors return raw blocks across all stated envelope states and unparseable manifests, as the issue requires; this finding records compliance.
Interpretation (the auditor's accepted statement):
Treating this as a shortfall would require a reachable state in which an accessor refuses those blocks, but the audit found no such state.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
A missing trailer returns PayloadError::NoTrailer
Explanation (the auditor's whole response):
`read_package_container` documents `PayloadError::NoTrailer` as the result for an installer without a trailer and returns that error when no container head is found (`src/payload.rs:2153`, `src/payload.rs:2165`). `a_file_without_a_trailer_is_no_trailer` covers the case (`src/payload/raw_block_tests.rs:513`). The requested behavior is present, so there is no shortfall to file.
Interpretation (the auditor's accepted statement):
The issue asks that a missing trailer be documented as PayloadError::NoTrailer, and the documentation and return path show that behavior; the finding records compliance.
Interpretation (the auditor's accepted statement):
Calling this a shortfall would require the documentation or return path to omit NoTrailer, but the audit found both present.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
The gated version-1 fixture writer produces input accepted by the real reader
Explanation (the auditor's whole response):
`append_version_1_trailer` is gated by `#[cfg(any(test, feature = "test-support"))]` and writes a version-1 footer around caller-supplied blocks (`src/payload.rs:1012`, `src/payload.rs:1029`). `the_version_1_writer_frames_a_container_the_real_readers_accept` checks the real reader, and `a_version_1_fixture_reads_through_the_real_reader` exercises it through the public API (`src/payload/raw_block_tests.rs:464`, `tests/raw_container_blocks.rs:80`). The requested fixture exists and works in the covered cases, so there is no shortfall to file.
Interpretation (the auditor's accepted statement):
The gated writer produces version-1 containers accepted by the real reader, satisfying the fixture requirement.
Interpretation (the auditor's accepted statement):
Treating the fixture as missing or unusable would require contrary code or test evidence, which the audit did not find.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
Existing verification behavior and public signatures remain intact
Explanation (the auditor's whole response):
The merged diff changes verifier callers to use the new accessor names while continuing to parse and verify the same raw manifest bytes and footer version (`src/verify.rs:1510`, `src/verify.rs:1677`). The existing `verification_never_reads_the_archive_block` test remains present (`src/verify.rs:3382`), and the inspected diff showed no change to an existing public signature or verdict path. This preserves behavior the issue required to remain intact, so the audit found no regression to file.
Interpretation (the auditor's accepted statement):
The verifier changes use the new accessor names while retaining the same raw bytes and footer version, so this finding records preserved behavior.
Interpretation (the auditor's accepted statement):
Reading the change as a regression would require a changed public signature, verdict path, or archive read during verification; the audit found none.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
All six changed paths serve issue #131
Explanation (the auditor's whole response):
All six changed paths serve issue #131. `src/payload.rs:1806` contains the new reader API and `src/payload.rs:1012` the fixture writer; `src/payload/raw_block_tests.rs:329` and `tests/raw_container_blocks.rs:49` test their behavior; `src/verify.rs:1510` updates an internal caller; and `README.md:168`, `CHANGELOG.md:175`, and `CHANGELOG.md:183` document the additions. The audit found no changed path or change within those paths that went beyond the issue, so there is no extra change to file.
Interpretation (the auditor's accepted statement):
The six changed paths implement, test, adapt internal callers to, or document the requested API and fixture; this finding records changes within scope.
Interpretation (the auditor's accepted statement):
Calling any of those paths an extra change would require a specific change unrelated to issue #131, and the audit identified none.

Finding not filed — This finding did not meet the certainty bar for filing.
Finding (the auditor's accepted statement):
The full merge-commit CI matrix succeeded
Explanation (the auditor's whole response):
The merge-commit CI reread reported all six checks for PR #134 as completed successfully: CI, Markdown, both Platform checks, check, and test. That resolves the audit’s earlier evidence gap about the full CI matrix. It is a passing acceptance criterion, so there is no failure to file.
Interpretation (the auditor's accepted statement):
The supplied merge-commit CI reread shows all six checks completed successfully, so the CI acceptance criterion is verified.
Interpretation (the auditor's accepted statement):
Treating CI as an unresolved shortfall would rely on the earlier pending results and ignore the later completed results; the audit no longer has that evidence gap.