feat(generator): Add stateless/deterministic password derivation mode

[dinesh-git17]

Problem Statement

Users who prefer a stateless password management approach currently have no option in PassFX. Some users don't want to store passwords at all - they want to derive them deterministically from a master password + identifier combination.

Use cases:

• Users paranoid about vault file storage/sync
• Need consistent passwords across devices with zero sync infrastructure
• Minimal attack surface preference (no database to breach)
• Backup/recovery simplicity (nothing to back up except remembering the master password)

Proposed Solution

Add a Derived Mode to the existing password generator screen as an alternative to the current random generation:

Generator Screen
├── Random Mode (current)      → generates random passwords/passphrases
└── Derived Mode (new)         → deterministic from master + identifier

API Design

def derive_password(
    master_password: str,
    identifier: str,           # e.g., "myemail@gmail.com" or "YouTube2025"
    salt: bytes,               # from ~/.passfx/salt (already exists)
    length: int = 20,
    charset: Literal["special", "alnum", "numeric", "alpha"] = "special",
    version: int = 1,          # increment to rotate same identifier
) -> str:
    """Deterministically derive password from inputs."""

UI Changes

• Toggle switch in generator screen: Random / Derived
• When Derived mode selected:
  • Master password input (uses current vault master password or separate input)
  • Identifier input field (memorable label)
  • Version number spinner (default 1)
  • Existing charset and length options work as-is
• Clear warning: "If you forget the exact identifier or version, this password is unrecoverable"

Cryptographic Implementation

• PBKDF2-HMAC-SHA256 with 480,000 iterations (matching existing KDF parameters)
• Use existing salt from ~/.passfx/salt
• Proper entropy-preserving mapping from derived bytes to character set
• All operations via cryptography library and secrets module

Alternatives Considered

1. Separate standalone tool - Rejected; better UX to integrate into existing generator
2. Replace vault entirely - Rejected; vault needed for metadata, arbitrary credentials, import/export
3. Store derived password settings in vault - Could optionally save identifier/version/charset as a "recipe" without storing the actual password

Feature Area

Password Generator

Scope / Impact

Medium (new functionality, moderate changes)

Acceptance Criteria

• Generator screen has toggle between Random and Derived modes
• Derived mode accepts identifier, version, length, charset inputs
• Same inputs always produce identical output (deterministic)
• Uses PBKDF2-HMAC-SHA256 with 480k iterations
• Clear UI warning about unrecoverability
• Copy to clipboard works for derived passwords
• Unit tests cover derivation function with known test vectors
• No derived passwords or identifiers logged

Security Considerations

Strengths:

• Nothing stored = nothing to steal (for derived passwords)
• Attacker needs master password AND exact identifier AND version
• High iteration count makes brute force impractical

Risks to mitigate:

• Users forgetting identifiers (UI must warn clearly)
• Master password compromise affects ALL derived passwords (same as vault, but no rotation path)
• Side-channel: identifier input could leak via keyloggers (same risk as any input)

Implementation requirements:

• Must use secrets module, never random
• Must use cryptography library PBKDF2
• Must not log identifiers or derived passwords
• Constant-time comparison if any verification needed

Additional Context

Feature inspired by stateless password managers like LessPass, Master Password, and Spectre. This would give PassFX users the option to use either paradigm (or both) within the same tool.

Reference discussion: Reddit thread suggesting deterministic generation as alternative to vault storage.

[supasuge]

Suggested Improvements & Issues

Issues

1). Metadata Leakage + Salt file confusion

• Though this is medium-low severity, the less metadata available to a possible attacker the better. Error messages appear to leak metadata in various places.
• Salt stored in separate file: potential for desynchronization attacks

Why it matters

Scenario:
1. User creates vault with Salt_A -> vault.enc encrypted with Key_A
2. Attacker replaces salt file with Salt_B (symlink attack, race condition, backup restore)
3. User enters correct password -> derives Key_B (different from Key_A)
4. Decryption fails with generic "InvalidToken" error.

Mitigation/Remediation

# Store salt as prefix in vault file itself (like scrypt/bcrypt do)
vault_format = salt (32 bytes) || nonce || ciphertext || tag

# OR use HMAC of salt stored with vault
salt_verification = HMAC-SHA256(derived_key, salt)

2. Plaintext export is a footgun, and the UI exports sensitive fields by default:

Evidence (code):

passfx/utils/io.py:107 export_vault(... include_sensitive: bool = True)
passfx/screens/settings.py:217 calls export_vault(... include_sensitive=True) unconditionally.

Why it matters
Even with 0600 permissions, exports tend to:

• get copied, backed up, synced, emailed, indexed, or left on disk forever.
• be grabbed by malware without needing to crack anything. (Unimportant if data is encrypted due to low likelihood of brute-force)

Remediation

Default to masked export (no passwords/CVV) unless user explicitly enables sensitive export.

Add an encrypted export format (recommended):

• age (X25519) recipient keys
• password-based encryption with Argon2id + AEAD, or OS keychain wrapped key.
• Put a screaming warning + forced confirmation when exporting secrets.

Severity: High (user-triggered but catastrophic when it happens).

2.2 Memory Exposure Risks
Issue 1: String Interning
Python interns small strings and may keep them in memory indefinitely:

# PROBLEMATIC - password may be interned
password = input("Enter password: ")  # String object, immutable

# BETTER - use bytearray for sensitive data
password = bytearray(input("Enter password: "), 'utf-8')
# ... use password ...
for i in range(len(password)):
    password[i] = 0  # Explicit zeroing

2.3 Garbage Collection Timing

# BAD - derived_key stays in memory until GC
derived_key = pbkdf2_derive(password, salt)
fernet = Fernet(derived_key)
# derived_key reference persists

# BETTER - minimize key lifetime
class SecureKey:
    def __init__(self, key_bytes):
        self._key = bytearray(key_bytes)
    
    def __del__(self):
        for i in range(len(self._key)):
            self._key[i] = 0
    
    def get_key(self):
        return bytes(self._key)

2.4 Core Dumps
If the process crashes, memory contents (including decrypted vault) may be written to core dump files.

Mitigation

# Recommended: Disable core dumps at startup
import resource
resource.setrlimit(resource.RLIMIT_CORE, (0, 0))

# Also use mlock() for sensitive memory regions (requires CAP_IPC_LOCK)
import ctypes
libc = ctypes.CDLL('libc.so.6')
libc.mlock(sensitive_buffer, len(sensitive_buffer))

