cadrumo.application.user_profile.custody_ports module

Typed application boundary for profile-custody infrastructure.

Application policy owns the neutral models and structural protocols declared here. Persistence owns bucket layout, custody records, cryptography, key material, and repository construction. An executable host binds that concrete infrastructure for its lifetime through the single aggregate port below.

class ProfileCustodyCommitPort(*args, **kwargs)[source]

Bases: Protocol

Publication identity exposed by one recognized profile capsule.

property transaction_id: UUID

The transaction that durably published this capsule.

property publication_kind: Literal[ProfilePublicationKind.ENROLL, ProfilePublicationKind.RESTORE]

Whether this capsule was enrolled locally or restored.

property published_at: str

The canonical UTC instant recorded by the publication marker.

class ProfileCustodyCapsuleLabelPort(*args, **kwargs)[source]

Bases: Protocol

Canonical label provenance exposed by physical custody storage.

property label: str

The normalized operator-facing profile label.

property label_revision: int

The revision of this label lineage.

property content_digest: str

The digest of the label payload excluding derived digests.

property self_digest: str

The digest authenticating the complete label record.

canonical_json_bytes()[source]

Return the canonical bytes committed into the capsule inventory.

Return type:

bytes

class ProfileCustodyCapsuleSummaryWitnessPort(*args, **kwargs)[source]

Bases: Protocol

One coherent, non-authenticating observation of a committed capsule.

The commit and the label were read under a single filesystem anchor and proved to name the same UUID, so a consumer may join them without re-opening either record and without entering custody at all.

property profile_id: UUID

The UUID proven independently by both observed records.

property commit: ProfileCustodyCommitPort

The recognized current publication marker.

property label: ProfileCustodyCapsuleLabelPort

The UUID-bound label provenance observed under the same anchor.

class ProfileCustodyLabelHeadPort(*args, **kwargs)[source]

Bases: Protocol

Authenticated head of one committed profile-label lineage.

property label_revision: int

The latest authenticated label revision.

property label_content_digest: str

The content digest of the latest authenticated label.

property label_self_digest: str

The self-digest of the latest authenticated label.

property self_digest: str

The self-digest authenticating this lineage head.

class ProfileCustodyPasswordMaterialPort(*args, **kwargs)[source]

Bases: Protocol

Normal-password material exposed by the custody read boundary.

Every record-shaped port here declares its fields read-only. The custody records these narrow are frozen, and a mutable protocol member is invariant, so a read-write declaration would make the real record unassignable to the very port that exists to narrow it. Read-only is also the truthful shape: the application observes committed custody state, it never writes back through the narrowed view.

property envelope: ProfileCustodyEnvelopePort

The committed password envelope for this profile.

property sentinel: ProfileCustodySentinelPort

The committed DEK sentinel proving an unwrap succeeded.

property capsule_path: Path

Where the recognized capsule this material was read from lives.

The application does not open custody files by path; the provider owns those reads. The path identifies the exact recognized capsule.

property commit: ProfileCustodyCommitPort

The capsule publication marker that authenticated this material.

class ProfileCustodyPasswordProofMaterialPort(*args, **kwargs)[source]

Bases: Protocol

Only the two records a password proof reads.

property envelope: ProfileCustodyEnvelopePort

The password envelope to unwrap.

property sentinel: ProfileCustodySentinelPort

The sentinel that proves the unwrapped DEK.

class ProfileCustodySecureObjectRawRowPort(*args, **kwargs)[source]

Bases: Protocol

Metadata and payload fields exposed by one secure-object row.

property namespace: str

The registered namespace this row was written under.

property object_key: bytes

The opaque digest addressing this row within its namespace.

property payload: bytes

The row’s stored ciphertext.

property revision_id: str | None

The row’s current CAS revision token.

property previous_revision_id: str | None

The revision this row replaced.

property payload_hash: str | None

The plaintext digest recorded at write time.

property ciphertext_hash: str | None

The ciphertext digest recorded at write time.

property write_provenance: str | None

The recorded origin of this row’s most recent write.

property source_event_id: str | None

The lifecycle event that produced this row, if any.

class ProfileCustodySecureObjectRecordPort(*args, **kwargs)[source]

Bases: Protocol

Decrypted secure-object payload and its CAS revision token.

property revision_id: str

The record’s current CAS revision token.

property payload: bytes

The decrypted record bytes.

class ProfileCustodySecureObjectRepositoryPort(*args, **kwargs)[source]

Bases: Protocol

The small encrypted-object surface needed by a profile capsule.

object_key_digest(object_key)[source]

Derive the repository’s stored lookup digest for one natural key.

Return type:

bytes

Parameters:

object_key (str | bytes)

iter_all_records_raw(*, namespace=None)[source]

Iterate rows without bypassing the repository’s integrity checks.

Return type:

