zenithpasskeys 1.1.0__tar.gz

zenithpasskeys-1.1.0/.gitignore

@@ -0,0 +1,80 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+venv/
+.venv/
+env/
+.env/
+env.bak/
+venv.bak/
+
+# Environment Variables
+.env
+.env.local
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+*.bak
+*.tmp
+*~
+
+# Project specific
+/plan.md
+/audit_test.py
+/cli/tests/audit_test.py
+
+# Sensitive files — NEVER commit these
+vault.enc
+*.enc
+gdrive_token.json
+host_debug.log
+
+# Debug/temp scripts
+cli/fix_tests.py
+cli/test_debug.py
+cli/test_host.py
+
+# Native host manifests (generated per-machine)
+native-manifests/

zenithpasskeys-1.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.3
+Name: zenithpasskeys
+Version: 1.1.0
+Summary: Local-first, air-gapped passkey manager with encrypted vault
+Project-URL: Homepage, https://github.com/roshhellwett/projectwarden
+Project-URL: Repository, https://github.com/roshhellwett/projectwarden
+Project-URL: Documentation, https://github.com/roshhellwett/projectwarden/blob/main/docs/SETUP.md
+Project-URL: Issues, https://github.com/roshhellwett/projectwarden/issues
+Author-email: Zenith Open Source Projects <zenithprojects@icloud.com>
+License: MIT
+Keywords: cryptography,fido2,passkeys,password-manager,security,webauthn
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: cbor2>=5.6
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=43.0
+Requires-Dist: filelock>=3.13
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Zenith Passkeys (`zenithpasskeys`)
+
+[![PyPI version](https://img.shields.io/pypi/v/zenithpasskeys.svg)](https://pypi.org/project/zenithpasskeys/)
+[![Python versions](https://img.shields.io/pypi/pyversions/zenithpasskeys.svg)](https://pypi.org/project/zenithpasskeys/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> **Local-first, air-gapped passkey (WebAuthn & FIDO2) manager with an encrypted vault.**  
+> Built and managed by **Zenith Open Source Projects**.
+
+---
+
+## Highlights
+
+- 🔒 **100% Local-First & Air-Gapped:** Zero cloud accounts, zero telemetry, zero external network requests. Your private keys never touch the internet.
+- 🛡️ **Hardware-Grade Cryptography:** Master Encryption Key (MEK) protected by **Argon2id** (64MB RAM, 3 iterations, 4 lanes) and **AES-256-GCM** authenticated encryption.
+- 🔑 **Dual-Slot Emergency Recovery:** Instant vault recovery using a 32-character Crockford Base32 emergency key (`XXXX-XXXX-...`). Re-wraps the MEK under a new password without losing any passkeys.
+- ⚡ **Zero Setup Required:** Runs out of the box in any environment without manual virtualenv activation or system compilation.
+- 🌐 **Dual Standalone or Browser Mode:** Use purely from the terminal as an independent passkey vault, or pair seamlessly with the Zenith Passkeys Chrome/Edge/Firefox Web Extension.
+
+---
+
+## Installation
+
+Install in any environment via `pip`:
+
+```bash
+pip install zenithpasskeys
+```
+
+Or install cleanly using `pipx` (recommended for isolated CLI tools with zero venv management):
+
+```bash
+pipx install zenithpasskeys
+```
+
+Once installed, you can launch the CLI using either command:
+
+```bash
+zenith-passkeys
+# or
+zenithpasskeys
+```
+
+---
+
+## Quickstart Guide
+
+### 1. Initialize Your Secure Vault
+Create a new encrypted vault and generate your 32-character Emergency Recovery Key:
+
+```bash
+zenith-passkeys init
+```
+
+Save the printed recovery key in a physical notebook or cold storage.
+
+### 2. View Stored Passkeys
+List all passkey credentials stored in your local vault:
+
+```bash
+zenith-passkeys list
+
+# Filter by domain:
+zenith-passkeys list --domain github.com
+```
+
+### 3. Run a Security Audit
+Perform an offline diagnostic check for duplicate credentials or stale passkeys:
+
+```bash
+zenith-passkeys audit
+```
+
+### 4. Export & Import Credentials
+Securely export your credentials (encrypted with a dedicated export password):
+
+```bash
+# Encrypted export (recommended):
+zenith-passkeys export --encrypt
+
+# Plaintext export:
+zenith-passkeys export
+```
+
+Import credentials from another Zenith instance or migration file:
+
+```bash
+zenith-passkeys import export.json
+```
+
+### 5. Create Local Backup Snapshots
+Create an encrypted backup snapshot directly to an external drive, USB stick, or backup directory:
+
+```bash
+zenith-passkeys backup create /path/to/backup/zenith-vault-backup.enc
+```
+
+### 6. Emergency Recovery
+Forgot your master password? Recover your vault and set a new password using your Emergency Recovery Key:
+
+```bash
+zenith-passkeys recover
+```
+
+### 7. Instant Lock
+Clear active authentication sessions and lock the vault across all processes:
+
+```bash
+zenith-passkeys lock
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---|---|
+| `zenith-passkeys init` | Initialize a new vault and register native host messaging |
+| `zenith-passkeys list` | Display stored passkeys with rich metadata and domain filtering |
+| `zenith-passkeys audit` | Run offline security diagnostics and health scoring |
+| `zenith-passkeys export` | Export credentials to encrypted or plaintext JSON |
+| `zenith-passkeys import` | Import credentials from encrypted or plaintext export files |
+| `zenith-passkeys backup` | Create or restore encrypted vault backup snapshots |
+| `zenith-passkeys recover` | Reset master password using 32-character Emergency Recovery Key |
+| `zenith-passkeys change-password` | Update master password and re-wrap vault master key |
+| `zenith-passkeys lock` | Clear active memory session and lock the vault |
+| `zenith-passkeys config` | Configure auto-lock timeout (inactivity minutes) |
+| `zenith-passkeys delete` | Permanently delete a credential by domain |
+| `zenith-passkeys logs` | View internal diagnostic action audit trail |
+
+---
+
+## Pairing with the Browser Extension (Optional)
+
+Zenith Passkeys works as a standalone terminal manager, but also pairs with the **Zenith Passkeys Browser Extension** for passwordless web logins.
+
+When you run:
+
+```bash
+zenith-passkeys init
+```
+
+it automatically writes the Native Messaging manifest for Google Chrome, Microsoft Edge, and Mozilla Firefox. The browser extension can then securely communicate with the local `zenith-passkeys-host` daemon to sign WebAuthn ceremonies on sites like GitHub, Google, and Amazon.
+
+---
+
+## Security Architecture
+
+1. **Argon2id Key Derivation:**
+   - Memory: 64 MB (`m=65536`)
+   - Iterations: 3 (`t=3`)
+   - Parallelism: 4 lanes (`p=4`)
+2. **Dual-Slot Key Wrapping:**
+   - Slot 0 (`pwWrapped`): Master Encryption Key encrypted under master password.
+   - Slot 1 (`recWrapped`): Master Encryption Key encrypted under the 32-character recovery key.
+   - Password changes re-wrap Slot 0 while keeping the recovery key permanently functional.
+3. **Atomic Operations & Integrity:**
+   - Atomic file replace using tempfile swaps to eliminate corruption risks.
+   - File locks via `filelock` prevent concurrent write race conditions.
+   - Public Suffix List (PSL) validation prevents cross-subdomain credential spoofing.
+
+---
+
+## License & Support
+
+- **License:** Open source under the [MIT License](https://opensource.org/licenses/MIT).
+- **Repository:** [GitHub](https://github.com/roshhellwett/projectwarden)
+- **Support & Security Disclosures:** `zenithprojects@icloud.com`
+- **Maintained by:** **Zenith Open Source Projects**

zenithpasskeys-1.1.0/README.md

@@ -0,0 +1,169 @@
+# Zenith Passkeys (`zenithpasskeys`)
+
+[![PyPI version](https://img.shields.io/pypi/v/zenithpasskeys.svg)](https://pypi.org/project/zenithpasskeys/)
+[![Python versions](https://img.shields.io/pypi/pyversions/zenithpasskeys.svg)](https://pypi.org/project/zenithpasskeys/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> **Local-first, air-gapped passkey (WebAuthn & FIDO2) manager with an encrypted vault.**  
+> Built and managed by **Zenith Open Source Projects**.
+
+---
+
+## Highlights
+
+- 🔒 **100% Local-First & Air-Gapped:** Zero cloud accounts, zero telemetry, zero external network requests. Your private keys never touch the internet.
+- 🛡️ **Hardware-Grade Cryptography:** Master Encryption Key (MEK) protected by **Argon2id** (64MB RAM, 3 iterations, 4 lanes) and **AES-256-GCM** authenticated encryption.
+- 🔑 **Dual-Slot Emergency Recovery:** Instant vault recovery using a 32-character Crockford Base32 emergency key (`XXXX-XXXX-...`). Re-wraps the MEK under a new password without losing any passkeys.
+- ⚡ **Zero Setup Required:** Runs out of the box in any environment without manual virtualenv activation or system compilation.
+- 🌐 **Dual Standalone or Browser Mode:** Use purely from the terminal as an independent passkey vault, or pair seamlessly with the Zenith Passkeys Chrome/Edge/Firefox Web Extension.
+
+---
+
+## Installation
+
+Install in any environment via `pip`:
+
+```bash
+pip install zenithpasskeys
+```
+
+Or install cleanly using `pipx` (recommended for isolated CLI tools with zero venv management):
+
+```bash
+pipx install zenithpasskeys
+```
+
+Once installed, you can launch the CLI using either command:
+
+```bash
+zenith-passkeys
+# or
+zenithpasskeys
+```
+
+---
+
+## Quickstart Guide
+
+### 1. Initialize Your Secure Vault
+Create a new encrypted vault and generate your 32-character Emergency Recovery Key:
+
+```bash
+zenith-passkeys init
+```
+
+Save the printed recovery key in a physical notebook or cold storage.
+
+### 2. View Stored Passkeys
+List all passkey credentials stored in your local vault:
+
+```bash
+zenith-passkeys list
+
+# Filter by domain:
+zenith-passkeys list --domain github.com
+```
+
+### 3. Run a Security Audit
+Perform an offline diagnostic check for duplicate credentials or stale passkeys:
+
+```bash
+zenith-passkeys audit
+```
+
+### 4. Export & Import Credentials
+Securely export your credentials (encrypted with a dedicated export password):
+
+```bash
+# Encrypted export (recommended):
+zenith-passkeys export --encrypt
+
+# Plaintext export:
+zenith-passkeys export
+```
+
+Import credentials from another Zenith instance or migration file:
+
+```bash
+zenith-passkeys import export.json
+```
+
+### 5. Create Local Backup Snapshots
+Create an encrypted backup snapshot directly to an external drive, USB stick, or backup directory:
+
+```bash
+zenith-passkeys backup create /path/to/backup/zenith-vault-backup.enc
+```
+
+### 6. Emergency Recovery
+Forgot your master password? Recover your vault and set a new password using your Emergency Recovery Key:
+
+```bash
+zenith-passkeys recover
+```
+
+### 7. Instant Lock
+Clear active authentication sessions and lock the vault across all processes:
+
+```bash
+zenith-passkeys lock
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---|---|
+| `zenith-passkeys init` | Initialize a new vault and register native host messaging |
+| `zenith-passkeys list` | Display stored passkeys with rich metadata and domain filtering |
+| `zenith-passkeys audit` | Run offline security diagnostics and health scoring |
+| `zenith-passkeys export` | Export credentials to encrypted or plaintext JSON |
+| `zenith-passkeys import` | Import credentials from encrypted or plaintext export files |
+| `zenith-passkeys backup` | Create or restore encrypted vault backup snapshots |
+| `zenith-passkeys recover` | Reset master password using 32-character Emergency Recovery Key |
+| `zenith-passkeys change-password` | Update master password and re-wrap vault master key |
+| `zenith-passkeys lock` | Clear active memory session and lock the vault |
+| `zenith-passkeys config` | Configure auto-lock timeout (inactivity minutes) |
+| `zenith-passkeys delete` | Permanently delete a credential by domain |
+| `zenith-passkeys logs` | View internal diagnostic action audit trail |
+
+---
+
+## Pairing with the Browser Extension (Optional)
+
+Zenith Passkeys works as a standalone terminal manager, but also pairs with the **Zenith Passkeys Browser Extension** for passwordless web logins.
+
+When you run:
+
+```bash
+zenith-passkeys init
+```
+
+it automatically writes the Native Messaging manifest for Google Chrome, Microsoft Edge, and Mozilla Firefox. The browser extension can then securely communicate with the local `zenith-passkeys-host` daemon to sign WebAuthn ceremonies on sites like GitHub, Google, and Amazon.
+
+---
+
+## Security Architecture
+
+1. **Argon2id Key Derivation:**
+   - Memory: 64 MB (`m=65536`)
+   - Iterations: 3 (`t=3`)
+   - Parallelism: 4 lanes (`p=4`)
+2. **Dual-Slot Key Wrapping:**
+   - Slot 0 (`pwWrapped`): Master Encryption Key encrypted under master password.
+   - Slot 1 (`recWrapped`): Master Encryption Key encrypted under the 32-character recovery key.
+   - Password changes re-wrap Slot 0 while keeping the recovery key permanently functional.
+3. **Atomic Operations & Integrity:**
+   - Atomic file replace using tempfile swaps to eliminate corruption risks.
+   - File locks via `filelock` prevent concurrent write race conditions.
+   - Public Suffix List (PSL) validation prevents cross-subdomain credential spoofing.
+
+---
+
+## License & Support
+
+- **License:** Open source under the [MIT License](https://opensource.org/licenses/MIT).
+- **Repository:** [GitHub](https://github.com/roshhellwett/projectwarden)
+- **Support & Security Disclosures:** `zenithprojects@icloud.com`
+- **Maintained by:** **Zenith Open Source Projects**

zenithpasskeys-1.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling<1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zenithpasskeys"
+version = "1.1.0"
+description = "Local-first, air-gapped passkey manager with encrypted vault"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{name = "Zenith Open Source Projects", email = "zenithprojects@icloud.com"}]
+keywords = ["passkeys", "webauthn", "fido2", "password-manager", "cryptography", "security"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "click>=8.1",
+    "cryptography>=43.0",
+    "platformdirs>=4.0",
+    "filelock>=3.13",
+    "cbor2>=5.6",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+]
+
+[project.scripts]
+zenith-passkeys = "zenith_passkeys.main:cli"
+zenithpasskeys = "zenith_passkeys.main:cli"
+zenith-passkeys-host = "zenith_passkeys.native_host.host:main"
+
+[project.urls]
+Homepage = "https://github.com/roshhellwett/projectwarden"
+Repository = "https://github.com/roshhellwett/projectwarden"
+Documentation = "https://github.com/roshhellwett/projectwarden/blob/main/docs/SETUP.md"
+Issues = "https://github.com/roshhellwett/projectwarden/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zenith_passkeys"]

zenithpasskeys-1.1.0/src/zenith_passkeys/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

zenithpasskeys-1.1.0/src/zenith_passkeys/__main__.py

@@ -0,0 +1,4 @@
+from .main import cli
+
+if __name__ == "__main__":
+    cli()

zenithpasskeys-1.1.0/src/zenith_passkeys/backup/__init__.py

@@ -0,0 +1,4 @@
+"""Local backup module for Zenith Passkeys.
+
+Built and managed by Zenith Open Source Projects.
+"""

zenithpasskeys-1.1.0/src/zenith_passkeys/commands/_shared.py

@@ -0,0 +1,43 @@
+import click
+from rich.console import Console
+from rich.markup import escape
+
+from ..core.errors import SUPPORT_EMAIL
+from ..core.vault import VaultManager
+
+console = Console()
+
+VAULT_MISSING_MSG = "No vault found. Run [green]'zenith-passkeys init'[/green] first."
+
+
+def handle_vault_error(e: Exception) -> None:
+    """Translate vault-layer failures into clean, actionable CLI errors."""
+    from cryptography.exceptions import InvalidTag
+
+    if isinstance(e, InvalidTag) or "password" in str(e).lower():
+        console.print("[red]Wrong password.[/red]")
+    elif "recovery" in str(e).lower():
+        console.print("[red]Wrong recovery key or corrupted vault.[/red]")
+    elif "corrupted" in str(e).lower() or "Invalid" in str(e):
+        console.print(f"[red]Vault file is corrupted: {escape(str(e))}[/red]")
+        console.print(f"[yellow]Contact {SUPPORT_EMAIL} with error code below if this persists.[/yellow]")
+    else:
+        console.print(f"[red]{escape(str(e))}[/red]")
+    raise SystemExit(1)
+
+
+def require_vault(vault: VaultManager) -> None:
+    if not vault.exists():
+        console.print(f"[red]{VAULT_MISSING_MSG}[/red]")
+        raise SystemExit(1)
+
+
+def unlock_vault(vault: VaultManager, prompt: str = "Master password") -> tuple:
+    """Prompt, unlock, and convert any failure into a clean exit."""
+    from cryptography.exceptions import InvalidTag
+
+    password = click.prompt(prompt, hide_input=True)
+    try:
+        return vault.unlock(password), password
+    except (InvalidTag, ValueError) as e:
+        handle_vault_error(e)

zenithpasskeys-1.1.0/src/zenith_passkeys/commands/audit_cmd.py

@@ -0,0 +1,93 @@
+import json
+from datetime import datetime, timezone
+
+import click
+from cryptography.exceptions import InvalidTag
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from ..core.vault import VaultManager
+from ._shared import handle_vault_error, require_vault
+
+console = Console()
+
+
+@click.command()
+@click.option("--unused-days", default=90, type=int, help="Days of inactivity threshold")
+@click.option("--dns", is_flag=True, help="Also check domain DNS resolution (makes network requests)")
+@click.option("--json-output", "json_flag", is_flag=True, help="Output as JSON")
+def audit(unused_days: int, dns: bool, json_flag: bool):
+    """Audit vault for security issues (offline by default)."""
+    vault = VaultManager()
+    require_vault(vault)
+
+    from ._shared import unlock_vault
+    try:
+        (payload, _), _pw = unlock_vault(vault)
+    except (InvalidTag, ValueError) as e:
+        handle_vault_error(e)
+
+    issues = []
+    now = datetime.now(timezone.utc)
+
+    for c in payload.credentials:
+        if c.last_used_at:
+            try:
+                last = datetime.fromisoformat(c.last_used_at)
+            except ValueError:
+                continue
+            if (now - last).days >= unused_days:
+                issues.append({
+                    "type": "stale",
+                    "severity": "low",
+                    "rp_id": c.rp_id,
+                    "username": c.username,
+                    "detail": f"Not used in {(now - last).days} days",
+                })
+
+    seen = {}
+    for c in payload.credentials:
+        key = (c.rp_id, c.username)
+        if key in seen:
+            issues.append({
+                "type": "duplicate",
+                "severity": "medium",
+                "rp_id": c.rp_id,
+                "username": c.username,
+                "detail": "Multiple credentials for same rpId+username",
+            })
+        seen[key] = True
+
+    # DNS resolution is OPT-IN: it sends every stored domain to the system
+    # resolver, which leaks the user's site list. Default is offline.
+    if dns:
+        import socket
+        for domain in {c.rp_id for c in payload.credentials}:
+            try:
+                socket.getaddrinfo(domain, 443, socket.AF_INET, socket.SOCK_STREAM)
+            except socket.gaierror:
+                issues.append({
+                    "type": "unresolvable",
+                    "severity": "high",
+                    "rp_id": domain,
+                    "username": "",
+                    "detail": f"Cannot resolve {domain}",
+                })
+
+    if json_flag:
+        console.print_json(json.dumps(issues, indent=2))
+    else:
+        if not issues:
+            console.print("[green]No issues found. Vault looks good.[/green]")
+            raise SystemExit(0)
+
+        table = Table(title=f"Audit Issues ({len(issues)})")
+        table.add_column("Severity", style="yellow")
+        table.add_column("Type", style="cyan")
+        table.add_column("Domain", style="white")
+        table.add_column("Detail", style="white")
+        for issue in issues:
+            table.add_row(escape(issue["severity"]), escape(issue["type"]), escape(issue["rp_id"]), escape(issue["detail"]))
+        console.print(table)
+        raise SystemExit(1)