freemyid 0.2.0.dev1__py3-none-any.whl

freemyid/engine/matcher.py

@@ -0,0 +1,208 @@
+"""Deterministic listing matcher (rapidfuzz). No I/O.
+
+A broker search result is turned into a `Candidate` by a parser, then `score()` decides:
+  CONFIRMED = name match AND >= 2 supporting signals   -> auto-submit allowed
+  POSSIBLE  = name match AND exactly 1 signal          -> REVIEW_MATCH todo
+  NO_MATCH  = otherwise                                -> ignored
+
+Signals: location (city+state, or state alone counts only together with a city), age +-2,
+relative, phone, email. `match_reasons` holds signal NAMES only (never values).
+"""
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass, field
+from datetime import date
+
+from rapidfuzz import fuzz
+
+from ..models import Listing, MatchLevel, Profile, ProfileField, utcnow
+
+NAME_THRESHOLD = 88.0       # token_sort_ratio on normalized "first last"
+RELATIVE_THRESHOLD = 85.0
+USER_CONFIRMED = "user_confirmed"
+
+_US_STATES = {
+    "alabama": "AL", "alaska": "AK", "arizona": "AZ", "arkansas": "AR", "california": "CA",
+    "colorado": "CO", "connecticut": "CT", "delaware": "DE", "florida": "FL", "georgia": "GA",
+    "hawaii": "HI", "idaho": "ID", "illinois": "IL", "indiana": "IN", "iowa": "IA",
+    "kansas": "KS", "kentucky": "KY", "louisiana": "LA", "maine": "ME", "maryland": "MD",
+    "massachusetts": "MA", "michigan": "MI", "minnesota": "MN", "mississippi": "MS",
+    "missouri": "MO", "montana": "MT", "nebraska": "NE", "nevada": "NV",
+    "new hampshire": "NH", "new jersey": "NJ", "new mexico": "NM", "new york": "NY",
+    "north carolina": "NC", "north dakota": "ND", "ohio": "OH", "oklahoma": "OK",
+    "oregon": "OR", "pennsylvania": "PA", "rhode island": "RI", "south carolina": "SC",
+    "south dakota": "SD", "tennessee": "TN", "texas": "TX", "utah": "UT", "vermont": "VT",
+    "virginia": "VA", "washington": "WA", "west virginia": "WV", "wisconsin": "WI",
+    "wyoming": "WY", "district of columbia": "DC",
+}
+STATE_NAMES = {v: k.title() for k, v in _US_STATES.items()}
+
+
+@dataclass
+class Candidate:
+    """One search result as parsed from a broker page. Values are page DATA only."""
+    url: str
+    name: str | None = None
+    age: int | None = None
+    locations: list[str] = field(default_factory=list)   # "Springfield, IL" style
+    relatives: list[str] = field(default_factory=list)
+    phones: list[str] = field(default_factory=list)
+    emails: list[str] = field(default_factory=list)
+    has_address: bool = False      # page shows a street address
+    has_dob: bool = False
+
+
+@dataclass
+class MatchResult:
+    level: MatchLevel
+    score: float
+    reasons: list[str]
+
+
+def norm(s: str | None) -> str:
+    if not s:
+        return ""
+    s = unicodedata.normalize("NFKD", s)
+    s = "".join(c for c in s if not unicodedata.combining(c))
+    s = re.sub(r"[^a-z0-9 ]+", " ", s.lower())
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def digits(s: str) -> str:
+    d = re.sub(r"\D", "", s or "")
+    return d[-10:] if len(d) >= 10 else d
+
+
+def parse_age(text: str | None) -> int | None:
+    if not text:
+        return None
+    m = re.search(r"(?:age|aged)\D{0,3}(\d{1,3})", text, re.IGNORECASE) or re.search(r"\b(\d{2,3})\b",
+                                                                            text)
+    if m:
+        v = int(m.group(1))
+        return v if 0 < v < 131 else None
+    return None
+
+
+def parse_location(text: str) -> tuple[str, str | None]:
+    """'Springfield, IL 62701' -> ('springfield', 'IL'). State may be a full name."""
+    t = text.strip()
+    m = re.match(r"^\s*(.+?)\s*,\s*([A-Za-z .]+?)(?:\s+\d{5}(?:-\d{4})?)?\s*$", t)
+    if not m:
+        return norm(t), None
+    city, st = m.group(1), m.group(2).strip().rstrip(".")
+    if len(st) == 2:
+        return norm(city), st.upper()
+    return norm(city), _US_STATES.get(st.lower())
+
+
+def _profile_name_variants(p: Profile) -> list[str]:
+    out: list[str] = []
+    firsts = [p.name.first, *p.nicknames]
+    lasts = [n.last for n in p.all_names()]
+    for f in firsts:
+        for la in lasts:
+            out.append(norm(f"{f} {la}"))
+    for n in p.all_names():
+        out.append(norm(f"{n.first} {n.last}"))
+        if n.middle:
+            out.append(norm(f"{n.first} {n.middle} {n.last}"))
+    return sorted({o for o in out if o})
+
+
+def name_score(p: Profile, shown: str | None) -> float:
+    s = norm(shown)
+    if not s:
+        return 0.0
+    toks = s.split()
+    # drop single-letter middle initials so "Jane Q Testperson" ~ "Jane Testperson"
+    s2 = " ".join(t for t in toks if len(t) > 1) or s
+    best = 0.0
+    for v in _profile_name_variants(p):
+        best = max(best, fuzz.token_sort_ratio(v, s), fuzz.token_sort_ratio(v, s2))
+    return float(best)
+
+
+def score(profile: Profile, c: Candidate, today: date | None = None) -> MatchResult:
+    ns = name_score(profile, c.name)
+    if ns < NAME_THRESHOLD:
+        return MatchResult(MatchLevel.NO_MATCH, round(ns * 0.5, 1), [])
+    reasons: list[str] = []
+
+    # location: city + state from any current/previous address
+    prof_locs = {(norm(a.city), a.state) for a in profile.addresses}
+    for loc in c.locations:
+        city, st = parse_location(loc)
+        if any(city == pc and (st is None or st == ps) for pc, ps in prof_locs):
+            reasons.append("city")
+            break
+
+    est = profile.estimated_age(today)
+    if est is not None and c.age is not None and abs(est - c.age) <= 2:
+        reasons.append("age")
+
+    if profile.relatives and c.relatives:
+        rels = [norm(r) for r in profile.relatives]
+        if any(fuzz.token_sort_ratio(norm(x), r) >= RELATIVE_THRESHOLD
+               for x in c.relatives for r in rels):
+            reasons.append("relative")
+
+    pphones = {digits(x) for x in profile.phones if digits(x)}
+    if pphones and any(digits(x) in pphones for x in c.phones):
+        reasons.append("phone")
+
+    pemails = {e.strip().lower() for e in profile.emails}
+    if pemails and any(e.strip().lower() in pemails for e in c.emails):
+        reasons.append("email")
+
+    n = len(reasons)
+    level = MatchLevel.CONFIRMED if n >= 2 else MatchLevel.POSSIBLE if n == 1 else \
+        MatchLevel.NO_MATCH
+    sc = min(100.0, round(ns * 0.5 + 12.5 * n, 1))
+    return MatchResult(level, sc, reasons)
+
+
+def shown_fields(c: Candidate) -> list[ProfileField]:
+    """What the listing itself displays (data minimization input)."""
+    out: list[ProfileField] = [ProfileField.LISTING_URL]
+    if c.name:
+        out += [ProfileField.FULL_NAME, ProfileField.FIRST_NAME, ProfileField.LAST_NAME]
+    if c.locations:
+        out += [ProfileField.CITY, ProfileField.STATE]
+    if c.age is not None:
+        out.append(ProfileField.AGE)
+    if c.phones:
+        out.append(ProfileField.PHONE)
+    if c.has_address:
+        out += [ProfileField.STREET_ADDRESS, ProfileField.ZIP]
+    if c.has_dob:
+        out.append(ProfileField.DOB)
+    return out
+
+
+def to_listing(profile: Profile, broker_id: str, c: Candidate,
+               today: date | None = None) -> Listing:
+    r = score(profile, c, today)
+    now = utcnow()
+    return Listing(
+        profile_id=profile.id, broker_id=broker_id, url=c.url, name_shown=c.name,
+        age_shown=c.age, locations_shown=c.locations[:10], relatives_shown=c.relatives[:20],
+        match_score=r.score, match_level=r.level, match_reasons=r.reasons,
+        shown_fields=shown_fields(c), first_seen=now, last_seen=now,
+    )
+
+
+def score_all(profile: Profile, broker_id: str, cands: list[Candidate],
+              today: date | None = None) -> list[Listing]:
+    """Score candidates, drop NO_MATCH, de-duplicate by URL (best score wins)."""
+    best: dict[str, Listing] = {}
+    for c in cands:
+        li = to_listing(profile, broker_id, c, today)
+        if li.match_level == MatchLevel.NO_MATCH:
+            continue
+        cur = best.get(li.url)
+        if cur is None or li.match_score > cur.match_score:
+            best[li.url] = li
+    return sorted(best.values(), key=lambda x: -x.match_score)