2.5 Swap file access
Issue: Decrypted vault contents in memory may be swapped to disk by a skilled attacker

# Attacker with user access can dump PassFX memory
gcore $(pgrep passfx)
strings core.* | grep -i password

Mitigation: Use prctl(PR_SET_DUMPABLE, 0) to prevent ptrace/core dumps:

---

Additional/overall recommendations:

1. XChaCha-Poly1305/AES-GCM is recommendeded over Fernet which uses AES-128-CBC-HMAC. This is mostly fine, however XChaCha-Poly1305 + AES-GCM both offers faster and more standard AEAD encryption for your intended use case. (Low overall impact. Fernet works just fine here, though it is not ideal, generally speaking).
2. Overwrite keys in memory with 0's before attempting to delete. < This is not handled properly currently.

• Doesn't account for an attacker extracting secrets from
• An attacker could recover

4. ECC Hybrid Authentication over the use of a master password.- Pros:

• Brute forcing the master password is impossible here. For it would require the ECC private key used during signing.
• Cons:
  • Introduces issues related to key rotation and key storage.
  • Lots of additional complexity involved with key management.

Solution: Use a hybrid approach as shown below

4. Use a memory-hard KDF such as argon2id.
5. A huge 256-bit salt is not where password managers win or lose. The more important thing is: does the vault format include a clean header with:

- version
- KDF algorithm + parameters
- salt
- encryption scheme id
- (optional) key-wrapping scheme id

Hardening Recommendation: Add a small structured header (JSON or binary), then encrypt the actual payload.

6. Accurately follow OWASP Password storage recommendations:

• Use Argon2id with a minimum configuration of 19 MiB of memory, an iteration count of 2, and 1 degree of parallelism.
• If Argon2id is not available, use scrypt with a minimum CPU/memory cost parameter of (2^17), a minimum block size of 8 (1024 bytes), and a parallelization parameter of 1.
• For legacy systems using bcrypt, use a work factor of 10 or more and with a password limit of 72 bytes.
• If FIPS-140 compliance is required, use PBKDF2 with a work factor of 600,000 or more and set with an internal hash function of HMAC-SHA-256.
  Source

Your current implementation should consider using argon2id or at least 600,000 iterations for PBKDF2.

7. Ideally, if it were my choice, I'd go with a hybrid encryption mechanism. This also enables you to properly encrypt all files with a different key (assuming each "Group/Category" is associated with the same public/private keypair either individually, or as a whole. Using a ECDHE mechanism, as long as the proper key material is stored within the metadata/file structure as shown below.

ECC Challenge-Response Protocol                          


**[Setup Phase]**
1. User generates ECC keypair (secp256k1 or Ed25519)                      
 2. Private key stored on hardware token OR encrypted with password (thus the hybrid approach)         
 3. Public key stored in vault metadata (unencrypted)                      

[Authentication Phase]                                                      
  PassFX                          User/Token                                  
challenge = random(32) ─>                                       
signature = sign(private_key, challenge || timestamp)│
verify(public_key, challenge || timestamp, signature)
derive_vault_key(private_key)

Few things to note:

• Use ed25519 for signing, X25519 for ECDH key derivation.

Vault format reccomendation:

Current: [Fernet token]

Proposed:
┌────────────────────────────────────────────────────────────────┐
│ Magic (8 bytes): "PASSFX01"                                   │
├────────────────────────────────────────────────────────────────┤
│ Version (4 bytes): 0x00000002                                 │
├────────────────────────────────────────────────────────────────┤
│ KDF ID (1 byte): 0x02 = Argon2id                            │
├────────────────────────────────────────────────────────────────┤
│ KDF Params (variable):                                             │
│   - time_cost (4 bytes)                                              │
│   - memory_cost (4 bytes)                                        │
│   - parallelism (4 bytes)                                            │
│   - salt (32 bytes)                                                      │
├────────────────────────────────────────────────────────────────┤
│ Cipher ID (1 byte): 0x02 = XChaCha20-Poly1305    │
├────────────────────────────────────────────────────────────────┤
│ Nonce (24 bytes)                                                      │
├────────────────────────────────────────────────────────────────┤
│ Ciphertext (variable)                                                 │
├────────────────────────────────────────────────────────────────┤
│ Auth Tag (16 bytes)                                                   │
└────────────────────────────────────────────────────────────────┘

Here is an example implementation of a HybridECCAuthenticator I vibe-coded using claude:

#!/usr/bin/env python3
"""
test_ecc_auth.py - Complete standalone test for ECC Challenge-Response Authentication

This module provides a full implementation and test suite for elliptic curve
cryptography-based authentication as an alternative/supplement to master passwords.

Features:
    - Ed25519 digital signatures for challenge-response authentication
    - X25519 ECDH for vault key derivation
    - Argon2id password-based key encryption for software-only mode
    - Hybrid authentication (password + ECC for 2FA)
    - Comprehensive test coverage

Requirements:
    pip install cryptography argon2-cffi

"""

import os
import sys
import time
import struct
import secrets
import hashlib
import unittest
from typing import Tuple, Optional, Dict, Any
from dataclasses import dataclass, field

# Cryptographic imports
from cryptography.hazmat.primitives.asymmetric.ed25519 import (
    Ed25519PrivateKey, Ed25519PublicKey
)
from cryptography.hazmat.primitives.asymmetric.x25519 import (
    X25519PrivateKey, X25519PublicKey
)
from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
from cryptography.hazmat.backends import default_backend
from cryptography.exceptions import InvalidSignature

# Try to import Argon2, fall back to PBKDF2 if not available
try:
    from argon2.low_level import hash_secret_raw, Type as Argon2Type
    HAS_ARGON2 = True
except ImportError:
    HAS_ARGON2 = False
    print("Warning: argon2-cffi not installed, using PBKDF2 fallback")


# =============================================================================
# Constants
# =============================================================================

KEY_SIZE = 32           # 256-bit keys
NONCE_SIZE = 12         # ChaCha20-Poly1305 nonce
SALT_SIZE = 16          # Argon2id salt
CHALLENGE_VALIDITY = 60  # seconds

# Argon2id parameters (OWASP recommended for sensitive data)
ARGON2_TIME_COST = 3
ARGON2_MEMORY_COST = 65536  # 64 MB
ARGON2_PARALLELISM = 4

# PBKDF2 fallback parameters
PBKDF2_ITERATIONS = 480000


# =============================================================================
# Exceptions
# =============================================================================

class AuthenticationError(Exception):
    """Base exception for authentication errors."""
    pass


class ChallengeExpiredError(AuthenticationError):
    """The authentication challenge has expired."""
    pass


class InvalidSignatureError(AuthenticationError):
    """The signature verification failed."""
    pass


class NoPendingChallengeError(AuthenticationError):
    """No challenge is pending for verification."""
    pass


class KeyDerivationError(AuthenticationError):
    """Key derivation or decryption failed."""
    pass


# =============================================================================
# Data Classes
# =============================================================================

@dataclass
class Challenge:
    """
    Authentication challenge containing a cryptographic nonce and timestamp.
    
    The challenge must be signed by the user's private key within the
    validity window to prove possession of the key without revealing it.
    
    Attributes:
        nonce: 32 random bytes ensuring uniqueness
        timestamp: Unix timestamp when challenge was created
        validity_seconds: How long the challenge remains valid
    """
    nonce: bytes
    timestamp: int
    validity_seconds: int = CHALLENGE_VALIDITY
    
    def __post_init__(self):
        if len(self.nonce) != KEY_SIZE:
            raise ValueError(f"Nonce must be {KEY_SIZE} bytes")
    
    def to_bytes(self) -> bytes:
        """Serialize challenge for signing: nonce || big-endian timestamp."""
        return self.nonce + struct.pack('>Q', self.timestamp)
    
    def is_expired(self) -> bool:
        """Check if challenge validity window has passed."""
        return time.time() > self.timestamp + self.validity_seconds
    
    @classmethod
    def generate(cls, validity_seconds: int = CHALLENGE_VALIDITY) -> 'Challenge':
        """Generate a fresh random challenge."""
        return cls(
            nonce=secrets.token_bytes(KEY_SIZE),
            timestamp=int(time.time()),
            validity_seconds=validity_seconds
        )
    
    def to_dict(self) -> Dict[str, Any]:
        """Serialize to dictionary for JSON/storage."""
        return {
            'nonce': self.nonce.hex(),
            'timestamp': self.timestamp,
            'validity_seconds': self.validity_seconds
        }
    
    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> 'Challenge':
        """Deserialize from dictionary."""
        return cls(
            nonce=bytes.fromhex(data['nonce']),
            timestamp=data['timestamp'],
            validity_seconds=data.get('validity_seconds', CHALLENGE_VALIDITY)
        )


# =============================================================================
# Key Derivation Utilities
# =============================================================================

def derive_key_argon2id(password: bytes, salt: bytes) -> bytes:
    """
    Derive a key from password using Argon2id.
    
    Argon2id is the recommended algorithm for password hashing as it provides
    resistance against both GPU and side-channel attacks.
    
    Args:
        password: The password bytes
        salt: Random salt (should be at least 16 bytes)
        
    Returns:
        32-byte derived key
    """
    if HAS_ARGON2:
        return hash_secret_raw(
            secret=password,
            salt=salt,
            time_cost=ARGON2_TIME_COST,
            memory_cost=ARGON2_MEMORY_COST,
            parallelism=ARGON2_PARALLELISM,
            hash_len=KEY_SIZE,
            type=Argon2Type.ID
        )
    else:
        # Fallback to PBKDF2 if Argon2 not available
        kdf = PBKDF2HMAC(
            algorithm=hashes.SHA256(),
            length=KEY_SIZE,
            salt=salt,
            iterations=PBKDF2_ITERATIONS,
            backend=default_backend()
        )
        return kdf.derive(password)


def derive_subkey(master: bytes, context: bytes) -> bytes:
    """
    Derive a subkey from master key material using HKDF.
    
    Args:
        master: Master key material
        context: Context/info string for domain separation
        
    Returns:
        32-byte derived subkey
    """
    hkdf = HKDF(
        algorithm=hashes.SHA256(),
        length=KEY_SIZE,
        salt=None,
        info=context,
        backend=default_backend()
    )
    return hkdf.derive(master)


# =============================================================================
# ECC Key Manager
# =============================================================================

