cadrumo.core.remote_authority module

Canonical authority checks for read-only AEAT remote hosts.

This module owns the narrow parsing and suffix predicates used by remote-read guards and authenticated AEAT landings. It reads immutable external constants directly so runtime settings cannot become a competing authority.

REMOTE_READ_SCHEME: Final[str]

The only scheme a remote AEAT read may use. AEAT publishes every public and authenticated read surface over TLS, so a non-https authority reaching a guard or a landing predicate is a downgrade, never a legitimate surface.

canonical_remote_hostname(url)

Return the bare lower-cased hostname of url, or None to refuse it.

This is the single authority for turning a remote URL into the hostname a safety check may compare against an allow-list. It is fail-closed: None is returned — and every caller MUST treat that as a refusal — when the URL is malformed, is not REMOTE_READ_SCHEME, carries user-info credentials, or pins an explicit port.

User-info and ports are refused, not stripped and not string-matched, because each of the two obvious shortcuts admits a different attack:

• Matching the whole authority (urlsplit(url).netloc) admits https://evil@www6.agenciatributaria.gob.es/ — the credential prefix rides along inside a string that still ends in the AEAT suffix, and the browser will send it.

• Reading a stripped host (pydantic.AnyUrl.host) silently discards user-info and any port, so the same URL and an :8443 redirect both read as a plain AEAT host.

An authority that is not a bare host has no business reaching an authenticated AEAT surface, so it is refused rather than normalised.

Parameters:

url (str) – The remote URL to canonicalise, as written by the caller.

Return type:

str | None

Returns:

The lower-cased hostname when the authority is a bare host under REMOTE_READ_SCHEME, otherwise None.

aeat_host_suffixes()

Return host suffixes treated as AEAT-owned infrastructure.

Return type:

tuple[str, ...]

is_aeat_host(host)

Return whether host is under an AEAT-owned suffix.

Return type:

bool

Parameters:

host (str)

first_aeat_host(hosts)

Return the first AEAT-owned host in hosts or None.

Return type:

str | None

Parameters:

hosts (tuple[str, ...])

sanctioned_gov_idp_host_suffixes()

Return host suffixes for sanctioned national-IdP surfaces (Cl@ve).

Derived from the aeat.domains.clave central-config entry (Spain’s Cl@ve government identity provider). This is a NARROW, opt-in allowance distinct from is_aeat_host(): it names the single national-IdP apex an authenticated AEAT flow structurally delegates to, never a data surface.

Return type:

tuple[str, ...]

is_sanctioned_gov_idp_host(host)

Return whether host is under a sanctioned government-IdP apex (Cl@ve).

Suffix-shaped so the observed login subdomain (se-pasarela.clave.gob.es) is covered without enumerating unstable IdP subdomains. Admission of such a host in a guard policy is gated separately on an explicit opt-in (see RemoteStateGuardPolicy.allows_gov_idp_hosts).

Return type:

bool

Parameters:

host (str)