proton-alias-send 0.1.0__py3-none-any.whl

proton_alias_send/__init__.py

@@ -0,0 +1,7 @@
+"""Create Proton Pass / SimpleLogin reverse aliases from the command line."""
+
+__version__ = "0.1.0"
+
+from proton_alias_send.cli import create_contact, find_alias_id, main
+
+__all__ = ["__version__", "create_contact", "find_alias_id", "main"]

proton_alias_send/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for `python -m proton_alias_send`."""
+
+import sys
+
+from proton_alias_send.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

proton_alias_send/cli.py

@@ -0,0 +1,578 @@
+#!/usr/bin/env python3
+"""
+proton-alias-send - Create a Proton Pass / SimpleLogin reverse alias
+(contact) for sending email from an alias without going through the dashboard.
+
+Config file (create with --init-config):
+  Linux/macOS : ~/.config/proton-alias-send/config.toml  (or $XDG_CONFIG_HOME)
+  Windows     : %APPDATA%\\proton-alias-send\\config.toml
+
+Usage:
+  proton-alias-send --init-config                 # first-time setup
+  proton-alias-send recipient@example.com         # alias + key come from config
+  proton-alias-send -a alias@sl.io --copy recipient@example.com
+
+The reverse alias is written to stdout; progress/status goes to stderr, so
+the result can be piped or captured cleanly.
+
+Requires Python 3.11+ (stdlib tomllib).
+"""
+
+from __future__ import annotations
+
+import argparse
+import http.client
+import ipaddress
+import json
+import os
+import platform
+import stat
+import subprocess
+import sys
+import tomllib
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+APP_NAME = "proton-alias-send"
+DEFAULT_BASE_URL = "https://app.simplelogin.io"
+
+# Seconds to wait on any single API call before giving up.
+REQUEST_TIMEOUT = 30
+
+# Safety net for paginating alias search results: a server that ignores page_id
+# would otherwise loop forever. The API returns 20 aliases per page, so this is
+# 400 results, which is plenty because the search narrows them to near-matches.
+MAX_ALIAS_PAGES = 20
+
+# Keys recognised in the config file.
+KNOWN_CONFIG_KEYS = {"api_key", "alias", "base_url", "copy", "quiet"}
+
+SAMPLE_CONFIG = """\
+# proton-alias-send configuration
+# Run `proton-alias-send --init-config` to recreate this file.
+#
+# Tip: restrict read access after creation (already done on Unix):
+#   chmod 600 {config_path}
+
+# Your SimpleLogin API key (required if not passed via --api-key).
+# Get it at: https://app.simplelogin.io/dashboard/api_key
+# Leave empty to fall back to the $SIMPLELOGIN_API_KEY environment variable.
+api_key = ""
+
+# Default alias to send from. Override per-invocation with -a / --alias.
+# alias = "you@simplelogin.io"
+
+# SimpleLogin API base URL. Change only for self-hosted instances.
+base_url = "{base_url}"
+
+# Copy the reverse alias to the clipboard automatically after printing.
+copy = false
+
+# Suppress progress messages (stderr). Only the reverse alias is printed.
+quiet = false
+"""
+
+
+# ---------------------------------------------------------------------------
+# Config path
+# ---------------------------------------------------------------------------
+
+def get_config_dir() -> Path:
+    system = platform.system()
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    else:
+        # Linux, macOS, BSDs - honour XDG_CONFIG_HOME. Empty counts as unset, per
+        # the XDG spec; otherwise the config would land in the current directory.
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / APP_NAME
+
+
+def get_config_path() -> Path:
+    return get_config_dir() / "config.toml"
+
+
+# ---------------------------------------------------------------------------
+# Config loading and merging
+# ---------------------------------------------------------------------------
+
+def load_config(config_path: Path) -> dict[str, Any]:
+    """Load and return the TOML config, or {} if the file doesn't exist."""
+    if not config_path.exists():
+        return {}
+    try:
+        with open(config_path, "rb") as fh:
+            config = tomllib.load(fh)
+    except OSError as exc:
+        sys.exit(f"Error reading config file {config_path}: {exc}")
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        sys.exit(f"Error parsing config file {config_path}: {exc}")
+
+    unknown = set(config.keys()) - KNOWN_CONFIG_KEYS
+    if unknown:
+        print(
+            f"Warning: unknown config key(s) will be ignored: {', '.join(sorted(unknown))}",
+            file=sys.stderr,
+        )
+    return config
+
+
+def merge(cli_val: Any, config_val: Any, fallback: Any) -> Any:
+    """
+    Return the highest-priority set value: CLI > config > env/hardcoded default.
+
+    An empty string counts as unset so that the `api_key = ""` line in the
+    generated sample config still falls through to $SIMPLELOGIN_API_KEY.
+    """
+    for value in (cli_val, config_val):
+        if value is not None and value != "":
+            return value
+    return fallback
+
+
+# ---------------------------------------------------------------------------
+# Config initialisation
+# ---------------------------------------------------------------------------
+
+def cmd_init_config(config_path: Path) -> int:
+    """Write a sample config file and set restrictive permissions on Unix."""
+    if config_path.exists():
+        try:
+            answer = input(
+                f"Config already exists at {config_path}. Overwrite? [y/N] "
+            ).strip().lower()
+        except EOFError:
+            # Non-interactive stdin: refuse rather than clobber the file.
+            print(
+                f"Error: config already exists at {config_path} and stdin is not "
+                "interactive. Remove the file first to recreate it.",
+                file=sys.stderr,
+            )
+            return 1
+        if answer != "y":
+            print("Aborted.", file=sys.stderr)
+            return 0
+
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(
+            SAMPLE_CONFIG.format(config_path=config_path, base_url=DEFAULT_BASE_URL),
+            encoding="utf-8",
+        )
+        if platform.system() != "Windows":
+            config_path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 600
+            print(f"Created {config_path}  (permissions: 600)", file=sys.stderr)
+        else:
+            print(f"Created {config_path}", file=sys.stderr)
+    except OSError as exc:
+        print(f"Error writing config file {config_path}: {exc}", file=sys.stderr)
+        return 1
+
+    print("Edit the file to add your API key and default alias.", file=sys.stderr)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# SimpleLogin API
+# ---------------------------------------------------------------------------
+
+def _require_http_url(url: str) -> None:
+    """Reject anything but http(s), which urllib would otherwise happily open (e.g. file://)."""
+    try:
+        scheme = urllib.parse.urlsplit(url).scheme.lower()
+    except ValueError:
+        scheme = ""
+    if scheme not in ("http", "https"):
+        raise RuntimeError(f"Invalid base URL in {url}: it must start with https:// or http://")
+
+
+def _error_text(payload: Any) -> str:
+    """Pull a human-readable message out of whatever the API returned."""
+    if isinstance(payload, dict):
+        for key in ("error", "message"):
+            value = payload.get(key)
+            if isinstance(value, str) and value:
+                return value
+    return str(payload)
+
+
+def _request(
+    method: str, url: str, api_key: str, body: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """
+    Perform a JSON API call and return the decoded object.
+
+    Every failure mode - HTTP error, transport error, malformed body - is
+    normalised into RuntimeError so callers have a single thing to catch.
+    """
+    _require_http_url(url)
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(
+        url, data=data, headers={"Content-Type": "application/json"}, method=method
+    )
+    # Unredirected, so a redirect can't carry the key to another host. SimpleLogin
+    # spells this header `Authentication`, not `Authorization`.
+    req.add_unredirected_header("Authentication", api_key)
+    try:
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as exc:
+        try:
+            error_body = exc.read()
+        except (OSError, http.client.HTTPException):
+            error_body = b""
+        try:
+            payload = json.loads(error_body)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            payload = error_body.decode(errors="replace").strip()
+        hint = ""
+        if exc.code == 401:
+            hint = " (check your API key)"
+        raise RuntimeError(f"HTTP {exc.code} from {url}: {_error_text(payload)}{hint}") from None
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Could not reach {url}: {exc.reason}") from None
+    except TimeoutError:
+        raise RuntimeError(f"Timed out after {REQUEST_TIMEOUT}s waiting for {url}") from None
+    except (OSError, http.client.HTTPException) as exc:
+        raise RuntimeError(f"Could not reach {url}: {exc}") from None
+    except ValueError:
+        # http.client quotes the offending header in this exception, so never
+        # include it here: the bad value is usually the API key.
+        raise RuntimeError(
+            f"Could not send the request to {url}: the API key or URL contains "
+            "invalid characters."
+        ) from None
+
+    try:
+        decoded = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        snippet = raw[:200].decode(errors="replace").strip()
+        raise RuntimeError(f"Non-JSON response from {url}: {snippet!r}") from None
+
+    if not isinstance(decoded, dict):
+        raise RuntimeError(f"Unexpected response from {url}: expected an object, got {decoded!r}")
+    return decoded
+
+
+def find_alias_id(base_url: str, api_key: str, alias_email: str) -> int | None:
+    """Search the account's aliases and return the ID for alias_email, or None."""
+    alias_email = alias_email.lower().strip()
+    base_url = base_url.rstrip("/")
+    for page in range(MAX_ALIAS_PAGES):
+        # The query is a loose server-side match, so results still need the exact
+        # comparison below. POST is the documented way to send it in a body.
+        data = _request(
+            "POST",
+            f"{base_url}/api/v2/aliases?page_id={page}",
+            api_key,
+            body={"query": alias_email},
+        )
+        aliases = data.get("aliases") or []
+        if not aliases:
+            return None
+        if not isinstance(aliases, list):
+            raise RuntimeError(f"Unexpected API response (aliases is not a list): {data}")
+        for alias in aliases:
+            if not isinstance(alias, dict):
+                raise RuntimeError(f"Unexpected API response (malformed alias): {alias!r}")
+            if str(alias.get("email", "")).lower() == alias_email:
+                try:
+                    return int(alias["id"])
+                except (KeyError, TypeError, ValueError):
+                    raise RuntimeError(
+                        f"Alias '{alias_email}' returned without a valid id field."
+                    ) from None
+    raise RuntimeError(
+        f"Gave up after {MAX_ALIAS_PAGES} pages of search results without finding "
+        f"'{alias_email}'. Check the alias address for typos."
+    )
+
+
+def create_contact(base_url: str, api_key: str, alias_id: int, contact_email: str) -> str:
+    """
+    Create a contact for alias_id and return the reverse alias address.
+    Idempotent: returns the existing reverse alias if the contact already exists.
+    """
+    data = _request(
+        "POST",
+        f"{base_url.rstrip('/')}/api/aliases/{alias_id}/contacts",
+        api_key,
+        body={"contact": contact_email},
+    )
+    # Not `reverse_alias`, which is a display string: "Name a@b.c <ra+x@sl.co>".
+    address = data.get("reverse_alias_address")
+    if not isinstance(address, str) or not address:
+        raise RuntimeError(f"Unexpected API response (no reverse_alias_address field): {data}")
+    return address
+
+
+# ---------------------------------------------------------------------------
+# Clipboard
+# ---------------------------------------------------------------------------
+
+def copy_to_clipboard(text: str) -> bool:
+    """Try to copy text to the system clipboard. Returns True on success."""
+    system = platform.system()
+    candidates: list[list[str]] = []
+    if system == "Darwin":
+        candidates = [["pbcopy"]]
+    elif system == "Linux":
+        candidates = [
+            ["wl-copy"],  # Wayland
+            ["xclip", "-selection", "clipboard"],
+            ["xsel", "--clipboard", "--input"],
+        ]
+    elif system == "Windows":
+        candidates = [["clip"]]
+
+    for cmd in candidates:
+        try:
+            subprocess.run(
+                cmd, input=text.encode(), check=True,
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            )
+            return True
+        except (FileNotFoundError, OSError, subprocess.CalledProcessError):
+            continue
+    return False
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def build_parser(default_config_path: Path) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=APP_NAME,
+        description=(
+            "Create a SimpleLogin reverse alias so you can send email from an alias "
+            "to a new contact without touching the dashboard."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=f"""\
+config file (default): {default_config_path}
+  Run --init-config to create it. CLI flags always override config values.
+
+examples:
+  # First-time setup
+  proton-alias-send --init-config
+
+  # Minimal - alias, api_key, and other settings come from config
+  proton-alias-send boss@example.com
+
+  # Override the alias just for this invocation
+  proton-alias-send -a work@simplelogin.io boss@example.com
+
+  # Force clipboard copy regardless of config setting
+  proton-alias-send --copy boss@example.com
+
+  # Suppress config's copy=true for one run
+  proton-alias-send --no-copy boss@example.com
+
+  # Pipe the result directly (quiet suppresses progress noise on stderr)
+  open "mailto:$(proton-alias-send -q boss@example.com)"
+
+  # Use a non-default config file
+  proton-alias-send --config ~/work-sl.toml boss@example.com
+""",
+    )
+
+    from proton_alias_send import __version__
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "--init-config",
+        action="store_true",
+        help="Write a sample config file to the default path (or --config path) and exit.",
+    )
+    parser.add_argument(
+        "--config",
+        default=None,
+        metavar="PATH",
+        help=f"Path to config file. Default: {default_config_path}",
+    )
+    parser.add_argument(
+        "contact",
+        metavar="CONTACT_EMAIL",
+        nargs="?",
+        default=None,
+        help="Recipient address to create a contact (reverse alias) for.",
+    )
+    parser.add_argument(
+        "-a", "--alias",
+        default=None,
+        metavar="EMAIL",
+        help="SimpleLogin alias to send from. Overrides config 'alias'.",
+    )
+    parser.add_argument(
+        "-k", "--api-key",
+        default=None,
+        metavar="KEY",
+        help="SimpleLogin API key. Overrides config 'api_key' and $SIMPLELOGIN_API_KEY.",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=None,
+        metavar="URL",
+        help=f"SimpleLogin base URL. Overrides config 'base_url'. Default: {DEFAULT_BASE_URL}",
+    )
+    # BooleanOptionalAction generates the --no-* form itself; spelling it out
+    # here too would register duplicate and --no-no-* options.
+    parser.add_argument(
+        "--copy",
+        dest="copy",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Copy the reverse alias to clipboard. Overrides config 'copy'.",
+    )
+    parser.add_argument(
+        "-q", "--quiet",
+        dest="quiet",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Suppress progress messages. Overrides config 'quiet'.",
+    )
+    return parser
+
+
+def log(msg: str, quiet: bool) -> None:
+    if not quiet:
+        print(msg, file=sys.stderr)
+
+
+def _config_type_errors(strings: dict[str, Any], booleans: dict[str, Any]) -> list[str]:
+    """Report wrongly typed settings by name. Values stay out of it: one may be the API key."""
+    errors = [
+        f"Setting '{name}' must be a string."
+        for name, value in strings.items()
+        if value is not None and not isinstance(value, str)
+    ]
+    errors += [
+        f"Setting '{name}' must be true or false."
+        for name, value in booleans.items()
+        if not isinstance(value, bool)
+    ]
+    return errors
+
+
+def _is_plaintext_remote(base_url: str) -> bool:
+    """True for an http:// URL off this machine, where the API key travels unencrypted."""
+    try:
+        parts = urllib.parse.urlsplit(base_url)
+        host = parts.hostname or ""
+    except ValueError:
+        return False
+    if parts.scheme.lower() != "http" or host.lower() == "localhost":
+        return False
+    try:
+        return not ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return True
+
+
+def run(argv: list[str] | None = None) -> int:
+    default_config_path = get_config_path()
+    parser = build_parser(default_config_path)
+    args = parser.parse_args(argv)
+
+    config_path = Path(args.config).expanduser() if args.config else default_config_path
+
+    if args.init_config:
+        return cmd_init_config(config_path)
+
+    config = load_config(config_path)
+
+    # Resolve each setting: CLI > config file > env var / hardcoded default
+    api_key  = merge(args.api_key,  config.get("api_key"),  os.environ.get("SIMPLELOGIN_API_KEY"))
+    alias    = merge(args.alias,    config.get("alias"),    None)
+    base_url = merge(args.base_url, config.get("base_url"), DEFAULT_BASE_URL)
+    do_copy  = merge(args.copy,     config.get("copy"),     False)
+    quiet    = merge(args.quiet,    config.get("quiet"),    False)
+
+    # Validate - collect all errors before printing so the user can fix them in one go
+    errors = _config_type_errors(
+        strings={"api_key": api_key, "alias": alias, "base_url": base_url},
+        booleans={"copy": do_copy, "quiet": quiet},
+    )
+    if isinstance(api_key, str):
+        api_key = api_key.strip()
+    if not args.contact:
+        errors.append("CONTACT_EMAIL is required.")
+    if not api_key:
+        errors.append(
+            "No API key found. Set 'api_key' in the config file, use -k / --api-key, "
+            "or set $SIMPLELOGIN_API_KEY."
+        )
+    if not alias:
+        errors.append(
+            "No alias specified. Set 'alias' in the config file or use -a / --alias."
+        )
+    if errors:
+        for msg in errors:
+            print(f"Error: {msg}", file=sys.stderr)
+        return 1
+
+    if _is_plaintext_remote(base_url):
+        print(
+            f"Warning: {base_url} is not HTTPS, so your API key is sent unencrypted.",
+            file=sys.stderr,
+        )
+
+    try:
+        log(f"Looking up alias ID for {alias} ...", quiet)
+        alias_id = find_alias_id(base_url, api_key, alias)
+        if alias_id is None:
+            print(
+                f"Error: alias '{alias}' not found in your SimpleLogin account.",
+                file=sys.stderr,
+            )
+            return 1
+        log(f"  Found alias ID: {alias_id}", quiet)
+
+        log(f"Creating contact for {args.contact} ...", quiet)
+        reverse_alias = create_contact(base_url, api_key, alias_id, args.contact)
+        log("  Done.", quiet)
+    except RuntimeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    # Flush here so a closed pipe surfaces inside main(), not at interpreter exit.
+    print(reverse_alias, flush=True)
+
+    if do_copy:
+        if copy_to_clipboard(reverse_alias):
+            log("Copied to clipboard.", quiet)
+        else:
+            print(
+                "Warning: clipboard copy failed. No supported tool found "
+                "(pbcopy / xclip / xsel / wl-copy / clip).",
+                file=sys.stderr,
+            )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console-script entry point."""
+    try:
+        return run(argv)
+    except KeyboardInterrupt:
+        print("Interrupted.", file=sys.stderr)
+        return 130
+    except BrokenPipeError:
+        # e.g. `proton-alias-send ... | head` - exit quietly like other CLI tools.
+        # Point stdout at devnull so the flush at interpreter exit can't fail too.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        os.close(devnull)
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

proton_alias_send-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: proton-alias-send
+Version: 0.1.0
+Summary: Create Proton Pass / SimpleLogin reverse aliases from the command line
+Project-URL: Homepage, https://github.com/fictiontoreality/proton-alias-send
+Project-URL: Repository, https://github.com/fictiontoreality/proton-alias-send
+Project-URL: Issues, https://github.com/fictiontoreality/proton-alias-send/issues
+Project-URL: Changelog, https://github.com/fictiontoreality/proton-alias-send/blob/main/CHANGELOG.md
+Author-email: Jesse Johnson <gpg@fictiontoreality.dev>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: alias,cli,email,privacy,proton,proton-pass,simplelogin
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# proton-alias-send
+
+[![PyPI](https://img.shields.io/pypi/v/proton-alias-send.svg)](https://pypi.org/project/proton-alias-send/)
+[![Python](https://img.shields.io/pypi/pyversions/proton-alias-send.svg)](https://pypi.org/project/proton-alias-send/)
+[![License](https://img.shields.io/pypi/l/proton-alias-send.svg)](https://github.com/fictiontoreality/proton-alias-send/blob/main/LICENSE)
+
+Create a Proton Pass / SimpleLogin **reverse alias** from the command line or Python, so you can
+send mail *from* one of your aliases without opening the web dashboard.
+
+SimpleLogin aliases forward mail to you out of the box, but replying from an alias to a
+brand-new recipient requires creating a "contact" first. The dashboard makes you click
+through several screens for this. This tool does it in one command and prints the reverse
+alias address you actually put in your mail client's To: field.
+
+```console
+$ proton-alias-send boss@example.com
+Looking up alias ID for work@simplelogin.io ...
+  Found alias ID: 1234567
+Creating contact for boss@example.com ...
+  Done.
+ra+abc123xyz@simplelogin.co
+```
+
+Mail sent to `ra+abc123xyz@simplelogin.co` arrives at `boss@example.com`
+appearing to come from `work@simplelogin.io`. Send it from a mailbox linked to that alias;
+SimpleLogin only accepts mail to a reverse alias from those mailboxes.
+
+## Install
+
+```console
+pipx install proton-alias-send
+```
+
+or
+
+```console
+uv tool install proton-alias-send
+```
+
+It has **no dependencies** outside the standard library and needs Python 3.11+.
+
+## Setup
+
+```console
+$ proton-alias-send --init-config
+```
+
+That writes a commented config file (mode `600` on Unix) to:
+
+| Platform     | Path                                                              |
+| ------------ | ----------------------------------------------------------------- |
+| Linux / BSD  | `$XDG_CONFIG_HOME/proton-alias-send/config.toml`, else `~/.config/...` |
+| macOS        | `~/.config/proton-alias-send/config.toml`                          |
+| Windows      | `%APPDATA%\proton-alias-send\config.toml`                          |
+
+Fill in your API key from <https://app.simplelogin.io/dashboard/api_key> and the alias you
+usually send from. The key must belong to the SimpleLogin account that holds the alias.
+
+```toml
+api_key = "your-api-key-here"
+alias   = "work@simplelogin.io"
+copy    = true
+```
+
+If you'd rather not keep the key on disk, leave `api_key = ""` and export
+the environment variable `SIMPLELOGIN_API_KEY` instead. Avoid `-k` on shared machines: a
+key on the command line is visible in `ps` and saved in your shell history.
+
+## Usage
+
+```console
+$ proton-alias-send --help
+```
+
+| Flag                | Purpose                                                        |
+| ------------------- | -------------------------------------------------------------- |
+| `-a`, `--alias`     | Alias to send from, overriding the config default               |
+| `-k`, `--api-key`   | API key, overriding config and `$SIMPLELOGIN_API_KEY`           |
+| `--base-url`        | Point at a self-hosted SimpleLogin instance (warns on plain `http://`) |
+| `--copy/--no-copy`  | Copy the result to the clipboard (`pbcopy`/`wl-copy`/`xclip`/`xsel`/`clip`) |
+| `-q`, `--quiet`     | Silence progress output on stderr                               |
+| `--config PATH`     | Use an alternate config file                                    |
+| `--init-config`     | Write the sample config and exit                                |
+
+Settings resolve as **command line > config file > environment / built-in default**, so any
+config value can be overridden for a single run — including booleans, via `--no-copy` and
+`--no-quiet`.
+
+### Scripting
+
+The reverse alias is the only thing written to stdout; all progress and errors go to
+stderr. That makes it safe to capture:
+
+```console
+$ open "mailto:$(proton-alias-send -q boss@example.com)"
+```
+
+Exit status is `0` on success, `1` on any error, `130` if interrupted.
+
+Creating a contact is idempotent — running it twice for the same recipient returns the
+same reverse alias rather than failing.
+
+### As a library
+
+```python
+from proton_alias_send import create_contact, find_alias_id
+
+alias_id = find_alias_id("https://app.simplelogin.io", api_key, "work@simplelogin.io")
+reverse = create_contact("https://app.simplelogin.io", api_key, alias_id, "boss@example.com")
+```
+
+Both raise `RuntimeError` with a readable message on any API, network, or protocol failure.
+
+## Development
+
+```console
+$ uv sync                 # create the venv, including dev tools
+$ uv run pytest           # tests
+$ uv run pytest tests/test_config.py::test_merge_prefers_cli   # a single test
+$ uv run ruff check .     # lint (formatting is deliberately not enforced)
+$ uv run mypy             # type check (strict)
+$ uv build                # build sdist + wheel into dist/
+```
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/fictiontoreality/proton-alias-send/blob/main/LICENSE).
+
+Not affiliated with Proton AG or SimpleLogin.

proton_alias_send-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+proton_alias_send/__init__.py,sha256=9NFFUIWNbI-nRyif0iVngYw-zcmqvhpM41XebF-ZsGY,242
+proton_alias_send/__main__.py,sha256=OXGLAvzDMRGOcx9yrkYLeTku3cFvEQxyQYRqVZ2Xr3s,154
+proton_alias_send/cli.py,sha256=tn7nxb9_YdEqEXZ16iEp4ke-xXMKSjy4IjGNX58mJnw,20686
+proton_alias_send/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proton_alias_send-0.1.0.dist-info/METADATA,sha256=NSt1FMgeZzu8m24U0Ee1otiJtO7gIYNiuByOPYs84ew,6308
+proton_alias_send-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+proton_alias_send-0.1.0.dist-info/entry_points.txt,sha256=dHaQ4ziTamj-34pQNPY3xSMDolFAUvvaHZ7WtR9LT7w,65
+proton_alias_send-0.1.0.dist-info/licenses/LICENSE,sha256=qJcNSp67HYSDsPGjsxBQ215BxQ1zEZUgJZF7jhJ2cjk,11345
+proton_alias_send-0.1.0.dist-info/RECORD,,

proton_alias_send-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

proton_alias_send-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proton-alias-send = proton_alias_send.cli:main

proton_alias_send-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,203 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Jesse Johnson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+