Auth

Auth helper: turn a browser cURL paste into client credentials.

Assists filling and renewing the cf_clearance token + matching User-Agent; it does NOT defeat, solve, or automate the Cloudflare challenge — the human passes it in their own browser, copies the request as cURL (bash), and pastes it here.

Fill (initial setup) and renew (after a stale token) follow the same paste-a-cURL path::

from vgmdb_client import Client
from vgmdb_client.auth import Credentials
from vgmdb_client.transport.errors import CloudflareChallengeError

client = Client.from_credentials(Credentials.from_curl(curl_text))
try:
    album = client.get_album(4)
except CloudflareChallengeError:
    # token went stale — re-solve in the browser, copy a fresh cURL, re-apply, retry
    client.set_credentials(Credentials.from_curl(fresh_curl))
    album = client.get_album(4)

Credentials

Bases: BaseModel

An immutable cf_clearance token paired with the User-Agent it was issued for.

The two travel together because a cf_clearance cookie is only valid with the exact User-Agent (and IP) it was minted for; pairing them prevents a mismatched, dead-on-arrival token. Construct from a browser paste with :meth:from_curl.

Source code in src/vgmdb_client/auth/credentials.py

class Credentials(BaseModel):
    """An immutable ``cf_clearance`` token paired with the ``User-Agent`` it was issued for.

    The two travel together because a ``cf_clearance`` cookie is only valid with the exact
    ``User-Agent`` (and IP) it was minted for; pairing them prevents a mismatched, dead-on-arrival
    token. Construct from a browser paste with :meth:`from_curl`.
    """

    model_config = ConfigDict(frozen=True)

    cf_clearance: str
    user_agent: str

    @field_validator("cf_clearance", "user_agent")
    @classmethod
    def _non_empty(cls, value: str) -> str:
        if not value.strip():
            raise ValueError(_EMPTY_FIELD)
        return value

    @classmethod
    def from_curl(cls, curl_text: str) -> Credentials:
        """Build credentials from a browser "Copy as cURL" paste.

        Raises :class:`~vgmdb_client.auth.errors.CurlParseError` if the paste lacks a
        ``cf_clearance`` cookie or a ``User-Agent``, or cannot be tokenized.
        """
        cf_clearance, user_agent = parse_curl(curl_text)
        return cls(cf_clearance=cf_clearance, user_agent=user_agent)

    def to_config(self, **overrides: Any) -> TransportConfig:
        """Build a :class:`TransportConfig` carrying this pair, forwarding extra config overrides
        (e.g. ``timeout``, ``min_interval``, ``proxy``)."""
        return TransportConfig(cf_clearance=self.cf_clearance, user_agent=self.user_agent, **overrides)

from_curl(curl_text) classmethod

Build credentials from a browser "Copy as cURL" paste.

Raises :class:~vgmdb_client.auth.errors.CurlParseError if the paste lacks a cf_clearance cookie or a User-Agent, or cannot be tokenized.

Source code in src/vgmdb_client/auth/credentials.py

@classmethod
def from_curl(cls, curl_text: str) -> Credentials:
    """Build credentials from a browser "Copy as cURL" paste.

    Raises :class:`~vgmdb_client.auth.errors.CurlParseError` if the paste lacks a
    ``cf_clearance`` cookie or a ``User-Agent``, or cannot be tokenized.
    """
    cf_clearance, user_agent = parse_curl(curl_text)
    return cls(cf_clearance=cf_clearance, user_agent=user_agent)

to_config(**overrides)

Build a :class:TransportConfig carrying this pair, forwarding extra config overrides (e.g. timeout, min_interval, proxy).

Source code in src/vgmdb_client/auth/credentials.py

def to_config(self, **overrides: Any) -> TransportConfig:
    """Build a :class:`TransportConfig` carrying this pair, forwarding extra config overrides
    (e.g. ``timeout``, ``min_interval``, ``proxy``)."""
    return TransportConfig(cf_clearance=self.cf_clearance, user_agent=self.user_agent, **overrides)

CurlParseError

Bases: VgmdbClientError

Raised when a pasted cURL command lacks a cf_clearance cookie or a User-Agent, or cannot be tokenized as a shell command.

Source code in src/vgmdb_client/auth/errors.py

class CurlParseError(VgmdbClientError):
    """Raised when a pasted cURL command lacks a ``cf_clearance`` cookie or a ``User-Agent``,
    or cannot be tokenized as a shell command."""

    def __init__(self, message: str = _DEFAULT) -> None:
        super().__init__(message)