duckmail 0.1.0__py3-none-any.whl

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/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/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)}")

duckmail/api/client.py

@@ -0,0 +1,194 @@
+"""HTTP client for DuckDuckGo API."""
+
+import httpx
+from typing import Optional, Dict, Any
+from duckmail.config.settings import settings
+from duckmail.utils.storage import CredentialStorage
+
+
+class APIClient:
+    """HTTP client wrapper for DuckDuckGo API."""
+    
+    def __init__(self):
+        """Initialize API client."""
+        self.base_url = settings.api_base_url
+        self.client = httpx.Client(timeout=settings.timeout)
+    
+    def _get_headers(self, use_jwt: bool = False, use_access_token: bool = False) -> Dict[str, str]:
+        """Get request headers.
+        
+        Args:
+            use_jwt: Include JWT token in Authorization header
+            use_access_token: Include access token in Authorization header
+            
+        Returns:
+            Dictionary of headers
+        """
+        headers = {
+            "accept": "*/*",
+            "accept-language": "en-US,en;q=0.9",
+            "origin": "https://duckduckgo.com",
+            "referer": "https://duckduckgo.com/",
+            "sec-ch-ua": '"Chromium";v="147", "Not.A/Brand";v="8"',
+            "sec-ch-ua-mobile": "?0",
+            "sec-ch-ua-platform": '"Windows"',
+            "sec-fetch-dest": "empty",
+            "sec-fetch-mode": "cors",
+            "sec-fetch-site": "same-site",
+            "sec-gpc": "1",
+            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36"
+        }
+        
+        if use_jwt:
+            token = CredentialStorage.get_jwt_token()
+            if token:
+                headers["authorization"] = f"Bearer {token}"
+        
+        if use_access_token:
+            token = CredentialStorage.get_access_token()
+            if token:
+                headers["authorization"] = f"Bearer {token}"
+        
+        return headers
+    
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        use_jwt: bool = False,
+        use_access_token: bool = False,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make HTTP request to API.
+        
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            data: Request body data
+            params: Query parameters
+            use_jwt: Use JWT token for authorization
+            use_access_token: Use access token for authorization
+            **kwargs: Additional arguments for httpx
+            
+        Returns:
+            Response JSON data
+            
+        Raises:
+            httpx.HTTPStatusError: If request fails
+        """
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+        headers = self._get_headers(use_jwt=use_jwt, use_access_token=use_access_token)
+        
+        # Merge custom headers if provided
+        if 'headers' in kwargs:
+            headers.update(kwargs.pop('headers'))
+        
+        # Determine if we should send as form data or JSON
+        request_kwargs = {
+            'method': method,
+            'url': url,
+            'params': params,
+            **kwargs
+        }
+        
+        # If files parameter is provided (multipart/form-data), don't set content-type header
+        # httpx will automatically set it with the correct boundary
+        if 'files' not in request_kwargs:
+            request_kwargs['headers'] = headers
+            if data is not None:
+                content_type = headers.get('content-type', '')
+                if 'application/x-www-form-urlencoded' in content_type:
+                    request_kwargs['data'] = data
+                else:
+                    request_kwargs['json'] = data
+        else:
+            # For multipart/form-data, only include non-content-type headers
+            request_kwargs['headers'] = {k: v for k, v in headers.items() if k.lower() != 'content-type'}
+        
+        response = self.client.request(**request_kwargs)
+        response.raise_for_status()
+        
+        # Some endpoints return empty response
+        if response.text:
+            return response.json()
+        return {}
+    
+    def get(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        use_jwt: bool = False,
+        use_access_token: bool = False
+    ) -> Dict[str, Any]:
+        """Make GET request.
+        
+        Args:
+            endpoint: API endpoint path
+            params: Query parameters
+            use_jwt: Use JWT token for authorization
+            use_access_token: Use access token for authorization
+            
+        Returns:
+            Response JSON data
+        """
+        return self.request("GET", endpoint, params=params, use_jwt=use_jwt, use_access_token=use_access_token)
+    
+    def post(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        use_jwt: bool = False,
+        use_access_token: bool = False,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make POST request.
+        
+        Args:
+            endpoint: API endpoint path
+            data: Request body data
+            files: Files/form data for multipart/form-data
+            use_jwt: Use JWT token for authorization
+            use_access_token: Use access token for authorization
+            **kwargs: Additional arguments
+            
+        Returns:
+            Response JSON data
+        """
+        if files:
+            kwargs['files'] = files
+        return self.request("POST", endpoint, data=data, use_jwt=use_jwt, use_access_token=use_access_token, **kwargs)
+    
+    def delete(
+        self,
+        endpoint: str,
+        use_jwt: bool = False,
+        use_access_token: bool = False
+    ) -> Dict[str, Any]:
+        """Make DELETE request.
+        
+        Args:
+            endpoint: API endpoint path
+            use_jwt: Use JWT token for authorization
+            use_access_token: Use access token for authorization
+            
+        Returns:
+            Response JSON data
+        """
+        return self.request("DELETE", endpoint, use_jwt=use_jwt, use_access_token=use_access_token)
+    
+    def close(self) -> None:
+        """Close HTTP client."""
+        self.client.close()
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, *args):
+        """Context manager exit."""
+        self.close()
+
+# Made with Bob

