mirror of
https://github.com/PR0M3TH3AN/SeedPass.git
synced 2025-09-08 07:18:47 +00:00
update
This commit is contained in:
thePR0M3TH3AN
93
dev-plan.md
93
dev-plan.md
@@ -1,93 +0,0 @@
|
||||
### SeedPass Road-to-1.0 — Detailed Development Plan
|
||||
|
||||
*(Assumes today = 1 July 2025, team of 1-3 devs, weekly release cadence)*
|
||||
|
||||
| Phase | Goal | Key Deliverables | Target Window |
|
||||
| ------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
|
||||
| **0 – Vision Lock-in** | Be explicit about where you’re going so every later trade-off is easy. | • 2-page “north-star” doc covering product scope, security promises, platforms, and **“CLI is source of truth”** principle. <br>• Public roadmap Kanban board. | **Week 0** |
|
||||
| **1 – Package-ready Codebase** | Turn loose `src/` tree into a pip-installable library + console script. | • `pyproject.toml` with PEP-621 metadata, `setuptools-scm` dynamic version. <br>• Restructure to `seedpass/` (or keep `src/` but list `packages = ["seedpass"]`). <br>• Entry-point: `seedpass = "seedpass.main:cli"`. <br>• Dev extras: `pytest-cov`, `ruff`, `mypy`, `pre-commit`. <br>• Split pure business logic from I/O (e.g., encryption, BIP-85, vault ops) so GUI can reuse. | **Weeks 0-2** |
|
||||
| **2 – Local Quality Net** | Fail fast before CI runs. | • `make test` / `tox` quick matrix (3.10–3.12). <br>• 90 % line coverage gate. <br>• Static checks in pre-commit (black, ruff, mypy). | **Weeks 1-3** |
|
||||
| **3 – CI / Release Automation** | One Git tag → everything ships. | • GitHub Actions matrix (Ubuntu, macOS, Windows). <br>• Steps: install → unit tests → build wheels (`python -m build`) → PyInstaller one-file artefacts → upload to Release. <br>• Secrets for PyPI / code-signing left empty until 1.0. | **Weeks 2-4** |
|
||||
| **4 – OS-Native Packages** | Users can “apt install / brew install / flatpak install / download .exe”. | **Linux** • `stdeb` → `.deb`, `reprepro` mini-APT repo. <br>**Flatpak** • YAML manifest + GitHub Action to build & push to Flathub beta repo. <br>**Windows** • PyInstaller `--onefile` → NSIS installer. <br>**macOS** • Briefcase → notarised `.pkg` or `.dmg` (signing cert later). | **Weeks 4-8** |
|
||||
| **5 – Experimental GUI Track** | Ship a GUI **without** slowing CLI velocity. | • Decide stack (recommend **Textual** first; upgrade later to Toga or PySide). <br>• Create `seedpass.gui` package calling existing APIs; flag with `--gui`. <br>• Feature flag via env var `SEEDPASS_GUI=1` or CLI switch. <br>• Separate workflow that builds GUI artefacts, but does **not** block CLI releases. | **Weeks 6-12** (parallel) |
|
||||
| **6 – Plugin / Extensibility Layer** | Keep core slim while allowing future features. | • Define `entry_points={"seedpass.plugins": …}`. <br>• Document simple example plugin (e.g., custom password rule). <br>• Load plugins lazily to avoid startup cost. | **Weeks 10-14** |
|
||||
| **7 – Security & Hardening** | Turn security assumptions into guarantees before 1.0 | • SAST scan (Bandit, Semgrep). <br>• Threat-model doc: key-storage, BIP-85 determinism, Nostr backup flow. <br>• Repro-build check for PyInstaller artefacts. <br>• Signed releases (Sigstore, minisign). | **Weeks 12-16** |
|
||||
| **8 – 1.0 Launch Prep** | Final polish + docs. | • User manual (MkDocs, `docs.seedpass.org`). <br>• In-app `--check-update` hitting GitHub API. <br>• Blog post & template release notes. | **Weeks 16-18** |
|
||||
|
||||
---
|
||||
|
||||
### Ongoing Practices to Keep Development Nimble
|
||||
|
||||
| Practice | What to do |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| **Dynamic versioning** | Keep `version` dynamic via `setuptools-scm` / `hatch-vcs`; tag and push – nothing else. |
|
||||
| **Trunk-based dev** | Short-lived branches, PRs < 300 LOC; merge when tests pass. |
|
||||
| **Feature flags** | `seedpass.config.is_enabled("X")` so unfinished work can ship dark. |
|
||||
| **Fast feedback loops** | Local editable install; `invoke run --watch` (or `uvicorn --reload` for GUI) to hot-reload. |
|
||||
| **Weekly beta release** | Even during heavy GUI work, cut “beta” tags weekly; real users shake out regressions early. |
|
||||
|
||||
---
|
||||
|
||||
### First 2-Week Sprint (Concrete To-Dos)
|
||||
|
||||
1. **Bootstrap packaging**
|
||||
|
||||
```bash
|
||||
pip install --upgrade pip build setuptools_scm
|
||||
poetry init # if you prefer Poetry, else stick with setuptools
|
||||
```
|
||||
|
||||
Add `pyproject.toml`, move code to `seedpass/`.
|
||||
|
||||
2. **Console entry-point**
|
||||
In `seedpass/__main__.py` add `from .main import cli; cli()`.
|
||||
|
||||
3. **Editable dev install**
|
||||
`pip install -e .[dev]` → run `seedpass --help`.
|
||||
|
||||
4. **Set up pre-commit**
|
||||
`pre-commit install` with ruff + black + mypy hooks.
|
||||
|
||||
5. **GitHub Action skeleton** (`.github/workflows/ci.yml`)
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
test:
|
||||
strategy:
|
||||
matrix: os: [ubuntu-latest, windows-latest, macos-latest]
|
||||
python-version: ['3.12', '3.11']
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with: {python-version: ${{ matrix.python-version }}}
|
||||
- run: pip install --upgrade pip
|
||||
- run: pip install -e .[dev]
|
||||
- run: pytest -n auto
|
||||
```
|
||||
|
||||
6. **Smoke PyInstaller locally**
|
||||
`pyinstaller --onefile seedpass/main.py` – fix missing data/hooks; check binary runs.
|
||||
|
||||
When that’s green, cut tag `v0.1.0-beta` and let CI build artefacts automatically.
|
||||
|
||||
---
|
||||
|
||||
### Choosing the GUI Path (decision by Week 6)
|
||||
|
||||
| If you value… | Choose |
|
||||
| ---------------------------------- | ---------------------------- |
|
||||
| Terminal-first UX, live coding | **Textual (Rich-TUI)** |
|
||||
| Native look, single code base | **Toga / Briefcase** |
|
||||
| Advanced widgets, designer tooling | **PySide-6 / Qt for Python** |
|
||||
|
||||
Prototype one screen (vault list + “Add” dialog) and benchmark bundle size + startup time with PyInstaller before committing.
|
||||
|
||||
---
|
||||
|
||||
## Recap
|
||||
|
||||
* **Packaging & CI first** – lets every future feature ride an established release train.
|
||||
* **GUI lives in its own layer** – CLI stays stable; dev cycles remain quick.
|
||||
* **Security & signing** land after functionality is stable, before v1.0 marketing push.
|
||||
|
||||
Follow the phase table, keep weekly betas flowing, and you’ll reach a polished, installer-ready, GUI-enhanced 1.0 in roughly four months without sacrificing day-to-day agility.
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
|
||||
# SeedPass Feature Back‑Log (v2)
|
||||
|
||||
> **Encryption invariant** Everything at rest **and** in export remains cipher‑text that ultimately derives from the **profile master‑password + parent seed**. No unencrypted payload leaves the vault.
|
||||
>
|
||||
> **Surface rule** UI layers (CLI, GUI, future mobile) may *display* decrypted data **after** user unlock, but must never write plaintext to disk or network.
|
||||
|
||||
---
|
||||
|
||||
## Track vocabulary
|
||||
|
||||
| Label | Meaning |
|
||||
| ------------ | ------------------------------------------------------------------------------ |
|
||||
| **Core API** | `seedpass.api` – headless services consumed by CLI / GUI |
|
||||
| **Profile** | A fingerprint‑scoped vault: parent‑seed + hashed pw + entries |
|
||||
| **Entry** | One encrypted JSON blob on disk plus Nostr snapshot chunks and delta events |
|
||||
| **GUI MVP** | Desktop app built with PySide 6 announced in the v2 roadmap |
|
||||
|
||||
---
|
||||
|
||||
## Phase A • Core‑level enhancements (blockers for GUI)
|
||||
|
||||
| Prio | Feature | Notes |
|
||||
| ------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 🔥 | **Encrypted Search API** | • `VaultService.search(query:str, *, kinds=None) -> List[EntryMeta]` <br>• Decrypt *only* whitelisted meta‑fields per `kind` (title, username, url, tags) for in‑memory matching. |
|
||||
| 🔥 | **Rich Listing / Sort / Filter** | • `list_entries(sort_by="updated", kind="note")` <br>• Sorting by `title` must decrypt that field on‑the‑fly. |
|
||||
| 🔥 | **Custom Relay Set (per profile)** | • `StateManager.state["relays"]: List[str]` <br>• CRUD CLI commands & GUI dialog. <br>• `NostrClient` reads from state at instantiation. |
|
||||
| ⚡ | **Session Lock & Idle Timeout** | • Config `SESSION_TIMEOUT` (default 15 min). <br>• `AuthGuard` clears in‑memory keys & seeds. <br>• CLI `seedpass lock` + GUI menu “Lock vault”. |
|
||||
|
||||
**Exit‑criteria** : All functions green in CI, consumed by both CLI (Typer) *and* a minimal Qt test harness.
|
||||
|
||||
---
|
||||
|
||||
## Phase B • Data Portability (encrypted only)
|
||||
|
||||
| Prio | Feature | Notes | |
|
||||
| ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| ⭐ | **Encrypted Profile Export** | • CLI `seedpass export --out myprofile.enc` <br>• Serialise *encrypted* entry files → single JSON wrapper → `EncryptionManager.encrypt_data()` <br>• Always require active profile unlock. | |
|
||||
| ⭐ | **Encrypted Profile Import / Merge** | • CLI \`seedpass import myprofile.enc \[--strategy skip | overwrite-newer]` <br>• Verify fingerprint match before ingest. <br>• Conflict policy pluggable; default `skip\`. |
|
||||
|
||||
---
|
||||
|
||||
## Phase C • Advanced secrets & sync
|
||||
|
||||
| Prio | Feature | Notes |
|
||||
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| ◇ | **TOTP entry kind** | • `kind="totp_secret"` fields: title, issuer, username, secret\_key <br>• `secret_key` encrypted; handler uses `pyotp` to show current code. |
|
||||
| ◇ | **Manual Conflict Resolver** | • When `checksum` mismatch *and* both sides newer than last sync → prompt user (CLI) or modal (GUI). |
|
||||
|
||||
---
|
||||
|
||||
## Phase D • Desktop GUI MVP (Qt 6)
|
||||
|
||||
*Features here ride on the Core API; keep UI totally stateless.*
|
||||
|
||||
| Prio | Feature | Notes |
|
||||
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 🔥 | **Login Window** | • Unlock profile with master pw. <br>• Profile switcher drop‑down. |
|
||||
| 🔥 | **Vault Window** | • Sidebar (Entries, Search, Backups, Settings). <br>• `QTableView` bound to `VaultService.list_entries()` <br>• Sort & basic filters built‑in. |
|
||||
| 🔥 | **Entry Editor Dialog** | • Dynamic form driven by `kinds.py`. <br>• Add / Edit. |
|
||||
| ⭐ | **Sync Status Bar** | • Pulsing icon + last sync timestamp; hooks into `SyncService` bus. |
|
||||
| ◇ | **Relay Manager Dialog** | • CRUD & ping test per relay. |
|
||||
|
||||
*Binary packaging (PyInstaller matrix build) is already tracked in the roadmap and is not duplicated here.*
|
||||
|
||||
---
|
||||
|
||||
## Phase E • Later / Research
|
||||
|
||||
• Hardware‑wallet unlock (SLIP‑39 share)
|
||||
• Background daemon (`seedpassd` + gRPC)
|
||||
• Mobile companion (Flutter FFI)
|
||||
• Federated search across multiple profiles
|
||||
|
||||
---
|
||||
|
||||
**Reminder:** *No plaintext exports, no on‑disk temp files, and no writing decrypted data to Nostr.* Everything funnels through the encryption stack or stays in memory for the current unlocked session only.
|
||||
113
refactor.md
113
refactor.md
@@ -1,113 +0,0 @@
|
||||
# SeedPass v2 Roadmap — CLI → Desktop GUI
|
||||
|
||||
> **Guiding principles**
|
||||
>
|
||||
> 1. **Core-first** – a headless, testable Python package (`seedpass.core`) that is 100 % GUI-agnostic.
|
||||
> 2. **Thin adapters** – CLI, GUI, and future mobile layers merely call the core API.
|
||||
> 3. **Stateless UI** – all persistence lives in core services; UI never touches vault files directly.
|
||||
> 4. **Parity at every step** – CLI must keep working while GUI evolves.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 • Tooling Baseline
|
||||
|
||||
| # | Task | Rationale |
|
||||
| --- | ---------------------------------------------------------------------------------------------- | --------------------------------- |
|
||||
| 0.1 | ✅ **Adopt `poetry`** (or `hatch`) for builds & dependency pins. | Single-source version + lockfile. |
|
||||
| 0.2 | ✅ **GitHub Actions**: lint (ruff), type-check (mypy), tests (pytest -q), coverage gate ≥ 85 %. | Prevent regressions. |
|
||||
| 0.3 | ✅ Pre-commit hooks: ruff –fix, black, isort. | Uniform style. |
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 • Finalize Core Refactor (CLI still primary)
|
||||
|
||||
> *Most of this is already drafted – here’s what must ship before GUI work starts.*
|
||||
|
||||
| # | Component | Must-have work |
|
||||
| --- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| 1.1 | **`kinds.py` registry + per-kind handler modules** | import-safe; handler signature `(data,fingerprint,**svc)` |
|
||||
| 1.2 | **`StateManager`** | JSON file w/ fcntl lock<br>keys: `last_bip85_idx`, `last_sync_ts` |
|
||||
| 1.3 | **Checksum inside entry metadata** | `sha256(json.dumps(data,sort_keys=True))` |
|
||||
| 1.4 | **Replaceable Nostr events** (kind 31111, `d` tag = `"{kindtag}{entry_num}"`) | publish/update/delete tombstone |
|
||||
| 1.5 | **Per-entry `EntryManager` / `BackupManager`** | Save / load / backup / restore individual encrypted files |
|
||||
| 1.6 | **CLI rewritten with Typer** | Typer commands map 1-to-1 with core service methods; preserves colours. |
|
||||
| 1.7 | **Legacy index migration command** | `seedpass migrate-legacy` – idempotent, uses `add_entry()` under the hood. |
|
||||
| 1.8 | **bcrypt + NFKD master password hash** | Stored per fingerprint. |
|
||||
|
||||
> **Exit-criteria:** end-to-end flow (`add → list → sync → restore`) green in CI and covered by tests.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 • Core API Hardening (prep for GUI)
|
||||
|
||||
| # | Task | Deliverable |
|
||||
| --- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| 2.1 | **Public Service Layer** (`seedpass.api`) | Facade classes:<br>`VaultService`, `ProfileService`, `SyncService` – *no* CLI / UI imports. |
|
||||
| 2.2 | **Thread-safe gate** | Re-entrancy locks so GUI threads can call core safely. |
|
||||
| 2.3 | **Fast in-process event bus** | Simple `pubsub.py` (observer pattern) for GUI to receive progress callbacks (e.g. sync progress, long ops). |
|
||||
| 2.4 | **Docstrings + pydantic models** | Typed request/response objects → eases RPC later (e.g. REST, gRPC). |
|
||||
| 2.5 | **Library packaging** | `python -m pip install .` gives importable `seedpass`. |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 • Desktop GUI MVP
|
||||
|
||||
| # | Decision | Notes |
|
||||
| --- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| 3.0 | **Framework: PySide 6 (Qt 6)** | ✓ LGPL, ✓ native look, ✓ Python-first, ✓ WebEngine if needed. |
|
||||
| 3.1 | **Process model** | *Same* process; GUI thread ↔ core API via signals/slots.<br>(If we outgrow this, swap to a local gRPC server later.) |
|
||||
| 3.2 | **UI Skeleton (milestone “Hello Vault”)** | |
|
||||
| – | `LoginWindow` | master-password prompt → opens default profile |
|
||||
| – | `VaultWindow` | sidebar (Profiles, Entries, Backups) + stacked views |
|
||||
| – | `EntryTableView` | QTableView bound to `VaultService.list_entries()` |
|
||||
| – | `EntryEditorDialog` | Add / Edit forms – field set driven by `kinds.py` |
|
||||
| – | `SyncStatusBar` | pulse animation + last-sync timestamp |
|
||||
| 3.3 | **Icons / theming** | Start with Qt-built-in icons; later swap to SVG set. |
|
||||
| 3.4 | **Packaging** | `PyInstaller --onefile` for Win / macOS / Linux AppImage; GitHub Actions matrix build. |
|
||||
| 3.5 | **GUI E2E tests** | PyTest + pytest-qt (QtBot) smoke flows; run headless in CI (Xvfb). |
|
||||
|
||||
> **Stretch option:** wrap the same UI in **Tauri** later for a lighter binary (\~5 MB), reusing the core API through a local websocket RPC.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 • Unified Workflows & Coverage
|
||||
|
||||
| # | Task |
|
||||
| --- | --------------------------------------------------------------------------------------- |
|
||||
| 4.1 | Extend GitHub Actions to build GUI artifacts on every tag. |
|
||||
| 4.2 | Add synthetic coverage for GUI code paths (QtBot). |
|
||||
| 4.3 | Nightly job: spin up headless GUI, run `sync` against test relay, assert no exceptions. |
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 • Future-Proofing (post-GUI v1)
|
||||
|
||||
| Idea | Sketch |
|
||||
| -------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| **Background daemon** | Optional `seedpassd` exposing Unix socket + JSON-RPC; both CLI & GUI become thin clients. |
|
||||
| **Hardware-wallet unlock** | Replace master password with HWW + SLIP-39 share; requires PyUSB bridge. |
|
||||
| **Mobile companion app** | Reuse core via BeeWare or Flutter FFI; sync over Nostr only (no local vault). |
|
||||
| **End-to-end test farm** | dedicated relay docker-compose + pytest-subprocess to fake flaky relays. |
|
||||
|
||||
---
|
||||
|
||||
## Deliverables Checklist
|
||||
|
||||
* [ ] Core refactor merged, tests ≥ 85 % coverage
|
||||
* [ ] `seedpass` installs and passes `python -m seedpass.cli --help`
|
||||
* [ ] `seedpass-gui` binary opens vault, lists entries, adds & edits, syncs
|
||||
* [ ] GitHub Actions builds binaries for Win/macOS/Linux on tag
|
||||
* [ ] `docs/ARCHITECTURE.md` diagrams core ↔ CLI ↔ GUI layers
|
||||
|
||||
When the above are ✅ we can ship `v2.0.0-beta.1` and invite early desktop testers.
|
||||
|
||||
---
|
||||
|
||||
### 🔑 Key Takeaways
|
||||
|
||||
1. **Keep all state & crypto in the core package.**
|
||||
2. **Expose a clean Python API first – GUI is “just another client.”**
|
||||
3. **Checksum + replaceable Nostr events give rock-solid sync & conflict handling.**
|
||||
4. **Lock files and StateManager prevent index reuse and vault corruption.**
|
||||
5. **The GUI sprint starts only after Phase 1 + 2 are fully green in CI.**
|
||||
|
||||
Reference in New Issue
Block a user