cadrumo.application.user_profile.capsule_restore module

Restore a profile from capsule material an operator can actually point at.

The restore door takes a password envelope, a DEK sentinel and the database bytes, and is right to: the capsule being restored is by definition not published, so nothing can load that material through the committed-capsule reader. But that also makes it uncallable from a command line, because a command line has a PATH and not three parsed custody records.

This module is the missing half. It reads an unpublished capsule directory – the shape an operator holds after copying buckets/<profile-id>/ out of a backup, or after a publication was interrupted – and hands the parsed material to the door that proves the key.

Recovery material is deliberately not publication cargo. A source directory may contain an enrolled recovery wrapper, while a restorative archive never does; a restore installs neither. The restored profile enrols recovery again explicitly if the operator wants it, which the restore outcome says out loud.

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

Bases: CadrumoError

Raised when a restore source is not a readable capsule.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
class ProfileCapsuleSource(password_envelope, sentinel, database_bytes)[source]

Bases: object

Everything a restore needs, parsed from one unpublished capsule.

Parameters:
password_envelope: ProfileCustodyEnvelopePort
sentinel: ProfileCustodySentinelPort
database_bytes: bytes
class ProfileRestoreOutcome(**data)[source]

Bases: BaseModel

Typed result of one completed restore.

Carries no key material: the identity, which door proved it, and whether the republished capsule still has a recovery route.

Parameters:

data (Any)

profile_id: ProfileId
label: str
authority: ProfileRestoreAuthority
recovery_enrolled: bool

a restore never installs recovery in the destination.

Type:

Always false

read_profile_capsule_source(source)[source]

Parse an unpublished capsule directory into restorable material.

Every member is parsed rather than merely read, so a torn or truncated file is refused here – before any publication is attempted – instead of surfacing as a decryption failure against a capsule that has already been committed.

Recovery is not read here. Its presence, absence, or health says nothing about whether this password/archive source is restorable.

Raises:

ProfileCapsuleSourceError – When a required member is missing or will not parse as the record it claims to be.

Return type:

ProfileCapsuleSource

Parameters:

source (Path)

restore_profile_capsule_with_password(*, label, capsule, password, root=None, profile_decode_context)[source]

Publish already-read capsule material under its own password.

This is the shared publication authority. A directory restore and an archive import differ only in how they OBTAIN a ProfileCapsuleSource; once they have one, both arrive here, so there is exactly one thing that knows how to turn capsule material into a published profile. Adding a second would be the fork this arrangement exists to prevent.

Return type:

ProfileRestoreOutcome

Parameters:
restore_profile_with_password(*, label, password, password_envelope, sentinel, database_bytes, root=None, profile_decode_context)[source]

Republish one capsule proving nothing but the profile’s own password.

Password-only is a structural claim, not a description of the usual case: no shared master key, no ambient provider, no recovery secret and no environment value participates. The password unwraps this capsule’s own envelope, the resulting key is proved against this capsule’s own committed sentinel, and only then is anything published.

The session is closed in every exit path, including the failing ones, so a refused restore leaves no live key material behind.

Return type:

CommittedProfileView

Parameters: