optout 0.1.0__tar.gz

optout-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: optout
+Version: 0.1.0
+Summary: Self-hosted CLI that automates CCPA/CPRA data-broker opt-out requests via Playwright
+Author: Blake Matas
+License-Expression: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/Blake104/OptOut
+Project-URL: Repository, https://github.com/Blake104/OptOut
+Project-URL: Bug Tracker, https://github.com/Blake104/OptOut/issues
+Keywords: privacy,ccpa,cpra,data-broker,opt-out,playwright,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Utilities
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer[all]>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: pydantic>=2
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: sqlmodel>=0.0.19
+Requires-Dist: pyyaml>=6
+Requires-Dist: jinja2>=3
+Requires-Dist: httpx>=0.27
+Requires-Dist: playwright>=1.44
+Requires-Dist: structlog>=23.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: aiosmtpd>=1.4; extra == "dev"
+
+# OptOut
+
+Self-hosted CLI tool that automates submitting opt-out and data-deletion requests to data brokers.
+
+You run it on your own machine with your own information. There is no central server, no accounts, no SaaS. Because *you* are the data subject submitting on your own behalf, the entire "authorized agent" legal apparatus that commercial services like DeleteMe and Optery have to build does not apply here.
+
+---
+
+## What it does and does not do
+
+**Does:**
+- Submit opt-out / deletion requests to people-search and marketing data brokers.
+- Track deadlines (CCPA: 45 days, GDPR: 30 days, etc.) and surface overdue requests.
+- Re-scan brokers periodically and re-submit if your data reappears.
+- Open a real browser window (Chromium) so *you* solve CAPTCHAs — no bot-detection arms race.
+- Send opt-out emails from your own inbox so brokers can't block "the service."
+
+**Does not:**
+- Submit requests for anyone other than the person running the tool.
+- Touch credit bureaus (Experian, Equifax, TransUnion) — those have separate, regulated dispute processes.
+- Remove government records, court filings, or news articles.
+- Guarantee removal from sites that ignore opt-out requests.
+- Store your personal information anywhere except your own machine (`~/.config/optout/`).
+
+---
+
+## Install
+
+**Requirements:** Python 3.11+ and `pip` (or `uv`).
+
+```bash
+git clone https://github.com/your-username/optout.git
+cd optout
+pip install -e ".[dev]"          # or: uv pip install -e ".[dev]"
+playwright install chromium      # one-time browser download
+```
+
+---
+
+## Quickstart
+
+### 1. Initialize your profile
+
+```
+optout init
+```
+
+The interactive wizard asks for your name, address, email, and SMTP credentials. It writes `~/.config/optout/config.yml` (mode `600`) and creates the local SQLite database.
+
+### 2. Queue brokers for opt-out
+
+```
+optout brokers list              # see all supported brokers
+optout queue                     # queue all brokers
+optout queue --broker whitepages # queue one specific broker
+```
+
+### 3. Submit opt-out requests
+
+```
+optout submit
+```
+
+A browser window opens for each web-form broker. Follow the on-screen prompts — select your listing, solve CAPTCHAs, confirm emails. Email-method brokers are submitted automatically using your configured SMTP credentials.
+
+### 4. Check status
+
+```
+optout status
+```
+
+Shows a table of every submission: method used, current status, statutory deadline, and days remaining.
+
+### 5. Re-scan periodically
+
+```
+optout monitor
+```
+
+Checks which brokers still list you and re-queues any that have re-added your data. Cron-friendly — run it monthly.
+
+---
+
+## Commands
+
+```
+optout init                      # interactive setup wizard
+optout brokers list [--category] # list all known brokers
+optout brokers info <slug>       # details + your submission history for one broker
+optout scan [--broker SLUG]      # check which brokers currently list you
+optout queue [--broker SLUG]     # add brokers to the submission queue
+optout submit [--broker SLUG]    # process the queue and submit opt-outs
+optout status [--broker] [--status] # table of submissions, deadlines, callouts
+optout monitor                   # one-shot re-scan (schedule with cron or launchd)
+optout escalate                  # send follow-ups for submissions past their deadline
+optout export                    # dump all submission history as JSON
+```
+
+---
+
+## Configuration
+
+`~/.config/optout/config.yml` is generated by `optout init`. Key sections:
+
+```yaml
+profile:
+  legal_name: "Jane Q Public"
+  current_address:
+    street: "123 Main St"
+    city: "Austin"
+    state: "TX"
+    zip: "78701"
+  emails:
+    current: ["jane@example.com"]
+  phones:
+    current: ["+15125551234"]
+
+email:
+  method: smtp
+  smtp:
+    host: smtp.gmail.com
+    port: 587
+    username: jane@example.com
+    password_env: OPTOUT_SMTP_PASSWORD   # never stored in the file itself
+
+playwright:
+  headless: false    # keep false so you can solve CAPTCHAs
+  slow_mo_ms: 0
+
+monitoring:
+  rescan_interval_days: 30
+```
+
+Sensitive values (SMTP passwords) are read from environment variables, not stored in the config file.
+
+---
+
+## Supported brokers
+
+| Slug | Name | Method | Verification |
+|---|---|---|---|
+| `whitepages` | Whitepages | Web form | Phone (SMS) |
+| `spokeo` | Spokeo | Web form | Email |
+| `beenverified` | BeenVerified | Web form | Email |
+| `radaris` | Radaris | Email | None |
+| `mylife` | MyLife | Email | None |
+
+Community contributions add brokers as YAML files — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Running tests
+
+```bash
+pytest                           # full suite
+pytest tests/test_production_brokers.py  # validate all broker YAMLs only
+```
+
+---
+
+## Legal basis
+
+OptOut cites the applicable statute in every opt-out email and web-form submission:
+
+- **CCPA §1798.105** (California Consumer Privacy Act) — right to deletion, 45-day response window
+- **CPRA** (California Privacy Rights Act) — extends CCPA, same 45-day window
+- **GDPR Art. 17** (General Data Protection Regulation) — right to erasure, 30-day response window
+- **VCDPA, CPA, CTDPA, UCPA** — state-level equivalents
+
+Each broker's YAML lists which statutes apply. The tool automatically includes the correct citation in every submission.
+
+---
+
+## Honest limitations
+
+- Removal is not guaranteed. Some brokers comply reliably; others are slow or re-add data.
+- Web-form flows break when brokers redesign their opt-out pages. If a broker's steps stop working, open an issue or submit a YAML fix.
+- CAPTCHAs require your attention — the tool will pause and prompt you.
+- Email submissions depend on your SMTP server being reachable and not blocked by the broker.
+- Data frequently reappears (60–90 days is typical). Use `optout monitor` to catch this.
+
+---
+
+## License
+
+AGPL-3.0-only. See [LICENSE](LICENSE).
+
+This license was chosen intentionally: anyone who forks this and runs it as a hosted service must publish their changes. The project's legal model depends on each user running their own copy — a hosted fork changes the legal character of the tool.

optout-0.1.0/README.md

@@ -0,0 +1,188 @@
+# OptOut
+
+Self-hosted CLI tool that automates submitting opt-out and data-deletion requests to data brokers.
+
+You run it on your own machine with your own information. There is no central server, no accounts, no SaaS. Because *you* are the data subject submitting on your own behalf, the entire "authorized agent" legal apparatus that commercial services like DeleteMe and Optery have to build does not apply here.
+
+---
+
+## What it does and does not do
+
+**Does:**
+- Submit opt-out / deletion requests to people-search and marketing data brokers.
+- Track deadlines (CCPA: 45 days, GDPR: 30 days, etc.) and surface overdue requests.
+- Re-scan brokers periodically and re-submit if your data reappears.
+- Open a real browser window (Chromium) so *you* solve CAPTCHAs — no bot-detection arms race.
+- Send opt-out emails from your own inbox so brokers can't block "the service."
+
+**Does not:**
+- Submit requests for anyone other than the person running the tool.
+- Touch credit bureaus (Experian, Equifax, TransUnion) — those have separate, regulated dispute processes.
+- Remove government records, court filings, or news articles.
+- Guarantee removal from sites that ignore opt-out requests.
+- Store your personal information anywhere except your own machine (`~/.config/optout/`).
+
+---
+
+## Install
+
+**Requirements:** Python 3.11+ and `pip` (or `uv`).
+
+```bash
+git clone https://github.com/your-username/optout.git
+cd optout
+pip install -e ".[dev]"          # or: uv pip install -e ".[dev]"
+playwright install chromium      # one-time browser download
+```
+
+---
+
+## Quickstart
+
+### 1. Initialize your profile
+
+```
+optout init
+```
+
+The interactive wizard asks for your name, address, email, and SMTP credentials. It writes `~/.config/optout/config.yml` (mode `600`) and creates the local SQLite database.
+
+### 2. Queue brokers for opt-out
+
+```
+optout brokers list              # see all supported brokers
+optout queue                     # queue all brokers
+optout queue --broker whitepages # queue one specific broker
+```
+
+### 3. Submit opt-out requests
+
+```
+optout submit
+```
+
+A browser window opens for each web-form broker. Follow the on-screen prompts — select your listing, solve CAPTCHAs, confirm emails. Email-method brokers are submitted automatically using your configured SMTP credentials.
+
+### 4. Check status
+
+```
+optout status
+```
+
+Shows a table of every submission: method used, current status, statutory deadline, and days remaining.
+
+### 5. Re-scan periodically
+
+```
+optout monitor
+```
+
+Checks which brokers still list you and re-queues any that have re-added your data. Cron-friendly — run it monthly.
+
+---
+
+## Commands
+
+```
+optout init                      # interactive setup wizard
+optout brokers list [--category] # list all known brokers
+optout brokers info <slug>       # details + your submission history for one broker
+optout scan [--broker SLUG]      # check which brokers currently list you
+optout queue [--broker SLUG]     # add brokers to the submission queue
+optout submit [--broker SLUG]    # process the queue and submit opt-outs
+optout status [--broker] [--status] # table of submissions, deadlines, callouts
+optout monitor                   # one-shot re-scan (schedule with cron or launchd)
+optout escalate                  # send follow-ups for submissions past their deadline
+optout export                    # dump all submission history as JSON
+```
+
+---
+
+## Configuration
+
+`~/.config/optout/config.yml` is generated by `optout init`. Key sections:
+
+```yaml
+profile:
+  legal_name: "Jane Q Public"
+  current_address:
+    street: "123 Main St"
+    city: "Austin"
+    state: "TX"
+    zip: "78701"
+  emails:
+    current: ["jane@example.com"]
+  phones:
+    current: ["+15125551234"]
+
+email:
+  method: smtp
+  smtp:
+    host: smtp.gmail.com
+    port: 587
+    username: jane@example.com
+    password_env: OPTOUT_SMTP_PASSWORD   # never stored in the file itself
+
+playwright:
+  headless: false    # keep false so you can solve CAPTCHAs
+  slow_mo_ms: 0
+
+monitoring:
+  rescan_interval_days: 30
+```
+
+Sensitive values (SMTP passwords) are read from environment variables, not stored in the config file.
+
+---
+
+## Supported brokers
+
+| Slug | Name | Method | Verification |
+|---|---|---|---|
+| `whitepages` | Whitepages | Web form | Phone (SMS) |
+| `spokeo` | Spokeo | Web form | Email |
+| `beenverified` | BeenVerified | Web form | Email |
+| `radaris` | Radaris | Email | None |
+| `mylife` | MyLife | Email | None |
+
+Community contributions add brokers as YAML files — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Running tests
+
+```bash
+pytest                           # full suite
+pytest tests/test_production_brokers.py  # validate all broker YAMLs only
+```
+
+---
+
+## Legal basis
+
+OptOut cites the applicable statute in every opt-out email and web-form submission:
+
+- **CCPA §1798.105** (California Consumer Privacy Act) — right to deletion, 45-day response window
+- **CPRA** (California Privacy Rights Act) — extends CCPA, same 45-day window
+- **GDPR Art. 17** (General Data Protection Regulation) — right to erasure, 30-day response window
+- **VCDPA, CPA, CTDPA, UCPA** — state-level equivalents
+
+Each broker's YAML lists which statutes apply. The tool automatically includes the correct citation in every submission.
+
+---
+
+## Honest limitations
+
+- Removal is not guaranteed. Some brokers comply reliably; others are slow or re-add data.
+- Web-form flows break when brokers redesign their opt-out pages. If a broker's steps stop working, open an issue or submit a YAML fix.
+- CAPTCHAs require your attention — the tool will pause and prompt you.
+- Email submissions depend on your SMTP server being reachable and not blocked by the broker.
+- Data frequently reappears (60–90 days is typical). Use `optout monitor` to catch this.
+
+---
+
+## License
+
+AGPL-3.0-only. See [LICENSE](LICENSE).
+
+This license was chosen intentionally: anyone who forks this and runs it as a hosted service must publish their changes. The project's legal model depends on each user running their own copy — a hosted fork changes the legal character of the tool.

