aeat.adapters.persistence.storage.bucket._sealed_archive_reader module

Sealed bucket-export archive reader.

Validates the gzipped tar layout, strict-parses the header, and yields the encrypted payload bytes + optional recovery-wrap bytes for the caller to decrypt. Fast-fails on layout drift (extra, missing, out-of-order, or unknown members) before any decryption attempt so a tampered or wrong-version archive surfaces precisely.

Authority: 2026-06-03-bucket-sealed-archive-adr.

class SealedArchiveContents(header, payload_envelope_bytes, recovery_wrap_bytes)[source]

Bases: object

Decoded sealed-archive contents ready for downstream decryption.

The reader returns this aggregate so the caller composes its own decryption + validation pipeline without re-parsing the archive. payload_envelope_bytes is opaque to this layer — the caller deserialises it via the existing Envelope pipeline.

Parameters:
header: ExportArchiveHeader
payload_envelope_bytes: bytes
recovery_wrap_bytes: bytes | None
read_sealed_archive(source_path)[source]

Read and strict-validate a sealed bucket-export archive.

Parameters:

source_path (Path) – Operator-specified input path.

Return type:

SealedArchiveContents

Returns:

A SealedArchiveContents carrying the parsed header, the encrypted payload bytes, and the optional recovery-wrap bytes when header.recovery_wrap_present is True.

Raises:

  • SealedArchiveLayoutError – When the tar layout deviates from the ADR contract (extra / missing / out-of-order / unknown members, non-regular members).

  • SealedArchiveHeaderError – When header.json fails strict validation as ExportArchiveHeader.

  • SealedArchivePayloadError – When the payload member cannot be read, or when a torn write truncated the gzip stream so the decompression layer raises EOFError / gzip.BadGzipFile. Decryption failures surface from this same class when the caller’s Envelope parse fails.

Truncation-detection scope: a torn write that damages the gzip stream (the common case) is caught here at read time and surfaces as SealedArchivePayloadError. A near-complete truncation that still decompresses to the expected two or three members passes this reader; it is caught downstream by the AEAD tag on the encrypted payload, which the importer verifies before it provisions any bucket store, so a torn archive never restores a partial bucket. Read-time detection of a near-complete truncation would require a trailing integrity marker in the archive format (writer + reader change); that hardening is a tracked follow-up recorded in the crash-window reference.