class ECCKeyManager:
    """
    Manages Ed25519 signing keys and X25519 key exchange keys for a user.
    
    Architecture:
        - Ed25519: Used for challenge-response authentication (digital signatures)
        - X25519: Used for ECDH key agreement to derive vault encryption keys
    
    Both keys can be generated from a common seed for convenience, or
    independently for maximum entropy.
    
    Example:
        >>> keys = ECCKeyManager()  # Generate random keys
        >>> challenge = Challenge.generate()
        >>> sig = keys.sign_challenge(challenge)
        >>> vault_key = keys.derive_vault_key(vault_public_key)
    """
    
    def __init__(self, seed: Optional[bytes] = None):
        """
        Initialize key manager.
        
        Args:
            seed: Optional 32-byte seed for deterministic generation.
                  If None, generates cryptographically random keys.
        """
        if seed is not None:
            if len(seed) != KEY_SIZE:
                raise ValueError(f"Seed must be {KEY_SIZE} bytes")
            self._init_from_seed(seed)
        else:
            self._init_random()
    
    def _init_random(self) -> None:
        """Initialize with cryptographically random keys."""
        self._signing_key = Ed25519PrivateKey.generate()
        self._exchange_key = X25519PrivateKey.generate()
    
    def _init_from_seed(self, seed: bytes) -> None:
        """Initialize keys deterministically from seed using HKDF."""
        signing_material = derive_subkey(seed, b"passfx-ed25519-signing-v1")
        exchange_material = derive_subkey(seed, b"passfx-x25519-exchange-v1")
        
        self._signing_key = Ed25519PrivateKey.from_private_bytes(signing_material)
        self._exchange_key = X25519PrivateKey.from_private_bytes(exchange_material)
    
    @property
    def public_signing_key(self) -> Ed25519PublicKey:
        """Get Ed25519 public key for signature verification."""
        return self._signing_key.public_key()
    
    @property
    def public_exchange_key(self) -> X25519PublicKey:
        """Get X25519 public key for ECDH key agreement."""
        return self._exchange_key.public_key()
    
    def sign_challenge(self, challenge: Challenge) -> bytes:
        """
        Sign an authentication challenge.
        
        Args:
            challenge: The challenge to sign
            
        Returns:
            64-byte Ed25519 signature
            
        Raises:
            ChallengeExpiredError: If the challenge has expired
        """
        if challenge.is_expired():
            raise ChallengeExpiredError("Cannot sign an expired challenge")
        return self._signing_key.sign(challenge.to_bytes())
    
    def export_public_keys(self) -> Dict[str, str]:
        """
        Export public keys as hex strings for storage.
        
        Returns:
            Dictionary with 'signing_key' and 'exchange_key' as hex strings
        """
        return {
            'signing_key': self.public_signing_key.public_bytes(
                encoding=serialization.Encoding.Raw,
                format=serialization.PublicFormat.Raw
            ).hex(),
            'exchange_key': self.public_exchange_key.public_bytes(
                encoding=serialization.Encoding.Raw,
                format=serialization.PublicFormat.Raw
            ).hex()
        }
    
    def derive_vault_key(self, vault_public_key: X25519PublicKey) -> bytes:
        """
        Derive vault encryption key via ECDH.
        
        Performs Elliptic Curve Diffie-Hellman key agreement between
        the user's private exchange key and the vault's public key.
        
        Args:
            vault_public_key: The vault's X25519 public key
            
        Returns:
            32-byte vault encryption key
        """
        shared_secret = self._exchange_key.exchange(vault_public_key)
        return derive_subkey(shared_secret, b"passfx-vault-encryption-key-v1")
    
    def export_encrypted_keys(self, password: bytes) -> bytes:
        """
        Export private keys encrypted with a password.
        
        Format: salt (16) || nonce (12) || ciphertext (64 + 16 tag)
        
        Args:
            password: Password to encrypt the keys
            
        Returns:
            Encrypted blob containing both private keys
        """
        # Extract raw private key bytes
        signing_bytes = self._signing_key.private_bytes(
            encoding=serialization.Encoding.Raw,
            format=serialization.PrivateFormat.Raw,
            encryption_algorithm=serialization.NoEncryption()
        )
        exchange_bytes = self._exchange_key.private_bytes(
            encoding=serialization.Encoding.Raw,
            format=serialization.PrivateFormat.Raw,
            encryption_algorithm=serialization.NoEncryption()
        )
        
        # Combine keys (32 + 32 = 64 bytes)
        combined = signing_bytes + exchange_bytes
        
        # Derive encryption key from password
        salt = secrets.token_bytes(SALT_SIZE)
        encryption_key = derive_key_argon2id(password, salt)
        
        # Encrypt with ChaCha20-Poly1305
        cipher = ChaCha20Poly1305(encryption_key)
        nonce = secrets.token_bytes(NONCE_SIZE)
        ciphertext = cipher.encrypt(nonce, combined, b"passfx-ecc-keys-v1")
        
        return salt + nonce + ciphertext
    
    @classmethod
    def from_encrypted_keys(cls, blob: bytes, password: bytes) -> 'ECCKeyManager':
        """
        Restore key manager from encrypted private keys.
        
        Args:
            blob: Output from export_encrypted_keys()
            password: Password used for encryption
            
        Returns:
            ECCKeyManager instance with restored keys
            
        Raises:
            KeyDerivationError: If decryption fails
        """
        if len(blob) < SALT_SIZE + NONCE_SIZE + 64 + 16:
            raise KeyDerivationError("Invalid encrypted blob size")
        
        # Parse blob
        salt = blob[:SALT_SIZE]
        nonce = blob[SALT_SIZE:SALT_SIZE + NONCE_SIZE]
        ciphertext = blob[SALT_SIZE + NONCE_SIZE:]
        
        # Derive decryption key
        decryption_key = derive_key_argon2id(password, salt)
        
        # Decrypt
        try:
            cipher = ChaCha20Poly1305(decryption_key)
            combined = cipher.decrypt(nonce, ciphertext, b"passfx-ecc-keys-v1")
        except Exception as e:
            raise KeyDerivationError(f"Decryption failed: {e}")
        
        if len(combined) != 64:
            raise KeyDerivationError(f"Invalid decrypted size: {len(combined)}")
        
        # Create instance with restored keys
        instance = cls.__new__(cls)
        instance._signing_key = Ed25519PrivateKey.from_private_bytes(combined[:32])
        instance._exchange_key = X25519PrivateKey.from_private_bytes(combined[32:])
        
        return instance


# =============================================================================
# ECC Authenticator (Verifier Side)
# =============================================================================

class ECCAuthenticator:
    """
    Server-side authentication verifier.
    
    Stores the user's public keys and verifies challenge-response signatures.
    This component would run on the PassFX side to verify user identity.
    
    Example:
        >>> auth = ECCAuthenticator(signing_pub, exchange_pub)
        >>> challenge = auth.generate_challenge()
        >>> # User signs challenge...
        >>> if auth.verify_response(signature, timestamp):
        ...     # Authentication successful
    """
    
    def __init__(self, public_signing_key: bytes, public_exchange_key: bytes):
        """
        Initialize with user's public keys.
        
        Args:
            public_signing_key: 32-byte Ed25519 public key
            public_exchange_key: 32-byte X25519 public key
        """
        if len(public_signing_key) != KEY_SIZE:
            raise ValueError(f"Signing key must be {KEY_SIZE} bytes")
        if len(public_exchange_key) != KEY_SIZE:
            raise ValueError(f"Exchange key must be {KEY_SIZE} bytes")
        
        self._signing_key = Ed25519PublicKey.from_public_bytes(public_signing_key)
        self._exchange_key = X25519PublicKey.from_public_bytes(public_exchange_key)
        self._pending_challenge: Optional[Challenge] = None
    
    def generate_challenge(self, validity: int = CHALLENGE_VALIDITY) -> Challenge:
        """
        Generate a new authentication challenge.
        
        Args:
            validity: Challenge validity period in seconds
            
        Returns:
            Challenge object to send to user
        """
        self._pending_challenge = Challenge.generate(validity)
        return self._pending_challenge
    
    def verify_response(self, signature: bytes, timestamp: int) -> bool:
        """
        Verify a signed challenge response.
        
        Args:
            signature: 64-byte Ed25519 signature
            timestamp: Timestamp from the signed message
            
        Returns:
            True if verification succeeds
            
        Raises:
            NoPendingChallengeError: No challenge was generated
            ChallengeExpiredError: Challenge has expired
            InvalidSignatureError: Signature is invalid
        """
        if self._pending_challenge is None:
            raise NoPendingChallengeError("No pending challenge to verify")
        
        if self._pending_challenge.is_expired():
            self._pending_challenge = None
            raise ChallengeExpiredError("Challenge has expired")
        
        # Reconstruct signed message
        message = self._pending_challenge.nonce + struct.pack('>Q', timestamp)
        
        try:
            self._signing_key.verify(signature, message)
            self._pending_challenge = None  # Consume challenge (single-use)
            return True
        except InvalidSignature:
            raise InvalidSignatureError("Signature verification failed")
    
    @property
    def exchange_public_key(self) -> X25519PublicKey:
        """Get user's X25519 public key for vault key derivation."""
        return self._exchange_key


