aeat.application.auth._certificate_secret_backend module

Certificate-secret backend abstraction for named certificate sources.

Before this module, the certificate auth provider’s passphrase came from exactly one place: the env-only, never-persisted aeat_certificate_password_secret. That is a single global secret shared by whichever certificate happens to be active — it cannot express “the personal certificate uses passphrase A, the apoderado-acme certificate uses passphrase B” once _certificate_sources lets an operator register several named PKCS#12 sources with potentially different passphrases.

CertificateSecretBackend is the typed seam a per-source secret is read and written through. Two backends are provided:

  • SecureStorageCertificateSecretBackend (the default) persists the secret through the profile’s own encrypted SecretStore, at SECRET sensitivity (ciphertext at rest, per sensitive-financial-data-secure-storage-only). It requires no optional dependency and is scoped by the natural key to the active bucket, so two profiles never see each other’s secrets.

  • KeyringCertificateSecretBackend persists the secret in the OS keychain via the same KeyringClient seam KeyringMasterKeyProvider already uses, so a keychain-preferring operator keeps the certificate passphrase off the encrypted-file substrate entirely. keyring is already a project dependency (see pyproject.toml); this backend is therefore available today, not a scoped follow-up.

Never store a resolved secret in AuthState or any other persisted workflow-state record — the secret lives ONLY inside the backend; workflow state at most records which named sources exist, never their passphrases (sensitive-financial-data-secure-storage-only).

See also

_certificate_sources

Named certificate-source registry (path only, no secret) this module’s backend complements.

SecretStore

Encrypted substrate the default backend persists through.

SensitivityClass

Storage classification policy used by the secure-storage backend for certificate passphrases.

KeyringClient

Injection seam for the OS-keychain operations the keyring backend depends on; mirrored here rather than imported directly so this module does not reach into the master-key package’s internals.

class CertificateSecretBackendKind(*values)[source]

Bases: StrEnum

Closed set of certificate-secret backends a named source may use.

SECURE_STORAGE
KEYRING
exception CertificateSecretNotFoundError[source]

Bases: Exception

Raised when no secret is registered for a certificate source.

exception CertificateSecretBackendUnavailableError[source]

Bases: Exception

Raised when the selected backend cannot currently store or retrieve a secret.

class CertificateSecretBackend(*args, **kwargs)[source]

Bases: Protocol

Typed seam for reading, writing, and removing a named certificate secret.

Every method is keyed by the certificate source’s registered name (see name), scoping the secret to that one source. Implementations MUST scope storage to the active profile bucket so two profiles never share a namespace.

get(name)[source]

Return the persisted passphrase for source name, or None when absent.

Return type:

SecretStr | None

Parameters:

name (str)

set(name, secret)[source]

Persist secret for source name, overwriting any prior value (rotation).

Return type:

None

Parameters:

  • name (str)

  • secret (SecretStr)

remove(name)[source]

Remove the persisted secret for source name.

Return type:

bool

Returns:

True when a secret was removed, False when none was registered (a no-op, not an error).

Parameters:

name (str)

class SecureStorageCertificateSecretBackend(*, bucket_id, store=None)[source]

Bases: object

Default CertificateSecretBackend backed by storage.

Persists each certificate passphrase as a SecretRecord at SECRET sensitivity, scoped to bucket_id via the natural key. Requires no optional dependency; this is the backend every profile gets without further configuration.

Parameters:
get(name)[source]

Return the persisted passphrase for name, or None when absent.

Return type:

SecretStr | None

Parameters:

name (str)

set(name, secret)[source]

Persist (or rotate) the passphrase for name.

Return type:

None

Parameters:

  • name (str)

  • secret (SecretStr)

remove(name)[source]

Remove the persisted passphrase for name; a no-op when absent.

Return type:

bool

Parameters:

name (str)

class KeyringCertificateSecretBackend(*, bucket_id)[source]

Bases: object

CertificateSecretBackend backed by keyring.

Mirrors KeyringMasterKeyProvider: the active backend is probed before any read or write so the no-op fail.Keyring / null.Keyring placeholders raise CertificateSecretBackendUnavailableError rather than silently dropping the secret. Every account is f"{bucket_id}:{name}" under one service string, so profiles and sources never collide in the OS keychain namespace.

Parameters:

bucket_id (str)

get(name)[source]

Return the persisted passphrase for name, or None when absent.

Return type:

SecretStr | None

Parameters:

name (str)

set(name, secret)[source]

Persist (or rotate) the passphrase for name.

Return type:

None

Parameters:

  • name (str)

  • secret (SecretStr)

remove(name)[source]

Remove the persisted passphrase for name; a no-op when absent.

Return type:

bool

Parameters:

name (str)

certificate_secret_backend(*, bucket_id, kind=CertificateSecretBackendKind.SECURE_STORAGE)[source]

Return the CertificateSecretBackend for kind.

SECURE_STORAGE is the default and requires no optional dependency; KEYRING requires a usable OS keychain backend and raises CertificateSecretBackendUnavailableError (via the backend’s own probe) when none is available. The returned backend is scoped to bucket_id.

Return type:

CertificateSecretBackend

Parameters: