cadrumo.application.user_profile.login_session_port module

Typed application boundary for profile login-session infrastructure.

The login transaction owns ordering, rollback, and operator-facing outcomes. Persistence owns the live bucket session, throttle record, acceleration receipt, and key-buffer wipe. This module is the single dependency boundary between those responsibilities: it declares the exact structural DTOs the application observes and binds one concrete port for an explicit host lifetime.

class ProfileBucketSessionPort(*args, **kwargs)

Bases: Protocol

Live bucket-session capability exposed across the application boundary.

property bucket_id: str

The bucket this live session was opened against.

property dek: bytes

The session’s bound data-encryption key.

property idle_deadline: datetime

The sliding deadline the next activity advances.

property absolute_deadline: datetime

The immutable cap no activity can extend.

property opened_at: datetime

When this session was authenticated.

property sealed: bool

Whether this session has been closed and its key material zeroised.

touch(now)

Advance the sliding idle deadline.

Return type:

None

Parameters:

now (datetime)

is_expired(now)

Return whether this session has crossed either deadline.

Return type:

bool

Parameters:

now (datetime)

close()

Zeroise and retire this session’s local key material.

Return type:

None

class ProfilePersistedSessionPort(*args, **kwargs)

Bases: Protocol

Persisted acceleration-receipt fields needed by login orchestration.

property profile_id: UUID

The profile this receipt accelerates.

property session_id: UUID

The receipt’s own identity.

property custody_generation: int

The custody generation this receipt was minted against.

property dek_epoch: str

The DEK epoch this receipt was minted against.

property issued_at: datetime

When the receipt was minted.

property idle_deadline: datetime

The sliding deadline a resume may advance.

property absolute_deadline: datetime

The immutable cap no resume can extend.

class ProfileSessionResumeOutcomePort(*args, **kwargs)

Bases: Protocol

Fail-closed persisted-session evaluation result.

property resumed: bool

Whether the persisted receipt was accepted.

property refusal: ProfileSessionRefusalReason | None

The typed reason a resume was refused, if it was.

property record: ProfilePersistedSessionPort | None

The evaluated receipt, present whether or not it was accepted.

class ProfileLoginThrottleEvaluationPort(*args, **kwargs)

Bases: Protocol

Failed-login backoff decision exposed to the application.

property throttled: bool

Whether the caller must wait before another attempt.

property remaining_seconds: int

Seconds left on the current backoff window.

class ProfileLoginSessionPort(*args, **kwargs)

Bases: Protocol

Complete infrastructure capability used by the login-session aggregate.

Methods return the persistence substrate’s existing DTOs through structural protocols. The boundary never copies them: live-session identity is part of rollback and the exact receipt instance anchors idle-deadline renewal.

load_handover_journal(*, storage_root)

Load the durable profile-switch witness, if present.

Return type:

ProfileLoginHandoverJournal | None

Parameters:

storage_root (Path)

save_handover_journal(*, storage_root, journal)

Persist one monotonic profile-switch witness.

Return type:

None

Parameters:

• storage_root (Path)

• journal (ProfileLoginHandoverJournal)

clear_handover_journal(*, storage_root, journal)

Compare and clear the completed profile-switch witness.

Return type:

None

Parameters:

• storage_root (Path)

• journal (ProfileLoginHandoverJournal)

current_session()

Return the process-bound live session, if one exists.

Return type:

ProfileBucketSessionPort | None

open_resumed_session(*, bucket_id, dek, idle_minutes, opened_at, idle_deadline, absolute_deadline, storage_root)

Open one live session over the supplied authenticated DEK.

Return type:

ProfileBucketSessionPort

Parameters:

• bucket_id (str)

• dek (bytes)

• idle_minutes (int)

• opened_at (datetime)

• idle_deadline (datetime)

• absolute_deadline (datetime)

• storage_root (Path)

bind_session(session)

Bind one authenticated session to the process context.

Return type:

None

Parameters:

session (ProfileBucketSessionPort)

close_active_session()

Close and zeroise the process-bound live session.

Return type:

None

session_serves_bucket(session, bucket_id)

Return whether session serves the exact profile UUID.

Return type:

bool

Parameters:

• session (ProfileBucketSessionPort | None)

• bucket_id (str)

evaluate_throttle(*, storage_root, bucket_id, now)

Evaluate failed-login backoff before password derivation.

Return type:

ProfileLoginThrottleEvaluationPort

Parameters:

• storage_root (Path)

• bucket_id (str)

• now (datetime)

record_login_failure(*, storage_root, bucket_id, now)

Record one refused password proof without replacing its refusal.

Return type:

None

Parameters:

• storage_root (Path)

• bucket_id (str)

• now (datetime)

reset_throttle(*, storage_root, bucket_id)

Clear the revocable failed-login backoff cache.

Return type:

None

Parameters:

• storage_root (Path)

• bucket_id (str)

acceleration_receipt_path(*, storage_root, profile_id)

Return the exact local receipt locator for one profile.

Return type:

Path

Parameters:

• storage_root (Path)

• profile_id (UUID)

mint_acceleration_receipt(*, storage_root, profile_id, custody_generation, dek_epoch, dek, now, idle_minutes, absolute_minutes)

Mint and return the canonical persisted acceleration receipt.

Return type:

ProfilePersistedSessionPort

Parameters:

• storage_root (Path)

• profile_id (UUID)

• custody_generation (int)

• dek_epoch (str)

• dek (bytes)

• now (datetime)

• idle_minutes (int)

• absolute_minutes (int)

resume_acceleration_receipt(*, storage_root, profile_id, custody_generation, dek_epoch, now)

Evaluate one receipt and return its owned wipeable DEK buffer.

Return type:

tuple[ProfileSessionResumeOutcomePort, bytearray | None]

Parameters:

• storage_root (Path)

• profile_id (UUID)

• custody_generation (int)

• dek_epoch (str)

• now (datetime)

delete_acceleration_receipt(*, storage_root, profile_id)

Revoke one profile’s split-knowledge acceleration receipt.

Return type:

None

Parameters:

• storage_root (Path)

• profile_id (UUID)

advance_acceleration_idle_deadline(*, storage_root, profile_id, record, new_idle_deadline)

Advance a receipt while preserving its concrete DTO identity.

Return type:

ProfilePersistedSessionPort

Parameters:

• storage_root (Path)

• profile_id (UUID)

• record (ProfilePersistedSessionPort)

• new_idle_deadline (datetime)

is_persisted_receipt(record)

Narrow a resume record to the canonical persisted receipt DTO.

Return type:

TypeGuard[ProfilePersistedSessionPort]

Parameters:

record (object)

zeroise_owned_buffer(buffer)

Overwrite the exact mutable key buffer owned by the caller.

Return type:

None

Parameters:

buffer (bytearray)

bind_profile_login_session_port(port)

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

Return type:

Generator[ProfileLoginSessionPort]

Parameters:

port (ProfileLoginSessionPort)

profile_login_session_port()

Resolve the explicitly composed port for the current host context.

Return type:

ProfileLoginSessionPort

profile_session_serves_bucket(session, bucket_id)

Return whether a live bucket session serves the exact profile UUID.

Return type:

bool

Parameters:

• session (ProfileBucketSessionPort | None)

• bucket_id (str)

profile_current_bucket_session()

Observe the currently bound bucket session through the login-session port.

Return type:

ProfileBucketSessionPort | None