# =============================================================================
# Vault Key Derivation
# =============================================================================

class VaultKeyDerivation:
    """
    Vault-side ECDH key management.
    
    Each vault has its own X25519 keypair. The vault encryption key is
    derived via ECDH between the vault's private key and the user's public key.
    
    This enables:
        - Unique encryption key per vault
        - Multi-user access by storing multiple user public keys
        - Key derivation that doesn't depend on password strength
    """
    
    def __init__(self, private_key_bytes: Optional[bytes] = None):
        """
        Initialize vault key derivation.
        
        Args:
            private_key_bytes: Existing 32-byte private key, or None to generate
        """
        if private_key_bytes is None:
            self._private_key = X25519PrivateKey.generate()
        else:
            if len(private_key_bytes) != KEY_SIZE:
                raise ValueError(f"Private key must be {KEY_SIZE} bytes")
            self._private_key = X25519PrivateKey.from_private_bytes(private_key_bytes)
    
    @property
    def public_key(self) -> X25519PublicKey:
        """Get the vault's X25519 public key."""
        return self._private_key.public_key()
    
    @property
    def public_key_bytes(self) -> bytes:
        """Get the vault's public key as raw bytes."""
        return self.public_key.public_bytes(
            encoding=serialization.Encoding.Raw,
            format=serialization.PublicFormat.Raw
        )
    
    @property
    def private_key_bytes(self) -> bytes:
        """Get the vault's private key as raw bytes (handle securely!)."""
        return self._private_key.private_bytes(
            encoding=serialization.Encoding.Raw,
            format=serialization.PrivateFormat.Raw,
            encryption_algorithm=serialization.NoEncryption()
        )
    
    def derive_vault_key(self, user_public_key: X25519PublicKey) -> bytes:
        """
        Derive vault encryption key via ECDH with user's public key.
        
        Args:
            user_public_key: User's X25519 public key
            
        Returns:
            32-byte vault encryption key
        """
        shared_secret = self._private_key.exchange(user_public_key)
        return derive_subkey(shared_secret, b"passfx-vault-encryption-key-v1")


# =============================================================================
# Hybrid Authenticator (Password + ECC)
# =============================================================================

class HybridAuthenticator:
    """
    Hybrid authentication combining password and ECC.
    
    Supports three authentication modes:
        - "password": Password-only (backwards compatible)
        - "ecc": ECC-only (hardware token users)
        - "both": Both required (2FA for maximum security)
        - "any": Either factor accepted (flexible recovery)
    
    The vault key is derived from a combination of factors, ensuring
    that compromise of one factor alone doesn't expose the vault.
    """
    
    def __init__(self, salt: Optional[bytes] = None):
        """
        Initialize hybrid authenticator.
        
        Args:
            salt: 32-byte salt for password KDF. Generated if not provided.
        """
        if salt is None:
            self._salt = secrets.token_bytes(KEY_SIZE)
        else:
            if len(salt) != KEY_SIZE:
                raise ValueError(f"Salt must be {KEY_SIZE} bytes")
            self._salt = salt
    
    @property
    def salt(self) -> bytes:
        """Get the salt (for storage with vault)."""
        return self._salt
    
    def _derive_password_key(self, password: bytes) -> bytes:
        """Derive key from password using Argon2id."""
        return derive_key_argon2id(password, self._salt)
    
    def derive_vault_key(
        self,
        password: Optional[bytes] = None,
        ecc_key: Optional[bytes] = None,
        mode: str = "both"
    ) -> bytes:
        """
        Derive vault key from authentication factors.
        
        Args:
            password: User's master password
            ecc_key: Key derived from ECC authentication
            mode: Authentication mode:
                  - "password": Password only
                  - "ecc": ECC only
                  - "both": Both required (2FA)
                  - "any": Either accepted
                  
        Returns:
            32-byte vault encryption key
            
        Raises:
            ValueError: If required factors not provided
        """
        key_material = b""
        
        if mode == "password":
            if password is None:
                raise ValueError("Password required for password mode")
            key_material = self._derive_password_key(password)
            
        elif mode == "ecc":
            if ecc_key is None:
                raise ValueError("ECC key required for ecc mode")
            key_material = ecc_key
            
        elif mode == "both":
            if password is None:
                raise ValueError("Password required for both mode")
            if ecc_key is None:
                raise ValueError("ECC key required for both mode")
            # Concatenate both factors
            key_material = self._derive_password_key(password) + ecc_key
            
        elif mode == "any":
            if password is not None:
                key_material += self._derive_password_key(password)
            if ecc_key is not None:
                key_material += ecc_key
            if not key_material:
                raise ValueError("At least one authentication factor required")
        else:
            raise ValueError(f"Unknown mode: {mode}")
        
        # Final key derivation with domain separation
        return derive_subkey(key_material, b"passfx-hybrid-vault-key-v1")


# =============================================================================
# Test Suite
# =============================================================================

class TestChallenge(unittest.TestCase):
    """Tests for the Challenge class."""
    
    def test_challenge_generation(self):
        """Test that challenges are generated with correct properties."""
        challenge = Challenge.generate()
        self.assertEqual(len(challenge.nonce), 32)
        self.assertIsInstance(challenge.timestamp, int)
        self.assertFalse(challenge.is_expired())
    
    def test_challenge_uniqueness(self):
        """Test that consecutive challenges are unique."""
        c1 = Challenge.generate()
        c2 = Challenge.generate()
        self.assertNotEqual(c1.nonce, c2.nonce)
    
    def test_challenge_serialization(self):
        """Test challenge to_bytes produces correct format."""
        challenge = Challenge.generate()
        data = challenge.to_bytes()
        self.assertEqual(len(data), 32 + 8)  # nonce + timestamp
        
        # Verify timestamp is big-endian
        parsed_ts = struct.unpack('>Q', data[32:])[0]
        self.assertEqual(parsed_ts, challenge.timestamp)
    
    def test_challenge_expiry(self):
        """Test that expired challenges are detected."""
        challenge = Challenge(
            nonce=secrets.token_bytes(32),
            timestamp=int(time.time()) - 120,  # 2 minutes ago
            validity_seconds=60
        )
        self.assertTrue(challenge.is_expired())
    
    def test_challenge_dict_roundtrip(self):
        """Test serialization to/from dictionary."""
        original = Challenge.generate()
        restored = Challenge.from_dict(original.to_dict())
        
        self.assertEqual(original.nonce, restored.nonce)
        self.assertEqual(original.timestamp, restored.timestamp)
        self.assertEqual(original.validity_seconds, restored.validity_seconds)


