loz 0.2.0__py3-none-any.whl

loz/__init__.py

@@ -0,0 +1,10 @@
+"""
+loz - password manager
+"""
+
+__version__ = "0.2.0"
+__license__ = "BSD"
+__year__ = "2022-2026"
+__author__ = "Predrag Mandic"
+__author_email__ = "predrag@nul.one"
+__copyright__ = f"Copyright {__year__} {__author__} <{__author_email__}>"

loz/__main__.py

@@ -0,0 +1,395 @@
+"""loz main module."""
+
+import logging
+import sys
+from dataclasses import dataclass, field
+from getpass import getpass
+from os import path
+from typing import IO
+
+import click
+from click_aliases import ClickAliasedGroup
+from prompt_toolkit import prompt
+
+import loz as app
+from loz import loz
+from loz.exceptions import (
+    LozFileDoesNotExist,
+    LozIncompatibleFileVersion,
+    LozInvalidStorage,
+)
+from loz.models import ChangeRecord, StorageDict
+
+logger = logging.getLogger("loz")
+
+_DEFAULT_LOZ_FILE = path.expanduser("~/.loz")
+
+
+# ---------------------------------------------------------------------------
+# Runtime state dataclass  (stored in ctx.obj)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class LozState:
+    """Per-invocation CLI runtime state."""
+
+    loz_file: str = field(default=_DEFAULT_LOZ_FILE)
+    check_mode: bool = False
+    yes_mode: bool = False
+
+
+# ---------------------------------------------------------------------------
+# ANSI colour helpers
+# ---------------------------------------------------------------------------
+
+
+class color:
+    PURPLE = "\033[95m"
+    CYAN = "\033[96m"
+    DARKCYAN = "\033[36m"
+    BLUE = "\033[94m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    RED = "\033[91m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+    END = "\033[0m"
+
+
+# ---------------------------------------------------------------------------
+# CLI helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_state(ctx: click.Context) -> LozState:
+    """Return the :class:`LozState` attached to *ctx*."""
+    return ctx.ensure_object(LozState)
+
+
+def _load(state: LozState, warn: bool = True) -> StorageDict:
+    """Load the loz file; print a message and exit 1 on failure."""
+    try:
+        return loz.load(state.loz_file)
+    except LozFileDoesNotExist as e:
+        logger.debug(e)
+        if warn:
+            print("First time use. Run init command.")
+        sys.exit(1)
+    except LozIncompatibleFileVersion as e:
+        logger.debug(e)
+        if warn:
+            print(f"Update loz. {e}")
+        sys.exit(1)
+    except LozInvalidStorage as e:
+        logger.debug(e)
+        if warn:
+            print(
+                f"Lozfile is invalid and cannot be loaded. "
+                f"Inspect or delete {state.loz_file!r}. Detail: {e}"
+            )
+        sys.exit(1)
+
+
+def _confirm_change(state: LozState, change: ChangeRecord) -> bool:
+    if state.check_mode or state.yes_mode:
+        return True
+    if "-" not in change[0]:
+        # non-destructive change
+        return True
+    answer = input("Is this ok [Y/n]: ")
+    if answer.lower() in ["", "y", "yes"]:
+        print("Confirmed!")
+        return True
+    print("Abandoning changes.")
+    return False
+
+
+def _print_change(change: ChangeRecord) -> None:
+    col = color.GREEN
+    if "+" in change[0]:
+        col = color.YELLOW
+    if "-" in change[0]:
+        col = color.RED
+    line = (
+        f"{col}{change[0]} {color.BOLD}{change[1]}/{change[2]}"
+        f"{color.END} {col}{change[3]}{color.END}"
+    )
+    print(line)
+
+
+def _save(state: LozState, storage: StorageDict, change: ChangeRecord) -> None:
+    _print_change(change)
+    if not state.check_mode:
+        if _confirm_change(state, change):
+            loz.save(storage, state.loz_file)
+        return
+    print("Check mode is on, so nothing is really changed.")
+
+
+def _enter_password(storage: StorageDict) -> str:
+    while True:
+        password = getpass("enter password:")
+        if loz.validate_key(storage, password):
+            return password
+
+
+def _enter_new_password() -> str:
+    password: str | None = None
+    while password is None:
+        password = getpass("enter new password:")
+        if password != getpass("repeat:"):
+            print("passwords do not match")
+            password = None
+    return password
+
+
+# ---------------------------------------------------------------------------
+# CLI group
+# ---------------------------------------------------------------------------
+
+
+@click.group(cls=ClickAliasedGroup)
+@click.version_option(
+    version=app.__version__, message=f"%(prog)s %(version)s - {app.__copyright__}"
+)
+@click.option(
+    "-d",
+    "--debug",
+    is_flag=True,
+    help="Enable debug mode with output of each action in the log.",
+)
+@click.option(
+    "-c",
+    "--check",
+    is_flag=True,
+    help="Enable check mode that shows changes but changes nothing.",
+)
+@click.option(
+    "-y",
+    "--yes",
+    is_flag=True,
+    help="Answer yes to all questions.",
+)
+@click.option(
+    "-f",
+    "--file",
+    type=str,
+    default=_DEFAULT_LOZ_FILE,
+    help=f"Specify custom loz file. Defaults to: {_DEFAULT_LOZ_FILE}",
+)
+@click.pass_context
+def cli(ctx: click.Context, debug: bool, check: bool, yes: bool, file: str) -> None:
+    ctx.ensure_object(LozState)
+    state = _get_state(ctx)
+
+    # Configure logging once, inside CLI setup.
+    if not logging.root.handlers:
+        logging.basicConfig()
+    level = logging.DEBUG if debug else logging.WARNING
+    logging.getLogger("loz").setLevel(level)
+    if debug:
+        logger.info("debug mode is on")
+
+    state.check_mode = check
+    state.yes_mode = yes
+    state.loz_file = file
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.pass_context
+def init(ctx: click.Context) -> None:
+    "Initialize .loz file with master password."
+    state = _get_state(ctx)
+    change: ChangeRecord = ["", "", "", "Initialize lozfile with password."]
+    if path.isfile(state.loz_file):
+        change = ["+-", "", "", "Overwrite lozfile and reinitialize."]
+    password = _enter_new_password()
+    storage = loz.init(password)
+    _save(state, storage, change)
+
+
+@cli.command()
+@click.pass_context
+def passwd(ctx: click.Context) -> None:
+    "Change password and re-encrypt storage."
+    state = _get_state(ctx)
+    storage = _load(state)
+    _enter_password(storage)  # validates key; loads private key into global pto
+    new_password = _enter_new_password()
+    new_storage = loz.change_password(storage, new_password)
+    change: ChangeRecord = ["-+", "", "", "Change master password."]
+    _save(state, new_storage, change)
+
+
+@cli.command(aliases=["set"])
+@click.argument("domain")
+@click.argument("user")
+@click.pass_context
+def add(ctx: click.Context, domain: str, user: str) -> None:
+    "Set secret for 'domain user' pair."
+    state = _get_state(ctx)
+    storage = _load(state)
+    secret = prompt(
+        "Write multiline secret. Alt+Return to save:\n", default="", multiline=True
+    )
+    change = loz.store(storage, domain, user, secret)
+    _save(state, storage, change)
+
+
+@cli.command()
+@click.argument("domain")
+@click.argument("user")
+@click.pass_context
+def make(ctx: click.Context, domain: str, user: str) -> None:
+    "Make random secret for 'domain user' pair."
+    state = _get_state(ctx)
+    storage = _load(state)
+    change = loz.make(storage, domain, user)
+    _save(state, storage, change)
+
+
+@cli.command()
+@click.argument("domain")
+@click.argument("user")
+@click.pass_context
+def get(ctx: click.Context, domain: str, user: str) -> None:
+    "Get secret for 'domain user' pair."
+    state = _get_state(ctx)
+    storage = _load(state)
+    if not loz.exists(storage, domain, user):
+        print(f"user not found: {color.BOLD}{domain}/{user}{color.END}")
+        sys.exit(1)
+    _enter_password(storage)  # validates key; loads private key into global pto
+    secret = loz.get(storage, domain, user)
+    print(secret)
+
+
+@cli.command(aliases=["del"])
+@click.argument("domain")
+@click.argument("user", required=False, default=None)
+@click.pass_context
+def rm(ctx: click.Context, domain: str, user: str | None) -> None:
+    "Delete user from domain or whole domain."
+    state = _get_state(ctx)
+    storage = _load(state)
+    change = loz.rm(storage, domain, user)
+    _save(state, storage, change)
+
+
+@cli.command()
+@click.argument("domain")
+@click.pass_context
+def show(ctx: click.Context, domain: str) -> None:
+    "List all secrets in one domain."
+    state = _get_state(ctx)
+    storage = _load(state)
+    if not loz.exists(storage, domain):
+        print(f"domain not found: {color.BOLD}{domain}{color.END}")
+        sys.exit(1)
+    _enter_password(storage)  # validates key; loads private key into global pto
+    for dom, user, secret in loz.show(storage, domain):
+        print(f"\n{color.BOLD}{dom}/{user}{color.END}\n{secret}")
+
+
+@cli.command()
+@click.argument("domain", required=False, default=None)
+@click.pass_context
+def ls(ctx: click.Context, domain: str | None) -> None:
+    "List all storage or users under one domain."
+    state = _get_state(ctx)
+    storage = _load(state)
+    results = loz.ls(storage, domain)
+    print("\n".join(results))
+
+
+@cli.command(aliases=["search"])
+@click.argument("word")
+@click.pass_context
+def find(ctx: click.Context, word: str) -> None:
+    "List storage and users that contain the search phrase."
+    state = _get_state(ctx)
+    storage = _load(state)
+    results = loz.find(storage, word)
+    for res in results:
+        bold = f"{color.BOLD}{res[-1]}{color.END}"
+        res[-1] = bold
+        print("/".join(res))
+
+
+@cli.command("import")
+@click.argument("csv_file", type=click.File("r"))
+@click.pass_context
+def import_csv(ctx: click.Context, csv_file: IO[str]) -> None:
+    "Import CSV file and merge with existing lozfile."
+    state = _get_state(ctx)
+    storage = _load(state)
+    total_change: ChangeRecord = ["", "", "", "total change"]
+    for change in loz.import_csv(storage, csv_file):
+        _print_change(change)
+        total_change[0] += change[0]
+    if not total_change[0]:
+        print("\bNo changes detected.")
+        return
+    _save(state, storage, total_change)
+
+
+@cli.command("export")
+@click.argument("csv_file", type=click.File("w"), required=False, default=sys.stdout)
+@click.pass_context
+def export_csv(ctx: click.Context, csv_file: IO[str]) -> None:
+    "Export plaintext storage and print to output or save to CSV file."
+    state = _get_state(ctx)
+    storage = _load(state)
+    _enter_password(storage)  # validates key; loads private key into global pto
+    loz.export_csv(storage, csv_file)
+
+
+@cli.command()
+def bash_completion() -> None:
+    "Generate bash completion file contents."
+    completion = (
+        f"_loz()\n"
+        f"{{\n"
+        f"    local cur prev\n"
+        f"    COMPREPLY=()\n"
+        f'    cur="${{COMP_WORDS[COMP_CWORD]}}"\n'
+        f'    prev="${{COMP_WORDS[COMP_CWORD - 1]}}"\n'
+        f"    words=\n"
+        f"\n"
+        f'    if [ "$COMP_CWORD" == "1" ]; then\n'
+        f'        words="{" ".join([n for n, v in cli.commands.items()])}"\n'
+        f"    fi\n"
+        f"\n"
+        f'    cmd="${{COMP_WORDS[1]}}"\n'
+        f'    case "$cmd" in\n'
+        f"        get|set|add|make|rm|del)\n"
+        f'            case "$COMP_CWORD" in\n'
+        f"                2)\n"
+        f'                    words="$(loz ls)"\n'
+        f"                    ;;\n"
+        f"                3)\n"
+        f'                    words="$(loz ls $prev)"\n'
+        f"                    ;;\n"
+        f"            esac\n"
+        f"            ;;\n"
+        f"        show|ls)\n"
+        f'            if [ "$COMP_CWORD" == "2" ]; then\n'
+        f'                words="$(loz ls)"\n'
+        f"            fi\n"
+        f"            ;;\n"
+        f"    esac\n"
+        f'    COMPREPLY=( $(compgen -W "${{words}}" -- ${{cur}}) )\n'
+        f"}}\n"
+        f"complete -F _loz loz\n"
+    )
+    print(completion)
+
+
+if __name__ == "__main__":
+    cli()

loz/cry.py

@@ -0,0 +1,130 @@
+"""Cryptographic primitives for loz."""
+
+import os
+import secrets
+import string
+from base64 import b64decode, b64encode, urlsafe_b64encode
+
+from cryptography.fernet import Fernet
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey, RSAPublicKey
+from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+
+key_size = 4096
+msg_size = 446
+salt_size = 16
+
+_SELECTABLE_PUNCTUATION = "+-=_&?/\\%#@~,."
+_PASSWORD_CHARS = (
+    string.ascii_lowercase
+    + string.ascii_uppercase
+    + string.digits
+    + _SELECTABLE_PUNCTUATION
+)
+
+
+class Pto:
+    """cry.Pto see what I did there?"""
+
+    private_key: RSAPrivateKey
+    public_key: RSAPublicKey
+
+    def __init__(self, pem: str, password: str | None = None) -> None:
+        if password:
+            # pem is private key
+            password_bytes = password.encode()
+            raw = b64decode(pem.encode())
+            salt = raw[:salt_size]
+            encrypted_pvt = raw[salt_size:]
+            fernet_key = Scrypt(salt=salt, length=32, n=2**18, r=8, p=1).derive(
+                password_bytes
+            )
+            fernet = Fernet(urlsafe_b64encode(fernet_key))
+            pvt = fernet.decrypt(encrypted_pvt)
+            loaded_pvt = serialization.load_pem_private_key(
+                data=pvt,
+                backend=default_backend(),
+                password=None,
+            )
+            if not isinstance(loaded_pvt, RSAPrivateKey):
+                raise TypeError(
+                    f"Expected RSAPrivateKey, got {type(loaded_pvt).__name__!r}."
+                )
+            self.private_key = loaded_pvt
+            self.public_key = self.private_key.public_key()
+            return
+        # pem is public key
+        loaded_pub = serialization.load_pem_public_key(
+            data=pem.encode(), backend=default_backend()
+        )
+        if not isinstance(loaded_pub, RSAPublicKey):
+            raise TypeError(
+                f"Expected RSAPublicKey, got {type(loaded_pub).__name__!r}."
+            )
+        self.public_key = loaded_pub
+
+    def encrypt(self, message: str) -> str:
+        bmsg = message.encode()
+        chunks = [bmsg[i : i + msg_size] for i in range(0, len(bmsg), msg_size)]
+        ciphertext = bytearray()
+        for chunk in chunks:
+            ciphertext += self.public_key.encrypt(
+                chunk,
+                padding.OAEP(
+                    mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                    algorithm=hashes.SHA256(),
+                    label=None,
+                ),
+            )
+        return b64encode(bytes(ciphertext)).decode("utf-8")
+
+    def decrypt(self, ciphertext: str) -> str:
+        bciph = b64decode(ciphertext.encode())
+        block = key_size // 8
+        chunks = [bciph[i : i + block] for i in range(0, len(bciph), block)]
+        message = bytearray()
+        for chunk in chunks:
+            message += self.private_key.decrypt(
+                chunk,
+                padding.OAEP(
+                    mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                    algorithm=hashes.SHA256(),
+                    label=None,
+                ),
+            )
+        return bytes(message).decode("utf-8")
+
+
+def generate_key_pair(password: str) -> tuple[str, str]:
+    """Generate an RSA key pair protected by *password*.
+
+    Returns ``(serialized_pvt, serialized_pub)`` -- both base64/PEM strings.
+    """
+    password_bytes = password.encode()
+    private_key = rsa.generate_private_key(
+        public_exponent=65537, key_size=key_size, backend=default_backend()
+    )
+    public_key = private_key.public_key()
+    pem_pvt = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    pem_pub = public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    salt = os.urandom(salt_size)
+    fernet_key = Scrypt(salt=salt, length=32, n=2**18, r=8, p=1).derive(password_bytes)
+    fernet = Fernet(urlsafe_b64encode(fernet_key))
+    encrypted_pvt = fernet.encrypt(pem_pvt)
+    serialized_pvt = b64encode(salt + encrypted_pvt).decode("utf-8")
+    serialized_pub = pem_pub.decode("utf-8")
+    return (serialized_pvt, serialized_pub)
+
+
+def make_password(length: int = 16) -> str:
+    """Generate a cryptographically secure random password of *length* characters."""
+    return "".join(secrets.choice(_PASSWORD_CHARS) for _ in range(length))

loz/exceptions.py

@@ -0,0 +1,17 @@
+"""loz custom exceptions."""
+
+
+class LozException(Exception):
+    """Generic loz exception."""
+
+
+class LozIncompatibleFileVersion(LozException):
+    """Current loz version does not support existing lozfile version."""
+
+
+class LozFileDoesNotExist(LozException):
+    """Lozfile not found."""
+
+
+class LozInvalidStorage(LozException):
+    """Lozfile exists but contains malformed JSON or an invalid storage schema."""

loz/loz.py

@@ -0,0 +1,422 @@
+"""loz core functions."""
+
+import csv
+import io
+import json
+import logging
+import os
+import tempfile
+from collections.abc import Generator
+from pathlib import Path
+from typing import IO, cast
+
+from cryptography.fernet import InvalidToken
+from packaging.version import InvalidVersion, Version
+
+from loz import cry
+from loz.exceptions import (
+    LozFileDoesNotExist,
+    LozIncompatibleFileVersion,
+    LozInvalidStorage,
+)
+from loz.models import ChangeRecord, DataSection, EntryRecord, StorageDict
+
+logger = logging.getLogger("loz")
+storage_version = "1.0"
+
+# Module-level Pto instance; set after load() or validate_key().
+pto: cry.Pto | None = None
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_pto() -> cry.Pto:
+    """Return the current unlocked :class:`cry.Pto` or raise *RuntimeError*.
+
+    Use this instead of bare ``assert pto is not None`` in production paths.
+    """
+    if pto is None:
+        raise RuntimeError(
+            "Crypto state not initialised; call load() then validate_key() first."
+        )
+    return pto
+
+
+def _validate_storage_schema(raw: object) -> StorageDict:
+    """Validate *raw* against the expected storage schema.
+
+    Raises :class:`~loz.exceptions.LozInvalidStorage` with a descriptive
+    message if any structural requirement is violated.  Returns the coerced
+    :class:`~loz.models.StorageDict` on success.
+    """
+    if not isinstance(raw, dict):
+        raise LozInvalidStorage("Storage root must be a JSON object.")
+
+    for required_key in ("version", "pvt", "pub", "data"):
+        if required_key not in raw:
+            raise LozInvalidStorage(
+                f"Storage is missing required key: '{required_key}'."
+            )
+
+    if not isinstance(raw["version"], str):
+        got = type(raw["version"]).__name__
+        raise LozInvalidStorage(f"Storage 'version' must be a string, got {got!r}.")
+    if not isinstance(raw["pvt"], str):
+        raise LozInvalidStorage(
+            f"Storage 'pvt' must be a string, got {type(raw['pvt']).__name__!r}."
+        )
+    if not isinstance(raw["pub"], str):
+        raise LozInvalidStorage(
+            f"Storage 'pub' must be a string, got {type(raw['pub']).__name__!r}."
+        )
+
+    data = raw["data"]
+    if not isinstance(data, dict):
+        raise LozInvalidStorage(
+            f"Storage 'data' must be a JSON object, got {type(data).__name__!r}."
+        )
+    for domain_key, domain_val in data.items():
+        if not isinstance(domain_key, str):
+            raise LozInvalidStorage(
+                f"Storage 'data' domain key must be a string, got {domain_key!r}."
+            )
+        if not isinstance(domain_val, dict):
+            raise LozInvalidStorage(
+                f"Storage 'data[{domain_key!r}]' must be a JSON object, "
+                f"got {type(domain_val).__name__!r}."
+            )
+        for user_key, ciphertext in domain_val.items():
+            if not isinstance(user_key, str):
+                raise LozInvalidStorage(
+                    f"Storage 'data[{domain_key!r}]' user key must be a string, "
+                    f"got {user_key!r}."
+                )
+            if not isinstance(ciphertext, str):
+                raise LozInvalidStorage(
+                    f"Storage 'data[{domain_key!r}][{user_key!r}]' ciphertext "
+                    f"must be a string, got {type(ciphertext).__name__!r}."
+                )
+
+    # Safe cast - structure has been verified above.
+    return cast(StorageDict, raw)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def load(loz_file: str | Path) -> StorageDict:
+    """Load a .loz file and return the validated storage dict.
+
+    Raises
+    ------
+    LozFileDoesNotExist
+        When *loz_file* does not exist.
+    LozInvalidStorage
+        When the file is not valid JSON or does not match the storage schema.
+    LozIncompatibleFileVersion
+        When the file was created by a newer version of loz.
+    """
+    global pto
+    loz_path = Path(loz_file)
+    if not loz_path.is_file():
+        raise LozFileDoesNotExist(f"No loz file found at {loz_file}.")
+    logger.debug("opening %s", loz_file)
+
+    try:
+        raw: object = json.loads(loz_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LozInvalidStorage(
+            f"Lozfile at {loz_file} contains invalid JSON: {exc}"
+        ) from exc
+
+    storage = _validate_storage_schema(raw)
+    logger.debug("loaded storage from %s", loz_file)
+
+    try:
+        file_version = Version(storage["version"])
+        app_version = Version(storage_version)
+    except InvalidVersion as exc:
+        raise LozInvalidStorage(
+            f"Lozfile version value {storage['version']!r} is not a valid version "
+            f"string: {exc}"
+        ) from exc
+
+    if file_version > app_version:
+        raise LozIncompatibleFileVersion(
+            f"Found lozfile version {storage['version']} but "
+            f"supports up to {storage_version}."
+        )
+
+    try:
+        pto = cry.Pto(storage["pub"])
+    except (TypeError, ValueError) as exc:
+        raise LozInvalidStorage(
+            "Lozfile contains an invalid public encryption key."
+        ) from exc
+    return storage
+
+
+def _atomic_write(loz_path: Path, text: str) -> None:
+    """Write *text* to *loz_path* atomically on POSIX systems.
+
+    The write goes to a sibling temporary file which is fsynced and then
+    renamed into place, so the original file is never truncated if the write
+    fails.  Permissions are set to 0o600 before the rename.
+    """
+    dir_path = loz_path.parent
+    fd, tmp_path_str = tempfile.mkstemp(dir=dir_path, suffix=".loz.tmp")
+    tmp_path = Path(tmp_path_str)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+            fh.flush()
+            os.fsync(fh.fileno())
+        tmp_path.chmod(0o600)
+        tmp_path.rename(loz_path)
+    except Exception:
+        # Clean up the temp file on any failure; suppress secondary errors.
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+
+
+def save(storage: StorageDict, loz_file: str | Path) -> None:
+    """Save *storage* as a pretty-printed UTF-8 JSON .loz file.
+
+    The write is atomic on POSIX: the existing file is never truncated if
+    writing fails.  The resulting file has permissions 0600.
+    """
+    loz_path = Path(loz_file)
+    logger.debug("opening %s", loz_file)
+    storage["version"] = storage_version
+    _atomic_write(loz_path, json.dumps(storage, indent=4))
+    logger.debug("storage written to %s", loz_file)
+
+
+def validate_key(storage: StorageDict, password: str | None = None) -> bool:
+    """Try to unlock storage with *password*; store key globally for later use.
+
+    Only expected crypto / password-decoding failures return ``False``.
+    Unexpected errors (e.g. programming mistakes, schema bugs) are re-raised.
+    A failed validation clears the global *pto* so a prior successful unlock
+    cannot be reused.
+    """
+    global pto
+    # Expected crypto failure types from the cryptography library.
+    _CRYPTO_ERRORS = (
+        InvalidToken,
+        ValueError,
+        TypeError,
+        UnicodeDecodeError,
+    )
+    try:
+        logger.debug("validating password")
+        pto = cry.Pto(storage["pvt"], password)
+        return True
+    except _CRYPTO_ERRORS:
+        logger.debug("password validation failed (expected crypto error)")
+        pto = None
+        return False
+    except Exception:
+        # Unexpected error - clear state then re-raise.
+        pto = None
+        raise
+
+
+def init(password: str) -> StorageDict:
+    """Initialize a new storage dict protected by *password*."""
+    pvt, pub = cry.generate_key_pair(password)
+    storage: StorageDict = {
+        "version": storage_version,
+        "pvt": pvt,
+        "pub": pub,
+        "data": {},
+    }
+    return storage
+
+
+def export_csv(storage: StorageDict, csv_file: IO[str] | None = None) -> str | None:
+    """Export plaintext storage to *csv_file* or return contents as a string."""
+    buf: io.StringIO | None = None
+    if csv_file is None:
+        buf = io.StringIO()
+        csv_file = buf
+    writer = csv.writer(
+        csv_file,
+        delimiter=" ",
+        quotechar="|",
+        quoting=csv.QUOTE_MINIMAL,
+        lineterminator="\n",
+    )
+    for row in get_all(storage):
+        writer.writerow(row)
+    if buf is not None:
+        return buf.getvalue()
+    return None
+
+
+def import_csv(
+    storage: StorageDict, csv_file: IO[str]
+) -> Generator[ChangeRecord, None, None]:
+    """Import rows from *csv_file* into *storage*, yielding each change list.
+
+    All rows are pre-validated before any mutations are applied.  If any row
+    does not have exactly three fields a :class:`ValueError` is raised with the
+    1-based row number and no changes are made to *storage*.
+    """
+    reader = csv.reader(
+        csv_file,
+        delimiter=" ",
+        quotechar="|",
+        quoting=csv.QUOTE_MINIMAL,
+        lineterminator="\n",
+    )
+    rows = list(reader)
+    for i, row in enumerate(rows, start=1):
+        if len(row) != 3:
+            raise ValueError(
+                f"import_csv: row {i} has {len(row)} field(s); expected exactly 3."
+            )
+    # All rows validated - now mutate.
+    for row in rows:
+        domain, user, secret = row[0], row[1], row[2]
+        change = store(storage, domain, user, secret)
+        yield change
+
+
+def change_password(storage: StorageDict, new_pass: str) -> StorageDict:
+    """Re-encrypt all secrets under *new_pass* and return the new storage dict."""
+    pvt, pub = cry.generate_key_pair(new_pass)
+    new_storage: StorageDict = {
+        "version": storage_version,
+        "pvt": pvt,
+        "pub": pub,
+        "data": {},
+    }
+    new_pto = cry.Pto(new_storage["pvt"], new_pass)
+    for domain, user, secret in get_all(storage):
+        logger.debug("moving %s/%s to new storage", domain, user)
+        encrypted = new_pto.encrypt(secret)
+        domain_data: DataSection = new_storage["data"]
+        if domain in domain_data:
+            domain_data[domain][user] = encrypted
+        else:
+            domain_data[domain] = {user: encrypted}
+    return new_storage
+
+
+def store(storage: StorageDict, domain: str, user: str, secret: str) -> ChangeRecord:
+    """Store *secret* for *domain*/*user*.
+
+    Returns ``[change_type, domain, user, message]``.
+    """
+    active_pto = _require_pto()
+    encrypted = active_pto.encrypt(secret)
+    if exists(storage, domain, user):  # update existing
+        logger.debug("updating secret for %s/%s", domain, user)
+        storage["data"][domain][user] = encrypted
+        return ["-+", domain, user, "Update existing secret."]
+    if exists(storage, domain):  # add new user
+        logger.debug("adding user %s with secret for %s", user, domain)
+        storage["data"][domain][user] = encrypted
+        return ["+", domain, user, "Add user and secret."]
+    # add user and domain
+    logger.debug("adding domain %s and user %s with secret", domain, user)
+    storage["data"][domain] = {user: encrypted}
+    return ["+", domain, user, "Add domain, user and secret."]
+
+
+def make(storage: StorageDict, domain: str, user: str) -> ChangeRecord:
+    """Generate a random secret for *domain*/*user* and print it; return change list."""
+    secret = cry.make_password()
+    print(secret)
+    return store(storage, domain, user, secret)
+
+
+def exists(storage: StorageDict, domain: str, user: str | None = None) -> bool:
+    """Return True if *domain* (and optionally *user*) exists in storage."""
+    if domain not in storage["data"]:
+        logger.debug("domain %s does not exist", domain)
+        return False
+    if user is None:
+        logger.debug("domain %s exists", domain)
+        return True
+    if user in storage["data"][domain]:
+        logger.debug("user %s exists in domain %s", user, domain)
+        return True
+    logger.debug("user %s does not exist in domain %s", user, domain)
+    return False
+
+
+def get(storage: StorageDict, domain: str, user: str) -> str | None:
+    """Return the decrypted secret for *domain*/*user*, or None if not found."""
+    active_pto = _require_pto()
+    if not exists(storage, domain, user):
+        logger.warning("%s/%s does not exist", domain, user)
+        return None
+    secret = storage["data"][domain][user]
+    return active_pto.decrypt(secret)
+
+
+def get_all(storage: StorageDict) -> Generator[EntryRecord, None, None]:
+    """Yield ``[domain, user, secret]`` for every entry in storage."""
+    for domain in storage["data"]:
+        for user in storage["data"][domain]:
+            secret = get(storage, domain, user)
+            if secret is not None:
+                yield [domain, user, secret]
+
+
+def rm(storage: StorageDict, domain: str, user: str | None = None) -> ChangeRecord:
+    """Delete *user* from *domain* (or the whole *domain*); return change list."""
+    if not exists(storage, domain):
+        return ["|", "", "", "No change."]
+    if user is not None and not exists(storage, domain, user):
+        return ["|", "", "", "No change."]
+    if user is not None:
+        del storage["data"][domain][user]
+        if not storage["data"][domain]:
+            del storage["data"][domain]
+            return ["-", domain, "*", "Delete whole domain."]
+        return ["-", domain, user, "Delete user."]
+    del storage["data"][domain]
+    return ["-", domain, "*", "Delete whole domain."]
+
+
+def show(storage: StorageDict, domain: str) -> Generator[EntryRecord, None, None]:
+    """Yield ``[domain, user, secret]`` for every user in *domain*."""
+    if not exists(storage, domain):
+        return
+    for user in ls(storage, domain):
+        logger.debug("user found, decrypting secret")
+        decrypted = get(storage, domain, user)
+        if decrypted is not None:
+            yield [domain, user, decrypted]
+
+
+def ls(storage: StorageDict, domain: str | None = None) -> list[str]:
+    """Return list of domains, or list of users within *domain*."""
+    if domain is None:
+        return list(storage["data"].keys())
+    if not exists(storage, domain):
+        return []
+    return list(storage["data"][domain].keys())
+
+
+def find(storage: StorageDict, word: str) -> list[list[str]]:
+    """Return list of ``[domain]`` or ``[domain, user]`` entries matching *word*."""
+    results: list[list[str]] = []
+    for domain in storage["data"]:
+        if word in domain:
+            results.append([domain])
+        for user in storage["data"][domain]:
+            if word in user:
+                results.append([domain, user])
+    return results

loz/models.py

@@ -0,0 +1,49 @@
+"""Typed data-model definitions for loz storage and change/entry records.
+
+All persisted JSON must conform to :class:`StorageDict`.
+Change records returned by mutating functions are :data:`ChangeRecord`.
+Entry records yielded by read functions are :data:`EntryRecord`.
+"""
+
+from __future__ import annotations
+
+from typing import TypeAlias, TypedDict
+
+# ---------------------------------------------------------------------------
+# Nested types
+# ---------------------------------------------------------------------------
+
+# Mapping of username to base64-encoded ciphertext.
+DomainData: TypeAlias = "dict[str, str]"
+
+# Allow arbitrary string keys for domains.
+DataSection: TypeAlias = "dict[str, DomainData]"
+
+
+# ---------------------------------------------------------------------------
+# Top-level storage
+# ---------------------------------------------------------------------------
+
+
+class StorageDict(TypedDict):
+    """The complete in-memory / on-disk representation of a loz storage file.
+
+    All four keys are required and must be present in every valid lozfile.
+    """
+
+    version: str
+    pvt: str
+    pub: str
+    data: DataSection
+
+
+# ---------------------------------------------------------------------------
+# Functional records
+# ---------------------------------------------------------------------------
+
+# ``[change_type, domain, user, message]``
+# e.g.  ["+", "example.com", "alice", "Add domain, user and secret."]
+ChangeRecord: TypeAlias = "list[str]"
+
+# ``[domain, user, secret]``
+EntryRecord: TypeAlias = "list[str]"

loz-0.2.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: loz
+Version: 0.2.0
+Summary: loz - password manager
+Author-email: Predrag Mandic <predrag@nul.one>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://gitlab.nul.one/mush/loz
+Project-URL: Source Code, https://gitlab.nul.one/mush/loz
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: click>=8.1
+Requires-Dist: click-aliases>=1.0.1
+Requires-Dist: cryptography>=38.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: prompt_toolkit>=3.0
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+
+loz
+==================================================
+Command line password manager.
+
+Why?
+-------------------------
+You may ask why is there a need for another open source password manager. Here are some features that most currently available password managers lack and that loz is focusing on:
+
+- **Designed for command line.** Loz allows you to perform all tasks directly on the command line.
+    - You can pipe the secrets out of it directly to files.
+    - Bash completion is available for all commands and even domains/usernames.
+    - Commands are entered directly without loading any custom loz console.
+
+- **Asymmetric encryption.** Need to quickly add new entry or generate a password? No problem. With asymmetric encryption, you don't need to type your master password each time you add new entry. It even makes no sense to have to do that, right? You already know what you are entering.
+
+- **Single file storage.** [Lozfile](#lozfile-and-encryption) contains all entries, secrets and encryption keys in a simple json format. You can just copy it over to another machine and continue where you left off.
+
+Requirements
+-------------------------
+- Python >= 3.10
+
+Install
+-------------------------
+```
+pip install loz
+```
+
+### Setup bash completion
+Add the following to your `.bashrc` or `.profile`:
+```bash
+eval "$(loz bash-completion)"
+```
+
+Alternatively generate a bash completion file in a directory specific for your system,
+e.g. for Debian, Ubuntu and Fedora:
+```bash
+loz bash-completion | sudo tee /etc/bash_completion.d/loz
+```
+
+Usage
+-------------------------
+
+### Initialize lozfile
+
+`loz init` - This is required first step that will generate storage file at default location `~/.loz`. If you want to use a different location or separate storage file, you can specify that with `loz -f path/to/lozfile [COMMAND] [OPTIONS]`, but then you always need to include that switch when using other commands.
+
+You will be asked to enter the master password which will be required for decrypting your secrets. Read more about the lozfile, what it contains, what is being encrypting and what it's always revealing in the [lozfile section](#lozfile-and-encryption) of this doc.
+
+### Add secret
+
+`loz add mydomain.com username@email.com` - After this you will be prompted to enter your secret in a multi-line prompt. Press **Alt-Return** to save.
+
+If you want loz to generate a secret for you, just use `loz make mydomain.com username@email.com` instead. It will generate and save a new secret and print it out for you.
+
+### Read secret
+
+`loz get mydomain.com username@email.com` - After this you will be prompted for the master password. Note that you can autocomplete name of domains and usernames by pressing **Tab**.
+
+`loz show mydomain.com` will print all secrets for all usernames under selected domain.
+
+### List entries
+
+`loz ls` will list domains and `loz ls mydomain.com` will list usernames under selected domain.
+
+`loz find searchword` will list all domains and/or usernames that contain a word `searchword`.
+
+### Delete an entry
+
+`loz rm mydomain.com username@email.com` will delete selected username. If that's the only username under selected domain, the whole domain will be removed. If you want to delete a domain with all usernames under it, just type `loz rm mydomain.com`.
+
+### Export/Import
+
+`loz export > backup.csv` will export all secrets in a plain text csv file. You can import a backed up file with `loz import backup.csv`. It will ask you if you want to overwrite existing entries.
+
+### Change password
+
+`loz passwd` will prompt you for old and new password. It will then generate new keys and re-encrypt all secrets.
+
+Development
+-------------------------
+
+Clone the repository and create a virtual environment:
+
+```bash
+git clone git@gitlab.nul.one:mush/loz.git
+cd loz
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Running checks
+
+```bash
+# Lint
+ruff check loz/ tests/
+
+# Format check
+ruff format --check loz/ tests/
+
+# Type check
+mypy loz/
+
+# Tests with coverage
+pytest
+
+# Build and verify distribution
+python -m build
+twine check dist/*
+```
+
+### Pre-commit hooks
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+Lozfile and encryption
+-------------------------
+
+Lozfile is the json storage of all secrets. It contains plaintext RSA public key and Fernet (password) encrypted private key as well. Public key is used in the background when you are entering or generating new secrets. Private key is useless without your master password, but weak password means weak encryption.
+
+All secrets are encrypted with RSA 4096. This is slow for encryption and decryption, but allows the asymmetric approach and doesn't have a big performance impact on short secrets.
+
+Password generation uses `secrets.choice` (the Python standard-library CSPRNG) to ensure cryptographic strength.
+
+### Compatibility
+Backwards compatibility will be guaranteed for all lozfiles created with loz versions 0.1.0 and above. If there is a change in lozfile format, you may be prompted to update your lozfile.
+
+### WARNING
+Lozfile is revealing domains and usernames. This is by design to enable autocomplete. Future versions of loz may offer full encryption option, but for now it's not available and it's not a focus. If you are concerned about privacy of your usernames, then loz is not for you!

loz-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+loz/__init__.py,sha256=JEOdGdiSnZLcJs30unDEEb5n5Bj7lBjWt-JGAlgA7io,238
+loz/__main__.py,sha256=q9DugFX9cAsUsO-EtANsFJYNER7Exax0ku0y7DMQKF4,11682
+loz/cry.py,sha256=-pog2zDgLPnLEzNspr_us1xvys_cdfnlGWRpWKe_I1U,4716
+loz/exceptions.py,sha256=WUyFLFifTuJoZKaK5oA-sZugxfLTjGaaufKDM-fPeaY,414
+loz/loz.py,sha256=Z_wTuUwE1RoxsmqgF6-PB-S47jeb73pWAUCOMkhd0cc,14830
+loz/models.py,sha256=bETDgdS9xPGYeqvC1Nm-aXJ2g4XhWG3zTHf4AHSsKsY,1545
+loz-0.2.0.dist-info/licenses/AUTHORS,sha256=zYlcvpx-TdX50K8-F7z5HkIeHfehk_zJpytmC5QKLjg,313
+loz-0.2.0.dist-info/licenses/LICENSE,sha256=MQJ5gH7ejduo6MrbpzAxVVJGbiaWDmNDl_rCMl0f_ts,1521
+loz-0.2.0.dist-info/METADATA,sha256=-gJDTfyRRbGeeOqFgAvJW6NeYYN1p6y-tbngRvly6I4,6803
+loz-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+loz-0.2.0.dist-info/entry_points.txt,sha256=yMW7Lo7d4Y6wnii6ghnWJLc_YMAEJauPXXZFHae5TNE,41
+loz-0.2.0.dist-info/top_level.txt,sha256=azMmi87gQ_2PGJ5YvSNkQ994TYBCfwW3bJSfvMZFFMA,4
+loz-0.2.0.dist-info/RECORD,,

loz-0.2.0.dist-info/WHEEL

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

loz-0.2.0.dist-info/entry_points.txt

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

loz-0.2.0.dist-info/licenses/AUTHORS

@@ -0,0 +1,7 @@
+# This is the list of loz authors for copyright purposes.
+#
+# This does not necessarily list everyone who has contributed code, since in
+# some cases, their employer may be the copyright holder. To see the full list
+# of contributors, see the revision history in source control.
+
+Predrag Mandic <predrag@nul.one>

loz-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2021-2026, the loz authors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

loz-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+loz