cadrumo.adapters.persistence.storage.custody._capsule_data module

Bounded capsule data-tree writes and password-authority reads.

write_data_files(data_root, data_files)[source]

Write one bounded portable data tree without following links.

Return type:

None

Parameters:
validated_data_path(value)[source]

Return value as a relative capsule path, or refuse it.

“Portable” is the whole contract: the value is parsed as POSIX because that is the capsule’s on-wire spelling, but it is JOINED onto a staging root on whatever platform is running – and a drive-qualified value means something different to the two. "C:/x" is an ordinary two-component relative path to PurePosixPath, so it is neither absolute nor dotted and clears the checks below; joined on Windows it discards the staging root entirely and resolves to C:x. "C:x" is worse, resolving against the process’s current directory on that drive.

So the POSIX reading alone cannot decide this, and the Windows reading is the one that matters at the join. Both are consulted.

The empty-parts check is not redundant with the component check below it. PurePosixPath normalises a lone . away, so "." and "./" parse to NO components at all – the {"", ".", ".."} membership test never sees the value it names, and the path resolves to the staging root itself, which is a directory rather than a file to write.

Return type:

PurePosixPath

Parameters:

value (str)

validate_data_file_inventory(data_files)[source]
Return type:

None

Parameters:

data_files (Mapping[str, bytes])

read_password_envelope(path, *, trace)[source]
Return type:

ProfileCustodyEnvelope

Parameters:
read_password_envelope_fd(parent_fd, *, display_path, trace)[source]
Return type:

ProfileCustodyEnvelope

Parameters:
read_sentinel(path, *, trace)[source]
Return type:

ProfileCustodySentinelRecord

Parameters:
read_sentinel_fd(parent_fd, *, display_path, trace)[source]
Return type:

ProfileCustodySentinelRecord

Parameters:
write_posix_data_files(data_fd, data_files)[source]
Return type:

None

Parameters:
replace_capsule_file(directory, filename, payload, *, expected_sha256, maximum_bytes)[source]

Compare-and-swap one already-present regular file inside a committed capsule.

The single writer for every in-place capsule replacement, so the members of a published capsule cannot come to be mutated by two write paths with different guarantees. Callers hold their capsule lifecycle lock, anchor the directory’s identity, and supply the digest of the exact authenticated bytes their command read.

The digest is a compare-and-swap witness rather than a checksum: if the current bytes are not the ones the caller authenticated, the mutation is refused outright rather than overwriting a concurrent writer’s work. The publication is a same-directory rename over a temporary the writer created exclusively, then a directory fsync – so a crash leaves either the old member or the new one, never a torn file.

Parameters:

  • directory (Path) – The already-anchored directory holding the member.

  • filename (str) – The member’s name within directory. One component; path traversal is the caller’s grammar to validate before arriving here.

  • payload (bytes) – The replacement bytes.

  • expected_sha256 (str) – Prefixed digest of the bytes being replaced.

  • maximum_bytes (int) – The member’s own bounded-read ceiling.

Raises:

ProfileCustodyRecordError – When the witness is stale or the replacement cannot be published.

Return type:

None