aeat.adapters.outbound.aeat.auth._certificate_backends._playwright_context module

Playwright per-context client-certificate backend.

Playwright (Python, >=1.46) exposes client certs as a per-context kwarg on playwright.async_api.Browser.new_context():

await browser.new_context(client_certificates=[{
    "origin": "https://sede.agenciatributaria.gob.es",
    "pfxPath": str(bundle.path),
    "passphrase": password_value,
}])

There is no post-hoc injection hook: a context that was constructed without client_certificates cannot be retrofitted with one. This backend therefore validates the contract at call time rather than mutating the context.

CertificateContextProvisioner calls build_client_certificates_kwarg() while creating a browser context and then stamps CERTIFICATE_CONTEXT_MARKER; PlaywrightContextBackend later checks that marker for the selected LoadedCertificate.

build_client_certificates_kwarg(cert, origin)

Build the Playwright client_certificates kwarg for cert.

Materialises the passphrase from pydantic.SecretStr at the exact call site and nowhere else. The returned list is wired directly into browser.new_context(client_certificates=...) by adapters.outbound.aeat.browser.

Parameters:

• cert (LoadedCertificate) – The loaded PKCS#12 certificate.

• origin (str) – URL origin to scope the cert to (e.g. "https://sede.agenciatributaria.gob.es").

Return type:

list[dict[str, str]]

Returns:

A single-element list of Playwright cert records.

class PlaywrightContextBackend

Bases: _CertBackend

Primary backend — per-context client cert via Playwright.

Implements the _CertBackend contract for browser-driven certificate sessions. The preload leg validates the CERTIFICATE_CONTEXT_MARKER stamp produced by CertificateContextProvisioner. The verify leg delegates to HttpxFallbackBackend, which fails closed unless a future backend can perform mTLS verification without materialising plaintext key files.

preload(cert, context)

Verify the context was constructed with this cert.

The browser session layer is expected to tag the constructed playwright.async_api.BrowserContext with an attribute named CERTIFICATE_CONTEXT_MARKER matching cert.sha256_thumbprint. If the marker is absent, raises adapters.outbound.aeat.auth.certificate.CertificateError pointing the operator at build_client_certificates_kwarg().

Parameters:

• cert (LoadedCertificate) – The loaded PKCS#12 certificate.

• context (object) – A Playwright BrowserContext object (typed as object to avoid leaking the Playwright dependency upward).

Raises:

CertificateError – When the context lacks the expected thumbprint marker.

Return type:

None

verify(cert, url)

Delegate to the fail-closed httpx fallback for handshake verification.

The Playwright backend has no standalone handshake primitive — spinning up a full browser just to probe TLS would be wasteful. The fallback refuses verification rather than writing decrypted PEM/key material to temporary files.

Parameters:

• cert (LoadedCertificate) – The loaded PKCS#12 certificate to present.

• url (str) – HTTPS endpoint to probe.

Return type:

HandshakeResult

Returns:

A HandshakeResult describing the outcome.