cadrumo.adapters.persistence.storage.custody.acceleration_receipt module¶

Profile acceleration receipt: cross-process custody of a wrapped bucket DEK.

This is NOT a session. It has no counterparty and no protocol: it is a locally held wrap of an already-unlocked DEK, carrying a deadline, that lets a later process skip the passphrase. The AEAT authority session – an encrypted row inside the bucket, revocable only with the key – is the artefact that owns the word “session” in this codebase, and conflating the two has produced a wrong architectural premise more than once. The “logged in” state minted by aeat config login survives across CLI processes as two split-knowledge artefacts, either of which is useless alone:

an ephemeral 32-byte session key held ONLY in the OS keychain under the service cadrumo:profile-session:v2 with the immutable profile UUID plus minted session UUID as account, and
an on-disk session.v2.json record in the separated profile keystore directory carrying the AES-256-GCM wrap of the bucket DEK under that session key, with EVERY metadata field (schema version, immutable profile UUID, random session UUID, custody generation, DEK epoch, issued_at, the sliding idle deadline, and immutable absolute deadline) bound as AEAD associated data.

A disk-only attacker sees ciphertext no more revealing than the already-persisted wrapped bucket.dek.json; a keychain-only attacker holds a random key with nothing to decrypt; altering any persisted deadline breaks the GCM tag. Resume evaluation is FAIL-CLOSED: an expired, tampered, version-mismatched, or keychain-orphaned record is deleted and refused with a typed ProfileSessionRefusalReason, never silently tolerated. No plaintext KEK, DEK, or session-key byte ever lands on disk.

Zeroisation honesty: the session key and DEK are held in bytearray buffers wiped through zeroise() on every exit path, but the AEAD primitives and the pydantic boundary require transient immutable bytes views whose lifetime the garbage collector owns — the same best-effort contract BucketSession documents for the live in-process buffers.

Keychain failures are normalised to KeyringUnavailableError on every path, including failures raised OUTSIDE the keyring library’s own exception hierarchy. A backend can pass the class-level usability probe and still fail at call time: the Windows credential store raises win32ctypes.pywin32.pywintypes.error (for example WinError 1312, “a specified logon session does not exist”) from a process whose logon session the credential manager cannot reach, and that type derives directly from Exception – it is neither a KeyringError nor an OSError, so a guard naming either lets it escape as a raw traceback. Normalising here is what makes the documented degradation reachable: no persisted artefact, a process-scoped login, and a warning to the operator. The error type is caught structurally rather than imported by name so this module carries no platform-specific import.