Iterator[ProfileCustodySecureObjectRawRowPort]

Parameters:

namespace (str | None)

load(namespace, object_key, *, expected_class, max_supported_version)[source]

Load and decrypt one object under its registered namespace contract.

Core types: SensitivityClass.

Return type:

ProfileCustodySecureObjectRecordPort | None

Parameters:
apply_batch(writes)[source]

Commit an atomic set of encrypted-object writes.

Return type:

None

Parameters:

writes (tuple[SecureObjectWrite, ...])

class ProfileSnapshotPersistencePort(*args, **kwargs)[source]

Bases: Protocol

Encrypted persistence boundary for immutable filing-time snapshots.

exists(snapshot_id)[source]

Report whether one immutable snapshot row exists.

Return type:

bool

Parameters:

snapshot_id (str)

load(snapshot_id)[source]

Load and decode one snapshot, or report its absence.

Return type:

UserProfileSnapshot | None

Parameters:

snapshot_id (str)

save(snapshot)[source]

Encode and persist one immutable snapshot.

Return type:

None

Parameters:

snapshot (UserProfileSnapshot)

class ProfileCustodyEnvelopePort(*args, **kwargs)[source]

Bases: Protocol

Opaque password-envelope contract accepted by custody transactions.

profile_id: UUID
password_generation: int
self_digest: str
dek_epoch: str
canonical_json_bytes()[source]

Return the exact committed bytes of this envelope.

Declared because a rotation must name the envelope it believes it is replacing: the compare-and-swap witness is the digest of these bytes, and computing it from anything else would let a concurrent write slip between the read and the swap. The application still reads no field of the payload – it forwards the bytes and their digest, both opaque.

Return type:

bytes

class ProfileCustodySentinelPort(*args, **kwargs)[source]

Bases: Protocol

Opaque DEK-sentinel contract accepted by custody transactions.

profile_id: UUID
canonical_json_bytes()[source]

Return the exact committed bytes of this sentinel.

Declared for the same reason as the envelope’s: a backup carries the record verbatim, and the archive is built from bytes rather than from fields. The bytes cross the boundary; their MEANING does not. Nothing here reads a field of the payload, and the sentinel carries no plaintext secret to read in any case.

Return type:

bytes

class ProfileCustodyRecoveryEnvelopePort(*args, **kwargs)[source]

Bases: Protocol

Recovery-envelope contract forwarded to custody storage.

The two identity fields are declared because the application genuinely reads them: a recovery wrapper is only valid for the exact profile and DEK epoch it was minted against, and an enrollment that cannot be checked against the password envelope beside it is an enrollment nothing can prove belongs to this capsule. Everything else about the record – the KDF parameters, the wrapped key, the AAD descriptor – stays opaque, because the application has no business INTERPRETING key material.

“Interpreting” rather than “touching” is the precise line, and canonical_json_bytes() is why it has to be stated. A backup carries this record verbatim, so the application does handle the whole of it – wrapped key, KDF parameters and all – as an opaque run of bytes it forwards and digests without reading a field. What stays forbidden is deciding anything from the payload’s contents. A reader who sees that method sitting under this paragraph should conclude the two agree, not that one of them is stale.

profile_id: UUID
dek_epoch: str
canonical_json_bytes()[source]

Return the exact committed bytes of this recovery wrapper.

Return type:

bytes

class ProfileCustodyLocalRecordStore(*args, **kwargs)[source]

Bases: Protocol

The filesystem capabilities needed by custody-owner authorities.

ensure_directory(path)[source]

Create or validate one custody-owned directory.

Return type:

None

Parameters:

path (Path)

lock(path, *, timeout_seconds=30.0)[source]

Return the anchored local-record lock context.

Return type:

AbstractContextManager[None]

Parameters:
root_lock(root, *, timeout_seconds=30.0)[source]

Return the canonical profile-custody root lock context.

Return type:

AbstractContextManager[None]

Parameters:
read(path, *, maximum_bytes)[source]

Read one bounded, no-follow local record.

Return type:

bytes

Parameters:
read_optional(path, *, maximum_bytes)[source]

Read one bounded local record or prove its anchored absence.

Return type:

bytes | None

Parameters:
write(path, payload, *, publish_once)[source]

Atomically persist one local record.

Return type:

None

Parameters:
clear(path)[source]

Remove one anchored local record without following its leaf.

Return type:

None

Parameters:

path (Path)

compare_and_replace(path, *, expected, replacement, maximum_bytes)[source]

CAS-replace one local record without a separate app-layer read.

Return type:

None

Parameters:
compare_and_replace_same_or_predecessor(path, *, current, predecessor, maximum_bytes)[source]

Idempotently CAS one local record without an app-layer read.

Return type:

None

Parameters:
compare_and_clear(path, *, expected, maximum_bytes)[source]

