cadrumo.application.auth.apoderado_service 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 through the application-owned configuration repository capability. The repository implementation is responsible for encryption and storage; 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, translated_message=None)[source]

Bases: CadrumoError

Raised when status or check runs without a configured apoderado.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception ApoderadoRepresentedNifInvalidError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when configure receives an invalid represented-party tax id.

Both the flag-driven and the paged-flow transports commit through ApoderadoService.configure(), which validates the represented party’s identifier through the canonical cadrumo.domain.calculations.registry.tax_id_runtime.validate_runtime_identity() authority. The raised error carries NO raw identifier in its context – the value is identity-sensitive and must never leak into a diagnostic.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception ApoderadoLiveCheckUnavailableError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

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

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception ApoderadoConfigurationIdentityError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when a stored configuration does not belong to the key it sits under.

The persisted record key IS the bucket binding for this record: nothing else in the row asserts ownership. A configuration for bucket B placed under bucket A’s key would otherwise be returned by status(bucket_id=A) and projected with B’s represented tax identifier – an identity-bearing cross-bucket leak that the key-only boundary cannot otherwise detect.

The error carries no represented identifier: that value is identity-sensitive and must never reach a diagnostic.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
class ApoderadoConfiguration(**data)[source]

Bases: BaseModel

Persisted apoderado configuration for one bucket.

Parameters:

data (Any)

bucket_id: BucketId
represented_nif: RepresentedNif
granted_scopes: tuple[str, ...]
catalogue_version: str
configured_at: datetime
notes: ApoderadoNotes
class ApoderadoStatus(**data)[source]

Bases: BaseModel

Read-only status surface returned by apoderado status.

Parameters:

data (Any)

bucket_id: BucketId
configured: bool
represented_nif: str | None
granted_scopes: tuple[str, ...]
catalogue_version: str | None
configured_at: datetime | None
class ApoderadoService(*, repository_factory, operation, settings=None, catalogue=None)[source]

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:
property catalogue: ApoderamientosCatalogue

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

status(*, bucket_id)[source]

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='')[source]

Persist apoderado config and return the resulting ApoderadoConfiguration.

Validates the represented party’s tax identifier through the authority-aware cadrumo.domain.calculations.registry.tax_id_runtime.validate_runtime_identity() (the single validation law both the flag path and the paged flow commit through), then validates and dedups scopes against the catalogue.

Raises:

ApoderadoRepresentedNifInvalidError – When represented_nif is not a valid NIF, NIE, or CIF.

Return type:

ApoderadoConfiguration

Parameters:
clear(*, bucket_id)[source]

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

Return type:

bool

Parameters:

bucket_id (str)

check(*, bucket_id)[source]

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)