Repository Guidelines

This project is written in Python. Follow these instructions when working with the code base.

Installation Quickstart for AI Agents

Prerequisites

Ensure the system has the required build tools and Python headers. Examples:

# Ubuntu/Debian
sudo apt update && sudo apt install -y \
    build-essential \
    libffi-dev \
    pkg-config \
    python3.11-dev \
    curl \
    git

# CentOS/RHEL
sudo yum install -y gcc gcc-c++ libffi-devel pkgconfig python3-devel curl git

# macOS
brew install python@3.11 libffi pkg-config git

Installation

Run the installer script to fetch the latest release:

# Stable release
bash -c "$(curl -sSL https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.sh)"

# Beta branch
bash -c "$(curl -sSL https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.sh)" _ -b beta

Environment Layout

Virtual environment: ~/.seedpass/app/venv/
Entry point: ~/.seedpass/app/src/main.py

Verification

cd ~/.seedpass/app && source venv/bin/activate
cd src && python main.py --version  # Expected: SeedPass v[version]

Running SeedPass

cd ~/.seedpass/app && source venv/bin/activate
cd src && python main.py

Running Tests

Set up a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install --require-hashes -r requirements.lock

Run the test suite using pytest:
```
pytest
```
Currently the test folder is located in src/tests/. New tests should be placed there so pytest can discover them automatically.

Style Guidelines

Adhere to PEP 8 conventions (4‑space indentation, descriptive names, docstrings).
Use black to format Python files before committing:
```
black .
```
Optionally run flake8 or another linter to catch style issues.

Security Practices

Never commit seed phrases, passwords, private keys, or other sensitive data.
Use environment variables or local configuration files (ignored by Git) for secrets.
Review code for potential information leaks (e.g., verbose logging) before submitting.

Following these practices helps keep the code base consistent and secure.

Deterministic Artifact Generation

All generated artifacts (passwords, keys, TOTP secrets, etc.) must be fully deterministic across runs and platforms.
Randomness is only permitted for security primitives (e.g., encryption nonces, in-memory keys) and must never influence derived artifacts.

Legacy Index Migration

Always provide a migration path for index archives and import/export routines.
Support older SeedPass versions whose indexes lacked salts or password-based encryption by detecting legacy formats and upgrading them to the current schema.
Ensure migrations unlock older account indexes and allow Nostr synchronization.
Add regression tests covering these migrations whenever the index format or encryption changes.

Integrating New Entry Types

SeedPass supports multiple kind values in its JSON entry files. When adding a new kind (for example, SSH keys or BIP‑39 seeds) use the checklist below:

Menu Updates – Extend the CLI menus in main.py so "Add Entry" offers choices for the new types and retrieval operations handle them properly. The current main menu looks like this:
```
Select an option:
1. Add Entry
2. Retrieve Entry
3. Search Entries
4. Modify an Existing Entry
5. 2FA Codes
6. Settings
7. Exit
```
JSON Schema – Each entry file must include a kind field describing the entry type. Add new values (ssh, seed, etc.) as needed and implement handlers so older kinds continue to work.
Best Practices – When introducing a new kind, follow the modular architecture guidelines from docs/json_entries.md:
- Use clear, descriptive names.
- Keep handler code for each kind separate.
- Validate required fields and gracefully handle missing data.
- Add regression tests to ensure backward compatibility.

This procedure keeps the UI consistent and ensures new data types integrate smoothly with existing functionality.

4.2 KiB Raw Permalink Blame History Unescape Escape