class TestECCKeyManager(unittest.TestCase):
    """Tests for the ECCKeyManager class."""
    
    def test_random_key_generation(self):
        """Test that keys are generated successfully."""
        keys = ECCKeyManager()
        self.assertIsNotNone(keys.public_signing_key)
        self.assertIsNotNone(keys.public_exchange_key)
    
    def test_deterministic_generation(self):
        """Test that same seed produces same keys."""
        seed = secrets.token_bytes(32)
        keys1 = ECCKeyManager(seed=seed)
        keys2 = ECCKeyManager(seed=seed)
        
        self.assertEqual(
            keys1.export_public_keys(),
            keys2.export_public_keys()
        )
    
    def test_different_seeds_different_keys(self):
        """Test that different seeds produce different keys."""
        keys1 = ECCKeyManager(seed=secrets.token_bytes(32))
        keys2 = ECCKeyManager(seed=secrets.token_bytes(32))
        
        self.assertNotEqual(
            keys1.export_public_keys()['signing_key'],
            keys2.export_public_keys()['signing_key']
        )
    
    def test_challenge_signing(self):
        """Test challenge signing produces valid signature."""
        keys = ECCKeyManager()
        challenge = Challenge.generate()
        
        signature = keys.sign_challenge(challenge)
        
        self.assertEqual(len(signature), 64)  # Ed25519 signature size
    
    def test_expired_challenge_rejected(self):
        """Test that expired challenges cannot be signed."""
        keys = ECCKeyManager()
        expired = Challenge(
            nonce=secrets.token_bytes(32),
            timestamp=int(time.time()) - 120,
            validity_seconds=60
        )
        
        with self.assertRaises(ChallengeExpiredError):
            keys.sign_challenge(expired)
    
    def test_key_export_roundtrip(self):
        """Test encrypted export and restoration."""
        original = ECCKeyManager()
        password = b"test-password-123"
        
        # Export
        encrypted = original.export_encrypted_keys(password)
        
        # Restore
        restored = ECCKeyManager.from_encrypted_keys(encrypted, password)
        
        # Verify keys match
        self.assertEqual(
            original.export_public_keys(),
            restored.export_public_keys()
        )
    
    def test_wrong_password_fails(self):
        """Test that wrong password fails decryption."""
        keys = ECCKeyManager()
        encrypted = keys.export_encrypted_keys(b"correct-password")
        
        with self.assertRaises(KeyDerivationError):
            ECCKeyManager.from_encrypted_keys(encrypted, b"wrong-password")
    
    def test_ecdh_key_agreement(self):
        """Test ECDH produces matching keys on both sides."""
        user_keys = ECCKeyManager()
        vault_keys = VaultKeyDerivation()
        
        # User derives key with vault's public key
        user_derived = user_keys.derive_vault_key(vault_keys.public_key)
        
        # Vault derives key with user's public key
        vault_derived = vault_keys.derive_vault_key(user_keys.public_exchange_key)
        
        # Keys must match (ECDH property)
        self.assertEqual(user_derived, vault_derived)


class TestECCAuthenticator(unittest.TestCase):
    """Tests for the ECCAuthenticator class."""
    
    def setUp(self):
        """Set up test fixtures."""
        self.user_keys = ECCKeyManager()
        public = self.user_keys.export_public_keys()
        self.authenticator = ECCAuthenticator(
            public_signing_key=bytes.fromhex(public['signing_key']),
            public_exchange_key=bytes.fromhex(public['exchange_key'])
        )
    
    def test_challenge_generation(self):
        """Test authenticator generates valid challenges."""
        challenge = self.authenticator.generate_challenge()
        self.assertIsNotNone(challenge)
        self.assertFalse(challenge.is_expired())
    
    def test_valid_authentication(self):
        """Test successful authentication flow."""
        challenge = self.authenticator.generate_challenge()
        signature = self.user_keys.sign_challenge(challenge)
        
        result = self.authenticator.verify_response(signature, challenge.timestamp)
        
        self.assertTrue(result)
    
    def test_invalid_signature_rejected(self):
        """Test that invalid signatures are rejected."""
        challenge = self.authenticator.generate_challenge()
        
        # Create signature with wrong keys
        wrong_keys = ECCKeyManager()
        bad_signature = wrong_keys.sign_challenge(challenge)
        
        with self.assertRaises(InvalidSignatureError):
            self.authenticator.verify_response(bad_signature, challenge.timestamp)
    
    def test_no_pending_challenge_error(self):
        """Test verification without challenge raises error."""
        with self.assertRaises(NoPendingChallengeError):
            self.authenticator.verify_response(b"x" * 64, int(time.time()))
    
    def test_challenge_consumed_after_verification(self):
        """Test that challenge is consumed after successful verification."""
        challenge = self.authenticator.generate_challenge()
        signature = self.user_keys.sign_challenge(challenge)
        
        # First verification succeeds
        self.authenticator.verify_response(signature, challenge.timestamp)
        
        # Second verification fails (challenge consumed)
        with self.assertRaises(NoPendingChallengeError):
            self.authenticator.verify_response(signature, challenge.timestamp)
    
    def test_tampered_timestamp_rejected(self):
        """Test that modified timestamps are rejected."""
        challenge = self.authenticator.generate_challenge()
        signature = self.user_keys.sign_challenge(challenge)
        
        # Try with different timestamp
        with self.assertRaises(InvalidSignatureError):
            self.authenticator.verify_response(signature, challenge.timestamp + 1)


class TestHybridAuthenticator(unittest.TestCase):
    """Tests for the HybridAuthenticator class."""
    
    def setUp(self):
        """Set up test fixtures."""
        self.hybrid = HybridAuthenticator()
        self.password = b"test-password-123"
        self.ecc_key = secrets.token_bytes(32)
    
    def test_password_only_mode(self):
        """Test password-only authentication."""
        key = self.hybrid.derive_vault_key(
            password=self.password,
            mode="password"
        )
        self.assertEqual(len(key), 32)
    
    def test_ecc_only_mode(self):
        """Test ECC-only authentication."""
        key = self.hybrid.derive_vault_key(
            ecc_key=self.ecc_key,
            mode="ecc"
        )
        self.assertEqual(len(key), 32)
    
    def test_both_mode(self):
        """Test both factors required."""
        key = self.hybrid.derive_vault_key(
            password=self.password,
            ecc_key=self.ecc_key,
            mode="both"
        )
        self.assertEqual(len(key), 32)
    
    def test_any_mode_password(self):
        """Test any mode with password only."""
        key = self.hybrid.derive_vault_key(
            password=self.password,
            mode="any"
        )
        self.assertEqual(len(key), 32)
    
    def test_any_mode_ecc(self):
        """Test any mode with ECC only."""
        key = self.hybrid.derive_vault_key(
            ecc_key=self.ecc_key,
            mode="any"
        )
        self.assertEqual(len(key), 32)
    
    def test_different_factors_different_keys(self):
        """Test that different factors produce different keys."""
        pwd_key = self.hybrid.derive_vault_key(password=self.password, mode="password")
        ecc_key = self.hybrid.derive_vault_key(ecc_key=self.ecc_key, mode="ecc")
        both_key = self.hybrid.derive_vault_key(
            password=self.password, ecc_key=self.ecc_key, mode="both"
        )
        
        # All keys should be different
        self.assertNotEqual(pwd_key, ecc_key)
        self.assertNotEqual(pwd_key, both_key)
        self.assertNotEqual(ecc_key, both_key)
    
    def test_missing_password_in_password_mode(self):
        """Test error when password missing in password mode."""
        with self.assertRaises(ValueError):
            self.hybrid.derive_vault_key(mode="password")
    
    def test_missing_ecc_in_ecc_mode(self):
        """Test error when ECC key missing in ECC mode."""
        with self.assertRaises(ValueError):
            self.hybrid.derive_vault_key(mode="ecc")
    
    def test_missing_factors_in_both_mode(self):
        """Test error when factors missing in both mode."""
        with self.assertRaises(ValueError):
            self.hybrid.derive_vault_key(password=self.password, mode="both")
        
        with self.assertRaises(ValueError):
            self.hybrid.derive_vault_key(ecc_key=self.ecc_key, mode="both")
    
    def test_deterministic_derivation(self):
        """Test that same inputs produce same outputs."""
        key1 = self.hybrid.derive_vault_key(
            password=self.password, ecc_key=self.ecc_key, mode="both"
        )
        key2 = self.hybrid.derive_vault_key(
            password=self.password, ecc_key=self.ecc_key, mode="both"
        )
        self.assertEqual(key1, key2)


class TestVaultKeyDerivation(unittest.TestCase):
    """Tests for the VaultKeyDerivation class."""
    
    def test_key_generation(self):
        """Test vault keypair generation."""
        vault = VaultKeyDerivation()
        self.assertEqual(len(vault.public_key_bytes), 32)
        self.assertEqual(len(vault.private_key_bytes), 32)
    
    def test_key_restoration(self):
        """Test vault key restoration from bytes."""
        original = VaultKeyDerivation()
        restored = VaultKeyDerivation(original.private_key_bytes)
        
        self.assertEqual(original.public_key_bytes, restored.public_key_bytes)
    
    def test_ecdh_symmetry(self):
        """Test ECDH produces same key on both ends."""
        vault = VaultKeyDerivation()
        user = ECCKeyManager()
        
        # Both sides derive the same key
        vault_side = vault.derive_vault_key(user.public_exchange_key)
        user_side = user.derive_vault_key(vault.public_key)
        
        self.assertEqual(vault_side, user_side)


# =============================================================================
# Integration Test / Demo
# =============================================================================

def run_integration_demo():
    """Run a complete integration demonstration."""
    
    print("=" * 70)
    print("ECC Authentication - Full Integration Demo")
    print("=" * 70)
    
    # === PHASE 1: SETUP ===
    print("\n" + "─" * 70)
    print("PHASE 1: Initial Setup")
    print("─" * 70)
    
    # User generates keypair (stored on hardware token or encrypted locally)
    print("\n[1.1] User generating ECC keypair...")
    user_keys = ECCKeyManager()
    public_keys = user_keys.export_public_keys()
    print(f"      ├─ Signing key:  {public_keys['signing_key'][:40]}...")
    print(f"      └─ Exchange key: {public_keys['exchange_key'][:40]}...")
    
    # Vault generates its keypair
    print("\n[1.2] Vault generating ECDH keypair...")
    vault_keys = VaultKeyDerivation()
    print(f"      └─ Public key:   {vault_keys.public_key_bytes.hex()[:40]}...")
    
    # Create encrypted backup of user keys
    print("\n[1.3] Creating encrypted backup of user keys...")
    backup_password = b"secure-backup-password"
    encrypted_backup = user_keys.export_encrypted_keys(backup_password)
    print(f"      └─ Backup size:  {len(encrypted_backup)} bytes")
    
    # === PHASE 2: AUTHENTICATION ===
    print("\n" + "─" * 70)
    print("PHASE 2: Challenge-Response Authentication")
    print("─" * 70)
    
    # Create authenticator with stored public keys
    print("\n[2.1] Initializing authenticator with stored public keys...")
    authenticator = ECCAuthenticator(
        public_signing_key=bytes.fromhex(public_keys['signing_key']),
        public_exchange_key=bytes.fromhex(public_keys['exchange_key'])
    )
    
    # Generate challenge
    print("\n[2.2] Generating authentication challenge...")
    challenge = authenticator.generate_challenge()
    print(f"      ├─ Nonce:      {challenge.nonce.hex()[:40]}...")
    print(f"      ├─ Timestamp:  {challenge.timestamp}")
    print(f"      └─ Validity:   {challenge.validity_seconds}s")
    
    # User signs challenge
    print("\n[2.3] User signing challenge with private key...")
    signature = user_keys.sign_challenge(challenge)
    print(f"      └─ Signature:  {signature.hex()[:40]}...")
    
    # Verify signature
    print("\n[2.4] Verifying signature...")
    try:
        is_valid = authenticator.verify_response(signature, challenge.timestamp)
        print(f"      └─ Result:     ✓ AUTHENTICATION SUCCESSFUL")
    except InvalidSignatureError:
        print(f"      └─ Result:     ✗ AUTHENTICATION FAILED")
        return False
    
    # === PHASE 3: KEY DERIVATION ===
    print("\n" + "─" * 70)
    print("PHASE 3: Vault Key Derivation (ECDH)")
    print("─" * 70)
    
    # User derives vault key
    print("\n[3.1] User deriving vault key (ECDH with vault public key)...")
    user_vault_key = user_keys.derive_vault_key(vault_keys.public_key)
    print(f"      └─ Key:        {user_vault_key.hex()[:40]}...")
    
    # Vault derives same key
    print("\n[3.2] Vault deriving same key (ECDH with user public key)...")
    vault_vault_key = vault_keys.derive_vault_key(user_keys.public_exchange_key)
    print(f"      └─ Key:        {vault_vault_key.hex()[:40]}...")
    
    # Verify match
    keys_match = user_vault_key == vault_vault_key
    print(f"\n[3.3] Verifying key agreement...")
    print(f"      └─ Keys match: {'✓ YES' if keys_match else '✗ NO'}")
    
    # === PHASE 4: KEY RECOVERY ===
    print("\n" + "─" * 70)
    print("PHASE 4: Key Recovery from Encrypted Backup")
    print("─" * 70)
    
    print("\n[4.1] Restoring keys from encrypted backup...")
    restored_keys = ECCKeyManager.from_encrypted_keys(encrypted_backup, backup_password)
    restored_public = restored_keys.export_public_keys()
    
    keys_restored = (
        restored_public['signing_key'] == public_keys['signing_key'] and
        restored_public['exchange_key'] == public_keys['exchange_key']
    )
    print(f"      └─ Restored:   {'✓ SUCCESS' if keys_restored else '✗ FAILED'}")
    
    # === PHASE 5: HYBRID AUTHENTICATION ===
    print("\n" + "─" * 70)
    print("PHASE 5: Hybrid Authentication (Password + ECC)")
    print("─" * 70)
    
    hybrid = HybridAuthenticator()
    password = b"my-master-password"
    
    print("\n[5.1] Password-only mode...")
    pwd_key = hybrid.derive_vault_key(password=password, mode="password")
    print(f"      └─ Key:        {pwd_key.hex()[:40]}...")
    
    print("\n[5.2] ECC-only mode...")
    ecc_key = hybrid.derive_vault_key(ecc_key=user_vault_key, mode="ecc")
    print(f"      └─ Key:        {ecc_key.hex()[:40]}...")
    
    print("\n[5.3] 2FA mode (both required)...")
    both_key = hybrid.derive_vault_key(
        password=password, ecc_key=user_vault_key, mode="both"
    )
    print(f"      └─ Key:        {both_key.hex()[:40]}...")
    
    # Verify all keys are different
    all_unique = len({pwd_key, ecc_key, both_key}) == 3
    print(f"\n[5.4] Verifying key uniqueness...")
    print(f"      └─ All unique: {'✓ YES' if all_unique else '✗ NO'}")
    
    # === SUMMARY ===
    print("\n" + "=" * 70)
    print("Demo Complete!")
    print("=" * 70)
    print("""
Security Properties Demonstrated:
  ✓ Challenge-response prevents replay attacks
  ✓ ECDH derives vault key without password brute-force risk
  ✓ Encrypted backup allows software-only operation
  ✓ Hybrid mode enables 2FA for maximum security
  ✓ Different authentication modes produce different keys
    """)
    
    return True