CAS-clear one local record without a separate app-layer read.

Return type:

None

Parameters:
canonical_snapshot_payload(model)[source]

Return a snapshot’s canonical digest payload without its self-digest.

Return type:

dict[str, object]

Parameters:

model (BaseModel)

canonical_snapshot_bytes(model, *, maximum_bytes, subject)[source]

Encode one snapshot deterministically, enforcing its byte budget.

Return type:

bytes

Parameters:

  • model (BaseModel)

  • maximum_bytes (int)

  • subject (str)

canonical_snapshot_digest(model, *, maximum_bytes, subject)[source]

Digest the canonical snapshot fields that exclude self_digest.

Return type:

str

Parameters:

  • model (BaseModel)

  • maximum_bytes (int)

  • subject (str)

profile_custody_owner_root(root, owner)[source]

Return one canonical owner directory below profile-custody evidence.

Return type:

Path

Parameters:
ensure_profile_custody_owner_root(store, root)[source]

Create the anchored evidence hierarchy needed by one custody owner.

Return type:

None

Parameters:
default_profile_custody_local_record_store()[source]

Resolve the composed local-record store through the custody boundary.

Return type:

ProfileCustodyLocalRecordStore

exception ProfileRecordCryptoError(message=None, *, context=None, translated_message=None)[source]

Bases: CoreError

The configured profile-record crypto provider rejected an operation.

Roots at CoreError so the refusal binds to the error registry rather than reaching an operator as an unregistered builtin. The port deliberately does not root at the persistence layer’s own EncryptionError: this package exists to keep the adapter’s crypto types off the application port, and adopting that family would make the port’s refusal catchable by every storage-family handler — a broadening, not a re-root. RuntimeError is retained so the ancestry every existing caller was written against is unchanged.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ProfileCustodyRecordIntegrityError(message=None, *, context=None, translated_message=None)[source]

Bases: CoreError

The persistence provider refused a malformed or altered custody record.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ProfileCustodyConcurrentChangeError(message=None, *, context=None, translated_message=None)[source]

Bases: ProfileCustodyRecordIntegrityError

A capsule changed generation between two reads of one observation.

Narrower than its parent on purpose: the store is not damaged, the caller simply lost a race with a publication or a deletion. A listing that reports this is telling the operator to look again, not to repair.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class ProfileRecordEncryptedBlob(**data)[source]

Bases: BaseModel

Neutral encrypted-record shape exchanged across the application port.

Parameters:

data (Any)

nonce: bytes
ciphertext: bytes
to_wire()[source]

Serialise the blob as its canonical nonce-plus-ciphertext bytes.

Return type:

bytes

classmethod from_wire(payload)[source]

Parse the canonical wire representation without adapter imports.

Return type:

ProfileRecordEncryptedBlob

Parameters:

payload (bytes)

class ProfilePassphraseKdfPolicy(version, minimum_memory_cost_kib, maximum_memory_cost_kib, minimum_time_cost, maximum_time_cost, minimum_parallelism, maximum_parallelism, salt_bytes)[source]

Bases: object

Supported Argon2id version and window for passphrase-sealed records.

Parameters:

  • version (int)

  • minimum_memory_cost_kib (int)

  • maximum_memory_cost_kib (int)

  • minimum_time_cost (int)

  • maximum_time_cost (int)

  • minimum_parallelism (int)

  • maximum_parallelism (int)

  • salt_bytes (int)

version: int
minimum_memory_cost_kib: int
maximum_memory_cost_kib: int
minimum_time_cost: int
maximum_time_cost: int
minimum_parallelism: int
maximum_parallelism: int
salt_bytes: int
class ProfilePassphraseKdfParameters(version, memory_cost, time_cost, parallelism, salt)[source]

Bases: object

Persisted KDF parameters accompanying one passphrase-sealed record.

Parameters:
version: int
memory_cost: int
time_cost: int
parallelism: int
salt: bytes
class ProfilePassphraseEncryptedRecord(parameters, blob)[source]

Bases: object

Neutral KDF metadata and AEAD ciphertext minted by persistence.

Parameters:
parameters: ProfilePassphraseKdfParameters
blob: ProfileRecordEncryptedBlob
class ProfileRecordCryptoPort(*args, **kwargs)[source]

Bases: Protocol

AEAD and passphrase-sealing operations for profile-owned records.

passphrase_kdf_policy()[source]

Return the single supported Argon2id version and cost window.

Return type:

ProfilePassphraseKdfPolicy

passphrase_kdf_window_accepts(*, memory_cost, time_cost, parallelism, salt)[source]

Return whether persisted parameters satisfy the supported cost window.

Return type:

bool

Parameters:
encrypt_record(plaintext, *, key, associated_data=None)[source]

Encrypt one record using authenticated associated data.

Return type:

ProfileRecordEncryptedBlob

Parameters:
decrypt_record(blob, *, key, associated_data=None)[source]

Decrypt one record and verify its authenticated associated data.

Return type:

bytes

Parameters:
seal_with_passphrase(plaintext, *, passphrase, associated_data)[source]

Derive a fresh passphrase key and seal one record under it.

Return type:

ProfilePassphraseEncryptedRecord

Parameters:
open_with_passphrase(blob, *, passphrase, parameters, associated_data)[source]

Derive the persisted passphrase key and authenticate one record.

Return type:

bytes

Parameters:
class ProfileCustodyRegistrationMaterial(envelope, sentinel)[source]

Bases: object

The envelope and sentinel minted for one new profile.

Parameters:
envelope: ProfileCustodyEnvelopePort
sentinel: ProfileCustodySentinelPort
class ProfileCustodyRecordSessionMaterial(envelope, dek)[source]

Bases: object

The exact envelope and DEK already authenticated for one profile.

Parameters:
envelope: ProfileCustodyEnvelopePort
dek: bytes
class ProfileCustodyCapsuleSourceMaterial(password_envelope, sentinel, database_bytes)[source]

Bases: object

Parsed unpublished capsule members required by restore orchestration.

Parameters:
password_envelope: ProfileCustodyEnvelopePort
sentinel: ProfileCustodySentinelPort
database_bytes: bytes
class ProfileCapsuleArchiveHeaderMaterial(product, bucket_id, manifest_digest, archive_schema_version, created_at)[source]

Bases: object

Plaintext archive header fields observed by profile lifecycle policy.

Parameters:

  • product (str)

  • bucket_id (str)

  • manifest_digest (str)

  • archive_schema_version (int)

  • created_at (datetime)

product: str
bucket_id: str
manifest_digest: str
archive_schema_version: int
created_at: datetime
class ProfileCapsuleArchiveContentsMaterial(header, payload_bytes)[source]

Bases: object

Opaque sealed-container result supplied to profile archive policy.

Parameters:
header: ProfileCapsuleArchiveHeaderMaterial
payload_bytes: bytes
profile_capsule_archive_schema_version()[source]

Return the sealed-container schema version implemented by persistence.

Return type:

int

write_profile_capsule_archive_container(target, *, header, payload_bytes)[source]

Write an opaque profile payload through the sealed-container provider.

Return type:

None

Parameters:
read_profile_capsule_archive_container(source)[source]

Read an opaque profile payload through the sealed-container provider.

Return type:

ProfileCapsuleArchiveContentsMaterial

Parameters:

source (Path)

parse_profile_custody_capsule_members(*, envelope_bytes, sentinel_bytes, database_bytes)[source]

Parse archive-carried custody records through their persistence owner.

Return type:

ProfileCustodyCapsuleSourceMaterial

Parameters:
read_profile_custody_capsule_source(source)[source]

Read and parse one unpublished capsule through the custody provider.

Return type:

ProfileCustodyCapsuleSourceMaterial

Parameters:

source (Path)

class ProfileRecoveryKeyPort(*args, **kwargs)[source]

Bases: Protocol

Wipeable recovery secret held across the enrollment handoff.

property code: str

Return the canonical grouped recovery code.

wipe()[source]

Overwrite the key material owned by this container.

Return type:

None

class ProfileCustodyRecoveryEnrollmentMaterial(envelope, recovery_key)[source]

Bases: object

A minted recovery wrapper and the secret that opens it.

The secret is handed back in its wipeable container rather than as a str, because the operator holds it across an interactive confirmation and a string copy is unreachable by any wipe primitive for its whole lifetime. The caller owns the wipe.

Parameters:
envelope: ProfileCustodyRecoveryEnvelopePort
recovery_key: ProfileRecoveryKeyPort
class ProfileCustodyUnlockPort(*args, **kwargs)[source]

Bases: Protocol

A current-envelope DEK accepted only after the sentinel proof.

property profile_id: UUID

The profile whose envelope produced this key material.

property envelope_digest: str

The digest of the exact envelope that was unwrapped.

property dek: bytes

The authenticated data-encryption key.

class ProfileCustodyRecoveryUnlockPort(*args, **kwargs)[source]

Bases: Protocol

A DEK accepted through the explicit recovery-code door.

property profile_id: UUID

The profile whose recovery wrapper produced this key.

property dek_epoch: str

The DEK epoch bound into the proven artifact.

property recovery_digest: str

The digest of the exact recovery record that was proved.

property dek: bytes

The authenticated data-encryption key.

class ProfileCustodyRecoveryMaterialPort(*args, **kwargs)[source]

Bases: Protocol

The committed password custody of one capsule beside its enrolled recovery wrapper.

property capsule_path: Path

The committed capsule directory the material was read from.

property password_envelope: ProfileCustodyEnvelopePort

