pitt 0.4.7__tar.gz

pitt-0.4.7/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.3
+Name: pitt
+Version: 0.4.7
+Summary: an extremely simple terminal-based password manager
+Author: quandelaa
+Author-email: quandelaa <sergiotobamasilalahi@gmail.com>
+Requires-Dist: argon2-cffi>=25.1.0
+Requires-Dist: cryptography>=49.0.0
+Requires-Dist: platformdirs>=4.10.1
+Requires-Dist: pyperclip>=1.11.0
+Requires-Dist: rich>=15.0.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pitt
+
+an extremely simple terminal-based password manager.
+
+## installation
+
+```bash
+pip install git+https://github.com/quandelaa/pitt.git
+```
+
+## usage
+
+### commands
+
+1. `pitt init`:
+    * asks for a master password
+    * when given, encrypts it using Argon2id and stores it in the database
+
+    example:
+    ```bash
+    pitt init
+    ```
+
+2. `pitt add`:
+    * create random password
+    * encrypts the random password using Fernet
+    * stores the encrypted password with a specified username or service or note in the database
+
+    example:
+    ```bash
+    pitt add --service github --username quandelaa --note "this is my song"
+    ```
+
+3. `pitt get`:
+    * gets the password that is saved with the given service or username
+    * decrypts the password
+    * copies it to user's clipboard
+
+    example:
+    ```bash
+    pitt get --service github --username quandelaa
+    ```
+
+4. `pitt list`:
+    * lists only the details (service, username and notes) of all the saved passwords
+
+    example:
+    ```bash
+    pitt list"
+    ```
+
+4. `pitt del`:
+    * deletes a password in the password vault that is saved with the given service or username 
+
+    example:
+    ```bash
+    pitt del --service github --username quandelaa
+    ```
+
+## license
+
+this project is licensed under the MIT License - see the LICENSE file for details
+
+## credits
+
+inspired by: themohitnair's sfnx | (https://github.com/themohitnair/sfnx)
+
+---
+
+curated by me with passion and a teensy bit of stress

pitt-0.4.7/README.md

@@ -0,0 +1,70 @@
+# pitt
+
+an extremely simple terminal-based password manager.
+
+## installation
+
+```bash
+pip install git+https://github.com/quandelaa/pitt.git
+```
+
+## usage
+
+### commands
+
+1. `pitt init`:
+    * asks for a master password
+    * when given, encrypts it using Argon2id and stores it in the database
+
+    example:
+    ```bash
+    pitt init
+    ```
+
+2. `pitt add`:
+    * create random password
+    * encrypts the random password using Fernet
+    * stores the encrypted password with a specified username or service or note in the database
+
+    example:
+    ```bash
+    pitt add --service github --username quandelaa --note "this is my song"
+    ```
+
+3. `pitt get`:
+    * gets the password that is saved with the given service or username
+    * decrypts the password
+    * copies it to user's clipboard
+
+    example:
+    ```bash
+    pitt get --service github --username quandelaa
+    ```
+
+4. `pitt list`:
+    * lists only the details (service, username and notes) of all the saved passwords
+
+    example:
+    ```bash
+    pitt list"
+    ```
+
+4. `pitt del`:
+    * deletes a password in the password vault that is saved with the given service or username 
+
+    example:
+    ```bash
+    pitt del --service github --username quandelaa
+    ```
+
+## license
+
+this project is licensed under the MIT License - see the LICENSE file for details
+
+## credits
+
+inspired by: themohitnair's sfnx | (https://github.com/themohitnair/sfnx)
+
+---
+
+curated by me with passion and a teensy bit of stress

