duckmail 0.1.0__tar.gz

duckmail-0.1.0/LICENSE

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

duckmail-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: duckmail
+Version: 0.1.0
+Summary: Lightweight CLI for DuckDuckGo Email Protection
+Author: DuckMail Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/duckmail
+Project-URL: Documentation, https://github.com/yourusername/duckmail/blob/main/README.md
+Project-URL: Repository, https://github.com/yourusername/duckmail
+Project-URL: Issues, https://github.com/yourusername/duckmail/issues
+Keywords: duckduckgo,email,cli,privacy,email-protection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyperclip>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.0.270; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# DuckMail CLI
+
+Lightweight CLI for DuckDuckGo Email Protection - Manage your duck email addresses from the terminal.
+
+**[English](README.md)** | [Tiếng Việt](README.vi.md)
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install -r requirements.txt
+pip install -e .
+
+# First time setup: Sign up via browser
+# Visit https://duckduckgo.com/email/ to create account
+
+# Login with your credentials
+duckmail auth login
+
+# Generate address and copy to clipboard
+duckmail g -c
+```
+
+> **Note:** Account signup must be done via browser at https://duckduckgo.com/email/ due to DuckDuckGo's bot protection. After signing up, use the CLI to login and manage your addresses.
+
+## Features
+
+- 🔐 **Secure Authentication** - OTP-based login
+- 📧 **Generate Addresses** - Create duck email addresses
+- 📋 **Copy to Clipboard** - Auto-copy with `-c` flag
+- ⚡ **Fast & Lightweight** - Quick commands with aliases
+- 💾 **Secure Storage** - System keyring integration
+- 🎨 **Beautiful Output** - Rich terminal UI
+
+## Command Aliases
+
+- `duckmail auth` → `duckmail a`
+- `duckmail generate` → `duckmail g` or `duckmail gen`
+- `duckmail info` → `duckmail i`
+
+## Common Commands
+
+```bash
+# Authentication
+duckmail auth login            # Login with username
+duckmail auth logout           # Logout
+duckmail auth status           # Check authentication status
+
+# Generate
+duckmail g                     # Generate 1 address
+duckmail g -c                  # Generate & copy
+duckmail g -n 5                # Generate 5 addresses
+
+# Info
+duckmail i                     # Account info
+duckmail version               # Version
+```
+
+## Documentation
+
+📖 **[Complete Documentation](DOCS.md)** - Full guide with:
+- Installation instructions
+- Usage examples
+- API documentation
+- Troubleshooting
+- Command reference
+
+## Project Structure
+
+```
+duckmail/
+├── duckmail/              # Main package
+│   ├── api/              # API clients
+│   ├── config/           # Configuration
+│   ├── utils/            # Utilities
+│   └── cli.py            # CLI interface
+├── DOCS.md               # Complete documentation
+├── PLAN.md               # Project plan
+├── README.md             # This file
+└── requirements.txt      # Dependencies
+```
+
+## Development
+
+```bash
+# Setup
+python -m venv venv
+.\venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+pip install -e .
+
+# Run
+duckmail --help
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file
+
+## Disclaimer
+
+Unofficial tool, not affiliated with DuckDuckGo. Use at your own risk.
+
+---
+
+**Made with ❤️ for the DuckDuckGo community** 🦆

duckmail-0.1.0/README.md