duckmail/cli.py

@@ -0,0 +1,342 @@
+"""Command-line interface for DuckMail."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.prompt import Prompt, Confirm
+from typing import Optional
+import pyperclip
+
+from duckmail.api.auth import AuthAPI
+from duckmail.api.addresses import AddressAPI
+from duckmail.config.settings import settings
+
+app = typer.Typer(
+    name="duckmail",
+    help="Lightweight CLI for DuckDuckGo Email Protection",
+    add_completion=True
+)
+auth_app = typer.Typer(help="Authentication commands")
+app.add_typer(auth_app, name="auth")
+
+console = Console()
+
+
+@auth_app.command("login")
+def login(
+    username: Optional[str] = typer.Option(None, "--username", "-u", help="DuckDuckGo username")
+):
+    """Login to DuckDuckGo Email Protection.
+    
+    This will send an OTP to your registered email address.
+    """
+    auth = AuthAPI()
+    
+    # Get username
+    if not username:
+        username = Prompt.ask("Enter your DuckDuckGo username")
+    
+    try:
+        # Request OTP
+        console.print(f"[yellow]Requesting login OTP for user:[/yellow] {username}")
+        auth.request_login(username)
+        console.print("[green]OK[/green] OTP sent to your email!")
+        
+        # Get OTP from user
+        console.print("\n[cyan]Check your email for the OTP passphrase.[/cyan]")
+        console.print("[dim]Format: word1+word2+word3+word4[/dim]")
+        otp = Prompt.ask("\nEnter OTP passphrase")
+        
+        # Confirm login
+        console.print("\n[yellow]Authenticating...[/yellow]")
+        response = auth.confirm_login(username, otp)
+        
+        if response.get("status") == "authenticated":
+            console.print("[green]OK[/green] Login successful!")
+            
+            # Get dashboard to retrieve access token
+            console.print("[yellow]Fetching account information...[/yellow]")
+            dashboard = auth.get_dashboard()
+            
+            user_email = dashboard.get("user", {}).get("email", "N/A")
+            addresses_count = dashboard.get("stats", {}).get("addresses_generated", 0)
+            
+            console.print(f"\n[green]Welcome back![/green]")
+            console.print(f"Username: [cyan]{username}[/cyan]")
+            console.print(f"Email: [cyan]{user_email}[/cyan]")
+            console.print(f"Addresses generated: [cyan]{addresses_count}[/cyan]")
+        else:
+            console.print("[red]ERROR[/red] Login failed")
+            raise typer.Exit(1)
+            
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@auth_app.command("signup", hidden=True)
+def signup(
+    username: Optional[str] = typer.Option(None, "--username", "-u", help="Desired username"),
+    email: Optional[str] = typer.Option(None, "--email", "-e", help="Email for forwarding"),
+    disable_secure_reply: bool = typer.Option(False, "--disable-secure-reply", help="Disable secure reply")
+):
+    """Sign up for DuckDuckGo Email Protection.
+    
+    NOTE: This command may not work due to DuckDuckGo's bot protection.
+    Please sign up via browser at https://duckduckgo.com/email/ first,
+    then use 'duckmail auth login' to authenticate.
+    """
+    auth = AuthAPI()
+    
+    try:
+        # Get username
+        if not username:
+            username = Prompt.ask("Enter desired username")
+        
+        # Get email
+        if not email:
+            email = Prompt.ask("Enter your email address")
+        
+        # Validate username (dry run)
+        console.print(f"[yellow]Checking username availability...[/yellow]")
+        dryrun_response = auth.signup_dryrun(username, email, disable_secure_reply)
+        
+        if dryrun_response.get("status") != "valid":
+            console.print(f"[red]X[/red] Username '{username}' is not available")
+            raise typer.Exit(1)
+        
+        console.print(f"[green]OK[/green] Username '{username}' is available")
+        
+        # Validate email
+        console.print(f"[yellow]Validating email address...[/yellow]")
+        if not auth.validate_email(email):
+            console.print(f"[red]X[/red] Email '{email}' is not valid")
+            raise typer.Exit(1)
+        
+        console.print(f"[green]OK[/green] Email is valid")
+        
+        # Confirm signup
+        console.print(f"\n[cyan]Account Details:[/cyan]")
+        console.print(f"Username: [cyan]{username}[/cyan]")
+        console.print(f"Email: [cyan]{email}[/cyan]")
+        console.print(f"Secure Reply: [cyan]{'Disabled' if disable_secure_reply else 'Enabled'}[/cyan]")
+        
+        if not Confirm.ask("\nProceed with signup?", default=True):
+            console.print("[yellow]Signup cancelled[/yellow]")
+            raise typer.Exit(0)
+        
+        # Create account
+        console.print(f"\n[yellow]Creating account...[/yellow]")
+        signup_response = auth.signup(username, email, disable_secure_reply)
+        
+        if signup_response.get("status") != "created":
+            console.print(f"[red]ERROR[/red] Signup failed")
+            raise typer.Exit(1)
+        
+        console.print(f"[green]OK[/green] Account created!")
+        console.print(f"[yellow]OTP sent to {email}[/yellow]")
+        
+        # Get OTP
+        console.print("\n[cyan]Check your email for the OTP passphrase.[/cyan]")
+        console.print("[dim]Format: word1+word2+word3+word4[/dim]")
+        otp = Prompt.ask("\nEnter OTP passphrase")
+        
+        # Verify email
+        console.print("\n[yellow]Verifying email...[/yellow]")
+        verify_response = auth.verify_signup(username, otp)
+        
+        if verify_response.get("status") == "authenticated":
+            console.print("[green]OK[/green] Email verified!")
+            
+            # Get dashboard
+            console.print("[yellow]Setting up account...[/yellow]")
+            dashboard = auth.get_dashboard()
+            
+            console.print(f"\n[green]Welcome to DuckDuckGo Email Protection![/green]")
+            console.print(f"Username: [cyan]{username}[/cyan]")
+            console.print(f"Email: [cyan]{email}[/cyan]")
+            console.print(f"\n[dim]You can now generate duck email addresses with:[/dim]")
+            console.print(f"[dim]  duckmail generate[/dim]")
+        else:
+            console.print("[red]ERROR[/red] Verification failed")
+            raise typer.Exit(1)
+            
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@auth_app.command("logout")
+def logout():
+    """Logout from DuckDuckGo Email Protection.
+    
+    This will clear all stored credentials.
+    """
+    auth = AuthAPI()
+    auth.logout()
+    console.print("[green]OK[/green] Logged out successfully")
+    console.print("[dim]All credentials have been cleared[/dim]")
+
+
+@auth_app.command("status")
+def status():
+    """Check authentication status."""
+    auth = AuthAPI()
+    
+    if auth.is_authenticated():
+        # Try to verify token
+        console.print("[yellow]Verifying authentication...[/yellow]")
+        
+        if auth.verify_token():
+            user_data = settings.load_user_data()
+            
+            console.print("[green]OK[/green] Authenticated")
+            if user_data:
+                console.print(f"Username: [cyan]{user_data.get('username', 'N/A')}[/cyan]")
+                console.print(f"Email: [cyan]{user_data.get('email', 'N/A')}[/cyan]")
+            
+            if auth.has_access_token():
+                console.print("[green]OK[/green] Access token available")
+        else:
+            console.print("[yellow]WARNING[/yellow] Token expired")
+            console.print("[dim]Please login again[/dim]")
+    else:
+        console.print("[red]ERROR[/red] Not authenticated")
+        console.print("[dim]Use 'duckmail auth login' to authenticate[/dim]")
+
+
+@app.command("generate")
+def generate_address(
+    count: int = typer.Option(1, "--count", "-n", help="Number of addresses to generate"),
+    copy: bool = typer.Option(False, "--copy", "-c", help="Copy generated address to clipboard")
+):
+    """Generate new duck email address(es).
+    
+    Generates random duck email addresses that forward to your registered email.
+    """
+    auth = AuthAPI()
+    
+    # Check authentication
+    if not auth.has_access_token():
+        console.print("[red]ERROR[/red] Not authenticated")
+        console.print("[dim]Use 'duckmail auth login' first[/dim]")
+        raise typer.Exit(1)
+    
+    address_api = AddressAPI()
+    
+    try:
+        if count == 1:
+            console.print("[yellow]Generating address...[/yellow]")
+            alias = address_api.generate()
+            full_address = address_api.get_full_address(alias)
+            console.print(f"\n[green]OK[/green] Generated: [cyan]{full_address}[/cyan]")
+            
+            # Copy to clipboard if requested
+            if copy:
+                try:
+                    pyperclip.copy(full_address)
+                    console.print("[green]OK[/green] Copied to clipboard!")
+                except Exception as e:
+                    console.print(f"[yellow]WARNING[/yellow] Could not copy to clipboard: {e}")
+        else:
+            if copy:
+                console.print("[yellow]WARNING[/yellow] Copy option only works with single address generation")
+            
+            console.print(f"[yellow]Generating {count} addresses...[/yellow]\n")
+            
+            table = Table(title=f"Generated Addresses")
+            table.add_column("#", style="dim")
+            table.add_column("Address", style="cyan")
+            
+            for i in range(count):
+                alias = address_api.generate()
+                full_address = address_api.get_full_address(alias)
+                table.add_row(str(i + 1), full_address)
+            
+            console.print(table)
+            console.print(f"\n[green]OK[/green] Generated {count} addresses successfully")
+            
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@app.command("info")
+def show_info():
+    """Show account information and statistics."""
+    auth = AuthAPI()
+    
+    # Check authentication
+    if not auth.is_authenticated():
+        console.print("[red]ERROR[/red] Not authenticated")
+        console.print("[dim]Use 'duckmail auth login' first[/dim]")
+        raise typer.Exit(1)
+    
+    try:
+        console.print("[yellow]Fetching account information...[/yellow]\n")
+        dashboard = auth.get_dashboard()
+        
+        user = dashboard.get("user", {})
+        stats = dashboard.get("stats", {})
+        
+        # Create info table
+        table = Table(title="Account Information", show_header=False)
+        table.add_column("Field", style="cyan")
+        table.add_column("Value", style="green")
+        
+        table.add_row("Username", user.get("username", "N/A"))
+        table.add_row("Email", user.get("email", "N/A"))
+        table.add_row("Cohort", user.get("cohort", "N/A"))
+        table.add_row("Addresses Generated", str(stats.get("addresses_generated", 0)))
+        
+        console.print(table)
+        
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+# Aliases for commands
+@app.command("g", hidden=True)
+def g(
+    count: int = typer.Option(1, "--count", "-n", help="Number of addresses to generate"),
+    copy: bool = typer.Option(False, "--copy", "-c", help="Copy generated address to clipboard")
+):
+    """Alias for generate command."""
+    generate_address(count, copy)
+
+
+@app.command("gen", hidden=True)
+def gen(
+    count: int = typer.Option(1, "--count", "-n", help="Number of addresses to generate"),
+    copy: bool = typer.Option(False, "--copy", "-c", help="Copy generated address to clipboard")
+):
+    """Alias for generate command."""
+    generate_address(count, copy)
+
+
+@app.command("i", hidden=True)
+def i():
+    """Alias for info command."""
+    show_info()
+
+
+@app.command("version")
+def version():
+    """Show version information."""
+    console.print("[cyan]DuckMail CLI[/cyan] [green]v0.1.0[/green]")
+    console.print("[dim]Lightweight CLI for DuckDuckGo Email Protection[/dim]")
+
+
+@app.callback()
+def main():
+    """
+    DuckMail CLI - Manage DuckDuckGo Email Protection from the terminal.
+    
+    Use 'duckmail --help' to see available commands.
+    """
+    pass
+
+
+if __name__ == "__main__":
+    app()

duckmail/config/settings.py

@@ -0,0 +1,110 @@
+"""Configuration management for DuckMail CLI."""
+
+from pathlib import Path
+from typing import Optional
+import json
+from pydantic import BaseModel, Field
+
+
+class Settings(BaseModel):
+    """Application settings."""
+    
+    api_base_url: str = Field(
+        default="https://quack.duckduckgo.com/api",
+        description="Base URL for DuckDuckGo API"
+    )
+    
+    config_dir: Path = Field(
+        default_factory=lambda: Path.home() / ".config" / "duckmail",
+        description="Configuration directory"
+    )
+    
+    cache_dir: Path = Field(
+        default_factory=lambda: Path.home() / ".cache" / "duckmail",
+        description="Cache directory"
+    )
+    
+    timeout: int = Field(
+        default=30,
+        description="HTTP request timeout in seconds"
+    )
+    
+    class Config:
+        arbitrary_types_allowed = True
+    
+    def __init__(self, **data):
+        super().__init__(**data)
+        # Create directories if they don't exist
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+    
+    @property
+    def config_file(self) -> Path:
+        """Path to configuration file."""
+        return self.config_dir / "config.json"
+    
+    @property
+    def user_file(self) -> Path:
+        """Path to user data file."""
+        return self.config_dir / "user.json"
+    
+    def save(self) -> None:
+        """Save settings to file."""
+        data = self.model_dump(mode='json')
+        # Convert Path objects to strings for JSON serialization
+        data['config_dir'] = str(self.config_dir)
+        data['cache_dir'] = str(self.cache_dir)
+        
+        with open(self.config_file, 'w') as f:
+            json.dump(data, f, indent=2)
+    
+    @classmethod
+    def load(cls) -> "Settings":
+        """Load settings from file or create default."""
+        settings = cls()
+        
+        if settings.config_file.exists():
+            try:
+                with open(settings.config_file) as f:
+                    data = json.load(f)
+                    # Convert string paths back to Path objects
+                    if 'config_dir' in data:
+                        data['config_dir'] = Path(data['config_dir'])
+                    if 'cache_dir' in data:
+                        data['cache_dir'] = Path(data['cache_dir'])
+                    return cls(**data)
+            except Exception:
+                # If loading fails, return default settings
+                pass
+        
+        return settings
+    
+    def save_user_data(self, username: str, email: Optional[str] = None) -> None:
+        """Save user data to file."""
+        data = {
+            "username": username,
+            "email": email
+        }
+        with open(self.user_file, 'w') as f:
+            json.dump(data, f, indent=2)
+    
+    def load_user_data(self) -> Optional[dict]:
+        """Load user data from file."""
+        if self.user_file.exists():
+            try:
+                with open(self.user_file) as f:
+                    return json.load(f)
+            except Exception:
+                pass
+        return None
+    
+    def clear_user_data(self) -> None:
+        """Clear user data file."""
+        if self.user_file.exists():
+            self.user_file.unlink()
+
+
+# Global settings instance
+settings = Settings.load()
+
+# Made with Bob

duckmail/utils/storage.py

@@ -0,0 +1,106 @@
+"""Secure credential storage using system keyring."""
+
+import keyring
+from typing import Optional
+import keyring.errors
+
+
+SERVICE_NAME = "duckmail"
+
+
+class CredentialStorage:
+    """Secure storage for authentication credentials."""
+    
+    @staticmethod
+    def save_jwt_token(token: str) -> None:
+        """Save JWT authentication token securely.
+        
+        Args:
+            token: JWT token from login
+        """
+        try:
+            keyring.set_password(SERVICE_NAME, "jwt_token", token)
+        except keyring.errors.NoKeyringError:
+            # Keyring not available, silently fail
+            pass
+    
+    @staticmethod
+    def get_jwt_token() -> Optional[str]:
+        """Retrieve JWT authentication token.
+        
+        Returns:
+            JWT token or None if not found
+        """
+        try:
+            return keyring.get_password(SERVICE_NAME, "jwt_token")
+        except keyring.errors.NoKeyringError:
+            # Keyring not available
+            return None
+    
+    @staticmethod
+    def delete_jwt_token() -> None:
+        """Delete JWT authentication token."""
+        try:
+            keyring.delete_password(SERVICE_NAME, "jwt_token")
+        except (keyring.errors.PasswordDeleteError, keyring.errors.NoKeyringError):
+            pass
+    
+    @staticmethod
+    def save_access_token(token: str) -> None:
+        """Save long-lived access token securely.
+        
+        Args:
+            token: Access token from dashboard
+        """
+        try:
+            keyring.set_password(SERVICE_NAME, "access_token", token)
+        except keyring.errors.NoKeyringError:
+            # Keyring not available, silently fail
+            pass
+    
+    @staticmethod
+    def get_access_token() -> Optional[str]:
+        """Retrieve access token.
+        
+        Returns:
+            Access token or None if not found
+        """
+        try:
+            return keyring.get_password(SERVICE_NAME, "access_token")
+        except keyring.errors.NoKeyringError:
+            # Keyring not available
+            return None
+    
+    @staticmethod
+    def delete_access_token() -> None:
+        """Delete access token."""
+        try:
+            keyring.delete_password(SERVICE_NAME, "access_token")
+        except (keyring.errors.PasswordDeleteError, keyring.errors.NoKeyringError):
+            pass
+    
+    @staticmethod
+    def has_jwt_token() -> bool:
+        """Check if JWT token exists.
+        
+        Returns:
+            True if JWT token is stored
+        """
+        return CredentialStorage.get_jwt_token() is not None
+    
+    @staticmethod
+    def has_access_token() -> bool:
+        """Check if access token exists.
+        
+        Returns:
+            True if access token is stored
+        """
+        return CredentialStorage.get_access_token() is not None
+    
+    @staticmethod
+    def clear_all() -> None:
+        """Clear all stored credentials."""
+        CredentialStorage.delete_jwt_token()
+        CredentialStorage.delete_access_token()
+
+# Made with Bob

duckmail-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+duckmail/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckmail/__main__.py,sha256=XJ4jaw9x0e-_eugPU4DAgaedKSRh4W2mp5cVfRZgFOI,134
+duckmail/cli.py,sha256=mO4Sr_9YxNjjDFkYpmYdQoCd3NXJVAxs-sdmOOLOgGs,12691
+duckmail/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckmail/api/addresses.py,sha256=kaCw1Ngf09E1RnDlwfFFBoIqmMJOwzp9G5BPI7VrdMc,1465
+duckmail/api/auth.py,sha256=-Xax7uJY1bXeNe0afaWtm7zjZ8PdDZCJNpi5uH1phd8,10164
+duckmail/api/client.py,sha256=mpTdLQ3W-VpHFiUnSwTkz5MfXzFpfPIwTg4PsODWgls,6655
+duckmail/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckmail/config/settings.py,sha256=BWNT6e1PBnlyCFYbUXiC6C3HrWKfNu-VF-syCnxXwUA,3435
+duckmail/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckmail/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckmail/utils/storage.py,sha256=YAF28RsRhcvHuWaDtKz6Fdk_Sz8qpNvbUlGrgFnoaD4,3121
+duckmail-0.1.0.dist-info/licenses/LICENSE,sha256=K88YQZbkkLd_oNxQN1m-nwayWo4tpgHYvp5Faibi4M0,1097
+duckmail-0.1.0.dist-info/METADATA,sha256=ANUeezxjd_i5B91YyvmwfQyMyBDSHHUGfc6cxLcrmdI,4492
+duckmail-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+duckmail-0.1.0.dist-info/entry_points.txt,sha256=dIqw7jCfBBt0-70IeD5DZHwbQTSO4t5vJ1jI1HXGxfc,46
+duckmail-0.1.0.dist-info/top_level.txt,sha256=vce8aekTrxrlK7ggsYSRPIKMspu3quxNsDsSF7I6PJI,9
+duckmail-0.1.0.dist-info/RECORD,,

duckmail-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

duckmail-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+duckmail = duckmail.cli:app

duckmail-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+duckmail