sspwd 0.1.0__tar.gz

sspwd-0.1.0/LICENSE

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

sspwd-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: sspwd
+Version: 0.1.0
+Summary: A local, encrypted password manager with a web UI.
+Author: Yauheniya Varabyova
+Maintainer: Yauheniya Varabyova
+License: MIT
+Project-URL: Repository, https://github.com/yauheniya-ai/sspwd
+Project-URL: Changelog, https://github.com/yauheniya-ai/sspwd/blob/main/CHANGELOG.md
+Keywords: password,manager,security,encryption,cli,vault
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=5.0; extra == "dev"
+Requires-Dist: mypy>=0.991; extra == "dev"
+Requires-Dist: pre-commit>=2.20.0; extra == "dev"
+Requires-Dist: sphinx>=5.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "dev"
+Requires-Dist: myst-parser>=0.18; extra == "dev"
+Dynamic: license-file
+
+# sspwd – super secret password
+
+A local, encrypted password manager with a built-in web UI.
+
+Passwords are stored in `~/.sspwd/vault.db` — fully encrypted with a key
+derived from your master password. Nothing leaves your machine.
+
+---
+
+## Installation
+
+```bash
+pip install sspwd
+```
+
+> Requires Python ≥ 3.10.
+
+---
+
+## Quick start
+
+### Web UI
+
+```bash
+sspwd serve
+```
+
+Opens `http://127.0.0.1:7523` in your default browser. Enter your master
+password when prompted (a new vault is created automatically on first run).
+
+### CLI
+
+```bash
+# Add an entry
+sspwd add
+
+# List all entries
+sspwd list
+
+# Search
+sspwd list --search github
+
+# Show a single entry (reveals password)
+sspwd get 3
+
+# Delete an entry
+sspwd delete 3
+```
+
+### Custom vault location
+
+```bash
+sspwd serve --vault-dir /path/to/my/vault
+```
+
+---
+
+## Security
+
+| Detail | Value |
+|---|---|
+| Encryption | AES-128-CBC via [Fernet](https://cryptography.io/en/latest/fernet/) |
+| Key derivation | PBKDF2-HMAC-SHA256, 390 000 iterations |
+| Storage | SQLite (`~/.sspwd/vault.db`) |
+| Key never stored | Only a random 32-byte salt is persisted |
+
+The master password is required every time you start the app. There is no
+"remember me" — the derived key lives only in process memory.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/yauheniya-ai/sspwd
+cd sspwd/pypi
+
+# Install in editable mode with dev extras
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src tests
+```
+
+### Building the React UI
+
+```bash
+cd ../frontend
+npm install
+npm run build
+# Copy dist/ into pypi/src/sspwd/ui/static/
+cp -r dist/* ../pypi/src/sspwd/ui/static/
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sspwd-0.1.0/README.md

@@ -0,0 +1,102 @@
+# sspwd – super secret password
+
+A local, encrypted password manager with a built-in web UI.
+
+Passwords are stored in `~/.sspwd/vault.db` — fully encrypted with a key
+derived from your master password. Nothing leaves your machine.
+
+---
+
+## Installation
+
+```bash
+pip install sspwd
+```
+
+> Requires Python ≥ 3.10.
+
+---
+
+## Quick start
+
+### Web UI
+
+```bash
+sspwd serve
+```
+
+Opens `http://127.0.0.1:7523` in your default browser. Enter your master
+password when prompted (a new vault is created automatically on first run).
+
+### CLI
+
+```bash
+# Add an entry
+sspwd add
+
+# List all entries
+sspwd list
+
+# Search
+sspwd list --search github
+
+# Show a single entry (reveals password)
+sspwd get 3
+
+# Delete an entry
+sspwd delete 3
+```
+
+### Custom vault location
+
+```bash
+sspwd serve --vault-dir /path/to/my/vault
+```
+
+---
+
+## Security
+
+| Detail | Value |
+|---|---|
+| Encryption | AES-128-CBC via [Fernet](https://cryptography.io/en/latest/fernet/) |
+| Key derivation | PBKDF2-HMAC-SHA256, 390 000 iterations |
+| Storage | SQLite (`~/.sspwd/vault.db`) |
+| Key never stored | Only a random 32-byte salt is persisted |
+
+The master password is required every time you start the app. There is no
+"remember me" — the derived key lives only in process memory.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/yauheniya-ai/sspwd
+cd sspwd/pypi
+
+# Install in editable mode with dev extras
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src tests
+```
+
+### Building the React UI
+
+```bash
+cd ../frontend
+npm install
+npm run build
+# Copy dist/ into pypi/src/sspwd/ui/static/
+cp -r dist/* ../pypi/src/sspwd/ui/static/
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sspwd-0.1.0/pyproject.toml

@@ -0,0 +1,103 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# ---------------------------------------------------------------------------
+# Project metadata
+# ---------------------------------------------------------------------------
+[project]
+name = "sspwd"
+version = "0.1.0"
+description = "A local, encrypted password manager with a web UI."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Yauheniya Varabyova"}
+]
+maintainers = [
+    {name = "Yauheniya Varabyova"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Utilities",
+]
+keywords = ["password", "manager", "security", "encryption", "cli", "vault"]
+requires-python = ">=3.10"
+
+dependencies = [
+    # Web server
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "python-multipart>=0.0.9",
+    "pydantic>=2.0",           # FastAPI uses Pydantic v2 for request/response models
+    # CLI
+    "click>=8.1",
+    # Encryption  (PBKDF2 key derivation + Fernet AES)
+    "cryptography>=42.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "twine",
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pytest-mock",
+    "httpx>=0.27",             # needed by FastAPI TestClient
+    "black>=22.0",
+    "flake8>=5.0",
+    "mypy>=0.991",
+    "pre-commit>=2.20.0",
+    "sphinx>=5.0",
+    "sphinx-rtd-theme>=1.0",
+    "myst-parser>=0.18",
+]
+
+[project.urls]
+"Repository" = "https://github.com/yauheniya-ai/sspwd"
+"Changelog"  = "https://github.com/yauheniya-ai/sspwd/blob/main/CHANGELOG.md"
+
+# ---------------------------------------------------------------------------
+# Entry point — `sspwd` command becomes available after `pip install`
+# ---------------------------------------------------------------------------
+[project.scripts]
+sspwd = "sspwd.cli:main"
+
+# ---------------------------------------------------------------------------
+# Package discovery
+# ---------------------------------------------------------------------------
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Bundle the pre-built React/Vite static files shipped inside the package.
+[tool.setuptools.package-data]
+"sspwd.ui" = ["static/**/*"]
+
+# ---------------------------------------------------------------------------
+# Test / coverage config
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths  = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["sspwd"]
+omit   = ["*/tests/*", "*/__pycache__/*", "*/site-packages/*"]
+
+# ---------------------------------------------------------------------------
+# Mypy
+# ---------------------------------------------------------------------------
+[tool.mypy]
+python_version         = "3.10"
+ignore_missing_imports = true

sspwd-0.1.0/setup.cfg

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

sspwd-0.1.0/src/sspwd/__init__.py

@@ -0,0 +1,8 @@
+"""
+sspwd - A local password manager with a web UI.
+Passwords are stored encrypted in ~/.sspwd/
+"""
+
+from .__version__ import __version__
+
+__all__ = ["__version__"]

sspwd-0.1.0/src/sspwd/__version__.py

@@ -0,0 +1,5 @@
+"""Version information for finamt package."""
+
+from importlib.metadata import version
+
+__version__ = version("sspwd")

sspwd-0.1.0/src/sspwd/cli.py

@@ -0,0 +1,166 @@
+"""
+Command-line interface for sspwd.
+
+Usage
+-----
+    sspwd serve               # start the web UI (prompts for master password)
+    sspwd add                 # add a new entry interactively
+    sspwd list                # list all entries
+    sspwd get  <id>           # show a single entry (password revealed)
+    sspwd delete <id>         # delete an entry
+    sspwd version             # print version and exit
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from .__version__ import __version__
+from .storage.sqlite import SQLiteStorage
+from .storage.base import PasswordEntry
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_storage(master_password: str, vault_dir: Optional[Path] = None) -> SQLiteStorage:
+    return SQLiteStorage(master_password=master_password, vault_dir=vault_dir)
+
+
+def _prompt_master() -> str:
+    return click.prompt("Master password", hide_input=True)
+
+
+# ---------------------------------------------------------------------------
+# Root group
+# ---------------------------------------------------------------------------
+
+
+@click.group()
+@click.version_option(__version__, prog_name="sspwd")
+def cli() -> None:
+    """sspwd — a local, encrypted password manager."""
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.option("--host", default="127.0.0.1", show_default=True, help="Bind address.")
+@click.option("--port", default=7523, show_default=True, help="TCP port.")
+@click.option("--no-browser", is_flag=True, default=False, help="Do not open browser.")
+@click.option("--vault-dir", default=None, type=click.Path(), help="Custom vault directory.")
+def serve(host: str, port: int, no_browser: bool, vault_dir: Optional[str]) -> None:
+    """Start the web UI."""
+    from .ui.server import UIServer
+
+    master = _prompt_master()
+    storage = _get_storage(master, Path(vault_dir) if vault_dir else None)
+    server = UIServer(
+        storage=storage,
+        host=host,
+        port=port,
+        open_browser=not no_browser,
+    )
+    server.start(block=True)
+
+
+@cli.command("add")
+@click.option("--vault-dir", default=None, type=click.Path())
+def add_entry(vault_dir: Optional[str]) -> None:
+    """Add a new password entry interactively."""
+    master = _prompt_master()
+    storage = _get_storage(master, Path(vault_dir) if vault_dir else None)
+
+    title = click.prompt("Title")
+    username = click.prompt("Username")
+    password = click.prompt("Password", hide_input=True, confirmation_prompt=True)
+    url = click.prompt("URL (optional)", default="")
+    notes = click.prompt("Notes (optional)", default="")
+
+    entry = PasswordEntry(
+        id=None,
+        title=title,
+        username=username,
+        password=password,
+        url=url or None,
+        notes=notes or None,
+    )
+    created = storage.add(entry)
+    click.echo(click.style(f"✓ Saved (id={created.id})", fg="green"))
+
+
+@cli.command("list")
+@click.option("--search", "-s", default=None, help="Filter by title / username / URL.")
+@click.option("--vault-dir", default=None, type=click.Path())
+def list_entries(search: Optional[str], vault_dir: Optional[str]) -> None:
+    """List all stored entries."""
+    master = _prompt_master()
+    storage = _get_storage(master, Path(vault_dir) if vault_dir else None)
+
+    entries = storage.list(search=search)
+    if not entries:
+        click.echo("No entries found.")
+        return
+
+    click.echo(f"\n{'ID':>4}  {'Title':<30}  {'Username':<25}  URL")
+    click.echo("-" * 80)
+    for e in entries:
+        click.echo(f"{e.id:>4}  {e.title:<30}  {e.username:<25}  {e.url or ''}")
+
+
+@cli.command("get")
+@click.argument("entry_id", type=int)
+@click.option("--vault-dir", default=None, type=click.Path())
+def get_entry(entry_id: int, vault_dir: Optional[str]) -> None:
+    """Show a single entry including the password."""
+    master = _prompt_master()
+    storage = _get_storage(master, Path(vault_dir) if vault_dir else None)
+
+    entry = storage.get(entry_id)
+    if entry is None:
+        click.echo(click.style(f"Entry {entry_id} not found.", fg="red"), err=True)
+        sys.exit(1)
+
+    click.echo(f"\nTitle    : {entry.title}")
+    click.echo(f"Username : {entry.username}")
+    click.echo(f"Password : {entry.password}")
+    click.echo(f"URL      : {entry.url or '-'}")
+    click.echo(f"Notes    : {entry.notes or '-'}")
+    click.echo(f"Updated  : {entry.updated_at}")
+
+
+@cli.command("delete")
+@click.argument("entry_id", type=int)
+@click.option("--yes", "-y", is_flag=True, default=False, help="Skip confirmation.")
+@click.option("--vault-dir", default=None, type=click.Path())
+def delete_entry(entry_id: int, yes: bool, vault_dir: Optional[str]) -> None:
+    """Delete an entry by ID."""
+    master = _prompt_master()
+    storage = _get_storage(master, Path(vault_dir) if vault_dir else None)
+
+    if not yes:
+        click.confirm(f"Delete entry {entry_id}?", abort=True)
+
+    try:
+        storage.delete(entry_id)
+        click.echo(click.style(f"✓ Deleted entry {entry_id}.", fg="green"))
+    except KeyError:
+        click.echo(click.style(f"Entry {entry_id} not found.", fg="red"), err=True)
+        sys.exit(1)
+
+
+@cli.command("version")
+def version() -> None:
+    """Print version."""
+    click.echo(f"sspwd {__version__}")
+
+
+def main() -> None:
+    cli()

sspwd-0.1.0/src/sspwd/storage/__init__.py

@@ -0,0 +1,3 @@
+from .sqlite import SQLiteStorage
+
+__all__ = ["SQLiteStorage"]

sspwd-0.1.0/src/sspwd/storage/base.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class PasswordEntry:
+    id: Optional[int]
+    title: str
+    username: str
+    password: str          # stored encrypted, returned decrypted
+    url: Optional[str] = None
+    notes: Optional[str] = None
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    updated_at: datetime = field(default_factory=datetime.utcnow)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "username": self.username,
+            "password": self.password,
+            "url": self.url,
+            "notes": self.notes,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }
+
+
+class BaseStorage(ABC):
+    """Abstract interface that every storage backend must implement."""
+
+    @abstractmethod
+    def initialize(self) -> None:
+        """Create tables / files if they do not exist yet."""
+
+    @abstractmethod
+    def add(self, entry: PasswordEntry) -> PasswordEntry:
+        """Persist a new entry and return it with its assigned id."""
+
+    @abstractmethod
+    def get(self, entry_id: int) -> Optional[PasswordEntry]:
+        """Return a single entry by id, or None if not found."""
+
+    @abstractmethod
+    def list(self, search: Optional[str] = None) -> list[PasswordEntry]:
+        """Return all entries, optionally filtered by a search string."""
+
+    @abstractmethod
+    def update(self, entry: PasswordEntry) -> PasswordEntry:
+        """Overwrite an existing entry. Raises KeyError if id not found."""
+
+    @abstractmethod
+    def delete(self, entry_id: int) -> None:
+        """Remove an entry by id. Raises KeyError if not found."""