freemyid 0.2.0.dev1__py3-none-any.whl

freemyid/setup_config.py

@@ -0,0 +1,311 @@
+"""`freemyid setup --from config.yaml`: non-interactive setup from a versioned YAML file.
+
+OWNER: automation-engineer (CLI v0.2). Schema: schema/setup-config.schema.json (generated by
+tools/gen_schema.py from :class:`SetupConfig`). Example: docs/examples/setup-config.example.yaml.
+
+The file is turned into the same wizard Draft and goes through the same validators as the
+web and terminal wizards (``wizard.draft.apply_step``), so the rules can never drift apart.
+Passwords are never written in the file: the YAML names an environment variable or a file.
+Consent stays explicit: ``consent.agreed: true`` plus a typed ``signed_name``, and the CLI
+shows what will happen and needs ``--yes`` or an interactive confirm.
+"""
+from __future__ import annotations
+
+import os
+from datetime import date
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .wizard.draft import Draft
+
+SETUP_CONFIG_VERSION = 1
+MAX_ADDRESSES = 4     # the wizard's limit
+MAX_FILE_BYTES = 256 * 1024
+
+
+class _M(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class SetupConsent(_M):
+    agreed: bool = Field(description="Must be true: you have read and agree to the consent "
+                         "text that `freemyid setup --from` prints")
+    signed_name: str = Field(min_length=1, description="Full name of the person giving "
+                             "permission, typed as a signature")
+    basis: Literal["self", "guardian_of_minor", "authorized_agent"] = Field(
+        default="self", description="self = I am this person; guardian_of_minor = parent or "
+        "legal guardian of someone under 18; authorized_agent = signed written permission")
+    authorization_file: str | None = Field(
+        default=None, description="Signed authorization form (PDF/image), required for "
+        "authorized_agent. Relative paths are relative to this YAML file")
+
+
+class SetupName(_M):
+    first: str = Field(min_length=1)
+    middle: str | None = None
+    last: str = Field(min_length=1)
+    suffix: str | None = None
+
+
+class SetupAddress(_M):
+    street: str | None = None
+    city: str = Field(min_length=1)
+    state: str = Field(pattern=r"^[A-Za-z]{2}$", description="2-letter US state, e.g. IL")
+    zip: str | None = None
+    current: bool = False
+
+
+class SetupPerson(_M):
+    label: str | None = Field(default=None, description="What to call them on screen, e.g. "
+                              "'Mom'. Defaults to the first name")
+    name: SetupName
+    nicknames: list[str] = []
+    previous_names: list[str] = Field(default=[], description="Full previous/maiden names")
+    birth_year: int | None = Field(default=None, ge=1900, description="Only the year is kept")
+    age: int | None = Field(default=None, ge=0, le=130, description="If birth_year is unknown")
+    addresses: list[SetupAddress] = Field(min_length=1, max_length=MAX_ADDRESSES)
+    phones: list[str] = []
+    emails: list[str] = Field(default=[], description="Personal emails, used only to "
+                              "recognize listings, never sent anywhere")
+    relatives: list[str] = []
+
+
+class SetupPermissions(_M):
+    allow_id_upload: bool = False
+    allow_account_creation: bool = False
+    allow_phone_disclosure: bool = False
+
+
+class SetupMailbox(_M):
+    provider: Literal["gmail", "yahoo", "icloud", "proton_bridge", "other"]
+    address: str = Field(description="The dedicated removal mailbox address")
+    username: str | None = Field(default=None, description="Login name if not the address")
+    password_env: str | None = Field(default=None, description="Name of an environment "
+                                     "variable holding the app password")
+    password_file: str | None = Field(default=None, description="File holding the app "
+                                      "password (first line). Keep it chmod 600")
+    imap_host: str | None = None
+    imap_port: int | None = Field(default=None, ge=1, le=65535)
+    imap_ssl: bool | None = None
+    imap_starttls: bool | None = None
+    smtp_host: str | None = None
+    smtp_port: int | None = Field(default=None, ge=1, le=65535)
+    smtp_starttls: bool | None = None
+    tls_cert_sha256: str | None = Field(
+        default=None, pattern=r"^[0-9A-Fa-f:]{64,95}$",
+        description="Proton Mail Bridge only: the certificate fingerprint you approved")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _no_inline_password(cls, v: Any) -> Any:
+        if isinstance(v, dict) and "password" in v:
+            raise ValueError("never put the password in the file; use password_env or "
+                             "password_file")
+        return v
+
+    @model_validator(mode="after")
+    def _one_password_source(self) -> SetupMailbox:
+        if bool(self.password_env) == bool(self.password_file):
+            raise ValueError("give exactly one of password_env or password_file")
+        return self
+
+
+class SetupSchedule(_M):
+    weekly_recheck: bool = True
+    weekday: int = Field(default=6, ge=0, le=6, description="0=Mon .. 6=Sun")
+    hour: int = Field(default=10, ge=0, le=23)
+    install_job: bool = Field(default=False, description="Also install the background job "
+                              "(same as `freemyid schedule install`)")
+
+
+class SetupConfig(_M):
+    """Free My ID setup file, version 1. One file = one person."""
+    version: Literal[1] = Field(description="Setup file format version")
+    consent: SetupConsent
+    person: SetupPerson
+    permissions: SetupPermissions = SetupPermissions()
+    mailbox: SetupMailbox | None = None
+    email_mode: Literal["approve_each", "auto"] = "approve_each"
+    schedule: SetupSchedule = SetupSchedule()
+
+
+class SetupFileError(ValueError):
+    """The setup file is unreadable or invalid. `problems` are plain-language lines."""
+
+    def __init__(self, problems: list[str]) -> None:
+        super().__init__("; ".join(problems))
+        self.problems = problems
+
+
+def load(path: Path) -> SetupConfig:
+    path = Path(path)
+    try:
+        if path.stat().st_size > MAX_FILE_BYTES:
+            raise SetupFileError([f"{path.name} is too large to be a setup file"])
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except OSError as e:
+        raise SetupFileError([f"cannot read {path}: {type(e).__name__}"]) from e
+    except yaml.YAMLError as e:
+        raise SetupFileError([f"{path.name} is not valid YAML"]) from e
+    if not isinstance(raw, dict):
+        raise SetupFileError([f"{path.name} should be a YAML mapping (key: value)"])
+    try:
+        return SetupConfig.model_validate(raw)
+    except ValidationError as e:
+        # field paths and messages only: never echo the values (they are PII)
+        raise SetupFileError([f"{'.'.join(str(x) for x in err['loc']) or 'file'}: {err['msg']}"
+                              for err in e.errors(include_input=False)]) from e
+
+
+def _resolve(base: Path, p: str) -> Path:
+    q = Path(os.path.expanduser(p))
+    return q if q.is_absolute() else base / q
+
+
+def read_password(mb: SetupMailbox, base: Path) -> str:
+    if mb.password_env:
+        pw = os.environ.get(mb.password_env, "")
+        if not pw:
+            raise SetupFileError([(f"mailbox.password_env: environment variable "
+                                  f"{mb.password_env} is not set")])
+        return pw
+    assert mb.password_file
+    f = _resolve(base, mb.password_file)
+    try:
+        lines = f.read_text(encoding="utf-8").splitlines()
+    except OSError as e:
+        raise SetupFileError([f"mailbox.password_file: cannot read it ({type(e).__name__})"]
+                             ) from e
+    pw = lines[0].strip() if lines else ""
+    if not pw:
+        raise SetupFileError(["mailbox.password_file: the file is empty"])
+    return pw
+
+
+def _flag(b: bool | None) -> str:
+    return "1" if b else ""
+
+
+def to_draft(cfg: SetupConfig, base: Path) -> Draft:
+    """Build a wizard Draft through the wizard's own validators. Raises SetupFileError."""
+    from .wizard import draft as dr
+    from .wizard.flows import _Form
+
+    d = dr.Draft()
+    problems: list[str] = []
+
+    def step(name: str, form: dict[str, Any], files: dict | None = None) -> None:
+        problems.extend(f"{name}: {e}" for e in dr.apply_step(d, name, _Form(form), files))
+
+    c = cfg.consent
+    if not c.agreed:
+        problems.append("consent.agreed must be true (read the consent text first)")
+    files = None
+    if c.authorization_file:
+        f = _resolve(base, c.authorization_file)
+        try:
+            files = {"authorization": (f.name, f.read_bytes())}
+        except OSError as e:
+            problems.append(f"consent.authorization_file: cannot read it ({type(e).__name__})")
+    elif c.basis == "authorized_agent":
+        problems.append("consent.authorization_file is required for authorized_agent")
+    step("consent", {"basis": c.basis, "attested_by": c.signed_name,
+                     "ack": "1" if c.agreed else ""}, files)
+
+    pp = cfg.person
+    step("name", {"first": pp.name.first, "middle": pp.name.middle or "",
+                  "last": pp.name.last, "suffix": pp.name.suffix or "",
+                  "label": pp.label or "", "nicknames": "\n".join(pp.nicknames),
+                  "previous_names": "\n".join(pp.previous_names)})
+    addr: dict[str, Any] = {}
+    for i, a in enumerate(pp.addresses):
+        addr.update({f"street{i}": a.street or "", f"city{i}": a.city,
+                     f"state{i}": a.state, f"zip{i}": a.zip or ""})
+    cur = next((i for i, a in enumerate(pp.addresses) if a.current), 0)
+    addr["current"] = str(cur)
+    step("address", addr)
+    about: dict[str, Any] = {"phones": "\n".join(pp.phones), "emails": "\n".join(pp.emails),
+                             "relatives": "\n".join(pp.relatives)}
+    if pp.birth_year is not None:
+        if pp.birth_year > date.today().year:
+            problems.append("person.birth_year is in the future")
+        about["birth_year"] = str(pp.birth_year)
+    elif pp.age is not None:
+        about["age"] = str(pp.age)
+    step("about", about)
+    perm = cfg.permissions
+    step("permissions", {k: _flag(getattr(perm, k)) for k in
+                         ("allow_id_upload", "allow_account_creation",
+                          "allow_phone_disclosure")})
+
+    mb = cfg.mailbox
+    if mb is None:
+        step("mailbox", {"provider": "skip"})
+    else:
+        try:
+            pw = read_password(mb, base)
+        except SetupFileError as e:
+            problems.extend(e.problems)
+            pw = ""
+        if mb.tls_cert_sha256:
+            d.tls_pin = mb.tls_cert_sha256.replace(":", "").lower()
+        form: dict[str, Any] = {"provider": mb.provider, "address": mb.address,
+                                "username": mb.username or "", "password": pw}
+        hosts = ("imap_host", "smtp_host", "imap_port", "smtp_port", "imap_ssl",
+                 "imap_starttls", "smtp_starttls")
+        if mb.provider == "other" or any(getattr(mb, k) is not None for k in hosts):
+            preset = dr.PRESETS[mb.provider]
+            form["custom_hosts"] = "1"
+            for k in hosts:
+                v = getattr(mb, k)
+                v = preset.get(k) if v is None else v
+                form[k] = _flag(v) if isinstance(v, bool) or k.endswith(("ssl", "tls")) \
+                    else ("" if v is None else str(v))
+        if pw:
+            step("mailbox", form)
+        for i, msg in enumerate(problems):
+            if msg.startswith("mailbox:") and "security code" in msg:
+                problems[i] = ("mailbox: Proton Mail Bridge needs tls_cert_sha256 (approve "
+                               "the certificate once in the wizard, then copy its fingerprint)")
+    step("email", {"email_mode": cfg.email_mode})
+    step("schedule", {"weekly_recheck": _flag(cfg.schedule.weekly_recheck)})
+    d.weekday, d.hour = cfg.schedule.weekday, cfg.schedule.hour
+    if problems:
+        raise SetupFileError(problems)
+    return d
+
+
+def plan_lines(cfg: SetupConfig) -> list[str]:
+    """What will happen, in plain words. Shows only what the person wrote to be shown."""
+    from .wizard import draft as dr
+    pp = cfg.person
+    label = pp.label or pp.name.first
+    lines = [f"Free My ID will save one person on this computer: {label}.",
+             f"  {len(pp.addresses)} address(es), {len(pp.phones)} phone(s), "
+             f"{len(pp.emails)} email(s), {len(pp.relatives)} relative(s); "
+             + ("birth year given." if pp.birth_year else
+                "age given." if pp.age is not None else "no birth year."),
+             "  Removal mailbox: " + (cfg.mailbox.provider if cfg.mailbox else
+                                      "none (email removals stay off)") + ".",
+             "  Emails to brokers: " + ("sent automatically" if cfg.email_mode == "auto"
+                                         else "each one waits for your approval") + ".",
+             "  Background re-checks: " + (
+                 ("weekly; the job will be installed now" if cfg.schedule.install_job
+                  else "weekly once you run `freemyid schedule install`")
+                 if cfg.schedule.weekly_recheck else "off") + ".",
+             ("  Practice mode stays as it is: nothing is sent until real submissions are "
+             "enabled (`freemyid config enable-submissions`)."),
+             "",
+             f"Permission ({dr.BASIS_LABELS[cfg.consent.basis]}):"]
+    lines += [f"  - {t}" for t in dr.CONSENT_TEXT]
+    lines.append(f"Signed: {cfg.consent.signed_name}")
+    return lines
+
+
+def find_existing(store: Any, label: str) -> Any:
+    k = label.strip().lower()
+    return next((p for p in store.list_profiles() if p.label.strip().lower() == k), None)

freemyid/state.py

@@ -0,0 +1,151 @@
+"""Per (profile, broker) state machine and escalation policy.
+
+OWNER: orchestrator. Pure functions only: no I/O, fully deterministic, easy to test.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from enum import StrEnum
+
+from .models import Broker, BrokerStatus
+from .models import ListingState as S
+
+GRACE_DAYS = 15
+
+# Allowed transitions. NEEDS_HUMAN and ERROR are reachable from anywhere and can return to
+# any non-terminal state once resolved, so they are handled in `can_transition`.
+TRANSITIONS: dict[S, set[S]] = {
+    S.UNKNOWN: {S.NOT_FOUND, S.FOUND},
+    S.NOT_FOUND: {S.NOT_FOUND, S.FOUND, S.REAPPEARED},
+    S.FOUND: {S.FOUND, S.SUBMITTED, S.NOT_FOUND},
+    S.SUBMITTED: {S.SUBMITTED, S.AWAITING_VERIFICATION, S.CONFIRMED, S.REMOVED},
+    S.AWAITING_VERIFICATION: {S.AWAITING_VERIFICATION, S.CONFIRMED, S.SUBMITTED, S.REMOVED},
+    S.CONFIRMED: {S.CONFIRMED, S.REMOVED, S.SUBMITTED},
+    S.REMOVED: {S.REMOVED, S.REAPPEARED},
+    S.REAPPEARED: {S.REAPPEARED, S.SUBMITTED, S.REMOVED},
+}
+_ANYWHERE = {S.NEEDS_HUMAN, S.ERROR}
+
+
+class TransitionError(ValueError):
+    pass
+
+
+def can_transition(src: S, dst: S) -> bool:
+    if dst in _ANYWHERE:
+        return True
+    if src in _ANYWHERE:
+        return dst != S.UNKNOWN
+    return dst in TRANSITIONS.get(src, set())
+
+
+def transition(status: BrokerStatus, dst: S, now: datetime) -> BrokerStatus:
+    """Move to `dst`. Entering SUBMITTED from another state counts as a send.
+
+    A rescan that leaves the state unchanged (SUBMITTED -> SUBMITTED) does NOT re-stamp
+    `last_submitted_at`/`attempts`, otherwise escalation would never become due (SEC-01).
+    A real resubmission of an already-SUBMITTED listing must call `mark_submitted`.
+    """
+    if not can_transition(status.state, dst):
+        raise TransitionError(f"{status.state} -> {dst} not allowed")
+    upd = status.model_copy(update={"state": dst, "updated_at": now})
+    if dst == S.SUBMITTED and status.state != S.SUBMITTED:
+        upd.last_submitted_at = now
+        upd.attempts = status.attempts + 1
+    if dst != S.NEEDS_HUMAN:
+        upd.needs_human_reason = None
+    if dst in (S.REMOVED, S.NOT_FOUND):
+        upd.escalation_level = 0
+        upd.last_escalated_at = None
+    return upd
+
+
+def mark_submitted(status: BrokerStatus, now: datetime) -> BrokerStatus:
+    """Record a real send (first submission or resubmission). Call only after a send succeeded."""
+    if not can_transition(status.state, S.SUBMITTED):
+        raise TransitionError(f"{status.state} -> {S.SUBMITTED} not allowed")
+    return status.model_copy(update={
+        "state": S.SUBMITTED, "updated_at": now, "last_submitted_at": now,
+        "attempts": status.attempts + 1, "needs_human_reason": None,
+    })
+
+
+def after_scan(status: BrokerStatus, found: bool, now: datetime) -> S:
+    """Which state a scan result moves us to (caller then calls `transition`)."""
+    st = status.state
+    if st in (S.UNKNOWN, S.NOT_FOUND, S.ERROR, S.NEEDS_HUMAN) and status.last_submitted_at is None:
+        return S.FOUND if found else S.NOT_FOUND
+    if st == S.REMOVED:
+        return S.REAPPEARED if found else S.REMOVED
+    if st in (S.SUBMITTED, S.AWAITING_VERIFICATION, S.CONFIRMED):
+        return st if found else S.REMOVED
+    if st == S.REAPPEARED:
+        return S.REAPPEARED if found else S.REMOVED
+    if st == S.FOUND:
+        return S.FOUND if found else S.NOT_FOUND
+    # NOT_FOUND / NEEDS_HUMAN / ERROR after a prior submission: a listing that is visible
+    # again goes back on the submit path (nothing was sent from these states).
+    if found:
+        return S.REAPPEARED
+    return S.NOT_FOUND if st == S.NOT_FOUND else S.REMOVED
+
+
+def should_submit(state: S) -> bool:
+    return state in (S.FOUND, S.REAPPEARED)
+
+
+# --------------------------------------------------------------------------- escalation
+
+
+class Escalation(StrEnum):
+    NONE = "none"
+    RESUBMIT = "resubmit"            # level 1
+    FOLLOW_UP = "follow_up"          # level 2 (state-law follow-up email)
+    LEGAL_DEMAND = "legal_demand"    # level 3 (formal demand email, always needs approval)
+    COMPLAINT = "complaint"          # level 4 (todo with AG / CPPA links)
+
+
+_LADDER = [Escalation.RESUBMIT, Escalation.FOLLOW_UP, Escalation.LEGAL_DEMAND, Escalation.COMPLAINT]
+
+
+@dataclass(frozen=True)
+class EscalationDecision:
+    action: Escalation
+    new_level: int
+    due_at: datetime | None   # when this step became due (None if nothing to do)
+
+
+def escalation_window(broker: Broker) -> timedelta:
+    return timedelta(days=broker.typical_processing_days + GRACE_DAYS)
+
+
+def next_escalation(status: BrokerStatus, broker: Broker, now: datetime) -> EscalationDecision:
+    """If a submitted request has been ignored, decide the next step.
+
+    Rung n+1 becomes due one window (processing days + 15) after the later of the last
+    submission and the last escalation. Caller applies the decision and sets
+    `escalation_level=new_level, last_escalated_at=now`. Removal resets the ladder.
+    """
+    if status.state not in (S.SUBMITTED, S.AWAITING_VERIFICATION, S.CONFIRMED):
+        return EscalationDecision(Escalation.NONE, status.escalation_level, None)
+    if status.last_submitted_at is None or status.escalation_level >= len(_LADDER):
+        return EscalationDecision(Escalation.NONE, status.escalation_level, None)
+    anchor = max(t for t in (status.last_submitted_at, status.last_escalated_at) if t)
+    due = anchor + escalation_window(broker)
+    if now < due:
+        return EscalationDecision(Escalation.NONE, status.escalation_level, None)
+    return EscalationDecision(_LADDER[status.escalation_level], status.escalation_level + 1, due)
+
+
+def next_check_at(broker: Broker, state: S, now: datetime, weekly: bool = True) -> datetime:
+    """When this broker should next be scanned for this profile."""
+    if state in (S.SUBMITTED, S.AWAITING_VERIFICATION, S.CONFIRMED):
+        days = max(3, min(broker.typical_processing_days, 14))
+    elif state in (S.REMOVED, S.NOT_FOUND):
+        days = broker.recheck_interval_days
+    else:
+        days = 7
+    if weekly:
+        days = min(days, 7) if state in (S.FOUND, S.REAPPEARED, S.NEEDS_HUMAN) else days
+    return now + timedelta(days=days)

freemyid/storage/__init__.py

@@ -0,0 +1,3 @@
+from .db import Store
+
+__all__ = ["Store"]