@@ -0,0 +1,108 @@
+# DuckMail CLI
+
+Lightweight CLI for DuckDuckGo Email Protection - Manage your duck email addresses from the terminal.
+
+**[English](README.md)** | [Tiếng Việt](README.vi.md)
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install -r requirements.txt
+pip install -e .
+
+# First time setup: Sign up via browser
+# Visit https://duckduckgo.com/email/ to create account
+
+# Login with your credentials
+duckmail auth login
+
+# Generate address and copy to clipboard
+duckmail g -c
+```
+
+> **Note:** Account signup must be done via browser at https://duckduckgo.com/email/ due to DuckDuckGo's bot protection. After signing up, use the CLI to login and manage your addresses.
+
+## Features
+
+- 🔐 **Secure Authentication** - OTP-based login
+- 📧 **Generate Addresses** - Create duck email addresses
+- 📋 **Copy to Clipboard** - Auto-copy with `-c` flag
+- ⚡ **Fast & Lightweight** - Quick commands with aliases
+- 💾 **Secure Storage** - System keyring integration
+- 🎨 **Beautiful Output** - Rich terminal UI
+
+## Command Aliases
+
+- `duckmail auth` → `duckmail a`
+- `duckmail generate` → `duckmail g` or `duckmail gen`
+- `duckmail info` → `duckmail i`
+
+## Common Commands
+
+```bash
+# Authentication
+duckmail auth login            # Login with username
+duckmail auth logout           # Logout
+duckmail auth status           # Check authentication status
+
+# Generate
+duckmail g                     # Generate 1 address
+duckmail g -c                  # Generate & copy
+duckmail g -n 5                # Generate 5 addresses
+
+# Info
+duckmail i                     # Account info
+duckmail version               # Version
+```
+
+## Documentation
+
+📖 **[Complete Documentation](DOCS.md)** - Full guide with:
+- Installation instructions
+- Usage examples
+- API documentation
+- Troubleshooting
+- Command reference
+
+## Project Structure
+
+```
+duckmail/
+├── duckmail/              # Main package
+│   ├── api/              # API clients
+│   ├── config/           # Configuration
+│   ├── utils/            # Utilities
+│   └── cli.py            # CLI interface
+├── DOCS.md               # Complete documentation
+├── PLAN.md               # Project plan
+├── README.md             # This file
+└── requirements.txt      # Dependencies
+```
+
+## Development
+
+```bash
+# Setup
+python -m venv venv
+.\venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+pip install -e .
+
+# Run
+duckmail --help
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file
+
+## Disclaimer
+
+Unofficial tool, not affiliated with DuckDuckGo. Use at your own risk.
+
+---
+
+**Made with ❤️ for the DuckDuckGo community** 🦆

duckmail-0.1.0/duckmail/__main__.py

@@ -0,0 +1,8 @@
+"""Main entry point for DuckMail CLI."""
+
+from duckmail.cli import app
+
+if __name__ == "__main__":
+    app()
+
+# Made with Bob

duckmail-0.1.0/duckmail/api/addresses.py

@@ -0,0 +1,52 @@
+"""Address management API for DuckDuckGo Email Protection."""
+
+from typing import Optional
+from duckmail.api.client import APIClient
+
+
+class AddressAPI:
+    """Address management API wrapper."""
+    
+    def __init__(self, client: Optional[APIClient] = None):
+        """Initialize address API.
+        
+        Args:
+            client: Optional API client instance
+        """
+        self.client = client or APIClient()
+    
+    def generate(self) -> str:
+        """Generate a new random duck email address.
+        
+        Returns:
+            The generated address alias (without @duck.com)
+            
+        Raises:
+            Exception: If generation fails
+        """
+        try:
+            response = self.client.post(
+                "/email/addresses",
+                use_access_token=True,
+                headers={"content-length": "0"}
+            )
+            
+            address = response.get("address", "")
+            return address
+        except Exception as e:
+            raise Exception(f"Failed to generate address: {str(e)}")
+    
+    def get_full_address(self, alias: str) -> str:
+        """Get full email address from alias.
+        
+        Args:
+            alias: Address alias
+            
+        Returns:
+            Full email address (alias@duck.com)
+        """
+        if "@" in alias:
+            return alias
+        return f"{alias}@duck.com"
+
+# Made with Bob

duckmail-0.1.0/duckmail/api/auth.py

