data-broker-optout

name	data-broker-optout
description	Automates U.S. people-search and data-broker opt-outs with Cursor @Browser and Gmail MCP (user-gmail) using config.yml and BROKER.md (BADBOOL). Use when the user asks to opt out, remove personal data from brokers, run Redactly, process BADBOOL, fill broker forms, or work on internet privacy control in this repo.

Data Broker Opt-Out

Automate opt-outs from people-search sites with Cursor @Browser only. Subject data lives in config.yml; broker steps and URLs live in BROKER.md.

Do not use Playwright, Selenium, or other local browser automation in this repo.

Setup (once)

uv sync

Optional — list brokers from BADBOOL:

uv run python skills/data-broker-optout/scripts/parse_brokers.py BROKER.md
uv run python skills/data-broker-optout/scripts/parse_brokers.py BROKER.md --json

Load config in Python (agents only; never log values):

from config_helpers import load_config, birthday_parts

Quick start

1. Read config.yml (PII — never commit, log, or paste into chat).
2. List brokers by priority (parse_brokers.py or BROKER.md 💐 / ☠ sections).
3. Read the broker's ### section in BROKER.md.
4. Automate with @Browser — browser_navigate, browser_snapshot, browser_fill, browser_click, etc.
5. One broker at a time — finish each site before starting the next (see Sequential execution).
6. CAPTCHA / Cloudflare — hard user gate; stop the session until the user completes it manually (see CAPTCHA / Cloudflare hard gate).
7. End with a session summary (no full PII) — but not if the active broker is waiting on a CAPTCHA/Cloudflare handoff (see hard gate).

Sequential execution

Default: run brokers one by one — one active broker tab, complete or record status in output/progress.yml, then the next. Do not open multiple broker opt-outs in parallel unless the user explicitly asks.

Do not go to the next broker until the current broker is done. Treat the active broker as a gate: no browser_navigate to another broker’s opt-out/find URL, no Gmail searches for another broker’s mail, and no “while we wait” work on a different site until the current broker reaches a terminal status in output/progress.yml.

A broker is done (you may advance) when its status is one of:

Status	Meaning
done	Opt-out submitted and any required email/link confirmation finished
skipped	User confirmed skip (📞/💰/🎫) or broker not applicable
not-listed	No matching listing; documented in notes
blocked	CAPTCHA/Cloudflare or site block after user handoff; cannot proceed

Stay on in-progress, pending-email, or pending-user until resolved (including after the user replies done for CAPTCHA or you confirm via Gmail + @Browser). Only then update output/progress.yml and start the next broker from BROKER.md.

CAPTCHA / Cloudflare is stricter: while the active broker shows a challenge, that broker is a hard gate — see CAPTCHA / Cloudflare hard gate. Do not start the next broker, peek at other sites, or “continue the run” in the same turn.

Mode	How
Agent (@Browser)	Single broker tab; use MCP browser tools; record output/progress.yml between brokers
Broker list CLI	parse_brokers.py — planning only, no browser

Rules:

• One broker flow at a time — leave the previous tab on a confirmation page or close it before the next broker (unless the user asked to keep tabs for email confirm).
• No early switching — if the current broker needs CAPTCHA, email confirm, or a resubmit, finish that broker first; do not open Radaris/Nuwber/etc. “in parallel” or “while waiting.”
• CAPTCHA / Cloudflare — hard gate only; one challenge tab; stop and wait for user done before any next broker (see CAPTCHA / Cloudflare hard gate).
• Skip by default — tier 1 (💐) first; skip 📞/💰/🎫 unless the user confirms.

@Browser rules

Mandatory: Use the cursor-ide-browser MCP for all form filling, navigation, and screenshots.

• Lock workflow — browser_navigate → browser_lock → interactions → browser_unlock.
• Snapshot before clicks — use browser_snapshot for element refs; prefer browser_fill / browser_click over raw CDP for input.
• Screenshots on failure — browser_take_screenshot; save or note path under output/screenshots/<broker>/.
• Never log config values — read from config.yml and type into fields only via browser tools.

