aeat.application.auth._apoderado module

Apoderado application service.

Operator verbs:

status

Read-only summary of the active apoderado configuration.

configure

Set --represented-nif NIF --scope SCOPE (repeated).

clear

Retire the apoderado configuration for the active bucket.

check

Live verification of the stored apoderamiento against the AEAT sede. The live-read path is not wired, so this verb refuses with ApoderadoLiveCheckUnavailableError; use status for the offline configuration read.

Configuration is persisted per-bucket as an encrypted adapters.persistence.storage.Envelope row in the adapters.persistence.storage.SecureObjectRepository under adapters.persistence.storage.AUTH_APODERADO_CONFIGURATION_NAMESPACE. The represented_nif is an identity-bearing tax identifier, so the record carries adapters.persistence.storage.SensitivityClass IDENTITY and is encrypted at rest; the service never writes plaintext to disk. Live mutation of AEAT-side apoderamiento state (registrar, ampliar, revocar, confirmar, renunciar, presentar-en-representacion) is permanently refused at this boundary; the service has no verb that would write to AEAT.

exception ApoderadoConfigurationNotSetError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised when status or check runs without a configured apoderado.

Parameters:

• message (str | None)

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

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception ApoderadoLiveCheckUnavailableError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised when the live-read path is not yet wired or AEAT contact fails.

Parameters:

• message (str | None)

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

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

class ApoderadoConfiguration(**data)

Bases: BaseModel

Persisted apoderado configuration for one bucket.

Parameters:

• bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

• represented_nif (str)

• granted_scopes (tuple[str, ...])

• catalogue_version (str)

• configured_at (datetime)

• notes (str)

bucket_id: BucketId

represented_nif: str

granted_scopes: tuple[str, ...]

catalogue_version: str

configured_at: datetime

notes: str

class ApoderadoStatus(**data)

Bases: BaseModel

Read-only status surface returned by apoderado status.

Parameters:

• bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

• configured (bool)

• represented_nif (str | None)

• granted_scopes (tuple[str, ...])

• catalogue_version (str | None)

• configured_at (datetime | None)

bucket_id: BucketId

configured: bool

represented_nif: str | None

granted_scopes: tuple[str, ...]

catalogue_version: str | None

configured_at: datetime | None

class ApoderadoService(settings=None, catalogue=None)

Bases: object

Local apoderado configuration management.

Live AEAT mutation is permanently refused at this boundary. check performs read-only verification only; the actual remote contact is a sealed extension point.

Parameters:

• settings (Settings | None)

• catalogue (ApoderamientosCatalogue | None)

property catalogue: ApoderamientosCatalogue

Return the AEAT apoderamiento scope ApoderamientosCatalogue in use by this service.

status(*, bucket_id)

Return the current ApoderadoStatus for bucket_id.

Reads the persisted ApoderadoConfiguration (if any) and projects it into a read-only status record. Does not contact AEAT.

Parameters:

bucket_id (str) – The profile bucket’s UUIDv4 identifier.

Return type:

ApoderadoStatus

configure(*, bucket_id, represented_nif, scope_tokens, notes='')

Persist apoderado config and return the resulting ApoderadoConfiguration.

Validates and dedups scopes against the catalogue.

Return type:

ApoderadoConfiguration

Parameters:

• bucket_id (str)

• represented_nif (str)

• scope_tokens (tuple[str, ...])

• notes (str)

clear(*, bucket_id)

Retire the configuration. Returns True iff a record was removed.

Return type:

bool

Parameters:

bucket_id (str)

check(*, bucket_id)

Read-only live verification (sealed pending live-read wiring).

check is the live-verification verb: it would contact the AEAT sede to confirm the stored apoderamiento is still granted. That live-read path is not wired (live AEAT reads are refused at this boundary per the safety gate), so check raises ApoderadoLiveCheckUnavailableError unconditionally rather than silently re-reading stored configuration and presenting it as a live result. Use status for the offline configuration read.

Returns the live ApoderadoStatus once the live-read path is wired; until then it raises.

Raises:

ApoderadoLiveCheckUnavailableError – always, until the live-read path is wired.

Return type:

ApoderadoStatus

Parameters:

bucket_id (str)