The committed password envelope, whose DEK epoch the wrapper must share.

property sentinel: ProfileCustodySentinelPort

The committed DEK sentinel the recovery proof is checked against.

property recovery_envelope: ProfileCustodyRecoveryEnvelopePort

The enrolled recovery wrapper.

class ProfileCustodySecureObjectNamespace(namespace, sensitivity, schema_version)[source]

Bases: object

Registered namespace contract needed by an application capsule.

Parameters:
namespace: str
sensitivity: SensitivityClass
schema_version: int
class ProfileCustodyCarryMaterial(carried_objects, carried_namespaces, excluded_namespaces, row_counts_by_namespace, unclassified_namespaces)[source]

Bases: object

Immutable persistence facts projected for one portable-profile carry.

Persistence resolves natural keys and registry custody dispositions. The application consumes only the carried domain rows plus exact coverage facts; it retains ownership of fail-closed export policy and manifest construction.

Parameters:
carried_objects: tuple[CarriedSecureObject, ...]
carried_namespaces: tuple[str, ...]
excluded_namespaces: tuple[str, ...]
row_counts_by_namespace: Mapping[str, int]
unclassified_namespaces: tuple[str, ...]
class ProfileCustodyBucketEventHistoryPort(*args, **kwargs)[source]

Bases: Protocol

Current bucket-event history authority for custody-bound operations.

exists()[source]

Return whether the encrypted event catalogue has been persisted.

Return type:

bool

load()[source]

Load the current bucket event catalogue.

Return type:

BucketEventHistoryCatalogue

save(catalogue)[source]

Persist one complete event catalogue through the active secure store.

Return type:

None

Parameters:

catalogue (BucketEventHistoryCatalogue)

load_revisioned()[source]

Load the catalogue together with its secure-object CAS revision.

Return type:

tuple[BucketEventHistoryCatalogue, str]

to_secure_object_write(catalogue, *, expected_revision_id=None)[source]

Prepare an atomic secure-object write for the catalogue.

Return type:

SecureObjectWrite

Parameters:
class ProfileBucketStoragePathsPort(*args, **kwargs)[source]

Bases: Protocol

Resolved filesystem paths for one profile bucket.

property bucket_dir: Path

The bucket’s own directory.

property db_dir: Path

The directory holding the bucket’s database.

property blobs_dir: Path

The directory holding the bucket’s content-addressed blobs.

property database_file: Path

The bucket’s encrypted database file.

property bucket_id: str

The bucket these paths were resolved for.

Declared because the lock refusals name it, which is what lets this narrowed view satisfy the bucket lock’s own target protocol directly. Without it the two lock delegations had to re-widen the port back to the concrete record through a runtime identity check – a check that stood in for exactly this declaration.

class ProfileBucketStoragePort(*args, **kwargs)[source]

Bases: Protocol

Bucket layout and lock operations exposed to application authorities.

resolve(root, bucket_id)[source]

Resolve one bucket’s paths without touching the filesystem.

Return type:

ProfileBucketStoragePathsPort

Parameters:
acquire_lock(paths, *, wait_seconds)[source]

Acquire the canonical lock for a bucket target.

Return type:

None

Parameters:
release_lock(paths)[source]

Release the canonical lock for a bucket target.

Return type:

None

Parameters:

paths (ProfileBucketStoragePathsPort)

class ProfileCustodyInventoryEntryPort(*args, **kwargs)[source]

Bases: Protocol

One non-secret capsule member observed by physical custody storage.

property size_bytes: int
class ProfileCustodyInventoryPort(*args, **kwargs)[source]

Bases: Protocol

Exact inventory shape consumed by application custody transactions.

property digest: str
property digest_entries: tuple[ProfileCustodyInventoryEntryPort, ...]
class ProfileCustodyPort(*args, **kwargs)[source]

Bases: Protocol

Complete persistence capability required by profile-custody policy.

local_record_store()[source]

Return the canonical anchored local-record store.

Return type:

ProfileCustodyLocalRecordStore

archive_schema_version()[source]

Return the current sealed-profile archive schema version.

Return type:

int

write_archive_container(target, *, header, payload_bytes)[source]

Write one opaque sealed profile archive.

Return type:

None

Parameters:
read_archive_container(source)[source]

Read one opaque sealed profile archive.

Return type:

ProfileCapsuleArchiveContentsMaterial

Parameters:

source (Path)

parse_capsule_members(*, envelope_bytes, sentinel_bytes, database_bytes)[source]

Parse archive-carried custody records through their owner.

Return type:

ProfileCustodyCapsuleSourceMaterial

Parameters:
read_capsule_source(source)[source]

Read and parse one unpublished capsule directory.

Return type:

ProfileCustodyCapsuleSourceMaterial

Parameters:

source (Path)

inventory_committed(profile_id, *, root=None)[source]