Gmail MCP (verification email)

Use the Gmail MCP server (user-gmail) to read verification and opt-out emails. Do not navigate to Gmail in @Browser.

1. Find threads — CallMcpTool → server user-gmail, tool search_threads:
   • query: Gmail search syntax, e.g. newer_than:2d (from:beenverified OR from:peopleconnect OR from:radaris OR from:nuwber OR from:checkpeople OR subject:opt-out OR subject:verify)
   • Check spam if nothing in inbox: in:spam newer_than:7d subject:verify
   • Narrow to the subject inbox: to:<email-from-config.yml> newer_than:1d
2. Read full message — get_thread with threadId from search; use messageFormat: FULL_CONTENT to get htmlBody / plaintextBody and extract the confirmation link.
3. Confirm in browser — browser_navigate to the verification URL in @Browser; complete any on-site steps; update output/progress.yml (pending-email → done when confirmed).
4. Privacy — Do not paste full email bodies or tokens into chat; log broker name + status only.

If Gmail MCP is unavailable or returns auth errors, ask the user to fix MCP auth or paste the verification link, then continue in @Browser.

Typical flow

browser_navigate(opt-out URL)
browser_lock
browser_snapshot → find refs
browser_fill / browser_click (from config.yml fields per broker section in BROKER.md)
[CAPTCHA / Cloudflare? → HARD STOP → user manual → wait for done → then resume THIS broker only]
browser_take_screenshot (submitted or error)
browser_unlock
update output/progress.yml
[pending-email? → Gmail MCP search_threads → get_thread → browser_navigate(verify link)]

Priority

Tier	Symbol	Count	Action
1	💐	13	Do first
2	☠	6	Do after tier 1
3	—	rest	Then remaining People Search Sites
skip	📞 💰 🎫	—	Skip unless user confirms

Also cover Search Engines when the user wants de-indexing, not just broker removal.

Per-broker workflow

- [ ] Search — @Browser: goto find URL, confirm listing exists
- [ ] Capture — copy profile URL from address bar or listing link
- [ ] Opt out — @Browser: fill from config.yml, submit, handle multi-step
- [ ] Verify — Gmail MCP: find confirmation email, open link in @Browser; phone-only (📞) → ask user
- [ ] Record — status: done | skipped | pending-email | blocked | not-listed

Data rule: Only submit fields the broker already shows on the listing. No SSN or full ID numbers.

CAPTCHA / Cloudflare hard gate

When Cloudflare (“Just a moment…”, “Performing security verification”), Turnstile, reCAPTCHA, hCaptcha, or any other CAPTCHA is visible (or still present after the short wait below), the active broker becomes a hard gate. The user must finish it manually before anything else happens.

Hard gate rules (mandatory)

1. Stop automation immediately on that broker — no more browser_click, browser_fill, CDP tricks, or “one more try” on the challenge.
2. Do not go to the next broker — no browser_navigate to another opt-out/find URL, no Gmail searches for another broker, no parse_brokers.py planning for “what’s next,” no parallel tabs, no “while you solve this I’ll start X.”
3. End the agent turn after handoff — unlock @Browser (browser_lock unlock), set output/progress.yml to pending-user with challenge type in notes, optional screenshot under output/screenshots/<broker>/, send the user message below, then stop. Do not continue the broker list in the same turn.
4. Wait for an explicit user reply — the user must complete the challenge in the open tab and reply done (or say they cannot). Until then, do not resume automation, even if the user sends unrelated messages.
5. After done only — resume the same broker from the same URL/step (submit form, email confirm, etc.). Advance to the next broker only when this broker reaches a terminal status (done, skipped, not-listed, or blocked if the user cannot finish).
6. Never use CAPTCHA-solving services, bypass plugins, or repeated challenge clicks.