@@ -0,0 +1,314 @@
+"""Authentication API for DuckDuckGo Email Protection."""
+
+from typing import Optional, Dict, Any
+from duckmail.api.client import APIClient
+from duckmail.utils.storage import CredentialStorage
+from duckmail.config.settings import settings
+
+
+class AuthAPI:
+    """Authentication API wrapper."""
+    
+    def __init__(self, client: Optional[APIClient] = None):
+        """Initialize authentication API.
+        
+        Args:
+            client: Optional API client instance
+        """
+        self.client = client or APIClient()
+    
+    def request_login(self, username: str) -> bool:
+        """Request login OTP to be sent to user's email.
+        
+        Args:
+            username: DuckDuckGo username
+            
+        Returns:
+            True if request was successful
+            
+        Raises:
+            Exception: If request fails
+        """
+        try:
+            self.client.get(
+                "/auth/loginlink",
+                params={"user": username}
+            )
+            return True
+        except Exception as e:
+            raise Exception(f"Failed to request login: {str(e)}")
+    
+    def confirm_login(self, username: str, otp: str) -> Dict[str, Any]:
+        """Confirm login with OTP and get JWT token.
+        
+        Args:
+            username: DuckDuckGo username
+            otp: OTP passphrase (e.g., "word1+word2+word3+word4")
+            
+        Returns:
+            Dictionary with status, token, and user
+            
+        Raises:
+            Exception: If login fails
+        """
+        try:
+            response = self.client.get(
+                "/auth/login",
+                params={
+                    "user": username,
+                    "otp": otp
+                }
+            )
+            
+            # Save JWT token
+            if response.get("token"):
+                CredentialStorage.save_jwt_token(response["token"])
+                # Save username
+                settings.save_user_data(username)
+            
+            return response
+        except Exception as e:
+            raise Exception(f"Login failed: {str(e)}")
+    
+    def get_dashboard(self) -> Dict[str, Any]:
+        """Get dashboard information including access token.
+        
+        Returns:
+            Dashboard data with user info and access token
+            
+        Raises:
+            Exception: If request fails
+        """
+        try:
+            response = self.client.get(
+                "/email/dashboard",
+                use_jwt=True
+            )
+            
+            # Save access token
+            if response.get("user", {}).get("access_token"):
+                CredentialStorage.save_access_token(response["user"]["access_token"])
+                # Save email if available
+                if response.get("user", {}).get("email"):
+                    user_data = settings.load_user_data()
+                    if user_data:
+                        settings.save_user_data(
+                            user_data.get("username", ""),
+                            response["user"]["email"]
+                        )
+            
+            return response
+        except Exception as e:
+            raise Exception(f"Failed to get dashboard: {str(e)}")
+    
+    def logout(self) -> None:
+        """Logout by clearing all stored credentials."""
+        CredentialStorage.clear_all()
+        settings.clear_user_data()
+    
+    def is_authenticated(self) -> bool:
+        """Check if user is authenticated.
+        
+        Returns:
+            True if JWT token exists
+        """
+        return CredentialStorage.has_jwt_token()
+    
+    def has_access_token(self) -> bool:
+        """Check if access token exists.
+        
+        Returns:
+            True if access token is stored
+        """
+        return CredentialStorage.has_access_token()
+    
+    def verify_token(self) -> bool:
+        """Verify if current JWT token is valid.
+        
+        Returns:
+            True if token is valid
+        """
+        if not self.is_authenticated():
+            return False
+        
+        try:
+            self.get_dashboard()
+            return True
+        except:
+            return False
+    
+    def request_email_change(self, username: str) -> bool:
+        """Request OTP to change forwarding email address.
+        
+        Args:
+            username: DuckDuckGo username
+            
+        Returns:
+            True if request was successful
+            
+        Raises:
+            Exception: If request fails
+        """
+        try:
+            self.client.get(
+                "/auth/confirmlink",
+                params={
+                    "action": "change_email_address",
+                    "user": username
+                }
+            )
+            return True
+        except Exception as e:
+            raise Exception(f"Failed to request email change: {str(e)}")
+    
+    def confirm_email_change_request(self, username: str, otp: str) -> Dict[str, Any]:
+        """Confirm email change request with OTP.
+        
+        Args:
+            username: DuckDuckGo username
+            otp: OTP passphrase
+            
+        Returns:
+            Response with temporary token
+            
+        Raises:
+            Exception: If confirmation fails
+        """
+        try:
+            response = self.client.get(
+                "/auth/confirm",
+                params={
+                    "action": "change_email_address",
+                    "user": username,
+                    "otp": otp
+                }
+            )
+            return response
+        except Exception as e:
+            raise Exception(f"Failed to confirm email change request: {str(e)}")
+    
+    def validate_email(self, email: str) -> bool:
+        """Validate if email address is acceptable.
+        
+        Args:
+            email: Email address to validate
+            
+        Returns:
+            True if email is valid
+            
+        Raises:
+            Exception: If validation fails
+        """
+        try:
+            response = self.client.get(
+                "/auth/validate-email-address",
+                params={"email": email}
+            )
+            return response.get("valid", False)
+        except Exception as e:
+            raise Exception(f"Failed to validate email: {str(e)}")
+    
+    def signup_dryrun(self, username: str, email: str, disable_secure_reply: bool = False) -> Dict[str, Any]:
+        """Validate username availability before signup.
+        
+        Args:
+            username: Desired username
+            email: Email address for forwarding
+            disable_secure_reply: Whether to disable secure reply
+            
+        Returns:
+            Response with status and user
+            
+        Raises:
+            Exception: If validation fails
+        """
+        try:
+            # Prepare form data as application/x-www-form-urlencoded
+            form_data = {
+                "user": username,
+                "email": email,
+                "disable_secure_reply": "1" if disable_secure_reply else "0",
+                "dry_run": "1"
+            }
+            
+            response = self.client.post(
+                "/auth/signup",
+                data=form_data,
+                headers={"content-type": "application/x-www-form-urlencoded"}
+            )
+            
+            return response
+        except Exception as e:
+            # Try to extract error message from response
+            error_msg = str(e)
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_data = e.response.json()
+                    if 'error' in error_data:
+                        error_msg = error_data['error']
+                except:
+                    pass
+            raise Exception(f"Failed to validate username: {error_msg}")
+    
+    def signup(self, username: str, email: str, disable_secure_reply: bool = False) -> Dict[str, Any]:
+        """Create new DuckDuckGo Email Protection account.
+        
+        Args:
+            username: Desired username
+            email: Email address for forwarding
+            disable_secure_reply: Whether to disable secure reply
+            
+        Returns:
+            Response with status and user
+            
+        Raises:
+            Exception: If signup fails
+        """
+        try:
+            # Prepare form data as application/x-www-form-urlencoded
+            form_data = {
+                "user": username,
+                "email": email,
+                "disable_secure_reply": "1" if disable_secure_reply else "0"
+            }
+            
+            response = self.client.post(
+                "/auth/signup",
+                data=form_data,
+                headers={"content-type": "application/x-www-form-urlencoded"}
+            )
+            
+            return response
+        except Exception as e:
+            raise Exception(f"Signup failed: {str(e)}")
+    
+    def verify_signup(self, username: str, otp: str) -> Dict[str, Any]:
+        """Verify email and activate account with OTP.
+        
+        Args:
+            username: Username
+            otp: OTP passphrase from email
+            
+        Returns:
+            Response with JWT token
+            
+        Raises:
+            Exception: If verification fails
+        """
+        try:
+            response = self.client.get(
+                "/auth/verify",
+                params={
+                    "user": username,
+                    "otp": otp
+                }
+            )
+            
+            # Save JWT token
+            if response.get("token"):
+                CredentialStorage.save_jwt_token(response["token"])
+                settings.save_user_data(username)
+            
+            return response
+        except Exception as e:
+            raise Exception(f"Verification failed: {str(e)}")