freemyid/engine/outbox.py

@@ -0,0 +1,421 @@
+"""Outgoing privacy-request email: compose, queue for approval, send. Never sends in dry runs.
+
+Every email is a `Request`. The rendered letter is stored as encrypted LETTER evidence tied
+to the request, so what the user approves is exactly what gets sent.
+
+* dry_run                    -> Request(status=DRAFT, dry_run=True). Nothing is sent, ever.
+* email_mode APPROVE_EACH    -> QUEUED_FOR_APPROVAL (default)
+* LEGAL_DEMAND               -> always QUEUED_FOR_APPROVAL
+* email_mode AUTO + mailer   -> sent now
+* after a send               -> EMAIL_SENT evidence (the raw message), Request SENT.
+
+`approve_and_send(store, request_id)` is the user-approved send (CLI `outbox approve`,
+dashboard). It refuses unless `config.real_submissions_enabled` (or a mailer is injected,
+e.g. the dev fixture run's FakeMailer).
+
+The letter template follows the person's state: CA -> ccpa, a state with a privacy statute
+-> state_privacy, else generic_removal. Only fields the listings already show go in
+(`letters.letter_vars`).
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from datetime import date, datetime
+from urllib.parse import quote, urlencode
+
+from .. import config as cfgmod
+from ..models import (
+    Actor,
+    Broker,
+    EmailMode,
+    Event,
+    Evidence,
+    EvidenceKind,
+    Listing,
+    Method,
+    Profile,
+    Registry,
+    Request,
+    RequestKind,
+    RequestStatus,
+    StateLaw,
+    utcnow,
+)
+from ..models import ListingState as S
+from ..state import can_transition, mark_submitted, transition
+from . import letters
+
+log = logging.getLogger(__name__)
+
+DEV_FIXTURES_ENV = "FREEMYID_DEV_FIXTURES"
+_DEV_LOOPBACK = frozenset({"127.0.0.1", "localhost", "::1"})
+_dev_warned = False
+
+
+def dev_fixture_base() -> str | None:
+    """Base URL of the dev fixture server, or None.
+
+    SEC-21: honored only for a plain-http loopback URL and never in a frozen (installed)
+    build; anything else is ignored (logged once, value not logged).
+    """
+    global _dev_warned
+    v = os.environ.get(DEV_FIXTURES_ENV)
+    if not v:
+        return None
+    from urllib.parse import urlsplit
+
+    from ..netpolicy import host_of
+    try:
+        scheme = urlsplit(v).scheme
+    except ValueError:
+        scheme = ""
+    if scheme == "http" and host_of(v) in _DEV_LOOPBACK and not getattr(sys, "frozen", False):
+        return v
+    if not _dev_warned:
+        log.warning("%s ignored (only a loopback http URL in a dev checkout)",
+                    DEV_FIXTURES_ENV)
+        _dev_warned = True
+    return None
+
+
+class OutboxError(RuntimeError):
+    """PII-free reason an email could not be queued or sent."""
+
+
+# --------------------------------------------------------------------------- composing
+
+
+def law_in_effect(state_law: StateLaw | None, today: date | None = None) -> bool:
+    """A verified (`last_verified` set) statute with a deletion right already in effect."""
+    if state_law is None or not state_law.statute_name or state_law.last_verified is None:
+        return False
+    if not any("delet" in r.lower() for r in state_law.rights):
+        return False
+    return state_law.effective_date is None or state_law.effective_date <= (today or date.today())
+
+
+def effective_law(profile: Profile, state_law: StateLaw | None,
+                  today: date | None = None) -> StateLaw | None:
+    """The law to cite: only the CURRENT address's state, only if verified and in effect.
+    Anything else -> None (generic voluntary request, no citations). PLAN_V1."""
+    if state_law is None or state_law.state.upper() != profile.state_of_residence:
+        return None
+    return state_law if law_in_effect(state_law, today) else None
+
+
+def initial_template(profile: Profile, state_law: StateLaw | None,
+                     today: date | None = None) -> str:
+    """ccpa for CA / state_privacy elsewhere, only with a verified law in effect for the
+    current address's state; otherwise generic_removal."""
+    law = effective_law(profile, state_law, today)
+    if law is None:
+        return "generic_removal"
+    return "ccpa" if law.state.upper() == "CA" else "state_privacy"
+
+
+def template_for(kind: RequestKind, profile: Profile, state_law: StateLaw | None) -> str:
+    if kind == RequestKind.FOLLOW_UP:
+        return "follow_up"
+    if kind == RequestKind.LEGAL_DEMAND:
+        return "legal_demand"
+    return initial_template(profile, state_law)
+
+
+def compose(profile: Profile, broker: Broker, listings: list[Listing],
+            state_law: StateLaw | None, kind: RequestKind = RequestKind.OPT_OUT, *,
+            original: Request | None = None) -> tuple[str, str]:
+    """(subject, body) for a request letter. Data-minimized via letters.letter_vars.
+    Statutes are cited only when `effective_law` says so."""
+    law = effective_law(profile, state_law)
+    v = letters.letter_vars(
+        profile, broker, listings, law,
+        original_request_date=(original.sent_at or original.created_at) if original else None,
+        reference=original.reference if original else None)
+    text = letters.render(template_for(kind, profile, law), **v)
+    return letters.split_subject(text)
+
+
+def compose_links(to: str, subject: str, body: str) -> dict[str, str]:
+    """Web-mail compose URLs with to/subject/body prefilled (no-mailbox Assisted path)."""
+    return {
+        "Gmail": "https://mail.google.com/mail/?" + urlencode(
+            {"view": "cm", "fs": "1", "to": to, "su": subject, "body": body}, quote_via=quote),
+        "Outlook": "https://outlook.live.com/mail/0/deeplink/compose?" + urlencode(
+            {"to": to, "subject": subject, "body": body}, quote_via=quote),
+        "Yahoo": "https://compose.mail.yahoo.com/?" + urlencode(
+            {"to": to, "subject": subject, "body": body}, quote_via=quote),
+        "Email app": f"mailto:{quote(to, safe='@')}?" + urlencode(
+            {"subject": subject, "body": body}, quote_via=quote),
+    }
+
+
+def _letter_blob(to: str, subject: str, body: str) -> bytes:
+    return f"To: {to}\nSubject: {subject}\n\n{body}".encode()
+
+
+def _parse_letter(blob: bytes) -> tuple[str, str, str]:
+    head, _, body = blob.decode().partition("\n\n")
+    hdr = dict(line.split(": ", 1) for line in head.splitlines() if ": " in line)
+    return hdr.get("To", ""), hdr.get("Subject", ""), body
+
+
+def letter_for(store, req: Request) -> tuple[str, str, str]:
+    """(to, subject, body) stored for a request."""
+    for ev in store.list_evidence(req.profile_id, req.broker_id):
+        if ev.request_id == req.id and ev.kind == EvidenceKind.LETTER:
+            return _parse_letter(store.read_evidence(ev))
+    raise OutboxError("no stored letter for this request")
+
+
+def _save_blob(store, profile_id: str, broker_id: str, kind: EvidenceKind, data: bytes,
+               request_id: str, caption: str, ext: str) -> Evidence:
+    ev = Evidence(profile_id=profile_id, broker_id=broker_id, kind=kind, request_id=request_id,
+                  relpath="x", sha256="", caption=caption)
+    ev = ev.model_copy(update={"relpath": f"{profile_id}/{broker_id}/{ev.id}.{ext}"})
+    return store.save_evidence(ev, data)
+
+
+# --------------------------------------------------------------------------- queueing
+
+
+def _open_request(store, profile_id: str, broker_id: str, kind: RequestKind,
+                  dry_run: bool) -> Request | None:
+    for r in store.list_requests(profile_id, broker_id):
+        if r.kind != kind or r.dry_run != dry_run:
+            continue
+        if r.status in (RequestStatus.QUEUED_FOR_APPROVAL, RequestStatus.DRAFT):
+            return r
+    return None
+
+
+HOLD_ACTION = "email_held_first_approval"   # SEC-27 Event marker (detail: request_id)
+RELEASE_ACTION = "held_emails_released"      # SEC-27 Event marker (detail: counts)
+
+
+def email_sent_before(store, profile_id: str) -> bool:
+    """True once a real (non-dry) EMAIL request for this profile has gone out. A web-form
+    submission does not count: the person must have seen one of Free My ID's emails."""
+    return any(r.status == RequestStatus.SENT and r.method == Method.EMAIL and not r.dry_run
+               for r in store.list_requests(profile_id))
+
+
+def needs_approval(profile: Profile, kind: RequestKind, store=None) -> bool:
+    """Legal demands and every non-AUTO email wait for approval. SEC-27: in AUTO mode the
+    FIRST email for a profile waits too, so the person sees one before any goes out."""
+    if kind == RequestKind.LEGAL_DEMAND or profile.email_mode != EmailMode.AUTO:
+        return True
+    if store is None:
+        return True       # can't prove an earlier send: be safe
+    return not email_sent_before(store, profile.id)
+
+
+def held_by_first_approval(profile: Profile, req: Request, store) -> bool:
+    """A queued email that is waiting only because the profile's first email has not been
+    approved yet (AUTO mode). Approving any email of the profile releases it."""
+    return (profile.email_mode == EmailMode.AUTO and not req.dry_run
+            and req.method == Method.EMAIL
+            and req.status == RequestStatus.QUEUED_FOR_APPROVAL
+            and req.kind != RequestKind.LEGAL_DEMAND
+            and not email_sent_before(store, profile.id))
+
+
+def _auto_releasable(profile: Profile, req: Request) -> bool:
+    return (profile.email_mode == EmailMode.AUTO and not req.dry_run
+            and req.method == Method.EMAIL
+            and req.status == RequestStatus.QUEUED_FOR_APPROVAL
+            and req.kind != RequestKind.LEGAL_DEMAND)
+
+
+def released_by_approval(store, profile: Profile, req: Request) -> list[Request]:
+    """SEC-47: the OTHER queued emails that approving `req` would also send (AUTO profile,
+    first approval). The approve card must list or count these. Empty when approving `req`
+    sends only `req` (approve_each, gate already open, legal demand, dry run)."""
+    if (req.kind == RequestKind.LEGAL_DEMAND or req.dry_run
+            or profile.email_mode != EmailMode.AUTO or email_sent_before(store, profile.id)):
+        return []
+    return [r for r in store.list_requests(profile.id, status=RequestStatus.QUEUED_FOR_APPROVAL)
+            if r.id != req.id and _auto_releasable(profile, r)]
+
+
+def first_email_pending(store, profile: Profile) -> Request | None:
+    """The oldest email held for the profile's first approval (dashboard: "approve this one
+    and the rest go out by themselves"), or None."""
+    for r in store.list_requests(profile.id, status=RequestStatus.QUEUED_FOR_APPROVAL):
+        if held_by_first_approval(profile, r, store):
+            return r
+    return None
+
+
+def queue_email(store, profile: Profile, broker: Broker, listings: list[Listing], *,
+                kind: RequestKind = RequestKind.OPT_OUT, state_law: StateLaw | None = None,
+                dry_run: bool, mailer=None, original: Request | None = None,
+                now: datetime | None = None) -> Request:
+    """Create (or reuse) the Request for this letter; send it now only in AUTO mode.
+
+    Does NOT change the BrokerStatus: the runner does that from the returned request
+    (status SENT = a real send happened).
+    """
+    if not broker.opt_out_email:
+        raise OutboxError("broker has no opt-out email address")
+    now = now or utcnow()
+    existing = _open_request(store, profile.id, broker.id, kind, dry_run)
+    if existing:
+        # SEC-27: an AUTO email that was held for the first approval goes out once the
+        # profile has an approved send (approve_and_send also releases them right away).
+        if (mailer is not None and _auto_releasable(profile, existing)
+                and not needs_approval(profile, kind, store)):
+            return send_request(store, existing, profile, mailer, now=now)
+        return existing
+    subject, body = compose(profile, broker, listings, state_law, kind, original=original)
+    attempt = 1 + sum(1 for r in store.list_requests(profile.id, broker.id)
+                      if r.kind == kind and r.status == RequestStatus.SENT)
+    req = Request(profile_id=profile.id, broker_id=broker.id, kind=kind, method=Method.EMAIL,
+                  listing_ids=[li.id for li in listings], created_at=now, dry_run=dry_run,
+                  attempt=attempt,
+                  original_request_id=original.id if original else None,
+                  status=RequestStatus.DRAFT if dry_run else RequestStatus.QUEUED_FOR_APPROVAL)
+    store.save_request(req)
+    _save_blob(store, profile.id, broker.id, EvidenceKind.LETTER,
+               _letter_blob(broker.opt_out_email, subject, body), req.id,
+               f"{kind.value} letter", "txt")
+    store.log(Event(profile_id=profile.id, broker_id=broker.id, actor=Actor.ENGINE,
+                    action="email_drafted" if dry_run else "email_queued",
+                    detail={"request_id": req.id, "kind": kind.value, "dry_run": dry_run}))
+    if dry_run or mailer is None:
+        return req
+    if needs_approval(profile, kind, store):
+        if _auto_releasable(profile, req):
+            store.log(Event(profile_id=profile.id, broker_id=broker.id, actor=Actor.ENGINE,
+                            action=HOLD_ACTION, detail={"request_id": req.id}))
+        return req
+    return send_request(store, req, profile, mailer, now=now)
+
+
+def send_request(store, req: Request, profile: Profile, mailer, *,
+                 now: datetime | None = None) -> Request:
+    """Send a stored request letter. Never for dry-run requests."""
+    if req.dry_run:
+        raise OutboxError("dry-run requests are never sent")
+    if req.status not in (RequestStatus.QUEUED_FOR_APPROVAL, RequestStatus.DRAFT):
+        raise OutboxError(f"request is {req.status.value}, not sendable")
+    if profile.mailbox is None:
+        raise OutboxError("profile has no removal mailbox")
+    now = now or utcnow()
+    to, subject, body = letter_for(store, req)
+    try:
+        mid = mailer.send(profile, to, subject, body, req.id)
+    except Exception as e:  # noqa: BLE001 - any mailer failure marks the request FAILED
+        store.save_request(req.model_copy(update={"status": RequestStatus.FAILED}))
+        store.log(Event(profile_id=profile.id, broker_id=req.broker_id, actor=Actor.ENGINE,
+                        action="email_failed",
+                        detail={"request_id": req.id, "error": type(e).__name__}))
+        raise OutboxError(f"send failed: {type(e).__name__}") from None
+    raw = getattr(mailer, "last_raw", None) or _letter_blob(to, subject, body)
+    _save_blob(store, profile.id, req.broker_id, EvidenceKind.EMAIL_SENT, raw, req.id,
+               f"{req.kind.value} email sent", "eml")
+    sent = req.model_copy(update={"status": RequestStatus.SENT, "sent_at": now,
+                                  "reference": req.reference})
+    store.save_request(sent)
+    store.log(Event(profile_id=profile.id, broker_id=req.broker_id, actor=Actor.ENGINE,
+                    action="email_sent", detail={"request_id": req.id,
+                                                 "kind": req.kind.value,
+                                                 "has_message_id": bool(mid)}))
+    return sent
+
+
+# --------------------------------------------------------------------------- approval
+
+
+def _default_mailer(profile: Profile, registry: Registry | None):
+    from ..netpolicy import NetPolicy
+    from .mail import FakeMailer, SmtpImapMailer
+    if dev_fixture_base():
+        return FakeMailer()
+    if not cfgmod.load().real_submissions_enabled:
+        raise OutboxError("real email sending is not enabled yet "
+                          "(freemyid config enable-submissions)")
+    return SmtpImapMailer(NetPolicy(registry, [profile]))
+
+
+def apply_sent(store, req: Request, broker: Broker | None, now: datetime) -> None:
+    """After an approved OPT_OUT/RESUBMIT send, move the broker status to SUBMITTED."""
+    if req.kind not in (RequestKind.OPT_OUT, RequestKind.RESUBMIT):
+        return
+    st = store.get_status(req.profile_id, req.broker_id)
+    if not can_transition(st.state, S.SUBMITTED):
+        return
+    new = mark_submitted(st, now)
+    if broker is not None and broker.needs_email_verification:
+        new = transition(new, S.AWAITING_VERIFICATION, now)
+    store.save_status(new)
+    store.log(Event(profile_id=req.profile_id, broker_id=req.broker_id, actor=Actor.USER,
+                    action="submitted", from_state=st.state, to_state=new.state,
+                    detail={"request_id": req.id, "via": "email"}))
+
+
+def approve_and_send(store, request_id: str, *, mailer=None, registry: Registry | None = None,
+                     now: datetime | None = None) -> None:
+    """User-approved send of a QUEUED_FOR_APPROVAL email (interfaces.py entry point)."""
+    req = store.get_request(request_id)
+    if req is None:
+        raise OutboxError("unknown request")
+    if req.status != RequestStatus.QUEUED_FOR_APPROVAL or req.dry_run:
+        raise OutboxError("request is not waiting for approval")
+    profile = store.get_profile(req.profile_id)
+    if profile is None:
+        raise OutboxError("profile no longer exists")
+    from ..consent import consent_ok
+    ok, _why = consent_ok(profile, store)
+    if not ok:
+        raise OutboxError("consent check failed for this profile")
+    if registry is None:
+        from ..registry import load_registry
+        registry = load_registry()
+    try:
+        broker: Broker | None = registry.get(req.broker_id)
+    except KeyError:
+        broker = None
+    mailer = mailer or _default_mailer(profile, registry)
+    now = now or utcnow()
+    store.log(Event(profile_id=req.profile_id, broker_id=req.broker_id, actor=Actor.USER,
+                    action="email_approved", detail={"request_id": req.id}))
+    sent = send_request(store, req, profile, mailer, now=now)
+    apply_sent(store, sent, broker, now)
+    if profile.email_mode == EmailMode.AUTO:
+        release_held(store, profile, mailer=mailer, registry=registry, now=now)
+
+
+def release_held(store, profile: Profile, *, mailer, registry: Registry | None = None,
+                 now: datetime | None = None) -> dict[str, int]:
+    """SEC-27: after the profile's first approved send, send the AUTO emails that were held
+    for it. Legal demands, dry-run and non-AUTO requests are never touched. One failure
+    never stops the rest (the failed request is marked FAILED by send_request)."""
+    counts = {"sent": 0, "failed": 0}
+    if profile.email_mode != EmailMode.AUTO or not email_sent_before(store, profile.id):
+        return counts
+    from ..consent import consent_ok
+    if not consent_ok(profile, store)[0]:
+        return counts
+    now = now or utcnow()
+    for r in store.list_requests(profile.id, status=RequestStatus.QUEUED_FOR_APPROVAL):
+        if not _auto_releasable(profile, r):
+            continue
+        try:
+            sent = send_request(store, r, profile, mailer, now=now)
+        except OutboxError:
+            counts["failed"] += 1
+            continue
+        broker: Broker | None = None
+        if registry is not None:
+            try:
+                broker = registry.get(r.broker_id)
+            except KeyError:
+                broker = None
+        apply_sent(store, sent, broker, now)
+        counts["sent"] += 1
+    if counts["sent"] or counts["failed"]:
+        store.log(Event(profile_id=profile.id, actor=Actor.ENGINE, action=RELEASE_ACTION,
+                        detail=dict(counts)))
+    return counts