Observe the canonical committed-capsule inventory.

Return type:

ProfileCustodyInventoryPort

Parameters:
create_capsule_label(*, profile_id, label)[source]

Create the canonical initial label record for a new capsule.

Return type:

ProfileCustodyCapsuleLabelPort

Parameters:
staging_path(*, profile_id, transaction_id, root)[source]

Resolve the transaction-owned sibling staging path.

Return type:

Path

Parameters:
deletion_path(*, profile_id, transaction_id, root)[source]

Resolve the transaction-owned deletion tombstone path.

Return type:

Path

Parameters:
committed_capsule_path(profile_id, *, root)[source]

Return the recognized current-format capsule path when committed.

Return type:

Path | None

Parameters:
list_committed_profile_ids(*, root)[source]

List recognized current-format capsule identities.

Return type:

tuple[UUID, ...]

Parameters:

root (Path)

list_committed_capsule_summaries(*, root)[source]

Observe every current capsule’s commit and UUID-bound label once.

This is the pure listing route. It opens no envelope, derives no key, touches no session or keyring state, and never publishes or repairs a label head; a caller needing any of those must go through the owning custody operation instead.

Return type:

tuple[ProfileCustodyCapsuleSummaryWitnessPort, ...]

Parameters:

root (Path)

load_committed_capsule_label(profile_id, *, root)[source]

Load the authenticated label from one committed capsule.

Return type:

ProfileCustodyCapsuleLabelPort

Parameters:
verify_or_recover_initial_label_head(*, label, source_witness, root)[source]

Verify the label head or recover its initial committed witness.

Return type:

ProfileCustodyLabelHeadPort

Parameters:
load_staged_capsule_label(profile_id, transaction_id, *, root)[source]

Load the authenticated label from one transaction-owned stage.

Return type:

ProfileCustodyCapsuleLabelPort

Parameters:
stage_capsule(*, profile_id, transaction_id, publication_kind, password_envelope, sentinel, data_files, label_record, root, published_at, stage_initializer)[source]

Durably build, but do not publish, one transaction-owned capsule stage.

Return type:

Path

Parameters:
inventory_staged(*, profile_id, transaction_id, root)[source]

Observe the exact inventory of one transaction-owned stage.

Return type:

ProfileCustodyInventoryPort

Parameters:
publish_staged(*, profile_id, transaction_id, root)[source]

Atomically publish one verified transaction-owned stage.

Return type:

Path

Parameters:
write_deletion_marker(*, profile_id, transaction_id, inventory_digest, root)[source]

Bind one prepared deletion to its committed capsule.

Return type:

None

Parameters:

  • profile_id (UUID)

  • transaction_id (UUID)

  • inventory_digest (str)

  • root (Path)

verify_deletion_marker(*, profile_id, transaction_id, inventory_digest, root)[source]

Authenticate the prepared marker while its capsule remains current.

Return type:

None

Parameters:

  • profile_id (UUID)

  • transaction_id (UUID)

  • inventory_digest (str)

  • root (Path)

verify_deletion_tombstone(*, profile_id, transaction_id, inventory_digest, root)[source]

Authenticate the exact renamed capsule before local removal.

Return type:

None

Parameters:

  • profile_id (UUID)

  • transaction_id (UUID)

  • inventory_digest (str)

  • root (Path)

rename_capsule_for_deletion(*, profile_id, transaction_id, root)[source]

Atomically rename one marked capsule to its transaction tombstone.

Return type:

Path

Parameters:
remove_deletion_tombstone(*, profile_id, transaction_id, root)[source]

Remove only the transaction-owned, previously verified tombstone.

Return type:

None

Parameters:
bucket_storage()[source]

Return canonical bucket path and lock operations.

Return type:

ProfileBucketStoragePort

read_output_language_hint(*, storage_root, bucket_id)[source]

Read one bucket’s non-secret failure-rendering language hint.

Return type:

str | None

Parameters:

  • storage_root (Path)

  • bucket_id (str)

write_output_language_hint(*, storage_root, bucket_id, language)[source]

Mirror the profile’s language preference into the non-secret hint.

Returns False for an unsupported value, which never reaches disk.

Return type:

bool

Parameters:
clear_output_language_hint(*, storage_root, bucket_id)[source]

Remove the hint when the preference it mirrors is cleared.

Return type:

None

Parameters:

  • storage_root (Path)

  • bucket_id (str)

collect_profile_custody_carry(*, bucket_id, profile, profile_decode_context)[source]

Project portable rows and namespace coverage through persistence.

Return type:

ProfileCustodyCarryMaterial

Parameters:
profile_snapshot_persistence(bucket_id, *, object_key, objects=None, profile_decode_context)[source]

Return immutable profile-snapshot persistence for one bucket.

Return type:

ProfileSnapshotPersistencePort

