freemyid 0.2.0.dev1__py3-none-any.whl

freemyid/engine/handoff.py

@@ -0,0 +1,237 @@
+"""Human handoff (CAPTCHA, ID upload, unexpected page, match review). Never solves anything.
+
+* `QueuedHandoff` (scheduled / headless / non-tty): persist the Todo with a resume_token,
+  notify (PII-free), return False immediately. Never blocks.
+* `InteractiveHandoff`: persist the Todo, open a HEADED browser on the same URL (cookies
+  carried over), notify, then wait until the user presses Enter, marks the todo done in the
+  dashboard, or the timeout passes. Falls back to queued behaviour when there is no tty or
+  no display.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from typing import TYPE_CHECKING, Any, cast
+
+from ..models import Actor, Event, Todo
+from ..models import ListingState as S
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page
+
+    from ..interfaces import Notifier
+    from ..storage import Store
+    from .browser import BrowserManager
+
+log = logging.getLogger(__name__)
+
+
+class LogNotifier:
+    """Fallback when freemyid.notify is not available. Body is PII-free by contract."""
+
+    def notify(self, title: str, body: str, url: str | None = None) -> None:
+        log.info("notify: %s: %s", title, body)
+
+
+def get_notifier() -> Notifier:
+    try:
+        from ..notify import get_notifier as _gn  # type: ignore[import-not-found]
+        return _gn()
+    except Exception:  # noqa: BLE001 - module may not exist yet / no desktop session
+        return LogNotifier()
+
+
+def resume_token(todo: Todo) -> str:
+    return f"{todo.profile_id}:{todo.broker_id or '-'}:{todo.kind.value}"
+
+
+def _existing_open(store: Store, todo: Todo) -> Todo | None:
+    for t in store.list_todos(todo.profile_id):
+        if t.broker_id == todo.broker_id and t.kind == todo.kind and t.request_id == \
+                todo.request_id:
+            return t
+    return None
+
+
+def persist_todo(store: Store, todo: Todo) -> Todo:
+    """Save a todo unless an identical open one exists (dedupe across scheduled runs)."""
+    if not todo.resume_token:
+        todo = todo.model_copy(update={"resume_token": resume_token(todo)})
+    cur = _existing_open(store, todo)
+    if cur:
+        return cur
+    store.save_todo(todo)
+    return todo
+
+
+GENERIC_HELP = "Free My ID needs your help with 1 site. Open Free My ID to see it."
+
+
+class QueuedHandoff:
+    def __init__(self, store: Store, notifier: Notifier, label: str = "") -> None:
+        self.store, self.notifier, self.label = store, notifier, label
+        self.count = 0
+
+    async def request(self, todo: Todo, page: Page | None, timeout_s: int = 900) -> bool:
+        persist_todo(self.store, todo)
+        self.count += 1
+        # SEC-28: lock-screen text stays generic (no label, kind or site)
+        self.notifier.notify("Free My ID needs you", GENERIC_HELP)
+        return False
+
+
+class InteractiveHandoff(QueuedHandoff):
+    def __init__(self, store: Store, notifier: Notifier, browser: BrowserManager | None,
+                 label: str = "") -> None:
+        super().__init__(store, notifier, label)
+        self.browser = browser
+
+    @staticmethod
+    def can_block() -> bool:
+        if not sys.stdin or not sys.stdin.isatty():
+            return False
+        if sys.platform.startswith("linux") and not (os.environ.get("DISPLAY") or
+                                                     os.environ.get("WAYLAND_DISPLAY")):
+            return False
+        return True
+
+    async def request(self, todo: Todo, page: Page | None, timeout_s: int = 900) -> bool:
+        if not self.can_block():
+            return await super().request(todo, page, timeout_s)
+        todo = persist_todo(self.store, todo)
+        self.count += 1
+        headed_ctx = None
+        if page is not None and self.browser is not None:
+            try:
+                state = await page.context.storage_state()
+                hosts = sorted(getattr(page.context, "freemyid_hosts", set()))
+                headed_ctx = await self.browser.new_context(hosts, storage_state=state,
+                                                            headed=True)
+                hp = await headed_ctx.new_page()
+                await self.browser.goto(hp, page.url, check_challenge=False)
+            except Exception as e:  # noqa: BLE001
+                log.warning("could not open visible browser: %s", type(e).__name__)
+        self.notifier.notify("Free My ID needs you", GENERIC_HELP)
+        print(f"\n[Free My ID] {todo.title}\n  {todo.body}\n"
+              "  Finish it in the browser window, then press Enter here "
+              f"(or wait {timeout_s // 60} min to skip).", flush=True)
+        done = await self._wait(todo, timeout_s)
+        if headed_ctx is not None:
+            try:
+                if page is not None and done:
+                    # carry the solved session back to the automated page's context
+                    await page.context.add_cookies(cast(Any, await headed_ctx.cookies()))
+                await headed_ctx.close()
+            except Exception as e:  # noqa: BLE001
+                log.debug("closing visible browser failed: %s", type(e).__name__)
+        if done:
+            self.store.complete_todo(todo.id)
+        return done
+
+    async def _wait(self, todo: Todo, timeout_s: int) -> bool:
+        loop = asyncio.get_running_loop()
+        enter = loop.run_in_executor(None, sys.stdin.readline)
+        deadline = loop.time() + timeout_s
+        while loop.time() < deadline:
+            if enter.done():
+                return True
+            if all(t.id != todo.id for t in self.store.list_todos(todo.profile_id)):
+                return True      # resolved from the dashboard
+            await asyncio.sleep(1.0)
+        return False
+
+
+def make_handoff(store: Store, notifier: Notifier, interactive: bool,
+                 browser: BrowserManager | None, label: str = "") -> QueuedHandoff:
+    if interactive:
+        return InteractiveHandoff(store, notifier, browser, label)
+    return QueuedHandoff(store, notifier, label)
+
+
+# --------------------------------------------------------------------------- resolution
+# Helpers for the dashboard / CLI (wizard-packager) once a human has acted.
+
+
+def confirm_review(store: Store, listing_id: str, profile_id: str, is_me: bool) -> None:
+    """User answered a REVIEW_MATCH todo. A 'yes' promotes the listing to CONFIRMED (the
+    matcher keeps user confirmations on re-scan); 'no' leaves it ignored."""
+    from ..models import MatchLevel
+    for li in store.list_listings(profile_id):
+        if li.id == listing_id:
+            if is_me:
+                li = li.model_copy(update={
+                    "match_level": MatchLevel.CONFIRMED,
+                    "match_reasons": sorted({*li.match_reasons, "user_confirmed"})})
+            else:
+                li = li.model_copy(update={"match_level": MatchLevel.NO_MATCH,
+                                           "match_reasons": ["user_rejected"]})
+            store.save_listing(li)
+            st = store.get_status(profile_id, li.broker_id)
+            store.save_status(st.model_copy(update={"next_check_at": None}))  # re-run soon
+            store.log(Event(profile_id=profile_id, broker_id=li.broker_id, actor=Actor.USER,
+                            action="review_match", detail={"is_me": is_me}))
+            return
+
+
+def mark_manual_submitted(store: Store, profile_id: str, broker_id: str,
+                          request_id: str | None = None) -> None:
+    """User mailed the letter / made the call / finished the form by hand."""
+    from ..models import RequestStatus, utcnow
+    from ..state import transition
+    now = utcnow()
+    st = store.get_status(profile_id, broker_id)
+    new = transition(st, S.SUBMITTED, now)
+    store.save_status(new)
+    if request_id and (r := store.get_request(request_id)):
+        store.save_request(r.model_copy(update={"status": RequestStatus.SENT, "sent_at": now}))
+    store.log(Event(profile_id=profile_id, broker_id=broker_id, actor=Actor.USER,
+                    action="manual_submitted", from_state=st.state, to_state=new.state))
+
+
+_SUBMIT_KINDS = frozenset({"assisted_opt_out", "send_email_manually", "postal_letter",
+                           "phone_call", "account_required"})
+
+
+def mark_resolved(store: Store, todo: Todo) -> None:
+    """Dashboard "I did it" hook (wizard/server.py looks this up by name).
+
+    For hand-done opt-outs (Assisted card, manual email, letter, call) the broker becomes
+    SUBMITTED so the re-check and escalation clocks start. Follow-up/demand letters sent by
+    hand do not restart the clock. Other kinds just get closed by the caller.
+    """
+    if todo.broker_id and (todo.resume_token or "").startswith("id_requested:"):
+        _resume_after_id_request(store, todo)
+        return
+    if not todo.broker_id or todo.kind.value not in _SUBMIT_KINDS:
+        return
+    tok = todo.resume_token or ""
+    if tok.count(":") >= 2:          # manual_email:<broker>:<follow_up|legal_demand>
+        store.log(Event(profile_id=todo.profile_id, broker_id=todo.broker_id,
+                        actor=Actor.USER, action="manual_letter_sent",
+                        detail={"todo_kind": todo.kind.value}))
+        return
+    from ..state import can_transition
+    st = store.get_status(todo.profile_id, todo.broker_id)
+    if st.state == S.SUBMITTED or not can_transition(st.state, S.SUBMITTED):
+        return
+    if st.state in (S.UNKNOWN, S.NOT_FOUND):
+        return      # nothing was found to remove; just close the to-do
+    mark_manual_submitted(store, todo.profile_id, todo.broker_id, todo.request_id)
+
+
+def _resume_after_id_request(store: Store, todo: Todo) -> None:
+    """The person dealt with a site's request for ID themselves: the site goes back to
+    SUBMITTED, so the re-check and escalation clocks restart from today."""
+    from ..models import utcnow
+    from ..state import transition
+    assert todo.broker_id is not None
+    st = store.get_status(todo.profile_id, todo.broker_id)
+    if st.state != S.NEEDS_HUMAN or st.last_submitted_at is None:
+        return
+    new = transition(st, S.SUBMITTED, utcnow())
+    store.save_status(new.model_copy(update={"needs_human_reason": None}))
+    store.log(Event(profile_id=todo.profile_id, broker_id=todo.broker_id, actor=Actor.USER,
+                    action="id_request_resolved", from_state=st.state, to_state=S.SUBMITTED,
+                    detail={"todo_kind": todo.kind.value}))

freemyid/engine/letters.py

@@ -0,0 +1,125 @@
+"""Letter / email / call-script rendering from jinja2 templates in freemyid/templates/.
+
+`render(template, **vars) -> str` is the CLI-facing entry point (interfaces.py).
+`letter_vars(...)` builds the variable set with DATA MINIMIZATION: only fields the broker's
+listings already show (Listing.shown_fields) plus the removal mailbox are included.
+
+Every email template starts with a `Subject: ...` line; `split_subject` separates it.
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from jinja2 import FileSystemLoader, StrictUndefined
+from jinja2.sandbox import SandboxedEnvironment
+
+from ..models import Broker, Listing, Profile, ProfileField, StateLaw
+from .matcher import STATE_NAMES
+
+TEMPLATES_DIR = Path(__file__).resolve().parent.parent / "templates"
+TEMPLATES = ("generic_removal", "ccpa", "state_privacy", "follow_up", "legal_demand",
+             "postal_letter", "phone_script")
+_ALIASES = {"generic": "generic_removal", "cpra": "ccpa", "california": "ccpa",
+            "state": "state_privacy"}
+
+_env = SandboxedEnvironment(loader=FileSystemLoader(str(TEMPLATES_DIR)),
+                            undefined=StrictUndefined, autoescape=False,
+                            trim_blocks=True, lstrip_blocks=True, keep_trailing_newline=True)
+
+
+def _resolve(template: str) -> str:
+    name = template.removesuffix(".j2").removesuffix(".txt")
+    name = _ALIASES.get(name, name)
+    if name not in TEMPLATES:
+        raise ValueError(f"unknown template {template!r}")
+    return f"{name}.txt.j2"
+
+
+def render(template: str, **vars: Any) -> str:
+    """Render a named template. Missing variables raise (StrictUndefined)."""
+    defaults: dict[str, Any] = {
+        "listing_urls": [], "city": None, "state": None, "age": None, "phone": None,
+        "statute_name": None, "citation": None, "response_days": None,
+        "original_request_date": None, "response_deadline": None, "reference": None,
+        "broker_postal": None, "complaint_urls": [], "today": date.today().isoformat(),
+        "is_agent": False, "agent_name": None, "street_address": None, "zip": None,
+    }
+    defaults.update(vars)
+    return _env.get_template(_resolve(template)).render(**defaults)
+
+
+def split_subject(text: str) -> tuple[str, str]:
+    first, _, rest = text.partition("\n")
+    if first.lower().startswith("subject:"):
+        return first.split(":", 1)[1].strip(), rest.lstrip("\n")
+    return "Personal data deletion request", text
+
+
+def choose_template(state_law: StateLaw | None) -> str:
+    """Initial-request template family for a law that is ALREADY known to apply and be in
+    effect (see engine.outbox.effective_law): ccpa for CA, state_privacy for another state
+    with a statute, generic_removal otherwise."""
+    if state_law is None:
+        return "generic_removal"
+    if state_law.state.upper() == "CA":
+        return "ccpa"
+    return "state_privacy" if state_law.statute_name else "generic_removal"
+
+
+def letter_vars(profile: Profile, broker: Broker, listings: list[Listing],
+                state_law: StateLaw | None = None, *,
+                original_request_date: datetime | None = None,
+                reference: str | None = None, today: date | None = None) -> dict[str, Any]:
+    """Variables for templates, limited to what the listings already show.
+
+    If there are no listings (blind request to a non-searchable broker) only the name and
+    the removal mailbox are included.
+    """
+    today = today or date.today()
+    shown: set[ProfileField] = {f for li in listings for f in li.shown_fields}
+    cur = next((a for a in profile.addresses if a.current), profile.addresses[0])
+    v: dict[str, Any] = {
+        # SEC-29: middle name / suffix only if the listing itself shows the middle name
+        "name": profile.name.full if ProfileField.MIDDLE_NAME in shown
+        else f"{profile.name.first} {profile.name.last}",
+        "broker_name": broker.name,
+        "listing_urls": [li.url for li in listings],
+        "mailbox": profile.mailbox.address if profile.mailbox else None,
+        "today": today.isoformat(),
+        "is_agent": profile.consent.basis.value != "self",
+        "agent_name": profile.consent.attested_by
+        if profile.consent.basis.value != "self" else None,
+    }
+    if ProfileField.CITY in shown:
+        v["city"] = cur.city
+    if ProfileField.STATE in shown:
+        v["state"] = cur.state
+    if ProfileField.AGE in shown:
+        v["age"] = profile.estimated_age(today)
+    if ProfileField.STREET_ADDRESS in shown and cur.street:
+        v["street_address"] = cur.street
+    if ProfileField.ZIP in shown and cur.zip:
+        v["zip"] = cur.zip
+    if ProfileField.PHONE in shown and profile.permissions.allow_phone_disclosure and \
+            profile.phones:
+        v["phone"] = profile.phones[0]
+    if state_law:
+        v["statute_name"] = state_law.statute_name
+        v["citation"] = state_law.citation
+        v["response_days"] = state_law.response_days
+        v["state_name"] = STATE_NAMES.get(state_law.state, state_law.state)
+        v["complaint_urls"] = [str(u) for u in [state_law.ag_complaint_url,
+                                                *state_law.other_complaint_urls] if u]
+    if original_request_date:
+        v["original_request_date"] = original_request_date.date().isoformat()
+        days = (state_law.response_days if state_law and state_law.response_days
+                else broker.typical_processing_days)
+        v["response_deadline"] = (original_request_date.date() +
+                                  timedelta(days=days)).isoformat()
+    if reference:
+        v["reference"] = reference
+    if broker.postal:
+        v["broker_postal"] = "\n".join([broker.postal.recipient, *broker.postal.lines])
+    return v