pitt-0.4.7/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "pitt"
+version = "0.4.7"
+description = "an extremely simple terminal-based password manager"
+readme = "README.md"
+authors = [
+    { name = "quandelaa", email = "sergiotobamasilalahi@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "argon2-cffi>=25.1.0",
+    "cryptography>=49.0.0",
+    "platformdirs>=4.10.1",
+    "pyperclip>=1.11.0",
+    "rich>=15.0.0",
+]
+
+[project.scripts]
+pitt = "pitt.main:main"
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = []

pitt-0.4.7/src/pitt/db_handler.py

@@ -0,0 +1,118 @@
+import sqlite3 as sql
+from .utils import get_db_path
+
+def init_db() -> None:
+    """
+    Initialize the database that will store the encrypted passwords.
+    """
+
+    db_path = str(get_db_path())
+    
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    cur.executescript(
+        """CREATE TABLE IF NOT EXISTS passwords (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              service TEXT,
+              username TEXT,
+              note TEXT,
+              password BLOB NOT NULL);"""
+        )
+
+    cur.executescript(
+        """CREATE TABLE IF NOT EXISTS master (
+              master_hash TEXT NOT NULL,
+              salt BLOB NOT NULL);"""
+        )
+
+    conn.commit()
+    conn.close()
+
+def configure_vault(salt: bytes, new_hash: str) -> None:
+    """
+    Configures the current master password hash stored in the passwords database
+    """
+
+    db_path = str(get_db_path())
+
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    cur.execute("SELECT COUNT(*) FROM master")
+    row_count = cur.fetchone()[0]
+
+    if row_count == 0:
+        cur.execute("INSERT INTO master (salt, master_hash) VALUES ('', '')")
+
+    cur.execute("UPDATE master SET (master_hash, salt) = (?, ?)", (new_hash, salt))
+
+    conn.commit()
+    conn.close()
+
+def store_password(service: str | None, username: str | None, note: str | None, password: bytes) -> None:
+    """
+    Stores the password inside of the created database
+    """
+
+    db_path = str(get_db_path())
+
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    cur.execute("INSERT INTO passwords (service, username, note, password) VALUES (?, ?, ?, ?)", (service, username, note, password))
+
+    conn.commit()
+    conn.close()
+
+def get_by_properties(service: str | None, username: str | None) -> list:
+    """
+    Gets the encrypted password in the passwords database based on given service and username
+    """
+
+    db_path = str(get_db_path())
+
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    if username is None and service is not None:
+        cur.execute("SELECT * FROM passwords WHERE service = ?", (service,))
+    elif username is not None and service is None:
+        cur.execute("SELECT * FROM passwords WHERE username = ?", (username,))
+    elif username is not None and service is not None:
+        cur.execute("SELECT * FROM passwords WHERE (service, username) = (?, ?)", (service, username))
+
+    results = cur.fetchall()
+    
+    return results
+
+def get_all() -> list:
+    """
+    Gets the encrypted password in the passwords database based on given service and username
+    """
+
+    db_path = str(get_db_path())
+
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    cur.execute("SELECT * FROM passwords")
+
+    results = cur.fetchall()
+    
+    return results
+
+def delete_by_password(encrypted: bytes) -> None:
+    """
+    Deletes a password entry
+    """
+
+    db_path = str(get_db_path())
+
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    cur.execute("DELETE FROM passwords WHERE password = ?", (encrypted,))
+
+    conn.commit()
+    conn.close()

pitt-0.4.7/src/pitt/functions.py

@@ -0,0 +1,275 @@
+from rich.console import Console
+from getpass import getpass
+from pyperclip import copy
+from os import urandom
+from .db_handler import init_db, configure_vault, store_password, get_by_properties, get_all, delete_by_password
+from .security import master_encrypt, verify_master_password, encrypt, decrypt, derive_key
+from .utils import get_db_path, check_db_exists, get_vault_property, create_password
+
+def init() -> None:
+    """
+    Initialize the password manager's master password and the database
+    """
+
+    try:
+        console = Console()
+
+        if check_db_exists() is True:
+            db_path = get_db_path()
+            console.print(f"[bold yellow]:| your database was already initialized at [italic]{db_path}")
+
+            return
+
+        console.print("[bold yellow]! initializing..\n")
+
+        master_password = getpass("> master password: ")
+        confirm = getpass("> enter the password again (confirm): ")
+
+        if master_password != confirm:
+            console.print("\n[bold red]:( passwords do not match, sorry -- aborting")
+            return
+
+        console.print("\n[bold green]:) matched!")
+
+        db_path = str(get_db_path())
+        init_db()
+
+        console.print(f"[bold green]:) database set up at [italic]{db_path}")
+
+        salt = urandom(16)
+        
+        new_hash = master_encrypt(master_password)
+        configure_vault(salt, new_hash)
+        
+        console.print("[bold green]:) master password successfully set up!\n")
+        console.print("[bold yellow]! do pitt -h for help")
+    except KeyboardInterrupt:
+        console.print("\n[bold red]bye!")
+        return
+    except Exception as e:
+        console.print(f"\n[bold red]:( error: {e}")
+        console.print("[bold yellow]! do pitt -h for help")
+
+        return
+
+def add(service: str | None, username: str | None, note: str | None) -> None:
+    """
+    Adds a password to the password vault with the given service, username and a note
+    """
+
+    try:
+        console = Console()
+                
+        if service is None and username is None and note is None:
+            console.print("[bold red]:( you have to provide atleast a note, a username or a service")
+            return
+
+        master_password = getpass("> master password: ")
+
+        m_hash, salt = get_vault_property()
+
+        verify = verify_master_password(master_password, m_hash)
+        
+        if verify is False:
+            console.print("[bold red]:( wrong password!")
+            return
+
+        password = create_password()
+
+        console.print("\n[bold green]:) password created!")
+
+        key = derive_key(master_password, salt)
+        encrypted = encrypt(key, password)
+        
+        console.print("[bold green]:) password encrypted successfully!")
+        
+        store_password(service, username, note, encrypted)
+
+        console.print("[bold green]:) password stored in database successfully!")
+        console.print("\n[bold yellow]! do pitt -h for help")
+    except KeyboardInterrupt:
+        console.print("\n[bold red]bye!")
+        return
+    except Exception as e:
+        console.print(f"\n[bold red]:( error: {e}")
+        console.print("[bold yellow]! do pitt -h for help")
+
+        return
+
+def get(service: str | None, username: str | None) -> None:
+    """
+    Copies a password to the clipboard
+    """
+
+    try:
+        console = Console()
+
+        if service is None and username is None:
+            console.print("[bold red]:( you have to provide atleast a username or service")
+            return
+
+        master_password = getpass("> master password: ")
+
+        m_hash, salt = get_vault_property()
+
+        verify = verify_master_password(master_password, m_hash)
+        
+        if verify is False:
+            console.print("[bold red]:( wrong password!")
+            return
+        
+        console.print(f"[bold green]:) verification successful!")
+
+        results = get_by_properties(service, username)
+
+        if len(results) > 1:
+            console.print(f"\n[bold yellow]found passwords:\n")
+
+            for i, row in enumerate(results):
+                console.print(f"{i+1}. [bold]service: [/][honeydew2]{row[1]}[/], [bold]username: [/][light_cyan1]{row[2]}[/], [bold]note: [/][cornsilk1]{row[3]}")
+
+            console.print(f"\n[bold yellow]you have registered {len(results)} password that is saved with the given service or username")
+
+            p_index = int(console.input(f"[bold yellow]which one is the password to copy (index): "))
+            encrypted_password = results[p_index-1][4]
+
+            key = derive_key(master_password, salt)
+            byte_password = decrypt(key, encrypted_password)
+
+            password = byte_password.decode('utf-8')
+
+            copy(password)
+
+            console.print(f"\n[bold green]:) copied to the clipboard successfully!")
+        elif len(results) == 1:
+            row = results[0]
+
+            encrypted_password = row[4]
+
+            key = derive_key(master_password, salt)
+            byte_password = decrypt(key, encrypted_password)
+
+            password = byte_password.decode('utf-8')
+
+            copy(password)
+
+            console.print(f"[bold green]:) copied to the clipboard successfully!")
+        elif len(results) == 0:
+            console.print(f"\n[bold yellow]you have no registered password that is saved with the given service or username")
+    except KeyboardInterrupt:
+        console.print("\n[bold red]bye!")
+        return
+    except Exception as e:
+        console.print(f"\n[bold red]:( error: {e}")
+        console.print("[bold yellow]! do pitt -h for help")
+
+        return
+
+def list_cmd() -> None:
+    """
+    Lists all the saved passwords's details
+    """
+
+    try:
+        console = Console()
+        
+        master_password = getpass("> master password: ")
+
+        m_hash, _ = get_vault_property()
+
+        verify = verify_master_password(master_password, m_hash)
+        
+        if verify is False:
+            console.print("[bold red]:( wrong password!")
+            return
+        
+        console.print(f"[bold green]:) verification successful!")
+
+        passwords_results = get_all()
+        
+        console.print(f"\n[bold yellow]saved passwords:")
+
+        for password in passwords_results:
+            console.print(f"{password[0]}. [bold]service: [/][honeydew2]{password[1]}[/], [bold]username: [/][light_cyan1]{password[2]}[/], [bold]note: [/][cornsilk1]{password[3]}")
+    except KeyboardInterrupt:
+        console.print("\n[bold red]bye!")
+        return
+    except Exception as e:
+        console.print(f"\n[bold red]:( error: {e}")
+        console.print("[bold yellow]! do pitt -h for help")
+
+        return
+
+def del_cmd(service: str | None, username: str | None) -> None:
+    """
+    Deletes a password from the password vault
+    """
+
+    try:
+        console = Console()
+        
+        if service is None and username is None:
+            console.print("[bold red]:( you have to provide atleast a username or service")
+            return
+
+        master_password = getpass("> master password: ")
+
+        m_hash, _ = get_vault_property()
+
+        verify = verify_master_password(master_password, m_hash)
+        
+        if verify is False:
+            console.print("[bold red]:( wrong password!")
+            return
+        
+        console.print(f"[bold green]:) verification successful!")
+        
+        results = get_by_properties(service, username)
+
+        if len(results) > 1:
+            console.print(f"\n[bold yellow]found passwords:\n")
+
+            for i, row in enumerate(results):
+                console.print(f"{i+1}. [bold]service: [/][honeydew2]{row[1]}[/], [bold]username: [/][light_cyan1]{row[2]}[/], [bold]note: [/][cornsilk1]{row[3]}")
+
+            console.print(f"\n[bold yellow]you have registered {len(results)} password that is saved with the given service or username")
+
+            p_index = int(console.input(f"[bold yellow]which one is the password to delete (index): "))
+            encrypted_password = results[p_index-1][4]
+
+            delete_by_password(encrypted_password)
+        elif len(results) == 1:
+            encrypted_password = results[0][4]
+
+            res = None
+            console.print()
+
+            while res not in ('y', 'n', ''):
+                res = console.input("[bold yellow]! are you sure about this (y/N): ").lower()
+
+            if res == 'y':
+                res2 = None
+                console.print()
+
+                while res2 not in ('y', 'n', ''):
+                    res2 = console.input("[bold yellow]! are you really sure about this (y/N): ").lower()
+
+                if res2 == '' or res == 'n':
+                    return
+            elif res == '' or res == 'n':
+                return
+
+            delete_by_password(encrypted_password)
+        elif len(results) == 0:
+            console.print(f"\n[bold yellow]you have no registered password that is saved with the given service or username")
+            return
+
+        console.print(f"\n[bold green]:) deletion successful!")
+    except KeyboardInterrupt:
+        console.print("\n[bold red]bye!")
+        return
+    except Exception as e:
+        console.print(f"\n[bold red]:( error: {e}")
+        console.print("[bold yellow]! do pitt -h for help")
+
+        return

pitt-0.4.7/src/pitt/main.py

@@ -0,0 +1,16 @@
+from .functions import init, add, get, list_cmd, del_cmd
+from .parse import parse
+
+def main() -> None:
+    args = parse()  
+
+    if args.command == "init":
+        init()
+    elif args.command == "add":
+        add(args.service, args.username, args.note)
+    elif args.command == "get":
+        get(args.service, args.username)
+    elif args.command == "list":
+        list_cmd()
+    elif args.command == "del":
+        del_cmd(args.service, args.username)

pitt-0.4.7/src/pitt/parse.py

@@ -0,0 +1,30 @@
+import argparse
+
+def parse() -> argparse.Namespace:
+    """
+    Returns the parsed arguments
+    """
+
+    parser = argparse.ArgumentParser(allow_abbrev=False, prog="pitt")
+    subparser = parser.add_subparsers(dest="command", required=True, help="commands")
+
+    subparser.add_parser("init", help="set up a master password to initialize the password pit of doom and despair")
+    subparser.add_parser("list", help="lists all the saved password")
+
+    del_password_parser = subparser.add_parser("del", help="delete a saved password")
+    get_password_parser = subparser.add_parser("get", help="copy a stored password to the clipboard")
+    add_password_parser = subparser.add_parser("add", help="generate and store a new randomized password")
+
+    del_password_parser.add_argument("-s", "--service", help="specify the service assigned to the password that is to be deleted")
+    del_password_parser.add_argument("-u", "--username", help="specify the username assigned to the password that is to be copied to clipboard")
+
+    get_password_parser.add_argument("-s", "--service", help="specify the service assigned to the password that is to be copied to clipboard")
+    get_password_parser.add_argument("-u", "--username", help="specify the username assigned to the password that is to be copied to clipboard")
+
+    add_password_parser.add_argument("-s", "--service", help="specify the service that the new generated password belongs to")
+    add_password_parser.add_argument("-u", "--username", help="specify the username that the new generated password belongs to")
+    add_password_parser.add_argument("-n", "--note", help="specify notes about this particular password")
+
+    args = parser.parse_args()
+
+    return args

pitt-0.4.7/src/pitt/security.py

@@ -0,0 +1,59 @@
+from argon2 import PasswordHasher, exceptions, low_level, Type
+from cryptography.fernet import Fernet
+import base64
+import os
+
+def master_encrypt(password: str) -> str:
+    """
+    Returns the encrypted hash of a given master password
+    """
+
+    kdf = PasswordHasher()
+    hash = kdf.hash(password)
+
+    return hash
+
+def verify_master_password(password: str, hash: str) -> bool:
+    """
+    Verifies whether the inputted master password matches with the stored master password
+    """
+    
+    kdf = PasswordHasher()
+
+    try:
+        kdf.verify(hash, password)
+    except exceptions.VerifyMismatchError:
+        return False
+
+    return True
+
+def derive_key(password: str, salt: bytes) -> bytes:
+    """
+    Derives the 64-byte Argon2id key from the password
+    """
+
+    key = low_level.hash_secret_raw(password.encode("utf-8"), salt, 3, 65536, 1, 32, Type.ID)
+
+    b64_key = base64.urlsafe_b64encode(key)
+
+    return b64_key
+
+def encrypt(key: bytes, password: str) -> bytes:
+    """
+    Encrypts the given password using Fernet
+    """
+
+    f = Fernet(key)
+    token = f.encrypt(password.encode("utf-8"))
+
+    return token
+
+def decrypt(key: bytes, encrypted: bytes) -> bytes:
+    """
+    Decrypts the given encrypted password using Fernet
+    """
+
+    f = Fernet(key)
+    password = f.decrypt(encrypted)
+
+    return password

pitt-0.4.7/src/pitt/utils.py

@@ -0,0 +1,79 @@
+import sqlite3 as sql
+from random import choices, randint
+from platformdirs import PlatformDirs
+from pathlib import Path
+
+def get_db_path() -> Path:
+    """
+    Returns the default database path for all operating systems
+    """
+    
+    dirs = PlatformDirs("pitt")
+    return dirs.user_data_path / "passwords.db"
+
+def check_db_exists() -> bool:
+    """
+    Returns whether the password vault database exists
+    """
+
+    db_path = get_db_path()
+    return db_path.is_file()
+
+def check_master_password_exists() -> bool:
+    """
+    Returns whether the master password has been set up in the password vault database
+    """
+
+    if check_db_exists() is False:
+        return False
+
+    db_path = get_db_path()
+
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    cur.execute("SELECT master_hash FROM master")
+
+    vals = cur.fetchone()
+    conn.close()
+
+    if len(vals) == 0:
+        return False
+
+    return True
+
+def get_vault_property() -> tuple:
+    """
+    Returns master vault's properties
+    """
+
+    if check_db_exists() is False:
+        raise RuntimeError("database doesn't exist.")
+    elif check_master_password_exists() is False:
+        raise RuntimeError("master password isn't set yet the database file is created.")
+
+    db_path = get_db_path()
+
+    conn = sql.connect(db_path)
+    cur = conn.cursor()
+
+    cur.execute("SELECT master_hash, salt FROM master")
+
+    rows = cur.fetchone()
+    conn.close()
+
+    return rows
+
+def create_password() -> str:
+    """
+    Creates a random password
+    """
+
+    items = ['"', '`', '1', '2', '3','4','5','6','7','8','9','0','-','=','q','w','e','r','t','y','u','i','o','p','[',']','\\','a','s','d','f','g','h','j','k','l',';','z','x','c','v','b','n','m',',','.','/','~','!','@','#',"$","%","^","&","*",'(',')','_','+','Q','W','E','R','T','Y','U','I','O','P','{','}','|','A','S','D','F','G','H','J','K','L',':','Z','X','C','V','B','N','M','<','>','?']
+
+    p_len = randint(35,50)
+    list_char = choices(items, k=p_len)
+
+    password = ''.join(list_char)
+
+    return password