# =============================================================================
# Main Entry Point
# =============================================================================

def main():
    """Main entry point."""
    import argparse
    
    parser = argparse.ArgumentParser(
        description="ECC Authentication Test Suite and Demo"
    )
    parser.add_argument(
        '--test', '-t',
        action='store_true',
        help='Run unit tests'
    )
    parser.add_argument(
        '--demo', '-d',
        action='store_true',
        help='Run integration demo'
    )
    parser.add_argument(
        '--verbose', '-v',
        action='store_true',
        help='Verbose output for tests'
    )
    
    args = parser.parse_args()
    
    # Default to both if no args
    if not args.test and not args.demo:
        args.test = True
        args.demo = True
    
    success = True
    
    if args.test:
        print("\n" + "=" * 70)
        print("Running Unit Tests")
        print("=" * 70 + "\n")
        
        verbosity = 2 if args.verbose else 1
        loader = unittest.TestLoader()
        suite = unittest.TestSuite()
        
        # Add all test classes
        suite.addTests(loader.loadTestsFromTestCase(TestChallenge))
        suite.addTests(loader.loadTestsFromTestCase(TestECCKeyManager))
        suite.addTests(loader.loadTestsFromTestCase(TestECCAuthenticator))
        suite.addTests(loader.loadTestsFromTestCase(TestHybridAuthenticator))
        suite.addTests(loader.loadTestsFromTestCase(TestVaultKeyDerivation))
        
        runner = unittest.TextTestRunner(verbosity=verbosity)
        result = runner.run(suite)
        
        success = result.wasSuccessful()
        
        print(f"\n{'✓' if success else '✗'} Tests: {result.testsRun} run, "
              f"{len(result.failures)} failures, {len(result.errors)} errors")
    
    if args.demo:
        print()
        success = run_integration_demo() and success
    
    return 0 if success else 1


if __name__ == "__main__":
    sys.exit(main())

Usage:

python ecc_demo.py -d # demo
python ecc_demo.py -t # test, optionally add -v for verbose output.

• Environment confusion or a poisoned PATH env could lead to further damages, such as xclip being replaced by a malicious xclip binary that sends the copied contents back to a remote server after poisoning your PATH/xclip binary.
• Password managers should be secure even if your physical machine is compromised. For best practice, use a hybrid approach such as above as it not only guarantees 256-bit security across the board but also requires a password as is. Thus combining something you know, with some that you have. This could easily be expanded to using FIDO2/Ubikeys and other Hardware secret storage mechanisms.

Lastly, disable any terminal history, assume that a User WILL inevitably at some point make a mistake, such as pasting a password into the terminal without invoking passfx

• Set HISTCONTROL=ignorespace and prefix sensitive commands with space
• Consider terminal input capture for the app

Why ECC over a master password?

Aspect	Master Password	ECC Challenge-Response
Entropy	User-dependent (often weak)	256-bit guaranteed
Phishing Risk	High (can be intercepted)	None (proves possession)
Offline Brute Force	Possible with vault file	Impossible
Hardware Token Support	No	Yes (YubiKey, Ledger)
Key Derivation Cost	High (must be slow)	None needed depending on approach

Resources

https://github.com/samuel-lucas6/Cryptography-Guidelines/blob/main/README.md
https://www.usenix.org/system/files/usenixsecurity23-nair-mfkdf.pdf
https://fdzdev.medium.com/guide-to-identifying-and-exploiting-toctou-race-conditions-in-web-applications-c5f233e32b7f
https://doc.libsodium.org/memory_management