ya-passport-auth

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

Features

• Three login methods — QR code scan, OAuth Device Flow (short code on ya.ru/device, plus a refresh_token for silent re-auth), 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 — 464 tests, 97 % branch coverage.

Installation

pip install ya-passport-auth

With the Music Assistant integration layer (shared device-code login page, config-entry builders and the silent credential-refresh cascade used by the MA yandex providers):

pip install ya-passport-auth[ma]

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})")

Device flow

OAuth 2.0 Device Authorization Grant. The user opens ya.ru/device on any device, enters the short user_code, and the library receives an x_token plus a long-lived refresh_token for silent re-auth later.

from ya_passport_auth import DeviceCodeSession, PassportClient

async def device_login():
    def on_code(session: DeviceCodeSession) -> None:
        print(f"Open {session.verification_url} and enter: {session.user_code}")

    async with PassportClient.create() as client:
        creds = await client.login_device_code(on_code=on_code)
        # creds.refresh_token is populated (only for this flow).
        # Persist creds — the access token is valid for ~1 year.

After the x_token expires, mint a new one without user interaction:

new_creds = await client.refresh_credentials(creds)

Only device-flow credentials carry a refresh_token; QR/cookie-login credentials have refresh_token=None and cannot be silently refreshed.

Device flow for a caller-owned OAuth application

Service providers can use the same polling implementation with their own Yandex OAuth application. The returned tokens are not converted to Passport or Yandex Music credentials:

from ya_passport_auth import OAuthDeviceClient

async def service_login():
    async with OAuthDeviceClient.create(
        client_id="your-client-id",
        client_secret="your-client-secret",
        scope="cloud_api:disk.read",
    ) as client:
        tokens = await client.login_device_code(
            on_code=lambda code: print(code.verification_url, code.user_code)
        )
        # Persist tokens.refresh_token for silent rotation.

Music Assistant providers should use the universal hosted-page wrapper:

from ya_passport_auth.ma import (
    DevicePageConfig,
    refresh_oauth_tokens,
    run_oauth_device_flow,
)

tokens = await run_oauth_device_flow(
    mass,
    values["session_id"],
    DevicePageConfig(domain="my_yandex_provider"),
    client_id=client_id,
    client_secret=client_secret,
    scope="service.scope",
)

tokens = await refresh_oauth_tokens(
    client_id=client_id,
    client_secret=client_secret,
    refresh_token=tokens.refresh_token,
    scope="service.scope",
    session=mass.http_session,
)

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
    ├── DeviceCodeFlow     → device_code → ya.ru/device → x_token + refresh_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

OAuthDeviceClient  (caller-owned Yandex OAuth application)
└── DeviceCodeFlow → service-scoped access_token + refresh_token

API overview

PassportClient

OAuthDeviceClient

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():

Exception hierarchy

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

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).

Used by

• ma-provider-yandex-music — Music Assistant provider for Yandex Music
• ma-provider-yandex-ynison — Music Assistant provider for Yandex Ynison (Spotify Connect analog)
• ma-provider-yandex-station — Music Assistant provider for Yandex Station

Security disclaimer

The Passport-specific client interacts with Yandex 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. OAuthDeviceClient, by contrast, accepts credentials for an application owned by its caller.

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.