optout-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "optout"
+version = "0.1.0"
+description = "Self-hosted CLI that automates CCPA/CPRA data-broker opt-out requests via Playwright"
+readme = "README.md"
+license = "AGPL-3.0-only"
+requires-python = ">=3.12,<3.14"
+authors = [{ name = "Blake Matas" }]
+keywords = ["privacy", "ccpa", "cpra", "data-broker", "opt-out", "playwright", "automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer[all]>=0.12",
+    "rich>=13",
+    "pydantic>=2",
+    "pydantic-settings>=2",
+    "sqlmodel>=0.0.19",
+    "pyyaml>=6",
+    "jinja2>=3",
+    "httpx>=0.27",
+    "playwright>=1.44",
+    "structlog>=23.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Blake104/OptOut"
+Repository = "https://github.com/Blake104/OptOut"
+"Bug Tracker" = "https://github.com/Blake104/OptOut/issues"
+
+[project.scripts]
+optout = "optout.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "types-PyYAML",
+    "aiosmtpd>=1.4",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+optout = ["data/brokers/*.yml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_return_any = false
+disallow_untyped_defs = false
+check_untyped_defs = true
+
+# Playwright, SQLModel, and the engine use heavy Any-based dynamic dispatch.
+# Type-check the schema, config, and CLI where types are well-defined.
+[[tool.mypy.overrides]]
+module = [
+    "optout.engine.*",
+    "optout.scan.*",
+    "optout.monitoring",
+    "optout.db",
+    "optout.cli",
+    "optout.wizard",
+]
+ignore_errors = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

optout-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

optout-0.1.0/src/optout/__init__.py

@@ -0,0 +1,3 @@
+"""OptOut — self-hosted data broker opt-out tool."""
+
+__version__ = "0.1.0"

optout-0.1.0/src/optout/brokers/loader.py

@@ -0,0 +1,36 @@
+"""Loads and validates broker YAML files against BrokerDef."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from .schema import BrokerDef
+
+
+def load_broker(path: Path) -> BrokerDef:
+    """Parse and validate a single broker YAML file."""
+    data = yaml.safe_load(path.read_text())
+    try:
+        return BrokerDef.model_validate(data)
+    except ValidationError as exc:
+        raise ValueError(f"Invalid broker definition at {path}:\n{exc}") from exc
+
+
+def load_all_brokers(brokers_dir: Path) -> list[BrokerDef]:
+    """Load every *.yml file in brokers_dir, sorted by slug."""
+    results: list[BrokerDef] = []
+    errors: list[str] = []
+
+    for yml in sorted(brokers_dir.glob("*.yml")):
+        try:
+            results.append(load_broker(yml))
+        except (ValueError, yaml.YAMLError) as exc:
+            errors.append(str(exc))
+
+    if errors:
+        raise ValueError(f"{len(errors)} broker(s) failed validation:\n" + "\n\n".join(errors))
+
+    return results

optout-0.1.0/src/optout/brokers/registry.py

@@ -0,0 +1,56 @@
+"""In-memory broker catalog, populated from the brokers/ YAML directory."""
+
+from __future__ import annotations
+
+import os
+from importlib.resources import files
+from pathlib import Path
+
+from .loader import load_all_brokers
+from .schema import BrokerDef
+
+_registry: dict[str, BrokerDef] = {}
+_loaded = False
+
+
+def _brokers_dir() -> Path:
+    """Return the directory containing broker YAML files.
+
+    Priority:
+    1. OPTOUT_BROKERS_DIR env var — lets users/tests override with a custom set.
+    2. importlib.resources — finds the YAMLs bundled inside the installed package,
+       works for both editable installs (real filesystem path) and wheel installs.
+    """
+    env = os.environ.get("OPTOUT_BROKERS_DIR")
+    if env:
+        return Path(env)
+    return Path(str(files("optout").joinpath("data/brokers")))
+
+
+def load_registry(brokers_dir: Path | None = None) -> None:
+    global _registry, _loaded
+    directory = brokers_dir or _brokers_dir()
+    if not directory.exists():
+        _registry = {}
+        _loaded = True
+        return
+    _registry = {b.slug: b for b in load_all_brokers(directory)}
+    _loaded = True
+
+
+def _ensure_loaded() -> None:
+    if not _loaded:
+        load_registry()
+
+
+def get_broker(slug: str) -> BrokerDef:
+    _ensure_loaded()
+    try:
+        return _registry[slug]
+    except KeyError:
+        raise KeyError(f"Unknown broker slug: '{slug}'. Run `optout brokers list` to see options.")
+
+
+def all_brokers() -> list[BrokerDef]:
+    _ensure_loaded()
+    return sorted(_registry.values(), key=lambda b: b.name)