pending-user for CAPTCHA/Cloudflare is not permission to move on — it means “blocked on user until done.”

Detection flow

1. Wait 10–15s in @Browser for auto-complete; at most one gentle retry (refresh or re-snapshot) on the same page.
2. Challenge still present → hard gate (steps above).
3. User replies done → verify via snapshot/screenshot that the challenge is gone, then continue this broker only.
4. User cannot finish → status: blocked, screenshot, session summary; only then may you start the next broker.

Message to send the user (then stop)

[Broker name] is showing a security check (Cloudflare / CAPTCHA). Please complete it manually in the browser tab I have open (check the box, solve the puzzle, or wait for “Just a moment…” to finish). I will not continue to any other broker until you reply done and this step is finished.

Captchas and blocks

Same triggers and prohibitions as the hard gate. Summary: stop, hand off, wait for done, resume same broker only.

Do not loop retries, click the widget repeatedly, or use CAPTCHA-solving services.

Cloudflare and bot challenges

Tier-1 sites (BeenVerified, Nuwber search, etc.) often show “Performing security verification”, “Just a moment…”, or Turnstile. Cloudflare’s Browser Run product is built for agents that need a real browser, Live View, and Human in the Loop — not for silently defeating site security.

What to do (authorized opt-out only)

Step	Action
1	@Browser: navigate; wait for domcontentloaded / snapshot
2	Wait 10–15s — some challenges auto-complete
3	One gentle retry (refresh or re-snapshot)
4	Ask the user — manual CAPTCHA/Cloudflare in @Browser; wait for done
5	Optional Cloudflare Browser Run (remote CDP MCP) only if user wants; CAPTCHA still manual via Live View
6	User cannot finish → blocked, screenshot, session summary

Human in the loop (required for CAPTCHA)

Agents must not attempt to solve CAPTCHAs. Follow the hard gate: pause the whole run until the user replies done; no next broker until this broker clears the challenge.

• Cursor @Browser — User completes challenge in the open tab; agent resumes same broker after done only.
• Browser Run Live View — User opens Live View and completes the challenge; agent resumes same broker after done only.

Optional: Cloudflare Browser Run via MCP

Use when local @Browser repeatedly gets “Access restricted” or stuck Cloudflare interstitials. Requires env vars (never commit): CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN.

chrome-devtools-mcp + Browser Run (docs):

{
  "mcpServers": {
    "browser-rendering": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/devtools/browser?keep_alive=600000",
        "--wsHeaders={\"Authorization\":\"Bearer <API_TOKEN>\"}"
      ]
    }
  }
}

Replace placeholders from the Cloudflare dashboard.

What not to do

• Playwright, Puppeteer, or uv run playwright in this repo
• CAPTCHA-solving farms or “stealth” bypass plugins
• Assuming Browser Run /crawl will skip challenges (it won’t)

Status values

Status	When
blocked	Cloudflare interstitial, Turnstile, or “Access temporarily restricted” after retry + HITL offer
pending-user	User must finish in browser (CAPTCHA/Cloudflare/phone/etc.); hard gate — agent stops until user replies done; no next broker

Escalate to user

Always ask the user (do not guess) for: Cloudflare/CAPTCHA/Turnstile (hard gate — manual completion, then done; no next broker until then), phone-only (📞), paid flows (💰), ID upload (🎫), Gmail MCP auth failures (or user must forward a link), or live site contradicts BROKER.md instructions.

Session summary template

## Opt-out session

**Completed:** BrokerA, BrokerB
**Pending user:** BrokerC (email confirm)
**Skipped:** BrokerD (📞 phone required)
**Not listed:** BrokerE
**Blocked:** BrokerF (captcha — see output/screenshots/)

Reference

• @Browser patterns, parent companies, field mapping: reference.md
• Broker list JSON: uv run python skills/data-broker-optout/scripts/parse_brokers.py BROKER.md --json