Metadata-Version: 2.3
Name: xbl3auth
Version: 0.1.0
Summary: Security-conscious XBL3.0 token helper using MSAL and the OS keyring.
License: MIT
Author: DJ Stomp
Author-email: 85457381+DJStompZone@users.noreply.github.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: keyring (>=25.0.0,<26.0.0)
Requires-Dist: msal (>=1.30.0,<2.0.0)
Requires-Dist: platformdirs (>=4.0.0,<5.0.0)
Requires-Dist: requests (>=2.32.0,<3.0.0)
Description-Content-Type: text/markdown

# xbl3auth

Security-conscious helper library and CLI for obtaining **XBL3.0 tokens** for Xbox Live.

- Uses official Microsoft auth (MSAL) instead of scraping login pages.
- Never handles raw passwords: relies on browser/OS for sign-in.
- Stores refresh tokens in the OS keyring (Credential Manager, Keychain, etc.).
- Keeps XBL3.0 tokens in memory by default, printing to stdout when requested.
- Ships with a **built-in public client ID** and a **remote config endpoint** for rotation.

> This library is for legitimate use with accounts you control. Respect Microsoft ToS and local laws.

## Installation

```bash
poetry add xbl3auth
# or
pip install xbl3auth
```

## CLI usage

The CLI uses, in order of precedence:

1. `--client-id` flag
2. `XBL3AUTH_CLIENT_ID` environment variable
3. Remote config endpoint
4. Built-in default client ID

Basic usage:

```bash
python -m xbl3auth
```

This will:

1. Resolve the effective client ID.
2. Start a device code flow (you sign in in a browser).
3. Store a refresh token in your OS keyring.
4. Fetch an XBL3.0 token and print it to stdout:

```text
XBL3.0 x=<uhs>;<token>
```

### Overriding the client ID

If advanced users want to supply their own Azure app registration:

1. **Command-line flag**

```bash
python -m xbl3auth --client-id "<your-azure-client-id>"
```

2. **Environment variable**

```bash
export XBL3AUTH_CLIENT_ID="<your-azure-client-id>"
python -m xbl3auth
```

### JSON output

```bash
python -m xbl3auth --print-json
```

## Library usage

```python
from xbl3auth import XblAuthConfig, Xbl3AuthService

config = XblAuthConfig()  # uses remote/built-in client_id by default
service = Xbl3AuthService(config, account_id="default")

xbl3_token = service.get_xbl3_token()
print(xbl3_token)
```

To use a custom client ID:

```python
config = XblAuthConfig(client_id="<your-client-id>")
```

## Security model

- **No credential files**: No `email:password` lists, no plaintext token dumps by default.
- **Keyring-backed**: Refresh tokens are stored in the OS keyring:
  - Windows Credential Manager
  - macOS Keychain
  - GNOME Keyring / KWallet (depending on environment)
- **Short-lived tokens**: XBL3.0 tokens are treated as in-memory, ephemeral values.
- **Logging discipline**: Library is designed so callers can log error metadata without leaking secrets.

## Testing

```bash
poetry install
poetry run pytest
```

Tests:

- Use an in-memory secret storage backend.
- Monkeypatch HTTP requests to avoid real network calls.
- Avoid touching the real keyring.