Parameters:
record_crypto()[source]

Return the profile-record AEAD adapter.

Return type:

ProfileRecordCryptoPort

create_registration_material(*, profile_id, password, dek, dek_epoch, salt, password_generation)[source]

Mint a password envelope and its DEK sentinel.

Return type:

ProfileCustodyRegistrationMaterial

Parameters:
create_recovery_enrollment_material(*, profile_id, dek, dek_epoch, salt)[source]

Mint a recovery wrapper and its wipeable secret.

Return type:

ProfileCustodyRecoveryEnrollmentMaterial

Parameters:
install_recovery_envelope(*, profile_id, envelope, root)[source]

Exclusively install one recovery wrapper into a committed capsule.

Return type:

None

Parameters:
remove_recovery_envelope(*, profile_id, current, root)[source]

Compare-and-remove the enrolled recovery wrapper of a committed capsule.

Return type:

None

Parameters:
load_recovery_material(profile_id, *, root=None)[source]

Load the enrolled recovery wrapper beside its committed password custody.

Return type:

ProfileCustodyRecoveryMaterialPort

Parameters:
unlock_recovery(material, *, recovery_secret)[source]

Prove one enrolled recovery wrapper and return the authenticated DEK.

Return type:

ProfileCustodyRecoveryUnlockPort

Parameters:
verify_dek_against_sentinel(*, dek, profile_id, dek_epoch, sentinel)[source]

Prove that a DEK opens the exact profile sentinel.

Return type:

None

Parameters:
recovery_envelope_path(capsule_path)[source]

Return the current-format recovery-envelope path.

Return type:

Path

Parameters:

capsule_path (Path)

unlock_password(material, *, password)[source]

Authenticate one committed password envelope and sentinel.

Return type:

ProfileCustodyUnlockPort

Parameters:
replace_password_envelope(*, profile_id, current, rotated, root)[source]

CAS-replace exactly one committed password envelope.

Return type:

None

Parameters:
load_password_material(profile_id, *, root=None)[source]

Load the committed password proof material for one profile.

Return type:

ProfileCustodyPasswordMaterialPort

Parameters:
is_authentication_proof_failure(error, *, operation)[source]

Recognise a password or recovery proof refusal.

Return type:

bool

Parameters:
refuse_login_without_password_channel()[source]

Raise the canonical refusal for an absent password channel.

Return type:

NoReturn

is_keyring_unavailable(error)[source]

Recognise an unavailable keychain provider.

Return type:

bool

Parameters:

error (BaseException)

is_persistence_failure(error)[source]

Recognise a governed persistence failure without leaking adapter types.

Return type:

bool

Parameters:

error (BaseException)

secure_object_namespace()[source]

Return the registered current-profile value namespace.

Return type:

ProfileCustodySecureObjectNamespace

secure_object_repository(*, profile_id, dek, root, database_file=None)[source]

Open the canonical encrypted-object repository for one capsule.

Return type:

AbstractContextManager[ProfileCustodySecureObjectRepositoryPort]

Parameters:
bucket_event_history_repository(*, objects=None)[source]

Return the canonical encrypted bucket-event repository.

Return type:

ProfileCustodyBucketEventHistoryPort

Parameters:

objects (ProfileCustodySecureObjectRepositoryPort | None)

bind_profile_custody_port(port)[source]

Bind one outward-composed custody port for the host execution context.

Return type:

Generator[ProfileCustodyPort]

Parameters:

port (ProfileCustodyPort)

profile_custody_port()[source]

Resolve the explicitly composed custody port for the current host.

Return type:

ProfileCustodyPort

inventory_committed_profile_custody(profile_id, *, root=None)[source]

Observe one committed capsule through the custody persistence boundary.

Return type:

ProfileCustodyInventoryPort

Parameters:
read_profile_output_language_hint(*, storage_root, bucket_id)[source]

Read one bucket’s non-secret output-language hint through custody.

Return type:

str | None

Parameters:

  • storage_root (Path)

  • bucket_id (str)

write_profile_output_language_hint(*, storage_root, bucket_id, language)[source]

Write one bucket’s non-secret output-language hint through custody.

Return type:

bool

Parameters:
clear_profile_output_language_hint(*, storage_root, bucket_id)[source]

Remove one bucket’s non-secret output-language hint through custody.

Return type:

None

Parameters:

  • storage_root (Path)

  • bucket_id (str)

default_profile_record_crypto_port()[source]

Return the production crypto adapter through the application port.

Return type:

ProfileRecordCryptoPort

create_profile_custody_registration_material(*, profile_id, password, dek, dek_epoch, salt, password_generation=1)[source]

Mint the password envelope and DEK sentinel at the custody boundary.

password_generation defaults to the first, which is what creation wants. A rotation passes the successor: the same DEK and the same epoch re-wrapped under a new password, which is why this mint serves both doors instead of a rotation growing a parallel one.

