cadrumo.application.auth.protocols module¶

Protocol definitions for the application-layer auth session boundary.

These protocols declare the interface the application layer depends on for persisted auth session management. Concrete implementations live in the adapter layer (adapters/outbound/aeat/auth/session_store.py) and satisfy these protocols structurally. SessionStoreProtocol returns PersistedSessionDataProtocol records to the persisted-session service.

class BrowserResponsePort(*args, **kwargs)[source]¶

Bases: Protocol

Minimal response surface needed to classify an authentication probe.

property ok: bool¶: Whether the browser classified the response as successful.

property status: int¶: HTTP status observed by the browser.

class BrowserPagePort(*args, **kwargs)[source]¶

Bases: Protocol

Minimal page surface consumed by authentication providers.

property url: str¶: Final page URL after redirects.

async goto(url, *, timeout=None)[source]¶

Navigate to url and return its response, if any.

Return type:

BrowserResponsePort | None

Parameters:

url (str)
timeout (float | None)

async click(selector)[source]¶

Click one selector while driving an authentication flow.

Return type:: None
Parameters:: selector (str)

async close()[source]¶

Close the page after the authentication probe completes.

Return type:: None

class BrowserContextKwargs[source]¶

Bases: TypedDict

Subset of Playwright Browser.new_context() keyword arguments.

Only the kwargs that AEAT auth provisioners currently supply are declared here. total=False makes every key optional so callers can return a partial mapping.

client_certificates: list[dict[str, str | bytes]]¶

class BrowserContextProvisioner(*args, **kwargs)[source]¶

Bases: Protocol

Hook that decorates browser-context creation for auth providers.

Concrete outbound auth provisioners implement this protocol to add Playwright new_context() kwargs.

build_context_kwargs()[source]¶

Return the provider-owned browser context arguments.

Return type:: BrowserContextKwargs

class BrowserContextPort(*args, **kwargs)[source]¶

Bases: Protocol

Minimal browser context used by authentication providers.

async new_page()[source]¶

Create a page for a live verification flow.

Return type:: BrowserPagePort

async storage_state()[source]¶

Return the in-memory browser storage state.

Return type:: Mapping[str, object]

async close()[source]¶

Close the context during provider teardown.

Return type:: None

class BrowserSessionPort(*args, **kwargs)[source]¶

Bases: Protocol

Browser lifecycle required by concrete authentication providers.

async create_context(*, provisioner=None, storage_state=None)[source]¶

Create a context with optional provider or persisted state.

Return type:

BrowserContextPort

Parameters:

provisioner (BrowserContextProvisioner | None)
storage_state (Mapping[str, object] | None)

async close()[source]¶

Close the owned browser process.

Return type:: None

class BrowserSessionFactoryPort(*args, **kwargs)[source]¶

Bases: Protocol

Async browser-session constructor accepted by auth composition.

class PersistedSessionDataProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Minimal surface the application layer reads from a persisted session record.

property storage_state: Mapping[str, object]¶: Playwright browser storage state for the persisted session.

property metadata: Mapping[str, object]¶: Provider-specific session metadata.

class SessionStoreProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Structural interface for the persisted browser session store.

The application layer depends on this protocol rather than the concrete adapter module so that application/auth/sessions.py does not carry a direct import from adapters/outbound/aeat/auth/session_store.py.

exists(path)[source]¶

Return whether a session is persisted at logical path.

Return type:: bool
Parameters:: path (Path)

load(path)[source]¶

Load persisted session data for path.

Returns a PersistedSessionDataProtocol, or None when absent.

Return type:: PersistedSessionDataProtocol | None
Parameters:: path (Path)

delete(path)[source]¶

Delete persisted session data at path, returning True when removed.

Return type:: bool
Parameters:: path (Path)

bind_session_store(store)[source]¶

Bind the encrypted outbound session store for one runtime scope.

Return type:: Generator[SessionStoreProtocol]
Parameters:: store (SessionStoreProtocol)

session_store()[source]¶

Return the session store installed by outward composition.

Return type:: SessionStoreProtocol