aeat.adapters.persistence.storage.errors module

Storage-layer exceptions.

All storage errors inherit from core.errors.AeatError so callers can catch domain-wide failures with a single base class.

The class tree:

  • StorageError — base for every storage error.

  • PersistenceError — base for the at-rest crypto, secret store, blob store, envelope, file lock, path containment, and audit-redaction surfaces. Subclass of StorageError so existing catchers continue to work.

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

Bases: AeatError

Base class for secure-storage failures.

This named base keeps the encrypted persistence, secret-store, bucket-session, and per-bucket lifecycle surfaces catchable as one family while still deriving from the central AEAT error registry.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception StorageError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecureStorageError

Base class for every error raised by adapters.persistence.storage.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RepositoryError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: StorageError

Raised when a repository operation fails (not-found, integrity, etc.).

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RepositorySetupError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: RepositoryError

Raised when a concrete repository subclass is missing a required class attribute.

Programming-contract guard: the attribute must be declared on the subclass before instantiation. Unlike a plain TypeError, this error is enrolled in the AEAT error registry so it produces a structured envelope rather than an opaque interpreter-level exception.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception SecureObjectRevisionConflictError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: RepositoryError

Raised when a revision-aware secure-object write sees a stale revision.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception PersistenceError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: StorageError

Base class for governed-persistence error subtypes.

Errors raised by the at-rest crypto primitives, the secret store, the encrypted blob store, the schema-version envelope, the file-lock helper, the path containment helper, and the audit-sink redaction contract all inherit from this class.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception StorageValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PersistenceError, ValueError

Raised when a storage parameter fails validation (e.g. key length).

Inherits from both PersistenceError and ValueError to remain compatible with Pydantic’s validator-failure contract while allowing catch-all StorageError handlers to detect integrity failures.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
storage_validation_error(message)[source]

Build a StorageValidationError carrying the shared integrity message key.

Single canonical factory for the storage-validation error that the persistence-storage submodules (crypto, envelope, runtime, secret store, and the master-key helpers) previously each declared identically.

Return type:

StorageValidationError

Parameters:

message (str)

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

Bases: PersistenceError

Base class for AEAD encryption / decryption failures.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception DecryptionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: EncryptionError

Raised when AEAD decryption fails (tag mismatch, malformed input).

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception SecureObjectUnreadableError(namespace, row_id, *, cause=None)[source]

Bases: DecryptionError

Raised when one stored secure object cannot be decrypted under the current master key.

Distinct from the generic DecryptionError so iterator-shaped consumers can surface a structured per-row failure (namespace, row id, underlying cause) without aborting the iteration. The plaintext bound to such a row is cryptographically unrecoverable from this process: the master key under which it was sealed is no longer available.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception KeyDerivationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: EncryptionError

Raised when a key-derivation step fails.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception NonceCollisionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: EncryptionError

Raised on a defensive nonce-uniqueness invariant violation.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception SecretStoreError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PersistenceError

Base class for secret-store I/O failures.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception SessionExpiredError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when the active BucketSession has crossed its idle deadline.

The session was opened earlier in the process lifetime but the operator did not act before the configured idle-lock window elapsed. The session is sealed; the operator must re-activate by running aeat config switch NAME (or a subsequent bootstrap-exempt verb that opens a fresh session).

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception PassphraseTooShortError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when an operator-supplied passphrase falls below the NIST floor.

NIST SP 800-63B §5.1.1.1 mandates that verifiers SHALL require user- chosen memorized secrets to be at least 8 characters in length. The FileFallbackMasterKeyProvider rejects shorter passphrases at resolution time.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception KeyringUnavailableError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when the OS keychain backend is unusable.

Either no backend is registered (e.g. headless Linux without libsecret), the backend rejected the operation, or the configured backend is the no-op null keyring.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception MasterKeyUnavailableError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when no master key can be acquired from any provider.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception MasterKeyKdfVersionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: MasterKeyUnavailableError

Raised when the on-disk master.kdf declares a KDF version this build cannot consume.

The substrate gates the master.kdf parameters by version. Mismatch means the operator’s passphrase may be correct, but the on-disk parameters do not match this build’s supported key-derivation contract.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception MasterKeyKeychainLockedError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: MasterKeyUnavailableError

Raised when the OS keychain is reachable but the entry is locked.

Distinct from KeyringUnavailableError (no usable backend at all). This class signals a recoverable state: the operator unlocks the OS keychain (Touch ID / Windows Hello / desktop-wallet unlock) and retries. The CLI’s error envelope renders the actionable hint.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception MasterKeyPassphraseMismatchError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: MasterKeyUnavailableError

Raised when the file-fallback passphrase does not unwrap master.key.

Recoverable by re-entering the passphrase. If the passphrase has been forgotten, the operator can use aeat config recover to re-mint the master key from a recovery-key backup. The CLI’s error envelope distinguishes this case from MasterKeyMaterialMissingError so retries do not waste backoff budget on missing-file errors.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception MasterKeyMaterialMissingError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: MasterKeyUnavailableError

Raised when no master-key material exists at all.

Neither the keyring entry nor the file-fallback artefacts (master.key / master.kdf / salt) are present. The substrate has not been provisioned. The operator’s actionable next step is aeat config profile create NAME or, if a recovery key is available, aeat config recover.

Raised by canonical read paths to distinguish “not provisioned” from “wrong passphrase” without minting key material. Explicit profile creation is responsible for provisioning; ordinary load paths fail closed with this class when material is absent.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception UnsecuredModeRefusedError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when the unsecured backend is requested without proper gating.

Two refusal classes:

  1. The unsecured backend was selected (aeat_secret_store_backend=unsecured) but the operator did not set AEAT_ALLOW_UNENCRYPTED=1. The hostile- named env var is the legible-and-embarrassing opt-out gate.

  2. The unsecured backend is active AND the operator profile carries a real NIF/NIE/CIF (NIF-canary). Real tax data is incompatible with a published deterministic master key; the substrate refuses to write such records into the unsecured store.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ClassificationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a record’s declared sensitivity class is incompatible with its repository.

Example: writing a CORPUS-class blob through the encrypted-blob path, or loading an envelope under a different classification than the one persisted on disk.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception EnvelopeVersionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PersistenceError

Raised when an on-disk envelope version differs from the consumer contract.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception PathContainmentError(message=None, *, context=None)[source]

Bases: PersistenceError, ValueError

Raised when a computed path escapes its configured root directory.

Parameters:

  • message (str | None)

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

Return type:

None

code: ClassVar[ErrorCode]
exception BlobNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a blob lookup misses on the encrypted blob store.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception BlobIntegrityError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a blob’s on-disk SHA-256 disagrees with its manifest.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception SecretNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when a secret-store get does not find a record for the requested key.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception SecretAlreadyExistsError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when a secret-store put would overwrite an existing key without overwrite=True.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RetentionPolicyError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a record’s retention metadata violates its classification policy.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception NamespaceRegistryError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: StorageError, ValueError

Raised when a namespace-registry key or definition violates a boot-time invariant.

Fires from Pydantic field and model validators on SecureObjectNamespaceDefinition, StoragePathDefinition, and StorageHierarchyRegistry when a registry key, namespace slug, path segment, or uniqueness constraint is violated at construction time. Inherits from StorageError and ultimately from AeatError so callers can catch it without importing Pydantic internals.

Because these validators are called by Pydantic during model construction the exception propagates wrapped inside a pydantic.ValidationError when raised from a field validator; direct callers of StorageHierarchyRegistry model validators receive the raw NamespaceRegistryError.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]