cadrumo.adapters.persistence.storage.custody.kdf_supervision module

Supervised Argon2id work for current-format profile custody.

class ProfileCustodyKdfResources(available_memory_bytes, cpu_count)

Bases: object

Explicit local resources used to decide whether one grid point is safe.

Parameters:

• available_memory_bytes (int)

• cpu_count (int)

available_memory_bytes: int

cpu_count: int

class ProfileCustodyKdfCalibration(version, parameters, source, median_seconds)

Bases: object

Versioned result of deterministic finite-grid enrollment calibration.

Parameters:

• version (Literal[1])

• parameters (ProfileCustodyKdfParameters)

• source (Literal['measured', 'fallback'])

• median_seconds (float | None)

version: Literal[1]

parameters: ProfileCustodyKdfParameters

source: Literal['measured', 'fallback']

median_seconds: float | None

class ProfileCustodyUnlock(profile_id, envelope_digest, kdf, dek)

Bases: object

A DEK accepted only after a parent-owned sentinel proof.

Parameters:

• profile_id (UUID)

• envelope_digest (str)

• kdf (ProfileCustodyKdfParameters)

• dek (bytes)

profile_id: UUID

envelope_digest: str

kdf: ProfileCustodyKdfParameters

dek: bytes

profile_password_wrap_aad(*, profile_id, password_generation, dek_epoch, kdf)

Build the canonical password-wrap AAD for one current custody envelope.

Return type:

bytes

Parameters:

• profile_id (UUID)

• password_generation (int)

• dek_epoch (str)

• kdf (ProfileCustodyKdfParameters)

profile_kdf_grid(*, salt)

Return the complete deterministic Argon2id v1 grid, strongest first.

Return type:

tuple[ProfileCustodyKdfParameters, ...]

Parameters:

salt (bytes)

fixed_profile_kdf_fallback(*, salt)

Return the sole eligible fallback point without weakening its parameters.

Return type:

ProfileCustodyKdfParameters

Parameters:

salt (bytes)

profile_kdf_resources()

Read the portable resources that bound a local KDF worker.

Return type:

ProfileCustodyKdfResources

profile_kdf_is_eligible(parameters, *, resources)

Return whether one finite-grid point fits the explicit local envelope.

Return type:

bool

Parameters:

• parameters (ProfileCustodyKdfParameters)

• resources (ProfileCustodyKdfResources)

calibrate_profile_kdf(*, salt, settings=None)

Calibrate a fresh profile KDF with bounded real child-process samples.

Return type:

ProfileCustodyKdfCalibration

Parameters:

• salt (bytes)

• settings (Settings | None)

unlock_profile_custody(envelope, password, *, sentinel, settings=None, timeout_seconds=15.0)

Return a DEK only after supervised unwrap and parent sentinel proof.

Return type:

ProfileCustodyUnlock

Parameters:

• envelope (ProfileCustodyEnvelope)

• password (str)

• sentinel (ProfileCustodySentinelRecord)

• settings (Settings | None)

• timeout_seconds (float)

unlock_profile_custody_password_material(*, profile_id, dek_epoch, kdf, wrapped_dek, secret, associated_data, sentinel, settings=None, timeout_seconds=15.0)

Supervise one current-format wrapper unwrap and prove its immutable DEK.

The caller owns one closed wrapper AAD domain. This adapter owns password representation, process supervision, and the non-optional capsule proof. It never returns an unproved key.

Return type:

bytes

Parameters:

• profile_id (UUID)

• dek_epoch (str)

• kdf (ProfileCustodyKdfParameters)

• wrapped_dek (ProfileCustodyWrappedDek)

• secret (str)

• associated_data (bytes)

• sentinel (ProfileCustodySentinelRecord)

• settings (Settings | None)

• timeout_seconds (float)

wrap_profile_custody_password_material(*, secret, dek, kdf, associated_data, settings=None, timeout_seconds=15.0)

Build one wrapper only inside the existing supervised KDF boundary.

Return type:

ProfileCustodyWrappedDek

Parameters:

• secret (str)

• dek (bytes)

• kdf (ProfileCustodyKdfParameters)

• associated_data (bytes)

• settings (Settings | None)

• timeout_seconds (float)

unlock_profile_custody_recovery_material(*, profile_id, dek_epoch, kdf, wrapped_dek, secret, associated_data, sentinel, settings=None, timeout_seconds=15.0)

Unlock the DEK using the recovery secret, inside the same supervised KDF boundary.

The recovery-path sibling of the password unlock above it: same supervised worker and lease, but authenticated against the recovery secret rather than the login password, so a wrong recovery secret raises ProfileCustodyRecoverySecretError rather than the password error a caller further up must distinguish.

Return type:

bytes

Parameters:

• profile_id (UUID)

• dek_epoch (str)

• kdf (ProfileCustodyKdfParameters)

• wrapped_dek (ProfileCustodyWrappedDek)

• secret (str)

• associated_data (bytes)

• sentinel (ProfileCustodySentinelRecord)

• settings (Settings | None)

• timeout_seconds (float)

wrap_profile_custody_recovery_material(*, secret, dek, kdf, associated_data, settings=None, timeout_seconds=15.0)

Wrap the DEK under the recovery secret, inside the same supervised KDF boundary.

The recovery-path sibling of the password wrap above it — same supervised worker and lease, but the resulting wrapper is unlocked later by unlock_profile_custody_recovery_material() with the recovery secret, never the login password.

Return type:

ProfileCustodyWrappedDek

Parameters:

• secret (str)

• dek (bytes)

• kdf (ProfileCustodyKdfParameters)

• associated_data (bytes)

• settings (Settings | None)

• timeout_seconds (float)

profile_kdf_lease(*, deadline, settings=None)

Acquire the one OS-released KDF permit for a canonical installation root.

The descriptor stays open for the operation, so an abnormal owner death releases its permit at the operating-system boundary instead of leaving a process-local or persistent ownership record behind.

Return type:

Generator[None]

Parameters:

• deadline (float)

• settings (Settings | None)