Metadata-Version: 2.4
Name: lanyard
Version: 0.2.0
Summary: Official Python client for the Lanyard BYOK Vault.
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/ulixai/lanyard-py
Project-URL: Bug Tracker, https://github.com/ulixai/lanyard-py/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: keyring<27,>=25
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# Lanyard Python SDK 0.2

A synchronous desktop/CLI client for the local Lanyard vault. Requires Lanyard desktop 0.2 or later and Python 3.9+.

```bash
pip install 'lanyard>=0.2.0,<0.3'
```

```python
from lanyard import LanyardClient

client = LanyardClient('My desktop app', app_id='com.example.desktop')
linked = client.request_link(category='api_key', reason='Choose a key for this connection.')
# Save this nonsecret ID in your application preferences.
target_id = linked['target_id']
key = client.get_field(target_id, 'API_KEY')
```

The user must approve requests. Always grants work while the vault is unlocked. Pairing identities are generated randomly and stored in the OS credential store using `keyring`; names alone cannot inherit permissions. Linux needs an unlocked Secret Service keyring. No plaintext credential fallback is used.

For an ephemeral CLI invocation use `session_only=True`. Apps with their own secure store may pass a `CredentialStore` implementing `load(app_id) -> Credential | None` and `save(app_id, credential)`. Preserve the same identity between launches. `Credential.token` is excluded from its representation, but must still be treated as a secret.

```bash
python -m lanyard --app 'My CLI' --app-id com.example.cli link --category api_key
python -m lanyard --app 'My CLI' --app-id com.example.cli get ITEM_UUID --field API_KEY
```

These explicit CLI commands print requested secrets to stdout. Direct output to the consuming process, avoid logs and command history, and do not place tokens on command lines.

Errors derive from `LanyardError`: `LanyardNotRunningError`, `LanyardAccessDeniedError`, `LanyardTimeoutError`, `LanyardKeyNotFoundError`, and `LanyardUpgradeRequiredError`. Requests rediscover the desktop port each time, bypass proxies, reject redirects, and enforce response limits. The maximum consent timeout is 300 seconds.

## Migrating 0.1.2

Upgrade SDK and desktop together. Existing method names and return shapes are retained. Add a stable `app_id` (recommended), and handle native keychain availability. Old name-based grants require user approval again. First-launch desktop migration keeps the original Python vault untouched and imports its items/projects after validating its PIN.

The language-independent protocol is documented in the desktop project's `docs/DESKTOP_API.md`. Any native language with HTTP, JSON, secure randomness, and a credential-store integration can implement it.

Run tests with `python -m unittest discover -s tests`.
