cadrumo.adapters.persistence.storage.bucket.sealed_archive_writer module

Sealed bucket-export archive writer.

Writes a gzipped tar archive carrying the plaintext ExportArchiveHeader followed by the encrypted payload bytes. The layout is fixed at exactly those two members: there is no optional member, so the archive’s shape is a constant rather than something the header negotiates. Metadata for every tar member is normalised at write time (timestamps pinned to the header’s created_at, mode pinned to 0o400, ownership cleared) so two same-bucket exports differ only in the header’s created_at field.

SEALED_ARCHIVE_MEMBER_NAMES

The archive’s members, in the one order the reader accepts.

write_sealed_archive(target_path, *, header, payload_bytes)[source]

Write the sealed archive at target_path.

Parameters:

  • target_path (Path) – Operator-specified output path. Must be writable and must not exist (the writer refuses to overwrite a sealed archive to avoid accidental clobber; remove the file first if a re-export is intended).

  • header (ExportArchiveHeader) – Strict-validated ExportArchiveHeader. The writer serialises it to UTF-8 JSON as the first archive member.

  • payload_bytes (bytes) –

    The sealed payload, OPAQUE to this writer. It is written byte-for-byte as the second and last archive member and is never parsed, validated or interpreted here.

    This deliberately does NOT require an Envelope, and said so once by mistake. The archive is a transport: its guarantee is verbatim carriage, and binding it to one payload type would couple the transport to whichever caller happened to be first. Parsing here would be worse than useless – it would let the transport REFUSE a sealed payload it could not understand, which for encrypted material is a liability rather than a safeguard.

    Opaque is not unconstrained. Empty is refused below, because an empty payload yields a structurally valid archive carrying nothing to decrypt. Beyond that the caller owns the payload’s shape, its decryption, and its integrity: this layer verifies no digest, including the header’s manifest_digest, which it carries rather than checks.

Raises:

SealedArchiveWriteError – When target_path carries the wrong suffix, already exists, payload_bytes is empty, or the underlying IO write fails.

Return type:

None