ya-passport-auth 1.2.2

Async Yandex Passport (mobile) auth library for Music Assistant providers

ya-passport-auth

Async Yandex Passport (mobile) authentication library for Music Assistant providers.

Features

• Two login methods — QR code scan and cookie-based login.
• Full token-derivation graph — x_token exchange, music_token refresh, Passport cookie refresh (redirect-following), Quasar CSRF, Glagol device token, account info.
• Security-first — SecretStr redacts tokens in repr/str/format/tracebacks and blocks pickling; host allow-list with HTTPS-only enforcement; CSRF extraction; per-request rate limiting; response size caps; log redaction via RedactingFilter.
• Async-native — built on aiohttp with asyncio.Lock-protected rate limiter and connection management.
• Strictly typed — mypy --strict clean, PEP 561 py.typed marker.
• Well tested — 221 tests, 97.8 % branch coverage.

Installation

pip install ya-passport-auth

Quick start

QR login

from ya_passport_auth import PassportClient

async def qr_login():
    async with PassportClient.create() as client:
        qr = await client.start_qr_login()
        print(f"Scan QR: {qr.qr_url}")
        creds = await client.poll_qr_until_confirmed(qr)

        info = await client.fetch_account_info(creds.x_token)
        print(f"Logged in as {info.display_login} (uid={info.uid})")

Cookie login

from ya_passport_auth import PassportClient

async def cookie_login():
    cookies = "Session_id=...; sessionid2=..."  # from browser
    async with PassportClient.create() as client:
        creds = await client.login_cookies(cookies)
        print(f"x_token acquired, music_token ready")

Architecture

PassportClient  (public facade)
├── SafeHttpClient  (host allow-list, HTTPS enforcement, size caps, rate limiting)
│   └── AsyncMinDelayLimiter
└── Flows
    ├── QrLoginFlow        → CSRF scrape → session create → poll → x_token
    ├── CookieLoginFlow    → raw cookies → x_token
    ├── _token_exchange    → cookies→x_token, x_token→music_token  (shared)
    ├── PassportSessionRefresher  → x_token → session cookies (follows redirects)
    ├── AccountInfoFetcher → x_token → uid/login/avatar
    ├── QuasarCsrfFetcher  → CSRF token for IoT API
    └── GlagolDeviceTokenFetcher → music_token → Glagol device token

API overview

PassportClient

Method	Description
start_qr_login()	Begin QR login, returns QrSession
poll_qr_until_confirmed(qr)	Poll until scanned, returns Credentials
complete_qr_login(qr)	Exchange confirmed QR for tokens
login_cookies(cookies)	Exchange browser cookies for Credentials
refresh_music_token(x_token)	x_token → music_token
refresh_passport_cookies(x_token)	Refresh session cookies (follows redirect chain)
get_quasar_csrf_token()	Quasar CSRF token
get_glagol_device_token(music_token, ...)	Glagol device token
fetch_account_info(x_token)	Account metadata
validate_x_token(x_token)	Check if token is valid

SecretStr

Opaque wrapper — repr() and str() return ***, pickling raises TypeError. Access plaintext only via get_secret().

Credentials

Frozen, slotted dataclass returned by poll_qr_until_confirmed() and login_cookies():

Field	Type
x_token	SecretStr
music_token	SecretStr
uid	int | None
login	str | None

Exception hierarchy

YaPassportError
├── NetworkError
│   └── UnexpectedHostError
└── AuthFailedError
    ├── InvalidCredentialsError
    ├── CsrfExtractionError
    ├── RateLimitedError
    ├── QRPendingError
    └── QRTimeoutError

Security

• HTTPS-only — _check_host() rejects any non-https URL, preventing protocol-downgrade attacks via redirect Location headers.
• Host allow-list — every request is validated against a frozen set of allowed Yandex hosts. Redirect targets are checked at each hop.
• Token redaction — SecretStr hides values in repr/str/format; RedactingFilter scrubs OAuth headers and hex tokens from log output.
• No pickling — SecretStr and Credentials block pickle/copy.
• Response size caps — 1 MiB for JSON, 2 MiB for HTML.
• See SECURITY.md for the full threat model (T1–T14).

Security disclaimer

This library interacts with Yandex Passport using public mobile OAuth client IDs and secrets extracted from official Yandex Android applications. These values are well-known and present in many open-source projects; they are treated here as constants, not secrets. Do not use this library for anything other than authenticating into your own Yandex account.

There is no official Yandex API for the mobile Passport flow. Endpoints, response shapes, and regex patterns may break without notice.

License

MIT. See LICENSE and NOTICE for third-party attribution.