# LastPass Vault Py

An unofficial, Pythonic wrapper for the [LastPass CLI (`lpass`)](https://github.com/lastpass/lastpass-cli).

> **Disclaimer:** This project is an unofficial, community-driven tool. It is not affiliated with, maintained, or endorsed by LastPass, LogMeIn, or GoTo Technologies. No claim is made to the LastPass name, brand, trademarks, or intellectual property.

## Features

- Secure authentication via the official `lpass` CLI
- Full vault management — list, search, retrieve, add, edit, move, delete, and duplicate entries
- Password generation via `lpass generate`
- Passphrase generation using EFF Diceware wordlists with configurable entropy
- Passphrase strength assessment integrating mathematical entropy and optional zxcvbn analysis
- Vault backup and restore via CSV export/import
- All sensitive values (passwords, CSV data) transmitted to `lpass` via stdin — never via command-line arguments
- Sync control, background sync, and trust/plaintext-key login options
- Robust error handling and mock-friendly design for testing

## Prerequisites

The LastPass CLI must be installed:

- **Ubuntu/Debian:** `sudo apt install lastpass-cli`
- **macOS:** `brew install lastpass-cli`

## Installation

```bash
# Core library
pip install lastpass-vault-py

# With passphrase strength assessment (adds zxcvbn)
pip install lastpass-vault-py[strength]
```

## Quick Start

```python
from lastpass_vault import LastPassVault

vault = LastPassVault()

if not vault.is_logged_in():
    vault.login("user@example.com")

items = vault.list_items()
for item in items:
    print(item['name'])

password = vault.get_password("My Site")
```

## Passphrase Generation

```python
from lastpass_vault import generate_passphrase, passphrase_entropy

# 6-word passphrase from the EFF large list — ~77.5 bits of entropy
phrase = generate_passphrase()

# Meet "must contain uppercase, digit, and symbol" site requirements
phrase = generate_passphrase(
    num_words=5,
    capitalize="first",
    num_digits=1,
    num_special=1,
)

# Check entropy before using
bits = passphrase_entropy(num_words=5, capitalize="first", num_digits=1, num_special=1)
print(f"{bits:.1f} bits — NIST compliant: {bits >= 80}")
```

### Passphrase Strength Assessment

Requires `pip install lastpass-vault-py[strength]` for the zxcvbn integration.
The mathematical entropy is always available regardless.

```python
from lastpass_vault import (
    generate_passphrase, passphrase_entropy, check_passphrase_strength
)

phrase = generate_passphrase(num_words=6)
bits   = passphrase_entropy(num_words=6)
result = check_passphrase_strength(phrase, bits)

print(f"Entropy : {result.entropy_bits:.1f} bits ({result.entropy_rating})")
print(f"NIST OK : {result.nist_compliant}")

if result.zxcvbn_available:
    print(f"zxcvbn  : {result.zxcvbn_score}/4 ({result.zxcvbn_score_label})")
    print(f"Offline fast crack: "
          f"{result.zxcvbn_crack_times['offline_fast_hashing_1e10_per_second']}")

if result.zxcvbn_note:
    print(f"Note    : {result.zxcvbn_note}")
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

The project code is licensed under the **GNU General Public License v3 (GPLv3)**.
See [LICENSE](LICENSE) for the full text.

## Third-Party Components

This project bundles or optionally uses third-party material. Full license texts
are reproduced in [NOTICE](NOTICE).

### EFF Diceware Wordlists (bundled)

The files `eff_large.txt`, `eff_short1.txt`, and `eff_short2.txt` in
`src/lastpass_vault/wordlists/` are derived from wordlists created by the
**Electronic Frontier Foundation** and are used under the terms of the
[Creative Commons Attribution 3.0 United States License](https://creativecommons.org/licenses/by/3.0/us/).

- **Author:** Electronic Frontier Foundation (EFF)
- **Source:** <https://www.eff.org/dice>
- **Modification:** The original tab-separated dice-roll index numbers have been
  stripped; no words have been added, removed, or altered.

### zxcvbn (optional dependency)

When installed via `pip install lastpass-vault-py[strength]`, this project uses
the [`zxcvbn`](https://pypi.org/project/zxcvbn/) package by Daniel Wolf (MIT
License), a Python port of Dropbox's zxcvbn password strength estimator.
zxcvbn is not bundled — it is fetched separately from PyPI by the user.
