lockedpass-cli 0.1.0__py3-none-any.whl

lockedpass_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: lockedpass-cli
+Version: 0.1.0
+Summary: Official CLI for LockedPass — zero-knowledge password manager
+Author-email: Nextcoders <hello@lockedpass.com>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://lockedpass.com
+Project-URL: Documentation, https://account.lockedpass.com/api-docs
+Project-URL: Repository, https://github.com/nextcoders/lockedpass-cli
+Keywords: password,manager,cli,zero-knowledge,vault,encryption
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: pynacl>=1.5
+Requires-Dist: argon2-cffi>=23.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pyperclip>=1.8
+Dynamic: license-file
+
+# LockedPass CLI
+
+Official command-line interface for [LockedPass](https://lockedpass.com) — a zero-knowledge password manager for teams and AI agents.
+
+All encryption and decryption happens **locally on your machine**. The server never sees your master password, private key, or any plaintext credential data.
+
+## Requirements
+
+- Python 3.11+
+- A LockedPass account (Pro plan or higher)
+- An active CLI token generated from **Settings → API & CLI**
+
+## Install
+
+```bash
+pip install lockedpass-cli
+```
+
+## Quick start
+
+```bash
+lp login you@example.com
+# Master password: ••••••••  (prompted once, then cached)
+
+lp vault list
+lp ls
+lp get "GitHub"
+lp get "GitHub" --field password
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `lp login <email>` | Authenticate — master password required once |
+| `lp lock` | Wipe cached keys (re-prompt on next use) |
+| `lp unlock` | Re-cache keys from master password after lock |
+| `lp vault list` | List all vaults |
+| `lp ls` | List credentials in default vault |
+| `lp get <name>` | Show a credential |
+| `lp get <name> --field password` | Print a single field (scriptable) |
+| `lp add` | Create a credential interactively |
+| `lp edit <name>` | Edit a credential |
+| `lp rm <name>` | Delete a credential |
+| `lp otp <name>` | Generate a live TOTP code |
+| `lp generate` | Generate a random password |
+| `lp copy <name>` | Copy password to clipboard (clears in 30s) |
+| `lp status` | Show session status |
+| `lp logout` | Clear saved session |
+
+## Non-interactive / AI agent use
+
+The master password can be passed as an argument or environment variable — useful for automation and AI agents:
+
+```bash
+# Argument
+lp login lp.aivault@example.com "$LP_AI_PASSWORD"
+
+# Environment variable
+LP_MASTER_PASSWORD="$LP_AI_PASSWORD" lp login lp.aivault@example.com
+```
+
+After login the session is cached — subsequent commands run without any password.
+
+See [AGENT.md](AGENT.md) for the full AI agent setup guide.
+
+## Security
+
+- **Argon2id** key derivation — only a one-way hash (`auth_verifier`) is sent to the server
+- **X25519 + XSalsa20-Poly1305** (NaCl) for vault key encryption
+- **XSalsa20-Poly1305** for credential data encryption
+- Private key and vault keys never leave your machine in plaintext
+- Session cached with a random local key — wiped on `lp lock`
+
+## License
+
+Copyright (c) 2026 Nextcoders LLC. All Rights Reserved. — see [LICENSE](LICENSE)

lockedpass_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+lockedpass_cli-0.1.0.dist-info/licenses/LICENSE,sha256=jPSIk6Su8JaFEOsDNYNtj_0Jo6qlk2uqeYy7XRA9nG0,353
+lp/__init__.py,sha256=ch3u3UbWnVneQN9uEXXjuZH4bmfBtJ0Snv9ls1bSmR0,80
+lp/__main__.py,sha256=BtkIJkOCJAlxbh8CmmsCPLDCJykPrJvMU8UWSKd8as4,61
+lp/api.py,sha256=6AVB6YxO88DWZ8nYBqOivnckOfkT0ZQ24gqkwBj-z0E,5971
+lp/cli.py,sha256=r1msSjaJGMUlDM-Tn1LeFBW7L35NHmd8PvVVFxOSaCs,25925
+lp/crypto.py,sha256=8ZwvMgafLoSTwc5pfyYO-eoFHiu7A1Az41f6lMbgzKw,5550
+lp/session.py,sha256=TvPhQ0AYfLb_5dgg3HdnTwSzRwlTXBbgdS5Ojje8pOU,3141
+lockedpass_cli-0.1.0.dist-info/METADATA,sha256=44UJL6_2Gn5er2lS9hybdLKjTpqVaAhFd3JN0uFG9yI,3587
+lockedpass_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+lockedpass_cli-0.1.0.dist-info/entry_points.txt,sha256=6w5RUEJP33qP-rrRrhJBqNmZEMAvKC464Daci7bsc84,34
+lockedpass_cli-0.1.0.dist-info/top_level.txt,sha256=itu-yMNux89mPKAp65tBDua0uq70OwEe-nihpFEo3KU,3
+lockedpass_cli-0.1.0.dist-info/RECORD,,

lockedpass_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lockedpass_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lp = lp.cli:cli

lockedpass_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Nextcoders LLC. All Rights Reserved.
+
+This software and its source code are proprietary and confidential.
+Unauthorized copying, distribution, modification, or use of this software,
+via any medium, is strictly prohibited without the express written permission
+of Nextcoders LLC.
+
+For licensing inquiries, contact: hello@lockedpass.com

lockedpass_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lp

lp/__init__.py

@@ -0,0 +1,2 @@
+"""LockedPass CLI — zero-knowledge password manager."""
+__version__ = "0.1.0"

lp/__main__.py

@@ -0,0 +1,4 @@
+from lp.cli import cli
+
+if __name__ == "__main__":
+    cli()

lp/api.py

@@ -0,0 +1,140 @@
+"""HTTP client for the LockedPass API."""
+
+import httpx
+
+_DEFAULT_TIMEOUT = 15
+
+
+class APIError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(detail)
+        self.status = status
+
+    @classmethod
+    def from_response(cls, r: httpx.Response) -> "APIError":
+        try:
+            d = r.json()
+            detail = d.get("detail", f"HTTP {r.status_code}")
+            if isinstance(detail, list):
+                detail = "; ".join(e.get("msg", str(e)) for e in detail)
+        except Exception:
+            detail = f"HTTP {r.status_code}"
+        return cls(r.status_code, str(detail))
+
+
+class Client:
+    def __init__(self, base_url: str, token: str | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.token    = token
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self.token:
+            h["Authorization"] = f"Bearer {self.token}"
+        return h
+
+    def _check(self, r: httpx.Response) -> httpx.Response:
+        if not r.is_success:
+            raise APIError.from_response(r)
+        return r
+
+    def get(self, path: str) -> dict:
+        r = httpx.get(f"{self.base_url}{path}", headers=self._headers(), timeout=_DEFAULT_TIMEOUT)
+        return self._check(r).json()
+
+    def post(self, path: str, body: dict) -> dict | None:
+        r = httpx.post(f"{self.base_url}{path}", json=body, headers=self._headers(), timeout=_DEFAULT_TIMEOUT)
+        self._check(r)
+        return r.json() if r.status_code != 204 else None
+
+    def patch(self, path: str, body: dict) -> dict:
+        r = httpx.patch(f"{self.base_url}{path}", json=body, headers=self._headers(), timeout=_DEFAULT_TIMEOUT)
+        return self._check(r).json()
+
+    def delete(self, path: str) -> None:
+        r = httpx.delete(f"{self.base_url}{path}", headers=self._headers(), timeout=_DEFAULT_TIMEOUT)
+        self._check(r)
+
+    # ── Auth ─────────────────────────────────────────────────────────────────
+
+    def login_init(self, email: str) -> dict:
+        return self.post("/api/v1/auth/login/init", {"email": email})
+
+    def cli_login(self, email: str, auth_verifier: str) -> dict:
+        """Authenticate and get a 30-day CLI token."""
+        return self.post("/api/v1/auth/cli/token", {"email": email, "auth_verifier": auth_verifier})
+
+    def me(self) -> dict:
+        return self.get("/api/v1/cli/me")
+
+    # ── Vaults ───────────────────────────────────────────────────────────────
+
+    def list_vaults(self) -> list:
+        """Returns vaults with embedded members (no extra request needed)."""
+        return self.get("/api/v1/cli/vaults")
+
+    def create_vault(self, name_encrypted: str, vault_type: str, encrypted_vault_key: str) -> dict:
+        return self.post("/api/v1/vaults", {
+            "name_encrypted": name_encrypted,
+            "type": vault_type,
+            "encrypted_vault_key": encrypted_vault_key,
+        })
+
+    # ── Credentials ──────────────────────────────────────────────────────────
+
+    def list_credentials(self, vault_id: str, limit: int = 2000) -> list:
+        return self.get(f"/api/v1/cli/vaults/{vault_id}/credentials?limit={limit}")
+
+    def list_all_credentials(self, vault_id: str) -> list:
+        PAGE, skip, all_creds = 2000, 0, []
+        while True:
+            page = self.get(f"/api/v1/cli/vaults/{vault_id}/credentials?skip={skip}&limit={PAGE}")
+            all_creds.extend(page)
+            if len(page) < PAGE:
+                break
+            skip += PAGE
+        return all_creds
+
+    def get_credential_with_key(self, cred_id: str) -> dict:
+        """Single request — returns credential + vault_key_encrypted."""
+        return self.get(f"/api/v1/cli/credentials/{cred_id}")
+
+    def create_credential(self, vault_id: str, cred_type: str, name_enc: str, data_enc: str) -> dict:
+        return self.post("/api/v1/cli/credentials", {
+            "vault_id": vault_id,
+            "type": cred_type,
+            "name_encrypted": name_enc,
+            "encrypted_data": data_enc,
+        })
+
+    def update_credential(self, vault_id: str, cred_id: str, name_enc: str, data_enc: str) -> dict:
+        return self.patch(f"/api/v1/vaults/{vault_id}/credentials/{cred_id}", {
+            "name_encrypted": name_enc,
+            "encrypted_data": data_enc,
+        })
+
+    def delete_credential(self, vault_id: str, cred_id: str) -> None:
+        self.delete(f"/api/v1/vaults/{vault_id}/credentials/{cred_id}")
+
+    def get_otp_secret(self, cred_id: str) -> dict:
+        return self.get(f"/api/v1/cli/otps/{cred_id}/secret")
+
+    def generate_password(self, length: int = 20, upper: bool = True, lower: bool = True,
+                           numbers: bool = True, symbols: bool = True) -> str:
+        r = self.get(
+            f"/api/v1/cli/generate-password?length={length}"
+            f"&upper={str(upper).lower()}&lower={str(lower).lower()}"
+            f"&numbers={str(numbers).lower()}&symbols={str(symbols).lower()}"
+        )
+        return r["password"]
+
+    def log_action(self, vault_id: str, cred_id: str, action: str) -> None:
+        try:
+            self.post(f"/api/v1/vaults/{vault_id}/credentials/{cred_id}/log", {"action": action})
+        except Exception:
+            pass  # non-critical
+
+    # ── Users ────────────────────────────────────────────────────────────────
+
+    def lookup_user(self, email: str) -> dict:
+        return self.get(f"/api/v1/users/lookup?email={email}")

lp/cli.py

@@ -0,0 +1,727 @@
+"""LockedPass CLI — lp command."""
+
+import json
+import sys
+import threading
+import time
+from typing import Optional
+
+import click
+
+from lp import __version__
+from lp.api import APIError, Client
+from lp.crypto import (
+    b64_dec, b64_enc,
+    decrypt_json, decrypt_text, decrypt_vault_key,
+    encrypt_json, encrypt_text, encrypt_vault_key,
+    generate_password,
+)
+import nacl.utils
+from lp.session import (
+    cache_private_key, clear_session, get_master_password, load_config, load_session,
+    make_client, require_session, save_config, save_session, unlock,
+)
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def ok(msg):    click.echo(click.style(f"  ✓  {msg}", fg="green"))
+def warn(msg):  click.echo(click.style(f"  ⚠  {msg}", fg="yellow"))
+def err(msg):   click.echo(click.style(f"  ✗  {msg}", fg="red"), err=True)
+def info(msg):  click.echo(f"  {msg}")
+
+CRED_TYPE_EMOJI = {"password": "🔑", "otp": "🔐", "note": "📝", "custom": "⚙️"}
+
+
+def _load_vault_key(client: Client, vault: dict, priv_key: bytes, pub_key: bytes) -> bytes:
+    """Decrypt the vault key for the current user.
+    Vault dict from /api/v1/cli/vaults already embeds members — no extra request needed.
+    """
+    my_id = _current_user_id()
+    members = vault.get("members") or []
+    me = next((m for m in members if m["user_id"] == my_id), None)
+    if me is None:
+        raise click.ClickException("You are not a member of this vault")
+    adder = next((m for m in members if m["user_id"] == me["added_by"]), me)
+    sender_pub = b64_dec(adder["public_key"])
+    return decrypt_vault_key(vault["encrypted_vault_key"], sender_pub, priv_key)
+
+
+def _current_user_id() -> str:
+    s = load_session()
+    return s["user_id"] if s else ""
+
+
+def _resolve_vault(client: Client, name_or_id: Optional[str],
+                   priv_key: bytes, pub_key: bytes) -> tuple[dict, bytes]:
+    """Return (vault_dict, vault_key). Uses default if name_or_id is None."""
+    vaults = client.list_vaults()
+    if not vaults:
+        raise click.ClickException("No vaults found. Create one: lp vault new")
+
+    cfg = load_config()
+
+    if name_or_id:
+        match = next(
+            (v for v in vaults if v["id"] == name_or_id or _vault_display_name(v, priv_key, pub_key, client) == name_or_id),
+            None,
+        )
+    else:
+        default_id = cfg.get("default_vault")
+        match = next((v for v in vaults if v["id"] == default_id), vaults[0])
+
+    if not match:
+        raise click.ClickException(f"Vault not found: {name_or_id}")
+
+    vault_key = _load_vault_key(client, match, priv_key, pub_key)
+    return match, vault_key
+
+
+def _vault_display_name(vault: dict, priv_key: bytes, pub_key: bytes, client: Client) -> str:
+    try:
+        vk = _load_vault_key(client, vault, priv_key, pub_key)
+        return decrypt_text(vault["name_encrypted"], vk)
+    except Exception:
+        return "(encrypted)"
+
+
+def _resolve_cred(creds: list[dict], name_or_num: str, vault_key: bytes) -> tuple[dict, dict]:
+    """Return (cred_raw, decrypted_data) matching a name or #N."""
+    if name_or_num.isdigit():
+        idx = int(name_or_num) - 1
+        if 0 <= idx < len(creds):
+            c = creds[idx]
+            return c, decrypt_json(c["encrypted_data"], vault_key)
+        raise click.ClickException(f"No credential #{name_or_num}")
+
+    q = name_or_num.lower()
+    for c in creds:
+        try:
+            data = decrypt_json(c["encrypted_data"], vault_key)
+            if q in (data.get("name") or "").lower():
+                return c, data
+        except Exception:
+            pass
+    raise click.ClickException(f"Credential not found: {name_or_num}")
+
+
+def _clipboard_clear(text: str, seconds: int = 30) -> None:
+    """Copy text to clipboard and schedule a clear after `seconds`."""
+    import pyperclip
+    pyperclip.copy(text)
+    ok(f"Copied to clipboard — clears in {seconds}s")
+
+    def _clear():
+        time.sleep(seconds)
+        try:
+            if pyperclip.paste() == text:
+                pyperclip.copy("")
+        except Exception:
+            pass
+
+    t = threading.Thread(target=_clear, daemon=True)
+    t.start()
+    # Block briefly so the thread is started before the process exits
+    time.sleep(0.2)
+
+
+# ── Root command ───────────────────────────────────────────────────────────────
+
+@click.group()
+@click.version_option(__version__, prog_name="lp")
+def cli():
+    """🔐 LockedPass — zero-knowledge password manager"""
+
+
+# ── Auth ───────────────────────────────────────────────────────────────────────
+
+@cli.command()
+@click.option("--server", default="https://account.lockedpass.com", show_default=True,
+              envvar="LP_SERVER", help="API server URL")
+@click.option("--staging", is_flag=True, help="Use staging server (dev.lockedpass.com)")
+@click.argument("email")
+@click.argument("password", required=False, default=None)
+def login(email, password, server, staging):
+    """Authenticate and save session.
+
+    PASSWORD is optional — if omitted, reads LP_MASTER_PASSWORD env var or prompts.
+    Useful for non-interactive / AI agent use: lp login ai@example.com "$LP_AI_PASSWORD"
+    """
+    if staging:
+        server = "https://dev.lockedpass.com"
+
+    c = Client(server)
+    try:
+        params = c.login_init(email)
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    pw = password or get_master_password()
+
+    from lp.crypto import derive_keys, decrypt_private_key
+    keys = derive_keys(pw, params["argon2_params"])
+
+    try:
+        result = c.cli_login(email, keys["auth_verifier"])
+    except APIError as e:
+        if e.status == 403:
+            raise click.ClickException(str(e))
+        raise click.ClickException("Invalid email or master password")
+
+    priv_key = decrypt_private_key(result["encrypted_private_key"], keys["enc_key"])
+    sess = cache_private_key({
+        "server":                server,
+        "token":                 result["access_token"],
+        "user_id":               result["user_id"],
+        "email":                 email,
+        "plan":                  result["plan"],
+        "encrypted_private_key": result["encrypted_private_key"],
+        "argon2_params":         params["argon2_params"],
+        "public_key":            params["public_key"],
+    }, priv_key)
+    save_session(sess)
+    ok(f"Logged in as {email} (plan: {result['plan']})")
+
+
+@cli.command()
+def logout():
+    """Clear saved session."""
+    clear_session()
+    ok("Session cleared")
+
+
+@cli.command()
+def lock():
+    """Remove cached keys — master password required on next use."""
+    sess = load_session()
+    if sess:
+        sess.pop("_local_key", None)
+        sess.pop("_local_priv", None)
+        save_session(sess)
+    ok("Locked 🔒  (run 'lp unlock' to re-cache keys without re-logging in)")
+
+
+@cli.command(name="unlock")
+def unlock_cmd():
+    """Re-cache keys from master password after a lock."""
+    sess = require_session()
+    from lp.crypto import derive_keys, decrypt_private_key
+    pw = get_master_password()
+    keys = derive_keys(pw, sess["argon2_params"])
+    try:
+        priv_key = decrypt_private_key(sess["encrypted_private_key"], keys["enc_key"])
+    except Exception:
+        raise click.ClickException("Wrong master password")
+    save_session(cache_private_key(sess, priv_key))
+    ok("Unlocked 🔓")
+
+
+@cli.command()
+def status():
+    """Show current auth status."""
+    sess = load_session()
+    if not sess:
+        click.echo("Not logged in.")
+        return
+    ok(f"Logged in as {sess['email']}")
+    info(f"Server: {sess['server']}")
+    info(f"Plan:   {sess.get('plan', 'unknown')}")
+    cfg = load_config()
+    if cfg.get("default_vault"):
+        info(f"Vault:  {cfg['default_vault']} (default)")
+    # Verify token is still valid against server
+    try:
+        me = make_client(sess).me()
+        info(f"Token:  valid (plan: {me.get('plan_name', me.get('plan'))})")
+    except APIError as e:
+        warn(f"Token may be expired or invalid ({e}). Run: lp login")
+
+
+# ── Vault management ───────────────────────────────────────────────────────────
+
+@cli.group()
+def vault():
+    """Manage vaults."""
+
+
+@vault.command("list")
+def vault_list():
+    """List all vaults with decrypted names."""
+    sess    = require_session()
+    client  = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    try:
+        vaults = client.list_vaults()
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    if not vaults:
+        warn("No vaults. Create one: lp vault new <name>")
+        return
+
+    cfg = load_config()
+    default_id = cfg.get("default_vault")
+
+    click.echo()
+    for v in vaults:
+        name = _vault_display_name(v, priv, pub, client)
+        marker = click.style(" ◀ default", fg="cyan") if v["id"] == default_id else ""
+        role   = click.style(v["user_role"], fg="yellow")
+        click.echo(f"  {CRED_TYPE_EMOJI.get(v['type'], '🔒')}  {name}  [{role}]  {v['id'][:8]}…{marker}")
+    click.echo()
+
+
+@vault.command("new")
+@click.argument("name")
+@click.option("--type", "vault_type", default="personal",
+              type=click.Choice(["personal", "space"]), show_default=True)
+def vault_new(name, vault_type):
+    """Create a new vault."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    import nacl.utils
+    vault_key = nacl.utils.random(32)
+    enc_vault_key = encrypt_vault_key(vault_key, pub, priv)
+    name_enc      = encrypt_text(name, vault_key)
+
+    try:
+        v = client.create_vault(name_enc, vault_type, enc_vault_key)
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    # Auto-select as default if first vault
+    cfg = load_config()
+    if not cfg.get("default_vault"):
+        cfg["default_vault"] = v["id"]
+        save_config(cfg)
+
+    ok(f"Created vault \"{name}\" ({v['id'][:8]}…)")
+
+
+@vault.command("use")
+@click.argument("name_or_id")
+def vault_use(name_or_id):
+    """Set default vault by name or ID prefix."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vaults = client.list_vaults()
+    match  = None
+    for v in vaults:
+        dec_name = _vault_display_name(v, priv, pub, client)
+        if v["id"].startswith(name_or_id) or dec_name.lower() == name_or_id.lower():
+            match = v
+            break
+
+    if not match:
+        raise click.ClickException(f"Vault not found: {name_or_id}")
+
+    cfg = load_config()
+    cfg["default_vault"] = match["id"]
+    save_config(cfg)
+    ok(f"Default vault set to: {_vault_display_name(match, priv, pub, client)}")
+
+
+# ── Credential commands ────────────────────────────────────────────────────────
+
+@cli.command("ls")
+@click.option("--vault", "vault_name", default=None, help="Vault name or ID")
+@click.option("--type", "cred_type", default=None,
+              type=click.Choice(["password", "otp", "note", "custom"]))
+def ls(vault_name, cred_type):
+    """List credentials in the default (or specified) vault."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vault_obj, vault_key = _resolve_vault(client, vault_name, priv, pub)
+
+    try:
+        creds = client.list_all_credentials(vault_obj["id"])
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    if not creds:
+        warn("No credentials. Add one: lp add")
+        return
+
+    if cred_type:
+        creds = [c for c in creds if c["type"] == cred_type]
+
+    click.echo()
+    w = len(str(len(creds)))
+    for i, c in enumerate(creds, 1):
+        try:
+            data = decrypt_json(c["encrypted_data"], vault_key)
+            name = data.get("name") or "(no name)"
+            user = data.get("username") or data.get("issuer") or ""
+            sub  = f"  {click.style(user, fg='bright_black')}" if user else ""
+        except Exception:
+            name = "(encrypted)"
+            sub  = ""
+        icon = CRED_TYPE_EMOJI.get(c["type"], "❓")
+        num  = click.style(f"{i:{w}d}", fg="bright_black")
+        ty   = click.style(c["type"], fg="cyan")
+        click.echo(f"  {num}  {icon}  {click.style(name, bold=True)}{sub}  [{ty}]")
+    click.echo()
+
+
+@cli.command("get")
+@click.argument("name_or_num")
+@click.option("--vault", "vault_name", default=None)
+@click.option("--field", default=None,
+              help="Show only this field (password, username, url, notes, secret)")
+def get_cred(name_or_num, vault_name, field):
+    """Show a credential (decrypted)."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vault_obj, vault_key = _resolve_vault(client, vault_name, priv, pub)
+
+    try:
+        creds = client.list_all_credentials(vault_obj["id"])
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    cred_raw, data = _resolve_cred(creds, name_or_num, vault_key)
+    client.log_action(vault_obj["id"], cred_raw["id"], "viewed")
+
+    if field:
+        val = data.get(field)
+        if val is None:
+            raise click.ClickException(f"Field '{field}' not found")
+        click.echo(val)
+        return
+
+    click.echo()
+    _print_credential(data, cred_raw["type"])
+    click.echo()
+
+
+def _print_credential(data: dict, cred_type: str) -> None:
+    def row(label, value, secret=False):
+        if not value:
+            return
+        if secret:
+            import sys
+            is_tty = sys.stdin.isatty() and sys.stdout.isatty()
+            if is_tty:
+                click.echo(f"  {click.style(label+':', fg='bright_black', bold=True):<18} "
+                           f"{click.style('••••••••', fg='bright_black')}  "
+                           f"[Enter=reveal  c=copy]", nl=False)
+                try:
+                    ch = click.getchar(echo=False)
+                    click.echo()
+                    if ch in ("\r", "\n", ""):
+                        click.echo(f"  {click.style(label+':', fg='bright_black', bold=True):<18} {value}")
+                    elif ch.lower() == "c":
+                        _clipboard_clear(value)
+                    return
+                except OSError:
+                    click.echo()
+            click.echo(f"  {click.style(label+':', fg='bright_black', bold=True):<18} {click.style('••••••••', fg='bright_black')}")
+        else:
+            click.echo(f"  {click.style(label+':', fg='bright_black', bold=True):<18} {value}")
+
+    row("Name",     data.get("name"))
+    row("Username", data.get("username"))
+    row("Password", data.get("password"), secret=True)
+    row("URL",      data.get("url"))
+    row("Secret",   data.get("secret"), secret=True)
+    row("Issuer",   data.get("issuer"))
+    row("Notes",    data.get("notes"))
+    for f in data.get("custom_fields") or []:
+        row(f.get("label", "Field"), f.get("value"))
+
+
+@cli.command("copy")
+@click.argument("name_or_num")
+@click.option("--vault", "vault_name", default=None)
+@click.option("--field", default="password",
+              help="Field to copy (default: password)")
+def copy_cred(name_or_num, vault_name, field):
+    """Copy a credential field to clipboard (clears in 30s)."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vault_obj, vault_key = _resolve_vault(client, vault_name, priv, pub)
+
+    try:
+        creds = client.list_all_credentials(vault_obj["id"])
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    cred_raw, data = _resolve_cred(creds, name_or_num, vault_key)
+
+    val = data.get(field)
+    if not val:
+        raise click.ClickException(f"Field '{field}' is empty or not set")
+
+    _clipboard_clear(val)
+    client.log_action(vault_obj["id"], cred_raw["id"], "copied")
+
+
+@cli.command("add")
+@click.option("--type", "cred_type", default="password",
+              type=click.Choice(["password", "otp", "note", "custom"]), show_default=True)
+@click.option("--vault", "vault_name", default=None)
+def add_cred(cred_type, vault_name):
+    """Add a new credential (interactive)."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vault_obj, vault_key = _resolve_vault(client, vault_name, priv, pub)
+
+    click.echo(f"\n  Adding {cred_type} credential to vault...")
+    data: dict = {"name": None}
+
+    data["name"] = click.prompt("  Name / label")
+
+    if cred_type == "password":
+        data["username"] = click.prompt("  Username", default="")
+        pw_choice = click.prompt(
+            "  Password [Enter to generate]", default="", hide_input=False
+        )
+        if not pw_choice:
+            data["password"] = generate_password()
+            ok(f"Generated: {data['password']}")
+        else:
+            data["password"] = pw_choice
+        data["url"]   = click.prompt("  URL", default="")
+        data["notes"] = click.prompt("  Notes", default="")
+
+    elif cred_type == "otp":
+        data["secret"] = click.prompt("  TOTP secret")
+        data["issuer"] = click.prompt("  Issuer", default="")
+
+    elif cred_type == "note":
+        data["notes"] = click.prompt("  Note content")
+
+    elif cred_type == "custom":
+        data["username"] = click.prompt("  Username", default="")
+        data["password"] = click.prompt("  Password", default="", hide_input=True)
+        data["url"]      = click.prompt("  URL", default="")
+        fields = []
+        while click.confirm("  Add custom field?", default=False):
+            lbl = click.prompt("    Label")
+            val = click.prompt("    Value")
+            fields.append({"label": lbl, "value": val})
+        data["custom_fields"] = fields
+        data["notes"] = click.prompt("  Notes", default="")
+
+    name_enc = encrypt_text(data["name"], vault_key)
+    data_enc = encrypt_json(data, vault_key)
+
+    try:
+        client.create_credential(vault_obj["id"], cred_type, name_enc, data_enc)
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    ok(f"Created \"{data['name']}\"")
+
+
+@cli.command("edit")
+@click.argument("name_or_num")
+@click.option("--vault", "vault_name", default=None)
+def edit_cred(name_or_num, vault_name):
+    """Edit a credential (shows current values, Enter to keep)."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vault_obj, vault_key = _resolve_vault(client, vault_name, priv, pub)
+
+    try:
+        creds = client.list_all_credentials(vault_obj["id"])
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    cred_raw, data = _resolve_cred(creds, name_or_num, vault_key)
+    cred_type = cred_raw["type"]
+
+    click.echo(f"\n  Editing \"{data.get('name')}\" (Enter to keep current value)\n")
+
+    data["name"] = click.prompt("  Name", default=data.get("name", ""))
+
+    if cred_type == "password":
+        data["username"] = click.prompt("  Username", default=data.get("username", ""))
+        new_pw = click.prompt("  Password [Enter to keep]", default="", hide_input=True)
+        if new_pw:
+            data["password"] = new_pw
+        data["url"]   = click.prompt("  URL",   default=data.get("url", ""))
+        data["notes"] = click.prompt("  Notes", default=data.get("notes", ""))
+
+    elif cred_type == "otp":
+        data["secret"] = click.prompt("  TOTP secret", default=data.get("secret", ""))
+        data["issuer"] = click.prompt("  Issuer",      default=data.get("issuer", ""))
+
+    elif cred_type == "note":
+        data["notes"] = click.prompt("  Note content", default=data.get("notes", ""))
+
+    name_enc = encrypt_text(data["name"], vault_key)
+    data_enc = encrypt_json(data, vault_key)
+
+    try:
+        client.update_credential(vault_obj["id"], cred_raw["id"], name_enc, data_enc)
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    ok(f"Updated \"{data['name']}\"")
+
+
+@cli.command("rm")
+@click.argument("name_or_num")
+@click.option("--vault", "vault_name", default=None)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+def rm_cred(name_or_num, vault_name, yes):
+    """Delete a credential."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vault_obj, vault_key = _resolve_vault(client, vault_name, priv, pub)
+
+    try:
+        creds = client.list_all_credentials(vault_obj["id"])
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    cred_raw, data = _resolve_cred(creds, name_or_num, vault_key)
+    name = data.get("name") or name_or_num
+
+    if not yes and not click.confirm(f"  Delete \"{name}\"?"):
+        info("Cancelled")
+        return
+
+    try:
+        client.delete_credential(vault_obj["id"], cred_raw["id"])
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    ok(f"Deleted \"{name}\"")
+
+
+# ── Utilities ─────────────────────────────────────────────────────────────────
+
+@cli.command("otp")
+@click.argument("name_or_num")
+@click.option("--vault", "vault_name", default=None)
+@click.option("--copy", "-c", "do_copy", is_flag=True, help="Copy code to clipboard")
+def otp_cmd(name_or_num, vault_name, do_copy):
+    """Generate a TOTP code for a stored OTP credential."""
+    import time as _time
+    try:
+        import pyotp
+    except ImportError:
+        raise click.ClickException("pyotp is required: pip install pyotp")
+
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    vault_obj, vault_key = _resolve_vault(client, vault_name, priv, pub)
+
+    try:
+        creds = client.list_all_credentials(vault_obj["id"])
+    except APIError as e:
+        raise click.ClickException(str(e))
+
+    otp_creds = [c for c in creds if c["type"] == "otp"]
+    if not otp_creds:
+        raise click.ClickException("No OTP credentials in this vault")
+
+    cred_raw, data = _resolve_cred(otp_creds, name_or_num, vault_key)
+
+    secret = data.get("secret", "").replace(" ", "")
+    if not secret:
+        raise click.ClickException("OTP secret is empty")
+
+    try:
+        totp   = pyotp.TOTP(secret)
+        code   = totp.now()
+        remaining = 30 - (int(_time.time()) % 30)
+    except Exception as e:
+        raise click.ClickException(f"Failed to generate OTP: {e}")
+
+    name = data.get("name") or data.get("issuer") or "OTP"
+    click.echo()
+    click.echo(f"  {click.style(name, bold=True)}")
+    click.echo(f"  {click.style(code, fg='green', bold=True)}  "
+               f"{click.style(f'(valid {remaining}s)', fg='bright_black')}")
+    click.echo()
+
+    if do_copy:
+        _clipboard_clear(code, seconds=remaining)
+    client.log_action(vault_obj["id"], cred_raw["id"], "copied")
+
+
+@cli.command("generate")
+@click.option("--length", "-l", default=20, show_default=True, help="Password length")
+@click.option("--no-symbols", is_flag=True, help="Only alphanumeric")
+@click.option("--copy", "-c", "do_copy", is_flag=True, help="Copy to clipboard")
+@click.option("--count", "-n", default=1, show_default=True, help="How many to generate")
+def generate(length, no_symbols, do_copy, count):
+    """Generate cryptographically random password(s)."""
+    passwords = [generate_password(length, symbols=not no_symbols) for _ in range(count)]
+    for pw in passwords:
+        click.echo(f"  {pw}")
+    if do_copy and count == 1:
+        _clipboard_clear(passwords[0])
+
+
+@cli.command("export")
+@click.option("--vault", "vault_name", default=None, help="Vault name or ID (default: all vaults)")
+@click.option("--out", "-o", default=None, help="Output file (default: stdout)")
+@click.option("--format", "fmt", default="json", type=click.Choice(["json", "csv"]), show_default=True)
+def export_cmd(vault_name, out, fmt):
+    """Export credentials as decrypted JSON or CSV."""
+    sess   = require_session()
+    client = make_client(sess)
+    _, priv, pub = unlock(sess)
+
+    if vault_name:
+        target_vaults = [_resolve_vault(client, vault_name, priv, pub)[0]]
+    else:
+        target_vaults = client.list_vaults()
+
+    rows = []
+    for v in target_vaults:
+        try:
+            vault_key = _load_vault_key(client, v, priv, pub)
+            vault_dec_name = decrypt_text(v["name_encrypted"], vault_key)
+        except Exception:
+            continue
+        creds = client.list_all_credentials(v["id"])
+        for c in creds:
+            try:
+                data = decrypt_json(c["encrypted_data"], vault_key)
+                data["_vault"] = vault_dec_name
+                data["_type"]  = c["type"]
+                data["_id"]    = c["id"]
+                rows.append(data)
+            except Exception:
+                pass
+
+    if fmt == "json":
+        output = json.dumps(rows, indent=2, ensure_ascii=False)
+    else:
+        import csv, io
+        fields = ["_vault", "_type", "name", "username", "password", "url", "notes", "secret", "issuer", "_id"]
+        buf = io.StringIO()
+        w = csv.DictWriter(buf, fieldnames=fields, extrasaction="ignore")
+        w.writeheader()
+        w.writerows(rows)
+        output = buf.getvalue()
+
+    if out:
+        with open(out, "w", encoding="utf-8") as f:
+            f.write(output)
+        ok(f"Exported {len(rows)} credentials to {out}")
+    else:
+        click.echo(output)

lp/crypto.py

@@ -0,0 +1,143 @@
+"""
+Zero-knowledge crypto — byte-compatible with the JavaScript frontend.
+
+JS uses TweetNaCl + @noble/hashes. Python uses PyNaCl + argon2-cffi + cryptography.
+Both implement the same NaCl spec, so ciphertext produced by one decrypts in the other.
+
+Storage format for all encrypted blobs:
+  base64( nonce(24 bytes) + ciphertext(MAC_16 + plaintext) )
+"""
+
+import base64
+import os
+
+import nacl.secret
+import nacl.public
+import nacl.utils
+from argon2.low_level import hash_secret_raw, Type
+from cryptography.hazmat.primitives.hashes import SHA256
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF as _HKDF
+
+
+# ── Encoding ──────────────────────────────────────────────────────────────────
+
+def b64_enc(data: bytes) -> str:
+    return base64.b64encode(data).decode()
+
+def b64_dec(s: str) -> bytes:
+    return base64.b64decode(s)
+
+
+# ── HKDF (SHA-256) — matches @noble/hashes hkdf(sha256, ...) ─────────────────
+
+def hkdf(ikm: bytes, salt: bytes, info: bytes, length: int) -> bytes:
+    h = _HKDF(algorithm=SHA256(), length=length, salt=salt, info=info)
+    return h.derive(ikm)
+
+
+# ── Key derivation — matches src/crypto/index.js deriveKeys() ─────────────────
+
+def derive_keys(password: str, argon2_params: dict) -> dict:
+    """
+    Derive encKey + authVerifier from master password + stored argon2 params.
+    Must produce identical output to the JavaScript deriveKeys() function.
+    """
+    salt = b64_dec(argon2_params["salt"])
+
+    master = hash_secret_raw(
+        secret=password.encode(),
+        salt=salt,
+        time_cost=argon2_params["iterations"],
+        memory_cost=argon2_params["memory"],
+        parallelism=argon2_params["parallelism"],
+        hash_len=64,
+        type=Type.ID,
+    )
+
+    enc_key    = hkdf(master, salt, b"lockedpass-enc-v1",  32)
+    auth_bytes = hkdf(master, salt, b"lockedpass-auth-v1", 32)
+
+    return {
+        "master_key":    master,
+        "enc_key":       enc_key,
+        "auth_verifier": b64_enc(auth_bytes),
+    }
+
+
+# ── Private key (nacl.secretbox) ──────────────────────────────────────────────
+
+def decrypt_private_key(encrypted_b64: str, enc_key: bytes) -> bytes:
+    data = b64_dec(encrypted_b64)
+    nonce = data[:nacl.secret.SecretBox.NONCE_SIZE]
+    ct    = data[nacl.secret.SecretBox.NONCE_SIZE:]
+    return nacl.secret.SecretBox(enc_key).decrypt(ct, nonce)
+
+
+# ── Vault key (nacl.box — X25519 DH) ─────────────────────────────────────────
+
+def decrypt_vault_key(encrypted_b64: str, sender_pub_key: bytes, recipient_sec_key: bytes) -> bytes:
+    data = b64_dec(encrypted_b64)
+    nonce = data[:nacl.public.Box.NONCE_SIZE]
+    ct    = data[nacl.public.Box.NONCE_SIZE:]
+    box   = nacl.public.Box(nacl.public.PrivateKey(recipient_sec_key),
+                            nacl.public.PublicKey(sender_pub_key))
+    return box.decrypt(ct, nonce)
+
+
+def encrypt_vault_key(vault_key: bytes, recipient_pub_key: bytes, sender_sec_key: bytes) -> str:
+    nonce = nacl.utils.random(nacl.public.Box.NONCE_SIZE)
+    box   = nacl.public.Box(nacl.public.PrivateKey(sender_sec_key),
+                            nacl.public.PublicKey(recipient_pub_key))
+    ct    = box.encrypt(vault_key, nonce).ciphertext
+    return b64_enc(nonce + ct)
+
+
+# ── Vault contents (nacl.secretbox — XSalsa20-Poly1305) ──────────────────────
+
+def decrypt_text(encrypted_b64: str, vault_key: bytes) -> str:
+    data  = b64_dec(encrypted_b64)
+    nonce = data[:nacl.secret.SecretBox.NONCE_SIZE]
+    ct    = data[nacl.secret.SecretBox.NONCE_SIZE:]
+    return nacl.secret.SecretBox(vault_key).decrypt(ct, nonce).decode()
+
+
+def encrypt_text(text: str, vault_key: bytes) -> str:
+    nonce = nacl.utils.random(nacl.secret.SecretBox.NONCE_SIZE)
+    ct    = nacl.secret.SecretBox(vault_key).encrypt(text.encode(), nonce).ciphertext
+    return b64_enc(nonce + ct)
+
+
+def decrypt_json(encrypted_b64: str, vault_key: bytes) -> dict:
+    import json
+    return json.loads(decrypt_text(encrypted_b64, vault_key))
+
+
+def encrypt_json(obj: dict, vault_key: bytes) -> str:
+    import json
+    return encrypt_text(json.dumps(obj), vault_key)
+
+
+# ── Password generator ────────────────────────────────────────────────────────
+
+_LOWER   = "abcdefghijklmnopqrstuvwxyz"
+_UPPER   = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+_DIGITS  = "0123456789"
+_SYMBOLS = "!@#$%^&*()-_=+[]{}|;:,.<>?"
+
+def generate_password(length: int = 20, symbols: bool = True) -> str:
+    alphabet = _LOWER + _UPPER + _DIGITS
+    if symbols:
+        alphabet += _SYMBOLS
+    # Use os.urandom for cryptographic randomness
+    raw    = os.urandom(length * 4)
+    result = [alphabet[b % len(alphabet)] for b in raw][:length]
+    # Guarantee at least one of each character class
+    import random as _r
+    rng = _r.SystemRandom()
+    result[rng.randrange(length)] = rng.choice(_LOWER)
+    result[rng.randrange(length)] = rng.choice(_UPPER)
+    result[rng.randrange(length)] = rng.choice(_DIGITS)
+    if symbols:
+        result[rng.randrange(length)] = rng.choice(_SYMBOLS)
+    rng.shuffle(result)
+    return "".join(result)

lp/session.py

@@ -0,0 +1,105 @@
+"""
+Session management — persistent auth token + key material.
+
+~/.lockedpass/session.json stores the JWT and encrypted key material.
+Keys (encKey, privateKey) are derived on demand — never stored on disk.
+"""
+
+import json
+import os
+from pathlib import Path
+
+import click
+
+from lp.crypto import derive_keys, decrypt_private_key, b64_dec, b64_enc
+from lp.api import Client
+
+SESSION_DIR  = Path.home() / ".lockedpass"
+SESSION_FILE = SESSION_DIR / "session.json"
+CONFIG_FILE  = SESSION_DIR / "config.json"
+
+
+def save_session(data: dict) -> None:
+    SESSION_DIR.mkdir(mode=0o700, exist_ok=True)
+    SESSION_FILE.write_text(json.dumps(data, indent=2))
+    SESSION_FILE.chmod(0o600)
+
+
+def load_session() -> dict | None:
+    if not SESSION_FILE.exists():
+        return None
+    try:
+        return json.loads(SESSION_FILE.read_text())
+    except Exception:
+        return None
+
+
+def clear_session() -> None:
+    SESSION_FILE.unlink(missing_ok=True)
+
+
+def save_config(data: dict) -> None:
+    SESSION_DIR.mkdir(mode=0o700, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(data, indent=2))
+
+
+def load_config() -> dict:
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_FILE.read_text())
+    except Exception:
+        return {}
+
+
+def require_session() -> dict:
+    """Return session or abort with a helpful message."""
+    sess = load_session()
+    if not sess:
+        raise click.ClickException("Not logged in. Run: lp login")
+    return sess
+
+
+def get_master_password() -> str:
+    """Get master password from env var or prompt."""
+    pw = os.environ.get("LP_MASTER_PASSWORD")
+    if pw:
+        return pw
+    return click.prompt("Master password", hide_input=True)
+
+
+def cache_private_key(session: dict, priv_key: bytes) -> dict:
+    """Re-encrypt private key with a random local key and store in session."""
+    import nacl.secret
+    import nacl.utils
+    local_key = nacl.utils.random(nacl.secret.SecretBox.KEY_SIZE)
+    box = nacl.secret.SecretBox(local_key)
+    session = dict(session)
+    session["_local_key"] = b64_enc(local_key)
+    session["_local_priv"] = b64_enc(bytes(box.encrypt(priv_key)))
+    return session
+
+
+def unlock(session: dict) -> tuple[bytes, bytes, bytes]:
+    """
+    Returns (enc_key, private_key, public_key_bytes).
+    Uses locally-cached private key if available — no master password needed.
+    Falls back to prompting for master password.
+    """
+    if session.get("_local_key") and session.get("_local_priv"):
+        import nacl.secret
+        local_key = b64_dec(session["_local_key"])
+        box = nacl.secret.SecretBox(local_key)
+        priv_key = bytes(box.decrypt(b64_dec(session["_local_priv"])))
+        pub_key  = b64_dec(session["public_key"])
+        return b"", priv_key, pub_key
+
+    pw = get_master_password()
+    keys = derive_keys(pw, session["argon2_params"])
+    priv_key = decrypt_private_key(session["encrypted_private_key"], keys["enc_key"])
+    pub_key  = b64_dec(session["public_key"])
+    return keys["enc_key"], priv_key, pub_key
+
+
+def make_client(session: dict) -> Client:
+    return Client(session["server"], session["token"])