cadrumo.adapters.persistence.storage.sql._secure_object_integrity module

Decryptability diagnostics for SQL secure-object persistence.

The three operations here – quarantine, namespace counting, and per-row enumeration – differ in what they DO with an undecryptable row (move it, count it, describe it) but agree exactly on how they DECIDE one: probe_row_decryptability() is that single decision. Keeping it in one place means an AAD change or a new decryption-failure mode cannot be applied to two of the three surfaces and missed on the third.

class RowDecryptability(object_key, payload, readable, reason)

Bases: NamedTuple

Whether one stored row decrypts, with the bytes the caller needs to act.

object_key and payload are the normalised wire bytes: callers that quarantine a row re-insert exactly these, so the row that moves is the row that was probed. reason carries the decryption failure text and is None when readable is True.

Parameters:

• object_key (bytes)

• payload (bytes)

• readable (bool)

• reason (str | None)

object_key: bytes

Alias for field number 0

payload: bytes

Alias for field number 1

readable: bool

Alias for field number 2

reason: str | None

Alias for field number 3

probe_row_decryptability(raw, *, namespace)

Decide whether one secure-object row decrypts under the current master key.

The single decryptability decision behind quarantine, namespace counting, and per-row enumeration. Normalises the row’s bytes through database_bytes() (SQLite returns bytes, memoryview, or str depending on the driver and query form), rebuilds the row-identity AAD, and attempts the AEAD open.

Only DecryptionError is treated as “unreadable”: a row whose bytes are structurally impossible to normalise is a programming or schema fault and propagates.

Return type:

RowDecryptability

Parameters:

• raw (object)

• namespace (str)

quarantine_unreadable_rows(engine, *, logger)

Move every undecryptable row into secure_objects_quarantine.

Returns a tuple of SecureObjectNamespaceIntegrity records, one per namespace.

Return type:

tuple[SecureObjectNamespaceIntegrity, ...]

Parameters:

• engine (Engine)

• logger (Logger)

probe_namespace_integrity(engine, namespace, *, logger)

Count decryptable and undecryptable rows in namespace.

Returns a SecureObjectNamespaceIntegrity for the given namespace.

Return type:

SecureObjectNamespaceIntegrity

Parameters:

• engine (Engine)

• namespace (str)

• logger (Logger)

iter_namespace_decryptability(engine, namespace)

Yield SecureObjectDecryptabilityRow records for one namespace.

Return type:

Iterator[SecureObjectDecryptabilityRow]

Parameters:

• engine (Engine)

• namespace (str)