Return type:

ProfileCustodyRegistrationMaterial

Parameters:
create_profile_recovery_enrollment_material(*, profile_id, dek, dek_epoch, salt)[source]

Mint a recovery wrapper and its code at the custody boundary.

The secret is a minted 150-bit recovery code rather than an operator-typed string: the wrapper’s only barrier once its bytes are read is the KDF cost applied to the secret’s entropy, and a human-chosen string does not survive offline guessing at any cost a login can afford to spend.

The recovery wrapper is calibrated against its OWN salt, independent of the password envelope’s. The two wrappers cover the same DEK through genuinely independent derivations, so compromising one KDF input cannot shorten an attack on the other.

Return type:

ProfileCustodyRecoveryEnrollmentMaterial

Parameters:
install_profile_recovery_envelope(*, profile_id, envelope, root)[source]

Exclusively install a minted recovery wrapper into a committed capsule.

Return type:

None

Parameters:
remove_profile_recovery_envelope(*, profile_id, current, root)[source]

Compare-and-remove the enrolled recovery wrapper through its owner.

Return type:

None

Parameters:
load_profile_custody_recovery_material(profile_id, *, root=None)[source]

Load the enrolled recovery wrapper beside committed password custody.

Return type:

ProfileCustodyRecoveryMaterialPort

Parameters:
unlock_profile_custody_recovery(material, *, recovery_secret)[source]

Prove the enrolled recovery wrapper against its committed sentinel.

This installs nothing and changes no key schedule. It returns the DEK the wrapper protects, proven against the capsule’s own sentinel, for the one door that consumes it: re-wrapping under a new passphrase.

Return type:

ProfileCustodyRecoveryUnlockPort

Parameters:
verify_profile_custody_dek_against_sentinel(*, dek, profile_id, dek_epoch, sentinel)[source]

Prove a key opens this exact profile before anything is published.

Return type:

None

Parameters:
profile_custody_recovery_envelope_path(capsule_path)[source]

Return where a committed capsule keeps its recovery wrapper when enrolled.

Return type:

Path

Parameters:

capsule_path (Path)

unlock_profile_custody_password(material, *, password)[source]

Authenticate one committed profile through its password envelope.

This is the normal-login authority: the adapter runs the bounded supervised KDF and proves the resulting DEK against the committed sentinel before it returns any key material. It intentionally accepts material already loaded from the exact target capsule, so a caller cannot resolve one profile and unwrap another through ambient state.

Return type:

ProfileCustodyUnlockPort

Parameters:
replace_profile_custody_password_envelope(*, profile_id, current, rotated, root)[source]

CAS-replace exactly one committed password envelope through its owner.

Return type:

None

Parameters:
load_profile_custody_password_material(profile_id, *, root=None)[source]

Load committed password proof material through the custody boundary.

Return type:

ProfileCustodyPasswordMaterialPort

Parameters:
map_profile_authentication_proof_failure(error, *, operation)[source]

Collapse credential shape and proof failures for one named capability.

Return type:

ProfileAuthenticationRefusedError | None

Parameters:
refuse_profile_login_without_password_channel()[source]

Raise the current custody refusal for an absent explicit password channel.

Return type:

NoReturn

profile_custody_record_session_material(profile_id, *, root=None)[source]

Return record material only when the live session serves this profile and can still decrypt.

A session is sealed in place on logout: it keeps naming its bucket while its key is zeroised, so serving the bucket alone does not make it usable. A sealed session is therefore no session, and the caller sees the ordinary not-logged-in absence instead of a locked-bucket failure.

Return type:

ProfileCustodyRecordSessionMaterial | None

Parameters:
profile_is_keyring_unavailable(error)[source]

Recognise a keychain persistence refusal for the process-scoped fallback.

Return type:

bool

Parameters:

error (BaseException)

profile_is_persistence_failure(error)[source]

Recognise the storage failure family through the composed custody port.

Return type:

bool

Parameters:

error (BaseException)

profile_custody_secure_object_namespace()[source]

Resolve the registered current-profile value namespace at the app boundary.

Return type:

ProfileCustodySecureObjectNamespace

profile_custody_secure_object_repository(*, profile_id, dek, root, database_file=None)[source]

Open the canonical encrypted-object repository for one profile capsule.

The provider owns the persistence/runtime imports and the short-lived staging session needed before a capsule has been published. Application authorities consume only this narrow repository port.

Return type:

AbstractContextManager[ProfileCustodySecureObjectRepositoryPort]

Parameters:
default_profile_bucket_event_history_repository(*, objects=None)[source]

Resolve the encrypted bucket-event repository at the app boundary.

Return type:

ProfileCustodyBucketEventHistoryPort

Parameters:

objects (ProfileCustodySecureObjectRepositoryPort | None)