vw-cli 0.2.0__tar.gz

vw_cli-0.2.0/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2026 robertanrbrandao[at]gmail[dot]com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

vw_cli-0.2.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: vw-cli
+Version: 0.2.0
+Summary: Lightweight Vaultwarden (Bitwarden-compatible) CLI in Python
+Author-email: Roberta Brandao <roberta@betabrandao.com.br>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/betabrandao/vaultvarden-cli
+Project-URL: Repository, https://gitlab.com/betabrandao/vaultvarden-cli
+Keywords: bitwarden,vaultwarden,cli,password-manager,alpine
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+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: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: cryptography>=41
+Requires-Dist: argon2-cffi>=23
+Dynamic: license-file
+
+# vw-cli
+
+Lightweight Vaultwarden (Bitwarden-compatible) CLI written in Python.  
+Authenticates via API key, syncs the vault, derives the encryption key
+locally, and prints decrypted passwords or items — all in a single command.
+
+Designed for use in Alpine‑based Docker containers where the official
+`bw` Node.js CLI is impractical.
+
+## Quick start
+
+```sh
+pip install vw-cli
+
+export VW_SERVER=https://vault.example.com
+export VW_CLIENTID=user.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+export VW_CLIENTSECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export VW_PASSWORD="your master password"
+
+vw-cli get password "My Website"
+```
+
+## Usage
+
+```
+usage: vw-cli <command> [args]
+
+commands:
+  login                     authenticate with API key
+  sync                      sync vault and print raw JSON
+  unlock                    unlock vault (derive encryption key)
+  list                      list all item names
+  get password <item>       print password for <item>
+  get item <item>           print full decrypted <item> as JSON
+```
+
+### Commands
+
+| command | description |
+|---------|-------------|
+| `login` | Authenticate with the API key. Verifies credentials work. |
+| `sync`  | Pull the full vault (profile + all ciphers) and print raw JSON. |
+| `unlock` | Derive the master key locally and decrypt the stored symmetric key. |
+| `list` | Print every item name (lowercased), one per line. |
+| `get password <item>` | Print the password for the named item (empty string if none). |
+| `get item <item>` | Print the full decrypted item as JSON. |
+
+Item lookup is case‑insensitive and supports substring matching.
+
+## Environment variables
+
+| variable | required | default | description |
+|----------|----------|---------|-------------|
+| `VW_SERVER` | no | `https://vault.bitwarden.com` | Vaultwarden or Bitwarden server URL |
+| `VW_CLIENTID` | yes | — | API client ID (`user.xxx` or `org.xxx`) |
+| `VW_CLIENTSECRET` | yes | — | API client secret |
+| `VW_PASSWORD` | yes | — | Master password |
+
+When `VW_SERVER` contains `bitwarden` the official Bitwarden identity
+and API endpoints are used automatically; otherwise the same URL is used
+for both identity and API paths.
+
+## Docker example
+
+```Dockerfile
+FROM alpine:3.19
+RUN apk add --no-cache python3 py3-pip
+RUN pip install vw-cli
+```
+
+```sh
+docker run --rm \
+  -e VW_SERVER=https://vault.example.com \
+  -e VW_CLIENTID=user.xxx \
+  -e VW_CLIENTSECRET=xxx \
+  -e VW_PASSWORD="..." \
+  my-image vw-cli get password "Database"
+```
+
+## How it works
+
+1. **Login** — sends a `client_credentials` grant with the API key to
+   `{identity_url}/connect/token` and receives a bearer token.
+2. **Sync** — fetches `GET /api/sync` which returns the user profile
+   (email, KDF parameters, encrypted symmetric key) and all ciphers.
+3. **Unlock** — derives the 32‑byte master key using the password and
+   email (PBKDF2‑SHA256 or Argon2id, depending on the profile KDF), then
+   decrypts the 64‑byte symmetric key stored in the profile.
+4. **Decrypt** — splits the symmetric key into an AES‑256‑CBC encryption
+   key (first 32 bytes) and an HMAC‑SHA256 MAC key (last 32 bytes), then
+   decrypts individual cipher fields.
+
+All key derivation happens **locally** — no unlock endpoint is called.
+
+## Architecture
+
+```
+vw_cli/
+├── __init__.py     # package entry, re‑exports
+├── __main__.py     # python -m vw_cli support
+├── error.py        # VwError exception class
+├── crypto.py       # VwCryptoKey, key derivation, AES-CBC, HMAC
+├── auth.py         # VwAuth – API key login, session management
+├── vault.py        # VwVault – sync, unlock, cipher operations
+└── cli.py          # CLI argument parsing, orchestration
+```
+
+Separation of concerns:
+
+| module | responsibility |
+|--------|---------------|
+| `crypto.py` | Pure functions: key derivation, encryption/decryption, data types. No I/O. |
+| `auth.py` | `VwAuth` class: HTTP session, token acquisition, request helper. |
+| `vault.py` | `VwVault` class: sync, unlock, name cache, find/get/list operations. |
+| `cli.py` | Environment variable reading, argument parsing, command dispatch. |
+
+## Development
+
+### Virtualenv (recommended)
+
+```sh
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+The package is installed in **editable mode** (`-e`), so source changes take
+effect immediately — no need to reinstall.
+
+### Run without pip
+
+You don't need to `pip install` at all.  The `__main__.py` entry point lets you
+run the CLI directly from the checkout:
+
+```sh
+python -m vw_cli get password "My Website"
+```
+
+Or set up a shell alias for convenience:
+
+```sh
+alias vw-cli='python -m vw_cli'
+```
+
+### Test
+
+```sh
+python -m pytest tests/ -v
+```
+
+### Testing
+
+Three test files covering all layers:
+
+| test file | coverage |
+|-----------|----------|
+| `tests/test_crypto.py` | `VwCryptoKey`, `_safe_int`, key derivation, AES-CBC, HMAC, `decrypt`, `decrypt_bytes`, `decode_encrypted` |
+| `tests/test_client.py` | `VwAuth` (login, errors), `VwVault` (sync, unlock, find, get, list), `_setup_urls`, network errors, timeout |
+| `tests/test_cli.py` | CLI argument parsing, help/version output, error handling, exit codes |
+
+Tests use mocks and never touch the network.
+
+### Dependencies
+
+- `requests` — HTTP client
+- `cryptography` — AES‑256‑CBC via OpenSSL bindings
+- `argon2-cffi` — Argon2id KDF (optional; falls back gracefully)
+
+## License
+
+MIT

vw_cli-0.2.0/README.md

@@ -0,0 +1,171 @@
+# vw-cli
+
+Lightweight Vaultwarden (Bitwarden-compatible) CLI written in Python.  
+Authenticates via API key, syncs the vault, derives the encryption key
+locally, and prints decrypted passwords or items — all in a single command.
+
+Designed for use in Alpine‑based Docker containers where the official
+`bw` Node.js CLI is impractical.
+
+## Quick start
+
+```sh
+pip install vw-cli
+
+export VW_SERVER=https://vault.example.com
+export VW_CLIENTID=user.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+export VW_CLIENTSECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export VW_PASSWORD="your master password"
+
+vw-cli get password "My Website"
+```
+
+## Usage
+
+```
+usage: vw-cli <command> [args]
+
+commands:
+  login                     authenticate with API key
+  sync                      sync vault and print raw JSON
+  unlock                    unlock vault (derive encryption key)
+  list                      list all item names
+  get password <item>       print password for <item>
+  get item <item>           print full decrypted <item> as JSON
+```
+
+### Commands
+
+| command | description |
+|---------|-------------|
+| `login` | Authenticate with the API key. Verifies credentials work. |
+| `sync`  | Pull the full vault (profile + all ciphers) and print raw JSON. |
+| `unlock` | Derive the master key locally and decrypt the stored symmetric key. |
+| `list` | Print every item name (lowercased), one per line. |
+| `get password <item>` | Print the password for the named item (empty string if none). |
+| `get item <item>` | Print the full decrypted item as JSON. |
+
+Item lookup is case‑insensitive and supports substring matching.
+
+## Environment variables
+
+| variable | required | default | description |
+|----------|----------|---------|-------------|
+| `VW_SERVER` | no | `https://vault.bitwarden.com` | Vaultwarden or Bitwarden server URL |
+| `VW_CLIENTID` | yes | — | API client ID (`user.xxx` or `org.xxx`) |
+| `VW_CLIENTSECRET` | yes | — | API client secret |
+| `VW_PASSWORD` | yes | — | Master password |
+
+When `VW_SERVER` contains `bitwarden` the official Bitwarden identity
+and API endpoints are used automatically; otherwise the same URL is used
+for both identity and API paths.
+
+## Docker example
+
+```Dockerfile
+FROM alpine:3.19
+RUN apk add --no-cache python3 py3-pip
+RUN pip install vw-cli
+```
+
+```sh
+docker run --rm \
+  -e VW_SERVER=https://vault.example.com \
+  -e VW_CLIENTID=user.xxx \
+  -e VW_CLIENTSECRET=xxx \
+  -e VW_PASSWORD="..." \
+  my-image vw-cli get password "Database"
+```
+
+## How it works
+
+1. **Login** — sends a `client_credentials` grant with the API key to
+   `{identity_url}/connect/token` and receives a bearer token.
+2. **Sync** — fetches `GET /api/sync` which returns the user profile
+   (email, KDF parameters, encrypted symmetric key) and all ciphers.
+3. **Unlock** — derives the 32‑byte master key using the password and
+   email (PBKDF2‑SHA256 or Argon2id, depending on the profile KDF), then
+   decrypts the 64‑byte symmetric key stored in the profile.
+4. **Decrypt** — splits the symmetric key into an AES‑256‑CBC encryption
+   key (first 32 bytes) and an HMAC‑SHA256 MAC key (last 32 bytes), then
+   decrypts individual cipher fields.
+
+All key derivation happens **locally** — no unlock endpoint is called.
+
+## Architecture
+
+```
+vw_cli/
+├── __init__.py     # package entry, re‑exports
+├── __main__.py     # python -m vw_cli support
+├── error.py        # VwError exception class
+├── crypto.py       # VwCryptoKey, key derivation, AES-CBC, HMAC
+├── auth.py         # VwAuth – API key login, session management
+├── vault.py        # VwVault – sync, unlock, cipher operations
+└── cli.py          # CLI argument parsing, orchestration
+```
+
+Separation of concerns:
+
+| module | responsibility |
+|--------|---------------|
+| `crypto.py` | Pure functions: key derivation, encryption/decryption, data types. No I/O. |
+| `auth.py` | `VwAuth` class: HTTP session, token acquisition, request helper. |
+| `vault.py` | `VwVault` class: sync, unlock, name cache, find/get/list operations. |
+| `cli.py` | Environment variable reading, argument parsing, command dispatch. |
+
+## Development
+
+### Virtualenv (recommended)
+
+```sh
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+The package is installed in **editable mode** (`-e`), so source changes take
+effect immediately — no need to reinstall.
+
+### Run without pip
+
+You don't need to `pip install` at all.  The `__main__.py` entry point lets you
+run the CLI directly from the checkout:
+
+```sh
+python -m vw_cli get password "My Website"
+```
+
+Or set up a shell alias for convenience:
+
+```sh
+alias vw-cli='python -m vw_cli'
+```
+
+### Test
+
+```sh
+python -m pytest tests/ -v
+```
+
+### Testing
+
+Three test files covering all layers:
+
+| test file | coverage |
+|-----------|----------|
+| `tests/test_crypto.py` | `VwCryptoKey`, `_safe_int`, key derivation, AES-CBC, HMAC, `decrypt`, `decrypt_bytes`, `decode_encrypted` |
+| `tests/test_client.py` | `VwAuth` (login, errors), `VwVault` (sync, unlock, find, get, list), `_setup_urls`, network errors, timeout |
+| `tests/test_cli.py` | CLI argument parsing, help/version output, error handling, exit codes |
+
+Tests use mocks and never touch the network.
+
+### Dependencies
+
+- `requests` — HTTP client
+- `cryptography` — AES‑256‑CBC via OpenSSL bindings
+- `argon2-cffi` — Argon2id KDF (optional; falls back gracefully)
+
+## License
+
+MIT

vw_cli-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vw-cli"
+version = "0.2.0"
+description = "Lightweight Vaultwarden (Bitwarden-compatible) CLI in Python"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Roberta Brandao", email = "roberta@betabrandao.com.br"},
+]
+keywords = ["bitwarden", "vaultwarden", "cli", "password-manager", "alpine"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.10"
+dependencies = ["requests>=2.31", "cryptography>=41", "argon2-cffi>=23"]
+
+[project.urls]
+Homepage = "https://gitlab.com/betabrandao/vaultvarden-cli"
+Repository = "https://gitlab.com/betabrandao/vaultvarden-cli"
+
+[project.scripts]
+vw-cli = "vw_cli.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["vw_cli*"]

vw_cli-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vw_cli-0.2.0/tests/test_cli.py

@@ -0,0 +1,83 @@
+import sys
+
+import pytest
+import requests
+
+from vw_cli.cli import VERSION, main
+from vw_cli.error import VwError
+
+
+class TestHelp:
+    def test_help_exits_zero(self):
+        sys.argv = ["vw-cli", "--help"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 0
+
+    def test_help_with_no_args(self):
+        sys.argv = ["vw-cli"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 0
+
+    def test_help_with_h_flag(self):
+        sys.argv = ["vw-cli", "-h"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 0
+
+
+class TestVersion:
+    def test_version_output(self, capsys):
+        sys.argv = ["vw-cli", "--version"]
+        with pytest.raises(SystemExit):
+            main()
+        out, _ = capsys.readouterr()
+        assert "vw-cli" in out
+        assert VERSION in out
+
+
+class TestUnknownCommand:
+    def test_unknown_command_exits_1(self):
+        sys.argv = ["vw-cli", "nonsense"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 1
+
+
+class TestVwErrorCaught:
+    def test_bwerror_prints_and_exits_1(self, monkeypatch):
+        def fail(*a):
+            raise VwError("boom")
+
+        monkeypatch.setattr("vw_cli.auth.VwAuth.login", fail)
+        sys.argv = ["vw-cli", "login"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 1
+
+
+class TestRequestExceptionCaught:
+    def test_network_error_prints_and_exits_1(self, monkeypatch):
+        def fail(*a):
+            raise requests.ConnectionError("timeout")
+
+        monkeypatch.setattr("vw_cli.auth.VwAuth.login", fail)
+        sys.argv = ["vw-cli", "login"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 1
+
+
+class TestGetMissingArgs:
+    def test_get_without_subcommand(self):
+        sys.argv = ["vw-cli", "get"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 1
+
+    def test_get_without_name(self):
+        sys.argv = ["vw-cli", "get", "password"]
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 1